@nanobpm/urban 0.5.1 → 0.7.0

package/dist/runtime/core/host.d.ts

@@ -99,6 +99,10 @@ export interface EngineClient {
         processInstanceKey: string;
         variables?: Record<string, unknown>;
     }>;
+    /** Cancel a running process instance (the pages surface's row-cancel action). */
+    cancelInstance(input: {
+        processInstanceKey: string;
+    }): Promise<void>;
     /** Publish a message for correlation. */
     publishMessage(input: {
         name: string;

package/dist/runtime/core/manifest.d.ts

@@ -36,6 +36,14 @@ export interface SurfaceDecl {
     enabled?: boolean;
     path?: string;
     agent?: string;
+    /** pages surface: directory of `*.page.json` (relative to app root). Default `pages`. */
+    pagesDir?: string;
+    /** pages surface: the page served at `/`. Default `home`. */
+    homePage?: string;
+    /** pages surface: max rows a `dataGrid` fetch returns. Default 200. */
+    rowLimit?: number;
+    /** pages surface: the injected default datasource name. Default `app`. */
+    sourceName?: string;
 }
 export interface AppManifest {
     $schema?: string;

package/dist/runtime/core/modules/datasource.d.ts

@@ -1,6 +1,7 @@
 import type { RuntimeContext } from "../context.ts";
 import type { SqliteDb } from "../host.ts";
 import type { DomainType } from "../manifest.ts";
+import { Table, type DataSource as GatewayDataSource } from "./gateway.ts";
 /** A typed accessor over a table declared in manifest `types`. */
 export declare class TypeRepo {
     private readonly db;
@@ -20,6 +21,8 @@ export interface ProvisionedSource {
     readonly name: string;
     readonly driver: string;
     readonly db: SqliteDb;
+    /** The record-oriented gateway over this source — the RAD `Table<T>` surface (ADR 0055). */
+    readonly source: GatewayDataSource;
     readonly migrationsApplied: string[];
     close(): void;
 }
@@ -31,6 +34,12 @@ export declare class DataLayer {
     source(name?: string): ProvisionedSource;
     /** A typed accessor for a declared domain type (uses the default source). */
     repo(typeName: string, sourceName?: string): TypeRepo;
+    /** The record-oriented `DataSource` gateway for a source (the default when omitted) — the
+     * raw-SQL + `Table<T>` surface app handlers bind to (ADR 0055). */
+    open(sourceName?: string): GatewayDataSource;
+    /** A typed `Table<T>` gateway over one table on a source (the default when omitted). `pk` is
+     * the primary-key column (default "id"). */
+    table<T extends object = Record<string, unknown>>(name: string, pk?: string, sourceName?: string): Table<T>;
     describe(): Record<string, unknown>;
     closeAll(): void;
 }

package/dist/runtime/core/modules/datasource.js

@@ -2,6 +2,7 @@
 // `types` domain model. Only the `sqlite` driver is implemented; other drivers hit an
 // explicit seam (they are declared in the manifest but not yet provisioned). This is the
 // runtime side of ADR 0024 (datasource) + ADR 0040 (domain model), scoped to what an app needs.
+import { makeGateway } from "./gateway.js";
 function sqlitePathFromUrl(url) {
     // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
     return url.replace(/^(file|sqlite):(\/\/)?/, "");
@@ -93,6 +94,16 @@ export class DataLayer {
             throw new Error(`no such type "${typeName}"`);
         return new TypeRepo(this.source(sourceName).db, typeName, def);
     }
+    /** The record-oriented `DataSource` gateway for a source (the default when omitted) — the
+     * raw-SQL + `Table<T>` surface app handlers bind to (ADR 0055). */
+    open(sourceName) {
+        return this.source(sourceName).source;
+    }
+    /** A typed `Table<T>` gateway over one table on a source (the default when omitted). `pk` is
+     * the primary-key column (default "id"). */
+    table(name, pk, sourceName) {
+        return this.open(sourceName).table(name, pk);
+    }
     describe() {
         return {
             default: this.defaultSource,
@@ -153,6 +164,7 @@ async function provisionSqlite(ctx, name, src) {
         name,
         driver: "sqlite",
         db,
+        source: makeGateway(db),
         migrationsApplied,
         close: () => db.close(),
     };

package/dist/runtime/core/modules/gateway.d.ts

@@ -0,0 +1,81 @@
+import type { SqliteDb } from "../host.ts";
+export type Row = Record<string, unknown>;
+export interface ExecResult {
+    /** Rows changed by an INSERT/UPDATE/DELETE. */
+    changed: number;
+    /** Rowid of the last inserted row, when the driver reports one. */
+    lastInsertId?: number | bigint;
+}
+/** One column of a table, from the datasource's introspected schema. */
+export interface ColumnMeta {
+    name: string;
+    type: string;
+    notNull: boolean;
+    primaryKey: boolean;
+}
+/** One foreign-key constraint: `column` references `refTable(refColumn)`. `refColumn` is empty
+ * when the FK targets the parent's primary key without naming a column; `onDelete` is the
+ * referential action (e.g. `CASCADE`), empty when none was declared. */
+export interface ForeignKeyMeta {
+    column: string;
+    refTable: string;
+    refColumn: string;
+    onDelete: string;
+}
+/** One table: its columns, index names, and foreign keys. Powers domain-type projection and
+ * the page runtime's list/detail binding. */
+export interface TableMeta {
+    name: string;
+    columns: ColumnMeta[];
+    indexes: string[];
+    foreignKeys: ForeignKeyMeta[];
+}
+/** The one thin, uniform interface behind every driver (ADR 0024 §2) — the `TDataSet`
+ * equivalent. Every consumer shares exactly this surface, so the driver underneath is
+ * interchangeable. */
+export interface DataSource {
+    /** Run a SELECT (or any row-returning statement) and collect the rows. */
+    query(sql: string, params?: unknown[]): Promise<Row[]>;
+    /** Run a non-row statement (INSERT/UPDATE/DELETE/DDL). */
+    exec(sql: string, params?: unknown[]): Promise<ExecResult>;
+    /** Run `fn` inside a transaction, committing on success and rolling back on throw. The
+     * handle passed to `fn` targets the same connection. */
+    tx<T>(fn: (t: DataSource) => Promise<T>): Promise<T>;
+    /** Introspect the datasource's tables/columns/indexes/foreign keys. */
+    schema(): Promise<TableMeta[]>;
+    /** A typed gateway over one table — the RAD "TTable". `pk` is the primary-key column
+     * (default "id"). */
+    table<T extends object = Row>(name: string, pk?: string): Table<T>;
+}
+/** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
+export declare function quoteIdent(name: string): string;
+/** A typed gateway over a single table — the record-oriented data object a handler binds to
+ * instead of hand-writing SQL (the Delphi `TTable`/data-module idea, ADR 0029 §6). It builds
+ * parameterised SQL from a typed row object's own keys, so callers manipulate rows as records.
+ * `T` comes from a generated row type; this class is generic *runtime* and knows nothing about
+ * any specific schema. `pk` is the primary-key column (default `id`). */
+export declare class Table<T extends object = Row> {
+    #private;
+    readonly name: string;
+    readonly pk: string;
+    constructor(src: DataSource, name: string, pk?: string);
+    /** Insert one row (only the present keys are written); returns the new primary-key value
+     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    insert(row: Partial<T>): Promise<number | bigint>;
+    /** Fetch the row with the given primary key, or `undefined`. */
+    get(id: unknown): Promise<T | undefined>;
+    /** Every row (optionally capped at `limit`). */
+    all(limit?: number): Promise<T[]>;
+    /** Rows matching an equality filter (keys ANDed). An empty filter matches all rows. */
+    find(where?: Partial<T>): Promise<T[]>;
+    /** The first row matching an equality filter, or `undefined`. */
+    findOne(where?: Partial<T>): Promise<T | undefined>;
+    /** Patch the row with the given primary key; returns rows changed. */
+    update(id: unknown, patch: Partial<T>): Promise<number>;
+    /** Delete the row with the given primary key; returns rows changed. */
+    delete(id: unknown): Promise<number>;
+    /** Count rows matching an equality filter (all rows when omitted). */
+    count(where?: Partial<T>): Promise<number>;
+}
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
+export declare function makeGateway(db: SqliteDb): DataSource;

package/dist/runtime/core/modules/gateway.js

@@ -0,0 +1,170 @@
+// The record-oriented datasource gateway (ADR 0024 / ADR 0029 §6, ADR 0055 phase 1).
+//
+// This is the runtime port of the console-generated `data-sdk.ts` `DataSource` + `Table<T>`:
+// the RAD "TTable" a handler binds to instead of hand-writing SQL. It sits on the runtime's
+// synchronous `SqliteDb` host seam but keeps the *async* app-facing contract (every method
+// returns a Promise), so an app-hosted worker/action/surface handler reaches typed records the
+// same way regardless of which driver backs the source underneath.
+//
+//   const db = app.data.open();                 // the default source as a DataSource
+//   await db.exec("INSERT INTO orders(id) VALUES (?)", [id]);
+//   const orders = db.table<Order>("orders");   // a typed gateway over one table
+//   await orders.insert({ id, status: "new" });
+//   const o = await orders.get(id);
+/** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
+export function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** Build a parameterised ` WHERE a = ? AND b = ?` clause from an equality map; an empty map
+ * yields an empty clause (matches all rows). Takes `object` (not `Row`) so a `Partial<T>` for a
+ * generated `interface` row type (which lacks a string index signature) is accepted. */
+function whereClause(where) {
+    const w = where;
+    const keys = Object.keys(w);
+    if (keys.length === 0)
+        return { clause: "", params: [] };
+    const clause = " WHERE " + keys.map((k) => `${quoteIdent(k)} = ?`).join(" AND ");
+    return { clause, params: keys.map((k) => w[k]) };
+}
+/** A typed gateway over a single table — the record-oriented data object a handler binds to
+ * instead of hand-writing SQL (the Delphi `TTable`/data-module idea, ADR 0029 §6). It builds
+ * parameterised SQL from a typed row object's own keys, so callers manipulate rows as records.
+ * `T` comes from a generated row type; this class is generic *runtime* and knows nothing about
+ * any specific schema. `pk` is the primary-key column (default `id`). */
+export class Table {
+    name;
+    pk;
+    #src;
+    constructor(src, name, pk = "id") {
+        this.#src = src;
+        this.name = name;
+        this.pk = pk;
+    }
+    /** Insert one row (only the present keys are written); returns the new primary-key value
+     * (the inserted rowid for an INTEGER PRIMARY KEY). */
+    async insert(row) {
+        const keys = Object.keys(row);
+        if (keys.length === 0) {
+            throw new Error(`Table(${this.name}).insert: no columns to insert`);
+        }
+        const cols = keys.map(quoteIdent).join(", ");
+        const ph = keys.map(() => "?").join(", ");
+        const r = await this.#src.exec(`INSERT INTO ${quoteIdent(this.name)} (${cols}) VALUES (${ph})`, keys.map((k) => row[k]));
+        if (r.lastInsertId == null) {
+            // The driver reported no rowid — treat as a failed/ambiguous insert rather than
+            // silently returning 0, which a caller could mistake for a real primary key.
+            throw new Error(`Table(${this.name}).insert: driver reported no lastInsertId`);
+        }
+        return r.lastInsertId;
+    }
+    /** Fetch the row with the given primary key, or `undefined`. */
+    async get(id) {
+        const rows = await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)} WHERE ${quoteIdent(this.pk)} = ? LIMIT 1`, [id]);
+        return rows[0];
+    }
+    /** Every row (optionally capped at `limit`). */
+    async all(limit) {
+        const lim = typeof limit === "number" && Number.isFinite(limit)
+            ? ` LIMIT ${Math.max(0, Math.floor(limit))}`
+            : "";
+        return (await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${lim}`));
+    }
+    /** Rows matching an equality filter (keys ANDed). An empty filter matches all rows. */
+    async find(where = {}) {
+        const { clause, params } = whereClause(where);
+        return (await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause}`, params));
+    }
+    /** The first row matching an equality filter, or `undefined`. */
+    async findOne(where = {}) {
+        const { clause, params } = whereClause(where);
+        const rows = await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause} LIMIT 1`, params);
+        return rows[0];
+    }
+    /** Patch the row with the given primary key; returns rows changed. */
+    async update(id, patch) {
+        const keys = Object.keys(patch);
+        if (keys.length === 0)
+            return 0;
+        const set = keys.map((k) => `${quoteIdent(k)} = ?`).join(", ");
+        const r = await this.#src.exec(`UPDATE ${quoteIdent(this.name)} SET ${set} WHERE ${quoteIdent(this.pk)} = ?`, [...keys.map((k) => patch[k]), id]);
+        return r.changed;
+    }
+    /** Delete the row with the given primary key; returns rows changed. */
+    async delete(id) {
+        const r = await this.#src.exec(`DELETE FROM ${quoteIdent(this.name)} WHERE ${quoteIdent(this.pk)} = ?`, [id]);
+        return r.changed;
+    }
+    /** Count rows matching an equality filter (all rows when omitted). */
+    async count(where = {}) {
+        const { clause, params } = whereClause(where);
+        const rows = await this.#src.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(this.name)}${clause}`, params);
+        return Number(rows[0]?.n ?? 0);
+    }
+}
+/** A `DataSource` implemented over the runtime's synchronous `SqliteDb` host seam. The methods
+ * are async to hold the app-facing contract; the work underneath is synchronous. */
+class SqliteGateway {
+    #db;
+    constructor(db) {
+        this.#db = db;
+    }
+    async query(sql, params = []) {
+        return this.#db.all(sql, params);
+    }
+    async exec(sql, params = []) {
+        const r = this.#db.run(sql, params);
+        return { changed: Number(r.changes), lastInsertId: r.lastInsertRowid };
+    }
+    async tx(fn) {
+        this.#db.exec("BEGIN");
+        try {
+            const out = await fn(this);
+            this.#db.exec("COMMIT");
+            return out;
+        }
+        catch (e) {
+            this.#db.exec("ROLLBACK");
+            throw e;
+        }
+    }
+    async schema() {
+        // Exclude SQLite internals (`sqlite_%`) and Nano's own bookkeeping tables (`_urban_%` /
+        // `_nano_%`, e.g. the migrations ledger): neither is a user/domain table, so they must
+        // never surface in the domain model, DB Manager, or forms.
+        const tables = this.#db.all("SELECT name FROM sqlite_master WHERE type = 'table' " +
+            "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '\\_urban\\_%' ESCAPE '\\' " +
+            "AND name NOT LIKE '\\_nano\\_%' ESCAPE '\\' ORDER BY name");
+        const out = [];
+        for (const t of tables) {
+            const cols = this.#db.all(`PRAGMA table_info(${quoteIdent(t.name)})`);
+            const idx = this.#db.all(`PRAGMA index_list(${quoteIdent(t.name)})`);
+            const fks = this.#db.all(`PRAGMA foreign_key_list(${quoteIdent(t.name)})`);
+            out.push({
+                name: t.name,
+                columns: cols.map((c) => ({
+                    name: c.name,
+                    type: c.type,
+                    notNull: !!c.notnull,
+                    primaryKey: !!c.pk,
+                })),
+                indexes: idx.map((i) => String(i.name)),
+                foreignKeys: fks.map((f) => ({
+                    column: f.from,
+                    refTable: f.table,
+                    refColumn: f.to ?? "",
+                    onDelete: f.on_delete && f.on_delete.toUpperCase() !== "NO ACTION"
+                        ? f.on_delete.toUpperCase()
+                        : "",
+                })),
+            });
+        }
+        return out;
+    }
+    table(name, pk = "id") {
+        return new Table(this, name, pk);
+    }
+}
+/** Wrap a provisioned `SqliteDb` as the record-oriented `DataSource` gateway. */
+export function makeGateway(db) {
+    return new SqliteGateway(db);
+}

package/dist/runtime/core/modules/pages.d.ts

@@ -0,0 +1,42 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { EngineClient } from "../host.ts";
+import { type Route } from "../router.ts";
+/** The subset of the datasource gateway the page runtime needs. */
+export interface PagesDataSource {
+    query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    schema(): Promise<{
+        name: string;
+    }[]>;
+}
+export interface PagesOptions {
+    /** Directory holding `*.page.json` (relative to the app root). Default `pages`. */
+    pagesDir?: string;
+    /** The page served at `/`. Default `home`. */
+    homePage?: string;
+    /** Max rows a `dataGrid` fetch returns. Default 200. */
+    rowLimit?: number;
+    /** The injected default datasource name (the alias apps bind to). Default `app`. */
+    sourceName?: string;
+}
+export interface PagesDeps {
+    db: PagesDataSource;
+    engine: EngineClient;
+    /** Read a page file; injectable for tests. */
+    readPage(path: string): Promise<string>;
+}
+/**
+ * Build the page-runtime routes over an injected datasource + engine. Pure over its deps
+ * so it is unit-testable without a real host/server (see pages.test.ts).
+ */
+export declare function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[];
+export interface PagesHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/**
+ * Mount the `pages` surface when enabled in the manifest. Binds the page runtime to the
+ * app's datasource gateway (`app.data.open(source)`), engine, and the host's file read.
+ * Returns no routes when the surface is disabled or absent.
+ */
+export declare function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle;