@aigne/afs-sqlite 1.0.1-beta

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

@@ -0,0 +1,75 @@
+import type { AFSSearchOptions, AFSSearchResult } from "@aigne/afs";
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import type { TableSchema } from "../schema/types.js";
+/**
+ * FTS5 search configuration for a table
+ */
+export interface FTSTableConfig {
+    /** Columns to include in FTS index */
+    columns: string[];
+    /** Whether FTS table has been created */
+    initialized?: boolean;
+}
+/**
+ * FTS5 search configuration
+ */
+export interface FTSConfig {
+    /** Whether FTS is enabled */
+    enabled: boolean;
+    /** Per-table FTS configuration */
+    tables: Map<string, FTSTableConfig>;
+}
+/**
+ * FTS5 Search operations for SQLite AFS
+ */
+export declare class FTSSearch {
+    private db;
+    private schemas;
+    private config;
+    private basePath;
+    constructor(db: LibSQLDatabase, schemas: Map<string, TableSchema>, config: FTSConfig, basePath?: string);
+    /**
+     * Performs full-text search across configured tables
+     */
+    search(query: string, options?: AFSSearchOptions & {
+        /** Specific tables to search (defaults to all FTS-enabled tables) */
+        tables?: string[];
+    }): Promise<AFSSearchResult>;
+    /**
+     * Searches within a specific table
+     */
+    searchTable(tableName: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult>;
+    /**
+     * Checks if FTS is configured for a table
+     */
+    hasFTS(tableName: string): boolean;
+    /**
+     * Gets FTS configuration for a table
+     */
+    getFTSConfig(tableName: string): FTSTableConfig | undefined;
+    /**
+     * Checks if an FTS table exists
+     */
+    private ftsTableExists;
+    /**
+     * Prepares a query string for FTS5
+     * Handles special characters and case sensitivity
+     */
+    private prepareFTSQuery;
+    /**
+     * Updates the schemas map (after refresh)
+     */
+    setSchemas(schemas: Map<string, TableSchema>): void;
+    /**
+     * Simple search fallback when FTS is not available
+     * Uses LIKE queries on specified columns
+     */
+    simpleLikeSearch(tableName: string, query: string, columns: string[], options?: AFSSearchOptions): Promise<AFSSearchResult>;
+}
+/**
+ * Creates FTS configuration from options
+ */
+export declare function createFTSConfig(options?: {
+    enabled?: boolean;
+    tables?: Record<string, string[]>;
+}): FTSConfig;

package/lib/dts/router/path-router.d.ts

@@ -0,0 +1,38 @@
+import { type RadixRouter } from "radix3";
+import type { RouteData, RouteMatch } from "./types.js";
+export type { RouteData };
+/**
+ * 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 declare function createPathRouter(): RadixRouter<RouteData>;
+/**
+ * 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 declare function matchPath(router: RadixRouter<RouteData>, path: string): RouteMatch | undefined;
+/**
+ * Builds a path from components
+ */
+export declare function buildPath(table?: string, pk?: string, suffix?: string): string;
+/**
+ * Checks if a path segment is a virtual path (@attr, @meta, @actions, @schema)
+ */
+export declare function isVirtualPath(segment: string): boolean;
+/**
+ * Gets the type of virtual path
+ */
+export declare function getVirtualPathType(segment: string): "attr" | "meta" | "actions" | "schema" | null;

package/lib/dts/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/dts/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/dts/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/dts/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;
+}

package/lib/esm/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/esm/actions/built-in.js

