@tailor-platform/sdk 2.10.0 → 2.11.0

package/dist/vitest/mocks/tailordb-pglite.d.mts

@@ -0,0 +1,88 @@
+import { PGliteClient } from "../pglite-kysely.mjs";
+//#region src/vitest/mocks/tailordb-pglite.d.ts
+/** A query executed through the PGlite-backed TailorDB client. */
+interface ExecutedPGliteQuery {
+  /** Namespace of the `getDB` call that issued the query. */
+  namespace: string;
+  /** SQL text with positional (`$1`, `$2`, ...) placeholders. */
+  query: string;
+  /** Parameter values bound to the placeholders. */
+  params: unknown[];
+}
+/** Options for {@link mockTailordbWithPGlite}. */
+interface MockTailordbPGliteOptions {
+  /**
+   * PGlite instance per `getDB` namespace. A `getDB` call for a namespace
+   * missing here throws instead of falling back to another instance. Pass the
+   * same instance under several namespaces to share one database between them.
+   */
+  namespaces: Record<string, PGliteClient>;
+}
+interface CreatedClient {
+  namespace: string;
+  ended: boolean;
+}
+/**
+ * Acquire a disposable mock that backs the generated `getDB(namespace)` with
+ * PGlite, so resolver/executor/workflow code runs unchanged and its queries
+ * execute as real SQL on an in-memory Postgres. Restored on dispose; the
+ * PGlite instances are borrowed, never closed — close them yourself (e.g. in
+ * `afterAll`).
+ *
+ * Create the tables a test needs up front with `CREATE TABLE` statements
+ * matching the generated Kysely types. PGlite runs full PostgreSQL while
+ * TailorDB supports a subset of it, so a statement passing here can still be
+ * rejected by the platform.
+ *
+ * Transactions on a shared instance are serialized: while one is open,
+ * queries from other `getDB` instances on the same PGlite instance wait for
+ * it to finish. Do not run such tests with `test.concurrent`, and do not
+ * query the same instance through a second `getDB` from inside a transaction
+ * — that waits on itself.
+ * @param options - PGlite instance registration per namespace
+ * @returns Disposable TailorDB mock control object
+ * @example
+ * ```typescript
+ * import { PGlite } from "@electric-sql/pglite";
+ * import { mockTailordbWithPGlite } from "@tailor-platform/sdk/vitest";
+ * import { getDB } from "../generated/tailordb";
+ *
+ * const pglite = new PGlite();
+ * afterAll(() => pglite.close());
+ *
+ * test("real SQL", async () => {
+ *   using _db = mockTailordbWithPGlite({ namespaces: { tailordb: pglite } });
+ *   await pglite.query(`CREATE TABLE "User" ("id" uuid PRIMARY KEY, "name" text NOT NULL)`);
+ *   await getDB("tailordb").insertInto("User").values({ id: crypto.randomUUID(), name: "a" }).execute();
+ * });
+ * ```
+ */
+declare function mockTailordbWithPGlite(options: MockTailordbPGliteOptions): {
+  /** The mock `tailordb.Client` constructor (`vi.fn`). */
+  Client: import("vitest").Mock<(this: any, config?: {
+    namespace?: string;
+  }) => void>;
+  /**
+   * All queries executed on the PGlite instances, in order, with the
+   * namespace that issued each.
+   * @returns Executed queries array
+   */
+  readonly executedQueries: ExecutedPGliteQuery[];
+  /**
+   * All TailorDB clients created, with their namespace and end state.
+   * @returns Created clients array
+   */
+  readonly createdClients: CreatedClient[];
+  /**
+   * Clear recorded queries and clients while keeping the mock installed.
+   * Throws if a transaction is open.
+   */
+  clear(): void;
+  /**
+   * Reset recorded state and restore the default client behavior.
+   * Throws if a transaction is open.
+   */
+  reset(): void;
+} & Disposable;
+//#endregion
+export { ExecutedPGliteQuery, MockTailordbPGliteOptions, mockTailordbWithPGlite };

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

@@ -1,5 +1,16 @@
 import { ColumnType, Kysely } from "kysely";
 //#region src/vitest/pglite-kysely.d.ts
+/** Result of a {@link PGliteClient.query} call. */
+interface PGliteQueryResult {
+  /** Rows returned by the statement. */
+  rows: unknown[];
+  /** Number of rows an INSERT/UPDATE/DELETE touched. */
+  affectedRows?: number;
+  /** Postgres command tag of the statement (`"SELECT"`, `"INSERT"`, ...). */
+  command?: string;
+  /** Row count reported alongside the command tag. */
+  rowCount?: number;
+}
 /**
  * The subset of a `@electric-sql/pglite` `PGlite` instance used by
  * {@link createKyselyPGlite}. Any client with a compatible `query`/`close`
@@ -7,10 +18,7 @@ import { ColumnType, Kysely } from "kysely";
  */
 interface PGliteClient {
   /** Run a single SQL statement with positional (`$1`, `$2`, ...) parameters. */
-  query(query: string, params?: unknown[]): Promise<{
-    rows: unknown[];
-    affectedRows?: number;
-  }>;
+  query(query: string, params?: unknown[]): Promise<PGliteQueryResult>;
   /** Release the underlying database. Called by `db.destroy()`. */
   close(): Promise<void>;
 }
