@graypirate/tabula 1.0.0

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

@@ -0,0 +1,123 @@
+import { ObjectPrefix } from "../../utils/id";
+/**
+ * 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 function insertStoredObject(db, metadata) {
+    validateObjectMetadata(metadata);
+    db.query(`
+        INSERT INTO objects (id, name, properties)
+        VALUES ($id, $name, $properties)
+    `).run(mapObjectParameters(metadata));
+}
+/**
+ * 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 function upsertStoredObject(db, metadata) {
+    validateObjectMetadata(metadata);
+    if (isStoredObject(db, metadata.id)) {
+        db.query(`
+            UPDATE objects
+            SET name = $name,
+                properties = $properties
+            WHERE id = $id
+        `).run(mapObjectParameters(metadata));
+        return;
+    }
+    insertStoredObject(db, metadata);
+}
+/**
+ * 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 function getObjectMetadata(db, objectID) {
+    const row = db.query(`
+        SELECT id, name, properties
+        FROM objects
+        WHERE id = $id
+    `).get({ $id: objectID });
+    if (!row) {
+        throw new Error(`Object not found: ${objectID}`);
+    }
+    return {
+        id: row.id,
+        type: "object",
+        name: row.name,
+        properties: JSON.parse(row.properties),
+    };
+}
+/**
+ * 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 function getStoredObject(db, objectID) {
+    return getObjectMetadata(db, objectID);
+}
+/**
+ * Updates object metadata without changing containment edges.
+ * @param db - The database containing the object
+ * @param metadata - The object metadata to update
+ */
+export function updateObjectMetadata(db, metadata) {
+    validateObjectMetadata(metadata);
+    if (!isStoredObject(db, metadata.id)) {
+        throw new Error(`Object not found: ${metadata.id}`);
+    }
+    db.query(`
+        UPDATE objects
+        SET name = $name,
+            properties = $properties
+        WHERE id = $id
+    `).run(mapObjectParameters(metadata));
+}
+/**
+ * Updates the stored object row without changing recursive children.
+ * @param db - The database containing the object
+ * @param object - The object metadata to update
+ */
+export function updateStoredObject(db, object) {
+    updateObjectMetadata(db, object);
+}
+/**
+ * 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 function deleteStoredObject(db, objectID) {
+    const result = db.query(`
+        DELETE FROM objects
+        WHERE id = $id
+    `).run({ $id: objectID });
+    return result.changes > 0;
+}
+/**
+ * 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 function isStoredObject(db, objectID) {
+    return db.query("SELECT 1 FROM objects WHERE id = $id").get({ $id: objectID }) !== null;
+}
+/** Validates an object ID. */
+function validateObjectMetadata(metadata) {
+    if (!metadata.id.startsWith(`${ObjectPrefix}_`)) {
+        throw new Error(`Invalid object id: ${metadata.id}`);
+    }
+}
+/** Maps object metadata to SQLite named parameters. */
+function mapObjectParameters(metadata) {
+    return {
+        $id: metadata.id,
+        $name: metadata.name,
+        $properties: JSON.stringify(metadata.properties ?? {}),
+    };
+}

package/dist/src/storage/db/schema.sql

