dataply 0.0.8 → 0.0.10

package/dist/cjs/index.js

@@ -4626,9 +4626,6 @@ var HookallSync = class _HookallSync {
     return value;
   }
 };
-function useHookallSync(target = HookallSync.Global) {
-  return new HookallSync(target);
-}
 
 // src/core/VirtualFileSystem.ts
 var import_node_fs2 = __toESM(require("node:fs"));
@@ -5425,24 +5422,13 @@ var TextCodec = class _TextCodec {
   }
 };
 
-// src/core/transaction/TxContext.ts
-var import_node_async_hooks = require("node:async_hooks");
-var storage = new import_node_async_hooks.AsyncLocalStorage();
-var TxContext = {
-  run: (tx, callback) => {
-    return storage.run(tx, callback);
-  },
-  get: () => {
-    return storage.getStore();
-  }
-};
-
 // src/core/RowIndexStrategy.ts
 var RowIdentifierStrategy = class extends SerializeStrategyAsync {
-  constructor(order, pfs) {
+  constructor(order, pfs, txContext) {
     super(order);
     this.order = order;
     this.pfs = pfs;
+    this.txContext = txContext;
     this.factory = new PageManagerFactory();
     this.indexPageManger = this.factory.getManagerFromType(PageManager.CONSTANT.PAGE_TYPE_INDEX);
     this.codec = new TextCodec();
@@ -5452,12 +5438,12 @@ var RowIdentifierStrategy = class extends SerializeStrategyAsync {
   indexPageManger;
   codec;
   async id(isLeaf) {
-    const tx = TxContext.get();
+    const tx = this.txContext.get();
     const pageId = await this.pfs.appendNewPage(PageManager.CONSTANT.PAGE_TYPE_INDEX, tx);
     return pageId.toString();
   }
   async read(id) {
-    const tx = TxContext.get();
+    const tx = this.txContext.get();
     const pageId = +id;
     const page = await this.pfs.get(pageId, tx);
     const indexId = this.indexPageManger.getIndexId(page);
@@ -5489,7 +5475,7 @@ var RowIdentifierStrategy = class extends SerializeStrategyAsync {
     return res;
   }
   async write(id, node) {
-    const tx = TxContext.get();
+    const tx = this.txContext.get();
     const pageId = +id;
     const page = await this.pfs.get(pageId, tx);
     if (node.leaf) {
@@ -5524,7 +5510,7 @@ var RowIdentifierStrategy = class extends SerializeStrategyAsync {
     await this.pfs.setPage(pageId, page, tx);
   }
   async delete(id) {
-    const tx = TxContext.get();
+    const tx = this.txContext.get();
     const manager = this.factory.getManagerFromType(PageManager.CONSTANT.PAGE_TYPE_INDEX);
     let pageId = +id;
     while (true) {
@@ -5538,7 +5524,7 @@ var RowIdentifierStrategy = class extends SerializeStrategyAsync {
     }
   }
   async readHead() {
-    const tx = TxContext.get();
+    const tx = this.txContext.get();
     const metadataPage = await this.pfs.getMetadata(tx);
     const manager = this.factory.getManager(metadataPage);
     const rootIndexPageId = manager.getRootIndexPageId(metadataPage);
@@ -5552,7 +5538,7 @@ var RowIdentifierStrategy = class extends SerializeStrategyAsync {
     };
   }
   async writeHead(head) {
-    const tx = TxContext.get();
+    const tx = this.txContext.get();
     const { root, order } = head;
     if (root === null) {
       throw new Error("");
@@ -5620,8 +5606,9 @@ var KeyManager = class {
 
 // src/core/RowTableEngine.ts
 var RowTableEngine = class {
-  constructor(pfs, options) {
+  constructor(pfs, txContext, options) {
     this.pfs = pfs;
+    this.txContext = txContext;
     this.options = options;
     this.factory = new PageManagerFactory();
     this.metadataPageManager = this.factory.getManagerFromType(MetadataPageManager.CONSTANT.PAGE_TYPE_METADATA);
@@ -5634,7 +5621,7 @@ var RowTableEngine = class {
     this.maxBodySize = this.pfs.pageSize - DataPageManager.CONSTANT.SIZE_PAGE_HEADER;
     this.order = this.getOptimalOrder(pfs.pageSize, IndexPageManager.CONSTANT.SIZE_KEY, IndexPageManager.CONSTANT.SIZE_VALUE);
     this.bptree = new BPTreeAsync(
-      new RowIdentifierStrategy(this.order, pfs),
+      new RowIdentifierStrategy(this.order, pfs, txContext),
       new NumericComparator(),
       {
         capacity: this.options.pageCacheCapacity
@@ -6064,7 +6051,8 @@ var Transaction = class {
    * @param vfs VFS instance
    * @param lockManager LockManager instance
    */
-  constructor(id, vfs, lockManager) {
+  constructor(id, context, vfs, lockManager) {
+    this.context = context;
     this.vfs = vfs;
     this.lockManager = lockManager;
     this.id = id;
@@ -6173,7 +6161,7 @@ var Transaction = class {
   async commit() {
     await this.vfs.prepareCommit(this);
     await this.vfs.finalizeCommit(this);
-    await TxContext.run(this, async () => {
+    await this.context.run(this, async () => {
       for (const hook of this.commitHooks) {
         await hook();
       }
@@ -6214,15 +6202,25 @@ var Transaction = class {
   }
 };
 
+// src/core/transaction/TxContext.ts
+var import_node_async_hooks = require("node:async_hooks");
+var TransactionContext = class {
+  storage = new import_node_async_hooks.AsyncLocalStorage();
+  run(tx, callback) {
+    return this.storage.run(tx, callback);
+  }
+  get() {
+    return this.storage.getStore();
+  }
+};
+
 // src/core/DataplyAPI.ts
 var DataplyAPI = class {
   constructor(file, options) {
     this.file = file;
-    this.hook = {
-      sync: useHookallSync(this),
-      async: useHookall(this)
-    };
+    this.hook = useHookall(this);
     this.options = this.verboseOptions(options);
+    this.isNewlyCreated = !import_node_fs3.default.existsSync(file);
     this.fileHandle = this.createOrOpen(file, this.options);
     this.pfs = new PageFileSystem(
       this.fileHandle,
@@ -6231,19 +6229,36 @@ var DataplyAPI = class {
       this.options.wal
     );
     this.textCodec = new TextCodec();
+    this.txContext = new TransactionContext();
     this.lockManager = new LockManager();
-    this.rowTableEngine = new RowTableEngine(this.pfs, this.options);
+    this.rowTableEngine = new RowTableEngine(this.pfs, this.txContext, this.options);
     this.initialized = false;
     this.txIdCounter = 0;
   }
+  /**
+   * These are not the same options that were used when the database was created.
+   * They are simply the options received when the instance was created.
+   * If you want to retrieve the options used during database creation, use `getMetadata()` instead.
+   */
   options;
+  /** File handle. Database file descriptor */
   fileHandle;
+  /** Page file system. Used for managing pages. If you know what it is, you can skip this. */
   pfs;
+  /** Row table engine. Used for managing rows. If you know what it is, you can skip this. */
   rowTableEngine;
+  /** Lock manager. Used for managing transactions */
   lockManager;
+  /** Text codec. Used for encoding and decoding text data */
   textCodec;
+  /** Transaction context */
+  txContext;
+  /** Hook */
   hook;
+  /** Whether the database was initialized via `init()` */
   initialized;
+  /** Whether the database was created this time. */
+  isNewlyCreated;
   txIdCounter;
   /**
    * Verifies if the page file is a valid Dataply file.
@@ -6280,47 +6295,45 @@ var DataplyAPI = class {
    * @param fileHandle File handle
    */
   initializeFile(file, fileHandle, options) {
-    this.hook.sync.trigger("create", void 0, () => {
-      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
-      ]));
-    }, file, 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
+    ]));
   }
   /**
    * Opens the database file. If the file does not exist, it initializes it.
@@ -6367,11 +6380,12 @@ var DataplyAPI = class {
     if (this.initialized) {
       return;
     }
-    await this.runWithDefault(() => {
-      return this.hook.async.trigger("init", void 0, async () => {
+    await this.runWithDefault(async (tx) => {
+      await this.hook.trigger("init", tx, async (tx2) => {
         await this.rowTableEngine.init();
         this.initialized = true;
-      });
+        return tx2;
+      }, this.isNewlyCreated);
     });
   }
   /**
@@ -6381,7 +6395,12 @@ var DataplyAPI = class {
    * @returns Transaction object
    */
   createTransaction() {
-    return new Transaction(++this.txIdCounter, this.pfs.vfsInstance, this.lockManager);
+    return new Transaction(
+      ++this.txIdCounter,
+      this.txContext,
+      this.pfs.vfsInstance,
+      this.lockManager
+    );
   }
   /**
    * Runs a callback function within a transaction context.
@@ -6397,7 +6416,7 @@ var DataplyAPI = class {
     if (!tx) {
       tx = this.createTransaction();
     }
-    const [error, result] = await catchPromise(TxContext.run(tx, () => callback(tx)));
+    const [error, result] = await catchPromise(this.txContext.run(tx, () => callback(tx)));
     if (error) {
       if (isInternalTx) {
         await tx.rollback();
@@ -6530,7 +6549,7 @@ var DataplyAPI = class {
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
-    return this.hook.async.trigger("close", void 0, async () => {
+    return this.hook.trigger("close", void 0, async () => {
       await this.pfs.close();
       import_node_fs3.default.closeSync(this.fileHandle);
     });

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

@@ -1,15 +1,13 @@
 import type { DataplyOptions, DataplyMetadata } from '../types';
-import { type IHookall, type IHookallSync } from 'hookall';
+import { type IHookall } 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: (_: void, file: string, fileHandle: number, options: Required<DataplyOptions>) => void;
-}
+import { TransactionContext } from './transaction/TxContext';
 interface DataplyAPIAsyncHook {
-    init: () => Promise<void>;
+    init: (tx: Transaction, isNewlyCreated: boolean) => Promise<Transaction>;
     close: () => Promise<void>;
 }
 /**
@@ -17,17 +15,30 @@ interface DataplyAPIAsyncHook {
  */
 export declare class DataplyAPI {
     protected readonly file: string;
+    /**
+     * These are not the same options that were used when the database was created.
+     * They are simply the options received when the instance was created.
+     * If you want to retrieve the options used during database creation, use `getMetadata()` instead.
+     */
     readonly options: Required<DataplyOptions>;
+    /** File handle. Database file descriptor */
     protected readonly fileHandle: number;
+    /** Page file system. Used for managing pages. If you know what it is, you can skip this. */
     protected readonly pfs: PageFileSystem;
+    /** Row table engine. Used for managing rows. If you know what it is, you can skip this. */
     protected readonly rowTableEngine: RowTableEngine;
+    /** Lock manager. Used for managing transactions */
     protected readonly lockManager: LockManager;
+    /** Text codec. Used for encoding and decoding text data */
     protected readonly textCodec: TextCodec;
-    protected readonly hook: {
-        sync: IHookallSync<DataplyAPISyncHook>;
-        async: IHookall<DataplyAPIAsyncHook>;
-    };
+    /** Transaction context */
+    protected readonly txContext: TransactionContext;
+    /** Hook */
+    protected readonly hook: IHookall<DataplyAPIAsyncHook>;
+    /** Whether the database was initialized via `init()` */
     protected initialized: boolean;
+    /** Whether the database was created this time. */
+    private readonly isNewlyCreated;
     private txIdCounter;
     constructor(file: string, options: DataplyOptions);
     /**

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

@@ -3,14 +3,16 @@ import { SerializeStrategyAsync } from 'serializable-bptree';
 import { PageFileSystem } from './PageFileSystem';
 import { IndexPageManager, PageManagerFactory } from './Page';
 import { TextCodec } from '../utils/TextCodec';
+import { TransactionContext } from './transaction/TxContext';
 export declare class RowIdentifierStrategy extends SerializeStrategyAsync<number, number> {
     readonly order: number;
     protected readonly pfs: PageFileSystem;
+    protected readonly txContext: TransactionContext;
     protected rootPageId: number;
     protected factory: PageManagerFactory;
     protected indexPageManger: IndexPageManager;
     protected codec: TextCodec;
-    constructor(order: number, pfs: PageFileSystem);
+    constructor(order: number, pfs: PageFileSystem, txContext: TransactionContext);
     id(isLeaf: boolean): Promise<string>;
     read(id: string): Promise<BPTreeNode<number, number>>;
     write(id: string, node: BPTreeNode<number, number>): Promise<void>;

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

@@ -5,8 +5,10 @@ import { Row } from './Row';
 import { KeyManager } from './KeyManager';
 import { PageManagerFactory } from './Page';
 import { Transaction } from './transaction/Transaction';
+import { TransactionContext } from './transaction/TxContext';
 export declare class RowTableEngine {
     protected readonly pfs: PageFileSystem;
+    protected readonly txContext: TransactionContext;
     protected readonly options: Required<DataplyOptions>;
     protected readonly bptree: BPTreeAsync<number, number>;
     protected readonly order: number;
@@ -20,7 +22,7 @@ export declare class RowTableEngine {
     private readonly ridBuffer;
     private readonly pageIdBuffer;
     private initialized;
-    constructor(pfs: PageFileSystem, options: Required<DataplyOptions>);
+    constructor(pfs: PageFileSystem, txContext: TransactionContext, options: Required<DataplyOptions>);
     /**
      * Initializes the B+ Tree.
      */

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

@@ -1,12 +1,14 @@
 import { LockManager } from './LockManager';
 import { VirtualFileSystem } from '../VirtualFileSystem';
+import { TransactionContext } from './TxContext';
 /**
  * Transaction class.
  * Manages the lifecycle and resources of a database transaction.
  */
 export declare class Transaction {
-    private vfs;
-    private lockManager;
+    readonly context: TransactionContext;
+    private readonly vfs;
+    private readonly lockManager;
     /** Transaction ID */
     readonly id: number;
     /** List of held lock IDs (LOCK_ID) */
@@ -26,7 +28,7 @@ export declare class Transaction {
      * @param vfs VFS instance
      * @param lockManager LockManager instance
      */
-    constructor(id: number, vfs: VirtualFileSystem, lockManager: LockManager);
+    constructor(id: number, context: TransactionContext, vfs: VirtualFileSystem, lockManager: LockManager);
     /**
      * Registers a commit hook.
      * @param hook Function to execute

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

@@ -1,5 +1,6 @@
 import { Transaction } from './Transaction';
-export declare const TxContext: {
-    run: <T>(tx: Transaction, callback: () => T) => T;
-    get: () => Transaction | undefined;
-};
+export declare class TransactionContext {
+    private readonly storage;
+    run<T>(tx: Transaction, callback: () => T): T;
+    get(): Transaction | undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "A lightweight storage engine for Node.js with support for MVCC, WAL.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",

package/readme.md

@@ -178,6 +178,8 @@ Rolls back all added transactions.
 
 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.
 
+For a detailed guide and examples on how to extend Dataply using Hooks, see [Extending Dataply Guide](docs/extension.md).
+
 ### Using DataplyAPI
 
 ```typescript
@@ -222,7 +224,7 @@ graph TD
 - **Fixed-size Pages**: All data is managed in fixed-size units (default 8KB) called pages.
 - **VFS Cache**: Minimizes disk I/O by caching frequently accessed pages in memory.
 - **Dirty Page Tracking**: Tracks modified pages (Dirty) to synchronize them with disk efficiently only at the time of commit.
-- **Detailed Structure**: For technical details on the physical layout, see [structure.md](structure.md).
+- **Detailed Structure**: For technical details on the physical layout, see [structure.md](docs/structure.md).
 
 #### Page & Row Layout
 Dataply uses a **Slotted Page** architecture to manage records efficiently: