@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/postgres/store.js

@@ -27,6 +27,27 @@
  * predicate (`uri LIKE prefix% AND uri NOT LIKE prefix%/%`) is
  * enforced in the WHERE clause against the entity's table.
  *
+ * `fn=find` (v2 §3.5) push down to SQL too — same shape minus the
+ * `NOT LIKE %/%` shallow clause. With `pushDownFind: true` dispatch
+ * trusts the backend to combine the URI-embedded glob with pagination,
+ * cursor, and sort inside the query.
+ *
+ * `fn=count` honours deep (`**`) URLs by dropping the shallow clause
+ * when `parsed.glob.includes("**")`. With `pushDownCount: true`,
+ * dispatch routes every count shape — shallow and deep — to the
+ * backend's own `COUNT(*)` (faster than walking-and-counting through
+ * find).
+ *
+ * ## LIKE-injection safety
+ *
+ * Every value spliced into a SQL `LIKE` pattern via concatenation is
+ * pre-escaped with `escapeSqlLike()` (`%` → `\%`, `_` → `\_`,
+ * `\` → `\\`) and the surrounding clauses declare `ESCAPE '\\'`. This
+ * prevents a URI prefix or cursor containing `%` or `_` from matching
+ * siblings (e.g. `store://r/100%/` must NOT match `store://r/100x/...`
+ * under `fn=ls`). The glob body produced by `globToSqlLike` already
+ * encodes its own escaping for literal `%`/`_` in the pattern source.
+ *
  * Writes are wrapped in a transaction (`capabilities.atomicBatch =
  * true`). Stream-shaped values on `BYTEA` columns are collected to
  * `Uint8Array` *before* the transaction opens, so a stream failure
@@ -36,9 +57,10 @@ import { dispatchRead } from "../dispatch.js";
 import { storageFailure } from "../errors.js";
 import { toBytes } from "../payload.js";
 import { validateReadParams } from "../read.js";
+import { globToSqlLike } from "../glob.js";
+import { IDENTIFIER_PATTERN, isValidIdentifier } from "../identifiers.js";
 import { planColumns } from "./columns.js";
 const STORE_NAME = "PostgresStore";
-const TABLE_PREFIX = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 /** Map a `ColumnPlan.sqlType` to the `information_schema.columns.data_type` value. */
 const INFO_SCHEMA_TYPE = {
     TEXT: "text",
@@ -63,9 +85,25 @@ function rowToBytes(value) {
     }
     throw new Error(`${STORE_NAME}: unexpected payload type ${typeof value}`);
 }
