@telorun/sql 0.1.1

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 DiglyAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact DiglyAI.

package/dist/sql-connection-controller.d.ts

@@ -0,0 +1,45 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { Kysely, type QueryResult } from "kysely";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+import type { SqliteDb } from "./sqlite-driver-interface.js";
+interface PoolConfig {
+    min?: number;
+    max?: number;
+    idleTimeoutMs?: number;
+    connectionTimeoutMs?: number;
+}
+interface SqlConnectionManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    driver: "postgres" | "sqlite";
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    ssl?: boolean;
+    file?: string;
+    pool?: PoolConfig;
+}
+export type SqlDriver = SqlConnectionManifest["driver"];
+export declare class SqlConnectionResource implements ResourceInstance {
+    readonly driver: SqlDriver;
+    private readonly db;
+    private readonly sqlite?;
+    constructor(m: SqlConnectionManifest, sqlite?: SqliteDb);
+    init(): Promise<void>;
+    teardown(): Promise<void>;
+    transaction<T>(cb: () => Promise<T>): Promise<T>;
+    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    executeScript(sql: string): Promise<void>;
+    toRowCount(result: QueryResult<unknown>): number;
+    get kysely(): Kysely<any>;
+    snapshot(): Record<string, unknown>;
+    private resolveExecutor;
+}
+export declare function register(): void;
+export declare function create(resource: SqlConnectionManifest, ctx: ResourceContext): Promise<SqlConnectionResource>;
+export {};

package/dist/sql-connection-controller.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "crypto";
+import { CompiledQuery, Kysely, PostgresDialect, SqliteDialect, } from "kysely";
+import { Pool } from "pg";
+import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-store.js";
+export class SqlConnectionResource {
+    driver;
+    db;
+    sqlite;
+    constructor(m, sqlite) {
+        this.driver = m.driver;
+        if (m.driver === "postgres") {
+            this.db = new Kysely({
+                dialect: new PostgresDialect({
+                    pool: new Pool({
+                        ...(m.connectionString
+                            ? { connectionString: m.connectionString }
+                            : { host: m.host, port: m.port ?? 5432, database: m.database, user: m.user, password: m.password }),
+                        ssl: m.ssl ? { rejectUnauthorized: false } : false,
+                        min: m.pool?.min ?? 1,
+                        max: m.pool?.max ?? 10,
+                        idleTimeoutMillis: m.pool?.idleTimeoutMs,
+                        connectionTimeoutMillis: m.pool?.connectionTimeoutMs,
+                    }),
+                }),
+            });
+        }
+        else if (m.driver === "sqlite") {
+            if (!sqlite) {
+                throw new Error("Sql: sqlite database was not initialized");
+            }
+            this.sqlite = sqlite;
+            this.db = new Kysely({
+                dialect: new SqliteDialect({
+                    database: this.sqlite,
+                }),
+            });
+        }
+        else {
+            throw new Error("Invalid SQL Connection driver");
+        }
+    }
+    async init() {
+        await this.db.connection().execute(async () => {
+            // just checking
+        });
+    }
+    async teardown() {
+        await this.db.destroy();
+    }
+    async transaction(cb) {
+        const txId = randomUUID();
+        return this.db.transaction().execute(async (trx) => {
+            setTx(txId, { executor: trx });
+            try {
+                return await txStorage.run(txId, cb);
+            }
+            finally {
+                deleteTx(txId);
+            }
+        });
+    }
+    async execute(sql, params = [], transaction) {
+        const executor = this.resolveExecutor(transaction);
+        return executor.executeQuery(CompiledQuery.raw(sql, params));
+    }
+    async executeScript(sql) {
+        if (this.driver === "sqlite") {
+            this.sqlite?.exec(sql);
+            return;
+        }
+        await this.execute(sql);
+    }
+    toRowCount(result) {
+        if (result.numAffectedRows !== undefined) {
+            return Number(result.numAffectedRows);
+        }
+        return result.rows.length;
+    }
+    get kysely() {
+        return this.db;
+    }
+    snapshot() {
+        return {};
+    }
+    resolveExecutor(transaction) {
+        if (transaction) {
+            transaction.assertActive();
+        }
+        const txId = currentTxId();
+        if (txId) {
+            const entry = getTx(txId);
+            if (entry) {
+                return entry.executor;
+            }
+        }
+        return this.db;
+    }
+}
+export function register() { }
+export async function create(resource, ctx) {
+    const sqlite = resource.driver === "sqlite" ? await openSqliteDatabase(resource.file) : undefined;
+    return new SqlConnectionResource(resource, sqlite);
+}
+async function openSqliteDatabase(file = ":memory:") {
+    if (typeof Bun !== "undefined") {
+        const { openDatabase } = await import("./sqlite-driver-bun.js");
+        return openDatabase(file);
+    }
+    const { openDatabase } = await import("./sqlite-driver-node.js");
+    return openDatabase(file);
+}

