@jarenjs/db 0.34.0

package/src/entity.js

@@ -0,0 +1,367 @@
+//@ts-check
+/**
+ * @file Entity sets: create / read by key / update / delete over the
+ * hybrid mapping. The physical row is the mapped scalar columns, the
+ * foreign-key columns, and one JSONB `doc` column for everything
+ * else; a write SPLITS the completed document along the mapping and a
+ * read MERGES it back. Defaults apply in JavaScript before validation
+ * — the value the application sees and the value stored are the same
+ * — and identity follows the declared strategy (caller, uuid, auto).
+ *
+ * Epoch date columns are DERIVED: the document keeps the RFC 3339
+ * string, the column carries `getEpochOf…RFC3339(value)` so range
+ * predicates are index-friendly; reads take the string from the
+ * document and skip the derived column.
+ */
+
+import { compileJsonQuery } from '@jarenjs/json/query';
+import {
+  getEpochOfDateTimeRFC3339, getEpochOfDateOnlyRFC3339,
+} from '@jarenjs/core/dates/rfc3339';
+
+import { DbRuntimeError } from './errors.js';
+import { chain } from './driver.js';
+
+/**
+ * The write/read machinery for one entity, prepared once.
+ * @param {any} connection
+ * @param {any} entity - the normalized entity (model.js)
+ * @param {any} entityMapping - `explainMapping(...).entities[name]`
+ * @param {((doc: any) => any) | null} validate
+ * @returns {any}
+ */
+export function entityCore(connection, entity, entityMapping, validate) {
+  const dialect = connection.dialect;
+  const q = dialect.quoteIdentifier;
+  const table = entityMapping.table;
+  const docPath = entity.docPath;
+
+  // the column plan: mapped scalars (epoch ones derived), then FKs;
+  // everything else lives in the JSONB document
+  const scalarColumns = entityMapping.columns.map((column) => ({
+    ...column,
+    epoch: column.source === 'epoch(document)',
+    property: entity.properties.get(column.name),
+  }));
+  // a declared via property is ALREADY a scalar column — the foreign
+  // key adds a column only when no property claims it
+  const scalarNames = new Set(scalarColumns.map((column) => column.name));
+  const fkColumns = entityMapping.foreignKeys
+    .map((fk) => fk.column)
+    .filter((name) => !scalarNames.has(name));
+  const columnNames = [
+    ...scalarColumns.map((column) => column.name),
+    ...fkColumns,
+  ];
+  const columnSet = new Set(columnNames);
+  const keys = entityMapping.keys;
+  const autoKey = keys.length === 1
+    && entity.properties.get(keys[0]).default === 'auto' ? keys[0] : null;
+
+  const epochOf = (property, value) => {
+    if (typeof value !== 'string') return null;
+    // the mapped-instant contract (§10.3): a present string on an
+    // integer date column must parse in the property's own family and
+    // be Z-normalized — an offset form would let the derived epoch
+    // order hours away from the document string the engine compares
+    const dateOnly = property?.format === 'date';
+    const epoch = dateOnly
+      ? getEpochOfDateOnlyRFC3339(value)
+      : getEpochOfDateTimeRFC3339(value);
+    if ((dateOnly || value.endsWith('Z'))
+      && typeof epoch === 'number' && Number.isFinite(epoch)) return epoch;
+    throw new DbRuntimeError('JD2003',
+      `entity '${entity.name}' maps '${property.name}' to an integer date column: `
+      + `the value must be ${dateOnly
+        ? "a 'YYYY-MM-DD' date" : 'a Z-normalized RFC 3339 date-time'}`
+      + ` (got ${JSON.stringify(value)})`,
+      { docPath, collection: entity.name });
+  };
+
+  const relationNames = new Set(
+    [...entity.properties.values()]
+      .filter((property) => property.relation !== undefined)
+      .map((property) => property.name));
+
+  /** Split a completed document into bound column values + the rest.
+   * Relation members are PROJECTIONS (§10.1) — never stored. */
+  const split = (doc) => {
+    const values = [];
+    /** @type {any} */
+    const rest = {};
+    for (const key of Object.keys(doc)) {
+      if (!columnSet.has(key) && !relationNames.has(key)) rest[key] = doc[key];
+    }
+    for (const column of scalarColumns) {
+      if (column.name === autoKey && doc[column.name] === undefined) continue;
+      const value = doc[column.name];
+      if (column.epoch) {
+        // derived: the string stays in the document, the epoch rides
+        // the column
+        rest[column.name] = value;
+        values.push({ name: column.name, value: epochOf(column.property, value) });
+        continue;
+      }
+      values.push({
+        name: column.name,
+        value: value === undefined || value === null
+          ? null
+          : typeof value === 'boolean' ? (value ? 1 : 0) : value,
+      });
+    }
+    for (const fk of fkColumns) {
+      const value = doc[fk];
+      values.push({ name: fk, value: value === undefined || value === null ? null : value });
+    }
+    return { values, rest };
+  };
+
+  /** Merge a row back into a document. */
+  const merge = (row) => {
+    const doc = JSON.parse(row.doc);
+    for (const column of scalarColumns) {
+      if (column.epoch) continue; // the string is already in the doc
+      const value = row[column.name];
+      if (value === null || value === undefined) continue; // absent (§9.3)
+      doc[column.name] = column.storage === 'boolean' ? value === 1 : value;
+    }
+    for (const fk of fkColumns) {
+      const value = row[fk];
+      if (value !== null && value !== undefined) doc[fk] = value;
+    }
+    return doc;
+  };
+
+  // defaults, compiled once
+  const defaulters = [];
+  const updateStamps = [];
+  for (const property of entity.properties.values()) {
+    const declared = property.default;
+    if (declared === undefined || property.relation !== undefined) continue;
+    if (declared === 'now' || declared === 'updated') {
+      defaulters.push({ name: property.name, fill: () => new Date().toISOString() });
+      if (declared === 'updated')
+        updateStamps.push({ name: property.name, fill: () => new Date().toISOString() });
+      continue;
+    }
+    if (declared === 'uuid') {
+      defaulters.push({ name: property.name, fill: () => crypto.randomUUID() });
+      continue;
+    }
+    if (declared === 'auto') continue; // the database allocates
+    if (Object.hasOwn(declared, 'value')) {
+      defaulters.push({ name: property.name, fill: () => structuredClone(declared.value) });
+      continue;
+    }
+    const compiled = compileJsonQuery(declared.query);
+    defaulters.push({ name: property.name, fill: (doc) => compiled(doc) });
+  }
+
+  const applyDefaults = (doc, { updating }) => {
+    const out = { ...doc };
+    for (const { name, fill } of defaulters) {
+      if (out[name] === undefined) out[name] = fill(out);
+    }
+    if (updating) {
+      for (const { name, fill } of updateStamps) out[name] = fill(out);
+    }
+    return out;
+  };
+
+  const checkValid = (doc) => {
+    if (validate === null) return;
+    const outcome = validate(doc);
+    const valid = outcome === true || outcome?.valid === true;
+    if (!valid) {
+      throw new DbRuntimeError('JD2003',
+        `entity '${entity.name}' rejected the document`,
+        Array.isArray(outcome?.errors)
+          ? { docPath, collection: entity.name, errors: outcome.errors }
+          : { docPath, collection: entity.name });
+    }
+  };
+
+  // prepared statements, built lazily from the column plan
+  /** @type {Map<string, any>} */
+  const statements = new Map();
+  const prepared = (name, sql) => {
+    let statement = statements.get(name);
+    if (statement === undefined) {
+      statement = connection.prepare(sql);
+      statements.set(name, statement);
+    }
+    return statement;
+  };
+  const parameterAt = (i) => dialect.parameterRef(i, 'v');
+  const keyWhere = (offset) => keys
+    .map((key, i) => `${q(key)} = ${parameterAt(offset + i + 1)}`).join(' AND ');
+  const selectColumns = [
+    ...scalarColumns.filter((column) => !column.epoch).map((column) => q(column.name)),
+    ...fkColumns.map((column) => q(column)),
+    `${dialect.jsonText(q('doc'))} AS ${q('doc')}`,
+  ].join(', ');
+
+  const insertSqlFor = (names) => {
+    const withDoc = [...names, 'doc'];
+    const refs = withDoc.map((name, i) => (name === 'doc'
+      ? dialect.jsonEncode(parameterAt(i + 1))
+      : parameterAt(i + 1)));
+    const returning = autoKey !== null && !names.includes(autoKey)
+      ? ` RETURNING ${q(autoKey)} AS ${q('key')}`
+      : '';
+    return `INSERT INTO ${q(table)} (${withDoc.map(q).join(', ')}) `
+      + `VALUES (${refs.join(', ')})${returning}`;
+  };
+
+  const normalizeKeyArg = (key) => {
+    if (keys.length === 1) {
+      if (typeof key === 'string' || typeof key === 'number') return [key];
+      if (key !== null && typeof key === 'object' && !Array.isArray(key)
+        && typeof key[keys[0]] !== 'object' && key[keys[0]] !== undefined)
+        return [key[keys[0]]];
+    }
+    else if (key !== null && typeof key === 'object' && !Array.isArray(key)) {
+      const parts = keys.map((name) => key[name]);
+      if (parts.every((part) => typeof part === 'string' || typeof part === 'number'))
+        return parts;
+    }
+    throw new DbRuntimeError('JD2002',
+      keys.length === 1
+        ? 'an entity key must be a scalar'
+        : `a composite key needs { ${keys.join(', ')} }`,
+      { docPath, collection: entity.name });
+  };
+
+  const wrapWrite = (error, key) => {
+    if (/** @type {any} */ (error)?.code === 'JD2003') return error;
+    return new DbRuntimeError('JD2005',
+      `the database rejected the operation: ${/** @type {any} */ (error)?.message ?? String(error)}`,
+      key === undefined
+        ? { docPath, collection: entity.name, cause: error }
+        : { docPath, collection: entity.name, key, cause: error });
+  };
+
+  const columnByName = new Map(scalarColumns.map((column) => [column.name, column]));
+  /** Encode ONE column assignment the way {@link split} would. */
+  const encodeColumn = (name, value) => {
+    const column = columnByName.get(name);
+    if (column !== undefined && column.epoch)
+      return value === undefined ? null : epochOf(column.property, value);
+    if (value === undefined || value === null) return null;
+    return typeof value === 'boolean' ? (value ? 1 : 0) : value;
+  };
+
+  return {
+    // the unit-of-work exposure (tracker.js): the column plan and the
+    // completion/validation/stamping machinery, one source of truth
+    plan: {
+      table,
+      keys,
+      autoKey,
+      version: entity.version ?? null,
+      scalarColumns,
+      fkColumns,
+      columnSet,
+      split,
+      merge,
+      encodeColumn,
+    },
+    complete: (doc, { updating }) => {
+      const completed = applyDefaults(doc, { updating });
+      checkValid(completed);
+      return completed;
+    },
+    validateOnly: (doc) => checkValid(doc),
+    stampUpdated: (doc) => {
+      if (updateStamps.length === 0) return doc;
+      const out = { ...doc };
+      for (const { name, fill } of updateStamps) out[name] = fill(out);
+      return out;
+    },
+    normalizeKey: (key) => normalizeKeyArg(key),
+    create(doc) {
+      for (const name of relationNames) {
+        const value = doc?.[name];
+        if (value !== undefined && (!Array.isArray(value) || value.length > 0)) {
+          throw new DbRuntimeError('JD2003',
+            `'${name}' is a relation member — create() stores no `
+            + 'projections; use the unit of work for membership',
+            { docPath, collection: entity.name });
+        }
+      }
+      const completed = applyDefaults(doc, { updating: false });
+      checkValid(completed);
+      const { values, rest } = split(completed);
+      const names = values.map((value) => value.name);
+      const sql = insertSqlFor(names);
+      return chain(prepared(`insert:${names.join(',')}`, sql), (statement) => {
+        const params = [...values.map((value) => value.value), JSON.stringify(rest)];
+        let out;
+        try {
+          out = autoKey !== null && !names.includes(autoKey)
+            ? statement.get(params)
+            : (statement.run(params), null);
+        }
+        catch (error) {
+          throw wrapWrite(error, completed[keys[0]]);
+        }
+        if (out !== null) return { ...completed, [autoKey]: out.key };
+        return completed;
+      });
+    },
+    get(key) {
+      const parts = normalizeKeyArg(key);
+      const sql = `SELECT ${selectColumns} FROM ${q(table)} WHERE ${keyWhere(0)}`;
+      return chain(prepared('get', sql), (statement) =>
+        chain(statement.get(parts), (row) => (row === undefined ? undefined : merge(row))));
+    },
+    update(key, changes) {
+      const parts = normalizeKeyArg(key);
+      return chain(this.get(key), (current) => {
+        if (current === undefined) {
+          throw new DbRuntimeError('JD2006',
+            `no '${entity.name}' to update under that key`,
+            { docPath, collection: entity.name });
+        }
+        const next = applyDefaults({ ...current, ...changes }, { updating: true });
+        // an explicit update is last-write-wins by contract (§11.2),
+        // but it still moves a declared version token so optimistic
+        // savers see the row changed
+        if (entity.version !== null && entity.version !== undefined)
+          next[entity.version] = (Number(current[entity.version]) || 0) + 1;
+        checkValid(next);
+        const { values, rest } = split(next);
+        const assignments = [
+          ...values.map((value, i) => `${q(value.name)} = ${parameterAt(i + 1)}`),
+          `${q('doc')} = ${dialect.jsonEncode(parameterAt(values.length + 1))}`,
+        ].join(', ');
+        const sql = `UPDATE ${q(table)} SET ${assignments} `
+          + `WHERE ${keyWhere(values.length + 1)}`;
+        return chain(prepared(`update:${values.length}`, sql), (statement) => {
+          try {
+            statement.run([...values.map((value) => value.value),
+              JSON.stringify(rest), ...parts]);
+          }
+          catch (error) {
+            throw wrapWrite(error, parts[0]);
+          }
+          return next;
+        });
+      });
+    },
+    delete(key) {
+      const parts = normalizeKeyArg(key);
+      const sql = `DELETE FROM ${q(table)} WHERE ${keyWhere(0)}`;
+      return chain(prepared('delete', sql), (statement) => {
+        let out;
+        try {
+          out = statement.run(parts);
+        }
+        catch (error) {
+          throw wrapWrite(error, parts[0]);
+        }
+        return chain(out, (result) => Number(result?.changes ?? 0) > 0);
+      });
+    },
+  };
+}