+/**
+ * Escape a literal value for inclusion in a SQL `LIKE` pattern. The
+ * surrounding query MUST declare `ESCAPE '\\'` for this to apply. The
+ * three SQL-LIKE metacharacters are escaped:
+ *   - `%` → `\%`
+ *   - `_` → `\_`
+ *   - `\` → `\\` (escape char itself)
+ *
+ * Without this, a URI prefix carrying `%` or `_` would broaden the
+ * LIKE match — e.g. `store://r/100%/` would match every sibling under
+ * `store://r/100x/...` (the `%` would act as wildcard inside the
+ * concatenated pattern `prefix || '%'`).
+ */
+function escapeSqlLike(value) {
+    return value.replace(/[\\%_]/g, "\\$&");
+}
 function entityTableName(tablePrefix, entityName) {
-    if (!TABLE_PREFIX.test(entityName)) {
-        throw new Error(`${STORE_NAME}: entity name '${entityName}' must match ${TABLE_PREFIX.source}`);
+    if (!isValidIdentifier(entityName)) {
+        throw new Error(`${STORE_NAME}: entity name '${entityName}' must match ${IDENTIFIER_PATTERN.source}`);
     }
     return `${tablePrefix}_${entityName}_data`;
 }
@@ -75,8 +113,8 @@ export class PostgresStore {
     constructor(tablePrefix, executor) {
         if (!tablePrefix)
             throw new Error("tablePrefix is required");
-        if (!TABLE_PREFIX.test(tablePrefix)) {
-            throw new Error(`tablePrefix must match ${TABLE_PREFIX.source}; got '${tablePrefix}'`);
+        if (!isValidIdentifier(tablePrefix)) {
+            throw new Error(`tablePrefix must match ${IDENTIFIER_PATTERN.source}; got '${tablePrefix}'`);
         }
         if (!executor)
             throw new Error("executor is required");
@@ -212,6 +250,12 @@ CREATE INDEX IF NOT EXISTS idx_${meta.tableName}_uri ON ${meta.tableName} (uri);
             read: (p) => this._readOne(meta, p.uri),
             ls: (p) => this._ls(meta, p),
             count: (p) => this._count(meta, p),
+            find: (p) => this._find(meta, p),
+            pushDownPattern: true,
+            pushDownCursor: true,
+            pushDownSortBy: true,
+            pushDownFind: true,
+            pushDownCount: true,
         });
     }
     async delete(meta, uris) {
@@ -236,7 +280,7 @@ CREATE INDEX IF NOT EXISTS idx_${meta.tableName}_uri ON ${meta.tableName} (uri);
             return {
                 status: "healthy",
                 message: "PostgreSQL store is operational",
-                fns: ["read", "ls", "count"],
+                fns: ["read", "ls", "find", "count"],
                 details: { tablePrefix: this.tablePrefix },
             };
         }
@@ -244,7 +288,7 @@ CREATE INDEX IF NOT EXISTS idx_${meta.tableName}_uri ON ${meta.tableName} (uri);
             return {
                 status: "unhealthy",
                 message: `PostgreSQL health check failed: ${error instanceof Error ? error.message : String(error)}`,
-                fns: ["read", "ls", "count"],
+                fns: ["read", "ls", "find", "count"],
             };
         }
     }
@@ -265,6 +309,31 @@ CREATE INDEX IF NOT EXISTS idx_${meta.tableName}_uri ON ${meta.tableName} (uri);
         return adaptRowForRead(meta, res.rows[0]);
     }
     async _ls(meta, parsed) {
+        return await this._listQuery(meta, parsed, /*deep*/ false);
+    }
+    /**
+     * `fn=find` handler — deep walk under the prefix. Same query shape as
+     * `_ls` minus the `NOT LIKE prefix || '%/%'` shallow clause: every
+     * descendant URI matches the prefix; the URI-embedded glob (passed in
+     * via `params.pattern` by the parser) tightens the set with a SQL
+     * `LIKE` body. `pushDownFind: true` is declared so dispatch trusts the
+     * backend with pattern + pagination + sort.
+     */
+    async _find(meta, parsed) {
+        return await this._listQuery(meta, parsed, /*deep*/ true);
+    }
+    /**
+     * Shared SELECT for `_ls` and `_find`. The only structural difference
+     * is the shallow clause: `_ls` includes `uri NOT LIKE prefix || '%/%'
+     * ESCAPE '\\'`; `_find` drops it. Everything else — pattern body,
+     * cursor, sort, pagination — is identical.
+     *
+     * LIKE-injection safety: `parsed.uri` is pre-escaped with
+     * `escapeSqlLike()` before being bound. The bind value is the escaped
+     * prefix; the surrounding `LIKE $1 || '%' ESCAPE '\\'` then treats
+     * any `%`/`_` in the original prefix as literals.
+     */
+    async _listQuery(meta, parsed, deep) {
         validateReadParams(parsed.params, STORE_NAME);
         const { params } = parsed;
         const format = params.format ?? "full";
@@ -272,11 +341,43 @@ CREATE INDEX IF NOT EXISTS idx_${meta.tableName}_uri ON ${meta.tableName} (uri);
             ? "uri, " + meta.columns.map((c) => `"${c.name}"`).join(", ")
             : "uri";
         const selectClause = format === "uris" ? "uri" : cols;
-        const order = params.sortBy === "uri"
-            ? ` ORDER BY uri ${params.sortOrder === "desc" ? "DESC" : "ASC"}`
+        // sortBy: "uri" sorts on the implicit URI column; any other value
+        // must be a declared user field, or dispatch will have already
+        // post-sorted and we should not double-sort here (dispatch strips
+        // non-uri sortBy from the handler call unless pushDownSortBy is
+        // true — which it is for this backend).
+        const sortByCol = params.sortBy === "uri"
+            ? "uri"
+            : (params.sortBy !== undefined && meta.declared.has(params.sortBy)
+                ? `"${params.sortBy}"`
+                : "");
+        const order = sortByCol
+            ? ` ORDER BY ${sortByCol} ${params.sortOrder === "desc" ? "DESC" : "ASC"}`
             : "";
-        let sql = `SELECT ${selectClause} FROM ${meta.tableName} WHERE uri LIKE $1 || '%' AND uri NOT LIKE $1 || '%/%'${order}`;
-        const args = [parsed.uri];
+        // `$1` is the escaped prefix; `ESCAPE '\\'` is declared on every
+        // LIKE clause that uses it so embedded `%`/`_` in the URI stay
+        // literal. The shallow `NOT LIKE prefix || '%/%'` clause is dropped
+        // for the find (deep) path. When `pattern` is set we tighten with
+        // an additional `LIKE prefix || patternBody` clause (the body is
+        // produced by `globToSqlLike` and already escapes its own
+        // metacharacters). When `cursor` is set we add `uri > cursor` (or
+        // `<` for desc) — cursor goes into a comparison op, not LIKE, so
+        // no escaping needed there.
+        let sql = `SELECT ${selectClause} FROM ${meta.tableName} WHERE uri LIKE $1 || '%' ESCAPE '\\'`;
+        if (!deep) {
+            sql += ` AND uri NOT LIKE $1 || '%/%' ESCAPE '\\'`;
+        }
+        const args = [escapeSqlLike(parsed.uri)];
+        if (params.pattern !== undefined) {
+            args.push(globToSqlLike(params.pattern));
+            sql += ` AND uri LIKE $1 || $${args.length} ESCAPE '\\'`;
+        }
+        if (params.cursor !== undefined) {
+            args.push(params.cursor);
+            const op = params.sortOrder === "desc" ? "<" : ">";
+            sql += ` AND uri ${op} $${args.length}`;
+        }
+        sql += order;
         if (params.limit !== undefined) {
             const page = params.page ?? 1;
             args.push(params.limit, (page - 1) * params.limit);
@@ -291,11 +392,30 @@ CREATE INDEX IF NOT EXISTS idx_${meta.tableName}_uri ON ${meta.tableName} (uri);
             adaptRowForRead(meta, r),
         ]);
     }
