@hozon/db 0.3.0 → 0.5.0

package/lib/db.d.ts

@@ -3,16 +3,31 @@ 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 StoreContext = {
+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;
 };
-export type StoreDefinition<Tables, API> = {
+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>;
@@ -22,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, context: StoreContext) => 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
@@ -61,16 +82,22 @@ export type StoreProvider<Stores extends Record<string, unknown> = Record<string
     /** 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;
@@ -89,3 +116,4 @@ export declare class HozonDB implements StoreProvider {
     migrate(): Promise<void>;
     close(): Promise<void>;
 }
+export {};

package/lib/db.js

@@ -2,11 +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, StoreAlreadyRegisteredError } from './errors.js';
 import { LoaderRegistry } from './loader-registry.js';
-import { checkStore } from './preflight.js';
+import { checkStore, readAppliedMigrations } 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;
@@ -26,6 +30,7 @@ export class HozonDB {
     #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);
@@ -45,13 +50,17 @@ 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) {
             if (existing !== store) {
-                this.#logger.warn('store "{name}" registered with different definition, ignoring', {
-                    name: store.name
-                });
+                throw new StoreAlreadyRegisteredError(store.name);
             }
             return;
         }
@@ -67,7 +76,7 @@ export class HozonDB {
             if (store == null) {
                 throw new Error(`Store "${name}" is not registered`);
             }
-            this.#storeAPIs.set(name, this.#createStoreAPI(store, this.#db, this.#storeDB, this.#loaders));
+            this.#storeAPIs.set(name, this.#createStoreAPI(store, this.#db, this.#storeDB, this.#loaders, this));
         }
         return this.#storeAPIs.get(name);
     }
@@ -86,6 +95,7 @@ export class HozonDB {
         });
         const storeAPIs = new Map();
         const provider = {
+            isTransactionBound: false,
             getStore: async (name)=>{
                 this.#assertOpen();
                 await this.#ensurePreflight();
@@ -94,7 +104,7 @@ export class HozonDB {
                 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));
+                    storeAPIs.set(name, this.#createStoreAPI(store, this.#db, this.#storeDB, registry, provider));
                 }
                 return storeAPIs.get(name);
             },
@@ -144,70 +154,114 @@ 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`);
                                 }
-                                txStoreAPIs.set(name, this.#createStoreAPI(store, txKysely, txStoreDB, registry));
+                                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;
                 };
                 try {
@@ -260,6 +314,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{
@@ -294,13 +359,31 @@ export class HozonDB {
         }
         return migrations;
     }
-    // Hands stores only createLoader, so they cannot reach close/dispatchAll/clearAll.
     // Stores on the default plugin must share one Kysely instance: keep-set locks key on it.
-    #createStoreAPI(store, kysely, defaultDB, registry) {
+    #createStoreAPI(store, kysely, defaultDB, registry, provider, assertActive) {
         const storeDB = store.unprefixedTables == null ? defaultDB : kysely.withPlugin(this.#getStorePlugin(store));
-        return store.createAPI(storeDB, this.#adapter, {
-            createLoader: (params)=>registry.createLoader(params)
+        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;
@@ -363,6 +446,15 @@ export class HozonDB {
         if (Object.keys(migrations).length === 0) {
             return;
         }
+        // Kysely's migrator opens a transaction even when nothing is pending, which fails while
+        // another database instance holds the same single SQLite connection in a transaction.
+        const applied = await readAppliedMigrations(this.#db, this.#tablePrefix, name);
+        if (applied != null && Object.keys(migrations).every((key)=>applied.has(key))) {
+            this.#logger.debug('store {name} migrations already applied', {
+                name
+            });
+            return;
+        }
         const migrator = new Migrator({
             db: this.#db,
             provider: {

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,6 +16,9 @@ export declare class InvalidTablePrefixError extends Error {
 export declare class HozonDBClosedError extends Error {
     constructor();
 }
+export declare class StoreAlreadyRegisteredError extends Error {
+    constructor(store: string);
+}
 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,6 +34,12 @@ export class HozonDBClosedError extends Error {
         this.name = 'HozonDBClosedError';
     }
 }
+export class StoreAlreadyRegisteredError extends Error {
+    constructor(store){
+        super(`Store "${store}" is already registered with a different definition`);
+        this.name = 'StoreAlreadyRegisteredError';
+    }
+}
 export class BatchLimitError extends Error {
     constructor(size, limit){
         super(`Batch of ${size} keys exceeds limit ${limit}`);

package/lib/index.d.ts

@@ -3,9 +3,10 @@ export { Kysely, sql } from 'kysely';
 export type { Migration } from 'kysely/migration';
 export { assertBatchSize, type BatchReadOptions, type IterateBatchesOptions, iterateBatches, } from './batch.js';
 export { type BatchLoader, type BatchLoaderParams, createBatchLoader, } from './batch-loader.js';
-export type { HozonDBParams, MigrationContext, StoreContext, StoreDefinition, StoreProvider, } from './db.js';
+export type { BaseStoreContext, ContextFactory, HozonDBParams, MigrationContext, StoreContext, StoreDefinition, StoreProvider, } from './db.js';
 export { HozonDB } from './db.js';
-export { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError, } from './errors.js';
-export { chunk, withKeepSet } from './keep-set.js';
+export { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, KeyLockScopeError, SavepointOverlapError, SavepointReleasedError, SchemaVersionError, StoreAlreadyRegisteredError, } 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

@@ -2,7 +2,8 @@ export { Kysely, sql } from 'kysely';
 export { assertBatchSize, iterateBatches } from './batch.js';
 export { createBatchLoader } from './batch-loader.js';
 export { HozonDB } from './db.js';
-export { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError } from './errors.js';
-export { chunk, withKeepSet } from './keep-set.js';
+export { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, KeyLockScopeError, SavepointOverlapError, SavepointReleasedError, SchemaVersionError, StoreAlreadyRegisteredError } 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/preflight.d.ts

@@ -1,2 +1,4 @@
 import type { Kysely } from 'kysely';
+/** Names of the migrations recorded for a store, or `null` when its migration table is absent. */
+export declare function readAppliedMigrations<DB>(db: Kysely<DB>, prefix: string, name: string): Promise<Set<string> | null>;
 export declare function checkStore<DB>(db: Kysely<DB>, prefix: string, name: string, keys: Array<string>): Promise<void>;

