@chipmobilesdk/rn-local-db 0.4.0 → 0.5.0

package/lib/module/platform/location.js

@@ -0,0 +1,120 @@
+"use strict";
+
+/**
+ * The managed storage area, and the single guard every filesystem call routes
+ * through.
+ *
+ * POL-011(b) flags media-and-files as a risk because this package deletes
+ * files from disk on cascade. The mitigation is that there is exactly one
+ * function that turns a caller's intent into a path, and it refuses anything
+ * outside the root. One choke point is what makes SC-013a's filesystem
+ * tracing pass reliably rather than usually.
+ */
+
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+import { fileSystem } from "./fs.js";
+export const MANAGED_ROOT_NAME = 'chipmobilesdk-localdb';
+export const CATALOG_FILE = 'catalog.db';
+export const SCOPES_DIR = 'scopes';
+export const DATA_FILE = 'data.db';
+export const ARTIFACTS_DIR = 'artifacts';
+
+/** Normalize separators and collapse redundant segments. No `..` survives. */
+export function normalizePath(path) {
+  const unified = path.replace(/\\/g, '/');
+  const segments = [];
+  for (const segment of unified.split('/')) {
+    if (segment === '' || segment === '.') {
+      continue;
+    }
+    if (segment === '..') {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  const prefix = unified.startsWith('/') ? '/' : '';
+  return prefix + segments.join('/');
+}
+const SCOPE_KEY = /^[0-9a-f]{64}$/;
+const ARTIFACT_ID = /^[A-Za-z0-9._-]{1,128}$/;
+// `.` and `..` are made entirely of permitted characters and are the two that
+// matter: `artifacts/..` resolves to the scope directory itself, still inside
+// the managed root, so the boundary guard would wave it through and a cascade
+// would unlink the whole scope. A leading dot is refused with them, since no
+// attachment id needs one and hidden files are the package's own.
+const DOT_PREFIXED = /^\./;
+
+/**
+ * An attachment id must be a safe single path segment.
+ *
+ * Shared by both adapters rather than left to the one that touches a
+ * filesystem. The in-memory adapter has no paths to escape, but a consumer
+ * whose tests accept `../../etc/passwd` and whose device build refuses it has
+ * a test suite that stops predicting the device — which is the one thing the
+ * adapter exists to avoid (FR-096).
+ */
+export function assertValidAttachmentId(attachmentId) {
+  if (!ARTIFACT_ID.test(attachmentId) || DOT_PREFIXED.test(attachmentId)) {
+    raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
+      message: 'attachment id is not a valid path segment'
+    });
+  }
+}
+export function createLayout(documentDirectory, databaseName) {
+  const root = normalizePath(`${documentDirectory}/${MANAGED_ROOT_NAME}/${databaseName}`);
+  const scopePath = scopeKey => {
+    // The scope key is our own SHA-256 output. Validating its shape here
+    // means a caller cannot smuggle a traversal through it even if some
+    // future path reaches this function with unvalidated input.
+    if (!SCOPE_KEY.test(scopeKey)) {
+      raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
+        message: 'scope key is not a valid digest'
+      });
+    }
+    return `${root}/${SCOPES_DIR}/${scopeKey}`;
+  };
+  return {
+    root,
+    catalogPath: `${root}/${CATALOG_FILE}`,
+    scopePath,
+    scopeDataPath: scopeKey => `${scopePath(scopeKey)}/${DATA_FILE}`,
+    scopeArtifactsPath: scopeKey => `${scopePath(scopeKey)}/${ARTIFACTS_DIR}`,
+    artifactPath: (scopeKey, attachmentId) => {
+      assertValidAttachmentId(attachmentId);
+      return `${scopePath(scopeKey)}/${ARTIFACTS_DIR}/${attachmentId}`;
+    }
+  };
+}
+
+/**
+ * The layout for one logical database, rooted at the app's private documents
+ * directory.
+ *
+ * Resolved lazily through the filesystem peer rather than captured at module
+ * load, so importing this package does not require the peer to be installed —
+ * a consumer running only the in-memory adapter never reaches this function.
+ */
+export function layoutFor(databaseName) {
+  return createLayout(fileSystem().DocumentDirectoryPath, databaseName);
+}
+
+/**
+ * The guard. Every read, write, and delete passes through this, and anything
+ * resolving outside the managed root is refused before it reaches the
+ * filesystem (FR-073, FR-073f).
+ */
+export function assertWithinManagedArea(layout, candidate) {
+  const normalized = normalizePath(candidate);
+  const root = normalizePath(layout.root);
+  if (normalized !== root && !normalized.startsWith(`${root}/`)) {
+    raise(DiagnosticCodes.ATTACHMENT_OUT_OF_BOUNDS, {
+      // The offending path is NOT reported: it may contain a scope
+      // component or a user-chosen filename.
+      message: 'path resolves outside the managed storage area'
+    });
+  }
+  return normalized;
+}
+//# sourceMappingURL=location.js.map

