@hozon/db 0.2.3 → 0.4.0

package/lib/batch-loader.d.ts

@@ -0,0 +1,19 @@
+export type BatchLoaderParams<TKey, TValue> = {
+    load: (keys: Array<TKey>) => Promise<Map<TKey, TValue | null>>;
+    maxBatchSize: number;
+};
+export type BatchLoader<TKey, TValue> = {
+    load(key: TKey): Promise<TValue | null>;
+    clear(key: TKey): void;
+    clearAll(): void;
+    dispatch(): void;
+};
+/**
+ * Coalesces same-tick `load` calls into batched `params.load` calls of at most `maxBatchSize`
+ * keys. `remember` is read at settle time so a scope can switch the loader to batch-only.
+ */
+export declare function createBatchLoader<TKey, TValue>(params: BatchLoaderParams<TKey, TValue> & {
+    remember: () => boolean;
+}): BatchLoader<TKey, TValue>;
+/** Test probe: number of per-key generation entries a loader currently tracks. */
+export declare function trackedGenerationCount(loader: object): number;

package/lib/batch-loader.js

@@ -0,0 +1,84 @@
+import { defer } from '@sozai/async';
+import { chunk } from './keep-set.js';
+// Runs after the microtask queue drains, so loads chained behind a few awaits still coalesce.
+function scheduleAfterMicrotasks(fn) {
+    if (typeof setImmediate === 'function') setImmediate(fn);
+    else setTimeout(fn, 0);
+}
+/**
+ * Coalesces same-tick `load` calls into batched `params.load` calls of at most `maxBatchSize`
+ * keys. `remember` is read at settle time so a scope can switch the loader to batch-only.
+ */ export function createBatchLoader(params) {
+    const { load, maxBatchSize, remember } = params;
+    let pending = new Map();
+    let scheduled = false;
+    const remembered = new Map();
+    // Both counters only grow, so their sum changes whenever either is bumped.
+    const keyGenerations = new Map();
+    let globalGeneration = 0;
+    // Per-key bumps only matter to in-flight chunks; dropping them when idle bounds the map.
+    let inFlight = 0;
+    const generationOf = (key)=>globalGeneration + (keyGenerations.get(key) ?? 0);
+    async function dispatchChunk(entries) {
+        const generations = entries.map(([key])=>generationOf(key));
+        inFlight++;
+        try {
+            const results = await load(entries.map(([key])=>key));
+            const shouldRemember = remember();
+            entries.forEach(([key, deferred], index)=>{
+                const value = results.get(key) ?? null;
+                if (shouldRemember && generationOf(key) === generations[index]) {
+                    remembered.set(key, value);
+                }
+                deferred.resolve(value);
+            });
+        } catch (error) {
+            for (const [, deferred] of entries)deferred.reject(error);
+        } finally{
+            inFlight--;
+            if (inFlight === 0) keyGenerations.clear();
+        }
+    }
+    function dispatch() {
+        if (pending.size === 0) return;
+        const entries = [
+            ...pending
+        ];
+        pending = new Map();
+        for (const part of chunk(entries, maxBatchSize))void dispatchChunk(part);
+    }
+    const loader = {
+        load (key) {
+            if (remember() && remembered.has(key)) {
+                return Promise.resolve(remembered.get(key));
+            }
+            const existing = pending.get(key);
+            if (existing != null) return existing.promise;
+            const deferred = defer();
+            pending.set(key, deferred);
+            if (!scheduled) {
+                scheduled = true;
+                scheduleAfterMicrotasks(()=>{
+                    scheduled = false;
+                    dispatch();
+                });
+            }
+            return deferred.promise;
+        },
+        clear (key) {
+            if (inFlight > 0) keyGenerations.set(key, (keyGenerations.get(key) ?? 0) + 1);
+            remembered.delete(key);
+        },
+        clearAll () {
+            globalGeneration++;
+            remembered.clear();
+        },
+        dispatch
+    };
+    generationProbes.set(loader, ()=>keyGenerations.size);
+    return loader;
+}
+const generationProbes = new WeakMap();
+/** Test probe: number of per-key generation entries a loader currently tracks. */ export function trackedGenerationCount(loader) {
+    return generationProbes.get(loader)?.() ?? 0;
+}

package/lib/batch.d.ts

@@ -0,0 +1,17 @@
+export type BatchReadOptions = {
+    batchLimit?: number;
+};
+export type IterateBatchesOptions = {
+    batchSize: number;
+    signal?: AbortSignal;
+};
+/** Throws if `size` exceeds `batchLimit ?? max`, or if `batchLimit` is invalid or above `max`. */
+export declare function assertBatchSize(size: number, max: number, batchLimit?: number): void;
+/**
+ * Dedupes `keys`, loads them in sequential chunks of `batchSize` and yields each chunk with
+ * its results. Checks `signal` before each chunk.
+ */
+export declare function iterateBatches<TKey, TValue>(keys: Iterable<TKey>, load: (chunk: Array<TKey>) => Promise<Map<TKey, TValue | null>>, options: IterateBatchesOptions): AsyncGenerator<{
+    keys: Array<TKey>;
+    results: Map<TKey, TValue | null>;
+}>;