@@ -0,0 +1,59 @@
+CREATE TABLE IF NOT EXISTS "database" (
+    id TEXT PRIMARY KEY
+        REFERENCES nodes(id)
+        ON DELETE RESTRICT
+        DEFERRABLE INITIALLY DEFERRED,
+    name TEXT,
+    schema_version TEXT NOT NULL
+);
+
+CREATE TRIGGER IF NOT EXISTS database_singleton_insert
+BEFORE INSERT ON "database"
+WHEN (SELECT COUNT(*) FROM "database") >= 1
+BEGIN
+    SELECT RAISE(ABORT, 'database metadata already exists');
+END;
+
+CREATE TABLE IF NOT EXISTS nodes (
+    id TEXT PRIMARY KEY,
+    type TEXT NOT NULL CHECK (type IN ('database', 'object', 'block'))
+);
+
+CREATE TABLE IF NOT EXISTS objects (
+    id TEXT PRIMARY KEY
+        REFERENCES nodes(id)
+        ON DELETE CASCADE
+        DEFERRABLE INITIALLY DEFERRED,
+    name TEXT NOT NULL,
+    properties TEXT NOT NULL DEFAULT '{}'
+        CHECK (json_valid(properties))
+);
+
+CREATE TABLE IF NOT EXISTS blocks (
+    id TEXT PRIMARY KEY
+        REFERENCES nodes(id)
+        ON DELETE CASCADE
+        DEFERRABLE INITIALLY DEFERRED,
+    content TEXT NOT NULL,
+    properties TEXT NOT NULL DEFAULT '{}'
+        CHECK (json_valid(properties))
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+    parent_id TEXT NOT NULL
+        REFERENCES nodes(id)
+        ON DELETE CASCADE
+        DEFERRABLE INITIALLY DEFERRED,
+    child_id TEXT NOT NULL
+        REFERENCES nodes(id)
+        ON DELETE CASCADE
+        DEFERRABLE INITIALLY DEFERRED,
+    position INTEGER NOT NULL CHECK (position >= 0),
+    PRIMARY KEY (parent_id, child_id),
+    UNIQUE (child_id),
+    UNIQUE (parent_id, position),
+    CHECK (parent_id <> child_id)
+);
+
+CREATE INDEX IF NOT EXISTS edges_parent_id_idx
+ON edges(parent_id);

package/dist/src/storage/index.d.ts

@@ -0,0 +1,47 @@
+import type { Database } from "bun:sqlite";
+import type { Block, BlockID, BlockMetadata } from "../types/block";
+import type { DBMetadata } from "../types/database";
+import type { Entity, EntityReference } from "../types/graph";
+import type { Obj, ObjID, ObjMetadata } from "../types/object";
+import type { StoredEntity, StoredEntityID, StoredEntityReference } from "./types";
+export type { StoredBlock, StoredEntity, StoredEntityID, StoredEntityReference, StoredEntityType, StoredObject, } from "./types";
+export type SearchType = "object" | "block";
+export interface SearchResult {
+    type: SearchType;
+    id: string;
+    label: string;
+}
+export declare function initializeStorage(path: string, name?: string): Database;
+export declare function openStorage(path: string): Database;
+export declare function readDatabaseMetadata(db: Database): DBMetadata;
+/**
+ * Create an entity with parent placement.
+ *
+ * Objects: parentID defaults to database root if unspecified.
+ * Blocks require an explicit object or block parent.
+ * @param db
+ * @param entity
+ * @param parentID
+ */
+export declare function createEntity(db: Database, entity: StoredEntity, parentID?: StoredEntityID): void;
+export declare function objectExists(db: Database, objectID: ObjID): boolean;
+export declare function blockExists(db: Database, blockID: BlockID): boolean;
+export declare function entityExists(db: Database, id: string): boolean;
+export declare function readObjectTree(db: Database, objectID: ObjID): Obj;
+export declare function readBlockTree(db: Database, blockID: BlockID): Block;
+export declare function readEntityTree(db: Database, entityID: string, visited?: Set<string>): Entity;
+export declare function readDatabaseRootObjects(db: Database): ObjID[];
+export declare function readObjectMetadata(db: Database, objectID: ObjID): ObjMetadata;
+export declare function readBlockMetadata(db: Database, blockID: BlockID): BlockMetadata;
+export declare function readDirectEntityChildIDs(db: Database, parentID: string): StoredEntityID[];
+export declare function readEntityParent(db: Database, entityID: string): StoredEntityReference | undefined;
+export declare function readEntityParentID(db: Database, entityID: string): StoredEntityID | null;
+export declare function persistEntityTree(db: Database, root: Entity): void;
+export declare function writeEntityTree(db: Database, root: Entity, parentID?: StoredEntityID): Entity;
+export declare function moveObjectToDatabaseRoot(db: Database, objectID: ObjID): void;
+export declare function attachEntityChild(db: Database, parentID: StoredEntityID, child: EntityReference): void;
+export declare function replaceDirectEntityChildren(db: Database, desiredChildrenByParent: Map<string, EntityReference[]>): void;
+export declare function deleteObjectTree(db: Database, objectID: ObjID): boolean;
+export declare function deleteBlockTree(db: Database, blockID: BlockID): boolean;
+export declare function deleteEntityTree(db: Database, entityID: string): boolean;
+export declare function searchEntities(db: Database, query: string, type?: SearchType): SearchResult[];

