@telorun/sql 0.8.0 → 0.10.0

package/README.md

@@ -23,7 +23,7 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api.yaml
+$ telo ./examples/hello-api
 
 {"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
 ```
@@ -44,146 +44,7 @@ $ telo ./examples/hello-api.yaml
 
 ## Example manifest
 
-Here is an example Telo application that defines a simple HTTP API:
-
-```yaml
-kind: Telo.Application
-metadata:
-  name: feedback
-  version: 1.0.0
-  description: |
-    A complete feedback collection REST API — no code, pure YAML.
-    Persists entries to SQLite and serves them over HTTP.
-imports:
-  Http: std/http-server@0.12.0
-  Sql: std/sql@0.9.2
-targets:
-  - !ref Migrations
-  - !ref Server
----
-# SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
-kind: Sql.Connection
-metadata:
-  name: Db
-driver: sqlite
-file: ./tmp/feedback.db
----
-# Migrations: applied automatically before the server starts
-kind: Sql.Migrations
-metadata:
-  name: Migrations
-connection: !ref Db
----
-kind: Sql.Migration
-metadata:
-  name: Migration_20260413_182154_CreateFeedback
-version: 20260413_182154_CreateFeedback
-sql: |
-  CREATE TABLE IF NOT EXISTS feedback (
-    id        INTEGER PRIMARY KEY AUTOINCREMENT,
-    text      TEXT    NOT NULL,
-    source    TEXT,
-    score     INTEGER NOT NULL DEFAULT 0,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-  )
----
-kind: Http.Server
-metadata:
-  name: Server
-baseUrl: http://localhost:8844
-port: 8844
-logger: true
-openapi:
-  info:
-    title: Feedback API
-    version: 1.0.0
-mounts:
-  - path: /v1
-    mount: !ref FeedbackRoutes
----
-kind: Http.Api
-metadata:
-  name: FeedbackRoutes
-routes:
-  # POST /v1/feedback — insert a new entry, score derived from body length heuristic
-  - request:
-      path: /feedback
-      method: POST
-      schema:
-        body:
-          type: object
-          properties:
-            text:
-              type: string
-              minLength: 1
-            source:
-              type: string
-          required: [ text ]
-    handler:
-      kind: Sql.Exec
-      connection: !ref Db
-    inputs:
-      sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
-      bindings:
-        - "${{ request.body.text }}"
-        - "${{ request.body.source }}"
-        - "${{ size(request.body.text) }}"
-    response:
-      - status: 201
-        headers:
-          Content-Type: application/json
-        body:
-          ok: true
-          message: Feedback received
-
-  # GET /v1/feedback — list all entries, newest first
-  - request:
-      path: /feedback
-      method: GET
-    handler:
-      kind: Sql.Select
-      connection: !ref Db
-      from: feedback
-      columns: [ id, text, source, score, created_at ]
-      orderBy:
-        - { column: created_at, direction: desc }
-    response:
-      - status: 200
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows }}"
-
-  # GET /v1/feedback/{id} — fetch a single entry
-  - request:
-      path: /feedback/{id}
-      method: GET
-      schema:
-        params:
-          type: object
-          properties:
-            id:
-              type: integer
-          required: [ id ]
-    handler:
-      kind: Sql.Select
-      connection: !ref Db
-      from: feedback
-      columns: [ id, text, source, score, created_at ]
-      where:
-        - { column: id, op: "=", value: "${{ request.params.id }}" }
-    response:
-      - status: 200
-        when: "size(result.rows) > 0"
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows[0] }}"
-      - status: 404
-        headers:
-          Content-Type: application/json
-        body:
-          ok: false
-          message: Not found
-```
+See [examples/](./examples/) for a list of working applications.
 
 ## Status
 

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { SqlConnectionResource, createSqlConnection, type SqlDriver, type PlaceholderStyle, } from "./sql-connection-controller.js";
-export { resolveSqlConnection } from "./sql-connection-ref.js";
-export type { SqliteDb, SqliteStatement } from "./sqlite-driver-interface.js";
+export { SqlConnectionBase } from "./sql-connection-base.js";
+export { quoteAnsiIdentifier, type PlaceholderStyle, type SqlConnection, type SqlDialect, } from "./sql-connection.js";
+export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";

package/dist/index.js

@@ -1,2 +1,3 @@
-export { SqlConnectionResource, createSqlConnection, } from "./sql-connection-controller.js";
-export { resolveSqlConnection } from "./sql-connection-ref.js";
+export { SqlConnectionBase } from "./sql-connection-base.js";
+export { quoteAnsiIdentifier, } from "./sql-connection.js";
+export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";

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

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 interface SqlCommandManifest {
@@ -7,7 +7,7 @@ interface SqlCommandManifest {
         name: string;
         module: string;
     };
-    connection?: SqlConnectionResource;
+    connection?: SqlConnection;
     transaction?: SqlTransactionResource;
     inputs: {
         sql: string;

package/dist/sql-command-controller.js

@@ -10,7 +10,8 @@ class SqlCommandResource {
     async invoke(input) {
         const m = this.manifest;
         const ctx = this.ctx;
-        const connection = resolveSqlConnection(m.connection, ctx) ?? m.transaction?.getConnection();
+        const connection = resolveSqlConnection(m.connection, ctx, () => `Sql.Command "${m.metadata.name}": 'connection'`) ??
+            m.transaction?.getConnection();
         if (!connection) {
             throw new Error("Sql: either 'connection' or 'transaction' must be set");
         }

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

@@ -0,0 +1,29 @@
+import { type Kysely, type QueryResult } from "kysely";
+import type { SqlConnection, SqlDialect } from "./sql-connection.js";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+/**
+ * The dialect-neutral half of a connection: statement execution, transaction
+ * scoping, template binding and row-count normalization over a kysely instance.
+ *
+ * Backends extend it, supply their {@link SqlDialect}, and override only what is
+ * genuinely theirs — `teardown` for resources kysely does not own, `executeScript`
+ * where the driver has a native multi-statement path.
+ */
+export declare abstract class SqlConnectionBase implements SqlConnection {
+    readonly dialect: SqlDialect;
+    protected readonly db: Kysely<any>;
+    constructor(db: Kysely<any>, dialect: SqlDialect);
+    get kysely(): Kysely<any>;
+    init(): Promise<void>;
+    teardown(): Promise<void>;
+    transaction<T>(cb: () => Promise<T>): Promise<T>;
+    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    executeTemplate<T>(fragments: string[], values: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    /** Hand the whole script to the driver as one statement. Backends whose driver
+     *  needs a dedicated multi-statement entry point override this. */
+    executeScript(sql: string): Promise<void>;
+    toRowCount(result: QueryResult<unknown>): number;
+    snapshot(): Record<string, unknown>;
+    private placeholder;
+    private resolveExecutor;
+}

package/dist/{sql-connection-controller.js → sql-connection-base.js}

@@ -2,20 +2,22 @@ import { randomUUID } from "crypto";
 import { CompiledQuery } from "kysely";
 import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-store.js";
 /**
- * Driver-agnostic SQL connection. The kysely instance (and, for SQLite, the
- * underlying database handle used by `executeScript`) is built by the driver
- * backend (`sql-postgres`, `sql-sqlite`) and handed in via
- * {@link createSqlConnection}. Everything here — execution, transactions,
- * placeholder style, row-count normalization — is transport-neutral.
+ * The dialect-neutral half of a connection: statement execution, transaction
+ * scoping, template binding and row-count normalization over a kysely instance.
+ *
+ * Backends extend it, supply their {@link SqlDialect}, and override only what is
+ * genuinely theirs — `teardown` for resources kysely does not own, `executeScript`
+ * where the driver has a native multi-statement path.
  */
-export class SqlConnectionResource {
-    driver;
+export class SqlConnectionBase {
+    dialect;
     db;
-    sqlite;
-    constructor(driver, db, sqlite) {
-        this.driver = driver;
+    constructor(db, dialect) {
+        this.dialect = dialect;
         this.db = db;
-        this.sqlite = sqlite;
+    }
+    get kysely() {
+        return this.db;
     }
     async init() {
         await this.db.connection().execute(async () => {
@@ -41,12 +43,6 @@ export class SqlConnectionResource {
         const executor = this.resolveExecutor(transaction);
         return executor.executeQuery(CompiledQuery.raw(sql, params));
     }
-    get placeholderStyle() {
-        return this.driver === "postgres" ? "numbered" : "qmark";
-    }
-    /** Assemble SQL from literal fragments by interleaving driver-native
-     *  placeholders, then bind `values` positionally. `fragments.length` must
-     *  equal `values.length + 1`. */
     async executeTemplate(fragments, values, transaction) {
         let sql = fragments[0] ?? "";
         for (let i = 1; i < fragments.length; i++) {
@@ -54,14 +50,9 @@ export class SqlConnectionResource {
         }
         return this.execute(sql, values, transaction);
     }
-    placeholder(index) {
-        return this.placeholderStyle === "numbered" ? `$${index}` : "?";
-    }
+    /** Hand the whole script to the driver as one statement. Backends whose driver
+     *  needs a dedicated multi-statement entry point override this. */
     async executeScript(sql) {
-        if (this.driver === "sqlite") {
-            this.sqlite?.exec(sql);
-            return;
-        }
         await this.execute(sql);
     }
     toRowCount(result) {
@@ -70,12 +61,12 @@ export class SqlConnectionResource {
         }
         return result.rows.length;
     }
-    get kysely() {
-        return this.db;
-    }
     snapshot() {
         return {};
     }
+    placeholder(index) {
+        return this.dialect.placeholderStyle === "numbered" ? `$${index}` : "?";
+    }
     resolveExecutor(transaction) {
         if (transaction) {
             transaction.assertActive();
@@ -90,12 +81,3 @@ export class SqlConnectionResource {
         return this.db;
     }
 }
-/**
- * Build a connection from a driver-constructed kysely instance. Driver backends
- * (`sql-postgres`, `sql-sqlite`) own dialect construction and call this; the
- * `sqlite` handle is required only for SQLite (its `executeScript` runs through
- * the native handle).
- */
-export function createSqlConnection(driver, db, sqlite) {
-    return new SqlConnectionResource(driver, db, sqlite);
-}

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

@@ -1,8 +1,11 @@
-import type { ResourceContext } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
-interface ConnectionRef {
-    name: string;
-    alias?: string;
-}
-export declare function resolveSqlConnection(value: SqlConnectionResource | ConnectionRef | undefined, ctx: ResourceContext): SqlConnectionResource | undefined;
-export {};
+import type { KindRef, ResourceContext } from "@telorun/sdk";
+import type { SqlConnection } from "./sql-connection.js";
+/** True when a value already exposes the connection contract (Phase-5 injected). */
+export declare function isSqlConnection(value: unknown): value is SqlConnection;
+/**
+ * Resolve a `connection` `!ref` field to a live connection. The slot is optional
+ * — an unset one yields `undefined` so the caller can fall back to a `transaction`
+ * — but a slot that IS set must resolve. `describe` names the owning resource and
+ * slot, so the failure points at a concrete manifest location.
+ */
+export declare function resolveSqlConnection(value: SqlConnection | KindRef<SqlConnection> | undefined, ctx: ResourceContext, describe: () => string): SqlConnection | undefined;

package/dist/sql-connection-ref.js

@@ -1,24 +1,15 @@
-export function resolveSqlConnection(value, ctx) {
-    if (!value) {
+/** True when a value already exposes the connection contract (Phase-5 injected). */
+export function isSqlConnection(value) {
+    return typeof value?.execute === "function";
+}
+/**
+ * Resolve a `connection` `!ref` field to a live connection. The slot is optional
+ * — an unset one yields `undefined` so the caller can fall back to a `transaction`
+ * — but a slot that IS set must resolve. `describe` names the owning resource and
+ * slot, so the failure points at a concrete manifest location.
+ */
+export function resolveSqlConnection(value, ctx, describe) {
+    if (!value)
         return undefined;
-    }
-    if (typeof value.execute === "function") {
-        return value;
-    }
-    const ref = value;
-    if (typeof ref.name !== "string") {
-        throw new Error("Sql: invalid connection reference");
-    }
-    // Cross-module reference (`!ref Alias.Connection`): a connection resolved
-    // inside a nested library is not Phase-5-injected, so the controller receives
-    // the raw `{name, alias}` ref and must route through the import's exported
-    // scope rather than a bare local lookup.
-    if (ref.alias && ref.alias !== "Self") {
-        const instance = ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name);
-        if (typeof instance?.execute !== "function") {
-            throw new Error(`Sql: connection reference '${ref.alias}.${ref.name}' did not resolve to an exported connection instance.`);
-        }
-        return instance;
-    }
-    return ctx.moduleContext.getInstance(ref.name);
+    return ctx.resolveRef(value, isSqlConnection, describe, "std/sql#Connection");
 }

package/dist/sql-connection.d.ts

@@ -0,0 +1,45 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import type { Kysely, QueryResult } from "kysely";
+import type { SqlTransactionResource } from "./sql-transaction-controller.js";
+/** Native bind-placeholder syntax: SQLite binds anonymous `?`, PostgreSQL binds
+ *  numbered `$1`, `$2`, … */
+export type PlaceholderStyle = "qmark" | "numbered";
+/**
+ * Renders the SQL constructs that differ between database dialects. A backend
+ * supplies one; the `Sql.*` operations build statements through it and never
+ * branch on which database sits behind the connection.
+ */
+export interface SqlDialect {
+    readonly placeholderStyle: PlaceholderStyle;
+    /** Quote an identifier — table, column, alias. */
+    quoteIdentifier(name: string): string;
+    /** Render set membership. Dialects disagree: PostgreSQL binds the whole array
+     *  to a single placeholder, SQLite binds one per element. `column` arrives
+     *  already quoted. */
+    renderIn(column: string, values: unknown[], addParam: (value: unknown) => string): string;
+}
+/** ANSI identifier quoting (`"name"`), for the dialects that follow the standard. */
+export declare function quoteAnsiIdentifier(name: string): string;
+/**
+ * The contract every SQL backend satisfies and every `Sql.*` operation programs
+ * against. Backends (`sql-postgres`, `sql-sqlite`) own their own implementation
+ * — usually by extending {@link SqlConnectionBase} — so nothing in this module
+ * knows which databases exist.
+ */
+export interface SqlConnection extends ResourceInstance {
+    readonly dialect: SqlDialect;
+    /** The underlying kysely instance, when the backend is built on one —
+     *  {@link SqlConnectionBase} always provides it. Optional because the contract
+     *  must stay implementable by a driver kysely does not support; a consumer
+     *  that needs it (`Sql.Migrations`) checks and fails with a clear message. */
+    readonly kysely?: Kysely<any>;
+    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    /** Assemble SQL from literal fragments by interleaving dialect-native
+     *  placeholders, then bind `values` positionally. */
+    executeTemplate<T>(fragments: string[], values: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    /** Run a multi-statement script. */
+    executeScript(sql: string): Promise<void>;
+    transaction<T>(cb: () => Promise<T>): Promise<T>;
+    /** Rows affected by a write, normalized across drivers. */
+    toRowCount(result: QueryResult<unknown>): number;
+}

package/dist/sql-connection.js

@@ -0,0 +1,4 @@
+/** ANSI identifier quoting (`"name"`), for the dialects that follow the standard. */
+export function quoteAnsiIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}

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

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 interface MigrationEntry {
     statement?: string;
     statements?: string[];
@@ -9,7 +9,7 @@ interface SqlMigrationsManifest {
         name: string;
         module: string;
     };
-    connection: SqlConnectionResource;
+    connection: SqlConnection;
     migrations?: Record<string, MigrationEntry>;
 }
 declare class SqlMigrationsResource implements ResourceInstance {

package/dist/sql-migrations-controller.js

@@ -32,7 +32,7 @@ class SqlMigrationsResource {
         this.ctx = ctx;
     }
     async run() {
-        const conn = resolveSqlConnection(this.manifest.connection, this.ctx) ?? failMissingConnection();
+        const conn = resolveSqlConnection(this.manifest.connection, this.ctx, () => `Sql.Migrations "${this.manifest.metadata.name}": 'connection'`) ?? failMissingConnection();
         const migrations = {};
         // Legacy: standalone `Sql.Migration` resources in the same module scope.
         for (const [, { resource }] of this.ctx.moduleContext.resourceInstances) {
@@ -50,6 +50,11 @@ class SqlMigrationsResource {
             }
             migrations[name] = statements;
         }
+        if (!conn.kysely) {
+            throw new Error(`Sql.Migrations '${this.manifest.metadata.name}': the referenced connection is not ` +
+                `built on kysely, which this kind's migration runner requires. Use a backend that ` +
+                `extends SqlConnectionBase, or run the statements through Sql.Command.`);
+        }
         const migrator = new Migrator({
             db: conn.kysely,
             provider: new TeloMigrationProvider(migrations),

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

@@ -1,12 +1,12 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 interface SqlQueryManifest {
     metadata: {
         name: string;
         module: string;
     };
-    connection?: SqlConnectionResource;
+    connection?: SqlConnection;
     transaction?: SqlTransactionResource;
     inputs: {
         sql: string;

package/dist/sql-query-controller.js

@@ -10,13 +10,15 @@ class SqlQueryResource {
     async invoke(input) {
         const m = this.manifest;
         const ctx = this.ctx;
-        const connection = resolveConnection(m.connection, m.transaction, ctx);
+        const connection = resolveConnection(m.connection, m.transaction, ctx, () => `Sql.Query "${m.metadata.name}": 'connection'`);
         const result = await runSql(connection, m.transaction, input, ctx);
         return { rows: result.rows, rowCount: result.rows.length };
     }
 }
-function resolveConnection(connection, transaction, ctx) {
-    return (resolveSqlConnection(connection, ctx) ?? transaction?.getConnection() ?? failMissingConnection());
+function resolveConnection(connection, transaction, ctx, describe) {
+    return (resolveSqlConnection(connection, ctx, describe) ??
+        transaction?.getConnection() ??
+        failMissingConnection());
 }
 function failMissingConnection() {
     throw new Error("Sql: either 'connection' or 'transaction' must be set");

package/dist/sql-run.d.ts

@@ -1,6 +1,6 @@
 import { type ResourceContext } from "@telorun/sdk";
 import type { QueryResult } from "kysely";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 /** Execute the `sql` input of a Query/Exec resource against `connection`.
  *
@@ -13,4 +13,4 @@ import type { SqlTransactionResource } from "./sql-transaction-controller.js";
  *
  *  Mixing a `!sql` template with `bindings` is rejected. A plain string `sql`
  *  with neither is executed verbatim. */
-export declare function runSql(connection: SqlConnectionResource, transaction: SqlTransactionResource | undefined, input: unknown, ctx: ResourceContext): Promise<QueryResult<Record<string, unknown>>>;
+export declare function runSql(connection: SqlConnection, transaction: SqlTransactionResource | undefined, input: unknown, ctx: ResourceContext): Promise<QueryResult<Record<string, unknown>>>;

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

@@ -1,5 +1,5 @@
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
-import type { SqlConnectionResource } from "./sql-connection-controller.js";
+import type { SqlConnection } from "./sql-connection.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 type ColumnDef = string | {
@@ -44,7 +44,7 @@ interface SelectManifest {
         name: string;
         module: string;
     };
-    connection?: SqlConnectionResource;
+    connection?: SqlConnection;
     transaction?: SqlTransactionResource;
     from: string;
     columns?: ColumnDef[];