@tailor-platform/sdk 2.1.0 → 2.3.0

package/docs/services/tailordb.md

@@ -8,22 +8,22 @@ TailorDB provides:
 
 - Type-safe schema definitions using TypeScript
 - Automatic GraphQL API generation (CRUD operations)
-- Relations between types with automatic index and foreign key constraints
+- Relations between tables with automatic index and foreign key constraints
 - Permission system for access control
 - Field-level hooks and validations
 
 For the official Tailor Platform documentation, see [TailorDB Guide](https://docs.tailor.tech/guides/tailordb/overview).
 
-## Type Definition
+## Table Definition
 
-Define TailorDB Types in files matching glob patterns specified in `tailor.config.ts`.
+Define TailorDB tables in files matching glob patterns specified in `tailor.config.ts`.
 
 **Definition Rules:**
 
-- **Multiple types per file**: You can define multiple TailorDB types in a single file
+- **Multiple tables per file**: You can define multiple TailorDB tables in a single file
 - **Export method**: Use named exports (`export const`)
 - **Export both value and type**: Always export both the runtime value and TypeScript type
-- **Uniqueness**: Type names must be unique across all TailorDB namespaces in the application
+- **Uniqueness**: Table names must be unique across all TailorDB namespaces in the application
 
 ```typescript
 import { db } from "@tailor-platform/sdk";
@@ -37,7 +37,7 @@ export const user = db.table("User", {
 });
 export type user = typeof user;
 
-// You can define multiple types in the same file
+// You can define multiple tables in the same file
 export const role = db.table("Role", {
   name: db.string().unique(),
 });
@@ -254,8 +254,8 @@ type User {
 }
 ```
 
-- `toward.as` - Customizes the field name for accessing the related type from this type
-- `backward` - Customizes the field name for accessing this type from the related type
+- `toward.as` - Customizes the field name for accessing the related table from this table
+- `backward` - Customizes the field name for accessing this table from the related table
 
 Relation names share the same GraphQL field namespace as fields, files, and other relations on
 the table. The SDK rejects duplicate or empty relation names. When `toward.as` is omitted, the
@@ -356,7 +356,7 @@ export const order = db
   });
 ```
 
-**Note:** `.hooks()` can only be called once on a type. Duplicate type-level calls fail at compile time and throw at runtime.
+**Note:** `.hooks()` can only be called once on a table. Duplicate type-level calls fail at compile time and throw at runtime.
 
 ### Validation
 
@@ -415,7 +415,7 @@ For datetime/date/time fields, pass `"now"` to use the operation timestamp:
 db.datetime().default("now");
 ```
 
-**Note:** `.validate()` can only be called once on a type. Duplicate type-level calls fail at compile time and throw at runtime.
+**Note:** `.validate()` can only be called once on a table. Duplicate type-level calls fail at compile time and throw at runtime.
 
 ### Vector Search
 
