@frostpillar/frostpillar-storage-engine 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Datastore } from './storage/datastore/Datastore.js';
+export type { AutoCommitConfig, AutoCommitFrequencyInput, CapacityConfig, CapacityPolicy, DatastoreConfig, DuplicateKeyPolicy, DatastoreDriver, DatastoreDriverController, DatastoreDriverInitContext, DatastoreDriverInitResult, DatastoreDriverSnapshot, DatastoreErrorEvent, DatastoreErrorListener, DatastoreKeyDefinition, EntryId, FileBackendConfig, FileTargetByDirectoryConfig, FileTargetByPathConfig, FileTargetConfig, InputRecord, IndexedDBConfig, KeyedRecord, LocalStorageConfig, OpfsConfig, PersistedRecord, RecordPayload, SyncStorageConfig, } from './types.js';
+export { BinaryFormatError, ClosedDatastoreError, ConfigurationError, DatabaseLockedError, FrostpillarError, IndexCorruptionError, InvalidQueryRangeError, PageCorruptionError, QuotaExceededError, StorageEngineError, UnsupportedBackendError, ValidationError, } from './errors/index.js';
+export { localStorageDriver } from './drivers/localStorage.js';
+export { indexedDBDriver } from './drivers/indexedDB.js';
+export { opfsDriver } from './drivers/opfs.js';
+export { syncStorageDriver } from './drivers/syncStorage.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Datastore } from './storage/datastore/Datastore.js';
+export { BinaryFormatError, ClosedDatastoreError, ConfigurationError, DatabaseLockedError, FrostpillarError, IndexCorruptionError, InvalidQueryRangeError, PageCorruptionError, QuotaExceededError, StorageEngineError, UnsupportedBackendError, ValidationError, } from './errors/index.js';
+export { localStorageDriver } from './drivers/localStorage.js';
+export { indexedDBDriver } from './drivers/indexedDB.js';
+export { opfsDriver } from './drivers/opfs.js';
+export { syncStorageDriver } from './drivers/syncStorage.js';

package/dist/storage/backend/asyncDurableAutoCommitController.d.ts

@@ -0,0 +1,26 @@
+import type { FileAutoCommitState } from './types.js';
+export declare abstract class AsyncDurableAutoCommitController {
+    private readonly autoCommit;
+    private readonly onAutoCommitError;
+    private pendingAutoCommitBytes;
+    private dirtyFromClear;
+    private autoCommitTimer;
+    private commitInFlight;
+    private pendingForegroundCommitRequest;
+    private pendingBackgroundCommitRequest;
+    private closed;
+    protected constructor(autoCommit: FileAutoCommitState, onAutoCommitError: (error: unknown) => void);
+    handleRecordAppended(encodedBytes: number): Promise<void>;
+    handleCleared(): Promise<void>;
+    commitNow(): Promise<void>;
+    close(): Promise<void>;
+    protected getPendingAutoCommitBytes(): number;
+    protected abstract executeSingleCommit(): Promise<void>;
+    protected onCloseAfterDrain(): Promise<void>;
+    private waitForCommitSettlement;
+    private queueCommitRequest;
+    private runCommitLoop;
+    private startAutoCommitSchedule;
+    private stopAutoCommitSchedule;
+    private handleAutoCommitTick;
+}

package/dist/storage/backend/asyncDurableAutoCommitController.js

