@damarkuncoro/posindonesia 1.0.2 → 1.0.4

package/README.md

@@ -49,21 +49,36 @@ const dki = await search('Gambir', { provinceCode: '31' });
 const byCode = await searchByCode('10110');
 ```
 
-### **2. Penggunaan Advanced (Repository)**
+### **2. Penggunaan Advanced (Repository & Custom Data)**
+
+Untuk skenario yang lebih kompleks, seperti menggunakan sumber data Anda sendiri (misal: dari database), Anda dapat menyuntikkan `DataProvider` custom ke dalam `TsPostalCodeRepository`.
 
 ```typescript
-import { TsPostalCodeRepository, SearchPostalCode } from '@damarkuncoro/posindonesia';
+import { 
+  TsPostalCodeRepository, 
+  SearchPostalCode, 
+  type DataProvider, 
+  type PostalCodeData 
+} from '@damarkuncoro/posindonesia';
+
+// 1. Buat DataProvider Anda sendiri
+class MyDbProvider implements DataProvider {
+  async getAll(): Promise<PostalCodeData[]> {
+    // Logika untuk mengambil data dari database Anda
+    return []; 
+  }
+  async getByProvince(provinceCode: string): Promise<PostalCodeData[]> {
+    // Logika untuk mengambil data provinsi tertentu dari DB
+    return [];
+  }
+}
 
-const repo = new TsPostalCodeRepository({ 
-  useFuzzy: true, 
-  fuzzyThreshold: 0.3 
-});
+// 2. Suntikkan ke Repository
+const myProvider = new MyDbProvider();
+const repo = new TsPostalCodeRepository({ dataProvider: myProvider });
 
 const searchUseCase = new SearchPostalCode(repo);
 const results = await searchUseCase.execute(['Bandung']);
