@claudetools/tools 0.3.9 → 0.5.0

package/docs/ENTITY_DSL_REFERENCE.md

@@ -0,0 +1,685 @@
+# Entity DSL Reference
+
+Complete reference for CodeDNA's Entity DSL (Domain-Specific Language) for defining data models.
+
+## Table of Contents
+
+1. [Syntax Overview](#syntax-overview)
+2. [Field Types](#field-types)
+3. [Constraints](#constraints)
+4. [Relations](#relations)
+5. [Advanced Features](#advanced-features)
+6. [Examples](#examples)
+
+---
+
+## Syntax Overview
+
+### Basic Format
+
+```
+EntityName(field1:type:constraint, field2:type:constraint, ...)
+```
+
+### Rules
+
+- **Entity names** MUST start with uppercase letter (PascalCase)
+- **Field names** MUST start with lowercase letter or underscore (camelCase)
+- **Fields** are separated by commas
+- **Type** and **constraints** are separated by colons
+- Empty entities are allowed: `Entity()`
+
+---
+
+## Field Types
+
+### Primitive Types
+
+| Type | SQL Type | TypeScript Type | Description |
+|------|----------|-----------------|-------------|
+| `string` | VARCHAR(255) | string | Text string |
+| `integer` | INTEGER | number | Whole number |
+| `decimal` | DECIMAL(10,2) | number | Decimal number |
+| `boolean` | BOOLEAN | boolean | True/false |
+| `datetime` | TIMESTAMP | Date | Date and time |
+| `email` | VARCHAR(255) | string | Email address (validation built-in) |
+| `url` | VARCHAR(512) | string | URL (validation built-in) |
+| `json` | JSONB | any | JSON object |
+
+**Examples:**
+
+```
+User(name:string, age:integer, verified:boolean)
+Product(price:decimal, createdAt:datetime)
+Contact(email:email, website:url)
+Config(settings:json)
+```
+
+### Array Types
+
+Syntax: `array(itemType)`
+
+Supported item types: `string`, `integer`, `decimal`, `boolean`
+
+**Examples:**
+
+```
+Post(tags:array(string))
+Stats(scores:array(integer))
+Chart(values:array(decimal))
+Flags(options:array(boolean))
+```
+
+**Generated as:**
+- SQL: `TEXT[]`, `INTEGER[]`, etc. (PostgreSQL arrays)
+- TypeScript: `string[]`, `number[]`, etc.
+
+### Reference Types
+
+#### Simple Reference
+Syntax: `ref(EntityName)`
+
+Foreign key to another entity.
+
+**Example:**
+```
+Post(author:ref(User))
+```
+
+#### One-to-Many Reference
+Syntax: `refOne(EntityName)`
+
+Entity has one parent of this type (e.g., Post has one Author).
+
+**Example:**
+```
+Post(author:refOne(User))
+Comment(post:refOne(Post))
+```
+
+#### Many-to-Many Reference
+Syntax: `refMany(EntityName)`
+
+Entity can have many of this type and vice versa (e.g., Post has many Tags, Tag has many Posts).
+
+**Example:**
+```
+Post(tags:refMany(Tag))
+Student(courses:refMany(Course))
+```
+
+**Generated as:**
+- Simple/OneToMany: Foreign key column + index
+- ManyToMany: Junction table with composite primary key
+
+### Enum Types
+
+Syntax: `enum(value1,value2,value3)`
+
+Restricted set of allowed values.
+
+**Examples:**
+
+```
+Order(status:enum(pending,paid,shipped,cancelled))
+User(role:enum(admin,user,guest))
+```
+
+**Generated as:**
+- SQL: ENUM type
+- TypeScript: Union type (`'pending' | 'paid' | 'shipped' | 'cancelled'`)
+
+### Computed Fields
+
+Syntax: `computed(expression)`
+
+Virtual field calculated from other fields.
+
+**Examples:**
+
+```
+User(fullName:computed(firstName + lastName))
+Order(total:computed(price * quantity))
+Product(discountedPrice:computed(price * (1 - discount)))
+```
+
+**Generated as:**
+- SQL: GENERATED column or database trigger
+- TypeScript: Getter function
+
+---
+
+## Constraints
+
+### Simple Constraints
+
+No parameters, just add to field definition.
+
+| Constraint | Description | Example |
+|------------|-------------|---------|
+| `required` | NOT NULL | `email:string:required` |
+| `unique` | UNIQUE constraint | `email:string:unique` |
+| `index` | Database index | `username:string:index` |
+| `hashed` | Bcrypt hash before save | `password:string:hashed` |
+| `nullable` | Allows NULL | `middleName:string:nullable` |
+| `immutable` | Cannot be updated after creation | `id:integer:immutable` |
+| `email` | Email format validation | `contact:string:email` |
+| `url` | URL format validation | `homepage:string:url` |
+
+**Examples:**
+
+```
+User(email:email:unique:required, password:string:hashed:required)
+Post(slug:string:unique:index, deletedAt:datetime:nullable)
+Account(accountNumber:string:immutable:unique)
+```
+
+### Parameterized Constraints
+
+Constraints that take values.
+
+#### min(value)
+Minimum value for numbers, minimum length for strings.
+
+```
+User(age:integer:min(18))
+Product(price:decimal:min(0))
+```
+
+#### max(value)
+Maximum value for numbers, maximum length for strings.
+
+```
+Product(price:decimal:max(9999))
+Rating(stars:integer:max(5))
+```
+
+#### default(value)
+Default value for field.
+
+```
+User(role:enum(admin,user):default(user))
+Post(views:integer:default(0))
+Product(inStock:boolean:default(true))
+```
+
+#### length(max) or length(min,max)
+String length constraints.
+
+```
+User(username:string:length(20))
+User(password:string:length(8,100))
+Bio(text:string:length(10,500))
+```
+
+**Generates:**
+- SQL: CHECK constraint
+- TypeScript: Runtime validation
+- Frontend: Input maxLength/minLength
+
+#### pattern(regex)
+Regular expression validation.
+
+Regex can be provided with or without slashes.
+
+```
+User(zipCode:string:pattern(/^\d{5}$/))
+Product(sku:string:pattern(^[A-Z]{3}-\d{4}$))
+User(phone:string:pattern(/^\+1\d{10}$/))
+```
+
+**Generates:**
+- SQL: CHECK constraint (where supported)
+- TypeScript: RegExp test
+- Frontend: Input pattern attribute
+
+---
+
+## Relations
+
+### Simple Foreign Key
+
+Use `ref(Entity)` for a basic foreign key relationship.
+
+```
+Post(author:ref(User))
+```
+
+**Generates:**
+- SQL: `author_id INTEGER REFERENCES users(id)`
+- TypeScript: `author: User` or `authorId: number`
+
+### One-to-Many
+
+Use `refOne(Entity)` when entity has ONE parent.
+
+```
+Comment(post:refOne(Post), author:refOne(User))
+```
+
+**Real-world meaning:**
+- Each Comment belongs to ONE Post
+- Each Comment belongs to ONE User (author)
+- But Post can have MANY Comments
+- User can have MANY Comments
+
+**Generates:**
+- Foreign key with index
+- Cascade delete options
+- TypeScript navigation properties
+
+### Many-to-Many
+
+Use `refMany(Entity)` for many-to-many relationships.
+
+```
+Post(tags:refMany(Tag))
+Student(courses:refMany(Course))
+```
+
+**Real-world meaning:**
+- Each Post can have MANY Tags
+- Each Tag can belong to MANY Posts
+- Each Student can have MANY Courses
+- Each Course can have MANY Students
+
+**Generates:**
+- Junction table (e.g., `post_tags`)
+- Composite primary key
+- Foreign keys to both entities
+- TypeScript: `tags: Tag[]`
+
+---
+
+## Advanced Features
+
+### Self-Referencing Entities
+
+Entity can reference itself for hierarchical data.
+
+```
+Category(parent:ref(Category))
+Comment(replyTo:ref(Comment))
+```
+
+**Generates:**
+- Self-referential foreign key
+- Allows NULL for root items
+- Query methods for hierarchy traversal
+
+### Multiple Constraints
+
+Chain multiple constraints for complex validation.
+
+```
+User(
+  email:email:unique:required:email,
+  password:string:hashed:required:length(8,100):pattern(/^(?=.*[A-Z])(?=.*[0-9])/),
+  age:integer:required:min(18):max(120)
+)
+```
+
+### Complex Field Example
+
+```
+Product(
+  name:string:required:length(3,100),
+  slug:string:unique:index:pattern(/^[a-z0-9-]+$/),
+  price:decimal:required:min(0):max(999999),
+  category:refOne(Category),
+  tags:refMany(Tag),
+  inStock:boolean:default(true),
+  metadata:json:nullable
+)
+```
+
+---
+
+## Examples
+
+### Blog Platform
+
+```
+User(
+  email:email:unique:required,
+  username:string:unique:required:length(3,20):pattern(/^[a-zA-Z0-9_]+$/),
+  password:string:hashed:required:length(8,100),
+  bio:string:length(10,500):nullable,
+  website:url:url:nullable,
+  role:enum(admin,editor,author,reader):default(reader),
+  createdAt:datetime:required
+)
+
+Post(
+  title:string:required:length(3,200),
+  slug:string:unique:required:index:pattern(/^[a-z0-9-]+$/),
+  content:string:required,
+  excerpt:string:length(10,500):nullable,
+  author:refOne(User),
+  category:refOne(Category),
+  tags:refMany(Tag),
+  status:enum(draft,published,archived):default(draft),
+  publishedAt:datetime:nullable,
+  viewCount:integer:default(0),
+  createdAt:datetime:required,
+  updatedAt:datetime:required
+)
+
+Category(
+  name:string:unique:required:length(2,50),
+  slug:string:unique:required:index,
+  description:string:nullable,
+  parent:ref(Category)
+)
+
+Tag(
+  name:string:unique:required:length(2,30),
+  slug:string:unique:required:index
+)
+
+Comment(
+  content:string:required:length(1,1000),
+  author:refOne(User),
+  post:refOne(Post),
+  replyTo:ref(Comment),
+  status:enum(pending,approved,spam):default(pending),
+  createdAt:datetime:required
+)
+```
+
+### E-Commerce Store
+
+```
+Product(
+  name:string:required:length(3,200),
+  sku:string:unique:required:index:pattern(/^[A-Z]{3}-\d{6}$/),
+  description:string:required,
+  price:decimal:required:min(0):max(999999.99),
+  compareAtPrice:decimal:min(0):nullable,
+  cost:decimal:min(0):nullable,
+  stock:integer:min(0):default(0),
+  category:refOne(Category),
+  tags:refMany(Tag),
+  images:array(string),
+  metadata:json:nullable,
+  status:enum(active,inactive,discontinued):default(active),
+  createdAt:datetime:required,
+  updatedAt:datetime:required
+)
+
+Order(
+  orderNumber:string:unique:required:immutable:pattern(/^ORD-\d{8}$/),
+  customer:refOne(User),
+  items:refMany(Product),
+  subtotal:decimal:required:min(0),
+  tax:decimal:required:min(0),
+  shipping:decimal:required:min(0),
+  total:computed(subtotal + tax + shipping),
+  status:enum(pending,paid,processing,shipped,delivered,cancelled):default(pending),
+  shippingAddress:json:required,
+  billingAddress:json:required,
+  createdAt:datetime:required,
+  updatedAt:datetime:required
+)
+
+Customer(
+  email:email:unique:required,
+  firstName:string:required:length(2,50),
+  lastName:string:required:length(2,50),
+  fullName:computed(firstName + lastName),
+  phone:string:pattern(/^\+1\d{10}$/):nullable,
+  addresses:json:nullable,
+  createdAt:datetime:required
+)
+```
+
+### SaaS Application
+
+```
+Organization(
+  name:string:required:unique:length(2,100),
+  slug:string:unique:required:index:pattern(/^[a-z0-9-]+$/),
+  plan:enum(free,starter,pro,enterprise):default(free),
+  settings:json:nullable,
+  createdAt:datetime:required
+)
+
+User(
+  email:email:unique:required,
+  password:string:hashed:required:length(8,100),
+  firstName:string:required:length(2,50),
+  lastName:string:required:length(2,50),
+  organization:refOne(Organization),
+  role:enum(owner,admin,member,guest):default(member),
+  permissions:array(string),
+  avatar:url:url:nullable,
+  lastLoginAt:datetime:nullable,
+  createdAt:datetime:required
+)
+
+Project(
+  name:string:required:length(2,100),
+  description:string:nullable,
+  organization:refOne(Organization),
+  owner:refOne(User),
+  members:refMany(User),
+  status:enum(active,archived,deleted):default(active),
+  settings:json:nullable,
+  createdAt:datetime:required
+)
+
+Task(
+  title:string:required:length(3,200),
+  description:string:nullable,
+  project:refOne(Project),
+  assignee:refOne(User),
+  status:enum(todo,in_progress,review,done):default(todo),
+  priority:enum(low,medium,high,critical):default(medium),
+  dueDate:datetime:nullable,
+  completedAt:datetime:nullable,
+  createdAt:datetime:required
+)
+```
+
+---
+
+## TypeScript Type Generation
+
+The DSL generates TypeScript types automatically:
+
+### Input DSL:
+
+```
+User(
+  email:email:unique:required,
+  age:integer:min(18):nullable,
+  roles:array(string),
+  organization:refOne(Organization),
+  tags:refMany(Tag)
+)
+```
+
+### Generated TypeScript:
+
+```typescript
+interface User {
+  id: number;
+  email: string;
+  age: number | null;
+  roles: string[];
+  organizationId: number;
+  organization?: Organization;
+  tags?: Tag[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+---
+
+## SQL Schema Generation
+
+### Input DSL:
+
+```
+Product(
+  name:string:required:length(3,200),
+  price:decimal:required:min(0),
+  stock:integer:min(0):default(0),
+  status:enum(active,inactive):default(active)
+)
+```
+
+### Generated SQL (PostgreSQL):
+
+```sql
+CREATE TYPE product_status AS ENUM ('active', 'inactive');
+
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(200) NOT NULL CHECK (LENGTH(name) >= 3),
+  price DECIMAL(10,2) NOT NULL CHECK (price >= 0),
+  stock INTEGER DEFAULT 0 CHECK (stock >= 0),
+  status product_status DEFAULT 'active',
+  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+```
+
+---
+
+## Best Practices
+
+### 1. Use Semantic Field Types
+
+Prefer `email` and `url` types over generic `string` when applicable.
+
+❌ BAD:
+```
+User(email:string:required)
+```
+
+✅ GOOD:
+```
+User(email:email:required)
+```
+
+### 2. Add Validation Constraints
+
+Use `length`, `pattern`, `min`, `max` for data integrity.
+
+❌ BAD:
+```
+User(username:string)
+```
+
+✅ GOOD:
+```
+User(username:string:required:length(3,20):pattern(/^[a-zA-Z0-9_]+$/))
+```
+
+### 3. Use Appropriate Relation Types
+
+Choose `ref`, `refOne`, or `refMany` based on cardinality.
+
+❌ BAD (ambiguous):
+```
+Post(author:ref(User), tags:ref(Tag))
+```
+
+✅ GOOD (explicit):
+```
+Post(author:refOne(User), tags:refMany(Tag))
+```
+
+### 4. Add Indexes for Lookups
+
+Use `:index` on fields used in WHERE clauses.
+
+```
+User(email:email:unique:index, username:string:unique:index)
+```
+
+### 5. Use Computed Fields for Derived Data
+
+Don't store data that can be calculated.
+
+❌ BAD:
+```
+Order(subtotal:decimal, tax:decimal, shipping:decimal, total:decimal)
+```
+
+✅ GOOD:
+```
+Order(subtotal:decimal, tax:decimal, shipping:decimal, total:computed(subtotal + tax + shipping))
+```
+
+---
+
+## Migration from v0.3.x
+
+If you're upgrading from CodeDNA v0.3.x:
+
+### Breaking Changes
+
+None! All v0.3.x syntax remains valid.
+
+### New Features Available
+
+| Feature | Old Syntax | New Syntax |
+|---------|-----------|-----------|
+| Email | `email:string` | `email:email` |
+| URL | `website:string` | `website:url` |
+| JSON | N/A | `settings:json` |
+| Arrays | N/A | `tags:array(string)` |
+| One-to-Many | `author:ref(User)` | `author:refOne(User)` (more explicit) |
+| Many-to-Many | N/A | `tags:refMany(Tag)` |
+| Computed | N/A | `total:computed(price * qty)` |
+| Length | N/A | `name:string:length(3,100)` |
+| Pattern | N/A | `code:string:pattern(/^[A-Z]+$/)` |
+| Nullable | N/A | `middleName:string:nullable` |
+| Immutable | N/A | `id:integer:immutable` |
+
+---
+
+## Cheat Sheet
+
+### Quick Reference
+
+```
+# Primitive Types
+string, integer, decimal, boolean, datetime, email, url, json
+
+# Array Types
+array(string), array(integer), array(decimal), array(boolean)
+
+# Reference Types
+ref(Entity)       # Simple foreign key
+refOne(Entity)    # One-to-many (this entity has one parent)
+refMany(Entity)   # Many-to-many (bidirectional)
+
+# Enum
+enum(val1,val2,val3)
+
+# Computed
+computed(expression)
+
+# Simple Constraints
+required, unique, index, hashed, nullable, immutable, email, url
+
+# Parameterized Constraints
+min(value)                # Minimum value/length
+max(value)                # Maximum value/length
+default(value)            # Default value
+length(max)               # Max length
+length(min,max)           # Min and max length
+pattern(regex)            # Regex validation
+```
+
+---
+
+## Support
+
+For questions, issues, or feature requests:
+- GitHub: [claudetools/tools](https://github.com/claudetools/tools)
+- Documentation: [CodeDNA Docs](https://docs.claudetools.dev/codedna)