@jxsuite/connector 0.1.0

package/src/table-actions.ts

@@ -0,0 +1,156 @@
+/**
+ * Table-actions — shared machinery behind TableInsert / TableUpdate / TableDelete.
+ *
+ * The action classes lower to inline `Function` defs in compiled sites: an event handler that reads
+ * the submitting form's FormData (merged under the def's literal `values`), fetches the /_jx/data
+ * route, and on success bumps `state._v` — the read-after-write convention every lowered TableQuery
+ * URL subscribes to (see table-shared.ts). In the interpreter (dev canvas) the classes resolve to
+ * an equivalent real function.
+ */
+
+import { jsObjectSource, jsValueSource, resolveIdValue } from "./table-shared.ts";
+import type { LowerContext } from "./table-state.ts";
+
+export type ActionMethod = "POST" | "PATCH" | "DELETE";
+
+/** The def shape all three action classes accept. */
+export interface ActionDef {
+  table?: string;
+  id?: unknown;
+  /** Literal payload columns merged over the submitting form's FormData. */
+  values?: Record<string, unknown>;
+  _document?: { route?: { _pathParams?: Record<string, string> } };
+  [key: string]: unknown;
+}
+
+/** Build the /_jx/data URL JS-source expression for a lowered action. */
+function urlSource(method: ActionMethod, def: ActionDef, context: LowerContext): string {
+  const table = def.table ?? "";
+  if (method === "POST") {
+    return jsValueSource(`/_jx/data/${table}`);
+  }
+  const id = resolveIdValue(def.id, context.route?._pathParams) ?? "";
+  return jsValueSource(`/_jx/data/${table}/${id}`);
+}
+
+/**
+ * Lower an action def into an inline `Function` def (specs/extensions.md §8.3).
+ *
+ * @param {ActionMethod} method
+ * @param {ActionDef} def
+ * @param {LowerContext} [context]
+ * @returns {Record<string, unknown>} A core Function def with an `event` parameter
+ */
+export function lowerActionDef(
+  method: ActionMethod,
+  def: ActionDef,
+  context: LowerContext = {},
+): Record<string, unknown> {
+  const url = urlSource(method, def, context);
+  const lines: string[] = [
+    "if (event && typeof event.preventDefault === 'function') event.preventDefault();",
+  ];
+  if (method === "DELETE") {
+    lines.push(
+      `fetch(${url}, { method: 'DELETE' }).then(function (res) {`,
+      "  if (res.ok) { state._v = (state._v || 0) + 1; }",
+      "});",
+    );
+  } else {
+    lines.push(
+      "var form = event && event.target && event.target.tagName === 'FORM' ? event.target : " +
+        "((event && event.target && event.target.form) || null);",
+      "var payload = Object.assign({}, form ? Object.fromEntries(new FormData(form)) : {}, " +
+        `${jsObjectSource(def.values)});`,
+      `fetch(${url}, { method: '${method}', headers: { 'Content-Type': 'application/json' }, ` +
+        "body: JSON.stringify(payload) }).then(function (res) {",
+      "  if (res.ok) {",
+      ...(method === "POST"
+        ? ["    if (form && typeof form.reset === 'function') form.reset();"]
+        : []),
+      "    state._v = (state._v || 0) + 1;",
+      "  }",
+      "});",
+    );
+  }
+  return {
+    $prototype: "Function",
+    body: lines.join("\n"),
+    parameters: ["event"],
+    timing: "client",
+  };
+}
+
+/** Evaluate a `${...}`-bearing values object against a live scope (interpreter path). */
+function evaluateValues(
+  values: Record<string, unknown> | undefined,
+  scope: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(values ?? {})) {
+    if (typeof value === "string" && value.includes("${")) {
+      try {
+        const fn = new Function("state", `return \`${value}\`;`) as (
+          state: Record<string, unknown>,
+        ) => unknown;
+        out[key] = fn(scope);
+      } catch {
+        out[key] = value;
+      }
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the live handler an action class resolves to in the interpreter (dev canvas).
+ *
+ * @param {ActionMethod} method
+ * @param {ActionDef} config
+ * @returns {(scope: Record<string, unknown>, event?: Event) => Promise<boolean>} Resolves true when
+ *   the write succeeded (and `scope._v` was bumped)
+ */
+export function makeActionHandler(method: ActionMethod, config: ActionDef) {
+  return async (scope: Record<string, unknown>, event?: Event): Promise<boolean> => {
+    if (event && typeof event.preventDefault === "function") {
+      event.preventDefault();
+    }
+    const table = config.table ?? "";
+    let url = `/_jx/data/${table}`;
+    if (method !== "POST") {
+      const id = resolveIdValue(config.id, config._document?.route?._pathParams) ?? "";
+      url = `${url}/${id}`;
+    }
+
+    let init: RequestInit;
+    let form: HTMLFormElement | null = null;
+    if (method === "DELETE") {
+      init = { method };
+    } else {
+      const target = event?.target as
+        | (HTMLElement & { form?: HTMLFormElement | null })
+        | null
+        | undefined;
+      form =
+        target && target.tagName === "FORM" ? (target as HTMLFormElement) : (target?.form ?? null);
+      const formData = form ? Object.fromEntries(new FormData(form)) : {};
+      const payload = { ...formData, ...evaluateValues(config.values, scope) };
+      init = {
+        body: JSON.stringify(payload),
+        headers: { "Content-Type": "application/json" },
+        method,
+      };
+    }
+
+    const response = await fetch(url, init);
+    if (response.ok) {
+      if (method === "POST" && form && typeof form.reset === "function") {
+        form.reset();
+      }
+      scope._v = ((scope._v as number) || 0) + 1;
+    }
+    return response.ok;
+  };
+}

package/src/table-delete.ts

@@ -0,0 +1,28 @@
+/**
+ * Table-delete — the TableDelete action class (DELETE /_jx/data/:table/:id).
+ *
+ * No payload; the id resolves like TableUpdate's. On success `state._v` bumps so lowered queries
+ * refetch. See table-actions.ts for the shared machinery.
+ */
+
+import { lowerActionDef, makeActionHandler } from "./table-actions.ts";
+import type { ActionDef } from "./table-actions.ts";
+import type { LowerContext } from "./table-state.ts";
+
+export class TableDelete {
+  config: ActionDef;
+
+  constructor(config: ActionDef) {
+    this.config = config;
+  }
+
+  /** Resolve to the live delete handler (interpreter path). */
+  resolve() {
+    return makeActionHandler("DELETE", this.config);
+  }
+
+  /** Static `lower` capability: compile away into an inline Function def. */
+  static lower(def: ActionDef, context: LowerContext = {}): Record<string, unknown> {
+    return lowerActionDef("DELETE", def, context);
+  }
+}

package/src/table-insert.ts

@@ -0,0 +1,29 @@
+/**
+ * Table-insert — the TableInsert action class (POST /_jx/data/:table).
+ *
+ * Wire it to a form: `"onsubmit": { "$ref": "#/state/addComment" }`. The handler merges the form's
+ * FormData under the def's literal `values`, POSTs the row, resets the form, and bumps `state._v`
+ * so lowered queries refetch. See table-actions.ts for the shared machinery.
+ */
+
+import { lowerActionDef, makeActionHandler } from "./table-actions.ts";
+import type { ActionDef } from "./table-actions.ts";
+import type { LowerContext } from "./table-state.ts";
+
+export class TableInsert {
+  config: ActionDef;
+
+  constructor(config: ActionDef) {
+    this.config = config;
+  }
+
+  /** Resolve to the live insert handler (interpreter path). */
+  resolve() {
+    return makeActionHandler("POST", this.config);
+  }
+
+  /** Static `lower` capability: compile away into an inline Function def. */
+  static lower(def: ActionDef, context: LowerContext = {}): Record<string, unknown> {
+    return lowerActionDef("POST", def, context);
+  }
+}

package/src/table-node.ts

@@ -0,0 +1,111 @@
+/**
+ * Table-node — direct-database resolution for TableQuery/TableEntry under node/Bun.
+ *
+ * The dev server's resolve proxy and compiler-timing SSG bakes land here (browsers fetch /_jx/data
+ * instead — see table-state.ts). The connection resolves through the first-party provider map
+ * (`resolveDialect`); sqlite connections are additively auto-synced before the first read so a
+ * fresh project queries cleanly. Errors propagate — the state classes turn them into warnings +
+ * empty results.
+ */
+
+import { Kysely } from "kysely";
+import { fromStorage, planTable } from "./columns.ts";
+import { resolveDialect } from "./connectors.ts";
+import { syncTables } from "./ddl.ts";
+import { applyFilter, applySort, normalizeFilter, normalizeSort } from "./query.ts";
+import { tablesForConnection } from "./provider-utils.ts";
+import type { SqlDialectKind } from "./columns.ts";
+import type { ConnectionsConfig } from "./connectors.ts";
+import type { DynamicDatabase } from "./query.ts";
+import type { TableQueryDef } from "./table-shared.ts";
+import type { TableDef } from "./types.ts";
+
+/** The `_project`-bearing config shape hosts inject into state classes. */
+export interface TableNodeConfig extends TableQueryDef {
+  id?: unknown;
+  _project?: {
+    config?: ConnectionsConfig & { data?: Record<string, TableDef> };
+    root?: string;
+    data?: Record<string, TableDef>;
+    [key: string]: unknown;
+  };
+}
+
+interface OpenedTable {
+  db: Kysely<DynamicDatabase>;
+  kind: SqlDialectKind;
+  tables: Record<string, TableDef>;
+  tableName: string;
+}
+
+/** Open the table's connection, auto-syncing local sqlite databases additively. */
+async function openTable(config: TableNodeConfig): Promise<OpenedTable> {
+  const project = config._project ?? {};
+  const projectConfig = project.config ?? {};
+  const tables = projectConfig.data ?? project.data ?? {};
+  const tableName = config.table ?? "";
+  const tableDef = tables[tableName];
+  if (!tableDef) {
+    throw new Error(`unknown table "${tableName}" (no data section entry)`);
+  }
+  const env: Record<string, unknown> = {
+    ...process.env,
+    ...(project.root === undefined ? {} : { JX_PROJECT_ROOT: project.root }),
+  };
+  const { dialect, type } = await resolveDialect(tableDef.connection, projectConfig, env);
+  const db = new Kysely<DynamicDatabase>({ dialect });
+  const connection = projectConfig.connections?.[tableDef.connection];
+  if (connection?.provider === "sqlite") {
+    // Additive-only and idempotent — a fresh local database materializes on first read.
+    await syncTables(db, tablesForConnection(tables, tableDef.connection), { dialect: type });
+  }
+  return { db, kind: type, tableName, tables };
+}
+
+/**
+ * Query a table with the def's filter/sort/limit/offset (the content grammar).
+ *
+ * @param {TableNodeConfig} config
+ * @returns {Promise<Record<string, unknown>[]>}
+ */
+export async function queryTable(config: TableNodeConfig): Promise<Record<string, unknown>[]> {
+  const { db, kind, tables, tableName } = await openTable(config);
+  try {
+    const plan = planTable(tableName, tables[tableName]!, tables, kind);
+    let qb = db.selectFrom(tableName).selectAll();
+    qb = applyFilter(qb, normalizeFilter(config.filter), plan.columns);
+    qb = applySort(qb, normalizeSort(config.sort), plan.columns);
+    if (typeof config.limit === "number" && config.limit > 0) {
+      qb = qb.limit(config.limit);
+    }
+    if (typeof config.offset === "number" && config.offset > 0) {
+      qb = qb.limit(config.limit ?? 100_000_000).offset(config.offset);
+    }
+    const rows = await qb.execute();
+    return rows.map((row) => fromStorage(plan.columns, row));
+  } finally {
+    await db.destroy();
+  }
+}
+
+/**
+ * Fetch one row by id, or null.
+ *
+ * @param {TableNodeConfig} config
+ * @param {string} id
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+export async function getEntry(
+  config: TableNodeConfig,
+  id: string,
+): Promise<Record<string, unknown> | null> {
+  const { db, kind, tables, tableName } = await openTable(config);
+  try {
+    const plan = planTable(tableName, tables[tableName]!, tables, kind);
+    const key = plan.idType === "integer" ? Number(id) : id;
+    const row = await db.selectFrom(tableName).selectAll().where("id", "=", key).executeTakeFirst();
+    return row ? fromStorage(plan.columns, row) : null;
+  } finally {
+    await db.destroy();
+  }
+}

package/src/table-shared.ts

@@ -0,0 +1,131 @@
+/**
+ * Table-shared — pure helpers behind the table state classes and their `lower` capability.
+ *
+ * Everything here is browser-safe string building: /_jx/data URL construction with
+ * template-placeholder preservation, `#/$params/` id resolution, and the JS-source emission used by
+ * lowered action bodies.
+ *
+ * Cache-busting convention (`_v`): lowered TableQuery Requests append `_v=${(state._v || 0)}` to
+ * their URL, and lowered write actions end with `state._v = (state._v || 0) + 1`. The compiled
+ * Request effect re-runs whenever a template-referenced signal changes, so bumping `_v` after a
+ * successful write refetches every query on the page — read-after-write without any bespoke runtime
+ * machinery.
+ */
+
+/** A `${...}` template span (Jx binding syntax preserved through lowering). */
+const TEMPLATE_SPAN = /(\$\{[^}]*\})/;
+
+/**
+ * Percent-encode a query value while leaving `${...}` template spans intact, so the runtime's
+ * template evaluation still sees them after lowering.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function encodeQueryValue(value: string): string {
+  return value
+    .split(TEMPLATE_SPAN)
+    .map((part) => (TEMPLATE_SPAN.test(part) ? part : encodeURIComponent(part)))
+    .join("");
+}
+
+/** The wire-facing query options a TableQuery/TableEntry def may carry. */
+export interface TableQueryDef {
+  table?: string;
+  filter?: unknown;
+  sort?: unknown;
+  limit?: number;
+  offset?: number;
+  include?: string | string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Build a /_jx/data URL for a query def, preserving template placeholders.
+ *
+ * @param {TableQueryDef} def
+ * @param {{ id?: string; versionParam?: boolean }} [options] - `id` appends a row path segment;
+ *   `versionParam` appends the `_v` cache-busting template (lowered Requests only)
+ * @returns {string}
+ */
+export function buildDataUrl(
+  def: TableQueryDef,
+  options: { id?: string; versionParam?: boolean } = {},
+): string {
+  const table = def.table ?? "";
+  const parts: string[] = [];
+  if (def.filter !== undefined && def.filter !== null) {
+    parts.push(`filter=${encodeQueryValue(JSON.stringify(def.filter))}`);
+  }
+  if (def.sort !== undefined && def.sort !== null) {
+    parts.push(`sort=${encodeQueryValue(JSON.stringify(def.sort))}`);
+  }
+  if (typeof def.limit === "number") {
+    parts.push(`limit=${def.limit}`);
+  }
+  if (typeof def.offset === "number") {
+    parts.push(`offset=${def.offset}`);
+  }
+  const include = Array.isArray(def.include) ? def.include.join(",") : def.include;
+  if (include) {
+    parts.push(`include=${encodeQueryValue(include)}`);
+  }
+  if (options.versionParam) {
+    // Read-after-write: writes bump state._v, re-running the compiled Request effect.
+    parts.push("_v=${(state._v || 0)}");
+  }
+  const path = options.id === undefined ? `/_jx/data/${table}` : `/_jx/data/${table}/${options.id}`;
+  return parts.length > 0 ? `${path}?${parts.join("&")}` : path;
+}
+
+/**
+ * Resolve an id value: `#/$params/<name>` refs read route params, everything else passes through as
+ * a string (template placeholders included).
+ *
+ * @param {unknown} id - The def's id value
+ * @param {Record<string, string> | undefined} pathParams - Route params when known
+ * @returns {string | undefined}
+ */
+export function resolveIdValue(
+  id: unknown,
+  pathParams: Record<string, string> | undefined,
+): string | undefined {
+  if (id === null || id === undefined) {
+    return undefined;
+  }
+  if (typeof id === "object") {
+    const ref = (id as { $ref?: string }).$ref;
+    if (typeof ref === "string" && ref.startsWith("#/$params/")) {
+      const param = ref.slice("#/$params/".length);
+      return pathParams?.[param];
+    }
+    return undefined;
+  }
+  return String(id);
+}
+
+/**
+ * Emit the JS source for a literal value inside a lowered Function body. Strings carrying `${...}`
+ * become template literals (evaluated against state at runtime); everything else is inlined JSON.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function jsValueSource(value: unknown): string {
+  if (typeof value === "string" && value.includes("${")) {
+    const escaped = value.replaceAll("\\", String.raw`\\`).replaceAll("`", "\\`");
+    return `\`${escaped}\``;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+/** Emit the JS source of an object literal whose values go through {@link jsValueSource}. */
+export function jsObjectSource(values: Record<string, unknown> | undefined): string {
+  if (!values || Object.keys(values).length === 0) {
+    return "{}";
+  }
+  const entries = Object.entries(values).map(
+    ([key, value]) => `${JSON.stringify(key)}: ${jsValueSource(value)}`,
+  );
+  return `{ ${entries.join(", ")} }`;
+}

package/src/table-state.ts

@@ -0,0 +1,134 @@
+/**
+ * Table-state — the TableQuery and TableEntry state classes.
+ *
+ * Both are ordinary external classes (constructor + resolve) with a static `lower` capability
+ * (specs/extensions.md §8.3). In browsers, resolve() fetches the live /_jx/data routes (dev server
+ * and deployed workers serve the same wire contract). Under node/Bun (dev-server resolve proxy,
+ * compiler-timing SSG bakes) it reaches the database directly through the node-only sibling module,
+ * loaded through an opaque specifier so browser bundles never pull kysely dialects in. When the
+ * database is unreachable at compile time (e.g. D1 without CLOUDFLARE_API_TOKEN) the bake degrades
+ * to an empty result with a warning, never a failed build.
+ *
+ * Lowering: in compiled sites a `timing: "client"` TableQuery becomes a core `Request` def whose
+ * URL carries the query params (template placeholders preserved) plus the `_v` read-after-write
+ * cache-busting param — see table-shared.ts.
+ */
+
+import { buildDataUrl, resolveIdValue } from "./table-shared.ts";
+import type { TableQueryDef } from "./table-shared.ts";
+
+/** Route/document context injected by hosts under `_document`. */
+interface DocumentContext {
+  route?: { _pathParams?: Record<string, string> };
+  [key: string]: unknown;
+}
+
+/** The context object hosts pass to `lower(def, context)`. */
+export interface LowerContext {
+  route?: { _pathParams?: Record<string, string>; sourcePath?: string };
+  projectConfig?: Record<string, unknown>;
+  root?: string;
+}
+
+interface TableStateConfig extends TableQueryDef {
+  id?: unknown;
+  _document?: DocumentContext;
+  _project?: Record<string, unknown>;
+}
+
+/** True when running in a browser (canvas/client); node hosts take the direct-database path. */
+function inBrowser(): boolean {
+  return typeof document !== "undefined" && typeof fetch === "function";
+}
+
+/** The surface of the node-only sibling module (see table-node.ts). */
+interface TableNodeModule {
+  queryTable: (config: TableStateConfig) => Promise<unknown>;
+  getEntry: (config: TableStateConfig, id: string) => Promise<unknown>;
+}
+
+/** Import the node-only sibling through an opaque specifier (bundlers must not follow it). */
+async function nodeModule(): Promise<TableNodeModule> {
+  const specifier = "./table-node.ts";
+  return (await import(specifier)) as TableNodeModule;
+}
+
+export class TableQuery {
+  config: TableStateConfig;
+
+  constructor(config: TableStateConfig) {
+    this.config = config;
+  }
+
+  /** Rows matching the def's filter/sort/limit — over HTTP in browsers, directly under node. */
+  async resolve(): Promise<unknown> {
+    if (inBrowser()) {
+      const response = await fetch(buildDataUrl(this.config));
+      return response.ok ? await response.json() : [];
+    }
+    try {
+      const { queryTable } = await nodeModule();
+      return await queryTable(this.config);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`TableQuery("${this.config.table}") could not reach the database: ${message}`);
+      return [];
+    }
+  }
+
+  /** Static `lower` capability: compile away into a core Request def (client fetch). */
+  static lower(def: Record<string, unknown>): Record<string, unknown> {
+    return {
+      $prototype: "Request",
+      timing: "client",
+      url: buildDataUrl(def as TableQueryDef, { versionParam: true }),
+      ...(def.default === undefined ? { default: [] } : { default: def.default }),
+    };
+  }
+}
+
+export class TableEntry {
+  config: TableStateConfig;
+
+  constructor(config: TableStateConfig) {
+    this.config = config;
+  }
+
+  /** One row by id (`#/$params/` refs resolve against the route), or null. */
+  async resolve(): Promise<unknown> {
+    const { _document } = this.config;
+    const id = resolveIdValue(this.config.id, _document?.route?._pathParams);
+    if (id === undefined || id === "") {
+      return null;
+    }
+    if (inBrowser()) {
+      const response = await fetch(buildDataUrl(this.config, { id }));
+      return response.ok ? await response.json() : null;
+    }
+    try {
+      const { getEntry } = await nodeModule();
+      return await getEntry(this.config, id);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`TableEntry("${this.config.table}") could not reach the database: ${message}`);
+      return null;
+    }
+  }
+
+  /** Static `lower` capability: compile away into a core Request def for one row. */
+  static lower(def: Record<string, unknown>, context: LowerContext = {}): Record<string, unknown> {
+    const id = resolveIdValue(def.id, context.route?._pathParams);
+    if (id === undefined) {
+      console.warn(
+        `TableEntry("${String(def.table)}"): id did not resolve at lower time — ` +
+          `the compiled Request will fetch an empty id`,
+      );
+    }
+    return {
+      $prototype: "Request",
+      timing: "client",
+      url: buildDataUrl(def as TableQueryDef, { id: id ?? "", versionParam: true }),
+      ...(def.default === undefined ? { default: null } : { default: def.default }),
+    };
+  }
+}

package/src/table-update.ts

@@ -0,0 +1,29 @@
+/**
+ * Table-update — the TableUpdate action class (PATCH /_jx/data/:table/:id).
+ *
+ * The id may be a literal, a `${...}` template, or `{ "$ref": "#/$params/<name>" }` (resolved
+ * against the route at lower time). Payload = form FormData merged under the def's `values`. See
+ * table-actions.ts for the shared machinery.
+ */
+
+import { lowerActionDef, makeActionHandler } from "./table-actions.ts";
+import type { ActionDef } from "./table-actions.ts";
+import type { LowerContext } from "./table-state.ts";
+
+export class TableUpdate {
+  config: ActionDef;
+
+  constructor(config: ActionDef) {
+    this.config = config;
+  }
+
+  /** Resolve to the live update handler (interpreter path). */
+  resolve() {
+    return makeActionHandler("PATCH", this.config);
+  }
+
+  /** Static `lower` capability: compile away into an inline Function def. */
+  static lower(def: ActionDef, context: LowerContext = {}): Record<string, unknown> {
+    return lowerActionDef("PATCH", def, context);
+  }
+}