@jpzip/jpzip 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nadai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# jpzip — TypeScript / JavaScript SDK
+
+> 日本の郵便番号を CDN 配信の JSON データから引く SDK。`jpzip.nadai.dev` から取得する。
+
+- 配信ドメイン: `https://jpzip.nadai.dev`
+- プロトコル仕様: [`jpzip/spec`](https://github.com/jpzip/spec)
+- データ ETL: [`jpzip/data`](https://github.com/jpzip/data)
+
+## インストール
+
+```sh
+npm install @jpzip/jpzip
+# or
+pnpm add @jpzip/jpzip
+```
+
+## 使い方
+
+### 関数 API
+
+```ts
+import { lookup, lookupGroup, lookupAll, preload, getMeta } from '@jpzip/jpzip';
+
+const entry = await lookup('2310017');
+// → { prefecture: '神奈川県', city: '横浜市中区', towns: [...], ... }
+
+const dict231 = await lookupGroup('231'); // /p/231.json
+const dict23  = await lookupGroup('23');  // /p/230.json - /p/239.json を並列 fetch
+const dict2   = await lookupGroup('2');   // /g/2.json
+
+const all = await lookupAll(); // /all.json (大きい)
+const meta = await getMeta();
+```
+
+### クラス API (L2 キャッシュ・複数インスタンス用)
+
+```ts
+import { JpzipClient } from '@jpzip/jpzip';
+
+const client = new JpzipClient({
+  baseUrl: 'https://jpzip.nadai.dev',
+  memoryCacheSize: 200,
+  // 永続キャッシュ (Cache インターフェースを満たす任意の実装)
+  cache: {
+    async get(k) { /* ... */ return null; },
+    async set(k, v) { /* ... */ },
+    async delete(k) { /* ... */ },
+    async clear() { /* ... */ },
+  },
+});
+
+await client.preload({ scope: 'all' }); // オフラインモード相当
+const entry = await client.lookup('2310017');
+```
+
+## キャッシュ戦略 (3 層)
+
+| 層 | 目的 | 既定 |
+|---|---|---|
+| **L1 メモリ LRU** | 同一プロセスの重複 fetch 抑制 | 常時 ON、prefix 100 件保持 |
+| **L2 永続キャッシュ** | 起動またぎ / preload 結果保持 | OFF、`cache` オプションで有効化 |
+| **L3 HTTP** | ブラウザ / OS のキャッシュ | SDK 制御外 |
+
+詳しくは [`jpzip/spec` §6.4](https://github.com/jpzip/spec/blob/main/spec/v1/protocol.md) を参照。
+
+## API
+
+| 関数 | 説明 |
+|---|---|
+| `lookup(zipcode)` | 単一 zipcode を引く。`null` は「見つからない」 |
+| `lookupGroup(prefix)` | 1〜3 桁の prefix 配下を返す |
+| `lookupAll()` | 全件辞書 (preload 用) |
+| `preload({scope})` | `'all'` または prefix を SDK 内キャッシュに格納 |
+| `getMeta()` | `/meta.json` を取得・キャッシュ |
+| `isValidZipcode(zip)` | 7 桁数字フォーマット検証 |
+| `configure(options)` | グローバルシングルトンのオプション差し替え |
+
+## 入力検証
+
+`lookup()` は `^\d{7}$` にマッチしない入力には fetch せず `null` を返す。
+
+## バージョン整合性
+
+`getMeta()` 初回呼び出し時、`spec_version` が SDK 対応バージョン (`"1.0"`) と異なる場合は `onSpecMismatch` コールバックを 1 回呼ぶ。`version` (データバージョン) が変わったらキャッシュを自動 invalidate。
+
+## ライセンス
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,301 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  JpzipClient: () => JpzipClient,
+  MemoryLRU: () => MemoryLRU,
+  _resetDefaultClient: () => _resetDefaultClient,
+  configure: () => configure,
+  getMeta: () => getMeta,
+  isValidZipcode: () => isValidZipcode,
+  lookup: () => lookup,
+  lookupAll: () => lookupAll,
+  lookupGroup: () => lookupGroup,
+  preload: () => preload
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/cache.ts
+var MemoryLRU = class {
+  max;
+  map = /* @__PURE__ */ new Map();
+  constructor(max = 100) {
+    this.max = Math.max(1, max);
+  }
+  get(key) {
+    const value = this.map.get(key);
+    if (value === void 0) return void 0;
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.max) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey !== void 0) this.map.delete(oldestKey);
+    }
+    this.map.set(key, value);
+  }
+  clear() {
+    this.map.clear();
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+
+// src/fetch.ts
+var MAX_RETRIES = 3;
+var BASE_DELAY_MS = 200;
+async function fetchJSON(url, opts = {}) {
+  const f = opts.fetch ?? fetch;
+  let lastErr;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      await sleep(BASE_DELAY_MS * 2 ** attempt);
+    }
+    try {
+      const init = {
+        method: "GET",
+        headers: { Accept: "application/json" }
+      };
+      if (opts.signal !== void 0) init.signal = opts.signal;
+      if (opts.noCache) init.cache = "no-cache";
+      const res = await f(url, init);
+      if (res.status === 404) return null;
+      if (res.status >= 500) {
+        lastErr = new Error(`jpzip: ${url} returned ${res.status}`);
+        continue;
+      }
+      if (!res.ok) {
+        throw new Error(`jpzip: ${url} returned ${res.status}`);
+      }
+      return await res.json();
+    } catch (err) {
+      lastErr = err;
+      if (err instanceof DOMException && err.name === "AbortError") throw err;
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error(`jpzip: fetch failed for ${url}: ${String(lastErr)}`);
+}
+var fetchDict = (url, opts) => fetchJSON(url, opts);
+var fetchMeta = (url, opts) => fetchJSON(url, opts);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://jpzip.nadai.dev";
+var SUPPORTED_SPEC = "1.0";
+var ZIP_REGEX = /^\d{7}$/;
+var PREFIX_REGEX = /^\d{1,3}$/;
+var JpzipClient = class {
+  baseUrl;
+  cache;
+  fetchImpl;
+  mem;
+  onSpecMismatch;
+  metaPromise = null;
+  knownVersion = null;
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.cache = opts.cache;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.mem = new MemoryLRU(opts.memoryCacheSize ?? 100);
+    this.onSpecMismatch = opts.onSpecMismatch;
+  }
+  /** Returns the entry for `zipcode`, or null if not found. */
+  async lookup(zipcode) {
+    if (!ZIP_REGEX.test(zipcode)) return null;
+    const prefix = zipcode.slice(0, 3);
+    const dict = await this.fetchPrefixDict(prefix);
+    if (!dict) return null;
+    return dict[zipcode] ?? null;
+  }
+  /** Returns the dictionary for a 1- or 3-digit prefix (2-digit is fanned out). */
+  async lookupGroup(prefix) {
+    if (!PREFIX_REGEX.test(prefix)) {
+      throw new Error(`jpzip: invalid prefix ${JSON.stringify(prefix)} (must be 1-3 digits)`);
+    }
+    if (prefix.length === 3) {
+      return await this.fetchPrefixDict(prefix) ?? {};
+    }
+    if (prefix.length === 1) {
+      const dict = await this.fetchGroupDict(prefix);
+      return dict ?? {};
+    }
+    const tasks = [];
+    for (let i = 0; i < 10; i++) {
+      tasks.push(this.fetchPrefixDict(`${prefix}${i}`));
+    }
+    const dicts = await Promise.all(tasks);
+    return Object.assign({}, ...dicts.filter(Boolean));
+  }
+  /**
+   * Returns the full dataset. The CDN does not expose a single /all.json
+   * because the combined file exceeds Cloudflare Pages' 25 MiB per-file
+   * limit; instead we fan out across /g/0..9.json in parallel and merge.
+   */
+  async lookupAll() {
+    const tasks = [];
+    for (let i = 0; i < 10; i++) {
+      tasks.push(this.fetchGroupDict(String(i)));
+    }
+    const dicts = await Promise.all(tasks);
+    return Object.assign({}, ...dicts.filter(Boolean));
+  }
+  /** Returns parsed meta.json, or null if the CDN has none yet. */
+  async getMeta() {
+    if (this.metaPromise === null) {
+      this.metaPromise = (async () => {
+        const m = await fetchMeta(`${this.baseUrl}/meta.json`, this.fetchOpts());
+        if (m && m.spec_version !== SUPPORTED_SPEC) {
+          this.onSpecMismatch?.({ expected: SUPPORTED_SPEC, received: m.spec_version });
+        }
+        if (m && this.knownVersion && this.knownVersion !== m.version) {
+          this.mem.clear();
+          await this.cache?.clear();
+        }
+        if (m) this.knownVersion = m.version;
+        return m;
+      })();
+    }
+    return this.metaPromise;
+  }
+  /**
+   * preload pulls the requested scope into both L1 (per-prefix entries) and
+   * L2 (when provided) so subsequent reads need no network.
+   */
+  async preload(opts) {
+    if (opts.scope === "all") {
+      const dict = await this.lookupAll();
+      const buckets = {};
+      for (const [zip, entry] of Object.entries(dict)) {
+        const p = zip.slice(0, 3);
+        (buckets[p] ??= {})[zip] = entry;
+      }
+      for (const [p, b] of Object.entries(buckets)) {
+        this.mem.set(this.prefixURL(p), b);
+        await this.writeL2(this.prefixURL(p), b);
+      }
+      return;
+    }
+    if (PREFIX_REGEX.test(opts.scope)) {
+      await this.lookupGroup(opts.scope);
+      return;
+    }
+    throw new Error(`jpzip: invalid preload scope ${JSON.stringify(opts.scope)}`);
+  }
+  /** Clear all SDK-managed caches (L1 + L2). */
+  async refresh() {
+    this.mem.clear();
+    this.metaPromise = null;
+    this.knownVersion = null;
+    await this.cache?.clear();
+  }
+  /* ----------------------------- internals ------------------------------ */
+  async fetchPrefixDict(prefix) {
+    const url = this.prefixURL(prefix);
+    const cached = this.mem.get(url);
+    if (cached) return cached;
+    const fromL2 = await this.readL2(url);
+    if (fromL2) {
+      this.mem.set(url, fromL2);
+      return fromL2;
+    }
+    const dict = await fetchDict(url, this.fetchOpts());
+    if (dict) {
+      this.mem.set(url, dict);
+      await this.writeL2(url, dict);
+    }
+    return dict;
+  }
+  async fetchGroupDict(prefix1) {
+    const url = `${this.baseUrl}/g/${prefix1}.json`;
+    const cached = this.mem.get(url);
+    if (cached) return cached;
+    const dict = await fetchDict(url, this.fetchOpts());
+    if (dict) this.mem.set(url, dict);
+    return dict;
+  }
+  prefixURL(prefix3) {
+    return `${this.baseUrl}/p/${prefix3}.json`;
+  }
+  fetchOpts() {
+    return { fetch: this.fetchImpl };
+  }
+  async readL2(url) {
+    if (!this.cache) return null;
+    const bytes = await this.cache.get(url);
+    if (!bytes) return null;
+    try {
+      const text = new TextDecoder().decode(bytes);
+      return JSON.parse(text);
+    } catch {
+      await this.cache.delete(url);
+      return null;
+    }
+  }
+  async writeL2(url, dict) {
+    if (!this.cache) return;
+    const bytes = new TextEncoder().encode(JSON.stringify(dict));
+    await this.cache.set(url, bytes);
+  }
+};
+
+// src/index.ts
+var _default = null;
+function defaultClient() {
+  if (_default === null) _default = new JpzipClient();
+  return _default;
+}
+function _resetDefaultClient() {
+  _default = null;
+}
+function configure(options) {
+  _default = new JpzipClient(options);
+}
+var lookup = (zipcode) => defaultClient().lookup(zipcode);
+var lookupGroup = (prefix) => defaultClient().lookupGroup(prefix);
+var lookupAll = () => defaultClient().lookupAll();
+var preload = (opts) => defaultClient().preload(opts);
+var getMeta = () => defaultClient().getMeta();
+function isValidZipcode(zip) {
+  return /^\d{7}$/.test(zip);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_URL,
+  JpzipClient,
+  MemoryLRU,
+  _resetDefaultClient,
+  configure,
+  getMeta,
+  isValidZipcode,
+  lookup,
+  lookupAll,
+  lookupGroup,
+  preload
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/cache.ts","../src/fetch.ts","../src/client.ts"],"sourcesContent":["export { JpzipClient, DEFAULT_BASE_URL, type JpzipClientOptions } from './client.js';\nexport { MemoryLRU, type PersistentCache } from './cache.js';\nexport type { ZipcodeEntry, Town, Meta, ZipcodeDict, Endpoints } from './types.js';\n\nimport { JpzipClient } from './client.js';\nimport type { Meta, ZipcodeDict, ZipcodeEntry } from './types.js';\n\n/**\n * The functional helpers below all delegate to a lazily-initialized default\n * client (L1 cache only, default base URL). For multiple SDK instances or\n * an L2 cache, construct `new JpzipClient({...})` yourself.\n */\n\nlet _default: JpzipClient | null = null;\nfunction defaultClient(): JpzipClient {\n  if (_default === null) _default = new JpzipClient();\n  return _default;\n}\n\n/** Reset the singleton (mainly for tests). */\nexport function _resetDefaultClient(): void {\n  _default = null;\n}\n\n/** Configure the singleton's options. Subsequent calls re-create the client. */\nexport function configure(options: ConstructorParameters<typeof JpzipClient>[0]): void {\n  _default = new JpzipClient(options);\n}\n\nexport const lookup = (zipcode: string): Promise<ZipcodeEntry | null> =>\n  defaultClient().lookup(zipcode);\n\nexport const lookupGroup = (prefix: string): Promise<ZipcodeDict> =>\n  defaultClient().lookupGroup(prefix);\n\nexport const lookupAll = (): Promise<ZipcodeDict> => defaultClient().lookupAll();\n\nexport const preload = (opts: Parameters<JpzipClient['preload']>[0]): Promise<void> =>\n  defaultClient().preload(opts);\n\nexport const getMeta = (): Promise<Meta | null> => defaultClient().getMeta();\n\n/** Helper: returns true iff `zip` is a syntactically valid 7-digit zipcode. */\nexport function isValidZipcode(zip: string): boolean {\n  return /^\\d{7}$/.test(zip);\n}\n","/**\n * Three-layer caching per spec §6.4:\n *\n *  - L1 (MemoryLRU)     — always on, bounded\n *  - L2 (PersistentCache) — opt-in via constructor\n *  - L3 (HTTP/fetch)    — out of SDK scope\n */\n\nimport type { ZipcodeDict } from './types.js';\n\n/** Public interface user-supplied L2 caches must implement. */\nexport interface PersistentCache {\n  get(key: string): Promise<Uint8Array | null>;\n  set(key: string, value: Uint8Array): Promise<void>;\n  delete(key: string): Promise<void>;\n  clear(): Promise<void>;\n}\n\n/** Bounded in-memory LRU keyed by URL path. Values are pre-parsed dicts. */\nexport class MemoryLRU {\n  private readonly max: number;\n  private readonly map = new Map<string, ZipcodeDict>();\n\n  constructor(max = 100) {\n    this.max = Math.max(1, max);\n  }\n\n  get(key: string): ZipcodeDict | undefined {\n    const value = this.map.get(key);\n    if (value === undefined) return undefined;\n    // refresh recency by re-inserting at the tail\n    this.map.delete(key);\n    this.map.set(key, value);\n    return value;\n  }\n\n  set(key: string, value: ZipcodeDict): void {\n    if (this.map.has(key)) {\n      this.map.delete(key);\n    } else if (this.map.size >= this.max) {\n      const oldestKey = this.map.keys().next().value;\n      if (oldestKey !== undefined) this.map.delete(oldestKey);\n    }\n    this.map.set(key, value);\n  }\n\n  clear(): void {\n    this.map.clear();\n  }\n\n  get size(): number {\n    return this.map.size;\n  }\n}\n","/** HTTP helpers with exponential-backoff retry for transient 5xx and network errors. */\n\nimport type { ZipcodeDict, Meta } from './types.js';\n\nconst MAX_RETRIES = 3;\nconst BASE_DELAY_MS = 200;\n\nexport interface FetchOptions {\n  /** Override the global fetch (mainly for tests). */\n  fetch?: typeof fetch;\n  /** Pass-through to fetch(). */\n  signal?: AbortSignal;\n  /** Forces no-cache; useful when the user explicitly refreshes. */\n  noCache?: boolean;\n}\n\n/**\n * fetchJSON returns the parsed JSON body for url. On 404 it returns null.\n * On 5xx / network errors it retries up to MAX_RETRIES with exponential backoff.\n * Other 4xx errors throw.\n */\nexport async function fetchJSON<T>(url: string, opts: FetchOptions = {}): Promise<T | null> {\n  const f = opts.fetch ?? fetch;\n\n  let lastErr: unknown;\n  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {\n    if (attempt > 0) {\n      await sleep(BASE_DELAY_MS * 2 ** attempt);\n    }\n    try {\n      const init: RequestInit = {\n        method: 'GET',\n        headers: { Accept: 'application/json' },\n      };\n      if (opts.signal !== undefined) init.signal = opts.signal;\n      if (opts.noCache) init.cache = 'no-cache';\n\n      const res = await f(url, init);\n      if (res.status === 404) return null;\n      if (res.status >= 500) {\n        lastErr = new Error(`jpzip: ${url} returned ${res.status}`);\n        continue;\n      }\n      if (!res.ok) {\n        throw new Error(`jpzip: ${url} returned ${res.status}`);\n      }\n      return (await res.json()) as T;\n    } catch (err) {\n      lastErr = err;\n      if (err instanceof DOMException && err.name === 'AbortError') throw err;\n    }\n  }\n  throw lastErr instanceof Error\n    ? lastErr\n    : new Error(`jpzip: fetch failed for ${url}: ${String(lastErr)}`);\n}\n\n/** Convenience aliases with parameterized return types. */\nexport const fetchDict = (url: string, opts?: FetchOptions): Promise<ZipcodeDict | null> =>\n  fetchJSON<ZipcodeDict>(url, opts);\n\nexport const fetchMeta = (url: string, opts?: FetchOptions): Promise<Meta | null> =>\n  fetchJSON<Meta>(url, opts);\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n","import { MemoryLRU, type PersistentCache } from './cache.js';\nimport { fetchDict, fetchMeta, type FetchOptions } from './fetch.js';\nimport type { Meta, ZipcodeDict, ZipcodeEntry } from './types.js';\n\nexport const DEFAULT_BASE_URL = 'https://jpzip.nadai.dev';\nconst SUPPORTED_SPEC = '1.0';\n\nexport interface JpzipClientOptions {\n  /** Override the CDN origin. Defaults to https://jpzip.nadai.dev */\n  baseUrl?: string;\n  /** L2 persistent cache. Default off. */\n  cache?: PersistentCache;\n  /** Override fetch (mainly tests). */\n  fetch?: typeof fetch;\n  /** L1 LRU capacity in prefix count. Default 100. */\n  memoryCacheSize?: number;\n  /** Surface a warning to the user when spec_version mismatches. */\n  onSpecMismatch?: (info: { expected: string; received: string }) => void;\n}\n\nconst ZIP_REGEX = /^\\d{7}$/;\nconst PREFIX_REGEX = /^\\d{1,3}$/;\n\n/**\n * JpzipClient is the SDK entrypoint. The functional shortcuts (`lookup`,\n * `lookupGroup`, …) below delegate to a default singleton instance backed\n * by L1 only.\n */\nexport class JpzipClient {\n  private readonly baseUrl: string;\n  private readonly cache: PersistentCache | undefined;\n  private readonly fetchImpl: typeof fetch;\n  private readonly mem: MemoryLRU;\n  private readonly onSpecMismatch: JpzipClientOptions['onSpecMismatch'];\n  private metaPromise: Promise<Meta | null> | null = null;\n  private knownVersion: string | null = null;\n\n  constructor(opts: JpzipClientOptions = {}) {\n    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.cache = opts.cache;\n    this.fetchImpl = opts.fetch ?? globalThis.fetch;\n    this.mem = new MemoryLRU(opts.memoryCacheSize ?? 100);\n    this.onSpecMismatch = opts.onSpecMismatch;\n  }\n\n  /** Returns the entry for `zipcode`, or null if not found. */\n  async lookup(zipcode: string): Promise<ZipcodeEntry | null> {\n    if (!ZIP_REGEX.test(zipcode)) return null;\n    const prefix = zipcode.slice(0, 3);\n    const dict = await this.fetchPrefixDict(prefix);\n    if (!dict) return null;\n    return dict[zipcode] ?? null;\n  }\n\n  /** Returns the dictionary for a 1- or 3-digit prefix (2-digit is fanned out). */\n  async lookupGroup(prefix: string): Promise<ZipcodeDict> {\n    if (!PREFIX_REGEX.test(prefix)) {\n      throw new Error(`jpzip: invalid prefix ${JSON.stringify(prefix)} (must be 1-3 digits)`);\n    }\n    if (prefix.length === 3) {\n      return (await this.fetchPrefixDict(prefix)) ?? {};\n    }\n    if (prefix.length === 1) {\n      const dict = await this.fetchGroupDict(prefix);\n      return dict ?? {};\n    }\n    // 2-digit fanout\n    const tasks: Promise<ZipcodeDict | null>[] = [];\n    for (let i = 0; i < 10; i++) {\n      tasks.push(this.fetchPrefixDict(`${prefix}${i}`));\n    }\n    const dicts = await Promise.all(tasks);\n    return Object.assign({}, ...dicts.filter(Boolean)) as ZipcodeDict;\n  }\n\n  /**\n   * Returns the full dataset. The CDN does not expose a single /all.json\n   * because the combined file exceeds Cloudflare Pages' 25 MiB per-file\n   * limit; instead we fan out across /g/0..9.json in parallel and merge.\n   */\n  async lookupAll(): Promise<ZipcodeDict> {\n    const tasks: Promise<ZipcodeDict | null>[] = [];\n    for (let i = 0; i < 10; i++) {\n      tasks.push(this.fetchGroupDict(String(i)));\n    }\n    const dicts = await Promise.all(tasks);\n    return Object.assign({}, ...dicts.filter(Boolean)) as ZipcodeDict;\n  }\n\n  /** Returns parsed meta.json, or null if the CDN has none yet. */\n  async getMeta(): Promise<Meta | null> {\n    if (this.metaPromise === null) {\n      this.metaPromise = (async () => {\n        const m = await fetchMeta(`${this.baseUrl}/meta.json`, this.fetchOpts());\n        if (m && m.spec_version !== SUPPORTED_SPEC) {\n          this.onSpecMismatch?.({ expected: SUPPORTED_SPEC, received: m.spec_version });\n        }\n        if (m && this.knownVersion && this.knownVersion !== m.version) {\n          // data version changed — drop L1 + L2 to avoid stale reads\n          this.mem.clear();\n          await this.cache?.clear();\n        }\n        if (m) this.knownVersion = m.version;\n        return m;\n      })();\n    }\n    return this.metaPromise;\n  }\n\n  /**\n   * preload pulls the requested scope into both L1 (per-prefix entries) and\n   * L2 (when provided) so subsequent reads need no network.\n   */\n  async preload(opts: { scope: 'all' } | { scope: string }): Promise<void> {\n    if (opts.scope === 'all') {\n      const dict = await this.lookupAll();\n      // Split into prefix buckets and prime L1.\n      const buckets: Record<string, ZipcodeDict> = {};\n      for (const [zip, entry] of Object.entries(dict)) {\n        const p = zip.slice(0, 3);\n        (buckets[p] ??= {})[zip] = entry;\n      }\n      for (const [p, b] of Object.entries(buckets)) {\n        this.mem.set(this.prefixURL(p), b);\n        await this.writeL2(this.prefixURL(p), b);\n      }\n      return;\n    }\n    if (PREFIX_REGEX.test(opts.scope)) {\n      await this.lookupGroup(opts.scope);\n      return;\n    }\n    throw new Error(`jpzip: invalid preload scope ${JSON.stringify(opts.scope)}`);\n  }\n\n  /** Clear all SDK-managed caches (L1 + L2). */\n  async refresh(): Promise<void> {\n    this.mem.clear();\n    this.metaPromise = null;\n    this.knownVersion = null;\n    await this.cache?.clear();\n  }\n\n  /* ----------------------------- internals ------------------------------ */\n\n  private async fetchPrefixDict(prefix: string): Promise<ZipcodeDict | null> {\n    const url = this.prefixURL(prefix);\n    const cached = this.mem.get(url);\n    if (cached) return cached;\n\n    const fromL2 = await this.readL2(url);\n    if (fromL2) {\n      this.mem.set(url, fromL2);\n      return fromL2;\n    }\n\n    const dict = await fetchDict(url, this.fetchOpts());\n    if (dict) {\n      this.mem.set(url, dict);\n      await this.writeL2(url, dict);\n    }\n    return dict;\n  }\n\n  private async fetchGroupDict(prefix1: string): Promise<ZipcodeDict | null> {\n    const url = `${this.baseUrl}/g/${prefix1}.json`;\n    const cached = this.mem.get(url);\n    if (cached) return cached;\n    const dict = await fetchDict(url, this.fetchOpts());\n    if (dict) this.mem.set(url, dict);\n    return dict;\n  }\n\n  private prefixURL(prefix3: string): string {\n    return `${this.baseUrl}/p/${prefix3}.json`;\n  }\n\n  private fetchOpts(): FetchOptions {\n    return { fetch: this.fetchImpl };\n  }\n\n  private async readL2(url: string): Promise<ZipcodeDict | null> {\n    if (!this.cache) return null;\n    const bytes = await this.cache.get(url);\n    if (!bytes) return null;\n    try {\n      const text = new TextDecoder().decode(bytes);\n      return JSON.parse(text) as ZipcodeDict;\n    } catch {\n      // corrupt cache — drop the entry and refetch\n      await this.cache.delete(url);\n      return null;\n    }\n  }\n\n  private async writeL2(url: string, dict: ZipcodeDict): Promise<void> {\n    if (!this.cache) return;\n    const bytes = new TextEncoder().encode(JSON.stringify(dict));\n    await this.cache.set(url, bytes);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBO,IAAM,YAAN,MAAgB;AAAA,EACJ;AAAA,EACA,MAAM,oBAAI,IAAyB;AAAA,EAEpD,YAAY,MAAM,KAAK;AACrB,SAAK,MAAM,KAAK,IAAI,GAAG,GAAG;AAAA,EAC5B;AAAA,EAEA,IAAI,KAAsC;AACxC,UAAM,QAAQ,KAAK,IAAI,IAAI,GAAG;AAC9B,QAAI,UAAU,OAAW,QAAO;AAEhC,SAAK,IAAI,OAAO,GAAG;AACnB,SAAK,IAAI,IAAI,KAAK,KAAK;AACvB,WAAO;AAAA,EACT;AAAA,EAEA,IAAI,KAAa,OAA0B;AACzC,QAAI,KAAK,IAAI,IAAI,GAAG,GAAG;AACrB,WAAK,IAAI,OAAO,GAAG;AAAA,IACrB,WAAW,KAAK,IAAI,QAAQ,KAAK,KAAK;AACpC,YAAM,YAAY,KAAK,IAAI,KAAK,EAAE,KAAK,EAAE;AACzC,UAAI,cAAc,OAAW,MAAK,IAAI,OAAO,SAAS;AAAA,IACxD;AACA,SAAK,IAAI,IAAI,KAAK,KAAK;AAAA,EACzB;AAAA,EAEA,QAAc;AACZ,SAAK,IAAI,MAAM;AAAA,EACjB;AAAA,EAEA,IAAI,OAAe;AACjB,WAAO,KAAK,IAAI;AAAA,EAClB;AACF;;;ACjDA,IAAM,cAAc;AACpB,IAAM,gBAAgB;AAgBtB,eAAsB,UAAa,KAAa,OAAqB,CAAC,GAAsB;AAC1F,QAAM,IAAI,KAAK,SAAS;AAExB,MAAI;AACJ,WAAS,UAAU,GAAG,UAAU,aAAa,WAAW;AACtD,QAAI,UAAU,GAAG;AACf,YAAM,MAAM,gBAAgB,KAAK,OAAO;AAAA,IAC1C;AACA,QAAI;AACF,YAAM,OAAoB;AAAA,QACxB,QAAQ;AAAA,QACR,SAAS,EAAE,QAAQ,mBAAmB;AAAA,MACxC;AACA,UAAI,KAAK,WAAW,OAAW,MAAK,SAAS,KAAK;AAClD,UAAI,KAAK,QAAS,MAAK,QAAQ;AAE/B,YAAM,MAAM,MAAM,EAAE,KAAK,IAAI;AAC7B,UAAI,IAAI,WAAW,IAAK,QAAO;AAC/B,UAAI,IAAI,UAAU,KAAK;AACrB,kBAAU,IAAI,MAAM,UAAU,GAAG,aAAa,IAAI,MAAM,EAAE;AAC1D;AAAA,MACF;AACA,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI,MAAM,UAAU,GAAG,aAAa,IAAI,MAAM,EAAE;AAAA,MACxD;AACA,aAAQ,MAAM,IAAI,KAAK;AAAA,IACzB,SAAS,KAAK;AACZ,gBAAU;AACV,UAAI,eAAe,gBAAgB,IAAI,SAAS,aAAc,OAAM;AAAA,IACtE;AAAA,EACF;AACA,QAAM,mBAAmB,QACrB,UACA,IAAI,MAAM,2BAA2B,GAAG,KAAK,OAAO,OAAO,CAAC,EAAE;AACpE;AAGO,IAAM,YAAY,CAAC,KAAa,SACrC,UAAuB,KAAK,IAAI;AAE3B,IAAM,YAAY,CAAC,KAAa,SACrC,UAAgB,KAAK,IAAI;AAE3B,SAAS,MAAM,IAA2B;AACxC,SAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AACzD;;;AC9DO,IAAM,mBAAmB;AAChC,IAAM,iBAAiB;AAevB,IAAM,YAAY;AAClB,IAAM,eAAe;AAOd,IAAM,cAAN,MAAkB;AAAA,EACN;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACT,cAA2C;AAAA,EAC3C,eAA8B;AAAA,EAEtC,YAAY,OAA2B,CAAC,GAAG;AACzC,SAAK,WAAW,KAAK,WAAW,kBAAkB,QAAQ,OAAO,EAAE;AACnE,SAAK,QAAQ,KAAK;AAClB,SAAK,YAAY,KAAK,SAAS,WAAW;AAC1C,SAAK,MAAM,IAAI,UAAU,KAAK,mBAAmB,GAAG;AACpD,SAAK,iBAAiB,KAAK;AAAA,EAC7B;AAAA;AAAA,EAGA,MAAM,OAAO,SAA+C;AAC1D,QAAI,CAAC,UAAU,KAAK,OAAO,EAAG,QAAO;AACrC,UAAM,SAAS,QAAQ,MAAM,GAAG,CAAC;AACjC,UAAM,OAAO,MAAM,KAAK,gBAAgB,MAAM;AAC9C,QAAI,CAAC,KAAM,QAAO;AAClB,WAAO,KAAK,OAAO,KAAK;AAAA,EAC1B;AAAA;AAAA,EAGA,MAAM,YAAY,QAAsC;AACtD,QAAI,CAAC,aAAa,KAAK,MAAM,GAAG;AAC9B,YAAM,IAAI,MAAM,yBAAyB,KAAK,UAAU,MAAM,CAAC,uBAAuB;AAAA,IACxF;AACA,QAAI,OAAO,WAAW,GAAG;AACvB,aAAQ,MAAM,KAAK,gBAAgB,MAAM,KAAM,CAAC;AAAA,IAClD;AACA,QAAI,OAAO,WAAW,GAAG;AACvB,YAAM,OAAO,MAAM,KAAK,eAAe,MAAM;AAC7C,aAAO,QAAQ,CAAC;AAAA,IAClB;AAEA,UAAM,QAAuC,CAAC;AAC9C,aAAS,IAAI,GAAG,IAAI,IAAI,KAAK;AAC3B,YAAM,KAAK,KAAK,gBAAgB,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC;AAAA,IAClD;AACA,UAAM,QAAQ,MAAM,QAAQ,IAAI,KAAK;AACrC,WAAO,OAAO,OAAO,CAAC,GAAG,GAAG,MAAM,OAAO,OAAO,CAAC;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,YAAkC;AACtC,UAAM,QAAuC,CAAC;AAC9C,aAAS,IAAI,GAAG,IAAI,IAAI,KAAK;AAC3B,YAAM,KAAK,KAAK,eAAe,OAAO,CAAC,CAAC,CAAC;AAAA,IAC3C;AACA,UAAM,QAAQ,MAAM,QAAQ,IAAI,KAAK;AACrC,WAAO,OAAO,OAAO,CAAC,GAAG,GAAG,MAAM,OAAO,OAAO,CAAC;AAAA,EACnD;AAAA;AAAA,EAGA,MAAM,UAAgC;AACpC,QAAI,KAAK,gBAAgB,MAAM;AAC7B,WAAK,eAAe,YAAY;AAC9B,cAAM,IAAI,MAAM,UAAU,GAAG,KAAK,OAAO,cAAc,KAAK,UAAU,CAAC;AACvE,YAAI,KAAK,EAAE,iBAAiB,gBAAgB;AAC1C,eAAK,iBAAiB,EAAE,UAAU,gBAAgB,UAAU,EAAE,aAAa,CAAC;AAAA,QAC9E;AACA,YAAI,KAAK,KAAK,gBAAgB,KAAK,iBAAiB,EAAE,SAAS;AAE7D,eAAK,IAAI,MAAM;AACf,gBAAM,KAAK,OAAO,MAAM;AAAA,QAC1B;AACA,YAAI,EAAG,MAAK,eAAe,EAAE;AAC7B,eAAO;AAAA,MACT,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,QAAQ,MAA2D;AACvE,QAAI,KAAK,UAAU,OAAO;AACxB,YAAM,OAAO,MAAM,KAAK,UAAU;AAElC,YAAM,UAAuC,CAAC;AAC9C,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,cAAM,IAAI,IAAI,MAAM,GAAG,CAAC;AACxB,SAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI;AAAA,MAC7B;AACA,iBAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,OAAO,GAAG;AAC5C,aAAK,IAAI,IAAI,KAAK,UAAU,CAAC,GAAG,CAAC;AACjC,cAAM,KAAK,QAAQ,KAAK,UAAU,CAAC,GAAG,CAAC;AAAA,MACzC;AACA;AAAA,IACF;AACA,QAAI,aAAa,KAAK,KAAK,KAAK,GAAG;AACjC,YAAM,KAAK,YAAY,KAAK,KAAK;AACjC;AAAA,IACF;AACA,UAAM,IAAI,MAAM,gCAAgC,KAAK,UAAU,KAAK,KAAK,CAAC,EAAE;AAAA,EAC9E;AAAA;AAAA,EAGA,MAAM,UAAyB;AAC7B,SAAK,IAAI,MAAM;AACf,SAAK,cAAc;AACnB,SAAK,eAAe;AACpB,UAAM,KAAK,OAAO,MAAM;AAAA,EAC1B;AAAA;AAAA,EAIA,MAAc,gBAAgB,QAA6C;AACzE,UAAM,MAAM,KAAK,UAAU,MAAM;AACjC,UAAM,SAAS,KAAK,IAAI,IAAI,GAAG;AAC/B,QAAI,OAAQ,QAAO;AAEnB,UAAM,SAAS,MAAM,KAAK,OAAO,GAAG;AACpC,QAAI,QAAQ;AACV,WAAK,IAAI,IAAI,KAAK,MAAM;AACxB,aAAO;AAAA,IACT;AAEA,UAAM,OAAO,MAAM,UAAU,KAAK,KAAK,UAAU,CAAC;AAClD,QAAI,MAAM;AACR,WAAK,IAAI,IAAI,KAAK,IAAI;AACtB,YAAM,KAAK,QAAQ,KAAK,IAAI;AAAA,IAC9B;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,eAAe,SAA8C;AACzE,UAAM,MAAM,GAAG,KAAK,OAAO,MAAM,OAAO;AACxC,UAAM,SAAS,KAAK,IAAI,IAAI,GAAG;AAC/B,QAAI,OAAQ,QAAO;AACnB,UAAM,OAAO,MAAM,UAAU,KAAK,KAAK,UAAU,CAAC;AAClD,QAAI,KAAM,MAAK,IAAI,IAAI,KAAK,IAAI;AAChC,WAAO;AAAA,EACT;AAAA,EAEQ,UAAU,SAAyB;AACzC,WAAO,GAAG,KAAK,OAAO,MAAM,OAAO;AAAA,EACrC;AAAA,EAEQ,YAA0B;AAChC,WAAO,EAAE,OAAO,KAAK,UAAU;AAAA,EACjC;AAAA,EAEA,MAAc,OAAO,KAA0C;AAC7D,QAAI,CAAC,KAAK,MAAO,QAAO;AACxB,UAAM,QAAQ,MAAM,KAAK,MAAM,IAAI,GAAG;AACtC,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI;AACF,YAAM,OAAO,IAAI,YAAY,EAAE,OAAO,KAAK;AAC3C,aAAO,KAAK,MAAM,IAAI;AAAA,IACxB,QAAQ;AAEN,YAAM,KAAK,MAAM,OAAO,GAAG;AAC3B,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,MAAc,QAAQ,KAAa,MAAkC;AACnE,QAAI,CAAC,KAAK,MAAO;AACjB,UAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,IAAI,CAAC;AAC3D,UAAM,KAAK,MAAM,IAAI,KAAK,KAAK;AAAA,EACjC;AACF;;;AH3LA,IAAI,WAA+B;AACnC,SAAS,gBAA6B;AACpC,MAAI,aAAa,KAAM,YAAW,IAAI,YAAY;AAClD,SAAO;AACT;AAGO,SAAS,sBAA4B;AAC1C,aAAW;AACb;AAGO,SAAS,UAAU,SAA6D;AACrF,aAAW,IAAI,YAAY,OAAO;AACpC;AAEO,IAAM,SAAS,CAAC,YACrB,cAAc,EAAE,OAAO,OAAO;AAEzB,IAAM,cAAc,CAAC,WAC1B,cAAc,EAAE,YAAY,MAAM;AAE7B,IAAM,YAAY,MAA4B,cAAc,EAAE,UAAU;AAExE,IAAM,UAAU,CAAC,SACtB,cAAc,EAAE,QAAQ,IAAI;AAEvB,IAAM,UAAU,MAA4B,cAAc,EAAE,QAAQ;AAGpE,SAAS,eAAe,KAAsB;AACnD,SAAO,UAAU,KAAK,GAAG;AAC3B;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,138 @@
+/**
+ * Types mirroring the jpzip protocol specification (spec_version 1.0).
+ * Mirror of https://github.com/jpzip/spec/blob/main/schema/v1/zipcode-entry.json
+ */
+interface Town {
+    town: string;
+    kana: string;
+    roma: string;
+    note?: string;
+}
+interface ZipcodeEntry {
+    prefecture: string;
+    prefecture_kana: string;
+    prefecture_roma: string;
+    prefecture_code: string;
+    city: string;
+    city_kana: string;
+    city_roma: string;
+    city_code: string;
+    towns: Town[];
+}
+interface Endpoints {
+    group: string;
+    prefix: string;
+}
+interface Meta {
+    version: string;
+    generated_at: string;
+    spec_version: string;
+    total_zipcodes: number;
+    prefix_count: number;
+    by_pref: Record<string, number>;
+    data_source: string;
+    endpoints: Endpoints;
+}
+/** Dictionary keyed by 7-digit zipcode string, as published by the CDN. */
+type ZipcodeDict = Record<string, ZipcodeEntry>;
+
+/**
+ * Three-layer caching per spec §6.4:
+ *
+ *  - L1 (MemoryLRU)     — always on, bounded
+ *  - L2 (PersistentCache) — opt-in via constructor
+ *  - L3 (HTTP/fetch)    — out of SDK scope
+ */
+
+/** Public interface user-supplied L2 caches must implement. */
+interface PersistentCache {
+    get(key: string): Promise<Uint8Array | null>;
+    set(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Bounded in-memory LRU keyed by URL path. Values are pre-parsed dicts. */
+declare class MemoryLRU {
+    private readonly max;
+    private readonly map;
+    constructor(max?: number);
+    get(key: string): ZipcodeDict | undefined;
+    set(key: string, value: ZipcodeDict): void;
+    clear(): void;
+    get size(): number;
+}
+
+declare const DEFAULT_BASE_URL = "https://jpzip.nadai.dev";
+interface JpzipClientOptions {
+    /** Override the CDN origin. Defaults to https://jpzip.nadai.dev */
+    baseUrl?: string;
+    /** L2 persistent cache. Default off. */
+    cache?: PersistentCache;
+    /** Override fetch (mainly tests). */
+    fetch?: typeof fetch;
+    /** L1 LRU capacity in prefix count. Default 100. */
+    memoryCacheSize?: number;
+    /** Surface a warning to the user when spec_version mismatches. */
+    onSpecMismatch?: (info: {
+        expected: string;
+        received: string;
+    }) => void;
+}
+/**
+ * JpzipClient is the SDK entrypoint. The functional shortcuts (`lookup`,
+ * `lookupGroup`, …) below delegate to a default singleton instance backed
+ * by L1 only.
+ */
+declare class JpzipClient {
+    private readonly baseUrl;
+    private readonly cache;
+    private readonly fetchImpl;
+    private readonly mem;
+    private readonly onSpecMismatch;
+    private metaPromise;
+    private knownVersion;
+    constructor(opts?: JpzipClientOptions);
+    /** Returns the entry for `zipcode`, or null if not found. */
+    lookup(zipcode: string): Promise<ZipcodeEntry | null>;
+    /** Returns the dictionary for a 1- or 3-digit prefix (2-digit is fanned out). */
+    lookupGroup(prefix: string): Promise<ZipcodeDict>;
+    /**
+     * Returns the full dataset. The CDN does not expose a single /all.json
+     * because the combined file exceeds Cloudflare Pages' 25 MiB per-file
+     * limit; instead we fan out across /g/0..9.json in parallel and merge.
+     */
+    lookupAll(): Promise<ZipcodeDict>;
+    /** Returns parsed meta.json, or null if the CDN has none yet. */
+    getMeta(): Promise<Meta | null>;
+    /**
+     * preload pulls the requested scope into both L1 (per-prefix entries) and
+     * L2 (when provided) so subsequent reads need no network.
+     */
+    preload(opts: {
+        scope: 'all';
+    } | {
+        scope: string;
+    }): Promise<void>;
+    /** Clear all SDK-managed caches (L1 + L2). */
+    refresh(): Promise<void>;
+    private fetchPrefixDict;
+    private fetchGroupDict;
+    private prefixURL;
+    private fetchOpts;
+    private readL2;
+    private writeL2;
+}
+
+/** Reset the singleton (mainly for tests). */
+declare function _resetDefaultClient(): void;
+/** Configure the singleton's options. Subsequent calls re-create the client. */
+declare function configure(options: ConstructorParameters<typeof JpzipClient>[0]): void;
+declare const lookup: (zipcode: string) => Promise<ZipcodeEntry | null>;
+declare const lookupGroup: (prefix: string) => Promise<ZipcodeDict>;
+declare const lookupAll: () => Promise<ZipcodeDict>;
+declare const preload: (opts: Parameters<JpzipClient["preload"]>[0]) => Promise<void>;
+declare const getMeta: () => Promise<Meta | null>;
+/** Helper: returns true iff `zip` is a syntactically valid 7-digit zipcode. */
+declare function isValidZipcode(zip: string): boolean;
+
+export { DEFAULT_BASE_URL, type Endpoints, JpzipClient, type JpzipClientOptions, MemoryLRU, type Meta, type PersistentCache, type Town, type ZipcodeDict, type ZipcodeEntry, _resetDefaultClient, configure, getMeta, isValidZipcode, lookup, lookupAll, lookupGroup, preload };

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Types mirroring the jpzip protocol specification (spec_version 1.0).
+ * Mirror of https://github.com/jpzip/spec/blob/main/schema/v1/zipcode-entry.json
+ */
+interface Town {
+    town: string;
+    kana: string;
+    roma: string;
+    note?: string;
+}
+interface ZipcodeEntry {
+    prefecture: string;
+    prefecture_kana: string;
+    prefecture_roma: string;
+    prefecture_code: string;
+    city: string;
+    city_kana: string;
+    city_roma: string;
+    city_code: string;
+    towns: Town[];
+}
+interface Endpoints {
+    group: string;
+    prefix: string;
+}
+interface Meta {
+    version: string;
+    generated_at: string;
+    spec_version: string;
+    total_zipcodes: number;
+    prefix_count: number;
+    by_pref: Record<string, number>;
+    data_source: string;
+    endpoints: Endpoints;
+}
+/** Dictionary keyed by 7-digit zipcode string, as published by the CDN. */
+type ZipcodeDict = Record<string, ZipcodeEntry>;
+
+/**
+ * Three-layer caching per spec §6.4:
+ *
+ *  - L1 (MemoryLRU)     — always on, bounded
+ *  - L2 (PersistentCache) — opt-in via constructor
+ *  - L3 (HTTP/fetch)    — out of SDK scope
+ */
+
+/** Public interface user-supplied L2 caches must implement. */
+interface PersistentCache {
+    get(key: string): Promise<Uint8Array | null>;
+    set(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Bounded in-memory LRU keyed by URL path. Values are pre-parsed dicts. */
+declare class MemoryLRU {
+    private readonly max;
+    private readonly map;
+    constructor(max?: number);
+    get(key: string): ZipcodeDict | undefined;
+    set(key: string, value: ZipcodeDict): void;
+    clear(): void;
+    get size(): number;
+}
+
+declare const DEFAULT_BASE_URL = "https://jpzip.nadai.dev";
+interface JpzipClientOptions {
+    /** Override the CDN origin. Defaults to https://jpzip.nadai.dev */
+    baseUrl?: string;
+    /** L2 persistent cache. Default off. */
+    cache?: PersistentCache;
+    /** Override fetch (mainly tests). */
+    fetch?: typeof fetch;
+    /** L1 LRU capacity in prefix count. Default 100. */
+    memoryCacheSize?: number;
+    /** Surface a warning to the user when spec_version mismatches. */
+    onSpecMismatch?: (info: {
+        expected: string;
+        received: string;
+    }) => void;
+}
+/**
+ * JpzipClient is the SDK entrypoint. The functional shortcuts (`lookup`,
+ * `lookupGroup`, …) below delegate to a default singleton instance backed
+ * by L1 only.
+ */
+declare class JpzipClient {
+    private readonly baseUrl;
+    private readonly cache;
+    private readonly fetchImpl;
+    private readonly mem;
+    private readonly onSpecMismatch;
+    private metaPromise;
+    private knownVersion;
+    constructor(opts?: JpzipClientOptions);
+    /** Returns the entry for `zipcode`, or null if not found. */
+    lookup(zipcode: string): Promise<ZipcodeEntry | null>;
+    /** Returns the dictionary for a 1- or 3-digit prefix (2-digit is fanned out). */
+    lookupGroup(prefix: string): Promise<ZipcodeDict>;
+    /**
+     * Returns the full dataset. The CDN does not expose a single /all.json
+     * because the combined file exceeds Cloudflare Pages' 25 MiB per-file
+     * limit; instead we fan out across /g/0..9.json in parallel and merge.
+     */
+    lookupAll(): Promise<ZipcodeDict>;
+    /** Returns parsed meta.json, or null if the CDN has none yet. */
+    getMeta(): Promise<Meta | null>;
+    /**
+     * preload pulls the requested scope into both L1 (per-prefix entries) and
+     * L2 (when provided) so subsequent reads need no network.
+     */
+    preload(opts: {
+        scope: 'all';
+    } | {
+        scope: string;
+    }): Promise<void>;
+    /** Clear all SDK-managed caches (L1 + L2). */
+    refresh(): Promise<void>;
+    private fetchPrefixDict;
+    private fetchGroupDict;
+    private prefixURL;
+    private fetchOpts;
+    private readL2;
+    private writeL2;
+}
+
+/** Reset the singleton (mainly for tests). */
+declare function _resetDefaultClient(): void;
+/** Configure the singleton's options. Subsequent calls re-create the client. */
+declare function configure(options: ConstructorParameters<typeof JpzipClient>[0]): void;
+declare const lookup: (zipcode: string) => Promise<ZipcodeEntry | null>;
+declare const lookupGroup: (prefix: string) => Promise<ZipcodeDict>;
+declare const lookupAll: () => Promise<ZipcodeDict>;
+declare const preload: (opts: Parameters<JpzipClient["preload"]>[0]) => Promise<void>;
+declare const getMeta: () => Promise<Meta | null>;
+/** Helper: returns true iff `zip` is a syntactically valid 7-digit zipcode. */
+declare function isValidZipcode(zip: string): boolean;
+
+export { DEFAULT_BASE_URL, type Endpoints, JpzipClient, type JpzipClientOptions, MemoryLRU, type Meta, type PersistentCache, type Town, type ZipcodeDict, type ZipcodeEntry, _resetDefaultClient, configure, getMeta, isValidZipcode, lookup, lookupAll, lookupGroup, preload };

package/dist/index.js

@@ -0,0 +1,264 @@
+// src/cache.ts
+var MemoryLRU = class {
+  max;
+  map = /* @__PURE__ */ new Map();
+  constructor(max = 100) {
+    this.max = Math.max(1, max);
+  }
+  get(key) {
+    const value = this.map.get(key);
+    if (value === void 0) return void 0;
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.max) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey !== void 0) this.map.delete(oldestKey);
+    }
+    this.map.set(key, value);
+  }
+  clear() {
+    this.map.clear();
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+
+// src/fetch.ts
+var MAX_RETRIES = 3;
+var BASE_DELAY_MS = 200;
+async function fetchJSON(url, opts = {}) {
+  const f = opts.fetch ?? fetch;
+  let lastErr;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      await sleep(BASE_DELAY_MS * 2 ** attempt);
+    }
+    try {
+      const init = {
+        method: "GET",
+        headers: { Accept: "application/json" }
+      };
+      if (opts.signal !== void 0) init.signal = opts.signal;
+      if (opts.noCache) init.cache = "no-cache";
+      const res = await f(url, init);
+      if (res.status === 404) return null;
+      if (res.status >= 500) {
+        lastErr = new Error(`jpzip: ${url} returned ${res.status}`);
+        continue;
+      }
+      if (!res.ok) {
+        throw new Error(`jpzip: ${url} returned ${res.status}`);
+      }
+      return await res.json();
+    } catch (err) {
+      lastErr = err;
+      if (err instanceof DOMException && err.name === "AbortError") throw err;
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error(`jpzip: fetch failed for ${url}: ${String(lastErr)}`);
+}
+var fetchDict = (url, opts) => fetchJSON(url, opts);
+var fetchMeta = (url, opts) => fetchJSON(url, opts);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://jpzip.nadai.dev";
+var SUPPORTED_SPEC = "1.0";
+var ZIP_REGEX = /^\d{7}$/;
+var PREFIX_REGEX = /^\d{1,3}$/;
+var JpzipClient = class {
+  baseUrl;
+  cache;
+  fetchImpl;
+  mem;
+  onSpecMismatch;
+  metaPromise = null;
+  knownVersion = null;
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.cache = opts.cache;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.mem = new MemoryLRU(opts.memoryCacheSize ?? 100);
+    this.onSpecMismatch = opts.onSpecMismatch;
+  }
+  /** Returns the entry for `zipcode`, or null if not found. */
+  async lookup(zipcode) {
+    if (!ZIP_REGEX.test(zipcode)) return null;
+    const prefix = zipcode.slice(0, 3);
+    const dict = await this.fetchPrefixDict(prefix);
+    if (!dict) return null;
+    return dict[zipcode] ?? null;
+  }
+  /** Returns the dictionary for a 1- or 3-digit prefix (2-digit is fanned out). */
+  async lookupGroup(prefix) {
+    if (!PREFIX_REGEX.test(prefix)) {
+      throw new Error(`jpzip: invalid prefix ${JSON.stringify(prefix)} (must be 1-3 digits)`);
+    }
+    if (prefix.length === 3) {
+      return await this.fetchPrefixDict(prefix) ?? {};
+    }
+    if (prefix.length === 1) {
+      const dict = await this.fetchGroupDict(prefix);
+      return dict ?? {};
+    }
+    const tasks = [];
+    for (let i = 0; i < 10; i++) {
+      tasks.push(this.fetchPrefixDict(`${prefix}${i}`));
+    }
+    const dicts = await Promise.all(tasks);
+    return Object.assign({}, ...dicts.filter(Boolean));
+  }
+  /**
+   * Returns the full dataset. The CDN does not expose a single /all.json
+   * because the combined file exceeds Cloudflare Pages' 25 MiB per-file
+   * limit; instead we fan out across /g/0..9.json in parallel and merge.
+   */
+  async lookupAll() {
+    const tasks = [];
+    for (let i = 0; i < 10; i++) {
+      tasks.push(this.fetchGroupDict(String(i)));
+    }
+    const dicts = await Promise.all(tasks);
+    return Object.assign({}, ...dicts.filter(Boolean));
+  }
+  /** Returns parsed meta.json, or null if the CDN has none yet. */
+  async getMeta() {
+    if (this.metaPromise === null) {
+      this.metaPromise = (async () => {
+        const m = await fetchMeta(`${this.baseUrl}/meta.json`, this.fetchOpts());
+        if (m && m.spec_version !== SUPPORTED_SPEC) {
+          this.onSpecMismatch?.({ expected: SUPPORTED_SPEC, received: m.spec_version });
+        }
+        if (m && this.knownVersion && this.knownVersion !== m.version) {
+          this.mem.clear();
+          await this.cache?.clear();
+        }
+        if (m) this.knownVersion = m.version;
+        return m;
+      })();
+    }
+    return this.metaPromise;
+  }
+  /**
+   * preload pulls the requested scope into both L1 (per-prefix entries) and
+   * L2 (when provided) so subsequent reads need no network.
+   */
+  async preload(opts) {
+    if (opts.scope === "all") {
+      const dict = await this.lookupAll();
+      const buckets = {};
+      for (const [zip, entry] of Object.entries(dict)) {
+        const p = zip.slice(0, 3);
+        (buckets[p] ??= {})[zip] = entry;
+      }
+      for (const [p, b] of Object.entries(buckets)) {
+        this.mem.set(this.prefixURL(p), b);
+        await this.writeL2(this.prefixURL(p), b);
+      }
+      return;
+    }
+    if (PREFIX_REGEX.test(opts.scope)) {
+      await this.lookupGroup(opts.scope);
+      return;
+    }
+    throw new Error(`jpzip: invalid preload scope ${JSON.stringify(opts.scope)}`);
+  }
+  /** Clear all SDK-managed caches (L1 + L2). */
+  async refresh() {
+    this.mem.clear();
+    this.metaPromise = null;
+    this.knownVersion = null;
+    await this.cache?.clear();
+  }
+  /* ----------------------------- internals ------------------------------ */
+  async fetchPrefixDict(prefix) {
+    const url = this.prefixURL(prefix);
+    const cached = this.mem.get(url);
+    if (cached) return cached;
+    const fromL2 = await this.readL2(url);
+    if (fromL2) {
+      this.mem.set(url, fromL2);
+      return fromL2;
+    }
+    const dict = await fetchDict(url, this.fetchOpts());
+    if (dict) {
+      this.mem.set(url, dict);
+      await this.writeL2(url, dict);
+    }
+    return dict;
+  }
+  async fetchGroupDict(prefix1) {
+    const url = `${this.baseUrl}/g/${prefix1}.json`;
+    const cached = this.mem.get(url);
+    if (cached) return cached;
+    const dict = await fetchDict(url, this.fetchOpts());
+    if (dict) this.mem.set(url, dict);
+    return dict;
+  }
+  prefixURL(prefix3) {
+    return `${this.baseUrl}/p/${prefix3}.json`;
+  }
+  fetchOpts() {
+    return { fetch: this.fetchImpl };
+  }
+  async readL2(url) {
+    if (!this.cache) return null;
+    const bytes = await this.cache.get(url);
+    if (!bytes) return null;
+    try {
+      const text = new TextDecoder().decode(bytes);
+      return JSON.parse(text);
+    } catch {
+      await this.cache.delete(url);
+      return null;
+    }
+  }
+  async writeL2(url, dict) {
+    if (!this.cache) return;
+    const bytes = new TextEncoder().encode(JSON.stringify(dict));
+    await this.cache.set(url, bytes);
+  }
+};
+
+// src/index.ts
+var _default = null;
+function defaultClient() {
+  if (_default === null) _default = new JpzipClient();
+  return _default;
+}
+function _resetDefaultClient() {
+  _default = null;
+}
+function configure(options) {
+  _default = new JpzipClient(options);
+}
+var lookup = (zipcode) => defaultClient().lookup(zipcode);
+var lookupGroup = (prefix) => defaultClient().lookupGroup(prefix);
+var lookupAll = () => defaultClient().lookupAll();
+var preload = (opts) => defaultClient().preload(opts);
+var getMeta = () => defaultClient().getMeta();
+function isValidZipcode(zip) {
+  return /^\d{7}$/.test(zip);
+}
+export {
+  DEFAULT_BASE_URL,
+  JpzipClient,
+  MemoryLRU,
+  _resetDefaultClient,
+  configure,
+  getMeta,
+  isValidZipcode,
+  lookup,
+  lookupAll,
+  lookupGroup,
+  preload
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cache.ts","../src/fetch.ts","../src/client.ts","../src/index.ts"],"sourcesContent":["/**\n * Three-layer caching per spec §6.4:\n *\n *  - L1 (MemoryLRU)     — always on, bounded\n *  - L2 (PersistentCache) — opt-in via constructor\n *  - L3 (HTTP/fetch)    — out of SDK scope\n */\n\nimport type { ZipcodeDict } from './types.js';\n\n/** Public interface user-supplied L2 caches must implement. */\nexport interface PersistentCache {\n  get(key: string): Promise<Uint8Array | null>;\n  set(key: string, value: Uint8Array): Promise<void>;\n  delete(key: string): Promise<void>;\n  clear(): Promise<void>;\n}\n\n/** Bounded in-memory LRU keyed by URL path. Values are pre-parsed dicts. */\nexport class MemoryLRU {\n  private readonly max: number;\n  private readonly map = new Map<string, ZipcodeDict>();\n\n  constructor(max = 100) {\n    this.max = Math.max(1, max);\n  }\n\n  get(key: string): ZipcodeDict | undefined {\n    const value = this.map.get(key);\n    if (value === undefined) return undefined;\n    // refresh recency by re-inserting at the tail\n    this.map.delete(key);\n    this.map.set(key, value);\n    return value;\n  }\n\n  set(key: string, value: ZipcodeDict): void {\n    if (this.map.has(key)) {\n      this.map.delete(key);\n    } else if (this.map.size >= this.max) {\n      const oldestKey = this.map.keys().next().value;\n      if (oldestKey !== undefined) this.map.delete(oldestKey);\n    }\n    this.map.set(key, value);\n  }\n\n  clear(): void {\n    this.map.clear();\n  }\n\n  get size(): number {\n    return this.map.size;\n  }\n}\n","/** HTTP helpers with exponential-backoff retry for transient 5xx and network errors. */\n\nimport type { ZipcodeDict, Meta } from './types.js';\n\nconst MAX_RETRIES = 3;\nconst BASE_DELAY_MS = 200;\n\nexport interface FetchOptions {\n  /** Override the global fetch (mainly for tests). */\n  fetch?: typeof fetch;\n  /** Pass-through to fetch(). */\n  signal?: AbortSignal;\n  /** Forces no-cache; useful when the user explicitly refreshes. */\n  noCache?: boolean;\n}\n\n/**\n * fetchJSON returns the parsed JSON body for url. On 404 it returns null.\n * On 5xx / network errors it retries up to MAX_RETRIES with exponential backoff.\n * Other 4xx errors throw.\n */\nexport async function fetchJSON<T>(url: string, opts: FetchOptions = {}): Promise<T | null> {\n  const f = opts.fetch ?? fetch;\n\n  let lastErr: unknown;\n  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {\n    if (attempt > 0) {\n      await sleep(BASE_DELAY_MS * 2 ** attempt);\n    }\n    try {\n      const init: RequestInit = {\n        method: 'GET',\n        headers: { Accept: 'application/json' },\n      };\n      if (opts.signal !== undefined) init.signal = opts.signal;\n      if (opts.noCache) init.cache = 'no-cache';\n\n      const res = await f(url, init);\n      if (res.status === 404) return null;\n      if (res.status >= 500) {\n        lastErr = new Error(`jpzip: ${url} returned ${res.status}`);\n        continue;\n      }\n      if (!res.ok) {\n        throw new Error(`jpzip: ${url} returned ${res.status}`);\n      }\n      return (await res.json()) as T;\n    } catch (err) {\n      lastErr = err;\n      if (err instanceof DOMException && err.name === 'AbortError') throw err;\n    }\n  }\n  throw lastErr instanceof Error\n    ? lastErr\n    : new Error(`jpzip: fetch failed for ${url}: ${String(lastErr)}`);\n}\n\n/** Convenience aliases with parameterized return types. */\nexport const fetchDict = (url: string, opts?: FetchOptions): Promise<ZipcodeDict | null> =>\n  fetchJSON<ZipcodeDict>(url, opts);\n\nexport const fetchMeta = (url: string, opts?: FetchOptions): Promise<Meta | null> =>\n  fetchJSON<Meta>(url, opts);\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n","import { MemoryLRU, type PersistentCache } from './cache.js';\nimport { fetchDict, fetchMeta, type FetchOptions } from './fetch.js';\nimport type { Meta, ZipcodeDict, ZipcodeEntry } from './types.js';\n\nexport const DEFAULT_BASE_URL = 'https://jpzip.nadai.dev';\nconst SUPPORTED_SPEC = '1.0';\n\nexport interface JpzipClientOptions {\n  /** Override the CDN origin. Defaults to https://jpzip.nadai.dev */\n  baseUrl?: string;\n  /** L2 persistent cache. Default off. */\n  cache?: PersistentCache;\n  /** Override fetch (mainly tests). */\n  fetch?: typeof fetch;\n  /** L1 LRU capacity in prefix count. Default 100. */\n  memoryCacheSize?: number;\n  /** Surface a warning to the user when spec_version mismatches. */\n  onSpecMismatch?: (info: { expected: string; received: string }) => void;\n}\n\nconst ZIP_REGEX = /^\\d{7}$/;\nconst PREFIX_REGEX = /^\\d{1,3}$/;\n\n/**\n * JpzipClient is the SDK entrypoint. The functional shortcuts (`lookup`,\n * `lookupGroup`, …) below delegate to a default singleton instance backed\n * by L1 only.\n */\nexport class JpzipClient {\n  private readonly baseUrl: string;\n  private readonly cache: PersistentCache | undefined;\n  private readonly fetchImpl: typeof fetch;\n  private readonly mem: MemoryLRU;\n  private readonly onSpecMismatch: JpzipClientOptions['onSpecMismatch'];\n  private metaPromise: Promise<Meta | null> | null = null;\n  private knownVersion: string | null = null;\n\n  constructor(opts: JpzipClientOptions = {}) {\n    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.cache = opts.cache;\n    this.fetchImpl = opts.fetch ?? globalThis.fetch;\n    this.mem = new MemoryLRU(opts.memoryCacheSize ?? 100);\n    this.onSpecMismatch = opts.onSpecMismatch;\n  }\n\n  /** Returns the entry for `zipcode`, or null if not found. */\n  async lookup(zipcode: string): Promise<ZipcodeEntry | null> {\n    if (!ZIP_REGEX.test(zipcode)) return null;\n    const prefix = zipcode.slice(0, 3);\n    const dict = await this.fetchPrefixDict(prefix);\n    if (!dict) return null;\n    return dict[zipcode] ?? null;\n  }\n\n  /** Returns the dictionary for a 1- or 3-digit prefix (2-digit is fanned out). */\n  async lookupGroup(prefix: string): Promise<ZipcodeDict> {\n    if (!PREFIX_REGEX.test(prefix)) {\n      throw new Error(`jpzip: invalid prefix ${JSON.stringify(prefix)} (must be 1-3 digits)`);\n    }\n    if (prefix.length === 3) {\n      return (await this.fetchPrefixDict(prefix)) ?? {};\n    }\n    if (prefix.length === 1) {\n      const dict = await this.fetchGroupDict(prefix);\n      return dict ?? {};\n    }\n    // 2-digit fanout\n    const tasks: Promise<ZipcodeDict | null>[] = [];\n    for (let i = 0; i < 10; i++) {\n      tasks.push(this.fetchPrefixDict(`${prefix}${i}`));\n    }\n    const dicts = await Promise.all(tasks);\n    return Object.assign({}, ...dicts.filter(Boolean)) as ZipcodeDict;\n  }\n\n  /**\n   * Returns the full dataset. The CDN does not expose a single /all.json\n   * because the combined file exceeds Cloudflare Pages' 25 MiB per-file\n   * limit; instead we fan out across /g/0..9.json in parallel and merge.\n   */\n  async lookupAll(): Promise<ZipcodeDict> {\n    const tasks: Promise<ZipcodeDict | null>[] = [];\n    for (let i = 0; i < 10; i++) {\n      tasks.push(this.fetchGroupDict(String(i)));\n    }\n    const dicts = await Promise.all(tasks);\n    return Object.assign({}, ...dicts.filter(Boolean)) as ZipcodeDict;\n  }\n\n  /** Returns parsed meta.json, or null if the CDN has none yet. */\n  async getMeta(): Promise<Meta | null> {\n    if (this.metaPromise === null) {\n      this.metaPromise = (async () => {\n        const m = await fetchMeta(`${this.baseUrl}/meta.json`, this.fetchOpts());\n        if (m && m.spec_version !== SUPPORTED_SPEC) {\n          this.onSpecMismatch?.({ expected: SUPPORTED_SPEC, received: m.spec_version });\n        }\n        if (m && this.knownVersion && this.knownVersion !== m.version) {\n          // data version changed — drop L1 + L2 to avoid stale reads\n          this.mem.clear();\n          await this.cache?.clear();\n        }\n        if (m) this.knownVersion = m.version;\n        return m;\n      })();\n    }\n    return this.metaPromise;\n  }\n\n  /**\n   * preload pulls the requested scope into both L1 (per-prefix entries) and\n   * L2 (when provided) so subsequent reads need no network.\n   */\n  async preload(opts: { scope: 'all' } | { scope: string }): Promise<void> {\n    if (opts.scope === 'all') {\n      const dict = await this.lookupAll();\n      // Split into prefix buckets and prime L1.\n      const buckets: Record<string, ZipcodeDict> = {};\n      for (const [zip, entry] of Object.entries(dict)) {\n        const p = zip.slice(0, 3);\n        (buckets[p] ??= {})[zip] = entry;\n      }\n      for (const [p, b] of Object.entries(buckets)) {\n        this.mem.set(this.prefixURL(p), b);\n        await this.writeL2(this.prefixURL(p), b);\n      }\n      return;\n    }\n    if (PREFIX_REGEX.test(opts.scope)) {\n      await this.lookupGroup(opts.scope);\n      return;\n    }\n    throw new Error(`jpzip: invalid preload scope ${JSON.stringify(opts.scope)}`);\n  }\n\n  /** Clear all SDK-managed caches (L1 + L2). */\n  async refresh(): Promise<void> {\n    this.mem.clear();\n    this.metaPromise = null;\n    this.knownVersion = null;\n    await this.cache?.clear();\n  }\n\n  /* ----------------------------- internals ------------------------------ */\n\n  private async fetchPrefixDict(prefix: string): Promise<ZipcodeDict | null> {\n    const url = this.prefixURL(prefix);\n    const cached = this.mem.get(url);\n    if (cached) return cached;\n\n    const fromL2 = await this.readL2(url);\n    if (fromL2) {\n      this.mem.set(url, fromL2);\n      return fromL2;\n    }\n\n    const dict = await fetchDict(url, this.fetchOpts());\n    if (dict) {\n      this.mem.set(url, dict);\n      await this.writeL2(url, dict);\n    }\n    return dict;\n  }\n\n  private async fetchGroupDict(prefix1: string): Promise<ZipcodeDict | null> {\n    const url = `${this.baseUrl}/g/${prefix1}.json`;\n    const cached = this.mem.get(url);\n    if (cached) return cached;\n    const dict = await fetchDict(url, this.fetchOpts());\n    if (dict) this.mem.set(url, dict);\n    return dict;\n  }\n\n  private prefixURL(prefix3: string): string {\n    return `${this.baseUrl}/p/${prefix3}.json`;\n  }\n\n  private fetchOpts(): FetchOptions {\n    return { fetch: this.fetchImpl };\n  }\n\n  private async readL2(url: string): Promise<ZipcodeDict | null> {\n    if (!this.cache) return null;\n    const bytes = await this.cache.get(url);\n    if (!bytes) return null;\n    try {\n      const text = new TextDecoder().decode(bytes);\n      return JSON.parse(text) as ZipcodeDict;\n    } catch {\n      // corrupt cache — drop the entry and refetch\n      await this.cache.delete(url);\n      return null;\n    }\n  }\n\n  private async writeL2(url: string, dict: ZipcodeDict): Promise<void> {\n    if (!this.cache) return;\n    const bytes = new TextEncoder().encode(JSON.stringify(dict));\n    await this.cache.set(url, bytes);\n  }\n}\n","export { JpzipClient, DEFAULT_BASE_URL, type JpzipClientOptions } from './client.js';\nexport { MemoryLRU, type PersistentCache } from './cache.js';\nexport type { ZipcodeEntry, Town, Meta, ZipcodeDict, Endpoints } from './types.js';\n\nimport { JpzipClient } from './client.js';\nimport type { Meta, ZipcodeDict, ZipcodeEntry } from './types.js';\n\n/**\n * The functional helpers below all delegate to a lazily-initialized default\n * client (L1 cache only, default base URL). For multiple SDK instances or\n * an L2 cache, construct `new JpzipClient({...})` yourself.\n */\n\nlet _default: JpzipClient | null = null;\nfunction defaultClient(): JpzipClient {\n  if (_default === null) _default = new JpzipClient();\n  return _default;\n}\n\n/** Reset the singleton (mainly for tests). */\nexport function _resetDefaultClient(): void {\n  _default = null;\n}\n\n/** Configure the singleton's options. Subsequent calls re-create the client. */\nexport function configure(options: ConstructorParameters<typeof JpzipClient>[0]): void {\n  _default = new JpzipClient(options);\n}\n\nexport const lookup = (zipcode: string): Promise<ZipcodeEntry | null> =>\n  defaultClient().lookup(zipcode);\n\nexport const lookupGroup = (prefix: string): Promise<ZipcodeDict> =>\n  defaultClient().lookupGroup(prefix);\n\nexport const lookupAll = (): Promise<ZipcodeDict> => defaultClient().lookupAll();\n\nexport const preload = (opts: Parameters<JpzipClient['preload']>[0]): Promise<void> =>\n  defaultClient().preload(opts);\n\nexport const getMeta = (): Promise<Meta | null> => defaultClient().getMeta();\n\n/** Helper: returns true iff `zip` is a syntactically valid 7-digit zipcode. */\nexport function isValidZipcode(zip: string): boolean {\n  return /^\\d{7}$/.test(zip);\n}\n"],"mappings":";AAmBO,IAAM,YAAN,MAAgB;AAAA,EACJ;AAAA,EACA,MAAM,oBAAI,IAAyB;AAAA,EAEpD,YAAY,MAAM,KAAK;AACrB,SAAK,MAAM,KAAK,IAAI,GAAG,GAAG;AAAA,EAC5B;AAAA,EAEA,IAAI,KAAsC;AACxC,UAAM,QAAQ,KAAK,IAAI,IAAI,GAAG;AAC9B,QAAI,UAAU,OAAW,QAAO;AAEhC,SAAK,IAAI,OAAO,GAAG;AACnB,SAAK,IAAI,IAAI,KAAK,KAAK;AACvB,WAAO;AAAA,EACT;AAAA,EAEA,IAAI,KAAa,OAA0B;AACzC,QAAI,KAAK,IAAI,IAAI,GAAG,GAAG;AACrB,WAAK,IAAI,OAAO,GAAG;AAAA,IACrB,WAAW,KAAK,IAAI,QAAQ,KAAK,KAAK;AACpC,YAAM,YAAY,KAAK,IAAI,KAAK,EAAE,KAAK,EAAE;AACzC,UAAI,cAAc,OAAW,MAAK,IAAI,OAAO,SAAS;AAAA,IACxD;AACA,SAAK,IAAI,IAAI,KAAK,KAAK;AAAA,EACzB;AAAA,EAEA,QAAc;AACZ,SAAK,IAAI,MAAM;AAAA,EACjB;AAAA,EAEA,IAAI,OAAe;AACjB,WAAO,KAAK,IAAI;AAAA,EAClB;AACF;;;ACjDA,IAAM,cAAc;AACpB,IAAM,gBAAgB;AAgBtB,eAAsB,UAAa,KAAa,OAAqB,CAAC,GAAsB;AAC1F,QAAM,IAAI,KAAK,SAAS;AAExB,MAAI;AACJ,WAAS,UAAU,GAAG,UAAU,aAAa,WAAW;AACtD,QAAI,UAAU,GAAG;AACf,YAAM,MAAM,gBAAgB,KAAK,OAAO;AAAA,IAC1C;AACA,QAAI;AACF,YAAM,OAAoB;AAAA,QACxB,QAAQ;AAAA,QACR,SAAS,EAAE,QAAQ,mBAAmB;AAAA,MACxC;AACA,UAAI,KAAK,WAAW,OAAW,MAAK,SAAS,KAAK;AAClD,UAAI,KAAK,QAAS,MAAK,QAAQ;AAE/B,YAAM,MAAM,MAAM,EAAE,KAAK,IAAI;AAC7B,UAAI,IAAI,WAAW,IAAK,QAAO;AAC/B,UAAI,IAAI,UAAU,KAAK;AACrB,kBAAU,IAAI,MAAM,UAAU,GAAG,aAAa,IAAI,MAAM,EAAE;AAC1D;AAAA,MACF;AACA,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI,MAAM,UAAU,GAAG,aAAa,IAAI,MAAM,EAAE;AAAA,MACxD;AACA,aAAQ,MAAM,IAAI,KAAK;AAAA,IACzB,SAAS,KAAK;AACZ,gBAAU;AACV,UAAI,eAAe,gBAAgB,IAAI,SAAS,aAAc,OAAM;AAAA,IACtE;AAAA,EACF;AACA,QAAM,mBAAmB,QACrB,UACA,IAAI,MAAM,2BAA2B,GAAG,KAAK,OAAO,OAAO,CAAC,EAAE;AACpE;AAGO,IAAM,YAAY,CAAC,KAAa,SACrC,UAAuB,KAAK,IAAI;AAE3B,IAAM,YAAY,CAAC,KAAa,SACrC,UAAgB,KAAK,IAAI;AAE3B,SAAS,MAAM,IAA2B;AACxC,SAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AACzD;;;AC9DO,IAAM,mBAAmB;AAChC,IAAM,iBAAiB;AAevB,IAAM,YAAY;AAClB,IAAM,eAAe;AAOd,IAAM,cAAN,MAAkB;AAAA,EACN;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACT,cAA2C;AAAA,EAC3C,eAA8B;AAAA,EAEtC,YAAY,OAA2B,CAAC,GAAG;AACzC,SAAK,WAAW,KAAK,WAAW,kBAAkB,QAAQ,OAAO,EAAE;AACnE,SAAK,QAAQ,KAAK;AAClB,SAAK,YAAY,KAAK,SAAS,WAAW;AAC1C,SAAK,MAAM,IAAI,UAAU,KAAK,mBAAmB,GAAG;AACpD,SAAK,iBAAiB,KAAK;AAAA,EAC7B;AAAA;AAAA,EAGA,MAAM,OAAO,SAA+C;AAC1D,QAAI,CAAC,UAAU,KAAK,OAAO,EAAG,QAAO;AACrC,UAAM,SAAS,QAAQ,MAAM,GAAG,CAAC;AACjC,UAAM,OAAO,MAAM,KAAK,gBAAgB,MAAM;AAC9C,QAAI,CAAC,KAAM,QAAO;AAClB,WAAO,KAAK,OAAO,KAAK;AAAA,EAC1B;AAAA;AAAA,EAGA,MAAM,YAAY,QAAsC;AACtD,QAAI,CAAC,aAAa,KAAK,MAAM,GAAG;AAC9B,YAAM,IAAI,MAAM,yBAAyB,KAAK,UAAU,MAAM,CAAC,uBAAuB;AAAA,IACxF;AACA,QAAI,OAAO,WAAW,GAAG;AACvB,aAAQ,MAAM,KAAK,gBAAgB,MAAM,KAAM,CAAC;AAAA,IAClD;AACA,QAAI,OAAO,WAAW,GAAG;AACvB,YAAM,OAAO,MAAM,KAAK,eAAe,MAAM;AAC7C,aAAO,QAAQ,CAAC;AAAA,IAClB;AAEA,UAAM,QAAuC,CAAC;AAC9C,aAAS,IAAI,GAAG,IAAI,IAAI,KAAK;AAC3B,YAAM,KAAK,KAAK,gBAAgB,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC;AAAA,IAClD;AACA,UAAM,QAAQ,MAAM,QAAQ,IAAI,KAAK;AACrC,WAAO,OAAO,OAAO,CAAC,GAAG,GAAG,MAAM,OAAO,OAAO,CAAC;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,YAAkC;AACtC,UAAM,QAAuC,CAAC;AAC9C,aAAS,IAAI,GAAG,IAAI,IAAI,KAAK;AAC3B,YAAM,KAAK,KAAK,eAAe,OAAO,CAAC,CAAC,CAAC;AAAA,IAC3C;AACA,UAAM,QAAQ,MAAM,QAAQ,IAAI,KAAK;AACrC,WAAO,OAAO,OAAO,CAAC,GAAG,GAAG,MAAM,OAAO,OAAO,CAAC;AAAA,EACnD;AAAA;AAAA,EAGA,MAAM,UAAgC;AACpC,QAAI,KAAK,gBAAgB,MAAM;AAC7B,WAAK,eAAe,YAAY;AAC9B,cAAM,IAAI,MAAM,UAAU,GAAG,KAAK,OAAO,cAAc,KAAK,UAAU,CAAC;AACvE,YAAI,KAAK,EAAE,iBAAiB,gBAAgB;AAC1C,eAAK,iBAAiB,EAAE,UAAU,gBAAgB,UAAU,EAAE,aAAa,CAAC;AAAA,QAC9E;AACA,YAAI,KAAK,KAAK,gBAAgB,KAAK,iBAAiB,EAAE,SAAS;AAE7D,eAAK,IAAI,MAAM;AACf,gBAAM,KAAK,OAAO,MAAM;AAAA,QAC1B;AACA,YAAI,EAAG,MAAK,eAAe,EAAE;AAC7B,eAAO;AAAA,MACT,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,QAAQ,MAA2D;AACvE,QAAI,KAAK,UAAU,OAAO;AACxB,YAAM,OAAO,MAAM,KAAK,UAAU;AAElC,YAAM,UAAuC,CAAC;AAC9C,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,cAAM,IAAI,IAAI,MAAM,GAAG,CAAC;AACxB,SAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI;AAAA,MAC7B;AACA,iBAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,OAAO,GAAG;AAC5C,aAAK,IAAI,IAAI,KAAK,UAAU,CAAC,GAAG,CAAC;AACjC,cAAM,KAAK,QAAQ,KAAK,UAAU,CAAC,GAAG,CAAC;AAAA,MACzC;AACA;AAAA,IACF;AACA,QAAI,aAAa,KAAK,KAAK,KAAK,GAAG;AACjC,YAAM,KAAK,YAAY,KAAK,KAAK;AACjC;AAAA,IACF;AACA,UAAM,IAAI,MAAM,gCAAgC,KAAK,UAAU,KAAK,KAAK,CAAC,EAAE;AAAA,EAC9E;AAAA;AAAA,EAGA,MAAM,UAAyB;AAC7B,SAAK,IAAI,MAAM;AACf,SAAK,cAAc;AACnB,SAAK,eAAe;AACpB,UAAM,KAAK,OAAO,MAAM;AAAA,EAC1B;AAAA;AAAA,EAIA,MAAc,gBAAgB,QAA6C;AACzE,UAAM,MAAM,KAAK,UAAU,MAAM;AACjC,UAAM,SAAS,KAAK,IAAI,IAAI,GAAG;AAC/B,QAAI,OAAQ,QAAO;AAEnB,UAAM,SAAS,MAAM,KAAK,OAAO,GAAG;AACpC,QAAI,QAAQ;AACV,WAAK,IAAI,IAAI,KAAK,MAAM;AACxB,aAAO;AAAA,IACT;AAEA,UAAM,OAAO,MAAM,UAAU,KAAK,KAAK,UAAU,CAAC;AAClD,QAAI,MAAM;AACR,WAAK,IAAI,IAAI,KAAK,IAAI;AACtB,YAAM,KAAK,QAAQ,KAAK,IAAI;AAAA,IAC9B;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,eAAe,SAA8C;AACzE,UAAM,MAAM,GAAG,KAAK,OAAO,MAAM,OAAO;AACxC,UAAM,SAAS,KAAK,IAAI,IAAI,GAAG;AAC/B,QAAI,OAAQ,QAAO;AACnB,UAAM,OAAO,MAAM,UAAU,KAAK,KAAK,UAAU,CAAC;AAClD,QAAI,KAAM,MAAK,IAAI,IAAI,KAAK,IAAI;AAChC,WAAO;AAAA,EACT;AAAA,EAEQ,UAAU,SAAyB;AACzC,WAAO,GAAG,KAAK,OAAO,MAAM,OAAO;AAAA,EACrC;AAAA,EAEQ,YAA0B;AAChC,WAAO,EAAE,OAAO,KAAK,UAAU;AAAA,EACjC;AAAA,EAEA,MAAc,OAAO,KAA0C;AAC7D,QAAI,CAAC,KAAK,MAAO,QAAO;AACxB,UAAM,QAAQ,MAAM,KAAK,MAAM,IAAI,GAAG;AACtC,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI;AACF,YAAM,OAAO,IAAI,YAAY,EAAE,OAAO,KAAK;AAC3C,aAAO,KAAK,MAAM,IAAI;AAAA,IACxB,QAAQ;AAEN,YAAM,KAAK,MAAM,OAAO,GAAG;AAC3B,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,MAAc,QAAQ,KAAa,MAAkC;AACnE,QAAI,CAAC,KAAK,MAAO;AACjB,UAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,KAAK,UAAU,IAAI,CAAC;AAC3D,UAAM,KAAK,MAAM,IAAI,KAAK,KAAK;AAAA,EACjC;AACF;;;AC3LA,IAAI,WAA+B;AACnC,SAAS,gBAA6B;AACpC,MAAI,aAAa,KAAM,YAAW,IAAI,YAAY;AAClD,SAAO;AACT;AAGO,SAAS,sBAA4B;AAC1C,aAAW;AACb;AAGO,SAAS,UAAU,SAA6D;AACrF,aAAW,IAAI,YAAY,OAAO;AACpC;AAEO,IAAM,SAAS,CAAC,YACrB,cAAc,EAAE,OAAO,OAAO;AAEzB,IAAM,cAAc,CAAC,WAC1B,cAAc,EAAE,YAAY,MAAM;AAE7B,IAAM,YAAY,MAA4B,cAAc,EAAE,UAAU;AAExE,IAAM,UAAU,CAAC,SACtB,cAAc,EAAE,QAAQ,IAAI;AAEvB,IAAM,UAAU,MAA4B,cAAc,EAAE,QAAQ;AAGpE,SAAS,eAAe,KAAsB;AACnD,SAAO,UAAU,KAAK,GAAG;AAC3B;","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jpzip/jpzip",
+  "version": "0.1.0",
+  "description": "Japan postal-code dataset SDK — fetches normalized JSON from jpzip.nadai.dev",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "japan",
+    "postal-code",
+    "zipcode",
+    "郵便番号",
+    "address"
+  ],
+  "author": "nadai",
+  "license": "MIT",
+  "homepage": "https://jpzip.nadai.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpzip/js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jpzip/js/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}