package/dist/sql-connection-ref.d.ts

@@ -0,0 +1,7 @@
+import type { ResourceContext } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+interface ConnectionRef {
+    name: string;
+}
+export declare function resolveSqlConnection(value: SqlConnectionResource | ConnectionRef | undefined, ctx: ResourceContext): SqlConnectionResource | undefined;
+export {};

package/dist/sql-connection-ref.js

@@ -0,0 +1,12 @@
+export function resolveSqlConnection(value, ctx) {
+    if (!value) {
+        return undefined;
+    }
+    if (typeof value.execute === "function") {
+        return value;
+    }
+    if (typeof value.name !== "string") {
+        throw new Error("Sql: invalid connection reference");
+    }
+    return ctx.moduleContext.getInstance(value.name);
+}

package/dist/sql-exec-controller.d.ts

@@ -0,0 +1,25 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlResult } from "./sql-query-controller.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+interface SqlExecManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    connection?: SqlConnectionResource;
+    transaction?: SqlTransactionResource;
+    inputs: {
+        sql: string;
+        bindings?: unknown[];
+    };
+}
+declare class SqlExecResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: SqlExecManifest, ctx: ResourceContext);
+    invoke(input: any): Promise<SqlResult>;
+}
+export declare function register(): void;
+export declare function create(resource: SqlExecManifest, ctx: ResourceContext): Promise<SqlExecResource>;
+export {};

package/dist/sql-exec-controller.js

@@ -0,0 +1,27 @@
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+class SqlExecResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    async invoke(input) {
+        const m = this.manifest;
+        const ctx = this.ctx;
+        const expandedInput = ctx.expandValue(input, {});
+        const connection = resolveSqlConnection(m.connection, ctx) ?? m.transaction?.getConnection();
+        if (!connection) {
+            throw new Error("Sql: either 'connection' or 'transaction' must be set");
+        }
+        return runExec(connection, m.transaction, expandedInput.sql, expandedInput.bindings ?? []);
+    }
+}
+async function runExec(connection, transaction, sql, params) {
+    const result = await connection.execute(sql, params, transaction);
+    return { rows: result.rows, rowCount: connection.toRowCount(result) };
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new SqlExecResource(resource, ctx);
+}

package/dist/sql-migration-controller.d.ts

@@ -0,0 +1,16 @@
+import type { ResourceInstance } from "@telorun/sdk";
+interface SqlMigrationManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    sql: string;
+}
+declare class SqlMigrationResource implements ResourceInstance {
+    readonly manifest: SqlMigrationManifest;
+    constructor(manifest: SqlMigrationManifest);
+    snapshot(): Record<string, unknown>;
+}
+export declare function register(): void;
+export declare function create(resource: SqlMigrationManifest): Promise<SqlMigrationResource>;
+export {};

package/dist/sql-migration-controller.js

@@ -0,0 +1,13 @@
+class SqlMigrationResource {
+    manifest;
+    constructor(manifest) {
+        this.manifest = manifest;
+    }
+    snapshot() {
+        return {};
+    }
+}
+export function register() { }
+export async function create(resource) {
+    return new SqlMigrationResource(resource);
+}

package/dist/sql-migrations-controller.d.ts

@@ -0,0 +1,18 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+interface SqlMigrationsManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    connection: SqlConnectionResource;
+}
+declare class SqlMigrationsResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: SqlMigrationsManifest, ctx: ResourceContext);
+    run(): Promise<void>;
+}
+export declare function register(): void;
+export declare function create(resource: SqlMigrationsManifest, ctx: ResourceContext): Promise<SqlMigrationsResource>;
+export {};

package/dist/sql-migrations-controller.js

@@ -0,0 +1,56 @@
+import { CompiledQuery, Migrator, } from "kysely";
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+class TeloMigrationProvider {
+    migrations;
+    constructor(migrations) {
+        this.migrations = migrations;
+    }
+    async getMigrations() {
+        return Object.fromEntries(this.migrations.map((m) => [
+            m.name,
+            {
+                async up(db) {
+                    await db.executeQuery(CompiledQuery.raw(m.sql));
+                },
+            },
+        ]));
+    }
+}
+class SqlMigrationsResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    async run() {
+        const conn = resolveSqlConnection(this.manifest.connection, this.ctx) ?? failMissingConnection();
+        const migrations = [];
+        for (const [, { resource }] of this.ctx.moduleContext.resourceInstances) {
+            if (resource.kind === "Sql.Migration") {
+                migrations.push({
+                    name: resource.metadata.name,
+                    sql: resource.sql,
+                });
+            }
+        }
+        migrations.sort((a, b) => a.name.localeCompare(b.name));
+        const migrator = new Migrator({
+            db: conn.kysely,
+            provider: new TeloMigrationProvider(migrations),
+            migrationTableName: "migrations",
+            migrationLockTableName: "migration_locks",
+        });
+        const { error } = await migrator.migrateToLatest();
+        if (error) {
+            throw error;
+        }
+    }
+}
+function failMissingConnection() {
+    throw new Error("Sql.Migrations: missing connection");
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new SqlMigrationsResource(resource, ctx);
+}

