@frostpillar/frostpillar-btree 0.2.0

package/dist/concurrency/ConcurrentInMemoryBTree.d.ts

@@ -0,0 +1,56 @@
+import { type BTreeEntry, type BTreeStats, type EntryId, type RangeBounds } from '../InMemoryBTree.js';
+import type { ConcurrentInMemoryBTreeConfig } from './types.js';
+export declare class ConcurrentInMemoryBTree<TKey, TValue> {
+    private readonly store;
+    private readonly maxRetries;
+    private readonly maxSyncMutationsPerBatch;
+    private readonly duplicateKeys;
+    private readonly configFingerprint;
+    private readonly readMode;
+    private readonly tree;
+    private currentVersion;
+    private operationQueue;
+    private initSeen;
+    constructor(config: ConcurrentInMemoryBTreeConfig<TKey, TValue>);
+    sync(): Promise<void>;
+    private syncUnlocked;
+    private applyMutationLocal;
+    private runExclusive;
+    private readOp;
+    /**
+     * Appends a mutation to the shared store using optimistic concurrency and,
+     * on success, applies the same mutation locally in this method.
+     *
+     * The `evaluate` callback is called against the current (synced) local tree to
+     * decide whether and what mutation to append. If the store append fails due to a
+     * concurrent write, the tree is re-synced and `evaluate` is invoked again.
+     *
+     * The callback MUST be a pure function: it must not produce side effects and must
+     * return the same logical result for equivalent tree states, because it may be
+     * called multiple times across retries.
+     *
+     */
+    private appendMutationAndApplyUnlocked;
+    put(key: TKey, value: TValue): Promise<EntryId>;
+    remove(key: TKey): Promise<BTreeEntry<TKey, TValue> | null>;
+    removeById(entryId: EntryId): Promise<BTreeEntry<TKey, TValue> | null>;
+    updateById(entryId: EntryId, value: TValue): Promise<BTreeEntry<TKey, TValue> | null>;
+    popFirst(): Promise<BTreeEntry<TKey, TValue> | null>;
+    get(key: TKey): Promise<TValue | null>;
+    hasKey(key: TKey): Promise<boolean>;
+    findFirst(key: TKey): Promise<BTreeEntry<TKey, TValue> | null>;
+    findLast(key: TKey): Promise<BTreeEntry<TKey, TValue> | null>;
+    range(startKey: TKey, endKey: TKey, options?: RangeBounds): Promise<BTreeEntry<TKey, TValue>[]>;
+    snapshot(): Promise<BTreeEntry<TKey, TValue>[]>;
+    size(): Promise<number>;
+    assertInvariants(): Promise<void>;
+    getStats(): Promise<BTreeStats>;
+    peekFirst(): Promise<BTreeEntry<TKey, TValue> | null>;
+    peekLast(): Promise<BTreeEntry<TKey, TValue> | null>;
+    popLast(): Promise<BTreeEntry<TKey, TValue> | null>;
+    peekById(entryId: EntryId): Promise<BTreeEntry<TKey, TValue> | null>;
+    count(startKey: TKey, endKey: TKey, options?: RangeBounds): Promise<number>;
+    nextHigherKey(key: TKey): Promise<TKey | null>;
+    nextLowerKey(key: TKey): Promise<TKey | null>;
+    getPairOrNextLower(key: TKey): Promise<BTreeEntry<TKey, TValue> | null>;
+}

package/dist/concurrency/helpers.d.ts

@@ -0,0 +1,27 @@
+import type { BTreeMutation, ConcurrentInMemoryBTreeConfig, ReadMode } from './types.js';
+import type { BTreeEntry, EntryId } from '../InMemoryBTree.js';
+export declare const computeConfigFingerprint: <TKey>(config: ConcurrentInMemoryBTreeConfig<TKey, unknown>) => string;
+export type MutationResult<TKey, TValue, TMutation extends BTreeMutation<TKey, TValue>> = TMutation extends {
+    type: 'init';
+} ? null : TMutation extends {
+    type: 'put';
+} ? EntryId : TMutation extends {
+    type: 'remove';
+} ? BTreeEntry<TKey, TValue> | null : TMutation extends {
+    type: 'removeById';
+} ? BTreeEntry<TKey, TValue> | null : TMutation extends {
+    type: 'updateById';
+} ? BTreeEntry<TKey, TValue> | null : TMutation extends {
+    type: 'popFirst';
+} ? BTreeEntry<TKey, TValue> | null : TMutation extends {
+    type: 'popLast';
+} ? BTreeEntry<TKey, TValue> | null : never;
+export type AnyMutationResult<TKey, TValue> = EntryId | BTreeEntry<TKey, TValue> | null;
+export declare const assertNeverMutation: (mutation: never) => never;
+export declare const normalizeMaxRetries: (value: number | undefined) => number;
+export declare const normalizeMaxSyncMutationsPerBatch: (value: number | undefined) => number;
+export declare const normalizeReadMode: (value: ReadMode | undefined) => ReadMode;
+export declare function assertAppendVersionContract(expectedVersion: bigint, appendResult: unknown): asserts appendResult is {
+    applied: boolean;
+    version: bigint;
+};

package/dist/concurrency/index.d.ts

@@ -0,0 +1,2 @@
+export { ConcurrentInMemoryBTree } from './ConcurrentInMemoryBTree.js';
+export type { BTreeMutation, ConcurrentInMemoryBTreeConfig, ReadMode, SharedTreeLog, SharedTreeStore, } from './types.js';

package/dist/concurrency/types.d.ts

@@ -0,0 +1,41 @@
+import type { EntryId, InMemoryBTreeConfig } from '../InMemoryBTree.js';
+export type BTreeMutation<TKey, TValue> = {
+    type: 'init';
+    configFingerprint: string;
+} | {
+    type: 'put';
+    key: TKey;
+    value: TValue;
+} | {
+    type: 'remove';
+    key: TKey;
+} | {
+    type: 'removeById';
+    entryId: EntryId;
+} | {
+    type: 'updateById';
+    entryId: EntryId;
+    value: TValue;
+} | {
+    type: 'popFirst';
+} | {
+    type: 'popLast';
+};
+export interface SharedTreeLog<TKey, TValue> {
+    version: bigint;
+    mutations: BTreeMutation<TKey, TValue>[];
+}
+export interface SharedTreeStore<TKey, TValue> {
+    getLogEntriesSince(version: bigint): Promise<SharedTreeLog<TKey, TValue>>;
+    append(expectedVersion: bigint, mutations: BTreeMutation<TKey, TValue>[]): Promise<{
+        applied: boolean;
+        version: bigint;
+    }>;
+}
+export type ReadMode = 'strong' | 'local';
+export interface ConcurrentInMemoryBTreeConfig<TKey, TValue> extends InMemoryBTreeConfig<TKey> {
+    store: SharedTreeStore<TKey, TValue>;
+    maxRetries?: number;
+    maxSyncMutationsPerBatch?: number;
+    readMode?: ReadMode;
+}