dataply 0.0.8 → 0.0.9

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"));
@@ -6218,11 +6215,9 @@ var Transaction = class {
 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,
@@ -6236,14 +6231,28 @@ var DataplyAPI = class {
     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;
+  /** 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 +6289,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 +6374,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);
     });
   }
   /**
@@ -6530,7 +6538,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,12 @@
 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;
-}
 interface DataplyAPIAsyncHook {
-    init: () => Promise<void>;
+    init: (tx: Transaction, isNewlyCreated: boolean) => Promise<Transaction>;
     close: () => Promise<void>;
 }
 /**
@@ -17,17 +14,28 @@ 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>;
-    };
+    /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "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: