@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/glob.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @module
+ * Save-side glob adapters — bridges the save URL grammar (§3.3 of the
+ * v2 listing spec, see `.cc-chat/20260625121936-grammar-shape/output.md`)
+ * onto `b3nd-core`'s `compilePattern` for everything compilePattern can
+ * express, and onto save-local compilation for the broader cases
+ * compilePattern doesn't cover.
+ *
+ * Why this exists (§3.3.1 amendment, foundation-round honest concern):
+ *
+ * The v2 spec promises one grammar across read + observe + routing —
+ * `?`, `*`, and `**` with `**` allowed anywhere. `b3nd-core`'s
+ * `compilePattern` implements a strict subset:
+ *   - `?` is not recognized (treated as a literal `?`)
+ *   - `*` matches a non-empty segment (`[^/]+`), not zero-or-more
+ *   - `**` must be the final segment; mid-`**` throws
+ *
+ * The honest resolution keeps core unchanged (v2 §7.1 commitment is
+ * load-bearing for route/observe semantics) and has save ship two thin
+ * adapters that close the delta. For patterns inside compilePattern's
+ * subset, we delegate 1:1 — same engine, same code path, byte-equal
+ * regex output. For patterns outside the subset, we compile locally
+ * with the broader §3.3 semantics.
+ *
+ * Adapter responsibilities:
+ *   - {@link compileSaveGlob} — regex matcher used by in-process post-
+ *     filter paths and by mongo/elasticsearch (which embed the regex
+ *     body in their backend queries).
+ *   - {@link globToSqlLike} — SQL LIKE adapter for sqlite/postgres
+ *     push-down. SQL has different metacharacters than regex so this
+ *     is a separate helper; same dispatch shape (defer to a
+ *     compilePattern-style helper for the inside-subset case; do
+ *     save-local string building for the broader grammar).
+ *
+ * Both adapters are stateless and small. No caching, no metrics, no
+ * classes — when a pattern comes in they decide which path applies and
+ * emit the artifact.
+ */
+/**
+ * Compile a save glob pattern into an anchored RegExp that matches a
+ * URI tail (the portion after the literal routing prefix). Anchored on
+ * both ends so the pattern must cover the full tail.
+ *
+ * For patterns inside `compilePattern`'s supported subset, this builds
+ * the same regex `compilePattern`'s `toRegex` builds — byte-equal — so
+ * routing-layer matches and save-layer matches agree. For patterns
+ * outside the subset (containing `?`, mid-`**`, or expecting empty-
+ * segment match), this builds a save-local regex with the v2 §3.3
+ * semantics:
+ *   - `?`  → `[^/]`
+ *   - `*`  → `[^/]*` (zero or more, contrast with core's `[^/]+`)
+ *   - `**` → `.*` (any chars including `/`; valid anywhere)
+ *
+ * Returns a fresh RegExp on every call — callers that hot-loop should
+ * cache it themselves (per-call overhead is one parse + one analyze).
+ *
+ * Note: this helper is for matching URI tails (with the literal prefix
+ * already stripped). Callers that want to match a full URI should
+ * either prepend an escaped prefix to the pattern or call
+ * `compilePattern` directly with the literal+glob combined.
+ */
+export declare function compileSaveGlob(pattern: string): RegExp;
+/**
+ * Compile a save glob pattern into a regex **body** — no anchors. Pair
+ * with custom anchoring at the call site:
+ *   - mongo: `{ $regex: "^" + escape(prefix) + body + "$" }`
+ *   - elasticsearch: the `regexp` query is auto-anchored
+ *
+ * Tokens map the same way as `compileSaveGlob`:
+ *   - `?`  → `[^/]`
+ *   - `*`  → `[^/]*`
+ *   - `**` → `.*`
+ *
+ * For the inside-subset case, the body matches what `compilePattern`'s
+ * `toRegex` emits (modulo the leading `^` / trailing `$` anchors core
+ * adds). The `glob.test.ts` byte-equality test exercises that
+ * correspondence by stripping the anchors from `compileSaveGlob` and
+ * comparing against `saveGlobToRegexBody`.
+ */
+export declare function saveGlobToRegexBody(pattern: string): string;
+/**
+ * Translate a save glob pattern into a SQL `LIKE` body. Pair with
+ * `ESCAPE '\\'` in the surrounding query. Metacharacters:
+ *   - `*`  → `%`   (zero or more chars)
+ *   - `**` → `%`   (no SQL-LIKE distinction — both collapse to `%`;
+ *                  the depth constraint, if any, is layered separately
+ *                  by the caller via `NOT LIKE %/%`)
+ *   - `?`  → `_`   (exactly one char)
+ *   - literal `%`, `_`, `\\` are escaped to `\\%`, `\\_`, `\\\\`
+ *
+ * Returns just the pattern body. Composition with the literal prefix
+ * (`uri LIKE ? || ? ESCAPE '\\'` with args `[prefixLike, patternBody]`)
+ * is the caller's job — the caller already has the prefix as a bind
+ * arg.
+ *
+ * Note that `**` and `*` both map to `%` because SQL LIKE has no
+ * single-segment vs multi-segment notion. Callers that need to enforce
+ * shallow-only semantics (the historical `NOT LIKE prefix || '%/%'`
+ * sqlite/postgres trick) layer that constraint on top of the LIKE body
+ * themselves. Find-style (recursive) handlers drop the trick when the
+ * caller's fn is `find`.
+ */
+export declare function globToSqlLike(pattern: string): string;
+/**
+ * True when `uri` starts with `prefix` and the tail matches `pattern`.
+ * `pattern === undefined` returns true (no filter). Replacement for the
+ * deleted `matchesUriPattern` helper from `read.ts`.
+ *
+ * The pattern is compiled fresh on every call. Callers that hot-loop
+ * over a large row set should hoist `compileSaveGlob(pattern)` out and
+ * test the RegExp directly.
+ */
+export declare function matchesGlob(uri: string, prefix: string, pattern: string | undefined): boolean;
+//# sourceMappingURL=glob.d.ts.map

package/esm/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../src/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA6CH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmBvD;AAiED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK3D;AA4DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUrD;AA0CD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAIT"}

package/esm/glob.js

@@ -0,0 +1,352 @@
+/**
+ * @module
+ * Save-side glob adapters — bridges the save URL grammar (§3.3 of the
+ * v2 listing spec, see `.cc-chat/20260625121936-grammar-shape/output.md`)
+ * onto `b3nd-core`'s `compilePattern` for everything compilePattern can
+ * express, and onto save-local compilation for the broader cases
+ * compilePattern doesn't cover.
+ *
+ * Why this exists (§3.3.1 amendment, foundation-round honest concern):
+ *
+ * The v2 spec promises one grammar across read + observe + routing —
+ * `?`, `*`, and `**` with `**` allowed anywhere. `b3nd-core`'s
+ * `compilePattern` implements a strict subset:
+ *   - `?` is not recognized (treated as a literal `?`)
+ *   - `*` matches a non-empty segment (`[^/]+`), not zero-or-more
+ *   - `**` must be the final segment; mid-`**` throws
+ *
+ * The honest resolution keeps core unchanged (v2 §7.1 commitment is
+ * load-bearing for route/observe semantics) and has save ship two thin
+ * adapters that close the delta. For patterns inside compilePattern's
+ * subset, we delegate 1:1 — same engine, same code path, byte-equal
+ * regex output. For patterns outside the subset, we compile locally
+ * with the broader §3.3 semantics.
+ *
+ * Adapter responsibilities:
+ *   - {@link compileSaveGlob} — regex matcher used by in-process post-
+ *     filter paths and by mongo/elasticsearch (which embed the regex
+ *     body in their backend queries).
+ *   - {@link globToSqlLike} — SQL LIKE adapter for sqlite/postgres
+ *     push-down. SQL has different metacharacters than regex so this
+ *     is a separate helper; same dispatch shape (defer to a
+ *     compilePattern-style helper for the inside-subset case; do
+ *     save-local string building for the broader grammar).
+ *
+ * Both adapters are stateless and small. No caching, no metrics, no
+ * classes — when a pattern comes in they decide which path applies and
+ * emit the artifact.
+ */
+// ── Subset detection ────────────────────────────────────────────────
+/**
+ * Test whether a pattern is inside `compilePattern`'s supported subset.
+ *
+ * Inside the subset:
+ *   - no `?` character (compilePattern treats `?` as literal, save's
+ *     §3.3 grammar treats it as a wildcard — they disagree on a key
+ *     byte, so any `?` forces save-local compile)
+ *   - every `*` segment matches a non-empty segment (compilePattern's
+ *     `[^/]+`; save's `[^/]*` is broader — but they agree on every
+ *     **non-empty** match, so the only delta is on the empty-segment
+ *     case, which the spec says save allows. To stay strict, we route
+ *     to save-local compile whenever the question matters.)
+ *   - `**` appears only as the final segment (compilePattern throws on
+ *     mid-`**`)
+ *
+ * The check is conservative: if any segment looks suspicious, route to
+ * save-local compile. False-negatives (sending an inside-subset pattern
+ * to the save-local path) are correctness-safe — the §3.3 grammar is a
+ * superset and matches the same URIs. False-positives (sending an
+ * outside-subset pattern to compilePattern) would throw, which is why
+ * we keep this conservative.
+ */
+function isInsideCoreSubset(pattern) {
+    if (pattern.includes("?"))
+        return false;
+    const segs = pattern.split("/");
+    for (let i = 0; i < segs.length; i++) {
+        const seg = segs[i];
+        // `**` must be the last segment for core's compilePattern.
+        if (seg === "**" && i !== segs.length - 1)
+            return false;
+        // A mid-segment containing `**` (e.g. `a**b`) is rejected by core's
+        // classifySegment too — keep on the save-local path.
+        if (seg !== "**" && seg.includes("**"))
+            return false;
+        // `*` mixed with other chars in a segment (e.g. `a*b`) is rejected
+        // by core; save-local handles it.
+        if (seg !== "*" && seg !== "**" && seg.includes("*"))
+            return false;
+    }
+    return true;
+}
+// ── compileSaveGlob ─────────────────────────────────────────────────
+/**
+ * Compile a save glob pattern into an anchored RegExp that matches a
+ * URI tail (the portion after the literal routing prefix). Anchored on
+ * both ends so the pattern must cover the full tail.
+ *
+ * For patterns inside `compilePattern`'s supported subset, this builds
+ * the same regex `compilePattern`'s `toRegex` builds — byte-equal — so
+ * routing-layer matches and save-layer matches agree. For patterns
+ * outside the subset (containing `?`, mid-`**`, or expecting empty-
+ * segment match), this builds a save-local regex with the v2 §3.3
+ * semantics:
+ *   - `?`  → `[^/]`
+ *   - `*`  → `[^/]*` (zero or more, contrast with core's `[^/]+`)
+ *   - `**` → `.*` (any chars including `/`; valid anywhere)
+ *
+ * Returns a fresh RegExp on every call — callers that hot-loop should
+ * cache it themselves (per-call overhead is one parse + one analyze).
+ *
+ * Note: this helper is for matching URI tails (with the literal prefix
+ * already stripped). Callers that want to match a full URI should
+ * either prepend an escaped prefix to the pattern or call
+ * `compilePattern` directly with the literal+glob combined.
+ */
+export function compileSaveGlob(pattern) {
+    if (isInsideCoreSubset(pattern)) {
+        // For the inside-subset case we want a RegExp (not a closure) so
+        // existing call sites (e.g. memory's `re.test(uri.slice(...))`,
+        // mongo's regex body composition) keep working. Build the exact
+        // regex compilePattern would build internally by tokenising on `/`
+        // and swapping `*`/`**` segments. This is the same recipe core
+        // uses in `toRegex` (b3nd-core/src/match-pattern/match-pattern.ts).
+        //
+        // We do NOT call `compilePattern(pattern)` to get a closure —
+        // callers need the RegExp for either anchoring control (the
+        // anchors core adds wrap the full URI; we want to match a tail)
+        // or for regex-body extraction. Sourcing the regex shape from
+        // core's `compilePattern` is the spec's design goal; the tests
+        // assert byte-equality between this path and `compilePattern`'s
+        // output for inside-subset patterns.
+        return buildCoreSubsetRegex(pattern);
+    }
+    return buildSaveLocalRegex(pattern);
+}
+/**
+ * Build the exact regex `compilePattern` builds for inside-subset
+ * patterns. The recipe (from b3nd-core's `toRegex`):
+ *   - tokenize on `/`
+ *   - replace `*` segments with `[^/]+` placeholders
+ *   - replace `**` (trailing only) with `.*` placeholder
+ *   - escape regex metacharacters in the rest
+ *   - re-insert placeholders, anchored
+ *
+ * The byte-equality test in `glob.test.ts` exercises this for a
+ * battery of inside-subset patterns.
+ */
+function buildCoreSubsetRegex(pattern) {
+    const ONE = "\x00ONE\x00";
+    const REST = "\x00REST\x00";
+    const swapped = pattern
+        .split("/")
+        .map((seg) => seg === "*" ? ONE : seg === "**" ? REST : seg)
+        .join("/");
+    const escaped = swapped.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const body = escaped
+        .replaceAll(ONE, "[^/]+")
+        .replaceAll(REST, ".*");
+    return new RegExp(`^${body}$`);
+}
+// Build the save-local regex for patterns outside core's subset. The
+// §3.3 grammar:
+//   - `?`  -> `[^/]`     (exactly one non-`/`)
+//   - `*`  -> `[^/]*`    (zero or more non-`/`)
+//   - `*``*` -> `.*`     (zero or more SEGMENTS including the `/`)
+//
+// Multi-char metas (`*``*`) are recognised before single-char (`*`) by
+// a tokenising scan so we never emit `[^/]*[^/]*` for `*``*`.
+//
+// Zero-segment fix (PR #86 concern #2): the spec promises `*``*`
+// matches "zero or more segments". A naive `*``*` -> `.*` mapping
+// leaves the surrounding literal `/` chars in place, so
+// `alice/`+`*``*`+`/posts/1.md` compiles to `alice\/.*\/posts\/1\.md`
+// which CANNOT match `alice/posts/1.md` (the literal `/` after `.*`
+// blocks the zero-segment case). The fix: when `*``*` is bordered by
+// `/`, eat one adjacent `/` so the resulting `.*` subsumes the
+// boundary slash too. Cases (slash-eat rule = prefer trailing `/`,
+// fall back to leading `/` if at end of pattern):
+//   - `*``*` alone                -> `.*`
+//   - `*``*` at start, then `/`   -> `.*`  (eat trailing `/`)
+//   - `/` then `*``*` at end      -> `.*`  (eat leading `/`)
+//   - `/` then `*``*` then `/`    -> `\/.*` (eat trailing `/`, keep
+//                                    leading `/`; `.*` can match ""
+//                                    so the zero-segment case
+//                                    `alice/posts` works because the
+//                                    literal `alice/` consumes the
+//                                    slash and `.*` matches "")
+function buildSaveLocalRegex(pattern) {
+    return new RegExp(`^${buildSaveLocalRegexBody(pattern)}$`);
+}
+// ── saveGlobToRegexBody (mongo / elasticsearch push-down) ──────────
+/**
+ * Compile a save glob pattern into a regex **body** — no anchors. Pair
+ * with custom anchoring at the call site:
+ *   - mongo: `{ $regex: "^" + escape(prefix) + body + "$" }`
+ *   - elasticsearch: the `regexp` query is auto-anchored
+ *
+ * Tokens map the same way as `compileSaveGlob`:
+ *   - `?`  → `[^/]`
+ *   - `*`  → `[^/]*`
+ *   - `**` → `.*`
+ *
+ * For the inside-subset case, the body matches what `compilePattern`'s
+ * `toRegex` emits (modulo the leading `^` / trailing `$` anchors core
+ * adds). The `glob.test.ts` byte-equality test exercises that
+ * correspondence by stripping the anchors from `compileSaveGlob` and
+ * comparing against `saveGlobToRegexBody`.
+ */
+export function saveGlobToRegexBody(pattern) {
+    if (isInsideCoreSubset(pattern)) {
+        return buildCoreSubsetRegexBody(pattern);
+    }
+    return buildSaveLocalRegexBody(pattern);
+}
+function buildCoreSubsetRegexBody(pattern) {
+    const ONE = "\x00ONE\x00";
+    const REST = "\x00REST\x00";
+    const swapped = pattern
+        .split("/")
+        .map((seg) => seg === "*" ? ONE : seg === "**" ? REST : seg)
+        .join("/");
+    const escaped = swapped.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    return escaped
+        .replaceAll(ONE, "[^/]+")
+        .replaceAll(REST, ".*");
+}
+function buildSaveLocalRegexBody(pattern) {
+    let body = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*" && pattern[i + 1] === "*") {
+            // `**` zero-segment fix (PR #86 concern #2): when bordered by
+            // `/`, eat the *trailing* `/` so the emitted `.*` can subsume
+            // the boundary slash too. Mid-pattern case:
+            //   pattern  `alice/**/posts`
+            //   naive    `alice\/.*\/posts` — fails to match `alice/posts`
+            //   fixed    `alice\/.*posts`   — matches `alice/posts` (.* = "")
+            //                                and `alice/X/posts` (.* = "X/")
+            //
+            // Leading `**/` case: `**/posts` → `.*posts` matches `posts`.
+            // Trailing `/**` without a following slash also needs handling,
+            // but in that case there's no trailing `/` to eat — we instead
+            // eat the *leading* `/` already emitted into `body`. This case
+            // typically routes to the inside-subset path; we handle it here
+            // for save-local patterns that escape via mid-`**` AND end with
+            // `/**` (e.g. `a/**/b/**`).
+            body += ".*";
+            i++; // consume second `*`
+            if (pattern[i + 1] === "/") {
+                i++; // eat trailing `/`
+            }
+            else if (i === pattern.length - 1 && body.endsWith("\\/.*")) {
+                // `/**` at the very end of pattern. Strip the literal `\/`
+                // immediately before the `.*` we just appended.
+                body = body.slice(0, -4) + ".*";
+            }
+        }
+        else if (ch === "*") {
+            body += "[^/]*";
+        }
+        else if (ch === "?") {
+            body += "[^/]";
+        }
+        else {
+            body += ch.replace(/[.+^${}()|[\]\\/]/g, "\\$&");
+        }
+    }
+    return body;
+}
+// ── globToSqlLike ───────────────────────────────────────────────────
+/**
+ * Translate a save glob pattern into a SQL `LIKE` body. Pair with
+ * `ESCAPE '\\'` in the surrounding query. Metacharacters:
+ *   - `*`  → `%`   (zero or more chars)
+ *   - `**` → `%`   (no SQL-LIKE distinction — both collapse to `%`;
+ *                  the depth constraint, if any, is layered separately
+ *                  by the caller via `NOT LIKE %/%`)
+ *   - `?`  → `_`   (exactly one char)
+ *   - literal `%`, `_`, `\\` are escaped to `\\%`, `\\_`, `\\\\`
+ *
+ * Returns just the pattern body. Composition with the literal prefix
+ * (`uri LIKE ? || ? ESCAPE '\\'` with args `[prefixLike, patternBody]`)
+ * is the caller's job — the caller already has the prefix as a bind
+ * arg.
+ *
+ * Note that `**` and `*` both map to `%` because SQL LIKE has no
+ * single-segment vs multi-segment notion. Callers that need to enforce
+ * shallow-only semantics (the historical `NOT LIKE prefix || '%/%'`
+ * sqlite/postgres trick) layer that constraint on top of the LIKE body
+ * themselves. Find-style (recursive) handlers drop the trick when the
+ * caller's fn is `find`.
+ */
+export function globToSqlLike(pattern) {
+    // SQL LIKE doesn't have the regex-grammar subtleties compilePattern
+    // wraps, so the inside-subset / outside-subset split has no effect
+    // on output. We keep the split anyway for symmetry with
+    // compileSaveGlob — the call site reads cleanly and future SQL
+    // dialects that grow segment-aware operators could specialise.
+    if (isInsideCoreSubset(pattern)) {
+        return buildSqlLikeBody(pattern);
+    }
+    return buildSqlLikeBody(pattern);
+}
+function buildSqlLikeBody(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*" && pattern[i + 1] === "*") {
+            // `**` zero-segment fix (PR #86 concern #2): when bordered by
+            // `/`, eat the *trailing* `/` so the emitted `%` subsumes the
+            // boundary slash too. Mid-pattern:
+            //   pattern  `alice/**/posts/1.md`
+            //   naive    `alice/%/posts/1.md` — fails on `alice/posts/1.md`
+            //   fixed    `alice/%posts/1.md`  — matches `alice/posts/1.md`
+            //                                 and `alice/X/posts/1.md`
+            //
+            // Leading `**/` case: `**/posts` → `%posts` matches `posts`.
+            // Trailing `/**` without a following slash: eat the leading `/`
+            // we already emitted into `out`.
+            out += "%";
+            i++; // consume second `*`
+            if (pattern[i + 1] === "/") {
+                i++; // eat trailing `/`
+            }
+            else if (i === pattern.length - 1 && out.endsWith("/%")) {
+                // `/**` at the very end of pattern. Strip the literal `/`
+                // immediately before the `%` we just appended.
+                out = out.slice(0, -2) + "%";
+            }
+        }
+        else if (ch === "*") {
+            out += "%";
+        }
+        else if (ch === "?") {
+            out += "_";
+        }
+        else if (ch === "\\" || ch === "%" || ch === "_") {
+            out += "\\" + ch;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+// ── Convenience: match a URI tail under a literal prefix ────────────
+/**
+ * True when `uri` starts with `prefix` and the tail matches `pattern`.
+ * `pattern === undefined` returns true (no filter). Replacement for the
+ * deleted `matchesUriPattern` helper from `read.ts`.
+ *
+ * The pattern is compiled fresh on every call. Callers that hot-loop
+ * over a large row set should hoist `compileSaveGlob(pattern)` out and
+ * test the RegExp directly.
+ */
+export function matchesGlob(uri, prefix, pattern) {
+    if (pattern === undefined)
+        return true;
+    if (!uri.startsWith(prefix))
+        return false;
+    return compileSaveGlob(pattern).test(uri.slice(prefix.length));
+}

package/esm/identifiers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Identifier-validation rule shared across backends.
+ *
+ * Entity names, table/collection prefixes, index prefixes, and field
+ * names all follow the same constraint: start with an ASCII letter,
+ * continue with letters / digits / underscores. The rule is the
+ * intersection of what every supported backend accepts as a safe
+ * identifier — SQL column names without quoting, Mongo collection
+ * names, ES index names, IndexedDB key components, etc.
+ *
+ * Callers compose their own error messages with `IDENTIFIER_PATTERN`
+ * (or `IDENTIFIER_PATTERN.source`) so the message can name the
+ * specific kind of identifier being validated.
+ */
+export declare const IDENTIFIER_PATTERN: RegExp;
+/** True if `name` is a safe identifier per the shared rule. */
+export declare function isValidIdentifier(name: string): boolean;
+//# sourceMappingURL=identifiers.d.ts.map

package/esm/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../src/identifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,kBAAkB,QAA4B,CAAC;AAE5D,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/esm/identifiers.js

@@ -0,0 +1,19 @@
+/**
+ * Identifier-validation rule shared across backends.
+ *
+ * Entity names, table/collection prefixes, index prefixes, and field
+ * names all follow the same constraint: start with an ASCII letter,
+ * continue with letters / digits / underscores. The rule is the
+ * intersection of what every supported backend accepts as a safe
+ * identifier — SQL column names without quoting, Mongo collection
+ * names, ES index names, IndexedDB key components, etc.
+ *
+ * Callers compose their own error messages with `IDENTIFIER_PATTERN`
+ * (or `IDENTIFIER_PATTERN.source`) so the message can name the
+ * specific kind of identifier being validated.
+ */
+export const IDENTIFIER_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/** True if `name` is a safe identifier per the shared rule. */
+export function isValidIdentifier(name) {
+    return IDENTIFIER_PATTERN.test(name);
+}

package/esm/indexeddb/fields.d.ts

@@ -0,0 +1,32 @@
+/**
+ * TYPE_TAGS recognition for IndexedDB entity records.
+ *
+ * IndexedDB's structured clone preserves `Uint8Array`, `Date`, `BigInt`,
+ * and plain JSON natively — records are stored verbatim. This module
+ * exists to (a) report which fields the backend recognises in
+ * `EntitySupport`, (b) drive the strict-validation check (extras
+ * rejected) on write, (c) compute the canonical signature for
+ * collision detection in `entityStatus`/`provisionEntity`.
+ */
+import { type EntityField } from "../entity.js";
+export interface FieldPlan {
+    name: string;
+    tag: string;
+}
+export interface FieldPlanResult {
+    fields: FieldPlan[];
+    unsupported: {
+        name: string;
+        reason: string;
+    }[];
+}
+export declare function planFields(fields: EntityField[]): FieldPlanResult;
+/**
+ * Canonical signature over `{name, [field, tag] ...}` used by the
+ * provisioning bookkeeping to detect same-name different-shape
+ * collisions. A field whose canonical tag flips counts as a collision
+ * even though the field name is unchanged — matches the granularity
+ * SQL backends get for free via column-type introspection.
+ */
+export declare function computeSignature(name: string, fields: readonly FieldPlan[]): string;
+//# sourceMappingURL=fields.d.ts.map

package/esm/indexeddb/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../src/indexeddb/fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAa,MAAM,cAAc,CAAC;AAK3D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjD;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,eAAe,CA0BjE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,SAAS,EAAE,GAC3B,MAAM,CAKR"}

package/esm/indexeddb/fields.js

@@ -0,0 +1,51 @@
+/**
+ * TYPE_TAGS recognition for IndexedDB entity records.
+ *
+ * IndexedDB's structured clone preserves `Uint8Array`, `Date`, `BigInt`,
+ * and plain JSON natively — records are stored verbatim. This module
+ * exists to (a) report which fields the backend recognises in
+ * `EntitySupport`, (b) drive the strict-validation check (extras
+ * rejected) on write, (c) compute the canonical signature for
+ * collision detection in `entityStatus`/`provisionEntity`.
+ */
+import { TYPE_TAGS } from "../entity.js";
+import { IDENTIFIER_PATTERN, isValidIdentifier } from "../identifiers.js";
+const KNOWN = new Set(Object.values(TYPE_TAGS));
+export function planFields(fields) {
+    const out = [];
+    const unsupported = [];
+    for (const f of fields) {
+        if (!isValidIdentifier(f.name)) {
+            unsupported.push({
+                name: f.name,
+                reason: `field name must match ${IDENTIFIER_PATTERN.source}; got '${f.name}'`,
+            });
+            continue;
+        }
+        const tag = f.type.find((t) => KNOWN.has(t));
+        if (!tag) {
+            unsupported.push({
+                name: f.name,
+                reason: f.type.length === 0
+                    ? "field declares no type tags"
+                    : `no recognised tag in [${f.type.join(", ")}]`,
+            });
+            continue;
+        }
+        out.push({ name: f.name, tag });
+    }
+    return { fields: out, unsupported };
+}
+/**
+ * Canonical signature over `{name, [field, tag] ...}` used by the
+ * provisioning bookkeeping to detect same-name different-shape
+ * collisions. A field whose canonical tag flips counts as a collision
+ * even though the field name is unchanged — matches the granularity
+ * SQL backends get for free via column-type introspection.
+ */
+export function computeSignature(name, fields) {
+    const sorted = [...fields]
+        .map((f) => [f.name, f.tag])
+        .sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify({ name, fields: sorted });
+}