@orkestrel/database 0.0.1

package/dist/src/core/helpers.d.ts

@@ -0,0 +1,383 @@
+import type { ContractShape, FieldPath } from '@orkestrel/contract';
+import type { AggregateFunction, ColumnType, ConformanceFinding, Condition, Criteria, DriverInterface, Key, Migration, MigrationStep, Order, Row, TableSchema } from './types.js';
+/**
+ * A total ordering over arbitrary values — the comparator behind sorting and the
+ * range operators.
+ *
+ * @remarks
+ * Values of different types order by a fixed type rank (`undefined` < `null` <
+ * boolean < number < string < other); same-typed values compare naturally.
+ * `NaN` sorts after every other number and equal to itself, so the comparator
+ * is total and never returns `NaN`.
+ *
+ * @param left - The left value
+ * @param right - The right value
+ * @returns `-1`, `0`, or `1`
+ */
+export declare function compareValues(left: unknown, right: unknown): number;
+/**
+ * Structural equality by SameValueZero leaves — the comparator behind conformance
+ * checks and any test/fixture that needs "same data", not "same reference".
+ *
+ * @remarks
+ * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
+ * Arrays compare by index (same length, every element `deepEqual`). Plain
+ * records (via `isRecord`) compare by their OWN enumerable keys: same key
+ * COUNT and, for every key in `left`, `right` has that key (`Object.hasOwn`)
+ * with a `deepEqual` value — so a key present with value `undefined` is NOT
+ * equal to that key being absent (both differ in `Object.keys` membership).
+ * Anything else (functions, class instances, mismatched shapes) falls through
+ * to `false`. There is no cycle detection — a cyclic input recurses forever;
+ * callers pass acyclic data (rows, plans, config).
+ *
+ * @param left - The left value
+ * @param right - The right value
+ * @returns Whether `left` and `right` are structurally equal
+ *
+ * @example
+ * ```ts
+ * deepEqual(Number.NaN, Number.NaN) // true
+ * deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
+ * deepEqual({ a: undefined }, {}) // false — present-undefined ≠ absent
+ * ```
+ */
+export declare function deepEqual(left: unknown, right: unknown): boolean;
+/**
+ * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
+ * engine behind {@link likeMatch} and {@link globMatch}.
+ *
+ * @remarks
+ * A backtracking RegExp (`a%b%c` → `^a.*b.*c$`) is CATASTROPHIC on a hostile pattern:
+ * `.*` segments separated by literals, matched against a long non-matching input, blow
+ * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it
+ * (AGENTS §6.5, now that the authed server runs model-supplied `list` criteria over the
+ * wire). So this builds NO regex. It runs the classic GREEDY TWO-POINTER wildcard match:
+ * the `any` wildcard records its position and, on a later mismatch, backtracks ONLY to
+ * that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
+ * never the exponential / polynomial backtracking a regex would do. The pattern length
+ * is capped at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it),
+ * bounding the pattern factor so a match stays linear in the value length whatever the
+ * pattern.
+ *
+ * The `any` wildcard matches any run (including empty); `single` matches exactly one
+ * char; every other pattern char matches itself LITERALLY (a pattern `.` / `(` / `\` is
+ * a literal — the regex-metacharacter hazard is gone with the regex). `any` is tested
+ * BEFORE a literal match, so a value that literally contains the wildcard char never
+ * shadows the wildcard. Case folding is applied to BOTH sides when `fold` is set.
+ *
+ * @param value - The value to test
+ * @param pattern - The wildcard pattern
+ * @param any - The any-run wildcard char (`%` for `LIKE`, `*` for `GLOB`)
+ * @param single - The single-char wildcard char (`_` for `LIKE`, `?` for `GLOB`)
+ * @param fold - Whether to match case-INSENSITIVELY (`LIKE` folds; `GLOB` does not)
+ * @returns Whether `value` matches `pattern`
+ * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
+ */
+export declare function wildcardMatch(value: string, pattern: string, any: string, single: string, fold: boolean): boolean;
+export declare function likeMatch(value: string, pattern: string): boolean;
+export declare function globMatch(value: string, pattern: string): boolean;
+/**
+ * Evaluate one {@link Condition} against a row — the per-operator predicate.
+ *
+ * @remarks
+ * Reads the condition's column — a `FieldPath`, resolved with `resolveField` (a
+ * string is one column; an array descends a nested value) — and applies the
+ * operator. Range operators use {@link compareValues}; `like` / `glob` / `starts`
+ * / `ends` match only strings; `any` / `none` test membership by value equality.
+ * Total — a type mismatch is simply a non-match.
+ *
+ * @param row - The row to test
+ * @param condition - The condition to apply
+ * @returns Whether the row satisfies the condition
+ */
+export declare function matchesCondition(row: Row, condition: Condition): boolean;
+/**
+ * Fold a row through a list of conditions, joining each by its connector.
+ *
+ * @remarks
+ * Evaluated left-to-right: the first condition seeds the result, and each later
+ * condition combines with `&&` (`and`) or `||` (`or`). An empty list matches
+ * every row. There is no operator precedence — conditions combine in the order
+ * the query builder recorded them.
+ *
+ * @param row - The row to test
+ * @param conditions - The conditions to fold
+ * @returns Whether the row satisfies the combined conditions
+ */
+export declare function matchesCriteria(row: Row, conditions: readonly Condition[]): boolean;
+/**
+ * Filter rows by a list of conditions — the shared basis for a table's count
+ * and aggregate paths (no sort/page, unlike {@link applyCriteria}).
+ *
+ * @remarks
+ * An empty condition list matches every row (returned as-is, no copy). Folds
+ * each row through {@link matchesCriteria}.
+ *
+ * @param rows - The rows to filter
+ * @param conditions - The conditions to apply (empty matches everything)
+ * @returns The matching rows
+ *
+ * @example
+ * ```ts
+ * filterRows(
+ * 	[{ age: 30 }, { age: 12 }],
+ * 	[{ column: 'age', operator: 'above', values: [18], connector: 'and' }],
+ * ) // => [{ age: 30 }]
+ * ```
+ */
+export declare function filterRows(rows: readonly Row[], conditions: readonly Condition[]): readonly Row[];
+/**
+ * Sort rows by an ordering specification, leaving the input untouched.
+ *
+ * @remarks
+ * Applies the terms in priority order — the first term that distinguishes two
+ * rows decides — using {@link compareValues}, reversing for `descending`.
+ *
+ * @param rows - The rows to sort
+ * @param order - The ordering terms in priority order
+ * @returns A new, sorted array
+ */
+export declare function sortRows(rows: readonly Row[], order: readonly Order[]): readonly Row[];
+/**
+ * Apply a {@link Criteria} to rows — filter, then sort, then page.
+ *
+ * @remarks
+ * The whole portable read pipeline in one place: conditions filter, `order`
+ * sorts, and `offset` / `limit` window the result. Each step is skipped when its
+ * part of the criteria is absent. The reference {@link DriverInterface} backends
+ * lean on this rather than each re-deriving it.
+ *
+ * @param rows - The rows to process (typically a table's full `scan`)
+ * @param criteria - The read specification, or `undefined` for all rows as-is
+ * @returns The filtered, sorted, paged rows
+ */
+export declare function applyCriteria(rows: readonly Row[], criteria?: Criteria): readonly Row[];
+/**
+ * Compute an aggregate over a column across rows.
+ *
+ * @remarks
+ * `count` returns the row count. The numeric aggregates coerce each cell with
+ * the contracts `parseNumber` (so `'42'` counts) and ignore non-numeric cells;
+ * over zero numeric values they return `undefined` — the SQL `NULL` of an empty
+ * aggregate.
+ *
+ * @param rows - The rows to aggregate (non-record entries are ignored)
+ * @param operation - The aggregate to compute
+ * @param column - The column to aggregate
+ * @returns The aggregate value, or `undefined` when undefined for the inputs
+ */
+export declare function computeAggregate(rows: readonly unknown[], operation: AggregateFunction, column: FieldPath): number | undefined;
+/**
+ * Read a row's primary key from a column, when it is a usable {@link Key}.
+ *
+ * @param row - The row to read
+ * @param column - The primary-key column name
+ * @returns The key (a string or finite number), or `undefined`
+ */
+export declare function extractKey(row: Row, column: string): Key | undefined;
+/**
+ * Map a column's {@link ContractShape} to its portable {@link ColumnType} — the
+ * value a `TableSchema` carries so a native backend can declare a real column.
+ *
+ * @remarks
+ * `string` → `text`; `number` → `integer` when the shape is integer-only, else
+ * `real`; `boolean` → `boolean`. A `literal` takes the type of its values
+ * (all-boolean → `boolean`, all-integer → `integer`, mixed/fractional numbers →
+ * `real`, anything else → `text`). `optional` / `nullable` unwrap to their inner
+ * type (nullability is tracked separately). `null` / `object` / `array` / `union` /
+ * `json` / `raw` → `json`: a backend stores them as JSON text and can `json_extract`
+ * for nested `FieldPath` queries. A scan-only backend ignores the result.
+ *
+ * @param shape - The column's contract shape
+ * @returns The portable column type
+ *
+ * @example
+ * ```ts
+ * shapeToColumnType(stringShape()) // 'text'
+ * shapeToColumnType(integerShape()) // 'integer'
+ * shapeToColumnType(optionalShape(integerShape())) // 'integer'
+ * shapeToColumnType(objectShape({ a: stringShape() })) // 'json'
+ * ```
+ */
+export declare function shapeToColumnType(shape: ContractShape): ColumnType;
+/**
+ * Throw when an {@link ReadOptions.signal | AbortSignal} has fired — the shared
+ * cancellation gate checked at operation boundaries and between streamed rows.
+ *
+ * @remarks
+ * A no-op for `undefined` or a live signal, so callers thread `options?.signal`
+ * straight through. When the signal has aborted, throws an `ABORTED`
+ * {@link DatabaseError} carrying the signal's `reason` in its context — callers
+ * mint signals with whatever tool they like (`AbortSignal.timeout(ms)`,
+ * `new AbortController()`, `@orkestrel/abort`).
+ *
+ * @param signal - The signal to check, if any
+ * @returns Nothing — returns normally while the signal is live
+ * @throws An `ABORTED` {@link DatabaseError} when the signal has aborted
+ *
+ * @example
+ * ```ts
+ * import { checkAbort } from '@orkestrel/database'
+ *
+ * const controller = new AbortController()
+ * checkAbort(controller.signal) // returns
+ * controller.abort('too slow')
+ * checkAbort(controller.signal) // throws DatabaseError('ABORTED', …)
+ * ```
+ */
+export declare function checkAbort(signal: AbortSignal | undefined): void;
+/**
+ * Structurally diff a deployed and a declared table set into a {@link Migration}
+ * plan.
+ *
+ * @remarks
+ * Tables present in `declared` but not `deployed` become `table.add` steps
+ * (carrying the full declared {@link TableSchema}); tables present in
+ * `deployed` but not `declared` become `table.remove` steps. Tables present in
+ * both are diffed column-by-column (by name) and index-group-by-index-group
+ * (by deep equality of the column-name array), each producing `column.add` /
+ * `column.remove` / `index.add` / `index.remove` steps. Step order is
+ * deterministic: every `table.remove`, then every `table.add`, then each
+ * shared table's column/index changes in `declared` order. `from` / `to` are
+ * plan labels only — version tracking itself is deferred to persistent
+ * backends.
+ *
+ * @param deployed - The table schemas currently applied
+ * @param declared - The table schemas the caller wants applied
+ * @param from - The plan's source version label (defaults to `0`)
+ * @param to - The plan's target version label (defaults to `1`)
+ * @returns The migration plan moving `deployed` toward `declared`
+ *
+ * @example
+ * ```ts
+ * const plan = planMigration(
+ * 	[{ name: 'users', primary: 'id', columns: [], indexes: [] }],
+ * 	[{ name: 'users', primary: 'id', columns: [{ name: 'age', type: 'integer', nullable: false }], indexes: [] }],
+ * )
+ * // plan.steps === [{ operation: 'column.add', table: 'users', column: { name: 'age', ... } }]
+ * ```
+ */
+export declare function planMigration(deployed: readonly TableSchema[], declared: readonly TableSchema[], from?: number, to?: number): Migration;
+/**
+ * Apply one table's {@link MigrationStep}s to its rows — a pure row transform.
+ *
+ * @remarks
+ * `column.remove` drops that field from every row (a fresh copy — inputs are
+ * never mutated, AGENTS §11); `column.add` leaves rows as-is (an absent field
+ * reads as `undefined`, backfill is application policy). `table.add` /
+ * `table.remove` / `index.add` / `index.remove` are no-ops here (they operate
+ * on storage shape, not row shape). Steps for tables other than the one
+ * `rows` belongs to are ignored — pass only the steps relevant to this table.
+ *
+ * @param rows - The table's current rows
+ * @param steps - The migration steps to apply (typically one table's slice of a {@link Migration})
+ * @returns A new array of transformed rows; `rows` is never mutated
+ *
+ * @example
+ * ```ts
+ * const rows = [{ id: 'a', name: 'Ada', legacy: true }]
+ * migrateRows(rows, [{ operation: 'column.remove', table: 'users', column: 'legacy' }])
+ * // => [{ id: 'a', name: 'Ada' }]
+ * ```
+ */
+export declare function migrateRows(rows: readonly Row[], steps: readonly MigrationStep[]): readonly Row[];
+/**
+ * Run the driver-conformance battery against a fresh {@link DriverInterface}
+ * per phase, yielding one {@link ConformanceFinding} per violated invariant —
+ * the shared invariant suite every backend (in-memory, SQLite, IndexedDB)
+ * must uphold to be a drop-in {@link DriverInterface}.
+ *
+ * @remarks
+ * Framework-agnostic: no test-runner or Node imports, only sibling core
+ * modules — so it runs equally from a unit test, a smoke script, or a new
+ * driver's own README. Opens a fixed two-table schema (`users` keyed by the
+ * default `id`, `posts` keyed by a non-id `slug`) and, calling `factory()`
+ * fresh for each phase so failures stay isolated, verifies: `open`/`close`;
+ * `read` of a missing key returns `undefined`; `write`/`read` round-trip with
+ * copy-in/copy-out isolation (mutating the caller's row after `write`, or the
+ * row `read` returns, never perturbs stored state) and upsert-overwrite;
+ * `delete` returns `true` then `false`; `keys`/`scan` yield in ascending key
+ * order; `clear` empties only its target table; `snapshot`'s rollback thunk
+ * restores pre-snapshot state; a scoped `snapshot(['users'])` rolls back only
+ * the named table, leaving a concurrent mutation to another table intact; a
+ * non-`id` primary key (`posts.slug`) round-trips; a nested-object row
+ * round-trips structurally (via {@link deepEqual}). The optional surface is
+ * presence-gated: when `migrate` exists, a `column.remove` plan strips the
+ * column from stored rows and a plan referencing an unknown table throws
+ * `DatabaseError` `MIGRATION`; when `stream` exists, it yields only
+ * condition-matching rows and honors `offset`/`limit`; when `transaction`
+ * exists, `commit` persists and `rollback` restores; when both `meta` and
+ * `stamp` exist, a fresh store's `meta()` is `undefined`, and after
+ * `stamp({ version, schema })`, `meta()` returns the exact stamped value.
+ *
+ * Each phase runs within a `try`/`catch`: an EXPECTED mismatch yields a
+ * finding built from the assertion, while an UNEXPECTED throw (a driver
+ * crash mid-phase) is caught and yielded as a finding too, naming the phase
+ * as `check` and carrying the caught error in `context.error` — a broken
+ * driver can never escape the battery as an unhandled rejection. Within a
+ * phase, the FIRST violated assertion yields and the phase stops (matching
+ * the historical fail-fast shape at phase granularity); the generator then
+ * moves on to the next phase regardless. Because this is a **generator**,
+ * consuming only the first yielded value reproduces true fail-fast (later
+ * phases never run) — that is exactly what {@link conformDriver} does.
+ *
+ * @param factory - Mints a fresh, unopened driver instance (called once per phase)
+ * @yields One {@link ConformanceFinding} per violated invariant, in phase order
+ *
+ * @example
+ * ```ts
+ * import { createMemoryDriver, driverFindings } from '@orkestrel/database'
+ *
+ * for await (const finding of driverFindings(() => createMemoryDriver())) {
+ * 	console.log(finding.check, finding.message)
+ * }
+ * ```
+ */
+export declare function driverFindings(factory: () => DriverInterface): AsyncGenerator<ConformanceFinding>;
+/**
+ * Run the driver-conformance battery, throwing on the first violated
+ * invariant — the fail-fast entry point most callers (test setup, CI smoke
+ * checks) want.
+ *
+ * @remarks
+ * A thin driver over {@link driverFindings}: because that generator is
+ * lazy, consuming only its first yielded value means every LATER phase
+ * never runs — true fail-fast, not merely "report only the first". The
+ * thrown error is byte-compatible with the historical shape: a
+ * `CONFORMANCE` {@link DatabaseError} whose `message` is the finding's
+ * `message` and whose `context` is `{ check, ...finding.context }`.
+ *
+ * @param factory - Mints a fresh, unopened driver instance (called once per phase)
+ * @returns Nothing — resolves once every phase has passed
+ * @throws A `CONFORMANCE` {@link DatabaseError} on the first violated invariant
+ *
+ * @example
+ * ```ts
+ * import { conformDriver, createMemoryDriver } from '@orkestrel/database'
+ *
+ * await conformDriver(() => createMemoryDriver()) // resolves when every invariant holds
+ * ```
+ */
+export declare function conformDriver(factory: () => DriverInterface): Promise<void>;
+/**
+ * Run the FULL driver-conformance battery and collect every violation — the
+ * audit entry point for a driver author who wants a complete report rather
+ * than a single fail-fast throw.
+ *
+ * @remarks
+ * Drains {@link driverFindings} to completion: every phase runs regardless
+ * of earlier violations, so a driver breaking two independent invariants
+ * reports both. An empty array means the driver is fully conformant.
+ *
+ * @param factory - Mints a fresh, unopened driver instance (called once per phase)
+ * @returns Every violated invariant found, in phase order (empty when fully conformant)
+ *
+ * @example
+ * ```ts
+ * import { auditDriver, createMemoryDriver } from '@orkestrel/database'
+ *
+ * const findings = await auditDriver(() => createMemoryDriver())
+ * for (const finding of findings) console.log(`${finding.check}: ${finding.message}`)
+ * ```
+ */
+export declare function auditDriver(factory: () => DriverInterface): Promise<readonly ConformanceFinding[]>;

package/dist/src/core/index.d.ts

@@ -0,0 +1,11 @@
+export type * from './types.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './helpers.js';
+export * from './factories.js';
+export * from './Database.js';
+export * from './drivers/MemoryDriver.js';
+export * from './Table.js';
+export * from './Query.js';
+export * from './Clause.js';
+export * from './Cursor.js';