@jarenjs/db 0.84.3 → 0.85.0

package/src/query.js

@@ -34,7 +34,7 @@
 import { physicalSelection, columnCodec } from './physical.js';
 
 import { createSemanticCache } from '@jarenjs/core/cache';
-import { analyzeQuery } from '@jarenjs/json/query';
+import { analyzeQuery, JsonQueryRuntimeError } from '@jarenjs/json/query';
 
 import { DbCompileError, DbRuntimeError, wrapDriverError, classifyDriverError } from './errors.js';
 import { chain, attempt, isThenable } from './driver.js';
@@ -1653,7 +1653,7 @@ export function createEntityQueryEngine(context) {
       planned = { ...planned, mode: 'set', plan: null,
         reasons: [{ construct: 'pushdown', reason: BIND_REASONS.pushdown }] };
     }
-    if (planned.plan?.group && dialect.name !== 'sqlite') {
+    if ((planned.plan?.group || planned.plan?.scalarAggregate) && dialect.name !== 'sqlite') {
       planned = { ...planned, mode: 'set', plan: null,
         reasons: [{ construct: '$groupby', reason: 'entity grouping runtime guards are qualified for SQLite' }] };
     }
@@ -1872,11 +1872,30 @@ export function createEntityQueryEngine(context) {
     // the database cannot take (a missing external, a boolean, a null,
     // a region with no box) sends the call to the residual, where the
     // ENGINE raises its own error or answers with its own semantics
-    const params = entry.slots.map((slot) => slotValue(slot, externals));
-    if (params.some((value) => !bindable(value)))
+    const diverted = divertReason(entry, externals);
+    if (diverted !== null) {
+      entry.runtimeReason = diverted;
+      if (strict) throw new DbCompileError('JD0010',
+        `strict mode refused a residual: '${diverted.construct}' — ${diverted.reason}`);
+      if (profile?.refuseFullScan) throw profileEntityRefusal(
+        'the profile refuses the decoded scan required by the external binding', '/entities');
       return runResidual(entry, document, externals);
+    }
+    const params = entry.slots.map((slot) => slotValue(slot, externals));
     if (entry.statement === null) entry.statement = connection.prepare(entry.sql, { readOnly: true });
     return chain(guardEntityScan(entry), () => chain(entry.statement, (statement) => {
+      if (entry.planned.plan.scalarAggregate) return chain(statement.get(params), (row) => {
+        admittedRows(entry, row ? [row] : []);
+        if (row?._valid === 0) throw new DbRuntimeError('JD2003', 'an aggregate column refuses a lossy or invalid value');
+        if (row?._nulls > 0) throw new JsonQueryRuntimeError('JQ2001', 'an aggregate requires numbers or strings, got null');
+        if (row?._safe === 0) {
+          entry.runtimeReason = { construct: 'aggregate', reason: 'integer accumulation exceeded its runtime exactness bound' };
+          if (strict) throw new DbCompileError('JD0010', entry.runtimeReason.reason);
+          if (profile?.refuseFullScan) throw profileEntityRefusal('the profile refuses the decoded scan required by integer accumulation', '/entities');
+          return runResidual(entry, document, externals);
+        }
+        return wrapValue(entry, row?.value ?? (entry.planned.plan.aggregate === 'sum' ? 0 : undefined));
+      });
       if (entry.planned.plan.aggregate === 'count')
         return chain(statement.get(params), (row) => { admittedRows(entry, row ? [row] : []); return wrapValue(entry, row?.value ?? 0); });
       return chain(statement.all(params), (rows) => {
@@ -1928,7 +1947,8 @@ export function createEntityQueryEngine(context) {
    */
   const divertReason = (entry, externals) => {
     for (const slot of entry.slots) {
-      if (bindable(slotValue(slot, externals))) continue;
+      const value = slotValue(slot, externals);
+      if (bindable(value) || (slot.nullable === true && value === null)) continue;
       const name = 'external' in slot ? slot.external
         : 'derived' in slot ? (slot.derived.kind === 'bboxAxis' ? slot.derived.external
           : [slot.derived.centre, slot.derived.radius].find((input) => 'external' in input)?.external) : null;
@@ -1949,6 +1969,10 @@ export function createEntityQueryEngine(context) {
    */
   const cursorClass = (entry, externals) => {
     const buffered = (barrier) => ({ streaming: 'buffered', barrier });
+    if (entry.planned.mode === 'native' && externals !== null) {
+      const diverted = divertReason(entry, externals);
+      if (diverted !== null) return buffered(diverted);
+    }
     if (entry.planned.wrapped === true) {
       return buffered({ construct: 'window', reason: BIND_REASONS.wrappedWindow });
     }
@@ -1997,11 +2021,20 @@ export function createEntityQueryEngine(context) {
         + 'entity binding — read it untracked, or return the binding itself');
     }
     const each = register === undefined ? (item) => item : (item) => register(retEntity, item);
+    entry.runtimeReason = null;
     const classified = cursorClass(entry, externals);
+    if (classified.barrier?.construct === 'external') {
+      entry.admitted = { statements: 0, rows: 0, bytes: 0 };
+      entry.runtimeReason = classified.barrier;
+      if (strict) throw new DbCompileError('JD0010',
+        `strict mode refused a residual: 'external' — ${classified.barrier.reason}`);
+      if (profile?.refuseFullScan) throw profileEntityRefusal(
+        'the profile refuses the decoded scan required by the external binding', '/entities');
+    }
     refuseBuffered(options, classified, entities.get(entry.planned.retEntity ?? '')?.docPath);
     const signal = options?.signal;
     const deadline = options?.deadline;
-    if (entry.planned.wrapped === true || entry.planned.plan?.group) {
+    if (entry.planned.wrapped === true || entry.planned.plan?.group || entry.planned.plan?.scalarAggregate) {
       return cursorFactory({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
         materialize: () => chain(execute(document, options), (value) => entry.planned.wrapped === true
           ? [value] : value === undefined ? [] : Array.isArray(value) ? value : [value]) });

package/src/relational-api.js

@@ -0,0 +1,6 @@
+//@ts-check
+/** Lightweight column-first SQLite authoring and execution. */
+export { sql, planRelational, relational } from './dialects/sqlite-relational.js';
+export { defineTable, planTable } from './dialects/sqlite-schema.js';
+export { planTableMigration, applyTableMigration, withForeignKeysSuspended } from './table-migration.js';
+export { sqliteDialect } from './dialects/sqlite.js';

package/src/store.js

@@ -34,7 +34,7 @@ import { refuseUnsupportedPragmaKeys, resolvePragmaRequests, configurePragmas }
 import { createMaintenance } from './maintenance.js';
 import { createBackup } from './backup.js';
 import { normalizeProfile, assertProfileRoots } from './profile.js';
-import { normalizeEntities, explainMapping, joinTableRoots } from './model.js';
+import { compileEntityModel, joinTableRoots } from './model.js';
 import { entityCore } from './entity.js';
 import { verifyPhysical } from './physical.js';
 import { trustedSql, synchronousBody } from './sql.js';
@@ -59,7 +59,8 @@ import {
 } from './expression.js';
 
 /** The model format version this store implements. */
-export const MODEL_VERSION = '0.1';
+import { MODEL_VERSION } from './engine-metadata.js';
+export { MODEL_VERSION };
 
 const COLLECTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const IDENTITIES = new Set(['uuid', 'integer']);
@@ -975,8 +976,9 @@ export function openStore(model, options) {
   let mapping;
   try {
     collections = normalizeModel(model, options.expressions);
-    entities = normalizeEntities(model);
-    mapping = entities.size > 0 ? explainMapping(model) : null;
+    const compiled = compileEntityModel(model);
+    entities = compiled.entities;
+    mapping = entities.size > 0 ? compiled.mapping : null;
     if ([...entities.values()].some((e) => e.physical !== null) && (options.capture || options.replication))
       throw new DbCompileError('JD0051', 'column adoption preserves application triggers; complete capture is not qualified');
     if (options.adopt === true && (options.capture || options.replication))

package/src/table-migration.js

@@ -0,0 +1,158 @@
+//@ts-check
+/** Reviewable SQLite table rebuilds, guarded by the observed physical schema. */
+import { hashContent } from '@jarenjs/core/string';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { DbCompileError } from './errors.js';
+import { defineTable, planTable } from './dialects/sqlite-schema.js';
+import { relationalEmitter, relationalIdentifier as q, sql } from './dialects/sqlite-relational.js';
+import { sqliteDialect as dialect, sqliteTableMigration } from './dialects/sqlite.js';
+import { sqlTokens } from './dialects/check-read.js';
+
+const refuse = (message) => { throw new DbCompileError('JD0021', message); };
+const fingerprint = (v) => canonicalizeJson(v);
+const schema = (connection) => connection.prepare(sqliteTableMigration.schema()).all([]).map((v) => ({ ...v }));
+const createdSql = (text) => text.replace(/^CREATE (TABLE|(?:UNIQUE )?INDEX|TRIGGER) IF NOT EXISTS /i, 'CREATE $1 ');
+const owned = (objects, table) => objects.filter((o) => o.tbl_name === table).map((o) => [o.type, o.name, o.sql]).sort((a, b) => (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+const sync = (connection) => {
+  if (connection.dialect.name !== 'sqlite' || !connection.synchronous || connection.mustQueue) refuse('table migration requires an available synchronous SQLite connection');
+};
+
+/** Inspect a live schema and generate a table plan without changing it.
+ * Rebuilds require explicit opt-in. Unlisted indexes and triggers are preserved.
+ * @param {any} connection @param {any} definition
+ * @param {{id:string,allowRebuild?:boolean,copy?:Record<string,any>,dropColumns?:string[],dropObjects?:string[]}} options */
+export function planTableMigration(connection, definition, options) {
+  sync(connection);
+  if (!options || typeof options.id !== 'string' || !options.id) refuse('table migration requires an id');
+  for (const key of Object.keys(options)) if (!['id', 'allowRebuild', 'copy', 'dropColumns', 'dropObjects'].includes(key)) refuse(`unknown table migration option '${key}'`);
+  if (options.allowRebuild !== undefined && typeof options.allowRebuild !== 'boolean') refuse('allowRebuild must be boolean');
+  if (options.dropColumns !== undefined && (!Array.isArray(options.dropColumns)
+    || options.dropColumns.some((name) => typeof name !== 'string')
+    || new Set(options.dropColumns).size !== options.dropColumns.length)) refuse('dropColumns must be a distinct list of names');
+  const target = defineTable(definition);
+  const source = schema(connection);
+  const before = source.filter((o) => o.tbl_name === target.name);
+  const existing = before.find((o) => o.type === 'table');
+  if (!existing && source.some((o) => o.name === target.name)) refuse('the target name belongs to a non-table schema object');
+  const plan = planTable(target);
+  const after = plan.createSql.map((text, index) => ({
+    type: index === 0 ? 'table' : /^CREATE (?:UNIQUE )?INDEX/.test(text) ? 'index' : 'trigger',
+    name: index === 0 ? target.name : (index <= (target.indexes?.length ?? 0)
+      ? target.indexes[index - 1].name : target.triggers[index - 1 - (target.indexes?.length ?? 0)].name),
+    tbl_name: target.name, sql: createdSql(text),
+  }));
+  const dropObjects = options.dropObjects ?? [];
+  if (!Array.isArray(dropObjects) || new Set(dropObjects).size !== dropObjects.length
+    || dropObjects.some((name) => !before.some((o) => o.name === name && o.type !== 'table') || after.some((o) => o.name === name))) refuse('dropObjects must name distinct existing indexes/triggers absent from the target');
+  const preserved = before.filter((o) => o.type !== 'table' && !dropObjects.includes(o.name) && !after.some((a) => a.name === o.name));
+  after.push(...preserved);
+  const equal = fingerprint(owned(before, target.name)) === fingerprint(owned(after, target.name));
+  const rebuild = !!existing && !equal;
+  if (rebuild && options.allowRebuild !== true) refuse('the table differs; review a plan with allowRebuild:true');
+  const temporary = `_jaren_rebuild_${hashContent(fingerprint([options.id, target.name]))}`;
+  if (source.some((o) => o.name === temporary)) refuse('the rebuild temporary name already exists');
+  const oldColumns = existing ? connection.prepare(dialect.introspect.columns(target.name)).all([]) : [];
+  const oldKey = oldColumns.filter((c) => c.pk > 0).sort((a, b) => a.pk - b.pk).map((c) => c.name);
+  if (rebuild && sqlTokens(existing.sql).some((t) => t.kind === 'word' && t.value.toUpperCase() === 'AUTOINCREMENT')
+    && !target.columns.some((c) => c.identity === 'autoincrement')) refuse('rebuild must preserve AUTOINCREMENT allocation');
+  if (rebuild && (oldKey.length !== (target.primaryKey?.length ?? 0)
+    || oldKey.some((name) => !target.primaryKey.includes(name)))) refuse('rebuild must preserve every primary-key column');
+  const dropped = oldColumns.filter((c) => !target.columns.some((t) => t.name === c.name)).map((c) => c.name);
+  if (fingerprint([...dropped].sort()) !== fingerprint([...(options.dropColumns ?? [])].sort())) refuse('every removed source column needs an explicit dropColumns disposition');
+  const copy = options.copy ?? {};
+  if (!copy || typeof copy !== 'object' || Array.isArray(copy)) refuse('copy must be an assignment object');
+  for (const key of Object.keys(copy)) if (!target.columns.some((c) => c.name === key && c.generated === undefined) || oldKey.includes(key)) refuse('copy targets a writable non-key column');
+  const writable = target.columns.filter((c) => c.generated === undefined
+    && (Object.hasOwn(copy, c.name) || oldColumns.some((old) => old.name === c.name)));
+  if (rebuild && !writable.length) refuse('rebuild needs columns to copy');
+  const names = writable.map((c) => c.name);
+  const expressions = writable.map((c) => Object.hasOwn(copy, c.name) ? copy[c.name] : sql.column(c.name));
+  const unchanged = writable.filter((c) => !Object.hasOwn(copy, c.name)).map((c) => c.name);
+  // Preserve hidden rowids too, including text/composite-key rowid tables.
+  const tableInfo = existing ? connection.prepare(sqliteTableMigration.tableList()).all([]).find((t) => t.schema === 'main' && t.name === target.name) : null;
+  if (rebuild && !!tableInfo.wr !== !!target.withoutRowid) refuse('rebuild cannot change rowid ownership');
+  if (rebuild && !tableInfo.wr && !(oldKey.length === 1 && oldColumns.find((c) => c.name === oldKey[0]).type.toUpperCase() === 'INTEGER')) {
+    const rowid = ['rowid', '_rowid_', 'oid'].find((name) => !oldColumns.some((c) => c.name.toLowerCase() === name)
+      && !target.columns.some((c) => c.name.toLowerCase() === name));
+    if (!rowid) refuse('the source shadows every rowid alias');
+    names.unshift(rowid); expressions.unshift(sql.column(rowid)); unchanged.unshift(rowid);
+  }
+  const emitter = relationalEmitter({ inline: true });
+  const statements = equal ? [] : !existing ? [...plan.createSql] : [
+    planTable({ ...target, name: temporary, indexes: [], triggers: [] }).createSql[0],
+    `INSERT INTO ${q(temporary)} (${names.map(q).join(', ')}) SELECT ${expressions.map((v) => emitter.expr(v)).join(', ')} FROM ${q(target.name)}`,
+  ];
+  const finish = rebuild ? [`DROP TABLE ${q(target.name)}`, `ALTER TABLE ${q(temporary)} RENAME TO ${q(target.name)}`,
+    ...plan.createSql.slice(1), ...preserved.map((o) => o.sql)] : [];
+  const body = { version: 1, id: options.id, table: target.name, source, after, rebuild, temporary, unchanged, statements, finish };
+  return { ...body, checksum: fingerprint(body) };
+}
+
+/** Run a generated plan atomically. A repeated completed plan changes nothing.
+ * A rebuild with enabled foreign keys must start outside a transaction; call
+ * withForeignKeysSuspended for an outer scope containing nested rebuilds.
+ * @param {any} connection @param {ReturnType<typeof planTableMigration>} plan */
+export function applyTableMigration(connection, plan) {
+  sync(connection);
+  const { checksum, ...body } = plan;
+  if (body.version !== 1 || checksum !== fingerprint(body)) refuse('table migration checksum differs');
+  if (fingerprint(owned(schema(connection), plan.table)) === fingerprint(owned(plan.after, plan.table))) return { changed: 0 };
+  const run = () => connection.transaction(() => {
+    const actual = schema(connection);
+    if (fingerprint(owned(actual, plan.table)) === fingerprint(owned(plan.after, plan.table))) return { changed: 0 };
+    if (fingerprint(actual) !== fingerprint(plan.source)) refuse('source schema changed after planning');
+    const sequenceExists = connection.prepare(sqliteTableMigration.sequenceExists()).get([]);
+    const sequence = sequenceExists ? connection.prepare(sqliteTableMigration.sequence()).get([plan.table]) : null;
+    for (const statement of plan.statements) connection.exec(statement);
+    if (plan.rebuild) {
+      const from = q(plan.table), to = q(plan.temporary);
+      const counts = connection.prepare(`SELECT (SELECT count(*) FROM ${from}) AS a,(SELECT count(*) FROM ${to}) AS b`).get([]);
+      if (counts.a !== counts.b) refuse('rebuild changed the row count');
+      if (plan.unchanged.length) {
+        // Both values and storage classes must survive; BINARY prevents
+        // inherited NOCASE from hiding a changed byte sequence.
+        const values = plan.unchanged.flatMap((name) => [`${q(name)} COLLATE BINARY`, `typeof(${q(name)})`]).join(', ');
+        const difference = connection.prepare(`SELECT 1 FROM (SELECT ${values} FROM ${from} EXCEPT SELECT ${values} FROM ${to}) LIMIT 1`).get([]);
+        if (difference) refuse('rebuild changed a preserved value or storage class');
+      }
+    }
+    for (const statement of plan.finish) connection.exec(statement);
+    if (sequence && plan.rebuild) {
+      connection.prepare(sqliteTableMigration.raiseSequence()).run([sequence.seq, plan.table]);
+      connection.prepare(sqliteTableMigration.seedSequence()).run([plan.table, sequence.seq, plan.table]);
+    }
+    if (connection.prepare(dialect.pragma.foreignKeyCheck()).get([])) refuse('migration violates foreign-key references');
+    if (fingerprint(owned(schema(connection), plan.table)) !== fingerprint(owned(plan.after, plan.table))) refuse('migrated schema differs from the reviewed target');
+    return { changed: plan.statements.length + plan.finish.length };
+  }, { mode: 'immediate' });
+  return plan.rebuild ? withForeignKeysSuspended(connection, run) : run();
+}
+
+/** Explicit outer migration scope for SQLite's foreign-key transition.
+ * Always restore the connection settings, including failure and nested scopes.
+ * @param {any} connection @param {() => any} fn @returns {any} */
+export function withForeignKeysSuspended(connection, fn) {
+  sync(connection);
+  if (typeof fn !== 'function' || Object.prototype.toString.call(fn) === '[object AsyncFunction]')
+    refuse('a physical migration scope requires a synchronous callback');
+  const foreignKeys = connection.prepare(dialect.introspect.pragma('foreign_keys')).get([]).foreign_keys;
+  const legacy = connection.prepare(dialect.introspect.pragma('legacy_alter_table')).get([]).legacy_alter_table;
+  try {
+    connection.exec(dialect.pragma.foreignKeys(false));
+    if (connection.prepare(dialect.introspect.pragma('foreign_keys')).get([]).foreign_keys !== 0) refuse('foreign_keys cannot change inside a transaction; establish the outer migration scope first');
+    connection.exec(dialect.pragma.set('legacy_alter_table', 'ON'));
+    return connection.transaction(() => {
+      const result = fn();
+      if (result != null && typeof result.then === 'function') {
+        Promise.resolve(result).catch(() => {});
+        refuse('a physical migration scope must settle synchronously');
+      }
+      if (connection.prepare(dialect.pragma.foreignKeyCheck()).get([])) refuse('migration violates foreign-key references');
+      return result;
+    }, { mode: 'immediate' });
+  }
+  finally {
+    connection.exec(dialect.pragma.set('legacy_alter_table', legacy ? 'ON' : 'OFF'));
+    connection.exec(dialect.pragma.foreignKeys(!!foreignKeys));
+  }
+}

package/types/bun.d.ts

@@ -7,3 +7,6 @@ export declare function bunDriver(): Driver;
 export declare function adaptBunDatabase(db: unknown): unknown;
 /** Construct and adapt from a loaded `bun:sqlite`-shaped module. */
 export declare function fromBunModule(mod: unknown, path: string, options?: unknown): unknown;
+
+/** Disk-backed consistent snapshot; refuses an existing destination. */
+export declare function snapshotDatabase(connection: unknown, target: string): Promise<{ path: string; pages: number }>;

package/types/entity.d.ts

@@ -0,0 +1 @@
+export { entityCore } from './index.js';

package/types/index.d.ts

@@ -602,8 +602,11 @@ export interface UntrackedReads<T = unknown> {
 /** Closed native mutation forms over declared SQLite column layouts. */
 export type EntityMutation = {
   returning?: readonly string[]; maxRows?: number; maxBytes?: number;
-} & ({ op: 'update'; key: EntityKeyArg; expectedRevision?: number; set: Readonly<Record<string, unknown>> }
-  | { op: 'upsert'; values: Readonly<Record<string, unknown>>; conflict: readonly string[]; update: readonly string[] }
+} & ({ op: 'update'; key?: EntityKeyArg; where?: unknown; expectedRevision?: number; set?: Readonly<Record<string, unknown>>;
+    expressions?: Readonly<Record<string, import('./relational.js').SqlInput>>; reporting?: 'matched' | 'changed' }
+  | { op: 'delete'; key?: EntityKeyArg; where?: unknown; expectedRevision?: number }
+  | { op: 'upsert'; values: Readonly<Record<string, unknown>>; conflict: readonly string[]; update?: readonly string[];
+      conflictWhere?: import('./relational.js').SqlInput; onConflict?: 'nothing' | 'update'; reporting?: 'matched' | 'changed' }
   | { op: 'insert-select'; source: string; where?: unknown; select: Readonly<Record<string, string | { $literal: unknown }>>;
       conflict: readonly string[]; onConflict: 'nothing' });
 export interface MutationResult {
@@ -1207,6 +1210,8 @@ export declare const MAINTENANCE_OPERATIONS: readonly string[];
 
 export declare function normalizeEntities(model: unknown): Map<string, unknown>;
 export declare function explainMapping(model: unknown): unknown;
+/** One normalization shared by the entity engine and its physical mapping. */
+export declare function compileEntityModel(model: unknown): { entities: Map<string, unknown>; mapping: unknown };
 /** The relation tables of normalized entities, keyed by entity name
  * then by relation member (MODEL-FORMAT §10.1) — what every entity set
  * exposes as `relations` and every scope carries for all its roots. */
@@ -2037,3 +2042,5 @@ export declare function planInvariants(model: unknown, options: { dialect: Diale
 export declare function planPhysicalMigration(connection: unknown, fromModel: unknown, toModel: unknown,
   options: { id: string; steps: readonly unknown[]; dispositions: Readonly<Record<string, 'preserve' | 'replace' | 'drop'>>;
     assertions?: readonly { sql: string; params?: readonly unknown[]; expected: readonly unknown[] }[] }): unknown;
+
+export { sql, relational, planRelational, defineTable, planTable, planTableMigration, applyTableMigration, withForeignKeysSuspended } from './relational.js';

package/types/model.d.ts

@@ -0,0 +1 @@
+export { normalizeEntities, explainMapping, compileEntityModel, readSchema, introspectModel, INTROSPECT_CODES, relationTables } from './index.js';

package/types/node.d.ts

@@ -88,3 +88,6 @@ export declare function openNullTarget(): DocumentTarget;
 /** Read an explicit collection bundle, materialized under the declared bounds. */
 export declare function readCollectionBundle(source: DocumentByteSource,
   bounds: { maxBytes: number | null; maxRows: number | null }): Promise<Record<string, unknown[]>>;
+
+/** Disk-backed consistent snapshot; refuses an existing destination. */
+export declare function snapshotDatabase(connection: unknown, target: string): Promise<{ path: string; pages: number }>;

package/types/query.d.ts

@@ -0,0 +1,2 @@
+export { createQueryEngine, createQueryState, collectEntityRoots, entityRoot, createEntityQueryEngine, createLoadEngine,
+  INCLUDE_DEPTH_DEFAULT, INCLUDE_ROWS_DEFAULT, INCLUDE_BYTES_DEFAULT } from './index.js';

package/types/relational.d.ts

@@ -0,0 +1,114 @@
+/** Structural SQLite authoring, with explicit native SQL semantics. */
+export type SqlValue = string | number | bigint | Uint8Array | null;
+export type SqlInput = SqlValue | SqlExpression;
+export type SqlOperator = '=' | '<>' | '<' | '<=' | '>' | '>=' | 'IS' | 'IS NOT'
+  | '+' | '-' | '*' | '/' | '%' | '||' | 'AND' | 'OR' | 'LIKE' | 'NOT LIKE' | 'GLOB';
+export type SqlFunction = 'coalesce' | 'nullif' | 'trim' | 'ltrim' | 'rtrim' | 'lower' | 'upper'
+  | 'length' | 'abs' | 'round' | 'typeof' | 'json_extract' | 'json_valid'
+  | 'count' | 'sum' | 'total' | 'avg' | 'min' | 'max'
+  | 'date' | 'time' | 'datetime' | 'julianday' | 'unixepoch' | 'strftime';
+export type SqlType = 'INTEGER' | 'REAL' | 'TEXT' | 'BLOB' | 'NUMERIC';
+export type SqlCollation = 'BINARY' | 'NOCASE' | 'RTRIM';
+export type SqlExpression =
+  | { readonly $sql: 'column'; readonly name: string; readonly table?: string }
+  | { readonly $sql: 'value'; readonly value: SqlValue }
+  | { readonly $sql: 'param'; readonly name: string }
+  | { readonly $sql: 'binary'; readonly op: SqlOperator; readonly left: SqlInput; readonly right: SqlInput }
+  | { readonly $sql: 'not'; readonly value: SqlInput }
+  | { readonly $sql: 'in'; readonly value: SqlInput; readonly values: readonly SqlInput[] | SqlSelect; readonly negate?: boolean }
+  | { readonly $sql: 'call'; readonly name: SqlFunction; readonly args: readonly SqlInput[]; readonly distinct?: boolean }
+  | { readonly $sql: 'cast'; readonly value: SqlInput; readonly type: SqlType }
+  | { readonly $sql: 'collate'; readonly value: SqlInput; readonly collation: SqlCollation }
+  | { readonly $sql: 'case'; readonly branches: readonly { when: SqlInput; then: SqlInput }[]; readonly otherwise?: SqlInput }
+  | { readonly $sql: 'scalar' | 'exists'; readonly query: SqlSelect };
+export interface SqlOrder { readonly by: SqlInput; readonly direction?: 'asc' | 'desc'; readonly nulls?: 'first' | 'last' }
+export type SqlProjection = '*' | Readonly<Record<string, SqlInput>>;
+export type SqlSource = string | { readonly table: string; readonly as?: string } | { readonly query: SqlSelect; readonly as?: string };
+export interface SqlSelect {
+  readonly from?: SqlSource;
+  readonly columns?: SqlProjection;
+  readonly joins?: readonly { source: SqlSource; type?: 'inner' | 'left' | 'cross'; on?: SqlInput }[];
+  readonly where?: SqlInput;
+  readonly groupBy?: readonly SqlInput[];
+  readonly having?: SqlInput;
+  readonly orderBy?: readonly SqlOrder[];
+  readonly distinct?: boolean;
+  readonly limit?: number;
+  readonly offset?: number;
+  readonly union?: readonly SqlSelect[];
+  readonly all?: boolean;
+}
+export type SqlConflict = { readonly target?: readonly (string | SqlExpression)[]; readonly where?: SqlInput } & (
+  { readonly action: 'nothing' } | { readonly action: 'update'; readonly set: Readonly<Record<string, SqlInput>>; readonly updateWhere?: SqlInput });
+export type SqlMutation = { readonly table: string; readonly returning?: SqlProjection } & (
+  | { readonly op: 'update'; readonly set: Readonly<Record<string, SqlInput>>; readonly where: SqlInput; readonly reporting?: 'matched' | 'changed' }
+  | { readonly op: 'delete'; readonly where: SqlInput }
+  | ({ readonly op: 'insert'; readonly conflict?: SqlConflict; readonly ignore?: boolean } & (
+    { readonly values: Readonly<Record<string, SqlInput>> } | { readonly source: SqlSelect; readonly columns: readonly string[] })));
+export interface RelationalOptions { readonly externals?: Readonly<Record<string, SqlValue>> }
+export interface RelationalPlan { readonly sql: string; readonly params: readonly SqlValue[]; readonly access: 'read' | 'write' }
+export interface RelationalMutationResult { readonly affected: number; readonly rows?: readonly Record<string, unknown>[]; readonly lastInsertRowid?: number | bigint }
+export interface RelationalEngine {
+  plan(document: SqlSelect | SqlMutation, options?: RelationalOptions): RelationalPlan;
+  all<T = Record<string, unknown>>(document: SqlSelect, options?: RelationalOptions): T[];
+  get<T = Record<string, unknown>>(document: SqlSelect, options?: RelationalOptions): T | undefined;
+  iterate<T = Record<string, unknown>>(document: SqlSelect, options?: RelationalOptions): IterableIterator<T>;
+  execute(document: SqlMutation, options?: RelationalOptions): RelationalMutationResult;
+}
+export declare const sql: {
+  column(name: string, table?: string): SqlExpression;
+  value(value: SqlValue): SqlExpression;
+  param(name: string): SqlExpression;
+  binary(op: SqlOperator, left: SqlInput, right: SqlInput): SqlExpression;
+  not(value: SqlInput): SqlExpression;
+  in(value: SqlInput, values: readonly SqlInput[] | SqlSelect, negate?: boolean): SqlExpression;
+  call(name: SqlFunction, args: readonly SqlInput[], options?: { distinct?: boolean }): SqlExpression;
+  cast(value: SqlInput, type: SqlType): SqlExpression;
+  collate(value: SqlInput, collation: SqlCollation): SqlExpression;
+  case(branches: readonly { when: SqlInput; then: SqlInput }[], otherwise?: SqlInput): SqlExpression;
+  scalar(query: SqlSelect): SqlExpression;
+  exists(query: SqlSelect): SqlExpression;
+};
+export declare function planRelational(document: SqlSelect | SqlMutation, options?: RelationalOptions): RelationalPlan;
+/** Requires a synchronous SQLite connection; no model is opened. */
+export declare function relational(connection: unknown): RelationalEngine;
+
+export interface TableColumn {
+  readonly name: string; readonly type: SqlType | 'ANY'; readonly nullable?: boolean;
+  readonly default?: SqlInput; readonly collation?: SqlCollation;
+  readonly identity?: 'rowid' | 'autoincrement'; readonly check?: SqlInput;
+  readonly generated?: SqlInput; readonly stored?: boolean;
+}
+export type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+export type TableConstraint = { readonly name?: string } & (
+  { readonly kind: 'unique'; readonly columns: readonly string[] }
+  | { readonly kind: 'check'; readonly expression: SqlInput }
+  | { readonly kind: 'foreignKey'; readonly columns: readonly string[]; readonly table: string; readonly references: readonly string[];
+      readonly onDelete?: ForeignKeyAction; readonly onUpdate?: ForeignKeyAction; readonly deferred?: boolean });
+export interface TableIndex { readonly name: string; readonly terms: readonly Omit<SqlOrder, 'nulls'>[]; readonly unique?: boolean; readonly where?: SqlInput }
+export type TriggerRaise = { readonly raise: { readonly action: 'abort' | 'fail' | 'rollback'; readonly message: string } | { readonly action: 'ignore' } };
+export interface TableTrigger {
+  readonly name: string; readonly timing: 'before' | 'after'; readonly event: 'insert' | 'update' | 'delete';
+  readonly of?: readonly string[]; readonly when?: SqlInput; readonly steps: readonly (SqlMutation | TriggerRaise)[];
+}
+export interface TableDefinition {
+  readonly name: string; readonly columns: readonly TableColumn[]; readonly primaryKey?: readonly string[];
+  readonly constraints?: readonly TableConstraint[]; readonly indexes?: readonly TableIndex[]; readonly triggers?: readonly TableTrigger[];
+  readonly strict?: boolean; readonly withoutRowid?: boolean;
+}
+export interface TablePlan { readonly table: string; readonly createSql: readonly string[]; readonly expected: unknown }
+export declare function defineTable(definition: TableDefinition): TableDefinition;
+export declare function planTable(definition: TableDefinition): TablePlan;
+export interface TableMigrationOptions {
+  readonly id: string; readonly allowRebuild?: boolean; readonly copy?: Readonly<Record<string, SqlInput>>;
+  readonly dropColumns?: readonly string[]; readonly dropObjects?: readonly string[];
+}
+export interface TableMigrationPlan {
+  readonly version: 1; readonly id: string; readonly table: string; readonly checksum: string;
+  readonly source: readonly unknown[]; readonly after: readonly unknown[]; readonly rebuild: boolean;
+  readonly temporary: string; readonly unchanged: readonly string[]; readonly statements: readonly string[]; readonly finish: readonly string[];
+}
+export declare function planTableMigration(connection: unknown, definition: TableDefinition, options: TableMigrationOptions): TableMigrationPlan;
+export declare function applyTableMigration(connection: unknown, plan: TableMigrationPlan): { changed: number };
+export declare function withForeignKeysSuspended<T>(connection: unknown, fn: () => T): T;
+export { sqliteDialect } from './index.js';