package/dist/src/storage/index.js

@@ -0,0 +1,315 @@
+import { getBlockMetadata, getStoredBlock, insertStoredBlock, isStoredBlock, upsertStoredBlock, } from "./db/blocks";
+import { appendEntityChild, appendDatabaseRootObject, getDatabaseRootObjects, getDirectEntityChildren, getDirectEntityChildIDs, getEntityParent, replaceEntityChildren, } from "./db/edges";
+import { getDatabaseMetadata, initDatabase, openDatabase as openStoredDatabase, } from "./db/init";
+import { deleteStoredNodes, getStoredNodeType, insertStoredNode, isStoredNode, upsertStoredNode, } from "./db/nodes";
+import { getObjectMetadata, getStoredObject, insertStoredObject, isStoredObject, upsertStoredObject, } from "./db/objects";
+// DB functionality
+export function initializeStorage(path, name) {
+    return initDatabase(path, name);
+}
+export function openStorage(path) {
+    return openStoredDatabase(path);
+}
+export function readDatabaseMetadata(db) {
+    return getDatabaseMetadata(db);
+}
+// Creation and existence
+/**
+ * Create an entity with parent placement.
+ *
+ * Objects: parentID defaults to database root if unspecified.
+ * Blocks require an explicit object or block parent.
+ * @param db
+ * @param entity
+ * @param parentID
+ */
+export function createEntity(db, entity, parentID) {
+    const create = db.transaction(() => {
+        insertStoredNode(db, {
+            type: entity.type,
+            id: entity.id,
+        });
+        if (entity.type === "object") {
+            insertStoredObject(db, entity);
+        }
+        else {
+            insertStoredBlock(db, entity);
+        }
+        appendEntityChild(db, resolveRootParentID(db, entity.type, parentID), {
+            type: entity.type,
+            id: entity.id,
+        });
+    });
+    create();
+}
+export function objectExists(db, objectID) {
+    return isStoredObject(db, objectID);
+}
+export function blockExists(db, blockID) {
+    return isStoredBlock(db, blockID);
+}
+export function entityExists(db, id) {
+    return isStoredNode(db, id);
+}
+// Read
+export function readObjectTree(db, objectID) {
+    const type = getStoredNodeType(db, objectID);
+    if (type === undefined || type !== "object") {
+        throw new Error(`Object not found: ${objectID}`);
+    }
+    const entity = readEntityTree(db, objectID);
+    if (entity.type !== "object") {
+        throw new Error(`Object not found: ${objectID}`);
+    }
+    return entity;
+}
+export function readBlockTree(db, blockID) {
+    const type = getStoredNodeType(db, blockID);
+    if (type === undefined || type !== "block") {
+        throw new Error(`Block not found: ${blockID}`);
+    }
+    const entity = readEntityTree(db, blockID);
+    if (entity.type !== "block") {
+        throw new Error(`Block not found: ${blockID}`);
+    }
+    return entity;
+}
+export function readEntityTree(db, entityID, visited = new Set()) {
+    if (visited.has(entityID)) {
+        throw new Error(`Entity cycle detected at ${entityID}`);
+    }
+    visited.add(entityID);
+    const type = getStoredNodeType(db, entityID);
+    if (type === undefined) {
+        throw new Error(`Entity not found: ${entityID}`);
+    }
+    if (type === "database") {
+        throw new Error(`Database cannot be read as a public entity: ${entityID}`);
+    }
+    const children = getDirectEntityChildren(db, entityID).map((child) => readEntityTree(db, child.id, new Set(visited)));
+    if (type === "object") {
+        return {
+            ...getStoredObject(db, entityID),
+            children,
+        };
+    }
+    return {
+        ...getStoredBlock(db, entityID),
+        children,
+    };
+}
+export function readDatabaseRootObjects(db) {
+    return getDatabaseRootObjects(db, getDatabaseMetadata(db).id);
+}
+export function readObjectMetadata(db, objectID) {
+    return getObjectMetadata(db, objectID);
+}
+export function readBlockMetadata(db, blockID) {
+    return getBlockMetadata(db, blockID);
+}
+export function readDirectEntityChildIDs(db, parentID) {
+    return getDirectEntityChildIDs(db, parentID);
+}
+export function readEntityParent(db, entityID) {
+    return getEntityParent(db, entityID);
+}
+export function readEntityParentID(db, entityID) {
+    return readEntityParent(db, entityID)?.id ?? null;
+}
+// Insert and write
+export function persistEntityTree(db, root) {
+    const visit = (entity) => {
+        upsertStoredNode(db, {
+            type: entity.type,
+            id: entity.id,
+        });
+        if (entity.type === "object") {
+            upsertStoredObject(db, {
+                id: entity.id,
+                type: "object",
+                name: entity.name,
+                properties: entity.properties ?? {},
+            });
+        }
+        else {
+            upsertStoredBlock(db, {
+                id: entity.id,
+                type: "block",
+                content: entity.content,
+                properties: entity.properties ?? {},
+            });
+        }
+        entity.children.forEach(visit);
+    };
+    visit(root);
+}
+export function writeEntityTree(db, root, parentID) {
+    const write = db.transaction(() => {
+        persistEntityTree(db, root);
+        appendEntityChild(db, resolveRootParentID(db, root.type, parentID), {
+            type: root.type,
+            id: root.id,
+        });
+        const desiredChildrenByParent = buildChildMap(root);
+        const submittedIDs = collectSubmittedEntityIDs(root);
+        const omittedChildIDs = collectOmittedChildIDs(db, desiredChildrenByParent, submittedIDs);
+        replaceEntityChildren(db, desiredChildrenByParent);
+        deleteOmittedEntitySubtrees(db, omittedChildIDs);
+    });
+    write();
+    return readEntityTree(db, root.id);
+}
+export function moveObjectToDatabaseRoot(db, objectID) {
+    appendDatabaseRootObject(db, getDatabaseMetadata(db).id, objectID);
+}
+export function attachEntityChild(db, parentID, child) {
+    appendEntityChild(db, parentID, child);
+}
+export function replaceDirectEntityChildren(db, desiredChildrenByParent) {
+    replaceEntityChildren(db, desiredChildrenByParent);
+}
+// Deletion
+export function deleteObjectTree(db, objectID) {
+    const type = getStoredNodeType(db, objectID);
+    if (type === undefined) {
+        return false;
+    }
+    if (type !== "object") {
+        throw new Error(`Object not found: ${objectID}`);
+    }
+    return deleteEntityTree(db, objectID);
+}
+export function deleteBlockTree(db, blockID) {
+    const type = getStoredNodeType(db, blockID);
+    if (type === undefined) {
+        return false;
+    }
+    if (type !== "block") {
+        throw new Error(`Block not found: ${blockID}`);
+    }
+    return deleteEntityTree(db, blockID);
+}
+export function deleteEntityTree(db, entityID) {
+    const type = getStoredNodeType(db, entityID);
+    if (type === undefined) {
+        return false;
+    }
+    if (type === "database") {
+        throw new Error(`Database cannot be deleted as a public entity: ${entityID}`);
+    }
+    const ids = collectEntitySubtreeIDs(db, entityID);
+    deleteStoredNodes(db, ids);
+    return true;
+}
+// Search functionality
+export function searchEntities(db, query, type) {
+    const types = type === undefined
+        ? ["object", "block"]
+        : [type];
+    const rows = [];
+    const parameters = { $query: query };
+    if (types.includes("object")) {
+        rows.push(...db.query(`
+            SELECT 'object' AS type, id, name AS label
+            FROM objects
+            WHERE instr(lower(name), lower($query)) > 0
+               OR instr(lower(properties), lower($query)) > 0
+        `).all(parameters));
+    }
+    if (types.includes("block")) {
+        rows.push(...db.query(`
+            SELECT 'block' AS type, id, content AS label
+            FROM blocks
+            WHERE instr(lower(content), lower($query)) > 0
+               OR instr(lower(properties), lower($query)) > 0
+        `).all(parameters));
+    }
+    return rows
+        .map((row) => ({
+        ...row,
+        label: row.type === "block" ? blockLabel(row.label) : row.label,
+    }))
+        .sort((left, right) => left.type.localeCompare(right.type)
+        || left.label.localeCompare(right.label)
+        || left.id.localeCompare(right.id));
+}
+/** Converts block content into a compact single-line search label. */
+function blockLabel(content) {
+    const normalized = content.replace(/\s+/g, " ").trim();
+    return normalized.length <= 80 ? normalized : `${normalized.slice(0, 77)}...`;
+}
+/** Builds complete direct-child replacement lists for every entity in a tree. */
+function buildChildMap(root) {
+    const map = new Map();
+    const visit = (entity) => {
+        map.set(entity.id, entity.children.map((child) => ({
+            type: child.type,
+            id: child.id,
+        })));
+        entity.children.forEach(visit);
+    };
+    visit(root);
+    return map;
+}
+/** Resolves public root placement. */
+function resolveRootParentID(db, type, parentID) {
+    if (parentID !== undefined) {
+        return parentID;
+    }
+    if (type === "object") {
+        return getDatabaseMetadata(db).id;
+    }
+    throw new Error("Block parent is required");
+}
+/** Collects every entity ID explicitly present in a submitted tree. */
+function collectSubmittedEntityIDs(root) {
+    const ids = new Set();
+    const visit = (entity) => {
+        ids.add(entity.id);
+        entity.children.forEach(visit);
+    };
+    visit(root);
+    return ids;
+}
+/** Finds existing direct children that a replacement write omitted. */
+function collectOmittedChildIDs(db, desiredChildrenByParent, submittedIDs) {
+    const omitted = new Set();
+    for (const [parentID, desiredChildren] of desiredChildrenByParent) {
+        const desiredChildIDs = new Set(desiredChildren.map((child) => child.id));
+        for (const child of getDirectEntityChildren(db, parentID)) {
+            if (!desiredChildIDs.has(child.id) && !submittedIDs.has(child.id)) {
+                omitted.add(child.id);
+            }
+        }
+    }
+    return [...omitted];
+}
+/** Deletes omitted children after moved descendants have been reparented. */
+function deleteOmittedEntitySubtrees(db, rootIDs) {
+    const deleted = new Set();
+    for (const rootID of rootIDs) {
+        if (deleted.has(rootID) || getStoredNodeType(db, rootID) === undefined) {
+            continue;
+        }
+        const ids = collectEntitySubtreeIDs(db, rootID);
+        deleteStoredNodes(db, ids);
+        ids.forEach((id) => deleted.add(id));
+    }
+}
+/** Collects one entity and all of its recursive containment descendants. */
+function collectEntitySubtreeIDs(db, rootID) {
+    const ids = [];
+    const visited = new Set();
+    const visit = (id) => {
+        if (visited.has(id)) {
+            throw new Error(`Entity cycle detected at ${id}`);
+        }
+        visited.add(id);
+        ids.push(id);
+        for (const child of getDirectEntityChildren(db, id)) {
+            visit(child.id);
+        }
+    };
+    visit(rootID);
+    return ids;
+}

