@tailor-platform/sdk 2.7.0 → 2.10.0

package/dist/vitest/pglite-kysely.d.mts

@@ -1,4 +1,4 @@
-import { Kysely } from "kysely";
+import { ColumnType, Kysely } from "kysely";
 //#region src/vitest/pglite-kysely.d.ts
 /**
  * The subset of a `@electric-sql/pglite` `PGlite` instance used by
@@ -14,11 +14,33 @@ interface PGliteClient {
   /** Release the underlying database. Called by `db.destroy()`. */
   close(): Promise<void>;
 }
+type WritableAs<S, W> = [S] extends [W] ? W : [W] extends [S] ? S : W | Exclude<S, W>;
+type UnmigratedColumn<C> = C extends ColumnType<infer S, infer I, infer U> ? ColumnType<S, WritableAs<S, I>, WritableAs<S, U>> : C;
+/**
+ * `DB` as its rows stand before the migration script has run: every column
+ * accepts on insert and update whatever it can still hold on read.
+ *
+ * The generated `db.ts` types a column the migration makes required as
+ * `ColumnType<T | null, T, T>`, and an enum whose values it narrows as
+ * `ColumnType<Before, After, After>`, so `migrate.ts` cannot write a null
+ * or a removed value into them — and neither can a test that has to stage
+ * the rows the script converts. Type the PGlite instance with
+ * `Unmigrated<Database>` to stage them; `main` still receives a
+ * `Transaction<Database>`.
+ * @example
+ * ```typescript
+ * const db = createKyselyPGlite<Unmigrated<Database>>(new PGlite());
+ * await db.insertInto("User").values({ name: "a", email: null }).execute();
+ * await db.transaction().execute((trx) => main(trx));
+ * ```
+ */
+type Unmigrated<DB> = { [T in keyof DB]: { [C in keyof DB[T]]: UnmigratedColumn<DB[T][C]>; }; };
 /**
  * Create a Kysely instance backed by a PGlite in-memory Postgres, for
  * executing a migration script's queries against real data in tests.
- * Pass the migration's schema as the type argument, e.g.
- * `createKyselyPGlite<Database>(new PGlite())`.
+ * Pass the migration's schema as the type argument — wrapped in
+ * {@link Unmigrated} so the test can stage the rows the script has not yet
+ * backfilled: `createKyselyPGlite<Unmigrated<Database>>(new PGlite())`.
  *
  * PGlite runs full PostgreSQL while TailorDB supports a subset of it, so a
  * statement passing here can still be rejected by the platform; keep a
@@ -27,17 +49,17 @@ interface PGliteClient {
  * @returns A Kysely instance that executes queries on the client and closes it on `destroy()`
  * @example
  * ```typescript
- * // migrations/0005/migrate.test.ts
+ * // migrations/0005/migrate.pglite.test.ts
  * import { PGlite } from "@electric-sql/pglite";
- * import { createKyselyPGlite } from "@tailor-platform/sdk/vitest";
+ * import { createKyselyPGlite, type Unmigrated } from "@tailor-platform/sdk/vitest";
  * import type { Database } from "./db";
  * import { main } from "./migrate";
  *
- * const db = createKyselyPGlite<Database>(new PGlite());
+ * const db = createKyselyPGlite<Unmigrated<Database>>(new PGlite());
  * // create tables matching db.ts, insert rows, then:
  * await db.transaction().execute((trx) => main(trx));
  * ```
  */
 declare function createKyselyPGlite<DB = Record<string, never>>(client: PGliteClient): Kysely<DB>;
 //#endregion
-export { PGliteClient, createKyselyPGlite };
+export { PGliteClient, Unmigrated, createKyselyPGlite };

package/docs/plugin/custom.md

