dataply 0.0.2 → 0.0.3

package/dist/cjs/index.js

@@ -36,6 +36,7 @@ __export(src_exports, {
   CacheEntanglementSync: () => CacheEntanglementSync2,
   Dataply: () => Dataply,
   DataplyAPI: () => DataplyAPI,
+  GlobalTransaction: () => GlobalTransaction,
   InMemoryStoreStrategyAsync: () => InMemoryStoreStrategyAsync,
   InMemoryStoreStrategySync: () => InMemoryStoreStrategySync,
   InvertedWeakMap: () => InvertedWeakMap,
@@ -2906,6 +2907,320 @@ var InvertedWeakMap = class {
 // src/core/DataplyAPI.ts
 var import_node_fs3 = __toESM(require("node:fs"));
 
+// node_modules/hookall/dist/esm/index.mjs
+var HookallStore = class extends WeakMap {
+  ensure(obj, key) {
+    if (!this.has(obj)) {
+      const scope2 = {};
+      this.set(obj, scope2);
+    }
+    const scope = this.get(obj);
+    if (!Object.prototype.hasOwnProperty.call(scope, key)) {
+      scope[key] = /* @__PURE__ */ new Map();
+    }
+    return scope[key];
+  }
+};
+var Hookall = class _Hookall {
+  static Global = {};
+  static _Store = new HookallStore();
+  beforeHooks;
+  afterHooks;
+  /**
+   * Create hook system. you can pass a target object or undefined.
+   * If you pass a object, the hook system will be work for object locally. You're going to want this kind of usage in general.
+   * If not specified, will be work for global. This is useful when you want to share your work with multiple files.
+   * @param target The object to work with locally. If not specified, will be work for global.
+   */
+  constructor(target) {
+    this.beforeHooks = _Hookall._Store.ensure(target, "before");
+    this.afterHooks = _Hookall._Store.ensure(target, "after");
+  }
+  _ensureCommand(hooks, command) {
+    if (!hooks.has(command)) {
+      hooks.set(command, []);
+    }
+    return hooks.get(command);
+  }
+  _createWrapper(command, callback, repeat) {
+    return {
+      callback,
+      command,
+      repeat
+    };
+  }
+  _on(hooks, command, callback, repeat) {
+    const wrappers = this._ensureCommand(hooks, command);
+    const wrapper = this._createWrapper(command, callback, repeat);
+    wrappers.unshift(wrapper);
+  }
+  /**
+   * You register a preprocessing function, which is called before the callback function of the `trigger` method.
+   * The value returned by this function is passed as a parameter to the `trigger` method's callback function.
+   * If you register multiple preprocessing functions, they are executed in order, with each function receiving the value returned by the previous one as a parameter.
+   * @param command Command to work.
+   * @param callback Preprocessing function to register.
+   */
+  onBefore(command, callback) {
+    this._on(this.beforeHooks, command, callback, -1);
+    return this;
+  }
+  /**
+   * Similar to the `onBefore` method, but it only runs once.
+   * For more details, please refer to the `onBefore` method.
+   * @param command Command to work.
+   * @param callback Preprocessing function to register.
+   */
+  onceBefore(command, callback) {
+    this._on(this.beforeHooks, command, callback, 1);
+    return this;
+  }
+  /**
+   * You register a post-processing function which is called after the callback function of the `trigger` method finishes.
+   * This function receives the value returned by the `trigger` method's callback function as a parameter.
+   * If you register multiple post-processing functions, they are executed in order, with each function receiving the value returned by the previous one as a parameter.
+   * @param command Command to work.
+   * @param callback Post-preprocessing function to register.
+   */
+  onAfter(command, callback) {
+    this._on(this.afterHooks, command, callback, -1);
+    return this;
+  }
+  /**
+   * Similar to the `onAfter` method, but it only runs once.
+   * For more details, please refer to the `onAfter` method.
+   * @param command Command to work.
+   * @param callback Post-preprocessing function to register.
+   */
+  onceAfter(command, callback) {
+    this._on(this.afterHooks, command, callback, 1);
+    return this;
+  }
+  _off(hooks, command, callback) {
+    const wrappers = this._ensureCommand(hooks, command);
+    if (callback) {
+      const i = wrappers.findIndex((wrapper) => wrapper.callback === callback);
+      if (i !== -1) {
+        wrappers.splice(i, 1);
+      }
+    } else {
+      wrappers.length = 0;
+    }
+    return this;
+  }
+  /**
+   * You remove the preprocessing functions registered with `onBefore` or `onceBefore` methods.
+   * If you don't specify a callback parameter, it removes all preprocessing functions registered for that command.
+   * @param command Commands with preprocessing functions to be deleted.
+   * @param callback Preprocessing function to be deleted.
+   */
+  offBefore(command, callback) {
+    this._off(this.beforeHooks, command, callback);
+    return this;
+  }
+  /**
+   * You remove the post-preprocessing functions registered with `onAfter` or `onceAfter` methods.
+   * If you don't specify a callback parameter, it removes all post-preprocessing functions registered for that command.
+   * @param command Commands with post-preprocessing functions to be deleted.
+   * @param callback post-Preprocessing function to be deleted.
+   */
+  offAfter(command, callback) {
+    this._off(this.afterHooks, command, callback);
+    return this;
+  }
+  async _hookWith(hooks, command, value, ...params) {
+    let wrappers = this._ensureCommand(hooks, command);
+    let i = wrappers.length;
+    while (i--) {
+      const wrapper = wrappers[i];
+      value = await wrapper.callback(value, ...params);
+      wrapper.repeat -= 1;
+      if (wrapper.repeat === 0) {
+        this._off(hooks, command, wrapper.callback);
+      }
+    }
+    return value;
+  }
+  /**
+   * You execute the callback function provided as a parameter. This callback function receives the 'initialValue' parameter.
+   * 
+   * If preprocessing functions are registered, they run first, and the value returned by the preprocessing functions becomes the 'initialValue' parameter.
+   * After the callback function finishes, post-processing functions are called.
+   * These post-processing functions receive the value returned by the callback function as a parameter and run sequentially.
+   * 
+   * The final value returned becomes the result of the `trigger` method.
+   * @param command Command to work.
+   * @param initialValue Initial value to be passed to the callback function.
+   * @param callback The callback function to be executed.
+   */
+  async trigger(command, initialValue, callback, ...params) {
+    let value;
+    value = await this._hookWith(this.beforeHooks, command, initialValue, ...params);
+    value = await callback(value, ...params);
+    value = await this._hookWith(this.afterHooks, command, value, ...params);
+    return value;
+  }
+};
+function useHookall(target = Hookall.Global) {
+  return new Hookall(target);
+}
+var HookallStore2 = class extends WeakMap {
+  ensure(obj, key) {
+    if (!this.has(obj)) {
+      const scope2 = {};
+      this.set(obj, scope2);
+    }
+    const scope = this.get(obj);
+    if (!Object.prototype.hasOwnProperty.call(scope, key)) {
+      scope[key] = /* @__PURE__ */ new Map();
+    }
+    return scope[key];
+  }
+};
+var HookallSync = class _HookallSync {
+  static Global = {};
+  static _Store = new HookallStore2();
+  beforeHooks;
+  afterHooks;
+  /**
+   * Create hook system. you can pass a target object or undefined.
+   * If you pass a object, the hook system will be work for object locally. You're going to want this kind of usage in general.
+   * If not specified, will be work for global. This is useful when you want to share your work with multiple files.
+   * @param target The object to work with locally. If not specified, will be work for global.
+   */
+  constructor(target) {
+    this.beforeHooks = _HookallSync._Store.ensure(target, "before");
+    this.afterHooks = _HookallSync._Store.ensure(target, "after");
+  }
+  _ensureCommand(hooks, command) {
+    if (!hooks.has(command)) {
+      hooks.set(command, []);
+    }
+    return hooks.get(command);
+  }
+  _createWrapper(command, callback, repeat) {
+    return {
+      callback,
+      command,
+      repeat
+    };
+  }
+  _on(hooks, command, callback, repeat) {
+    const wrappers = this._ensureCommand(hooks, command);
+    const wrapper = this._createWrapper(command, callback, repeat);
+    wrappers.unshift(wrapper);
+  }
+  /**
+   * You register a preprocessing function, which is called before the callback function of the `trigger` method.
+   * The value returned by this function is passed as a parameter to the `trigger` method's callback function.
+   * If you register multiple preprocessing functions, they are executed in order, with each function receiving the value returned by the previous one as a parameter.
+   * @param command Command to work.
+   * @param callback Preprocessing function to register.
+   */
+  onBefore(command, callback) {
+    this._on(this.beforeHooks, command, callback, -1);
+    return this;
+  }
+  /**
+   * Similar to the `onBefore` method, but it only runs once.
+   * For more details, please refer to the `onBefore` method.
+   * @param command Command to work.
+   * @param callback Preprocessing function to register.
+   */
+  onceBefore(command, callback) {
+    this._on(this.beforeHooks, command, callback, 1);
+    return this;
+  }
+  /**
+   * You register a post-processing function which is called after the callback function of the `trigger` method finishes.
+   * This function receives the value returned by the `trigger` method's callback function as a parameter.
+   * If you register multiple post-processing functions, they are executed in order, with each function receiving the value returned by the previous one as a parameter.
+   * @param command Command to work.
+   * @param callback Post-preprocessing function to register.
+   */
+  onAfter(command, callback) {
+    this._on(this.afterHooks, command, callback, -1);
+    return this;
+  }
+  /**
+   * Similar to the `onAfter` method, but it only runs once.
+   * For more details, please refer to the `onAfter` method.
+   * @param command Command to work.
+   * @param callback Post-preprocessing function to register.
+   */
+  onceAfter(command, callback) {
+    this._on(this.afterHooks, command, callback, 1);
+    return this;
+  }
+  _off(hooks, command, callback) {
+    const wrappers = this._ensureCommand(hooks, command);
+    if (callback) {
+      const i = wrappers.findIndex((wrapper) => wrapper.callback === callback);
+      if (i !== -1) {
+        wrappers.splice(i, 1);
+      }
+    } else {
+      wrappers.length = 0;
+    }
+    return this;
+  }
+  /**
+   * You remove the preprocessing functions registered with `onBefore` or `onceBefore` methods.
+   * If you don't specify a callback parameter, it removes all preprocessing functions registered for that command.
+   * @param command Commands with preprocessing functions to be deleted.
+   * @param callback Preprocessing function to be deleted.
+   */
+  offBefore(command, callback) {
+    this._off(this.beforeHooks, command, callback);
+    return this;
+  }
+  /**
+   * You remove the post-preprocessing functions registered with `onAfter` or `onceAfter` methods.
+   * If you don't specify a callback parameter, it removes all post-preprocessing functions registered for that command.
+   * @param command Commands with post-preprocessing functions to be deleted.
+   * @param callback post-Preprocessing function to be deleted.
+   */
+  offAfter(command, callback) {
+    this._off(this.afterHooks, command, callback);
+    return this;
+  }
+  _hookWith(hooks, command, value, ...params) {
+    let wrappers = this._ensureCommand(hooks, command);
+    let i = wrappers.length;
+    while (i--) {
+      const wrapper = wrappers[i];
+      value = wrapper.callback(value, ...params);
+      wrapper.repeat -= 1;
+      if (wrapper.repeat === 0) {
+        this._off(hooks, command, wrapper.callback);
+      }
+    }
+    return value;
+  }
+  /**
+   * You execute the callback function provided as a parameter. This callback function receives the 'initialValue' parameter.
+   * 
+   * If preprocessing functions are registered, they run first, and the value returned by the preprocessing functions becomes the 'initialValue' parameter.
+   * After the callback function finishes, post-processing functions are called.
+   * These post-processing functions receive the value returned by the callback function as a parameter and run sequentially.
+   * 
+   * The final value returned becomes the result of the `trigger` method.
+   * @param command Command to work.
+   * @param initialValue Initial value to be passed to the callback function.
+   * @param callback The callback function to be executed.
+   */
+  trigger(command, initialValue, callback, ...params) {
+    let value;
+    value = this._hookWith(this.beforeHooks, command, initialValue, ...params);
+    value = callback(value, ...params);
+    value = this._hookWith(this.afterHooks, command, value, ...params);
+    return value;
+  }
+};
+function useHookallSync(target = HookallSync.Global) {
+  return new HookallSync(target);
+}
+
 // src/utils/numberToBytes.ts
 function numberToBytes(value, buffer, offset = 0, length = buffer.length) {
   if (length === 4) {
@@ -4323,9 +4638,33 @@ var LogManager = class {
       });
     });
   }
+  /**
+   * Writes a commit marker to the log file.
+   * This indicates that the preceding logs are part of a committed transaction.
+   */
+  async writeCommitMarker() {
+    if (this.fd === null) {
+      this.open();
+    }
+    this.view.setUint32(0, 4294967295, true);
+    this.buffer.fill(0, 4);
+    await new Promise((resolve, reject) => {
+      import_node_fs.default.write(this.fd, this.buffer, 0, this.entrySize, null, (err) => {
+        if (err) return reject(err);
+        resolve();
+      });
+    });
+    await new Promise((resolve, reject) => {
+      import_node_fs.default.fsync(this.fd, (err) => {
+        if (err) return reject(err);
+        resolve();
+      });
+    });
+  }
   /**
    * Reads the log file to recover the page map.
    * Runs synchronously as it is called by the VFS constructor.
+   * Only returns pages from committed transactions (ended with a commit marker).
    * @returns Recovered page map
    */
   readAllSync() {
@@ -4335,11 +4674,19 @@ var LogManager = class {
     const restoredPages = /* @__PURE__ */ new Map();
     const currentFileSize = import_node_fs.default.fstatSync(this.fd).size;
     let offset = 0;
+    let pendingPages = /* @__PURE__ */ new Map();
     while (offset + this.entrySize <= currentFileSize) {
       import_node_fs.default.readSync(this.fd, this.buffer, 0, this.entrySize, offset);
       const pageId = this.view.getUint32(0, true);
-      const pageData = this.buffer.slice(4, 4 + this.pageSize);
-      restoredPages.set(pageId, pageData);
+      if (pageId === 4294967295) {
+        for (const [pId, pData] of pendingPages) {
+          restoredPages.set(pId, pData);
+        }
+        pendingPages.clear();
+      } else {
+        const pageData = this.buffer.slice(4, 4 + this.pageSize);
+        pendingPages.set(pageId, pageData);
+      }
       offset += this.entrySize;
     }
     return restoredPages;
@@ -4441,13 +4788,13 @@ var VirtualFileSystem = class {
     }
   }
   /**
-   * Commits the transaction.
+   * Prepares the transaction for commit (Phase 1).
+   * Writes dirty pages to WAL but does not update the main database file.
    * @param tx Transaction
    */
-  async commit(tx) {
+  async prepareCommit(tx) {
     const dirtyPages = tx.__getDirtyPages();
     if (dirtyPages.size === 0) {
-      this.cleanupTransaction(tx);
       return;
     }
     const dirtyPageMap = /* @__PURE__ */ new Map();
@@ -4460,6 +4807,21 @@ var VirtualFileSystem = class {
     if (this.logManager && dirtyPageMap.size > 0) {
       await this.logManager.append(dirtyPageMap);
     }
+  }
+  /**
+   * Finalizes the transaction commit (Phase 2).
+   * Writes commit marker to WAL and updates the main database file (Checkpoint).
+   * @param tx Transaction
+   */
+  async finalizeCommit(tx) {
+    const dirtyPages = tx.__getDirtyPages();
+    if (dirtyPages.size === 0) {
+      this.cleanupTransaction(tx);
+      return;
+    }
+    if (this.logManager) {
+      await this.logManager.writeCommitMarker();
+    }
     const sortedPages = Array.from(dirtyPages).sort((a, b) => a - b);
     const promises = [];
     for (const pageId of sortedPages) {
@@ -4482,6 +4844,15 @@ var VirtualFileSystem = class {
     }
     this.cleanupTransaction(tx);
   }
+  /**
+   * Commits the transaction (Single Phase).
+   * Wrapper for prepare + finalize for backward compatibility.
+   * @param tx Transaction
+   */
+  async commit(tx) {
+    await this.prepareCommit(tx);
+    await this.finalizeCommit(tx);
+  }
   /**
    * Rolls back the transaction.
    * @param tx Transaction
@@ -5728,11 +6099,19 @@ var Transaction = class {
     this.heldLocks.add(lockId);
     this.pageLocks.set(pageId, lockId);
   }
+  /**
+   * Prepares the transaction for commit (Phase 1 of 2PC).
+   * Writes dirty pages to WAL but does not update the database file yet.
+   */
+  async prepare() {
+    await this.vfs.prepareCommit(this);
+  }
   /**
    * Commits the transaction.
    */
   async commit() {
-    await this.vfs.commit(this);
+    await this.vfs.prepareCommit(this);
+    await this.vfs.finalizeCommit(this);
     await TxContext.run(this, async () => {
       for (const hook of this.commitHooks) {
         await hook();
@@ -5776,11 +6155,20 @@ var Transaction = class {
 
 // src/core/DataplyAPI.ts
 var DataplyAPI = class {
-  constructor(file, fileHandle, options) {
+  constructor(file, options) {
     this.file = file;
-    this.fileHandle = fileHandle;
-    this.options = options;
-    this.pfs = new PageFileSystem(fileHandle, options.pageSize, options.pageCacheCapacity, options.wal);
+    this.hook = {
+      sync: useHookallSync(this),
+      async: useHookall(this)
+    };
+    this.options = this.verboseOptions(options);
+    this.fileHandle = this.createOrOpen(file, this.options);
+    this.pfs = new PageFileSystem(
+      this.fileHandle,
+      this.options.pageSize,
+      this.options.pageCacheCapacity,
+      this.options.wal
+    );
     this.textCodec = new TextCodec();
     this.lockManager = new LockManager();
     this.rowTableEngine = new RowTableEngine(this.pfs, this.options);
@@ -5788,10 +6176,12 @@ var DataplyAPI = class {
     this.txIdCounter = 0;
   }
   options;
+  fileHandle;
   pfs;
   rowTableEngine;
   lockManager;
   textCodec;
+  hook;
   initialized;
   txIdCounter;
   /**
@@ -5800,7 +6190,7 @@ var DataplyAPI = class {
    * @param fileHandle File handle
    * @returns Whether the page file is a valid Dataply file
    */
-  static VerifyFormat(fileHandle) {
+  verifyFormat(fileHandle) {
     const size = MetadataPageManager.CONSTANT.OFFSET_MAGIC_STRING + MetadataPageManager.CONSTANT.MAGIC_STRING.length;
     const metadataPage = new Uint8Array(size);
     import_node_fs3.default.readSync(fileHandle, metadataPage, 0, size, 0);
@@ -5814,7 +6204,7 @@ var DataplyAPI = class {
    * @param options Options
    * @returns Options filled without omissions
    */
-  static VerboseOptions(options) {
+  verboseOptions(options) {
     return Object.assign({
       pageSize: 8192,
       pageCacheCapacity: 1e4,
@@ -5825,67 +6215,71 @@ var DataplyAPI = class {
    * Initializes the database file.
    * The first page is initialized as the metadata page.
    * The second page is initialized as the first data page.
+   * @param file Database file path
    * @param fileHandle File handle
    */
-  static InitializeFile(fileHandle, options) {
-    const metadataPageManager = new MetadataPageManager();
-    const bitmapPageManager = new BitmapPageManager();
-    const dataPageManager = new DataPageManager();
-    const metadataPage = new Uint8Array(options.pageSize);
-    const dataPage = new Uint8Array(options.pageSize);
-    metadataPageManager.initial(
-      metadataPage,
-      MetadataPageManager.CONSTANT.PAGE_TYPE_METADATA,
-      0,
-      0,
-      options.pageSize - MetadataPageManager.CONSTANT.SIZE_PAGE_HEADER
-    );
-    metadataPageManager.setMagicString(metadataPage);
-    metadataPageManager.setPageSize(metadataPage, options.pageSize);
-    metadataPageManager.setRootIndexPageId(metadataPage, -1);
-    metadataPageManager.setBitmapPageId(metadataPage, 1);
-    metadataPageManager.setLastInsertPageId(metadataPage, 2);
-    metadataPageManager.setPageCount(metadataPage, 3);
-    metadataPageManager.setFreePageId(metadataPage, -1);
-    const bitmapPage = new Uint8Array(options.pageSize);
-    bitmapPageManager.initial(
-      bitmapPage,
-      BitmapPageManager.CONSTANT.PAGE_TYPE_BITMAP,
-      1,
-      -1,
-      options.pageSize - BitmapPageManager.CONSTANT.SIZE_PAGE_HEADER
-    );
-    dataPageManager.initial(
-      dataPage,
-      DataPageManager.CONSTANT.PAGE_TYPE_DATA,
-      2,
-      -1,
-      options.pageSize - DataPageManager.CONSTANT.SIZE_PAGE_HEADER
-    );
-    import_node_fs3.default.appendFileSync(fileHandle, new Uint8Array([
-      ...metadataPage,
-      ...bitmapPage,
-      ...dataPage
-    ]));
+  initializeFile(file, fileHandle, options) {
+    const fileData = this.hook.sync.trigger("create", new Uint8Array(), (prepareFileData) => {
+      const metadataPageManager = new MetadataPageManager();
+      const bitmapPageManager = new BitmapPageManager();
+      const dataPageManager = new DataPageManager();
+      const metadataPage = new Uint8Array(options.pageSize);
+      const dataPage = new Uint8Array(options.pageSize);
+      metadataPageManager.initial(
+        metadataPage,
+        MetadataPageManager.CONSTANT.PAGE_TYPE_METADATA,
+        0,
+        0,
+        options.pageSize - MetadataPageManager.CONSTANT.SIZE_PAGE_HEADER
+      );
+      metadataPageManager.setMagicString(metadataPage);
+      metadataPageManager.setPageSize(metadataPage, options.pageSize);
+      metadataPageManager.setRootIndexPageId(metadataPage, -1);
+      metadataPageManager.setBitmapPageId(metadataPage, 1);
+      metadataPageManager.setLastInsertPageId(metadataPage, 2);
+      metadataPageManager.setPageCount(metadataPage, 3);
+      metadataPageManager.setFreePageId(metadataPage, -1);
+      const bitmapPage = new Uint8Array(options.pageSize);
+      bitmapPageManager.initial(
+        bitmapPage,
+        BitmapPageManager.CONSTANT.PAGE_TYPE_BITMAP,
+        1,
+        -1,
+        options.pageSize - BitmapPageManager.CONSTANT.SIZE_PAGE_HEADER
+      );
+      dataPageManager.initial(
+        dataPage,
+        DataPageManager.CONSTANT.PAGE_TYPE_DATA,
+        2,
+        -1,
+        options.pageSize - DataPageManager.CONSTANT.SIZE_PAGE_HEADER
+      );
+      return new Uint8Array([
+        ...prepareFileData,
+        ...metadataPage,
+        ...bitmapPage,
+        ...dataPage
+      ]);
+    }, file, fileHandle, options);
+    import_node_fs3.default.appendFileSync(fileHandle, fileData);
   }
   /**
    * Opens the database file. If the file does not exist, it initializes it.
    * @param file Database file path
    * @param options Options
-   * @returns Dataply instance
+   * @returns File handle
    */
-  static Use(file, options) {
-    const verboseOption = this.VerboseOptions(options);
+  createOrOpen(file, options) {
     let fileHandle;
-    if (verboseOption.pageCacheCapacity < 100) {
+    if (options.pageCacheCapacity < 100) {
       throw new Error("Page cache capacity must be at least 100");
     }
     if (!import_node_fs3.default.existsSync(file)) {
-      if (verboseOption.pageSize < 4096) {
+      if (options.pageSize < 4096) {
         throw new Error("Page size must be at least 4096 bytes");
       }
       fileHandle = import_node_fs3.default.openSync(file, "w+");
-      this.InitializeFile(fileHandle, verboseOption);
+      this.initializeFile(file, fileHandle, options);
     } else {
       fileHandle = import_node_fs3.default.openSync(file, "r+");
       const buffer = new Uint8Array(
@@ -5896,14 +6290,14 @@ var DataplyAPI = class {
       if (metadataManager.isMetadataPage(buffer)) {
         const storedPageSize = metadataManager.getPageSize(buffer);
         if (storedPageSize > 0) {
-          verboseOption.pageSize = storedPageSize;
+          options.pageSize = storedPageSize;
         }
       }
     }
-    if (!this.VerifyFormat(fileHandle)) {
+    if (!this.verifyFormat(fileHandle)) {
       throw new Error("Invalid dataply file");
     }
-    return new this(file, fileHandle, verboseOption);
+    return fileHandle;
   }
   /**
    * Initializes the dataply instance.
@@ -5914,8 +6308,12 @@ var DataplyAPI = class {
     if (this.initialized) {
       return;
     }
-    await this.runWithDefault(() => this.rowTableEngine.init());
-    this.initialized = true;
+    await this.runWithDefault(() => {
+      return this.hook.async.trigger("init", void 0, async () => {
+        await this.rowTableEngine.init();
+        this.initialized = true;
+      });
+    });
   }
   /**
    * Creates a transaction.
@@ -5974,10 +6372,11 @@ var DataplyAPI = class {
       throw new Error("Dataply instance is not initialized");
     }
     return this.runWithDefault((tx2) => {
+      incrementRowCount = incrementRowCount ?? true;
       if (typeof data === "string") {
         data = this.textCodec.encode(data);
       }
-      return this.rowTableEngine.insert(data, incrementRowCount ?? true, tx2);
+      return this.rowTableEngine.insert(data, incrementRowCount, tx2);
     }, tx);
   }
   /**
@@ -5993,10 +6392,11 @@ var DataplyAPI = class {
       throw new Error("Dataply instance is not initialized");
     }
     return this.runWithDefault(async (tx2) => {
+      incrementRowCount = incrementRowCount ?? true;
       const pks = [];
       for (const data of dataList) {
         const encoded = typeof data === "string" ? this.textCodec.encode(data) : data;
-        const pk = await this.rowTableEngine.insert(encoded, incrementRowCount ?? true, tx2);
+        const pk = await this.rowTableEngine.insert(encoded, incrementRowCount, tx2);
         pks.push(pk);
       }
       return pks;
@@ -6030,7 +6430,8 @@ var DataplyAPI = class {
       throw new Error("Dataply instance is not initialized");
     }
     return this.runWithDefault(async (tx2) => {
-      await this.rowTableEngine.delete(pk, decrementRowCount ?? true, tx2);
+      decrementRowCount = decrementRowCount ?? true;
+      await this.rowTableEngine.delete(pk, decrementRowCount, tx2);
     }, tx);
   }
   async select(pk, asRaw = false, tx) {
@@ -6051,8 +6452,10 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    await this.pfs.close();
-    import_node_fs3.default.closeSync(this.fileHandle);
+    return this.hook.async.trigger("close", void 0, async () => {
+      await this.pfs.close();
+      import_node_fs3.default.closeSync(this.fileHandle);
+    });
   }
 };
 
@@ -6060,7 +6463,7 @@ var DataplyAPI = class {
 var Dataply = class {
   api;
   constructor(file, options) {
-    this.api = DataplyAPI.Use(file, options);
+    this.api = new DataplyAPI(file, options ?? {});
   }
   /**
    * Gets the options used to open the dataply.
@@ -6139,6 +6542,52 @@ var Dataply = class {
     return this.api.close();
   }
 };
+
+// src/core/transaction/GlobalTransaction.ts
+var GlobalTransaction = class {
+  transactions = [];
+  isCommitted = false;
+  isRolledBack = false;
+  /**
+   * Adds a transaction to the global transaction.
+   * @param tx Transaction to add
+   */
+  add(tx) {
+    this.transactions.push(tx);
+  }
+  /**
+   * Commits all transactions atomically.
+   * Phase 1: Prepare (Write WAL)
+   * Phase 2: Commit (Write Commit Marker & Checkpoint)
+   */
+  async commit() {
+    if (this.isCommitted || this.isRolledBack) {
+      throw new Error("Transaction is already finished");
+    }
+    try {
+      await Promise.all(this.transactions.map((tx) => tx.prepare()));
+    } catch (e) {
+      await this.rollback();
+      throw new Error(`Global commit failed during prepare phase: ${e}`);
+    }
+    try {
+      await Promise.all(this.transactions.map((tx) => tx.commit()));
+      this.isCommitted = true;
+    } catch (e) {
+      throw new Error(`Global commit failed during finalize phase: ${e}`);
+    }
+  }
+  /**
+   * Rolls back all transactions.
+   */
+  async rollback() {
+    if (this.isCommitted || this.isRolledBack) {
+      return;
+    }
+    await Promise.all(this.transactions.map((tx) => tx.rollback()));
+    this.isRolledBack = true;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BPTreeAsync,
@@ -6147,6 +6596,7 @@ var Dataply = class {
   CacheEntanglementSync,
   Dataply,
   DataplyAPI,
+  GlobalTransaction,
   InMemoryStoreStrategyAsync,
   InMemoryStoreStrategySync,
   InvertedWeakMap,

package/dist/types/core/DataplyAPI.d.ts

@@ -1,50 +1,63 @@
 import type { DataplyOptions, DataplyMetadata } from '../types';
+import { type IHookall, type IHookallSync } from 'hookall';
 import { PageFileSystem } from './PageFileSystem';
 import { RowTableEngine } from './RowTableEngine';
 import { TextCodec } from '../utils/TextCodec';
 import { LockManager } from './transaction/LockManager';
 import { Transaction } from './transaction/Transaction';
+interface DataplyAPISyncHook {
+    create: (fileData: Uint8Array, file: string, fileHandle: number, options: Required<DataplyOptions>) => Uint8Array;
+}
+interface DataplyAPIAsyncHook {
+    init: () => Promise<void>;
+    close: () => Promise<void>;
+}
 /**
  * Class for managing Dataply files.
  */
 export declare class DataplyAPI {
-    protected file: string;
-    protected fileHandle: number;
+    protected readonly file: string;
     readonly options: Required<DataplyOptions>;
+    protected readonly fileHandle: number;
     protected readonly pfs: PageFileSystem;
     protected readonly rowTableEngine: RowTableEngine;
     protected readonly lockManager: LockManager;
     protected readonly textCodec: TextCodec;
+    protected readonly hook: {
+        sync: IHookallSync<DataplyAPISyncHook>;
+        async: IHookall<DataplyAPIAsyncHook>;
+    };
     protected initialized: boolean;
     private txIdCounter;
-    protected constructor(file: string, fileHandle: number, options: Required<DataplyOptions>);
+    constructor(file: string, options: DataplyOptions);
     /**
      * Verifies if the page file is a valid Dataply file.
      * The metadata page must be located at the beginning of the Dataply file.
      * @param fileHandle File handle
      * @returns Whether the page file is a valid Dataply file
      */
-    static VerifyFormat(fileHandle: number): boolean;
+    private verifyFormat;
     /**
      * Fills missing options with default values.
      * @param options Options
      * @returns Options filled without omissions
      */
-    static VerboseOptions(options?: DataplyOptions): Required<DataplyOptions>;
+    private verboseOptions;
     /**
      * Initializes the database file.
      * The first page is initialized as the metadata page.
      * The second page is initialized as the first data page.
+     * @param file Database file path
      * @param fileHandle File handle
      */
-    static InitializeFile(fileHandle: number, options: Required<DataplyOptions>): void;
+    private initializeFile;
     /**
      * Opens the database file. If the file does not exist, it initializes it.
      * @param file Database file path
      * @param options Options
-     * @returns Dataply instance
+     * @returns File handle
      */
-    static Use(file: string, options?: DataplyOptions): DataplyAPI;
+    private createOrOpen;
     /**
      * Initializes the dataply instance.
      * Must be called before using the dataply instance.
@@ -119,3 +132,4 @@ export declare class DataplyAPI {
      */
     close(): Promise<void>;
 }
+export {};

package/dist/types/core/LogManager.d.ts

@@ -25,9 +25,15 @@ export declare class LogManager {
      * @param pages Map of changed pages (Page ID -> Data)
      */
     append(pages: Map<number, Uint8Array>): Promise<void>;
+    /**
+     * Writes a commit marker to the log file.
+     * This indicates that the preceding logs are part of a committed transaction.
+     */
+    writeCommitMarker(): Promise<void>;
     /**
      * Reads the log file to recover the page map.
      * Runs synchronously as it is called by the VFS constructor.
+     * Only returns pages from committed transactions (ended with a commit marker).
      * @returns Recovered page map
      */
     readAllSync(): Map<number, Uint8Array>;

package/dist/types/core/VirtualFileSystem.d.ts

@@ -29,7 +29,20 @@ export declare class VirtualFileSystem {
      */
     private recover;
     /**
-     * Commits the transaction.
+     * Prepares the transaction for commit (Phase 1).
+     * Writes dirty pages to WAL but does not update the main database file.
+     * @param tx Transaction
+     */
+    prepareCommit(tx: Transaction): Promise<void>;
+    /**
+     * Finalizes the transaction commit (Phase 2).
+     * Writes commit marker to WAL and updates the main database file (Checkpoint).
+     * @param tx Transaction
+     */
+    finalizeCommit(tx: Transaction): Promise<void>;
+    /**
+     * Commits the transaction (Single Phase).
+     * Wrapper for prepare + finalize for backward compatibility.
      * @param tx Transaction
      */
     commit(tx: Transaction): Promise<void>;

package/dist/types/core/transaction/GlobalTransaction.d.ts

@@ -0,0 +1,25 @@
+import { Transaction } from './Transaction';
+/**
+ * Global Transaction Manager.
+ * Coordinates transactions across multiple instances (shards) using 2-Phase Commit (2PC).
+ */
+export declare class GlobalTransaction {
+    private transactions;
+    private isCommitted;
+    private isRolledBack;
+    /**
+     * Adds a transaction to the global transaction.
+     * @param tx Transaction to add
+     */
+    add(tx: Transaction): void;
+    /**
+     * Commits all transactions atomically.
+     * Phase 1: Prepare (Write WAL)
+     * Phase 2: Commit (Write Commit Marker & Checkpoint)
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back all transactions.
+     */
+    rollback(): Promise<void>;
+}

package/dist/types/core/transaction/Transaction.d.ts

@@ -86,6 +86,11 @@ export declare class Transaction {
      * @param pageId Page ID
      */
     __acquireWriteLock(pageId: number): Promise<void>;
+    /**
+     * Prepares the transaction for commit (Phase 1 of 2PC).
+     * Writes dirty pages to WAL but does not update the database file yet.
+     */
+    prepare(): Promise<void>;
     /**
      * Commits the transaction.
      */

package/dist/types/index.d.ts

@@ -4,3 +4,4 @@ export * from 'cache-entanglement';
 export type { DataplyOptions } from './types';
 export { Dataply } from './core/Dataply';
 export { DataplyAPI } from './core/DataplyAPI';
+export { GlobalTransaction } from './core/transaction/GlobalTransaction';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A lightweight storage engine for Node.js with support for MVCC, WAL.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -45,7 +45,8 @@
   },
   "dependencies": {
     "cache-entanglement": "^1.7.1",
+    "hookall": "^2.2.0",
     "ryoiki": "^1.2.0",
     "serializable-bptree": "^5.2.1"
   }
-}
+}

package/readme.md

@@ -82,6 +82,36 @@ try {
 }
 ```
 
+### Global Transactions
+You can perform atomic operations across multiple `Dataply` instances using the `GlobalTransaction` class. This uses a **2-Phase Commit (2PC)** mechanism to ensure that either all instances commit successfully or all are rolled back.
+
+```typescript
+import { Dataply, GlobalTransaction } from 'dataply'
+
+const db1 = new Dataply('./db1.db', { wal: './db1.wal' })
+const db2 = new Dataply('./db2.db', { wal: './db2.wal' })
+
+await db1.init()
+await db2.init()
+
+const tx1 = db1.createTransaction()
+const tx2 = db2.createTransaction()
+
+const globalTx = new GlobalTransaction()
+globalTx.add(tx1)
+globalTx.add(tx2)
+
+try {
+  await db1.insert('Data for DB1', tx1)
+  await db2.insert('Data for DB2', tx2)
+  
+  // Phase 1: Prepare (WAL write) -> Phase 2: Commit (Marker write)
+  await globalTx.commit() 
+} catch (error) {
+  await globalTx.rollback()
+}
+```
+
 ### Auto-Transaction
 If you omit the `tx` argument when calling methods like `insert`, `update`, or `delete`, Dataply internally **creates an individual transaction automatically**.
 
@@ -133,6 +163,17 @@ Permanently reflects all changes made during the transaction to disk and release
 #### `async rollback(): Promise<void>`
 Cancels all changes made during the transaction and restores the original state.
 
+### GlobalTransaction Class
+
+#### `add(tx: Transaction): void`
+Adds an individual transaction from a `Dataply` instance to the global transaction.
+
+#### `async commit(): Promise<void>`
+Atomically commits all added transactions using a 2-Phase Commit (2PC) process.
+
+#### `async rollback(): Promise<void>`
+Rolls back all added transactions.
+
 ## Extending Dataply
 
 If you want to extend Dataply's functionality, use the `DataplyAPI` class. Unlike the standard `Dataply` class, `DataplyAPI` provides direct access to internal components like `PageFileSystem` or `RowTableEngine`, offering much more flexibility for custom implementations.
@@ -152,7 +193,7 @@ class CustomDataply extends DataplyAPI {
   }
 }
 
-const custom = CustomDataply.Use('./data.db')
+const custom = new CustomDataply('./data.db')
 await custom.init()
 
 const stats = await custom.getInternalStats()

package/dist/types/core/RowIndexStategy.d.ts

@@ -1,19 +0,0 @@
-import { type BPTreeNode, type SerializeStrategyHead, SerializeStrategyAsync } from 'serializable-bptree';
-import { PageFileSystem } from './PageFileSystem';
-import { IndexPageManager, PageManagerFactory } from './Page';
-import { TextCodec } from '../utils/TextCodec';
-export declare class RowIdentifierStrategy extends SerializeStrategyAsync<number, number> {
-    readonly order: number;
-    protected readonly pfs: PageFileSystem;
-    protected rootPageId: number;
-    protected factory: PageManagerFactory;
-    protected indexPageManger: IndexPageManager;
-    protected codec: TextCodec;
-    constructor(order: number, pfs: PageFileSystem);
-    id(isLeaf: boolean): Promise<string>;
-    read(id: string): Promise<BPTreeNode<number, number>>;
-    write(id: string, node: BPTreeNode<number, number>): Promise<void>;
-    delete(id: string): Promise<void>;
-    readHead(): Promise<SerializeStrategyHead | null>;
-    writeHead(head: SerializeStrategyHead): Promise<void>;
-}

package/dist/types/core/Shard.d.ts

@@ -1,75 +0,0 @@
-import type { ShardOptions, ShardMetadata } from '../types';
-import { ShardAPI } from './ShareAPI';
-import { Transaction } from './transaction/Transaction';
-/**
- * Class for managing Shard files.
- */
-export declare class Shard {
-    protected readonly api: ShardAPI;
-    constructor(file: string, options?: ShardOptions);
-    /**
-     * Gets the options used to open the shard.
-     * @returns Options used to open the shard.
-     */
-    get options(): Required<ShardOptions>;
-    /**
-     * Creates a transaction.
-     * The created transaction object can be used to add or modify data.
-     * A transaction must be terminated by calling either `commit` or `rollback`.
-     * @returns Transaction object
-     */
-    createTransaction(): Transaction;
-    /**
-     * Initializes the shard instance.
-     * Must be called before using the shard instance.
-     * If not called, the shard instance cannot be used.
-     */
-    init(): Promise<void>;
-    /**
-     * Retrieves metadata from the shard.
-     * @returns Metadata of the shard.
-     */
-    getMetadata(): Promise<ShardMetadata>;
-    /**
-     * Inserts data. Returns the PK of the added row.
-     * @param data Data to add
-     * @param tx Transaction
-     * @returns PK of the added data
-     */
-    insert(data: string | Uint8Array, tx?: Transaction): Promise<number>;
-    /**
-     * Inserts multiple data in batch.
-     * If a transaction is not provided, it internally creates a single transaction to process.
-     * @param dataList Array of data to add
-     * @param tx Transaction
-     * @returns Array of PKs of the added data
-     */
-    insertBatch(dataList: (string | Uint8Array)[], tx?: Transaction): Promise<number[]>;
-    /**
-     * Updates data.
-     * @param pk PK of the data to update
-     * @param data Data to update
-     * @param tx Transaction
-     */
-    update(pk: number, data: string | Uint8Array, tx?: Transaction): Promise<void>;
-    /**
-     * Deletes data.
-     * @param pk PK of the data to delete
-     * @param tx Transaction
-     */
-    delete(pk: number, tx?: Transaction): Promise<void>;
-    /**
-     * Selects data.
-     * @param pk PK of the data to select
-     * @param asRaw Whether to return the selected data as raw
-     * @param tx Transaction
-     * @returns Selected data
-     */
-    select(pk: number, asRaw: true, tx?: Transaction): Promise<Uint8Array | null>;
-    select(pk: number, asRaw: false, tx?: Transaction): Promise<string | null>;
-    select(pk: number, asRaw?: boolean, tx?: Transaction): Promise<string | null>;
-    /**
-     * Closes the shard file.
-     */
-    close(): Promise<void>;
-}

package/dist/types/core/ShareAPI.d.ts

@@ -1,121 +0,0 @@
-import type { ShardOptions, ShardMetadata } from '../types';
-import { PageFileSystem } from './PageFileSystem';
-import { RowTableEngine } from './RowTableEngine';
-import { TextCodec } from '../utils/TextCodec';
-import { LockManager } from './transaction/LockManager';
-import { Transaction } from './transaction/Transaction';
-/**
- * Class for managing Shard files.
- */
-export declare class ShardAPI {
-    protected file: string;
-    protected fileHandle: number;
-    readonly options: Required<ShardOptions>;
-    protected readonly pfs: PageFileSystem;
-    protected readonly rowTableEngine: RowTableEngine;
-    protected readonly lockManager: LockManager;
-    protected readonly textCodec: TextCodec;
-    protected initialized: boolean;
-    private txIdCounter;
-    protected constructor(file: string, fileHandle: number, options: Required<ShardOptions>);
-    /**
-     * Verifies if the page file is a valid Shard file.
-     * The metadata page must be located at the beginning of the Shard file.
-     * @param fileHandle File handle
-     * @returns Whether the page file is a valid Shard file
-     */
-    static VerifyFormat(fileHandle: number): boolean;
-    /**
-     * Fills missing options with default values.
-     * @param options Options
-     * @returns Options filled without omissions
-     */
-    static VerboseOptions(options?: ShardOptions): Required<ShardOptions>;
-    /**
-     * Initializes the database file.
-     * The first page is initialized as the metadata page.
-     * The second page is initialized as the first data page.
-     * @param fileHandle File handle
-     */
-    static InitializeFile(fileHandle: number, options: Required<ShardOptions>): void;
-    /**
-     * Opens the database file. If the file does not exist, it initializes it.
-     * @param file Database file path
-     * @param options Options
-     * @returns Shard instance
-     */
-    static Use(file: string, options?: ShardOptions): ShardAPI;
-    /**
-     * Initializes the shard instance.
-     * Must be called before using the shard instance.
-     * If not called, the shard instance cannot be used.
-     */
-    init(): Promise<void>;
-    /**
-     * Creates a transaction.
-     * The created transaction object can be used to add or modify data.
-     * A transaction must be terminated by calling either `commit` or `rollback`.
-     * @returns Transaction object
-     */
-    createTransaction(): Transaction;
-    /**
-     * Runs a callback function within a transaction context.
-     * If no transaction is provided, a new transaction is created.
-     * The transaction is committed if the callback completes successfully,
-     * or rolled back if an error occurs.
-     * @param callback The callback function to run within the transaction context.
-     * @param tx The transaction to use. If not provided, a new transaction is created.
-     * @returns The result of the callback function.
-     */
-    private runWithDefault;
-    /**
-     * Retrieves metadata from the shard.
-     * @returns Metadata of the shard.
-     */
-    getMetadata(): Promise<ShardMetadata>;
-    /**
-     * Inserts data. Returns the PK of the added row.
-     * @param data Data to add
-     * @param incrementRowCount Whether to increment the row count to metadata
-     * @param tx Transaction
-     * @returns PK of the added data
-     */
-    insert(data: string | Uint8Array, incrementRowCount?: boolean, tx?: Transaction): Promise<number>;
-    /**
-     * Inserts multiple data in batch.
-     * If a transaction is not provided, it internally creates a single transaction to process.
-     * @param dataList Array of data to add
-     * @param incrementRowCount Whether to increment the row count to metadata
-     * @param tx Transaction
-     * @returns Array of PKs of the added data
-     */
-    insertBatch(dataList: (string | Uint8Array)[], incrementRowCount?: boolean, tx?: Transaction): Promise<number[]>;
-    /**
-     * Updates data.
-     * @param pk PK of the data to update
-     * @param data Data to update
-     * @param tx Transaction
-     */
-    update(pk: number, data: string | Uint8Array, tx?: Transaction): Promise<void>;
-    /**
-     * Deletes data.
-     * @param pk PK of the data to delete
-     * @param decrementRowCount Whether to decrement the row count to metadata
-     * @param tx Transaction
-     */
-    delete(pk: number, decrementRowCount?: boolean, tx?: Transaction): Promise<void>;
-    /**
-     * Selects data.
-     * @param pk PK of the data to select
-     * @param asRaw Whether to return the selected data as raw
-     * @param tx Transaction
-     * @returns Selected data
-     */
-    select(pk: number, asRaw: true, tx?: Transaction): Promise<Uint8Array | null>;
-    select(pk: number, asRaw: false, tx?: Transaction): Promise<string | null>;
-    select(pk: number, asRaw?: boolean, tx?: Transaction): Promise<string | null>;
-    /**
-     * Closes the shard file.
-     */
-    close(): Promise<void>;
-}