@tailor-platform/sdk 2.0.0-next.0 → 2.0.0-next.2

package/docs/generator/builtin.md

@@ -1,257 +0,0 @@
-# Builtin Generators
-
-The SDK includes four builtin generators for common code generation tasks.
-
-## @tailor-platform/kysely-type
-
-Generates Kysely type definitions and the `getDB()` function for type-safe database access.
-
-### Configuration
-
-```typescript
-["@tailor-platform/kysely-type", { distPath: "./generated/tailordb.ts" }];
-```
-
-| Option     | Type     | Description                 |
-| ---------- | -------- | --------------------------- |
-| `distPath` | `string` | Output file path (required) |
-
-### Output
-
-Generates a TypeScript file containing:
-
-- Type definitions for all TailorDB types
-- `getDB(namespace)` function to create Kysely instances
-- Utility types for `Timestamp`, `Serial`, and `ObjectColumnType` (used for nested object fields so insert and select types stay correct)
-
-### Usage
-
-```typescript
-import { getDB } from "./generated/tailordb";
-
-// In resolvers
-body: async (context) => {
-  const db = getDB("tailordb");
-  const users = await db
-    .selectFrom("User")
-    .selectAll()
-    .where("email", "=", context.input.email)
-    .execute();
-  return { users };
-};
-
-// In executors
-body: async ({ newRecord }) => {
-  const db = getDB("tailordb");
-  await db.insertInto("AuditLog").values({ userId: newRecord.id, action: "created" }).execute();
-};
-
-// In workflow jobs
-body: async (input, { env }) => {
-  const db = getDB("tailordb");
-  return await db
-    .selectFrom("Order")
-    .selectAll()
-    .where("id", "=", input.orderId)
-    .executeTakeFirst();
-};
-```
-
-### Raw SQL
-
-For queries that the Kysely query builder can't express, use the `sql` tag re-exported from `@tailor-platform/sdk/kysely`. Plain value substitutions (`${...}`) are sent as bound parameters, so user-supplied values are parameterized safely. SQL fragments produced by Kysely helpers (for example `sql.raw(...)`, identifiers, refs) are inlined into the generated SQL string by design — do not pass untrusted input through those.
-
-```typescript
-import { sql } from "@tailor-platform/sdk/kysely";
-import { getDB } from "./generated/tailordb";
-
-createResolver({
-  name: "supplierCountByState",
-  operation: "query",
-  input: { country: t.string() },
-  output: t.object({
-    rows: t.array(t.object({ state: t.string(), count: t.int() })),
-  }),
-  body: async ({ input }) => {
-    const db = getDB("tailordb");
-    const { rows } = await sql<{ state: string; count: number }>`
-      SELECT state, COUNT(*) AS count
-        FROM "Supplier"
-       WHERE country = ${input.country}
-    GROUP BY state
-    `.execute(db);
-    return { rows };
-  },
-});
-```
-
-The same `sql` tag works inside `db.transaction().execute(async (trx) => ...)` by passing `trx` to `.execute()`:
-
-```typescript
-await db.transaction().execute(async (trx) => {
-  await sql`UPDATE "Supplier" SET state = ${state} WHERE id = ${id}`.execute(trx);
-});
-```
-
-## @tailor-platform/enum-constants
-
-Extracts enum constants from TailorDB type definitions.
-
-### Configuration
-
-```typescript
-["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }];
-```
-
-| Option     | Type     | Description                 |
-| ---------- | -------- | --------------------------- |
-| `distPath` | `string` | Output file path (required) |
-
-### Output
-
-Generates TypeScript constants for all enum fields:
-
-```typescript
-// Generated output
-export const OrderStatus = {
-  PENDING: "PENDING",
-  PROCESSING: "PROCESSING",
-  COMPLETED: "COMPLETED",
-  CANCELLED: "CANCELLED",
-} as const;
-
-export type OrderStatus = (typeof OrderStatus)[keyof typeof OrderStatus];
-```
-
-### Usage
-
-```typescript
-import { OrderStatus } from "./generated/enums";
-
-// Type-safe enum usage
-const status: OrderStatus = OrderStatus.PENDING;
-
-// In queries
-const orders = await db
-  .selectFrom("Order")
-  .selectAll()
-  .where("status", "=", OrderStatus.COMPLETED)
-  .execute();
-```
-
-## @tailor-platform/file-utils
-
-Generates utility functions for handling file-type fields in TailorDB.
-
-### Configuration
-
-```typescript
-["@tailor-platform/file-utils", { distPath: "./generated/files.ts" }];
-```
-
-| Option     | Type     | Description                 |
-| ---------- | -------- | --------------------------- |
-| `distPath` | `string` | Output file path (required) |
-
-### Output
-
-Generates TypeScript interfaces and utilities for types with file fields:
-
-```typescript
-// Generated output
-export interface UserFileFields {
-  avatar: string;
-  documents: string;
-}
-
-export function getUserFileFields(): (keyof UserFileFields)[] {
-  return ["avatar", "documents"];
-}
-```
-
-## @tailor-platform/seed
-
-Generates seed data configuration files for database initialization.
-
-### Configuration
-
-```typescript
-// Basic configuration
-["@tailor-platform/seed", { distPath: "./seed" }];
-
-// With default machine user
-["@tailor-platform/seed", { distPath: "./seed", machineUserName: "admin" }];
-```
-
-| Option               | Type                                           | Description                                                                                                                                                       |
-| -------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `distPath`           | `string`                                       | Output directory path (required)                                                                                                                                  |
-| `machineUserName`    | `string`                                       | Default machine user name (can be overridden at runtime)                                                                                                          |
-| `disableIdpUserSync` | `{ userToIdp?: boolean; idpToUser?: boolean }` | Skip emitting individual `_User <-> userProfile` foreign keys. Both directions are emitted by default. See [IdP user synchronization](#idp-user-synchronization). |
-
-### IdP user synchronization
-
-When `auth.userProfile` is configured, the seed plugin treats the userProfile
-type (e.g. `User`) and the IdP-managed `_User` table as a pair. By default it
-emits foreign keys in both directions so that `validate` rejects any row in
-either table that does not have a matching counterpart:
-
-| Direction   | Foreign key                                    | Catches                                        |
-| ----------- | ---------------------------------------------- | ---------------------------------------------- |
-| `idpToUser` | `_User.name` → `<userProfile>.<usernameField>` | Creating an IdP credential with no profile row |
-| `userToIdp` | `<userProfile>.<usernameField>` → `_User.name` | Creating a profile row with no IdP credential  |
-
-Neither direction is enforced by the runtime. In production it is normal for
-one side to exist without the other — for example a userProfile row exists
-the moment a user is invited, but the corresponding `_User` row appears only
-after the user finishes signing up. To seed such states, set the relevant
-direction in `disableIdpUserSync` to `true`:
-
-```typescript
-// Allow seeding invited-but-not-registered userProfile rows.
-// Still rejects _User rows without a matching userProfile row.
-["@tailor-platform/seed", { distPath: "./seed", disableIdpUserSync: { userToIdp: true } }];
-
-// Allow seeding _User rows whose userProfile does not exist yet.
-// Still rejects userProfile rows without a matching _User row.
-["@tailor-platform/seed", { distPath: "./seed", disableIdpUserSync: { idpToUser: true } }];
-```
-
-Omitted directions default to `false` (FK emitted).
-
-### Output
-
-Generates a seed directory structure:
-
-```
-seed/
-├── data/
-│   ├── User.jsonl        # Seed data files (JSONL format)
-│   ├── User.schema.ts    # lines-db schema definitions
-│   └── Product.jsonl
-└── exec.mjs              # Executable script
-```
-
-### Usage
-
-Run the generated executable script:
-
-```bash
-# With machine user from config
-node seed/exec.mjs
-
-# Specify machine user at runtime (required if not configured, or to override)
-node seed/exec.mjs --machine-user admin
-
-# Short form
-node seed/exec.mjs -m admin
-
-# With other options
-node seed/exec.mjs -m admin --truncate --yes
-```
-
-The `--machine-user` option is required at runtime if `machineUserName` is not configured in the generator options.
-
-The generated files are compatible with gql-ingest for bulk data import.
-
-The `exec.mjs` is fully regenerated on every `sdk generate` and starts with an `@generated` header — do not hand-edit it. Its `--truncate` path reuses the `tailordb truncate` command, so namespaces declared with `{ external: true }` are skipped automatically and a shell app cannot wipe a sibling app's data via `seed:reset`.

package/docs/generator/custom.md

@@ -1,147 +0,0 @@
-# Custom Generators (Deprecated)
-
-> **Deprecated**: Use `definePlugins()` with generation-time hooks (`onTypeLoaded`, `generate`, etc.) instead. See [Custom Plugins](../plugin/custom.md) for the recommended approach.
-
-Create your own generators by implementing the `CodeGenerator` interface.
-
-## CodeGenerator Interface
-
-```typescript
-interface CodeGenerator<T, R, E, Ts, Rs> {
-  id: string;
-  description: string;
-
-  // Process individual items
-  processType(args: {
-    type: TailorDBType;
-    namespace: string;
-    source: { filePath: string; exportName: string };
-  }): T | Promise<T>;
-
-  processResolver(args: { resolver: Resolver; namespace: string }): R | Promise<R>;
-
-  processExecutor(executor: Executor): E | Promise<E>;
-
-  // Aggregate per namespace (optional)
-  processTailorDBNamespace?(args: {
-    namespace: string;
-    types: Record<string, T>;
-  }): Ts | Promise<Ts>;
-
-  processResolverNamespace?(args: {
-    namespace: string;
-    resolvers: Record<string, R>;
-  }): Rs | Promise<Rs>;
-
-  // Final aggregation
-  aggregate(args: {
-    input: GeneratorInput<Ts, Rs>;
-    executorInputs: E[];
-    baseDir: string;
-  }): GeneratorResult | Promise<GeneratorResult>;
-}
-```
-
-## GeneratorResult
-
-Generators return a `GeneratorResult` containing files to create:
-
-```typescript
-interface GeneratorResult {
-  files: Array<{
-    path: string; // Relative path from project root
-    content: string; // File content
-    skipIfExists?: boolean; // Skip if file already exists (default: false)
-    executable?: boolean; // Make file executable (default: false)
-  }>;
-  errors?: string[];
-}
-```
-
-## Example: Simple Type List Generator
-
-```typescript
-import type { CodeGenerator, GeneratorResult } from "@tailor-platform/sdk";
-
-const typeListGenerator: CodeGenerator<string, null, null, string[], null> = {
-  id: "type-list",
-  description: "Generates a list of all TailorDB type names",
-
-  processType({ type }) {
-    return type.name;
-  },
-
-  processResolver() {
-    return null;
-  },
-
-  processExecutor() {
-    return null;
-  },
-
-  processTailorDBNamespace({ types }) {
-    return Object.values(types);
-  },
-
-  aggregate({ input }) {
-    const allTypes = input.tailordb.flatMap((ns) => ns.types);
-    const content = `// Generated type list\nexport const types = ${JSON.stringify(allTypes, null, 2)} as const;\n`;
-
-    return {
-      files: [{ path: "generated/types.ts", content }],
-    };
-  },
-};
-```
-
-## Using Custom Generators
-
-Pass the generator object directly to `defineGenerators()`:
-
-```typescript
-import { defineGenerators } from "@tailor-platform/sdk";
-import { typeListGenerator } from "./generators/type-list";
-
-export const generators = defineGenerators(
-  ["@tailor-platform/kysely-type", { distPath: "./generated/tailordb.ts" }],
-  typeListGenerator, // Custom generator
-);
-```
-
-## Available Input Data
-
-### TailorDBType
-
-Contains full type information including:
-
-- `name`: Type name
-- `fields`: Field definitions with types, validation, and descriptions
-- `relations`: Relationship definitions
-- `indexes`: Index configurations
-- `permission`: Permission rules
-
-### Resolver
-
-Contains resolver configuration:
-
-- `name`: Resolver name
-- `operation`: Query or mutation
-- `input`: Input schema
-- `output`: Output schema
-
-### Executor
-
-Contains executor configuration:
-
-- `name`: Executor name
-- `trigger`: Trigger configuration
-- `operation`: Execution target
-
-### GeneratorAuthInput
-
-Contains authentication configuration when available:
-
-- `name`: Auth service name
-- `userProfile`: User profile type information
-- `machineUsers`: Machine user definitions
-- `oauth2Clients`: OAuth2 client configurations

package/docs/generator/index.md

@@ -1,66 +0,0 @@
-# Generators
-
-Generators analyze your TailorDB types, Resolvers, and Executors to automatically generate TypeScript code.
-
-## Overview
-
-When you run `tailor-sdk generate`, the SDK:
-
-1. Loads all TailorDB types, Resolvers, and Executors from your configuration
-2. Passes each definition to the configured generators
-3. Aggregates the results and writes output files
-
-This enables generators to create derived code based on your application's schema. For example, the `@tailor-platform/kysely-type` generator produces type-safe database access code from your TailorDB definitions.
-
-## Configuration
-
-Define generators in `tailor.config.ts` using `defineGenerators()`:
-
-```typescript
-import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
-
-export const generators = defineGenerators(
-  ["@tailor-platform/kysely-type", { distPath: "./generated/tailordb.ts" }],
-  ["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }],
-);
-
-export default defineConfig({
-  name: "my-app",
-  // ...
-});
-```
-
-**Important**: The `generators` export must be a named export (not default).
-
-## CLI Commands
-
-### Generate Files
-
-```bash
-tailor-sdk generate
-```
-
-Generates all configured output files.
-
-### Watch Mode
-
-```bash
-tailor-sdk generate --watch
-```
-
-Watches for file changes and regenerates automatically.
-
-## Environment Variables
-
-### `TAILOR_PLATFORM_SDK_DTS_PATH`
-
-Customize the output path of the generated `tailor.d.ts` type definition file. By default, `tailor.d.ts` is written next to `tailor.config.ts`.
-
-```bash
-TAILOR_PLATFORM_SDK_DTS_PATH=src/types/tailor.d.ts tailor-sdk generate
-```
-
-## Generator Types
-
-- [Builtin Generators](./builtin.md) - Ready-to-use generators included with the SDK
-- [Custom Generators](./custom.md) - Create your own generators (Preview)