-
-// Bebaskan memori cache jika diperlukan
-repo.clearMemory();
 ```
 
 ## Penggunaan (CLI)

package/lib/cjs/domain/models/PostalCode.d.ts

@@ -2,6 +2,10 @@ import { PostalCodeData } from '../../types.js';
 /**
  * Domain model representing a Postal Code entry with its administrative details.
  */
+/**
+ * Represents a single postal code entry with its associated administrative data.
+ * This is the core domain model returned by all search operations.
+ */
 export declare class PostalCode {
     readonly postalCode: string;
     readonly province: string;

package/lib/cjs/domain/models/PostalCode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PostalCode.d.ts","sourceRoot":"","sources":["../../../../src/domain/models/PostalCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH,qBAAa,UAAU;IACrB,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,WAAW,EAAE,MAAM,CAAC;gBAExB,IAAI,EAAE,cAAc;IAchC,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO;IAMjE;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAW/D;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO;IAIpC;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,cAAc;CAazB"}
+{"version":3,"file":"PostalCode.d.ts","sourceRoot":"","sources":["../../../../src/domain/models/PostalCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH;;;GAGG;AACH,qBAAa,UAAU;IACrB,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,WAAW,EAAE,MAAM,CAAC;gBAExB,IAAI,EAAE,cAAc;IAchC,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO;IAMjE;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAW/D;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO;IAIpC;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,cAAc;CAazB"}

package/lib/cjs/domain/models/PostalCode.js

@@ -4,6 +4,10 @@ exports.PostalCode = void 0;
 /**
  * Domain model representing a Postal Code entry with its administrative details.
  */
+/**
+ * Represents a single postal code entry with its associated administrative data.
+ * This is the core domain model returned by all search operations.
+ */
 class PostalCode {
     constructor(data) {
         this.postalCode = data.postalCode;

package/lib/cjs/domain/models/PostalCode.js.map

@@ -1 +1 @@
-{"version":3,"file":"PostalCode.js","sourceRoot":"","sources":["../../../../src/domain/models/PostalCode.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PostalCode.js","sourceRoot":"","sources":["../../../../src/domain/models/PostalCode.ts"],"names":[],"mappings":";;;AAEA;;GAEG;AACH;;;GAGG;AACH,MAAa,UAAU;IAWrB,YAAY,IAAoB;QAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QAEpC,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAEO,QAAQ;QACd,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACpE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,IAAoB,EAAE,QAAkB;QACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;QACvH,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAoB,EAAE,IAAY;QACnD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,CACL,IAAI,CAAC,UAAU,KAAK,SAAS;YAC7B,IAAI,CAAC,WAAW,KAAK,SAAS;YAC9B,IAAI,CAAC,YAAY,KAAK,SAAS;YAC/B,IAAI,CAAC,QAAQ,KAAK,SAAS;YAC3B,IAAI,CAAC,YAAY,KAAK,SAAS,CAChC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,QAAkB;QACxB,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,IAAY;QACtB,OAAO,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,GAAG,IAAI,CAAC,UAAU,MAAM,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClG,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;CACF;AA9FD,gCA8FC"}

package/lib/cjs/domain/repositories/DataProvider.d.ts

@@ -0,0 +1,17 @@
+import { PostalCodeData } from '../../types.js';
+/**
+ * An interface for any class that can provide postal code data.
+ * This allows the repository to be decoupled from the data source.
+ */
+export interface DataProvider {
+    /**
+     * Retrieves all postal code data.
+     */
+    getAll(): Promise<PostalCodeData[]>;
+    /**
+     * Retrieves postal code data for a specific province.
+     * @param provinceCode The 2-digit province code.
+     */
+    getByProvince(provinceCode: string): Promise<PostalCodeData[]>;
+}
+//# sourceMappingURL=DataProvider.d.ts.map

package/lib/cjs/domain/repositories/DataProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataProvider.d.ts","sourceRoot":"","sources":["../../../../src/domain/repositories/DataProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEpC;;;OAGG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CAChE"}

package/lib/cjs/domain/repositories/DataProvider.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=DataProvider.js.map

package/lib/cjs/domain/repositories/DataProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataProvider.js","sourceRoot":"","sources":["../../../../src/domain/repositories/DataProvider.ts"],"names":[],"mappings":""}

package/lib/cjs/infrastructure/data-providers/TsDataProvider.d.ts

@@ -0,0 +1,13 @@
+import { DataProvider } from '../../domain/repositories/DataProvider.js';
+import { PostalCodeData } from '../../types.js';
+/**
+ * A DataProvider implementation that loads data from the internal TypeScript files.
+ */
+export declare class TsDataProvider implements DataProvider {
+    private provinceCache;
+    private provinceLoadPromises;
+    getByProvince(provinceCode: string): Promise<PostalCodeData[]>;
+    getAll(): Promise<PostalCodeData[]>;
+    clearCache(): void;
+}
+//# sourceMappingURL=TsDataProvider.d.ts.map

package/lib/cjs/infrastructure/data-providers/TsDataProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TsDataProvider.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/data-providers/TsDataProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD;;GAEG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,oBAAoB,CAAqD;IAE3E,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA+B9D,MAAM,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAYzC,UAAU,IAAI,IAAI;CAInB"}

package/lib/cjs/infrastructure/data-providers/TsDataProvider.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TsDataProvider = void 0;
+const index_js_1 = require("../../data/index.js");
+/**
+ * A DataProvider implementation that loads data from the internal TypeScript files.
+ */
+class TsDataProvider {
+    constructor() {
+        this.provinceCache = new Map();
+        this.provinceLoadPromises = new Map();
+    }
+    async getByProvince(provinceCode) {
+        if (this.provinceCache.has(provinceCode)) {
+            return this.provinceCache.get(provinceCode);
+        }
+        let loadPromise = this.provinceLoadPromises.get(provinceCode);
+        if (!loadPromise) {
+            loadPromise = (async () => {
+                const loader = index_js_1.PROVINCE_LOADERS[provinceCode];
+                if (!loader)
+                    return [];
+                try {
+                    const module = await loader();
+                    const exportKey = Object.keys(module).find(k => k !== 'default');
+                    if (!exportKey)
+                        return [];
+                    const rawData = module[exportKey];
+                    this.provinceCache.set(provinceCode, rawData);
+                    return rawData;
+                }
+                catch (error) {
+                    return [];
+                }
+                finally {
+                    this.provinceLoadPromises.delete(provinceCode);
+                }
+            })();
+            this.provinceLoadPromises.set(provinceCode, loadPromise);
+        }
+        return loadPromise;
+    }
+    async getAll() {
+        const codes = Object.keys(index_js_1.PROVINCE_LOADERS);
+        const results = await Promise.allSettled(codes.map(code => this.getByProvince(code)));
+        return results
+            .filter((r) => r.status === 'fulfilled')
+            .map(r => r.value)
+            .flat();
+    }
+    clearCache() {
+        this.provinceCache.clear();
+        this.provinceLoadPromises.clear();
+    }
+}
+exports.TsDataProvider = TsDataProvider;
+//# sourceMappingURL=TsDataProvider.js.map

package/lib/cjs/infrastructure/data-providers/TsDataProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TsDataProvider.js","sourceRoot":"","sources":["../../../../src/infrastructure/data-providers/TsDataProvider.ts"],"names":[],"mappings":";;;AAEA,kDAAuD;AAEvD;;GAEG;AACH,MAAa,cAAc;IAA3B;QACU,kBAAa,GAAkC,IAAI,GAAG,EAAE,CAAC;QACzD,yBAAoB,GAA2C,IAAI,GAAG,EAAE,CAAC;IAiDnF,CAAC;IA/CC,KAAK,CAAC,aAAa,CAAC,YAAoB;QACtC,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAE,CAAC;QAC/C,CAAC;QAED,IAAI,WAAW,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC9D,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;gBACxB,MAAM,MAAM,GAAG,2BAAgB,CAAC,YAAY,CAAC,CAAC;gBAC9C,IAAI,CAAC,MAAM;oBAAE,OAAO,EAAE,CAAC;gBAEvB,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC;oBAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;oBACjE,IAAI,CAAC,SAAS;wBAAE,OAAO,EAAE,CAAC;oBAE1B,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAqB,CAAC;oBACtD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;oBAC9C,OAAO,OAAO,CAAC;gBACjB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,EAAE,CAAC;gBACZ,CAAC;wBAAS,CAAC;oBACT,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;gBACjD,CAAC;YACH,CAAC,CAAC,EAAE,CAAC;YACL,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QAC3D,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,2BAAgB,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAC5C,CAAC;QAEF,OAAO,OAAO;aACX,MAAM,CAAC,CAAC,CAAC,EAAiD,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;aACtF,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;aACjB,IAAI,EAAE,CAAC;IACZ,CAAC;IAED,UAAU;QACR,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC;IACpC,CAAC;CACF;AAnDD,wCAmDC"}

package/lib/cjs/infrastructure/repositories/TsPostalCodeRepository.d.ts

@@ -1,24 +1,42 @@
 import { PostalCode } from '../../domain/models/PostalCode.js';
 import { SearchableRepository, PostalCodeFilter } from '../../domain/repositories/PostalCodeRepository.js';
+import { DataProvider } from '../../domain/repositories/DataProvider.js';
+/**
+ * Configuration for the TsPostalCodeRepository.
+ */
 export interface TsRepoConfig {
+    /**
+     * If true, enables fuzzy search mode using Fuse.js.
+     * @default false
+     */
     useFuzzy?: boolean;
+    /**
+     * The threshold for fuzzy search sensitivity (0.0 to 1.0).
+     * Lower values are more strict.
+     * @default 0.4
+     */
     fuzzyThreshold?: number;
+    /**
+     * Optional custom data provider. Defaults to internal TsDataProvider.
+     */
+    dataProvider?: DataProvider;
 }
 /**
- * Implementation of SearchableRepository using internal TypeScript data.
+ * Implementation of SearchableRepository.
  * Optimized with Flyweight pattern, dynamic imports, and secondary indexing.
  */
 export declare class TsPostalCodeRepository implements SearchableRepository {
-    private provinceCache;
-    private provinceLoadPromises;
     private allData;
     private allLoadPromise;
     private postalCodeIndex;
+    private invertedIndex;
+    private allDataArray;
     private readonly useFuzzy;
     private readonly fuzzyThreshold;
+    private readonly dataProvider;
     constructor(config?: TsRepoConfig);
     /**
-     * Internal helper to build an index for postal codes.
+     * Internal helper to build an index for postal codes and inverted index for text search.
      */
     private buildIndex;
     /**

package/lib/cjs/infrastructure/repositories/TsPostalCodeRepository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TsPostalCodeRepository.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/repositories/TsPostalCodeRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AAK3G,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,oBAAoB,CAAqD;IACjF,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,cAAc,CAA0C;IAChE,OAAO,CAAC,eAAe,CAA4C;IACnE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,GAAE,YAAiB;IAKrC;;OAEG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;YACW,YAAY;IAgC1B;;OAEG;YACW,eAAe;IAyB7B;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAsBtF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqB5E;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAiB1F;;OAEG;IACH,WAAW,IAAI,IAAI;CAOpB"}
+{"version":3,"file":"TsPostalCodeRepository.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/repositories/TsPostalCodeRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AAE3G,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAIzE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,cAAc,CAA0C;IAChE,OAAO,CAAC,eAAe,CAA4C;IACnE,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEhC,MAAM,GAAE,YAAiB;IAMrC;;OAEG;IACH,OAAO,CAAC,UAAU;IA4BlB;;OAEG;YACW,YAAY;IAM1B;;OAEG;YACW,eAAe;IAiB7B;;OAEG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAgDtF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqB5E;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAiB1F;;OAEG;IACH,WAAW,IAAI,IAAI;CAUpB"}

package/lib/cjs/infrastructure/repositories/TsPostalCodeRepository.js

@@ -5,66 +5,56 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TsPostalCodeRepository = void 0;
 const PostalCode_js_1 = require("../../domain/models/PostalCode.js");
-const index_js_1 = require("../../data/index.js");
+const TsDataProvider_js_1 = require("../data-providers/TsDataProvider.js");
 const fuse_js_1 = __importDefault(require("fuse.js"));
 /**
- * Implementation of SearchableRepository using internal TypeScript data.
+ * Implementation of SearchableRepository.
  * Optimized with Flyweight pattern, dynamic imports, and secondary indexing.
  */
 class TsPostalCodeRepository {
     constructor(config = {}) {
-        this.provinceCache = new Map();
-        this.provinceLoadPromises = new Map();
         this.allData = null;
         this.allLoadPromise = null;
         this.postalCodeIndex = new Map();
+        this.invertedIndex = new Map();
+        this.allDataArray = [];
         this.useFuzzy = config.useFuzzy ?? false;
         this.fuzzyThreshold = config.fuzzyThreshold ?? 0.4;
+        this.dataProvider = config.dataProvider ?? new TsDataProvider_js_1.TsDataProvider();
     }
     /**
-     * Internal helper to build an index for postal codes.
+     * Internal helper to build an index for postal codes and inverted index for text search.
      */
     buildIndex(data) {
-        data.forEach(item => {
+        const startIndex = this.allDataArray.length;
+        data.forEach((item, idx) => {
+            const globalIdx = startIndex + idx;
+            this.allDataArray.push(item);
+            // Postal Code Index
             if (!this.postalCodeIndex.has(item.postalCode)) {
                 this.postalCodeIndex.set(item.postalCode, []);
             }
             this.postalCodeIndex.get(item.postalCode).push(item);
+            // Inverted Index for text search
+            const text = `${item.province} ${item.city} ${item.district} ${item.village}`.toLowerCase();
+            const tokens = text.split(/[\s,.-]+/).filter(t => t.length > 0);
+            // Use a Set to avoid duplicate tokens for the same document
+            const uniqueTokens = new Set(tokens);
+            uniqueTokens.forEach(token => {
+                if (!this.invertedIndex.has(token)) {
+                    this.invertedIndex.set(token, []);
+                }
+                this.invertedIndex.get(token).push(globalIdx);
+            });
         });
     }
     /**
      * Internal helper to load data for a specific province.
      */
     async loadProvince(code) {
-        if (this.provinceCache.has(code)) {
-            return this.provinceCache.get(code);
-        }
-        let loadPromise = this.provinceLoadPromises.get(code);
-        if (!loadPromise) {
-            loadPromise = (async () => {
-                const loader = index_js_1.PROVINCE_LOADERS[code];
-                if (!loader)
-                    return [];
-                try {
-                    const module = await loader();
-                    const exportKey = Object.keys(module).find(k => k !== 'default');
-                    if (!exportKey)
-                        return [];
-                    const rawData = module[exportKey];
-                    this.provinceCache.set(code, rawData);
-                    this.buildIndex(rawData);
-                    return rawData;
-                }
-                catch (error) {
-                    return [];
-                }
-                finally {
-                    this.provinceLoadPromises.delete(code);
-                }
-            })();
-            this.provinceLoadPromises.set(code, loadPromise);
-        }
-        return loadPromise;
+        const data = await this.dataProvider.getByProvince(code);
+        this.buildIndex(data);
+        return data;
     }
     /**
      * Internal helper to load all data.
@@ -75,12 +65,8 @@ class TsPostalCodeRepository {
         }
         if (!this.allLoadPromise) {
             this.allLoadPromise = (async () => {
-                const codes = Object.keys(index_js_1.PROVINCE_LOADERS);
-                const results = await Promise.allSettled(codes.map(code => this.loadProvince(code)));
-                const combinedData = results
-                    .filter((r) => r.status === 'fulfilled')
-                    .map(r => r.value)
-                    .flat();
+                const combinedData = await this.dataProvider.getAll();
+                this.buildIndex(combinedData);
                 this.allData = combinedData;
                 return combinedData;
             })();
@@ -104,7 +90,29 @@ class TsPostalCodeRepository {
             matches = fuse.search(keywords.join(' ')).map(result => result.item);
         }
         else {
-            matches = rawData.filter((data) => PostalCode_js_1.PostalCode.matches(data, keywords));
+            // Use Inverted Index for standard search
+            const lowerKeywords = keywords.map(k => k.toLowerCase());
+            const resultIndices = new Set();
+            if (lowerKeywords.length > 0) {
+                const firstKeyword = lowerKeywords[0];
+                const initialDocs = this.invertedIndex.get(firstKeyword) || [];
+                initialDocs.forEach(idx => resultIndices.add(idx));
+                for (let i = 1; i < lowerKeywords.length; i++) {
+                    const keyword = lowerKeywords[i];
+                    const docsForKeyword = new Set(this.invertedIndex.get(keyword) || []);
+                    resultIndices.forEach(idx => {
+                        if (!docsForKeyword.has(idx)) {
+                            resultIndices.delete(idx);
+                        }
+                    });
+                }
+            }
+            const finalIndices = Array.from(resultIndices);
+            matches = finalIndices.map(idx => this.allDataArray[idx]);
+            // If provinceCode is provided, we need to filter the results from the global index
+            if (provinceCode) {
+                matches = matches.filter(m => m.provinceCode === provinceCode);
+            }
         }
         // Flyweight: Instantiate PostalCode only for results
         return matches.map(data => new PostalCode_js_1.PostalCode(data));
@@ -156,11 +164,14 @@ class TsPostalCodeRepository {
      * Clear the memory cache.
      */
     clearMemory() {
-        this.provinceCache.clear();
-        this.provinceLoadPromises.clear();
         this.postalCodeIndex.clear();
+        this.invertedIndex.clear();
         this.allData = null;
+        this.allDataArray = [];
         this.allLoadPromise = null;
+        if (this.dataProvider instanceof TsDataProvider_js_1.TsDataProvider) {
+            this.dataProvider.clearCache();
+        }
     }
 }
 exports.TsPostalCodeRepository = TsPostalCodeRepository;

package/lib/cjs/infrastructure/repositories/TsPostalCodeRepository.js.map

@@ -1 +1 @@
-{"version":3,"file":"TsPostalCodeRepository.js","sourceRoot":"","sources":["../../../../src/infrastructure/repositories/TsPostalCodeRepository.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TsPostalCodeRepository.js","sourceRoot":"","sources":["../../../../src/infrastructure/repositories/TsPostalCodeRepository.ts"],"names":[],"mappings":"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"}

package/lib/cjs/main.d.ts

@@ -8,13 +8,56 @@ export * from './domain/services/Logger.js';
 export * from './domain/errors/PostalCodeError.js';
 export * from './application/use-cases/SearchPostalCode.js';
 export { TsPostalCodeRepository, type TsRepoConfig };
+export { TsDataProvider } from './infrastructure/data-providers/TsDataProvider.js';
 export * from './types.js';
-export declare function search(keywords: string | string[] | PostalCodeFilter, options?: {
+export interface SearchOptions {
+    province?: string;
     provinceCode?: string;
     useFuzzy?: boolean;
-}): Promise<PostalCode[]>;
+}
+/**
+ * Searches for postal codes based on various criteria.
+ * This is the primary, recommended function for all search operations.
+ *
+ * @example
+ * // Search by keywords
+ * await search(['Gambir', 'Jakarta Pusat']);
+ *
+ * @example
+ * // Fuzzy search for a typo
+ * await search('Gmbir', { useFuzzy: true });
+ *
+ * @example
+ * // Structured search for a specific village and city
+ * await search({ village: 'Gambir', city: 'Jakarta Pusat' });
+ *
+ * @example
+ * // Search within a specific province by name (more intuitive)
+ * await search('Bandung', { province: 'Jawa Barat' });
+ *
+ * @param keywords - A search term, an array of terms, or a structured filter object.
+ * @param options - Configuration for the search, such as province filter or fuzzy mode.
+ * @returns A promise that resolves to an array of `PostalCode` instances.
+ */
+export declare function search(keywords: string | string[] | PostalCodeFilter, options?: SearchOptions): Promise<PostalCode[]>;
 /**
- * Global helper for quick search by specific code.
+ * A quick-access helper to find postal codes by a specific code.
+ * This is optimized for searching by a 5-digit postal code or administrative codes.
+ *
+ * @example
+ * // Find by postal code
+ * await searchByCode('10110');
+ *
+ * @example
+ * // Find by village code within a specific province
+ * await searchByCode('3171010001', { province: 'DKI Jakarta' });
+ *
+ * @param code - The code to search for (e.g., '10110').
+ * @param options - Optional configuration to narrow down the search by province.
+ * @returns A promise that resolves to an array of `PostalCode` instances.
  */
-export declare function searchByCode(code: string, provinceCode?: string): Promise<PostalCode[]>;
+export declare function searchByCode(code: string, options?: {
+    province?: string;
+    provinceCode?: string;
+}): Promise<PostalCode[]>;
 //# sourceMappingURL=main.d.ts.map

package/lib/cjs/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,yDAAyD,CAAC;AAE/G,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAGjF,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACtB,MAAM,+CAA+C,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,6CAA6C,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,KAAK,YAAY,EAAE,CAAC;AACrD,cAAc,YAAY,CAAC;AAS3B,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,gBAAgB,EAC9C,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1D,OAAO,CAAC,UAAU,EAAE,CAAC,CAyBvB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC,CAOvB"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,yDAAyD,CAAC;AAE/G,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAGjF,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACtB,MAAM,+CAA+C,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,6CAA6C,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,KAAK,YAAY,EAAE,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mDAAmD,CAAC;AACnF,cAAc,YAAY,CAAC;AAW3B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,gBAAgB,EAC9C,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,EAAE,CAAC,CAgCvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,OAAO,CAAC,UAAU,EAAE,CAAC,CAcvB"}

package/lib/cjs/main.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TsPostalCodeRepository = void 0;
+exports.TsDataProvider = exports.TsPostalCodeRepository = void 0;
 exports.search = search;
 exports.searchByCode = searchByCode;
 const TsPostalCodeRepository_js_1 = require("./infrastructure/repositories/TsPostalCodeRepository.js");
@@ -26,13 +26,40 @@ __exportStar(require("./domain/services/PostalCodeMatcher.js"), exports);
 __exportStar(require("./domain/services/Logger.js"), exports);
 __exportStar(require("./domain/errors/PostalCodeError.js"), exports);
 __exportStar(require("./application/use-cases/SearchPostalCode.js"), exports);
+var TsDataProvider_js_1 = require("./infrastructure/data-providers/TsDataProvider.js");
+Object.defineProperty(exports, "TsDataProvider", { enumerable: true, get: function () { return TsDataProvider_js_1.TsDataProvider; } });
 __exportStar(require("./types.js"), exports);
+const index_js_1 = require("./data/index.js");
 /**
  * Global helper for quick postal code searching without manual instantiation.
  * Uses the internal TypeScript database with caching.
  */
 let globalStandardRepo = null;
 let globalFuzzyRepo = null;
+/**
+ * Searches for postal codes based on various criteria.
+ * This is the primary, recommended function for all search operations.
+ *
+ * @example
+ * // Search by keywords
+ * await search(['Gambir', 'Jakarta Pusat']);
+ *
+ * @example
+ * // Fuzzy search for a typo
+ * await search('Gmbir', { useFuzzy: true });
+ *
+ * @example
+ * // Structured search for a specific village and city
+ * await search({ village: 'Gambir', city: 'Jakarta Pusat' });
+ *
+ * @example
+ * // Search within a specific province by name (more intuitive)
+ * await search('Bandung', { province: 'Jawa Barat' });
+ *
+ * @param keywords - A search term, an array of terms, or a structured filter object.
+ * @param options - Configuration for the search, such as province filter or fuzzy mode.
+ * @returns A promise that resolves to an array of `PostalCode` instances.
+ */
 async function search(keywords, options = {}) {
     const isFuzzy = !!options.useFuzzy;
     let repo;
@@ -49,20 +76,44 @@ async function search(keywords, options = {}) {
         repo = globalStandardRepo;
     }
     const useCase = new SearchPostalCode_js_1.SearchPostalCode(repo);
+    // Resolve province name to code
+    let resolvedProvinceCode = options.provinceCode;
+    if (options.province && !resolvedProvinceCode) {
+        const upperProvince = options.province.toUpperCase().replace(/\s+/g, '_');
+        resolvedProvinceCode = index_js_1.PROVINCE_ALIAS_MAP[upperProvince];
+    }
     if (typeof keywords === 'object' && !Array.isArray(keywords)) {
-        return useCase.executeByFilter(keywords, options.provinceCode);
+        return useCase.executeByFilter(keywords, resolvedProvinceCode);
     }
     const keywordArray = Array.isArray(keywords) ? keywords : [keywords];
-    return useCase.execute(keywordArray, options.provinceCode);
+    return useCase.execute(keywordArray, resolvedProvinceCode);
 }
 /**
- * Global helper for quick search by specific code.
+ * A quick-access helper to find postal codes by a specific code.
+ * This is optimized for searching by a 5-digit postal code or administrative codes.
+ *
+ * @example
+ * // Find by postal code
+ * await searchByCode('10110');
+ *
+ * @example
+ * // Find by village code within a specific province
+ * await searchByCode('3171010001', { province: 'DKI Jakarta' });
+ *
+ * @param code - The code to search for (e.g., '10110').
+ * @param options - Optional configuration to narrow down the search by province.
+ * @returns A promise that resolves to an array of `PostalCode` instances.
  */
-async function searchByCode(code, provinceCode) {
+async function searchByCode(code, options = {}) {
     if (!globalStandardRepo) {
         globalStandardRepo = new TsPostalCodeRepository_js_1.TsPostalCodeRepository();
     }
     const useCase = new SearchPostalCode_js_1.SearchPostalCode(globalStandardRepo);
-    return useCase.executeByCode(code, provinceCode);
+    let resolvedProvinceCode = options.provinceCode;
+    if (options.province && !resolvedProvinceCode) {
+        const upperProvince = options.province.toUpperCase().replace(/\s+/g, '_');
+        resolvedProvinceCode = index_js_1.PROVINCE_ALIAS_MAP[upperProvince];
+    }
+    return useCase.executeByCode(code, resolvedProvinceCode);
 }
 //# sourceMappingURL=main.js.map

package/lib/cjs/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AA2BA,wBA4BC;AAKD,oCAUC;AAtED,uGAA+G;AAiBtG,uGAjBA,kDAAsB,OAiBA;AAhB/B,qFAA+E;AAI/E,4BAA4B;AAC5B,gEAA8C;AAO9C,yEAAuD;AACvD,8DAA4C;AAC5C,qEAAmD;AACnD,8EAA4D;AAE5D,6CAA2B;AAE3B;;;GAGG;AACH,IAAI,kBAAkB,GAAkC,IAAI,CAAC;AAC7D,IAAI,eAAe,GAAkC,IAAI,CAAC;AAEnD,KAAK,UAAU,MAAM,CAC1B,QAA8C,EAC9C,UAAyD,EAAE;IAE3D,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnC,IAAI,IAA4B,CAAC;IAEjC,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,eAAe,GAAG,IAAI,kDAAsB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,GAAG,eAAe,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACxB,kBAAkB,GAAG,IAAI,kDAAsB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,GAAG,kBAAkB,CAAC;IAC5B,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,sCAAgB,CAAC,IAAI,CAAC,CAAC;IAE3C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7D,OAAO,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAErE,OAAO,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;AAC7D,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,YAAqB;IAErB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,kBAAkB,GAAG,IAAI,kDAAsB,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,sCAAgB,CAAC,kBAAkB,CAAC,CAAC;IACzD,OAAO,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AA4DA,wBAmCC;AAkBD,oCAiBC;AAlID,uGAA+G;AAiBtG,uGAjBA,kDAAsB,OAiBA;AAhB/B,qFAA+E;AAI/E,4BAA4B;AAC5B,gEAA8C;AAO9C,yEAAuD;AACvD,8DAA4C;AAC5C,qEAAmD;AACnD,8EAA4D;AAE5D,uFAAmF;AAA1E,mHAAA,cAAc,OAAA;AACvB,6CAA2B;AAE3B,8CAAqD;AAErD;;;GAGG;AACH,IAAI,kBAAkB,GAAkC,IAAI,CAAC;AAC7D,IAAI,eAAe,GAAkC,IAAI,CAAC;AAQ1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,KAAK,UAAU,MAAM,CAC1B,QAA8C,EAC9C,UAAyB,EAAE;IAE3B,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnC,IAAI,IAA4B,CAAC;IAEjC,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,eAAe,GAAG,IAAI,kDAAsB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,GAAG,eAAe,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACxB,kBAAkB,GAAG,IAAI,kDAAsB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,GAAG,kBAAkB,CAAC;IAC5B,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,sCAAgB,CAAC,IAAI,CAAC,CAAC;IAE3C,gCAAgC;IAChC,IAAI,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC;IAChD,IAAI,OAAO,CAAC,QAAQ,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC9C,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC1E,oBAAoB,GAAG,6BAAkB,CAAC,aAAa,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7D,OAAO,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAErE,OAAO,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,UAAwD,EAAE;IAE1D,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,kBAAkB,GAAG,IAAI,kDAAsB,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,sCAAgB,CAAC,kBAAkB,CAAC,CAAC;IAEzD,IAAI,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC;IAChD,IAAI,OAAO,CAAC,QAAQ,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC9C,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC1E,oBAAoB,GAAG,6BAAkB,CAAC,aAAa,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;AAC3D,CAAC"}