+    /**
+     * `fn=count` handler. Honours both shallow (`*`/`?` or no glob) and
+     * deep (`**`) URL shapes — the latter drops the `NOT LIKE %/%`
+     * predicate so descendants at any depth get counted. With
+     * `pushDownCount: true`, dispatch routes every count call through
+     * here (no walk-then-length fallback).
+     */
     async _count(meta, parsed) {
+        const deep = parsed.glob.includes("**");
+        let sql = `SELECT COUNT(*)::int AS n FROM ${meta.tableName} WHERE uri LIKE $1 || '%' ESCAPE '\\'`;
+        if (!deep) {
+            sql += ` AND uri NOT LIKE $1 || '%/%' ESCAPE '\\'`;
+        }
+        const args = [escapeSqlLike(parsed.uri)];
         if (parsed.params.pattern !== undefined) {
-            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+            args.push(globToSqlLike(parsed.params.pattern));
+            sql += ` AND uri LIKE $1 || $${args.length} ESCAPE '\\'`;
         }
-        const res = await this.executor.query(`SELECT COUNT(*)::int AS n FROM ${meta.tableName} WHERE uri LIKE $1 || '%' AND uri NOT LIKE $1 || '%/%'`, [parsed.uri]);
+        if (parsed.params.cursor !== undefined) {
+            args.push(parsed.params.cursor);
+            const op = parsed.params.sortOrder === "desc" ? "<" : ">";
+            sql += ` AND uri ${op} $${args.length}`;
+        }
+        const res = await this.executor.query(sql, args);
         const row = res.rows?.[0];
         return row?.n ?? 0;
     }

package/esm/read.d.ts

