dataply 0.0.1

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

@@ -0,0 +1,75 @@
+import type { DataplyOptions, DataplyMetadata } from '../types';
+import { DataplyAPI } from './DataplyAPI';
+import { Transaction } from './transaction/Transaction';
+/**
+ * Class for managing Dataply files.
+ */
+export declare class Dataply {
+    protected readonly api: DataplyAPI;
+    constructor(file: string, options?: DataplyOptions);
+    /**
+     * Gets the options used to open the dataply.
+     * @returns Options used to open the dataply.
+     */
+    get options(): Required<DataplyOptions>;
+    /**
+     * 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 dataply instance.
+     * Must be called before using the dataply instance.
+     * If not called, the dataply instance cannot be used.
+     */
+    init(): Promise<void>;
+    /**
+     * Retrieves metadata from the dataply.
+     * @returns Metadata of the dataply.
+     */
+    getMetadata(): Promise<DataplyMetadata>;
+    /**
+     * 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 dataply file.
+     */
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,121 @@
+import type { DataplyOptions, DataplyMetadata } 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 Dataply files.
+ */
+export declare class DataplyAPI {
+    protected file: string;
+    protected fileHandle: number;
+    readonly options: Required<DataplyOptions>;
+    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<DataplyOptions>);
+    /**
+     * Verifies if the page file is a valid Dataply file.
+     * The metadata page must be located at the beginning of the Dataply file.
+     * @param fileHandle File handle
+     * @returns Whether the page file is a valid Dataply file
+     */
+    static VerifyFormat(fileHandle: number): boolean;
+    /**
+     * Fills missing options with default values.
+     * @param options Options
+     * @returns Options filled without omissions
+     */
+    static VerboseOptions(options?: DataplyOptions): Required<DataplyOptions>;
+    /**
+     * 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<DataplyOptions>): void;
+    /**
+     * Opens the database file. If the file does not exist, it initializes it.
+     * @param file Database file path
+     * @param options Options
+     * @returns Dataply instance
+     */
+    static Use(file: string, options?: DataplyOptions): DataplyAPI;
+    /**
+     * Initializes the dataply instance.
+     * Must be called before using the dataply instance.
+     * If not called, the dataply 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 dataply.
+     * @returns Metadata of the dataply.
+     */
+    getMetadata(): Promise<DataplyMetadata>;
+    /**
+     * 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 dataply file.
+     */
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Key Manager class.
+ */
+export declare class KeyManager {
+    /**
+     * Returns a numeric key from the buffer.
+     * @param buffer Buffer
+     * @returns Numeric key
+     */
+    toNumericKey(buffer: Uint8Array): number;
+    /**
+     * Sets a numeric key in the buffer.
+     * @param key Numeric key
+     * @param buffer Buffer
+     * @returns Buffer
+     */
+    setBufferFromKey(key: number, buffer: Uint8Array): Uint8Array;
+    /**
+     * Returns the Page ID from the buffer.
+     * @param buffer Buffer
+     * @returns Page ID
+     */
+    getPageId(buffer: Uint8Array): number;
+    /**
+     * Sets the Page ID in the buffer.
+     * @param buffer Buffer
+     * @param pageId Page ID
+     */
+    setPageId(buffer: Uint8Array, pageId: number): void;
+    /**
+     * Returns the Slot Index from the buffer.
+     * @param buffer Buffer
+     * @returns Slot index
+     */
+    getSlotIndex(buffer: Uint8Array): number;
+    /**
+     * Sets the Slot Index in the buffer.
+     * @param buffer Buffer
+     * @param slotIndex Slot index
+     */
+    setSlotIndex(buffer: Uint8Array, slotIndex: number): void;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Log Manager class.
+ * Records changes to a log file (WAL) and manages them to ensure atomicity of the database.
+ */
+export declare class LogManager {
+    private fd;
+    private readonly walFilePath;
+    private readonly pageSize;
+    private readonly entrySize;
+    private buffer;
+    private view;
+    /**
+     * Constructor
+     * @param walFilePath WAL file path
+     * @param pageSize Page size
+     */
+    constructor(walFilePath: string, pageSize: number);
+    /**
+     * Opens the log file.
+     */
+    open(): void;
+    /**
+     * Appends changed pages to the log file.
+     * Records them sorted by page ID.
+     * @param pages Map of changed pages (Page ID -> Data)
+     */
+    append(pages: Map<number, Uint8Array>): Promise<void>;
+    /**
+     * Reads the log file to recover the page map.
+     * Runs synchronously as it is called by the VFS constructor.
+     * @returns Recovered page map
+     */
+    readAllSync(): Map<number, Uint8Array>;
+    /**
+     * Initializes (clears) the log file.
+     * Should be called after a checkpoint.
+     */
+    clear(): Promise<void>;
+    /**
+     * Cleans up resources.
+     */
+    close(): void;
+}