package/dist/src/storage/types.d.ts

@@ -0,0 +1,15 @@
+import type { BlockMetadata } from "../types/block";
+import type { DatabaseID } from "../types/database";
+import type { EntityID, EntityType } from "../types/graph";
+import type { ObjMetadata } from "../types/object";
+export type StoredEntityType = "database" | EntityType;
+export type StoredEntityID = DatabaseID | EntityID;
+export interface StoredEntityReference {
+    readonly type: StoredEntityType;
+    readonly id: StoredEntityID;
+}
+export type StoredObject = ObjMetadata;
+export interface StoredBlock extends BlockMetadata {
+    content: string;
+}
+export type StoredEntity = StoredObject | StoredBlock;

package/dist/src/storage/types.js

@@ -0,0 +1 @@
+// This file defines the internal stored rows for concrete entity tables.

package/dist/src/types/block.d.ts

@@ -0,0 +1,12 @@
+import type { Entity } from "./graph";
+import type { JSONRecord } from "./json";
+export type BlockID = string;
+export interface BlockMetadata {
+    readonly id: BlockID;
+    readonly type: "block";
+    properties?: JSONRecord;
+}
+export interface Block extends BlockMetadata {
+    content: string;
+    children: Entity[];
+}

package/dist/src/types/database.d.ts