@@ -575,6 +575,90 @@ declare module "@tailor-platform/sdk" {
 }
 ```
 
+### Injecting fields into the attached table's type (declaration merging)
+
+A plugin that adds fields to a table via `onTableLoaded`'s `extends.fields` (see
+[onTableLoaded](#ontableloaded) above) can also make those fields show up on the table's own
+static type right away, computed from the literal per-table config passed to `.plugin()`. Provide
+a declaration merge for the `PluginFieldExtensions` interface, keyed by the same `id` used in
+`PluginConfigs`:
+
+```typescript
+// your-plugin/types.d.ts (shipped with your plugin package)
+import type { TailorDBField } from "@tailor-platform/sdk";
+
+declare module "@tailor-platform/sdk" {
+  interface PluginConfigs<Fields extends string> {
+    "@example/lifecycle": {
+      transitions: Record<string, { from: readonly string[]; to: string }>;
+    };
+  }
+
+  interface PluginFieldExtensions<Fields extends string, Config> {
+    "@example/lifecycle": Config extends {
+      transitions: infer T extends Record<string, { from: readonly string[]; to: string }>;
+    }
+      ? {
+          status: TailorDBField<
+            { type: "enum"; array: false },
+            T[keyof T]["from"][number] | T[keyof T]["to"]
+          >;
+        }
+      : never;
+  }
+}
+```
+
+With this in place, the table returned by `.plugin()` already has the derived field. The status enum
+includes every state that appears anywhere in `transitions` — both a `from` state that a transition
+never produces (like the initial `"PENDING"` below) and every `to` state:
+
+```typescript
+import { db } from "@tailor-platform/sdk";
+
+const approvalRequest = db.table("ApprovalRequest", { title: db.string() }).plugin({
+  "@example/lifecycle": {
+    transitions: {
+      approve: { from: ["PENDING"], to: "APPROVED" },
+      reject: { from: ["PENDING"], to: "REJECTED" },
+    },
+  },
+});
+// approvalRequest's type now includes status: "PENDING" | "APPROVED" | "REJECTED"
+```
+
+The type registered in `PluginFieldExtensions` must describe only the fields being added — it is
+merged into the table's existing fields, not a replacement for them. A field name that collides
+with an existing field, with a file key declared via `.files()`, or with a field injected by
+another plugin attached in the same `.plugin()` call, is a type error at the call site — regardless
+of whether `.files()` or `.plugin()` was called first. `tailor generate` also rejects the same
+collision at runtime, as a backstop for any case a table's static type doesn't otherwise catch.
+
+This only affects the table's static type. The corresponding field exists on the table's
+generated schema, and on the table object's own `fields`, only after `tailor generate` actually
+applies `extends.fields`. Before that, reading an injected field directly off the table
+(`table.fields.status`) returns `undefined`, and `pickFields(["status"])` throws — call these only
+with the table's originally declared fields, not ones a plugin injects.
+
+To keep the declared type and the runtime implementation in sync, give `Plugin`'s optional third
+type parameter the same shape and use it inside `onTableLoaded`:
+
+```typescript
+import { db, type Plugin, type TailorDBField } from "@tailor-platform/sdk";
+
+const lifecyclePlugin: Plugin<
+  LifecycleTableConfig,
+  LifecyclePluginConfig,
+  { status: TailorDBField<{ type: "enum"; array: false }, "PENDING" | "APPROVED" | "REJECTED"> }
+> = {
+  id: "@example/lifecycle",
+  description: "Derives a status field from a transitions map",
+  onTableLoaded(context) {
+    return { extends: { fields: { status: db.enum(["PENDING", "APPROVED", "REJECTED"]) } } };
+  },
+};
+```
+
 ### Resolving plugin-level config from a `Plugin[]` array (declaration merging)
 
 `PluginConfig` is already available inside your own plugin's hooks via `context.pluginConfig`.

package/docs/services/executor.md

@@ -44,6 +44,23 @@ export default createExecutor({
 });
 ```
 
+### Disabling an Executor
+
+Set `disabled: true` to deploy an executor without letting it run. The definition stays deployed, and the platform skips dispatching jobs to it.
+
+```typescript
+export default createExecutor({
+  name: "user-welcome-paused",
+  disabled: true,
+  trigger: recordCreatedTrigger({ type: user }),
+  operation: { kind: "function", body: async () => {} },
+});
+```
+
+A disabled executor does not count as a subscriber when `deploy` resolves `publishEvents` on the resource its trigger names. Publishing is not enabled on that resource's behalf, and an explicit `publishEvents: false` on it is not rejected. If the resource was publishing only for this executor, the next `deploy` turns publishing back off — so disabling the last subscriber of a shared table changes that table for every config that reads its events.
+
+The trigger is still deployed, so it must still name a resource the deploy declares; a disabled executor whose trigger names nothing fails the deploy exactly as an enabled one does.
+
 ## Trigger Types
 
 ### Record Triggers

