@tailor-platform/sdk 2.14.2 → 2.16.0

package/docs/plugin/custom.md

@@ -324,6 +324,37 @@ const AuditLog = await getGeneratedTable(configPath, "@example/audit-log", null,
 5. Caches the result to avoid redundant processing
 6. Returns the generated table matching the specified kind
 
+## getExtendedTable Helper
+
+A table that plugins are attached to gains the fields those plugins return in `extends.fields`, but only in the table `tailor generate` registers — the object exported from the table's source file stays as written. `getExtendedTable()` returns the table with every plugin-added field applied, so tooling that reads the table at runtime sees the same fields `tailor generate` does.
+
+```typescript
+import { join } from "node:path";
+import { getExtendedTable } from "@tailor-platform/sdk/plugin";
+import { customer } from "./tailordb/customer";
+
+const configPath = join(import.meta.dirname, "./tailor.config.ts");
+
+const extendedCustomer = await getExtendedTable(configPath, customer);
+extendedCustomer.fields.deletedAt; // added by a plugin attached with .plugin()
+```
+
+**Parameters:**
+
+- `configPath`: Path to `tailor.config.ts` (absolute or relative to cwd)
+- `sourceTable`: The TailorDB table as exported from its source file
+
+**How it works:**
+
+1. Returns `sourceTable` itself when no plugin is attached to it
+2. Loads and caches the config from the given path
+3. Auto-resolves the namespace from config
+4. Calls each attached plugin's `onTableLoaded()` in the order of the `.plugin()` calls, each seeing the fields the plugins before it added
+5. Caches the result per config path and table
+6. Returns a new table with the added fields; `sourceTable` is not changed
+
+The seed schema files `tailor generate` writes for tables with plugins attached use this helper, so `tailor seed validate` checks plugin-added fields like the table's own.
+
 ## Examples
 
 ### Definition-time Plugin (Soft Delete)
@@ -646,10 +677,11 @@ of whether `.files()` or `.plugin()` was called first. `tailor generate` also re
 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.
+generated schema, and on the table `tailor generate` registers, only once `extends.fields` is
+applied; the table object exported from the source file never gains it. Reading an injected field
+directly off that object (`table.fields.status`) returns `undefined`, and `pickFields(["status"])`
+throws — call these only with the table's originally declared fields, or load the table with
+[`getExtendedTable()`](#getextendedtable-helper) first.
 
 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`:

package/docs/runtime.md

@@ -43,6 +43,45 @@ const { url } = await aigateway.get("my-aigateway");
 logger.info("order processed", { orderId: "o-1", total: 99.5 });
 ```
 
+## Uploading files
+
+Pass bytes directly to `file.upload`. For strings, specify how to interpret the input:
+
+```ts
+import { file } from "@tailor-platform/sdk/runtime";
+
+await file.upload("my-namespace", "Document", "attachment", recordId, text, {
+  encoding: "utf8",
+  contentType: "text/plain",
+});
+
+await file.upload("my-namespace", "Document", "attachment", recordId, imageBase64, {
+  encoding: "base64",
+  contentType: "image/png",
+});
+```
+
+`encoding` controls the input string's interpretation; `contentType` describes the stored file.
+Setting `contentType: "image/png"` does not decode Base64. Byte arrays and buffers are uploaded
+unchanged, even when `encoding` is supplied. Omitting `contentType` with `encoding: "utf8"`
+stores the file as `text/plain; charset=utf-8`; omitting it with `"base64"` leaves the content
+type unset, unless the Base64 string is a `data:<contentType>;base64,<data>` URL, in which case
+`<contentType>` is used. An explicit `contentType` option always takes precedence over one
+found in a data URL.
+
+Base64 input may omit padding and contain ASCII whitespace. Invalid characters and invalid
+padding are rejected with `TypeError` before upload. Decoding Base64 does not validate the
+resulting file's format.
+
+Uploading a string without `encoding` still stores it as text, but that overload is deprecated
+and will be removed in v3. Add `encoding: "utf8"` to preserve existing behavior, or choose
+`"base64"` when decoding is intended. Calls with byte arrays or buffers are not deprecated.
+The generated `uploadFile` helper supports the same options; run `tailor generate` to update it.
+
+The encoding option is available on the imported SDK `file.upload` and generated helpers.
+For code using the global `tailordb.file.upload`, switch to the imported `file.upload` before
+using this option.
+
 ## Subpath imports
 
 Each namespace can also be imported individually so you only pull what you need:

package/docs/services/resolver.md

@@ -139,7 +139,9 @@ createResolver({
 
 GraphQL still accepts and returns `YYYY-MM-DD` strings. The SDK converts input to a `Date` at midnight UTC and formats output using its UTC year, month, and day. Use UTC getters and setters for date arithmetic; local getters and setters depend on the runtime's timezone. Any time component in the returned `Date` is discarded according to UTC, so `new Date("2026-09-07T00:00:00+09:00")` returns `"2026-09-06"`.
 
-This option also works in nested objects and with `array: true` or `optional: true`. Input must be a valid calendar date, and output must be a valid `Date` with a UTC year between 0000 and 9999. Both deployed resolvers and `tailor function run` perform these conversions.
+This option also works in nested objects and with `array: true` or `optional: true`. Input must be a valid calendar date, and output must be a valid `Date` with a 4-digit UTC year (0000-9999). Both deployed resolvers and `tailor function run` perform these conversions.
+
+An executor subscribing to the resolver with `resolverExecutedTrigger` receives the event as JSON, so `result` holds the `YYYY-MM-DD` string rather than a `Date`.
 
 ### Custom Type Name (`typeName`)
 

package/docs/services/tailordb-migration.md

@@ -164,15 +164,33 @@ During deploy, the pre-migration phase keeps the old field and adds the new fiel
 
 If you decline the prompt (or confirm the removal with `--drop`), the change stays a plain removal + addition with the usual data-loss warning.
 
-Renaming a member inside a **nested field** is not detected as a rename: `User.address.zip` → `zipCode` becomes a single `field_modified` on `address`, so no `field_renamed` change is recorded and no copy script is generated. The removed member is reported as a data-loss warning instead, which `migration validate --strict` picks up like any other warning; when a compatible member was added at the same level, the warning names it as a possible rename target:
+#### Renaming a member inside a nested field
+
+Members inside a **nested field** (`db.object(...)`) are detected the same way: when `migration generate` finds a member removed from a nested field and a compatible member added under the same parent, it asks whether the member was renamed. Two members qualify only when copying the value preserves it exactly, because nested member constraints other than the new member's requiredness and unique constraint are not relaxed: the type, array-ness, requiredness, foreign key target, decimal scale, hooks, and validations must match (index, unique, and vector may differ, as for a top-level rename), enum values may be added but not removed, an object-typed member must keep the same members recursively, and serial members never qualify.
+
+```
+? User.address.zip was removed and zipCode was added with a compatible type. Was it renamed to zipCode? (Y/n)
+```
+
+In non-interactive environments the command fails while a candidate is left unresolved, exactly like field renames. Resolve it with the nested member forms of the same flags (a value with two or more dots before the `:` targets a member; deeper members use their dotted path, and the new name is a single segment under the same parent):
+
+```bash
+tailor tailordb migration generate --rename "User.address.zip:zipCode"
+tailor tailordb migration generate --rename "User.address.geo.lat:latitude"
+tailor tailordb migration generate --drop "User.address.zip"
+```
+
+A confirmed rename is recorded on the nested field's `field_modified` change as `memberRenames` and treated as **breaking**, so a migration script is required. The generated `migrate.ts` reads every row's nested value, stores each renamed member under its new name (descending into arrays at every level), and writes the value back; the old member is kept in the written value because it stays on the schema until the post-migration phase drops it. During deploy, the pre-migration phase keeps the old member on the nested field and adds the new member as optional, the script copies the values, and the post-migration phase drops the old member and enforces the new member's requiredness.
+
+A member removed without a confirmed rename stays a data-loss warning, which `migration validate --strict` picks up like any other warning; when a compatible sibling was added, the warning names it and the `--rename` value that confirms the rename:
 
 ```
 Warning: data loss possible:
 
-  - User.address.zip: Nested member removed (existing values will no longer be accessible through the schema). Possibly renamed to zipCode: nested renames are not detected, so copy its values with a migration script if it was renamed
+  - User.address.zip: Nested member removed (existing values will no longer be accessible through the schema). Possibly renamed to zipCode: confirm it with --rename "User.address.zip:<newName>" to scaffold a copy script, or keep the removal and copy the values yourself
 ```
 
-To carry the values over, add a custom `tailordb migration script` to the migration. The pre-migration phase keeps the removed member on the nested field until the script finishes, exactly like a removed top-level field, so the script can read `zip` and write `zipCode`. Nested fields reach the script as objects, so the copy rewrites the whole `address` value; keep the old member in what you write, because it is still part of the schema until the post-migration phase drops it. Declare the new member as optional: the platform rejects a nested member that is required while existing records lack it, and nested member constraints are not relaxed during the pre-migration phase.
+The pre-migration phase keeps a removed member on the nested field until the script finishes, exactly like a removed top-level field, so a custom script can still read it. Nested fields reach the script as objects. Renaming a nested member cannot be combined in one migration with renaming its table or the nested field itself, and an object-typed member cannot be renamed in the same migration as one of its own members; split such changes into separate migrations (rename the object first, then its member).
 
 ### Renaming a table
 
@@ -261,7 +279,7 @@ export default defineConfig({
 
 ### Migration file format compatibility
 
-Migration files are versioned independently of the SDK package. This SDK writes format version `3` and reads versions `1` through `3`. It normalizes supported older formats in memory; it never rewrites applied migration files on disk.
+Migration files are versioned independently of the SDK package. This SDK writes format version `6` and reads versions `1` through `6`. It normalizes supported older formats in memory; it never rewrites applied migration files on disk. Format version `6` records renames of members inside nested fields (`memberRenames`); older SDK versions refuse to read it rather than deploying such a migration without the copy step.
 
 If a future SDK can no longer replay an old migration format, re-baseline while using an SDK version that still supports the complete history, commit the new baseline, deploy it to every environment, and then upgrade the SDK. A file from a newer unsupported format instead requires upgrading the SDK first. The CLI rejects both cases with guidance rather than attempting a best-effort replay.
 
@@ -348,6 +366,8 @@ The `env` values are injected at bundle time (the same mechanism as resolvers/ex
 | Add required field                | Yes       | Yes               | Script populates default values                                                                                                                                                                                                                    |
 | Remove field                      | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve or clear data before the field leaves the active schema. The field stays readable from `migrate.ts` during Pre-migration.             |
 | Rename field                      | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "Table.oldField:newField"` — see [Renaming a field](#renaming-a-field). Auto-generated script copies values from the old field to the new one; both fields coexist during Pre-migration. |
+| Remove nested member              | No        | Optional          | Warning tier — see [Renaming a member inside a nested field](#renaming-a-member-inside-a-nested-field). The member stays readable from `migrate.ts` during Pre-migration.                                                                          |
+| Rename nested member              | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "Table.field.oldMember:newMember"`. Auto-generated script rewrites each row's nested value; the old member stays readable and the new member is optional during Pre-migration.           |
 | Change optional → required        | Yes       | Yes               | Script sets defaults for null values                                                                                                                                                                                                               |
 | Change required → optional        | No        | No                | Schema change only                                                                                                                                                                                                                                 |
 | Add index (non-unique)            | No        | No                | Schema change only                                                                                                                                                                                                                                 |
@@ -366,7 +386,7 @@ The `env` values are injected at bundle time (the same mechanism as resolvers/ex
 | Change field type (verified pair) | Yes       | Yes               | In-place for the pairs listed under [Field type changes](#field-type-changes); review the generated normalization scaffold and customize it only when existing values need transformation                                                          |
 | Change field type (other pair)    | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Edit the conversion in the first; the second needs no changes.                                                                     |
 | Change array → single value       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |
-| Change single value → array       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |
+| Change single value → array       | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Each stored value becomes a one-element array, so the conversion needs no edits.                                                   |
 
 ### Field type changes
 
@@ -440,7 +460,7 @@ The generated `never` annotation intentionally causes a TypeScript error until y
 
 ### Converting a field type
 
-A field type change outside the verified in-place pairs — `string` → `integer`, for example — cannot be applied in one step, because the field would have to hold both shapes at once. `migration generate` offers to carry the values through a temporary field instead:
+A field type change outside the verified in-place pairs — `string` → `integer`, for example — cannot be applied in one step, because the field would have to hold both shapes at once. The same holds when a single value becomes an array (`string` → `string[]`): the stored values must be rewritten as arrays before the field can take the new shape. `migration generate` offers to carry the values through a temporary field instead:
 
 ```
 User.price changes from string to integer, which cannot be applied in one step.
@@ -449,9 +469,11 @@ User.price changes from string to integer, which cannot be applied in one step.
 
 Confirming writes two migrations:
 
-1. **The conversion.** Adds a temporary field (`priceMigrate`), converts each stored value into it, and clears and removes the original field. Edit the conversion expression before deploying: the generated `never` annotation fails your typecheck, and `tailordb migration validate` rejects the migration while the review marker is still there.
+1. **The conversion.** Adds a temporary field (`priceMigrate`), converts each stored value into it, and clears and removes the original field. Edit the conversion expression before deploying: the generated `never` annotation fails your typecheck, and `tailordb migration validate` rejects the migration while the review marker is still there. When only the array-ness changes (`string` → `string[]`), the conversion stores each value as a one-element array and carries no review marker; when the element type changes as well (`integer` → `string[]`), you convert the element and the script wraps it.
 2. **The rename.** Renames the temporary field back to `price`. Its copy script is complete, but this migration also carries every other schema change the same run picked up, so review it as you would any generated migration.
 
+If converting to an array also reduces a decimal field's `scale` or removes enum values, the conversion keeps the review marker. Edit the element conversion to satisfy the target field before deploying.
+
 `tailor deploy` applies both. Because the conversion only touches rows whose original value is still set, a re-run resumes where it stopped rather than converting a row twice.
 
 The original field is removed in the first migration rather than the second, because the rename needs its name free. Your script can still read it while the conversion runs.
@@ -470,7 +492,7 @@ Without the flag the command fails rather than converting anything, so a scripte
 
 Some changes are still rejected and need a temporary field you add yourself — add the new field, write a script that fills it and clears the old one, then remove the old field and rename the temporary one in a later migration:
 
-- Array-to-scalar and scalar-to-array, since collapsing an array has no answer the generated script could choose for you.
+- A field that is already an array: collapsing it into a single value has no answer the generated script could choose for you, and changing its element type (`string[]` → `integer[]`) is not generated either.
 - A field that is unique, or that an index, relationship, permission, or table-level script names. Those keep pointing at the original name, which the conversion removes.
 
 ## Testing Pending Migrations
@@ -552,7 +574,7 @@ When you run `tailor deploy`, the SDK detects pending migrations (anything past
 
 For each pending migration:
 
-1. **Pre-migration**: Schema changes that would be breaking are applied in a relaxed form first. A verified in-place field type change keeps its complete previous field contract until Post-migration, including field and table-level hooks or validators changed by the same migration. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the table so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped); members removed from a nested field are kept the same way. For a renamed field, the old field is kept and the new field is added with its constraints relaxed, so the script can read the old field and write the new one. For a renamed table, the new table is created with its full constraints while the old table stays on the namespace until post-migration cleanup, so the script can copy rows between them. Breaking table-level index changes are relaxed the same way: a newly-added unique index is withheld, and an index gaining a unique constraint (or a unique index changing its field set) keeps its previous definition, so `migrate.ts` can resolve duplicates first. Non-breaking changes that are part of the same migration are also applied here.
+1. **Pre-migration**: Schema changes that would be breaking are applied in a relaxed form first. A verified in-place field type change keeps its complete previous field contract until Post-migration, including field and table-level hooks or validators changed by the same migration. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the table so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped); members removed from a nested field are kept the same way, and the new member of a confirmed nested rename is added as optional and non-unique. For a renamed field, the old field is kept and the new field is added with its constraints relaxed, so the script can read the old field and write the new one. For a renamed table, the new table is created with its full constraints while the old table stays on the namespace until post-migration cleanup, so the script can copy rows between them. Breaking table-level index changes are relaxed the same way: a newly-added unique index is withheld, and an index gaining a unique constraint (or a unique index changing its field set) keeps its previous definition, so `migrate.ts` can resolve duplicates first. Non-breaking changes that are part of the same migration are also applied here.
 2. **Script execution**: If `migrate.ts` exists on disk for this migration, it is bundled and sent to the platform via the script execution API and runs as the configured machine user inside a transaction. The script is hard-required for breaking changes (`diff.requiresMigrationScript`) — deploy fails if the file is missing, unless a `--no-script` acknowledgment was recorded (see [Breaking changes without a script](#breaking-changes-without-a-script)). It is also executed when present for warning-tier diffs — see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts).
 3. **Post-migration schema**: Required constraints and the target field definitions are applied. Do not assume that removing a field clears its underlying stored JSON value.
 4. **Checkpoint and cleanup**: The `sdk-migration` label is bumped to this migration's number, then removed GQL permissions and tables — including the old table left behind by a rename — are deleted. Advancing the checkpoint first prevents a failed checkpoint write from requiring the SDK to recreate irreversibly deleted records.

package/docs/testing.md

@@ -59,7 +59,7 @@ export default defineConfig({
 `tailorRuntime()` provides:
 
 1. **Node.js module blocking** — `import { randomBytes } from "node:crypto"` in production code throws an error with a suggestion for the Web Standard API alternative (`globalThis.crypto`). Test files (`*.test.ts`, `*.spec.ts`) are exempt.
-2. **Node.js globals removal** — Only globals available in the platform runtime are kept (whitelist). `Buffer`, `global`, `setImmediate`, `__dirname`, `__filename`, `performance`, and others are removed.
+2. **Node.js globals removal** — Only globals available in the platform runtime are kept (whitelist). `Buffer`, `global`, `setImmediate`, `__dirname`, `__filename`, and others are removed.
 3. **Platform API mocks** — the platform error classes (`TailorErrors`, `TailorDBFileError`) and `tailor.context` are always available. The other namespaces (`tailordb.Client`, `tailor.workflow`, `tailor.secretmanager`, …) are mocked when you acquire the corresponding `mockX()` — see below.
 
 ### Acquiring mocks with `using`
@@ -452,12 +452,7 @@ export default defineConfig({
   plugins: [tailorRuntime()],
   test: {
     projects: [
-      // `extends: true` is required so each project inherits the root-level
-      // `tailorRuntime()` plugin (transform hook + injected setup file).
-      // Without it, only the environment name rewrite applies — node:* import
-      // blocking and per-test global cleanup will silently not run.
       {
-        extends: true,
         test: {
           name: "unit",
           environment: "tailor-runtime",
@@ -465,7 +460,6 @@ export default defineConfig({
         },
       },
       {
-        extends: true,
         test: {
           name: "e2e",
           include: ["e2e/**/*.test.ts"],
@@ -477,6 +471,8 @@ export default defineConfig({
 });
 ```
 
+Inline projects inherit the root-level `tailorRuntime()` plugin by default on Vitest 5. On Vitest 4, add `extends: true` to each project; without it, `node:*` import blocking silently does not run.
+
 ### Known Limitations
 
 - **`process` and `require`** are not removed or blocked. Vitest's internal runner depends on them extensively. On the real platform runtime, they do not exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.14.2",
+  "version": "2.16.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -153,8 +153,8 @@
     "@badgateway/oauth2-client": "3.3.1",
     "@bufbuild/protobuf": "2.14.1",
     "@bufbuild/protovalidate": "1.2.0",
-    "@connectrpc/connect": "2.1.2",
-    "@connectrpc/connect-node": "2.1.2",
+    "@connectrpc/connect": "2.2.0",
+    "@connectrpc/connect-node": "2.2.0",
     "@inquirer/core": "12.0.2",
     "@inquirer/prompts": "8.7.1",
     "@jridgewell/trace-mapping": "0.3.31",
@@ -165,21 +165,22 @@
     "@opentelemetry/sdk-trace-node": "2.11.0",
     "@opentelemetry/semantic-conventions": "1.43.0",
     "@oxc-project/types": "0.148.0",
+    "@politty/zod": "0.2.1",
     "@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.6",
+    "@toiroakr/lines-db": "0.12.7",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.1.11",
-    "confbox": "0.2.4",
+    "confbox": "0.3.1",
     "date-fns": "4.4.0",
     "es-toolkit": "1.52.0",
     "find-up-simple": "1.0.1",
     "get-east-asian-width": "1.6.0",
     "get-tsconfig": "4.14.3",
-    "globals": "17.11.0",
+    "globals": "17.12.0",
     "graphql": "17.0.2",
     "inflection": "3.0.2",
     "kysely": "0.29.5",
@@ -190,7 +191,6 @@
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.2",
-    "politty": "0.11.9",
     "rolldown": "1.2.7",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
@@ -208,7 +208,7 @@
     "@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",
+    "@vitest/coverage-v8": "5.0.0",
     "eslint-plugin-zod": "4.12.0",
     "oxfmt": "0.66.0",
     "oxlint": "1.81.0",
@@ -216,8 +216,8 @@
     "sonda": "0.14.0",
     "tsdown": "0.23.0",
     "typescript": "6.0.3",
-    "vitest": "4.1.11",
-    "zinfer": "0.2.8"
+    "vitest": "5.0.0",
+    "zinfer": "0.4.5"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.2.0",