@graypirate/tabula 1.0.0

package/dist/CLI/io.d.ts

@@ -0,0 +1,6 @@
+export type ConfirmationOptions = {
+    isTTY?: boolean;
+    readResponse?: (prompt: string) => Promise<string | null>;
+};
+export declare function readStdin(required: boolean, isTTY?: boolean | undefined, read?: () => Promise<string>): Promise<string>;
+export declare function confirmationDialogue(prompt: string, options?: ConfirmationOptions): Promise<boolean>;

package/dist/CLI/io.js

@@ -0,0 +1,28 @@
+import { createInterface } from "node:readline/promises";
+export async function readStdin(required, isTTY = process.stdin.isTTY, read = () => Bun.stdin.text()) {
+    return required && isTTY !== true ? await read() : "";
+}
+export async function confirmationDialogue(prompt, options = {}) {
+    const isTTY = options.isTTY ?? process.stdin.isTTY;
+    if (isTTY !== true) {
+        return true;
+    }
+    const response = await (options.readResponse ?? readInteractiveResponse)(`${prompt} (y/n)`);
+    const normalized = response?.trim().toLowerCase();
+    return normalized === "y" || normalized === "yes";
+}
+async function readInteractiveResponse(prompt) {
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        return await readline.question(prompt);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        readline.close();
+    }
+}

package/dist/CLI/json.d.ts

@@ -0,0 +1,9 @@
+import type { BlockWrite, ObjectWrite } from "../index.js";
+export type WriteInput = {
+    entity: "block";
+    value: BlockWrite;
+} | {
+    entity: "object";
+    value: ObjectWrite;
+};
+export declare function parseWriteInput(input: string): WriteInput;

package/dist/CLI/json.js

