# @datafn/cli CLI tools and TypeScript code generation for DataFn. Generates Drizzle ORM schema definitions and typed interfaces from DataFn schemas. ## Installation ```bash npm install @datafn/cli ``` ## Features | Feature | Description | |---------|-------------| | **Schema Generation** | Generate Drizzle ORM schema (pgTable, mysqlTable, sqliteTable) from DataFn schema | | **Type Generation** | Generate TypeScript interfaces, `Tables` map, and `TypedClient` from DataFn schema | | **Multi-Database** | PostgreSQL, MySQL, SQLite — each with dialect-specific Drizzle column types | | **CLI Interface** | `npx @datafn/cli generate` command for schema + type generation | --- ## CLI Usage ### generate Generate Drizzle ORM schema and TypeScript type definitions from a DataFn schema. ```bash # Auto-discover schema file npx @datafn/cli generate --adapter drizzle --database postgres # Explicit schema file npx @datafn/cli generate --adapter drizzle --database postgres --schema ./schema.datafn.ts # Custom output directory npx @datafn/cli generate --adapter drizzle --database postgres --output ./src/db/ ``` #### Options | Option | Description | Default | |--------|-------------|---------| | `--adapter ` | ORM adapter (currently only `drizzle` supported) | Required | | `--database ` | Database dialect: `postgres`, `mysql`, `sqlite` | Required | | `--schema ` | Schema file (`.json` or `.ts`). Auto-discovers if omitted | Auto-discover | | `--output ` | Output directory for generated files | `./` | | `-h, --help` | Show help | — | #### Output Files The `generate` command produces two files in the output directory: 1. **`datafn-schema.drizzle.ts`** — Drizzle ORM table definitions 2. **`datafn-types.ts`** — TypeScript type definitions #### Example Output: Drizzle Schema (PostgreSQL) Given this DataFn schema: ```typescript // schema.datafn.ts export default { resources: [ { name: 'task', version: 1, fields: [ { name: 'id', type: 'string', required: true }, { name: 'title', type: 'string', required: true }, { name: 'done', type: 'boolean', required: false, default: false }, { name: 'createdAt', type: 'date', required: true }, ], indices: { base: ['createdAt'] }, }, ], relations: [], }; ``` The generated `datafn-schema.drizzle.ts` will be: ```typescript // Generated by @datafn/cli. DO NOT EDIT. // Database: postgres import { pgTable, text, boolean, bigint, index } from "drizzle-orm/pg-core"; export const task = pgTable("task", { createdAt: bigint("created_at", { mode: "number" }).notNull(), done: boolean("done").default(false), id: text("id").primaryKey(), title: text("title").notNull(), }, (table) => [ index("task_created_at_idx").on(table.createdAt), ]); export const schema = { task }; ``` #### Auto-Discovery When `--schema` is omitted, the CLI searches for schema files in this order: 1. `./schema.datafn.ts` 2. `./src/schema.datafn.ts` 3. `./schema.json` 4. `./src/schema.json` --- ## Production Workflow The recommended workflow for DataFn with generated schemas: ### 1. Define Your Schema Write your DataFn schema as the single source of truth: ```typescript // schema.datafn.ts import type { DatafnSchema } from '@datafn/core'; export default { resources: [ { name: 'user', version: 1, fields: [ { name: 'id', type: 'string', required: true }, { name: 'email', type: 'string', required: true, unique: true }, { name: 'name', type: 'string', required: true }, ], }, ], relations: [], } satisfies DatafnSchema; ``` ### 2. Generate ORM Schema + Types ```bash datafn generate --adapter drizzle --database postgres ``` This creates: - `./datafn-schema.drizzle.ts` — Drizzle table definitions - `./datafn-types.ts` — TypeScript interfaces ### 3. Generate Migrations Use your ORM's native migration tools: ```bash # Drizzle drizzle-kit generate drizzle-kit migrate ``` ### 4. Use Generated Schema in Your App ```typescript import { drizzle } from 'drizzle-orm/node-postgres'; import { schema } from './datafn-schema.drizzle'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL }); const db = drizzle(pool, { schema }); // Schema is now registered with Drizzle ``` ### 5. Create DataFn Server ```typescript import { createDatafnServer } from '@datafn/server'; import { drizzleAdapter } from '@superfunctions/db/adapters'; import { schema as datafnSchema } from './schema.datafn'; const server = await createDatafnServer({ schema: datafnSchema, db: drizzleAdapter({ db, dialect: "postgres", }), }); ``` **Important**: When upgrading to a new version of DataFn with schema changes, always: 1. Run `datafn generate` to update schema files 2. Run ORM migration tools to apply database changes 3. Deploy updated code --- ## TypeScript Schema Support ### Overview The DataFn CLI supports TypeScript schema files for a better developer experience with type safety and IDE autocomplete. ### Convention: `.datafn.ts` Extension Explicit `--schema` paths accept any `.ts` file. Use the `.datafn.ts` extension for auto-discovery and to make schema files easy to identify: ```typescript // schema.datafn.ts import type { DatafnSchema } from '@datafn/core'; export default { resources: [ { name: 'task', version: 1, fields: [ { name: 'id', type: 'string', required: true }, { name: 'title', type: 'string', required: true }, { name: 'done', type: 'boolean', required: false }, ], }, ], relations: [], } satisfies DatafnSchema; ``` **Why `.datafn.ts`?** - Auto-discovery: Only conventional `.datafn.ts` paths are searched automatically - Clarity: Signals that the file contains a DataFn schema - Convention: Similar to `*.config.ts`, `*.spec.ts`, etc. ### Auto-Discovery When you run `datafn generate` without the `--schema` flag, the CLI automatically searches for schema files in this order: 1. `./schema.datafn.ts` (current directory) 2. `./src/schema.datafn.ts` (source directory) 3. `./schema.json` (JSON schema file) 4. `./src/schema.json` (JSON schema file in src) The first file found is used. ### Export Formats Your `.datafn.ts` file must export the schema in one of these ways: **Default export (recommended):** ```typescript export default { resources: [...], relations: [...] }; ``` **Named export:** ```typescript export const schema = { resources: [...], relations: [...] }; ``` ### Security Best Practices ⚠️ **Important**: `.datafn.ts` files are executed during import. Follow these guidelines: **✅ Do:** - Define schema as a plain object literal - Import types from `@datafn/core` - Use simple object/array compositions **❌ Don't:** - Make network requests - Perform file system operations - Execute side effects in module scope - Import runtime dependencies unnecessarily **Good Example:** ```typescript import type { DatafnSchema } from '@datafn/core'; export default { resources: [/* ... */], relations: [], } satisfies DatafnSchema; ``` **Bad Example:** ```typescript import axios from 'axios'; // ❌ Runtime dependency const data = await axios.get('/api/schema'); // ❌ Side effect export default data.schema; ``` ### Migrating from JSON to TypeScript To convert an existing JSON schema to TypeScript: 1. Rename `schema.json` to `schema.datafn.ts` 2. Add type import: `import type { DatafnSchema } from '@datafn/core';` 3. Add export: `export default` before the schema object 4. Add type annotation: `satisfies DatafnSchema` after the object 5. Remove quotes from unquoted JSON keys if desired **Before (schema.json):** ```json { "resources": [ { "name": "task", "version": 1, "fields": [...] } ], "relations": [] } ``` **After (schema.datafn.ts):** ```typescript import type { DatafnSchema } from '@datafn/core'; export default { resources: [ { name: 'task', version: 1, fields: [...] } ], relations: [] } satisfies DatafnSchema; ``` ### Troubleshooting **Error: "Invalid schema file extension"** - Cause: Trying to use `.ts` file without `.datafn.` convention - Solution: Rename to `*.datafn.ts` **Error: "No schema export found"** - Cause: File doesn't export schema - Solution: Add `export default { ... }` or `export const schema = { ... }` **Error: "Failed to load TypeScript schema" (Node.js)** - Cause: `tsx` package not installed - Solution: Run `npm install tsx --save-dev` or use Bun **Types don't match expectations** - Cause: Schema validation failed - Solution: Check console output for validation errors from `validateSchema()` ### Runtime Requirements - **Bun**: Native TypeScript support (no additional deps) - **Node.js**: Requires `tsx` package (`npm install tsx --save-dev`) --- ## Programmatic API ### generateTypes(schema): string Generate TypeScript definitions from a DataFn schema. The schema is validated first; invalid schemas throw a `DatafnError`. ```typescript import { generateTypes } from "@datafn/cli"; const code = generateTypes({ resources: [ { name: "task", version: 1, fields: [ { name: "id", type: "string", required: true, unique: true }, { name: "title", type: "string", required: true }, { name: "done", type: "boolean", required: false }, { name: "priority", type: "number", required: false }, { name: "dueDate", type: "date", required: false }, { name: "metadata", type: "object", required: false }, { name: "tags", type: "array", required: false }, ], }, { name: "project", version: 1, fields: [ { name: "id", type: "string", required: true, unique: true }, { name: "name", type: "string", required: true }, ], }, ], }); console.log(code); ``` **Generated output:** ```typescript import type { DatafnClient, DatafnTable } from "@datafn/client"; export interface Project { id: string; name: string; } export interface Task { done?: boolean; dueDate?: number; id: string; metadata?: Record; priority?: number; tags?: unknown[]; title: string; } export interface Tables { project: Project; task: Task; } export type TypedClient = DatafnClient & { project: DatafnTable; task: DatafnTable; }; ``` **Type mapping:** | DataFn Type | TypeScript Type | |-------------|----------------| | `string` | `string` | | `number` | `number` | | `boolean` | `boolean` | | `object` | `Record` | | `array` | `unknown[]` | | `date` | `number` (timestamp) | | `file` | `string` (URL or ID) | Resources and fields are sorted alphabetically for deterministic output. --- ### generateDrizzleSchema(schema, dialect): string Generate Drizzle ORM table definitions from a DataFn schema. ```typescript import { generateDrizzleSchema } from "@datafn/cli"; const code = generateDrizzleSchema( { resources: [ { name: "task", version: 1, fields: [ { name: "id", type: "string", required: true }, { name: "title", type: "string", required: true }, { name: "done", type: "boolean", default: false }, { name: "createdAt", type: "date", required: true }, ], indices: { base: ["createdAt"] }, }, ], relations: [], }, "postgres" ); console.log(code); ``` **Generated output:** ```typescript // Generated by @datafn/cli. DO NOT EDIT. // Database: postgres import { pgTable, text, boolean, bigint, index } from "drizzle-orm/pg-core"; export const task = pgTable("task", { createdAt: bigint("created_at", { mode: "number" }).notNull(), done: boolean("done").default(false), id: text("id").primaryKey(), title: text("title").notNull(), }, (table) => [ index("task_created_at_idx").on(table.createdAt), ]); export const schema = { task }; ``` **Supported dialects:** - `"postgres"` — PostgreSQL (pgTable) - `"mysql"` — MySQL (mysqlTable) - `"sqlite"` — SQLite (sqliteTable) **Type mapping:** **PostgreSQL:** | DataFn Type | Drizzle Column | |-------------|---------------| | `string` | `text("field")` | | `number` | `numeric("field")` | | `boolean` | `boolean("field")` | | `date` | `bigint("field", { mode: "number" })` | | `object` | `jsonb("field")` | | `array` | `jsonb("field")` | | `file` | `text("field")` | **MySQL:** | DataFn Type | Drizzle Column | |-------------|---------------| | `string` | `text("field")` | | `number` | `int("field")` | | `boolean` | `boolean("field")` | | `date` | `bigint("field", { mode: "number" })` | | `object` | `json("field")` | | `array` | `json("field")` | | `file` | `text("field")` | **SQLite:** | DataFn Type | Drizzle Column | |-------------|---------------| | `string` | `text("field")` | | `number` | `integer("field")` | | `boolean` | `integer("field")` | | `date` | `integer("field")` | | `object` | `text("field")` | | `array` | `text("field")` | | `file` | `text("field")` | **Features:** - Automatic `id` field detection (`.primaryKey()`) - Field modifiers: `.notNull()`, `.unique()`, `.default(value)` - Index generation from `indices.base` - Join table generation for many-many relations - camelCase → snake_case column naming --- ## Exports ```typescript // Schema generation export { generateDrizzleSchema } // Type generation export { generateTypes } // Types export type { DatafnSchema } from '@datafn/core' ``` ## License MIT