package/docs/services/idp.md

@@ -330,7 +330,7 @@ defineIdp("my-idp", {
 });
 ```
 
-**Auto-configuration:** When `publishEvents` is omitted, `deploy` sets it from the executors taking part in the same run: `true` while one of their `idpUser` triggers targets this IdP, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`. Targeting is per-IdP: an executor specifies which IdP it subscribes to via the trigger's `idp` option (required in multi-IdP projects). Set the value explicitly to override:
+**Auto-configuration:** When `publishEvents` is omitted, `deploy` sets it from the executors taking part in the same run: `true` while one of their `idpUser` triggers targets this IdP, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`, as does disabling the last executor that carries one. Targeting is per-IdP: an executor specifies which IdP it subscribes to via the trigger's `idp` option (required in multi-IdP projects). Set the value explicitly to override:
 
 - `publishEvents: true`: always publish events.
 - `publishEvents: false`: never publish events. `deploy` rejects this with an error if an `idpUser` trigger taking part in the same run targets this IdP — either remove `publishEvents: false` or remove the matching trigger.

package/docs/services/resolver.md

@@ -310,7 +310,7 @@ createResolver({
 
 **Use cases:**
 
-1. **Auto-detection (recommended)**: Don't set `publishEvents` - `deploy` enables it while an executor taking part in the same run needs it
+1. **Auto-detection (recommended)**: Don't set `publishEvents` - `deploy` enables it while an executor taking part in the same run needs it. An executor declared with `disabled: true` never runs, so it does not count
 
    ```typescript
    // publishEvents is automatically enabled because an executor uses this resolver

package/docs/services/tailordb-migration.md

@@ -815,25 +815,27 @@ A statement-level test verifies what the script issues, not what it does to data
 npm install -D @electric-sql/pglite
 ```
 
-Create the tables the script touches (matching the shape in the generated `db.ts`), stage rows, then run the script in a transaction:
+Create the tables the script touches (matching the shape in the generated `db.ts`), stage rows, then run the script in a transaction. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.
 
 ```typescript
 // migrations/0005/migrate.pglite.test.ts
 import { PGlite } from "@electric-sql/pglite";
 import { sql } from "@tailor-platform/sdk/kysely";
-import { createKyselyPGlite } from "@tailor-platform/sdk/vitest";
+import { createKyselyPGlite, type Unmigrated } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import type { Database } from "./db";
 import { main } from "./migrate";
 
-const db = createKyselyPGlite<Database>(new PGlite());
+const db = createKyselyPGlite<Unmigrated<Database>>(new PGlite());
 
 beforeAll(async () => {
   await sql`
     CREATE TABLE "User" (
       "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
       "name" text NOT NULL,
-      "email" text
+      "email" text,
+      "createdAt" timestamptz NOT NULL,
+      "updatedAt" timestamptz NOT NULL
     )
   `.execute(db);
 });
