@aigne/afs-sqlite 1.0.1-beta

package/lib/cjs/sqlite-afs.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLiteAFS = void 0;
+const sqlite_1 = require("@aigne/sqlite");
+const built_in_js_1 = require("./actions/built-in.js");
+const registry_js_1 = require("./actions/registry.js");
+const config_js_1 = require("./config.js");
+const builder_js_1 = require("./node/builder.js");
+const crud_js_1 = require("./operations/crud.js");
+const search_js_1 = require("./operations/search.js");
+const path_router_js_1 = require("./router/path-router.js");
+const introspector_js_1 = require("./schema/introspector.js");
+/**
+ * SQLite AFS Module
+ *
+ * Exposes SQLite databases as AFS nodes with full CRUD support,
+ * schema introspection, FTS5 search, and virtual paths (@attr, @meta, @actions).
+ */
+class SQLiteAFS {
+    options;
+    name;
+    description;
+    accessMode;
+    db;
+    schemas = new Map();
+    router;
+    crud;
+    ftsSearch;
+    actions;
+    ftsConfig;
+    initialized = false;
+    constructor(options) {
+        this.options = options;
+        this.name = options.name ?? "sqlite-afs";
+        this.description = options.description ?? `SQLite database: ${options.url}`;
+        this.accessMode = options.accessMode ?? "readwrite";
+        this.ftsConfig = (0, search_js_1.createFTSConfig)(options.fts);
+        this.actions = new registry_js_1.ActionsRegistry();
+        (0, built_in_js_1.registerBuiltInActions)(this.actions);
+    }
+    /**
+     * Returns the Zod schema for configuration validation
+     */
+    static schema() {
+        return config_js_1.sqliteAFSConfigSchema;
+    }
+    /**
+     * Loads a module instance from configuration
+     */
+    static async load({ parsed }) {
+        const validated = config_js_1.sqliteAFSConfigSchema.parse(parsed);
+        return new SQLiteAFS(validated);
+    }
+    /**
+     * Called when the module is mounted to AFS
+     */
+    async onMount(_afs) {
+        await this.initialize();
+    }
+    /**
+     * Initializes the database connection and introspects schema
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Initialize database connection
+        this.db = await (0, sqlite_1.initDatabase)({
+            url: this.options.url,
+            wal: this.options.wal ?? true,
+        });
+        // Cast db to LibSQLDatabase for operations
+        const db = this.db;
+        // Introspect database schema
+        const introspector = new introspector_js_1.SchemaIntrospector();
+        this.schemas = await introspector.introspect(db, {
+            tables: this.options.tables,
+            excludeTables: this.options.excludeTables,
+        });
+        // Initialize components
+        this.router = (0, path_router_js_1.createPathRouter)();
+        this.crud = new crud_js_1.CRUDOperations(db, this.schemas, "");
+        this.ftsSearch = new search_js_1.FTSSearch(db, this.schemas, this.ftsConfig, "");
+        this.initialized = true;
+    }
+    /**
+     * Ensures the module is initialized
+     */
+    async ensureInitialized() {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+    }
+    /**
+     * Lists entries at a path
+     */
+    async list(path, options) {
+        await this.ensureInitialized();
+        const match = (0, path_router_js_1.matchPath)(this.router, path);
+        if (!match) {
+            return { data: [] };
+        }
+        switch (match.action) {
+            case "listTables":
+                return this.crud.listTables();
+            case "listTable":
+                if (!match.params.table)
+                    return { data: [] };
+                return this.crud.listTable(match.params.table, options);
+            case "listAttributes":
+                if (!match.params.table || !match.params.pk)
+                    return { data: [] };
+                return this.crud.listAttributes(match.params.table, match.params.pk);
+            case "listActions":
+                if (!match.params.table || !match.params.pk)
+                    return { data: [] };
+                return this.listActions(match.params.table, match.params.pk);
+            default:
+                return { data: [] };
+        }
+    }
+    /**
+     * Reads an entry at a path
+     */
+    async read(path, _options) {
+        await this.ensureInitialized();
+        const match = (0, path_router_js_1.matchPath)(this.router, path);
+        if (!match) {
+            return {};
+        }
+        switch (match.action) {
+            case "readRow":
+                if (!match.params.table || !match.params.pk)
+                    return {};
+                return this.crud.readRow(match.params.table, match.params.pk);
+            case "getSchema":
+                if (!match.params.table)
+                    return {};
+                return this.crud.getSchema(match.params.table);
+            case "getAttribute":
+                if (!match.params.table || !match.params.pk || !match.params.column)
+                    return {};
+                return this.crud.getAttribute(match.params.table, match.params.pk, match.params.column);
+            case "getMeta":
+                if (!match.params.table || !match.params.pk)
+                    return {};
+                return this.crud.getMeta(match.params.table, match.params.pk);
+            default:
+                return {};
+        }
+    }
+    /**
+     * Writes an entry at a path
+     */
+    async write(path, content, _options) {
+        await this.ensureInitialized();
+        if (this.accessMode === "readonly") {
+            throw new Error("Module is in readonly mode");
+        }
+        const match = (0, path_router_js_1.matchPath)(this.router, path);
+        if (!match) {
+            throw new Error(`Invalid path: ${path}`);
+        }
+        switch (match.action) {
+            case "createRow":
+                if (!match.params.table) {
+                    throw new Error("Table name required for create");
+                }
+                return this.crud.createRow(match.params.table, content.content ?? content);
+            case "readRow":
+                if (!match.params.table || !match.params.pk) {
+                    throw new Error("Table and primary key required for update");
+                }
+                return this.crud.updateRow(match.params.table, match.params.pk, content.content ?? content);
+            case "executeAction":
+                if (!match.params.table || !match.params.action) {
+                    throw new Error("Table and action name required");
+                }
+                return this.executeAction(match.params.table, match.params.pk, match.params.action, content.content ?? content);
+            default:
+                throw new Error(`Write not supported for path: ${path}`);
+        }
+    }
+    /**
+     * Deletes an entry at a path
+     */
+    async delete(path, _options) {
+        await this.ensureInitialized();
+        if (this.accessMode === "readonly") {
+            throw new Error("Module is in readonly mode");
+        }
+        const match = (0, path_router_js_1.matchPath)(this.router, path);
+        if (!match || match.action !== "readRow") {
+            throw new Error(`Delete not supported for path: ${path}`);
+        }
+        if (!match.params.table || !match.params.pk) {
+            throw new Error("Table and primary key required for delete");
+        }
+        return this.crud.deleteRow(match.params.table, match.params.pk);
+    }
+    /**
+     * Searches for entries matching a query
+     */
+    async search(path, query, options) {
+        await this.ensureInitialized();
+        // If path specifies a table, search only that table
+        const match = (0, path_router_js_1.matchPath)(this.router, path);
+        if (match?.params.table) {
+            return this.ftsSearch.searchTable(match.params.table, query, options);
+        }
+        // Otherwise search all FTS-enabled tables
+        return this.ftsSearch.search(query, options);
+    }
+    /**
+     * Executes a module operation
+     */
+    async exec(path, args, _options) {
+        await this.ensureInitialized();
+        const match = (0, path_router_js_1.matchPath)(this.router, path);
+        if (match?.action === "executeAction" && match.params.table && match.params.action) {
+            const result = await this.executeAction(match.params.table, match.params.pk, match.params.action, args);
+            return { data: result.data };
+        }
+        throw new Error(`Exec not supported for path: ${path}`);
+    }
+    /**
+     * Lists available actions for a row
+     */
+    listActions(table, pk) {
+        const actionNames = this.actions.listNames({ rowLevel: true });
+        return {
+            data: (0, builder_js_1.buildActionsListEntry)(table, pk, actionNames, { basePath: "" }),
+        };
+    }
+    /**
+     * Executes an action
+     */
+    async executeAction(table, pk, actionName, params) {
+        const schema = this.schemas.get(table);
+        if (!schema) {
+            throw new Error(`Table '${table}' not found`);
+        }
+        // Get row data if pk is provided
+        let row;
+        if (pk) {
+            const readResult = await this.crud.readRow(table, pk);
+            row = readResult.data?.content;
+        }
+        const ctx = {
+            db: this.db,
+            schemas: this.schemas,
+            table,
+            pk,
+            row,
+            module: {
+                refreshSchema: () => this.refreshSchema(),
+                exportTable: (t, f) => this.exportTable(t, f),
+            },
+        };
+        const result = await this.actions.execute(actionName, ctx, params);
+        if (!result.success) {
+            throw new Error(result.message ?? "Action failed");
+        }
+        return {
+            data: {
+                id: `${table}:${pk ?? ""}:@actions:${actionName}`,
+                path: pk ? `/${table}/${pk}/@actions/${actionName}` : `/${table}/@actions/${actionName}`,
+                content: result.data,
+            },
+        };
+    }
+    /**
+     * Refreshes the schema cache
+     */
+    async refreshSchema() {
+        const db = this.db;
+        const introspector = new introspector_js_1.SchemaIntrospector();
+        this.schemas = await introspector.introspect(db, {
+            tables: this.options.tables,
+            excludeTables: this.options.excludeTables,
+        });
+        this.crud.setSchemas(this.schemas);
+        this.ftsSearch.setSchemas(this.schemas);
+    }
+    /**
+     * Exports table data in specified format
+     */
+    async exportTable(table, format) {
+        const listResult = await this.crud.listTable(table, { limit: 10000 });
+        if (format === "csv") {
+            const schema = this.schemas.get(table);
+            if (!schema)
+                throw new Error(`Table '${table}' not found`);
+            const headers = schema.columns.map((c) => c.name).join(",");
+            const rows = listResult.data.map((entry) => {
+                const content = entry.content;
+                return schema.columns
+                    .map((c) => {
+                    const val = content[c.name];
+                    if (val === null || val === undefined)
+                        return "";
+                    if (typeof val === "string" && (val.includes(",") || val.includes('"'))) {
+                        return `"${val.replace(/"/g, '""')}"`;
+                    }
+                    return String(val);
+                })
+                    .join(",");
+            });
+            return `${headers}\n${rows.join("\n")}`;
+        }
+        // Default: JSON
+        return listResult.data.map((entry) => entry.content);
+    }
+    /**
+     * Registers a custom action
+     */
+    registerAction(name, handler, options) {
+        this.actions.registerSimple(name, async (ctx, params) => ({
+            success: true,
+            data: await handler(ctx, params),
+        }), options);
+    }
+    /**
+     * Gets table schemas (for external access)
+     */
+    getSchemas() {
+        return this.schemas;
+    }
+    /**
+     * Gets the database instance (for advanced operations)
+     */
+    getDatabase() {
+        return this.db;
+    }
+}
+exports.SQLiteAFS = SQLiteAFS;
+// Type check to ensure SQLiteAFS implements AFSModuleClass
+const _typeCheck = SQLiteAFS;

