dataply 0.0.16-alpha.6 → 0.0.16-alpha.7

package/dist/cjs/index.js

@@ -5614,7 +5614,6 @@ var VirtualFileSystem = class {
     this.fileSize = import_node_fs2.default.fstatSync(fileHandle).size;
     if (walPath) {
       this.logManager = new LogManager(walPath, pageSize);
-      this.recover();
     }
   }
   /** Cache list (Page ID -> Data Buffer) */
@@ -5633,10 +5632,9 @@ var VirtualFileSystem = class {
   activeTransactions = /* @__PURE__ */ new Map();
   /**
    * Performs recovery (Redo) using WAL logs.
-   * Called in constructor, so it's a synchronous process and data is only reflected in cache.
-   * Actual disk sync and log clearing are performed during future transactions or closure.
+   * Called during initialization (DataplyAPI.init), ensuring data is fully restored before operations start.
    */
-  recover() {
+  async recover() {
     if (!this.logManager) return;
     this.logManager.open();
     const restoredPages = this.logManager.readAllSync();
@@ -5669,11 +5667,10 @@ var VirtualFileSystem = class {
         this.fileSize = endPos;
       }
     }
-    Promise.all(promises).then(() => {
-      if (this.logManager && restoredPages.size > 0) {
-        this.logManager.clear().catch(console.error);
-      }
-    });
+    await Promise.all(promises);
+    if (this.logManager && restoredPages.size > 0) {
+      await this.logManager.clear();
+    }
   }
   /**
    * Prepares the transaction for commit (Phase 1).
@@ -5940,6 +5937,13 @@ var PageFileSystem = class {
   pageFactory = new PageManagerFactory();
   vfs;
   pageManagerFactory;
+  /**
+   * Initializes the page file system.
+   * Performs VFS recovery if necessary.
+   */
+  async init() {
+    await this.vfs.recover();
+  }
   /**
    * Updates the bitmap status for a specific page.
    * @param pageId The ID of the page to update
@@ -7266,6 +7270,7 @@ var DataplyAPI = class {
     }
     await this.runWithDefault(async (tx) => {
       await this.hook.trigger("init", tx, async (tx2) => {
+        await this.pfs.init();
         await this.rowTableEngine.init();
         this.initialized = true;
         return tx2;

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

@@ -21,6 +21,11 @@ export declare class PageFileSystem {
      * @param walPath WAL 파일 경로 (기본값: null)
      */
     constructor(fileHandle: number, pageSize: number, pageCacheCapacity: number, walPath?: string | undefined | null);
+    /**
+     * Initializes the page file system.
+     * Performs VFS recovery if necessary.
+     */
+    init(): Promise<void>;
     /**
      * Updates the bitmap status for a specific page.
      * @param pageId The ID of the page to update

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

@@ -22,10 +22,9 @@ export declare class VirtualFileSystem {
     constructor(fileHandle: number, pageSize: number, pageCacheCapacity: number, walPath?: string | undefined | null);
     /**
      * Performs recovery (Redo) using WAL logs.
-     * Called in constructor, so it's a synchronous process and data is only reflected in cache.
-     * Actual disk sync and log clearing are performed during future transactions or closure.
+     * Called during initialization (DataplyAPI.init), ensuring data is fully restored before operations start.
      */
-    private recover;
+    recover(): Promise<void>;
     /**
      * Prepares the transaction for commit (Phase 1).
      * Writes dirty pages to WAL but does not update the main database file.

package/package.json

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

package/readme.md

@@ -9,14 +9,15 @@
 
 ## Key Features
 
-- **🚀 Identity-Based Access**: Specialized in storing records and managing them via auto-generated Primary Keys.
-- **⚡ High-Performance B+Tree**: Optimizes data lookup and insertion through an asynchronous B+Tree structure.
-- **🛡️ MVCC Support**: Enables non-blocking read operations and guarantees data isolation between transactions.
-- **📝 WAL (Write-Ahead Logging)**: Ensures data integrity and provides recovery capabilities in case of system failures.
-- **💼 Transaction Mechanism**: Supports Commit and Rollback for atomic operations.
-- **📦 Page-Based Storage**: Efficient page caching and disk I/O optimization through Virtual File System (VFS).
-- **📉 Bitmap Space Optimization**: Uses bitmapped management to efficiently track page usage and maximize disk space utilization.
-- **⌨️ TypeScript Support**: Provides comprehensive type definitions for all APIs.
+Dataply provides essential features for high-performance data management:
+
+- **Identity-Based Access**: Manage records through auto-generated Primary Keys for ultra-fast retrieval.
+- **High-Performance B+Tree**: Asynchronous B+Tree structure optimizes both lookups and insertions.
+- **MVCC & Isolation**: Snapshot isolation via Multi-Version Concurrency Control (MVCC) enables non-blocking reads.
+- **Reliability (WAL)**: Write-Ahead Logging (WAL) ensures data integrity and automatic crash recovery.
+- **Atomic Transactions**: Full support for ACID-compliant Commit and Rollback operations.
+- **Efficient Storage**: Fixed-size page management with VFS-based caching and Bitmap space optimization.
+- **Type Safety**: Comprehensive TypeScript definitions for a seamless developer experience.
 
 ## Installation
 
@@ -148,10 +149,10 @@ try {
 ```
 
 ### Auto-Transaction
-If you omit the `tx` argument when calling methods like `insert`, `update`, or `delete`, Dataply internally **creates an individual transaction automatically**.
+If you omit the `tx` argument, Dataply creates an internal transaction for each operation.
 
-- **Guaranteed Atomicity**: Even single operations are processed within an internal transaction, ensuring they are only finalized on success and rolled back on failure.
-- **Performance Note**: For batch processing or multiple related operations, wrapping them in a single explicit transaction is significantly faster than relying on auto-transactions due to reduced I/O overhead.
+- **Security**: Atomicity is guaranteed even for single operations.
+- **Optimization Tip**: For bulk operations, use an **explicit transaction** to significantly reduce I/O overhead and increase performance.
 
 ## API Reference
 
@@ -201,13 +202,13 @@ 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.
+Registers a transaction from a Dataply instance to the global unit.
 
 #### `async commit(): Promise<void>`
-Atomically commits all added transactions using a 2-Phase Commit (2PC) process.
+Executes an atomic commit across all registered transactions via a 2-Phase Commit (2PC) protocol.
 
 #### `async rollback(): Promise<void>`
-Rolls back all added transactions.
+Rolls back all registered transactions simultaneously.
 
 ## Extending Dataply
 
@@ -331,12 +332,14 @@ As **Dataply** is currently in Alpha, there are several limitations to keep in m
 
 ### Q: Why should I use Dataply instead of a simple JSON file?
 
-The core differences between the commonly used JSON file approach and Dataply are as follows:
+While JSON is simple, Dataply is designed for scalable and reliable data management:
 
-1.  **Memory Efficiency**: While JSON requires loading the entire file into memory, Dataply uses a **page-based storage mechanism**, allowing it to handle large-scale data reliably with a constant memory footprint.
-2.  **Superior Search Performance**: Unlike JSON, which requires a full scan (O(N)), Dataply ensures extremely fast lookups (O(log N)) regardless of data size using a **B+Tree index**.
-3.  **Data Integrity**: In contrast to JSON files that risk corruption during system failures, Dataply protects your data using **WAL (Write-Ahead Logging)** and **Transactions**.
-4.  **Concurrency Control**: Using **MVCC (Multi-Version Concurrency Control)** and **page-level locking**, Dataply delivers peak performance even in environments where multiple users are reading and writing simultaneously.
+| Feature | JSON File Approach | Dataply Record Store |
+| :--- | :--- | :--- |
+| **Memory usage** | Loads entire file into RAM | Constant memory via page-based I/O |
+| **Search speed** | Linear scan (O(N)) | B+Tree Index lookups (O(log N)) |
+| **Integrity** | High risk of corruption on crash | Protected by WAL and Transactions |
+| **Concurrency** | Single-user only | Multi-user via MVCC & Locking |
 
 ### Q: What can I build with Dataply?