@kubun/db 0.17.0 → 0.18.0

package/lib/db.d.ts

@@ -1,18 +1,98 @@
-import type { Adapter, ColumnTypes, Functions } from '@kubun/db-adapter';
+import { type Adapter, type ColumnTypes, type Functions } from '@kubun/db-adapter';
 import { type Logger } from '@kubun/logger';
 import { Kysely } from 'kysely';
 import { type Migration } from 'kysely/migration';
+/** The SQL dialect family an adapter speaks. */
+export type MigrationDialect = 'postgres' | 'sqlite';
 export type MigrationContext = {
     types: ColumnTypes;
     functions: Functions;
+    dialect: MigrationDialect;
 };
+/** The migration context for an adapter, as KubunDB passes it to store migrations. */
+export declare function getMigrationContext(adapter: Adapter): MigrationContext;
 export type StoreDefinition<Tables, API> = {
     name: string;
     migrations: Record<string, Migration> | ((ctx: MigrationContext) => Record<string, Migration>);
     dependsOn?: Array<string>;
-    createAPI: (db: Kysely<Tables>, adapter: Adapter) => API;
+    createAPI: (db: Kysely<Tables>, adapter: Adapter, context?: StoreAPIContext) => API;
 };
+export type StoreAPIContext = {
+    provider: StoreProvider;
+    root: StoreProvider;
+    getCatalogRouteRules(nowMS: number, catalog?: CatalogRef): Promise<CatalogRouteRulesInput>;
+    /** Route rules read through the root provider: safe for work that outlives a transaction. */
+    getRootCatalogRouteRules(nowMS: number, catalog?: CatalogRef): Promise<CatalogRouteRulesInput>;
+    onClose?: (fn: () => Promise<void> | void) => void;
+    /** Bound to `provider`: tells the document bytes listeners, in the caller's transaction. */
+    documentBytes: {
+        needed(documentID: string): Promise<void>;
+        released(documentID: string): Promise<void>;
+    };
+    /** Bound to `provider`: tells the document applied listeners, in the caller's transaction. */
+    documentApplied(event: DocumentAppliedEvent): Promise<void>;
+    /** Absent until custody pin hooks are registered, and then bound to `provider`. */
+    custody?: {
+        guards(): Promise<ReadonlyArray<CustodyGuard>>;
+        keepsOwner(custodyOwner: string, documentOwner: string): Promise<boolean>;
+        /** Call once a queued custody scan is committed. */
+        scansQueued(): void;
+    };
+    /** Call once a stored custody assignment or acceptance is committed. */
+    custodyRecordsChanged?(): void;
+};
+/** A catalog's address: its owner DID and the owner-chosen catalog ID. */
+export type CatalogRef = {
+    owner: string;
+    id: string;
+};
+/** A catalog this device has accepted to guard for a custody owner. */
+export type CustodyGuard = {
+    catalog: CatalogRef;
+    custodyOwner: string;
+};
+export type CustodyPinHooks = {
+    /** The custodies this device currently guards, read through `stores`. */
+    guards(stores: StoreProvider): Promise<ReadonlyArray<CustodyGuard>>;
+    /** Whether the custody owner keeps documents of this owner: own or unresolved. */
+    keepsOwner(stores: StoreProvider, custodyOwner: string, documentOwner: string): Promise<boolean>;
+    /** Wakes whatever runs queued custody scans, so a scan need not wait for the next start. */
+    scansQueued?(): void;
+};
+/**
+ * Runs in the transaction that recomputes a document's refs. `needed`: a custody pin or a
+ * `SERVE_ONLY` catalog keeps the live document, so this device keeps its attachment bytes.
+ * `released`: the document held such a ref and holds none now.
+ */
+export type DocumentBytesListener = {
+    needed(stores: StoreProvider, documentID: string): Promise<void>;
+    released(stores: StoreProvider, documentID: string): Promise<void>;
+};
+/** A document's data was written in the transaction; `authored`: this device wrote it. */
+export type DocumentAppliedEvent = {
+    documentID: string;
+    authored: boolean;
+};
+/** Runs in the transaction that writes a document's data; a throw rolls that write back. */
+export type DocumentAppliedListener = (stores: StoreProvider, event: DocumentAppliedEvent) => Promise<void>;
+export type CatalogRouteRulesInput = ReadonlyArray<{
+    catalog: CatalogRef;
+    rules: ReadonlyArray<{
+        id: string;
+        models?: Array<string>;
+        owners?: Array<string>;
+        maxAge?: string;
+        maxAhead?: string;
+        dateField?: string;
+    }>;
+}>;
 export type StoreProvider<Stores extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly isTransactionBound: boolean;
