@vibeorm/dsl 0.2.0

package/README.md

@@ -0,0 +1,523 @@
+# @vibeorm/dsl
+
+TypeScript DSL for defining Prisma schemas programmatically. Define models, columns, relations, and enums in TypeScript and generate valid `.prisma` schema files.
+
+## Install
+
+```bash
+bun add @vibeorm/dsl
+```
+
+## Quick Start
+
+```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
+
+### Standalone Enums (Reusable)
+
+```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
+
+### Basic Model
+
+```typescript
+const User = dsl.create({
+  name: "User",
+  schema: {
+    id: dsl.id(),
+    email: dsl.string().unique(),
+    name: dsl.string(),
+    bio: dsl.string().optional(),
+  },
+});
+```
+
+### 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",
+  schema: {
+    userId: dsl.string(),
+    groupId: dsl.string(),
+    joinedAt: dsl.datetime().defaultNow(),
+  },
+  primaryKey: ["userId", "groupId"], // @@id([userId, groupId])
+});
+```
+
+### 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,
+    }),
+  },
+}));
+```
+
+### 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",
+    }),
+  },
+}));
+```
+
+Generates:
+
+```prisma
+model User {
+  // ...
+  Profile UserProfile?
+}
+
+model UserProfile {
+  // ...
+  User User @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+```
+
+### 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",
+  }),
+},
+```
+
+### 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",
+  }),
+},
+```
+
+### Optional Relations
+
+```typescript
+User: {
+  workspace: r.one.Workspace({
+    from: r.User.workspaceId,
+    to: r.Workspace.id,
+    optional: true,     // Workspace?
+  }),
+},
+```
+
+### Cascade Actions
+
+```typescript
+UserProfile: {
+  user: r.one.User({
+    from: r.UserProfile.userId,
+    to: r.User.id,
+    onDelete: "Cascade",   // onDelete: Cascade
+    onUpdate: "Cascade",   // onUpdate: Cascade
+  }),
+},
+```
+
+Supported actions: `"Cascade"`, `"SetNull"`, `"Restrict"`, `"NoAction"`, `"SetDefault"`.
+
+### Splitting Relations Across Files
+
+For large schemas, split relation definitions with `defineRelationsPart` and `mergeRelations`:
+
+```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,
+    }),
+  },
+}));
+
+// 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,
+    }),
+  },
+}));
+
+// file: schema.ts
+const relations = dsl.mergeRelations(userRelations, workspaceRelations);
+const schema = dsl.schema({ User, Workspace }, { relations });
+```
+
+## Templates
+
+Built-in field templates for common patterns. Templates use getters, so every spread produces fresh column instances (no shared mutable state):
+
+```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(),
+  },
+});
+```
+
+### 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
+
+### 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 });
+```
+
+## 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}`);
+}
+```
+
+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
+
+See `tests/fixtures/advanced-schema.ts` for a comprehensive 11-model schema covering:
+
+- 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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vibeorm/dsl",
+  "version": "0.2.0",
+  "description": "TypeScript DSL for defining Prisma schemas with type-safe models, relations, and templates",
+  "license": "MIT",
+  "keywords": [
+    "orm",
+    "dsl",
+    "prisma",
+    "schema",
+    "typescript",
+    "codegen",
+    "postgresql"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeorm/vibeorm.git",
+    "directory": "packages/dsl"
+  },
+  "homepage": "https://github.com/vibeorm/vibeorm",
+  "bugs": {
+    "url": "https://github.com/vibeorm/vibeorm/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prisma": "^7.3.0",
+    "typescript": "^5.9.3"
+  }
+}