serializable-bptree 6.1.0 → 6.2.0

package/dist/types/BPTreeAsync.d.ts

@@ -10,9 +10,7 @@ export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
     private _createCachedNode;
     protected readLock<T>(callback: () => Promise<T>): Promise<T>;
     protected writeLock<T>(callback: () => Promise<T>): Promise<T>;
-    protected getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Promise<BPTreePair<K, V>>;
-    protected getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Promise<BPTreePair<K, V>>;
-    protected getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1, earlyTerminate: boolean): Promise<BPTreePair<K, V>>;
+    protected getPairsGenerator(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1, earlyTerminate: boolean): AsyncGenerator<[K, V]>;
     protected _createNodeId(isLeaf: boolean): Promise<string>;
     protected _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): Promise<BPTreeUnknownNode<K, V>>;
     protected _deleteEntry(node: BPTreeUnknownNode<K, V>, key: BPTreeNodeKey<K>, value: V): Promise<void>;
@@ -25,6 +23,8 @@ export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
      * This allows finding nodes by primary value only, ignoring unique identifiers.
      */
     protected insertableNodeByPrimary(value: V): Promise<BPTreeLeafNode<K, V>>;
+    protected insertableRightestNodeByPrimary(value: V): Promise<BPTreeLeafNode<K, V>>;
+    protected insertableRightestEndNodeByPrimary(value: V): Promise<BPTreeLeafNode<K, V> | null>;
     protected insertableEndNode(value: V, direction: 1 | -1): Promise<BPTreeLeafNode<K, V> | null>;
     protected leftestNode(): Promise<BPTreeLeafNode<K, V>>;
     protected rightestNode(): Promise<BPTreeLeafNode<K, V>>;
@@ -32,6 +32,16 @@ export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
     protected commitNodeCreateBuffer(): Promise<void>;
     protected commitNodeUpdateBuffer(): Promise<void>;
     protected commitNodeDeleteBuffer(): Promise<void>;
+    /**
+     * Retrieves the value associated with the given key (PK).
+     * Note: This method performs a full scan of leaf nodes as the tree is ordered by Value, not Key.
+     *
+     * @param key The key to search for.
+     * @returns The value associated with the key, or undefined if not found.
+     */
+    get(key: K): Promise<V | undefined>;
+    keysStream(condition: BPTreeCondition<V>, filterValues?: Set<K>, limit?: number): AsyncGenerator<K>;
+    whereStream(condition: BPTreeCondition<V>, limit?: number): AsyncGenerator<[K, V]>;
     keys(condition: BPTreeCondition<V>, filterValues?: Set<K>): Promise<Set<K>>;
     where(condition: BPTreeCondition<V>): Promise<BPTreePair<K, V>>;
     insert(key: K, value: V): Promise<void>;

package/dist/types/BPTreeSync.d.ts

@@ -7,9 +7,7 @@ export declare class BPTreeSync<K, V> extends BPTree<K, V> {
     protected readonly nodes: ReturnType<typeof this._createCachedNode>;
     constructor(strategy: SerializeStrategySync<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
     private _createCachedNode;
-    protected getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): BPTreePair<K, V>;
-    protected getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): BPTreePair<K, V>;
-    protected getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1, earlyTerminate: boolean): BPTreePair<K, V>;
+    protected getPairsGenerator(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: 1 | -1, earlyTerminate: boolean): Generator<[K, V]>;
     protected _createNodeId(isLeaf: boolean): string;
     protected _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): BPTreeUnknownNode<K, V>;
     protected _deleteEntry(node: BPTreeUnknownNode<K, V>, key: BPTreeNodeKey<K>, value: V): void;
