@aigne/afs-sqlite 1.0.1-beta

package/lib/esm/router/path-router.js

@@ -0,0 +1,83 @@
+import { createRouter } from "radix3";
+/**
+ * Creates a radix3 router for SQLite AFS path routing
+ *
+ * Routes:
+ * - / → listTables
+ * - /:table → listTable
+ * - /:table/new → createRow
+ * - /:table/@schema → getSchema
+ * - /:table/:pk → readRow
+ * - /:table/:pk/@attr → listAttributes
+ * - /:table/:pk/@attr/:column → getAttribute
+ * - /:table/:pk/@meta → getMeta
+ * - /:table/:pk/@actions → listActions
+ * - /:table/:pk/@actions/:action → executeAction
+ */
+export function createPathRouter() {
+    return createRouter({
+        routes: {
+            // Root - list all tables
+            "/": { action: "listTables" },
+            // Table-level routes
+            "/:table": { action: "listTable" },
+            "/:table/new": { action: "createRow" },
+            "/:table/@schema": { action: "getSchema" },
+            // Row-level routes
+            "/:table/:pk": { action: "readRow" },
+            "/:table/:pk/@attr": { action: "listAttributes" },
+            "/:table/:pk/@attr/:column": { action: "getAttribute" },
+            "/:table/:pk/@meta": { action: "getMeta" },
+            "/:table/:pk/@actions": { action: "listActions" },
+            "/:table/:pk/@actions/:action": { action: "executeAction" },
+        },
+    });
+}
+/**
+ * Parses a path and returns the matched route with params
+ * @param router - The radix3 router instance
+ * @param path - The path to match
+ * @returns RouteMatch if matched, undefined otherwise
+ */
+export function matchPath(router, path) {
+    const result = router.lookup(path);
+    if (!result)
+        return undefined;
+    return {
+        action: result.action,
+        params: (result.params ?? {}),
+    };
+}
+/**
+ * Builds a path from components
+ */
+export function buildPath(table, pk, suffix) {
+    const parts = ["/"];
+    if (table)
+        parts.push(table);
+    if (pk)
+        parts.push(pk);
+    if (suffix)
+        parts.push(suffix);
+    return parts.join("/").replace(/\/+/g, "/");
+}
+/**
+ * Checks if a path segment is a virtual path (@attr, @meta, @actions, @schema)
+ */
+export function isVirtualPath(segment) {
+    return segment.startsWith("@");
+}
+/**
+ * Gets the type of virtual path
+ */
+export function getVirtualPathType(segment) {
+    if (segment === "@attr")
+        return "attr";
+    if (segment === "@meta")
+        return "meta";
+    if (segment === "@actions")
+        return "actions";
+    if (segment === "@schema")
+        return "schema";
+    return null;
+}

package/lib/esm/router/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Route action types for SQLite AFS
+ */
+export type RouteAction = "listTables" | "listTable" | "readRow" | "createRow" | "getSchema" | "listAttributes" | "getAttribute" | "getMeta" | "listActions" | "executeAction";
+/**
+ * Route data associated with each path pattern
+ */
+export interface RouteData {
+    /** The action to perform for this route */
+    action: RouteAction;
+}
+/**
+ * Route match result with params
+ */
+export interface RouteMatch extends RouteData {
+    params: RouteParams;
+}
+/**
+ * Dynamic route parameters extracted from path
+ */
+export interface RouteParams {
+    /** Table name */
+    table?: string;
+    /** Primary key value */
+    pk?: string;
+    /** Column name for attribute access */
+    column?: string;
+    /** Action name for @actions */
+    action?: string;
+}

package/lib/esm/router/types.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/schema/introspector.d.ts

