@jarenjs/db 0.34.0

package/src/drivers/wasm.js

@@ -0,0 +1,178 @@
+//@ts-check
+/**
+ * @file The wasm binding: an INJECTED handle behind the driver
+ * contract. This module imports no runtime builtin at all — the host
+ * (a browser, a worker) supplies the SQLite build, and this driver
+ * only adapts it. Every handle method may return a value or a promise;
+ * a main-thread OPFS-backed build is asynchronous and that is exactly
+ * why the public store surface is.
+ *
+ * The injected contract:
+ *
+ *   handle = {
+ *     open(path, options) -> raw | Promise<raw>,
+ *     synchronous?: boolean,           // default false
+ *     declares?: { userFunctions?, deterministicIndexableFunctions?,
+ *                  sessions? }         // default all false
+ *   }
+ *   raw = { exec(sql), prepare(sql) -> { run, get, all, iterate? },
+ *           close(), registerFunction?, registerAggregate?, session? }
+ *
+ * Capability truth still comes from the probe: whatever the handle
+ * declares is intersected with what the loaded library actually
+ * compiled in.
+ */
+
+import { chain, openConnection } from '../driver.js';
+import { sqliteDialect } from '../dialects/sqlite.js';
+import { DbCompileError } from '../errors.js';
+
+/**
+ * Adapt an already-constructed `sqlite3.oo1` database (the official
+ * SQLite wasm build's object API) into the raw contract. The oo1 API
+ * is SYNCHRONOUS — wasm SQLite computes in place and the SAH-pool
+ * OPFS VFS does synchronous I/O inside a dedicated worker — which is
+ * exactly what keeps journal capture, live queries and the job queue
+ * working unchanged in a browser.
+ *
+ * Statements are REUSED by the store's prepared caches: every
+ * operation ends in `reset()`, never `finalize()`. oo1 user functions
+ * receive a context pointer first — stripped here — and register
+ * variadic (`arity: -1`), matching the engine's fragment shapes.
+ * @param {any} sqlite3 - the loaded sqlite3 module (for `capi`)
+ * @param {any} db - an `sqlite3.oo1.DB`-shaped database
+ * @returns {any} the raw binding for {@link openConnection}
+ */
+export function adaptOo1Database(sqlite3, db) {
+  return {
+    /** @param {string} sql */
+    exec: (sql) => {
+      db.exec(sql);
+    },
+    /** @param {string} sql */
+    prepare: (sql) => {
+      const statement = db.prepare(sql);
+      const bind = (params) => {
+        statement.reset();
+        if (params.length > 0) statement.bind(params);
+      };
+      return {
+        run: (params = []) => {
+          bind(params);
+          statement.step();
+          statement.reset();
+          return {
+            changes: db.changes(),
+            lastInsertRowid: Number(
+              sqlite3.capi.sqlite3_last_insert_rowid(db)),
+          };
+        },
+        get: (params = []) => {
+          bind(params);
+          const row = statement.step() ? statement.get({}) : undefined;
+          statement.reset();
+          return row;
+        },
+        all: (params = []) => {
+          bind(params);
+          const rows = [];
+          while (statement.step()) rows.push(statement.get({}));
+          statement.reset();
+          return rows;
+        },
+        iterate: (params = []) => {
+          bind(params);
+          return {
+            next() {
+              if (statement.step()) return { done: false, value: statement.get({}) };
+              statement.reset();
+              return { done: true, value: undefined };
+            },
+            return(value) {
+              statement.reset();
+              return { done: true, value };
+            },
+            [Symbol.iterator]() { return this; },
+          };
+        },
+      };
+    },
+    close: () => db.close(),
+    registerFunction: (name, options, fn) => db.createFunction(name,
+      (_context, ...args) => fn(...args),
+      { deterministic: options?.deterministic === true, arity: -1 }),
+  };
+}
+
+/**
+ * Build the injected HANDLE from a loaded sqlite3 module — the D6
+ * recipe: the host loads the wasm build and picks the database class
+ * (`sqlite3.oo1.DB` for `:memory:`, the SAH-pool util's `OpfsSAHPoolDb`
+ * for OPFS persistence), and this package only adapts it.
+ *
+ * `sessions` is deliberately NOT declared even though the canonical
+ * wasm build compiles `ENABLE_SESSION`: this adapter does not yet map
+ * the session C API, so capture runs in the journal mode — stated in
+ * the capability matrix, adapting it is a roadmap item.
+ * @param {any} sqlite3 - the loaded sqlite3 module
+ * @param {{ DbClass?: any }} [handleOptions] - the database class to
+ *   construct (default `sqlite3.oo1.DB`)
+ * @returns {any} a handle for {@link wasmDriver}
+ */
+export function sqlite3Handle(sqlite3, handleOptions) {
+  if (sqlite3 === null || typeof sqlite3 !== 'object'
+    || typeof sqlite3?.oo1?.DB !== 'function') {
+    throw new DbCompileError('JD0003',
+      'sqlite3Handle needs a loaded sqlite3 module exposing oo1.DB');
+  }
+  const DbClass = handleOptions?.DbClass ?? sqlite3.oo1.DB;
+  return {
+    synchronous: true,
+    declares: {
+      userFunctions: true,
+      deterministicIndexableFunctions: true,
+      sessions: false,
+    },
+    /**
+     * @param {string} path
+     * @param {{ readOnly?: boolean }} [options]
+     */
+    open: (path, options) => adaptOo1Database(sqlite3,
+      new DbClass(path ?? ':memory:', options?.readOnly === true ? 'r' : 'c')),
+  };
+}
+
+/**
+ * The wasm driver over an injected handle.
+ * @param {any} handle - The host-supplied SQLite handle (see the file
+ *   header for the contract)
+ * @returns {any}
+ */
+export function wasmDriver(handle) {
+  if (handle === null || typeof handle !== 'object'
+    || typeof handle.open !== 'function') {
+    throw new DbCompileError('JD0003',
+      'wasmDriver needs an injected handle exposing open(path, options)');
+  }
+  return Object.freeze({
+    name: 'wasm-sqlite',
+    dialect: sqliteDialect,
+    /**
+     * @param {string} path
+     * @param {any} [options]
+     * @returns {any}
+     */
+    open: (path, options) => chain(handle.open(path, options), (raw) =>
+      openConnection(raw, {
+        dialect: sqliteDialect,
+        synchronous: handle.synchronous === true,
+        declared: {
+          sessions: handle.declares?.sessions === true,
+          userFunctions: handle.declares?.userFunctions === true,
+          deterministicIndexableFunctions:
+            handle.declares?.deterministicIndexableFunctions === true,
+          aggregateFunctions: handle.declares?.aggregateFunctions === true,
+        },
+      })),
+  });
+}