+    /**
+     * The outermost transaction's provider, shared by its savepoint scopes. Lets
+     * per-transaction state survive a savepoint boundary. Absent outside a transaction.
+     */
+    readonly transactionRoot?: StoreProvider;
     getStore<S extends keyof Stores & string>(name: S): Promise<Stores[S]>;
     /**
      * Returns whether a store definition is registered, synchronously and
@@ -41,20 +121,46 @@ export type StoreProvider<Stores extends Record<string, unknown> = Record<string
      * On a transactional `tx` provider obtained from a parent
      * `withTransaction` call, this method runs `fn` inline with `this` as the
      * nested `tx`. The underlying driver does not nest transactions
-     * (no savepoints), so atomicity is inherited from the outer transaction
-     * — a throw in `fn` rolls the whole outer transaction back, exactly the
-     * semantics callers expect for "register + bind atomically".
+     * (no implicit savepoints), so atomicity is inherited from the enclosing
+     * transaction or explicit savepoint.
      */
     withTransaction<NestedStores extends Record<string, unknown>, R>(fn: (tx: 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>;
 };
+/**
+ * Thrown when a scope opens a savepoint while one of its savepoints is still
+ * open. Run sequential savepoints one after another, and nest through the
+ * provider the open savepoint passes to its callback.
+ */
+export declare class SavepointOverlapError extends Error {
+    constructor();
+}
 export type KubunDBParams = {
     adapter: Adapter;
     logger?: Logger;
 };
 export declare class KubunDB implements StoreProvider {
     #private;
+    get isTransactionBound(): boolean;
     constructor(params: KubunDBParams);
     get adapter(): Adapter;
+    setCatalogRouteRulesProvider(provider: (stores: StoreProvider, nowMS: number, catalog?: CatalogRef) => Promise<CatalogRouteRulesInput>): void;
+    /**
+     * Register the check a local catalog rule change must pass before it commits:
+     * whatever routes the catalog decides which limits apply. Called inside the
+     * write's transaction, so a throw rolls the change back.
+     */
+    setCatalogRuleWriteValidator(validator: (stores: StoreProvider, catalog: CatalogRef) => Promise<void>): void;
+    /** Register how ref recompute learns which custodies pin documents here. */
+    setCustodyPinHooks(hooks: CustodyPinHooks): void;
+    /** A throwing listener rolls back the transaction that recomputed the document's refs. */
+    addDocumentBytesListener(listener: DocumentBytesListener): () => void;
+    /** A throwing listener rolls back the transaction that wrote the document's data. */
+    addDocumentAppliedListener(listener: DocumentAppliedListener): () => void;
+    /** Called after a custody assignment or acceptance write commits; errors are logged. */
+    addCustodyRecordsListener(listener: () => void): () => void;
+    validateCatalogRuleWrite(stores: StoreProvider, catalog: CatalogRef): Promise<void>;
     register<Tables, API>(store: StoreDefinition<Tables, API>): void;
     getStore<T>(name: string): Promise<T>;
     hasStore(name: string): boolean;

package/lib/db.js

@@ -1,13 +1,42 @@
+import { AbstractPostgresAdapter } from '@kubun/db-adapter';
 import { getKubunLogger } from '@kubun/logger';
-import { Kysely, ParseJSONResultsPlugin } from 'kysely';
+import { Kysely, ParseJSONResultsPlugin, sql } from 'kysely';
 import { Migrator } from 'kysely/migration';
+/** The migration context for an adapter, as KubunDB passes it to store migrations. */ export function getMigrationContext(adapter) {
+    return {
+        types: adapter.types,
+        functions: adapter.functions,
+        dialect: adapter instanceof AbstractPostgresAdapter ? 'postgres' : 'sqlite'
+    };
+}
+/**
+ * Thrown when a scope opens a savepoint while one of its savepoints is still
+ * open. Run sequential savepoints one after another, and nest through the
+ * provider the open savepoint passes to its callback.
+ */ export class SavepointOverlapError extends Error {
+    constructor(){
+        super('A savepoint is already open in this transaction scope');
+        this.name = 'SavepointOverlapError';
+    }
+}
 export class KubunDB {
+    get isTransactionBound() {
+        return false;
+    }
     #adapter;
     #db;
     #logger;
     #migrated = new Map();
     #storeAPIs = new Map();
     #stores = new Map();
+    #closeHooks = new Set();
+    #closePromise = null;
+    #catalogRouteRulesProvider = null;
+    #catalogRuleWriteValidator = null;
+    #custodyPinHooks = null;
+    #documentBytesListeners = new Set();
+    #documentAppliedListeners = new Set();
+    #custodyRecordsListeners = new Set();
     constructor(params){
         this.#adapter = params.adapter;
         this.#db = new Kysely({
@@ -21,6 +50,81 @@ export class KubunDB {
     get adapter() {
         return this.#adapter;
     }
+    setCatalogRouteRulesProvider(provider) {
+        this.#catalogRouteRulesProvider = provider;
+    }
+    /**
+   * Register the check a local catalog rule change must pass before it commits:
+   * whatever routes the catalog decides which limits apply. Called inside the
+   * write's transaction, so a throw rolls the change back.
+   */ setCatalogRuleWriteValidator(validator) {
+        this.#catalogRuleWriteValidator = validator;
+    }
+    /** Register how ref recompute learns which custodies pin documents here. */ setCustodyPinHooks(hooks) {
+        this.#custodyPinHooks = hooks;
+    }
+    /** A throwing listener rolls back the transaction that recomputed the document's refs. */ addDocumentBytesListener(listener) {
+        this.#documentBytesListeners.add(listener);
+        return ()=>{
+            this.#documentBytesListeners.delete(listener);
+        };
+    }
+    /** A throwing listener rolls back the transaction that wrote the document's data. */ addDocumentAppliedListener(listener) {
+        this.#documentAppliedListeners.add(listener);
+        return ()=>{
+            this.#documentAppliedListeners.delete(listener);
+        };
+    }
+    /** Called after a custody assignment or acceptance write commits; errors are logged. */ addCustodyRecordsListener(listener) {
+        this.#custodyRecordsListeners.add(listener);
+        return ()=>{
+            this.#custodyRecordsListeners.delete(listener);
+        };
+    }
+    #custodyRecordsChanged() {
+        for (const listener of this.#custodyRecordsListeners){
+            try {
+                listener();
+            } catch (error) {
+                this.#logger.warn('custody records listener failed', {
+                    error
+                });
+            }
+        }
+    }
+    #documentBytesContext(stores) {
+        return {
+            needed: async (documentID)=>{
+                for (const listener of this.#documentBytesListeners)await listener.needed(stores, documentID);
+            },
+            released: async (documentID)=>{
+                for (const listener of this.#documentBytesListeners)await listener.released(stores, documentID);
+            }
+        };
+    }
+    #documentAppliedContext(stores) {
+        return async (event)=>{
+            for (const listener of this.#documentAppliedListeners)await listener(stores, event);
+        };
+    }
+    #custodyContext(stores) {
+        const hooks = this.#custodyPinHooks;
+        if (hooks == null) return undefined;
+        return {
+            guards: ()=>hooks.guards(stores),
+            keepsOwner: (custodyOwner, documentOwner)=>hooks.keepsOwner(stores, custodyOwner, documentOwner),
+            scansQueued: ()=>{
+                hooks.scansQueued?.();
+            }
+        };
+    }
+    async validateCatalogRuleWrite(stores, catalog) {
+        await this.#catalogRuleWriteValidator?.(stores, catalog);
+    }
+    async #getCatalogRouteRules(stores, nowMS, catalog) {
+        const rules = await this.#catalogRouteRulesProvider?.(stores, nowMS, catalog) ?? [];
+        return catalog == null ? rules : rules.filter((entry)=>entry.catalog.owner === catalog.owner && entry.catalog.id === catalog.id);
+    }
     register(store) {
         const existing = this.#stores.get(store.name);
         if (existing != null) {
@@ -40,7 +144,21 @@ export class KubunDB {
             if (store == null) {
                 throw new Error(`Store "${name}" is not registered`);
             }
-            this.#storeAPIs.set(name, store.createAPI(this.#db, this.#adapter));
+            const custodyContext = ()=>this.#custodyContext(this);
+            this.#storeAPIs.set(name, store.createAPI(this.#db, this.#adapter, {
+                provider: this,
+                root: this,
+                getCatalogRouteRules: (nowMS, catalog)=>this.#getCatalogRouteRules(this, nowMS, catalog),
+                getRootCatalogRouteRules: (nowMS, catalog)=>this.#getCatalogRouteRules(this, nowMS, catalog),
+                onClose: (fn)=>this.#closeHooks.add(fn),
+                documentBytes: this.#documentBytesContext(this),
+                documentApplied: this.#documentAppliedContext(this),
+                custodyRecordsChanged: ()=>this.#custodyRecordsChanged(),
+                // Read when called, so hooks registered after the store was created still apply.
+                get custody () {
+                    return custodyContext();
+                }
+            }));
         }
         return this.#storeAPIs.get(name);
     }