@@ -0,0 +1,48 @@
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import { type TableSchema } from "./types.js";
+/**
+ * Schema introspector that uses SQLite PRAGMA queries to discover database schema
+ */
+export declare class SchemaIntrospector {
+    /**
+     * Introspects all tables in the database
+     * @param db - Drizzle database instance
+     * @param options - Introspection options
+     * @returns Map of table name to TableSchema
+     */
+    introspect(db: LibSQLDatabase, options?: {
+        /** Whitelist of tables to include */
+        tables?: string[];
+        /** Tables to exclude */
+        excludeTables?: string[];
+    }): Promise<Map<string, TableSchema>>;
+    /**
+     * Introspects a single table
+     * @param db - Drizzle database instance
+     * @param tableName - Name of the table to introspect
+     * @returns TableSchema for the specified table
+     */
+    introspectTable(db: LibSQLDatabase, tableName: string): Promise<TableSchema>;
+    /**
+     * Gets the primary key column name for a table
+     * Returns the first PK column, or 'rowid' if no explicit PK
+     */
+    getPrimaryKeyColumn(schema: TableSchema): string;
+    /**
+     * Checks if a table has FTS (Full-Text Search) enabled
+     */
+    hasFTS(db: LibSQLDatabase, tableName: string): Promise<boolean>;
+    /**
+     * Creates FTS5 table for full-text search on specified columns
+     */
+    createFTS(db: LibSQLDatabase, tableName: string, columns: string[], options?: {
+        /** Content table (defaults to tableName) */
+        contentTable?: string;
+        /** Content rowid column (defaults to 'rowid') */
+        contentRowid?: string;
+    }): Promise<void>;
+    /**
+     * Rebuilds FTS index for a table (useful after bulk inserts)
+     */
+    rebuildFTS(db: LibSQLDatabase, tableName: string): Promise<void>;
+}

package/lib/esm/schema/introspector.js