@@ -844,10 +846,14 @@ afterAll(async () => {
 
 describe("0005 add required email", () => {
   test("backfills null emails and keeps existing ones", async () => {
-    await sql`
-      INSERT INTO "User" ("name", "email")
-      VALUES ('a', NULL), ('b', 'b@example.com')
-    `.execute(db);
+    const now = new Date();
+    await db
+      .insertInto("User")
+      .values([
+        { name: "a", email: null, createdAt: now, updatedAt: now },
+        { name: "b", email: "b@example.com", createdAt: now, updatedAt: now },
+      ])
+      .execute();
 
     await db.transaction().execute((trx) => main(trx));
 

package/docs/services/tailordb.md

@@ -519,6 +519,8 @@ db.table("User", {
 - When `publishEvents: true`, record creation/update/deletion events are published
 - When not specified, `deploy` sets it from the executors taking part in the same run: `true` while one of them uses this table with `recordCreatedTrigger`, `recordUpdatedTrigger`, or `recordDeletedTrigger`, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`
 - When explicitly set to `false` while an executor taking part in the same run uses this table, `deploy` fails
+- An executor declared with `disabled: true` never runs, so it does not count as using the table
+- While a `deploy` applies pending migrations, every table in the migrating namespace is read-only: create, update, delete, and bulk-upsert operations are disabled while the existing read setting is preserved. Record event publishing is also switched off so a migration script's writes do not reach executors from the previous deploy. After success, the configured settings take effect. If a later migration fails, settings from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior settings and leaves its newly created tables restricted until a successful retry. Restoration is skipped if the checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified. A table left behind by a failed post-checkpoint deletion also remains read-only for manual recovery
 
 **Use cases:**
 
@@ -563,6 +565,8 @@ db.table("User", {
 
 Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a table. All operations are enabled by default.
 
+While a `deploy` applies pending migrations, every GraphQL operation — `create`, `update`, `delete`, `read`, and bulk upsert — is switched off across the migrating namespace, so nothing reads or writes an intermediate schema. After success, the configured operations take effect. If a later migration fails, operations from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior operations and leaves its newly created tables restricted until a successful retry. Restoration is skipped if the checkpoint number or migration history changed concurrently.
+
 ```typescript
 db.table("Order", {
   status: db.string(),

package/docs/services/workflow.md

@@ -208,7 +208,7 @@ export default createWorkflow({
 
 Workflows can publish execution lifecycle events for executors. When an executor subscribes to a workflow's events, `deploy` enables publishing automatically. A `workflowExecution*` trigger enables it on the workflow, and a `workflowJobExecution*` trigger enables it on every job that workflow runs. See [Workflow Execution Triggers](./executor.md#workflow-execution-triggers).
 
-Publishing follows the subscription in both directions: removing the last subscribing trigger turns it back off on the next `deploy`.
+Publishing follows the subscription in both directions: removing the last subscribing trigger turns it back off on the next `deploy`, as does disabling the last executor that carries one.
 
 Set `publishEvents` explicitly to pin the value instead. Use `true` to publish workflow-level events with no subscribing executor:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.7.0",
+  "version": "2.10.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -155,8 +155,8 @@
     "@bufbuild/protovalidate": "1.2.0",
     "@connectrpc/connect": "2.1.2",
     "@connectrpc/connect-node": "2.1.2",
-    "@inquirer/core": "12.0.0",
-    "@inquirer/prompts": "8.6.0",
+    "@inquirer/core": "12.0.1",
+    "@inquirer/prompts": "8.7.0",
     "@jridgewell/trace-mapping": "0.3.31",
     "@napi-rs/keyring": "1.3.0",
     "@opentelemetry/api": "1.9.1",
@@ -164,9 +164,9 @@
     "@opentelemetry/resources": "2.10.0",
     "@opentelemetry/sdk-trace-node": "2.10.0",
     "@opentelemetry/semantic-conventions": "1.43.0",
-    "@oxc-project/types": "0.146.0",
-    "@secretlint/core": "13.0.4",
-    "@secretlint/secretlint-rule-preset-recommend": "13.0.4",
+    "@oxc-project/types": "0.147.0",
+    "@secretlint/core": "13.0.5",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@toiroakr/lines-db": "0.12.2",
@@ -185,7 +185,7 @@
     "kysely": "0.29.5",
     "mime-types": "3.0.2",
     "open": "11.0.1",
-    "oxc-parser": "0.146.0",
+    "oxc-parser": "0.147.0",
     "p-limit": "7.3.1",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
@@ -202,22 +202,22 @@
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "2.10.0",
+    "@tailor-platform/shared": "^0.0.0",
+    "@tailor-platform/tailor-proto": "^0.0.1",
     "@types/mime-types": "3.0.1",
     "@types/node": "24.13.3",
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "4.1.11",
-    "eslint-plugin-zod": "4.9.1",
-    "oxfmt": "0.64.0",
-    "oxlint": "1.79.0",
+    "eslint-plugin-zod": "4.10.0",
+    "oxfmt": "0.65.0",
+    "oxlint": "1.80.0",
     "oxlint-tsgolint": "7.0.2001",
     "sonda": "0.14.0",
     "tsdown": "0.22.14",
     "typescript": "6.0.3",
     "vitest": "4.1.11",
-    "zinfer": "0.2.8",
-    "@tailor-platform/shared": "^0.0.0",
-    "@tailor-platform/tailor-proto": "^0.0.1"
+    "zinfer": "0.2.8"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.2.0",