@jarenjs/db 0.49.2 → 0.66.1

package/src/json-bytes.js

@@ -0,0 +1,58 @@
+//@ts-check
+/** JSON byte accounting over decoded data, without allocating encoded text. */
+
+/** UTF-8 bytes of a JSON string, including quotes and well-formed escapes.
+ * @param {string} value @returns {number}
+ */
+export function jsonStringBytes(value) {
+  let bytes = 2;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code === 34 || code === 92 || code === 8 || code === 9
+      || code === 10 || code === 12 || code === 13) bytes += 2;
+    else if (code < 32) bytes += 6;
+    else if (code < 128) bytes++;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdfff) {
+      const next = value.charCodeAt(i + 1);
+      if (code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) { bytes += 4; i++; }
+      else bytes += 6;
+    }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
+/** The JSON serialization size of decoded JSON data. Objects are memoized
+ * during decoding, so a nested include reads its size without another walk.
+ * @param {any} value @param {WeakMap<object, number>} [sizes]
+ * @returns {number}
+ */
+export function jsonBytes(value, sizes = new WeakMap()) {
+  if (value === null) return 4;
+  if (typeof value === 'string') return jsonStringBytes(value);
+  if (typeof value === 'boolean') return value ? 4 : 5;
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value).length : 4;
+  if (typeof value !== 'object') throw new TypeError('byte accounting requires decoded JSON data');
+  const cached = sizes.get(value);
+  if (cached !== undefined) return cached;
+  const keys = Object.keys(value);
+  let bytes = 2 + Math.max(0, keys.length - 1);
+  const array = Array.isArray(value);
+  for (const key of keys) bytes += (array ? 0 : jsonStringBytes(key) + 1) + jsonBytes(value[key], sizes);
+  sizes.set(value, bytes);
+  return bytes;
+}
+
+/** Decode and account bottom-up in the decoder's construction traversal.
+ * The caller checks the incoming text bound before decoding and checks the
+ * recorded nested bounds before attaching any reconstructed children.
+ * @param {string} text @param {WeakMap<object, number>} sizes
+ * @returns {any}
+ */
+export function decodeCountedJson(text, sizes) {
+  return JSON.parse(text, (_key, value) => {
+    if (value !== null && typeof value === 'object') jsonBytes(value, sizes);
+    return value;
+  });
+}

package/src/live-time.js