package/src/errors.js

@@ -0,0 +1,173 @@
+//@ts-check
+/**
+ * @file Error types for @jarenjs/db, built on `@jarenjs/core`'s coded
+ * contract: every failure carries a stable `code` (JD0xxx compile-time,
+ * JD2xxx runtime), a bare `reason`, a composed `message`, and — where a
+ * position in the model document exists — a `docPath`. Runtime errors
+ * additionally carry the `collection` and, where one exists, the `key`
+ * as own properties. Database errors are wrapped, never leaked raw: the
+ * reason keeps the original text, `cause` keeps the original error. The
+ * normative table lives in docs/MODEL-FORMAT.md §7, proven in sync with
+ * `DB_CODES` below by a test.
+ */
+
+import { CodedError } from '@jarenjs/core/errors';
+
+/**
+ * The runtime code table (the `CSV_CODES` shape): one entry per code
+ * this package can raise, proven in sync with MODEL-FORMAT.md §7's
+ * normative table by a test.
+ */
+export const DB_CODES = Object.freeze({
+  JD0001: 'the SQLite library is below the supported floor',
+  JD0002: 'the declared model disagrees with the existing database',
+  JD0003: 'the driver binding is unavailable on this runtime',
+  JD0004: 'an index path is not a singular member selection',
+  JD0005: 'the model document is invalid',
+  JD0010: 'strict mode refused a residual',
+  JD0011: 'the profile refused the document',
+  JD0012: 'work waited too long for the open transaction to settle',
+  JD0030: 'an unknown x-entity member was declared',
+  JD0031: 'relation declarations contradict each other',
+  JD0032: 'the include specification is invalid',
+  JD0040: 'the save spans a relation cycle',
+  JD0050: 'live queries require change capture',
+  JD0051: 'the demanded live mode is unavailable',
+  JD0052: 'the live-query bound was reached',
+  JD0020: "the migration's from-shape does not match the database",
+  JD0021: 'the migration is missing a required data transform',
+  JD0022: 'an applied migration disagrees with the history record',
+  JD0023: 'a migration step failed',
+  JD2001: 'insert found the key already present',
+  JD2002: 'a usable key could not be resolved for the write',
+  JD2003: 'the write failed schema validation',
+  JD2004: 'an undeclared collection was requested',
+  JD2005: 'a database operation failed',
+  JD2006: 'patch found no document at the key',
+  JD2007: 'the result exceeded the profile row bound',
+  JD2040: 'the row changed under an optimistic update',
+  JD2050: 'a changeset could not be decoded',
+  JD2051: 'the change log is not enabled',
+  JD2060: 'the maintained live state exceeded its bound',
+  JD2061: 'another context owns the database',
+  JD2062: 'the store closed with job handlers still in flight',
+});
+
+/**
+ * A defect found while opening a store — in the model document, the
+ * declared indexes, the driver binding, or the database's agreement
+ * with the declaration. Codes:
+ *
+ *  - `JD0001` — the SQLite library reported a version below the
+ *    supported floor; the reason names the version found
+ *  - `JD0002` — a declared collection already exists in the database
+ *    with a different shape; nothing was altered — changing shape is
+ *    the migration story, a later capability
+ *  - `JD0003` — the runtime builtin behind a driver could not be
+ *    loaded here (Node cannot resolve `bun:`; Bun ships no
+ *    `node:sqlite`), or an injected handle is missing
+ *  - `JD0004` — an index path does not select exactly one member
+ *    (wildcards, slices, filters and descendants are not indexable);
+ *    the reason names the expression
+ *  - `JD0005` — the model document is invalid; `docPath` points at
+ *    the offending member
+ *  - `JD0010` — `strict: true` and part of the query would have run
+ *    outside the database; the reason names the forcing construct
+ *  - `JD0011` — the active profile refused the document before any
+ *    execution: an undeclared external, host function, collation or
+ *    collection, or a refused full-table scan; the reason names it
+ *  - `JD0030` — an unknown member inside an `x-entity` block; a
+ *    silently ignored mapping directive is a data-loss bug waiting
+ *  - `JD0031` — two relation declarations whose inverses contradict
+ *    (different `via`, impossible `many` pairings)
+ *  - `JD0032` — a graph-load include specification is invalid: an
+ *    unknown relation, a cycle, an untranslatable filter, or the
+ *    depth bound exceeded (the bound is printed, never silent)
+ *  - `JD0040` — `saveChanges()` cannot order its statements: the
+ *    entities being inserted or deleted form a foreign-key cycle
+ *    (self-references included); break the save in two
+ *  - `JD0050` — a live query was registered on a store opened without
+ *    `capture`; the patch stream is the invalidation source
+ *  - `JD0051` — `mode: 'incremental'` was demanded but the document
+ *    classifies as re-run; the reason names the forcing construct
+ *  - `JD0052` — registering would exceed the store's `live.maxQueries`
+ *    bound; the bound is printed, never silent
+ *  - `JD0020` — a migration's `from` hash does not match the
+ *    database's recorded shape; running it would corrupt
+ *  - `JD0021` — a draft transform was not filled in, or a document no
+ *    longer validates after the migration (a narrowing without an
+ *    adequate transform)
+ *  - `JD0022` — the migration list disagrees with the applied history
+ *    (an edited file, a missing file, a reordered sequence)
+ *  - `JD0023` — a step failed: an assertion returned rows, DDL was
+ *    rejected, or a transform produced an unstorable value
+ */
+export class DbCompileError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed per
+   *   the coded contract.
+   * @param {string} [docPath] - JSON Pointer into the model document,
+   *   where one exists.
+   * @param {Error} [cause]
+   */
+  constructor(code, reason, docPath, cause) {
+    super('DbCompileError', code, reason, docPath,
+      cause !== undefined ? { cause } : undefined);
+  }
+}
+
+/**
+ * A failure while reading or writing an open store. Codes:
+ *
+ *  - `JD2001` — `insert` hit a document already stored under the key
+ *  - `JD2002` — the declared key pointer resolved to nothing or to a
+ *    non-scalar, or an explicit key argument is not a string or number
+ *  - `JD2003` — the injected validation hook rejected the document
+ *    that a write would have stored; `errors` carries the hook's
+ *    findings when it produced any
+ *  - `JD2004` — `collection()` named a collection the model does not
+ *    declare
+ *  - `JD2005` — the database rejected an operation for a reason that
+ *    is not a duplicate key; the original error is the `cause`
+ *  - `JD2006` — `patch` addressed a key with no stored document
+ *  - `JD2007` — a fetch crossed the profile's `maxRows` bound; the
+ *    result is refused whole, never silently truncated
+ *  - `JD2040` — an optimistic update or delete matched no row: the
+ *    declared version changed under the save (or the row is gone);
+ *    the error names the entity and key, and the whole save rolled
+ *    back
+ *  - `JD2050` — a session changeset carried bytes this decoder does
+ *    not recognise (a future SQLite format change would land here)
+ *  - `JD2051` — `changesSince` was called on a store whose capture
+ *    has no persisted log
+ *  - `JD2060` — maintenance crossed the live query's `maxMaintained`
+ *    bound; the query delivered this error and closed rather than
+ *    degrade
+ *  - `JD2061` — a second context tried to open a database whose
+ *    storage grants one context exclusive access (the owner topology
+ *    of LIVE-FORMAT §11); connect to the owner instead
+ */
+export class DbRuntimeError extends CodedError {
+  /**
+   * @param {string} code
+   * @param {string} reason - The bare reason; `message` is composed per
+   *   the coded contract.
+   * @param {{ docPath?: string, collection?: string,
+   *   key?: string | number, errors?: unknown[], cause?: unknown }} [details]
+   *   - `docPath` points into the model document (the collection the
+   *   failure belongs to); `collection`/`key` are installed as own
+   *   properties; `errors` carries validation findings; `cause` follows
+   *   the coded contract's `hasOwn` form.
+   */
+  constructor(code, reason, details = undefined) {
+    super('DbRuntimeError', code, reason,
+      details?.docPath !== undefined ? { docPath: details.docPath } : undefined,
+      details !== undefined && Object.hasOwn(details, 'cause')
+        ? { cause: details.cause }
+        : undefined);
+    if (details?.collection !== undefined) this.collection = details.collection;
+    if (details?.key !== undefined) this.key = details.key;
+    if (details?.errors !== undefined) this.errors = details.errors;
+  }
+}