package/lib/dts/actions/built-in.d.ts

@@ -0,0 +1,5 @@
+import type { ActionsRegistry } from "./registry.js";
+/**
+ * Registers built-in actions to the registry
+ */
+export declare function registerBuiltInActions(registry: ActionsRegistry): void;

package/lib/dts/actions/registry.d.ts

@@ -0,0 +1,49 @@
+import type { ActionContext, ActionDefinition, ActionHandler, ActionResult } from "./types.js";
+/**
+ * Registry for managing action handlers
+ */
+export declare class ActionsRegistry {
+    private handlers;
+    /**
+     * Registers an action handler
+     */
+    register(definition: ActionDefinition): void;
+    /**
+     * Registers a simple action with just name and handler
+     */
+    registerSimple(name: string, handler: ActionHandler, options?: {
+        description?: string;
+        tableLevel?: boolean;
+        rowLevel?: boolean;
+    }): void;
+    /**
+     * Unregisters an action
+     */
+    unregister(name: string): boolean;
+    /**
+     * Checks if an action is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Gets an action definition
+     */
+    get(name: string): ActionDefinition | undefined;
+    /**
+     * Lists all registered actions
+     */
+    list(options?: {
+        tableLevel?: boolean;
+        rowLevel?: boolean;
+    }): ActionDefinition[];
+    /**
+     * Lists action names
+     */
+    listNames(options?: {
+        tableLevel?: boolean;
+        rowLevel?: boolean;
+    }): string[];
+    /**
+     * Executes an action
+     */
+    execute(name: string, ctx: ActionContext, params?: Record<string, unknown>): Promise<ActionResult>;
+}