@@ -77,7 +77,7 @@ export function normalizeEventTime(options, collection) {
   const declared = options?.eventTime;
   if (declared === undefined || declared === null) return null;
   const refuse = (reason) => {
-    throw new DbCompileError('JD0053', reason, { collection });
+    throw new DbCompileError('JD0053', reason, `/collections/${collection}`);
   };
   if (!isJsonObject(declared))
     refuse('live eventTime is an object with a path, a watermark and a retention');
@@ -178,6 +178,15 @@ export function classifyEventTime(inner, windowed, keyed, eventTime) {
     return rerun(`'${name}' — a named zone resolves through the injected provider, which `
       + 'maintenance would have to consult per boundary');
   }
+  // the kernel reads member NAMES (`at`, `value`); the document spells
+  // them as row selectors (`$.at`) — handed the document's spelling, the
+  // kernel read `row['$.at']` and every fold died on its first reading
+  const valueMember = spec.value === undefined ? null : singularSelector(spec.value);
+  if (spec.value !== undefined && valueMember === null) {
+    return rerun(`'${name}' — the spec reads a value selector this view cannot follow`);
+  }
+  const kernelSpec = { ...spec, at: eventTime.member,
+    ...(valueMember === null ? {} : { value: valueMember }) };
   const aggregate = spec.aggregate ?? 'mean';
   if (!MAINTAINED_AGGREGATES.includes(aggregate)) {
     return rerun(`'${name}' — '${aggregate}' names a row by its position in the series, `
@@ -215,7 +224,7 @@ export function classifyEventTime(inner, windowed, keyed, eventTime) {
     return {
       strategy: 'rolling',
       source: operand.source,
-      spec,
+      spec: kernelSpec,
       member: eventTime.member,
       width: span.width,
       eventTime,
@@ -236,7 +245,7 @@ export function classifyEventTime(inner, windowed, keyed, eventTime) {
   return {
     strategy: 'bucket',
     source: operand.source,
-    spec,
+    spec: kernelSpec,
     member: eventTime.member,
     ladder,
     fill,

package/src/live.js

@@ -79,12 +79,22 @@ function unwrapDocument(document) {
   return { inner: doc, whole, windowed, offset, limit, aggregate };
 }
 
+/** Whether a `$for` source is the whole collection: the bare `$[*]`, or
+ * its packed spelling `["$[*]"]` — one array item a `$for` unpacks back
+ * into the rows, which is how `@jarenjs/linq` binds every source so an
+ * array-valued row stays one item. Over a collection the two are the
+ * same rows (the planner reads through the packing the same way). */
+function isWholeCollection(source) {
+  return source === '$[*]'
+    || (Array.isArray(source) && source.length === 1 && source[0] === '$[*]');
+}
+
 /** The single for-binding name of a canonical flwor, or null. */
 function bindingNameOf(inner) {
   if (!isJsonObject(inner) || !isJsonObject(inner.$for)) return null;
   const names = Object.keys(inner.$for);
   if (names.length !== 1) return null;
-  return inner.$for[names[0]] === '$[*]' ? names[0] : null;
+  return isWholeCollection(inner.$for[names[0]]) ? names[0] : null;
 }
 
 /** The whole-documents read behind a flwor: same binding, same

package/src/maintenance.js

@@ -0,0 +1,175 @@
+//@ts-check
+/**
+ * @file The maintenance surface: the four operations an operator runs
+ * on a production SQLite database — a WAL checkpoint, an integrity
+ * check, a foreign-key check and `PRAGMA optimize` — as typed store
+ * operations. Each runs under the store gate (so it never interleaves
+ * an in-flight write), returns SQLite's own answer as typed data, and
+ * is refused by code (`JD2077`) exactly where the capability report
+ * says it is unavailable: a driver whose binding does not declare it,
+ * or — for the two that write — a read-only store, on which the engine
+ * would otherwise answer a checkpoint with a silent no-op.
+ *
+ * Nothing here interprets the engine's numbers. A checkpoint answers
+ * the row `PRAGMA wal_checkpoint` returns, so a store that is not in
+ * WAL mode reports `-1` frames as the engine does; a second passive
+ * checkpoint reports the same frame counts as the first (the frames
+ * stay in the log until a writer restarts it) and a second `truncate`
+ * reports zeros; an integrity check answers `ok: true` for the single
+ * `ok` row and the engine's problem rows verbatim otherwise — corruption
+ * is the RESULT, never a throw. Only a driver failure throws (`JD2078`).
+ */
+
+import { DbRuntimeError, wrapDriverError } from './errors.js';
+import { chain, attempt } from './driver.js';
+import { refuseCancelled } from './cancellation.js';
+
+/** The checkpoint modes `PRAGMA wal_checkpoint` accepts, closed. */
+export const CHECKPOINT_MODES = Object.freeze(['passive', 'full', 'restart', 'truncate']);
+
+/** The operations, in the order the capability report lists them. */
+export const MAINTENANCE_OPERATIONS = Object.freeze(
+  ['checkpoint', 'integrityCheck', 'foreignKeyCheck', 'optimize']);
+
+/** The two operations that write, refused on a read-only store. */
+const WRITES = new Set(['checkpoint', 'optimize']);
+
+/**
+ * The driver failure wrap: an error that already carries a code is the
+ * error; the driver's own failure becomes `JD2078` with the original as
+ * `cause`.
+ * @param {string} operation
+ * @returns {(error: any) => Error}
+ */
+const failed = (operation) => (error) => wrapDriverError(error,
+  { code: 'JD2078', reason: `the maintenance operation '${operation}' failed`, always: true });
+
+/**
+ * The per-operation capability booleans of one store: the binding's
+ * declaration, and for the writing operations the store's read-only
+ * flag as well — the report says `false` exactly where a call is
+ * refused.
+ * @param {Readonly<Record<string, boolean>> | undefined} declared - the
+ *   connection's `capabilities.maintenance`
+ * @param {boolean} readOnly
+ * @returns {Readonly<Record<string, boolean>>}
+ */
+export function maintenanceCapabilities(declared, readOnly) {
+  /** @type {Record<string, boolean>} */
+  const out = {};
+  for (const operation of MAINTENANCE_OPERATIONS) {
+    out[operation] = declared?.[operation] === true && !(readOnly && WRITES.has(operation));
+  }
+  return Object.freeze(out);
+}
+
+/**
+ * Build the maintenance operations over a connection. The caller owns
+ * the gate: every operation here is value-or-promise and issues its
+ * statements wherever the connection routes them.
+ * Every operation takes `{ signal, deadline }` and checks them once,
+ * before the one statement it issues — the granularity the driver has
+ * (`JD2081` for an abort, `JD2075` for a passed deadline, on the clock
+ * the store was opened with).
+ * @param {{ connection: any, readOnly: boolean, now: () => number }} context
+ * @returns {{ capabilities: Readonly<Record<string, boolean>>,
+ *   checkpoint: (options?: { mode?: string, signal?: AbortSignal, deadline?: number }) => any,
+ *   integrityCheck: (options?: { limit?: number, signal?: AbortSignal, deadline?: number }) => any,
+ *   foreignKeyCheck: (options?: { signal?: AbortSignal, deadline?: number }) => any,
+ *   optimize: (options?: { signal?: AbortSignal, deadline?: number }) => any }}
+ */
+export function createMaintenance({ connection, readOnly, now }) {
+  const dialect = connection.dialect;
+  const capabilities = maintenanceCapabilities(connection.capabilities.maintenance, readOnly);
+
+  /** The cancellation check before an operation's statement.
+   * @param {any} options @param {string} operation */
+  const callable = (options, operation) => refuseCancelled(options, now,
+    { abortCode: 'JD2081', aborted: `'${operation}' ran`, passed: `'${operation}' ran` });
+
+  /** @param {string} operation */
+  const require = (operation) => {
+    if (capabilities[operation] === true) return;
+    throw new DbRuntimeError('JD2077',
+      readOnly && WRITES.has(operation) && connection.capabilities.maintenance?.[operation] === true
+        ? `the maintenance operation '${operation}' is unavailable on a read-only store: it writes`
+        : `the maintenance operation '${operation}' is unavailable on this store: the driver's `
+          + 'binding does not declare it');
+  };
+
+  /** Run one pragma statement and answer its rows, driver failures wrapped.
+   * @param {string} operation @param {string} sql */
+  const rows = (operation, sql) => attempt(
+    () => chain(connection.prepare(sql), (statement) => statement.all([])),
+    failed(operation));
+
+  return {
+    capabilities,
+    /**
+     * `PRAGMA wal_checkpoint(<mode>)`: the engine's row, typed. `busy`
+     * is whether the checkpoint could not complete because a reader or
+     * writer held it; the frame counts are the engine's (`-1` when the
+     * database is not in WAL mode).
+     * @param {{ mode?: string, signal?: AbortSignal, deadline?: number }} [options]
+     */
+    checkpoint(options = undefined) {
+      const mode = options?.mode ?? 'passive';
+      if (typeof mode !== 'string' || !CHECKPOINT_MODES.includes(mode)) {
+        throw new TypeError(`checkpoint: mode is one of ${
+          CHECKPOINT_MODES.map((m) => `'${m}'`).join(', ')}, got ${JSON.stringify(mode)}`);
+      }
+      callable(options, 'checkpoint');
+      require('checkpoint');
+      return chain(rows('checkpoint', dialect.pragma.walCheckpoint(mode)), (answer) => {
+        const row = answer[0] ?? {};
+        return {
+          busy: Number(row.busy) === 1,
+          logFrames: Number(row.log ?? -1),
+          checkpointedFrames: Number(row.checkpointed ?? -1),
+        };
+      });
+    },
+    /**
+     * `PRAGMA integrity_check(<limit>)`: `ok` for the single `ok` row,
+     * otherwise the engine's problem rows verbatim. Corruption is the
+     * result, not a throw.
+     * @param {{ limit?: number, signal?: AbortSignal, deadline?: number }} [options]
+     */
+    integrityCheck(options = undefined) {
+      const limit = options?.limit;
+      if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1)) {
+        throw new TypeError(`integrityCheck: limit is a positive integer, got ${JSON.stringify(limit)}`);
+      }
+      callable(options, 'integrityCheck');
+      require('integrityCheck');
+      return chain(rows('integrityCheck', dialect.pragma.integrityCheck(limit)), (answer) => {
+        const problems = answer.map((row) => String(Object.values(row)[0]));
+        const ok = problems.length === 1 && problems[0] === 'ok';
+        return { ok, problems: ok ? [] : problems };
+      });
+    },
+    /** `PRAGMA foreign_key_check`: every violating row, typed.
+     * @param {{ signal?: AbortSignal, deadline?: number }} [options] */
+    foreignKeyCheck(options = undefined) {
+      callable(options, 'foreignKeyCheck');
+      require('foreignKeyCheck');
+      return chain(rows('foreignKeyCheck', dialect.pragma.foreignKeyCheck()), (answer) => ({
+        ok: answer.length === 0,
+        violations: answer.map((row) => ({
+          table: String(row.table),
+          rowId: row.rowid === null || row.rowid === undefined ? null : Number(row.rowid),
+          parent: String(row.parent),
+          fkid: Number(row.fkid),
+        })),
+      }));
+    },
+    /** `PRAGMA optimize`: the engine answers no rows, so the honest
+     * result is that it ran — no invented statistics.
+     * @param {{ signal?: AbortSignal, deadline?: number }} [options] */
+    optimize(options = undefined) {
+      callable(options, 'optimize');
+      require('optimize');
+      return chain(rows('optimize', dialect.pragma.optimize()), () => ({ ran: true }));
+    },
+  };
+}