@@ -0,0 +1,182 @@
+import { sql } from "@aigne/sqlite";
+import { SYSTEM_TABLES, } from "./types.js";
+/**
+ * Executes a raw SQL query and returns all rows
+ */
+async function execAll(db, query) {
+    return db.all(sql.raw(query)).execute();
+}
+/**
+ * Executes a raw SQL query (for INSERT, UPDATE, DELETE)
+ */
+async function execRun(db, query) {
+    await db.run(sql.raw(query)).execute();
+}
+/**
+ * Maps raw PRAGMA table_info row to ColumnInfo
+ */
+function mapColumn(row) {
+    return {
+        name: row.name,
+        type: row.type,
+        notnull: row.notnull === 1,
+        pk: row.pk,
+        dfltValue: row.dflt_value,
+    };
+}
+/**
+ * Maps raw PRAGMA foreign_key_list row to ForeignKeyInfo
+ */
+function mapForeignKey(row) {
+    return {
+        id: row.id,
+        seq: row.seq,
+        table: row.table,
+        from: row.from,
+        to: row.to,
+        onUpdate: row.on_update,
+        onDelete: row.on_delete,
+        match: row.match,
+    };
+}
+/**
+ * Maps raw PRAGMA index_list row to IndexInfo
+ */
+function mapIndex(row) {
+    return {
+        seq: row.seq,
+        name: row.name,
+        unique: row.unique === 1,
+        origin: row.origin,
+        partial: row.partial === 1,
+    };
+}
+/**
+ * Schema introspector that uses SQLite PRAGMA queries to discover database schema
+ */
+export class SchemaIntrospector {
+    /**
+     * Introspects all tables in the database
+     * @param db - Drizzle database instance
+     * @param options - Introspection options
+     * @returns Map of table name to TableSchema
+     */
+    async introspect(db, options) {
+        const schemas = new Map();
+        // Get all user tables (exclude system tables and FTS tables)
+        const tablesResult = await execAll(db, `
+      SELECT name FROM sqlite_master
+      WHERE type = 'table'
+      AND name NOT LIKE 'sqlite_%'
+      AND name NOT LIKE '%_fts%'
+      ORDER BY name
+    `);
+        for (const { name } of tablesResult) {
+            // Skip system tables
+            if (SYSTEM_TABLES.includes(name)) {
+                continue;
+            }
+            // Apply whitelist filter
+            if (options?.tables && !options.tables.includes(name)) {
+                continue;
+            }
+            // Apply exclude filter
+            if (options?.excludeTables?.includes(name)) {
+                continue;
+            }
+            const schema = await this.introspectTable(db, name);
+            schemas.set(name, schema);
+        }
+        return schemas;
+    }
+    /**
+     * Introspects a single table
+     * @param db - Drizzle database instance
+     * @param tableName - Name of the table to introspect
+     * @returns TableSchema for the specified table
+     */
+    async introspectTable(db, tableName) {
+        // Get column information
+        const columnsResult = await execAll(db, `PRAGMA table_info("${tableName}")`);
+        const columns = columnsResult.map(mapColumn);
+        // Get primary key columns (pk > 0 indicates part of primary key)
+        const primaryKey = columns.filter((c) => c.pk > 0).map((c) => c.name);
+        // Get foreign keys
+        const fksResult = await execAll(db, `PRAGMA foreign_key_list("${tableName}")`);
+        const foreignKeys = fksResult.map(mapForeignKey);
+        // Get indexes
+        const indexesResult = await execAll(db, `PRAGMA index_list("${tableName}")`);
+        const indexes = indexesResult.map(mapIndex);
+        return {
+            name: tableName,
+            columns,
+            primaryKey,
+            foreignKeys,
+            indexes,
+        };
+    }
+    /**
+     * Gets the primary key column name for a table
+     * Returns the first PK column, or 'rowid' if no explicit PK
+     */
+    getPrimaryKeyColumn(schema) {
+        if (schema.primaryKey.length > 0 && schema.primaryKey[0]) {
+            return schema.primaryKey[0];
+        }
+        // SQLite tables without explicit PK use rowid
+        return "rowid";
+    }
+    /**
+     * Checks if a table has FTS (Full-Text Search) enabled
+     */
+    async hasFTS(db, tableName) {
+        const ftsTableName = `${tableName}_fts`;
+        const result = await execAll(db, `
+      SELECT name FROM sqlite_master
+      WHERE type = 'table'
+      AND name = '${ftsTableName}'
+    `);
+        return result.length > 0;
+    }
+    /**
+     * Creates FTS5 table for full-text search on specified columns
+     */
+    async createFTS(db, tableName, columns, options) {
+        const ftsTableName = `${tableName}_fts`;
+        const contentTable = options?.contentTable ?? tableName;
+        const contentRowid = options?.contentRowid ?? "rowid";
+        const columnList = columns.join(", ");
+        // Create FTS5 virtual table
+        await execRun(db, `
+      CREATE VIRTUAL TABLE IF NOT EXISTS "${ftsTableName}" USING fts5(
+        ${columnList},
+        content="${contentTable}",
+        content_rowid="${contentRowid}"
+      )
+    `);
+        // Create triggers to keep FTS in sync
+        await execRun(db, `
+      CREATE TRIGGER IF NOT EXISTS "${tableName}_ai" AFTER INSERT ON "${tableName}" BEGIN
+        INSERT INTO "${ftsTableName}"(rowid, ${columnList}) VALUES (new.${contentRowid}, ${columns.map((c) => `new."${c}"`).join(", ")});
+      END
+    `);
+        await execRun(db, `
+      CREATE TRIGGER IF NOT EXISTS "${tableName}_ad" AFTER DELETE ON "${tableName}" BEGIN
+        INSERT INTO "${ftsTableName}"("${ftsTableName}", rowid, ${columnList}) VALUES ('delete', old.${contentRowid}, ${columns.map((c) => `old."${c}"`).join(", ")});
+      END
+    `);
+        await execRun(db, `
+      CREATE TRIGGER IF NOT EXISTS "${tableName}_au" AFTER UPDATE ON "${tableName}" BEGIN
+        INSERT INTO "${ftsTableName}"("${ftsTableName}", rowid, ${columnList}) VALUES ('delete', old.${contentRowid}, ${columns.map((c) => `old."${c}"`).join(", ")});
+        INSERT INTO "${ftsTableName}"(rowid, ${columnList}) VALUES (new.${contentRowid}, ${columns.map((c) => `new."${c}"`).join(", ")});
+      END
+    `);
+    }
+    /**
+     * Rebuilds FTS index for a table (useful after bulk inserts)
+     */
+    async rebuildFTS(db, tableName) {
+        const ftsTableName = `${tableName}_fts`;
+        await execRun(db, `INSERT INTO "${ftsTableName}"("${ftsTableName}") VALUES ('rebuild')`);
+    }
+}