package/dist/sql-query-controller.d.ts

@@ -0,0 +1,28 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+interface SqlQueryManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    connection?: SqlConnectionResource;
+    transaction?: SqlTransactionResource;
+    inputs: {
+        sql: string;
+        bindings?: unknown[];
+    };
+}
+export interface SqlResult {
+    rows: Record<string, unknown>[];
+    rowCount: number;
+}
+declare class SqlQueryResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: SqlQueryManifest, ctx: ResourceContext);
+    invoke(input: unknown): Promise<SqlResult>;
+}
+export declare function register(): void;
+export declare function create(resource: SqlQueryManifest, ctx: ResourceContext): Promise<SqlQueryResource>;
+export {};

package/dist/sql-query-controller.js

@@ -0,0 +1,30 @@
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+class SqlQueryResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    async invoke(input) {
+        const m = this.manifest;
+        const ctx = this.ctx;
+        const expandedInput = ctx.expandValue(input, {});
+        const connection = resolveConnection(m.connection, m.transaction, ctx);
+        return runQuery(connection, m.transaction, expandedInput.sql, expandedInput.bindings);
+    }
+}
+function resolveConnection(connection, transaction, ctx) {
+    return (resolveSqlConnection(connection, ctx) ?? transaction?.getConnection() ?? failMissingConnection());
+}
+async function runQuery(connection, transaction, sql, params) {
+    const result = await connection.execute(sql, params, transaction);
+    return { rows: result.rows, rowCount: result.rows.length };
+}
+function failMissingConnection() {
+    throw new Error("Sql: either 'connection' or 'transaction' must be set");
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new SqlQueryResource(resource, ctx);
+}

package/dist/sql-transaction-controller.d.ts

@@ -0,0 +1,22 @@
+import type { Invocable, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { SqlConnectionResource } from "./sql-connection-controller.js";
+interface SqlTransactionManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    connection: SqlConnectionResource;
+    steps: Invocable;
+    inputs?: Record<string, unknown>;
+}
+export declare class SqlTransactionResource implements ResourceInstance {
+    private readonly manifest;
+    private readonly ctx;
+    constructor(manifest: SqlTransactionManifest, ctx: ResourceContext);
+    getConnection(): SqlConnectionResource;
+    assertActive(): void;
+    invoke(input: unknown): Promise<unknown>;
+}
+export declare function register(): void;
+export declare function create(resource: SqlTransactionManifest, ctx: ResourceContext): Promise<SqlTransactionResource>;
+export {};

package/dist/sql-transaction-controller.js

@@ -0,0 +1,38 @@
+import { resolveSqlConnection } from "./sql-connection-ref.js";
+import { currentTxId } from "./transaction-store.js";
+export class SqlTransactionResource {
+    manifest;
+    ctx;
+    constructor(manifest, ctx) {
+        this.manifest = manifest;
+        this.ctx = ctx;
+    }
+    getConnection() {
+        return (resolveSqlConnection(this.manifest.connection, this.ctx) ??
+            failMissingConnection(this.manifest.metadata.name));
+    }
+    assertActive() {
+        if (!currentTxId()) {
+            throw new Error(`Sql.Transaction '${this.manifest.metadata.name}': used outside an active transaction`);
+        }
+    }
+    async invoke(input) {
+        const m = this.manifest;
+        const ctx = this.ctx;
+        // Flat nesting: if already inside a transaction, reuse it
+        if (currentTxId()) {
+            const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
+            return m.steps.invoke(expandedInputs);
+        }
+        const conn = this.getConnection();
+        const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
+        return conn.transaction(() => m.steps.invoke(expandedInputs));
+    }
+}
+function failMissingConnection(name) {
+    throw new Error(`Sql.Transaction '${name}': missing connection`);
+}
+export function register() { }
+export async function create(resource, ctx) {
+    return new SqlTransactionResource(resource, ctx);
+}

package/dist/sqlite-driver-bun.d.ts