@@ -22,6 +20,8 @@ export declare class BPTreeSync<K, V> extends BPTree<K, V> {
      * This allows finding nodes by primary value only, ignoring unique identifiers.
      */
     protected insertableNodeByPrimary(value: V): BPTreeLeafNode<K, V>;
+    protected insertableRightestNodeByPrimary(value: V): BPTreeLeafNode<K, V>;
+    protected insertableRightestEndNodeByPrimary(value: V): BPTreeLeafNode<K, V> | null;
     protected insertableEndNode(value: V, direction: 1 | -1): BPTreeLeafNode<K, V> | null;
     protected leftestNode(): BPTreeLeafNode<K, V>;
     protected rightestNode(): BPTreeLeafNode<K, V>;
@@ -29,6 +29,16 @@ export declare class BPTreeSync<K, V> extends BPTree<K, V> {
     protected commitNodeCreateBuffer(): void;
     protected commitNodeUpdateBuffer(): void;
     protected commitNodeDeleteBuffer(): void;
+    /**
+     * Retrieves the value associated with the given key (PK).
+     * Note: This method performs a full scan of leaf nodes as the tree is ordered by Value, not Key.
+     *
+     * @param key The key to search for.
+     * @returns The value associated with the key, or undefined if not found.
+     */
+    get(key: K): V | undefined;
+    keysStream(condition: BPTreeCondition<V>, filterValues?: Set<K>, limit?: number): Generator<K>;
+    whereStream(condition: BPTreeCondition<V>, limit?: number): Generator<[K, V]>;
     keys(condition: BPTreeCondition<V>, filterValues?: Set<K>): Set<K>;
     where(condition: BPTreeCondition<V>): BPTreePair<K, V>;
     insert(key: K, value: V): void;

package/dist/types/base/BPTree.d.ts

@@ -28,6 +28,18 @@ export type BPTreeCondition<V> = Partial<{
      * Useful for composite values where you want to find all entries with the same primary value.
      */
     primaryEqual: Partial<V>;
+    /** Searches for pairs where the primary field is greater than the given value. */
+    primaryGt: Partial<V>;
+    /** Searches for pairs where the primary field is greater than or equal to the given value. */
+    primaryGte: Partial<V>;
+    /** Searches for pairs where the primary field is less than the given value. */
+    primaryLt: Partial<V>;
+    /** Searches for pairs where the primary field is less than or equal to the given value. */
+    primaryLte: Partial<V>;
+    /** Searches for pairs where the primary field is not equal to the given value. */
+    primaryNotEqual: Partial<V>;
+    /** Searches for pairs where the primary field matches at least one of the given values. */
+    primaryOr: Partial<V>[];
 }>;
 export type BPTreePair<K, V> = Map<K, V>;
 export type BPTreeUnknownNode<K, V> = BPTreeInternalNode<K, V> | BPTreeLeafNode<K, V>;
@@ -78,11 +90,45 @@ export declare abstract class BPTree<K, V> {
      * Only applicable for conditions that guarantee contiguous matches in a sorted B+Tree.
      */
     protected readonly verifierEarlyTerminate: Record<keyof BPTreeCondition<V>, boolean>;
+    /**
+     * Priority map for condition types.
+     * Higher value = higher selectivity (fewer expected results).
+     * Used by `chooseDriver` to select the most selective index.
+     */
+    protected static readonly conditionPriority: Record<keyof BPTreeCondition<unknown>, number>;
+    /**
+     * Selects the best driver tree from multiple tree/condition pairs.
+     * Uses rule-based optimization to choose the tree with highest estimated selectivity.
+     *
+     * @param candidates Array of { tree, condition } pairs to evaluate
+     * @returns The candidate with highest priority condition, or null if empty
+     *
+     * @example
+     * ```typescript
+     * const driver = BPTreeSync.chooseDriver([
+     *   { tree: idxId, condition: { equal: 100 } },
+     *   { tree: idxAge, condition: { gt: 20 } }
+     * ])
+     * // Returns { tree: idxId, condition: { equal: 100 } } because 'equal' has higher priority
+     * ```
+     */
+    static ChooseDriver<T>(candidates: Array<{
+        tree: T;
+        condition: BPTreeCondition<unknown>;
+    }>): {
+        tree: T;
+        condition: BPTreeCondition<unknown>;
+    } | null;
+    /**
+     * Verified if the value satisfies the condition.
+     *
+     * @param nodeValue The value to verify.
+     * @param condition The condition to verify against.
+     * @returns Returns true if the value satisfies the condition.
+     */
+    verify(nodeValue: V, condition: BPTreeCondition<V>): boolean;
     protected constructor(strategy: SerializeStrategy<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
     private _createCachedRegexp;
-    protected abstract getPairsRightToLeft(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Deferred<BPTreePair<K, V>>;
-    protected abstract getPairsLeftToRight(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, earlyTerminate: boolean): Deferred<BPTreePair<K, V>>;
-    protected abstract getPairs(value: V, startNode: BPTreeLeafNode<K, V>, endNode: BPTreeLeafNode<K, V> | null, comparator: (nodeValue: V, value: V) => boolean, direction: -1 | 1, earlyTerminate: boolean): Deferred<BPTreePair<K, V>>;
     protected abstract _createNodeId(isLeaf: boolean): Deferred<string>;
     protected abstract _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): Deferred<BPTreeUnknownNode<K, V>>;
     protected abstract _deleteEntry(node: BPTreeUnknownNode<K, V>, key: BPTreeNodeKey<K>, value: V): Deferred<void>;
@@ -90,6 +136,8 @@ export declare abstract class BPTree<K, V> {
     protected abstract getNode(id: string): Deferred<BPTreeUnknownNode<K, V>>;
     protected abstract insertableNode(value: V): Deferred<BPTreeLeafNode<K, V>>;
     protected abstract insertableNodeByPrimary(value: V): Deferred<BPTreeLeafNode<K, V>>;
+    protected abstract insertableRightestNodeByPrimary(value: V): Deferred<BPTreeLeafNode<K, V>>;
+    protected abstract insertableRightestEndNodeByPrimary(value: V): Deferred<BPTreeLeafNode<K, V> | null>;
     protected abstract insertableEndNode(value: V, direction: 1 | -1): Deferred<BPTreeLeafNode<K, V> | null>;
     protected abstract leftestNode(): Deferred<BPTreeLeafNode<K, V>>;
     protected abstract rightestNode(): Deferred<BPTreeLeafNode<K, V>>;
@@ -153,6 +201,8 @@ export declare abstract class BPTree<K, V> {
     protected ensureValues(v: V | V[]): V[];
     protected lowestValue(v: V[]): V;
     protected highestValue(v: V[]): V;
+    protected lowestPrimaryValue(v: V[]): V;
+    protected highestPrimaryValue(v: V[]): V;
     protected _insertAtLeaf(node: BPTreeLeafNode<K, V>, key: K, value: V): void;
     protected bufferForNodeCreate(node: BPTreeUnknownNode<K, V>): void;
     protected bufferForNodeUpdate(node: BPTreeUnknownNode<K, V>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serializable-bptree",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Store the B+tree flexibly, not only in-memory.",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.cjs",