package/src/graph.js

@@ -0,0 +1,101 @@
+//@ts-check
+/**
+ * @file Row → entity-graph reconstruction. One place owns the merge
+ * discipline (§9.3): mapped scalar columns fold back into the JSONB
+ * document's parse (booleans un-integer, SQL NULL reads back ABSENT,
+ * derived epoch columns are skipped because the string never left the
+ * document), foreign-key columns fold in the same way, and — for the
+ * one-statement graph loads — projected relation JSON parses
+ * recursively into child arrays or single children.
+ */
+
+/**
+ * Merge one database row back into its entity document.
+ * @param {any} entityMapping - `explainMapping(...).entities[name]`
+ * @param {any} row - a row carrying the entity's columns plus the
+ *   rendered document text
+ * @param {string} [docField] - the column the document text rides in
+ * @returns {any}
+ */
+export function mergeEntityRow(entityMapping, row, docField = 'doc') {
+  const doc = JSON.parse(row[docField]);
+  for (const column of entityMapping.columns) {
+    if (column.source === 'epoch(document)') continue;
+    const value = row[column.name];
+    if (value === null || value === undefined) continue;
+    doc[column.name] = column.storage === 'boolean' ? value === 1 : value;
+  }
+  for (const fk of entityMapping.foreignKeys) {
+    const value = row[fk.column];
+    if (value !== null && value !== undefined) doc[fk.column] = value;
+  }
+  return doc;
+}
+
+/**
+ * Parse one graph-load row: the root entity's merge plus every
+ * included relation's projected JSON, recursively.
+ * @param {any} node - the include-plan node
+ *   `{ entityMapping, includes: { name, field, many, count, child }[] }`
+ * @param {any} row
+ * @param {string} docField
+ * @returns {any}
+ */
+export function parseGraphRow(node, row, docField = '__doc') {
+  const doc = mergeEntityRow(node.entityMapping, row, docField);
+  for (const include of node.includes) {
+    const raw = row[include.field];
+    if (include.count === true) {
+      doc[include.name] = Number(raw ?? 0);
+      continue;
+    }
+    if (raw === null || raw === undefined) {
+      doc[include.name] = include.many ? [] : null;
+      continue;
+    }
+    const parsed = JSON.parse(raw);
+    doc[include.name] = include.many
+      ? parsed.map((child) => parseGraphChild(include.child, child))
+      : parseGraphChild(include.child, parsed);
+  }
+  return doc;
+}
+
+/**
+ * A child arrives as a plain object (json_object projection): columns
+ * under their names, the document under `__doc` — embedded as real
+ * JSON, because json() carries the JSON subtype into json_object —
+ * and nested includes under their fields.
+ * @param {any} node
+ * @param {any} child
+ * @returns {any}
+ */
+function parseGraphChild(node, child) {
+  const doc = typeof child.__doc === 'string' ? JSON.parse(child.__doc) : child.__doc;
+  for (const column of node.entityMapping.columns) {
+    if (column.source === 'epoch(document)') continue;
+    const value = child[column.name];
+    if (value === null || value === undefined) continue;
+    doc[column.name] = column.storage === 'boolean' ? value === 1 : value;
+  }
+  for (const fk of node.entityMapping.foreignKeys) {
+    const value = child[fk.column];
+    if (value !== null && value !== undefined) doc[fk.column] = value;
+  }
+  for (const include of node.includes) {
+    const raw = child[include.field];
+    if (include.count === true) {
+      doc[include.name] = Number(raw ?? 0);
+      continue;
+    }
+    if (raw === null || raw === undefined) {
+      doc[include.name] = include.many ? [] : null;
+      continue;
+    }
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    doc[include.name] = include.many
+      ? parsed.map((grandchild) => parseGraphChild(include.child, grandchild))
+      : parseGraphChild(include.child, parsed);
+  }
+  return doc;
+}