@aigne/afs-sqlite 1.0.1-beta

package/lib/esm/actions/registry.js

@@ -0,0 +1,98 @@
+/**
+ * Registry for managing action handlers
+ */
+export class ActionsRegistry {
+    handlers = new Map();
+    /**
+     * Registers an action handler
+     */
+    register(definition) {
+        this.handlers.set(definition.name, definition);
+    }
+    /**
+     * Registers a simple action with just name and handler
+     */
+    registerSimple(name, handler, options) {
+        this.register({
+            name,
+            handler,
+            description: options?.description,
+            tableLevel: options?.tableLevel ?? false,
+            rowLevel: options?.rowLevel ?? true,
+        });
+    }
+    /**
+     * Unregisters an action
+     */
+    unregister(name) {
+        return this.handlers.delete(name);
+    }
+    /**
+     * Checks if an action is registered
+     */
+    has(name) {
+        return this.handlers.has(name);
+    }
+    /**
+     * Gets an action definition
+     */
+    get(name) {
+        return this.handlers.get(name);
+    }
+    /**
+     * Lists all registered actions
+     */
+    list(options) {
+        const actions = Array.from(this.handlers.values());
+        if (options?.tableLevel !== undefined || options?.rowLevel !== undefined) {
+            return actions.filter((a) => {
+                if (options.tableLevel && !a.tableLevel)
+                    return false;
+                if (options.rowLevel && !a.rowLevel)
+                    return false;
+                return true;
+            });
+        }
+        return actions;
+    }
+    /**
+     * Lists action names
+     */
+    listNames(options) {
+        return this.list(options).map((a) => a.name);
+    }
+    /**
+     * Executes an action
+     */
+    async execute(name, ctx, params = {}) {
+        const definition = this.handlers.get(name);
+        if (!definition) {
+            return {
+                success: false,
+                message: `Unknown action: ${name}`,
+            };
+        }
+        // Validate action level
+        if (ctx.pk && !definition.rowLevel) {
+            return {
+                success: false,
+                message: `Action '${name}' is not available at row level`,
+            };
+        }
+        if (!ctx.pk && !definition.tableLevel) {
+            return {
+                success: false,
+                message: `Action '${name}' is not available at table level`,
+            };
+        }
+        try {
+            return await definition.handler(ctx, params);
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}

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

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

package/lib/esm/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/esm/config.js

@@ -0,0 +1,30 @@
+import { accessModeSchema } from "@aigne/afs";
+import { z } from "zod";
+/**
+ * FTS (Full-Text Search) configuration schema
+ */
+export const ftsConfigSchema = z
+    .object({
+    enabled: z.boolean().default(true).describe("Whether FTS is enabled"),
+    tables: z
+        .record(z.array(z.string()))
+        .optional()
+        .describe("Map of table name to columns to index for FTS"),
+})
+    .optional();
+/**
+ * SQLite AFS module configuration schema
+ */
+export const sqliteAFSConfigSchema = z.object({
+    url: z.string().describe("SQLite database URL (file:./path or :memory:)"),
+    name: z.string().optional().describe("Module name, defaults to 'sqlite-afs'"),
+    description: z.string().optional().describe("Description of this module"),
+    accessMode: accessModeSchema,
+    tables: z
+        .array(z.string())
+        .optional()
+        .describe("Whitelist of tables to expose (if not specified, all tables are exposed)"),
+    excludeTables: z.array(z.string()).optional().describe("Tables to exclude from exposure"),
+    fts: ftsConfigSchema,
+    wal: z.boolean().optional().default(true).describe("Enable WAL mode for better concurrency"),
+});

package/lib/esm/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/esm/index.js

@@ -0,0 +1,17 @@
+// Main module export
+export { registerBuiltInActions } from "./actions/built-in.js";
+// Actions
+export { ActionsRegistry } from "./actions/registry.js";
+// Configuration
+export { sqliteAFSConfigSchema } from "./config.js";
+// Node builder
+export { buildActionsListEntry, buildAttributeEntry, buildAttributeListEntry, buildMetaEntry, buildRowEntry, buildSchemaEntry, buildSearchEntry, buildTableEntry, } from "./node/builder.js";
+// Operations
+export { CRUDOperations } from "./operations/crud.js";
+export { buildDelete, buildGetLastRowId, buildInsert, buildSelectAll, buildSelectByPK, buildUpdate, } from "./operations/query-builder.js";
+export { createFTSConfig, FTSSearch, } from "./operations/search.js";
+// Router
+export { buildPath, createPathRouter, getVirtualPathType, isVirtualPath, matchPath, } from "./router/path-router.js";
+// Schema types and introspector
+export { SchemaIntrospector } from "./schema/introspector.js";
+export { SQLiteAFS } from "./sqlite-afs.js";

package/lib/esm/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/esm/node/builder.js

@@ -0,0 +1,177 @@
+/**
+ * Builds an AFSEntry from a database row
+ */
+export function buildRowEntry(table, schema, row, options) {
+    const pkColumn = schema.primaryKey[0] ?? "rowid";
+    const pk = String(row[pkColumn] ?? row.rowid);
+    const basePath = options?.basePath ?? "";
+    return {
+        id: `${table}:${pk}`,
+        path: `${basePath}/${table}/${pk}`,
+        content: row,
+        metadata: {
+            table,
+            primaryKey: pkColumn,
+            primaryKeyValue: pk,
+        },
+        createdAt: parseDate(row.created_at ?? row.createdAt),
+        updatedAt: parseDate(row.updated_at ?? row.updatedAt),
+    };
+}
+/**
+ * Builds an AFSEntry for a table listing
+ */
+export function buildTableEntry(table, schema, options) {
+    const basePath = options?.basePath ?? "";
+    return {
+        id: table,
+        path: `${basePath}/${table}`,
+        description: `Table: ${table} (${schema.columns.length} columns)`,
+        metadata: {
+            table,
+            columnCount: schema.columns.length,
+            primaryKey: schema.primaryKey,
+            childrenCount: options?.rowCount,
+        },
+    };
+}
+/**
+ * Builds an AFSEntry for table schema
+ */
+export function buildSchemaEntry(table, schema, options) {
+    const basePath = options?.basePath ?? "";
+    return {
+        id: `${table}:@schema`,
+        path: `${basePath}/${table}/@schema`,
+        description: `Schema for table: ${table}`,
+        content: {
+            name: schema.name,
+            columns: schema.columns.map((col) => ({
+                name: col.name,
+                type: col.type,
+                nullable: !col.notnull,
+                primaryKey: col.pk > 0,
+                defaultValue: col.dfltValue,
+            })),
+            primaryKey: schema.primaryKey,
+            foreignKeys: schema.foreignKeys.map((fk) => ({
+                column: fk.from,
+                references: {
+                    table: fk.table,
+                    column: fk.to,
+                },
+                onUpdate: fk.onUpdate,
+                onDelete: fk.onDelete,
+            })),
+            indexes: schema.indexes.map((idx) => ({
+                name: idx.name,
+                unique: idx.unique,
+                origin: idx.origin,
+            })),
+        },
+        metadata: {
+            table,
+            type: "schema",
+        },
+    };
+}
+/**
+ * Builds an AFSEntry for an attribute (single column value)
+ */
+export function buildAttributeEntry(table, pk, column, value, options) {
+    const basePath = options?.basePath ?? "";
+    return {
+        id: `${table}:${pk}:@attr:${column}`,
+        path: `${basePath}/${table}/${pk}/@attr/${column}`,
+        content: value,
+        metadata: {
+            table,
+            primaryKeyValue: pk,
+            column,
+            type: "attribute",
+        },
+    };
+}
+/**
+ * Builds an AFSEntry listing all attributes for a row
+ */
+export function buildAttributeListEntry(table, schema, pk, row, options) {
+    const basePath = options?.basePath ?? "";
+    return schema.columns.map((col) => ({
+        id: `${table}:${pk}:@attr:${col.name}`,
+        path: `${basePath}/${table}/${pk}/@attr/${col.name}`,
+        summary: col.name,
+        description: `${col.type}${col.notnull ? " NOT NULL" : ""}`,
+        content: row[col.name],
+        metadata: {
+            column: col.name,
+            type: col.type,
+        },
+    }));
+}
+/**
+ * Builds an AFSEntry for row metadata
+ */
+export function buildMetaEntry(table, schema, pk, row, options) {
+    const basePath = options?.basePath ?? "";
+    return {
+        id: `${table}:${pk}:@meta`,
+        path: `${basePath}/${table}/${pk}/@meta`,
+        content: {
+            table,
+            primaryKey: schema.primaryKey[0] ?? "rowid",
+            primaryKeyValue: pk,
+            schema: {
+                columns: schema.columns.map((c) => c.name),
+                types: Object.fromEntries(schema.columns.map((c) => [c.name, c.type])),
+            },
+            foreignKeys: schema.foreignKeys.filter((fk) => Object.keys(row).includes(fk.from)),
+            rowid: row.rowid,
+        },
+        metadata: {
+            table,
+            type: "meta",
+        },
+    };
+}
+/**
+ * Builds AFSEntry for actions list
+ */
+export function buildActionsListEntry(table, pk, actions, options) {
+    const basePath = options?.basePath ?? "";
+    return actions.map((action) => ({
+        id: `${table}:${pk}:@actions:${action}`,
+        path: `${basePath}/${table}/${pk}/@actions/${action}`,
+        summary: action,
+        metadata: {
+            execute: {
+                name: action,
+                description: `Execute ${action} action on ${table}:${pk}`,
+            },
+        },
+    }));
+}
+/**
+ * Builds a search result entry with highlights
+ */
+export function buildSearchEntry(table, schema, row, snippet, options) {
+    const entry = buildRowEntry(table, schema, row, options);
+    if (snippet) {
+        entry.summary = snippet;
+    }
+    return entry;
+}
+/**
+ * Parses a date from various formats
+ */
+function parseDate(value) {
+    if (!value)
+        return undefined;
+    if (value instanceof Date)
+        return value;
+    if (typeof value === "string")
+        return new Date(value);
+    if (typeof value === "number")
+        return new Date(value);
+    return undefined;
+}

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