@orkestrel/database 0.0.13 → 0.0.14

package/dist/src/core/index.js

@@ -2,7 +2,7 @@ import { cloneJSONRecord, cloneJSONValue, compileGuard, compileSchema, createCon
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /**
-* Supplies the primary-key column assumed when {@link PrimaryMap} does not name one.
+* Supplies the primary-key column, `'id'`, assumed when {@link PrimaryMap} does not name one.
 *
 * @remarks
 * `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
@@ -10,12 +10,13 @@ import { Emitter } from "@orkestrel/emitter";
 */
 var DEFAULT_PRIMARY = "id";
 /**
-* Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts before rejecting it.
+* Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before
+* rejecting it.
 *
 * @remarks
 * A `LIKE` / `GLOB` pattern is a caller-supplied operand, so
 * `matchesLikePattern` / `matchesGlobPattern` run patterns this package cannot
-* trust. The matcher is the LINEAR greedy two-pointer wildcard match — never a
+* trust. The matcher is the linear greedy two-pointer wildcard match — never a
 * backtracking regex (`.*`-segments-separated-by-literals against a long input is the
 * catastrophic shape JS cannot bound without atomic groups), so it is O(value ×
 * pattern). Capping the pattern length bounds that pattern factor, leaving a match
@@ -89,11 +90,13 @@ var CONFORMANCE_POSTS_SCHEMA = Object.freeze({
 	indexes: Object.freeze([])
 });
 /**
-* Holds the fixed two-table schema every driver-conformance phase opens.
+* Holds the fixed `users` and `posts` schema every driver-conformance phase opens.
 *
 * @remarks
 * Each phase mints a fresh driver and opens this exact schema, so a finding
-* names a violated invariant rather than a setup difference between phases.
+* names a violated invariant rather than a setup difference between phases. The
+* array and each schema in it are frozen, so a consumer holding it cannot change
+* what a later phase opens.
 */
 var CONFORMANCE_SCHEMA = Object.freeze([CONFORMANCE_USERS_SCHEMA, CONFORMANCE_POSTS_SCHEMA]);
 //#endregion
@@ -156,6 +159,10 @@ function isKey(value) {
 /**
 * Checks whether a value is a portable column schema.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link ColumnSchema}; false otherwise
 */
@@ -171,6 +178,10 @@ function isColumnSchema(value) {
 /**
 * Checks whether a value is a portable table schema.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link TableSchema}; false otherwise
 */
@@ -190,6 +201,10 @@ function isTableSchema(value) {
 /**
 * Checks whether a value is a complete portable driver schema.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a table-schema collection with unique table names; false otherwise
 */
@@ -206,6 +221,10 @@ function isDriverSchema(value) {
 /**
 * Checks whether a value is one ordered migration step.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link MigrationStep}; false otherwise
 */
@@ -230,6 +249,10 @@ function isMigrationStep(value) {
 /**
 * Checks whether a value is an ordered migration plan.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link Migration}; false otherwise
 */
@@ -245,6 +268,12 @@ function isMigration(value) {
 /**
 * Checks whether a value is persisted driver metadata.
 *
+* @remarks
+* The boundary check a versioning driver's `metadata()` narrows a stored or
+* deserialized record through, so no call site needs an assertion. Total over any
+* input: a hostile getter, a revoked proxy, or a cyclic value is contained as a
+* non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is complete {@link DriverMetadata}; false otherwise
 */
@@ -260,6 +289,10 @@ function isDriverMetadata(value) {
 /**
 * Checks whether a value is one atomic migration request.
 *
+* @remarks
+* Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+* contained as a non-match rather than a throw.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete {@link MigrationInput}; false otherwise
 */
@@ -277,6 +310,11 @@ function isMigrationInput(value) {
 /**
 * Clones unknown driver metadata into a distinct deeply frozen snapshot.
 *
+* @remarks
+* The clone is validated as {@link DriverMetadata} before it is returned, so a
+* malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+* `context.path === 'metadata'` rather than surfacing a raw Contract or caller error.
+*
 * @param value - Unknown metadata
 * @returns Owned driver metadata
 */
@@ -296,6 +334,11 @@ function cloneDriverMetadata(value) {
 /**
 * Clones unknown driver schema into a distinct deeply frozen snapshot.
 *
+* @remarks
+* The clone is validated as a table-schema collection before it is returned, so a
+* malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+* `context.path === 'schema'` rather than surfacing a raw Contract or caller error.
+*
 * @param value - Unknown table schema collection
 * @returns Owned driver schema
 */
@@ -315,6 +358,11 @@ function cloneDriverSchema(value) {
 /**
 * Clones unknown migration input into a distinct deeply frozen snapshot.
 *
+* @remarks
+* The clone is validated as a {@link MigrationInput} before it is returned, so a
+* malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+* `context.path === 'migration'` rather than surfacing a raw Contract or caller error.
+*
 * @param value - Unknown migration input
 * @returns Owned migration input
 */
@@ -390,9 +438,9 @@ function compareValues(left, right) {
 * @remarks
 * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
 * Arrays compare by index (same length, every element `equalsValue`). Plain
-* records (through `isRecord`) compare by their OWN enumerable keys: same key
-* COUNT and, for every key in `left`, `right` has that key (`Object.hasOwn`)
-* with a `equalsValue` value — so a key present with value `undefined` is NOT
+* records (through `isRecord`) compare by their own enumerable keys: same key
+* count and, for every key in `left`, `right` has that key (`Object.hasOwn`)
+* with a `equalsValue` 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`. Container pairs are tracked iteratively, so self-referential and
@@ -458,16 +506,16 @@ function equalsValue(left, right) {
 	}
 }
 /**
-* Matches a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
+* Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe
 * engine behind {@link matchesLikePattern} and {@link matchesGlobPattern}.
 *
 * @remarks
-* A backtracking RegExp (`a%b%c` → `^a.*b.*c$`) is CATASTROPHIC on a hostile pattern:
+* 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,
 * while a `LIKE` / `GLOB` pattern is a caller-supplied operand this package cannot
-* trust. 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
+* trust. 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),
@@ -475,16 +523,16 @@ function equalsValue(left, right) {
 * pattern.
 *
 * The `any` wildcard matches any run (including empty); `single` matches exactly one
-* char; every other pattern char matches itself LITERALLY (a pattern `.` / `(` / `\` is
+* 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.
+* 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)
+* @param fold - Whether to match case-insensitively (`LIKE` folds; `GLOB` does not)
 * @returns True if `value` matches `pattern`; false otherwise
 * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
 */
@@ -546,7 +594,7 @@ function matchesLikePattern(value, pattern) {
 * @remarks
 * `*` matches any run of characters (including none) and `?` matches exactly one
 * character; every other pattern character matches itself literally, so a
-* character class such as `[a-z]` is NOT interpreted. Runs on
+* character class such as `[a-z]` is not interpreted. Runs on
 * {@link matchesWildcardPattern}, so the match is linear in the value length and
 * the pattern is capped at {@link MAX_PATTERN_LENGTH}.
 *
@@ -572,7 +620,7 @@ function matchesGlobPattern(value, pattern) {
 * string is one column; an array descends a nested value) — and applies the
 * operator. Range operators (`above` / `below` / `from` / `to` / `between`) use
 * {@link compareValues}, the total order; the equality family (`equals` / `not`
-* / `any` / `none`) uses {@link equalsValue} — STRUCTURAL equality, not the total
+* / `any` / `none`) uses {@link equalsValue} — structural equality, not the total
 * order's rank-5-collapses-all-objects behavior, so `equals` on an object/array
 * operand only matches a structurally-equal value, never every row holding any
 * object. This is a semantics change from ranking: `equalsValue` is SameValueZero
@@ -730,7 +778,9 @@ function computeAggregate(rows, operation, column) {
 		const total = numbers.reduce((sum, value) => sum + value, 0);
 		return operation === "average" ? total / numbers.length : total;
 	}
-	return operation === "minimum" ? Math.min(...numbers) : Math.max(...numbers);
+	let result = operation === "minimum" ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+	for (const value of numbers) result = operation === "minimum" ? Math.min(result, value) : Math.max(result, value);
+	return result;
 }
 /**
 * Reads a row's primary key from a column, when it is a usable {@link Key}.
@@ -908,16 +958,16 @@ function checkAbort(signal) {
 * plan labels only; versioning drivers persist and reconcile them through
 * {@link DriverMetadata}.
 *
-* A column present in BOTH schemas under the same name but with a different
+* A column present in both schemas under the same name but with a different
 * `storage`, `optional`, or `nullable` value throws a `MIGRATION`
 * {@link DatabaseError} naming the table, the column, and the from→to
-* difference — a name-only diff would otherwise silently produce NO step for
+* difference — a name-only diff would otherwise silently produce no step for
 * the drift, and versioned reconciliation would stamp over it. There is no
 * automatic in-place type-change step: the manual path is to add a new column,
 * copy/convert the data at the application layer, then remove the old column —
 * two separate plans, never a single implicit "alter" step.
 *
-* @param deployed - The table schemas currently applied
+* @param deployed - The already-applied table schemas
 * @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`)
@@ -1024,6 +1074,8 @@ function planMigration(deployed, declared, from = 0, to = 1) {
 }
 /**
 * Projects migration steps sequentially over a canonical validated owned schema.
+*
+* @remarks
 * Adding a required non-null column to an existing table rejects with
 * `MIGRATION`; optional-only and nullable-only additions remain portable.
 *
@@ -1187,14 +1239,14 @@ function migrateRows(rows, steps) {
 * 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 DEEP copy-in/copy-out isolation (mutating the caller's row —
-* including a NESTED field — after `write`, or a row `read` returns, never
+* with deep copy-in/copy-out isolation (mutating the caller's row —
+* including a nested field — after `write`, or a row `read` returns, never
 * perturbs stored state) and upsert-overwrite; simultaneous same-key
 * `insert` calls produce exactly one commit and one `CONFLICT`; pre-aborted
 * `write`, `insert`, and `delete` calls leave storage unchanged; `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, including a NESTED field mutated in place on
+* restores pre-snapshot state, including a nested field mutated in place on
 * a read-back row between capture and restore; a scoped
 * `snapshot(['users'])` rolls back only the named table, leaving a
 * concurrent mutation to another table intact; a non-`id` primary key
@@ -1208,12 +1260,12 @@ function migrateRows(rows, steps) {
 * store's `metadata()` is `undefined`, and after
 * `stamp({ version, schema })`, `metadata()` 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
+* 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
+* 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
@@ -2024,11 +2076,13 @@ async function* scanDriver(factory) {
 *
 * @remarks
 * Consumes only the first value {@link scanDriver} yields: because that
-* generator is lazy, every LATER phase never runs — true fail-fast, not
+* generator is lazy, 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 }`.
+* `message` and whose `context` is `{ check, ...finding.context }`. The battery
+* takes a driver factory and reports through a throw, so it binds no test
+* framework and runs from any runner.
 *
 * @param factory - Mints a fresh, unopened driver instance (called once per phase)
 * @returns Nothing — resolves once every phase has passed
@@ -2048,7 +2102,7 @@ async function conformDriver(factory) {
 	});
 }
 /**
-* Runs the FULL driver-conformance battery and collects every violation — the
+* Runs the full driver-conformance battery and collects every violation — the
 * audit entry point for a driver author who wants a complete report rather
 * than a single fail-fast throw.
 *
@@ -2718,10 +2772,10 @@ var Query = class {
 * @remarks
 * - **Observable.** The owned {@link emitter} ({@link TableEventMap}) carries the
 *   per-row mutation moments — `write` (set / add / update), `remove`, `clear` — for
-*   fire-and-forget observers (cache invalidation, sync, an audit log), ALONGSIDE the
-*   database-level lifecycle. Events carry the affected KEY only (no value payload, to
+*   fire-and-forget observers (cache invalidation, sync, an audit log), alongside the
+*   database-level lifecycle. Events carry the affected key only (no value payload, to
 *   keep fan-out lean); reads / queries / counts are not emitted. Every event is emitted
-*   directly, strictly AFTER the driver write / delete / clear completes; the emitter
+*   directly, strictly after the driver write / delete / clear completes; the emitter
 *   isolates a listener throw and routes it to its `error` handler (the `error` option),
 *   so a buggy observer can never corrupt a write or perturb a transaction.
 */
@@ -2834,7 +2888,7 @@ var Table = class {
 	* conditions.
 	*
 	* @remarks
-	* Unlike {@link count}, `aggregate` operates on STORED rows WITHOUT the
+	* Unlike {@link count}, `aggregate` operates on stored rows without the
 	* contract guard {@link records} / {@link scan} apply — a non-conforming
 	* stored row still contributes to the computed aggregate when it matches
 	* the conditions, even though it would never appear in `records()`'s
@@ -3162,6 +3216,10 @@ var DatabaseTransaction = class {
 * generator. Imported views register their physical schemas with the same
 * internal context before opening begins, so every view observes one driver,
 * merged schema, emitter, status, transaction boundary, and terminal close.
+*
+* The view owns the driver and its declared `tables`, connects that driver lazily on
+* first use, `import`s further tables and `export`s their portable definitions, and
+* runs `transaction` scopes over the shared context.
 */
 var Database = class Database {
 	#context;
@@ -3284,7 +3342,7 @@ var Database = class Database {
 * @remarks
 * The in-between made concrete: it runs identically in a browser or on a server,
 * so it is the storage behind tests, ephemeral caches, and any code that wants
-* the database API without a persistent backend. Rows are DEEP-copied (through
+* the database API without a persistent backend. Rows are deep-copied (through
 * `structuredClone`) in and out — at `write`, `read`, `scan`, `stream`, and both
 * snapshot capture and restore — so a caller mutating a nested field of an input
 * row, a returned row, or a row mutated in place between snapshot and rollback
@@ -3359,7 +3417,7 @@ var MemoryDriver = class {
 	* toward `offset` / `limit`. Both are applied lazily as matches are found —
 	* `offset` matches are skipped without being yielded, and iteration stops the
 	* instant `limit` yields have been produced, so a large table is never fully
-	* walked for a small page. `input.order` is IGNORED (the same contract as
+	* walked for a small page. `input.order` is ignored (the same contract as
 	* `TableInterface.scan` and `QueryInterface.stream`): streaming yields key
 	* order, sorted output is `records()`'s job. Rows yield copy-out, and an
 	* unknown table mirrors `scan`'s empty-yield behavior.
@@ -3588,20 +3646,29 @@ var MemoryDriver = class {
 *   `name`, `generator`, `version`, and emitter hooks
 * @returns A typed {@link DatabaseInterface}
 *
-* @example
+* @example Create a database
 * ```ts
 * import { createDatabase, createMemoryDriver } from '@orkestrel/database'
 * import { integerShape, stringShape } from '@orkestrel/contract'
 *
 * const db = createDatabase({
-* 	driver: createMemoryDriver(),
+* 	driver: createMemoryDriver(), // any DriverInterface — a persistent backend swaps in, same API
 * 	tables: {
-* 		users: { id: stringShape(), age: integerShape() },
+* 		users: { id: stringShape(), name: stringShape(), age: integerShape() },
 * 		posts: { slug: stringShape(), title: stringShape() },
 * 	},
-* 	primary: { posts: 'slug' },
+* 	primary: { posts: 'slug' }, // non-`id` primary-key columns, per table
 * })
-* await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
+*
+* const users = db.table('users') // hold the handle; TableInterface<{ id; name; age }>
+*
+* await users.set({ id: 'u1', name: 'Ada', age: 36 }) // coerced + validated through the contract
+* await users.get('u1') // typed { id; name; age } | undefined — narrowed, never `as`
+* await users
+* 	.query()
+* 	.condition({ column: 'age', operator: 'from', values: [18], connector: 'and' })
+* 	.order({ column: 'age', direction: 'descending' })
+* 	.collect() // typed rows
 * ```
 */
 function createDatabase(options) {