@frostpillar/frostpillar-btree 0.2.5 → 0.2.7

package/dist/btree/node-ops.d.ts

@@ -0,0 +1,15 @@
+import type { BranchNode, BTreeNode, LeafEntry, LeafNode, NodeKey } from './types.js';
+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>;
+export declare const leafEntryCount: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => number;
+export declare const leafEntryAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, i: number) => LeafEntry<TKey, TValue>;
+export declare const leafShiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
+export declare const leafPopEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => LeafEntry<TKey, TValue> | undefined;
+export declare const leafUnshiftEntry: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, entry: LeafEntry<TKey, TValue>) => void;
+export declare const leafRemoveAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number) => void;
+export declare const leafInsertAt: <TKey, TValue>(leaf: LeafNode<TKey, TValue>, logicalIndex: number, entry: LeafEntry<TKey, TValue>) => void;
+export declare const leafCompact: <TKey, TValue>(leaf: LeafNode<TKey, TValue>) => void;
+export declare const branchCompact: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => void;
+export declare const branchChildCount: <TKey, TValue>(branch: BranchNode<TKey, TValue>) => number;
+export declare const branchInsertAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, logicalIndex: number, child: BTreeNode<TKey, TValue>, key: NodeKey<TKey>) => void;
+export declare const branchRemoveAt: <TKey, TValue>(branch: BranchNode<TKey, TValue>, physIndex: number) => void;

package/dist/btree/rangeQuery.d.ts

@@ -1,3 +1,7 @@
 import { type BTreeEntry, type BTreeState, type RangeBounds } from './types.js';
+export declare function isEmptyRange<TKey>(compare: (a: TKey, b: TKey) => number, startKey: TKey, endKey: TKey, options?: RangeBounds): boolean;
 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>[];
+/** Single-pass range query that produces public entries (via freezeEntry) inline. */
+export declare const rangeQueryPublicEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, startKey: TKey, endKey: TKey, options?: RangeBounds) => BTreeEntry<TKey, TValue>[];
+/** Streaming range iteration — invokes callback for each entry without array allocation. */
+export declare const forEachRangeEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>, startKey: TKey, endKey: TKey, callback: (entry: BTreeEntry<TKey, TValue>) => void, options?: RangeBounds) => void;

package/dist/btree/rebalance-branch.d.ts

@@ -0,0 +1,4 @@
+import { type BTreeNode, type BTreeState, type BranchNode } from './types.js';
+export declare const updateMinKeyInAncestors: <TKey, TValue>(node: BTreeNode<TKey, TValue>) => void;
+export declare const removeChildFromBranch: <TKey, TValue>(branch: BranchNode<TKey, TValue>, childIndex: number) => void;
+export declare const rebalanceAfterBranchRemoval: <TKey, TValue>(state: BTreeState<TKey, TValue>, branch: BranchNode<TKey, TValue>) => void;

package/dist/btree/rebalance.d.ts

@@ -1,4 +1,7 @@
-import { type BTreeNode, type BTreeState, type LeafNode } from './types.js';
-declare const updateMinKeyInAncestors: <TKey, TValue>(node: BTreeNode<TKey, TValue>) => void;
+import { type BTreeState, type LeafNode } from './types.js';
+import { updateMinKeyInAncestors } from './rebalance-branch.js';
 export { updateMinKeyInAncestors };
+/** Applies the lazy divisor to a minimum-occupancy value. */
+export declare const applyLazyThreshold: (min: number) => number;
+export declare const leafRebalanceThreshold: <TKey, TValue>(state: BTreeState<TKey, TValue>) => number;
 export declare const rebalanceAfterLeafRemoval: <TKey, TValue>(state: BTreeState<TKey, TValue>, leaf: LeafNode<TKey, TValue>) => void;

package/dist/btree/serialization.d.ts

