@graypirate/tabula 1.0.0

package/dist/src/storage/db/edges.js

@@ -0,0 +1,306 @@
+import { BlockPrefix, DatabasePrefix, ObjectPrefix } from "../../utils/id";
+import { getStoredNodeType, isStoredNode, } from "./nodes";
+/**
+ * Reads the current direct parent for an object or block node.
+ * @param db - The database containing the child node
+ * @param childID - The object or block ID whose parent should be read
+ * @returns The parent reference, or undefined when the child is unattached
+ */
+export function getEntityParent(db, childID) {
+    const childType = getStoredNodeType(db, childID);
+    if (childType === undefined) {
+        throw new Error(`Entity not found: ${childID}`);
+    }
+    if (childType === "database") {
+        throw new Error(`Database cannot be a child entity: ${childID}`);
+    }
+    const row = db.query(`
+        SELECT
+            edges.parent_id AS id,
+            nodes.type
+        FROM edges
+        JOIN nodes ON nodes.id = edges.parent_id
+        WHERE edges.child_id = $childID
+    `).get({ $childID: childID });
+    return row === null
+        ? undefined
+        : {
+            type: row.type,
+            id: row.id,
+        };
+}
+/**
+ * Adds an object as a root child of the database.
+ * @param db - The database containing the object
+ * @param databaseID - The database parent ID
+ * @param objectID - The object child ID
+ */
+export function appendDatabaseRootObject(db, databaseID, objectID) {
+    appendEntityChild(db, databaseID, { type: "object", id: objectID });
+}
+/**
+ * Appends an existing object or block under a database, object, or block parent.
+ * If the child already has a parent, it is moved to the new parent.
+ * @param db - The database containing the parent and child
+ * @param parentID - The database, object, or block parent ID
+ * @param child - The object or block child to attach
+ */
+export function appendEntityChild(db, parentID, child) {
+    validateParent(db, parentID);
+    validateChildBatch(db, parentID, [child]);
+    if (hasEntityChild(db, parentID, child.id)) {
+        return;
+    }
+    const append = db.transaction(() => {
+        detachEntityParent(db, child.id);
+        const row = db.query(`
+            SELECT COALESCE(MAX(position), -1) AS maxPosition
+            FROM edges
+            WHERE parent_id = $parentID
+        `).get({ $parentID: parentID });
+        db.query(`
+            INSERT INTO edges (parent_id, child_id, position)
+            VALUES ($parentID, $childID, $position)
+        `).run({
+            $parentID: parentID,
+            $childID: child.id,
+            $position: row.maxPosition + 1,
+        });
+        validateNoEntityCycles(db);
+    });
+    append();
+}
+/**
+ * Reads root object IDs ordered under the database.
+ * @param db - The database to read
+ * @param databaseID - The database ID whose root objects should be listed
+ * @returns Ordered root object IDs
+ */
+export function getDatabaseRootObjects(db, databaseID) {
+    validateDatabaseParent(db, databaseID);
+    const rows = db.query(`
+        SELECT child_id AS id
+        FROM edges
+        JOIN nodes ON nodes.id = edges.child_id
+        WHERE parent_id = $databaseID
+          AND nodes.type = 'object'
+        ORDER BY position
+    `).all({ $databaseID: databaseID });
+    return rows.map((row) => row.id);
+}
+/**
+ * Reads direct child entity references for a database, object, or block parent.
+ * @param db - The database containing the parent
+ * @param parentID - The database or entity parent ID
+ * @returns Ordered child entity references
+ */
+export function getDirectEntityChildren(db, parentID) {
+    validateParent(db, parentID);
+    const rows = db.query(`
+        SELECT
+            child_id AS id,
+            nodes.type,
+            position
+        FROM edges
+        JOIN nodes ON nodes.id = edges.child_id
+        WHERE parent_id = $parentID
+        ORDER BY position
+    `).all({ $parentID: parentID });
+    return rows.map((row) => {
+        if (row.type === "database") {
+            throw new Error(`Database cannot be a child entity: ${row.id}`);
+        }
+        return {
+            type: row.type,
+            id: row.id,
+        };
+    });
+}
+/**
+ * Replaces direct children for one or more parents.
+ * @param db - The database containing the parents and children
+ * @param desiredChildrenByParent - Complete desired child lists keyed by parent ID
+ */
+export function replaceEntityChildren(db, desiredChildrenByParent) {
+    if (desiredChildrenByParent.size === 0) {
+        return;
+    }
+    const replace = db.transaction(() => {
+        const incomingChildIDs = new Set();
+        for (const [parentID, children] of desiredChildrenByParent) {
+            validateParent(db, parentID);
+            validateChildBatch(db, parentID, children);
+            for (const child of children) {
+                if (incomingChildIDs.has(child.id)) {
+                    throw new Error(`Duplicate child entity: ${child.id}`);
+                }
+                incomingChildIDs.add(child.id);
+            }
+        }
+        for (const parentID of desiredChildrenByParent.keys()) {
+            db.query(`
+                DELETE FROM edges
+                WHERE parent_id = $parentID
+            `).run({ $parentID: parentID });
+        }
+        const insert = db.query(`
+            INSERT INTO edges (parent_id, child_id, position)
+            VALUES ($parentID, $childID, $position)
+        `);
+        for (const [parentID, children] of desiredChildrenByParent) {
+            children.forEach((child, position) => {
+                detachEntityParent(db, child.id);
+                insert.run({
+                    $parentID: parentID,
+                    $childID: child.id,
+                    $position: position,
+                });
+            });
+        }
+        validateNoEntityCycles(db);
+    });
+    replace();
+}
+/**
+ * Reads direct child IDs without joining subtype rows.
+ * @param db - The database containing the parent
+ * @param parentID - The parent ID to read
+ * @returns Ordered child IDs
+ */
+export function getDirectEntityChildIDs(db, parentID) {
+    return getDirectEntityChildren(db, parentID).map((child) => child.id);
+}
+/**
+ * Removes the current parent edge for a child so it can be reparented or detached.
+ * @param db - The database containing the edge
+ * @param childID - The child ID to detach
+ */
+export function detachEntityParent(db, childID) {
+    db.query(`
+        DELETE FROM edges
+        WHERE child_id = $childID
+    `).run({ $childID: childID });
+}
+/** Checks whether any parent edge references an entity. */
+export function hasEntityParent(db, id) {
+    return db.query(`
+        SELECT 1
+        FROM edges
+        WHERE child_id = $id
+    `).get({ $id: id }) !== null;
+}
+/** Checks whether a direct parent/child edge already exists. */
+function hasEntityChild(db, parentID, childID) {
+    return db.query(`
+        SELECT 1
+        FROM edges
+        WHERE parent_id = $parentID
+          AND child_id = $childID
+    `).get({
+        $parentID: parentID,
+        $childID: childID,
+    }) !== null;
+}
+/** Validates that an entity reference uses the correct ID prefix for its type. */
+function validateEntityReference(reference) {
+    if (reference.type === "database") {
+        throw new Error(`Database cannot be a child entity: ${reference.id}`);
+    }
+    if (reference.type === "object" && !reference.id.startsWith(`${ObjectPrefix}_`)) {
+        throw new Error(`Invalid object id: ${reference.id}`);
+    }
+    if (reference.type === "block" && !reference.id.startsWith(`${BlockPrefix}_`)) {
+        throw new Error(`Invalid block id: ${reference.id}`);
+    }
+}
+/** Validates that an entity exists and matches the requested type. */
+function validateExistingEntity(db, reference) {
+    validateEntityReference(reference);
+    const type = getStoredNodeType(db, reference.id);
+    if (type === undefined) {
+        throw new Error(`Entity not found: ${reference.id}`);
+    }
+    if (type !== reference.type) {
+        throw new Error(`Entity ${reference.id} is a ${type}, not a ${reference.type}`);
+    }
+}
+/** Validates one direct child list for parent/child type rules and duplicates. */
+function validateChildBatch(db, parentID, children) {
+    const childIDs = new Set();
+    for (const child of children) {
+        validateExistingEntity(db, child);
+        if (parentID === child.id) {
+            throw new Error(`Entity ${child.id} cannot parent itself`);
+        }
+        if (parentID.startsWith(`${DatabasePrefix}_`) && child.type === "block") {
+            throw new Error(`Database children must be objects: ${child.id}`);
+        }
+        if (childIDs.has(child.id)) {
+            throw new Error(`Duplicate child entity: ${child.id}`);
+        }
+        childIDs.add(child.id);
+    }
+}
+/** Validates that a database, object, or block parent exists. */
+function validateParent(db, parentID) {
+    if (parentID.startsWith(`${DatabasePrefix}_`)) {
+        validateDatabaseParent(db, parentID);
+        return;
+    }
+    if (!isStoredNode(db, parentID)) {
+        throw new Error(`Parent entity not found: ${parentID}`);
+    }
+}
+/** Validates that a database parent exists. */
+function validateDatabaseParent(db, databaseID) {
+    if (!databaseID.startsWith(`${DatabasePrefix}_`)) {
+        throw new Error(`Invalid database id: ${databaseID}`);
+    }
+    const row = db.query(`
+        SELECT nodes.type
+        FROM "database"
+        JOIN nodes ON nodes.id = "database".id
+        WHERE "database".id = $id
+    `).get({ $id: databaseID });
+    if (!row) {
+        throw new Error(`Database not found: ${databaseID}`);
+    }
+    if (row.type !== "database") {
+        throw new Error(`Entity ${databaseID} is a ${row.type}, not a database`);
+    }
+}
+/** Validates that global containment edges do not contain object/block cycles. */
+function validateNoEntityCycles(db) {
+    const rows = db.query(`
+        SELECT parent_id AS parentID, child_id AS childID
+        FROM edges
+    `).all();
+    const childrenByParent = new Map();
+    for (const row of rows) {
+        if (row.parentID.startsWith(`${DatabasePrefix}_`)) {
+            continue;
+        }
+        const children = childrenByParent.get(row.parentID) ?? [];
+        children.push(row.childID);
+        childrenByParent.set(row.parentID, children);
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id)) {
+            throw new Error(`Entity cycle detected at ${id}`);
+        }
+        if (visited.has(id)) {
+            return;
+        }
+        visiting.add(id);
+        for (const childID of childrenByParent.get(id) ?? []) {
+            visit(childID);
+        }
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const parentID of childrenByParent.keys()) {
+        visit(parentID);
+    }
+}