package/lib/esm/schema/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Column information from SQLite PRAGMA table_info
+ */
+export interface ColumnInfo {
+    /** Column name */
+    name: string;
+    /** SQLite type (INTEGER, TEXT, REAL, BLOB, etc.) */
+    type: string;
+    /** Whether the column has NOT NULL constraint */
+    notnull: boolean;
+    /** Whether this column is part of the primary key */
+    pk: number;
+    /** Default value for the column */
+    dfltValue: unknown;
+}
+/**
+ * Foreign key information from SQLite PRAGMA foreign_key_list
+ */
+export interface ForeignKeyInfo {
+    /** Foreign key id */
+    id: number;
+    /** Sequence number for composite foreign keys */
+    seq: number;
+    /** Referenced table */
+    table: string;
+    /** Column in this table */
+    from: string;
+    /** Column in referenced table */
+    to: string;
+    /** ON UPDATE action */
+    onUpdate: string;
+    /** ON DELETE action */
+    onDelete: string;
+    /** MATCH clause */
+    match: string;
+}
+/**
+ * Index information from SQLite PRAGMA index_list
+ */
+export interface IndexInfo {
+    /** Index sequence number */
+    seq: number;
+    /** Index name */
+    name: string;
+    /** Whether this is a unique index */
+    unique: boolean;
+    /** Origin of the index (c = CREATE INDEX, u = UNIQUE constraint, pk = PRIMARY KEY) */
+    origin: string;
+    /** Whether the index is partial */
+    partial: boolean;
+}
+/**
+ * Complete schema information for a single table
+ */
+export interface TableSchema {
+    /** Table name */
+    name: string;
+    /** Column definitions */
+    columns: ColumnInfo[];
+    /** Primary key column names */
+    primaryKey: string[];
+    /** Foreign key relationships */
+    foreignKeys: ForeignKeyInfo[];
+    /** Indexes on this table */
+    indexes: IndexInfo[];
+}
+/**
+ * Raw PRAGMA table_info result row
+ */
+export interface PragmaTableInfoRow {
+    cid: number;
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: unknown;
+    pk: number;
+}
+/**
+ * Raw PRAGMA foreign_key_list result row
+ */
+export interface PragmaForeignKeyRow {
+    id: number;
+    seq: number;
+    table: string;
+    from: string;
+    to: string;
+    on_update: string;
+    on_delete: string;
+    match: string;
+}
+/**
+ * Raw PRAGMA index_list result row
+ */
+export interface PragmaIndexListRow {
+    seq: number;
+    name: string;
+    unique: number;
+    origin: string;
+    partial: number;
+}
+/**
+ * System tables that should be excluded from introspection
+ */
+export declare const SYSTEM_TABLES: readonly ["sqlite_sequence", "sqlite_stat1", "sqlite_stat2", "sqlite_stat3", "sqlite_stat4"];

package/lib/esm/schema/types.js

@@ -0,0 +1,10 @@
+/**
+ * System tables that should be excluded from introspection
+ */
+export const SYSTEM_TABLES = [
+    "sqlite_sequence",
+    "sqlite_stat1",
+    "sqlite_stat2",
+    "sqlite_stat3",
+    "sqlite_stat4",
+];

package/lib/esm/sqlite-afs.d.ts