@@ -1,4 +1,4 @@
-import { type BTreeState, type DuplicateKeyPolicy, type InMemoryBTreeConfig, type KeyComparator } from './types.js';
+import { type BTreeState, type DeleteRebalancePolicy, type DuplicateKeyPolicy, type InMemoryBTreeConfig, type KeyComparator } from './types.js';
 export interface BTreeJSON<TKey, TValue> {
     version: number;
     config: {
@@ -7,10 +7,12 @@ export interface BTreeJSON<TKey, TValue> {
         duplicateKeys: DuplicateKeyPolicy;
         enableEntryIdLookup: boolean;
         autoScale: boolean;
+        deleteRebalancePolicy?: DeleteRebalancePolicy;
     };
     entries: [TKey, 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 validateBTreeJSONSortOrder: <TKey, TValue>(json: BTreeJSON<TKey, TValue>, compareKeys: KeyComparator<TKey>) => void;
 export declare const buildConfigFromJSON: <TKey>(json: BTreeJSON<TKey, unknown>, compareKeys: KeyComparator<TKey>) => InMemoryBTreeConfig<TKey>;

package/dist/btree/split.d.ts

@@ -0,0 +1,3 @@
+import { type BTreeState, type BranchNode, type LeafNode } from './types.js';
+export declare const splitLeaf: <TKey, TValue>(state: BTreeState<TKey, TValue>, leaf: LeafNode<TKey, TValue>) => void;
+export declare const splitBranch: <TKey, TValue>(state: BTreeState<TKey, TValue>, branch: BranchNode<TKey, TValue>) => void;

package/dist/btree/traversal.d.ts

@@ -0,0 +1,7 @@
+import { type BTreeEntry, type BTreeState } from './types.js';
+/** Collect all entries into a pre-allocated array, frozen for safe external use. */
+export declare const snapshotEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>) => BTreeEntry<TKey, TValue>[];
+/** Collect all internal entries (no freeze) for internal use (clone, serialize). */
+export declare const collectInternalEntries: <TKey, TValue>(state: BTreeState<TKey, TValue>) => BTreeEntry<TKey, TValue>[];
+/** Iterate all entries, invoking callback with frozen entries. */
+export declare const forEachEntry: <TKey, TValue>(state: BTreeState<TKey, TValue>, callback: (entry: BTreeEntry<TKey, TValue>) => void, thisArg?: unknown) => void;

package/dist/btree/types.d.ts

@@ -6,11 +6,19 @@ 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 type DeleteRebalancePolicy = 'standard' | 'lazy';
+/**
+ * Defines the inclusivity of the lower and upper bounds for a key range scan.
+ * Both bounds default to `'inclusive'` when omitted.
+ */
 export interface RangeBounds {
+    /** Lower bound type. Defaults to `'inclusive'` when omitted. */
     lowerBound?: 'inclusive' | 'exclusive';
+    /** Upper bound type. Defaults to `'inclusive'` when omitted. */
     upperBound?: 'inclusive' | 'exclusive';
 }
 export declare const normalizeDuplicateKeyPolicy: (value: DuplicateKeyPolicy | undefined) => DuplicateKeyPolicy;
+export declare const normalizeDeleteRebalancePolicy: (value: DeleteRebalancePolicy | undefined) => DeleteRebalancePolicy;
 export type EntryId = number & {
     readonly __brand: 'EntryId';
 };
@@ -29,6 +37,18 @@ export interface LeafEntry<TKey, TValue> {
     key: TKey;
     value: TValue;
 }
+/**
+ * Freezes and returns an internal entry for safe exposure via the public API.
+ * Idempotent: re-freezing an already-frozen object is a no-op in V8.
+ * All entries are frozen at creation via createEntry, so this is a zero-allocation cast.
+ */
+export declare const freezeEntry: <TKey, TValue>(entry: LeafEntry<TKey, TValue>) => BTreeEntry<TKey, TValue>;
+/**
+ * Creates a frozen LeafEntry with a canonical property order.
+ * All entry creation MUST go through this function to guarantee a single
+ * V8 hidden class across all entries in the tree.
+ */
+export declare const createEntry: <TKey, TValue>(key: TKey, entryId: EntryId, value: TValue) => LeafEntry<TKey, TValue>;
 export interface LeafNode<TKey, TValue> {
     kind: typeof NODE_LEAF;
     entries: LeafEntry<TKey, TValue>[];
@@ -61,6 +81,7 @@ export interface BTreeState<TKey, TValue> {
     minBranchChildren: number;
     entryKeys: Map<EntryId, TKey> | null;
     autoScale: boolean;
+    deleteRebalancePolicy: DeleteRebalancePolicy;
     _nextAutoScaleThreshold: number;
     /** @internal Shared return object for navigation functions — never store a reference across calls. */
     _cursor: {
@@ -75,6 +96,7 @@ export interface InMemoryBTreeConfig<TKey> {
     duplicateKeys?: DuplicateKeyPolicy;
     enableEntryIdLookup?: boolean;
     autoScale?: boolean;
+    deleteRebalancePolicy?: DeleteRebalancePolicy;
 }
 export interface BTreeStats {
     height: number;
@@ -85,29 +107,4 @@ export interface BTreeStats {
 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;
+export { createLeafNode, createBranchNode, leafEntryCount, leafEntryAt, leafShiftEntry, leafPopEntry, leafUnshiftEntry, leafRemoveAt, leafInsertAt, leafCompact, branchCompact, branchChildCount, branchInsertAt, branchRemoveAt, } from './node-ops.js';