@hozon/db 0.2.2 → 0.3.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,12 +2,16 @@ 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';
 export type MigrationContext = {
     tablePrefix: string;
     kind: Adapter['kind'];
     types: ColumnTypes;
     functions: Functions;
 };
+export type StoreContext = {
+    createLoader<TKey, TValue>(params: BatchLoaderParams<TKey, TValue>): BatchLoader<TKey, TValue>;
+};
 export type StoreDefinition<Tables, API> = {
     name: string;
     migrations: Record<string, Migration> | ((ctx: MigrationContext) => Record<string, Migration>);
@@ -18,7 +22,7 @@ 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;
+    createAPI: (db: Kysely<Tables>, adapter: Adapter, context: StoreContext) => API;
 };
 export type StoreProvider<Stores extends Record<string, unknown> = Record<string, unknown>> = {
     getStore<S extends keyof Stores & string>(name: S): Promise<Stores[S]>;
@@ -53,6 +57,7 @@ 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>;
 };
@@ -70,6 +75,7 @@ export declare class HozonDB implements StoreProvider {
     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

package/lib/db.js

@@ -1,8 +1,9 @@
 import { getLogger } from '@sozai/log';
-import { Kysely, ParseJSONResultsPlugin, sql } from 'kysely';
+import { Kysely, sql } from 'kysely';
 import { Migrator } from 'kysely/migration';
 import { withTransactionalDDL } from './dialect.js';
 import { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError } from './errors.js';
+import { LoaderRegistry } from './loader-registry.js';
 import { checkStore } from './preflight.js';
 import { TablePrefixPlugin } from './table-prefix.js';
 export class HozonDB {
@@ -19,6 +20,9 @@ export class HozonDB {
     #storePlugins = new Map();
     #logger;
     #migrated = new Map();
+    #loaders = new LoaderRegistry({
+        remember: false
+    });
     #storeAPIs = new Map();
     #stores = new Map();
     constructor(params){
@@ -30,10 +34,7 @@ export class HozonDB {
         this.#adapter = params.adapter;
         this.#db = new Kysely({
             // SQLite supports transactional DDL, but Kysely's SQLite adapters do not report it.
-            dialect: this.#adapter.kind === 'sqlite' ? withTransactionalDDL(this.#adapter.dialect) : this.#adapter.dialect,
-            plugins: [
-                new ParseJSONResultsPlugin()
-            ]
+            dialect: this.#adapter.kind === 'sqlite' ? withTransactionalDDL(this.#adapter.dialect) : this.#adapter.dialect
         });
         this.#storeDB = this.#db.withPlugin(this.#defaultPlugin);
         this.#logger = params.logger ?? getLogger([
@@ -66,8 +67,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));
         }
         return this.#storeAPIs.get(name);
     }
@@ -79,6 +79,41 @@ 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 = {
+            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));
+                }
+                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
@@ -88,6 +123,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
@@ -96,6 +134,9 @@ export class HozonDB {
         this.#assertOpen();
         const commitHooks = [];
         const rollbackHooks = [];
+        const registry = new LoaderRegistry({
+            remember: true
+        });
         let result;
         let savepointID = 0;
         try {
@@ -116,8 +157,7 @@ export class HozonDB {
                                 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));
                             }
                             return txStoreAPIs.get(name);
                         },
@@ -128,6 +168,9 @@ export class HozonDB {
                         onRollback: (hook)=>{
                             scopedRollbackHooks.push(hook);
                         },
+                        withScope: async (nestedFn)=>{
+                            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
@@ -142,16 +185,21 @@ export class HozonDB {
                                 const savepointCommitHooks = [];
                                 const savepointRollbackHooks = [];
                                 const scopedProvider = createScopedProvider(savepointCommitHooks, savepointRollbackHooks);
+                                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);
                                     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);
+                                    registry.clearAll();
                                     this.#runHooks(savepointRollbackHooks, 'rollback');
                                     throw error;
                                 }
@@ -162,9 +210,14 @@ export class HozonDB {
                     };
                     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
@@ -174,6 +227,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
@@ -239,6 +294,14 @@ 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) {
+        const storeDB = store.unprefixedTables == null ? defaultDB : kysely.withPlugin(this.#getStorePlugin(store));
+        return store.createAPI(storeDB, this.#adapter, {
+            createLoader: (params)=>registry.createLoader(params)
+        });
+    }
     #getStorePlugin(store) {
         if (store.unprefixedTables == null) return this.#defaultPlugin;
         let plugin = this.#storePlugins.get(store.name);

package/lib/errors.d.ts

@@ -10,3 +10,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

@@ -22,3 +22,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,11 @@
 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 { HozonDBParams, MigrationContext, StoreContext, StoreDefinition, StoreProvider, } from './db.js';
 export { HozonDB } from './db.js';
-export { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError, } from './errors.js';
+export { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError, } from './errors.js';
 export { chunk, withKeepSet } from './keep-set.js';
 export { withStoreTransaction } from './store-transaction.js';
 export { type TablePrefixOptions, TablePrefixPlugin } from './table-prefix.js';

package/lib/index.js

@@ -1,6 +1,8 @@
 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 { BatchLimitError, HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError } from './errors.js';
 export { chunk, withKeepSet } from './keep-set.js';
 export { withStoreTransaction } from './store-transaction.js';
 export { TablePrefixPlugin } from './table-prefix.js';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hozon/db",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Database registry, migrations and transactions for Hozon",
   "repository": {
     "type": "git",
@@ -18,14 +18,15 @@
   ],
   "dependencies": {
     "@hozon/adapter": "^0.1.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"
+    "@types/node": "^26.6.5",
+    "del-cli": "^8.0.1",
+    "vitest": "5.0.5"
   },
   "engines": {
     "node": ">=24"