@frostpillar/frostpillar-btree 0.2.0

package/dist/InMemoryBTree.d.ts

@@ -0,0 +1,45 @@
+import { type BTreeJSON } from './btree/serialization.js';
+import { type BTreeEntry, type BTreeStats, type DuplicateKeyPolicy, type EntryId, type InMemoryBTreeConfig, type KeyComparator, type RangeBounds } from './btree/types.js';
+export type { BTreeJSON };
+export type { BTreeEntry, BTreeStats, DuplicateKeyPolicy, EntryId, InMemoryBTreeConfig, RangeBounds };
+export declare class InMemoryBTree<TKey, TValue> {
+    private readonly state;
+    constructor(config: InMemoryBTreeConfig<TKey>);
+    put(key: TKey, value: TValue): EntryId;
+    putMany(entries: readonly {
+        key: TKey;
+        value: TValue;
+    }[]): EntryId[];
+    remove(key: TKey): BTreeEntry<TKey, TValue> | null;
+    removeById(entryId: EntryId): BTreeEntry<TKey, TValue> | null;
+    peekById(entryId: EntryId): BTreeEntry<TKey, TValue> | null;
+    updateById(entryId: EntryId, value: TValue): BTreeEntry<TKey, TValue> | null;
+    popFirst(): BTreeEntry<TKey, TValue> | null;
+    peekFirst(): BTreeEntry<TKey, TValue> | null;
+    peekLast(): BTreeEntry<TKey, TValue> | null;
+    popLast(): BTreeEntry<TKey, TValue> | null;
+    clear(): void;
+    get(key: TKey): TValue | null;
+    hasKey(key: TKey): boolean;
+    findFirst(key: TKey): BTreeEntry<TKey, TValue> | null;
+    findLast(key: TKey): BTreeEntry<TKey, TValue> | null;
+    nextHigherKey(key: TKey): TKey | null;
+    nextLowerKey(key: TKey): TKey | null;
+    getPairOrNextLower(key: TKey): BTreeEntry<TKey, TValue> | null;
+    count(startKey: TKey, endKey: TKey, options?: RangeBounds): number;
+    deleteRange(startKey: TKey, endKey: TKey, options?: RangeBounds): number;
+    range(startKey: TKey, endKey: TKey, options?: RangeBounds): BTreeEntry<TKey, TValue>[];
+    entries(): IterableIterator<BTreeEntry<TKey, TValue>>;
+    entriesReversed(): IterableIterator<BTreeEntry<TKey, TValue>>;
+    keys(): IterableIterator<TKey>;
+    values(): IterableIterator<TValue>;
+    [Symbol.iterator](): IterableIterator<BTreeEntry<TKey, TValue>>;
+    forEach(callback: (entry: BTreeEntry<TKey, TValue>) => void, thisArg?: unknown): void;
+    snapshot(): BTreeEntry<TKey, TValue>[];
+    clone(): InMemoryBTree<TKey, TValue>;
+    toJSON(): BTreeJSON<TKey, TValue>;
+    static fromJSON<TKey, TValue>(json: BTreeJSON<TKey, TValue>, compareKeys: KeyComparator<TKey>): InMemoryBTree<TKey, TValue>;
+    size(): number;
+    assertInvariants(): void;
+    getStats(): BTreeStats;
+}

package/dist/btree/autoScale.d.ts

@@ -0,0 +1,9 @@
+import { type BTreeState, type InMemoryBTreeConfig } from './types.js';
+export declare const computeAutoScaleTier: (entryCount: number) => {
+    readonly maxLeaf: number;
+    readonly maxBranch: number;
+};
+export declare const computeNextAutoScaleThreshold: (entryCount: number) => number;
+export declare const createInitialState: <TKey, TValue>(config: InMemoryBTreeConfig<TKey>) => BTreeState<TKey, TValue>;
+export declare const maybeAutoScale: <TKey, TValue>(state: BTreeState<TKey, TValue>) => void;
+export declare const applyAutoScaleCapacitySnapshot: <TKey, TValue>(state: BTreeState<TKey, TValue>, maxLeafEntries: number, maxBranchChildren: number) => void;

package/dist/btree/bulkLoad.d.ts

@@ -0,0 +1,5 @@
+import { type BTreeState, type EntryId } from './types.js';
+export declare const bulkLoadEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, entries: readonly {
+    key: TKey;
+    value: TValue;
+}[]) => EntryId[];

