@doviui/dev-db 0.2.1 → 0.3.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,8 +251,20 @@ 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
@@ -332,6 +406,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 +533,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 +552,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:**

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.3.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.
    *

package/src/generator.ts

@@ -206,12 +206,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
@@ -309,6 +310,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 +340,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 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.
-   * @returns FieldBuilder instance for method chaining
-   */
-  json(): FieldBuilder {
-    return new FieldBuilder('json');
+   * @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(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.
-   * @returns FieldBuilder instance for method chaining
-   */
-  jsonb(): FieldBuilder {
-    return new FieldBuilder('jsonb');
+   * @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(schema?: JsonSchema): FieldBuilder {
+    const builder = new FieldBuilder('jsonb');
+    if (schema) {
+      builder.withJsonSchema(schema);
+    }
+    return builder;
   },
 
   // Relationships

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

@@ -59,6 +59,16 @@ export interface FieldConfig {
 
   /** 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;
 }
 
 /**