@@ -1,5 +1,5 @@
 /**
- * In-process post-processing for `fn=ls` results.
+ * In-process post-processing for `fn=ls`/`fn=find` results.
  *
  * Stores that cannot push `sortBy`/`limit`/`page`/`format` down to
  * their backend collect the raw `Output[]` rows under a prefix and
@@ -9,8 +9,15 @@
  *
  * Throws on unsupported params — programmer errors are not silent
  * "misses." See project decisions in `project_core_upgrade.md`.
+ *
+ * Glob compilation lives in `./glob.ts` — see `compileSaveGlob`,
+ * `globToSqlLike`, and `matchesGlob` for the regex/SQL adapters. This
+ * module no longer maintains its own glob grammar; the v2 listing
+ * spec (`.cc-chat/20260625121936-grammar-shape/output.md`) collapses
+ * read+observe onto one grammar — see §3.3.1 for the foundation-round
+ * wrapper resolution.
  */
-import type { Output } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import type { Output } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/src/types/types.js";
 import type { ReadParams } from "./url.js";
 /**
  * Validate standard ReadParams and throw on anything we cannot honor.
@@ -20,10 +27,17 @@ import type { ReadParams } from "./url.js";
  * Stores that post-process in memory call `applyReadParams` instead,
  * which validates and applies in one go.
  *
- * Project-wide baseline: `pattern` and `cursor` are unsupported
- * everywhere; `sortBy` only accepts `"uri"`; `format` only accepts
- * `"full"` (default) or `"uris"`. Per-store relaxations should be
- * added explicitly as features land.
+ * Project-wide baseline:
+ * - `sortBy` accepts `"uri"` (push-down everywhere), `"leaf"` (basename
+ *   `localeCompare`), or any record field name (dispatch-layer post-sort,
+ *   or backend push-down where advertised)
+ * - `format` only accepts `"full"` (default) or `"uris"`
+ * - `pattern` is supported as a glob over the URI tail
+ * - `cursor` is supported as a stateless continuation token (the URI
+ *   of the last entry from a previous page); combining with `page` is
+ *   a programmer error since the two are alternative pagination modes
+ *
+ * Per-store relaxations should be added explicitly as features land.
  */
 export declare function validateReadParams(params: ReadParams, storeName: string): void;
 /**
@@ -34,7 +48,40 @@ export declare function validateReadParams(params: ReadParams, storeName: string
  * @param storeName label used in thrown error messages
  *
  * Returns `Output[]` when `format` is `"full"` (default) or `string[]`
- * when `format` is `"uris"`.
+ * when `format` is `"uris"`. When `params.fields` is set and `format`
+ * is `"full"`, each row's payload is projected via `projectRecord` —
+ * unknown projection field names are silently absent.
+ *
+ * `sortBy` values:
+ *   - `"uri"` — `localeCompare` of the full URI
+ *   - `"leaf"` — `localeCompare` of the basename
+ *     (`uri.slice(uri.lastIndexOf("/") + 1)`)
+ *   - any other string — treated as a record-field name; non-record
+ *     payloads sort last (`undefined`)
  */
 export declare function applyReadParams<T>(rows: Output<T>[], params: ReadParams, storeName: string): Output<T>[] | string[];
+/**
+ * Basename of a URI — everything after the last `/`. For URIs without a
+ * `/` (rare in save context but possible for opaque protocols) returns
+ * the whole string. Used by `sortBy=leaf` and exported for stores that
+ * push that sort down to a backend that needs a precomputed leaf
+ * column.
+ */
+export declare function leafOf(uri: string): string;
+/**
+ * Stable, type-aware comparator: nulls/undefineds sort last; numbers
+ * and bigints compare numerically; dates compare by `valueOf()`; the
+ * rest falls back to string-coerced `localeCompare` so the comparator
+ * never throws on heterogeneous field values.
+ */
+export declare function compareSortable(a: unknown, b: unknown): number;
+/**
+ * Project an `EntityRecord` down to the named fields. Unknown field
+ * names are silently absent — projection is a presentation directive,
+ * not a validation. Non-record values (eg `undefined` from a read
+ * miss, or a raw `Uint8Array` from a BYTES_ENTITY) pass through
+ * unchanged so callers can still detect misses and the BYTES path
+ * keeps its current shape.
+ */
+export declare function projectRecord<T>(value: T, fields: readonly string[]): T;
 //# sourceMappingURL=read.d.ts.map