package/dist/src/storage/db/init.d.ts

@@ -0,0 +1,22 @@
+import { Database } from "bun:sqlite";
+import type { DBMetadata } from "../../types/database";
+export declare const SchemaVersion = "0.0.3";
+/**
+ * Opens a database, initializes its schema, and creates its metadata when needed.
+ * @param path - The path of the SQLite database
+ * @param name - The optional database name
+ * @returns The initialized SQLite database connection
+ */
+export declare function initDatabase(path: string, name?: string): Database;
+/**
+ * Opens an existing initialized database without re-running schema setup.
+ * @param path - The path of the SQLite database
+ * @returns The opened SQLite database connection
+ */
+export declare function openDatabase(path: string): Database;
+/**
+ * Reads the metadata associated with a database.
+ * @param db - The database to read
+ * @returns The database metadata
+ */
+export declare function getDatabaseMetadata(db: Database): DBMetadata;

package/dist/src/storage/db/init.js

@@ -0,0 +1,108 @@
+import { Database } from "bun:sqlite";
+import { createDatabaseID } from "../../utils/id";
+import schema from "./schema.sql" with { type: "text" };
+export const SchemaVersion = "0.0.3";
+/**
+ * Opens a database, initializes its schema, and creates its metadata when needed.
+ * @param path - The path of the SQLite database
+ * @param name - The optional database name
+ * @returns The initialized SQLite database connection
+ */
+export function initDatabase(path, name) {
+    const db = new Database(path);
+    try {
+        db.exec("PRAGMA busy_timeout = 5000;");
+        db.exec("PRAGMA foreign_keys = ON;");
+        const isFresh = isEmptyDatabase(db);
+        if (!isFresh) {
+            validateDatabaseMetadata(db);
+        }
+        db.exec("PRAGMA journal_mode = WAL;");
+        db.exec(schema);
+        if (isFresh) {
+            const insertMetadata = db.transaction(() => {
+                const databaseID = createDatabaseID();
+                db.query(`
+                    INSERT INTO nodes (id, type)
+                    VALUES ($id, 'database')
+                `).run({ $id: databaseID });
+                db.query(`
+                    INSERT INTO "database" (id, name, schema_version)
+                    VALUES ($id, $name, $schemaVersion)
+                `).run({
+                    $id: databaseID,
+                    $name: name ?? null,
+                    $schemaVersion: SchemaVersion,
+                });
+            });
+            insertMetadata();
+        }
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    return db;
+}
+/**
+ * Opens an existing initialized database without re-running schema setup.
+ * @param path - The path of the SQLite database
+ * @returns The opened SQLite database connection
+ */
+export function openDatabase(path) {
+    const db = new Database(path, { create: false, readwrite: true });
+    try {
+        db.exec("PRAGMA busy_timeout = 5000;");
+        db.exec("PRAGMA foreign_keys = ON;");
+        validateDatabaseMetadata(db);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    return db;
+}
+function isEmptyDatabase(db) {
+    const row = db.query(`
+        SELECT COUNT(*) AS count
+        FROM sqlite_master
+        WHERE name NOT LIKE 'sqlite_%'
+    `).get();
+    return row.count === 0;
+}
+/**
+ * Reads the metadata associated with a database.
+ * @param db - The database to read
+ * @returns The database metadata
+ */
+export function getDatabaseMetadata(db) {
+    const rows = db.query(`
+        SELECT
+            id,
+            name,
+            schema_version AS schemaVersion
+        FROM "database"
+        LIMIT 2
+    `).all();
+    if (rows.length !== 1) {
+        throw new Error("Database metadata not found");
+    }
+    const row = rows[0];
+    return {
+        id: row.id,
+        name: row.name ?? undefined,
+        schemaVersion: row.schemaVersion,
+    };
+}
+function validateDatabaseMetadata(db) {
+    let metadata;
+    try {
+        metadata = getDatabaseMetadata(db);
+    }
+    catch {
+        throw new Error(`Incompatible database schema; expected valid version ${SchemaVersion} metadata`);
+    }
+    if (metadata.schemaVersion !== SchemaVersion) {
+        throw new Error(`Unsupported database schema version ${metadata.schemaVersion}; expected ${SchemaVersion}`);
+    }
+}

package/dist/src/storage/db/nodes.d.ts

@@ -0,0 +1,34 @@
+import type { Database } from "bun:sqlite";
+import type { StoredEntityReference, StoredEntityType } from "../types";
+/**
+ * Inserts one graph node row.
+ * @param db - The database containing the node
+ * @param reference - The node type and ID to insert
+ */
+export declare function insertStoredNode(db: Database, reference: StoredEntityReference): void;
+/**
+ * Inserts one graph node row, or validates that an existing row has the same type.
+ * @param db - The database containing the node
+ * @param reference - The node type and ID to persist
+ */
+export declare function upsertStoredNode(db: Database, reference: StoredEntityReference): void;
+/**
+ * Checks whether a graph node exists.
+ * @param db - The database to check
+ * @param id - The node ID to check
+ * @returns True if the node exists
+ */
+export declare function isStoredNode(db: Database, id: string): boolean;
+/**
+ * Reads the stored node type for an ID.
+ * @param db - The database containing the node
+ * @param id - The node ID to read
+ * @returns The node type, or undefined when no node exists
+ */
+export declare function getStoredNodeType(db: Database, id: string): StoredEntityType | undefined;
+/**
+ * Deletes graph nodes by ID.
+ * @param db - The database containing the nodes
+ * @param ids - The node IDs to delete
+ */
+export declare function deleteStoredNodes(db: Database, ids: string[]): void;

package/dist/src/storage/db/nodes.js

@@ -0,0 +1,91 @@
+import { BlockPrefix, DatabasePrefix, ObjectPrefix } from "../../utils/id";
+/**
+ * Inserts one graph node row.
+ * @param db - The database containing the node
+ * @param reference - The node type and ID to insert
+ */
+export function insertStoredNode(db, reference) {
+    validateNodeReference(reference);
+    const existingType = getStoredNodeType(db, reference.id);
+    if (existingType !== undefined) {
+        throw new Error(`Entity already exists: ${reference.id}`);
+    }
+    db.query(`
+        INSERT INTO nodes (id, type)
+        VALUES ($id, $type)
+    `).run({
+        $id: reference.id,
+        $type: reference.type,
+    });
+}
+/**
+ * Inserts one graph node row, or validates that an existing row has the same type.
+ * @param db - The database containing the node
+ * @param reference - The node type and ID to persist
+ */
+export function upsertStoredNode(db, reference) {
+    validateNodeReference(reference);
+    const existingType = getStoredNodeType(db, reference.id);
+    if (existingType !== undefined) {
+        if (existingType !== reference.type) {
+            throw new Error(`Entity ${reference.id} is a ${existingType}, not a ${reference.type}`);
+        }
+        return;
+    }
+    db.query(`
+        INSERT INTO nodes (id, type)
+        VALUES ($id, $type)
+    `).run({
+        $id: reference.id,
+        $type: reference.type,
+    });
+}
+/**
+ * Checks whether a graph node exists.
+ * @param db - The database to check
+ * @param id - The node ID to check
+ * @returns True if the node exists
+ */
+export function isStoredNode(db, id) {
+    return getStoredNodeType(db, id) !== undefined;
+}
+/**
+ * Reads the stored node type for an ID.
+ * @param db - The database containing the node
+ * @param id - The node ID to read
+ * @returns The node type, or undefined when no node exists
+ */
+export function getStoredNodeType(db, id) {
+    const row = db.query(`
+        SELECT type
+        FROM nodes
+        WHERE id = $id
+    `).get({ $id: id });
+    return row?.type;
+}
+/**
+ * Deletes graph nodes by ID.
+ * @param db - The database containing the nodes
+ * @param ids - The node IDs to delete
+ */
+export function deleteStoredNodes(db, ids) {
+    if (ids.length === 0) {
+        return;
+    }
+    db.query(`
+        DELETE FROM nodes
+        WHERE id IN (SELECT value FROM json_each($ids))
+    `).run({ $ids: JSON.stringify(ids) });
+}
+/** Validates that a node reference uses the correct ID prefix for its type. */
+function validateNodeReference(reference) {
+    if (reference.type === "database" && !reference.id.startsWith(`${DatabasePrefix}_`)) {
+        throw new Error(`Invalid database id: ${reference.id}`);
+    }
+    if (reference.type === "object" && !reference.id.startsWith(`${ObjectPrefix}_`)) {
+        throw new Error(`Invalid object id: ${reference.id}`);
+    }
+    if (reference.type === "block" && !reference.id.startsWith(`${BlockPrefix}_`)) {
+        throw new Error(`Invalid block id: ${reference.id}`);
+    }
+}

package/dist/src/storage/db/objects.d.ts

@@ -0,0 +1,55 @@
+import type { Database } from "bun:sqlite";
+import type { ObjID, ObjMetadata } from "../../types/object";
+import type { StoredObject } from "../types";
+/**
+ * Inserts an object row without adding database-root or child containment edges.
+ * @param db - The database containing the object
+ * @param metadata - The object metadata to insert
+ */
+export declare function insertStoredObject(db: Database, metadata: StoredObject): void;
+/**
+ * Inserts or updates an object row without changing containment edges.
+ * @param db - The database containing the object
+ * @param metadata - The object metadata to persist
+ */
+export declare function upsertStoredObject(db: Database, metadata: StoredObject): void;
+/**
+ * Reads object metadata without recursive children.
+ * @param db - The database containing the object
+ * @param objectID - The object ID to read
+ * @returns The object metadata
+ */
+export declare function getObjectMetadata(db: Database, objectID: ObjID): ObjMetadata;
+/**
+ * Reads the stored object row without recursive children.
+ * @param db - The database containing the object
+ * @param objectID - The object ID to read
+ * @returns The stored object metadata
+ */
+export declare function getStoredObject(db: Database, objectID: ObjID): StoredObject;
+/**
+ * Updates object metadata without changing containment edges.
+ * @param db - The database containing the object
+ * @param metadata - The object metadata to update
+ */
+export declare function updateObjectMetadata(db: Database, metadata: StoredObject): void;
+/**
+ * Updates the stored object row without changing recursive children.
+ * @param db - The database containing the object
+ * @param object - The object metadata to update
+ */
+export declare function updateStoredObject(db: Database, object: StoredObject): void;
+/**
+ * Deletes an object row without deleting its graph node or containment subtree.
+ * @param db - The database containing the object
+ * @param objectID - The object ID to delete
+ * @returns True if the object existed and was deleted
+ */
+export declare function deleteStoredObject(db: Database, objectID: ObjID): boolean;
+/**
+ * Checks whether an object row exists.
+ * @param db - The database to check
+ * @param objectID - The object ID to check
+ * @returns True if the object exists
+ */
+export declare function isStoredObject(db: Database, objectID: ObjID): boolean;