@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/storage/datastore/Datastore.js

@@ -0,0 +1,525 @@
+/* eslint-disable max-lines */
+import { ConfigurationError, IndexCorruptionError, InvalidQueryRangeError, QuotaExceededError, ValidationError, toErrorInstance, } from '../../errors/index.js';
+import { toPublicRecord } from '../record/ordering.js';
+import { emitAutoCommitErrorToListeners } from '../backend/autoCommit.js';
+import { AsyncMutex } from '../backend/asyncMutex.js';
+import { validateAndNormalizePayload } from '../../validation/payload.js';
+import { enforceCapacityPolicy } from '../backend/capacity.js';
+import { resolveCapacityState } from '../backend/capacityResolver.js';
+import { estimateKeySizeBytes, estimateRecordSizeBytes } from '../backend/encoding.js';
+import { parseDuplicateKeyConfig } from '../config/config.shared.js';
+import { DatastoreLifecycle } from './datastoreLifecycle.js';
+import { deleteRecordById, getPublicRecordById, updateRecordById, } from './mutationById.js';
+import { closeDatastore } from './datastoreClose.js';
+import { RecordKeyIndexBTree, clampComparatorResult, normalizeComparatorResult, } from '../btree/recordKeyIndexBTree.js';
+import { readRawInsertKey, resolveKeyDefinition, } from './datastoreKeyDefinition.js';
+export class Datastore {
+    errorListeners;
+    keyIndex;
+    keyDefinition;
+    duplicateKeyPolicy;
+    capacityState;
+    skipPayloadValidation;
+    lifecycle;
+    writeMutex;
+    currentSizeBytes;
+    backendController;
+    pendingInit;
+    pendingInitError;
+    constructor(config) {
+        this.errorListeners = new Set();
+        this.keyDefinition = resolveKeyDefinition(config);
+        const duplicateKeys = parseDuplicateKeyConfig(config.duplicateKeys);
+        this.duplicateKeyPolicy = duplicateKeys;
+        this.keyIndex = new RecordKeyIndexBTree({
+            compareKeys: (left, right) => this.keyDefinition.compare(left, right),
+            duplicateKeys,
+        });
+        this.capacityState = resolveCapacityState(config);
+        this.skipPayloadValidation = config.skipPayloadValidation === true;
+        this.lifecycle = new DatastoreLifecycle();
+        this.writeMutex = new AsyncMutex();
+        this.currentSizeBytes = 0;
+        this.backendController = null;
+        this.pendingInit = null;
+        this.pendingInitError = null;
+        if (config.driver === undefined) {
+            if (config.autoCommit !== undefined) {
+                throw new ConfigurationError('autoCommit requires a durable driver.');
+            }
+            return;
+        }
+        const backendInit = config.driver.init({
+            getSnapshot: () => ({
+                treeJSON: this.keyIndex.toJSON(),
+            }),
+            autoCommit: config.autoCommit,
+            onAutoCommitError: (error) => {
+                emitAutoCommitErrorToListeners(this.errorListeners, error);
+            },
+        });
+        if (!isPromiseLike(backendInit)) {
+            this.applyBackendInitResult(backendInit);
+            return;
+        }
+        this.pendingInit = Promise.resolve(backendInit)
+            .then((result) => { this.applyBackendInitResult(result); })
+            .catch((error) => {
+            this.pendingInitError = toErrorInstance(error, 'Datastore backend initialization failed with a non-Error value.');
+        })
+            .finally(() => {
+            this.pendingInit = null; // clear atomically after init settles (single-flight)
+        });
+    }
+    put(record) {
+        return this.runWithOpenExclusive(() => this.putSingle(record));
+    }
+    get(key) {
+        return this.runWithOpen(() => {
+            const normalizedKey = this.keyDefinition.normalize(key, 'key');
+            return this.keyIndex.rangeQuery(normalizedKey, normalizedKey).map((e) => toPublicRecord(e.entryId, e.key, e.value));
+        });
+    }
+    getFirst(key) {
+        return this.runWithOpen(() => {
+            const normalizedKey = this.keyDefinition.normalize(key, 'key');
+            const entry = this.keyIndex.findFirst(normalizedKey);
+            if (entry === null) {
+                return null;
+            }
+            return toPublicRecord(entry.entryId, entry.key, entry.value);
+        });
+    }
+    getLast(key) {
+        return this.runWithOpen(() => {
+            const normalizedKey = this.keyDefinition.normalize(key, 'key');
+            const entry = this.keyIndex.findLast(normalizedKey);
+            if (entry === null) {
+                return null;
+            }
+            return toPublicRecord(entry.entryId, entry.key, entry.value);
+        });
+    }
+    delete(key) {
+        return this.runWithOpenExclusive(() => this.deleteSingle(key));
+    }
+    has(key) {
+        return this.runWithOpen(() => {
+            const normalizedKey = this.keyDefinition.normalize(key, 'key');
+            return this.keyIndex.hasKey(normalizedKey);
+        });
+    }
+    getAll() {
+        return this.runWithOpen(() => {
+            return this.keyIndex.snapshot().map((e) => toPublicRecord(e.entryId, e.key, e.value));
+        });
+    }
+    getRange(start, end) {
+        return this.runWithOpen(() => {
+            const normalizedStart = this.keyDefinition.normalize(start, 'start');
+            const normalizedEnd = this.keyDefinition.normalize(end, 'end');
+            if (normalizeComparatorResult(this.keyDefinition.compare(normalizedStart, normalizedEnd)) > 0) {
+                throw new InvalidQueryRangeError('start must be <= end.');
+            }
+            return this.keyIndex.rangeQuery(normalizedStart, normalizedEnd).map((e) => toPublicRecord(e.entryId, e.key, e.value));
+        });
+    }
+    getMany(keys) {
+        return this.runWithOpen(() => {
+            const normalizedKeys = [];
+            for (const key of keys) {
+                normalizedKeys.push(this.keyDefinition.normalize(key, 'key'));
+            }
+            normalizedKeys.sort((left, right) => clampComparatorResult(this.keyDefinition.compare(left, right)));
+            const results = [];
+            let lastKey = undefined;
+            for (let i = 0; i < normalizedKeys.length; i += 1) {
+                if (i > 0 && clampComparatorResult(this.keyDefinition.compare(normalizedKeys[i], lastKey)) === 0) {
+                    continue;
+                }
+                lastKey = normalizedKeys[i];
+                const entries = this.keyIndex.rangeQuery(normalizedKeys[i], normalizedKeys[i]);
+                for (const entry of entries) {
+                    results.push(toPublicRecord(entry.entryId, entry.key, entry.value));
+                }
+            }
+            return results;
+        });
+    }
+    putMany(records) {
+        return this.runWithOpenExclusive(async () => {
+            // P12: Pure in-memory sync loop — no capacity, no backend, no microtask overhead
+            if (this.capacityState === null && this.backendController === null) {
+                for (const record of records) {
+                    const { rawKey, keyFieldName } = readRawInsertKey(record);
+                    const normalizedKey = this.keyDefinition.normalize(rawKey, keyFieldName);
+                    if (this.duplicateKeyPolicy === 'reject' && this.keyIndex.findFirst(normalizedKey) !== null) {
+                        throw new ValidationError('Duplicate key rejected: a record with this key already exists.');
+                    }
+                    const normalizedPayload = this.skipPayloadValidation
+                        ? record.payload
+                        : validateAndNormalizePayload(record.payload).payload;
+                    this.keyIndex.put(normalizedKey, { payload: normalizedPayload, sizeBytes: 0 });
+                }
+                return;
+            }
+            // No capacity but has backend: need async for handleRecordAppended
+            if (this.capacityState === null) {
+                for (const record of records) {
+                    await this.putSingle(record);
+                }
+                return;
+            }
+            // Turnover policy: per-record path (eviction is order-dependent)
+            if (this.capacityState.policy === 'turnover') {
+                for (const record of records) {
+                    await this.putSingle(record);
+                }
+                return;
+            }
+            // Strict policy: atomic batch — prepare phase first, then insert
+            await this.putManyStrict(records);
+        });
+    }
+    deleteMany(keys) {
+        return this.runWithOpenExclusive(async () => {
+            // P12: Pure in-memory sync loop — no backend, no microtask overhead
+            if (this.backendController === null) {
+                let totalRemoved = 0;
+                for (const key of keys) {
+                    const normalizedKey = this.keyDefinition.normalize(key, 'key');
+                    const entries = this.keyIndex.rangeQuery(normalizedKey, normalizedKey);
+                    if (entries.length === 0) {
+                        continue;
+                    }
+                    let freedBytes = 0;
+                    for (const entry of entries) {
+                        freedBytes += entry.value.sizeBytes;
+                    }
+                    totalRemoved += this.keyIndex.deleteRange(normalizedKey, normalizedKey);
+                    this.currentSizeBytes = Math.max(0, this.currentSizeBytes - freedBytes);
+                }
+                return totalRemoved;
+            }
+            let totalRemoved = 0;
+            for (const key of keys) {
+                totalRemoved += await this.deleteSingle(key);
+            }
+            return totalRemoved;
+        });
+    }
+    clear() {
+        return this.runWithOpenExclusive(async () => {
+            this.keyIndex.clear();
+            this.currentSizeBytes = 0;
+            await this.backendController?.handleCleared();
+        });
+    }
+    count() {
+        return this.runWithOpen(() => {
+            return this.keyIndex.size();
+        });
+    }
+    keys() {
+        return this.runWithOpen(() => {
+            const distinctKeys = [];
+            let lastKey = undefined;
+            let isFirst = true;
+            for (const key of this.keyIndex.keys()) {
+                if (isFirst || clampComparatorResult(this.keyDefinition.compare(key, lastKey)) !== 0) {
+                    distinctKeys.push(key);
+                    lastKey = key;
+                    isFirst = false;
+                }
+            }
+            return distinctKeys;
+        });
+    }
+    getById(id) {
+        return this.runWithOpen(() => {
+            return getPublicRecordById(this.keyIndex, id);
+        });
+    }
+    updateById(id, patch) {
+        return this.runWithOpenExclusive(async () => {
+            const result = updateRecordById({
+                keyIndex: this.keyIndex,
+                id,
+                patch,
+                capacityState: this.capacityState,
+                currentSizeBytes: this.currentSizeBytes,
+                skipPayloadValidation: this.skipPayloadValidation,
+            });
+            if (!result.updated) {
+                return false;
+            }
+            this.currentSizeBytes = result.currentSizeBytes;
+            await this.backendController?.handleRecordAppended(result.durabilitySignalBytes);
+            return true;
+        });
+    }
+    deleteById(id) {
+        return this.runWithOpenExclusive(async () => {
+            const result = deleteRecordById({
+                keyIndex: this.keyIndex,
+                id,
+                currentSizeBytes: this.currentSizeBytes,
+            });
+            if (!result.deleted) {
+                return false;
+            }
+            this.currentSizeBytes = result.currentSizeBytes;
+            await this.backendController?.handleRecordAppended(result.durabilitySignalBytes);
+            return true;
+        });
+    }
+    commit() {
+        return this.runWithOpenExclusive(async () => {
+            await this.backendController?.commitNow();
+        });
+    }
+    on(event, listener) {
+        if (event !== 'error') {
+            throw new ValidationError('Only "error" event is supported.');
+        }
+        this.errorListeners.add(listener);
+        return () => { this.off(event, listener); };
+    }
+    off(event, listener) {
+        if (event !== 'error') {
+            throw new ValidationError('Only "error" event is supported.');
+        }
+        this.errorListeners.delete(listener);
+    }
+    async close() {
+        await closeDatastore({
+            lifecycle: this.lifecycle,
+            getPendingInit: () => this.pendingInit,
+            getPendingInitError: () => this.pendingInitError,
+            setPendingInitError: (pendingInitError) => {
+                this.pendingInitError = pendingInitError;
+            },
+            getBackendController: () => this.backendController,
+            setBackendController: (backendController) => {
+                this.backendController = backendController;
+            },
+            clearInMemoryState: () => {
+                this.keyIndex.clear();
+                this.errorListeners.clear();
+            },
+        });
+    }
+    resolvePayload(record, normalizedKey) {
+        if (this.skipPayloadValidation) {
+            const payload = record.payload;
+            return { payload, encodedBytes: estimateRecordSizeBytes(normalizedKey, payload) };
+        }
+        const validationResult = validateAndNormalizePayload(record.payload);
+        const keyBytes = estimateKeySizeBytes(normalizedKey);
+        return { payload: validationResult.payload, encodedBytes: validationResult.sizeBytes + keyBytes };
+    }
+    async putSingle(record) {
+        const { rawKey, keyFieldName } = readRawInsertKey(record);
+        const normalizedKey = this.keyDefinition.normalize(rawKey, keyFieldName);
+        // Fast-reject before expensive validation/serialization
+        if (this.duplicateKeyPolicy === 'reject' && this.keyIndex.findFirst(normalizedKey) !== null) {
+            throw new ValidationError('Duplicate key rejected: a record with this key already exists.');
+        }
+        // P5-A: Capacity-Bypass Fast Path — no capacity, no size tracking needed
+        if (this.capacityState === null && this.backendController === null) {
+            const normalizedPayload = this.skipPayloadValidation
+                ? record.payload
+                : validateAndNormalizePayload(record.payload).payload;
+            this.keyIndex.put(normalizedKey, { payload: normalizedPayload, sizeBytes: 0 });
+            return;
+        }
+        // Size computation needed (capacity or durable backend)
+        const { payload: normalizedPayload, encodedBytes } = this.resolvePayload(record, normalizedKey);
+        if (this.capacityState === null) {
+            // Durable but no capacity: bytes for backend signal only
+            this.keyIndex.put(normalizedKey, { payload: normalizedPayload, sizeBytes: encodedBytes });
+            await this.backendController.handleRecordAppended(encodedBytes);
+            return;
+        }
+        // Full enforcement path (capacity configured)
+        const persistedRecord = { payload: normalizedPayload, sizeBytes: encodedBytes };
+        if (encodedBytes > this.capacityState.maxSizeBytes) {
+            throw new QuotaExceededError('Record exceeds configured capacity.maxSize boundary.');
+        }
+        // For replace policy: remove the existing record before capacity enforcement
+        // so that the turnover eviction loop cannot evict the replacement target,
+        // which would cause the capacity delta to be miscalculated.
+        if (this.duplicateKeyPolicy === 'replace') {
+            const existing = this.keyIndex.findFirst(normalizedKey);
+            if (existing !== null) {
+                this.currentSizeBytes = Math.max(0, this.currentSizeBytes - existing.value.sizeBytes);
+                this.keyIndex.removeById(existing.entryId);
+            }
+        }
+        this.currentSizeBytes = enforceCapacityPolicy(this.capacityState, this.currentSizeBytes, encodedBytes, () => this.keyIndex.size(), () => {
+            const evicted = this.keyIndex.popFirst();
+            if (evicted === null) {
+                throw new IndexCorruptionError('Record buffer reported empty state during turnover eviction.');
+            }
+            return evicted.value.sizeBytes;
+        });
+        this.keyIndex.put(normalizedKey, persistedRecord);
+        this.currentSizeBytes = Math.max(0, this.currentSizeBytes + encodedBytes);
+        await this.backendController?.handleRecordAppended(encodedBytes);
+    }
+    async putManyStrict(records) {
+        const capacityState = this.capacityState;
+        const compare = this.keyDefinition.compare;
+        // Phase 1: Normalize all records and tag with original index — O(M)
+        const tagged = [];
+        for (let i = 0; i < records.length; i += 1) {
+            const { rawKey, keyFieldName } = readRawInsertKey(records[i]);
+            tagged.push({ idx: i, normalizedKey: this.keyDefinition.normalize(rawKey, keyFieldName), record: records[i] });
+        }
+        // Phase 2: Sort by (key, originalIndex) — O(M log M)
+        tagged.sort((a, b) => {
+            const cmp = clampComparatorResult(compare(a.normalizedKey, b.normalizedKey));
+            return cmp !== 0 ? cmp : a.idx - b.idx;
+        });
+        // Phase 3: Detect duplicates and build the deduplicated insertion list — O(M)
+        const { prepared, totalBatchDelta } = this.buildStrictBatchEntries(tagged, compare, capacityState.maxSizeBytes);
+        // Phase 4: Budget check — all-or-nothing
+        if (this.currentSizeBytes + totalBatchDelta > capacityState.maxSizeBytes) {
+            throw new QuotaExceededError('Insert exceeds configured capacity.maxSize under strict policy.');
+        }
+        // Phase 5: Insert — safe to mutate
+        let effectiveTotalDelta = 0;
+        let totalEncodedBytes = 0;
+        for (const { normalizedKey, persistedRecord, encodedBytes, replacedBytes } of prepared) {
+            const actualReplaced = replacedBytes > 0 && this.keyIndex.findFirst(normalizedKey) === null ? 0 : replacedBytes;
+            effectiveTotalDelta += encodedBytes - actualReplaced;
+            totalEncodedBytes += encodedBytes;
+            this.keyIndex.put(normalizedKey, persistedRecord);
+        }
+        this.currentSizeBytes = Math.max(0, this.currentSizeBytes + effectiveTotalDelta);
+        await this.backendController?.handleRecordAppended(totalEncodedBytes);
+    }
+    buildStrictBatchEntries(tagged, compare, maxSizeBytes) {
+        const prepared = [];
+        let totalBatchDelta = 0;
+        for (let i = 0; i < tagged.length; i += 1) {
+            const { normalizedKey, record } = tagged[i];
+            const isIntraBatchDuplicate = i > 0 && clampComparatorResult(compare(tagged[i - 1].normalizedKey, normalizedKey)) === 0;
+            if (this.duplicateKeyPolicy === 'reject') {
+                if (isIntraBatchDuplicate || this.keyIndex.findFirst(normalizedKey) !== null) {
+                    throw new ValidationError('Duplicate key rejected: a record with this key already exists.');
+                }
+            }
+            const { payload: normalizedPayload, encodedBytes } = this.resolvePayload(record, normalizedKey);
+            if (encodedBytes > maxSizeBytes) {
+                throw new QuotaExceededError('Record exceeds configured capacity.maxSize boundary.');
+            }
+            let replacedBytes = 0;
+            if (this.duplicateKeyPolicy === 'replace' && isIntraBatchDuplicate) {
+                const prev = prepared[prepared.length - 1];
+                totalBatchDelta -= prev.encodedBytes - prev.replacedBytes;
+                replacedBytes = prev.replacedBytes;
+                prepared.pop();
+            }
+            else if (this.duplicateKeyPolicy === 'replace') {
+                const existing = this.keyIndex.findFirst(normalizedKey);
+                replacedBytes = existing !== null ? existing.value.sizeBytes : 0;
+            }
+            const persistedRecord = { payload: normalizedPayload, sizeBytes: encodedBytes };
+            totalBatchDelta += encodedBytes - replacedBytes;
+            prepared.push({ normalizedKey, persistedRecord, encodedBytes, replacedBytes });
+        }
+        return { prepared, totalBatchDelta };
+    }
+    async deleteSingle(key) {
+        const normalizedKey = this.keyDefinition.normalize(key, 'key');
+        const entries = this.keyIndex.rangeQuery(normalizedKey, normalizedKey);
+        if (entries.length === 0) {
+            return 0;
+        }
+        let freedBytes = 0;
+        for (const entry of entries) {
+            freedBytes += entry.value.sizeBytes;
+        }
+        const removedCount = this.keyIndex.deleteRange(normalizedKey, normalizedKey);
+        this.currentSizeBytes = Math.max(0, this.currentSizeBytes - freedBytes);
+        await this.backendController?.handleRecordAppended(freedBytes);
+        return removedCount;
+    }
+    // P7: Synchronous fast-path — avoids async/Promise overhead for read operations
+    // when no pending init exists.
+    runWithOpen(operation) {
+        if (this.pendingInit !== null) {
+            return this.pendingInit.then(() => {
+                if (this.pendingInitError !== null) {
+                    throw this.pendingInitError;
+                }
+                return this.executeWithLifecycle(operation);
+            });
+        }
+        if (this.pendingInitError !== null) {
+            return Promise.reject(this.pendingInitError);
+        }
+        try {
+            return Promise.resolve(this.executeWithLifecycle(operation));
+        }
+        catch (error) {
+            return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    executeWithLifecycle(operation) {
+        this.lifecycle.beginOperation();
+        try {
+            const result = operation();
+            if (isPromiseLike(result)) {
+                return Promise.resolve(result).then((value) => { this.lifecycle.endOperation(); return value; }, (error) => { this.lifecycle.endOperation(); throw error; });
+            }
+            this.lifecycle.endOperation();
+            return result;
+        }
+        catch (error) {
+            this.lifecycle.endOperation();
+            throw error;
+        }
+    }
+    async runWithOpenExclusive(operation) {
+        const release = await this.writeMutex.acquire();
+        try {
+            return await this.runWithOpen(operation);
+        }
+        finally {
+            release();
+        }
+    }
+    applyBackendInitResult(result) {
+        if (result.initialTreeJSON !== null) {
+            this.keyIndex = RecordKeyIndexBTree.fromJSON(result.initialTreeJSON, {
+                compareKeys: (left, right) => {
+                    return this.keyDefinition.compare(left, right);
+                },
+                duplicateKeys: this.duplicateKeyPolicy,
+            });
+            this.backfillMissingSizeBytes();
+        }
+        this.currentSizeBytes = result.initialCurrentSizeBytes;
+        this.backendController = result.controller;
+    }
+    backfillMissingSizeBytes() {
+        for (const entry of this.keyIndex.snapshot()) {
+            if (typeof entry.value.sizeBytes !== 'number') {
+                const patched = {
+                    payload: entry.value.payload,
+                    sizeBytes: estimateRecordSizeBytes(entry.key, entry.value.payload),
+                };
+                this.keyIndex.updateById(entry.entryId, patched);
+            }
+        }
+    }
+}
+const isPromiseLike = (value) => {
+    if ((typeof value !== 'object' && typeof value !== 'function') ||
+        value === null) {
+        return false;
+    }
+    return typeof value.then === 'function';
+};

package/dist/storage/datastore/datastoreClose.d.ts

@@ -0,0 +1,12 @@
+import { DatastoreLifecycle } from './datastoreLifecycle.js';
+import type { DurableBackendController } from '../backend/types.js';
+export interface DatastoreCloseOptions {
+    lifecycle: DatastoreLifecycle;
+    getPendingInit: () => Promise<void> | null;
+    getPendingInitError: () => Error | null;
+    setPendingInitError: (pendingInitError: Error | null) => void;
+    getBackendController: () => DurableBackendController | null;
+    setBackendController: (backendController: DurableBackendController | null) => void;
+    clearInMemoryState: () => void;
+}
+export declare const closeDatastore: (options: DatastoreCloseOptions) => Promise<void>;

package/dist/storage/datastore/datastoreClose.js

@@ -0,0 +1,60 @@
+import { toErrorInstance } from '../../errors/index.js';
+const readAggregateErrorConstructor = () => {
+    const candidate = globalThis.AggregateError;
+    if (typeof candidate !== 'function') {
+        return null;
+    }
+    return candidate;
+};
+const createCloseAggregateError = (deferredError, closeError) => {
+    const aggregateErrorConstructor = readAggregateErrorConstructor();
+    if (aggregateErrorConstructor !== null) {
+        return new aggregateErrorConstructor([deferredError, closeError], 'Datastore close failed with multiple errors.');
+    }
+    const fallbackError = new Error('Datastore close failed with multiple errors.');
+    fallbackError.errors = [deferredError, closeError];
+    return fallbackError;
+};
+export const closeDatastore = async (options) => {
+    if (options.lifecycle.isClosed()) {
+        return;
+    }
+    const closeInFlight = options.lifecycle.getCloseInFlight();
+    if (closeInFlight !== null) {
+        await closeInFlight;
+        return;
+    }
+    options.lifecycle.markClosing();
+    const closeOperation = performClose(options).finally(() => {
+        options.lifecycle.setCloseInFlight(null);
+    });
+    options.lifecycle.setCloseInFlight(closeOperation);
+    await closeOperation;
+};
+const performClose = async (options) => {
+    const pendingInit = options.getPendingInit();
+    if (pendingInit !== null) {
+        await pendingInit;
+    }
+    await options.lifecycle.waitForActiveOperationsToDrain();
+    let deferredError = options.getPendingInitError();
+    try {
+        await options.getBackendController()?.close();
+    }
+    catch (error) {
+        const closeError = toErrorInstance(error, 'Datastore close failed with a non-Error value.');
+        if (deferredError === null) {
+            deferredError = closeError;
+        }
+        else {
+            deferredError = createCloseAggregateError(deferredError, closeError);
+        }
+    }
+    options.setBackendController(null);
+    options.setPendingInitError(null);
+    options.lifecycle.markClosed();
+    options.clearInMemoryState();
+    if (deferredError !== null) {
+        throw deferredError;
+    }
+};

package/dist/storage/datastore/datastoreKeyDefinition.d.ts

@@ -0,0 +1,7 @@
+import type { DatastoreConfig, DatastoreKeyDefinition } from '../../types.js';
+export declare const DEFAULT_STRING_KEY_DEFINITION: DatastoreKeyDefinition<string, string>;
+export declare const resolveKeyDefinition: (config: DatastoreConfig) => DatastoreKeyDefinition<unknown, unknown>;
+export declare const readRawInsertKey: (rawRecord: Record<string, unknown>) => {
+    rawKey: unknown;
+    keyFieldName: string;
+};

package/dist/storage/datastore/datastoreKeyDefinition.js

@@ -0,0 +1,60 @@
+import { ConfigurationError, ValidationError, } from '../../errors/index.js';
+const ensureNonEmptyStringKey = (value, fieldName) => {
+    if (typeof value !== 'string') {
+        throw new ValidationError(`${fieldName} must be a string.`);
+    }
+    if (value.length === 0) {
+        throw new ValidationError(`${fieldName} must be a non-empty string.`);
+    }
+    return value;
+};
+export const DEFAULT_STRING_KEY_DEFINITION = {
+    normalize: (value, fieldName) => {
+        return ensureNonEmptyStringKey(value, fieldName);
+    },
+    compare: (left, right) => {
+        if (left < right) {
+            return -1;
+        }
+        if (left > right) {
+            return 1;
+        }
+        return 0;
+    },
+    serialize: (key) => {
+        return ensureNonEmptyStringKey(key, 'key');
+    },
+    deserialize: (serialized) => {
+        return ensureNonEmptyStringKey(serialized, 'serialized key');
+    },
+};
+const validateKeyDefinition = (definition) => {
+    if (typeof definition.normalize !== 'function') {
+        throw new ConfigurationError('config.key.normalize must be a function.');
+    }
+    if (typeof definition.compare !== 'function') {
+        throw new ConfigurationError('config.key.compare must be a function.');
+    }
+    if (typeof definition.serialize !== 'function') {
+        throw new ConfigurationError('config.key.serialize must be a function.');
+    }
+    if (typeof definition.deserialize !== 'function') {
+        throw new ConfigurationError('config.key.deserialize must be a function.');
+    }
+};
+export const resolveKeyDefinition = (config) => {
+    if (config.key === undefined) {
+        return DEFAULT_STRING_KEY_DEFINITION;
+    }
+    validateKeyDefinition(config.key);
+    return config.key;
+};
+export const readRawInsertKey = (rawRecord) => {
+    if (Object.prototype.hasOwnProperty.call(rawRecord, 'key')) {
+        return {
+            rawKey: rawRecord.key,
+            keyFieldName: 'key',
+        };
+    }
+    throw new ValidationError('Record must include "key".');
+};

package/dist/storage/datastore/datastoreLifecycle.d.ts

@@ -0,0 +1,18 @@
+export declare class DatastoreLifecycle {
+    private closed;
+    private closing;
+    private closeInFlight;
+    private activeOperationCount;
+    private activeOperationsDrained;
+    private resolveActiveOperationsDrained;
+    constructor();
+    isClosed(): boolean;
+    markClosing(): void;
+    markClosed(): void;
+    getCloseInFlight(): Promise<void> | null;
+    setCloseInFlight(closeInFlight: Promise<void> | null): void;
+    ensureOpen(): void;
+    beginOperation(): void;
+    endOperation(): void;
+    waitForActiveOperationsToDrain(): Promise<void>;
+}