@jxsuite/connector 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# `@jxsuite/connector`
+
+> Database connections and dynamic data tables for Jx sites.
+
+## Overview
+
+`@jxsuite/connector` is the Jx extension bridging sites to live databases. It contributes two
+project.json sections and serves them over the canonical `/_jx/data` wire contract
+(specs/extensions.md §11–§12):
+
+- **`connections`** — named database connections. Entries carry identifiers and env-var _names_
+  only (`binding`, `databaseId`, `urlEnv`, `hyperdriveId`); secret values live in `.dev.vars`
+  locally and the platform secret store in production. Providers: Cloudflare **D1**, **Supabase**
+  (postgres over postgres-js/Hyperdrive), and file-backed **Sqlite** (bun:sqlite).
+- **`data`** — dynamic tables. Each entry names its connection, a column `schema` (plain Jx field
+  schemas plus relationship refs — see specs/relationships.md), an `id` strategy
+  (`"uuid"` | `"integer"`), `timestamps`, `indexes`, `permissions`
+  (`public | none | authenticated | owner | role:<r>`), and an optional `ownerField`.
+
+Kysely is the data bridge: one JSON-drivable query/schema builder across D1, postgres, and
+sqlite, on Workers, Bun, and node.
+
+## Enable it
+
+```json
+{
+  "extensions": ["@jxsuite/parser", "@jxsuite/connector"],
+  "connections": { "main": { "provider": "sqlite" } },
+  "data": {
+    "comments": {
+      "connection": "main",
+      "permissions": { "read": "public", "insert": "public" },
+      "schema": {
+        "type": "object",
+        "properties": { "message": { "type": "string" } },
+        "required": ["message"]
+      }
+    }
+  }
+}
+```
+
+Then `jx schema` (regenerates the project schemas) and `jx db push [--dry-run]` (additive-only
+schema sync — tables and columns are created, never dropped or retyped). In dev, the server
+stands D1 connections in with local SQLite at `.jx/data/<connection>.sqlite`, auto-synced on
+first touch.
+
+## State classes
+
+- `TableQuery` / `TableEntry` — rows (content filter grammar: `filter`, `sort`, `limit`,
+  `offset`, `include`) and single rows by id (`#/$params/<name>` refs resolve against the route).
+- `TableInsert` / `TableUpdate` / `TableDelete` — form-friendly write actions
+  (`"onsubmit": { "$ref": "#/state/addComment" }` reads the form's FormData).
+
+In compiled sites these **lower** to core defs (specs/extensions.md §8.3): queries become plain
+`Request` fetches against `/_jx/data`, actions become inline `Function` handlers — no extension
+code ships to the browser. Read-after-write rides the `_v` convention: lowered queries append
+`_v=${(state._v || 0)}` to their URL and successful writes bump `state._v`, re-running every
+query effect on the page.
+
+## Permissions (fail-closed)
+
+`public` rules pass without auth; `none` always denies; every other rule requires the auth
+extension's hooks on the shared server context — absent auth means 401. Defaults: read `public`,
+writes `none`. Owner rules scope reads/writes via `ownerField`.
+
+## Field-union extras
+
+Table columns are plain core field schemas plus relationship refs, so this package ships **no**
+`schemas.fields` fragment — the manifest convention (a fragment whose `$defs` members join the
+per-project field union) exists for extensions that need shapes beyond the core union.
+
+## Versioning
+
+Published to npm as `@jxsuite/connector` — TypeScript source, like every `@jxsuite` package,
+following the monorepo's release train. Extensions may depend on core packages
+(`@jxsuite/schema`) but never the reverse; the auth extension builds on this package's
+`resolveDialect` seam and permission types (`@jxsuite/connector/types`).

package/jx-extension.json

@@ -0,0 +1,20 @@
+{
+  "name": "@jxsuite/connector",
+  "title": "Data & Connections",
+  "description": "Database connections and dynamic data tables served over /_jx/data",
+  "classes": {
+    "D1": "./src/D1.class.json",
+    "Supabase": "./src/Supabase.class.json",
+    "Sqlite": "./src/Sqlite.class.json",
+    "Connections": "./src/Connections.class.json",
+    "Data": "./src/Data.class.json",
+    "TableQuery": "./src/TableQuery.class.json",
+    "TableEntry": "./src/TableEntry.class.json",
+    "TableInsert": "./src/TableInsert.class.json",
+    "TableUpdate": "./src/TableUpdate.class.json",
+    "TableDelete": "./src/TableDelete.class.json"
+  },
+  "schemas": {
+    "project": "./schemas/project.fragment.schema.json"
+  }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@jxsuite/connector",
+  "version": "0.1.0",
+  "description": "Jx database connections and dynamic data tables served over /_jx/data",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "extensions/connector"
+  },
+  "files": [
+    "src/",
+    "jx-extension.json",
+    "schemas/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/connectors.ts",
+    "./types": "./src/types.ts",
+    "./columns": "./src/columns.ts",
+    "./ddl": "./src/ddl.ts",
+    "./query": "./src/query.ts",
+    "./validate": "./src/validate.ts",
+    "./worker": "./src/worker.ts",
+    "./d1": "./src/d1.ts",
+    "./supabase": "./src/supabase.ts",
+    "./sqlite": "./src/sqlite.ts",
+    "./table-state": "./src/table-state.ts",
+    "./table-node": "./src/table-node.ts",
+    "./table-shared": "./src/table-shared.ts",
+    "./table-actions": "./src/table-actions.ts",
+    "./table-insert": "./src/table-insert.ts",
+    "./table-update": "./src/table-update.ts",
+    "./table-delete": "./src/table-delete.ts",
+    "./provider-utils": "./src/provider-utils.ts",
+    "./dialects/bun-sqlite": "./src/dialects/bun-sqlite.ts",
+    "./dialects/d1-http": "./src/dialects/d1-http.ts",
+    "./jx-extension.json": "./jx-extension.json",
+    "./schemas/project.fragment.schema.json": "./schemas/project.fragment.schema.json",
+    "./D1.class.json": "./src/D1.class.json",
+    "./Supabase.class.json": "./src/Supabase.class.json",
+    "./Sqlite.class.json": "./src/Sqlite.class.json",
+    "./Connections.class.json": "./src/Connections.class.json",
+    "./Data.class.json": "./src/Data.class.json",
+    "./TableQuery.class.json": "./src/TableQuery.class.json",
+    "./TableEntry.class.json": "./src/TableEntry.class.json",
+    "./TableInsert.class.json": "./src/TableInsert.class.json",
+    "./TableUpdate.class.json": "./src/TableUpdate.class.json",
+    "./TableDelete.class.json": "./src/TableDelete.class.json"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage",
+    "upgrade": "bunx npm-check-updates -u && bun install"
+  },
+  "dependencies": {
+    "@jxsuite/schema": "workspace:^",
+    "kysely": "^0.28.17",
+    "kysely-d1": "^0.4.0",
+    "kysely-postgres-js": "^3.0.0",
+    "postgres": "^3.4.9"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260711.1",
+    "ajv": "^8.20.0",
+    "hono": "^4.11.3"
+  },
+  "jx": "./jx-extension.json"
+}

