@apisurf/ngn-core 0.2.2

package/dist/core.d.ts

@@ -0,0 +1,292 @@
+import { FsNodeFileDescriptor } from '@apisurf/ngn-os';
+import { Client, InArgs, ResultSet, InStatement } from '@apisurf/ngn-persistence';
+export { initDbFileIfNotExists } from '@apisurf/ngn-persistence';
+
+type CompilerOptions = {
+    /** Minify output */
+    minify?: boolean;
+    /** Generate sourcemaps */
+    sourcemap?: boolean;
+    /** Suppress output */
+    silent?: boolean;
+    /** Patterns to NOT externalize (will be bundled) */
+    noExternal?: (string | RegExp)[];
+};
+declare class Compiler {
+    private options;
+    private externalizePlugin;
+    constructor(options?: CompilerOptions);
+    /**
+     * Creates an esbuild plugin that externalizes all bare package imports
+     * except for those matching the noExternal patterns.
+     * This approach automatically handles all dependencies (including transitive ones)
+     * without needing to maintain a list or read package.json.
+     *
+     * NOTE: There are esbuild config options that can be used to externalize dependencies
+     * but they are not as flexible as this plugin. This plugin is more flexible and
+     * can be used to externalize dependencies that are not in the package.json(alternative approach).
+     * Previous implementations used tsup which did this by default or used a list of
+     * dependencies to externalize. This approach externalizes everything dynamically.
+     * Problematic dependencies were: playwright, playwright-core, chromium-bidi, etc.
+     */
+    private createExternalizePlugin;
+    /**
+     * Compile entry files to in-memory strings (no disk I/O)
+     * @param entry - Array of input paths
+     * @returns Map of input file path to compiled code string
+     */
+    compile(entry: string[]): Promise<{
+        compiled: Map<string, string>;
+    }>;
+    /**
+     * Compile source code from memory (no disk I/O required)
+     * @param sourceCode - The source code string to compile
+     * @param virtualPath - A virtual file path for the source (used for resolve directory and loader detection)
+     * @returns The compiled code string
+     */
+    compileFromSource(sourceCode: string, virtualPath: string): Promise<string>;
+}
+
+/**
+ * Executes IIFE-compiled code in an isolated VM context.
+ * The code should be compiled with esbuild's iife format and globalName: "__exports".
+ *
+ * @param code - The IIFE code string to execute
+ * @returns The module's exports object
+ */
+declare function executeEsm(code: string): Promise<Record<string, unknown>>;
+
+/**
+ * A database migration
+ */
+interface Migration {
+    /** Unique identifier (use datetime format e.g., "2024-01-13-001") */
+    id: string;
+    /** SQL statement(s) to execute */
+    up: string;
+}
+/**
+ * Options for opening an additional database next to the task file
+ */
+interface InitDBOptions {
+    /**
+     * Database file, relative to the folder the task file lives in
+     * (e.g. "cache.db" or "data/cache.db"). A leading "file:" is accepted.
+     * Paths that reach outside the task folder are rejected.
+     */
+    file: string;
+    /** Optional migrations to run */
+    migrations?: Migration[];
+}
+/**
+ * A database instance opened by initDB
+ */
+interface DBInstance {
+    /** Raw libsql client for advanced usage */
+    client: Client;
+    /** Absolute path of the database file */
+    path: string;
+    /** Execute a single SQL statement */
+    execute: (sql: string, args?: InArgs) => Promise<ResultSet>;
+    /** Execute multiple SQL statements in a batch */
+    batch: (statements: InStatement[]) => Promise<ResultSet[]>;
+    /** Close the database connection */
+    close: () => void;
+}
+/**
+ * SQLite API injected into every task as `ctx.sqlite`.
+ *
+ * Reads and writes are confined to the folder the task file lives in: the
+ * default database sits next to the task, and `initDB` only opens paths that
+ * resolve inside that folder. A task cannot reach a sibling folder's data by
+ * walking up with "..", and cannot open a database by absolute path.
+ */
+interface TaskSqlite {
+    /** Raw libsql client for the task's own database */
+    readonly client: Client;
+    /** Absolute path of the task's own database file */
+    readonly path: string;
+    /** Execute a single SQL statement against the task's own database */
+    execute: (sql: string, args?: InArgs) => Promise<ResultSet>;
+    /** Execute multiple SQL statements against the task's own database */
+    batch: (statements: InStatement[]) => Promise<ResultSet[]>;
+    /** Open another database in the task's folder, with optional migrations */
+    initDB: (options: InitDBOptions) => Promise<DBInstance>;
+    /** Delete a database file in the task's folder */
+    destroyDB: (file: string) => Promise<void>;
+}
+/**
+ * Close every database opened by a task. Called by the CLI on shutdown.
+ */
+declare function closeTaskDatabases(): void;
+
+type LiveSourceParams = {
+    livePath: `live:${string}`;
+    code: string;
+};
+type DbSourceParams = {
+    compiledCode: string;
+    descriptor: FsNodeFileDescriptor;
+    tasksRootDir: string;
+};
+type EntryParams = LiveSourceParams | DbSourceParams;
+/**
+ * The single argument every task export receives.
+ */
+interface TaskContext {
+    meta: {
+        fileTaskId: number;
+        fileTaskVersionId: number;
+        file: FsNodeFileDescriptor;
+        tasksRootDir: string;
+    };
+    env: Record<string, string> | null;
+    kv: {
+        set(key: string, value: string): Promise<void>;
+        get(key: string): Promise<string | null>;
+        delete(key: string): Promise<void>;
+    };
+    log: {
+        info(value: string): Promise<void>;
+        error(value: string): Promise<void>;
+        warning(value: string): Promise<void>;
+    };
+    timing: {
+        start(label: string): () => Promise<void>;
+    };
+    /**
+     * SQLite scoped to the folder this task file lives in. Always present — no
+     * configuration required.
+     */
+    sqlite: TaskSqlite;
+}
+
+interface CompiledTaskCallbacks {
+    onTaskLoadComplete?: ({ paths, md5Hash, compiledCode, }: {
+        paths: {
+            compiled: string;
+            source: string;
+            relativeEntry: string;
+            relativeParent: string;
+        };
+        md5Hash: string;
+        compiledCode: string;
+    }) => Promise<{
+        fileTaskId: number;
+        fileTaskVersionId: number;
+    }>;
+    onTaskExecutionStart?: () => Promise<void>;
+    onTaskCodeLoaded?: () => Promise<void>;
+    onTaskExportsLoaded?: () => Promise<void>;
+}
+interface TaskRuntimeCallbacks {
+    onNotFound?: (meta: {
+        path: string;
+    }) => Promise<void>;
+    onSkip?: (meta: {
+        path: string;
+    }) => Promise<void>;
+    onStart?: (meta: {
+        path: string;
+    }) => Promise<void>;
+    onSuccess?: (meta: {
+        path: string;
+    }) => Promise<void>;
+    onFailure?: (meta: {
+        path: string;
+    }) => Promise<void>;
+}
+type BuildCompiledTaskConfigFn = ({ sourcePath, compiledPath, }: {
+    sourcePath: string;
+    compiledPath: string;
+}) => {
+    compiledPath: string;
+    sourcePath: string;
+    taskCallbacks: CompiledTaskCallbacks;
+    runtimeCallbacks: TaskRuntimeCallbacks;
+    env: TaskContext["env"];
+    kv: TaskContext["kv"];
+    log: TaskContext["log"];
+    timing: TaskContext["timing"];
+    sqlite: TaskContext["sqlite"];
+};
+
+declare class Task {
+    private taskCallbacks;
+    private runtimeCallbacks;
+    private env;
+    private kv;
+    private log;
+    private timing;
+    private sqlite;
+    private meta;
+    private entry;
+    private entryExports;
+    constructor({ entryParams, buildConfigFn, }: {
+        entryParams: EntryParams;
+        buildConfigFn: BuildCompiledTaskConfigFn;
+    });
+    get sourcePath(): string;
+    get compiledPath(): string;
+    /**
+     * Unique identifier for the task - the relative entry path
+     */
+    get taskPath(): string;
+    get codeHash(): string | null;
+    get timingPattern(): string | undefined;
+    hasTaskExport(): boolean;
+    hasTimingExport(): boolean;
+    loadEntry(): Promise<void>;
+    execute(): Promise<void>;
+}
+
+declare class TaskLibrary {
+    private tasks;
+    constructor();
+    add(taskOrTasks: Task | Array<Task>): void;
+    remove(taskPath: string | Array<Task>): void;
+    /**
+     * Add tasks from in-memory compiled code (stored in DB)
+     */
+    addFromCompiledCode({ compiledCode, descriptors, tasksRootDir, buildConfigFn, }: {
+        compiledCode: Map<string, string>;
+        descriptors: Record<string, FsNodeFileDescriptor>;
+        tasksRootDir: string;
+        buildConfigFn: BuildCompiledTaskConfigFn;
+    }): void;
+    execute(taskPath: string): Promise<void>;
+    getTasks(): Task[];
+}
+
+type Options$1 = {
+    taskLibrary: TaskLibrary;
+};
+declare class TaskLibraryScheduler {
+    private taskLibrary;
+    private scheduledTasks;
+    constructor(options: Options$1);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    scheduleTask(task: Task): Promise<void>;
+    unscheduleTask(task: Task): void;
+    isCronPatternValid(cronPattern: string): boolean;
+}
+
+type Options = {
+    task: Task;
+};
+declare class TaskOnceRunner {
+    private task;
+    constructor(options: Options);
+    run(): Promise<void>;
+}
+
+declare function setupDbClient(dbPath: string): Promise<Client>;
+declare function getDbClient(): Client;
+
+declare function createControlsGenerator({ dbClient, env, }: {
+    dbClient: Client;
+    env: TaskContext["env"];
+}): BuildCompiledTaskConfigFn;
+
+export { Compiler, type DBInstance, type InitDBOptions, type Migration, Task, type TaskContext, TaskLibrary, TaskLibraryScheduler, TaskOnceRunner, type TaskSqlite, closeTaskDatabases, createControlsGenerator, executeEsm, getDbClient, setupDbClient };