package/lib/batch.js

@@ -0,0 +1,27 @@
+import { BatchLimitError } from './errors.js';
+import { chunk } from './keep-set.js';
+/** Throws if `size` exceeds `batchLimit ?? max`, or if `batchLimit` is invalid or above `max`. */ export function assertBatchSize(size, max, batchLimit) {
+    if (batchLimit != null && (!Number.isInteger(batchLimit) || batchLimit <= 0 || batchLimit > max)) {
+        throw new RangeError(`batchLimit must be a positive integer no greater than ${max}`);
+    }
+    const limit = batchLimit ?? max;
+    if (size > limit) throw new BatchLimitError(size, limit);
+}
+/**
+ * Dedupes `keys`, loads them in sequential chunks of `batchSize` and yields each chunk with
+ * its results. Checks `signal` before each chunk.
+ */ export async function* iterateBatches(keys, load, options) {
+    const { batchSize, signal } = options;
+    if (!Number.isInteger(batchSize) || batchSize <= 0) {
+        throw new RangeError('batchSize must be a positive integer');
+    }
+    for (const chunkKeys of chunk([
+        ...new Set(keys)
+    ], batchSize)){
+        signal?.throwIfAborted();
+        yield {
+            keys: chunkKeys,
+            results: await load(chunkKeys)
+        };
+    }
+}

package/lib/db.d.ts

@@ -2,13 +2,32 @@ import type { Adapter, ColumnTypes, Functions } from '@hozon/adapter';
 import { type Logger } from '@sozai/log';
 import { Kysely } from 'kysely';
 import { type Migration } from 'kysely/migration';
+import type { BatchLoader, BatchLoaderParams } from './batch-loader.js';
+import { type CompareDefinition } from './sync.js';
 export type MigrationContext = {
     tablePrefix: string;
     kind: Adapter['kind'];
     types: ColumnTypes;
     functions: Functions;
 };
