@doviui/dev-db 0.3.0 → 0.4.0

package/README.md

@@ -269,7 +269,9 @@ t.json({
 
 #### 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
@@ -301,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:
@@ -655,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(),
@@ -667,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)
   }
@@ -701,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),
@@ -716,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doviui/dev-db",
-  "version": "0.3.0",
+  "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

@@ -209,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;
@@ -250,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) {

package/src/schema-builder.ts

@@ -1,4 +1,4 @@
-import { FieldBuilder, ForeignKeyBuilder } from './field-builder';
+import { FieldBuilder, ForeignKeyBuilder, BelongsToBuilder, HasManyBuilder } from './field-builder';
 import type { JsonSchema } from './types';
 
 /**
@@ -247,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.ts

@@ -57,6 +57,12 @@ 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;
 

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);