@tailor-platform/sdk 2.8.0 → 2.10.0

package/dist/vitest/mocks/file.d.mts

@@ -46,10 +46,10 @@ declare function mockFile(options?: MockFileOptions): {
   calls: FileCall[];
   clear(): void;
   reset(): void;
+  delete: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<void>>;
   upload: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string, data: string | ArrayBuffer | Uint8Array | number[], options?: FileUploadOptions) => Promise<FileUploadResponse>>;
   download: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileDownloadResponse>>;
   downloadAsBase64: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileDownloadAsBase64Response>>;
-  delete: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<void>>;
   getMetadata: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileMetadata>>;
   downloadStream: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileDownloadStreamResponse>>;
   uploadStream: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string, readableStream: ReadableStream<Uint8Array | ArrayBuffer>, options?: FileUploadStreamOptions) => Promise<FileUploadResponse>>;

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.8.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",
@@ -165,8 +165,8 @@
     "@opentelemetry/sdk-trace-node": "2.10.0",
     "@opentelemetry/semantic-conventions": "1.43.0",
     "@oxc-project/types": "0.147.0",
-    "@secretlint/core": "13.0.4",
-    "@secretlint/secretlint-rule-preset-recommend": "13.0.4",
+    "@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",