package/schemas/project.fragment.schema.json

@@ -0,0 +1,122 @@
+{
+  "$id": "https://jxsuite.com/schema/ext/connector/project/v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Connector project fragment",
+  "description": "Project-schema fragment contributed by @jxsuite/connector: the `connections` section naming database connections (identifiers only — secret values never enter project.json) and the `data` section declaring dynamic tables served over /_jx/data.",
+  "type": "object",
+  "properties": {
+    "connections": {
+      "description": "Named database connections. Entries carry identifiers and env-var NAMES only; secret values live in .dev.vars locally and the platform secret store in production (specs/extensions.md §13).",
+      "type": "object",
+      "additionalProperties": {
+        "description": "Connection definition. `provider` names a connector class provider id from an enabled extension (\"d1\", \"supabase\", \"sqlite\").",
+        "type": "object",
+        "properties": {
+          "provider": {
+            "description": "Connector provider id (the `connector.provider` of an enabled connector class).",
+            "type": "string"
+          },
+          "binding": {
+            "description": "Cloudflare binding name for this connection (D1 database binding, or the Hyperdrive binding for postgres providers).",
+            "type": "string"
+          },
+          "databaseId": {
+            "description": "Cloudflare D1 database UUID (identifier, not a secret).",
+            "type": "string"
+          },
+          "accountId": {
+            "description": "Cloudflare account id for HTTP-API access (falls back to the CLOUDFLARE_ACCOUNT_ID env var).",
+            "type": "string"
+          },
+          "urlEnv": {
+            "description": "NAME of the env var holding the postgres connection URL (e.g. \"SUPABASE_DB_URL\"). The value itself is a secret and never enters project.json.",
+            "type": "string"
+          },
+          "hyperdriveId": {
+            "description": "Cloudflare Hyperdrive configuration id fronting a postgres connection from Workers.",
+            "type": "string"
+          },
+          "file": {
+            "description": "SQLite database file path relative to the project root (defaults to ./.jx/data/<name>.sqlite).",
+            "type": "string"
+          }
+        },
+        "required": ["provider"]
+      }
+    },
+    "data": {
+      "description": "Dynamic data tables. Each key names a table served at /_jx/data/<name>; rows live in the named connection's database. Schema sync is additive-only (`jx db push`).",
+      "type": "object",
+      "additionalProperties": {
+        "description": "Table definition: connection, column schema, id strategy, and permissions.",
+        "type": "object",
+        "properties": {
+          "connection": {
+            "description": "Name of a `connections` entry this table lives in.",
+            "type": "string"
+          },
+          "schema": {
+            "description": "Column schema. `properties` values are field schemas from the effective project field union (relationship refs included).",
+            "type": "object",
+            "properties": {
+              "type": { "const": "object" },
+              "properties": {
+                "description": "Column definitions; values are field schemas from the effective project field union.",
+                "type": "object",
+                "additionalProperties": { "$ref": "https://jxsuite.com/schema/project/fields/v2" }
+              },
+              "required": {
+                "description": "Columns every row must provide on insert.",
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          },
+          "id": {
+            "description": "Primary-key strategy: \"uuid\" (text ids via crypto.randomUUID) or \"integer\" (auto-increment).",
+            "enum": ["uuid", "integer"],
+            "default": "uuid"
+          },
+          "timestamps": {
+            "description": "Maintain created_at / updated_at columns (ISO 8601 strings set by the data mount).",
+            "type": "boolean",
+            "default": true
+          },
+          "indexes": {
+            "description": "Secondary indexes: a column name, or an array of column names for a composite index.",
+            "type": "array",
+            "items": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+              ]
+            }
+          },
+          "permissions": {
+            "description": "Per-action access rules. Defaults: read \"public\", writes \"none\". Rules beyond \"public\" require the auth extension; without it the data mount fails closed.",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "read": { "$ref": "#/$defs/PermissionRule" },
+              "insert": { "$ref": "#/$defs/PermissionRule" },
+              "update": { "$ref": "#/$defs/PermissionRule" },
+              "delete": { "$ref": "#/$defs/PermissionRule" }
+            }
+          },
+          "ownerField": {
+            "description": "Column recording the owning user id — required by \"owner\" permission rules; set on insert and used to scope owner reads/writes.",
+            "type": "string"
+          }
+        },
+        "required": ["connection", "schema"]
+      }
+    }
+  },
+  "$defs": {
+    "PermissionRule": {
+      "description": "Access rule: public | none | authenticated | owner | role:<role>.",
+      "type": "string",
+      "pattern": "^(public|none|authenticated|owner|role:.+)$"
+    }
+  }
+}