@@ -69,36 +187,98 @@ export class KubunDB {
         const commitHooks = [];
         const rollbackHooks = [];
         let result;
+        let savepointID = 0;
         try {
             result = await this.#db.transaction().execute(async (trx)=>{
                 const txKysely = trx;
-                const txStoreAPIs = new Map();
-                const provider = {
-                    getStore: async (name)=>{
-                        if (!txStoreAPIs.has(name)) {
-                            const store = this.#stores.get(name);
-                            if (store == null) {
-                                throw new Error(`Store "${name}" is not registered`);
+                let rootProvider;
+                const createScopedProvider = (scopedCommitHooks, scopedRollbackHooks)=>{
+                    // 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 scopedStoreAPIs = new Map();
+                    const provider = {
+                        isTransactionBound: true,
+                        get transactionRoot () {
+                            return rootProvider;
+                        },
+                        getStore: async (name)=>{
+                            if (!scopedStoreAPIs.has(name)) {
+                                const store = this.#stores.get(name);
+                                if (store == null) {
+                                    throw new Error(`Store "${name}" is not registered`);
+                                }
+                                const custodyContext = ()=>this.#custodyContext(provider);
+                                scopedStoreAPIs.set(name, store.createAPI(txKysely, this.#adapter, {
+                                    provider,
+                                    root: this,
+                                    getCatalogRouteRules: (nowMS, catalog)=>this.#getCatalogRouteRules(provider, nowMS, catalog),
+                                    getRootCatalogRouteRules: (nowMS, catalog)=>this.#getCatalogRouteRules(this, nowMS, catalog),
+                                    onClose: (fn)=>this.#closeHooks.add(fn),
+                                    documentBytes: this.#documentBytesContext(provider),
+                                    documentApplied: this.#documentAppliedContext(provider),
+                                    custodyRecordsChanged: ()=>this.#custodyRecordsChanged(),
+                                    get custody () {
+                                        return custodyContext();
+                                    }
+                                }));
+                            }
+                            return scopedStoreAPIs.get(name);
+                        },
+                        hasStore: (name)=>this.#stores.has(name),
+                        onCommit: (hook)=>{
+                            scopedCommitHooks.push(hook);
+                        },
+                        onRollback: (hook)=>{
+                            scopedRollbackHooks.push(hook);
+                        },
+                        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.
+                            return await nestedFn(provider);
+                        },
+                        withSavepoint: async (nestedFn)=>{
+                            if (savepointOpen) throw new SavepointOverlapError();
+                            savepointOpen = true;
+                            try {
+                                const name = `kubun_sp_${++savepointID}`;
+                                const savepointCommitHooks = [];
+                                const savepointRollbackHooks = [];
+                                const scopedProvider = createScopedProvider(savepointCommitHooks, savepointRollbackHooks);
+                                await sql.raw(`SAVEPOINT ${name}`).execute(trx);
+                                try {
+                                    const value = await nestedFn(scopedProvider);
+                                    await sql.raw(`RELEASE SAVEPOINT ${name}`).execute(trx);
+                                    scopedCommitHooks.push(...savepointCommitHooks);
+                                    scopedRollbackHooks.push(...savepointRollbackHooks);
+                                    return value;
+                                } catch (error) {
+                                    await sql.raw(`ROLLBACK TO SAVEPOINT ${name}`).execute(trx);
+                                    await sql.raw(`RELEASE SAVEPOINT ${name}`).execute(trx);
+                                    for (const [index, hook] of savepointRollbackHooks.entries()){
+                                        try {
+                                            hook();
+                                        } catch (hookError) {
+                                            this.#logger.error('rollback hook {index}/{count} failed', {
+                                                index,
+                                                count: savepointRollbackHooks.length,
+                                                error: hookError
+                                            });
+                                        }
+                                    }
+                                    throw error;
+                                }
+                            } finally{
+                                savepointOpen = false;
                             }
-                            txStoreAPIs.set(name, store.createAPI(txKysely, this.#adapter));
                         }
-                        return txStoreAPIs.get(name);
-                    },
-                    hasStore: (name)=>this.#stores.has(name),
-                    onCommit: (hook)=>{
-                        commitHooks.push(hook);
-                    },
-                    onRollback: (hook)=>{
-                        rollbackHooks.push(hook);
-                    },
-                    withTransaction: async (nestedFn)=>{
-                        // Already inside a transaction — Kysely does not nest.
-                        // Run `nestedFn` inline with the same provider so a throw rolls
-                        // the outer transaction back.
-                        return await nestedFn(provider);
-                    }
+                    };
+                    rootProvider ??= provider;
+                    return provider;
                 };
-                return await fn(provider);
+                return await fn(createScopedProvider(commitHooks, rollbackHooks));
             });
         } catch (err) {
             // Kysely issues ROLLBACK and rejects `execute()` when the callback
@@ -137,9 +317,14 @@ export class KubunDB {
         }
         return result;
     }