package/lib/dts/actions/types.d.ts

@@ -0,0 +1,51 @@
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import type { TableSchema } from "../schema/types.js";
+/**
+ * Context provided to action handlers
+ */
+export interface ActionContext {
+    /** Database instance */
+    db: LibSQLDatabase;
+    /** All table schemas */
+    schemas: Map<string, TableSchema>;
+    /** Table this action is being executed on */
+    table: string;
+    /** Primary key of the row (if row-level action) */
+    pk?: string;
+    /** The row data (if available) */
+    row?: Record<string, unknown>;
+    /** Reference to the parent module for advanced operations */
+    module: {
+        refreshSchema(): Promise<void>;
+        exportTable(table: string, format: string): Promise<unknown>;
+    };
+}
+/**
+ * Action handler function signature
+ */
+export type ActionHandler = (ctx: ActionContext, params: Record<string, unknown>) => Promise<ActionResult>;
+/**
+ * Result from an action execution
+ */
+export interface ActionResult {
+    success: boolean;
+    data?: unknown;
+    message?: string;
+}
+/**
+ * Action definition with metadata
+ */
+export interface ActionDefinition {
+    /** Action name */
+    name: string;
+    /** Description of what the action does */
+    description?: string;
+    /** Whether this action is available at table level (vs row level) */
+    tableLevel?: boolean;
+    /** Whether this action is available at row level */
+    rowLevel?: boolean;
+    /** Input schema for the action parameters */
+    inputSchema?: Record<string, unknown>;
+    /** The handler function */
+    handler: ActionHandler;
+}