package/esm/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kEAAkE,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,GAChB,IAAI,CAcN;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EACjB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAkBxB"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../src/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kEAAkE,CAAC;AAE/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,GAChB,IAAI,CAUN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EACjB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CA8CxB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG1C;AAgBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAiB9D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAYvE"}

package/esm/read.js

@@ -1,5 +1,5 @@
 /**
- * In-process post-processing for `fn=ls` results.
+ * In-process post-processing for `fn=ls`/`fn=find` results.
  *
  * Stores that cannot push `sortBy`/`limit`/`page`/`format` down to
  * their backend collect the raw `Output[]` rows under a prefix and
@@ -9,6 +9,13 @@
  *
  * Throws on unsupported params — programmer errors are not silent
  * "misses." See project decisions in `project_core_upgrade.md`.
+ *
+ * Glob compilation lives in `./glob.ts` — see `compileSaveGlob`,
+ * `globToSqlLike`, and `matchesGlob` for the regex/SQL adapters. This
+ * module no longer maintains its own glob grammar; the v2 listing
+ * spec (`.cc-chat/20260625121936-grammar-shape/output.md`) collapses
+ * read+observe onto one grammar — see §3.3.1 for the foundation-round
+ * wrapper resolution.
  */
 /**
  * Validate standard ReadParams and throw on anything we cannot honor.
@@ -18,20 +25,21 @@
  * Stores that post-process in memory call `applyReadParams` instead,
  * which validates and applies in one go.
  *
- * Project-wide baseline: `pattern` and `cursor` are unsupported
- * everywhere; `sortBy` only accepts `"uri"`; `format` only accepts
- * `"full"` (default) or `"uris"`. Per-store relaxations should be
- * added explicitly as features land.
+ * Project-wide baseline:
+ * - `sortBy` accepts `"uri"` (push-down everywhere), `"leaf"` (basename
+ *   `localeCompare`), or any record field name (dispatch-layer post-sort,
+ *   or backend push-down where advertised)
+ * - `format` only accepts `"full"` (default) or `"uris"`
+ * - `pattern` is supported as a glob over the URI tail
+ * - `cursor` is supported as a stateless continuation token (the URI
+ *   of the last entry from a previous page); combining with `page` is
+ *   a programmer error since the two are alternative pagination modes
+ *
+ * Per-store relaxations should be added explicitly as features land.
  */
 export function validateReadParams(params, storeName) {
-    if (params.pattern !== undefined) {
-        throw new Error(`${storeName}: pattern filter not supported`);
-    }
-    if (params.cursor !== undefined) {
-        throw new Error(`${storeName}: cursor not supported`);
-    }
-    if (params.sortBy !== undefined && params.sortBy !== "uri") {
-        throw new Error(`${storeName}: unsupported sortBy: ${params.sortBy}`);
+    if (params.cursor !== undefined && params.page !== undefined) {
+        throw new Error(`${storeName}: cursor and page cannot be combined — pick one pagination mode`);
     }
     const format = params.format ?? "full";
     if (format !== "full" && format !== "uris") {
@@ -46,15 +54,42 @@ export function validateReadParams(params, storeName) {
  * @param storeName label used in thrown error messages
  *
  * Returns `Output[]` when `format` is `"full"` (default) or `string[]`
- * when `format` is `"uris"`.
+ * when `format` is `"uris"`. When `params.fields` is set and `format`
+ * is `"full"`, each row's payload is projected via `projectRecord` —
+ * unknown projection field names are silently absent.
+ *
+ * `sortBy` values:
+ *   - `"uri"` — `localeCompare` of the full URI
+ *   - `"leaf"` — `localeCompare` of the basename
+ *     (`uri.slice(uri.lastIndexOf("/") + 1)`)
+ *   - any other string — treated as a record-field name; non-record
+ *     payloads sort last (`undefined`)
  */
 export function applyReadParams(rows, params, storeName) {
     validateReadParams(params, storeName);
     const format = params.format ?? "full";
     let out = rows;
-    if (params.sortBy === "uri") {
+    if (params.sortBy !== undefined) {
         const dir = params.sortOrder === "desc" ? -1 : 1;
-        out = [...out].sort(([a], [b]) => a.localeCompare(b) * dir);
+        if (params.sortBy === "uri") {
+            out = [...out].sort(([a], [b]) => a.localeCompare(b) * dir);
+        }
+        else if (params.sortBy === "leaf") {
+            out = [...out].sort(([a], [b]) => leafOf(a).localeCompare(leafOf(b)) * dir);
+        }
+        else {
+            const field = params.sortBy;
+            out = [...out].sort(([, a], [, b]) => {
+                const av = recordField(a, field);
+                const bv = recordField(b, field);
+                return compareSortable(av, bv) * dir;
+            });
+        }
+    }
+    if (params.cursor !== undefined) {
+        const cursor = params.cursor;
+        const desc = params.sortOrder === "desc";
+        out = out.filter(([uri]) => desc ? uri.localeCompare(cursor) < 0 : uri.localeCompare(cursor) > 0);
     }
     if (params.limit !== undefined) {
         const page = params.page ?? 1;
@@ -63,5 +98,95 @@ export function applyReadParams(rows, params, storeName) {
     }
     if (format === "uris")
         return out.map(([uri]) => uri);
+    if (params.fields && params.fields.length > 0) {
+        const allow = params.fields;
+        return out.map(([uri, payload]) => [
+            uri,
+            projectRecord(payload, allow),
+        ]);
+    }
+    return out;
+}
+/**
+ * Basename of a URI — everything after the last `/`. For URIs without a
+ * `/` (rare in save context but possible for opaque protocols) returns
+ * the whole string. Used by `sortBy=leaf` and exported for stores that
+ * push that sort down to a backend that needs a precomputed leaf
+ * column.
+ */
+export function leafOf(uri) {
+    const idx = uri.lastIndexOf("/");
+    return idx < 0 ? uri : uri.slice(idx + 1);
+}
+/**
+ * Read a named field from a payload, returning `undefined` for any
+ * non-record payload (eg `Uint8Array`, `ReadableStream`, miss). Used
+ * by the in-memory sort path so non-uri sortBy works against
+ * `EntityRecord` rows.
+ */
+function recordField(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "object")
+        return undefined;
+    if (value instanceof Uint8Array)
+        return undefined;
+    if (value instanceof ReadableStream)
+        return undefined;
+    return value[field];
+}
+/**
+ * Stable, type-aware comparator: nulls/undefineds sort last; numbers
+ * and bigints compare numerically; dates compare by `valueOf()`; the
+ * rest falls back to string-coerced `localeCompare` so the comparator
+ * never throws on heterogeneous field values.
+ */
+export function compareSortable(a, b) {
+    const aMissing = a === undefined || a === null;
+    const bMissing = b === undefined || b === null;
+    if (aMissing && bMissing)
+        return 0;
+    if (aMissing)
+        return 1;
+    if (bMissing)
+        return -1;
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    if (typeof a === "bigint" && typeof b === "bigint") {
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    if (a instanceof Date && b instanceof Date) {
+        return a.valueOf() - b.valueOf();
+    }
+    if (typeof a === "boolean" && typeof b === "boolean") {
+        return (a ? 1 : 0) - (b ? 1 : 0);
+    }
+    return String(a).localeCompare(String(b));
+}
+/**
+ * Project an `EntityRecord` down to the named fields. Unknown field
+ * names are silently absent — projection is a presentation directive,
+ * not a validation. Non-record values (eg `undefined` from a read
+ * miss, or a raw `Uint8Array` from a BYTES_ENTITY) pass through
+ * unchanged so callers can still detect misses and the BYTES path
+ * keeps its current shape.
+ */
+export function projectRecord(value, fields) {
+    if (value === undefined || value === null)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ReadableStream)
+        return value;
+    if (Array.isArray(value))
+        return value;
+    const out = {};
+    const src = value;
+    for (const f of fields) {
+        if (Object.prototype.hasOwnProperty.call(src, f))
+            out[f] = src[f];
+    }
     return out;
 }