@@ -0,0 +1,2 @@
+import type { SqliteDb } from "./sqlite-driver-interface.js";
+export declare function openDatabase(file: string): SqliteDb;

package/dist/sqlite-driver-bun.js

@@ -0,0 +1,31 @@
+import { Database } from "bun:sqlite";
+export function openDatabase(file) {
+    const db = new Database(file);
+    return {
+        prepare(sql) {
+            const stmt = db.prepare(sql);
+            return {
+                reader: true,
+                all(params) {
+                    return stmt.all(...params);
+                },
+                run(params) {
+                    const result = stmt.run(...params);
+                    return {
+                        changes: result.changes,
+                        lastInsertRowid: result.lastInsertRowid,
+                    };
+                },
+                iterate(params) {
+                    return stmt.iterate(...params);
+                },
+            };
+        },
+        exec(sql) {
+            db.exec(sql);
+        },
+        close() {
+            db.close();
+        },
+    };
+}

package/dist/sqlite-driver-interface.d.ts

@@ -0,0 +1,14 @@
+export interface SqliteStatement {
+    readonly reader: boolean;
+    all(params: ReadonlyArray<unknown>): unknown[];
+    run(params: ReadonlyArray<unknown>): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    iterate(params: ReadonlyArray<unknown>): IterableIterator<unknown>;
+}
+export interface SqliteDb {
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): void;
+    close(): void;
+}

package/dist/sqlite-driver-interface.js

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

package/dist/sqlite-driver-node.d.ts

@@ -0,0 +1,2 @@
+import type { SqliteDb } from "./sqlite-driver-interface.js";
+export declare function openDatabase(file: string): SqliteDb;

package/dist/sqlite-driver-node.js

@@ -0,0 +1,31 @@
+import Database from "better-sqlite3";
+export function openDatabase(file) {
+    const db = new Database(file);
+    return {
+        prepare(sql) {
+            const stmt = db.prepare(sql);
+            return {
+                reader: stmt.reader,
+                all(params) {
+                    return stmt.all(...params);
+                },
+                run(params) {
+                    const result = stmt.run(...params);
+                    return {
+                        changes: result.changes,
+                        lastInsertRowid: result.lastInsertRowid,
+                    };
+                },
+                iterate(params) {
+                    return stmt.iterate(...params);
+                },
+            };
+        },
+        exec(sql) {
+            db.exec(sql);
+        },
+        close() {
+            db.close();
+        },
+    };
+}

package/dist/transaction-store.d.ts

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from "async_hooks";
+export interface TxEntry {
+    executor: unknown;
+}
+export declare const txStorage: AsyncLocalStorage<string>;
+export declare const setTx: (id: string, entry: TxEntry) => void;
+export declare const getTx: (id: string) => TxEntry | undefined;
+export declare const deleteTx: (id: string) => void;
+export declare const currentTxId: () => string | undefined;

package/dist/transaction-store.js

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from "async_hooks";
+const txMap = new Map();
+export const txStorage = new AsyncLocalStorage();
+export const setTx = (id, entry) => {
+    txMap.set(id, entry);
+};
+export const getTx = (id) => txMap.get(id);
+export const deleteTx = (id) => {
+    txMap.delete(id);
+};
+export const currentTxId = () => txStorage.getStore();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@telorun/sql",
+  "version": "0.1.1",
+  "type": "module",
+  "exports": {
+    "./sql-connection": {
+      "bun": "./src/sql-connection-controller.ts",
+      "import": "./dist/sql-connection-controller.js"
+    },
+    "./sql-query": {
+      "bun": "./src/sql-query-controller.ts",
+      "import": "./dist/sql-query-controller.js"
+    },
+    "./sql-exec": {
+      "bun": "./src/sql-exec-controller.ts",
+      "import": "./dist/sql-exec-controller.js"
+    },
+    "./sql-transaction": {
+      "bun": "./src/sql-transaction-controller.ts",
+      "import": "./dist/sql-transaction-controller.js"
+    },
+    "./sqlite-driver": {
+      "bun": "./src/sqlite-driver-bun.ts",
+      "import": "./dist/sqlite-driver-node.js"
+    },
+    "./sql-migration": {
+      "bun": "./src/sql-migration-controller.ts",
+      "import": "./dist/sql-migration-controller.js"
+    },
+    "./sql-migrations": {
+      "bun": "./src/sql-migrations-controller.ts",
+      "import": "./dist/sql-migrations-controller.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.8.0",
+    "pg": "^8.20.0",
+    "kysely": "^0.28.15",
+    "@telorun/sdk": "0.2.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.0.0",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^20.0.0",
+    "@types/pg": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json"
+  }
+}