@jarenjs/db 0.56.0 → 0.67.0

package/types/node-pool.d.ts

@@ -0,0 +1,28 @@
+import type { Driver } from './index.js';
+import type { NodeWorkerOptions, WorkerConnection } from './node-worker.js';
+
+export interface NodeWorkerPoolOptions {
+  readers?: number;
+  queueCapacity?: number;
+  graceMs?: number;
+  worker?: NodeWorkerOptions;
+}
+
+/** One writer and bounded read-only WAL workers. Memory uses the writer alone. */
+export declare function nodeWorkerPoolDriver(options?: NodeWorkerPoolOptions): NodeWorkerPoolDriver;
+
+export interface PoolMetrics {
+  readonly active: number;
+  readonly idle: number;
+  readonly queued: number;
+  readonly waitMs: Readonly<{ p50: number; p95: number }>;
+  readonly workers: readonly Readonly<{
+    readOnly: boolean; healthy: boolean; active: boolean; generation: number; executions: number;
+  }>[];
+}
+export interface NodeWorkerPoolConnection extends WorkerConnection {
+  metrics(): PoolMetrics;
+}
+export interface NodeWorkerPoolDriver extends Driver {
+  open(path?: string, options?: import('./node.js').NodeOpenOptions): Promise<NodeWorkerPoolConnection>;
+}

package/types/node-worker.d.ts