package/lib/preflight.js

@@ -1,18 +1,23 @@
 import { sql } from 'kysely';
 import { SchemaVersionError } from './errors.js';
-export async function checkStore(db, prefix, name, keys) {
-    let rows;
+/** Names of the migrations recorded for a store, or `null` when its migration table is absent. */ export async function readAppliedMigrations(db, prefix, name) {
     try {
         const result = await sql`SELECT name FROM ${sql.table(`${prefix}_${name}_migration`)}`.execute(db);
-        rows = result.rows;
+        return new Set(result.rows.map((row)=>row.name));
     } catch (error) {
         // Only a missing table is a fresh schema. Connection and permission errors must surface.
         if (error instanceof Error && ('code' in error && error.code === '42P01' || /no such table:/i.test(error.message))) {
-            return;
+            return null;
         }
         throw error;
     }
+}
+export async function checkStore(db, prefix, name, keys) {
+    const applied = await readAppliedMigrations(db, prefix, name);
+    if (applied == null) return;
     const known = new Set(keys);
-    const unknown = rows.map((row)=>row.name).filter((key)=>!known.has(key)).sort();
+    const unknown = [
+        ...applied
+    ].filter((key)=>!known.has(key)).sort();
     if (unknown.length > 0) throw new SchemaVersionError(name, unknown);
 }

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.3.0",
+  "version": "0.5.0",
   "description": "Database registry, migrations and transactions for Hozon",
   "repository": {
     "type": "git",
@@ -17,13 +17,13 @@
     "lib/*"
   ],
   "dependencies": {
-    "@hozon/adapter": "^0.1.0",
+    "@hozon/adapter": "^0.2.1",
     "@sozai/async": "^0.4.1",
     "@sozai/log": "^0.4.0",
     "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@hozon/node-sqlite": "^0.1.0",
+    "@hozon/node-sqlite": "^0.2.0",
     "@types/node": "^26.6.5",
     "del-cli": "^8.0.1",
     "vitest": "5.0.5"