package/dist/btree/deleteRange.d.ts

@@ -0,0 +1,3 @@
+import type { RangeBounds } from './types.js';
+import { type BTreeState } from './types.js';
+export declare const deleteRangeEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, startKey: TKey, endKey: TKey, options?: RangeBounds) => number;

package/dist/btree/integrity-helpers.d.ts

@@ -0,0 +1,6 @@
+import { type BTreeNode, type BTreeState, type KeyComparator, type NodeKey } from './types.js';
+export declare const nodeMinKey: <TKey, TValue>(node: BTreeNode<TKey, TValue>) => NodeKey<TKey> | null;
+export declare const compareNodeKeys: <TKey>(comparator: KeyComparator<TKey>, leftKey: TKey, leftSeq: number, rightKey: TKey, rightSeq: number) => number;
+export declare const assertReflexivityAsInvariant: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => void;
+export declare const assertTransitivityAsInvariant: <TKey, TValue>(state: BTreeState<TKey, TValue>, first: TKey, second: TKey, third: TKey) => void;
+export declare const validateLeafLinks: <TKey, TValue>(state: BTreeState<TKey, TValue>, expectedLeafCount: number) => void;

package/dist/btree/integrity.d.ts

@@ -0,0 +1,2 @@
+import { type BTreeState } from './types.js';
+export declare const assertInvariants: <TKey, TValue>(state: BTreeState<TKey, TValue>) => void;

package/dist/btree/mutations.d.ts

@@ -0,0 +1,12 @@
+import { type BTreeEntry, type BTreeState, type EntryId } from './types.js';
+export declare const putEntry: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey, value: TValue) => EntryId;
+export declare const popFirstEntry: <TKey, TValue>(state: BTreeState<TKey, TValue>) => BTreeEntry<TKey, TValue> | null;
+export declare const popLastEntry: <TKey, TValue>(state: BTreeState<TKey, TValue>) => BTreeEntry<TKey, TValue> | null;
+export declare const removeFirstMatchingEntry: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => BTreeEntry<TKey, TValue> | null;
+export declare const removeEntryById: <TKey, TValue>(state: BTreeState<TKey, TValue>, entryId: EntryId) => BTreeEntry<TKey, TValue> | null;
+export declare const peekEntryById: <TKey, TValue>(state: BTreeState<TKey, TValue>, entryId: EntryId) => BTreeEntry<TKey, TValue> | null;
+export declare const updateEntryById: <TKey, TValue>(state: BTreeState<TKey, TValue>, entryId: EntryId, newValue: TValue) => BTreeEntry<TKey, TValue> | null;
+export declare const putManyEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, entries: readonly {
+    key: TKey;
+    value: TValue;
+}[]) => EntryId[];

package/dist/btree/navigation.d.ts

@@ -0,0 +1,23 @@
+import { type BTreeState, type LeafNode } from './types.js';
+export declare const findLeafForKey: <TKey, TValue>(state: BTreeState<TKey, TValue>, userKey: TKey, sequence: number) => LeafNode<TKey, TValue>;
+export declare const lowerBoundInLeaf: <TKey, TValue>(state: BTreeState<TKey, TValue>, leaf: LeafNode<TKey, TValue>, userKey: TKey, sequence: number) => number;
+export declare const upperBoundInLeaf: <TKey, TValue>(state: BTreeState<TKey, TValue>, leaf: LeafNode<TKey, TValue>, userKey: TKey, sequence: number) => number;
+export declare const findLeafFromHint: <TKey, TValue>(state: BTreeState<TKey, TValue>, hint: LeafNode<TKey, TValue>, userKey: TKey, sequence: number) => LeafNode<TKey, TValue>;
+/** Returns shared cursor — caller must consume result before the next navigation call. */
+export declare const findFirstMatchingUserKey: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => {
+    leaf: LeafNode<TKey, TValue>;
+    index: number;
+} | null;
+/** Returns shared cursor — caller must consume result before the next navigation call. */
+export declare const findLastMatchingUserKey: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => {
+    leaf: LeafNode<TKey, TValue>;
+    index: number;
+} | null;
+export declare const hasKeyEntry: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => boolean;
+export declare const findNextHigherKey: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => TKey | null;
+export declare const findNextLowerKey: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => TKey | null;
+/** Returns shared cursor — caller must consume result before the next navigation call. */
+export declare const findPairOrNextLower: <TKey, TValue>(state: BTreeState<TKey, TValue>, key: TKey) => {
+    leaf: LeafNode<TKey, TValue>;
+    index: number;
+} | null;

