GeoThai NPM Packages

Welcome to the GeoThai NPM Packages repository! 🌟 This repository provides an npm package for Node.js that allows you to retrieve detailed geographic data of provinces, districts, subdistricts, and postal code in Thailand.

📦 Overview

This package includes functions to access and retrieve data about:

• Provinces
• Districts
• Subdistricts
• Postal Code

The data is sourced from comprehensive JSON files included in the package.

📊 Features

• Retrieve All Provinces: Fetch a list of all provinces in Thailand.
• Retrieve Province by ID: Get details of a specific province using its ID.
• Retrieve All Districts: Fetch a list of all districts.
• Retrieve District by ID: Get details of a specific district using its ID.
• Retrieve All Subdistricts: Fetch a list of all subdistricts.
• Retrieve Subdistrict by ID: Get details of a specific subdistrict using its ID.
• Retrieve All Postal Codes: Fetch a list of all postal codes.
• Retrieve Postal Code by Code: Get details of a specific postal code using its code.
• Filter by Criterion: Retrieve entities based on specific criteria.

🚀 Installation

You can install the package via npm:

npm install geothai

🛠️ Usage

Here’s a quick guide on how to use the package:

import { getAllProvinces, getProvinceByCode, getProvincesByCriterion } from 'geothai'

// Retrieve all provinces
const provinces = getAllProvinces()
console.log(provinces)

// Retrieve a single province by code (with auto-completion)
const province = getProvinceByCode('10')
console.log(province)

// Retrieve provinces by a specific criterion
const filteredProvinces = getProvincesByCriterion({ name_th: 'กรุงเทพมหานคร' })
console.log(filteredProvinces)

🤝 Contributing

We welcome contributions to enhance this package. Please follow the guidelines in the CONTRIBUTING.md file.

📝 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙋‍♂️ Contact

For any questions or support, please open an issue or contact us at contact@fasu.dev.

Happy coding! 🎉

GeoThai NPM Packages Changelog

2.0.1

Patch Changes

chore: update .npmignore to replace pnpm-lock.yaml with bun.lock and ignore all source files

Full Changelog: https://github.com/GeoThai/npm-packages/compare/v2.0.0...v2.0.1

2.0.0 - 2025-05-08

Minor Changes

• BREAKING CHANGE: Updated the data structure for provinces, districts, subdistricts, and postal codes. The internal JSON format has changed, which impacts the shape of the exported types.

• Type Changes: The following functions now expect different type shapes for their input and output due to the updated data definitions:

  • getProvincesByCriterion(criterion: Partial<Province>)
  • getDistrictsByCriterion(criterion: Partial<District>)

  • getSubdistrictsByCriterion(criterion: Partial<Subdistrict>)

    [!WARNING] While function names and signatures remain the same, the change in data types can result in TypeScript compilation errors or runtime issues if existing code assumes the old structure.

• Refactor: Services for provinces, districts, subdistricts, and postal codes have been updated to work with the new structure. This improves consistency and prepares for better scalability, but may require consumers to adjust their usage of types.

1.0.0 - 2024-08-17

Added

• Integrated Data Structure: Replaced individual JSON files with a more integrated data structure, featuring nested relationships among provinces, districts, and subdistricts. Added additional postal code data with src/data/postal_codes.json.
• Metadata: Introduced src/data/metadata.json to provide detailed information about data versioning and statistics.
• Postal Code Service: Added new service src/services/postal-code.ts to handle postal code data, including retrieval functions.
• New Type Definitions: Added new TypeScript types for metadata and postal codes:
  • src/types/Metadata.ts
  • src/types/PostalCode.ts

Changed

• Data Files: Updated data files for provinces, districts, and subdistricts to reflect the new integrated structure and added postal code data.
• Service Implementations: Refactored existing services (province.ts, district.ts, subdistrict.ts) to accommodate the new data structure:
  • Updated identifiers from province_id, district_id, subdistrict_id to id.
  • Adjusted data retrieval logic to work with the new nested data format.