@@ -0,0 +1,144 @@
+import type { AFSAccessMode, AFSDeleteOptions, AFSDeleteResult, AFSExecOptions, AFSExecResult, AFSListOptions, AFSListResult, AFSModule, AFSModuleLoadParams, AFSReadOptions, AFSReadResult, AFSRoot, AFSSearchOptions, AFSSearchResult, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "@aigne/afs";
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import type { ActionContext } from "./actions/types.js";
+import { type SQLiteAFSOptions } from "./config.js";
+import type { TableSchema } from "./schema/types.js";
+/**
+ * SQLite AFS Module
+ *
+ * Exposes SQLite databases as AFS nodes with full CRUD support,
+ * schema introspection, FTS5 search, and virtual paths (@attr, @meta, @actions).
+ */
+export declare class SQLiteAFS implements AFSModule {
+    private options;
+    readonly name: string;
+    readonly description: string;
+    readonly accessMode: AFSAccessMode;
+    private db;
+    private schemas;
+    private router;
+    private crud;
+    private ftsSearch;
+    private actions;
+    private ftsConfig;
+    private initialized;
+    constructor(options: SQLiteAFSOptions);
+    /**
+     * Returns the Zod schema for configuration validation
+     */
+    static schema(): import("zod").ZodObject<{
+        url: import("zod").ZodString;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+        accessMode: import("zod").ZodOptional<import("zod").ZodEnum<["readonly", "readwrite"]>>;
+        tables: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+        excludeTables: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+        fts: import("zod").ZodOptional<import("zod").ZodObject<{
+            enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+            tables: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodArray<import("zod").ZodString, "many">>>;
+        }, "strip", import("zod").ZodTypeAny, {
+            enabled: boolean;
+            tables?: Record<string, string[]> | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            tables?: Record<string, string[]> | undefined;
+        }>>;
+        wal: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
+    }, "strip", import("zod").ZodTypeAny, {
+        url: string;
+        wal: boolean;
+        tables?: string[] | undefined;
+        name?: string | undefined;
+        description?: string | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        excludeTables?: string[] | undefined;
+        fts?: {
+            enabled: boolean;
+            tables?: Record<string, string[]> | undefined;
+        } | undefined;
+    }, {
+        url: string;
+        tables?: string[] | undefined;
+        name?: string | undefined;
+        description?: string | undefined;
+        accessMode?: "readonly" | "readwrite" | undefined;
+        excludeTables?: string[] | undefined;
+        fts?: {
+            enabled?: boolean | undefined;
+            tables?: Record<string, string[]> | undefined;
+        } | undefined;
+        wal?: boolean | undefined;
+    }>;
+    /**
+     * Loads a module instance from configuration
+     */
+    static load({ parsed }: AFSModuleLoadParams): Promise<SQLiteAFS>;
+    /**
+     * Called when the module is mounted to AFS
+     */
+    onMount(_afs: AFSRoot): Promise<void>;
+    /**
+     * Initializes the database connection and introspects schema
+     */
+    private initialize;
+    /**
+     * Ensures the module is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Lists entries at a path
+     */
+    list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+    /**
+     * Reads an entry at a path
+     */
+    read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
+    /**
+     * Writes an entry at a path
+     */
+    write(path: string, content: AFSWriteEntryPayload, _options?: AFSWriteOptions): Promise<AFSWriteResult>;
+    /**
+     * Deletes an entry at a path
+     */
+    delete(path: string, _options?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+    /**
+     * Searches for entries matching a query
+     */
+    search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+    /**
+     * Executes a module operation
+     */
+    exec(path: string, args: Record<string, unknown>, _options: AFSExecOptions): Promise<AFSExecResult>;
+    /**
+     * Lists available actions for a row
+     */
+    private listActions;
+    /**
+     * Executes an action
+     */
+    private executeAction;
+    /**
+     * Refreshes the schema cache
+     */
+    refreshSchema(): Promise<void>;
+    /**
+     * Exports table data in specified format
+     */
+    exportTable(table: string, format: string): Promise<unknown>;
+    /**
+     * Registers a custom action
+     */
+    registerAction(name: string, handler: (ctx: ActionContext, params: Record<string, unknown>) => Promise<unknown>, options?: {
+        description?: string;
+        tableLevel?: boolean;
+        rowLevel?: boolean;
+    }): void;
+    /**
+     * Gets table schemas (for external access)
+     */
+    getSchemas(): Map<string, TableSchema>;
+    /**
+     * Gets the database instance (for advanced operations)
+     */
+    getDatabase(): LibSQLDatabase;
+}