@doviui/dev-db 0.2.1 → 0.4.0

package/README.md

@@ -15,6 +15,7 @@ dev-db eliminates the friction of setting up databases during development. Defin
 ## Key Features
 
 - **Type-Safe Schema Definition** - Fluent TypeScript API with full IntelliSense support
+- **TypeScript Types Generation** - Auto-generate type definitions from schemas for type-safe data consumption
 - **Automatic Relationship Resolution** - Foreign keys handled intelligently with topological sorting
 - **Production-Quality Mock Data** - Powered by Faker.js for realistic, diverse datasets
 - **Built-In Validation** - Detect circular dependencies, missing tables, and constraint conflicts before generation
@@ -145,12 +146,73 @@ function getPostsByUserId(userId: number) {
 app.get('/users/:id', (req, res) => {
   const user = getUserById(parseInt(req.params.id))
   if (!user) return res.status(404).json({ error: 'User not found' })
-  
+
   const userPosts = getPostsByUserId(user.id)
   res.json({ ...user, posts: userPosts })
 })
 ```
 
+### Type-Safe Data Consumption
+
+Generate TypeScript type definitions from your schemas for full type safety when consuming the mock data:
+
+```bash
+# Generate types alongside JSON data
+bunx @doviui/dev-db schema.ts --types
+```
+
+This creates a `types.ts` file with interfaces matching your schema:
+
+```typescript
+// mock-data/types.ts (auto-generated)
+export interface User {
+  id: number;
+  username: string;
+  email: string;
+  age: number | null;
+  created_at?: string;
+}
+
+export interface Post {
+  id: number;
+  user_id: number;  // Correctly typed based on User.id
+  title: string;
+  content: string | null;
+  created_at?: string;
+}
+```
+
+Import and use the types in your application:
+
+```typescript
+// server.ts
+import users from './mock-data/User.json'
+import posts from './mock-data/Post.json'
+import type { User, Post } from './mock-data/types'
+
+// Fully type-safe!
+function getUserById(id: number): User | undefined {
+  return users.find(u => u.id === id)
+}
+
+function getPostsByUserId(userId: number): Post[] {
+  return posts.filter(p => p.user_id === userId)
+}
+```
+
+**Programmatic API:**
+
+```typescript
+import { TypesGenerator } from '@doviui/dev-db'
+
+const typesGenerator = new TypesGenerator(schema, {
+  outputDir: './mock-data',
+  fileName: 'types.ts'  // Optional, defaults to 'types.ts'
+})
+
+await typesGenerator.generate()
+```
+
 ## API Reference
 
 ### Data Types
@@ -189,13 +251,27 @@ t.timestamptz()  // Date and time with timezone
 ```typescript
 t.boolean()      // True/false
 t.uuid()         // UUID v4
-t.json()         // JSON object
-t.jsonb()        // JSON binary
+
+// JSON types with optional structured schemas
+t.json()         // JSON object (unstructured)
+t.jsonb()        // JSON binary (unstructured)
+
+// Structured JSON with type-safe schema
+t.json({
+  id: t.integer(),
+  name: t.varchar(100),
+  preferences: t.json({
+    theme: t.varchar(20),
+    notifications: t.boolean()
+  })
+})
 ```
 
 #### Relationships
 ```typescript
-t.foreignKey('TableName', 'column')  // Foreign key reference
+t.foreignKey('TableName', 'column')           // Foreign key reference
+t.belongsTo('TableName', 'foreignKeyField')   // Many-to-one relationship
+t.hasMany('TableName', 'foreignKeyField', { min: 1, max: 5 })  // One-to-many relationship (virtual)
 ```
 
 ### Field Modifiers
@@ -227,6 +303,81 @@ Chain modifiers to configure field behavior and constraints:
 
 ## Advanced Usage
 
+### hasMany and belongsTo Relationships
+
+For clearer relationship semantics and automatic record count calculation, use `hasMany()` and `belongsTo()` helpers:
+
+```typescript
+import { t } from '@doviui/dev-db'
+
+export default {
+  User: {
+    $count: 100,
+    id: t.bigserial().primaryKey(),
+    username: t.varchar(50).unique().generate('internet.userName'),
+
+    // Define one-to-many: each user has 2-5 posts
+    posts: t.hasMany('Post', 'userId', { min: 2, max: 5 })
+  },
+
+  Post: {
+    // $count is automatically calculated: 100 users * avg(2,5) posts = 350 posts
+    id: t.bigserial().primaryKey(),
+    userId: t.integer(),  // The actual foreign key field
+
+    // Define many-to-one for clearer intent
+    author: t.belongsTo('User', 'userId'),
+
+    title: t.varchar(200).generate('lorem.sentence'),
+    content: t.text().generate('lorem.paragraphs')
+  }
+}
+```
+
+**Key Benefits:**
+
+- **Auto-calculated counts**: `hasMany` automatically calculates child table record counts based on parent count and min/max constraints
+- **Clearer intent**: `belongsTo` makes many-to-one relationships more explicit than raw `foreignKey`
+- **Virtual fields**: Both `hasMany` and `belongsTo` fields don't appear in generated output—they're metadata for generation logic
+
+**How it works:**
+
+1. `hasMany('Post', 'userId', { min: 2, max: 5 })` tells the generator: "Each User should have between 2-5 Posts"
+2. The generator calculates: `100 users * average(2, 5) = 100 * 3.5 = 350 posts`
+3. `belongsTo('User', 'userId')` instructs the generator to populate the `userId` field with valid User IDs
+4. Neither `posts` nor `author` appear in the generated JSON—only the actual data fields
+
+**Complex Example:**
+
+```typescript
+export default {
+  Author: {
+    $count: 50,
+    id: t.uuid().primaryKey(),
+    name: t.varchar(100).generate('person.fullName'),
+    articles: t.hasMany('Article', 'authorId', { min: 3, max: 10 })
+  },
+
+  Article: {
+    // Auto-calculated: 50 * 6.5 = 325 articles
+    id: t.bigserial().primaryKey(),
+    authorId: t.varchar(36),  // UUID foreign key
+    author: t.belongsTo('Author', 'authorId'),
+    title: t.varchar(200),
+
+    comments: t.hasMany('Comment', 'articleId', { min: 0, max: 20 })
+  },
+
+  Comment: {
+    // Auto-calculated: 325 * 10 = 3,250 comments
+    id: t.bigserial().primaryKey(),
+    articleId: t.integer(),
+    article: t.belongsTo('Article', 'articleId'),
+    content: t.text()
+  }
+}
+```
+
 ### Multi-Table Schemas
 
 You can organize schemas in two ways:
@@ -332,6 +483,95 @@ Schema validation failed:
   Post.user_id: Foreign key references non-existent table 'User'
 ```
 
+### Structured JSON Fields
+
+Define type-safe JSON schemas for complex nested data structures. This generates proper TypeScript types instead of `any`, and creates realistic structured data:
+
+```typescript
+import { t } from '@doviui/dev-db'
+
+export default {
+  User: {
+    $count: 100,
+    id: t.bigserial().primaryKey(),
+    email: t.varchar(255).unique().notNull(),
+
+    // Structured JSON field with nested schema
+    profile: t.json({
+      firstName: t.varchar(50).generate('person.firstName'),
+      lastName: t.varchar(50).generate('person.lastName'),
+      age: t.integer().min(18).max(90),
+
+      // Deeply nested structures
+      preferences: t.json({
+        theme: t.varchar(20).enum(['light', 'dark', 'auto']).default('auto'),
+        notifications: t.json({
+          email: t.boolean().default(true),
+          push: t.boolean().default(false),
+          frequency: t.varchar(20).enum(['realtime', 'daily', 'weekly'])
+        })
+      })
+    }),
+
+    // Simple unstructured JSON (fallback)
+    metadata: t.jsonb()
+  }
+}
+```
+
+**Generated TypeScript types:**
+
+```typescript
+// mock-data/types.ts
+export interface User {
+  id: number;
+  email: string;
+  profile: {
+    firstName: string;
+    lastName: string;
+    age: number;
+    preferences: {
+      theme?: string;  // Optional because it has a default
+      notifications: {
+        email?: boolean;
+        push?: boolean;
+        frequency: string;
+      };
+    };
+  };
+  metadata: any;  // Unstructured JSON falls back to 'any'
+}
+```
+
+**Generated JSON data:**
+
+```json
+{
+  "id": 1,
+  "email": "john@example.com",
+  "profile": {
+    "firstName": "John",
+    "lastName": "Doe",
+    "age": 34,
+    "preferences": {
+      "theme": "dark",
+      "notifications": {
+        "email": true,
+        "push": false,
+        "frequency": "daily"
+      }
+    }
+  },
+  "metadata": { "data": "sample" }
+}
+```
+
+**Benefits:**
+- ✅ Full TypeScript type safety for nested JSON structures
+- ✅ All field modifiers work (`.nullable()`, `.default()`, `.enum()`, `.generate()`, etc.)
+- ✅ Supports unlimited nesting depth
+- ✅ Works with both `t.json()` and `t.jsonb()`
+
 ### Custom Data Generators
 
 Leverage any [Faker.js](https://fakerjs.dev/) method for realistic data generation:
@@ -370,6 +610,7 @@ Arguments:
 Options:
   -o, --output <dir>     Output directory for generated JSON files (default: ./mock-data)
   -s, --seed <number>    Random seed for reproducible data generation
+  -t, --types            Generate TypeScript type definitions alongside JSON
   -h, --help             Show help message
 ```
 
@@ -388,8 +629,11 @@ bunx @doviui/dev-db ./schemas -o ./data
 # Reproducible generation with seed
 bunx @doviui/dev-db schema.ts -s 42
 
+# Generate TypeScript types
+bunx @doviui/dev-db schema.ts --types
+
 # All options combined
-bunx @doviui/dev-db ./schemas --output ./database --seed 12345
+bunx @doviui/dev-db ./schemas --output ./database --seed 12345 --types
 ```
 
 **Schema File Format:**
@@ -488,9 +732,12 @@ export default {
     first_name: t.varchar(50).generate('person.firstName'),
     last_name: t.varchar(50).generate('person.lastName'),
     phone: t.varchar(20).generate('phone.number'),
-    created_at: t.timestamptz().default('now')
+    created_at: t.timestamptz().default('now'),
+
+    // Each customer has 1-5 orders
+    orders: t.hasMany('Order', 'customerId', { min: 1, max: 5 })
   },
-  
+
   Product: {
     $count: 100,
     id: t.bigserial().primaryKey(),
@@ -500,21 +747,27 @@ export default {
     stock: t.integer().min(0).max(1000),
     category: t.varchar(50).enum(['electronics', 'clothing', 'home', 'books'])
   },
-  
+
   Order: {
-    $count: 500,
+    // Auto-calculated: 200 * 3 = 600 orders
     id: t.bigserial().primaryKey(),
-    customer_id: t.foreignKey('Customer', 'id').notNull(),
+    customerId: t.varchar(36),
+    customer: t.belongsTo('Customer', 'customerId'),
     status: t.varchar(20).enum(['pending', 'processing', 'shipped', 'delivered']),
     total: t.decimal(10, 2).min(10).max(10000),
-    created_at: t.timestamptz().default('now')
+    created_at: t.timestamptz().default('now'),
+
+    // Each order has 1-4 items
+    items: t.hasMany('OrderItem', 'orderId', { min: 1, max: 4 })
   },
-  
+
   OrderItem: {
-    $count: 1500,
+    // Auto-calculated: 600 * 2.5 = 1,500 items
     id: t.bigserial().primaryKey(),
-    order_id: t.foreignKey('Order', 'id').notNull(),
-    product_id: t.foreignKey('Product', 'id').notNull(),
+    orderId: t.integer(),
+    order: t.belongsTo('Order', 'orderId'),
+    productId: t.integer(),
+    product: t.belongsTo('Product', 'productId'),
     quantity: t.integer().min(1).max(10),
     price: t.decimal(10, 2)
   }
@@ -534,13 +787,17 @@ export default {
     username: t.varchar(50).unique().generate('internet.userName'),
     email: t.varchar(255).unique().generate('internet.email'),
     bio: t.text().generate('lorem.paragraph'),
-    avatar_url: t.varchar(500).generate('image.avatar')
+    avatar_url: t.varchar(500).generate('image.avatar'),
+
+    // Each author has 3-10 articles
+    articles: t.hasMany('Article', 'authorId', { min: 3, max: 10 })
   },
-  
+
   Article: {
-    $count: 300,
+    // Auto-calculated: 50 * 6.5 = 325 articles
     id: t.bigserial().primaryKey(),
-    author_id: t.foreignKey('Author', 'id'),
+    authorId: t.varchar(36),
+    author: t.belongsTo('Author', 'authorId'),
     title: t.varchar(200).generate('lorem.sentence'),
     slug: t.varchar(200).unique().generate('lorem.slug'),
     content: t.text().generate('lorem.paragraphs', 5),
@@ -549,17 +806,19 @@ export default {
     published_at: t.timestamptz().nullable(),
     created_at: t.timestamptz().default('now')
   },
-  
+
   Tag: {
     $count: 30,
     id: t.serial().primaryKey(),
     name: t.varchar(50).unique().generate('lorem.word')
   },
-  
+
   ArticleTag: {
     $count: 800,
-    article_id: t.foreignKey('Article', 'id'),
-    tag_id: t.foreignKey('Tag', 'id')
+    articleId: t.integer(),
+    article: t.belongsTo('Article', 'articleId'),
+    tagId: t.integer(),
+    tag: t.belongsTo('Tag', 'tagId')
   }
 }
 ```

package/cli.ts

@@ -6,6 +6,7 @@
 
 import { MockDataGenerator } from './src/generator';
 import { SchemaValidator } from './src/validator';
+import { TypesGenerator } from './src/types-generator';
 import type { Schema } from './src/types';
 import { readdirSync, statSync } from 'fs';
 import { join, extname, resolve } from 'path';
@@ -22,6 +23,7 @@ ARGUMENTS:
 OPTIONS:
   -o, --output <dir>     Output directory for generated JSON files (default: ./mock-data)
   -s, --seed <number>    Random seed for reproducible data generation
+  -t, --types            Generate TypeScript type definitions alongside JSON
   -h, --help             Show this help message
 
 EXAMPLES:
@@ -29,6 +31,7 @@ EXAMPLES:
   dev-db ./schemas
   dev-db schema.ts -o ./data -s 42
   dev-db ./schemas --output ./database --seed 12345
+  dev-db schema.ts --types
 
 SCHEMA FILE FORMAT:
   Schema files must export a default object or named 'schema' export:
@@ -53,12 +56,14 @@ interface CLIOptions {
   schemaPath?: string;
   outputDir: string;
   seed?: number;
+  generateTypes: boolean;
   help: boolean;
 }
 
 function parseArgs(args: string[]): CLIOptions {
   const options: CLIOptions = {
     outputDir: './mock-data',
+    generateTypes: false,
     help: false,
   };
 
@@ -74,6 +79,8 @@ function parseArgs(args: string[]): CLIOptions {
     } else if (arg === '-s' || arg === '--seed') {
       const nextArg = args[++i];
       if (nextArg !== undefined) options.seed = parseInt(nextArg, 10);
+    } else if (arg === '-t' || arg === '--types') {
+      options.generateTypes = true;
     } else if (!arg.startsWith('-')) {
       options.schemaPath = arg;
     }
@@ -189,6 +196,17 @@ async function main() {
     await generator.generate();
 
     console.log(`Generated mock data in: ${absoluteOutputDir}`);
+
+    // Generate TypeScript types if requested
+    if (options.generateTypes) {
+      const typesGenerator = new TypesGenerator(schema, {
+        outputDir: absoluteOutputDir,
+      });
+
+      await typesGenerator.generate();
+
+      console.log(`Generated TypeScript types in: ${absoluteOutputDir}/types.ts`);
+    }
   } catch (error) {
     console.error('Error:', error instanceof Error ? error.message : error);
     process.exit(1);

package/index.ts

@@ -34,6 +34,8 @@
 export { t } from './src/schema-builder';
 export { MockDataGenerator } from './src/generator';
 export { SchemaValidator } from './src/validator';
+export { TypesGenerator } from './src/types-generator';
 export type { Schema, TableConfig, FieldConfig, Generator } from './src/types';
 export type { ValidationError } from './src/validator';
 export type { GeneratorOptions } from './src/generator';
+export type { TypesGeneratorOptions } from './src/types-generator';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doviui/dev-db",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "TypeScript-first mock database generator for rapid application development",
   "main": "index.ts",
   "module": "index.ts",

package/src/field-builder.ts

@@ -1,5 +1,5 @@
 import type { Faker } from '@faker-js/faker';
-import type { FieldConfig, FieldBuilderLike } from './types';
+import type { FieldConfig, FieldBuilderLike, JsonSchema } from './types';
 
 export type Generator = string | ((faker: Faker) => any);
 
@@ -160,6 +160,29 @@ export class FieldBuilder implements FieldBuilderLike {
     return this;
   }
 
+  /**
+   * Sets a nested schema for JSON/JSONB fields.
+   * Defines the structure and types of properties within the JSON object.
+   *
+   * @param schema - The JSON schema defining nested fields
+   * @returns The builder instance for chaining
+   *
+   * @example
+   * ```typescript
+   * t.json({
+   *   userId: t.integer(),
+   *   preferences: t.json({
+   *     theme: t.varchar(20),
+   *     notifications: t.boolean()
+   *   })
+   * })
+   * ```
+   */
+  withJsonSchema(schema: JsonSchema): this {
+    this.config.jsonSchema = schema;
+    return this;
+  }
+
   /**
    * Converts the builder to a plain FieldConfig object.
    *
@@ -186,3 +209,44 @@ export class ForeignKeyBuilder extends FieldBuilder {
     this.config.foreignKey = { table, column };
   }
 }
+
+/**
+ * Builder class for belongsTo relationships.
+ * Alias for ForeignKeyBuilder with clearer intent for many-to-one relationships.
+ */
+export class BelongsToBuilder extends FieldBuilder {
+  /**
+   * Creates a new belongsTo relationship builder.
+   *
+   * @param table - The referenced table name
+   * @param foreignKey - The foreign key field name in the current table
+   */
+  constructor(table: string, foreignKey: string) {
+    super('belongsTo');
+    this.config.belongsTo = { table, foreignKey };
+  }
+}
+
+/**
+ * Builder class for hasMany relationships.
+ * Defines one-to-many relationships. This is a virtual field that doesn't appear in output
+ * but controls how related records are generated.
+ */
+export class HasManyBuilder extends FieldBuilder {
+  /**
+   * Creates a new hasMany relationship builder.
+   *
+   * @param table - The related table name
+   * @param foreignKey - The foreign key field name in the related table
+   * @param options - Min/max constraints for how many related records to generate
+   */
+  constructor(table: string, foreignKey: string, options?: { min?: number; max?: number }) {
+    super('hasMany');
+    this.config.hasMany = {
+      table,
+      foreignKey,
+      min: options?.min,
+      max: options?.max
+    };
+  }
+}

package/src/generator.ts

@@ -79,6 +79,9 @@ export class MockDataGenerator {
    * ```
    */
   async generate(): Promise<GeneratedData> {
+    // Calculate record counts based on hasMany relationships
+    this.calculateRecordCounts();
+
     // Topologically sort tables based on foreign key dependencies
     const sortedTables = this.topologicalSort();
 
@@ -98,6 +101,34 @@ export class MockDataGenerator {
     return this.generatedData;
   }
 
+  /**
+   * Calculates record counts for tables based on hasMany relationships.
+   * If a parent table has a hasMany relationship, it overrides the child table's $count.
+   */
+  private calculateRecordCounts(): void {
+    for (const [tableName, tableConfig] of Object.entries(this.schema)) {
+      const fields = Object.entries(tableConfig).filter(([key]) => key !== '$count');
+
+      for (const [_, field] of fields) {
+        const fieldConfig = this.toFieldConfig(field);
+
+        if (fieldConfig?.hasMany) {
+          const { table: relatedTable, min = 1, max = 5 } = fieldConfig.hasMany;
+          const parentCount = tableConfig.$count || 10;
+
+          // Calculate child count: average of min/max per parent * parent count
+          const avgPerParent = (min + max) / 2;
+          const calculatedCount = Math.ceil(parentCount * avgPerParent);
+
+          // Override the related table's $count
+          if (this.schema[relatedTable]) {
+            this.schema[relatedTable].$count = calculatedCount;
+          }
+        }
+      }
+    }
+  }
+
   private topologicalSort(): string[] {
     const tables = Object.keys(this.schema);
     const visited = new Set<string>();
@@ -115,12 +146,22 @@ export class MockDataGenerator {
       // Visit dependencies first
       for (const [_, field] of fields) {
         const fieldConfig = this.toFieldConfig(field);
+
+        // Handle foreignKey dependencies
         if (fieldConfig?.foreignKey) {
           const refTable = fieldConfig.foreignKey.table;
           if (refTable !== tableName) { // Avoid self-references
             visit(refTable);
           }
         }
+
+        // Handle belongsTo dependencies
+        if (fieldConfig?.belongsTo) {
+          const refTable = fieldConfig.belongsTo.table;
+          if (refTable !== tableName) { // Avoid self-references
+            visit(refTable);
+          }
+        }
       }
 
       result.push(tableName);
@@ -144,6 +185,11 @@ export class MockDataGenerator {
       for (const [fieldName, field] of fields) {
         const fieldConfig = this.toFieldConfig(field);
         if (fieldConfig) {
+          // Skip hasMany and belongsTo fields (they're virtual and don't appear in output)
+          if (fieldConfig.hasMany || fieldConfig.belongsTo) {
+            continue;
+          }
+
           record[fieldName] = this.generateFieldValue(
             fieldName,
             fieldConfig,
@@ -186,6 +232,22 @@ export class MockDataGenerator {
       return fieldConfig.default;
     }
 
+    // Check if this field is a foreign key in a belongsTo relationship
+    const belongsToRelationship = this.findBelongsToForField(tableName, fieldName);
+    if (belongsToRelationship) {
+      const refTable = belongsToRelationship.table;
+      const refData = this.generatedData[refTable];
+
+      if (!refData || refData.length === 0) {
+        if (fieldConfig.nullable) return null;
+        throw new Error(`Cannot generate belongsTo for ${tableName}.${fieldName}: no data in ${refTable}`);
+      }
+
+      const randomRecord = refData[Math.floor(Math.random() * refData.length)];
+      // Get the primary key value from the referenced table
+      return randomRecord.id || randomRecord[Object.keys(randomRecord)[0]];
+    }
+
     // Handle foreign keys
     if (fieldConfig.foreignKey) {
       const refTable = fieldConfig.foreignKey.table;
@@ -206,12 +268,13 @@ export class MockDataGenerator {
       return index + 1;
     }
 
-    // Handle nullable fields (but not if they have enum, min/max constraints, or custom generators)
+    // Handle nullable fields (but not if they have enum, min/max constraints, custom generators, or JSON schemas)
     if (
       fieldConfig.nullable &&
       !fieldConfig.notNull &&
       !fieldConfig.enum &&
       !fieldConfig.generator &&
+      !fieldConfig.jsonSchema &&
       fieldConfig.min === undefined &&
       fieldConfig.max === undefined &&
       Math.random() < 0.1
@@ -249,6 +312,25 @@ export class MockDataGenerator {
     return value;
   }
 
+  /**
+   * Finds a belongsTo relationship that references the given field name.
+   */
+  private findBelongsToForField(tableName: string, fieldName: string): { table: string; foreignKey: string } | null {
+    const tableConfig = this.schema[tableName];
+    if (!tableConfig) return null;
+
+    const fields = Object.entries(tableConfig).filter(([key]) => key !== '$count');
+
+    for (const [_, field] of fields) {
+      const fieldConfig = this.toFieldConfig(field);
+      if (fieldConfig?.belongsTo && fieldConfig.belongsTo.foreignKey === fieldName) {
+        return fieldConfig.belongsTo;
+      }
+    }
+
+    return null;
+  }
+
   private generateValueByType(fieldConfig: FieldConfig): any {
     // Use custom generator if provided
     if (fieldConfig.generator) {
@@ -309,6 +391,11 @@ export class MockDataGenerator {
 
       case 'json':
       case 'jsonb':
+        // If there's a nested schema, generate structured data
+        if (fieldConfig.jsonSchema) {
+          return this.generateJsonFromSchema(fieldConfig.jsonSchema);
+        }
+        // Otherwise, generate a simple object with sample data
         return { data: faker.lorem.word() };
 
       default:
@@ -334,6 +421,21 @@ export class MockDataGenerator {
     return current;
   }
 
+  private generateJsonFromSchema(jsonSchema: any): any {
+    const result: any = {};
+
+    for (const [fieldName, field] of Object.entries(jsonSchema)) {
+      const fieldConfig = this.toFieldConfig(field);
+      if (!fieldConfig) continue;
+
+      // Generate value based on field config
+      // Note: We don't track unique values for nested JSON fields
+      result[fieldName] = this.generateValueByType(fieldConfig);
+    }
+
+    return result;
+  }
+
   private async writeDataToFiles(): Promise<void> {
     const outputDir = this.options.outputDir ?? './mock-data';
 

package/src/schema-builder.ts

@@ -1,4 +1,5 @@
-import { FieldBuilder, ForeignKeyBuilder } from './field-builder';
+import { FieldBuilder, ForeignKeyBuilder, BelongsToBuilder, HasManyBuilder } from './field-builder';
+import type { JsonSchema } from './types';
 
 /**
  * Type builder API for defining database schemas with a fluent interface.
@@ -183,19 +184,55 @@ export const t = {
 
   /**
    * Creates a JSON field for storing structured data.
+   * @param schema - Optional nested schema defining the JSON structure
    * @returns FieldBuilder instance for method chaining
+   * @example
+   * ```typescript
+   * // Simple JSON field
+   * t.json()
+   *
+   * // Structured JSON field with schema
+   * t.json({
+   *   id: t.integer(),
+   *   preferences: t.json({
+   *     dark: t.boolean()
+   *   })
+   * })
+   * ```
    */
-  json(): FieldBuilder {
-    return new FieldBuilder('json');
+  json(schema?: JsonSchema): FieldBuilder {
+    const builder = new FieldBuilder('json');
+    if (schema) {
+      builder.withJsonSchema(schema);
+    }
+    return builder;
   },
 
   /**
    * Creates a binary JSON field (JSONB).
    * More efficient for querying than regular JSON.
+   * @param schema - Optional nested schema defining the JSON structure
    * @returns FieldBuilder instance for method chaining
+   * @example
+   * ```typescript
+   * // Simple JSONB field
+   * t.jsonb()
+   *
+   * // Structured JSONB field with schema
+   * t.jsonb({
+   *   userId: t.integer(),
+   *   metadata: t.json({
+   *     tags: t.varchar(255)
+   *   })
+   * })
+   * ```
    */
-  jsonb(): FieldBuilder {
-    return new FieldBuilder('jsonb');
+  jsonb(schema?: JsonSchema): FieldBuilder {
+    const builder = new FieldBuilder('jsonb');
+    if (schema) {
+      builder.withJsonSchema(schema);
+    }
+    return builder;
   },
 
   // Relationships
@@ -210,4 +247,42 @@ export const t = {
   foreignKey(table: string, column: string): ForeignKeyBuilder {
     return new ForeignKeyBuilder(table, column);
   },
+
+  /**
+   * Creates a belongsTo relationship (many-to-one).
+   * This is an alias for foreignKey with clearer intent.
+   * @param table - The referenced table name
+   * @param foreignKey - The foreign key field name in the current table
+   * @returns BelongsToBuilder instance for method chaining
+   * @example
+   * ```typescript
+   * Post: {
+   *   userId: t.belongsTo('User', 'userId')
+   * }
+   * ```
+   */
+  belongsTo(table: string, foreignKey: string): BelongsToBuilder {
+    return new BelongsToBuilder(table, foreignKey);
+  },
+
+  /**
+   * Creates a hasMany relationship (one-to-many).
+   * This is a virtual field that controls generation of related records.
+   * It does not appear in the generated output.
+   * @param table - The related table name
+   * @param foreignKey - The foreign key field name in the related table
+   * @param options - Min/max constraints for number of related records
+   * @returns HasManyBuilder instance for method chaining
+   * @example
+   * ```typescript
+   * User: {
+   *   $count: 100,
+   *   id: t.bigserial().primaryKey(),
+   *   posts: t.hasMany('Post', 'userId', { min: 2, max: 10 })
+   * }
+   * ```
+   */
+  hasMany(table: string, foreignKey: string, options?: { min?: number; max?: number }): HasManyBuilder {
+    return new HasManyBuilder(table, foreignKey, options);
+  },
 };

package/src/types-generator.ts

@@ -0,0 +1,250 @@
+import type { Schema, FieldConfig, TableConfig } from './types';
+
+/**
+ * Options for configuring the TypeScript types generator.
+ */
+export interface TypesGeneratorOptions {
+  /** Directory where the types file will be saved (default: './mock-data') */
+  outputDir?: string;
+
+  /** Name of the generated types file (default: 'types.ts') */
+  fileName?: string;
+}
+
+/**
+ * Generates TypeScript type definitions from dev-db schemas.
+ *
+ * Features:
+ * - Converts field types to TypeScript types
+ * - Handles nullable and optional fields
+ * - Generates interfaces for each table
+ * - Creates a single types file for easy importing
+ *
+ * @example
+ * ```typescript
+ * const generator = new TypesGenerator(schema, {
+ *   outputDir: './mock-data',
+ *   fileName: 'types.ts'
+ * });
+ *
+ * await generator.generate();
+ * // Creates ./mock-data/types.ts with all interfaces
+ * ```
+ */
+export class TypesGenerator {
+  private schema: Schema;
+  private options: TypesGeneratorOptions;
+
+  /**
+   * Creates a new TypeScript types generator.
+   *
+   * @param schema - The schema definition
+   * @param options - Generator options
+   */
+  constructor(schema: Schema, options: TypesGeneratorOptions = {}) {
+    this.schema = schema;
+    this.options = {
+      outputDir: options.outputDir || './mock-data',
+      fileName: options.fileName || 'types.ts',
+    };
+  }
+
+  /**
+   * Generates TypeScript type definitions for all tables in the schema.
+   *
+   * Creates a single .ts file with interface definitions that match
+   * the structure of the generated JSON data.
+   *
+   * @returns Promise resolving when the types file is written
+   *
+   * @example
+   * ```typescript
+   * await generator.generate();
+   * // Creates ./mock-data/types.ts
+   * ```
+   */
+  async generate(): Promise<void> {
+    const interfaces: string[] = [];
+
+    // Generate interface for each table
+    for (const [tableName, tableConfig] of Object.entries(this.schema)) {
+      const interfaceCode = this.generateInterface(tableName, tableConfig);
+      interfaces.push(interfaceCode);
+    }
+
+    // Combine all interfaces into a single file
+    const fileContent = interfaces.join('\n\n');
+
+    // Write to file
+    const outputPath = `${this.options.outputDir}/${this.options.fileName}`;
+    await Bun.write(outputPath, fileContent);
+  }
+
+  private generateInterface(tableName: string, tableConfig: TableConfig): string {
+    const fields: string[] = [];
+
+    // Process each field
+    for (const [fieldName, field] of Object.entries(tableConfig)) {
+      // Skip the $count property
+      if (fieldName === '$count') continue;
+
+      const fieldConfig = this.toFieldConfig(field);
+      if (!fieldConfig) continue;
+
+      const fieldDeclaration = this.generateFieldDeclaration(fieldName, fieldConfig);
+      fields.push(`  ${fieldDeclaration};`);
+    }
+
+    // Generate interface
+    return `export interface ${tableName} {\n${fields.join('\n')}\n}`;
+  }
+
+  private generateFieldDeclaration(fieldName: string, fieldConfig: FieldConfig): string {
+    const tsType = this.mapFieldTypeToTypeScript(fieldConfig);
+    const isOptional = this.isFieldOptional(fieldConfig);
+    const isNullable = this.isFieldNullable(fieldConfig);
+
+    let declaration = fieldName;
+
+    // Add optional marker if needed
+    if (isOptional) {
+      declaration += '?';
+    }
+
+    declaration += ': ';
+
+    // Add type
+    declaration += tsType;
+
+    // Add null union if nullable (but only if not already optional with a default)
+    if (isNullable && !(isOptional && fieldConfig.default !== undefined)) {
+      declaration += ' | null';
+    }
+
+    return declaration;
+  }
+
+  private mapFieldTypeToTypeScript(fieldConfig: FieldConfig): string {
+    // Handle foreign keys by looking up the referenced column type
+    if (fieldConfig.foreignKey) {
+      const refTable = fieldConfig.foreignKey.table;
+      const refColumn = fieldConfig.foreignKey.column;
+
+      const refTableConfig = this.schema[refTable];
+      if (refTableConfig) {
+        const refFieldConfig = this.toFieldConfig(refTableConfig[refColumn]);
+        if (refFieldConfig) {
+          return this.mapBasicTypeToTypeScript(refFieldConfig.type);
+        }
+      }
+
+      // Fallback if reference not found
+      return 'any';
+    }
+
+    // Handle JSON/JSONB with nested schema
+    if ((fieldConfig.type === 'json' || fieldConfig.type === 'jsonb') && fieldConfig.jsonSchema) {
+      return this.generateJsonSchemaType(fieldConfig.jsonSchema);
+    }
+
+    return this.mapBasicTypeToTypeScript(fieldConfig.type);
+  }
+
+  private generateJsonSchemaType(jsonSchema: any): string {
+    const fields: string[] = [];
+
+    for (const [fieldName, field] of Object.entries(jsonSchema)) {
+      const fieldConfig = this.toFieldConfig(field);
+      if (!fieldConfig) continue;
+
+      const tsType = this.mapFieldTypeToTypeScript(fieldConfig);
+      const isNullable = this.isFieldNullable(fieldConfig);
+      const isOptional = this.isFieldOptional(fieldConfig);
+
+      let declaration = `${fieldName}`;
+
+      if (isOptional) {
+        declaration += '?';
+      }
+
+      declaration += `: ${tsType}`;
+
+      if (isNullable && !(isOptional && fieldConfig.default !== undefined)) {
+        declaration += ' | null';
+      }
+
+      fields.push(`    ${declaration}`);
+    }
+
+    return `{\n${fields.join(';\n')}${fields.length > 0 ? ';' : ''}\n  }`;
+  }
+
+  private mapBasicTypeToTypeScript(type: string): string {
+    switch (type) {
+      case 'bigint':
+      case 'bigserial':
+      case 'integer':
+      case 'smallint':
+      case 'serial':
+      case 'decimal':
+      case 'numeric':
+      case 'real':
+      case 'double':
+        return 'number';
+
+      case 'varchar':
+      case 'char':
+      case 'text':
+      case 'uuid':
+        return 'string';
+
+      case 'boolean':
+        return 'boolean';
+
+      case 'date':
+      case 'time':
+      case 'timestamp':
+      case 'timestamptz':
+        return 'string'; // ISO format strings
+
+      case 'json':
+      case 'jsonb':
+        return 'any'; // Could be `object` or a generic type parameter in the future
+
+      default:
+        return 'any';
+    }
+  }
+
+  private isFieldOptional(fieldConfig: FieldConfig): boolean {
+    // A field is optional if it has a default value
+    // This means it doesn't need to be provided when creating the object
+    return fieldConfig.default !== undefined;
+  }
+
+  private isFieldNullable(fieldConfig: FieldConfig): boolean {
+    // A field can be null if:
+    // - Explicitly marked as nullable AND not marked as notNull
+    if (fieldConfig.notNull) return false;
+    if (fieldConfig.nullable === true) return true;
+
+    // Fields with defaults are not nullable unless explicitly set
+    if (fieldConfig.default !== undefined) return false;
+
+    // Primary keys are not nullable
+    if (fieldConfig.primaryKey) return false;
+
+    return false; // Default to not nullable unless explicitly set
+  }
+
+  private toFieldConfig(field: any): FieldConfig | null {
+    if (!field) return null;
+    if (typeof field === 'object' && 'toConfig' in field) {
+      return field.toConfig();
+    }
+    if (typeof field === 'object' && 'type' in field) {
+      return field;
+    }
+    return null;
+  }
+}

package/src/types.ts

@@ -57,8 +57,24 @@ export interface FieldConfig {
   /** Foreign key reference to another table */
   foreignKey?: { table: string; column: string };
 
+  /** One-to-many relationship definition (virtual field, not in output) */
+  hasMany?: { table: string; foreignKey: string; min?: number; max?: number };
+
+  /** Many-to-one relationship definition (alias for foreignKey with clearer intent) */
+  belongsTo?: { table: string; foreignKey: string };
+
   /** Custom generator function or Faker.js method path */
   generator?: Generator;
+
+  /** Nested JSON schema for json/jsonb types */
+  jsonSchema?: JsonSchema;
+}
+
+/**
+ * Schema definition for JSON fields, mapping property names to field configurations.
+ */
+export interface JsonSchema {
+  [fieldName: string]: FieldConfig | FieldBuilderLike;
 }
 
 /**

package/src/validator.ts

@@ -156,6 +156,69 @@ export class SchemaValidator {
       }
     }
 
+    // Validate belongsTo relationships
+    if (fieldConfig.belongsTo) {
+      const { table: refTable, foreignKey: refForeignKey } = fieldConfig.belongsTo;
+
+      if (!schema[refTable]) {
+        this.errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `belongsTo references non-existent table '${refTable}'`,
+        });
+      }
+
+      // Check if the foreign key field exists in the current table
+      const currentTableFields = Object.keys(schema[tableName]).filter(key => key !== '$count');
+      if (!currentTableFields.includes(refForeignKey)) {
+        this.errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `belongsTo references non-existent foreign key field '${refForeignKey}' in current table`,
+        });
+      }
+    }
+
+    // Validate hasMany relationships
+    if (fieldConfig.hasMany) {
+      const { table: relatedTable, foreignKey: foreignKeyField, min, max } = fieldConfig.hasMany;
+
+      if (!schema[relatedTable]) {
+        this.errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `hasMany references non-existent table '${relatedTable}'`,
+        });
+      } else {
+        // Check if the foreign key field exists in the related table
+        const relatedTableFields = Object.keys(schema[relatedTable]).filter(key => key !== '$count');
+        if (!relatedTableFields.includes(foreignKeyField)) {
+          this.errors.push({
+            table: tableName,
+            field: fieldName,
+            message: `hasMany references non-existent foreign key field '${foreignKeyField}' in table '${relatedTable}'`,
+          });
+        }
+      }
+
+      // Validate min/max constraints for hasMany
+      if (min !== undefined && max !== undefined && min > max) {
+        this.errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `hasMany min (${min}) cannot be greater than max (${max})`,
+        });
+      }
+
+      if (min !== undefined && min < 0) {
+        this.errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `hasMany min (${min}) cannot be negative`,
+        });
+      }
+    }
+
     // Validate min/max constraints
     if (fieldConfig.min !== undefined && fieldConfig.max !== undefined) {
       if (fieldConfig.min > fieldConfig.max) {
@@ -201,6 +264,8 @@ export class SchemaValidator {
 
       for (const [_, fieldConfig] of fields) {
         const config = this.toFieldConfig(fieldConfig);
+
+        // Check foreignKey dependencies
         if (config?.foreignKey) {
           const refTable = config.foreignKey.table;
 
@@ -216,6 +281,23 @@ export class SchemaValidator {
             return true;
           }
         }
+
+        // Check belongsTo dependencies
+        if (config?.belongsTo) {
+          const refTable = config.belongsTo.table;
+
+          if (!visited.has(refTable)) {
+            if (hasCycle(refTable, [...path, refTable])) {
+              return true;
+            }
+          } else if (recursionStack.has(refTable)) {
+            this.errors.push({
+              table: tableName,
+              message: `Circular dependency detected: ${[...path, refTable].join(' -> ')}`,
+            });
+            return true;
+          }
+        }
       }
 
       recursionStack.delete(tableName);