• Index and Exports: Updated src/index.ts to include the new postal code service and metadata.
• Test Updates: Revised tests to match the updated data structure and identifiers. Added new tests for postal codes and metadata.

Improvements

• Data Integration: Enhanced data organization by integrating related entities and adding postal code information, improving data accessibility and usability.
• Performance: Improved service performance and consistency with the updated data structure and new caching mechanisms.

0.2.0 - 2024-08-15

Minor Changes

Added

• Caching: Introduced src/utils/cache.ts to cache results and improve performance for frequently accessed data.
• Service Creation Utility: Added src/utils/create-service.ts to simplify the creation of data services with caching and lookup functionality.

Changed

• District Service: Updated to use caching and the createService utility. Functions now cache results for better performance.
• Province Service: Refactored to leverage caching and the createService utility. Improved performance with result caching.
• Subdistrict Service: Enhanced with caching and the createService utility. Optimized data retrieval with cached results.

Improvements

• Improved data retrieval performance across services by integrating caching mechanisms.
• Modularized service creation with createService utility, promoting code reuse and consistency.
• Enhanced maintainability and performance by centralizing caching logic in src/utils/cache.ts.

0.1.0 - 2024-08-14

Minor Changes

Added

• New Services: Split functionality into modular services:
  • src/services/province.ts: Handles all province-related operations.
  • src/services/district.ts: Handles all district-related operations.
  • src/services/subdistrict.ts: Handles all subdistrict-related operations.
• Utility Function: Added src/utils/criteria-matcher.ts for consistent criteria-based filtering across services.

Changed

• Code Refactoring:
  • Moved logic from src/index.ts to the new service modules.
  • Simplified index.ts by re-exporting the services and utilities.
• Test Structure:
  • Removed outdated tests (tests/index.test.ts).
  • Introduced new tests for individual services (tests/district.test.ts, tests/province.test.ts, tests/subdistrict.test.ts).

Removed

• Deprecated Test: Removed tests/index.test.ts in favor of more granular test coverage in new service-specific tests.

Improvements

• Enhanced code organization by modularizing the service logic, improving maintainability and readability.
• Centralized criteria matching logic in a dedicated utility function, ensuring consistency across different modules.

0.0.2 - 2024-08-13

Patch Changes

Improvements

• Added TypeScript type annotations to Map objects for provinces, districts, and subdistricts to enhance type safety.
• Replaced spread operator with Array.from() for converting Map values to arrays for consistency and readability.
• Refined filtering logic in getProvincesByCriterion, getDistrictsByCriterion, and getSubdistrictsByCriterion functions to use appropriate TypeScript type assertions.

Code Cleanup

• Enhanced type safety and clarity in src/index.ts.

0.0.1 - 2024-08-13

Initial Release

• Data Integration: Imported and initialized data for provinces, districts, and subdistricts from JSON files.
• Data Storage: Created Map objects to efficiently store and access provinces, districts, and subdistricts by their IDs.
• APIs Implemented:
  • getAllProvinces(): Retrieves all provinces.
  • getProvinceById(provinceId: number): Retrieves a single province by its ID.
  • getAllDistricts(): Retrieves all districts.
  • getDistrictById(districtId: number): Retrieves a single district by its ID.
  • getAllSubdistricts(): Retrieves all subdistricts.
  • getSubdistrictById(subdistrictId: number): Retrieves a single subdistrict by its ID.
  • getProvincesByCriterion(criterion: Partial<Province>): Retrieves provinces matching a specific criterion.
  • getDistrictsByCriterion(criterion: Partial<District>): Retrieves districts matching a specific criterion.
  • getSubdistrictsByCriterion(criterion: Partial<Subdistrict>): Retrieves subdistricts matching a specific criterion.
• Type Definitions: Utilized TypeScript types for provinces, districts, and subdistricts for better type safety and code clarity.