feat: update data to v4 (#520)

BREAKING CHANGES

Author: fityannugroho

docs/upgrading/upgrade-to-v7.md

@@ -0,0 +1,215 @@
+# Upgrade to idn-area version 7
+
+## Breaking Changes Overview
+
+Version 7 introduces significant changes to the code format and data structure. This upgrade uses [idn-area-data v4.0.0](https://github.com/fityannugroho/idn-area-data/releases/tag/v4.0.0) which includes data changes and formats. We also restores the original dotted notation for area codes that was previously stripped in earlier API versions.
+
+## Requirements
+
+### Node.js Version Requirement
+
+Version 7 requires **Node.js ≥22.0.0** due to the updated `idn-area-data` dependency.
+
+```json
+{
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}
+```
+
+### Data Version Update
+
+This version uses **idn-area-data v4.0.0** and introduces the following changes:
+
+#### Format Changes
+- **Restored original dotted notation**: The API now preserves the dotted format from the source data instead of removing dots like in previous versions
+- **Standardized name capitalization**: Changed from ALL CAPS to proper case formatting
+
+#### Data Updates
+- Latest 2025 administrative area data
+- Improved data structure consistency
+- Enhanced data validation
+
+#### Technical Background
+The underlying `idn-area-data` package has always used dotted notation in its source data (e.g., regency codes like `32.01`, district codes like `32.01.01`). However, previous API versions processed this data and removed the dots before serving it. Version 7 eliminates this processing step and serves the data in its original format, making the hierarchical relationships more explicit and easier to understand.
+
+## Backward Compatibility
+
+⚠️ **This is a breaking change.** Version 7 is **NOT** backward compatible with v6 due to the fundamental change in code formats.
+
+## Restored Dotted Notation for Area Codes
+
+**Important Context**: The underlying data source (`idn-area-data`) has always used dotted notation (e.g., `32.01`, `32.01.01`), but previous API versions (including v6) removed the dots to provide numeric-only codes. **Version 7 now preserves the original dotted format** from the data source.
+
+### Code Format Changes
+
+| Administrative Level | v6 Format    | v7 Format       |
+| -------------------- | ------------ | --------------- |
+| Province             | `32`         | `32`            |
+| Regency              | `3201`       | `32.01`         |
+| District             | `320101`     | `32.01.01`      |
+| Village              | `3201012001` | `32.01.01.2001` |
+| Island               | `320140001`  | `32.01.40001`   |
+
+### Background: Why This Change?
+
+In previous versions (v6 and earlier), the API processed the source data and **removed dots** to provide numeric-only codes. For example:
+- Source data: `32.01` (Kabupaten Bogor)
+- API v6 output: `3201` (dots removed)
+- API v7 output: `32.01` (preserves original format)
+
+This change aligns the API output with the actual data structure used in the Indonesian administrative system and makes the hierarchical relationship more explicit.
+
+### Database Schema Updates
+
+The following field lengths have been updated to accommodate the new dotted format:
+
+| Table       | Field           | v6 Length   | v7 Length   |
+| ----------- | --------------- | ----------- | ----------- |
+| `regencies` | `code`          | VARCHAR(4)  | VARCHAR(5)  |
+| `districts` | `code`          | VARCHAR(6)  | VARCHAR(8)  |
+| `districts` | `regency_code`  | VARCHAR(4)  | VARCHAR(5)  |
+| `villages`  | `code`          | VARCHAR(10) | VARCHAR(13) |
+| `villages`  | `district_code` | VARCHAR(6)  | VARCHAR(8)  |
+| `islands`   | `code`          | VARCHAR(9)  | VARCHAR(11) |
+| `islands`   | `regency_code`  | VARCHAR(4)  | VARCHAR(5)  |
+
+## Updated Name Capitalization
+
+Version 7 also standardizes the capitalization of administrative area names to follow proper name formatting instead of ALL CAPS.
+
+### Name Format Changes
+
+| Administrative Level | v6 Format (ALL CAPS) | v7 Format (Proper Case)      |
+| -------------------- | -------------------- | ---------------------------- |
+| Province             | `JAWA BARAT`         | `Jawa Barat`                 |
+| Province             | `DI YOGYAKARTA`      | `Daerah Istimewa Yogyakarta` |
+| Regency              | `KABUPATEN BOGOR`    | `Kabupaten Bogor`            |
+| Regency              | `KOTA BOGOR`         | `Kota Bogor`                 |
+| District             | `NANGGUNG`           | `Nanggung`                   |
+| Village              | `BANTARJATI`         | `Bantarjati`                 |
+| Island               | `PULAU RAMBUT`       | `Pulau Rambut`               |
+
+### Examples of Name Changes
+
+**Provinces:**
+- `ACEH` → `Aceh`
+- `SUMATERA UTARA` → `Sumatera Utara`
+- `JAWA BARAT` → `Jawa Barat`
+- `DI YOGYAKARTA` → `Daerah Istimewa Yogyakarta`
+
+**Regencies:**
+- `KABUPATEN ACEH SELATAN` → `Kabupaten Aceh Selatan`
+- `KABUPATEN BOGOR` → `Kabupaten Bogor`
+- `KOTA JAKARTA PUSAT` → `Kota Jakarta Pusat`
+
+## API Response Changes
+
+### Updated Response Examples
+
+All endpoints now return codes in the new dotted format:
+
+**Get a regency (v7):**
+```
+GET /regencies/32.01
+```
+```json
+{
+  "statusCode": 200,
+  "message": "OK",
+  "data": {
+    "code": "32.01",
+    "name": "Kabupaten Bogor",
+    "provinceCode": "32"
+  }
+}
+```
+
+**Get districts (v7):**
+```
+GET /districts?regencyCode=32.01
+```
+```json
+{
+  "statusCode": 200,
+  "message": "OK",
+  "data": [
+    {
+      "code": "32.01.01",
+      "name": "Nanggung",
+      "regencyCode": "32.01"
+    },
+    {
+      "code": "32.01.02",
+      "name": "Leuwiliang",
+      "regencyCode": "32.01"
+    }
+  ],
+  "meta": {
+    "total": 2,
+    "pages": {
+      "first": 1,
+      "last": 1,
+      "current": 1,
+      "previous": null,
+      "next": null
+    }
+  }
+}
+```
+
+### Island Response Improvements
+
+Islands now automatically include calculated decimal coordinates in the response:
+
+```json
+{
+  "code": "32.01.40001",
+  "name": "Pulau Rambut",
+  "coordinate": "06°10'30.00\" S 106°38'30.00\" E",
+  "isOutermostSmall": false,
+  "isPopulated": false,
+  "regencyCode": "32.01",
+  "latitude": -6.175000000000001,
+  "longitude": 106.64166666666668
+}
+```
+
+The `latitude` and `longitude` fields are now automatically computed from the `coordinate` field and included in all island responses.
+
+## New Features
+
+### Enhanced Island Data
+
+Islands now include automatically calculated decimal coordinates:
+- `latitude`: Decimal latitude from DMS coordinate
+- `longitude`: Decimal longitude from DMS coordinate
+
+These fields are computed server-side and always included in island responses.
+
+### Improved Testing Infrastructure
+
+Version 7 includes significant improvements to the testing framework:
+- Comprehensive E2E testing covering complete user journeys
+- Simplified test data fixtures
+- Better mock services for unit testing
+- Performance-focused testing strategies
+
+## FAQ
+
+### Q: Can I gradually migrate to v7?
+**A:** No, due to the fundamental change in code format, you need to migrate completely. The old numeric format is no longer supported.
+
+### Q: Are there any tools to help with migration?
+**A:** You can create migration scripts using the patterns shown above. Consider writing automated tests to verify your migration.
+
+### Q: Will the API endpoints change?
+**A:** No, the endpoint URLs remain the same. Only the code formats in requests and responses have changed.
+
+## Need Help?
+
+If you encounter issues during migration:
+1. Check the [main documentation](../../README.md) for usage examples
+2. Review the [test fixtures](../../test/fixtures/data.fixtures.ts) for correct code formats
+3. Open an issue on [GitHub](https://github.com/fityannugroho/idn-area/issues)

package.json

@@ -66,7 +66,7 @@
     "@types/supertest": "^6.0.3",
     "@vitest/coverage-v8": "^3.2.4",
     "husky": "^9.1.7",
-    "idn-area-data": "^3.1.2",
+    "idn-area-data": "^4.0.0",
     "lint-staged": "^16.1.5",
     "prisma": "^6.14.0",
     "source-map-support": "^0.5.21",

pnpm-lock.yaml

@@ -0,0 +1,58 @@
+/*
+  Warnings:
+
+  - The primary key for the `districts` table will be changed. If it partially fails, the table could be left without primary key constraint.
+  - The primary key for the `islands` table will be changed. If it partially fails, the table could be left without primary key constraint.
+  - The primary key for the `regencies` table will be changed. If it partially fails, the table could be left without primary key constraint.
+  - The primary key for the `villages` table will be changed. If it partially fails, the table could be left without primary key constraint.
+
+*/
+-- DropForeignKey
+ALTER TABLE `districts` DROP FOREIGN KEY `districts_regency_code_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `islands` DROP FOREIGN KEY `islands_regency_code_fkey`;
+
+-- DropForeignKey
+ALTER TABLE `villages` DROP FOREIGN KEY `villages_district_code_fkey`;
+
+-- DropIndex
+DROP INDEX `districts_regency_code_fkey` ON `districts`;
+
+-- DropIndex
+DROP INDEX `islands_regency_code_fkey` ON `islands`;
+
+-- DropIndex
+DROP INDEX `villages_district_code_fkey` ON `villages`;
+
+-- AlterTable
+ALTER TABLE `districts` DROP PRIMARY KEY,
+    MODIFY `code` VARCHAR(8) NOT NULL,
+    MODIFY `regency_code` VARCHAR(5) NOT NULL,
+    ADD PRIMARY KEY (`code`);
+
+-- AlterTable
+ALTER TABLE `islands` DROP PRIMARY KEY,
+    MODIFY `code` VARCHAR(11) NOT NULL,
+    MODIFY `regency_code` VARCHAR(5) NULL,
+    ADD PRIMARY KEY (`code`);
+
+-- AlterTable
+ALTER TABLE `regencies` DROP PRIMARY KEY,
+    MODIFY `code` VARCHAR(5) NOT NULL,
+    ADD PRIMARY KEY (`code`);
+
+-- AlterTable
+ALTER TABLE `villages` DROP PRIMARY KEY,
+    MODIFY `code` VARCHAR(13) NOT NULL,
+    MODIFY `district_code` VARCHAR(8) NOT NULL,
+    ADD PRIMARY KEY (`code`);
+
+-- AddForeignKey
+ALTER TABLE `districts` ADD CONSTRAINT `districts_regency_code_fkey` FOREIGN KEY (`regency_code`) REFERENCES `regencies`(`code`) ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `islands` ADD CONSTRAINT `islands_regency_code_fkey` FOREIGN KEY (`regency_code`) REFERENCES `regencies`(`code`) ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE `villages` ADD CONSTRAINT `villages_district_code_fkey` FOREIGN KEY (`district_code`) REFERENCES `districts`(`code`) ON DELETE RESTRICT ON UPDATE CASCADE;

prisma/mysql/migrations/20250816073853_update_code_format_to_dotted/migration.sql

@@ -9,22 +9,22 @@ generator client {
 }
 
 model District {
-  code        String    @id @db.VarChar(6)
+  code        String    @id @db.VarChar(8)
   name        String    @db.VarChar(255)
-  regencyCode String    @map("regency_code") @db.VarChar(4)
+  regencyCode String    @map("regency_code") @db.VarChar(5)
   regency     Regency   @relation(fields: [regencyCode], references: [code])
   villages    Village[]
 
   @@map("districts")
 }
 
 model Island {
-  code             String   @id @db.VarChar(9)
+  code             String   @id @db.VarChar(11)
   coordinate       String   @db.VarChar(30)
   isOutermostSmall Boolean  @map("is_outermost_small")
   isPopulated      Boolean  @map("is_populated")
   name             String   @db.VarChar(255)
-  regencyCode      String?  @map("regency_code") @db.VarChar(4)
+  regencyCode      String?  @map("regency_code") @db.VarChar(5)
   regency          Regency? @relation(fields: [regencyCode], references: [code])
 
   @@map("islands")
@@ -39,7 +39,7 @@ model Province {
 }
 
 model Regency {
-  code         String     @id @db.VarChar(4)
+  code         String     @id @db.VarChar(5)
   name         String     @db.VarChar(255)
   provinceCode String     @map("province_code") @db.VarChar(2)
   islands      Island[]
@@ -58,8 +58,8 @@ model SeederLogs {
 }
 
 model Village {
-  code         String   @id @db.VarChar(10)
-  districtCode String   @map("district_code") @db.VarChar(6)
+  code         String   @id @db.VarChar(13)
+  districtCode String   @map("district_code") @db.VarChar(8)
   name         String   @db.VarChar(255)
   district     District @relation(fields: [districtCode], references: [code])