package/src/Connections.class.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/connector/Connections.class.json",
+  "title": "Connections",
+  "description": "Owner of the project.json `connections` section: named database connections carrying identifiers and env-var names only — secret values never enter project.json",
+  "$prototype": "Class",
+  "extends": "Object",
+
+  "project": {
+    "key": "connections",
+    "title": "Connections",
+    "description": "Named database connections (identifiers only; secrets live in .dev.vars / the platform secret store)"
+  },
+
+  "$studio": {
+    "settings": {
+      "icon": "sp-icon-data",
+      "label": "Connections",
+      "order": 60,
+      "layout": "map",
+      "entry": {
+        "ui": {
+          "urlEnv": { "control": "secret" }
+        },
+        "newEntry": { "provider": "sqlite" }
+      }
+    }
+  }
+}

package/src/D1.class.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/connector/D1.class.json",
+  "title": "D1",
+  "description": "Cloudflare D1 connection provider: binding-backed inside Workers, HTTP-API-backed for deploys, tests, and compiler bakes",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./d1.js",
+
+  "connector": {
+    "provider": "d1",
+    "kind": "sqlite",
+    "local": "sqlite",
+    "serve": "@jxsuite/connector/worker",
+    "module": "@jxsuite/connector/d1"
+  },
+
+  "$defs": {
+    "methods": {
+      "dialect": {
+        "role": "dialect",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "dialect",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          {
+            "identifier": "connection",
+            "type": { "type": "object" },
+            "description": "Connection definition (with $name injected by the host)"
+          },
+          {
+            "identifier": "env",
+            "type": { "type": "object" },
+            "description": "Host environment: bindings and env vars"
+          }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Kysely dialect for the connection: the D1 binding when present, else the D1 HTTP API via CLOUDFLARE_API_TOKEN"
+      },
+      "deploySchema": {
+        "role": "deploySchema",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "deploySchema",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          {
+            "identifier": "tables",
+            "type": { "type": "object" },
+            "description": "Table definitions of this connection"
+          },
+          { "identifier": "connection", "type": { "type": "object" } },
+          {
+            "identifier": "options",
+            "type": {
+              "type": "object",
+              "properties": { "env": { "type": "object" }, "dryRun": { "type": "boolean" } }
+            }
+          }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Additive schema sync: { statements, applied, warnings }"
+      },
+      "bindings": {
+        "role": "bindings",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "bindings",
+        "timing": ["compiler", "server"],
+        "parameters": [{ "identifier": "connection", "type": { "type": "object" } }],
+        "returnType": { "type": "object" },
+        "description": "Wrangler config fragment: the d1_databases binding for this connection"
+      },
+      "testConnection": {
+        "role": "testConnection",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "testConnection",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          { "identifier": "connection", "type": { "type": "object" } },
+          { "identifier": "env", "type": { "type": "object" } }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Probe the connection with `select 1`: { ok, error? }"
+      }
+    }
+  }
+}