package/lib/dts/config.d.ts

@@ -0,0 +1,89 @@
+import { type AFSAccessMode } from "@aigne/afs";
+import { z } from "zod";
+/**
+ * FTS (Full-Text Search) configuration schema
+ */
+export declare const ftsConfigSchema: z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    tables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    tables?: Record<string, string[]> | undefined;
+}, {
+    enabled?: boolean | undefined;
+    tables?: Record<string, string[]> | undefined;
+}>>;
+/**
+ * SQLite AFS module configuration schema
+ */
+export declare const sqliteAFSConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    accessMode: z.ZodOptional<z.ZodEnum<["readonly", "readwrite"]>>;
+    tables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    excludeTables: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    fts: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        tables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        tables?: Record<string, string[]> | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        tables?: Record<string, string[]> | undefined;
+    }>>;
+    wal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.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;
+}>;
+/**
+ * SQLite AFS module configuration type
+ */
+export type SQLiteAFSConfig = z.infer<typeof sqliteAFSConfigSchema>;
+/**
+ * SQLite AFS module options (after parsing)
+ */
+export interface SQLiteAFSOptions {
+    /** SQLite database URL */
+    url: string;
+    /** Module name */
+    name?: string;
+    /** Module description */
+    description?: string;
+    /** Access mode */
+    accessMode?: AFSAccessMode;
+    /** Tables to expose */
+    tables?: string[];
+    /** Tables to exclude */
+    excludeTables?: string[];
+    /** FTS configuration */
+    fts?: {
+        enabled?: boolean;
+        tables?: Record<string, string[]>;
+    };
+    /** Enable WAL mode */
+    wal?: boolean;
+}