package/dist/btree/rangeQuery.d.ts

@@ -0,0 +1,3 @@
+import { type BTreeEntry, type BTreeState, type RangeBounds } from './types.js';
+export declare const countRangeEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, startKey: TKey, endKey: TKey, options?: RangeBounds) => number;
+export declare const rangeQueryEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, startKey: TKey, endKey: TKey, options?: RangeBounds) => BTreeEntry<TKey, TValue>[];

package/dist/btree/rebalance.d.ts

@@ -0,0 +1,4 @@
+import { type BTreeNode, type BTreeState, type LeafNode } from './types.js';
+declare const updateMinKeyInAncestors: <TKey, TValue>(node: BTreeNode<TKey, TValue>) => void;
+export { updateMinKeyInAncestors };
+export declare const rebalanceAfterLeafRemoval: <TKey, TValue>(state: BTreeState<TKey, TValue>, leaf: LeafNode<TKey, TValue>) => void;

package/dist/btree/serialization.d.ts

@@ -0,0 +1,20 @@
+import { type BTreeState, type DuplicateKeyPolicy, type InMemoryBTreeConfig, type KeyComparator } from './types.js';
+export interface BTreeJSON<TKey, TValue> {
+    version: number;
+    config: {
+        maxLeafEntries: number;
+        maxBranchChildren: number;
+        duplicateKeys: DuplicateKeyPolicy;
+        enableEntryIdLookup: boolean;
+        autoScale: boolean;
+    };
+    entries: [TKey, TValue][];
+}
+export declare const collectEntryPairs: <TKey, TValue>(state: BTreeState<TKey, TValue>) => {
+    key: TKey;
+    value: TValue;
+}[];
+export declare const buildConfigFromState: <TKey, TValue>(state: BTreeState<TKey, TValue>) => InMemoryBTreeConfig<TKey>;
+export declare const serializeToJSON: <TKey, TValue>(state: BTreeState<TKey, TValue>) => BTreeJSON<TKey, TValue>;
+export declare const validateBTreeJSON: <TKey, TValue>(json: BTreeJSON<TKey, TValue>) => void;
+export declare const buildConfigFromJSON: <TKey>(json: BTreeJSON<TKey, unknown>, compareKeys: KeyComparator<TKey>) => InMemoryBTreeConfig<TKey>;

package/dist/btree/stats.d.ts

@@ -0,0 +1,2 @@
+import { type BTreeState, type BTreeStats } from './types.js';
+export declare const getStats: <TKey, TValue>(state: BTreeState<TKey, TValue>) => BTreeStats;

package/dist/btree/types.d.ts

