inibase 2.0.1 → 3.1.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.js

@@ -1,3 +1,4 @@
+import { COMPUTED_EXPR_MAX_LENGTH } from "./expression.js";
 /**
  * Type guard function to check if the input is an array of objects.
  *
@@ -663,6 +664,15 @@ export const ERROR_MESSAGES = {
         INVALID_REGEX_MATCH: "Field {variable} does not match the expected pattern",
         INVALID_NAME: "Name {variable} is not valid",
         NO_ENV: "No environment file found",
+        COMPUTED_FIELD_SYNTAX: "Invalid computed expression syntax in field {variable}",
+        COMPUTED_FIELD_UNKNOWN_FIELD: "Field {variable} references unknown field id {variable}",
+        COMPUTED_FIELD_INVALID_LINK: "Field {variable} has an invalid link at hop {variable}",
+        COMPUTED_FIELD_INVALID_TARGET: "Field {variable} references an invalid target ({variable})",
+        COMPUTED_FIELD_CONFLICT: "Field {variable} cannot be computed and required/unique/regex at the same time",
+        COMPUTED_FIELD_CYCLE: "Computed fields form a cycle: {variable}",
+        COMPUTED_FIELD_SETTABLE: "Field {variable} is computed and cannot be set directly",
+        COMPUTED_FIELD_DANGLING_LINK: "Computed field {variable} references a missing row in table {variable}",
+        COMPUTED_FIELD_ARITHMETIC: "Computed field {variable} failed evaluation ({variable})",
     },
     ar: {
         TABLE_EMPTY: "الجدول {variable} فارغ",
@@ -678,6 +688,15 @@ export const ERROR_MESSAGES = {
         INVALID_REGEX_MATCH: "الحقل {variable} لا يتطابق مع النمط المتوقع",
         INVALID_NAME: "الاسم {variable} غير صالح",
         NO_ENV: "لم يتم العثور على ملف البيئة",
+        COMPUTED_FIELD_SYNTAX: "صيغة الحقل المحسوب غير صالحة في الحقل {variable}",
+        COMPUTED_FIELD_UNKNOWN_FIELD: "الحقل {variable} يشير إلى معرف حقل غير معروف {variable}",
+        COMPUTED_FIELD_INVALID_LINK: "الحقل {variable} يحتوي على رابط غير صالح عند الخطوة {variable}",
+        COMPUTED_FIELD_INVALID_TARGET: "الحقل {variable} يشير إلى هدف غير صالح ({variable})",
+        COMPUTED_FIELD_CONFLICT: "لا يمكن أن يكون الحقل {variable} محسوبًا ومطلوبًا/فريدًا/بنمط في نفس الوقت",
+        COMPUTED_FIELD_CYCLE: "الحقول المحسوبة تشكل دورة: {variable}",
+        COMPUTED_FIELD_SETTABLE: "الحقل {variable} محسوب ولا يمكن تعيينه مباشرة",
+        COMPUTED_FIELD_DANGLING_LINK: "الحقل المحسوب {variable} يشير إلى صف غير موجود في الجدول {variable}",
+        COMPUTED_FIELD_ARITHMETIC: "فشل تقييم الحقل المحسوب {variable} ({variable})",
     },
     fr: {
         TABLE_EMPTY: "La table {variable} est vide",
@@ -693,6 +712,15 @@ export const ERROR_MESSAGES = {
         INVALID_REGEX_MATCH: "Le champ {variable} ne correspond pas au modèle attendu",
         INVALID_NAME: "Le nom {variable} n'est pas valide",
         NO_ENV: "Aucun fichier d'environnement trouvé",
+        COMPUTED_FIELD_SYNTAX: "Syntaxe d'expression calculée invalide pour le champ {variable}",
+        COMPUTED_FIELD_UNKNOWN_FIELD: "Le champ {variable} référence un identifiant de champ inconnu {variable}",
+        COMPUTED_FIELD_INVALID_LINK: "Le champ {variable} possède un lien invalide à l'étape {variable}",
+        COMPUTED_FIELD_INVALID_TARGET: "Le champ {variable} référence une cible invalide ({variable})",
+        COMPUTED_FIELD_CONFLICT: "Le champ {variable} ne peut pas être calculé et requis/unique/regex à la fois",
+        COMPUTED_FIELD_CYCLE: "Les champs calculés forment un cycle : {variable}",
+        COMPUTED_FIELD_SETTABLE: "Le champ {variable} est calculé et ne peut pas être défini directement",
+        COMPUTED_FIELD_DANGLING_LINK: "Le champ calculé {variable} référence une ligne manquante dans la table {variable}",
+        COMPUTED_FIELD_ARITHMETIC: "L'évaluation du champ calculé {variable} a échoué ({variable})",
     },
     es: {
         TABLE_EMPTY: "La tabla {variable} está vacía",
@@ -708,6 +736,15 @@ export const ERROR_MESSAGES = {
         INVALID_REGEX_MATCH: "El campo {variable} no coincide con el patrón esperado",
         INVALID_NAME: "El nombre {variable} no es válido",
         NO_ENV: "No se encontró el archivo de entorno",
+        COMPUTED_FIELD_SYNTAX: "Sintaxis de expresión calculada no válida en el campo {variable}",
+        COMPUTED_FIELD_UNKNOWN_FIELD: "El campo {variable} referencia un id de campo desconocido {variable}",
+        COMPUTED_FIELD_INVALID_LINK: "El campo {variable} tiene un enlace no válido en el paso {variable}",
+        COMPUTED_FIELD_INVALID_TARGET: "El campo {variable} referencia un destino no válido ({variable})",
+        COMPUTED_FIELD_CONFLICT: "El campo {variable} no puede ser calculado y requerido/único/regex a la vez",
+        COMPUTED_FIELD_CYCLE: "Los campos calculados forman un ciclo: {variable}",
+        COMPUTED_FIELD_SETTABLE: "El campo {variable} es calculado y no puede establecerse directamente",
+        COMPUTED_FIELD_DANGLING_LINK: "El campo calculado {variable} referencia una fila inexistente en la tabla {variable}",
+        COMPUTED_FIELD_ARITHMETIC: "Falló la evaluación del campo calculado {variable} ({variable})",
     },
 };
 /**
@@ -784,6 +821,23 @@ export const validateSchema = (schema, language = "en") => {
         validateName(field.key, language);
         if (field.table)
             validateName(field.table, language);
+        if (typeof field.computed !== "undefined") {
+            const computed = field.computed;
+            const isValidForm = typeof computed === "string"
+                ? computed.length > 0 && computed.length <= COMPUTED_EXPR_MAX_LENGTH
+                : typeof computed === "object" &&
+                    computed !== null &&
+                    typeof computed.expr === "string" &&
+                    typeof computed.ast === "object" &&
+                    computed.expr.length > 0 &&
+                    computed.expr.length <= COMPUTED_EXPR_MAX_LENGTH;
+            if (!isValidForm)
+                throw createError(language, "COMPUTED_FIELD_SYNTAX", field.key);
+            if (field.required !== undefined ||
+                field.unique !== undefined ||
+                field.regex !== undefined)
+                throw createError(language, "COMPUTED_FIELD_CONFLICT", field.key);
+        }
         if (field.children && isArrayOfObjects(field.children))
             validateSchema(field.children, language);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inibase",
-  "version": "2.0.1",
+  "version": "3.1.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,8 +86,13 @@
     "prebuild": "biome check --write src",
     "build": "tsc",
     "benchmark": "./benchmark/run.js",
+    "benchmark:durability": "tsx ./benchmark/durability.ts",
+    "benchmark:computed": "tsx ./benchmark/computed.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:expression": "tsx ./tests/expression.test.ts",
     "test:advanced": "tsx ./tests/inibase.advanced.test.ts"
   }
 }