feat: implement caching for country data with gzip compression (#26)

* feat: implement caching for country data with gzip compression

* feat: update SonarCloud action to use SONAR_TOKEN from secrets

* Refactor countries service and DTOs for improved structure and readability

- Simplified the CountriesService by extracting common logic into helper functions.
- Introduced GeoAreaDto as a base class for RegionDto and SubregionDto to reduce redundancy.
- Updated entity definitions to reflect the new structure, including renaming RegionEntity to GeoAreaEntity.
- Added new helper functions for parsing exclusion options and simplifying country/state entities.
- Created comprehensive unit tests for new and existing functionality, ensuring robust coverage.
- Implemented mock data fixtures for consistent testing across various modules.

* feat: add unit tests for database initialization, provider, and caching services

* refactor: update string normalization method and streamline imports in country repository

Author: rgdevment

.eslintrc.js

@@ -150,14 +150,13 @@ jobs:
           name: coverage
           path: coverage/
 
-      - uses: SonarSource/sonarcloud-github-action@v4
+      - uses: SonarSource/sonarqube-scan-action@v7
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
         with:
           args: >
             -Dsonar.projectKey=${{ secrets.SONAR_KEY_RC }}
             -Dsonar.organization=${{ secrets.SONAR_ORGANIZATION }}
             -Dsonar.sources=src
             -Dsonar.tests=test
             -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
-            -Dsonar.host.url=https://sonarcloud.io
-        env:
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_RC }}

.github/workflows/main.yml

@@ -54,3 +54,6 @@ pids
 *.sqlite3-journal
 *.sqlite3-wal
 *.sqlite3-shm
+
+# Static JSON cache (generated on boot)
+/data/cache

.gitignore

