Merge pull request #53 from fityannugroho/feat/island

v1.1.0: Create island endpoints 🏝️

Author: fityannugroho

CONTRIBUTING.md

@@ -72,6 +72,7 @@ The following is the list of supported scopes:
 - `regency`: for changes made on `src/regency` directory.
 - `district`: for changes made on `src/district` directory.
 - `village`: for changes made on `src/village` directory.
+- `island`: for changes made on `src/island` file.
 
 If your change affect more than one package, separate the scopes with a comma (e.g. `test,province`).
 

README.md

@@ -11,6 +11,8 @@ API that provides information on the **administrative areas of Indonesia**, from
 
 Built with [NestJS framework](https://nestjs.com) and writen in TypeScript. [Prisma](https://www.prisma.io) is used as the ORM to interact with any kind of database (in future). For now, we use MongoDB.
 
+> **NEW!** [Island endpoints 🏝️](#12-get-islands-by-name) available in version 1.2.0 or higher.
+
 <h2>Table of Content</h2>
 
 - [Getting Started](#getting-started)
@@ -24,11 +26,14 @@ Built with [NestJS framework](https://nestjs.com) and writen in TypeScript. [Pri
   - [4. Get Regencies by Name](#4-get-regencies-by-name)
   - [5. Get Specific Regency](#5-get-specific-regency)
   - [6. Get All Districts in a Regency](#6-get-all-districts-in-a-regency)
+  - [Get All Islands in a Regency](#get-all-islands-in-a-regency)
   - [7. Get Districts by Name](#7-get-districts-by-name)
   - [8. Get Specific District](#8-get-specific-district)
   - [9. Get All Villages in a District](#9-get-all-villages-in-a-district)
   - [10. Get Villages by Name](#10-get-villages-by-name)
   - [11. Get Specific Village](#11-get-specific-village)
+  - [12. Get Islands by Name](#12-get-islands-by-name)
+  - [13. Get Specific Island](#13-get-specific-island)
   - [Query Parameters](#query-parameters)
     - [`sortBy`](#sortby)
     - [`sortOrder`](#sortorder)
@@ -149,6 +154,19 @@ GET /regencies/{regencyCode}/districts
 
 > This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries.
 
+### Get All Islands in a Regency
+
+```
+GET /regencies/{regencyCode}/islands
+```
+
+- Use this endpoint to **get all islands in a regency**.
+- The `{regencyCode}` must be **4 numeric characters**. If not, you will get `400 Bad Request` response.
+- This endpoint **will return** the array of island if the `{regencyCode}` is exists. Otherwise, you will get a `404 Not Found` response.
+- Usage example: http://localhost:3000/regencies/1101/islands
+
+> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries.
+
 ### 7. Get Districts by Name
 
 ```
@@ -210,6 +228,30 @@ GET /villages/{villageCode}
 - This endpoint **will return** the village with the same code as `{villageCode}`. Otherwise, you will get a `404 Not Found` response.
 - Usage example: http://localhost:3000/villages/3273111004
 
+### 12. Get Islands by Name
+
+```
+GET /islands?name={islandName}
+```
+
+- Use this endpoint to **get the islands by its name**.
+- The `{islandName}` **is required** and must be **at least 3 characters**, maximum 255 characters, and does not contains any other symbols besides `'-/`. If not, you will get `400 Bad Request` response.
+- This endpoint **will return** an array of island, or an **empty array** `[]` if there are no island matched with the `{islandName}`.
+- Usage example: http://localhost:3000/islands?name=java
+
+> This endpoint also support [`sortBy`][sortby-query] and [`sortOrder`][sortorder-query] queries.
+
+### 13. Get Specific Island
+
+```
+GET /islands/{islandCode}
+```
+
+- Use this endpoint to **get a specific island**.
+- The `{islandCode}` must be **9 numeric characters**. If not, you will get `400 Bad Request` response.
+- This endpoint **will return** the island with the same code as `{islandCode}`. Otherwise, you will get a `404 Not Found` response.
+- Usage example: http://localhost:3000/islands/110140001
+
 ### Query Parameters
 
 You can use query parameters to control what data is returned in endpoint responses.

prisma/schema.prisma

@@ -18,6 +18,19 @@ model District {
   @@map("districts")
 }
 
+model Island {
+  id               String   @id @default(auto()) @map("_id") @db.ObjectId
+  code             String   @unique
+  coordinate       String
+  isOutermostSmall Boolean  @map("is_outermost_small")
+  isPopulated      Boolean  @map("is_populated")
+  name             String
+  regencyCode      String?  @map("regency_code")
+  regency          Regency? @relation(fields: [regencyCode], references: [code])
+
+  @@map("islands")
+}
+
 model Province {
   id        String    @id @default(auto()) @map("_id") @db.ObjectId
   code      String    @unique
@@ -32,6 +45,7 @@ model Regency {
   code         String     @unique
   name         String
   provinceCode String     @map("province_code")
+  islands      Island[]
   districts    District[]
   province     Province   @relation(fields: [provinceCode], references: [code])
 

prisma/seed.ts

@@ -23,6 +23,11 @@ const insertVillages = async () => {
   return await prisma.village.createMany({ data: villages });
 };
 
+const insertIslands = async () => {
+  const islands = await IdnArea.islands({ transform: true });
+  return await prisma.island.createMany({ data: islands });
+};
+
 /**
  * Delete all data in a collection.
  */
@@ -59,6 +64,9 @@ const insertAreaData = async (collection: IdnArea.Areas) => {
     case 'villages':
       result = await insertVillages();
       break;
+    case 'islands':
+      result = await insertIslands();
+      break;
     default:
       throw new Error('Invalid collection');
   }
@@ -70,11 +78,13 @@ const insertAreaData = async (collection: IdnArea.Areas) => {
 async function main() {
   await deleteAreaData('villages');
   await deleteAreaData('districts');
+  await deleteAreaData('islands');
   await deleteAreaData('regencies');
   await deleteAreaData('provinces');
 
   await insertAreaData('provinces');
   await insertAreaData('regencies');
+  await insertAreaData('islands');
   await insertAreaData('districts');
   await insertAreaData('villages');
 }

src/app.module.ts

@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { AppController } from './app.controller';
 import { DistrictModule } from './district/district.module';
+import { IslandModule } from './island/island.module';
 import { ProvinceModule } from './province/province.module';
 import { RegencyModule } from './regency/regency.module';
 import { VillageModule } from './village/village.module';
@@ -13,6 +14,7 @@ import { VillageModule } from './village/village.module';
     RegencyModule,
     DistrictModule,
     VillageModule,
+    IslandModule,
   ],
   controllers: [AppController],
   providers: [],

src/common/helper/coordinate-converter/index.ts

@@ -0,0 +1,56 @@
+export default class CoordinateConverter {
+  /**
+   * Check if the coordinate has valid DMS (degrees minutes seconds) format.
+   *
+   * Valid DMS format: `{a}°{b}'{c}" {y} {d}°{e}'{f}" {x}`
+   * - `{a}` should be 2 digit integer from 00 to 90
+   * - `{b}` should be 2 digit integer from 00 to 60
+   * - `{c}` should be 2 digit integer with 2 decimal points from 00.00 to 60.00
+   * - `{y}` should be N or S
+   * - `{d}` should be 3 digit integer from 000 to 180
+   * - `{e}` should be 2 digit integer from 00 to 60
+   * - `{f}` should be 2 digit integer with 2 decimal points from 00.00 to 60.00
+   * - `{x}` should be E or W
+   *
+   * Tested here: https://regex101.com/r/GQe8WT
+   */
+  isValid(coordinate: string) {
+    const regex =
+      /^([0-8][0-9]|90)°([0-5][0-9]|60)'(([0-5][0-9].[0-9]{2})|60.00)"\s(N|S)\s(0\d{2}|1([0-7][0-9]|80))°([0-5][0-9]|60)'(([0-5][0-9].[0-9]{2})|60.00)"\s(E|W)$/;
+
+    return regex.test(coordinate);
+  }
+
+  private calculate(
+    degrees: string,
+    minutes: string,
+    seconds: string,
+    pole: string,
+  ) {
+    return (
+      (parseFloat(degrees) +
+        parseFloat(minutes) / 60 +
+        parseFloat(seconds) / 3600) *
+      (['N', 'E'].includes(pole) ? 1 : -1)
+    );
+  }
+
+  /**
+   * Convert coordinate string to number.
+   *
+   * @throws Error if the coordinate is not in valid DMS (degrees minutes seconds) format
+   */
+  convertToNumber(coordinate: string): number[] {
+    if (!this.isValid(coordinate)) {
+      throw new Error('Invalid coordinate format');
+    }
+
+    const [a, b, c, d, e, f] = coordinate.match(/[0-9,\.]+/g);
+    const [y, x] = coordinate.match(/(N|S|E|W)/g);
+
+    const latitude = this.calculate(a, b, c, y);
+    const longitude = this.calculate(d, e, f, x);
+
+    return [latitude, longitude];
+  }
+}

src/island/island.controller.spec.ts

@@ -0,0 +1,21 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { IslandController } from './island.controller';
+import { IslandService } from './island.service';
+import { PrismaService } from '../common/services/prisma';
+
+describe('IslandController', () => {
+  let controller: IslandController;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [IslandController],
+      providers: [IslandService, PrismaService],
+    }).compile();
+
+    controller = module.get<IslandController>(IslandController);
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+});

src/island/island.controller.ts

@@ -0,0 +1,85 @@
+import {
+  Controller,
+  Get,
+  NotFoundException,
+  Param,
+  Query,
+} from '@nestjs/common';
+import { IslandService } from './island.service';
+import { IslandFindByCodeParams, IslandFindQueries } from './island.dto';
+import {
+  ApiBadRequestResponse,
+  ApiNotFoundResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiQuery,
+  ApiTags,
+} from '@nestjs/swagger';
+import { Island } from '@prisma/client';
+
+@ApiTags('Island')
+@Controller('islands')
+export class IslandController {
+  constructor(private readonly islandService: IslandService) {}
+
+  @ApiOperation({
+    description: 'Get the islands by its name.',
+  })
+  @ApiQuery({
+    name: 'name',
+    description: 'The island name.',
+    required: true,
+    type: 'string',
+    example: 'sabang',
+  })
+  @ApiQuery({
+    name: 'sortBy',
+    description: 'Sort islands by its code, name, or coordinate.',
+    required: false,
+    type: 'string',
+    example: 'code',
+  })
+  @ApiQuery({
+    name: 'sortOrder',
+    description: 'Sort islands in ascending or descending order.',
+    required: false,
+    type: 'string',
+    example: 'asc',
+  })
+  @ApiOkResponse({ description: 'Returns array of islands.' })
+  @ApiBadRequestResponse({ description: 'If there are invalid query values.' })
+  @Get()
+  async find(@Query() queries: IslandFindQueries) {
+    const { name, sortBy, sortOrder } = queries ?? {};
+    return this.islandService.find(name, {
+      sortBy: sortBy,
+      sortOrder: sortOrder,
+    });
+  }
+
+  @ApiOperation({ description: 'Get an island by its code.' })
+  @ApiParam({
+    name: 'code',
+    description: 'The island code',
+    required: true,
+    type: 'string',
+    example: '110140001',
+  })
+  @ApiOkResponse({ description: 'Returns an island.' })
+  @ApiBadRequestResponse({ description: 'If the `code` is invalid.' })
+  @ApiNotFoundResponse({
+    description: 'If no island matches the `code`.',
+  })
+  @Get(':code')
+  async findByCode(@Param() params: IslandFindByCodeParams): Promise<Island> {
+    const { code } = params;
+    const island = await this.islandService.findByCode(code);
+
+    if (!island) {
+      throw new NotFoundException(`Island with code ${code} not found.`);
+    }
+
+    return island;
+  }
+}

src/island/island.dto.ts

@@ -0,0 +1,55 @@
+import {
+  IsBooleanString,
+  IsNotEmpty,
+  IsNumberString,
+  IsOptional,
+  IsString,
+  Length,
+} from 'class-validator';
+import { IsNotSymbol } from '../common/decorator/IsNotSymbol';
+import { EqualsAny } from '../common/decorator/EqualsAny';
+import { SortQuery } from '../common/helper/sort';
+import { IntersectionType, PickType } from '@nestjs/mapped-types';
+
+export class Island {
+  @IsNotEmpty()
+  @IsNumberString()
+  @Length(9, 9)
+  code: string;
+
+  @IsNotEmpty()
+  @IsString()
+  coordinate: string;
+
+  @IsNotEmpty()
+  @IsBooleanString()
+  isOutermostSmall: boolean;
+
+  @IsNotEmpty()
+  @IsBooleanString()
+  isPopulated: boolean;
+
+  @IsNotEmpty()
+  @IsNotSymbol("'-/")
+  @Length(3, 255)
+  name: string;
+
+  @IsOptional()
+  @IsNumberString()
+  @Length(4, 4)
+  regencyCode?: string;
+}
+
+export class IslandSortQuery extends SortQuery<'code' | 'name' | 'coordinate'> {
+  @EqualsAny(['code', 'name', 'coordinate'])
+  sortBy: 'code' | 'name';
+}
+
+export class IslandFindQueries extends IntersectionType(
+  PickType(Island, ['name'] as const),
+  IslandSortQuery,
+) {}
+
+export class IslandFindByCodeParams extends PickType(Island, [
+  'code',
+] as const) {}

src/island/island.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { IslandController } from './island.controller';
+import { IslandService } from './island.service';
+import { PrismaService } from '../common/services/prisma';
+
+@Module({
+  providers: [IslandService, PrismaService],
+  controllers: [IslandController],
+  exports: [IslandService],
+})
+export class IslandModule {}