package/lib/dts/index.d.ts

@@ -0,0 +1,13 @@
+export { registerBuiltInActions } from "./actions/built-in.js";
+export { ActionsRegistry } from "./actions/registry.js";
+export type { ActionContext, ActionDefinition, ActionHandler, ActionResult, } from "./actions/types.js";
+export { type SQLiteAFSConfig, type SQLiteAFSOptions, sqliteAFSConfigSchema } from "./config.js";
+export { type BuildEntryOptions, buildActionsListEntry, buildAttributeEntry, buildAttributeListEntry, buildMetaEntry, buildRowEntry, buildSchemaEntry, buildSearchEntry, buildTableEntry, } from "./node/builder.js";
+export { CRUDOperations } from "./operations/crud.js";
+export { buildDelete, buildGetLastRowId, buildInsert, buildSelectAll, buildSelectByPK, buildUpdate, } from "./operations/query-builder.js";
+export { createFTSConfig, type FTSConfig, FTSSearch, type FTSTableConfig, } from "./operations/search.js";
+export { buildPath, createPathRouter, getVirtualPathType, isVirtualPath, matchPath, } from "./router/path-router.js";
+export type { RouteAction, RouteData, RouteMatch, RouteParams } from "./router/types.js";
+export { SchemaIntrospector } from "./schema/introspector.js";
+export type { ColumnInfo, ForeignKeyInfo, IndexInfo, PragmaForeignKeyRow, PragmaIndexListRow, PragmaTableInfoRow, TableSchema, } from "./schema/types.js";
+export { SQLiteAFS } from "./sqlite-afs.js";

package/lib/dts/node/builder.d.ts

@@ -0,0 +1,43 @@
+import type { AFSEntry } from "@aigne/afs";
+import type { TableSchema } from "../schema/types.js";
+/**
+ * Options for building an AFSEntry
+ */
+export interface BuildEntryOptions {
+    /** Base path prefix (e.g., empty string or module mount path) */
+    basePath?: string;
+}
+/**
+ * Builds an AFSEntry from a database row
+ */
+export declare function buildRowEntry(table: string, schema: TableSchema, row: Record<string, unknown>, options?: BuildEntryOptions): AFSEntry;
+/**
+ * Builds an AFSEntry for a table listing
+ */
+export declare function buildTableEntry(table: string, schema: TableSchema, options?: BuildEntryOptions & {
+    rowCount?: number;
+}): AFSEntry;
+/**
+ * Builds an AFSEntry for table schema
+ */
+export declare function buildSchemaEntry(table: string, schema: TableSchema, options?: BuildEntryOptions): AFSEntry;
+/**
+ * Builds an AFSEntry for an attribute (single column value)
+ */
+export declare function buildAttributeEntry(table: string, pk: string, column: string, value: unknown, options?: BuildEntryOptions): AFSEntry;
+/**
+ * Builds an AFSEntry listing all attributes for a row
+ */
+export declare function buildAttributeListEntry(table: string, schema: TableSchema, pk: string, row: Record<string, unknown>, options?: BuildEntryOptions): AFSEntry[];
+/**
+ * Builds an AFSEntry for row metadata
+ */
+export declare function buildMetaEntry(table: string, schema: TableSchema, pk: string, row: Record<string, unknown>, options?: BuildEntryOptions): AFSEntry;
+/**
+ * Builds AFSEntry for actions list
+ */
+export declare function buildActionsListEntry(table: string, pk: string, actions: string[], options?: BuildEntryOptions): AFSEntry[];
+/**
+ * Builds a search result entry with highlights
+ */
+export declare function buildSearchEntry(table: string, schema: TableSchema, row: Record<string, unknown>, snippet?: string, options?: BuildEntryOptions): AFSEntry;

