@vibeorm/dsl 0.3.0 → 2.0.0-alpha.1

package/README.md

@@ -1,523 +1,114 @@
 # @vibeorm/dsl
 
-TypeScript DSL for defining Prisma schemas programmatically. Define models, columns, relations, and enums in TypeScript and generate valid `.prisma` schema files.
+> Part of **[VibeORM](https://github.com/vibeorm/vibeorm)** — a type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
 
-## Install
+The code-first schema input: models and relations written in TypeScript, compiled straight to the canonical `SchemaIR`. It is the peer of the `.prisma` parser, and it also emits `.prisma` text for interop.
 
 ```bash
-bun add @vibeorm/dsl
+bun add @vibeorm/dsl@alpha
 ```
 
-## Quick Start
+> **Pre-release.** `2.0.0-alpha.x`, published under the `alpha` dist-tag. `npm i vibeorm` still resolves to the stable v1 line.
 
-```typescript
-import { dsl } from "@vibeorm/dsl";
-
-// Define models
-const Workspace = dsl.create({
-  name: "Workspace",
-  schema: {
-    ...dsl.templates.base,
-    name: dsl.string(),
-    slug: dsl.string().unique(),
-  },
-});
-
-const User = dsl.create({
-  name: "User",
-  schema: {
-    ...dsl.templates.base,
-    email: dsl.string().unique(),
-    workspaceId: dsl.string().index(),
-  },
-});
-
-// Define relations
-const relations = dsl.defineRelations({ Workspace, User }, (r) => ({
-  Workspace: {
-    users: r.many.User({
-      from: r.Workspace.id,
-      to: r.User.workspaceId,
-    }),
-  },
-  User: {
-    workspace: r.one.Workspace({
-      from: r.User.workspaceId,
-      to: r.Workspace.id,
-    }),
-  },
-}));
-
-// Assemble schema and generate
-const schema = dsl.schema({ Workspace, User }, { relations });
-const prismaOutput = dsl.generate.prisma(schema);
-```
-
-## Column Types
-
-Every column builder supports both **object syntax** and **chainable syntax**:
-
-```typescript
-// Object syntax
-dsl.string({ optional: true, unique: true, default: "hello" })
-
-// Chainable syntax (equivalent)
-dsl.string().optional().unique().default("hello")
-```
-
-### Available Types
-
-| Builder | Prisma Type | Notes |
-|---|---|---|
-| `dsl.string()` | `String` | `.maxLength(n)` for `@db.VarChar(n)`, `.text()` for `@db.Text` |
-| `dsl.int()` | `Int` | |
-| `dsl.bigint()` | `BigInt` | |
-| `dsl.float()` | `Float` | |
-| `dsl.decimal()` | `Decimal` | `.precision(p, s)` for `@db.Decimal(p, s)` |
-| `dsl.boolean()` | `Boolean` | |
-| `dsl.datetime()` | `DateTime` | `.defaultNow()`, `.updatedAt()`, `.tz()` for `@db.Timestamptz()` |
-| `dsl.json()` | `Json` | |
-| `dsl.id()` | `String`/`Int` | `.type("ulid" \| "cuid" \| "uuid" \| "autoincrement")` |
-| `dsl.bytes()` | `Bytes` | |
-| `dsl.unsupported("tsvector")` | `Unsupported("tsvector")` | For database-native types without Prisma mapping |
-
-### Common Modifiers
-
-All column types support these chainable methods:
-
-```typescript
-dsl.string()
-  .optional()                // Nullable (String?)
-  .unique()                  // @unique
-  .index()                   // @@index
-  .array()                   // String[]
-  .default("value")          // @default("value")
-  .map("db_column_name")     // @map("db_column_name")
-  .dbgenerated("expression") // @default(dbgenerated("expression"))
-  .comment("text")           // /// text (triple-slash comment above column)
-```
-
-### ID Types
-
-```typescript
-dsl.id()                   // String @id @default(ulid())  — default
-dsl.id().type("cuid")      // String @id @default(cuid())
-dsl.id().type("uuid")      // String @id @default(uuid())
-dsl.id().type("autoincrement") // Int @id @default(autoincrement())
-```
-
-### Datetime Shortcuts
-
-```typescript
-dsl.datetime().defaultNow()           // @default(now())
-dsl.datetime().updatedAt()            // @updatedAt
-dsl.datetime().tz()                   // @db.Timestamptz()
-dsl.datetime().defaultNow().updatedAt().tz() // All combined
-```
-
-## Enums
+Most users never install this directly — it ships as a dependency of [`vibeorm`](https://www.npmjs.com/package/vibeorm). Reach for it when you are building tooling on the IR or SQL layer.
 
-### Standalone Enums (Reusable)
+## Usage
 
-```typescript
-const UserRole = dsl.enum({
-  name: "UserRole",
-  options: ["admin", "user", "guest"],
-});
-
-const User = dsl.create({
-  name: "User",
-  schema: {
-    id: dsl.id(),
-    role: UserRole.field().default("user"),
-  },
-});
-```
-
-### Inline Enums (One-Off)
-
-Auto-named as `ModelNameColumnName`:
-
-```typescript
-const Project = dsl.create({
-  name: "Project",
-  schema: {
-    id: dsl.id(),
-    // Generates: enum ProjectStatus { active, archived, deleted }
-    status: dsl.enum({ options: ["active", "archived", "deleted"] }).default("active"),
-  },
-});
-```
-
-## Models
+```ts
+// src/schema.ts
+import { dsl } from "@vibeorm/dsl";
 
-### Basic Model
+const Role = dsl.enum({ name: "Role", options: ["USER", "ADMIN"] });
 
-```typescript
 const User = dsl.create({
   name: "User",
   schema: {
-    id: dsl.id(),
+    id: dsl.id({ type: "autoincrement" }),
+    createdAt: dsl.datetime().defaultNow(),
+    updatedAt: dsl.datetime().updatedAt(),
     email: dsl.string().unique(),
-    name: dsl.string(),
-    bio: dsl.string().optional(),
+    name: dsl.string().optional(),
+    role: Role.field({ default: "USER" }),
   },
 });
-```
-
-### With Indexes
-
-The `indexes` callback provides a type-safe index builder:
-
-```typescript
-const User = dsl.create({
-  name: "User",
-  schema: {
-    id: dsl.id(),
-    email: dsl.string().index(),       // Single-column: @@index([email])
-    organizationId: dsl.string().index(),
-  },
-  indexes: (i) => [
-    i.unique("organizationId", "email"),   // @@unique([organizationId, email])
-    i.gin("tags"),                         // @@index([tags], type: Gin)
-  ],
-});
-```
 
-### With Compound Primary Key
-
-```typescript
-const UserGroup = dsl.create({
-  name: "UserGroup",
+const Post = dsl.create({
+  name: "Post",
   schema: {
-    userId: dsl.string(),
-    groupId: dsl.string(),
-    joinedAt: dsl.datetime().defaultNow(),
+    id: dsl.id({ type: "uuid" }),
+    title: dsl.string(),
+    published: dsl.boolean().default(false),
+    meta: dsl.json().optional(),
+    authorId: dsl.int().index(),
   },
-  primaryKey: ["userId", "groupId"], // @@id([userId, groupId])
+  indexes: (i) => [i.unique("authorId", "title")],
 });
-```
 
-### With Table Mapping
-
-```typescript
-const User = dsl.create({
-  name: "User",
-  schema: {
-    id: dsl.id(),
-    firstName: dsl.string().map("first_name"),
-  },
-  map: "users", // @@map("users")
-});
-```
-
-### With Children (Inline Nested Models)
-
-Use a callback for `schema` to access the children builder:
-
-```typescript
-const Order = dsl.create({
-  name: "Order",
-  schema: (s) => ({
-    id: dsl.id(),
-    total: dsl.decimal(),
-    // Creates an OrderItem model with an auto-generated orderId FK
-    items: s.children({
-      name: "OrderItem",
-      schema: {
-        id: dsl.id(),
-        quantity: dsl.int(),
-        price: dsl.decimal(),
-      },
-    }),
-  }),
-});
-```
-
-## Relations
-
-Relations are defined separately from models using `dsl.defineRelations()`. This keeps models focused on columns and allows relations to reference each other.
-
-### One-to-Many
-
-```typescript
-const relations = dsl.defineRelations({ Workspace, User }, (r) => ({
-  Workspace: {
-    users: r.many.User({
-      from: r.Workspace.id,
-      to: r.User.workspaceId,
-    }),
-  },
-  User: {
-    workspace: r.one.Workspace({
-      from: r.User.workspaceId,
-      to: r.Workspace.id,
-    }),
-  },
+const relations = dsl.defineRelations({ User, Post }, (r) => ({
+  User: { posts: r.many.Post({ from: r.User.id, to: r.Post.authorId }) },
+  Post: { author: r.one.User({ from: r.Post.authorId, to: r.User.id, onDelete: "Cascade" }) },
 }));
-```
-
-### One-to-One
 
-When both sides define `r.one`, the generator merges them into a single Prisma relation. The side with the FK column becomes the owning side:
-
-```typescript
-const relations = dsl.defineRelations({ User, UserProfile }, (r) => ({
-  User: {
-    profile: r.one.UserProfile({
-      from: r.User.id,
-      to: r.UserProfile.userId,
-    }),
-  },
-  UserProfile: {
-    user: r.one.User({
-      from: r.UserProfile.userId,
-      to: r.User.id,
-      onDelete: "Cascade",
-    }),
-  },
-}));
+export const schema = dsl.schema({ Role, User, Post }, { relations });
+export default schema;
 ```
 
-Generates:
+Point `vibeorm.config.ts` at the `.ts` entry (`schema: "./src/schema.ts"`) and the CLI takes it from there. The module must export the composed schema as `default`, as `export const schema`, or as a `schema` property on the default export.
 
-```prisma
-model User {
-  // ...
-  Profile UserProfile?
-}
-
-model UserProfile {
-  // ...
-  User User @relation(fields: [userId], references: [id], onDelete: Cascade)
-}
-```
+To go to the IR yourself: `dsl.toIR({ schema })` returns a `SchemaIR`, optionally taking `provider` and an `extensions` registry. `dsl.validateSchema(schema)` returns `ValidationError[]` without throwing.
 
-### Self-Referential Relations
-
-Use `alias` to disambiguate when a model references itself:
-
-```typescript
-Task: {
-  parentTask: r.one.Task({
-    from: r.Task.parentTaskId,
-    to: r.Task.id,
-    optional: true,
-    alias: "TaskHierarchy",
-  }),
-  childTasks: r.many.Task({
-    from: r.Task.id,
-    to: r.Task.parentTaskId,
-    alias: "TaskHierarchy",
-  }),
-},
-```
+## Column factories
 
-### Multiple Relations to Same Model
-
-Use `alias` to distinguish different relations between the same models:
-
-```typescript
-Referral: {
-  referrer: r.one.User({
-    from: r.Referral.referrerId,
-    to: r.User.id,
-    alias: "ReferralReferrer",
-  }),
-  referredUser: r.one.User({
-    from: r.Referral.referredUserId,
-    to: r.User.id,
-    optional: true,
-    alias: "ReferralReferred",
-  }),
-},
-```
+`dsl.string()` · `dsl.int()` · `dsl.bigint()` · `dsl.float()` · `dsl.decimal()` · `dsl.boolean()` · `dsl.datetime()` · `dsl.json()` · `dsl.bytes()` · `dsl.id({ type })` · `dsl.unsupported("tsvector")` · `dsl.extensionType({ ... })` · `dsl.enum(...)`.
 
-### Optional Relations
+`dsl.enum` has two forms: with a `name` it creates a reusable enum whose `.field()` yields a column, without one it creates an inline single-use enum column.
 
-```typescript
-User: {
-  workspace: r.one.Workspace({
-    from: r.User.workspaceId,
-    to: r.Workspace.id,
-    optional: true,     // Workspace?
-  }),
-},
-```
+Id strategies are `dsl.id({ type: "ulid" | "uuid" | "cuid" | "nanoid" | "autoincrement" | "none" })`. The default is `"ulid"`, a `String` column generated in the app; `"autoincrement"` makes it an `Int`.
 
-### Cascade Actions
-
-```typescript
-UserProfile: {
-  user: r.one.User({
-    from: r.UserProfile.userId,
-    to: r.User.id,
-    onDelete: "Cascade",   // onDelete: Cascade
-    onUpdate: "Cascade",   // onUpdate: Cascade
-  }),
-},
-```
+## Chainable modifiers
 
-Supported actions: `"Cascade"`, `"SetNull"`, `"Restrict"`, `"NoAction"`, `"SetDefault"`.
+On every column: `.optional()`, `.unique()`, `.index()`, `.array()`, `.default(value)`, `.map("db_col")`, `.dbgenerated("expr")`, `.comment("...")`.
 
-### Splitting Relations Across Files
+Kind-specific: `.maxLength(n)` and `.text()` on strings, `.precision(p, s)` on decimals, `.defaultNow()`, `.updatedAt()` and `.tz()` on datetimes.
 
-For large schemas, split relation definitions with `defineRelationsPart` and `mergeRelations`:
+## Relations
 
-```typescript
-// file: user-relations.ts
-export const userRelations = dsl.defineRelationsPart({ User, Workspace }, (r) => ({
-  User: {
-    workspace: r.one.Workspace({
-      from: r.User.workspaceId,
-      to: r.Workspace.id,
-    }),
-  },
-}));
+Relations are declared separately from columns, in `dsl.defineRelations(models, (r) => ...)`, which keeps column references typed on both ends.
 
-// file: workspace-relations.ts
-export const workspaceRelations = dsl.defineRelationsPart({ User, Workspace }, (r) => ({
-  Workspace: {
-    users: r.many.User({
-      from: r.Workspace.id,
-      to: r.User.workspaceId,
-    }),
-  },
-}));
+- One side: `r.one.X({ from, to, optional?, alias?, onDelete?, onUpdate? })`.
+- Many side: `r.many.X({ from, to })`.
+- Implicit many-to-many: both sides `r.many`.
+- Explicit many-to-many, through a junction model: `r.many.Group({ from: r.User.id.through(r.UserGroup.userId), to: r.Group.id.through(r.UserGroup.groupId) })`.
+- Self-relations, and several relations between the same pair of models, disambiguate with `alias`.
 
-// file: schema.ts
-const relations = dsl.mergeRelations(userRelations, workspaceRelations);
-const schema = dsl.schema({ User, Workspace }, { relations });
-```
+Large schemas can split relations across files with `dsl.defineRelationsPart` and recombine them with `dsl.mergeRelations`; `dsl.domain({ name, models })` groups models.
 
 ## Templates
 
-Built-in field templates for common patterns. Templates use getters, so every spread produces fresh column instances (no shared mutable state):
+`dsl.templates.base` spreads `id`, `createdAt`, `updatedAt` and `deletedAt` into a model. Also available: `baseWithWorkspace`, `withAudit`, `withActive`, `withMetadata`, `withNameDescription`, `withExternalId`, and `fields`.
 
-```typescript
-const User = dsl.create({
-  name: "User",
-  schema: {
-    ...dsl.templates.base,           // id, createdAt, updatedAt, deletedAt
-    ...dsl.templates.withMetadata,    // metadata, settings (optional Json)
-    email: dsl.string().unique(),
-  },
+```ts
+const Workspace = dsl.create({
+  name: "Workspace",
+  schema: { ...dsl.templates.base, name: dsl.string() },
 });
 ```
 
-### Available Templates
-
-| Template | Fields |
-|---|---|
-| `dsl.templates.base` | `id` (ULID), `createdAt`, `updatedAt`, `deletedAt` (optional) |
-| `dsl.templates.baseWithWorkspace` | Same as `base` + `workspaceId` (indexed String) |
-| `dsl.templates.withMetadata` | `metadata`, `settings` (optional Json) |
-| `dsl.templates.withActive` | `isActive` (Boolean, default `true`) |
-| `dsl.templates.withAudit` | `createdById`, `updatedById` (optional, indexed) |
-| `dsl.templates.withExternalId` | `externalId` (indexed String) |
-| `dsl.templates.withNameDescription` | `name` (String), `description` (optional String) |
-
-Individual fields are also available via `dsl.templates.fields`:
-
-```typescript
-dsl.templates.fields.id          // ULID primary key
-dsl.templates.fields.datetime    // DateTime with now + updatedAt + tz
-dsl.templates.fields.title       // String
-dsl.templates.fields.description // Optional String
-dsl.templates.fields.metadata    // Optional Json
-dsl.templates.fields.settings    // Optional Json
-dsl.templates.fields.isActive    // Boolean default true
-dsl.templates.fields.externalId  // Indexed String
-```
-
-## Schema Assembly
+## Interop
 
-### Basic Schema
-
-```typescript
-const schema = dsl.schema({ User, Workspace }, { relations });
-```
-
-### With Standalone Enums
-
-Pass standalone enums alongside models:
-
-```typescript
-const UserRole = dsl.enum({ name: "UserRole", options: ["admin", "user"] });
-
-const schema = dsl.schema(
-  { UserRole, User, Workspace },
-  { relations }
-);
-```
-
-### Grouped by Domain
-
-```typescript
-const schema = dsl.schema({
-  UserRole,
-  User,
-  shipping: { Carrier, CarrierService },
-  printing: { PrintAccount, PrintJob },
-}, { relations });
-```
+`dsl.generate.prisma(schema)` renders the schema as `.prisma` text, and `dsl.generate(schema)` returns it as a `GeneratorOutput`. That is what backs the CLI's conversion in both directions:
 
-## Generating Prisma Output
-
-```typescript
-const schema = dsl.schema({ User, Workspace }, { relations });
-
-// Generate just the models + enums (no datasource/generator blocks)
-const prismaBody = dsl.generate.prisma(schema);
-```
-
-The output contains only model and enum definitions. Add your own datasource and generator blocks:
-
-```typescript
-import { writeFileSync } from "fs";
-
-const fullSchema = `datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
-
-generator client {
-  provider = "prisma-client"
-  output   = "../src/generated/prisma"
-}
-
-${prismaBody}
-`;
-
-writeFileSync("prisma/schema.prisma", fullSchema);
-```
-
-## Validation
-
-Check for common issues before generating:
-
-```typescript
-const errors = dsl.validateSchema(schema);
-
-for (const error of errors) {
-  console.log(`[${error.type}] ${error.model}: ${error.message}`);
-}
+```bash
+vibeorm convert --to dsl --out src/schema.ts              # .prisma → TS DSL
+vibeorm convert --to prisma --out prisma/schema.prisma    # TS DSL → .prisma
 ```
 
-Checks for:
-- Duplicate model/enum names
-- Missing FK columns referenced in relations
-- Self-referential relations without aliases
-- Models without an `id` column or compound `primaryKey`
-- Relations targeting non-existent models
-
-## Full Example
+Conversion goes through the IR and round-trips are tested: emitted DSL compiles back to the same IR. `convert --to dsl` refuses constructs the DSL cannot express — views, composite-column foreign keys, non-standard index kinds, enum `@@map` names, exotic `@db.*` types — with one `VIBE_CONFIG` error naming every offender.
 
-See `tests/fixtures/advanced-schema.ts` for a comprehensive 11-model schema covering:
+## Links
 
-- Standalone and inline enums
-- One-to-many, one-to-one, self-referential, and multi-FK relations
-- Many-to-many via junction table
-- Children (nested inline models)
-- Array columns, optional FKs, composite indexes
-- Relation aliases for disambiguation
+- [Documentation](https://github.com/vibeorm/vibeorm/tree/master/docs)
+- [Getting started](https://github.com/vibeorm/vibeorm/blob/master/docs/getting-started.md)
+- [CLI reference](https://github.com/vibeorm/vibeorm/blob/master/docs/cli.md)
+- [Repository and issues](https://github.com/vibeorm/vibeorm)
+- MIT licensed