@@ -0,0 +1,113 @@
+export declare const DEFAULT_MAX_LEAF_ENTRIES = 64;
+export declare const DEFAULT_MAX_BRANCH_CHILDREN = 64;
+export declare const MIN_NODE_CAPACITY = 3;
+export declare const MAX_NODE_CAPACITY = 16384;
+export declare const NODE_LEAF: 0;
+export declare const NODE_BRANCH: 1;
+export type KeyComparator<TKey> = (left: TKey, right: TKey) => number;
+export type DuplicateKeyPolicy = 'allow' | 'reject' | 'replace';
+export interface RangeBounds {
+    lowerBound?: 'inclusive' | 'exclusive';
+    upperBound?: 'inclusive' | 'exclusive';
+}
+export declare const normalizeDuplicateKeyPolicy: (value: DuplicateKeyPolicy | undefined) => DuplicateKeyPolicy;
+export type EntryId = number & {
+    readonly __brand: 'EntryId';
+};
+export interface BTreeEntry<TKey, TValue> {
+    readonly entryId: EntryId;
+    readonly key: TKey;
+    readonly value: TValue;
+}
+export interface NodeKey<TKey> {
+    key: TKey;
+    sequence: number;
+}
+/** Internal mutable entry stored in leaf nodes. */
+export interface LeafEntry<TKey, TValue> {
+    entryId: EntryId;
+    key: TKey;
+    value: TValue;
+}
+export interface LeafNode<TKey, TValue> {
+    kind: typeof NODE_LEAF;
+    entries: LeafEntry<TKey, TValue>[];
+    entryOffset: number;
+    parent: BranchNode<TKey, TValue> | null;
+    indexInParent: number;
+    prev: LeafNode<TKey, TValue> | null;
+    next: LeafNode<TKey, TValue> | null;
+}
+export interface BranchNode<TKey, TValue> {
+    kind: typeof NODE_BRANCH;
+    children: BTreeNode<TKey, TValue>[];
+    keys: NodeKey<TKey>[];
+    childOffset: number;
+    parent: BranchNode<TKey, TValue> | null;
+    indexInParent: number;
+}
+export type BTreeNode<TKey, TValue> = LeafNode<TKey, TValue> | BranchNode<TKey, TValue>;
+export interface BTreeState<TKey, TValue> {
+    compareKeys: KeyComparator<TKey>;
+    maxLeafEntries: number;
+    maxBranchChildren: number;
+    duplicateKeys: DuplicateKeyPolicy;
+    root: BTreeNode<TKey, TValue>;
+    leftmostLeaf: LeafNode<TKey, TValue>;
+    rightmostLeaf: LeafNode<TKey, TValue>;
+    entryCount: number;
+    nextSequence: number;
+    minLeafEntries: number;
+    minBranchChildren: number;
+    entryKeys: Map<EntryId, TKey> | null;
+    autoScale: boolean;
+    _nextAutoScaleThreshold: number;
+    /** @internal Shared return object for navigation functions — never store a reference across calls. */
+    _cursor: {
+        leaf: LeafNode<TKey, TValue>;
+        index: number;
+    };
+}
+export interface InMemoryBTreeConfig<TKey> {
+    compareKeys: KeyComparator<TKey>;
+    maxLeafEntries?: number;
+    maxBranchChildren?: number;
+    duplicateKeys?: DuplicateKeyPolicy;
+    enableEntryIdLookup?: boolean;
+    autoScale?: boolean;
+}
+export interface BTreeStats {
+    height: number;
+    leafCount: number;
+    branchCount: number;
+    entryCount: number;
+}
+export declare const isLeafNode: <TKey, TValue>(node: BTreeNode<TKey, TValue>) => node is LeafNode<TKey, TValue>;
+export declare const writeMinKeyTo: <TKey, TValue>(node: BTreeNode<TKey, TValue>, target: NodeKey<TKey>) => boolean;
+export declare const normalizeNodeCapacity: (value: number | undefined, field: string, defaultValue: number) => number;
+export declare const createLeafNode: <TKey, TValue>(entries: LeafEntry<TKey, TValue>[], parent: BranchNode<TKey, TValue> | null) => LeafNode<TKey, TValue>;
+export declare const createBranchNode: <TKey, TValue>(children: BTreeNode<TKey, TValue>[], parent: BranchNode<TKey, TValue> | null) => BranchNode<TKey, TValue>;
+/** Number of logical entries in the leaf */
+export declare const leafEntryCount: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => number;
+/** Get logical entry at index i (0-based from the logical start) */
+export declare const leafEntryAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, i: number) => LeafEntry<TKey, TValue>;
+/** Remove and return the first logical entry. O(1) amortized — increments offset and compacts when dead slots reach half. */
+export declare const leafShiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
+/** Remove and return the last logical entry. O(1) — pops from the backing array tail. */
+export declare const leafPopEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
+/** Prepend entry to logical start. Falls back to unshift if no gap, otherwise fills gap. */
+export declare const leafUnshiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, entry: LeafEntry<TKey, TValue>) => void;
+/** Remove logical entry at index. Shifts the smaller side to halve average cost. */
+export declare const leafRemoveAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number) => void;
+/** Insert entry at logical index. Uses entryOffset gap when inserting in the first half. */
+export declare const leafInsertAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number, entry: LeafEntry<TKey, TValue>) => void;
+/** Compact the backing array — remove dead slots before entryOffset. Call before splits/merges. */
+export declare const leafCompact: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => void;
+/** Compact branch arrays — remove dead slots before childOffset, keeping a small gap. */
+export declare const branchCompact: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => void;
+/** Number of logical children in the branch. */
+export declare const branchChildCount: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => number;
+/** Insert a child at a logical index. Shifts the smaller side to halve average cost. */
+export declare const branchInsertAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, logicalIndex: number, child: BTreeNode<TKey, TValue>, key: NodeKey<TKey>) => void;
+/** Remove a child at a physical index. Shifts the smaller side. */
+export declare const branchRemoveAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, physIndex: number) => void;