@@ -62,4 +70,4 @@ type Unmigrated<DB> = { [T in keyof DB]: { [C in keyof DB[T]]: UnmigratedColumn<
  */
 declare function createKyselyPGlite<DB = Record<string, never>>(client: PGliteClient): Kysely<DB>;
 //#endregion
-export { PGliteClient, Unmigrated, createKyselyPGlite };
+export { PGliteClient, PGliteQueryResult, Unmigrated, createKyselyPGlite };

package/docs/plugin/custom.md

@@ -83,6 +83,13 @@ interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
 | `executors` | `PluginGeneratedExecutor[]`                     | Additional executors to generate                       |
 | `extends`   | `{ fields?: Record<string, TailorAnyDBField> }` | Fields to add to the source table                      |
 
+Tables in `tables` are validated as complete TailorDB table definitions before registration.
+Fields in `extends.fields` are validated as part of the resulting source table. You can return a
+table builder directly or a structural copy such as `{ ...db.table(...) }`; a copy is accepted as
+long as it retains valid table schema properties. Malformed output stops the build with an error
+that identifies the plugin and relevant table output, without partially registering tables from
+that source table's plugin processing.
+
 **Use cases**:
 
 - Generate derived tables (e.g., archive tables, history tables) from user-defined tables
@@ -115,6 +122,10 @@ onTableLoaded(context) {
 
 Same as `TablePluginOutput` but without `extends` (namespace plugins cannot extend a source table).
 
+Tables in `tables` undergo the same validation and support structural copies. If any returned
+table is malformed, the build stops before namespace-generated tables are registered and the
+error identifies the plugin and relevant table output.
+
 **Use cases**:
 
 - Generate tables that don't derive from a specific user table (e.g., audit log, settings table)

package/docs/plugin/index.md

@@ -102,6 +102,11 @@ Plugins can generate:
 - **Field Extensions**: Additional fields added to the source table
 - **Output Files**: TypeScript code and other files via generation-time hooks
 
+Tables produced by definition-time hooks are validated before registration. This includes
+generated tables and source tables after field extensions are applied. Malformed output stops
+the build with an error that identifies the plugin and relevant table output, without partially
+registering tables from that processing step.
+
 Generated files are placed under `.tailor/<plugin-id>/` (the plugin ID is sanitized,
 e.g. `@example/soft-delete` → `example-soft-delete`), such as:
 

package/docs/testing.md

@@ -24,6 +24,7 @@ For anonymous direct calls:
 Platform API mocks under `@tailor-platform/sdk/vitest` (for use with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below):
 
 - `mockTailordb` — TailorDB query stubs and call recording
+- `mockTailordbWithPGlite` — TailorDB backed by a real in-memory Postgres (PGlite)
 - `mockWorkflow` — `tailor.workflow` job / wait / resolve mocks
 - `runWorkflowLocally` — local full-chain workflow runner
 - `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger` — corresponding platform API mocks
@@ -63,7 +64,7 @@ export default defineConfig({
 
 ### Acquiring mocks with `using`
 
-Each mock controller (`mockTailordb`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
+Each mock controller (`mockTailordb`, `mockTailordbWithPGlite`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
 
 ```typescript
 import { mockTailordb } from "@tailor-platform/sdk/vitest";
@@ -144,6 +145,81 @@ Within one `mockTailordb()` instance, use either `onQuery()` matchers or a direc
 
 Pass `{ onUnhandled: "error" }` to make an unmatched query fail instead of returning an empty result.
 
+#### Real SQL execution with PGlite (`mockTailordbWithPGlite`)
+
+Instead of staging responses, back TailorDB with [`@electric-sql/pglite`](https://pglite.dev/) — an in-memory PostgreSQL (install it as a devDependency) — so the queries a resolver, executor, or workflow job issues through `getDB()` execute against real data. `getDB(namespace)` needs no test-side swap: acquire the mock, and each namespace you list resolves to its PGlite instance.
+
+Create the tables the test touches with `CREATE TABLE` statements matching the generated Kysely types — `text` for string and enum fields, `timestamptz` for date/datetime, `jsonb` for nested objects. The schema only has to match what your code reads and writes, not TailorDB's storage; relations are not enforced.
+
+```typescript
+import { PGlite } from "@electric-sql/pglite";
+import { mockTailordbWithPGlite } from "@tailor-platform/sdk/vitest";
+import { afterAll, beforeAll, expect, test } from "vitest";
+import { getDB } from "../generated/db";
+import resolver from "./upsertUsers";
+
+const pglite = new PGlite();
+
+beforeAll(async () => {
+  await pglite.exec(`
+    CREATE TABLE "User" (
+      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+      "name" text NOT NULL,
+      "email" text NOT NULL,
+      "age" integer NOT NULL
+    );
+  `);
+});
+
+afterAll(async () => {
+  await pglite.close();
+});
+
+test("upserts against real rows", async () => {
+  using _db = mockTailordbWithPGlite({ namespaces: { "main-db": pglite } });
+  const db = getDB("main-db");
+  await db
+    .insertInto("User")
+    .values({ name: "Existing", email: "exists@example.com", age: 40 })
+    .execute();
+
+  const result = await resolver.body({
+    input: {
+      users: [
+        { name: "Newcomer", email: "new@example.com", age: 22 },
+        { name: "Existing", email: "exists@example.com", age: 41 },
+      ],
+    },
+    caller: null,
+    invoker: null,
+    env: { appName: "Resolver Template", version: 1 },
+  });
+
+  expect(result).toEqual({ created: 1, updated: 1 });
+  const rows = await db.selectFrom("User").selectAll().orderBy("email", "asc").execute();
+  expect(rows.map((row) => row.age)).toEqual([41, 22]);
+});
+```
+
+A `.serial()` field is omitted from generated `getDB()` inserts, so its PGlite column must generate a value. Use an identity for an integer serial. For a formatted string serial, create a sequence and reproduce the format in its `DEFAULT` expression:
+
+```sql
+CREATE SEQUENCE "invoiceNumberSequence" START WITH 1000;
+CREATE TABLE "Invoice" (
+  "sequentialId" integer GENERATED BY DEFAULT AS IDENTITY (START WITH 1),
+  "invoiceNumber" text NOT NULL
+    DEFAULT ('INV-' || lpad(nextval('"invoiceNumberSequence"')::text, 5, '0'))
+);
+```
+
+PGlite does not apply the TailorDB `.serial()` configuration itself. Match the `start`, `format`, and any limit that the behavior under test relies on.
+
+- The PGlite instance is yours: the mock never closes it, so close it in `afterAll`. Reuse one instance across a suite — creating one per test is slow.
+- Pass the same instance under several namespaces to drive them against one shared database.
+- Seed through `getDB` itself. When a column type rejects a value that only the test must stage, use `createKyselyPGlite<Unmigrated<...>>(pglite)` instead — see [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally). This only affects test setup; it cannot supply a `.serial()` value for an insert issued by the code under test.
+- Transactions on a shared instance are serialized: while one is open, queries from other `getDB` instances wait. Do not use `test.concurrent` with a shared instance, and do not query the same instance through a second `getDB` from inside a transaction — that waits on itself.
+- PGlite runs full PostgreSQL while TailorDB supports a subset of it, and TailorDB hooks, validations, and permissions do not run here — a test passing on PGlite can still behave differently on the platform. Keep [`mockTailordb`](#tailordb-mock) or [`createKyselyMock`](#kysely-layer-mock-createkyselymock) tests for query shape and error paths, and E2E tests for platform behavior.
+
 ### Workflow Mock
 
 Workflow job `.start()` calls use the platform workflow runtime. Acquire `mockWorkflow()` when you want to provide start responses with `setJobHandler` / `enqueueResult` or assert on `startedJobs`. If no response is configured, the mock throws so missing job mocks fail loudly. Use `job(definition)` or `workflow(definition)` to get a stable, fully typed Vitest mock for one definition:
@@ -592,7 +668,7 @@ 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.
+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, or [`mockTailordbWithPGlite`](#real-sql-execution-with-pglite-mocktailordbwithpglite) to execute the queries against a real in-memory Postgres.
 
 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).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -169,13 +169,13 @@
     "@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",
+    "@toiroakr/lines-db": "0.12.5",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.1.11",
     "confbox": "0.2.4",
     "date-fns": "4.4.0",
-    "es-toolkit": "1.51.0",
+    "es-toolkit": "1.52.0",
     "find-up-simple": "1.0.1",
     "get-east-asian-width": "1.6.0",
     "get-tsconfig": "4.14.3",
@@ -191,7 +191,7 @@
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.1",
     "politty": "0.11.9",
-    "rolldown": "1.2.5",
+    "rolldown": "1.2.6",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
     "std-env": "4.2.0",
@@ -242,7 +242,7 @@
   "scripts": {
     "test": "vitest",
     "test:unit": "vitest --project=unit*",
-    "test:e2e": "vitest --project=e2e",
+    "test:e2e": "vitest --project=e2e*",
     "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",