package/lib/dts/operations/crud.d.ts

@@ -0,0 +1,64 @@
+import type { AFSDeleteResult, AFSListOptions, AFSListResult, AFSReadResult, AFSWriteResult } from "@aigne/afs";
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import type { TableSchema } from "../schema/types.js";
+/**
+ * CRUD operations for SQLite AFS
+ */
+export declare class CRUDOperations {
+    private db;
+    private schemas;
+    private basePath;
+    constructor(db: LibSQLDatabase, schemas: Map<string, TableSchema>, basePath?: string);
+    /**
+     * Lists all tables
+     */
+    listTables(): Promise<AFSListResult>;
+    /**
+     * Lists rows in a table
+     */
+    listTable(table: string, options?: AFSListOptions): Promise<AFSListResult>;
+    /**
+     * Reads a single row by primary key
+     */
+    readRow(table: string, pk: string): Promise<AFSReadResult>;
+    /**
+     * Gets table schema
+     */
+    getSchema(table: string): AFSReadResult;
+    /**
+     * Lists attributes (columns) for a row
+     */
+    listAttributes(table: string, pk: string): Promise<AFSListResult>;
+    /**
+     * Gets a single attribute (column value) for a row
+     */
+    getAttribute(table: string, pk: string, column: string): Promise<AFSReadResult>;
+    /**
+     * Gets row metadata
+     */
+    getMeta(table: string, pk: string): Promise<AFSReadResult>;
+    /**
+     * Creates a new row in a table
+     */
+    createRow(table: string, content: Record<string, unknown>): Promise<AFSWriteResult>;
+    /**
+     * Updates an existing row
+     */
+    updateRow(table: string, pk: string, content: Record<string, unknown>): Promise<AFSWriteResult>;
+    /**
+     * Deletes a row by primary key
+     */
+    deleteRow(table: string, pk: string): Promise<AFSDeleteResult>;
+    /**
+     * Checks if a table exists
+     */
+    hasTable(table: string): boolean;
+    /**
+     * Gets the schema for a table
+     */
+    getTableSchema(table: string): TableSchema | undefined;
+    /**
+     * Updates the schemas map (after refresh)
+     */
+    setSchemas(schemas: Map<string, TableSchema>): void;
+}

package/lib/dts/operations/query-builder.d.ts

@@ -0,0 +1,37 @@
+import type { TableSchema } from "../schema/types.js";
+/**
+ * Builds a SELECT query string for a single row by primary key
+ */
+export declare function buildSelectByPK(tableName: string, schema: TableSchema, pk: string): string;
+/**
+ * Builds a SELECT query string for listing rows with optional limit and offset
+ */
+export declare function buildSelectAll(tableName: string, options?: {
+    limit?: number;
+    offset?: number;
+    orderBy?: [string, "asc" | "desc"][];
+}): string;
+/**
+ * Builds an INSERT query string from content object
+ */
+export declare function buildInsert(tableName: string, schema: TableSchema, content: Record<string, unknown>): string;
+/**
+ * Builds an UPDATE query string from content object
+ */
+export declare function buildUpdate(tableName: string, schema: TableSchema, pk: string, content: Record<string, unknown>): string;
+/**
+ * Builds a DELETE query string by primary key
+ */
+export declare function buildDelete(tableName: string, schema: TableSchema, pk: string): string;
+/**
+ * Formats a value for SQL insertion
+ */
+export declare function formatValue(value: unknown): string;
+/**
+ * Escapes a string for safe SQL insertion
+ */
+export declare function escapeSQLString(str: string): string;
+/**
+ * Gets the last inserted rowid query string
+ */
+export declare function buildGetLastRowId(): string;