package/src/emit-model.js

@@ -0,0 +1,208 @@
+//@ts-check
+/**
+ * @file Entity types from models (D17): build an EMIT MODEL DOCUMENT
+ * — the published contract from EMIT-FORMAT.md — that renders entity
+ * interfaces, input variants and the typed-store metadata from the
+ * same model document the runtime validates against.
+ *
+ * The seam (EMIT-FORMAT §4.1, recorded here as the order demanded):
+ * the schema compiler is INJECTED (`options.compile` is
+ * `compileEmitModel` from `@jarenjs/emit`), called with
+ * `extensions: ['x-entity']` so the vocabulary rides the member nodes
+ * verbatim; this module then post-processes the MODEL DOCUMENT —
+ * replacing relation member types with references, flipping
+ * optionality, adding declarations — and never renders a character of
+ * TypeScript itself. Emit stays database-free, db stays
+ * renderer-free, and the injection keeps `@jarenjs/emit` out of db's
+ * dependency graph (the generator script wires the two).
+ *
+ * What the artifact says, deliberately:
+ * - entity interfaces are CLOSED objects (excess-property checking is
+ *   the point of generated types; the runtime validator stays
+ *   authoritative for what a database accepts);
+ * - relation members are optional references — present only when a
+ *   graph load included them; `date-time`/`date` strings carry the
+ *   `DateTime` brand so the linq date operators light up;
+ * - the `<Name>Input` variant makes defaulted and generated members
+ *   optional, drops to-one/to-many relation members (`create`/`add`
+ *   refuse them), and types many-to-many members as key-or-document
+ *   arrays (what `add()` accepts);
+ * - `EntityMetaMap` carries doc/input/key/relations per entity — the
+ *   generic typed-store surface (`@jarenjs/db/typed`) binds to it.
+ */
+
+import { normalizeEntities } from './model.js';
+
+const primitive = (name) => ({ kind: 'primitive', primitive: name });
+const ref = (name) => ({ kind: 'ref', ref: name });
+const arrayOf = (items) => ({ kind: 'array', items });
+const unionOf = (options) => ({ kind: 'union', options });
+const literal = (value) => ({ kind: 'literal', value });
+const member = (name, type, required, doc = []) =>
+  ({ kind: 'member', name, type, required, constraints: [], doc });
+const objectOf = (members) => ({ kind: 'object', members });
+const declaration = (name, type, doc = []) =>
+  ({ kind: 'declaration', name, type, constraints: [], doc });
+
+/** The `DateTime` brand: structurally the linq brand, generated
+ * inline so the artifact stands alone. */
+const DATE_TIME_DECLARATION = declaration('DateTime', {
+  kind: 'intersection',
+  parts: [primitive('string'), objectOf([
+    member('__jarenTag', literal('date-time'), true),
+  ])],
+}, ['An RFC 3339 string branded for the date operators;',
+  'structurally identical to the @jarenjs/linq brand.']);
+
+const keyTypeOf = (entity) => {
+  const parts = entity.keys.map((key) =>
+    primitive(entity.properties.get(key).type === 'string' ? 'string' : 'number'));
+  if (parts.length === 1) return parts[0];
+  return objectOf(entity.keys.map((key, i) => member(key, parts[i], true)));
+};
+
+/**
+ * Build the emit-model document for a model's entities.
+ * @param {any} model - a jaren-model document with `entities`
+ * @param {{ compile: (schema: any, options?: any) => any,
+ *   source?: string, reserved?: string[] }} options - `compile` is
+ *   `compileEmitModel` (injected; see the header)
+ * @returns {any} an EMIT-FORMAT `0.1` model document
+ */
+export function entityEmitModel(model, options) {
+  const compile = options?.compile;
+  if (typeof compile !== 'function')
+    throw new TypeError("entityEmitModel needs { compile: compileEmitModel } injected");
+  const entities = normalizeEntities(model);
+  const entityNames = [...entities.keys()];
+
+  // every entity name, input name and the brand are reserved up front
+  // so nested-shape hints can never steal them
+  const taken = [
+    ...(options?.reserved ?? []),
+    'DateTime', 'Entities', 'EntityInputs', 'EntityMetaMap',
+    ...entityNames,
+    ...entityNames.map((name) => `${name}Input`),
+  ];
+
+  /** @type {any[]} */
+  const declarations = [];
+  let usesDateTime = false;
+
+  for (const entity of entities.values()) {
+    const compiled = compile(entity.schema, {
+      name: entity.name,
+      extensions: ['x-entity'],
+      openObjects: 'closed',
+      reserved: taken.filter((name) => name !== entity.name),
+    });
+    for (const compiledDeclaration of compiled.declarations) {
+      if (!taken.includes(compiledDeclaration.name))
+        taken.push(compiledDeclaration.name);
+    }
+
+    const root = compiled.declarations
+      .find((candidate) => candidate.name === entity.name);
+    const others = compiled.declarations
+      .filter((candidate) => candidate !== root);
+
+    // post-process the entity's own members through the vocabulary
+    for (const memberNode of root.type.members) {
+      const property = entity.properties.get(memberNode.name);
+      if (property === undefined) continue;
+      if (property.relation !== undefined) {
+        // the seam is load-bearing: a relation member is DETECTED by
+        // the preserved keyword, resolved through the normalized model
+        if (memberNode.extensions?.['x-entity']?.relation === undefined) continue;
+        const relation = property.relation;
+        const target = ref(relation.to);
+        memberNode.type = relation.kind === 'oneToOne' ? target : arrayOf(target);
+        memberNode.required = false;
+        memberNode.doc = [
+          `The ${relation.kind} relation to ${relation.to}; present only`,
+          'when a graph load included it.'];
+        continue;
+      }
+      if (property.type === 'string'
+        && (property.format === 'date-time' || property.format === 'date')) {
+        memberNode.type = ref('DateTime');
+        usesDateTime = true;
+      }
+      if (property.version) {
+        memberNode.doc = ['The optimistic-concurrency token (§11.5):',
+          'engine-owned, bumped on every successful write.'];
+      }
+    }
+
+    // the input variant: defaulted/generated members optional, to-one
+    // and to-many members gone, many-to-many as key-or-document arrays
+    const inputMembers = [];
+    for (const memberNode of root.type.members) {
+      const property = entity.properties.get(memberNode.name);
+      if (property?.relation !== undefined) {
+        if (property.relation.kind !== 'manyToMany') continue;
+        const target = entities.get(property.relation.to);
+        inputMembers.push(member(memberNode.name,
+          arrayOf(unionOf([keyTypeOf(target), ref(property.relation.to)])),
+          false,
+          ['Membership rows to attach: target keys or documents.']));
+        continue;
+      }
+      const inputMember = {
+        ...memberNode,
+        // a DateTime read is a plain string write: the brand
+        // discriminates expressions, never blocks a caller's literal
+        type: memberNode.type.ref === 'DateTime' ? primitive('string') : memberNode.type,
+        required: property?.default !== undefined
+          ? false
+          : memberNode.required,
+      };
+      if (property?.default !== undefined) {
+        inputMember.doc = [`Defaulted (${JSON.stringify(property.default)});`,
+          'optional for a caller, present after the write.'];
+      }
+      inputMembers.push(inputMember);
+    }
+
+    declarations.push(...others, root,
+      declaration(`${entity.name}Input`, objectOf(inputMembers),
+        [`What create()/add() accept for ${entity.name}: defaulted and`,
+          'generated members are optional; relation projections are not',
+          'writable (many-to-many membership arrays are).']));
+  }
+
+  // the metadata the generic typed store binds to
+  const metaFor = (entity) => objectOf([
+    member('doc', ref(entity.name), true),
+    member('input', ref(`${entity.name}Input`), true),
+    member('key', keyTypeOf(entity), true),
+    member('relations', objectOf(
+      [...entity.properties.values()]
+        .filter((property) => property.relation !== undefined)
+        .map((property) => member(property.name, objectOf([
+          member('entity', literal(property.relation.to), true),
+          member('doc', ref(property.relation.to), true),
+          member('many', literal(property.relation.kind !== 'oneToOne'), true),
+        ]), true))), true),
+  ]);
+  declarations.push(
+    declaration('Entities',
+      objectOf(entityNames.map((name) => member(name, ref(name), true))),
+      ['Entity name to document shape.']),
+    declaration('EntityInputs',
+      objectOf(entityNames.map((name) => member(name, ref(`${name}Input`), true))),
+      ['Entity name to input shape.']),
+    declaration('EntityMetaMap',
+      objectOf(entityNames.map((name) => member(name, metaFor(entities.get(name)), true))),
+      ['The typed-store binding: pass this to TypedStore<…> from',
+        "'@jarenjs/db/typed'."]));
+
+  if (usesDateTime) declarations.unshift(DATE_TIME_DECLARATION);
+
+  return {
+    $emit: '0.1',
+    source: options?.source ?? null,
+    root: null,
+    declarations,
+  };
+}