@frostpillar/frostpillar-btree 0.2.6 → 0.2.7

package/dist/btree/rangeQuery.d.ts

@@ -1,4 +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,6 +6,7 @@ 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.
@@ -17,6 +18,7 @@ export interface RangeBounds {
     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';
 };
@@ -36,10 +38,17 @@ export interface LeafEntry<TKey, TValue> {
     value: TValue;
 }
 /**
- * Shallow-copies a `LeafEntry` into a plain `BTreeEntry` for safe public API return.
- * Prevents callers from holding a reference that mutates when `updateById` is called.
+ * 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 toPublicEntry: <TKey, TValue>(entry: LeafEntry<TKey, TValue>) => BTreeEntry<TKey, TValue>;
+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>[];
@@ -72,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: {
@@ -86,6 +96,7 @@ export interface InMemoryBTreeConfig<TKey> {
     duplicateKeys?: DuplicateKeyPolicy;
     enableEntryIdLookup?: boolean;
     autoScale?: boolean;
+    deleteRebalancePolicy?: DeleteRebalancePolicy;
 }
 export interface BTreeStats {
     height: number;