inibase 2.0.0 → 3.0.0

package/dist/journal.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Write-ahead journal for crash-atomic, multi-file commits.
+ *
+ * A transaction writes its intent to `journal.jsonl` (fsynced) before touching
+ * any live file, then swaps each live file aside (see `backup`), renames the
+ * freshly-written temp file into place, optionally renames the pagination
+ * metadata file, and finally appends a `commit` marker (fsynced).
+ *
+ * Two journal layouts share one recovery rule:
+ * - single-table ops: one `begin` entry carrying `files` + `pagination`;
+ * - database transactions: a `begin` entry (tables only) followed by one `op`
+ *   entry per staged mutation (`files` + optional `pagination`), then `commit`.
+ *
+ * Recovery rule (run under the lock before any access):
+ * - journal without `commit`  -> roll back (restore backups, undo pagination,
+ *   discard temps);
+ * - journal with `commit`     -> roll forward (complete swaps, discard backups).
+ *
+ * After recovery the journal is removed, so a logical operation spanning many
+ * column files + pagination (single- or multi-table) is atomic w.r.t. crashes.
+ */
+export interface JournalFileOp {
+    /** Absolute path of the live file being replaced or removed. */
+    live: string;
+    /** Absolute path where the original file is parked while the swap is in flight. */
+    backup: string;
+    /** Absolute path of the fully-written replacement, or null for pure removals. */
+    tmp: string | null;
+    /** Whether the live file existed when the transaction began. */
+    existed: boolean;
+}
+export interface JournalBeginEntry {
+    txn: string;
+    type: "begin";
+    /** Tables touched by a database transaction (single-table ops omit this). */
+    tables?: string[];
+    /** Single-table ops carry their intent directly on the begin entry. */
+    files?: JournalFileOp[];
+    /** Old/new absolute pagination file paths, or null when counts don't change. */
+    pagination?: {
+        from: string;
+        to: string;
+    } | null;
+}
+export interface JournalOpEntry {
+    txn: string;
+    type: "op";
+    files: JournalFileOp[];
+    /** Old/new absolute pagination file paths, or null when counts don't change. */
+    pagination?: {
+        from: string;
+        to: string;
+    } | null;
+}
+export interface JournalCommitEntry {
+    txn: string;
+    type: "commit";
+}
+export type JournalEntry = JournalBeginEntry | JournalOpEntry | JournalCommitEntry;
+export declare class Journal {
+    readonly path: string;
+    private readonly txn;
+    private handle;
+    constructor(tablePath: string, txn: string);
+    private openJournal;
+    private append;
+    begin(files: JournalFileOp[], pagination?: JournalBeginEntry["pagination"]): Promise<void>;
+    commit(): Promise<void>;
+    /**
+     * Undo an in-flight transaction whose `commit` marker was never written.
+     * Restores originals from backups, undoes the pagination rename (if any),
+     * removes created files and leftovers, then discards the journal.
+     */
+    rollback(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * Write-ahead journal for a database-level transaction spanning multiple
+ * tables. Holds `begin(tables)` once, then one `op` per staged mutation, and
+ * finally a single `commit` marker. Lives in `<database>/.tmp/journal.jsonl`
+ * next to the per-table `.tmp` directories.
+ */
+export declare class DatabaseJournal {
+    readonly path: string;
+    private readonly txn;
+    private handle;
+    constructor(dbPath: string, txn: string);
+    private openJournal;
+    private append;
+    begin(tables: string[]): Promise<void>;
+    op(files: JournalFileOp[], pagination?: JournalOpEntry["pagination"]): Promise<void>;
+    commit(): Promise<void>;
+    /**
+     * Undo the transaction: restore any published files (crash mid-commit in
+     * the same process — callers normally roll back before anything is
+     * published), discard temps/journals. Handles the un-published case
+     * identically (no backups exist -> restores are no-ops).
+     */
+    rollback(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * Recover from a crash. `tmpDirPath` is a `.tmp` directory (a table's or the
+ * database's) where `journal.jsonl` lives, in either single-table or
+ * database-transaction layout. Entries carry absolute paths, so no other
+ * context is needed. Must be called while holding the corresponding lock so no
+ * live writer can interleave.
+ */
+export declare function recover(tmpDirPath: string): Promise<void>;

package/dist/journal.js

@@ -0,0 +1,263 @@
+import { open, readFile, rename, rmdir, unlink, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+// Durability mirror of src/file.ts (kept local to avoid an ESM import cycle:
+// file.ts imports recover() from here). `none` skips fsyncs, `full` fsyncs
+// journal appends, recoveries and directory touches.
+const DURABLE = (process.env.INIBASE_DURABILITY ?? "full") !== "none";
+const maybeSync = async (handle) => {
+    if (DURABLE)
+        await handle.sync();
+};
+const exists = async (path) => {
+    try {
+        const handle = await open(path, "r");
+        await handle.close();
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const syncDir = async (path) => {
+    let handle = null;
+    try {
+        handle = await open(path, "r");
+        await maybeSync(handle);
+    }
+    catch {
+        // Directory fsync is not supported on every platform/filesystem.
+    }
+    finally {
+        await handle?.close();
+    }
+};
+/** Parse every journal entry; partial trailing lines (crash mid-append) are ignored. */
+const readEntries = async (journalPath) => {
+    let content;
+    try {
+        content = await readFile(journalPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of content.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // Partial trailing line: the append that wrote it was never
+            // fsynced, so the transaction never reached its `commit` marker.
+        }
+    }
+    return entries;
+};
+const readBegin = async (journalPath) => {
+    for (const entry of await readEntries(journalPath))
+        if (entry.type === "begin")
+            return entry;
+    return null;
+};
+/** Flatten begin/op entries into ordered file ops and pagination renames. */
+const collectOps = (entries) => {
+    const ops = [];
+    const paginations = [];
+    for (const entry of entries) {
+        if (entry.type === "commit")
+            continue;
+        if (entry.files?.length)
+            ops.push(...entry.files);
+        if (entry.pagination)
+            paginations.push(entry.pagination);
+    }
+    return { ops, paginations };
+};
+/**
+ * Undo an uncommitted transaction (in reverse order so chained pagination
+ * renames and repeated swaps of the same live file unwind correctly), discard
+ * temps and backups, and fsync the affected directories.
+ */
+const applyRollback = async (ops, paginations) => {
+    for (const op of ops.toReversed()) {
+        if (op.existed && (await exists(op.backup))) {
+            await unlink(op.live).catch(() => { });
+            await rename(op.backup, op.live);
+        }
+        else if (!op.existed) {
+            await unlink(op.live).catch(() => { });
+        }
+        if (op.tmp)
+            await unlink(op.tmp).catch(() => { });
+        await unlink(op.backup).catch(() => { });
+        // Drop the per-txn backup subdirectory once it is empty.
+        await rmEmptyDir(dirname(op.backup));
+    }
+    for (const { from, to } of paginations.toReversed())
+        if ((await exists(to)) && !(await exists(from)))
+            await rename(to, from);
+};
+/** Complete a committed transaction: finish any missing swaps, drop backups. */
+const applyRollForward = async (ops, paginations) => {
+    for (const op of ops) {
+        if (op.tmp && !(await exists(op.live)) && (await exists(op.tmp)))
+            await rename(op.tmp, op.live);
+        await unlink(op.backup).catch(() => { });
+        if (op.tmp)
+            await unlink(op.tmp).catch(() => { });
+        await rmEmptyDir(dirname(op.backup));
+    }
+    for (const { from, to } of paginations)
+        if ((await exists(from)) && !(await exists(to)))
+            await rename(from, to);
+};
+/** Best-effort removal of an empty directory (per-txn backup dir). */
+const rmEmptyDir = async (dirPath) => {
+    try {
+        await rmdir(dirPath);
+    }
+    catch {
+        // Not empty or already gone: leave it.
+    }
+};
+export class Journal {
+    path;
+    txn;
+    handle = null;
+    constructor(tablePath, txn) {
+        this.txn = txn;
+        this.path = join(tablePath, ".tmp", "journal.jsonl");
+    }
+    async openJournal() {
+        if (!this.handle)
+            this.handle = await open(this.path, "a+");
+    }
+    async append(entry) {
+        await this.openJournal();
+        const handle = this.handle;
+        if (!handle)
+            throw new Error("JOURNAL_NOT_OPEN");
+        await handle.writeFile(`${JSON.stringify(entry)}\n`);
+        await maybeSync(handle);
+    }
+    async begin(files, pagination = null) {
+        await this.append({ txn: this.txn, type: "begin", files, pagination });
+    }
+    async commit() {
+        await this.append({ txn: this.txn, type: "commit" });
+    }
+    /**
+     * Undo an in-flight transaction whose `commit` marker was never written.
+     * Restores originals from backups, undoes the pagination rename (if any),
+     * removes created files and leftovers, then discards the journal.
+     */
+    async rollback() {
+        try {
+            const begin = await readBegin(this.path);
+            if (!begin)
+                return;
+            const { ops, paginations } = collectOps([begin]);
+            await applyRollback(ops, paginations);
+        }
+        finally {
+            await this.dispose();
+            await unlink(this.path).catch(() => { });
+        }
+    }
+    async dispose() {
+        await this.handle?.close();
+        this.handle = null;
+    }
+}
+/**
+ * Write-ahead journal for a database-level transaction spanning multiple
+ * tables. Holds `begin(tables)` once, then one `op` per staged mutation, and
+ * finally a single `commit` marker. Lives in `<database>/.tmp/journal.jsonl`
+ * next to the per-table `.tmp` directories.
+ */
+export class DatabaseJournal {
+    path;
+    txn;
+    handle = null;
+    constructor(dbPath, txn) {
+        this.txn = txn;
+        this.path = join(dbPath, ".tmp", "journal.jsonl");
+    }
+    async openJournal() {
+        if (!this.handle)
+            this.handle = await open(this.path, "a+");
+    }
+    async append(entry) {
+        await this.openJournal();
+        const handle = this.handle;
+        if (!handle)
+            throw new Error("JOURNAL_NOT_OPEN");
+        await handle.writeFile(`${JSON.stringify(entry)}\n`);
+        await maybeSync(handle);
+    }
+    async begin(tables) {
+        await this.append({ txn: this.txn, type: "begin", tables });
+    }
+    async op(files, pagination = null) {
+        await this.append({ txn: this.txn, type: "op", files, pagination });
+    }
+    async commit() {
+        await this.append({ txn: this.txn, type: "commit" });
+    }
+    /**
+     * Undo the transaction: restore any published files (crash mid-commit in
+     * the same process — callers normally roll back before anything is
+     * published), discard temps/journals. Handles the un-published case
+     * identically (no backups exist -> restores are no-ops).
+     */
+    async rollback() {
+        try {
+            const { ops, paginations } = collectOps(await readEntries(this.path));
+            await applyRollback(ops, paginations);
+        }
+        finally {
+            await this.dispose();
+            await unlink(this.path).catch(() => { });
+        }
+    }
+    async dispose() {
+        await this.handle?.close();
+        this.handle = null;
+    }
+}
+/**
+ * Recover from a crash. `tmpDirPath` is a `.tmp` directory (a table's or the
+ * database's) where `journal.jsonl` lives, in either single-table or
+ * database-transaction layout. Entries carry absolute paths, so no other
+ * context is needed. Must be called while holding the corresponding lock so no
+ * live writer can interleave.
+ */
+export async function recover(tmpDirPath) {
+    const journalPath = join(tmpDirPath, "journal.jsonl");
+    const entries = await readEntries(journalPath);
+    if (!entries.length)
+        return; // no journal -> nothing to recover
+    const begin = entries.find((entry) => entry.type === "begin");
+    if (!begin) {
+        // Journal exists but its begin entry never became durable: no rename
+        // was performed, so the live files are untouched. Discard the journal.
+        await unlink(journalPath).catch(() => { });
+        return;
+    }
+    const committed = entries.some((entry) => entry.type === "commit");
+    const { ops, paginations } = collectOps(entries);
+    if (committed) {
+        // Roll forward: every rename already happened before `commit` was
+        // written; just make sure swaps completed and discard the backups.
+        await applyRollForward(ops, paginations);
+    }
+    else {
+        // Roll back: restore originals, undo pagination renames, remove files
+        // the transaction created and discard every leftover.
+        await applyRollback(ops, paginations);
+    }
+    await unlink(journalPath).catch(() => { });
+    await syncDir(tmpDirPath);
+    await syncDir(dirname(tmpDirPath));
+}

package/dist/utils.d.ts

@@ -115,7 +115,8 @@ export declare const isPassword: (input: unknown) => input is string;
  * @param input - The input to be checked, can be of any type.
  * @returns A boolean indicating whether the input is a valid date.
  */
-export declare const isDate: (input: unknown) => input is Date | number;
+export declare const dateToTimestamp: (input: unknown) => number | null;
+export declare const isDate: (input: unknown) => boolean;
 /**
  * Checks if the input is a valid ID.
  *

package/dist/utils.js

@@ -163,20 +163,36 @@ export const isPassword = (input) => typeof input === "string" && input.length =
  * @param input - The input to be checked, can be of any type.
  * @returns A boolean indicating whether the input is a valid date.
  */
-export const isDate = (input) => {
+export const dateToTimestamp = (input) => {
     // Check if the input is null, undefined, or an empty string
     if (input == null || input === "")
-        return false;
+        return null;
+    if (typeof input === "string") {
+        const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input);
+        if (match) {
+            const year = Number(match[1]);
+            const month = Number(match[2]);
+            const day = Number(match[3]);
+            const timestamp = Date.UTC(year, month - 1, day);
+            const date = new Date(timestamp);
+            return date.getUTCFullYear() === year &&
+                date.getUTCMonth() === month - 1 &&
+                date.getUTCDate() === day
+                ? timestamp
+                : null;
+        }
+    }
     // Convert to number and check if it's a valid number
     const numTimestamp = Number(input);
     // Check if the converted number is NaN or not finite
     if (Number.isNaN(numTimestamp) || !Number.isFinite(numTimestamp))
-        return false;
+        return null;
     // Create a Date object from the timestamp
     const date = new Date(numTimestamp);
     // Check if the date is valid
-    return date.getTime() === numTimestamp;
+    return date.getTime() === numTimestamp ? numTimestamp : null;
 };
+export const isDate = (input) => dateToTimestamp(input) !== null;
 /**
  * Checks if the input is a valid ID.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inibase",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "type": "module",
   "author": {
     "name": "Karim Amahtil",
@@ -17,7 +17,7 @@
   "bugs": {
     "url": "https://github.com/inicontent/inibase/issues"
   },
-  "description": "A file-based & memory-efficient, serverless, ACID compliant, relational database management system",
+  "description": "A file-based & memory-efficient, serverless relational database with crash-atomic ACID: single-table DML + multi-table transactions (per-table writer locks, write-ahead journal + crash recovery, fsync-backed durability, begin/commit/rollback)",
   "engines": {
     "node": ">=22"
   },
@@ -86,7 +86,10 @@
     "prebuild": "biome check --write src",
     "build": "tsc",
     "benchmark": "./benchmark/run.js",
+    "benchmark:durability": "tsx ./benchmark/durability.ts",
     "test": "tsx ./tests/inibase.test.ts",
+    "test:durability": "tsx ./tests/durability.test.ts",
+    "test:transaction": "tsx ./tests/transaction.test.ts",
     "test:utils": "tsx ./tests/utils.test.ts",
     "test:advanced": "tsx ./tests/inibase.advanced.test.ts"
   }