package/lib/module/platform/location.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DiagnosticCodes","raise","fileSystem","MANAGED_ROOT_NAME","CATALOG_FILE","SCOPES_DIR","DATA_FILE","ARTIFACTS_DIR","normalizePath","path","unified","replace","segments","segment","split","pop","push","prefix","startsWith","join","SCOPE_KEY","ARTIFACT_ID","DOT_PREFIXED","assertValidAttachmentId","attachmentId","test","ATTACHMENT_OUT_OF_BOUNDS","message","createLayout","documentDirectory","databaseName","root","scopePath","scopeKey","catalogPath","scopeDataPath","scopeArtifactsPath","artifactPath","layoutFor","DocumentDirectoryPath","assertWithinManagedArea","layout","candidate","normalized"],"sourceRoot":"../../../src","sources":["platform/location.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/query/budgets.js

@@ -0,0 +1,88 @@
+"use strict";
+
+/**
+ * Budget enforcement.
+ *
+ * Per-record size, page size, and batch size are HARD limits reported through
+ * typed errors (FR-088a). The rest are soft: exceeding them must not crash,
+ * hang, or drop data silently, and the degraded behavior is documented.
+ */
+
+import { Budgets } from "../contract/config.js";
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+
+/**
+ * UTF-8 length of a string, counted rather than encoded: measuring a 256 KB
+ * record used to allocate a 256 KB byte array just to read its length.
+ */
+export function utf8Length(value) {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (unit < 0x80) {
+      bytes += 1;
+    } else if (unit < 0x800) {
+      bytes += 2;
+    } else if (unit >= 0xd800 && unit <= 0xdbff && index + 1 < value.length) {
+      // A surrogate pair is one four-byte code point.
+      bytes += 4;
+      index += 1;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+}
+
+/** UTF-8 byte length of the serialized payload — what actually hits disk. */
+export function serializedSize(data) {
+  return utf8Length(JSON.stringify(data ?? {}));
+}
+
+/**
+ * Checks the size budget and returns the serialized payload, so the write that
+ * follows stores this string instead of serializing the record a second time.
+ */
+export function assertRecordWithinBudget(collection, data) {
+  const payload = JSON.stringify(data ?? {});
+  const size = utf8Length(payload);
+  if (size > Budgets.MAX_RECORD_BYTES) {
+    // Truncating would be silent data loss; failing opaquely would leave
+    // the consumer guessing. The size and the limit are both safe to
+    // report — neither can carry a field value.
+    raise(DiagnosticCodes.RECORD_TOO_LARGE, {
+      message: 'record exceeds the per-record size budget',
+      detail: {
+        collection,
+        sizeBytes: size,
+        limitBytes: Budgets.MAX_RECORD_BYTES
+      }
+    });
+  }
+  return payload;
+}
+export function assertBatchWithinBudget(count) {
+  if (count > Budgets.MAX_BATCH_OPERATIONS) {
+    raise(DiagnosticCodes.BATCH_TOO_LARGE, {
+      message: 'batch exceeds the operation budget',
+      detail: {
+        count,
+        limit: Budgets.MAX_BATCH_OPERATIONS
+      }
+    });
+  }
+}
+export function assertArtifactWithinBudget(id, size) {
+  if (size > Budgets.MAX_ARTIFACT_BYTES) {
+    raise(DiagnosticCodes.ATTACHMENT_WRITE_FAILED, {
+      message: 'artifact exceeds the size budget',
+      detail: {
+        attachmentId: id,
+        sizeBytes: size,
+        limitBytes: Budgets.MAX_ARTIFACT_BYTES
+      }
+    });
+  }
+}
+//# sourceMappingURL=budgets.js.map

package/lib/module/query/budgets.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Budgets","DiagnosticCodes","raise","utf8Length","value","bytes","index","length","unit","charCodeAt","serializedSize","data","JSON","stringify","assertRecordWithinBudget","collection","payload","size","MAX_RECORD_BYTES","RECORD_TOO_LARGE","message","detail","sizeBytes","limitBytes","assertBatchWithinBudget","count","MAX_BATCH_OPERATIONS","BATCH_TOO_LARGE","limit","assertArtifactWithinBudget","id","MAX_ARTIFACT_BYTES","ATTACHMENT_WRITE_FAILED","attachmentId"],"sourceRoot":"../../../src","sources":["query/budgets.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,OAAO,QAAQ,uBAAoB;AAC5C,SAASC,eAAe,QAAQ,uBAAoB;AAEpD,SAASC,KAAK,QAAQ,0BAAuB;;AAE7C;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CAACC,KAAa,EAAU;EACjD,IAAIC,KAAK,GAAG,CAAC;EACb,KAAK,IAAIC,KAAK,GAAG,CAAC,EAAEA,KAAK,GAAGF,KAAK,CAACG,MAAM,EAAED,KAAK,IAAI,CAAC,EAAE;IACrD,MAAME,IAAI,GAAGJ,KAAK,CAACK,UAAU,CAACH,KAAK,CAAC;IACpC,IAAIE,IAAI,GAAG,IAAI,EAAE;MAChBH,KAAK,IAAI,CAAC;IACX,CAAC,MAAM,IAAIG,IAAI,GAAG,KAAK,EAAE;MACxBH,KAAK,IAAI,CAAC;IACX,CAAC,MAAM,IAAIG,IAAI,IAAI,MAAM,IAAIA,IAAI,IAAI,MAAM,IAAIF,KAAK,GAAG,CAAC,GAAGF,KAAK,CAACG,MAAM,EAAE;MACxE;MACAF,KAAK,IAAI,CAAC;MACVC,KAAK,IAAI,CAAC;IACX,CAAC,MAAM;MACND,KAAK,IAAI,CAAC;IACX;EACD;EACA,OAAOA,KAAK;AACb;;AAEA;AACA,OAAO,SAASK,cAAcA,CAACC,IAAwB,EAAU;EAChE,OAAOR,UAAU,CAACS,IAAI,CAACC,SAAS,CAACF,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9C;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASG,wBAAwBA,CAACC,UAAkB,EAAEJ,IAAwB,EAAU;EAC9F,MAAMK,OAAO,GAAGJ,IAAI,CAACC,SAAS,CAACF,IAAI,IAAI,CAAC,CAAC,CAAC;EAC1C,MAAMM,IAAI,GAAGd,UAAU,CAACa,OAAO,CAAC;EAChC,IAAIC,IAAI,GAAGjB,OAAO,CAACkB,gBAAgB,EAAE;IACpC;IACA;IACA;IACAhB,KAAK,CAACD,eAAe,CAACkB,gBAAgB,EAAE;MACvCC,OAAO,EAAE,2CAA2C;MACpDC,MAAM,EAAE;QAAEN,UAAU;QAAEO,SAAS,EAAEL,IAAI;QAAEM,UAAU,EAAEvB,OAAO,CAACkB;MAAiB;IAC7E,CAAC,CAAC;EACH;EACA,OAAOF,OAAO;AACf;AAEA,OAAO,SAASQ,uBAAuBA,CAACC,KAAa,EAAQ;EAC5D,IAAIA,KAAK,GAAGzB,OAAO,CAAC0B,oBAAoB,EAAE;IACzCxB,KAAK,CAACD,eAAe,CAAC0B,eAAe,EAAE;MACtCP,OAAO,EAAE,oCAAoC;MAC7CC,MAAM,EAAE;QAAEI,KAAK;QAAEG,KAAK,EAAE5B,OAAO,CAAC0B;MAAqB;IACtD,CAAC,CAAC;EACH;AACD;AAEA,OAAO,SAASG,0BAA0BA,CAACC,EAAU,EAAEb,IAAY,EAAQ;EAC1E,IAAIA,IAAI,GAAGjB,OAAO,CAAC+B,kBAAkB,EAAE;IACtC7B,KAAK,CAACD,eAAe,CAAC+B,uBAAuB,EAAE;MAC9CZ,OAAO,EAAE,kCAAkC;MAC3CC,MAAM,EAAE;QACPY,YAAY,EAAEH,EAAE;QAChBR,SAAS,EAAEL,IAAI;QACfM,UAAU,EAAEvB,OAAO,CAAC+B;MACrB;IACD,CAAC,CAAC;EACH;AACD","ignoreList":[]}

package/lib/module/query/compare.js

@@ -0,0 +1,90 @@
+"use strict";
+
+/**
+ * Comparison and field access semantics.
+ *
+ * Defined once here, used by the in-memory adapter directly and by the SQL
+ * builder for validation and cursor construction. Two implementations of
+ * these rules would drift, and the drift would show up as a conformance
+ * divergence that hides a real bug (research.md R8).
+ */
+
+/**
+ * A field is one of three things, and the difference is the whole point of
+ * FR-019: present with a value, present and null, or absent.
+ */
+
+export function lookupField(data, field) {
+  if (!Object.prototype.hasOwnProperty.call(data, field)) {
+    return {
+      present: false
+    };
+  }
+  const value = data[field];
+  if (value === null) {
+    return {
+      present: true,
+      value: null
+    };
+  }
+  return {
+    present: true,
+    value: value
+  };
+}
+
+/**
+ * Ordering for values of the same declared type.
+ *
+ * Null sorts before every non-null value, matching SQLite's default so the
+ * two adapters agree without the SQL builder emitting NULLS FIRST/LAST
+ * clauses that older SQLite versions do not support.
+ */
+export function compareValues(a, b) {
+  if (a === null && b === null) {
+    return 0;
+  }
+  if (a === null) {
+    return -1;
+  }
+  if (b === null) {
+    return 1;
+  }
+  if (typeof a === 'boolean' || typeof b === 'boolean') {
+    return Number(a) - Number(b);
+  }
+  if (typeof a === 'number' && typeof b === 'number') {
+    if (Number.isNaN(a) || Number.isNaN(b)) {
+      return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? -1 : 1;
+    }
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  const sa = String(a);
+  const sb = String(b);
+  // Byte-order rather than locale collation: a locale-aware comparison would
+  // make the stored order depend on device settings, so the same data would
+  // page differently on two phones.
+  return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+
+/** Only primitives can be compared; a nested object is never a filter target. */
+export function asFilterValue(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+  return undefined;
+}
+
+/**
+ * Byte order, not locale collation.
+ *
+ * A locale-aware sort would make the reported order depend on device
+ * settings, so two phones holding identical data would report it differently.
+ */
+export function byteOrder(a, b) {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+}
+//# sourceMappingURL=compare.js.map

package/lib/module/query/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["lookupField","data","field","Object","prototype","hasOwnProperty","call","present","value","compareValues","a","b","Number","isNaN","sa","String","sb","asFilterValue","undefined","byteOrder"],"sourceRoot":"../../../src","sources":["query/compare.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA;AACA;AACA;AACA;;AAMA,OAAO,SAASA,WAAWA,CAACC,IAAwB,EAAEC,KAAa,EAAe;EACjF,IAAI,CAACC,MAAM,CAACC,SAAS,CAACC,cAAc,CAACC,IAAI,CAACL,IAAI,EAAEC,KAAK,CAAC,EAAE;IACvD,OAAO;MAAEK,OAAO,EAAE;IAAM,CAAC;EAC1B;EACA,MAAMC,KAAK,GAAGP,IAAI,CAACC,KAAK,CAAC;EACzB,IAAIM,KAAK,KAAK,IAAI,EAAE;IACnB,OAAO;MAAED,OAAO,EAAE,IAAI;MAAEC,KAAK,EAAE;IAAK,CAAC;EACtC;EACA,OAAO;IAAED,OAAO,EAAE,IAAI;IAAEC,KAAK,EAAEA;EAAsC,CAAC;AACvE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAACC,CAAc,EAAEC,CAAc,EAAU;EACrE,IAAID,CAAC,KAAK,IAAI,IAAIC,CAAC,KAAK,IAAI,EAAE;IAC7B,OAAO,CAAC;EACT;EACA,IAAID,CAAC,KAAK,IAAI,EAAE;IACf,OAAO,CAAC,CAAC;EACV;EACA,IAAIC,CAAC,KAAK,IAAI,EAAE;IACf,OAAO,CAAC;EACT;EACA,IAAI,OAAOD,CAAC,KAAK,SAAS,IAAI,OAAOC,CAAC,KAAK,SAAS,EAAE;IACrD,OAAOC,MAAM,CAACF,CAAC,CAAC,GAAGE,MAAM,CAACD,CAAC,CAAC;EAC7B;EACA,IAAI,OAAOD,CAAC,KAAK,QAAQ,IAAI,OAAOC,CAAC,KAAK,QAAQ,EAAE;IACnD,IAAIC,MAAM,CAACC,KAAK,CAACH,CAAC,CAAC,IAAIE,MAAM,CAACC,KAAK,CAACF,CAAC,CAAC,EAAE;MACvC,OAAOC,MAAM,CAACC,KAAK,CAACH,CAAC,CAAC,IAAIE,MAAM,CAACC,KAAK,CAACF,CAAC,CAAC,GAAG,CAAC,GAAGC,MAAM,CAACC,KAAK,CAACH,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;IACzE;IACA,OAAOA,CAAC,GAAGC,CAAC,GAAG,CAAC,CAAC,GAAGD,CAAC,GAAGC,CAAC,GAAG,CAAC,GAAG,CAAC;EAClC;EACA,MAAMG,EAAE,GAAGC,MAAM,CAACL,CAAC,CAAC;EACpB,MAAMM,EAAE,GAAGD,MAAM,CAACJ,CAAC,CAAC;EACpB;EACA;EACA;EACA,OAAOG,EAAE,GAAGE,EAAE,GAAG,CAAC,CAAC,GAAGF,EAAE,GAAGE,EAAE,GAAG,CAAC,GAAG,CAAC;AACtC;;AAEA;AACA,OAAO,SAASC,aAAaA,CAACT,KAAoB,EAA2B;EAC5E,IACCA,KAAK,KAAK,IAAI,IACd,OAAOA,KAAK,KAAK,QAAQ,IACzB,OAAOA,KAAK,KAAK,QAAQ,IACzB,OAAOA,KAAK,KAAK,SAAS,EACzB;IACD,OAAOA,KAAK;EACb;EACA,OAAOU,SAAS;AACjB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,SAASA,CAACT,CAAS,EAAEC,CAAS,EAAU;EACvD,IAAID,CAAC,GAAGC,CAAC,EAAE;IACV,OAAO,CAAC,CAAC;EACV;EACA,OAAOD,CAAC,GAAGC,CAAC,GAAG,CAAC,GAAG,CAAC;AACrB","ignoreList":[]}

package/lib/module/query/cursor.js

@@ -0,0 +1,91 @@
+"use strict";
+
+/**
+ * Keyset pagination cursors.
+ *
+ * Keyset rather than OFFSET for two reasons, both of which SC-007 measures:
+ * OFFSET degrades linearly at the 100,000-record budget because the engine
+ * still walks the skipped rows, and it shifts pages under concurrent writes
+ * so a record can be skipped or returned twice. A cursor anchored to the last
+ * row's sort values has neither problem.
+ */
+
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+import { compareValues } from "./compare.js";
+import { sortValueOf } from "./sort.js";
+import { base64ToBytes, bytesToBase64, host, utf8Bytes, utf8String } from "../platform/bytes.js";
+function shapeOf(sort) {
+  return sort.map(key => `${key.field}:${key.direction === 'desc' ? 'd' : 'a'}`).join(',');
+}
+function toBase64(value) {
+  if (host.btoa) {
+    return host.btoa(unescape(encodeURIComponent(value)));
+  }
+  return bytesToBase64(utf8Bytes(value));
+}
+function fromBase64(value) {
+  if (host.atob) {
+    return decodeURIComponent(escape(host.atob(value)));
+  }
+  return utf8String(base64ToBytes(value));
+}
+export function encodeCursor(record, sort) {
+  const payload = {
+    k: shapeOf(sort),
+    v: sort.map(key => sortValueOf(record, key.field) ?? null)
+  };
+  return toBase64(JSON.stringify(payload));
+}
+export function decodeCursor(cursor, sort) {
+  let payload;
+  try {
+    payload = JSON.parse(fromBase64(cursor));
+  } catch {
+    raise(DiagnosticCodes.CURSOR_INVALID, {
+      message: 'cursor is not decodable'
+    });
+  }
+  if (!payload || typeof payload.k !== 'string' || !Array.isArray(payload.v)) {
+    raise(DiagnosticCodes.CURSOR_INVALID, {
+      message: 'cursor payload is malformed'
+    });
+  }
+  // A cursor from a differently sorted query would produce a silently wrong
+  // page rather than an error, so the shape is part of the cursor.
+  if (payload.k !== shapeOf(sort)) {
+    raise(DiagnosticCodes.CURSOR_INVALID, {
+      message: 'cursor does not match this query shape'
+    });
+  }
+  if (payload.v.length !== sort.length) {
+    raise(DiagnosticCodes.CURSOR_INVALID, {
+      message: 'cursor arity does not match sort'
+    });
+  }
+  return payload.v;
+}
+
+/**
+ * Is this record strictly after the cursor position, under the sort order?
+ *
+ * Lexicographic across the sort keys: equal on the first key means the second
+ * decides, and so on down to the id tiebreaker that guarantees a total order.
+ */
+export function isAfterCursor(record, sort, anchor) {
+  for (let i = 0; i < sort.length; i += 1) {
+    const key = sort[i];
+    const direction = key.direction === 'desc' ? -1 : 1;
+    const value = sortValueOf(record, key.field) ?? null;
+    const result = compareValues(value, anchor[i] ?? null) * direction;
+    if (result > 0) {
+      return true;
+    }
+    if (result < 0) {
+      return false;
+    }
+  }
+  // Equal on every key including id — this is the anchor row itself.
+  return false;
+}
+//# sourceMappingURL=cursor.js.map

package/lib/module/query/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DiagnosticCodes","raise","compareValues","sortValueOf","base64ToBytes","bytesToBase64","host","utf8Bytes","utf8String","shapeOf","sort","map","key","field","direction","join","toBase64","value","btoa","unescape","encodeURIComponent","fromBase64","atob","decodeURIComponent","escape","encodeCursor","record","payload","k","v","JSON","stringify","decodeCursor","cursor","parse","CURSOR_INVALID","message","Array","isArray","length","isAfterCursor","anchor","i","result"],"sourceRoot":"../../../src","sources":["query/cursor.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/query/filter.js

@@ -0,0 +1,78 @@
+"use strict";
+
+/**
+ * Filter evaluation over a plain record.
+ *
+ * The in-memory adapter runs this directly. The SQLite adapter translates the
+ * same validated tree to SQL. Both must agree, which is why the semantics
+ * live here rather than in either of them.
+ */
+
+import { asFilterValue, compareValues, lookupField } from "./compare.js";
+function equals(a, b) {
+  return compareValues(a, b) === 0 && a === null === (b === null);
+}
+export function evaluateFilter(data, node) {
+  switch (node.op) {
+    case 'and':
+      return node.nodes.every(child => evaluateFilter(data, child));
+    case 'or':
+      return node.nodes.some(child => evaluateFilter(data, child));
+    case 'not':
+      return !evaluateFilter(data, node.node);
+    default:
+      break;
+  }
+  const lookup = lookupField(data, node.field);
+
+  // `exists` is the only operator that answers a question about presence,
+  // which is what keeps "absent" distinguishable from "null" (FR-019).
+  if (node.op === 'exists') {
+    return lookup.present === node.value;
+  }
+  if (!lookup.present) {
+    // An absent field satisfies nothing else — not even `ne` or `isNull`.
+    // SQL agrees: a comparison against a missing column yields NULL, which
+    // is not true.
+    return false;
+  }
+  const value = asFilterValue(lookup.value);
+  if (value === undefined) {
+    // A nested object or array is not comparable. Matching it would be a
+    // guess, so it simply does not satisfy a comparison.
+    return false;
+  }
+  switch (node.op) {
+    case 'isNull':
+      return value === null;
+    case 'isNotNull':
+      return value !== null;
+    case 'eq':
+      return equals(value, node.value);
+    case 'ne':
+      return !equals(value, node.value);
+    case 'lt':
+      return value !== null && node.value !== null && compareValues(value, node.value) < 0;
+    case 'lte':
+      return value !== null && node.value !== null && compareValues(value, node.value) <= 0;
+    case 'gt':
+      return value !== null && node.value !== null && compareValues(value, node.value) > 0;
+    case 'gte':
+      return value !== null && node.value !== null && compareValues(value, node.value) >= 0;
+    case 'in':
+      return node.value.some(candidate => equals(value, candidate));
+    case 'nin':
+      return !node.value.some(candidate => equals(value, candidate));
+    case 'between':
+      {
+        const [low, high] = node.value;
+        if (value === null || low === null || high === null) {
+          return false;
+        }
+        return compareValues(value, low) >= 0 && compareValues(value, high) <= 0;
+      }
+    default:
+      return false;
+  }
+}
+//# sourceMappingURL=filter.js.map

package/lib/module/query/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["asFilterValue","compareValues","lookupField","equals","a","b","evaluateFilter","data","node","op","nodes","every","child","some","lookup","field","present","value","undefined","candidate","low","high"],"sourceRoot":"../../../src","sources":["query/filter.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/query/paginate.js

@@ -0,0 +1,40 @@
+"use strict";
+
+/**
+ * Page assembly over already-filtered, already-sorted records.
+ *
+ * Shared so the in-memory adapter and the SQLite adapter produce identical
+ * pages, including the `hasMore` signal and when a cursor is emitted.
+ */
+
+import { Budgets } from "../contract/config.js";
+import { decodeCursor, encodeCursor, isAfterCursor } from "./cursor.js";
+export const DEFAULT_PAGE_SIZE = 50;
+export function resolvePageSize(page) {
+  return page?.size ?? DEFAULT_PAGE_SIZE;
+}
+
+/** Fetch one extra row to answer `hasMore` without a second count query. */
+export function fetchLimitFor(size) {
+  return Math.min(size, Budgets.MAX_PAGE_SIZE) + 1;
+}
+export function applyCursor(records, sort, cursor) {
+  if (!cursor) {
+    return records;
+  }
+  const anchor = decodeCursor(cursor, sort);
+  return records.filter(record => isAfterCursor(record, sort, anchor));
+}
+export function buildPage(records, sort, size) {
+  const hasMore = records.length > size;
+  const page = hasMore ? records.slice(0, size) : records;
+  const last = page[page.length - 1];
+  return {
+    records: page,
+    // No cursor on the final page: handing one back invites a consumer to
+    // keep paging past the end and treat an empty page as an error.
+    cursor: hasMore && last ? encodeCursor(last, sort) : undefined,
+    hasMore
+  };
+}
+//# sourceMappingURL=paginate.js.map

package/lib/module/query/paginate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Budgets","decodeCursor","encodeCursor","isAfterCursor","DEFAULT_PAGE_SIZE","resolvePageSize","page","size","fetchLimitFor","Math","min","MAX_PAGE_SIZE","applyCursor","records","sort","cursor","anchor","filter","record","buildPage","hasMore","length","slice","last","undefined"],"sourceRoot":"../../../src","sources":["query/paginate.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,OAAO,QAAQ,uBAAoB;AAG5C,SAASC,YAAY,EAAEC,YAAY,EAAEC,aAAa,QAAQ,aAAU;AAEpE,OAAO,MAAMC,iBAAiB,GAAG,EAAE;AAEnC,OAAO,SAASC,eAAeA,CAACC,IAA6B,EAAU;EACtE,OAAOA,IAAI,EAAEC,IAAI,IAAIH,iBAAiB;AACvC;;AAEA;AACA,OAAO,SAASI,aAAaA,CAACD,IAAY,EAAU;EACnD,OAAOE,IAAI,CAACC,GAAG,CAACH,IAAI,EAAEP,OAAO,CAACW,aAAa,CAAC,GAAG,CAAC;AACjD;AAEA,OAAO,SAASC,WAAWA,CAC1BC,OAAY,EACZC,IAAe,EACfC,MAA0B,EACpB;EACN,IAAI,CAACA,MAAM,EAAE;IACZ,OAAOF,OAAO;EACf;EACA,MAAMG,MAAM,GAAGf,YAAY,CAACc,MAAM,EAAED,IAAI,CAAC;EACzC,OAAOD,OAAO,CAACI,MAAM,CAACC,MAAM,IAAIf,aAAa,CAACe,MAAM,EAAEJ,IAAI,EAAEE,MAAM,CAAC,CAAC;AACrE;AAEA,OAAO,SAASG,SAASA,CACxBN,OAA0B,EAC1BC,IAAe,EACfP,IAAY,EACI;EAChB,MAAMa,OAAO,GAAGP,OAAO,CAACQ,MAAM,GAAGd,IAAI;EACrC,MAAMD,IAAI,GAAGc,OAAO,GAAGP,OAAO,CAACS,KAAK,CAAC,CAAC,EAAEf,IAAI,CAAC,GAAGM,OAAO;EACvD,MAAMU,IAAI,GAAGjB,IAAI,CAACA,IAAI,CAACe,MAAM,GAAG,CAAC,CAAC;EAClC,OAAO;IACNR,OAAO,EAAEP,IAAI;IACb;IACA;IACAS,MAAM,EAAEK,OAAO,IAAIG,IAAI,GAAGrB,YAAY,CAACqB,IAAI,EAAET,IAAI,CAAC,GAAGU,SAAS;IAC9DJ;EACD,CAAC;AACF","ignoreList":[]}

package/lib/module/query/sort.js

@@ -0,0 +1,53 @@
+"use strict";
+
+/**
+ * Sort ordering.
+ *
+ * The record id is always appended as the final sort key (FR-031). Without a
+ * tiebreaker, records with equal sort values come back in whatever order the
+ * engine happens to produce, which makes keyset pagination lose or repeat
+ * rows — the exact failure SC-007 forbids.
+ */
+
+import { asFilterValue, compareValues, lookupField } from "./compare.js";
+export const ID_SORT_KEY = {
+  field: 'id',
+  direction: 'asc'
+};
+
+/** Append `id ASC` unless the caller already sorted by it. */
+export function withStableTiebreaker(sort) {
+  const keys = sort ? [...sort] : [];
+  if (!keys.some(key => key.field === 'id')) {
+    keys.push(ID_SORT_KEY);
+  }
+  return keys;
+}
+
+/** Sort values come from the record id or from a declared field. */
+export function sortValueOf(record, field) {
+  if (field === 'id') {
+    return record.id;
+  }
+  const lookup = lookupField(record.data, field);
+  if (!lookup.present) {
+    // Absent sorts alongside null, matching how SQLite treats a NULL
+    // column, so the two adapters agree without special-casing.
+    return null;
+  }
+  return asFilterValue(lookup.value) ?? null;
+}
+export function compareRecords(a, b, sort) {
+  for (const key of sort) {
+    const direction = key.direction === 'desc' ? -1 : 1;
+    const result = compareValues(sortValueOf(a, key.field) ?? null, sortValueOf(b, key.field) ?? null);
+    if (result !== 0) {
+      return result * direction;
+    }
+  }
+  return 0;
+}
+export function sortRecords(records, sort) {
+  return [...records].sort((a, b) => compareRecords(a, b, sort));
+}
+//# sourceMappingURL=sort.js.map

package/lib/module/query/sort.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["asFilterValue","compareValues","lookupField","ID_SORT_KEY","field","direction","withStableTiebreaker","sort","keys","some","key","push","sortValueOf","record","id","lookup","data","present","value","compareRecords","a","b","result","sortRecords","records"],"sourceRoot":"../../../src","sources":["query/sort.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA,SAASA,aAAa,EAAEC,aAAa,EAAEC,WAAW,QAAQ,cAAW;AAErE,OAAO,MAAMC,WAAoB,GAAG;EAAEC,KAAK,EAAE,IAAI;EAAEC,SAAS,EAAE;AAAM,CAAC;;AAErE;AACA,OAAO,SAASC,oBAAoBA,CAACC,IAA2B,EAAa;EAC5E,MAAMC,IAAI,GAAGD,IAAI,GAAG,CAAC,GAAGA,IAAI,CAAC,GAAG,EAAE;EAClC,IAAI,CAACC,IAAI,CAACC,IAAI,CAACC,GAAG,IAAIA,GAAG,CAACN,KAAK,KAAK,IAAI,CAAC,EAAE;IAC1CI,IAAI,CAACG,IAAI,CAACR,WAAW,CAAC;EACvB;EACA,OAAOK,IAAI;AACZ;;AAEA;AACA,OAAO,SAASI,WAAWA,CAACC,MAAoB,EAAET,KAAa,EAAoC;EAClG,IAAIA,KAAK,KAAK,IAAI,EAAE;IACnB,OAAOS,MAAM,CAACC,EAAE;EACjB;EACA,MAAMC,MAAM,GAAGb,WAAW,CAACW,MAAM,CAACG,IAAI,EAAEZ,KAAK,CAAC;EAC9C,IAAI,CAACW,MAAM,CAACE,OAAO,EAAE;IACpB;IACA;IACA,OAAO,IAAI;EACZ;EACA,OAAOjB,aAAa,CAACe,MAAM,CAACG,KAAK,CAAC,IAAI,IAAI;AAC3C;AAEA,OAAO,SAASC,cAAcA,CAACC,CAAe,EAAEC,CAAe,EAAEd,IAAe,EAAU;EACzF,KAAK,MAAMG,GAAG,IAAIH,IAAI,EAAE;IACvB,MAAMF,SAAS,GAAGK,GAAG,CAACL,SAAS,KAAK,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC;IACnD,MAAMiB,MAAM,GAAGrB,aAAa,CAC3BW,WAAW,CAACQ,CAAC,EAAEV,GAAG,CAACN,KAAK,CAAC,IAAI,IAAI,EACjCQ,WAAW,CAACS,CAAC,EAAEX,GAAG,CAACN,KAAK,CAAC,IAAI,IAC9B,CAAC;IACD,IAAIkB,MAAM,KAAK,CAAC,EAAE;MACjB,OAAOA,MAAM,GAAGjB,SAAS;IAC1B;EACD;EACA,OAAO,CAAC;AACT;AAEA,OAAO,SAASkB,WAAWA,CAAyBC,OAAY,EAAEjB,IAAe,EAAO;EACvF,OAAO,CAAC,GAAGiB,OAAO,CAAC,CAACjB,IAAI,CAAC,CAACa,CAAC,EAAEC,CAAC,KAAKF,cAAc,CAACC,CAAC,EAAEC,CAAC,EAAEd,IAAI,CAAC,CAAC;AAC/D","ignoreList":[]}