@jpzip/jpzip 0.1.0 → 0.1.2

package/README.ja.md

@@ -0,0 +1,265 @@
+## jpzip-js
+
+[![npm version](https://img.shields.io/npm/v/@jpzip/jpzip.svg)](https://www.npmjs.com/package/@jpzip/jpzip)
+[![types: included](https://img.shields.io/npm/types/@jpzip/jpzip.svg)](https://www.npmjs.com/package/@jpzip/jpzip)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Test](https://github.com/jpzip/js/actions/workflows/test.yml/badge.svg)](https://github.com/jpzip/js/actions/workflows/test.yml)
+
+> **jpzip** の TypeScript / JavaScript SDK — 無料・無制限の日本郵便番号 API。
+> 日本郵便の `KEN_ALL.csv` / `KEN_ALL_ROME.csv` を JSON 正規化し CDN 配信。
+
+[English](./README.md) | **日本語**
+
+`@jpzip/jpzip` は `jpzip.nadai.dev` から日本の郵便番号 120,677 件を引く TypeScript SDK です。
+登録不要、レート制限なし、API キー不要。
+
+- 🇯🇵 **全件収録** — 漢字・カナ・ローマ字・自治体コード(JIS X 0401 / 総務省地方公共団体コード)
+- ⚡️ **高速** — L1 LRU + 任意の L2 永続キャッシュ。`preload` でネットワーク往復なしのルックアップが可能
+- 🛡️ **堅牢** — 5xx / ネットワーク失敗時は指数バックオフで最大 3 回リトライ
+- 🪶 **ランタイム依存ゼロ** — プラットフォーム標準の `fetch` のみ使用
+- 🧰 **型安全** — TypeScript ファーストクラス、ESM + CJS デュアルビルド
+- 🆓 **永久無料** — Cloudflare Pages 無料枠で運用(課金軸が存在しない)
+- 🔌 **同一 API** — [全 jpzip SDK](#他言語版) で API が揃う
+
+## 必要環境
+
+Node.js 18+(または `fetch` が標準搭載されたランタイム — Bun、Deno、モダンブラウザ、Cloudflare Workers、Vercel Edge)。
+
+## インストール
+
+```bash
+npm install @jpzip/jpzip
+# または
+pnpm add @jpzip/jpzip
+# または
+yarn add @jpzip/jpzip
+```
+
+## クイックスタート
+
+```ts
+import { lookup } from '@jpzip/jpzip';
+
+const entry = await lookup('2310017');
+if (entry === null) {
+  console.log('見つかりません');
+} else {
+  console.log(entry.prefecture, entry.city, entry.towns[0].town);
+  // 出力: 神奈川県 横浜市中区 港町
+}
+```
+
+ローマ字・自治体コードも同じエントリに含まれます:
+
+```ts
+console.log(entry.prefecture_roma, entry.city_roma, entry.towns[0].roma);
+// 出力: Kanagawa Ken Yokohama Shi Naka Ku Minatocho
+
+console.log(entry.prefecture_code, entry.city_code);
+// 出力: 14 14104
+```
+
+## ユースケース
+
+### 郵便番号ルックアップ HTTP エンドポイント (Hono)
+
+```ts
+import { Hono } from 'hono';
+import { lookup } from '@jpzip/jpzip';
+
+const app = new Hono();
+
+app.get('/api/zipcode/:code', async (c) => {
+  const entry = await lookup(c.req.param('code'));
+  if (entry === null) return c.notFound();
+  return c.json(entry);
+});
+
+export default app;
+```
+
+Node / Bun / Cloudflare Workers / Vercel Edge でそのまま動作します。
+
+### 郵便番号ルックアップ HTTP エンドポイント (Express)
+
+```ts
+import express from 'express';
+import { lookup } from '@jpzip/jpzip';
+
+const app = express();
+
+app.get('/api/zipcode/:code', async (req, res, next) => {
+  try {
+    const entry = await lookup(req.params.code);
+    if (entry === null) return res.status(404).end();
+    res.json(entry);
+  } catch (err) {
+    next(err);
+  }
+});
+
+app.listen(3000);
+```
+
+### CSV のバッチ検証
+
+```ts
+import { lookupAll } from '@jpzip/jpzip';
+
+const all = await lookupAll(); // 全件をメモリに展開(JSON 約 37 MiB)
+for (const zip of csvZipcodes) {
+  if (!(zip in all)) {
+    console.warn(`不正な郵便番号: ${zip}`);
+  }
+}
+```
+
+### キャッシュからの提供(任意の L2 バックエンド)
+
+データは 948 個の 3 桁 prefix バケットに分割されています。デフォルト L1 (100 件) は
+ホットなバケットを保持しますが、全件を常駐させるには L2 を併用するか
+`memoryCacheSize` を 948 超に設定してください。
+
+```ts
+import { JpzipClient, type PersistentCache } from '@jpzip/jpzip';
+import { readFile, writeFile, unlink, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const dir = '.jpzip-cache';
+const path = (key: string) => join(dir, createHash('sha1').update(key).digest('hex'));
+
+const fileCache: PersistentCache = {
+  async get(key) {
+    try {
+      return await readFile(path(key));
+    } catch {
+      return null;
+    }
+  },
+  async set(key, value) {
+    await writeFile(path(key), value);
+  },
+  async delete(key) {
+    await unlink(path(key)).catch(() => {});
+  },
+  async clear() {
+    await rm(dir, { recursive: true, force: true });
+  },
+};
+
+const client = new JpzipClient({
+  memoryCacheSize: 1024,
+  cache: fileCache,
+});
+
+await client.preload({ scope: 'all' });
+// 以降の lookup は L1/L2 で完結し、ネットワークにアクセスしない
+const entry = await client.lookup('2310017');
+```
+
+## API リファレンス
+
+### 関数(モジュールレベル、内部の default `JpzipClient` シングルトンを共有)
+
+| 関数 | 説明 |
+|---|---|
+| `lookup(zipcode)` | 7 桁の郵便番号で 1 件引く。見つからない / 不正な入力は `null`(不正入力時はネットワーク不使用)。 |
+| `lookupGroup(prefix)` | 1〜3 桁の prefix で引く。1 桁は `/g/{d}.json` を 1 回、3 桁は `/p/{ddd}.json` を 1 回、2 桁は 10 並列 fetch して結合。数字以外を含む入力では throw。 |
+| `lookupAll()` | `/g/0..9.json` を並列取得して全件(120k 件、約 37 MiB)を返す。 |
+| `getMeta()` | データバージョン・生成日時・都道府県別件数・spec version。client の `refresh()` を呼ぶまで結果をキャッシュ。 |
+| `preload({ scope })` | `'all'` または 1〜3 桁の prefix で L1(L2 設定時は L2 も)を温める。 |
+| `isValidZipcode(zip)` | 純粋な書式チェック(`^\d{7}$`)。ネットワーク不使用。 |
+| `configure(options)` | シングルトンを差し替え、以降の関数呼び出しに新オプションを適用。 |
+
+### `JpzipClient`(高度な用途)
+
+L2 キャッシュ、`fetch` 差し替え、配信元変更、複数の独立キャッシュが必要な場合にインスタンスを直接生成します:
+
+```ts
+import { JpzipClient } from '@jpzip/jpzip';
+
+const client = new JpzipClient({
+  baseUrl: 'https://jpzip.nadai.dev',
+  fetch: globalThis.fetch,            // 任意で差し替え
+  memoryCacheSize: 200,               // L1 容量(prefix バケット数)、デフォルト 100
+  cache: myPersistentCache,           // L2(任意)
+  onSpecMismatch: ({ expected, received }) => {
+    console.warn(`jpzip spec 不一致: SDK=${expected} server=${received}`);
+  },
+});
+```
+
+`JpzipClient` は `lookup` / `lookupGroup` / `lookupAll` / `getMeta` / `preload` に加えて:
+
+| メソッド | 説明 |
+|---|---|
+| `client.refresh()` | L1(L2 設定時は L2 も)を消し、キャッシュ済み meta を破棄。 |
+
+`getMeta()` が `/meta.json` の `version` 変更を検知すると L1/L2 が自動クリアされます。
+データ切り替えに追従するには `getMeta()` を定期的に呼んでください。
+
+### エラー
+
+- `lookup()` は「見つからない」「書式不正」いずれの場合も throw せず `null` を返します。
+- `lookupGroup(prefix)` は `prefix` が `/^\d{1,3}$/` に一致しない場合 `Error` を throw。
+- ネットワーク失敗と 5xx は最大 3 回試行(初回 + リトライ 2 回)、指数バックオフのスリープは 400ms / 800ms。404 以外の 4xx は即時 throw、404 は `null` 返却。`AbortError` はリトライせず再 throw。
+
+### `PersistentCache` インターフェース
+
+任意の L2 バックエンド(ファイル / IndexedDB / Redis / Cloudflare KV など)を渡せます:
+
+```ts
+export interface PersistentCache {
+  get(key: string): Promise<Uint8Array | null>;
+  set(key: string, value: Uint8Array): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+}
+```
+
+キーは prefix バケットの完全 URL(例: `https://jpzip.nadai.dev/p/231.json`)、値は生 JSON バイト列。
+
+### エクスポートされる型
+
+`ZipcodeEntry` / `Town` / `Meta` / `ZipcodeDict` / `Endpoints` / `JpzipClientOptions` / `PersistentCache` — すべて `@jpzip/jpzip` から import 可能。
+
+## なぜ jpzip-js か
+
+| | **jpzip-js** | [jpostcode][jpostcode] | [jposta][jposta] | [@ken-all/kenall][kenall] |
+|---|---|---|---|---|
+| ローマ字(`Yokohama Shi`) | ✅ | ❌ | ❌ | ⚠️ オプション |
+| 自治体コード(JIS / 総務省) | ✅ | ❌ | ⚠️ `prefNum` のみ | ✅ |
+| カナ | ✅ | ✅ | ❌ | ✅ |
+| ビルドに数 MB のデータを同梱しない | ✅ CDN fetch | ⚠️ npm 版は同梱 | ❌ JSON 同梱 | ✅ |
+| `npm install` 不要で月次更新 | ✅ CDN で自動 | ❌ 月次再公開 | ❌ 手動 | ✅ |
+| API キー不要 | ✅ | ✅ | ✅ | ❌ 必須 |
+| レート制限なし | ✅ | ✅ | ✅ | ⚠️ プラン依存 |
+| L1 + 差し替え可能な L2 | ✅ | ❌ | ❌ | ❌ |
+| ランタイム依存ゼロ | ✅ | ✅ | ✅ | ❌ (`zod`) |
+| ESM + CJS + TypeScript 型 | ✅ | ✅ | ✅ | ✅ |
+
+[jpostcode]: https://www.npmjs.com/package/jpostcode
+[jposta]: https://www.npmjs.com/package/jposta
+[kenall]: https://www.npmjs.com/package/@ken-all/kenall
+
+## 他言語版
+
+全 SDK で同一の API を提供しています:
+
+[Go](https://github.com/jpzip/go) · [Python](https://github.com/jpzip/python) · [Rust](https://github.com/jpzip/rust) · [Ruby](https://github.com/jpzip/ruby) · [PHP](https://github.com/jpzip/php) · [Swift](https://github.com/jpzip/swift) · [Dart](https://github.com/jpzip/dart)
+
+## 関連リソース
+
+- **Web サイト** — https://jpzip.nadai.dev
+- **プロトコル仕様** — [jpzip/spec](https://github.com/jpzip/spec)
+- **データ ETL** — [jpzip/data](https://github.com/jpzip/data)
+- **MCP サーバー** — [jpzip/mcp](https://github.com/jpzip/mcp) — Claude / ChatGPT / Cursor から jpzip を呼ぶ
+
+## キーワード
+
+日本郵便番号, 郵便番号, KEN_ALL, KEN_ALL_ROME, 住所バリデーション, 住所検索, japanese postal code, japan zipcode, postal code lookup typescript, typescript japanese address, node.js zipcode, hono 郵便番号, express 郵便番号, cloudflare workers 住所, JIS X 0401, 総務省地方公共団体コード
+
+## ライセンス
+
+[MIT](./LICENSE)

package/README.md

@@ -1,88 +1,270 @@
-# jpzip — TypeScript / JavaScript SDK
+## jpzip-js
 
-> 日本の郵便番号を CDN 配信の JSON データから引く SDK。`jpzip.nadai.dev` から取得する。
+[![npm version](https://img.shields.io/npm/v/@jpzip/jpzip.svg)](https://www.npmjs.com/package/@jpzip/jpzip)
+[![types: included](https://img.shields.io/npm/types/@jpzip/jpzip.svg)](https://www.npmjs.com/package/@jpzip/jpzip)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Test](https://github.com/jpzip/js/actions/workflows/test.yml/badge.svg)](https://github.com/jpzip/js/actions/workflows/test.yml)
 
-- 配信ドメイン: `https://jpzip.nadai.dev`
-- プロトコル仕様: [`jpzip/spec`](https://github.com/jpzip/spec)
-- データ ETL: [`jpzip/data`](https://github.com/jpzip/data)
+> TypeScript / JavaScript SDK for **jpzip** — a free, unlimited Japanese postal code (郵便番号) API.
+> 日本の全郵便番号 120,677 件を CDN 配信 JSON から引く TypeScript SDK。
 
-## インストール
+**English** | [日本語](./README.ja.md)
 
-```sh
+`@jpzip/jpzip` looks up Japanese postal codes (郵便番号) from `jpzip.nadai.dev`,
+a CDN-hosted dataset built from Japan Post's `KEN_ALL.csv` and `KEN_ALL_ROME.csv`
+normalized to JSON. No registration, no rate limits, no API key.
+
+- 🇯🇵 **Complete dataset** — 120,677 entries with kanji, kana, romaji, and government codes (JIS X 0401 / 総務省地方公共団体コード)
+- ⚡️ **Fast** — L1 LRU + optional L2 persistent cache; `preload` to serve lookups without per-request network round-trips
+- 🛡️ **Resilient** — up to 3 attempts with exponential backoff on 5xx / network failures
+- 🪶 **Zero runtime deps** — uses the platform `fetch` only
+- 🧰 **Typed end to end** — first-class TypeScript, ESM + CJS dual build
+- 🆓 **Free forever** — backed by Cloudflare Pages' free tier (no billing axis exists)
+- 🔌 **Drop-in** — same API surface across [every jpzip SDK](#other-languages)
+
+## Requirements
+
+Node.js 18+ (or any runtime with a global `fetch` — Bun, Deno, modern browsers, Cloudflare Workers, Vercel Edge).
+
+## Install
+
+```bash
 npm install @jpzip/jpzip
 # or
 pnpm add @jpzip/jpzip
+# or
+yarn add @jpzip/jpzip
 ```
 
-## 使い方
-
-### 関数 API
+## Quick Start
 
 ```ts
-import { lookup, lookupGroup, lookupAll, preload, getMeta } from '@jpzip/jpzip';
+import { lookup } from '@jpzip/jpzip';
 
 const entry = await lookup('2310017');
-// → { prefecture: '神奈川県', city: '横浜市中区', towns: [...], ... }
+if (entry === null) {
+  console.log('not found');
+} else {
+  console.log(entry.prefecture, entry.city, entry.towns[0].town);
+  // Output: 神奈川県 横浜市中区 港町
+}
+```
+
+Romaji and government codes are included on the same entry:
+
+```ts
+console.log(entry.prefecture_roma, entry.city_roma, entry.towns[0].roma);
+// Output: Kanagawa Ken Yokohama Shi Naka Ku Minatocho
+
+console.log(entry.prefecture_code, entry.city_code);
+// Output: 14 14104
+```
+
+## Use Cases
+
+### Zipcode lookup HTTP endpoint (Hono)
+
+```ts
+import { Hono } from 'hono';
+import { lookup } from '@jpzip/jpzip';
+
+const app = new Hono();
+
+app.get('/api/zipcode/:code', async (c) => {
+  const entry = await lookup(c.req.param('code'));
+  if (entry === null) return c.notFound();
+  return c.json(entry);
+});
+
+export default app;
+```
+
+Works unchanged on Node, Bun, Cloudflare Workers, and Vercel Edge.
+
+### Zipcode lookup HTTP endpoint (Express)
+
+```ts
+import express from 'express';
+import { lookup } from '@jpzip/jpzip';
+
+const app = express();
+
+app.get('/api/zipcode/:code', async (req, res, next) => {
+  try {
+    const entry = await lookup(req.params.code);
+    if (entry === null) return res.status(404).end();
+    res.json(entry);
+  } catch (err) {
+    next(err);
+  }
+});
+
+app.listen(3000);
+```
+
+### Batch validation
+
+```ts
+import { lookupAll } from '@jpzip/jpzip';
+
+const all = await lookupAll(); // entire dataset in memory (~37 MiB JSON)
+for (const zip of csvZipcodes) {
+  if (!(zip in all)) {
+    console.warn(`invalid zipcode: ${zip}`);
+  }
+}
+```
+
+### Serve lookups from cache (BYO L2 backend)
+
+The dataset is partitioned into 948 three-digit prefix buckets. The default
+L1 (100 entries) keeps the hottest buckets; to cache the whole dataset, pair
+`preload({ scope: 'all' })` with an L2 cache or raise `memoryCacheSize` above 948.
+
+```ts
+import { JpzipClient, type PersistentCache } from '@jpzip/jpzip';
+import { readFile, writeFile, unlink, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const dir = '.jpzip-cache';
+const path = (key: string) => join(dir, createHash('sha1').update(key).digest('hex'));
+
+const fileCache: PersistentCache = {
+  async get(key) {
+    try {
+      return await readFile(path(key));
+    } catch {
+      return null;
+    }
+  },
+  async set(key, value) {
+    await writeFile(path(key), value);
+  },
+  async delete(key) {
+    await unlink(path(key)).catch(() => {});
+  },
+  async clear() {
+    await rm(dir, { recursive: true, force: true });
+  },
+};
 
-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 client = new JpzipClient({
+  memoryCacheSize: 1024,
+  cache: fileCache,
+});
 
-const all = await lookupAll(); // /all.json (大きい)
-const meta = await getMeta();
+await client.preload({ scope: 'all' });
+// Subsequent lookups are served from L1/L2 without hitting the network.
+const entry = await client.lookup('2310017');
 ```
 
-### クラス API (L2 キャッシュ・複数インスタンス用)
+## API Reference
+
+### Functions (module-level, share a default `JpzipClient` singleton)
+
+| Function | Description |
+|---|---|
+| `lookup(zipcode)` | Look up a single 7-digit zipcode. Returns `null` for not-found or malformed input (no network call for malformed input). |
+| `lookupGroup(prefix)` | Look up by 1-, 2-, or 3-digit prefix. 1-digit fetches `/g/{d}.json`; 3-digit fetches `/p/{ddd}.json`; 2-digit fans out into 10 parallel 3-digit fetches and merges. Throws on non-digit input. |
+| `lookupAll()` | Fetch entire dataset (120k entries, ~37 MiB) in parallel across `/g/0..9.json`. |
+| `getMeta()` | Dataset version, generated-at, per-prefecture counts, spec version. Result is cached until `refresh()` is called on the client. |
+| `preload({ scope })` | Warm L1 (and L2 when configured) for `'all'` or a specific 1-3 digit prefix. |
+| `isValidZipcode(zip)` | Pure syntax check (`^\d{7}$`) — no network. |
+| `configure(options)` | Replace the singleton with a new `JpzipClient` configured with `options`. |
+
+### `JpzipClient` (advanced)
+
+Construct an instance for L2 caching, custom `fetch`, alternate base URL, or
+multiple isolated caches:
 
 ```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() { /* ... */ },
+  fetch: globalThis.fetch,            // optional override
+  memoryCacheSize: 200,               // L1 capacity in prefix buckets, default 100
+  cache: myPersistentCache,           // optional L2
+  onSpecMismatch: ({ expected, received }) => {
+    console.warn(`jpzip spec mismatch: SDK=${expected} server=${received}`);
   },
 });
+```
 
-await client.preload({ scope: 'all' }); // オフラインモード相当
-const entry = await client.lookup('2310017');
+`JpzipClient` exposes `lookup` / `lookupGroup` / `lookupAll` / `getMeta` / `preload` plus:
+
+| Method | Description |
+|---|---|
+| `client.refresh()` | Wipe L1 (and L2 when configured) and forget the cached meta. |
+
+When `getMeta()` observes that `/meta.json`'s `version` has changed since the last
+successful fetch, L1 and L2 are cleared automatically — call `getMeta()` periodically
+to pick up dataset rollovers.
+
+### Errors
+
+- `lookup()` returns `null` rather than throwing for both "not found" and malformed input.
+- `lookupGroup(prefix)` throws `Error` if `prefix` doesn't match `/^\d{1,3}$/`.
+- Transient network failures and 5xx responses are retried up to 3 attempts (initial + 2 retries) with exponential backoff sleeps of 400ms and 800ms. 4xx responses other than 404 throw immediately; 404 yields `null`. `AbortError` propagates without retry.
+
+### `PersistentCache` interface
+
+Bring your own L2 backend (file system, IndexedDB, Redis, Cloudflare KV, etc.):
+
+```ts
+export interface PersistentCache {
+  get(key: string): Promise<Uint8Array | null>;
+  set(key: string, value: Uint8Array): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+}
 ```
 
-## キャッシュ戦略 (3 層)
+Keys are the full bucket URLs (e.g. `https://jpzip.nadai.dev/p/231.json`); values
+are raw JSON bytes.
 
-| 層 | 目的 | 既定 |
-|---|---|---|
-| **L1 メモリ LRU** | 同一プロセスの重複 fetch 抑制 | 常時 ON、prefix 100 件保持 |
-| **L2 永続キャッシュ** | 起動またぎ / preload 結果保持 | OFF、`cache` オプションで有効化 |
-| **L3 HTTP** | ブラウザ / OS のキャッシュ | SDK 制御外 |
+### Exported types
 
-詳しくは [`jpzip/spec` §6.4](https://github.com/jpzip/spec/blob/main/spec/v1/protocol.md) を参照。
+`ZipcodeEntry`, `Town`, `Meta`, `ZipcodeDict`, `Endpoints`, `JpzipClientOptions`,
+`PersistentCache` — all importable from `@jpzip/jpzip`.
 
-## API
+## Why jpzip-js?
 
-| 関数 | 説明 |
-|---|---|
-| `lookup(zipcode)` | 単一 zipcode を引く。`null` は「見つからない」 |
-| `lookupGroup(prefix)` | 1〜3 桁の prefix 配下を返す |
-| `lookupAll()` | 全件辞書 (preload 用) |
-| `preload({scope})` | `'all'` または prefix を SDK 内キャッシュに格納 |
-| `getMeta()` | `/meta.json` を取得・キャッシュ |
-| `isValidZipcode(zip)` | 7 桁数字フォーマット検証 |
-| `configure(options)` | グローバルシングルトンのオプション差し替え |
+| | **jpzip-js** | [jpostcode][jpostcode] | [jposta][jposta] | [@ken-all/kenall][kenall] |
+|---|---|---|---|---|
+| Romaji (`Yokohama Shi`) | ✅ | ❌ | ❌ | ⚠️ Optional field |
+| Government codes (JIS / 総務省) | ✅ | ❌ | ⚠️ `prefNum` only | ✅ |
+| Kana | ✅ | ✅ | ❌ | ✅ |
+| No bundled multi-MB data in your build | ✅ CDN fetch | ⚠️ npm version embeds data | ❌ Embedded JSON | ✅ |
+| Monthly updates without re-`npm install` | ✅ Auto via CDN | ❌ Republished monthly | ❌ Manual | ✅ |
+| No API key | ✅ | ✅ | ✅ | ❌ Required |
+| Rate-limit-free | ✅ | ✅ | ✅ | ⚠️ Plan-based quota |
+| L1 + pluggable L2 cache | ✅ | ❌ | ❌ | ❌ |
+| Zero runtime deps | ✅ | ✅ | ✅ | ❌ (`zod`) |
+| ESM + CJS + TypeScript types | ✅ | ✅ | ✅ | ✅ |
+
+[jpostcode]: https://www.npmjs.com/package/jpostcode
+[jposta]: https://www.npmjs.com/package/jposta
+[kenall]: https://www.npmjs.com/package/@ken-all/kenall
+
+## Other Languages
+
+Same API surface across all SDKs:
+
+[Go](https://github.com/jpzip/go) · [Python](https://github.com/jpzip/python) · [Rust](https://github.com/jpzip/rust) · [Ruby](https://github.com/jpzip/ruby) · [PHP](https://github.com/jpzip/php) · [Swift](https://github.com/jpzip/swift) · [Dart](https://github.com/jpzip/dart)
 
-## 入力検証
+## Resources
 
-`lookup()` は `^\d{7}$` にマッチしない入力には fetch せず `null` を返す。
+- **Website** — https://jpzip.nadai.dev
+- **Protocol spec** — [jpzip/spec](https://github.com/jpzip/spec)
+- **Data ETL** — [jpzip/data](https://github.com/jpzip/data)
+- **MCP server** — [jpzip/mcp](https://github.com/jpzip/mcp) — use jpzip from Claude / ChatGPT / Cursor
 
-## バージョン整合性
+## Keywords
 
-`getMeta()` 初回呼び出し時、`spec_version` が SDK 対応バージョン (`"1.0"`) と異なる場合は `onSpecMismatch` コールバックを 1 回呼ぶ。`version` (データバージョン) が変わったらキャッシュを自動 invalidate。
+japanese postal code, japan zipcode, 郵便番号, KEN_ALL, KEN_ALL_ROME, address validation, postal code lookup typescript, typescript japanese address, node.js zipcode, hono postal code, express zipcode, cloudflare workers japan address, JIS X 0401, 総務省地方公共団体コード
 
-## ライセンス
+## License
 
 [MIT](./LICENSE)

package/dist/index.cjs

@@ -75,27 +75,29 @@ async function fetchJSON(url, opts = {}) {
     if (attempt > 0) {
       await sleep(BASE_DELAY_MS * 2 ** attempt);
     }
+    const init = {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    };
+    if (opts.signal !== void 0) init.signal = opts.signal;
+    if (opts.noCache) init.cache = "no-cache";
+    let res;
     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();
+      res = await f(url, init);
     } catch (err) {
-      lastErr = err;
       if (err instanceof DOMException && err.name === "AbortError") throw err;
+      lastErr = err;
+      continue;
+    }
+    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();
   }
   throw lastErr instanceof Error ? lastErr : new Error(`jpzip: fetch failed for ${url}: ${String(lastErr)}`);
 }

package/dist/index.cjs.map

@@ -1 +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":"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","names":[]}
+{"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    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    let res: Response;\n    try {\n      res = await f(url, init);\n    } catch (err) {\n      // Network-layer failures (DNS, TLS, fetch abort, etc.) — retry,\n      // unless the caller aborted us, which should propagate immediately.\n      if (err instanceof DOMException && err.name === 'AbortError') throw err;\n      lastErr = err;\n      continue;\n    }\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    // Other 4xx are not retried — the request itself is wrong.\n    if (!res.ok) {\n      throw new Error(`jpzip: ${url} returned ${res.status}`);\n    }\n    return (await res.json()) as T;\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":"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","names":[]}

package/dist/index.js

@@ -39,27 +39,29 @@ async function fetchJSON(url, opts = {}) {
     if (attempt > 0) {
       await sleep(BASE_DELAY_MS * 2 ** attempt);
     }
+    const init = {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    };
+    if (opts.signal !== void 0) init.signal = opts.signal;
+    if (opts.noCache) init.cache = "no-cache";
+    let res;
     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();
+      res = await f(url, init);
     } catch (err) {
-      lastErr = err;
       if (err instanceof DOMException && err.name === "AbortError") throw err;
+      lastErr = err;
+      continue;
+    }
+    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();
   }
   throw lastErr instanceof Error ? lastErr : new Error(`jpzip: fetch failed for ${url}: ${String(lastErr)}`);
 }

package/dist/index.js.map

@@ -1 +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":"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","names":[]}
+{"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    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    let res: Response;\n    try {\n      res = await f(url, init);\n    } catch (err) {\n      // Network-layer failures (DNS, TLS, fetch abort, etc.) — retry,\n      // unless the caller aborted us, which should propagate immediately.\n      if (err instanceof DOMException && err.name === 'AbortError') throw err;\n      lastErr = err;\n      continue;\n    }\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    // Other 4xx are not retried — the request itself is wrong.\n    if (!res.ok) {\n      throw new Error(`jpzip: ${url} returned ${res.status}`);\n    }\n    return (await res.json()) as T;\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":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpzip/jpzip",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Japan postal-code dataset SDK — fetches normalized JSON from jpzip.nadai.dev",
   "type": "module",
   "main": "./dist/index.cjs",