@@ -0,0 +1,6 @@
+export type DatabaseID = string;
+export interface DBMetadata {
+    readonly id: DatabaseID;
+    name?: string;
+    schemaVersion: string;
+}

package/dist/src/types/graph.d.ts

@@ -0,0 +1,11 @@
+import type { Block, BlockID } from "./block";
+import type { Obj, ObjID } from "./object";
+import type { WorkspaceID } from "./workspace";
+export type EntityType = "object" | "block";
+export type EntityID = ObjID | BlockID;
+export type Entity = Obj | Block;
+export interface EntityReference {
+    readonly type: EntityType;
+    readonly id: EntityID;
+}
+export type EntityParentID = WorkspaceID | EntityID | null;

package/dist/src/types/json.d.ts

@@ -0,0 +1,7 @@
+export type JSONPrimitive = string | number | boolean | null;
+export type JSONValue = JSONPrimitive | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+export type JSONRecord = {
+    [key: string]: JSONValue;
+};

package/dist/src/types/object.d.ts

@@ -0,0 +1,12 @@
+import type { Entity } from "./graph";
+import type { JSONRecord } from "./json";
+export type ObjID = string;
+export interface ObjMetadata {
+    readonly id: ObjID;
+    readonly type: "object";
+    name: string;
+    properties?: JSONRecord;
+}
+export interface Obj extends ObjMetadata {
+    children: Entity[];
+}