@@ -0,0 +1,188 @@
+import { toErrorInstance } from '../../errors/index.js';
+export class AsyncDurableAutoCommitController {
+    autoCommit;
+    onAutoCommitError;
+    pendingAutoCommitBytes;
+    dirtyFromClear;
+    autoCommitTimer;
+    commitInFlight;
+    pendingForegroundCommitRequest;
+    pendingBackgroundCommitRequest;
+    closed;
+    constructor(autoCommit, onAutoCommitError) {
+        this.autoCommit = autoCommit;
+        this.onAutoCommitError = onAutoCommitError;
+        this.pendingAutoCommitBytes = 0;
+        this.dirtyFromClear = false;
+        this.autoCommitTimer = null;
+        this.commitInFlight = null;
+        this.pendingForegroundCommitRequest = false;
+        this.pendingBackgroundCommitRequest = false;
+        this.closed = false;
+        this.startAutoCommitSchedule();
+    }
+    handleRecordAppended(encodedBytes) {
+        if (this.autoCommit.frequency === 'immediate') {
+            return this.commitNow();
+        }
+        this.pendingAutoCommitBytes += encodedBytes;
+        if (this.autoCommit.maxPendingBytes !== null &&
+            this.pendingAutoCommitBytes >= this.autoCommit.maxPendingBytes) {
+            return this.queueCommitRequest('foreground');
+        }
+        return Promise.resolve();
+    }
+    handleCleared() {
+        this.dirtyFromClear = true;
+        if (this.autoCommit.frequency === 'immediate') {
+            return this.commitNow();
+        }
+        return this.queueCommitRequest('background');
+    }
+    commitNow() {
+        return this.queueCommitRequest('foreground');
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.stopAutoCommitSchedule();
+        await this.waitForCommitSettlement();
+        let flushError = null;
+        if (this.pendingAutoCommitBytes > 0 || this.dirtyFromClear) {
+            try {
+                await this.executeSingleCommit();
+                this.pendingAutoCommitBytes = 0;
+                this.dirtyFromClear = false;
+            }
+            catch (error) {
+                flushError = toErrorInstance(error, 'Final close-time flush commit failed with a non-Error value.');
+            }
+        }
+        let drainError = null;
+        try {
+            await this.onCloseAfterDrain();
+        }
+        catch (error) {
+            drainError = toErrorInstance(error, 'onCloseAfterDrain failed with a non-Error value.');
+        }
+        if (flushError !== null && drainError !== null) {
+            throw createCloseAggregateError(flushError, drainError);
+        }
+        if (flushError !== null) {
+            throw flushError;
+        }
+        if (drainError !== null) {
+            throw drainError;
+        }
+    }
+    getPendingAutoCommitBytes() {
+        return this.pendingAutoCommitBytes;
+    }
+    onCloseAfterDrain() {
+        return Promise.resolve();
+    }
+    waitForCommitSettlement() {
+        if (this.commitInFlight === null) {
+            return Promise.resolve();
+        }
+        return this.commitInFlight
+            .then(() => undefined)
+            .catch(() => undefined);
+    }
+    queueCommitRequest(requestType) {
+        if (requestType === 'foreground') {
+            this.pendingForegroundCommitRequest = true;
+        }
+        else {
+            this.pendingBackgroundCommitRequest = true;
+        }
+        if (this.commitInFlight === null) {
+            this.commitInFlight = this.runCommitLoop().finally(() => {
+                this.commitInFlight = null;
+            });
+        }
+        if (requestType === 'background') {
+            return Promise.resolve();
+        }
+        return this.commitInFlight;
+    }
+    async runCommitLoop() {
+        let shouldContinue = true;
+        while (shouldContinue) {
+            const runForeground = this.pendingForegroundCommitRequest;
+            const runBackground = this.pendingBackgroundCommitRequest;
+            const runClear = this.dirtyFromClear;
+            this.pendingForegroundCommitRequest = false;
+            this.pendingBackgroundCommitRequest = false;
+            this.dirtyFromClear = false;
+            const shouldRunCommit = runForeground || (runBackground && (this.pendingAutoCommitBytes > 0 || runClear));
+            if (!shouldRunCommit) {
+                shouldContinue = false;
+                continue;
+            }
+            try {
+                const committedPendingBytes = this.pendingAutoCommitBytes;
+                await this.executeSingleCommit();
+                this.pendingAutoCommitBytes = Math.max(0, this.pendingAutoCommitBytes - committedPendingBytes);
+            }
+            catch (error) {
+                if (runClear) {
+                    this.dirtyFromClear = true;
+                }
+                if (runForeground) {
+                    throw toErrorInstance(error, 'Foreground auto-commit failed with a non-Error value.');
+                }
+                this.onAutoCommitError(error);
+            }
+            if (!this.pendingForegroundCommitRequest && !this.pendingBackgroundCommitRequest) {
+                shouldContinue = false;
+            }
+        }
+    }
+    startAutoCommitSchedule() {
+        if (this.autoCommit.frequency !== 'scheduled' ||
+            this.autoCommit.intervalMs === null) {
+            return;
+        }
+        this.autoCommitTimer = setInterval(() => {
+            this.handleAutoCommitTick();
+        }, this.autoCommit.intervalMs);
+        if (typeof this.autoCommitTimer === 'object' && this.autoCommitTimer !== null && 'unref' in this.autoCommitTimer) {
+            this.autoCommitTimer.unref();
+        }
+    }
+    stopAutoCommitSchedule() {
+        if (this.autoCommitTimer === null) {
+            return;
+        }
+        clearInterval(this.autoCommitTimer);
+        this.autoCommitTimer = null;
+    }
+    handleAutoCommitTick() {
+        if (this.closed) {
+            return;
+        }
+        if (this.pendingAutoCommitBytes <= 0 && !this.dirtyFromClear) {
+            return;
+        }
+        void this.queueCommitRequest('background');
+    }
+}
+const readAggregateErrorConstructor = () => {
+    const candidate = globalThis.AggregateError;
+    if (typeof candidate !== 'function') {
+        return null;
+    }
+    return candidate;
+};
+const createCloseAggregateError = (flushError, drainError) => {
+    const aggregateErrorConstructor = readAggregateErrorConstructor();
+    if (aggregateErrorConstructor !== null) {
+        return new aggregateErrorConstructor([flushError, drainError], 'Close failed: both final flush and drain produced errors.');
+    }
+    const fallbackError = new Error('Close failed: both final flush and drain produced errors.');
+    fallbackError.errors = [flushError, drainError];
+    return fallbackError;
+};

