dataply 0.0.1

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

@@ -0,0 +1,98 @@
+import { IndexPage, type MetadataPage } from '../types';
+import { PageManagerFactory } from './Page';
+import { VirtualFileSystem } from './VirtualFileSystem';
+import type { Transaction } from './transaction/Transaction';
+/**
+ * Page File System class.
+ * Manages pages using VFS and page factory.
+ */
+export declare class PageFileSystem {
+    readonly fileHandle: number;
+    readonly pageSize: number;
+    readonly pageCacheCapacity: number;
+    readonly walPath?: string | undefined | null;
+    protected readonly pageFactory: PageManagerFactory;
+    protected readonly vfs: VirtualFileSystem;
+    protected readonly pageManagerFactory: PageManagerFactory;
+    /**
+     * @param fileHandle 파일 핸들 (fs.open으로 얻은 핸들)
+     * @param pageSize 페이지 크기
+     * @param pageCacheCapacity 페이지 캐시 크기
+     * @param walPath WAL 파일 경로 (기본값: null)
+     */
+    constructor(fileHandle: number, pageSize: number, pageCacheCapacity: number, walPath?: string | undefined | null);
+    /**
+     * VFS 인스턴스를 반환합니다.
+     * Transaction 생성 시 사용됩니다.
+     */
+    get vfsInstance(): VirtualFileSystem;
+    /**
+     * @param pageIndex 페이지 인덱스
+     * @param tx 트랜잭션
+     * @returns 페이지 버퍼
+     */
+    get(pageIndex: number, tx: Transaction): Promise<Uint8Array>;
+    /**
+     * Reads the page header.
+     * @param pageIndex Page index
+     * @param tx Transaction
+     * @returns Page header buffer
+     */
+    getHeader(pageIndex: number, tx: Transaction): Promise<Uint8Array>;
+    /**
+     * Reads the page body.
+     * @param pageIndex Page index
+     * @param recursive Whether to read pages recursively
+     * @param tx Transaction
+     * @returns Page body buffer
+     */
+    getBody(pageIndex: number, recursive: boolean | undefined, tx: Transaction): Promise<Uint8Array>;
+    /**
+     * Returns the metadata page.
+     * @param tx Transaction
+     * @returns Metadata page
+     */
+    getMetadata(tx: Transaction): Promise<MetadataPage>;
+    /**
+     * Returns the number of pages stored in the database.
+     * @param tx Transaction
+     * @returns Number of pages
+     */
+    getPageCount(tx: Transaction): Promise<number>;
+    /**
+     * Returns the root index page.
+     * @param tx Transaction
+     * @returns Root index page
+     */
+    getRootIndex(tx: Transaction): Promise<IndexPage>;
+    /**
+     * Sets the metadata page.
+     * @param metadataPage Metadata page
+     * @param tx Transaction
+     */
+    setMetadata(metadataPage: MetadataPage, tx: Transaction): Promise<void>;
+    /**
+     * Sets the page.
+     * @param pageIndex Page index
+     * @param page Page data
+     * @param tx Transaction
+     */
+    setPage(pageIndex: number, page: Uint8Array, tx: Transaction): Promise<void>;
+    /**
+     * Appends and inserts a new page.
+     * @returns Created page ID
+     */
+    appendNewPage(pageType: number | undefined, tx: Transaction): Promise<number>;
+    /**
+     * Writes data to a page. If it overflows, creates the next page and continues writing.
+     * @param pageId Page ID
+     * @param data Data to write
+     * @param offset Position to write (default: 0)
+     * @param tx Transaction
+     */
+    writePageContent(pageId: number, data: Uint8Array, offset: number | undefined, tx: Transaction): Promise<void>;
+    /**
+     * Closes the page file system.
+     */
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * A row consists of a header and a body. The header is 3 bytes, and the body can be up to 65535 bytes.
+ */
+export declare class Row {
+    static readonly CONSTANT: {
+        readonly FLAG_DELETED: 0;
+        readonly FLAG_OVERFLOW: 2;
+        readonly SIZE_FLAG: 1;
+        readonly SIZE_BODY: 2;
+        readonly SIZE_PK: 6;
+        readonly SIZE_RID: 6;
+        readonly SIZE_HEADER: 9;
+        readonly OFFSET_FLAG: 0;
+        readonly OFFSET_BODY_SIZE: 1;
+        readonly OFFSET_PK: 3;
+    };
+    /**
+     * Returns whether the row is deleted.
+     * @param row Row data
+     * @returns Whether deleted
+     */
+    getDeletedFlag(row: Uint8Array): boolean;
+    /**
+     * Returns whether the row is overflowed.
+     * @param row Row data
+     * @returns Whether overflowed
+     */
+    getOverflowFlag(row: Uint8Array): boolean;
+    /**
+     * Returns the size of the row body. This represents purely the data size of the row.
+     * @param row Row data
+     * @returns Body size
+     */
+    getBodySize(row: Uint8Array): number;
+    /**
+     * Returns the primary key (PK) of the row.
+     * @param row Row data
+     * @returns Primary key (PK)
+     */
+    getPK(row: Uint8Array): number;
+    /**
+     * Returns the row body.
+     * @param row Row data
+     * @returns Row body
+     */
+    getBody(row: Uint8Array): Uint8Array;
+    /**
+     * Sets whether the row is deleted.
+     * @param row Row data
+     * @param deleted Whether deleted
+     */
+    setDeletedFlag(row: Uint8Array, deleted: boolean): void;
+    /**
+     * Sets whether the row is overflowed.
+     * @param row Row data
+     * @param overflow Whether overflowed
+     */
+    setOverflowFlag(row: Uint8Array, overflow: boolean): void;
+    /**
+     * Sets the size of the row body.
+     * @param row Row data
+     * @param rowSize Body size
+     */
+    setBodySize(row: Uint8Array, rowSize: number): void;
+    /**
+     * Sets the primary key (PK) of the row.
+     * @param row Row data
+     * @param pk Primary key (PK)
+     */
+    setPK(row: Uint8Array, pk: number): void;
+    /**
+     * Sets the row body.
+     * @param row Row data
+     * @param body Row body
+     */
+    setBody(row: Uint8Array, body: Uint8Array): void;
+}

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

@@ -0,0 +1,19 @@
+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/RowIndexStrategy.d.ts

@@ -0,0 +1,20 @@
+import type { BPTreeNode, SerializeStrategyHead } from 'serializable-bptree';
+import { 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/RowTableEngine.d.ts

@@ -0,0 +1,121 @@
+import type { DataplyMetadata, DataplyOptions } from '../types';
+import { BPTreeAsync } from 'serializable-bptree';
+import { PageFileSystem } from './PageFileSystem';
+import { Row } from './Row';
+import { KeyManager } from './KeyManager';
+import { PageManagerFactory } from './Page';
+import { Transaction } from './transaction/Transaction';
+export declare class RowTableEngine {
+    protected readonly pfs: PageFileSystem;
+    protected readonly options: Required<DataplyOptions>;
+    protected readonly bptree: BPTreeAsync<number, number>;
+    protected readonly order: number;
+    protected readonly factory: PageManagerFactory;
+    private readonly metadataPageManager;
+    private readonly dataPageManager;
+    private readonly overflowPageManager;
+    protected readonly keyManager: KeyManager;
+    protected readonly rowManager: Row;
+    protected readonly maxBodySize: number;
+    private readonly ridBuffer;
+    private readonly pageIdBuffer;
+    private initialized;
+    constructor(pfs: PageFileSystem, options: Required<DataplyOptions>);
+    /**
+     * Initializes the B+ Tree.
+     */
+    init(): Promise<void>;
+    /**
+     * Calculates the optimized order.
+     * @param pageSize Page size
+     * @param keySize Key size
+     * @param pointerSize Pointer size
+     * @returns Optimal order
+     */
+    protected getOptimalOrder(pageSize: number, keySize: number, pointerSize: number): number;
+    /**
+     * Returns the actual row size generated from the data.
+     * @param rowBody Data
+     * @returns Actual row size generated
+     */
+    protected getRequiredRowSize(rowBody: Uint8Array): number;
+    /**
+     * Sets the RID in the buffer.
+     * @param pageId Page ID
+     * @param slotIndex Slot index
+     * @returns Buffer
+     */
+    private setRID;
+    /**
+     * Returns the RID from the buffer.
+     * @returns RID
+     */
+    private getRID;
+    /**
+     * Returns the metadata of the dataply.
+     * @param tx Transaction
+     * @returns Metadata
+     */
+    getMetadata(tx: Transaction): Promise<DataplyMetadata>;
+    /**
+     * Inserts data.
+     * @param data Data
+     * @param incrementRowCount Whether to increment the row count to metadata
+     * @param tx Transaction
+     * @returns PK of the inserted data
+     */
+    insert(data: Uint8Array, incrementRowCount: boolean, tx: Transaction): Promise<number>;
+    /**
+     * Looks up the RID by PK.
+     * Checks Pending Updates first if a transaction exists.
+     * @param pk PK
+     * @param tx Transaction
+     * @returns RID or null (if not found)
+     */
+    private getRidByPK;
+    /**
+     * Looks up the RID corresponding to the PK in the B+ Tree and returns the actual row.
+     * @param pk Primary key of the row
+     * @param tx Transaction
+     * @returns Raw data of the row
+     */
+    /**
+     * Updates data.
+     * @param pk Primary key of the row
+     * @param data Data to update
+     * @param tx Transaction
+     */
+    update(pk: number, data: Uint8Array, tx: Transaction): Promise<void>;
+    /**
+     * Updates a normal row.
+     * @param page Page data
+     * @param pageId Page ID
+     * @param slotIndex Slot index
+     * @param row Row data
+     * @param pk Primary key of the row
+     * @param data Data to update
+     * @param tx Transaction
+     */
+    private updateNormalRow;
+    /**
+     * 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>;
+    /**
+     * Looks up the RID corresponding to the PK in the B+ Tree and returns the actual row.
+     * @param pk Primary key of the row
+     * @param tx Transaction
+     * @returns Raw data of the row
+     */
+    selectByPK(pk: number, tx: Transaction): Promise<Uint8Array | null>;
+    private fetchRowByRid;
+    /**
+     * Returns the count of rows.
+     * @param tx Transaction
+     * @returns Row count
+     */
+    getRowCount(tx: Transaction): Promise<number>;
+}

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

@@ -0,0 +1,75 @@
+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

@@ -0,0 +1,121 @@
+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>;
+}

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

@@ -0,0 +1,96 @@
+import { LRUMap } from 'cache-entanglement';
+import { LogManager } from './LogManager';
+import type { Transaction } from './transaction/Transaction';
+/**
+ * Virtual File System class that manages and caches files in page units.
+ */
+export declare class VirtualFileSystem {
+    protected fileHandle: number;
+    protected pageSize: number;
+    protected pageCacheCapacity: number;
+    /** Cache list (Page ID -> Data Buffer) */
+    protected cache: LRUMap<number, Uint8Array>;
+    /** Page IDs that have changes and need disk synchronization */
+    protected dirtyPages: Set<number>;
+    /** Track logical file size */
+    protected fileSize: number;
+    /** Bit shift value for page size */
+    protected pageShift: number;
+    /** Bit mask value for page size */
+    protected pageMask: number;
+    protected logManager?: LogManager;
+    protected dirtyPageOwners: Map<number, Transaction>;
+    protected activeTransactions: Map<number, Transaction>;
+    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.
+     */
+    private recover;
+    /**
+     * Commits the transaction.
+     * @param tx Transaction
+     */
+    commit(tx: Transaction): Promise<void>;
+    /**
+     * Rolls back the transaction.
+     * @param tx Transaction
+     */
+    rollback(tx: Transaction): Promise<void>;
+    private cleanupTransaction;
+    /**
+     * Reads data from a specific position in the file.
+     * @param handle File handle
+     * @param buffer Data buffer to read into
+     * @param offset Start position in buffer
+     * @param length Length of data to read
+     * @param position Start position in file
+     * @returns Length of data read
+     */
+    protected _readAsync(handle: number, buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
+    /**
+     * Writes data to a specific position in the file.
+     * @param handle File handle
+     * @param buffer Data buffer to write
+     * @param offset Start position in buffer
+     * @param length Length of data to write
+     * @param position Start position in file
+     */
+    protected _writeAsync(handle: number, buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
+    /**
+     * Appends data to the end of the file.
+     * @param buffer Data buffer to append
+     */
+    protected _appendAsync(handle: number, buffer: Uint8Array): Promise<void>;
+    protected _readPage(pageIndex: number, tx: Transaction): Promise<Uint8Array>;
+    /**
+     * Reads data from a specific position in the file.
+     * @param offset Start position
+     * @param length Length of data to read
+     * @param tx Transaction
+     * @returns Read data buffer
+     */
+    read(offset: number, length: number, tx: Transaction): Promise<Uint8Array>;
+    /**
+     * Appends data to the end of the file.
+     * @param buffer Data buffer to append
+     * @returns Length of appended data
+     */
+    append(buffer: Uint8Array, tx: Transaction): Promise<number>;
+    /**
+     * Writes data to a specific position in the file.
+     * @param offset Start position
+     * @param buffer Data buffer to write
+     * @returns Length of data written
+     */
+    write(offset: number, buffer: Uint8Array, tx: Transaction): Promise<number>;
+    /**
+     * Synchronizes dirty pages to disk.
+     */
+    sync(): Promise<void>;
+    /**
+     * Closes the file.
+     */
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Lock Manager class.
+ * Controls concurrency for page access.
+ * Implemented using the Ryoiki library.
+ */
+export declare class LockManager {
+    private lock;
+    private unlockMap;
+    constructor();
+    /**
+     * Requests a read (Shared) lock for a page.
+     * Ryoiki maintains the lock until explicitly released, even if the callback ends.
+     * @param pageId Page ID
+     * @returns Lock ID to be used for releasing the lock
+     */
+    acquireRead(pageId: number): Promise<string>;
+    /**
+     * Requests a write (Exclusive) lock for a page.
+     * @param pageId Page ID
+     * @returns Lock ID to be used for releasing the lock
+     */
+    acquireWrite(pageId: number): Promise<string>;
+    /**
+     * Releases a lock.
+     * @param lockId Lock ID to release
+     */
+    release(lockId: string): void;
+}