@structured-world/structured-public-domains 0.0.7 → 0.0.8

package/README.md

@@ -77,6 +77,32 @@ const bytes = pslData();   // Uint8Array — a defensive copy of the trie blob
 The JS lookup is verified byte-for-byte against the Rust implementation over the
 entire PSL on every CI run, so both languages return identical results.
 
+### Tiny build (runtime-fetched, no embedded data)
+
+For consumers who want always-fresh PSL **without bumping the package version**,
+the `/tiny` entry ships *without* the embedded blob. It fetches the prebuilt
+binary trie at runtime and caches it locally (Node: temp file with a TTL;
+browser: CacheStorage). After the first `await load()`, the lookup API is
+identical and synchronous.
+
+```typescript
+import { load, registrableDomain } from '@structured-world/structured-public-domains/tiny';
+
+await load();                              // fetch + cache once (default: jsDelivr CDN)
+registrableDomain('sub.example.co.uk');    // "example.co.uk"
+
+// Options: custom source, TTL, cache dir, or force refresh.
+await load({ url: 'https://psl.example.com/psl.bin', cacheTtlMs: 3_600_000, force: true });
+```
+
+The default source is the same `psl.bin` served from this package's jsDelivr CDN,
+pinned to the installed `major.minor` range — so it always tracks the latest
+PSL-data patch release (same trie format) but never a future format-breaking
+version the bundled parser can't read. Results are identical to the embedded
+build. Use the full `.` entry when you want zero network and instant startup; use
+`/tiny` when install size and
+always-current data matter more.
+
 ## Performance
 
 Benchmarks on Apple M-series (criterion, `cargo bench`):

package/dist/chunk-EON4VJGA.js