package/src/Data.class.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/connector/Data.class.json",
+  "title": "Data",
+  "description": "Owner of the project.json `data` section (dynamic tables) and the /_jx/data server mount implementing the canonical data wire contract",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./worker.js",
+
+  "project": {
+    "key": "data",
+    "title": "Data Tables",
+    "description": "Connection-backed dynamic tables served at /_jx/data/<table>",
+    "referenceable": true
+  },
+
+  "server": {
+    "basePath": "/_jx/data",
+    "order": 20,
+    "module": "@jxsuite/connector/worker"
+  },
+
+  "$studio": {
+    "settings": {
+      "icon": "sp-icon-table",
+      "label": "Data Tables",
+      "order": 55,
+      "layout": "map",
+      "entry": {
+        "ui": {
+          "schema": { "control": "schema-builder" },
+          "connection": { "enum": { "$ref": "#/$context/connections" } }
+        },
+        "newEntry": {
+          "connection": "",
+          "schema": { "type": "object", "properties": {}, "required": [] },
+          "permissions": { "read": "public" }
+        }
+      }
+    }
+  },
+
+  "$defs": {
+    "returnTypes": {
+      "SectionData": {
+        "type": "object",
+        "description": "Map of table name → table definition, stored as _project.data"
+      }
+    },
+
+    "methods": {
+      "projectData": {
+        "role": "projectData",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "projectData",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `data` section value (table name → definition)"
+          },
+          {
+            "identifier": "ctx",
+            "type": { "type": "object" },
+            "description": "Host context: { projectConfig, root, registry, io }"
+          }
+        ],
+        "returnType": { "$ref": "#/$defs/returnTypes/SectionData" },
+        "description": "Expose the table definitions under _project.data (rows stay in the database; reads go through TableQuery/TableEntry or /_jx/data)"
+      },
+      "mount": {
+        "role": "mount",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "mount",
+        "timing": ["server"],
+        "parameters": [
+          {
+            "identifier": "options",
+            "type": {
+              "type": "object",
+              "properties": {
+                "basePath": { "type": "string" },
+                "sections": { "type": "object" },
+                "connectors": { "type": "object" },
+                "autoSync": { "type": "boolean" }
+              }
+            },
+            "description": "Inlined mount options: project sections, provider constructors, sync mode"
+          },
+          {
+            "identifier": "ctx",
+            "type": { "type": "object" },
+            "description": "Shared JxServerContext (the auth mount populates ctx.auth)"
+          }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Fetch-style handler (request, env) → Response serving the /_jx/data wire contract; fail-closed without ctx.auth"
+      }
+    }
+  }
+}