-    async close() {
-        await this.#db.destroy();
-        this.#logger.info('closed');
+    close() {
+        this.#closePromise ??= Promise.resolve().then(async ()=>{
+            for (const hook of this.#closeHooks)await hook();
+            this.#closeHooks.clear();
+            await this.#db.destroy();
+            this.#logger.info('closed');
+        });
+        return this.#closePromise;
     }
     async #ensureMigrated(name) {
         let pending = this.#migrated.get(name);
@@ -160,10 +345,7 @@ export class KubunDB {
         for (const dep of store.dependsOn ?? []){
             await this.#ensureMigrated(dep);
         }
-        const migrations = typeof store.migrations === 'function' ? store.migrations({
-            types: this.#adapter.types,
-            functions: this.#adapter.functions
-        }) : store.migrations;
+        const migrations = typeof store.migrations === 'function' ? store.migrations(getMigrationContext(this.#adapter)) : store.migrations;
         if (Object.keys(migrations).length === 0) {
             return;
         }

package/lib/index.d.ts

@@ -1 +1 @@
-export { KubunDB, type KubunDBParams, type MigrationContext, type StoreDefinition, type StoreProvider, } from './db.js';
+export { type CatalogRef, type CustodyGuard, type CustodyPinHooks, type DocumentAppliedEvent, type DocumentAppliedListener, type DocumentBytesListener, getMigrationContext, KubunDB, type KubunDBParams, type MigrationContext, type MigrationDialect, SavepointOverlapError, type StoreAPIContext, type StoreDefinition, type StoreProvider, } from './db.js';

package/lib/index.js

@@ -1 +1 @@
-export { KubunDB } from './db.js';
+export { getMigrationContext, KubunDB, SavepointOverlapError } from './db.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/db",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,12 +15,14 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/db-adapter": "^0.17.0",
-    "@kubun/logger": "^0.17.0",
-    "kysely": "^0.29.5"
+    "@kubun/db-adapter": "^0.18.0",
+    "@kubun/logger": "^0.18.0",
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.17.0"
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/db-postgres": "^0.18.0",
+    "@testcontainers/postgresql": "^12.2.1"
   },
   "publishConfig": {
     "access": "public"