@@ -448,14 +448,14 @@ export const user = db.table("User", {
 
 `db.fields.timestamps()` adds non-null `createdAt` and `updatedAt` datetime fields. Both fields are populated when a record is created; provided values are preserved so seed data can use historical timestamps. `updatedAt` is also refreshed automatically when a record is updated.
 
-## Type Modifiers
+## Table Modifiers
 
-Type builder methods that set one type-level configuration can be called only once on the same type. Duplicate calls fail at compile time and throw at runtime. This applies to `.description()`, `.hooks()`, `.validate()`, `.features()`, `.indexes()`, `.files()`, `.permission()`, and `.gqlPermission()`.
+Table builder methods that set one type-level configuration can be called only once on the same table. Duplicate calls fail at compile time and throw at runtime. This applies to `.description()`, `.hooks()`, `.validate()`, `.features()`, `.indexes()`, `.files()`, `.permission()`, and `.gqlPermission()`.
 
 Conditional assignment is still supported when only one branch calls the method:
 
 ```typescript
-let user = db.type("User", {
+let user = db.table("User", {
   name: db.string(),
 });
 
@@ -502,7 +502,7 @@ db.table("User", {
 
 #### Event Publishing
 
-Enable event publishing for a type to trigger executors on record changes:
+Enable event publishing for a table to trigger executors on record changes:
 
 ```typescript
 db.table("User", {
@@ -515,15 +515,15 @@ db.table("User", {
 **Behavior:**
 
 - 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 type 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 type, `deploy` fails
+- 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
 
 **Use cases:**
 
 1. **Auto-detection (recommended)**: Don't set `publishEvents` - `deploy` enables it while an executor taking part in the same run needs it
 
    ```typescript
-   // publishEvents is automatically enabled because an executor uses this type
+   // publishEvents is automatically enabled because an executor uses this table
    export const order = db.table("Order", {
      status: db.string(),
    });
@@ -545,7 +545,7 @@ db.table("User", {
    });
    ```
 
-3. **Explicit disable**: Disable event publishing for a type that doesn't need it (error if an executor taking part in the same run uses it)
+3. **Explicit disable**: Disable event publishing for a table that doesn't need it (error if an executor taking part in the same run uses it)
 
    ```typescript
    db.table("TempData", {
@@ -555,14 +555,14 @@ db.table("User", {
    });
    ```
 
-**Sharing a type across configs:** an executor in another config auto-enables publishing the same way, as long as both configs take part in the same `deploy` (`--config a,b`). `deploy` records that dependency, so deploying the owning config alone later asks for confirmation instead of silently turning publishing off — it fails outright in a non-interactive environment. Set `publishEvents: true` on the type to keep it on regardless of which configs take part.
+**Sharing a table across configs:** an executor in another config auto-enables publishing the same way, as long as both configs take part in the same `deploy` (`--config a,b`). `deploy` records that dependency, so deploying the owning config alone later asks for confirmation instead of silently turning publishing off — it fails outright in a non-interactive environment. Set `publishEvents: true` on the table to keep it on regardless of which configs take part.
 
 #### GraphQL Operations
 
-Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a type. All operations are enabled by default.
+Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a table. All operations are enabled by default.
 
 ```typescript
-db.type("Order", {
+db.table("Order", {
   status: db.string(),
 }).features({
   gqlOperations: {
@@ -571,10 +571,10 @@ db.type("Order", {
 });
 ```
 
-Use the `"query"` alias to disable all mutations at once (read-only type: `create`/`update`/`delete` false, `read` true):
+Use the `"query"` alias to disable all mutations at once (read-only table: `create`/`update`/`delete` false, `read` true):
 
 ```typescript
-db.type("AuditLog", {
+db.table("AuditLog", {
   action: db.string(),
 }).features({
   gqlOperations: "query",
@@ -583,7 +583,7 @@ db.type("AuditLog", {
 
 **Namespace-level default**
 
-Set a default for every type in a TailorDB namespace in `tailor.config.ts`. A type's own `.features({ gqlOperations })` always takes precedence over this default.
+Set a default for every table in a TailorDB namespace in `tailor.config.ts`. A table's own `.features({ gqlOperations })` always takes precedence over this default.
 
 ```typescript
 // tailor.config.ts
@@ -591,13 +591,13 @@ export default defineConfig({
   db: {
     tailordb: {
       files: ["./tailordb/*.ts"],
-      gqlOperations: { delete: false }, // Default for every type in this namespace
+      gqlOperations: { delete: false }, // Default for every table in this namespace
     },
   },
 });
 ```
 
-This default is re-evaluated on every `tailor deploy`, so changing it also updates types that already exist on the platform, not only newly created ones.
+This default is re-evaluated on every `tailor deploy`, so changing it also updates tables that already exist on the platform, not only newly created ones.
 
 ### Field Extraction (`pickFields` / `omitFields`)
 
@@ -679,7 +679,7 @@ Configure Permission and GQLPermission. For details, see the [TailorDB Permissio
 
 **Important**: Following the secure-by-default principle, all operations are denied if permissions are not configured. You must explicitly grant permissions for each operation (create, read, update, delete).
 
-`generate`/`deploy` reject a type that has no `.permission()`, or no `.gqlPermission()` while GraphQL operations are enabled for it (see [GraphQL Operations](#graphql-operations) above). Disable GraphQL exposure entirely with `.features({ gqlOperations: { create: false, update: false, delete: false, read: false } })` if a type only needs record-level permission.
+`generate`/`deploy` reject a table that has no `.permission()`, or no `.gqlPermission()` while GraphQL operations are enabled for it (see [GraphQL Operations](#graphql-operations) above). Disable GraphQL exposure entirely with `.features({ gqlOperations: { create: false, update: false, delete: false, read: false } })` if a table only needs record-level permission.
 
 ```typescript
 db.table("User", {
@@ -723,6 +723,6 @@ db.table("User", {
 
 ## Migrations
 
-When you change a TailorDB type definition, the SDK can generate a migration that captures the diff and, for breaking changes, runs a data transformation script during `tailor deploy`. See the [TailorDB Migrations guide](./tailordb-migration.md) for the full workflow, configuration, supported change types, team coordination, and troubleshooting.
+When you change a TailorDB table definition, the SDK can generate a migration that captures the diff and, for breaking changes, runs a data transformation script during `tailor deploy`. See the [TailorDB Migrations guide](./tailordb-migration.md) for the full workflow, configuration, supported change types, team coordination, and troubleshooting.
 
 For the CLI command reference, see [`tailordb migration`](../cli/tailordb.md#tailordb-migration).

package/docs/services/workflow.md

@@ -248,6 +248,8 @@ export const approval = createWaitPoint<
 >("approval");
 ```
 
+Keys must match `[a-z0-9-]`, be 3 to 63 characters long, and start and end with `[a-z0-9]`.
+
 For multiple wait points, use `createWaitPoints` with a builder callback. Property names become wait point keys, and JSDoc on each property is preserved in IDE autocompletion:
 
 ```typescript
@@ -255,9 +257,19 @@ import { createWaitPoints } from "@tailor-platform/sdk";
 
 export const waitPoints = createWaitPoints((define) => ({
   /** Manager approval step */
-  managerApproval: define<{ amount: number }, { approved: boolean }>(),
+  "manager-approval": define<{ amount: number }, { approved: boolean }>(),
   /** Finance review step */
-  financeReview: define<{ invoiceId: string }, { validated: boolean }>(),
+  "finance-review": define<{ invoiceId: string }, { validated: boolean }>(),
+}));
+
+await waitPoints["manager-approval"].wait({ amount: 50000 });
+```
+
+Pass the key to `define` when the property name you want to read at the call site is not a valid key:
+
+```typescript
+export const waitPoints = createWaitPoints((define) => ({
+  managerApproval: define.for("manager-approval")<{ amount: number }, { approved: boolean }>(),
 }));
 
 await waitPoints.managerApproval.wait({ amount: 50000 });
@@ -335,6 +347,44 @@ export default createResolver({
 
 Wait points can be imported and used in any file (workflow jobs, resolvers, executors). For local testing, see [Jobs that wait on approval](../testing.md#jobs-that-wait-on-approval) in the testing guide.
 
+### Keys With Runtime Values
+
+A wait point key identifies one suspension inside one execution. When a job suspends more than once for the same reason — one approval per order line, one per approver — every suspension needs its own key, otherwise the second `wait()` fails because a suspension with that key is already pending.
+
+Write `$paramName` as a whole `-`-delimited segment of the key to leave a slot for a runtime value — `line-approval-$lineId` works, `line-approval$lineId` does not. Declare such a key through `createWaitPoints`, passing it to `define` **before** the `Payload` and `Result` type arguments — the param names then become the argument of `.with()`, which builds the concrete key:
+
+```typescript
+export const { lineApproval } = createWaitPoints((define) => ({
+  lineApproval: define.for("line-approval-$lineId")<{ message: string }, { approved: boolean }>(),
+}));
+
+// Suspends on "line-approval-<lineId>", so parallel lines never collide
+const result = await lineApproval.with({ lineId: line.id }).wait({ message: "Please approve" });
+```
+
+The key has to come before the type arguments because TypeScript stops inferring it as a literal type once `Payload` and `Result` are given explicitly, and the param names can only be read off a literal. `createWaitPoint` takes its type arguments first, so it cannot type `$params` at all, and `deploy` rejects such a key — one wait point per key is what it is for, and a key with `$params` stands for a family of them.
+
+`deploy` checks every declared key against the grammar above, so a key the platform would reject is reported before anything is deployed.
+
+A parameterized wait point exposes only `.with()` — there is no way to wait on the unsubstituted key.
+
+Resolve it from the same param values:
+
+```typescript
+await lineApproval.with({ lineId: input.lineId }).resolve(input.executionId, (payload) => {
+  console.log("Resolving:", payload.message);
+  return { approved: input.approved };
+});
+```
+
+Rules to keep in mind:
+
+- Param values must match `[a-z0-9-]`, cannot be empty, and cannot start or end with `-`. Record IDs work as-is; uppercase or underscored values do not.
+- The composed key still has to fit 63 characters. A UUID takes 36, so a key holding one leaves 26 characters for everything else.
+- The key needs at least one literal segment alongside its `$params`, so `"$lineId"` alone is rejected: a key made only of caller data carries no identity of its own.
+- Param values are part of the key, so they must be derived from the job's input. A value from `Date.now()` or `Math.random()` changes when the platform replays the job and the execution fails.
+- Keys are compared exactly, and the SDK does not check whether two declared keys can produce the same string. `"a-$x"` with `x = "b-c"` and `"a-b-$y"` with `y = "c"` both produce `a-b-c`. Keep the literal part of each key distinct, and prefer putting `$params` last.
+
 ## Retry Policy
 
 You can configure automatic retry behavior with exponential backoff by setting `retryPolicy` on a workflow. All fields are required when `retryPolicy` is set:

package/docs/testing.md

@@ -180,6 +180,18 @@ await approvalWaitPoint.wait({ message: "Please approve" });
 expect(approvalMock.wait).toHaveBeenCalledWith({ message: "Please approve" });
 ```
 
+For a wait point whose key contains `$params`, use `waitPointWith(definition, params)` to control one param binding at a time. Calls made with any other binding fall through to the platform mock:
+
+```typescript
+using wf = mockWorkflow();
+const lineOne = wf.waitPointWith(lineApproval, { lineId: "line-1" });
+
+lineOne.wait.mockResolvedValue({ approved: true });
+await lineApproval.with({ lineId: "line-1" }).wait({ message: "Please approve" });
+
+expect(lineOne.wait).toHaveBeenCalledWith({ message: "Please approve" });
+```
+
 Use `wf.setEnv(...)` when locally-run workflow job bodies need configuration values. Per-run `runWorkflowLocally(..., { env })` options take precedence over the mock's env.
 
 ### SecretManager Mock
@@ -582,6 +594,8 @@ describe("upsertUsers resolver", () => {
 
 Reach for [`mockTailordb`](#mocking-the-tailordb-client) instead when you want to drive the raw query sequence at the `tailordb.Client` level rather than at the Kysely layer.
 
+TailorDB migration scripts (`migrate.ts`) are unit-tested the same way: the generated `db.ts` exports the `Database` interface to type the mock, and `tailor tailordb migration script <N> --with-test` scaffolds a ready-to-fill test. To execute a migration script against real rows in an in-memory Postgres, use `createKyselyPGlite` with `@electric-sql/pglite`. See [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally).
+
 #### Resolvers that resume a workflow
 
 Resolvers that call `waitPoint.resolve(...)` delegate to `tailor.workflow.resolve` at runtime. With the `tailor-runtime` environment active, use `mockWorkflow().waitPoint(definition)` to invoke the callback with the payload that originally suspended the job:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -9,9 +9,10 @@
     "directory": "packages/sdk"
   },
   "bin": {
-    "tailor": "./dist/cli/index.mjs"
+    "tailor": "./bin/tailor.mjs"
   },
   "files": [
+    "bin",
     "CHANGELOG.md",
     "dist",
     "docs",
@@ -168,18 +169,17 @@
     "@secretlint/secretlint-rule-preset-recommend": "13.0.4",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@toiroakr/lines-db": "0.11.0",
+    "@toiroakr/lines-db": "0.12.0",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.1.11",
-    "chalk": "5.6.2",
     "confbox": "0.2.4",
     "date-fns": "4.4.0",
     "es-toolkit": "1.50.0",
     "find-up-simple": "1.0.1",
     "get-east-asian-width": "1.6.0",
     "get-tsconfig": "4.14.1",
-    "globals": "17.8.0",
+    "globals": "17.9.0",
     "graphql": "17.0.2",
     "inflection": "3.0.2",
     "kysely": "0.29.4",
@@ -204,7 +204,7 @@
     "@opentelemetry/sdk-trace-base": "2.10.0",
     "@types/mime-types": "3.0.1",
     "@types/node": "24.13.3",
-    "@types/semver": "7.7.1",
+    "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "4.1.10",
     "eslint-plugin-zod": "4.9.0",
@@ -216,13 +216,18 @@
     "typescript": "6.0.3",
     "vitest": "4.1.10",
     "zinfer": "0.2.7",
+    "@tailor-platform/shared": "^0.0.0",
     "@tailor-platform/tailor-proto": "^0.0.1"
   },
   "peerDependencies": {
+    "@electric-sql/pglite": ">=0.2.0",
     "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
     "vitest": ">=4"
   },
   "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     },
@@ -241,7 +246,7 @@
     "test:coverage": "vitest --coverage",
     "docs:check": "vitest run --project=unit* src/cli/docs.test.ts",
     "docs:update": "POLITTY_DOCS_UPDATE=true vitest run --project=unit* src/cli/docs.test.ts",
-    "build": "tsdown && politty generate-shim --entry ./main.mjs --program tailor && politty generate-worker --bin dist/cli/main.mjs --program tailor --shell zsh --verify",
+    "build": "tsdown && politty generate-shim --entry ../dist/cli/main.mjs --program tailor && politty generate-worker --bin dist/cli/main.mjs --program tailor --shell zsh --verify",
     "lint": "oxlint --type-aware .",
     "check:public-api-jsdoc": "node --experimental-strip-types scripts/check-public-api-jsdoc.ts",
     "check:zod-isolation": "node --experimental-strip-types scripts/check-zod-isolation.ts",

package/dist/application-Af1zIqSI.mjs

@@ -1,3 +0,0 @@
-import { n as generatePluginFilesIfNeeded, r as loadApplication, t as defineApplication } from "./application-D77KJFKD.mjs";
-
-export { defineApplication, generatePluginFilesIfNeeded };