@@ -0,0 +1,162 @@
+import { sql } from "@aigne/sqlite";
+/**
+ * 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();
+}
+/**
+ * Registers built-in actions to the registry
+ */
+export function registerBuiltInActions(registry) {
+    // Refresh schema action (table level)
+    registry.register({
+        name: "refresh",
+        description: "Refresh the schema cache for this module",
+        tableLevel: true,
+        rowLevel: false,
+        handler: async (ctx) => {
+            await ctx.module.refreshSchema();
+            return {
+                success: true,
+                message: "Schema refreshed successfully",
+            };
+        },
+    });
+    // Export table action (table level)
+    registry.register({
+        name: "export",
+        description: "Export table data in specified format (json, csv)",
+        tableLevel: true,
+        rowLevel: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                format: {
+                    type: "string",
+                    enum: ["json", "csv"],
+                    default: "json",
+                },
+            },
+        },
+        handler: async (ctx, params) => {
+            const format = params.format ?? "json";
+            const data = await ctx.module.exportTable(ctx.table, format);
+            return {
+                success: true,
+                data,
+            };
+        },
+    });
+    // Count rows action (table level)
+    registry.register({
+        name: "count",
+        description: "Get the total row count for this table",
+        tableLevel: true,
+        rowLevel: false,
+        handler: async (ctx) => {
+            const result = await execAll(ctx.db, `SELECT COUNT(*) as count FROM "${ctx.table}"`);
+            return {
+                success: true,
+                data: { count: result[0]?.count ?? 0 },
+            };
+        },
+    });
+    // Duplicate row action (row level)
+    registry.register({
+        name: "duplicate",
+        description: "Create a copy of this row",
+        tableLevel: false,
+        rowLevel: true,
+        handler: async (ctx) => {
+            if (!ctx.row) {
+                return { success: false, message: "Row data not available" };
+            }
+            const schema = ctx.schemas.get(ctx.table);
+            if (!schema) {
+                return { success: false, message: `Table '${ctx.table}' not found` };
+            }
+            // Create a copy without the primary key
+            const pkColumn = schema.primaryKey[0] ?? "rowid";
+            const rowCopy = { ...ctx.row };
+            delete rowCopy[pkColumn];
+            delete rowCopy.rowid;
+            // Build insert query
+            const columns = Object.keys(rowCopy);
+            const values = columns.map((col) => formatValueForSQL(rowCopy[col]));
+            await execRun(ctx.db, `INSERT INTO "${ctx.table}" (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${values.join(", ")})`);
+            // Get the new row's ID
+            const lastIdResult = await execAll(ctx.db, "SELECT last_insert_rowid() as id");
+            return {
+                success: true,
+                data: { newId: lastIdResult[0]?.id },
+                message: "Row duplicated successfully",
+            };
+        },
+    });
+    // Validate row action (row level)
+    registry.register({
+        name: "validate",
+        description: "Validate row data against schema constraints",
+        tableLevel: false,
+        rowLevel: true,
+        handler: async (ctx) => {
+            if (!ctx.row) {
+                return { success: false, message: "Row data not available" };
+            }
+            const schema = ctx.schemas.get(ctx.table);
+            if (!schema) {
+                return { success: false, message: `Table '${ctx.table}' not found` };
+            }
+            const errors = [];
+            // Check NOT NULL constraints
+            for (const col of schema.columns) {
+                if (col.notnull && (ctx.row[col.name] === null || ctx.row[col.name] === undefined)) {
+                    errors.push(`Column '${col.name}' cannot be null`);
+                }
+            }
+            // Check foreign key references
+            for (const fk of schema.foreignKeys) {
+                const value = ctx.row[fk.from];
+                if (value !== null && value !== undefined) {
+                    const refResult = await execAll(ctx.db, `SELECT COUNT(*) as count FROM "${fk.table}" WHERE "${fk.to}" = '${String(value).replace(/'/g, "''")}'`);
+                    if (refResult[0]?.count === 0) {
+                        errors.push(`Foreign key violation: ${fk.from} references non-existent ${fk.table}.${fk.to}`);
+                    }
+                }
+            }
+            return {
+                success: errors.length === 0,
+                data: { errors, valid: errors.length === 0 },
+                message: errors.length > 0 ? `Validation failed: ${errors.join("; ")}` : "Row is valid",
+            };
+        },
+    });
+}
+/**
+ * Formats a value for SQL insertion
+ */
+function formatValueForSQL(value) {
+    if (value === null || value === undefined) {
+        return "NULL";
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    if (typeof value === "boolean") {
+        return value ? "1" : "0";
+    }
+    if (value instanceof Date) {
+        return `'${value.toISOString()}'`;
+    }
+    if (typeof value === "object") {
+        return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+    }
+    return `'${String(value).replace(/'/g, "''")}'`;
+}

package/lib/esm/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>;
+}