package/dist/storage/backend/asyncMutex.d.ts

@@ -0,0 +1,7 @@
+export declare class AsyncMutex {
+    private queue;
+    private head;
+    private locked;
+    acquire(): Promise<() => void>;
+    private createRelease;
+}

package/dist/storage/backend/asyncMutex.js

@@ -0,0 +1,38 @@
+export class AsyncMutex {
+    queue = [];
+    head = 0;
+    locked = false;
+    acquire() {
+        if (!this.locked) {
+            this.locked = true;
+            return Promise.resolve(this.createRelease());
+        }
+        return new Promise((resolve) => {
+            this.queue.push(() => resolve(this.createRelease()));
+        });
+    }
+    createRelease() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (this.head < this.queue.length) {
+                const next = this.queue[this.head];
+                this.queue[this.head] = undefined; // allow GC
+                this.head += 1;
+                // Compact when more than half the array is dead entries and above threshold
+                if (this.head > 1024 && this.head > (this.queue.length >>> 1)) {
+                    this.queue = this.queue.slice(this.head);
+                    this.head = 0;
+                }
+                next();
+            }
+            else {
+                this.queue.length = 0;
+                this.head = 0;
+                this.locked = false;
+            }
+        };
+    }
+}

package/dist/storage/backend/autoCommit.d.ts

@@ -0,0 +1,2 @@
+import type { DatastoreErrorListener } from '../../types.js';
+export declare const emitAutoCommitErrorToListeners: (listeners: Set<DatastoreErrorListener>, error: unknown) => void;

package/dist/storage/backend/autoCommit.js

@@ -0,0 +1,22 @@
+import { StorageEngineError } from '../../errors/index.js';
+export const emitAutoCommitErrorToListeners = (listeners, error) => {
+    const storageError = error instanceof StorageEngineError
+        ? error
+        : new StorageEngineError(error instanceof Error
+            ? error.message
+            : 'Unknown auto-commit storage failure.', { cause: error });
+    const event = {
+        source: 'autoCommit',
+        error: storageError,
+        occurredAt: Date.now(),
+    };
+    for (const listener of listeners) {
+        try {
+            const delivered = listener(event);
+            void Promise.resolve(delivered).catch(() => undefined);
+        }
+        catch {
+            // listener isolation by contract
+        }
+    }
+};

package/dist/storage/backend/capacity.d.ts

@@ -0,0 +1,2 @@
+import type { CapacityState } from './types.js';
+export declare const enforceCapacityPolicy: (capacityState: CapacityState | null, currentSizeBytes: number, encodedBytes: number, getRecordCount: () => number, evictOldestRecord: () => number) => number;

package/dist/storage/backend/capacity.js

