# Install the CLI
bun add -D tangrams

# Initialize your config (interactive)
bunx tangrams init

# Generate the pieces
bunx tangrams generate

// Generated pieces snap right in
import { useQuery, useMutation } from "@tanstack/react-query"
import { getUserQueryOptions, updateUserMutationOptions } from "./tangrams/my-api/query/options"

function UserProfile({ id }: { id: string }) {
  // Type-safe query with automatic cache keys
  const { data } = useQuery(getUserQueryOptions({ id }))
  
  // Type-safe mutation
  const { mutate } = useMutation(updateUserMutationOptions())
  
  return <div>{data?.user.name}</div>
}

import { defineConfig } from "tangrams"

export default defineConfig({
  // Directory where the tangrams folder will be generated (default: ".")
  // With ".", files are generated at ./tangrams/<source>/...
  // With "./src", files are generated at ./src/tangrams/<source>/...
  output: ".",

  // Validation library for generated schemas (default: "zod")
  // Supported: "zod", "valibot", "arktype", "effect"
  // All four support Standard Schema for TanStack Form compatibility
  validator: "zod",

  // Array of data sources to generate from
  sources: [
    // ===================
    // GraphQL Source
    // ===================
    {
      // Unique name for this source (lowercase alphanumeric with hyphens)
      name: "graphql",
      // Source type discriminator
      type: "graphql",

      // Schema configuration - choose ONE of the following:

      // Option A: URL-based (introspection)
      schema: {
        url: "http://localhost:4000/graphql",
        // Optional headers for introspection request
        headers: {
          "x-api-key": process.env.API_KEY,
        },
      },

      // Option B: File-based (local SDL files)
      // schema: {
      //   file: "./schema.graphql",
      //   // Or multiple files with glob patterns:
      //   // file: ["./schema.graphql", "./extensions/**/*.graphql"],
      // },

      // Glob pattern(s) for GraphQL document files (.graphql)
      documents: "./src/graphql/**/*.graphql",
      // Or multiple patterns:
      // documents: ["./src/graphql/**/*.graphql", "./src/queries/**/*.graphql"],

      // What to generate from this source
      // Options: "query", "form", "db"
      // Note: "db" automatically enables "query"
      generates: ["query", "form", "db"],

      // Optional overrides
      overrides: {
        // Custom scalar mappings (GraphQL only)
        // Values must be valid expressions for the configured validator
        scalars: {
          DateTime: "z.string()",  // Use z.coerce.date() for Date objects
          JSON: "z.unknown()",
          Cursor: "z.string()",
        },

        // TanStack DB overrides
        db: {
          collections: {
            // Key is the entity name (e.g., "User", "Post")
            User: {
              // Override the key field (default: auto-detected "id")
              keyField: "rowId",
              // Sync mode: "full" (default) or "on-demand"
              syncMode: "on-demand",
              // Predicate mapping preset for on-demand mode
              // Options: "hasura", "prisma", "rest-simple", "jsonapi"
              predicateMapping: "hasura",
              // Override selector path for extracting array from response
              // Use dot notation for nested paths
              selectorPath: "users.data",
            },
          },
        },

        // TanStack Form overrides
        form: {
          // Validator timing (default: "onSubmitAsync")
          // Options: "onChange", "onChangeAsync", "onBlur", "onBlurAsync",
          //          "onSubmit", "onSubmitAsync", "onDynamic"
          validator: "onDynamic",
          // Validation logic (only used with "onDynamic" validator)
          validationLogic: {
            // When to run initial validation: "change", "blur", "submit"
            mode: "submit",
            // When to revalidate after first submission
            modeAfterSubmission: "change",
          },
        },
      },
    },

    // ===================
    // OpenAPI Source
    // ===================
    {
      name: "api",
      type: "openapi",

      // OpenAPI spec - local file path or remote URL
      spec: "./openapi.yaml",
      // spec: "https://api.example.com/openapi.json",

      // Optional headers for fetching remote spec
      headers: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },

      // Optional path filtering with glob patterns
      include: ["/users/**", "/posts/**"],
      exclude: ["/internal/**", "/admin/**"],

      generates: ["query", "form"],

      overrides: {
        db: {
          collections: {
            Pet: {
              keyField: "petId",
              syncMode: "on-demand",
              predicateMapping: "rest-simple",
            },
          },
        },
        form: {
          validator: "onBlurAsync",
        },
      },
    },
  ],
})

// Use Zod (default)
export default defineConfig({
  validator: "zod",
  sources: [/* ... */],
})

// Use Valibot for smaller bundles
export default defineConfig({
  validator: "valibot",
  sources: [/* ... */],
})

// Use ArkType for type-first validation
export default defineConfig({
  validator: "arktype",
  sources: [/* ... */],
})

// Use Effect for the Effect ecosystem
export default defineConfig({
  validator: "effect",
  sources: [/* ... */],
})

generates: ["query"]              // Query only
generates: ["query", "form"]      // Query and Form
generates: ["db"]                 // DB (auto-enables Query)
generates: ["query", "form", "db"] // All three

overrides: {
  db: {
    collections: {
      EntityName: {
        keyField: "uuid",           // Override key field (default: auto-detected "id")
        syncMode: "on-demand",      // "full" (default) or "on-demand"
        predicateMapping: "hasura", // Preset for on-demand mode
        selectorPath: "data.items", // Path to extract array from response
      },
    },
  },
}

overrides: {
  form: {
    validator: "onDynamic",
    validationLogic: {
      mode: "submit",
      modeAfterSubmission: "change",
    },
  },
}

tangrams/
└── <source-name>/
    ├── client.ts          # API client (GraphQL or REST)
    ├── schema.ts          # Validation schemas + TypeScript types
    ├── functions.ts       # Standalone fetch functions
    ├── query/
    │   └── options.ts     # queryOptions, mutationOptions
    ├── form/
    │   └── options.ts     # formOptions
    └── db/
        └── collections.ts # TanStack DB collections

tangrams init [options]

Options:
  -f, --force    Overwrite existing config file
  -s, --skip     Skip interactive prompts and generate a template config

tangrams generate [options]

Options:
  -c, --config <path>    Path to config file
  -f, --force            Force regeneration of all files including client
  -w, --watch            Watch for file changes and regenerate
  --clean                Remove stale source directories from previous generations
  -y, --yes              Skip confirmation prompts (use with --clean)
  --env-file <path>      Path to env file (can be specified multiple times)
  --no-dotenv            Disable automatic .env file loading

# Remove stale artifacts (prompts for confirmation)
tangrams generate --clean

# Remove stale artifacts without prompting
tangrams generate --clean --yes