-export type StoreDefinition<Tables, API> = {
+export type BaseStoreContext = {
+    compareWrite<T extends string>(table: T, row: Record<string, unknown>): Promise<{
+        changed: boolean;
+    }>;
+    createLoader<TKey, TValue>(params: BatchLoaderParams<TKey, TValue>): BatchLoader<TKey, TValue>;
+    provider: StoreProvider;
+    root: StoreProvider;
+    onClose(fn: () => Promise<void> | void): void;
+};
+type ContextExtension = object & {
+    [Key in keyof BaseStoreContext]?: never;
+};
+export type StoreContext<Ext extends ContextExtension = {}> = BaseStoreContext & Ext;
+export type ContextFactory<Ext extends ContextExtension> = (scope: {
+    provider: StoreProvider;
+    root: StoreProvider;
+}) => keyof Ext & keyof BaseStoreContext extends never ? Ext : never;
+export type StoreDefinition<Tables, API, Ext extends ContextExtension = {}> = {
     name: string;
     migrations: Record<string, Migration> | ((ctx: MigrationContext) => Record<string, Migration>);
     dependsOn?: Array<string>;
@@ -18,9 +37,15 @@ export type StoreDefinition<Tables, API> = {
      * tables are not namespaced: the store must keep them collision-free.
      */
     unprefixedTables?: (name: string) => boolean;
-    createAPI: (db: Kysely<Tables>, adapter: Adapter) => API;
+    sync?: {
+        [T in keyof Tables & string]?: CompareDefinition<Tables[T]>;
+    };
+    createAPI: (db: Kysely<Tables>, adapter: Adapter, context: StoreContext<Ext>) => API;
 };
 export type StoreProvider<Stores extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly isTransactionBound: boolean;
+    /** Identity of the outermost transaction provider, shared by savepoints. Absent outside transactions. */
+    readonly transactionRoot?: StoreProvider;
     getStore<S extends keyof Stores & string>(name: S): Promise<Stores[S]>;
     /**
      * Returns whether a store definition is registered, synchronously and
@@ -53,23 +78,31 @@ export type StoreProvider<Stores extends Record<string, unknown> = Record<string
      * transaction or explicit savepoint.
      */
     withTransaction<NestedStores extends Record<string, unknown>, R>(fn: (tx: StoreProvider<NestedStores>) => Promise<R>): Promise<R>;
+    withScope?<NestedStores extends Record<string, unknown>, R>(fn: (scope: StoreProvider<NestedStores>) => Promise<R>): Promise<R>;
     /** Roll back only this unit of work when called inside a transaction. */
     withSavepoint?<NestedStores extends Record<string, unknown>, R>(fn: (tx: StoreProvider<NestedStores>) => Promise<R>): Promise<R>;
 };
-export type HozonDBParams = {
+export type HozonDBParams<Ext extends ContextExtension = {}> = {
     adapter: Adapter;
     logger?: Logger;
     tablePrefix?: string;
-};
-export declare class HozonDB implements StoreProvider {
+} & (keyof Ext extends never ? {
+    context?: ContextFactory<Ext>;
+} : {
+    context: ContextFactory<Ext>;
+});
+export declare class HozonDB<Ext extends ContextExtension = {}> implements StoreProvider {
     #private;
-    constructor(params: HozonDBParams);
+    constructor(params: HozonDBParams<Ext>);
     get adapter(): Adapter;
-    register<Tables, API>(store: StoreDefinition<Tables, API>): void;
+    get isTransactionBound(): boolean;
+    get transactionRoot(): StoreProvider | undefined;
+    register<Tables, API>(store: StoreDefinition<Tables, API, Ext>): void;
     getStore<T>(name: string): Promise<T>;
     hasStore(name: string): boolean;
     onCommit(fn: () => void): void;
     onRollback(_fn: () => void): void;
+    withScope<Stores extends Record<string, unknown>, R>(fn: (scope: StoreProvider<Stores>) => Promise<R>): Promise<R>;
     /**
      * Runs `fn` inside a DB transaction and provides a scoped `StoreProvider`.
      * Concurrent calls on the same `HozonDB` instance are supported — the
@@ -83,3 +116,4 @@ export declare class HozonDB implements StoreProvider {
     migrate(): Promise<void>;
     close(): Promise<void>;
 }
+export {};

package/lib/db.js

@@ -2,10 +2,15 @@ import { getLogger } from '@sozai/log';
 import { Kysely, sql } from 'kysely';
 import { Migrator } from 'kysely/migration';
 import { withTransactionalDDL } from './dialect.js';
-import { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError } from './errors.js';
+import { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SavepointReleasedError } from './errors.js';
+import { LoaderRegistry } from './loader-registry.js';
 import { checkStore } from './preflight.js';
+import { bindSyncProvider, compareWrite, settleSyncProvider } from './sync.js';
 import { TablePrefixPlugin } from './table-prefix.js';
+// biome-ignore lint/complexity/noBannedTypes: The default adds no context fields.
 export class HozonDB {
+    #context;
+    #closeHooks = [];
     #tablePrefix;
     #defaultPlugin;
     #closed = false;
@@ -19,9 +24,13 @@ export class HozonDB {
     #storePlugins = new Map();
     #logger;
     #migrated = new Map();
+    #loaders = new LoaderRegistry({
+        remember: false
+    });
     #storeAPIs = new Map();
     #stores = new Map();
     constructor(params){
+        this.#context = params.context;
         this.#tablePrefix = params.tablePrefix ?? 'hozon';
         if (!/^[a-z][a-z0-9_]{0,30}$/.test(this.#tablePrefix)) {
             throw new InvalidTablePrefixError(this.#tablePrefix);
@@ -41,6 +50,12 @@ export class HozonDB {
     get adapter() {
         return this.#adapter;
     }
+    get isTransactionBound() {
+        return false;
+    }
+    get transactionRoot() {
+        return undefined;
+    }
     register(store) {
         const existing = this.#stores.get(store.name);
         if (existing != null) {
@@ -63,8 +78,7 @@ export class HozonDB {
             if (store == null) {
                 throw new Error(`Store "${name}" is not registered`);
             }
-            const storeDB = store.unprefixedTables == null ? this.#storeDB : this.#db.withPlugin(this.#getStorePlugin(store));
-            this.#storeAPIs.set(name, store.createAPI(storeDB, this.#adapter));
+            this.#storeAPIs.set(name, this.#createStoreAPI(store, this.#db, this.#storeDB, this.#loaders, this));
         }
         return this.#storeAPIs.get(name);
     }
@@ -76,6 +90,42 @@ export class HozonDB {
     }
     // Each standalone op auto-commits, so there is nothing to roll back — no-op.
     onRollback(_fn) {}
+    async withScope(fn) {
+        this.#assertOpen();
+        const registry = new LoaderRegistry({
+            remember: true
+        });
+        const storeAPIs = new Map();
+        const provider = {
+            isTransactionBound: false,
+            getStore: async (name)=>{
+                this.#assertOpen();
+                await this.#ensurePreflight();
+                await this.#ensureMigrated(name);
+                this.#assertOpen();
+                if (!storeAPIs.has(name)) {
+                    const store = this.#stores.get(name);
+                    if (store == null) throw new Error(`Store "${name}" is not registered`);
+                    storeAPIs.set(name, this.#createStoreAPI(store, this.#db, this.#storeDB, registry, provider));
+                }
+                return storeAPIs.get(name);
+            },
+            hasStore: (name)=>this.hasStore(name),
+            onCommit: (hook)=>hook(),
+            onRollback: ()=>{},
+            withScope: async (nestedFn)=>{
+                return await nestedFn(provider);
+            },
+            withTransaction: async (nestedFn)=>{
+                return await this.#withTransaction(nestedFn, ()=>registry.clearAll());
+            }
+        };
+        try {
+            return await fn(provider);
+        } finally{
+            registry.close();
+        }
+    }
     /**
    * Runs `fn` inside a DB transaction and provides a scoped `StoreProvider`.
    * Concurrent calls on the same `HozonDB` instance are supported — the
@@ -85,6 +135,9 @@ export class HozonDB {
    * `db.withTransaction` on the same instance inside the callback opens a
    * new independent transaction (no atomic nesting) and is a bug.
    */ async withTransaction(fn) {
+        return await this.#withTransaction(fn);
+    }
+    async #withTransaction(fn, beforeHooks) {
         // Migrate every registered store before opening the transaction. Stores
         // are internal and known up front, so a broken migration should fail fast
         // at startup rather than leave a runtime partition where one store's
@@ -93,6 +146,9 @@ export class HozonDB {
         this.#assertOpen();
         const commitHooks = [];
         const rollbackHooks = [];
+        const registry = new LoaderRegistry({
+            remember: true
+        });
         let result;
         let savepointID = 0;
         try {
@@ -100,68 +156,124 @@ export class HozonDB {
             result = await this.#db.transaction().execute(async (trx)=>{
                 const txKysely = trx;
                 const txStoreDB = txKysely.withPlugin(this.#defaultPlugin);
-                const txStoreAPIs = new Map();
-                const createScopedProvider = (scopedCommitHooks, scopedRollbackHooks)=>{
+                const createScopedProvider = (scopedCommitHooks, scopedRollbackHooks, transactionRoot, syncParent, syncSavepoint = false, scopeState = {
+                    savepointOpen: false,
+                    settled: false,
+                    savepointBound: syncSavepoint
+                })=>{
                     // Savepoints on one connection form a stack: a scope holds at most
                     // one open savepoint, and nesting goes through that savepoint's
                     // own provider.
-                    let savepointOpen = false;
+                    const assertActive = ()=>{
+                        if (scopeState.settled) throw new SavepointReleasedError();
+                    };
+                    const txStoreAPIs = new Map();
                     const provider = {
+                        isTransactionBound: true,
+                        get transactionRoot () {
+                            return transactionRoot ?? provider;
+                        },
                         getStore: async (name)=>{
+                            assertActive();
+                            this.#assertOpen();
                             if (!txStoreAPIs.has(name)) {
                                 const store = this.#stores.get(name);
                                 if (store == null) {
                                     throw new Error(`Store "${name}" is not registered`);
                                 }
-                                const storeDB = store.unprefixedTables == null ? txStoreDB : txKysely.withPlugin(this.#getStorePlugin(store));
-                                txStoreAPIs.set(name, store.createAPI(storeDB, this.#adapter));
+                                txStoreAPIs.set(name, this.#createStoreAPI(store, txKysely, txStoreDB, registry, provider, scopeState.savepointBound ? assertActive : undefined));
                             }
                             return txStoreAPIs.get(name);
                         },
-                        hasStore: (name)=>this.#stores.has(name),
+                        hasStore: (name)=>{
+                            assertActive();
+                            return this.#stores.has(name);
+                        },
                         onCommit: (hook)=>{
+                            assertActive();
                             scopedCommitHooks.push(hook);
                         },
                         onRollback: (hook)=>{
+                            assertActive();
                             scopedRollbackHooks.push(hook);
                         },
+                        withScope: async (nestedFn)=>{
+                            assertActive();
+                            return await nestedFn(provider);
+                        },
                         withTransaction: async (nestedFn)=>{
                             // Already inside a transaction — Kysely does not nest.
                             // Run `nestedFn` inline with the same provider so its hooks and
                             // writes remain within the enclosing transaction or savepoint.
+                            assertActive();
                             return await nestedFn(provider);
                         },
                         withSavepoint: async (nestedFn)=>{
-                            if (savepointOpen) throw new SavepointOverlapError();
-                            savepointOpen = true;
+                            assertActive();
+                            if (scopeState.savepointOpen) throw new SavepointOverlapError();
+                            scopeState.savepointOpen = true;
                             try {
                                 const name = `${this.#tablePrefix}_sp_${++savepointID}`;
                                 const savepointCommitHooks = [];
                                 const savepointRollbackHooks = [];
-                                const scopedProvider = createScopedProvider(savepointCommitHooks, savepointRollbackHooks);
+                                const savepointState = {
+                                    savepointOpen: false,
+                                    settled: false,
+                                    savepointBound: true
+                                };
+                                const scopedProvider = createScopedProvider(savepointCommitHooks, savepointRollbackHooks, provider.transactionRoot, provider, true, savepointState);
+                                registry.dispatchAll();
                                 await sql.raw(`SAVEPOINT ${name}`).execute(trx);
                                 try {
                                     const value = await nestedFn(scopedProvider);
+                                    registry.dispatchAll();
                                     await sql.raw(`RELEASE SAVEPOINT ${name}`).execute(trx);
-                                    scopedCommitHooks.push(...savepointCommitHooks);
-                                    scopedRollbackHooks.push(...savepointRollbackHooks);
+                                    savepointState.settled = true;
+                                    registry.clearAll();
+                                    for (const hook of savepointCommitHooks)provider.onCommit(hook);
+                                    for (const hook of savepointRollbackHooks)provider.onRollback(hook);
                                     return value;
                                 } catch (error) {
+                                    registry.dispatchAll();
                                     await sql.raw(`ROLLBACK TO SAVEPOINT ${name}`).execute(trx);
+                                    registry.dispatchAll();
                                     await sql.raw(`RELEASE SAVEPOINT ${name}`).execute(trx);
+                                    savepointState.settled = true;
+                                    registry.clearAll();
                                     this.#runHooks(savepointRollbackHooks, 'rollback');
                                     throw error;
+                                } finally{
+                                    savepointState.settled = true;
+                                    settleSyncProvider(scopedProvider);
                                 }
                             } finally{
-                                savepointOpen = false;
+                                scopeState.savepointOpen = false;
                             }
                         }
                     };
+                    bindSyncProvider(provider, {
+                        assertActive,
+                        derive: ()=>createScopedProvider(scopedCommitHooks, scopedRollbackHooks, provider.transactionRoot, provider, false, scopeState),
+                        db: txKysely,
+                        kind: this.#adapter.kind,
+                        tablePrefix: this.#tablePrefix,
+                        tableName: (table)=>{
+                            const unprefixed = [
+                                ...this.#stores.values()
+                            ].some((store)=>store.unprefixedTables?.(table));
+                            return unprefixed ? table : `${this.#tablePrefix}_${table}`;
+                        }
+                    }, syncParent, syncSavepoint);
                     return provider;
                 };
-                return await fn(createScopedProvider(commitHooks, rollbackHooks));
+                try {
+                    return await fn(createScopedProvider(commitHooks, rollbackHooks));
+                } finally{
+                    registry.dispatchAll();
+                }
             });
         } catch (err) {
+            registry.close();
             // Kysely issues ROLLBACK and rejects `execute()` when the callback
             // throws, so the DB is already reverted here. Run the rollback hooks to
             // drop any in-memory state that was eagerly advanced expecting a commit
@@ -171,6 +283,8 @@ export class HozonDB {
             this.#runHooks(rollbackHooks, 'rollback');
             throw err;
         }
+        registry.close();
+        beforeHooks?.();
         // The transaction has committed; post-commit hooks are best-effort side
         // effects (event emission, cache invalidation). A throwing hook must not
         // skip the remaining hooks or make the caller observe a durable write as a
@@ -202,6 +316,17 @@ export class HozonDB {
         return this.#closing;
     }
     async #close() {
+        // Publish #closing before a hook can re-enter close().
+        await Promise.resolve();
+        for (const hook of this.#closeHooks){
+            try {
+                await hook();
+            } catch (error) {
+                this.#logger.error('close hook failed', {
+                    error
+                });
+            }
+        }
         try {
             await this.#db.destroy();
         } finally{
@@ -236,6 +361,32 @@ export class HozonDB {
         }
         return migrations;
     }
+    // Stores on the default plugin must share one Kysely instance: keep-set locks key on it.
+    #createStoreAPI(store, kysely, defaultDB, registry, provider, assertActive) {
+        const storeDB = store.unprefixedTables == null ? defaultDB : kysely.withPlugin(this.#getStorePlugin(store));
+        const base = {
+            compareWrite: async (table, row)=>{
+                assertActive?.();
+                return await compareWrite(storeDB, table, row, store.sync?.[table]);
+            },
+            createLoader: (params)=>{
+                assertActive?.();
+                return registry.createLoader(params);
+            },
+            provider,
+            root: this,
+            onClose: (fn)=>{
+                this.#assertOpen();
+                this.#closeHooks.push(fn);
+            }
+        };
+        const ext = this.#context?.({
+            provider,
+            root: this
+        });
+        const context = Object.defineProperties(base, Object.getOwnPropertyDescriptors(ext ?? {}));
+        return store.createAPI(storeDB, this.#adapter, context);
+    }
     #getStorePlugin(store) {
         if (store.unprefixedTables == null) return this.#defaultPlugin;
         let plugin = this.#storePlugins.get(store.name);

package/lib/errors.d.ts

@@ -1,3 +1,9 @@
+export declare class SavepointReleasedError extends Error {
+    constructor();
+}
+export declare class KeyLockScopeError extends Error {
+    constructor();
+}
 export declare class SavepointOverlapError extends Error {
     constructor();
 }
@@ -10,3 +16,6 @@ export declare class InvalidTablePrefixError extends Error {
 export declare class HozonDBClosedError extends Error {
     constructor();
 }
+export declare class BatchLimitError extends Error {
+    constructor(size: number, limit: number);
+}

package/lib/errors.js

@@ -1,3 +1,15 @@
+export class SavepointReleasedError extends Error {
+    constructor(){
+        super('The savepoint has already been released or rolled back');
+        this.name = 'SavepointReleasedError';
+    }
+}
+export class KeyLockScopeError extends Error {
+    constructor(){
+        super('The key is reserved by an unsettled savepoint outside this provider scope');
+        this.name = 'KeyLockScopeError';
+    }
+}
 export class SavepointOverlapError extends Error {
     constructor(){
         super('A savepoint is already open in this transaction scope');
@@ -22,3 +34,9 @@ export class HozonDBClosedError extends Error {
         this.name = 'HozonDBClosedError';
     }
 }
+export class BatchLimitError extends Error {
+    constructor(size, limit){
+        super(`Batch of ${size} keys exceeds limit ${limit}`);
+        this.name = 'BatchLimitError';
+    }
+}

package/lib/index.d.ts

@@ -1,9 +1,12 @@
 export type { ColumnType, Expression, Generated, Insertable, RawBuilder, Selectable, SelectQueryBuilder, Transaction, Updateable, } from 'kysely';
 export { Kysely, sql } from 'kysely';
 export type { Migration } from 'kysely/migration';
-export type { HozonDBParams, MigrationContext, StoreDefinition, StoreProvider } from './db.js';
+export { assertBatchSize, type BatchReadOptions, type IterateBatchesOptions, iterateBatches, } from './batch.js';
+export { type BatchLoader, type BatchLoaderParams, createBatchLoader, } from './batch-loader.js';
+export type { BaseStoreContext, ContextFactory, HozonDBParams, MigrationContext, StoreContext, StoreDefinition, StoreProvider, } from './db.js';
 export { HozonDB } from './db.js';
-export { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError, } from './errors.js';
-export { chunk, withKeepSet } from './keep-set.js';
+export { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, KeyLockScopeError, SavepointOverlapError, SavepointReleasedError, SchemaVersionError, } from './errors.js';
+export { chunk, IN_LIST_CHUNK, withKeepSet } from './keep-set.js';
 export { withStoreTransaction } from './store-transaction.js';
+export { type CompareDefinition, compareText, withKeyLock, withKeyLocks } from './sync.js';
 export { type TablePrefixOptions, TablePrefixPlugin } from './table-prefix.js';

package/lib/index.js

@@ -1,6 +1,9 @@
 export { Kysely, sql } from 'kysely';
+export { assertBatchSize, iterateBatches } from './batch.js';
+export { createBatchLoader } from './batch-loader.js';
 export { HozonDB } from './db.js';
-export { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError } from './errors.js';
-export { chunk, withKeepSet } from './keep-set.js';
+export { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, KeyLockScopeError, SavepointOverlapError, SavepointReleasedError, SchemaVersionError } from './errors.js';
+export { chunk, IN_LIST_CHUNK, withKeepSet } from './keep-set.js';
 export { withStoreTransaction } from './store-transaction.js';
+export { compareText, withKeyLock, withKeyLocks } from './sync.js';
 export { TablePrefixPlugin } from './table-prefix.js';

package/lib/keep-set.d.ts

@@ -1,5 +1,8 @@
 import type { Kysely, SelectQueryBuilder } from 'kysely';
-export declare function chunk<T>(items: Array<T>, size?: number): Array<Array<T>>;
+export declare const IN_LIST_CHUNK = 500;
+export declare function chunk<T>(items: Iterable<T>, size?: number, options?: {
+    unique?: boolean;
+}): Array<Array<T>>;
 type KeepTable = {
     keep: {
         trace_id: string;

package/lib/keep-set.js

@@ -1,9 +1,15 @@
 import { sql } from 'kysely';
-export function chunk(items, size = 500) {
+export const IN_LIST_CHUNK = 500;
+export function chunk(items, size = IN_LIST_CHUNK, options) {
     if (!Number.isInteger(size) || size <= 0) throw new RangeError('Chunk size must be a positive integer');
     const chunks = [];
-    for(let offset = 0; offset < items.length; offset += size){
-        chunks.push(items.slice(offset, offset + size));
+    const values = options?.unique ? [
+        ...new Set(items)
+    ] : [
+        ...items
+    ];
+    for(let offset = 0; offset < values.length; offset += size){
+        chunks.push(values.slice(offset, offset + size));
     }
     return chunks;
 }

package/lib/loader-registry.d.ts

@@ -0,0 +1,11 @@
+import { type BatchLoader, type BatchLoaderParams } from './batch-loader.js';
+export declare class LoaderRegistry {
+    #private;
+    constructor(params: {
+        remember: boolean;
+    });
+    createLoader<TKey, TValue>(params: BatchLoaderParams<TKey, TValue>): BatchLoader<TKey, TValue>;
+    dispatchAll(): void;
+    clearAll(): void;
+    close(): void;
+}

package/lib/loader-registry.js

@@ -0,0 +1,26 @@
+import { createBatchLoader } from './batch-loader.js';
+export class LoaderRegistry {
+    #remember;
+    #loaders = new Set();
+    constructor(params){
+        this.#remember = params.remember;
+    }
+    createLoader(params) {
+        const loader = createBatchLoader({
+            ...params,
+            remember: ()=>this.#remember
+        });
+        this.#loaders.add(loader);
+        return loader;
+    }
+    dispatchAll() {
+        for (const loader of this.#loaders)loader.dispatch();
+    }
+    clearAll() {
+        for (const loader of this.#loaders)loader.clearAll();
+    }
+    close() {
+        this.#remember = false;
+        this.clearAll();
+    }
+}

package/lib/sync.d.ts

@@ -0,0 +1,29 @@
+import type { Adapter } from '@hozon/adapter';
+import type { ColumnDefinitionBuilder, Kysely } from 'kysely';
+import type { MigrationContext, StoreProvider } from './db.js';
+export type CompareDefinition<Row> = {
+    key: Array<keyof Row & string>;
+    compare: Array<keyof Row & string>;
+    inclusive?: boolean;
+    nullsOldest?: boolean;
+    skipUnchanged?: boolean;
+    cursor?: never;
+    tombstones?: never;
+};
+type LockContext = {
+    assertActive: () => void;
+    derive: () => StoreProvider;
+    db: Kysely<Record<string, unknown>>;
+    kind: Adapter['kind'];
+    tablePrefix: string;
+    tableName: (table: string) => string;
+};
+export declare function settleSyncProvider(provider: StoreProvider): void;
+export declare function bindSyncProvider(provider: StoreProvider, context: LockContext, parent?: StoreProvider, savepoint?: boolean): void;
+export declare function withKeyLock<R>(provider: StoreProvider, table: string, key: ReadonlyArray<string | number>, fn: (tx: StoreProvider) => Promise<R>): Promise<R>;
+export declare function withKeyLocks<R>(provider: StoreProvider, table: string, keys: ReadonlyArray<ReadonlyArray<string | number>>, fn: (tx: StoreProvider) => Promise<R>): Promise<R>;
+export declare function compareText(ctx: MigrationContext): (column: ColumnDefinitionBuilder) => ColumnDefinitionBuilder;
+export declare function compareWrite(db: Kysely<Record<string, unknown>>, table: string, row: Record<string, unknown>, definition?: CompareDefinition<Record<string, unknown>>): Promise<{
+    changed: boolean;
+}>;
+export {};

package/lib/sync.js

@@ -0,0 +1,188 @@
+import { sql } from 'kysely';
+import { KeyLockScopeError } from './errors.js';
+const providerScopes = new WeakMap();
+const savepointScopes = new WeakMap();
+export function settleSyncProvider(provider) {
+    const scope = providerScopes.get(provider);
+    if (scope) savepointScopes.get(provider.transactionRoot ?? provider)?.delete(scope);
+}
+const lockContexts = new WeakMap();
+const ownership = new WeakMap();
+const keyLocks = new WeakMap();
+export function bindSyncProvider(provider, context, parent, savepoint = false) {
+    lockContexts.set(provider, context);
+    ownership.set(provider, new Map(parent == null ? [] : ownership.get(parent)));
+    const parentScope = parent == null ? undefined : providerScopes.get(parent);
+    if (savepoint) {
+        const scope = {
+            parent: parentScope,
+            keys: new Set()
+        };
+        providerScopes.set(provider, scope);
+        const root = provider.transactionRoot ?? provider;
+        let scopes = savepointScopes.get(root);
+        if (!scopes) {
+            scopes = new Set();
+            savepointScopes.set(root, scopes);
+        }
+        scopes.add(scope);
+    } else if (parentScope) {
+        providerScopes.set(provider, parentScope);
+    }
+}
+async function withQueue(root, key, fn) {
+    let locks = keyLocks.get(root);
+    if (locks == null) {
+        locks = new Map();
+        keyLocks.set(root, locks);
+    }
+    const previous = locks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve)=>{
+        release = resolve;
+    });
+    const tail = previous.then(()=>current);
+    locks.set(key, tail);
+    await previous;
+    try {
+        return await fn();
+    } finally{
+        release();
+        if (locks.get(key) === tail) locks.delete(key);
+    }
+}
+export async function withKeyLock(provider, table, key, fn) {
+    return await withKeyLocks(provider, table, [
+        key
+    ], fn);
+}
+export async function withKeyLocks(provider, table, keys, fn) {
+    if (!provider.isTransactionBound) {
+        return await provider.withTransaction((tx)=>withKeyLocks(tx, table, keys, fn));
+    }
+    const root = provider.transactionRoot ?? provider;
+    const context = lockContexts.get(provider);
+    if (context == null) throw new Error('withKeyLock requires a HozonDB provider');
+    context.assertActive();
+    const identities = [
+        ...new Set(keys.map((key)=>{
+            if (key.some((part)=>typeof part === 'number' && !Number.isFinite(part))) {
+                throw new Error('Lock keys require finite numbers');
+            }
+            return JSON.stringify([
+                context.tablePrefix,
+                table,
+                key
+            ]);
+        }))
+    ];
+    let lockIDs;
+    if (context.kind === 'postgres') {
+        const ids = [];
+        for (const identity of identities){
+            const result = await sql`SELECT (('x' || substr(md5(${identity}::text), 1, 16))::bit(64)::bigint)::text AS id`.execute(context.db);
+            for (const row of result.rows)ids.push(BigInt(row.id));
+        }
+        // Order and deduplicate the actual IDs: collisions only add contention.
+        lockIDs = [
+            ...new Set(ids)
+        ].sort((a, b)=>a < b ? -1 : a > b ? 1 : 0).map(String);
+    } else {
+        lockIDs = identities.sort();
+    }
+    const scope = providerScopes.get(provider);
+    const ancestors = new Set();
+    for(let current = scope; current; current = current.parent)ancestors.add(current);
+    const checkScope = (id)=>{
+        for (const reservation of savepointScopes.get(root) ?? []){
+            if (reservation.keys.has(id) && !ancestors.has(reservation)) throw new KeyLockScopeError();
+        }
+    };
+    for (const id of lockIDs)checkScope(id);
+    const held = ownership.get(provider);
+    const acquired = {
+        active: true
+    };
+    const locked = context.derive();
+    // biome-ignore lint/style/noNonNullAssertion: derive binds ownership before returning.
+    const owned = ownership.get(locked);
+    const acquire = async (index)=>{
+        const id = lockIDs[index];
+        if (id === undefined) {
+            if (context.kind === 'sqlite' && lockIDs.length > 0) {
+                // Even a zero-row DELETE reserves SQLite's writer before the callback reads.
+                await sql`DELETE FROM ${sql.table(context.tableName(table))} WHERE 1 = 0`.execute(context.db);
+            }
+            for (const id of lockIDs){
+                checkScope(id);
+                for (const ancestor of ancestors)ancestor.keys.add(id);
+            }
+            context.assertActive();
+            return await fn(locked);
+        }
+        checkScope(id);
+        if (held?.get(id)?.active) return await acquire(index + 1);
+        return await withQueue(root, id, async ()=>{
+            checkScope(id);
+            if (context.kind === 'postgres') {
+                await sql`SELECT pg_advisory_xact_lock(${id}::bigint)`.execute(context.db);
+            }
+            for (const ancestor of ancestors)ancestor.keys.add(id);
+            owned.set(id, acquired);
+            return await acquire(index + 1);
+        });
+    };
+    try {
+        return await acquire(0);
+    } finally{
+        acquired.active = false;
+    }
+}
+export function compareText(ctx) {
+    return (column)=>ctx.kind === 'postgres' ? column.modifyEnd(sql`collate "C"`) : column;
+}
+export async function compareWrite(db, table, row, definition) {
+    if (definition == null) throw new Error(`Table "${table}" has no sync declaration`);
+    if (definition.key.length === 0 || definition.compare.length === 0) {
+        throw new Error('Sync declarations require key and compare columns');
+    }
+    const columns = Object.keys(row);
+    const stored = (column)=>sql.ref(`${table}.${column}`);
+    const incoming = (column)=>sql.ref(`excluded.${column}`);
+    const tuple = (names, ref)=>sql`(${sql.join(names.map(ref))})`;
+    const { compare } = definition;
+    let predicate;
+    if (definition.nullsOldest) {
+        const alternatives = compare.map((column, index)=>{
+            const equal = compare.slice(0, index).map((previous)=>sql`${incoming(previous)} IS NOT DISTINCT FROM ${stored(previous)}`);
+            const greater = sql`((${stored(column)} IS NULL AND ${incoming(column)} IS NOT NULL) OR ${incoming(column)} > ${stored(column)})`;
+            return sql`(${sql.join([
+                ...equal,
+                greater
+            ], sql` AND `)})`;
+        });
+        if (definition.inclusive) {
+            alternatives.push(sql`(${sql.join(compare.map((column)=>sql`${incoming(column)} IS NOT DISTINCT FROM ${stored(column)}`), sql` AND `)})`);
+        }
+        predicate = sql`(${sql.join(alternatives, sql` OR `)})`;
+    } else {
+        predicate = sql`${tuple(compare, incoming)} ${definition.inclusive ? sql`>=` : sql`>`} ${tuple(compare, stored)}`;
+    }
+    if (definition.skipUnchanged) {
+        predicate = sql`(${predicate}) AND ${tuple(columns, stored)} IS DISTINCT FROM ${tuple(columns, incoming)}`;
+    }
+    const query = db;
+    const updates = Object.fromEntries(columns.map((column)=>[
+            column,
+            incoming(column)
+        ]));
+    const statement = query.insertInto(table).values(row).onConflict((conflict)=>conflict.columns(definition.key).doUpdateSet(updates).where(predicate)).returning(definition.key);
+    const compiled = statement.compile();
+    if (compiled.parameters.length > 500) {
+        throw new Error('compareWrite cannot bind more than 500 parameters');
+    }
+    const result = await db.executeQuery(compiled);
+    return {
+        changed: result.rows.length > 0
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hozon/db",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "Database registry, migrations and transactions for Hozon",
   "repository": {
     "type": "git",
@@ -17,15 +17,16 @@
     "lib/*"
   ],
   "dependencies": {
-    "@hozon/adapter": "^0.1.0",
+    "@hozon/adapter": "^0.2.0",
+    "@sozai/async": "^0.4.1",
     "@sozai/log": "^0.4.0",
-    "kysely": "^0.29.6"
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@hozon/node-sqlite": "^0.1.0",
-    "@types/node": "^26.6.4",
-    "del-cli": "^7.0.0",
-    "vitest": "5.0.3"
+    "@hozon/node-sqlite": "^0.2.0",
+    "@types/node": "^26.6.5",
+    "del-cli": "^8.0.1",
+    "vitest": "5.0.5"
   },
   "engines": {
     "node": ">=24"