@@ -0,0 +1,33 @@
+import eslint from '@eslint/js';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import eslintPluginPrettier from 'eslint-plugin-prettier/recommended';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**', 'data/**', 'eslint.config.mjs'],
+  },
+
+  eslint.configs.recommended,
+
+  ...tseslint.configs.recommended,
+
+  eslintConfigPrettier,
+  eslintPluginPrettier,
+
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/interface-name-prefix': 'off',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+      'max-len': ['error', { code: 120 }],
+    },
+  },
+);

eslint.config.mjs

@@ -48,8 +48,6 @@
     "@types/express": "^5.0.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^24.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^9.0.0",
     "eslint-config-prettier": "^10.0.0",
     "eslint-plugin-prettier": "^5.2.0",
@@ -58,7 +56,8 @@
     "ts-jest": "^29.3.0",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0"
   },
   "jest": {
     "moduleFileExtensions": [

package-lock.json

@@ -3,12 +3,6 @@ import { Kysely, sql } from 'kysely';
 import { DATABASE_TOKEN } from './database.provider';
 import { Database } from './database.types';
 
-/**
- * Validates the SQLite database on every application boot.
- *
- * 1. Checks that all required tables exist — fails fast if any are missing.
- * 2. Ensures all indexes exist (CREATE INDEX IF NOT EXISTS) on every boot.
- */
 @Injectable()
 export class DatabaseInitializer implements OnModuleInit {
   private readonly logger = new Logger(DatabaseInitializer.name);
@@ -21,8 +15,6 @@ export class DatabaseInitializer implements OnModuleInit {
     this.logger.log('Database validated — schema and indexes OK.');
   }
 
-  // ── Schema validation ───────────────────────────────────────
-
   private async validateSchema(): Promise<void> {
     const required = ['regions', 'subregions', 'countries', 'states', 'cities'];
 
@@ -42,24 +34,19 @@ export class DatabaseInitializer implements OnModuleInit {
     }
   }
 
-  // ── Index management (runs on EVERY boot) ───────────────────
-
   private async ensureIndexes(): Promise<void> {
     const indexes = [
-      // FK indexes
       'CREATE INDEX IF NOT EXISTS idx_subregions_region_id   ON subregions(region_id)',
       'CREATE INDEX IF NOT EXISTS idx_countries_region_id    ON countries(region_id)',
       'CREATE INDEX IF NOT EXISTS idx_countries_subregion_id ON countries(subregion_id)',
       'CREATE INDEX IF NOT EXISTS idx_states_country_id      ON states(country_id)',
       'CREATE INDEX IF NOT EXISTS idx_cities_state_id        ON cities(state_id)',
       'CREATE INDEX IF NOT EXISTS idx_cities_country_id      ON cities(country_id)',
-      // Name lookups (COLLATE NOCASE)
       'CREATE INDEX IF NOT EXISTS idx_regions_name    ON regions(name COLLATE NOCASE)',
       'CREATE INDEX IF NOT EXISTS idx_subregions_name ON subregions(name COLLATE NOCASE)',
       'CREATE INDEX IF NOT EXISTS idx_countries_name  ON countries(name COLLATE NOCASE)',
       'CREATE INDEX IF NOT EXISTS idx_states_name     ON states(name COLLATE NOCASE)',
       'CREATE INDEX IF NOT EXISTS idx_cities_name     ON cities(name COLLATE NOCASE)',
-      // Common query patterns
       'CREATE INDEX IF NOT EXISTS idx_countries_capital ON countries(capital COLLATE NOCASE)',
       'CREATE INDEX IF NOT EXISTS idx_countries_iso2    ON countries(iso2)',
       'CREATE INDEX IF NOT EXISTS idx_countries_iso3    ON countries(iso3)',

package.json

@@ -15,7 +15,6 @@ export const DatabaseProvider: Provider = {
 
     const native = new BetterSqlite3(dbPath);
 
-    // SQLite pragmas from .env
     native.pragma(`journal_mode = ${config.getOrThrow('SQLITE_JOURNAL_MODE')}`);
     native.pragma('foreign_keys = ON');
     native.pragma(`busy_timeout = ${config.getOrThrow('SQLITE_BUSY_TIMEOUT')}`);

src/database/database.initializer.ts

@@ -1,7 +1,5 @@
 import type { Generated, Insertable, Selectable } from 'kysely';
 
-// ─── Table definitions ──────────────────────────────────────
-
 export interface RegionTable {
   id: Generated<number>;
   name: string;
@@ -87,8 +85,6 @@ export interface CityTable {
   wikiDataId: string | null;
 }
 
-// ─── Database map ────────────────────────────────────────────
-
 export interface Database {
   regions: RegionTable;
   subregions: SubregionTable;
@@ -97,16 +93,12 @@ export interface Database {
   cities: CityTable;
 }
 
-// ─── Row types (what comes out of SELECT) ────────────────────
-
 export type RegionRow = Selectable<RegionTable>;
 export type SubregionRow = Selectable<SubregionTable>;
 export type CountryRow = Selectable<CountryTable>;
 export type StateRow = Selectable<StateTable>;
 export type CityRow = Selectable<CityTable>;
 
-// ─── Insert types ────────────────────────────────────────────
-
 export type NewRegion = Insertable<RegionTable>;
 export type NewSubregion = Insertable<SubregionTable>;
 export type NewCountry = Insertable<CountryTable>;

src/database/database.provider.ts

@@ -0,0 +1,23 @@
+import { join } from 'node:path';
+import { ExcludeOption, ResponseType } from '../dto/country-query.dto';
+
+export const CACHE_DIR = join(process.cwd(), 'data', 'cache');
+
+export function getCacheFileName(type?: ResponseType, exclude?: ExcludeOption): string {
+  const typePart = type === ResponseType.SIMPLE ? 'simple' : 'full';
+
+  let excludePart = '';
+  if (exclude === ExcludeOption.STATES) excludePart = '-exclude-states';
+  else if (exclude === ExcludeOption.CITIES) excludePart = '-exclude-cities';
+
+  return `countries-${typePart}${excludePart}.json.gz`;
+}
+
+export const ALL_CACHE_COMBOS: { type?: ResponseType; exclude?: ExcludeOption }[] = [
+  { type: undefined, exclude: undefined },
+  { type: undefined, exclude: ExcludeOption.CITIES },
+  { type: undefined, exclude: ExcludeOption.STATES },
+  { type: ResponseType.SIMPLE, exclude: undefined },
+  { type: ResponseType.SIMPLE, exclude: ExcludeOption.CITIES },
+  { type: ResponseType.SIMPLE, exclude: ExcludeOption.STATES },
+];