@aigne/afs-sqlite 1.0.1-beta

package/lib/esm/sqlite-afs.js

@@ -0,0 +1,333 @@
+import { initDatabase } from "@aigne/sqlite";
+import { registerBuiltInActions } from "./actions/built-in.js";
+import { ActionsRegistry } from "./actions/registry.js";
+import { sqliteAFSConfigSchema } from "./config.js";
+import { buildActionsListEntry } from "./node/builder.js";
+import { CRUDOperations } from "./operations/crud.js";
+import { createFTSConfig, FTSSearch } from "./operations/search.js";
+import { createPathRouter, matchPath } from "./router/path-router.js";
+import { SchemaIntrospector } from "./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).
+ */
+export 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 = createFTSConfig(options.fts);
+        this.actions = new ActionsRegistry();
+        registerBuiltInActions(this.actions);
+    }
+    /**
+     * Returns the Zod schema for configuration validation
+     */
+    static schema() {
+        return sqliteAFSConfigSchema;
+    }
+    /**
+     * Loads a module instance from configuration
+     */
+    static async load({ parsed }) {
+        const validated = 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 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 SchemaIntrospector();
+        this.schemas = await introspector.introspect(db, {
+            tables: this.options.tables,
+            excludeTables: this.options.excludeTables,
+        });
+        // Initialize components
+        this.router = createPathRouter();
+        this.crud = new CRUDOperations(db, this.schemas, "");
+        this.ftsSearch = new 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 = 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 = 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 = 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 = 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 = 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 = 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: 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 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;
+    }
+}
+// Type check to ensure SQLiteAFS implements AFSModuleClass
+const _typeCheck = SQLiteAFS;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@aigne/afs-sqlite",
+  "version": "1.0.1-beta",
+  "description": "AIGNE AFS module for SQLite database storage with schema introspection",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
+  "homepage": "https://www.aigne.io/framework",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIGNE-io/aigne-framework"
+  },
+  "bugs": {
+    "url": "https://github.com/AIGNE-io/aigne-framework/issues"
+  },
+  "files": [
+    "lib/cjs",
+    "lib/dts",
+    "lib/esm",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js",
+      "types": "./lib/dts/index.d.ts"
+    },
+    "./*": {
+      "import": "./lib/esm/*",
+      "require": "./lib/cjs/*",
+      "types": "./lib/dts/*"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./lib/dts/index.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "radix3": "^1.1.2",
+    "zod": "^3.25.67",
+    "@aigne/afs": "^1.4.0-beta.9",
+    "@aigne/sqlite": "^0.4.9-beta.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.22",
+    "drizzle-orm": "^0.44.2",
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.2",
+    "@aigne/test-utils": "^0.5.69-beta.23"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc --build scripts/tsconfig.build.json",
+    "clean": "rimraf lib test/coverage",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
+    "postbuild": "node ../../scripts/post-build-lib.mjs"
+  }
+}