@jarenjs/db 0.73.0 → 0.83.2

package/src/window.js

@@ -100,6 +100,7 @@ export function createSortedWindow(terms, limit) {
   return {
     compare,
     size: () => entries.length,
+    clear: () => { entries.length = 0; byToken.clear(); },
     /** The visible slice: the first `limit` entries (all, unbounded). */
     visible: () => (limit === null ? [...entries] : entries.slice(0, limit)),
     /**

package/types/index.d.ts

@@ -291,6 +291,8 @@ export interface LoadContinuation {
  * write may change; `'live'` (the default) reports the truth in
  * `snapshot`. */
 export interface PageOptions<C = LoadContinuation> extends EntityCursorOptions {
+  /** False admits no lookahead row; a full page reports hasMore: null. */
+  lookahead?: boolean;
   limit?: number;
   after?: C;
   maxBytes?: number | null;
@@ -305,8 +307,11 @@ export interface PageOptions<C = LoadContinuation> extends EntityCursorOptions {
 export interface Page<T, C = LoadContinuation> {
   readonly items: T[];
   readonly continuation: C | null;
-  readonly hasMore: boolean;
+  readonly hasMore: boolean | null;
   readonly snapshot: boolean;
+  /** Present with lookahead:false; includes a row consumed at the byte boundary.
+   * Bytes count the serialized payloads consumed, excluding array punctuation. */
+  readonly work?: { readonly rows: number; readonly bytes: number };
 }
 
 export interface LoadExplanation {
@@ -594,12 +599,26 @@ export interface UntrackedReads<T = unknown> {
   load(spec?: LoadSpec): Promise<T[]>;
 }
 
+/** 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: 'insert-select'; source: string; where?: unknown; select: Readonly<Record<string, string | { $literal: unknown }>>;
+      conflict: readonly string[]; onConflict: 'nothing' });
+export interface MutationResult {
+  readonly mode: 'native'; readonly affected: number; readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+  readonly admitted: { readonly statements: number; readonly rows: number; readonly bytes: number };
+}
+
 export interface EntitySet<T = unknown, I = unknown> {
   /** The provider phantom: a chain over this set infers its item type. */
   readonly __item?: T;
   create(doc: I): Promise<Readonly<T>>;
   get(key: EntityKeyArg): Promise<Readonly<T> | undefined>;
   update(key: EntityKeyArg, changes: Partial<T>): Promise<Readonly<T>>;
+  /** One bounded native SQLite column mutation; unsupported shapes refuse JD0038. */
+  mutate(document: EntityMutation): Promise<MutationResult>;
   delete(key: EntityKeyArg): Promise<boolean>;
   load(spec?: LoadSpec): Promise<ReadonlyArray<Readonly<T>>>;
   /** The graph cursor: one root graph per pull, its includes attached
@@ -695,7 +714,7 @@ export interface SyncStore {
    * the consumer's words; the handle's writes take it and reads answer it. */
   collection<T = unknown>(name: string): SyncCollection<T>;
   entity(name: string): SyncEntitySet;
-  transaction<R>(fn: (store: TransactionStore) => R): R;
+  transaction<R>(fn: (store: TransactionStore) => R, options?: { mode?: 'deferred' | 'immediate' }): R;
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): SequenceResult<R>;
   explain?(document: unknown, options?: ExecuteOptions): unknown;
   /** The entity roots this store-level provider serves (present with
@@ -813,7 +832,7 @@ export interface TransactionScopeOptions {
    * upgrade `SQLITE_BUSY` the busy handler cannot retry — what a claim
    * needs under concurrent writers; `'deferred'` (the default) is the
    * savepoint as always. A nested `tx.transaction()` is a savepoint
-   * whichever mode the root chose; the synchronous twin has no mode. */
+   * whichever mode the root chose; the root synchronous twin accepts the same mode. */
   mode?: 'deferred' | 'immediate';
 }
 
@@ -845,6 +864,7 @@ export interface SyncSavepointController {
 /** The synchronous surface a transaction view carries: the store's,
  * plus the transaction-only savepoint group. */
 export interface TransactionSyncStore extends SyncStore {
+  readonly sql: TrustedSyncSql;
   readonly savepoints: SyncSavepointController;
 }
 
@@ -871,6 +891,7 @@ export interface TransactionStore extends Omit<Store,
   | 'jobs' | 'replication'> {
   /** The transactional outbox (JOBS-FORMAT §3): no administration here —
    * an admin operation is a root call. */
+  readonly sql: TrustedSql;
   readonly jobs?: JobsApi;
   transaction<R>(fn: (store: TransactionStore) => R | Promise<R>): Promise<Awaited<R>>;
   /** Named partial rollback over the transaction's one savepoint stack
@@ -978,7 +999,7 @@ export interface LiveEventTime {
 }
 
 export interface LiveMode {
-  readonly strategy: 'rows' | 'window' | 'accumulator' | 'group'
+  readonly strategy: 'rows' | 'window' | 'accumulator' | 'group' | 'distinct'
     | 'bucket' | 'rolling' | 'join' | 'graph' | 'nested-group' | 'rerun';
   readonly mode: 'incremental' | 'rerun';
   /** Present exactly when the strategy is 'rerun': the named reason. */
@@ -1051,6 +1072,8 @@ export interface LiveBounds {
 }
 
 export interface OpenStoreOptions {
+  /** Verify existing objects and create no schema or infrastructure. */
+  adopt?: boolean;
   replication?: ReplicationOptions;
   driver: Driver;
   path?: string;
@@ -1775,6 +1798,8 @@ export interface JobWorker {
 }
 
 export interface JobWorkerOptions {
+  /** Admit only when current durable effect policy returns true. */
+  effectSafety?: (job: ClaimedJob, context: { lease(): JobLease; signal: AbortSignal }) => boolean | Promise<boolean>;
   /**
    * `checkpoints` is bound to THIS attempt and follows its current
    * lease, so a renewal does not strand it. `signal` aborts for either
@@ -1784,6 +1809,9 @@ export interface JobWorkerOptions {
    */
   handlers: Record<string, (payload: unknown, context: {
     job: ClaimedJob;
+    lease(): JobLease;
+    /** Pause as cancelled, permitting explicit requeue for reconciliation. */
+    pause(): Promise<boolean>;
     checkpoints: { load(runId: string): unknown;
       save(runId: string, nodeId: string, value: unknown): unknown;
       complete(runId: string, result: unknown): unknown };
@@ -1824,6 +1852,8 @@ export interface JobsApi {
    * expired), never a silent `false`.
    */
   renew(lease: JobLease, options?: { leaseMs?: number }): Promise<JobLease>;
+  /** Check the existing token/expiry fence without writing. */
+  assertLease(lease: JobLease): Promise<boolean>;
   /** Settle the attempt this lease holds. `true`, or one of the three
    * coded refusals above — a caller that cannot tell "already done"
    * from "you are stale" guesses, and guesses wrong. */
@@ -1899,6 +1929,7 @@ export interface JobsOptions {
 }
 
 export declare function createDagJobRunner(store: Store, options: {
+  effectSafety?: JobWorkerOptions['effectSafety'];
   compileDag: Function;
   documents: Record<string, unknown>;
   tasks?: Record<string, Function | { run: Function; version?: string; taskVersions?: Record<string, string> }>;
@@ -1982,3 +2013,27 @@ export interface ReplicationSnapshot {
   receipts: ReplicationEnvelope[];
 }
 export declare function normalizeReplicationSnapshot(document: unknown): ReplicationSnapshot;
+
+/** Trusted prepared SQL; statements belong to one transaction scope. */
+export interface TrustedSql {
+  prepare(sql: string, options: { access: 'read' | 'write'; affects?: readonly string[] }): {
+    run(params?: readonly unknown[]): unknown;
+    get(params?: readonly unknown[]): Record<string, any> | undefined | Promise<Record<string, any> | undefined>;
+    all(params?: readonly unknown[]): Record<string, any>[] | Promise<Record<string, any>[]>;
+    close(): void;
+  };
+}
+export interface TrustedSyncSql {
+  prepare(sql: string, options: { access: 'read' | 'write'; affects?: readonly string[] }): {
+    run(params?: readonly unknown[]): unknown;
+    get(params?: readonly unknown[]): Record<string, any> | undefined;
+    all(params?: readonly unknown[]): Record<string, any>[];
+    close(): void;
+  };
+}
+export declare function planInvariants(model: unknown, options: { dialect: Dialect }): {
+  type: 'trigger'; name: string; owner: string; rule: string; sql: string;
+}[];
+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;

package/types/search.d.ts

@@ -0,0 +1,20 @@
+import type { Store } from './index.js';
+import type { LexicalDefinition } from '@jarenjs/core/search';
+
+export interface SearchStorage {
+  load(id: string): Promise<string | null>;
+  save(id: string, payload: string): Promise<{ changes: number }>;
+}
+export declare function createDbSearchStorage(store: Store, collection: string, options?: { maxBytes?: number }): SearchStorage;
+export interface DbSearch {
+  readonly sourceRevision: string;
+  refresh(): Promise<any>;
+  search(text: string, request?: Record<string, unknown>): Promise<any>;
+  row(id: string, revision: string): any;
+  subscribe(observer: (event: any) => void): () => void;
+  explain(): { mode: string; nativeFTS: boolean; reason: string; maxRows: number; maxBytes: number; capture: string; externalChanges: string };
+  stats(): any;
+  dispose(): Promise<void>;
+}
+export declare function createDbSearch(store: Store, entity: string, definition: LexicalDefinition,
+  options: { source: string; maxRows?: number; maxBytes?: number; storage?: SearchStorage; snapshotKey?: string }): Promise<DbSearch>;

package/types/typed.d.ts

@@ -101,6 +101,7 @@ export interface TypedUntrackedReads<E extends MetaMap<E>, M extends EntityMeta>
 }
 
 export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
+  mutate(document: import('./index.js').EntityMutation): Promise<import('./index.js').MutationResult>;
   /** The provider phantom: `from(typed.entity('User'))` infers `User`
    * without a cast. */
   readonly __item?: M['doc'];