@@ -0,0 +1,54 @@
+import type { Driver } from './index.js';
+
+export interface NodeWorkerOptions {
+  windowRows?: number;
+  windowBytes?: number;
+  maxPending?: number;
+  maxStatements?: number;
+  maxCursors?: number;
+  allMaxRows?: number;
+  allMaxBytes?: number;
+  closeTimeoutMs?: number;
+  startupTimeoutMs?: number;
+}
+
+/** One worker per connection; SQLite and its iterators live off the caller thread. */
+export declare function nodeWorkerDriver(options?: NodeWorkerOptions): NodeWorkerDriver;
+
+export interface WorkerMetrics {
+  readonly frames: number;
+  readonly rows: number;
+  readonly maxFrameRows: number;
+  readonly maxFrameBytes: number;
+  readonly maxPending: number;
+  readonly pending: number;
+  readonly generation: number;
+  readonly healthy: boolean;
+}
+export interface WorkerStatement {
+  run(params?: readonly unknown[]): Promise<unknown>;
+  get(params?: readonly unknown[]): Promise<Record<string, unknown> | undefined>;
+  all(params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+  iterate(params?: readonly unknown[]): Promise<AsyncIterableIterator<Record<string, unknown>>>;
+}
+/** The ordinary Connection operations; transactions pass their owning scope. */
+export interface WorkerConnectionScope {
+  exec(sql: string): Promise<unknown>;
+  prepare(sql: string, metadata?: { readOnly?: boolean; ephemeral?: boolean }): WorkerStatement | Promise<WorkerStatement>;
+  transaction<T>(body: (scope: WorkerConnectionScope) => T | Promise<T>): Promise<T>;
+}
+export interface WorkerConnection extends WorkerConnectionScope {
+  transaction<T>(body: (scope: WorkerConnectionScope) => T | Promise<T>, signal?: AbortSignal, mode?: 'deferred' | 'immediate'): Promise<T>;
+  readonly synchronous: false;
+  readonly capabilities: Readonly<Record<string, unknown>>;
+  close(): Promise<void>;
+}
+export interface NodeWorkerConnection extends WorkerConnection {
+  readonly generation: number;
+  metrics(): WorkerMetrics;
+  /** Fences this handle permanently; returns a newly opened connection. */
+  restart(): Promise<NodeWorkerConnection>;
+}
+export interface NodeWorkerDriver extends Driver {
+  open(path?: string, options?: import('./node.js').NodeOpenOptions): Promise<NodeWorkerConnection>;
+}

package/types/node.d.ts

@@ -11,7 +11,74 @@ export interface NodeOpenOptions {
 
 /** The `node:sqlite` binding; the builtin loads lazily inside open(). */
 export declare function nodeDriver(): Driver;
-/** Adapt an already-constructed DatabaseSync-shaped database. */
-export declare function adaptNodeDatabase(db: unknown): unknown;
+/** Adapt an already-constructed DatabaseSync-shaped database. `backup`
+ * is the online-backup primitive triple (`copy`, `rename`, `remove`);
+ * the connection declares the capability exactly when it is given. */
+export declare function adaptNodeDatabase(db: unknown, options?: {
+  queueTimeout?: number;
+  backup?: { copy: Function; rename: Function; remove: Function };
+}): unknown;
 /** Construct and adapt from a loaded `node:sqlite`-shaped module. */
 export declare function fromNodeModule(mod: unknown, path: string, options?: NodeOpenOptions): unknown;
+
+// ————— documents on a filesystem —————
+
+/** A byte source: a path, or anything that yields chunks — a
+ * `node:fs` read stream and `process.stdin` both are. Spelled
+ * structurally so these declarations need no ambient Node types. */
+export type DocumentByteSource = string | AsyncIterable<Uint8Array>;
+
+/** A byte sink: anything with `node:stream`'s callback `write`. */
+export interface DocumentByteSink {
+  write(chunk: string, callback: (error?: Error | null) => void): unknown;
+}
+
+/** The document encodings a file may carry. */
+export declare const DOCUMENT_FORMATS: readonly ['json', 'jsonl'];
+
+/** The encoding a path declares by its extension: `.jsonl`/`.ndjson`
+ * are line-delimited, everything else is one JSON array. */
+export declare function formatOf(file: string): 'json' | 'jsonl';
+
+/** The documents of a top-level JSON array, scanned structurally so the
+ * array is never held whole. Refuses a root that is not an array
+ * (`JD0024`). */
+export declare function readJsonDocuments(
+  source: DocumentByteSource,
+): AsyncGenerator<unknown>;
+
+/** The documents of a JSONL source, one line at a time. */
+export declare function readJsonlDocuments(
+  source: DocumentByteSource,
+): AsyncGenerator<unknown>;
+
+/** The documents of a file or stream in the named encoding. */
+export declare function readDocuments(
+  source: DocumentByteSource, format: 'json' | 'jsonl',
+): AsyncGenerator<unknown>;
+
+/** A sink that publishes whole or not at all. */
+export interface DocumentTarget {
+  /** The sibling file being filled, or null for a sink with no file. */
+  readonly temporary: string | null;
+  write(document: unknown): Promise<void>;
+  /** Flush, rename over the target, and answer what was written. */
+  commit(): Promise<{ bytes: number; documents: number }>;
+  /** Remove the temporary; the target keeps the bytes it had. */
+  abort(): Promise<void>;
+}
+
+/** Replace a file whole: a sibling temporary is renamed over the target
+ * on `commit`, and removed on `abort`, so a failed run leaves the
+ * original byte for byte. */
+export declare function openAtomicTarget(
+  target: string, format: 'json' | 'jsonl',
+): Promise<DocumentTarget>;
+
+/** Write to an open stream; `abort` cannot take back what has left. */
+export declare function openStreamTarget(
+  stream: DocumentByteSink, format: 'json' | 'jsonl',
+): DocumentTarget;
+
+/** Validate everything and write nothing. */
+export declare function openNullTarget(): DocumentTarget;

package/types/postgres.d.ts

@@ -0,0 +1,46 @@
+/** Hand-authored declarations for @jarenjs/db/postgres (strategy 1). */
+import type { Dialect, Driver } from '@jarenjs/db';
+
+/** The byte length PostgreSQL truncates an identifier at; the dialect
+ * refuses a longer one rather than letting two names silently become
+ * one. */
+export declare const IDENTIFIER_BYTES: number;
+/** The minimum server this store accepts, as `server_version_num`
+ * spells it. */
+export declare const POSTGRES_FLOOR: number;
+
+/**
+ * The PostgreSQL 16+ dialect. Pure text: it imports no client, so this
+ * subpath resolves and type-checks with nothing installed.
+ */
+export declare function postgresDialect(options?: {
+  /** The one schema every catalog statement looks in. Unset, the
+   * connection's own search path -- what a disposable per-run schema
+   * needs. */
+  searchPath?: string;
+}): Dialect;
+
+/** One acquired client, adapted to the raw binding contract. */
+export declare function adaptPostgresClient(client: {
+  query: Function;
+  release?: Function;
+}, options?: { onClose?: () => unknown }): unknown;
+
+/** The probe: the server's version floor, and every capability this
+ * engine does and does not have. */
+export declare function postgresProbe(raw: unknown): unknown;
+
+/**
+ * The driver over an injected connection source. A `pg.Pool` satisfies
+ * `{ connect() }` as it stands; a single client becomes one with
+ * `{ connect: () => client }`. One client is acquired at open, held for
+ * the store's life, and released exactly once at close.
+ */
+export declare function postgresDriver(source: {
+  connect: Function;
+}, options?: {
+  /** The schema the store lives in: set on the connection AND given to
+   * the dialect, so the DDL and the catalog reads agree. */
+  schema?: string;
+  queueTimeout?: number;
+}): Driver;

package/types/typed.d.ts

@@ -16,7 +16,8 @@ import type {
   EntityKeyArg, LoadExplanation, SaveReport, Store, StoreCapabilities,
   StoreStats, Collection, ExecuteOptions, SequenceResult, ValueOrPromise,
   Dialect, ChangeRecord, LiveOptions, LiveQuery, JobsApi, SyncStore,
-  EntityScope, RelationEntry, RelationTable,
+  EntityScope, RelationEntry, RelationTable, EntityCursorOptions, QueryCursor,
+  LoadContinuation, PageOptions, Page, ChangesReader, Replication, TransactionStore,
 } from '@jarenjs/db';
 
 /** The self-referential constraint an interface can satisfy: generated
@@ -44,7 +45,13 @@ export type TypedInclude<E extends MetaMap<E>, M extends EntityMeta> = {
 /** An include's clauses: the root's without `after` (a keyset cursor
  * paginates the root alone; an include windows with `skip`/`take`). */
 export type TypedIncludeSpec<E extends MetaMap<E>, M extends EntityMeta> =
-  TypedLoadSpecBase & { include?: TypedInclude<E, M> };
+  TypedLoadSpecBase & {
+    /** The per-root bounds (MODEL-FORMAT §10.4); `Infinity` spells the
+     * unbounded case. Crossing one is `JD2073`. */
+    maxRows?: number;
+    maxBytes?: number;
+    include?: TypedInclude<E, M>;
+  };
 
 export interface TypedLoadSpecBase {
   /** A query expression over `$it` — its format is the runtime's. */
@@ -57,7 +64,9 @@ export interface TypedLoadSpecBase {
 
 export type TypedLoadSpec<E extends MetaMap<E>, M extends EntityMeta> =
   TypedLoadSpecBase & {
-    after?: M['key'] extends string | number ? M['key'] : never;
+    /** The keyset cursor: a page's structural continuation, or the
+     * single-column form over the key. */
+    after?: (M['key'] extends string | number ? M['key'] : never) | LoadContinuation;
     include?: TypedInclude<E, M>;
   };
 
@@ -103,6 +112,13 @@ export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
   delete(key: EntityKeyArg): Promise<boolean>;
   load<const S extends TypedLoadSpec<E, M>>(spec?: S):
     Promise<Array<Readonly<Loaded<E, M, S>>>>;
+  /** The graph cursor: one root graph per pull, typed by the includes;
+   * untracked unless `tracking: true`. */
+  loadCursor<const S extends TypedLoadSpec<E, M>>(spec?: S, options?: EntityCursorOptions):
+    QueryCursor<Readonly<Loaded<E, M, S>>>;
+  /** One bounded page over the composite keyset, typed by the includes. */
+  page<const S extends TypedLoadSpec<E, M>>(spec?: S, options?: PageOptions):
+    Promise<Page<Readonly<Loaded<E, M, S>>>>;
   explainLoad(spec?: TypedLoadSpec<E, M>): LoadExplanation;
   add(doc: M['input']): Readonly<M['doc']>;
   put(next: M['doc']): Readonly<M['doc']>;
@@ -118,6 +134,9 @@ export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
   /** The provider contract over this entity's root (MODEL-FORMAT §10.1);
    * the answer is the engine's result shape, value-or-promise (D2). */
   execute<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
+  /** The same document as an item cursor: one row per pull, the
+   * statement released on `return()`; untracked unless `tracking: true`. */
+  cursor<R = M['doc']>(document: unknown, options?: EntityCursorOptions): QueryCursor<R>;
   explain(document: unknown, options?: ExecuteOptions): Promise<unknown>;
   /** The root expression this set's rows are bound through (`$.<Name>[*]`). */
   readonly root: string;
@@ -145,13 +164,17 @@ export interface TypedStore<E extends MetaMap<E>> {
   /** The relation tables of every entity, keyed by entity name. */
   readonly relations?: Readonly<Record<keyof E & string, RelationTable>>;
   saveChanges?(): Promise<SaveReport>;
-  transaction<R>(fn: (store: Store) => R | Promise<R>): Promise<Awaited<R>>;
+  transaction<R>(fn: (store: TransactionStore) => R | Promise<R>): Promise<Awaited<R>>;
   observe(fn: (record: ChangeRecord) => void): () => void;
+  /** Unbounded, and unsafe for a reconnecting consumer: `changes.page()`
+   * is the supported path (LIVE-FORMAT §5). */
   changesSince?(after: number): Promise<ChangeRecord[]>;
+  readonly changes?: ChangesReader;
   dataVersion(): Promise<number>;
   live?(document: unknown, options?: LiveOptions): Promise<LiveQuery>;
   close(options?: { graceMs?: number }): Promise<void>;
   readonly jobs?: JobsApi;
+  readonly replication?: Replication;
   readonly sync?: SyncStore;
 }
 

package/types/wasm.d.ts

@@ -10,3 +10,17 @@ export declare function adaptOo1Database(sqlite3: unknown, db: unknown): unknown
  * module: `DbClass` picks the database class (default `sqlite3.oo1.DB`;
  * the SAH-pool util's `OpfsSAHPoolDb` for OPFS persistence). */
 export declare function sqlite3Handle(sqlite3: unknown, options?: { DbClass?: unknown }): unknown;
+
+export interface SnapshotRecord { readonly revision: number; readonly bytes: Uint8Array }
+export interface SnapshotStorage {
+  read(key: string): Promise<SnapshotRecord | null>;
+  write(key: string, bytes: Uint8Array, revision: number): Promise<number>;
+  remove(key: string): Promise<number>;
+  close(): void;
+}
+/** Atomic version swaps; resolves writes only on IndexedDB transaction completion. */
+export declare function openSnapshotStorage(factory: unknown, name: string): Promise<SnapshotStorage>;
+/** Async SQLite binding with bounded, versioned IndexedDB snapshot durability. */
+export declare function indexedDbSnapshotHandle(sqlite3: unknown, options?: {
+  name?: string; indexedDB?: unknown; maxBytes?: number;
+}): unknown;