@@ -0,0 +1,121 @@
+// src/trie.ts
+var utf8 = new TextDecoder("utf-8", { fatal: true });
+function parseTrie(data) {
+  const cursor = { pos: 0 };
+  const root = parseNode(data, cursor);
+  if (cursor.pos !== data.length) {
+    throw new Error("PSL data: trailing bytes after root node");
+  }
+  return root;
+}
+function parseNode(data, cursor) {
+  const flags = byteAt(data, cursor.pos++);
+  if ((flags & -2) !== 0) {
+    throw new Error("PSL data: reserved flag bits set");
+  }
+  const lo = byteAt(data, cursor.pos++);
+  const hi = byteAt(data, cursor.pos++);
+  let numChildren = lo | hi << 8;
+  const MIN_CHILD_ENCODED_LEN = 5;
+  const remaining = data.length - cursor.pos;
+  if (remaining < 0 || numChildren > Math.floor(remaining / MIN_CHILD_ENCODED_LEN)) {
+    throw new Error("PSL data: num_children exceeds remaining bytes");
+  }
+  const labels = [];
+  const children = [];
+  let prev;
+  for (; numChildren > 0; numChildren--) {
+    const labelLen = byteAt(data, cursor.pos++);
+    if (labelLen === 0) {
+      throw new Error("PSL data: empty label");
+    }
+    const labelEnd = cursor.pos + labelLen;
+    if (labelEnd > data.length) {
+      throw new Error("PSL data: label runs past end of data");
+    }
+    const label = decodeLabel(data, cursor.pos, labelEnd);
+    cursor.pos = labelEnd;
+    if (prev !== void 0 && !(label > prev)) {
+      throw new Error("PSL data: children not strictly sorted");
+    }
+    prev = label;
+    labels.push(label);
+    children.push(parseNode(data, cursor));
+  }
+  return { suffixBoundary: (flags & 1) !== 0, labels, children };
+}
+function byteAt(data, i) {
+  if (i >= data.length) {
+    throw new Error("PSL data: unexpected end of data");
+  }
+  return data[i];
+}
+function decodeLabel(data, start, end) {
+  for (let i = start; i < end; i++) {
+    if (data[i] >= 128) return utf8.decode(data.subarray(start, end));
+  }
+  let s = "";
+  for (let i = start; i < end; i++) s += String.fromCharCode(data[i]);
+  return s;
+}
+function indexOfChild(node, label) {
+  let lo = 0;
+  let hi = node.labels.length - 1;
+  while (lo <= hi) {
+    const mid = lo + hi >>> 1;
+    const cur = node.labels[mid];
+    if (cur === label) return mid;
+    if (cur < label) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+function childOf(node, label) {
+  const i = indexOfChild(node, label);
+  return i < 0 ? void 0 : node.children[i];
+}
+function hasChild(node, label) {
+  return indexOfChild(node, label) >= 0;
+}
+function lookupTrie(root, domain) {
+  const trimmed = domain.trim();
+  const stripped = trimmed.endsWith(".") ? trimmed.slice(0, -1) : trimmed;
+  if (stripped === "") return void 0;
+  const labels = stripped.split(".").reverse();
+  for (const label of labels) {
+    if (label === "" || label === "*" || label.startsWith("!")) return void 0;
+  }
+  let node = root;
+  let suffixDepth = 0;
+  let known = false;
+  for (let depth = 0; depth < labels.length; depth++) {
+    const label = labels[depth].toLowerCase();
+    if (hasChild(node, "*")) {
+      if (hasChild(node, "!" + label)) {
+        suffixDepth = depth;
+      } else {
+        suffixDepth = depth + 1;
+      }
+      known = true;
+    }
+    const child = childOf(node, label);
+    if (child !== void 0) {
+      if (child.suffixBoundary) {
+        suffixDepth = depth + 1;
+        known = true;
+      }
+      node = child;
+      continue;
+    }
+    break;
+  }
+  if (suffixDepth === 0) {
+    suffixDepth = 1;
+    known = false;
+  }
+  const suffix = labels.slice(0, suffixDepth).reverse().map((l) => l.toLowerCase()).join(".");
+  const registrableDomain = labels.length > suffixDepth ? `${labels[suffixDepth].toLowerCase()}.${suffix}` : void 0;
+  return { suffix, registrableDomain, known };
+}
+
+export { lookupTrie, parseTrie };

package/dist/index.d.cts

@@ -1,12 +1,4 @@
-/** Result of a PSL lookup. */
-interface DomainInfo {
-    /** The public suffix (e.g. `"co.uk"`, `"com"`, `"github.io"`). */
-    readonly suffix: string;
-    /** The registrable domain (eTLD+1), or `undefined` if the input is itself a suffix. */
-    readonly registrableDomain: string | undefined;
-    /** Whether the suffix matched an explicit PSL rule (vs the `*` fallback). */
-    readonly known: boolean;
-}
+import { D as DomainInfo } from './trie-jGeN4GI6.cjs';
 
 /**
  * Look up a domain in the Public Suffix List.
@@ -41,4 +33,4 @@ declare function isKnownSuffix(domain: string): boolean;
  */
 declare function pslData(): Uint8Array;
 
-export { type DomainInfo, isKnownSuffix, lookup, pslData, registrableDomain };
+export { DomainInfo, isKnownSuffix, lookup, pslData, registrableDomain };

package/dist/index.d.ts

@@ -1,12 +1,4 @@
-/** Result of a PSL lookup. */
-interface DomainInfo {
-    /** The public suffix (e.g. `"co.uk"`, `"com"`, `"github.io"`). */
-    readonly suffix: string;
-    /** The registrable domain (eTLD+1), or `undefined` if the input is itself a suffix. */
-    readonly registrableDomain: string | undefined;
-    /** Whether the suffix matched an explicit PSL rule (vs the `*` fallback). */
-    readonly known: boolean;
-}
+import { D as DomainInfo } from './trie-jGeN4GI6.js';
 
 /**
  * Look up a domain in the Public Suffix List.
@@ -41,4 +33,4 @@ declare function isKnownSuffix(domain: string): boolean;
  */
 declare function pslData(): Uint8Array;
 
-export { type DomainInfo, isKnownSuffix, lookup, pslData, registrableDomain };
+export { DomainInfo, isKnownSuffix, lookup, pslData, registrableDomain };

package/dist/index.js

@@ -1,128 +1,6 @@
+import { lookupTrie, parseTrie } from './chunk-EON4VJGA.js';
 import { PSL_BASE64 } from './psl-data.cjs';
 
-// src/index.ts
-
-// src/trie.ts
-var utf8 = new TextDecoder("utf-8", { fatal: true });
-function parseTrie(data) {
-  const cursor = { pos: 0 };
-  const root = parseNode(data, cursor);
-  if (cursor.pos !== data.length) {
-    throw new Error("PSL data: trailing bytes after root node");
-  }
-  return root;
-}
-function parseNode(data, cursor) {
-  const flags = byteAt(data, cursor.pos++);
-  if ((flags & -2) !== 0) {
-    throw new Error("PSL data: reserved flag bits set");
-  }
-  const lo = byteAt(data, cursor.pos++);
-  const hi = byteAt(data, cursor.pos++);
-  let numChildren = lo | hi << 8;
-  const MIN_CHILD_ENCODED_LEN = 5;
-  const remaining = data.length - cursor.pos;
-  if (remaining < 0 || numChildren > Math.floor(remaining / MIN_CHILD_ENCODED_LEN)) {
-    throw new Error("PSL data: num_children exceeds remaining bytes");
-  }
-  const labels = [];
-  const children = [];
-  let prev;
-  for (; numChildren > 0; numChildren--) {
-    const labelLen = byteAt(data, cursor.pos++);
-    if (labelLen === 0) {
-      throw new Error("PSL data: empty label");
-    }
-    const labelEnd = cursor.pos + labelLen;
-    if (labelEnd > data.length) {
-      throw new Error("PSL data: label runs past end of data");
-    }
-    const label = decodeLabel(data, cursor.pos, labelEnd);
-    cursor.pos = labelEnd;
-    if (prev !== void 0 && !(label > prev)) {
-      throw new Error("PSL data: children not strictly sorted");
-    }
-    prev = label;
-    labels.push(label);
-    children.push(parseNode(data, cursor));
-  }
-  return { suffixBoundary: (flags & 1) !== 0, labels, children };
-}
-function byteAt(data, i) {
-  if (i >= data.length) {
-    throw new Error("PSL data: unexpected end of data");
-  }
-  return data[i];
-}
-function decodeLabel(data, start, end) {
-  for (let i = start; i < end; i++) {
-    if (data[i] >= 128) return utf8.decode(data.subarray(start, end));
-  }
-  let s = "";
-  for (let i = start; i < end; i++) s += String.fromCharCode(data[i]);
-  return s;
-}
-function indexOfChild(node, label) {
-  let lo = 0;
-  let hi = node.labels.length - 1;
-  while (lo <= hi) {
-    const mid = lo + hi >>> 1;
-    const cur = node.labels[mid];
-    if (cur === label) return mid;
-    if (cur < label) lo = mid + 1;
-    else hi = mid - 1;
-  }
-  return -1;
-}
-function childOf(node, label) {
-  const i = indexOfChild(node, label);
-  return i < 0 ? void 0 : node.children[i];
-}
-function hasChild(node, label) {
-  return indexOfChild(node, label) >= 0;
-}
-function lookupTrie(root, domain) {
-  const trimmed = domain.trim();
-  const stripped = trimmed.endsWith(".") ? trimmed.slice(0, -1) : trimmed;
-  if (stripped === "") return void 0;
-  const labels = stripped.split(".").reverse();
-  for (const label of labels) {
-    if (label === "" || label === "*" || label.startsWith("!")) return void 0;
-  }
-  let node = root;
-  let suffixDepth = 0;
-  let known = false;
-  for (let depth = 0; depth < labels.length; depth++) {
-    const label = labels[depth].toLowerCase();
-    if (hasChild(node, "*")) {
-      if (hasChild(node, "!" + label)) {
-        suffixDepth = depth;
-      } else {
-        suffixDepth = depth + 1;
-      }
-      known = true;
-    }
-    const child = childOf(node, label);
-    if (child !== void 0) {
-      if (child.suffixBoundary) {
-        suffixDepth = depth + 1;
-        known = true;
-      }
-      node = child;
-      continue;
-    }
-    break;
-  }
-  if (suffixDepth === 0) {
-    suffixDepth = 1;
-    known = false;
-  }
-  const suffix = labels.slice(0, suffixDepth).reverse().map((l) => l.toLowerCase()).join(".");
-  const registrableDomain2 = labels.length > suffixDepth ? `${labels[suffixDepth].toLowerCase()}.${suffix}` : void 0;
-  return { suffix, registrableDomain: registrableDomain2, known };
-}
-
-// src/index.ts
 var cachedBytes;
 var cachedTrie;
 function decodeBase64(b64) {

package/dist/tiny.cjs

@@ -0,0 +1,293 @@
+'use strict';
+
+// src/trie.ts
+var utf8 = new TextDecoder("utf-8", { fatal: true });
+function parseTrie(data) {
+  const cursor = { pos: 0 };
+  const root = parseNode(data, cursor);
+  if (cursor.pos !== data.length) {
+    throw new Error("PSL data: trailing bytes after root node");
+  }
+  return root;
+}
+function parseNode(data, cursor) {
+  const flags = byteAt(data, cursor.pos++);
+  if ((flags & -2) !== 0) {
+    throw new Error("PSL data: reserved flag bits set");
+  }
+  const lo = byteAt(data, cursor.pos++);
+  const hi = byteAt(data, cursor.pos++);
+  let numChildren = lo | hi << 8;
+  const MIN_CHILD_ENCODED_LEN = 5;
+  const remaining = data.length - cursor.pos;
+  if (remaining < 0 || numChildren > Math.floor(remaining / MIN_CHILD_ENCODED_LEN)) {
+    throw new Error("PSL data: num_children exceeds remaining bytes");
+  }
+  const labels = [];
+  const children = [];
+  let prev;
+  for (; numChildren > 0; numChildren--) {
+    const labelLen = byteAt(data, cursor.pos++);
+    if (labelLen === 0) {
+      throw new Error("PSL data: empty label");
+    }
+    const labelEnd = cursor.pos + labelLen;
+    if (labelEnd > data.length) {
+      throw new Error("PSL data: label runs past end of data");
+    }
+    const label = decodeLabel(data, cursor.pos, labelEnd);
+    cursor.pos = labelEnd;
+    if (prev !== void 0 && !(label > prev)) {
+      throw new Error("PSL data: children not strictly sorted");
+    }
+    prev = label;
+    labels.push(label);
+    children.push(parseNode(data, cursor));
+  }
+  return { suffixBoundary: (flags & 1) !== 0, labels, children };
+}
+function byteAt(data, i) {
+  if (i >= data.length) {
+    throw new Error("PSL data: unexpected end of data");
+  }
+  return data[i];
+}
+function decodeLabel(data, start, end) {
+  for (let i = start; i < end; i++) {
+    if (data[i] >= 128) return utf8.decode(data.subarray(start, end));
+  }
+  let s = "";
+  for (let i = start; i < end; i++) s += String.fromCharCode(data[i]);
+  return s;
+}
+function indexOfChild(node, label) {
+  let lo = 0;
+  let hi = node.labels.length - 1;
+  while (lo <= hi) {
+    const mid = lo + hi >>> 1;
+    const cur = node.labels[mid];
+    if (cur === label) return mid;
+    if (cur < label) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return -1;
+}
+function childOf(node, label) {
+  const i = indexOfChild(node, label);
+  return i < 0 ? void 0 : node.children[i];
+}
+function hasChild(node, label) {
+  return indexOfChild(node, label) >= 0;
+}
+function lookupTrie(root, domain) {
+  const trimmed = domain.trim();
+  const stripped = trimmed.endsWith(".") ? trimmed.slice(0, -1) : trimmed;
+  if (stripped === "") return void 0;
+  const labels = stripped.split(".").reverse();
+  for (const label of labels) {
+    if (label === "" || label === "*" || label.startsWith("!")) return void 0;
+  }
+  let node = root;
+  let suffixDepth = 0;
+  let known = false;
+  for (let depth = 0; depth < labels.length; depth++) {
+    const label = labels[depth].toLowerCase();
+    if (hasChild(node, "*")) {
+      if (hasChild(node, "!" + label)) {
+        suffixDepth = depth;
+      } else {
+        suffixDepth = depth + 1;
+      }
+      known = true;
+    }
+    const child = childOf(node, label);
+    if (child !== void 0) {
+      if (child.suffixBoundary) {
+        suffixDepth = depth + 1;
+        known = true;
+      }
+      node = child;
+      continue;
+    }
+    break;
+  }
+  if (suffixDepth === 0) {
+    suffixDepth = 1;
+    known = false;
+  }
+  const suffix = labels.slice(0, suffixDepth).reverse().map((l) => l.toLowerCase()).join(".");
+  const registrableDomain2 = labels.length > suffixDepth ? `${labels[suffixDepth].toLowerCase()}.${suffix}` : void 0;
+  return { suffix, registrableDomain: registrableDomain2, known };
+}
+
+// src/tiny.ts
+var PSL_RANGE = "0.0" ;
+var DEFAULT_PSL_URL = `https://cdn.jsdelivr.net/npm/@structured-world/structured-public-domains@${PSL_RANGE}/dist/psl.bin`;
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+var isNode = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+var cachedBytes;
+var cachedTrie;
+var inFlight;
+var latestGen = 0;
+var latestSettled;
+function load(opts = {}) {
+  if (cachedTrie !== void 0 && opts.force !== true) return Promise.resolve();
+  if (inFlight !== void 0 && opts.force !== true) return inFlight;
+  const gen = ++latestGen;
+  const pending = doLoad(opts, gen);
+  latestSettled = pending;
+  inFlight = pending;
+  pending.finally(() => {
+    if (inFlight === pending) inFlight = void 0;
+  }).catch(() => void 0);
+  return pending;
+}
+function mirrorLatest() {
+  return latestSettled ?? Promise.resolve();
+}
+async function doLoad(opts, gen) {
+  let data;
+  let trie;
+  try {
+    [data, trie] = await fetchAndParse(opts);
+  } catch (err) {
+    if (gen !== latestGen) return mirrorLatest();
+    throw err;
+  }
+  if (gen !== latestGen) return mirrorLatest();
+  cachedBytes = data;
+  cachedTrie = trie;
+}
+async function fetchAndParse(opts) {
+  const url = opts.url ?? DEFAULT_PSL_URL;
+  const ttlMs = opts.cacheTtlMs ?? DEFAULT_TTL_MS;
+  const useCache = opts.cache ?? true;
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  if (useCache && opts.force !== true) {
+    const cached = await readCache(url, ttlMs, opts.cacheDir);
+    if (cached !== void 0) {
+      try {
+        return [cached, parseTrie(cached)];
+      } catch {
+        await deleteCache(url, opts.cacheDir).catch(() => void 0);
+      }
+    }
+  }
+  if (typeof doFetch !== "function") {
+    throw new Error("no fetch implementation available; pass `fetch` in LoadOptions");
+  }
+  const data = await fetchBytes(doFetch, url);
+  const trie = parseTrie(data);
+  if (useCache) await writeCache(url, data, opts.cacheDir).catch(() => void 0);
+  return [data, trie];
+}
+function isLoaded() {
+  return cachedTrie !== void 0;
+}
+function requireTrie() {
+  if (cachedTrie === void 0) {
+    throw new Error("PSL data not loaded \u2014 call `await load()` before lookups");
+  }
+  return cachedTrie;
+}
+function lookup(domain) {
+  return lookupTrie(requireTrie(), domain);
+}
+function registrableDomain(domain) {
+  return lookup(domain)?.registrableDomain;
+}
+function isKnownSuffix(domain) {
+  return lookup(domain)?.known ?? false;
+}
+function pslData() {
+  if (cachedBytes === void 0) {
+    throw new Error("PSL data not loaded \u2014 call `await load()` before pslData()");
+  }
+  return cachedBytes.slice();
+}
+async function fetchBytes(doFetch, url) {
+  const res = await doFetch(url);
+  if (!res.ok) {
+    throw new Error(`failed to fetch PSL data from ${url}: ${res.status} ${res.statusText}`);
+  }
+  const data = new Uint8Array(await res.arrayBuffer());
+  if (data.length < 1024) {
+    throw new Error(`PSL data from ${url} is implausibly small (${data.length} bytes)`);
+  }
+  return data;
+}
+function cacheKey(url) {
+  let h = 2166136261;
+  for (let i = 0; i < url.length; i++) {
+    h ^= url.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+async function readCache(url, ttlMs, cacheDir) {
+  try {
+    return isNode ? await readNodeCache(url, ttlMs, cacheDir) : await readBrowserCache(url, ttlMs);
+  } catch {
+    return void 0;
+  }
+}
+async function writeCache(url, data, cacheDir) {
+  if (isNode) await writeNodeCache(url, data, cacheDir);
+  else await writeBrowserCache(url, data);
+}
+async function deleteCache(url, cacheDir) {
+  if (isNode) {
+    const { fs, file } = await nodeCache(url, cacheDir);
+    fs.rmSync(file, { force: true });
+  } else if (typeof caches !== "undefined") {
+    const cache = await caches.open("structured-public-domains");
+    await cache.delete(url);
+  }
+}
+var nodeRequire = (m) => import(
+  /* @vite-ignore */
+  m
+);
+async function nodeCache(url, cacheDir) {
+  const fs = await nodeRequire("node:fs");
+  const os = await nodeRequire("node:os");
+  const path = await nodeRequire("node:path");
+  const dir = cacheDir ?? path.join(os.tmpdir(), "structured-public-domains-cache");
+  return { fs, dir, file: path.join(dir, `psl-${cacheKey(url)}.bin`) };
+}
+async function readNodeCache(url, ttlMs, cacheDir) {
+  const { fs, file } = await nodeCache(url, cacheDir);
+  const stat = fs.statSync(file);
+  if (Date.now() - stat.mtimeMs >= ttlMs) return void 0;
+  return new Uint8Array(fs.readFileSync(file));
+}
+async function writeNodeCache(url, data, cacheDir) {
+  const { fs, dir, file } = await nodeCache(url, cacheDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+async function readBrowserCache(url, ttlMs) {
+  if (typeof caches === "undefined") return void 0;
+  const cache = await caches.open("structured-public-domains");
+  const res = await cache.match(url);
+  if (res == null) return void 0;
+  const cachedAt = Number(res.headers.get("x-cached-at") ?? "0");
+  if (!Number.isFinite(cachedAt) || Date.now() - cachedAt >= ttlMs) return void 0;
+  return new Uint8Array(await res.arrayBuffer());
+}
+async function writeBrowserCache(url, data) {
+  if (typeof caches === "undefined") return;
+  const cache = await caches.open("structured-public-domains");
+  const body = data.slice();
+  await cache.put(url, new Response(body, { headers: { "x-cached-at": String(Date.now()) } }));
+}
+
+exports.DEFAULT_PSL_URL = DEFAULT_PSL_URL;
+exports.isKnownSuffix = isKnownSuffix;
+exports.isLoaded = isLoaded;
+exports.load = load;
+exports.lookup = lookup;
+exports.pslData = pslData;
+exports.registrableDomain = registrableDomain;

package/dist/tiny.d.cts

@@ -0,0 +1,45 @@
+import { D as DomainInfo } from './trie-jGeN4GI6.cjs';
+
+/** Default data source: the prebuilt trie served from this package via jsDelivr's CDN. */
+declare const DEFAULT_PSL_URL: string;
+/** Options for {@link load}. */
+interface LoadOptions {
+    /** Where to fetch `psl.bin` from. Defaults to {@link DEFAULT_PSL_URL}. */
+    url?: string;
+    /** Custom fetch implementation (e.g. for proxies/tests). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Enable the persistent local cache (Node file / browser CacheStorage). Default `true`. */
+    cache?: boolean;
+    /** Cache freshness window in milliseconds. Default 24h. */
+    cacheTtlMs?: number;
+    /** Node only: directory for the cache file. Defaults to an OS temp subdir. */
+    cacheDir?: string;
+    /** Re-fetch even if already loaded / cached. Default `false`. */
+    force?: boolean;
+}
+/**
+ * Fetch, cache, and parse the PSL trie. Idempotent: a second call is a no-op
+ * unless `force` is set. Must be awaited before {@link lookup} and friends.
+ *
+ * @throws if the data cannot be fetched or is implausibly small / corrupt.
+ *
+ * @example
+ * ```ts
+ * import { load, registrableDomain } from '@structured-world/structured-public-domains/tiny';
+ * await load();
+ * registrableDomain('sub.example.co.uk'); // "example.co.uk"
+ * ```
+ */
+declare function load(opts?: LoadOptions): Promise<void>;
+/** Whether {@link load} has completed and the lookup API is ready. */
+declare function isLoaded(): boolean;
+/** Look up a domain. Requires a prior `await load()`. See the main entry's `lookup`. */
+declare function lookup(domain: string): DomainInfo | undefined;
+/** Extract the registrable domain (eTLD+1). Requires a prior `await load()`. */
+declare function registrableDomain(domain: string): string | undefined;
+/** Whether a domain's suffix is a known PSL entry. Requires a prior `await load()`. */
+declare function isKnownSuffix(domain: string): boolean;
+/** The raw binary trie blob that was loaded (defensive copy). Requires a prior `await load()`. */
+declare function pslData(): Uint8Array;
+
+export { DEFAULT_PSL_URL, DomainInfo, type LoadOptions, isKnownSuffix, isLoaded, load, lookup, pslData, registrableDomain };

package/dist/tiny.d.ts

@@ -0,0 +1,45 @@
+import { D as DomainInfo } from './trie-jGeN4GI6.js';
+
+/** Default data source: the prebuilt trie served from this package via jsDelivr's CDN. */
+declare const DEFAULT_PSL_URL: string;
+/** Options for {@link load}. */
+interface LoadOptions {
+    /** Where to fetch `psl.bin` from. Defaults to {@link DEFAULT_PSL_URL}. */
+    url?: string;
+    /** Custom fetch implementation (e.g. for proxies/tests). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Enable the persistent local cache (Node file / browser CacheStorage). Default `true`. */
+    cache?: boolean;
+    /** Cache freshness window in milliseconds. Default 24h. */
+    cacheTtlMs?: number;
+    /** Node only: directory for the cache file. Defaults to an OS temp subdir. */
+    cacheDir?: string;
+    /** Re-fetch even if already loaded / cached. Default `false`. */
+    force?: boolean;
+}
+/**
+ * Fetch, cache, and parse the PSL trie. Idempotent: a second call is a no-op
+ * unless `force` is set. Must be awaited before {@link lookup} and friends.
+ *
+ * @throws if the data cannot be fetched or is implausibly small / corrupt.
+ *
+ * @example
+ * ```ts
+ * import { load, registrableDomain } from '@structured-world/structured-public-domains/tiny';
+ * await load();
+ * registrableDomain('sub.example.co.uk'); // "example.co.uk"
+ * ```
+ */
+declare function load(opts?: LoadOptions): Promise<void>;
+/** Whether {@link load} has completed and the lookup API is ready. */
+declare function isLoaded(): boolean;
+/** Look up a domain. Requires a prior `await load()`. See the main entry's `lookup`. */
+declare function lookup(domain: string): DomainInfo | undefined;
+/** Extract the registrable domain (eTLD+1). Requires a prior `await load()`. */
+declare function registrableDomain(domain: string): string | undefined;
+/** Whether a domain's suffix is a known PSL entry. Requires a prior `await load()`. */
+declare function isKnownSuffix(domain: string): boolean;
+/** The raw binary trie blob that was loaded (defensive copy). Requires a prior `await load()`. */
+declare function pslData(): Uint8Array;
+
+export { DEFAULT_PSL_URL, DomainInfo, type LoadOptions, isKnownSuffix, isLoaded, load, lookup, pslData, registrableDomain };

package/dist/tiny.js

@@ -0,0 +1,167 @@
+import { parseTrie, lookupTrie } from './chunk-EON4VJGA.js';
+
+// src/tiny.ts
+var PSL_RANGE = "0.0" ;
+var DEFAULT_PSL_URL = `https://cdn.jsdelivr.net/npm/@structured-world/structured-public-domains@${PSL_RANGE}/dist/psl.bin`;
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+var isNode = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+var cachedBytes;
+var cachedTrie;
+var inFlight;
+var latestGen = 0;
+var latestSettled;
+function load(opts = {}) {
+  if (cachedTrie !== void 0 && opts.force !== true) return Promise.resolve();
+  if (inFlight !== void 0 && opts.force !== true) return inFlight;
+  const gen = ++latestGen;
+  const pending = doLoad(opts, gen);
+  latestSettled = pending;
+  inFlight = pending;
+  pending.finally(() => {
+    if (inFlight === pending) inFlight = void 0;
+  }).catch(() => void 0);
+  return pending;
+}
+function mirrorLatest() {
+  return latestSettled ?? Promise.resolve();
+}
+async function doLoad(opts, gen) {
+  let data;
+  let trie;
+  try {
+    [data, trie] = await fetchAndParse(opts);
+  } catch (err) {
+    if (gen !== latestGen) return mirrorLatest();
+    throw err;
+  }
+  if (gen !== latestGen) return mirrorLatest();
+  cachedBytes = data;
+  cachedTrie = trie;
+}
+async function fetchAndParse(opts) {
+  const url = opts.url ?? DEFAULT_PSL_URL;
+  const ttlMs = opts.cacheTtlMs ?? DEFAULT_TTL_MS;
+  const useCache = opts.cache ?? true;
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  if (useCache && opts.force !== true) {
+    const cached = await readCache(url, ttlMs, opts.cacheDir);
+    if (cached !== void 0) {
+      try {
+        return [cached, parseTrie(cached)];
+      } catch {
+        await deleteCache(url, opts.cacheDir).catch(() => void 0);
+      }
+    }
+  }
+  if (typeof doFetch !== "function") {
+    throw new Error("no fetch implementation available; pass `fetch` in LoadOptions");
+  }
+  const data = await fetchBytes(doFetch, url);
+  const trie = parseTrie(data);
+  if (useCache) await writeCache(url, data, opts.cacheDir).catch(() => void 0);
+  return [data, trie];
+}
+function isLoaded() {
+  return cachedTrie !== void 0;
+}
+function requireTrie() {
+  if (cachedTrie === void 0) {
+    throw new Error("PSL data not loaded \u2014 call `await load()` before lookups");
+  }
+  return cachedTrie;
+}
+function lookup(domain) {
+  return lookupTrie(requireTrie(), domain);
+}
+function registrableDomain(domain) {
+  return lookup(domain)?.registrableDomain;
+}
+function isKnownSuffix(domain) {
+  return lookup(domain)?.known ?? false;
+}
+function pslData() {
+  if (cachedBytes === void 0) {
+    throw new Error("PSL data not loaded \u2014 call `await load()` before pslData()");
+  }
+  return cachedBytes.slice();
+}
+async function fetchBytes(doFetch, url) {
+  const res = await doFetch(url);
+  if (!res.ok) {
+    throw new Error(`failed to fetch PSL data from ${url}: ${res.status} ${res.statusText}`);
+  }
+  const data = new Uint8Array(await res.arrayBuffer());
+  if (data.length < 1024) {
+    throw new Error(`PSL data from ${url} is implausibly small (${data.length} bytes)`);
+  }
+  return data;
+}
+function cacheKey(url) {
+  let h = 2166136261;
+  for (let i = 0; i < url.length; i++) {
+    h ^= url.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+async function readCache(url, ttlMs, cacheDir) {
+  try {
+    return isNode ? await readNodeCache(url, ttlMs, cacheDir) : await readBrowserCache(url, ttlMs);
+  } catch {
+    return void 0;
+  }
+}
+async function writeCache(url, data, cacheDir) {
+  if (isNode) await writeNodeCache(url, data, cacheDir);
+  else await writeBrowserCache(url, data);
+}
+async function deleteCache(url, cacheDir) {
+  if (isNode) {
+    const { fs, file } = await nodeCache(url, cacheDir);
+    fs.rmSync(file, { force: true });
+  } else if (typeof caches !== "undefined") {
+    const cache = await caches.open("structured-public-domains");
+    await cache.delete(url);
+  }
+}
+var nodeRequire = (m) => import(
+  /* @vite-ignore */
+  m
+);
+async function nodeCache(url, cacheDir) {
+  const fs = await nodeRequire("node:fs");
+  const os = await nodeRequire("node:os");
+  const path = await nodeRequire("node:path");
+  const dir = cacheDir ?? path.join(os.tmpdir(), "structured-public-domains-cache");
+  return { fs, dir, file: path.join(dir, `psl-${cacheKey(url)}.bin`) };
+}
+async function readNodeCache(url, ttlMs, cacheDir) {
+  const { fs, file } = await nodeCache(url, cacheDir);
+  const stat = fs.statSync(file);
+  if (Date.now() - stat.mtimeMs >= ttlMs) return void 0;
+  return new Uint8Array(fs.readFileSync(file));
+}
+async function writeNodeCache(url, data, cacheDir) {
+  const { fs, dir, file } = await nodeCache(url, cacheDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+async function readBrowserCache(url, ttlMs) {
+  if (typeof caches === "undefined") return void 0;
+  const cache = await caches.open("structured-public-domains");
+  const res = await cache.match(url);
+  if (res == null) return void 0;
+  const cachedAt = Number(res.headers.get("x-cached-at") ?? "0");
+  if (!Number.isFinite(cachedAt) || Date.now() - cachedAt >= ttlMs) return void 0;
+  return new Uint8Array(await res.arrayBuffer());
+}
+async function writeBrowserCache(url, data) {
+  if (typeof caches === "undefined") return;
+  const cache = await caches.open("structured-public-domains");
+  const body = data.slice();
+  await cache.put(url, new Response(body, { headers: { "x-cached-at": String(Date.now()) } }));
+}
+
+export { DEFAULT_PSL_URL, isKnownSuffix, isLoaded, load, lookup, pslData, registrableDomain };

package/dist/trie-jGeN4GI6.d.cts

@@ -0,0 +1,11 @@
+/** Result of a PSL lookup. */
+interface DomainInfo {
+    /** The public suffix (e.g. `"co.uk"`, `"com"`, `"github.io"`). */
+    readonly suffix: string;
+    /** The registrable domain (eTLD+1), or `undefined` if the input is itself a suffix. */
+    readonly registrableDomain: string | undefined;
+    /** Whether the suffix matched an explicit PSL rule (vs the `*` fallback). */
+    readonly known: boolean;
+}
+
+export type { DomainInfo as D };

package/dist/trie-jGeN4GI6.d.ts

@@ -0,0 +1,11 @@
+/** Result of a PSL lookup. */
+interface DomainInfo {
+    /** The public suffix (e.g. `"co.uk"`, `"com"`, `"github.io"`). */
+    readonly suffix: string;
+    /** The registrable domain (eTLD+1), or `undefined` if the input is itself a suffix. */
+    readonly registrableDomain: string | undefined;
+    /** Whether the suffix matched an explicit PSL rule (vs the `*` fallback). */
+    readonly known: boolean;
+}
+
+export type { DomainInfo as D };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-world/structured-public-domains",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Compact Public Suffix List (PSL) as a native TypeScript package: embedded ~108KB binary trie, synchronous zero-dependency lookups, ESM + CommonJS. Checked daily against publicsuffix.org.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,7 +31,18 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
-    }
+    },
+    "./tiny": {
+      "import": {
+        "types": "./dist/tiny.d.ts",
+        "default": "./dist/tiny.js"
+      },
+      "require": {
+        "types": "./dist/tiny.d.cts",
+        "default": "./dist/tiny.cjs"
+      }
+    },
+    "./psl.bin": "./dist/psl.bin"
   },
   "sideEffects": false,
   "files": [
@@ -46,7 +57,7 @@
   },
   "scripts": {
     "gen:data": "node scripts/gen-data.mjs",
-    "build": "npm run gen:data && tsup && node -e \"const fs=require('fs');fs.copyFileSync('src/psl-data.cjs','dist/psl-data.cjs');fs.copyFileSync('../README.md','README.md')\"",
+    "build": "npm run gen:data && tsup && node -e \"const fs=require('fs');fs.copyFileSync('src/psl-data.cjs','dist/psl-data.cjs');fs.copyFileSync('../src/psl.bin','dist/psl.bin');fs.copyFileSync('../README.md','README.md')\"",
     "test": "npm run gen:data && vitest run",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"