package/src/Sqlite.class.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/connector/Sqlite.class.json",
+  "title": "Sqlite",
+  "description": "File-backed SQLite connection provider over bun:sqlite — the dev-server default and the `local: \"sqlite\"` stand-in target",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./sqlite.js",
+
+  "connector": {
+    "provider": "sqlite",
+    "kind": "sqlite",
+    "serve": "@jxsuite/connector/worker",
+    "module": "@jxsuite/connector/sqlite"
+  },
+
+  "$defs": {
+    "methods": {
+      "dialect": {
+        "role": "dialect",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "dialect",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          { "identifier": "connection", "type": { "type": "object" } },
+          { "identifier": "env", "type": { "type": "object" } }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Kysely bun:sqlite dialect at <JX_PROJECT_ROOT>/.jx/data/<name>.sqlite (or the connection's file path)"
+      },
+      "deploySchema": {
+        "role": "deploySchema",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "deploySchema",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          { "identifier": "tables", "type": { "type": "object" } },
+          { "identifier": "connection", "type": { "type": "object" } },
+          {
+            "identifier": "options",
+            "type": {
+              "type": "object",
+              "properties": { "env": { "type": "object" }, "dryRun": { "type": "boolean" } }
+            }
+          }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Additive schema sync: { statements, applied, warnings }"
+      },
+      "bindings": {
+        "role": "bindings",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "bindings",
+        "timing": ["compiler", "server"],
+        "parameters": [{ "identifier": "connection", "type": { "type": "object" } }],
+        "returnType": { "type": "object" },
+        "description": "Empty fragment — SQLite is not a Cloudflare service"
+      },
+      "testConnection": {
+        "role": "testConnection",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "testConnection",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          { "identifier": "connection", "type": { "type": "object" } },
+          { "identifier": "env", "type": { "type": "object" } }
+        ],
+        "returnType": { "type": "object" },
+        "description": "Probe the database file with `select 1`: { ok, error? }"
+      }
+    }
+  }
+}