package/dist/src/types/workspace.d.ts

@@ -0,0 +1,6 @@
+export type WorkspaceID = string;
+export interface WorkspaceMetadata {
+    readonly id: WorkspaceID;
+    name?: string;
+    schemaVersion: string;
+}

package/dist/src/utils/id.d.ts

@@ -0,0 +1,6 @@
+export declare const ObjectPrefix: string;
+export declare const BlockPrefix: string;
+export declare const DatabasePrefix: string;
+export declare function createObjID(): string;
+export declare function createBlockID(): string;
+export declare function createDatabaseID(): string;

package/dist/src/utils/id.js

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+export const ObjectPrefix = "o";
+export const BlockPrefix = "b";
+export const DatabasePrefix = "d";
+// HELPER: Creates a unique ID with the given prefix
+function createID(prefix) {
+    const random = randomUUID().replaceAll("-", "");
+    return `${prefix}_${random}`;
+}
+export function createObjID() {
+    return createID(ObjectPrefix);
+}
+export function createBlockID() {
+    return createID(BlockPrefix);
+}
+export function createDatabaseID() {
+    return createID(DatabasePrefix);
+}

package/dist/src/utils/yaml.d.ts

@@ -0,0 +1,3 @@
+import type { ObjMetadata } from "../types/object";
+export declare function renderFrontmatter(frontmatter: ObjMetadata): string;
+export declare function parseFrontmatter<T>(markdown: string): T;