serializable-bptree 6.2.3 → 7.0.1

package/dist/types/BPTreeAsync.d.ts

@@ -1,52 +1,17 @@
-import { BPTree, BPTreeCondition, BPTreeLeafNode, BPTreePair, BPTreeNodeKey, BPTreeUnknownNode, BPTreeConstructorOption } from './base/BPTree';
+import type { BPTreeConstructorOption } from './types';
 import { SerializeStrategyAsync } from './SerializeStrategyAsync';
 import { ValueComparator } from './base/ValueComparator';
-import { SerializableData } from './base/SerializeStrategy';
-export declare class BPTreeAsync<K, V> extends BPTree<K, V> {
-    protected readonly strategy: SerializeStrategyAsync<K, V>;
-    protected readonly nodes: ReturnType<typeof this._createCachedNode>;
-    private readonly lock;
+import { BPTreeAsyncBase } from './base/BPTreeAsyncBase';
+import { BPTreeAsyncTransaction } from './transaction/BPTreeAsyncTransaction';
+export declare class BPTreeAsync<K, V> extends BPTreeAsyncBase<K, V> {
     constructor(strategy: SerializeStrategyAsync<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
-    private _createCachedNode;
-    protected readLock<T>(callback: () => Promise<T>): Promise<T>;
-    protected writeLock<T>(callback: () => Promise<T>): Promise<T>;
-    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>;
-    protected _insertInParent(node: BPTreeUnknownNode<K, V>, value: V, pointer: BPTreeUnknownNode<K, V>): Promise<void>;
-    init(): Promise<void>;
-    protected getNode(id: string): Promise<BPTreeUnknownNode<K, V>>;
-    protected insertableNode(value: V): Promise<BPTreeLeafNode<K, V>>;
     /**
-     * Find the insertable node using primaryAsc comparison.
-     * This allows finding nodes by primary value only, ignoring unique identifiers.
+     * Creates a new asynchronous transaction.
+     * @returns A promise that resolves to a new BPTreeAsyncTransaction.
      */
-    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>>;
-    protected commitHeadBuffer(): Promise<void>;
-    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>>;
+    createTransaction(): Promise<BPTreeAsyncTransaction<K, V>>;
     insert(key: K, value: V): Promise<void>;
     delete(key: K, value: V): Promise<void>;
-    exists(key: K, value: V): Promise<boolean>;
-    setHeadData(data: SerializableData): Promise<void>;
-    forceUpdate(): Promise<number>;
+    protected readLock<T>(fn: () => Promise<T>): Promise<T>;
+    protected writeLock<T>(fn: () => Promise<T>): Promise<T>;
 }

package/dist/types/BPTreeSync.d.ts

@@ -1,49 +1,15 @@
-import { BPTree, BPTreeCondition, BPTreeLeafNode, BPTreePair, BPTreeNodeKey, BPTreeUnknownNode, BPTreeConstructorOption } from './base/BPTree';
+import type { BPTreeConstructorOption } from './types';
 import { SerializeStrategySync } from './SerializeStrategySync';
 import { ValueComparator } from './base/ValueComparator';
-import { SerializableData } from './base/SerializeStrategy';
-export declare class BPTreeSync<K, V> extends BPTree<K, V> {
-    protected readonly strategy: SerializeStrategySync<K, V>;
-    protected readonly nodes: ReturnType<typeof this._createCachedNode>;
+import { BPTreeSyncBase } from './base/BPTreeSyncBase';
+import { BPTreeSyncTransaction } from './transaction/BPTreeSyncTransaction';
+export declare class BPTreeSync<K, V> extends BPTreeSyncBase<K, V> {
     constructor(strategy: SerializeStrategySync<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
-    private _createCachedNode;
-    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;
-    protected _insertInParent(node: BPTreeUnknownNode<K, V>, value: V, pointer: BPTreeUnknownNode<K, V>): void;
-    init(): void;
-    protected getNode(id: string): BPTreeUnknownNode<K, V>;
-    protected insertableNode(value: V): BPTreeLeafNode<K, V>;
     /**
-     * Find the insertable node using primaryAsc comparison.
-     * This allows finding nodes by primary value only, ignoring unique identifiers.
+     * Creates a new synchronous transaction.
+     * @returns A new BPTreeSyncTransaction.
      */
-    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>;
-    protected commitHeadBuffer(): void;
-    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>;
+    createTransaction(): BPTreeSyncTransaction<K, V>;
     insert(key: K, value: V): void;
     delete(key: K, value: V): void;
-    exists(key: K, value: V): boolean;
-    setHeadData(data: SerializableData): void;
-    forceUpdate(): number;
 }

package/dist/types/SerializeStrategyAsync.d.ts

@@ -1,6 +1,5 @@
-import { BPTreeNode } from './base/BPTree';
-import { SerializeStrategy, SerializeStrategyHead } from './base/SerializeStrategy';
-import { Json } from './utils/types';
+import { BPTreeNode, SerializeStrategyHead, Json } from './types';
+import { SerializeStrategy } from './base/SerializeStrategy';
 export declare abstract class SerializeStrategyAsync<K, V> extends SerializeStrategy<K, V> {
     abstract id(isLeaf: boolean): Promise<string>;
     abstract read(id: string): Promise<BPTreeNode<K, V>>;
@@ -11,6 +10,7 @@ export declare abstract class SerializeStrategyAsync<K, V> extends SerializeStra
     getHeadData(key: string, defaultValue: Json): Promise<Json>;
     setHeadData(key: string, data: Json): Promise<void>;
     autoIncrement(key: string, defaultValue: number): Promise<number>;
+    compareAndSwapHead(oldRoot: string | null, newRoot: string): Promise<boolean>;
 }
 export declare class InMemoryStoreStrategyAsync<K, V> extends SerializeStrategyAsync<K, V> {
     protected readonly node: Record<string, BPTreeNode<K, V>>;

package/dist/types/SerializeStrategySync.d.ts

@@ -1,6 +1,5 @@
-import { BPTreeNode } from './base/BPTree';
-import { SerializeStrategy, SerializeStrategyHead } from './base/SerializeStrategy';
-import { Json } from './utils/types';
+import { BPTreeNode, SerializeStrategyHead, Json } from './types';
+import { SerializeStrategy } from './base/SerializeStrategy';
 export declare abstract class SerializeStrategySync<K, V> extends SerializeStrategy<K, V> {
     abstract id(isLeaf: boolean): string;
     abstract read(id: string): BPTreeNode<K, V>;
@@ -11,6 +10,7 @@ export declare abstract class SerializeStrategySync<K, V> extends SerializeStrat
     getHeadData(key: string, defaultValue: Json): Json;
     setHeadData(key: string, data: Json): void;
     autoIncrement(key: string, defaultValue: number): number;
+    compareAndSwapHead(oldRoot: string | null, newRoot: string): boolean;
 }
 export declare class InMemoryStoreStrategySync<K, V> extends SerializeStrategySync<K, V> {
     protected readonly node: Record<string, BPTreeNode<K, V>>;

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

@@ -1,78 +1,7 @@
+import type { BPTreeCondition, BPTreeConstructorOption, BPTreeUnknownNode, Deferred, BPTreeLeafNode, BPTreeNodeKey, BPTreePair, SerializableData } from '../types';
 import { CacheEntanglementSync, CacheEntanglementAsync } from 'cache-entanglement';
 import { ValueComparator } from './ValueComparator';
-import { SerializableData, SerializeStrategy } from './SerializeStrategy';
-type Sync<T> = T;
-type Async<T> = Promise<T>;
-type Deferred<T> = Sync<T> | Async<T>;
-export type BPTreeNodeKey<K> = string | K;
-export type BPTreeCondition<V> = Partial<{
-    /** Searches for pairs greater than the given value. */
-    gt: Partial<V>;
-    /** Searches for pairs less than the given value. */
-    lt: Partial<V>;
-    /** Searches for pairs greater than or equal to the given value. */
-    gte: Partial<V>;
-    /** Searches for pairs less than or equal to the given value. */
-    lte: Partial<V>;
-    /** "Searches for pairs equal to the given value. */
-    equal: Partial<V>;
-    /** Searches for pairs not equal to the given value. */
-    notEqual: Partial<V>;
-    /** Searches for pairs that satisfy at least one of the conditions. */
-    or: Partial<V>[];
-    /** Searches for values matching the given pattern. '%' matches zero or more characters, and '_' matches exactly one character. */
-    /**
-     * Searches for pairs where the primary field equals the given value.
-     * Uses `primaryAsc` method for comparison, which compares only the primary sorting field.
-     * 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>[];
-    /**
-     * Searches for values matching the given pattern on the primary field.
-     * Uses `match` method for getting string representation.
-     * '%' matches zero or more characters, and '_' matches exactly one character.
-     */
-    like: string;
-}>;
-export type BPTreePair<K, V> = Map<K, V>;
-export type BPTreeUnknownNode<K, V> = BPTreeInternalNode<K, V> | BPTreeLeafNode<K, V>;
-export interface BPTreeConstructorOption {
-    /**
-     * The capacity of the cache.
-     * This value is used to determine how many nodes can be cached.
-     * If not specified, the default value is 1000.
-     */
-    capacity?: number;
-}
-export interface BPTreeNode<K, V> {
-    id: string;
-    keys: string[] | K[][];
-    values: V[];
-    leaf: boolean;
-    parent: string | null;
-    next: string | null;
-    prev: string | null;
-}
-export interface BPTreeInternalNode<K, V> extends BPTreeNode<K, V> {
-    leaf: false;
-    keys: string[];
-}
-export interface BPTreeLeafNode<K, V> extends BPTreeNode<K, V> {
-    leaf: true;
-    keys: K[][];
-}
+import { SerializeStrategy } from './SerializeStrategy';
 export declare abstract class BPTree<K, V> {
     private readonly _cachedRegexp;
     protected abstract readonly nodes: CacheEntanglementSync<any, any> | CacheEntanglementAsync<any, any>;
@@ -81,6 +10,16 @@ export declare abstract class BPTree<K, V> {
     protected readonly option: BPTreeConstructorOption;
     protected order: number;
     protected rootId: string;
+    /**
+     * Returns the ID of the root node.
+     * @returns The root node ID.
+     */
+    getRootId(): string;
+    /**
+     * Returns the order of the B+Tree.
+     * @returns The order of the tree.
+     */
+    getOrder(): number;
     protected _strategyDirty: boolean;
     protected readonly _nodeCreateBuffer: Map<string, BPTreeUnknownNode<K, V>>;
     protected readonly _nodeUpdateBuffer: Map<string, BPTreeUnknownNode<K, V>>;
@@ -200,18 +139,20 @@ export declare abstract class BPTree<K, V> {
     /**
      * This method deletes nodes cached in-memory and caches new nodes from the stored nodes.
      * Typically, there's no need to use this method, but it can be used to synchronize data in scenarios where the remote storage and the client are in a 1:n relationship.
+     * If you do not specify an ID, all nodes will be updated.
+     * @param id The ID of the node to update.
      * @returns The return value is the total number of nodes updated.
      */
-    abstract forceUpdate(): Deferred<number>;
+    abstract forceUpdate(id?: string): Deferred<number>;
     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;
-    protected bufferForNodeDelete(node: BPTreeUnknownNode<K, V>): void;
+    protected _insertAtLeaf(node: BPTreeLeafNode<K, V>, key: K, value: V): Deferred<void>;
+    protected bufferForNodeCreate(node: BPTreeUnknownNode<K, V>): Deferred<void>;
+    protected bufferForNodeUpdate(node: BPTreeUnknownNode<K, V>): Deferred<void>;
+    protected bufferForNodeDelete(node: BPTreeUnknownNode<K, V>): Deferred<void>;
     /**
      * Returns the user-defined data stored in the head of the tree.
      * This value can be set using the `setHeadData` method. If no data has been previously inserted, the default value is returned, and the default value is `{}`.
@@ -224,4 +165,3 @@ export declare abstract class BPTree<K, V> {
      */
     clear(): void;
 }
-export {};

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

@@ -0,0 +1,41 @@
+import type { BPTreeCondition, BPTreeConstructorOption, BPTreeUnknownNode, BPTreeLeafNode, BPTreeNodeKey, SerializableData, BPTreePair } from '../types';
+import { SerializeStrategyAsync } from '../SerializeStrategyAsync';
+import { BPTree } from './BPTree';
+import { ValueComparator } from './ValueComparator';
+export declare abstract class BPTreeAsyncBase<K, V> extends BPTree<K, V> {
+    protected readonly strategy: SerializeStrategyAsync<K, V>;
+    protected readonly nodes: ReturnType<typeof this._createCachedNode>;
+    constructor(strategy: SerializeStrategyAsync<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
+    private _createCachedNode;
+    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>;
+    protected _insertInParent(node: BPTreeUnknownNode<K, V>, value: V, pointer: BPTreeUnknownNode<K, V>): Promise<void>;
+    init(): Promise<void>;
+    protected getNode(id: string): Promise<BPTreeUnknownNode<K, V>>;
+    protected insertableNode(value: V): Promise<BPTreeLeafNode<K, V>>;
+    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>>;
+    exists(key: K, value: V): Promise<boolean>;
+    forceUpdate(id?: string): Promise<number>;
+    protected commitHeadBuffer(): Promise<void>;
+    protected commitNodeCreateBuffer(): Promise<void>;
+    protected commitNodeUpdateBuffer(): Promise<void>;
+    protected commitNodeDeleteBuffer(): Promise<void>;
+    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>;
+    delete(key: K, value: V): Promise<void>;
+    getHeadData(): SerializableData;
+    setHeadData(data: SerializableData): Promise<void>;
+    protected abstract readLock<T>(fn: () => Promise<T>): Promise<T>;
+    protected abstract writeLock<T>(fn: () => Promise<T>): Promise<T>;
+}

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

@@ -0,0 +1,39 @@
+import type { BPTreeCondition, BPTreeConstructorOption, BPTreeUnknownNode, BPTreeLeafNode, BPTreeNodeKey, BPTreePair, SerializableData } from '../types';
+import { SerializeStrategySync } from '../SerializeStrategySync';
+import { BPTree } from './BPTree';
+import { ValueComparator } from './ValueComparator';
+export declare abstract class BPTreeSyncBase<K, V> extends BPTree<K, V> {
+    protected readonly strategy: SerializeStrategySync<K, V>;
+    protected readonly nodes: ReturnType<typeof this._createCachedNode>;
+    constructor(strategy: SerializeStrategySync<K, V>, comparator: ValueComparator<V>, option?: BPTreeConstructorOption);
+    private _createCachedNode;
+    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;
+    protected _insertInParent(node: BPTreeUnknownNode<K, V>, value: V, pointer: BPTreeUnknownNode<K, V>): void;
+    init(): void;
+    protected getNode(id: string): BPTreeUnknownNode<K, V>;
+    protected insertableNode(value: V): BPTreeLeafNode<K, V>;
+    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>;
+    exists(key: K, value: V): boolean;
+    forceUpdate(id?: string): number;
+    protected commitHeadBuffer(): void;
+    protected commitNodeCreateBuffer(): void;
+    protected commitNodeUpdateBuffer(): void;
+    protected commitNodeDeleteBuffer(): void;
+    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;
+    delete(key: K, value: V): void;
+    getHeadData(): SerializableData;
+    setHeadData(data: SerializableData): void;
+}

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

@@ -1,11 +1,4 @@
-import { BPTreeNode } from './BPTree';
-import type { Json } from '../utils/types';
-export type SerializableData = Record<string, Json>;
-export interface SerializeStrategyHead {
-    root: string | null;
-    order: number;
-    data: SerializableData;
-}
+import type { BPTreeNode, Json, SerializeStrategyHead } from '../types';
 export declare abstract class SerializeStrategy<K, V> {
     readonly order: number;
     head: SerializeStrategyHead;
@@ -50,6 +43,14 @@ export declare abstract class SerializeStrategy<K, V> {
      * @param head This is the current state of the tree.
      */
     abstract writeHead(head: SerializeStrategyHead): void | Promise<void>;
+    /**
+     * Atomically updates the head if the current root matches the expected value.
+     * Required for Optimistic Concurrency Control (CoW).
+     * @param oldRoot The expected current root ID.
+     * @param newRoot The new root ID to set.
+     * @returns True if successful, False if the root has changed.
+     */
+    abstract compareAndSwapHead(oldRoot: string | null, newRoot: string): boolean | Promise<boolean>;
     /**
      * Retrieves the data stored in the tree.
      * If no value is stored in the tree, it stores a `defaultValue` and then returns that value.

package/dist/types/index.d.ts

@@ -1,7 +1,8 @@
-export type { BPTreeNode, BPTreeInternalNode, BPTreeLeafNode, BPTreeNodeKey, BPTreePair, BPTreeUnknownNode, BPTreeCondition } from './base/BPTree';
-export type { SerializeStrategyHead, SerializableData } from './base/SerializeStrategy';
+export type { BPTreeNode, BPTreeInternalNode, BPTreeLeafNode, BPTreeNodeKey, BPTreePair, BPTreeUnknownNode, BPTreeCondition, SerializeStrategyHead, SerializableData } from './types';
 export { ValueComparator, NumericComparator, StringComparator } from './base/ValueComparator';
 export { BPTreeSync } from './BPTreeSync';
+export { BPTreeSyncTransaction } from './transaction/BPTreeSyncTransaction';
 export { BPTreeAsync } from './BPTreeAsync';
+export { BPTreeAsyncTransaction } from './transaction/BPTreeAsyncTransaction';
 export { SerializeStrategySync, InMemoryStoreStrategySync } from './SerializeStrategySync';
 export { SerializeStrategyAsync, InMemoryStoreStrategyAsync } from './SerializeStrategyAsync';

package/dist/types/transaction/BPTreeAsyncSnapshotStrategy.d.ts

@@ -0,0 +1,17 @@
+import type { SerializeStrategyHead, BPTreeNode, Json } from '../types';
+import { SerializeStrategyAsync } from '../SerializeStrategyAsync';
+export declare class BPTreeAsyncSnapshotStrategy<K, V> extends SerializeStrategyAsync<K, V> {
+    private readonly baseStrategy;
+    private readonly snapshotHead;
+    constructor(baseStrategy: SerializeStrategyAsync<K, V>, root: string);
+    id(isLeaf: boolean): Promise<string>;
+    read(id: string): Promise<BPTreeNode<K, V>>;
+    write(id: string, node: BPTreeNode<K, V>): Promise<void>;
+    delete(id: string): Promise<void>;
+    readHead(): Promise<SerializeStrategyHead | null>;
+    writeHead(head: SerializeStrategyHead): Promise<void>;
+    compareAndSwapHead(oldRoot: string | null, newRoot: string): Promise<boolean>;
+    getHeadData(key: string, defaultValue: Json): Promise<Json>;
+    setHeadData(key: string, data: Json): Promise<void>;
+    autoIncrement(key: string, defaultValue: number): Promise<number>;
+}

package/dist/types/transaction/BPTreeAsyncTransaction.d.ts

@@ -0,0 +1,45 @@
+import type { BPTreeUnknownNode, BPTreeTransactionResult } from '../types';
+import { BPTreeAsyncBase } from '../base/BPTreeAsyncBase';
+/**
+ * Represents an asynchronous transaction for a B+ Tree.
+ * Provides Snapshot Isolation using MVCC and Copy-on-Write techniques.
+ */
+export declare class BPTreeAsyncTransaction<K, V> extends BPTreeAsyncBase<K, V> {
+    private readonly realBaseTree;
+    private readonly realBaseStrategy;
+    private txNodes;
+    protected readonly dirtyIds: Set<string>;
+    protected readonly createdInTx: Set<string>;
+    protected readonly deletedIds: Set<string>;
+    private initialRootId;
+    private transactionRootId;
+    constructor(baseTree: BPTreeAsyncBase<K, V>);
+    /**
+     * Initializes the transaction by capturing the current state of the tree.
+     */
+    initTransaction(): Promise<void>;
+    protected getNode(id: string): Promise<BPTreeUnknownNode<K, V>>;
+    protected bufferForNodeUpdate(node: BPTreeUnknownNode<K, V>): Promise<void>;
+    protected bufferForNodeCreate(node: BPTreeUnknownNode<K, V>): Promise<void>;
+    protected bufferForNodeDelete(node: BPTreeUnknownNode<K, V>): Promise<void>;
+    private markPathDirty;
+    protected _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): Promise<BPTreeUnknownNode<K, V>>;
+    /**
+     * Attempts to commit the transaction.
+     * Uses Optimistic Locking (Compare-And-Swap) on the root node ID to detect conflicts.
+     *
+     * @returns A promise that resolves to the transaction result.
+     */
+    commit(): Promise<BPTreeTransactionResult>;
+    /**
+     * Rolls back the transaction by clearing all buffered changes.
+     * Internal use only.
+     */
+    protected rollback(): Promise<void>;
+    protected readLock<T>(fn: () => Promise<T>): Promise<T>;
+    protected writeLock<T>(fn: () => Promise<T>): Promise<T>;
+    protected commitHeadBuffer(): Promise<void>;
+    protected commitNodeCreateBuffer(): Promise<void>;
+    protected commitNodeUpdateBuffer(): Promise<void>;
+    protected commitNodeDeleteBuffer(): Promise<void>;
+}

package/dist/types/transaction/BPTreeSyncSnapshotStrategy.d.ts

@@ -0,0 +1,17 @@
+import type { SerializeStrategyHead, BPTreeNode, Json } from '../types';
+import { SerializeStrategySync } from '../SerializeStrategySync';
+export declare class BPTreeSyncSnapshotStrategy<K, V> extends SerializeStrategySync<K, V> {
+    private readonly baseStrategy;
+    private readonly snapshotHead;
+    constructor(baseStrategy: SerializeStrategySync<K, V>, root: string);
+    id(isLeaf: boolean): string;
+    read(id: string): BPTreeNode<K, V>;
+    write(id: string, node: BPTreeNode<K, V>): void;
+    delete(id: string): void;
+    readHead(): SerializeStrategyHead | null;
+    writeHead(head: SerializeStrategyHead): void;
+    compareAndSwapHead(oldRoot: string | null, newRoot: string): boolean;
+    getHeadData(key: string, defaultValue: Json): Json;
+    setHeadData(key: string, data: Json): void;
+    autoIncrement(key: string, defaultValue: number): number;
+}

package/dist/types/transaction/BPTreeSyncTransaction.d.ts

@@ -0,0 +1,43 @@
+import type { BPTreeUnknownNode, BPTreeTransactionResult } from '../types';
+import { BPTreeSyncBase } from '../base/BPTreeSyncBase';
+/**
+ * Represents a synchronous transaction for a B+ Tree.
+ * Provides Snapshot Isolation using MVCC and Copy-on-Write techniques.
+ */
+export declare class BPTreeSyncTransaction<K, V> extends BPTreeSyncBase<K, V> {
+    private readonly realBaseTree;
+    private readonly realBaseStrategy;
+    private txNodes;
+    protected readonly dirtyIds: Set<string>;
+    protected readonly createdInTx: Set<string>;
+    protected readonly deletedIds: Set<string>;
+    private initialRootId;
+    private transactionRootId;
+    constructor(baseTree: BPTreeSyncBase<K, V>);
+    /**
+     * Initializes the transaction by capturing the current state of the tree.
+     */
+    initTransaction(): void;
+    protected getNode(id: string): BPTreeUnknownNode<K, V>;
+    protected bufferForNodeUpdate(node: BPTreeUnknownNode<K, V>): void;
+    protected bufferForNodeCreate(node: BPTreeUnknownNode<K, V>): void;
+    protected bufferForNodeDelete(node: BPTreeUnknownNode<K, V>): void;
+    private markPathDirty;
+    protected _createNode(isLeaf: boolean, keys: string[] | K[][], values: V[], leaf?: boolean, parent?: string | null, next?: string | null, prev?: string | null): BPTreeUnknownNode<K, V>;
+    /**
+     * Attempts to commit the transaction.
+     * Uses Optimistic Locking (Compare-And-Swap) on the root node ID to detect conflicts.
+     *
+     * @returns The transaction result.
+     */
+    commit(): BPTreeTransactionResult;
+    /**
+     * Rolls back the transaction by clearing all buffered changes.
+     * Internal use only.
+     */
+    protected rollback(): void;
+    protected commitHeadBuffer(): void;
+    protected commitNodeCreateBuffer(): void;
+    protected commitNodeUpdateBuffer(): void;
+    protected commitNodeDeleteBuffer(): void;
+}

package/dist/types/types/index.d.ts

@@ -0,0 +1,91 @@
+export type Sync<T> = T;
+export type Async<T> = Promise<T>;
+export type Deferred<T> = Sync<T> | Async<T>;
+export type BPTreeNodeKey<K> = string | K;
+export type BPTreeCondition<V> = Partial<{
+    /** Searches for pairs greater than the given value. */
+    gt: Partial<V>;
+    /** Searches for pairs less than the given value. */
+    lt: Partial<V>;
+    /** Searches for pairs greater than or equal to the given value. */
+    gte: Partial<V>;
+    /** Searches for pairs less than or equal to the given value. */
+    lte: Partial<V>;
+    /** "Searches for pairs equal to the given value. */
+    equal: Partial<V>;
+    /** Searches for pairs not equal to the given value. */
+    notEqual: Partial<V>;
+    /** Searches for pairs that satisfy at least one of the conditions. */
+    or: Partial<V>[];
+    /** Searches for values matching the given pattern. '%' matches zero or more characters, and '_' matches exactly one character. */
+    /**
+     * Searches for pairs where the primary field equals the given value.
+     * Uses `primaryAsc` method for comparison, which compares only the primary sorting field.
+     * 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>[];
+    /**
+     * Searches for values matching the given pattern on the primary field.
+     * Uses `match` method for getting string representation.
+     * '%' matches zero or more characters, and '_' matches exactly one character.
+     */
+    like: string;
+}>;
+export type BPTreePair<K, V> = Map<K, V>;
+export type BPTreeUnknownNode<K, V> = BPTreeInternalNode<K, V> | BPTreeLeafNode<K, V>;
+export interface BPTreeConstructorOption {
+    /**
+     * The capacity of the cache.
+     * This value is used to determine how many nodes can be cached.
+     * If not specified, the default value is 1000.
+     */
+    capacity?: number;
+}
+export interface BPTreeNode<K, V> {
+    id: string;
+    keys: string[] | K[][];
+    values: V[];
+    leaf: boolean;
+    parent: string | null;
+    next: string | null;
+    prev: string | null;
+}
+export interface BPTreeInternalNode<K, V> extends BPTreeNode<K, V> {
+    leaf: false;
+    keys: string[];
+}
+export interface BPTreeLeafNode<K, V> extends BPTreeNode<K, V> {
+    leaf: true;
+    keys: K[][];
+}
+/** Result of a transaction commit operation. */
+export interface BPTreeTransactionResult {
+    /** Whether the transaction was successfully committed. */
+    success: boolean;
+    /** IDs of new nodes created and written to storage during the transaction. */
+    createdIds: string[];
+    /** IDs of nodes that became obsolete and can be deleted after a successful commit. */
+    obsoleteIds: string[];
+}
+export type SerializableData = Record<string, Json>;
+export interface SerializeStrategyHead {
+    root: string | null;
+    order: number;
+    data: SerializableData;
+}
+export type Primitive = string | number | null | boolean;
+export type Json = Primitive | Primitive[] | Json[] | {
+    [key: string]: Json;
+};

package/package.json

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

package/dist/types/utils/types.d.ts

@@ -1,5 +0,0 @@
-type Primitive = string | number | null | boolean;
-type Json = Primitive | Primitive[] | Json[] | {
-    [key: string]: Json;
-};
-export type { Json };