@@ -0,0 +1,42 @@
+import { TabulaInputError, validateWriteInput } from "../index.js";
+import { CLIInputError } from "./errors.js";
+export function parseWriteInput(input) {
+    const value = parseJSONObject(input);
+    let entity;
+    try {
+        entity = validateWriteInput(value);
+    }
+    catch (error) {
+        if (error instanceof TabulaInputError) {
+            throw inputError(error.code, error.message, error.details);
+        }
+        throw error;
+    }
+    return entity.type === "object"
+        ? { entity: "object", value: entity }
+        : { entity: "block", value: entity };
+}
+function parseJSONObject(input) {
+    if (input.trim().length === 0) {
+        throw inputError("MISSING_INPUT", "JSON input is required on stdin");
+    }
+    let value;
+    try {
+        value = JSON.parse(input);
+    }
+    catch (error) {
+        throw inputError("INVALID_JSON", "stdin is not valid JSON", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return requireObject(value, "$");
+}
+function requireObject(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw inputError("INVALID_OBJECT", `Expected object at ${path}`, { path });
+    }
+    return value;
+}
+function inputError(code, message, details) {
+    return new CLIInputError(code, message, details);
+}

package/dist/CLI/properties.d.ts

@@ -0,0 +1,3 @@
+import type { JSONRecord } from "../index.js";
+export type Properties = JSONRecord;
+export declare function parseProperties(values: string[]): Properties;

package/dist/CLI/properties.js

@@ -0,0 +1,22 @@
+import { CLIInputError } from "./errors.js";
+export function parseProperties(values) {
+    const properties = {};
+    for (const property of values) {
+        const separator = property.indexOf("=");
+        if (separator < 1) {
+            throw new CLIInputError("INVALID_PROPERTY", `Property must use key=value syntax: ${property}`);
+        }
+        const key = property.slice(0, separator);
+        if (Object.hasOwn(properties, key)) {
+            throw new CLIInputError("DUPLICATE_PROPERTY", `Duplicate property: ${key}`);
+        }
+        const value = property.slice(separator + 1);
+        try {
+            properties[key] = JSON.parse(value);
+        }
+        catch {
+            properties[key] = value;
+        }
+    }
+    return properties;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./API/index.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./API/index.js";

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

@@ -0,0 +1,68 @@
+import type { Database } from "bun:sqlite";
+import type { BlockID, BlockMetadata } from "../../types/block";
+import type { StoredBlock } from "../types";
+/**
+ * Inserts a block row.
+ * @param db - The database containing the block
+ * @param block - The block metadata and content to insert
+ */
+export declare function insertStoredBlock(db: Database, block: StoredBlock): void;
+/**
+ * Inserts multiple block rows atomically.
+ * @param db - The database containing the blocks
+ * @param blocks - The blocks to insert
+ */
+export declare function insertStoredBlocks(db: Database, blocks: StoredBlock[]): void;
+/**
+ * Inserts or updates a block row without changing its containment children.
+ * @param db - The database containing the block
+ * @param block - The block metadata and content to persist
+ */
+export declare function upsertStoredBlock(db: Database, block: StoredBlock): void;
+/**
+ * Reads block metadata without content or children.
+ * @param db - The database containing the block
+ * @param blockID - The block ID to read
+ * @returns The block metadata
+ */
+export declare function getBlockMetadata(db: Database, blockID: BlockID): BlockMetadata;
+/**
+ * Reads the stored block row without recursive children.
+ * @param db - The database containing the block
+ * @param blockID - The block ID to read
+ * @returns The stored block metadata and content
+ */
+export declare function getStoredBlock(db: Database, blockID: BlockID): StoredBlock;
+/**
+ * Updates one existing block row without changing its containment children.
+ * @param db - The database containing the block
+ * @param block - The block metadata and content to update
+ */
+export declare function updateStoredBlock(db: Database, block: StoredBlock): void;
+/**
+ * Updates multiple existing block rows atomically.
+ * @param db - The database containing the blocks
+ * @param blocks - The block rows to update
+ */
+export declare function updateStoredBlocks(db: Database, blocks: StoredBlock[]): void;
+/**
+ * Deletes one block row without deleting its graph node or containment subtree.
+ * @param db - The database containing the block
+ * @param blockID - The block ID to delete
+ * @returns True if the block existed and was deleted
+ */
+export declare function deleteStoredBlock(db: Database, blockID: BlockID): boolean;
+/**
+ * Deletes block rows without deleting graph nodes or containment subtrees.
+ * @param db - The database containing the blocks
+ * @param blockIDs - The block IDs to delete
+ * @returns The number of requested block IDs that existed
+ */
+export declare function deleteStoredBlocks(db: Database, blockIDs: BlockID[]): number;
+/**
+ * Checks whether a block row exists.
+ * @param db - The database to check
+ * @param blockID - The block ID to check
+ * @returns True if the block exists
+ */
+export declare function isStoredBlock(db: Database, blockID: BlockID): boolean;

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

@@ -0,0 +1,185 @@
+import { BlockPrefix } from "../../utils/id";
+/**
+ * Inserts a block row.
+ * @param db - The database containing the block
+ * @param block - The block metadata and content to insert
+ */
+export function insertStoredBlock(db, block) {
+    validateBlock(block);
+    db.query(`
+        INSERT INTO blocks (id, content, properties)
+        VALUES ($id, $content, $properties)
+    `).run(blockParameters(block));
+}
+/**
+ * Inserts multiple block rows atomically.
+ * @param db - The database containing the blocks
+ * @param blocks - The blocks to insert
+ */
+export function insertStoredBlocks(db, blocks) {
+    if (blocks.length === 0) {
+        return;
+    }
+    validateBlockBatch(blocks);
+    const insert = db.transaction(() => {
+        for (const block of blocks) {
+            insertStoredBlock(db, block);
+        }
+    });
+    insert();
+}
+/**
+ * Inserts or updates a block row without changing its containment children.
+ * @param db - The database containing the block
+ * @param block - The block metadata and content to persist
+ */
+export function upsertStoredBlock(db, block) {
+    validateBlock(block);
+    if (isStoredBlock(db, block.id)) {
+        db.query(`
+            UPDATE blocks
+            SET content = $content,
+                properties = $properties
+            WHERE id = $id
+        `).run(blockParameters(block));
+        return;
+    }
+    insertStoredBlock(db, block);
+}
+/**
+ * Reads block metadata without content or children.
+ * @param db - The database containing the block
+ * @param blockID - The block ID to read
+ * @returns The block metadata
+ */
+export function getBlockMetadata(db, blockID) {
+    const row = db.query(`
+        SELECT id, properties
+        FROM blocks
+        WHERE id = $id
+    `).get({ $id: blockID });
+    if (!row) {
+        throw new Error(`Block not found: ${blockID}`);
+    }
+    return {
+        id: row.id,
+        type: "block",
+        properties: JSON.parse(row.properties),
+    };
+}
+/**
+ * Reads the stored block row without recursive children.
+ * @param db - The database containing the block
+ * @param blockID - The block ID to read
+ * @returns The stored block metadata and content
+ */
+export function getStoredBlock(db, blockID) {
+    const row = db.query(`
+        SELECT id, content, properties
+        FROM blocks
+        WHERE id = $id
+    `).get({ $id: blockID });
+    if (!row) {
+        throw new Error(`Block not found: ${blockID}`);
+    }
+    return {
+        id: row.id,
+        type: "block",
+        properties: JSON.parse(row.properties),
+        content: row.content,
+    };
+}
+/**
+ * Updates one existing block row without changing its containment children.
+ * @param db - The database containing the block
+ * @param block - The block metadata and content to update
+ */
+export function updateStoredBlock(db, block) {
+    updateStoredBlocks(db, [block]);
+}
+/**
+ * Updates multiple existing block rows atomically.
+ * @param db - The database containing the blocks
+ * @param blocks - The block rows to update
+ */
+export function updateStoredBlocks(db, blocks) {
+    if (blocks.length === 0) {
+        return;
+    }
+    validateBlockBatch(blocks);
+    const missingID = blocks.find((block) => !isStoredBlock(db, block.id))?.id;
+    if (missingID) {
+        throw new Error(`Block not found: ${missingID}`);
+    }
+    const update = db.transaction(() => {
+        const statement = db.query(`
+            UPDATE blocks
+            SET content = $content,
+                properties = $properties
+            WHERE id = $id
+        `);
+        for (const block of blocks) {
+            statement.run(blockParameters(block));
+        }
+    });
+    update();
+}
+/**
+ * Deletes one block row without deleting its graph node or containment subtree.
+ * @param db - The database containing the block
+ * @param blockID - The block ID to delete
+ * @returns True if the block existed and was deleted
+ */
+export function deleteStoredBlock(db, blockID) {
+    return deleteStoredBlocks(db, [blockID]) > 0;
+}
+/**
+ * Deletes block rows without deleting graph nodes or containment subtrees.
+ * @param db - The database containing the blocks
+ * @param blockIDs - The block IDs to delete
+ * @returns The number of requested block IDs that existed
+ */
+export function deleteStoredBlocks(db, blockIDs) {
+    if (blockIDs.length === 0) {
+        return 0;
+    }
+    const result = db.query(`
+        DELETE FROM blocks
+        WHERE id IN (SELECT value FROM json_each($ids))
+    `).run({ $ids: JSON.stringify([...new Set(blockIDs)]) });
+    return result.changes;
+}
+/**
+ * Checks whether a block row exists.
+ * @param db - The database to check
+ * @param blockID - The block ID to check
+ * @returns True if the block exists
+ */
+export function isStoredBlock(db, blockID) {
+    return db.query("SELECT 1 FROM blocks WHERE id = $id").get({ $id: blockID }) !== null;
+}
+/** Validates a block ID. */
+function validateBlock(block) {
+    if (!block.id.startsWith(`${BlockPrefix}_`)) {
+        throw new Error(`Invalid block id: ${block.id}`);
+    }
+}
+/** Validates block IDs and duplicate IDs within a batch. */
+function validateBlockBatch(blocks) {
+    const ids = new Set();
+    for (const block of blocks) {
+        validateBlock(block);
+        if (ids.has(block.id)) {
+            throw new Error(`Duplicate block id: ${block.id}`);
+        }
+        ids.add(block.id);
+    }
+}
+/** Maps a stored block to SQLite named parameters. */
+function blockParameters(block) {
+    return {
+        $id: block.id,
+        $content: block.content,
+        $properties: JSON.stringify(block.properties ?? {}),
+    };
+}

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

@@ -0,0 +1,61 @@
+import type { Database } from "bun:sqlite";
+import type { EntityReference } from "../../types/graph";
+import type { ObjID } from "../../types/object";
+import type { StoredEntityReference } from "../types";
+/**
+ * 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 declare function getEntityParent(db: Database, childID: string): StoredEntityReference | undefined;
+/**
+ * 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 declare function appendDatabaseRootObject(db: Database, databaseID: string, objectID: ObjID): void;
+/**
+ * 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 declare function appendEntityChild(db: Database, parentID: string, child: EntityReference): void;
+/**
+ * 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 declare function getDatabaseRootObjects(db: Database, databaseID: string): ObjID[];
+/**
+ * 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 declare function getDirectEntityChildren(db: Database, parentID: string): EntityReference[];
+/**
+ * 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 declare function replaceEntityChildren(db: Database, desiredChildrenByParent: Map<string, EntityReference[]>): void;
+/**
+ * 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 declare function getDirectEntityChildIDs(db: Database, parentID: string): string[];
+/**
+ * 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 declare function detachEntityParent(db: Database, childID: string): void;
+/** Checks whether any parent edge references an entity. */
+export declare function hasEntityParent(db: Database, id: string): boolean;