dataply 0.0.25-alpha.1 → 0.0.26-alpha.0

package/dist/cjs/index.js

@@ -8053,19 +8053,14 @@ var HookallSync = class _HookallSync {
 // src/core/WALManager.ts
 var import_node_fs = __toESM(require("node:fs"));
 var WALManager = class {
-  fd = null;
-  walFilePath;
-  pageSize;
-  entrySize;
-  buffer;
-  view;
-  totalWrittenPages = 0;
   /**
    * Constructor
    * @param walFilePath WAL file path
    * @param pageSize Page size
+   * @param logger Logger instance
    */
-  constructor(walFilePath, pageSize) {
+  constructor(walFilePath, pageSize, logger) {
+    this.logger = logger;
     if ((pageSize & pageSize - 1) !== 0) {
       throw new Error("Page size must be a power of 2");
     }
@@ -8075,6 +8070,13 @@ var WALManager = class {
     this.buffer = new Uint8Array(this.entrySize);
     this.view = new DataView(this.buffer.buffer);
   }
+  fd = null;
+  walFilePath;
+  pageSize;
+  entrySize;
+  buffer;
+  view;
+  totalWrittenPages = 0;
   /**
    * Opens the log file.
    */
@@ -8101,11 +8103,11 @@ var WALManager = class {
       try {
         const manager = new PageManagerFactory().getManager(data);
         if (!manager.verifyChecksum(data)) {
-          console.warn(`[WALManager] Checksum verification failed for PageID ${pageId} during recovery. Ignoring changes.`);
+          this.logger.warn(`Checksum verification failed for PageID ${pageId} during recovery. Ignoring changes.`);
           continue;
         }
       } catch (e) {
-        console.warn(`[WALManager] Failed to verify checksum for PageID ${pageId} during recovery: ${e}. Ignoring changes.`);
+        this.logger.warn(`Failed to verify checksum for PageID ${pageId} during recovery: ${e}. Ignoring changes.`);
         continue;
       }
       promises.push(writePage(pageId, data));
@@ -8422,13 +8424,14 @@ var PageFileSystem = class {
    * @param pageCacheCapacity 페이지 캐시 크기
    * @param options 데이터플라이 옵션
    */
-  constructor(fileHandle, pageSize, pageCacheCapacity, options) {
+  constructor(fileHandle, pageSize, pageCacheCapacity, options, logger) {
     this.fileHandle = fileHandle;
     this.pageSize = pageSize;
     this.pageCacheCapacity = pageCacheCapacity;
     this.options = options;
+    this.logger = logger;
     const walPath = options.wal;
-    this.walManager = walPath ? new WALManager(walPath, pageSize) : null;
+    this.walManager = walPath ? new WALManager(walPath, pageSize, this.logger) : null;
     this.pageManagerFactory = new PageManagerFactory();
     this.pageStrategy = new PageMVCCStrategy(fileHandle, pageSize, pageCacheCapacity);
   }
@@ -8460,7 +8463,9 @@ var PageFileSystem = class {
    * Performs WAL recovery if necessary.
    */
   async init() {
+    this.logger.info("Initializing");
     if (this.walManager) {
+      this.logger.debug("WALManager found, starting recovery");
       await this.walManager.recover(async (pageId, data) => {
         await this.pageStrategy.write(pageId, data);
       });
@@ -8632,6 +8637,7 @@ var PageFileSystem = class {
    * @returns Created or reused page ID
    */
   async appendNewPage(pageType = PageManager.CONSTANT.PAGE_TYPE_EMPTY, tx) {
+    this.logger.debug(`Appending new page of type ${pageType}`);
     await tx.__acquireWriteLock(0);
     const metadata = await this.getMetadata(tx);
     const metadataManager = this.pageFactory.getManager(metadata);
@@ -8735,6 +8741,7 @@ var PageFileSystem = class {
    * @param tx Transaction
    */
   async freeChain(startPageId, tx) {
+    this.logger.debug(`Freeing chain starting at page ${startPageId}`);
     let currentPageId = startPageId;
     const visited = /* @__PURE__ */ new Set();
     while (currentPageId !== -1 && currentPageId !== 0) {
@@ -8774,6 +8781,7 @@ var PageFileSystem = class {
    */
   async commitToWAL(dirtyPages) {
     if (this.walManager) {
+      this.logger.debug(`Committing ${dirtyPages.size} pages to WAL`);
       await this.walManager.prepareCommit(dirtyPages);
       await this.walManager.finalizeCommit(true);
     }
@@ -8785,6 +8793,7 @@ var PageFileSystem = class {
    * 3. WAL 로그 파일 비우기 (Clear/Truncate)
    */
   async checkpoint() {
+    this.logger.info("Starting checkpoint");
     await this.runGlobalLock(async () => {
       await this.pageStrategy.flush();
       await this.pageStrategy.sync();
@@ -8797,6 +8806,7 @@ var PageFileSystem = class {
    * Closes the page file system.
    */
   async close() {
+    this.logger.info("Closing");
     await this.checkpoint();
     if (this.walManager) {
       this.walManager.close();
@@ -9038,10 +9048,11 @@ var KeyManager = class {
 
 // src/core/RowTableEngine.ts
 var RowTableEngine = class {
-  constructor(pfs, txContext, options) {
+  constructor(pfs, txContext, options, logger) {
     this.pfs = pfs;
     this.txContext = txContext;
     this.options = options;
+    this.logger = logger;
     this.factory = new PageManagerFactory();
     this.metadataPageManager = this.factory.getManagerFromType(MetadataPageManager.CONSTANT.PAGE_TYPE_METADATA);
     this.dataPageManager = this.factory.getManagerFromType(DataPageManager.CONSTANT.PAGE_TYPE_DATA);
@@ -9110,6 +9121,7 @@ var RowTableEngine = class {
    */
   async init() {
     if (!this.initialized) {
+      this.logger.info("Initializing B+ Tree");
       await this.bptree.init();
       this.initialized = true;
     }
@@ -9157,6 +9169,7 @@ var RowTableEngine = class {
    * @returns Metadata
    */
   async getMetadata(tx) {
+    this.logger.debug("Getting metadata");
     if (!this.initialized) {
       throw new Error("RowTableEngine instance is not initialized");
     }
@@ -9182,6 +9195,7 @@ var RowTableEngine = class {
    * @returns Array of PKs of the inserted data
    */
   async insert(dataList, incrementRowCount, overflowForcly, tx) {
+    this.logger.debug(`Inserting ${dataList.length} rows (overflowForcly: ${overflowForcly})`);
     if (dataList.length === 0) {
       return [];
     }
@@ -9283,6 +9297,7 @@ var RowTableEngine = class {
    * @param tx Transaction
    */
   async update(pk, data, tx) {
+    this.logger.debug(`Updating row with PK: ${pk}`);
     await tx.__acquireWriteLock(0);
     const rid = await this.getRidByPK(pk, tx);
     if (rid === null) {
@@ -9368,6 +9383,7 @@ var RowTableEngine = class {
    * @param tx Transaction
    */
   async delete(pk, decrementRowCount, tx) {
+    this.logger.debug(`Deleting row with PK: ${pk}`);
     await tx.__acquireWriteLock(0);
     const rid = await this.getRidByPK(pk, tx);
     if (rid === null) {
@@ -9427,6 +9443,7 @@ var RowTableEngine = class {
    * @returns Raw data of the row
    */
   async selectByPK(pk, tx) {
+    this.logger.debug(`Selecting row by PK: ${pk}`);
     const rid = await this.getRidByPK(pk, tx);
     if (rid === null) {
       return null;
@@ -9441,6 +9458,7 @@ var RowTableEngine = class {
    * @returns Array of raw data of the rows in the same order as input PKs
    */
   async selectMany(pks, tx) {
+    this.logger.debug(`Selecting many rows (${pks.length} PKs)`);
     const collections = await this.collectItemsByPage(pks, tx);
     return this.fetchRowsByRids(collections, pks.length, tx);
   }
@@ -9828,26 +9846,80 @@ var TransactionContext = class {
   }
 };
 
+// src/core/Logger.ts
+var Colors = {
+  reset: "\x1B[0m",
+  debug: "\x1B[36m",
+  // Cyan
+  info: "\x1B[32m",
+  // Green
+  warn: "\x1B[33m",
+  // Yellow
+  error: "\x1B[31m",
+  // Red
+  white: "\x1B[37m",
+  // White
+  grey: "\x1B[90m"
+};
+var Logger = class {
+  level;
+  moduleName;
+  constructor(moduleName, level = 2 /* Info */) {
+    this.moduleName = moduleName;
+    this.level = level;
+  }
+  setLevel(level) {
+    this.level = level;
+  }
+  shouldLog(level) {
+    if (this.level === 0 /* None */) return false;
+    return level >= this.level;
+  }
+  debug(message, ...args) {
+    if (this.shouldLog(1 /* Debug */)) {
+      console.debug(`${Colors.debug}[DEBUG] [${this.moduleName}]${Colors.reset} ${Colors.white}${message}${Colors.reset}`, ...args);
+    }
+  }
+  info(message, ...args) {
+    if (this.shouldLog(2 /* Info */)) {
+      console.info(`${Colors.info}[INFO] [${this.moduleName}]${Colors.reset} ${Colors.white}${message}${Colors.reset}`, ...args);
+    }
+  }
+  warn(message, ...args) {
+    if (this.shouldLog(3 /* Warning */)) {
+      console.warn(`${Colors.warn}[WARN] [${this.moduleName}]${Colors.reset} ${Colors.white}${message}${Colors.reset}`, ...args);
+    }
+  }
+  error(message, ...args) {
+    if (this.shouldLog(4 /* Error */)) {
+      console.error(`${Colors.error}[ERROR] [${this.moduleName}]${Colors.reset} ${Colors.white}${message}${Colors.reset}`, ...args);
+    }
+  }
+};
+
 // src/core/DataplyAPI.ts
 var DataplyAPI = class {
   constructor(file, options) {
     this.file = file;
     this.hook = useHookall(this);
     this.options = this.verboseOptions(options);
+    this.logger = new Logger("DataplyAPI", this.options.logLevel);
     this.isNewlyCreated = !import_node_fs3.default.existsSync(file);
     this.fileHandle = this.createOrOpen(file, this.options);
     this.pfs = new PageFileSystem(
       this.fileHandle,
       this.options.pageSize,
       this.options.pageCacheCapacity,
-      this.options
+      this.options,
+      this.logger
     );
     this.textCodec = new TextCodec();
     this.txContext = new TransactionContext();
     this.lockManager = new LockManager();
-    this.rowTableEngine = new RowTableEngine(this.pfs, this.txContext, this.options);
+    this.rowTableEngine = new RowTableEngine(this.pfs, this.txContext, this.options, this.logger);
     this.initialized = false;
     this.txIdCounter = 0;
+    this.logger.debug(`DataplyAPI instance created with file: ${file}`);
   }
   /**
    * These are not the same options that were used when the database was created.
@@ -9869,6 +9941,8 @@ var DataplyAPI = class {
   txContext;
   /** Hook */
   hook;
+  /** Logger */
+  logger;
   /** Whether the database was initialized via `init()` */
   initialized;
   /** Whether the database was created this time. */
@@ -9883,6 +9957,7 @@ var DataplyAPI = class {
    * @returns Whether the page file is a valid Dataply file
    */
   verifyFormat(fileHandle) {
+    this.logger.debug(`Verifying format for file handle: ${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);
@@ -9902,7 +9977,8 @@ var DataplyAPI = class {
       pageCacheCapacity: 1e4,
       pagePreallocationCount: 1e3,
       wal: null,
-      walCheckpointThreshold: 1e3
+      walCheckpointThreshold: 1e3,
+      logLevel: 2 /* Info */
     }, options);
   }
   /**
@@ -9913,6 +9989,7 @@ var DataplyAPI = class {
    * @param fileHandle File handle
    */
   initializeFile(file, fileHandle, options) {
+    this.logger.info(`Initializing new dataply file: ${file}`);
     const metadataPageManager = new MetadataPageManager();
     const bitmapPageManager = new BitmapPageManager();
     const dataPageManager = new DataPageManager();
@@ -9962,6 +10039,7 @@ var DataplyAPI = class {
    * @returns File handle
    */
   createOrOpen(file, options) {
+    this.logger.info(`Opening dataply file: ${file}`);
     let fileHandle;
     if (options.pageCacheCapacity < 100) {
       throw new Error("Page cache capacity must be at least 100");
@@ -9997,6 +10075,7 @@ var DataplyAPI = class {
    * If not called, the dataply instance cannot be used.
    */
   async init() {
+    this.logger.info("Initializing DataplyAPI");
     if (this.initialized) {
       return;
     }
@@ -10016,6 +10095,7 @@ var DataplyAPI = class {
    * @returns Transaction object
    */
   createTransaction() {
+    this.logger.debug(`Creating transaction: ${this.txIdCounter + 1}`);
     return new Transaction(
       ++this.txIdCounter,
       this.txContext,
@@ -10040,6 +10120,7 @@ var DataplyAPI = class {
    * @returns A release function
    */
   acquireWriteLock() {
+    this.logger.debug("Acquiring write lock");
     const previous = this.writeQueue;
     let release;
     this.writeQueue = new Promise((resolve) => {
@@ -10057,6 +10138,7 @@ var DataplyAPI = class {
    * @returns The result of the callback.
    */
   async runWithDefaultWrite(callback, tx) {
+    this.logger.debug("Running with default write transaction");
     if (!tx) {
       const release = await this.acquireWriteLock();
       const internalTx = this.createTransaction();
@@ -10080,6 +10162,7 @@ var DataplyAPI = class {
     return result;
   }
   async runWithDefault(callback, tx) {
+    this.logger.debug("Running with default transaction");
     const isInternalTx = !tx;
     if (!tx) {
       tx = this.createTransaction();
@@ -10107,6 +10190,7 @@ var DataplyAPI = class {
    * @returns An AsyncGenerator that yields values from the callback.
    */
   async *streamWithDefault(callback, tx) {
+    this.logger.debug("Streaming with default transaction");
     const isInternalTx = !tx;
     if (!tx) {
       tx = this.createTransaction();
@@ -10134,6 +10218,7 @@ var DataplyAPI = class {
    * @returns Metadata of the dataply.
    */
   async getMetadata(tx) {
+    this.logger.debug("Getting metadata");
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10147,6 +10232,7 @@ var DataplyAPI = class {
    * @returns PK of the added data
    */
   async insert(data, incrementRowCount, tx) {
+    this.logger.debug("Inserting data");
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10167,6 +10253,7 @@ var DataplyAPI = class {
    * @returns PK of the added data
    */
   async insertAsOverflow(data, incrementRowCount, tx) {
+    this.logger.debug("Inserting data as overflow");
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10188,6 +10275,7 @@ var DataplyAPI = class {
    * @returns Array of PKs of the added data
    */
   async insertBatch(dataList, incrementRowCount, tx) {
+    this.logger.debug(`Inserting batch data: ${dataList.length} items`);
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10206,6 +10294,7 @@ var DataplyAPI = class {
    * @param tx Transaction
    */
   async update(pk, data, tx) {
+    this.logger.debug(`Updating data for PK: ${pk}`);
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10223,6 +10312,7 @@ var DataplyAPI = class {
    * @param tx Transaction
    */
   async delete(pk, decrementRowCount, tx) {
+    this.logger.debug(`Deleting data for PK: ${pk}`);
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10232,6 +10322,7 @@ var DataplyAPI = class {
     }, tx);
   }
   async select(pk, asRaw = false, tx) {
+    this.logger.debug(`Selecting data for PK: ${pk}`);
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10243,6 +10334,7 @@ var DataplyAPI = class {
     }, tx);
   }
   async selectMany(pks, asRaw = false, tx) {
+    this.logger.debug(`Selecting many data: ${pks.length} keys`);
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }
@@ -10259,6 +10351,7 @@ var DataplyAPI = class {
    * Closes the dataply file.
    */
   async close() {
+    this.logger.info("Closing DataplyAPI");
     if (!this.initialized) {
       throw new Error("Dataply instance is not initialized");
     }

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

@@ -1,4 +1,4 @@
-import type { DataplyOptions, DataplyMetadata } from '../types';
+import { type DataplyOptions, type DataplyMetadata } from '../types';
 import { type IHookall } from 'hookall';
 import { PageFileSystem } from './PageFileSystem';
 import { RowTableEngine } from './RowTableEngine';
@@ -6,6 +6,7 @@ import { TextCodec } from '../utils/TextCodec';
 import { LockManager } from './transaction/LockManager';
 import { Transaction } from './transaction/Transaction';
 import { TransactionContext } from './transaction/TxContext';
+import { Logger } from './Logger';
 interface DataplyAPIAsyncHook {
     init: (tx: Transaction, isNewlyCreated: boolean) => Promise<Transaction>;
     close: () => Promise<void>;
@@ -35,6 +36,8 @@ export declare class DataplyAPI {
     protected readonly txContext: TransactionContext;
     /** Hook */
     protected readonly hook: IHookall<DataplyAPIAsyncHook>;
+    /** Logger */
+    protected readonly logger: Logger;
     /** Whether the database was initialized via `init()` */
     protected initialized: boolean;
     /** Whether the database was created this time. */

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

@@ -0,0 +1,12 @@
+import { LogLevel } from '../types';
+export declare class Logger {
+    private level;
+    private moduleName;
+    constructor(moduleName: string, level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    private shouldLog;
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}

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

@@ -3,6 +3,7 @@ import type { Transaction } from './transaction/Transaction';
 import { PageManagerFactory } from './Page';
 import { WALManager } from './WALManager';
 import { PageMVCCStrategy } from './PageMVCCStrategy';
+import { Logger } from './Logger';
 /**
  * Page File System class.
  * mvcc-api 기반으로 페이지 관리를 수행합니다.
@@ -12,6 +13,7 @@ export declare class PageFileSystem {
     readonly pageSize: number;
     readonly pageCacheCapacity: number;
     readonly options: Required<DataplyOptions>;
+    protected readonly logger: Logger;
     protected readonly pageFactory: PageManagerFactory;
     protected readonly walManager: WALManager | null;
     protected readonly pageManagerFactory: PageManagerFactory;
@@ -22,7 +24,7 @@ export declare class PageFileSystem {
      * @param pageCacheCapacity 페이지 캐시 크기
      * @param options 데이터플라이 옵션
      */
-    constructor(fileHandle: number, pageSize: number, pageCacheCapacity: number, options: Required<DataplyOptions>);
+    constructor(fileHandle: number, pageSize: number, pageCacheCapacity: number, options: Required<DataplyOptions>, logger: Logger);
     /**
      * 글로벌 동기화 범위 내에서 작업을 실행합니다.
      * @param task 수행할 비동기 작업

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

@@ -7,10 +7,12 @@ import { KeyManager } from './KeyManager';
 import { PageManagerFactory } from './Page';
 import { Transaction } from './transaction/Transaction';
 import { TransactionContext } from './transaction/TxContext';
+import { Logger } from './Logger';
 export declare class RowTableEngine {
     protected readonly pfs: PageFileSystem;
     protected readonly txContext: TransactionContext;
     protected readonly options: Required<DataplyOptions>;
+    protected readonly logger: Logger;
     protected readonly bptree: BPTreeAsync<number, number>;
     protected readonly strategy: RowIdentifierStrategy;
     protected readonly order: number;
@@ -24,7 +26,7 @@ export declare class RowTableEngine {
     private readonly ridBuffer;
     private readonly pageIdBuffer;
     private initialized;
-    constructor(pfs: PageFileSystem, txContext: TransactionContext, options: Required<DataplyOptions>);
+    constructor(pfs: PageFileSystem, txContext: TransactionContext, options: Required<DataplyOptions>, logger: Logger);
     /**
      * Retrieves the BPTree transaction associated with the given transaction.
      * If it doesn't exist, it creates a new one and registers commit/rollback hooks.

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

@@ -1,9 +1,11 @@
+import { Logger } from './Logger';
 /**
  * WAL (Write-Ahead Logging) Manager class.
  * Records changes to a log file and manages them to ensure atomicity of the database.
  * Handles commit phases and crash recovery.
  */
 export declare class WALManager {
+    private readonly logger;
     private fd;
     private readonly walFilePath;
     private readonly pageSize;
@@ -15,8 +17,9 @@ export declare class WALManager {
      * Constructor
      * @param walFilePath WAL file path
      * @param pageSize Page size
+     * @param logger Logger instance
      */
-    constructor(walFilePath: string, pageSize: number);
+    constructor(walFilePath: string, pageSize: number, logger: Logger);
     /**
      * Opens the log file.
      */

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

@@ -1,3 +1,25 @@
+export declare enum LogLevel {
+    /**
+     * No logging.
+     */
+    None = 0,
+    /**
+     * Debug logging.
+     */
+    Debug = 1,
+    /**
+     * Info logging.
+    */
+    Info = 2,
+    /**
+      * Warning logging.
+    */
+    Warning = 3,
+    /**
+     * Error logging.
+     */
+    Error = 4
+}
 export interface DataplyOptions {
     /**
      * The size of a page in bytes.
@@ -10,6 +32,8 @@ export interface DataplyOptions {
     wal?: string | undefined | null;
     /**
      * The maximum number of pages to cache in memory.
+     * This value **DOES NOT** guarantee that the application's memory usage will be exactly `pageSize * pageCacheCapacity`.
+     * This value is only a recommendation for optimizing memory usage.
      * Default is 10000.
      */
     pageCacheCapacity?: number;
@@ -23,6 +47,11 @@ export interface DataplyOptions {
      * Default is 1000.
      */
     walCheckpointThreshold?: number;
+    /**
+     * The log level.
+     * Default is `LogLevel.Info`.
+     */
+    logLevel?: LogLevel;
 }
 export interface DataplyMetadata {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataply",
-  "version": "0.0.25-alpha.1",
+  "version": "0.0.26-alpha.0",
   "description": "A lightweight storage engine for Node.js with support for MVCC, WAL.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
@@ -38,9 +38,9 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.0.3",
-    "esbuild": "^0.27.2",
-    "jest": "^30.2.0",
+    "@types/node": "^25.4.0",
+    "esbuild": "^0.27.3",
+    "jest": "^30.3.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.9.3"
   },