@@ -0,0 +1,27 @@
+import { IndexCorruptionError, QuotaExceededError } from '../../errors/index.js';
+export const enforceCapacityPolicy = (capacityState, currentSizeBytes, encodedBytes, getRecordCount, evictOldestRecord) => {
+    if (capacityState === null) {
+        return currentSizeBytes;
+    }
+    if (encodedBytes > capacityState.maxSizeBytes) {
+        throw new QuotaExceededError('Record exceeds configured capacity.maxSize boundary.');
+    }
+    if (capacityState.policy === 'strict') {
+        if (currentSizeBytes + encodedBytes > capacityState.maxSizeBytes) {
+            throw new QuotaExceededError('Insert exceeds configured capacity.maxSize under strict policy.');
+        }
+        return currentSizeBytes;
+    }
+    let nextSizeBytes = currentSizeBytes;
+    while (nextSizeBytes + encodedBytes > capacityState.maxSizeBytes) {
+        if (getRecordCount() === 0) {
+            throw new QuotaExceededError('Record cannot fit in turnover policy with empty datastore.');
+        }
+        const evictedBytes = evictOldestRecord();
+        if (!Number.isSafeInteger(evictedBytes) || evictedBytes <= 0) {
+            throw new IndexCorruptionError('Turnover eviction reported non-progressing reclaimed bytes.');
+        }
+        nextSizeBytes -= evictedBytes;
+    }
+    return Math.max(0, nextSizeBytes);
+};

package/dist/storage/backend/capacityResolver.d.ts

@@ -0,0 +1,3 @@
+import type { DatastoreConfig } from '../../types.js';
+import type { CapacityState } from './types.js';
+export declare const resolveCapacityState: (config: DatastoreConfig) => CapacityState | null;

package/dist/storage/backend/capacityResolver.js

@@ -0,0 +1,25 @@
+import { ConfigurationError } from '../../errors/index.js';
+import { parseCapacityConfig } from '../config/config.shared.js';
+const resolveCapacityConfigWithBackendLimit = (config) => {
+    if (config.capacity === undefined) {
+        return undefined;
+    }
+    if (config.capacity.maxSize !== 'backendLimit') {
+        return config.capacity;
+    }
+    if (config.driver === undefined) {
+        throw new ConfigurationError('capacity.maxSize "backendLimit" requires a durable driver.');
+    }
+    if (config.driver.resolveBackendLimitBytes === undefined) {
+        throw new ConfigurationError('capacity.maxSize "backendLimit" is not supported by the selected driver.');
+    }
+    const resolvedMaxSize = config.driver.resolveBackendLimitBytes();
+    return {
+        ...config.capacity,
+        maxSize: resolvedMaxSize,
+    };
+};
+export const resolveCapacityState = (config) => {
+    const resolvedCapacityConfig = resolveCapacityConfigWithBackendLimit(config);
+    return parseCapacityConfig(resolvedCapacityConfig);
+};

package/dist/storage/backend/encoding.d.ts

@@ -0,0 +1,17 @@
+import type { RecordPayload } from '../../types.js';
+export declare const computeUtf8ByteLength: (value: string) => number;
+/**
+ * Compute the UTF-8 byte length of a string as it would appear in JSON output
+ * (i.e., with JSON escaping applied), INCLUDING the surrounding quotes.
+ */
+export declare const estimateJsonStringBytes: (value: string) => number;
+/**
+ * Estimate the UTF-8 byte length of `JSON.stringify(value)` by walking the
+ * object tree structurally. Does NOT call JSON.stringify.
+ *
+ * Supports: null, boolean, number, string, plain objects.
+ * Arrays are NOT supported (payloads don't contain arrays).
+ */
+export declare const estimateObjectSizeBytes: (value: unknown) => number;
+export declare const estimateRecordSizeBytes: (key: unknown, payload: RecordPayload) => number;
+export declare const estimateKeySizeBytes: (key: unknown) => number;

package/dist/storage/backend/encoding.js

@@ -0,0 +1,148 @@
+// ---------------------------------------------------------------------------
+// P8: Platform-native UTF-8 byte length with JS fallback for browsers
+// ---------------------------------------------------------------------------
+const computeUtf8ByteLengthJs = (value) => {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x7f) {
+            bytes += 1;
+        }
+        else if (code <= 0x7ff) {
+            bytes += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4;
+                i++; // skip low surrogate
+            }
+            else {
+                bytes += 3; // lone high surrogate → U+FFFD replacement (3 bytes)
+            }
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            bytes += 3; // lone low surrogate → U+FFFD replacement (3 bytes)
+        }
+        else {
+            bytes += 3;
+        }
+    }
+    return bytes;
+};
+const hasBuffer = typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function';
+export const computeUtf8ByteLength = hasBuffer
+    ? (value) => Buffer.byteLength(value, 'utf8')
+    : computeUtf8ByteLengthJs;
+// ---------------------------------------------------------------------------
+// P9: Structural size estimation — walk object tree without JSON.stringify
+// ---------------------------------------------------------------------------
+/**
+ * Compute the UTF-8 byte length of a string as it would appear in JSON output
+ * (i.e., with JSON escaping applied), INCLUDING the surrounding quotes.
+ */
+export const estimateJsonStringBytes = (value) => {
+    // 2 bytes for the surrounding quotes
+    let bytes = 2;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        // JSON.stringify escapes: " → \", \\ → \\, \n → \\n, \r → \\r, \t → \\t,
+        // \b → \\b, \f → \\f, and U+0000–U+001F → \\uXXXX (6 chars)
+        if (code === 0x22 || code === 0x5c) {
+            // " or \ → 2 ASCII bytes
+            bytes += 2;
+        }
+        else if (code <= 0x1f) {
+            // Control characters: \b(8), \t(9), \n(10), \f(12), \r(13) → 2 bytes each
+            // Others → \uXXXX → 6 bytes each
+            if (code === 0x08 || code === 0x09 || code === 0x0a || code === 0x0c || code === 0x0d) {
+                bytes += 2;
+            }
+            else {
+                bytes += 6;
+            }
+        }
+        else if (code <= 0x7f) {
+            bytes += 1;
+        }
+        else if (code <= 0x7ff) {
+            bytes += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < value.length ? value.charCodeAt(i + 1) : 0;
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4;
+                i++; // skip low surrogate
+            }
+            else {
+                bytes += 6; // lone high surrogate → JSON.stringify emits \uDXXX (6 ASCII bytes)
+            }
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            bytes += 6; // lone low surrogate → JSON.stringify emits \uDXXX (6 ASCII bytes)
+        }
+        else {
+            bytes += 3;
+        }
+    }
+    return bytes;
+};
+/**
+ * Estimate the UTF-8 byte length of `JSON.stringify(value)` by walking the
+ * object tree structurally. Does NOT call JSON.stringify.
+ *
+ * Supports: null, boolean, number, string, plain objects.
+ * Arrays are NOT supported (payloads don't contain arrays).
+ */
+export const estimateObjectSizeBytes = (value) => {
+    if (value === null) {
+        return 4; // "null"
+    }
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 4 : 5; // "true" / "false"
+        case 'number':
+            // Use String() for correctness with all number representations
+            return String(value).length;
+        case 'string':
+            return estimateJsonStringBytes(value);
+        case 'object': {
+            const obj = value;
+            let size = 2; // { }
+            let visibleCount = 0;
+            for (const k of Object.keys(obj)) {
+                const v = obj[k];
+                // JSON.stringify omits undefined values
+                if (v === undefined) {
+                    continue;
+                }
+                if (visibleCount > 0) {
+                    size += 1; // comma
+                }
+                // key: quoted key string + colon
+                size += estimateJsonStringBytes(k) + 1;
+                // value
+                size += estimateObjectSizeBytes(v);
+                visibleCount++;
+            }
+            return size;
+        }
+        default:
+            return 0;
+    }
+};
+// ---------------------------------------------------------------------------
+// P9: Refactored estimateRecordSizeBytes using structural estimation
+// ---------------------------------------------------------------------------
+// JSON_ROOT_WRAPPER_OVERHEAD = 15 matches: [key,{"payload":...}]
+// Breakdown: [ + key + , + {"payload": + payload_json + } + ] = 1+1+10+1+1+1 = 15 overhead
+const JSON_ROOT_WRAPPER_OVERHEAD = 15;
+export const estimateRecordSizeBytes = (key, payload) => {
+    return estimateObjectSizeBytes(key) + estimateObjectSizeBytes(payload) + JSON_ROOT_WRAPPER_OVERHEAD;
+};
+// ---------------------------------------------------------------------------
+// P10: estimateKeySizeBytes
+// ---------------------------------------------------------------------------
+export const estimateKeySizeBytes = (key) => {
+    return estimateObjectSizeBytes(key);
+};