@doviui/dev-db 0.1.0

package/src/schema-builder.ts

@@ -0,0 +1,213 @@
+import { FieldBuilder, ForeignKeyBuilder } from './field-builder';
+
+/**
+ * Type builder API for defining database schemas with a fluent interface.
+ * Provides methods for creating various SQL-like field types with constraints.
+ *
+ * @example
+ * ```typescript
+ * import { t } from '@doviui/dev-db';
+ *
+ * const schema = {
+ *   User: {
+ *     $count: 100,
+ *     id: t.bigserial().primaryKey(),
+ *     email: t.varchar(255).unique().notNull().generate('internet.email'),
+ *     age: t.integer().min(18).max(100),
+ *     created_at: t.timestamptz().default('now')
+ *   }
+ * };
+ * ```
+ */
+export const t = {
+  // Numeric types
+
+  /**
+   * Creates a big integer field (64-bit).
+   * @returns FieldBuilder instance for method chaining
+   */
+  bigint(): FieldBuilder {
+    return new FieldBuilder('bigint');
+  },
+
+  /**
+   * Creates an auto-incrementing big integer field.
+   * Commonly used for primary keys.
+   * @returns FieldBuilder instance for method chaining
+   */
+  bigserial(): FieldBuilder {
+    return new FieldBuilder('bigserial');
+  },
+
+  /**
+   * Creates a standard integer field (32-bit).
+   * @returns FieldBuilder instance for method chaining
+   */
+  integer(): FieldBuilder {
+    return new FieldBuilder('integer');
+  },
+
+  /**
+   * Creates a small integer field (16-bit).
+   * @returns FieldBuilder instance for method chaining
+   */
+  smallint(): FieldBuilder {
+    return new FieldBuilder('smallint');
+  },
+
+  /**
+   * Creates an auto-incrementing integer field.
+   * @returns FieldBuilder instance for method chaining
+   */
+  serial(): FieldBuilder {
+    return new FieldBuilder('serial');
+  },
+
+  /**
+   * Creates a decimal/numeric field with specified precision and scale.
+   * @param precision - Total number of digits
+   * @param scale - Number of digits after the decimal point
+   * @returns FieldBuilder instance for method chaining
+   * @example t.decimal(10, 2) // e.g., 12345678.90
+   */
+  decimal(precision: number, scale: number): FieldBuilder {
+    return new FieldBuilder('decimal', undefined, precision, scale);
+  },
+
+  /**
+   * Creates a numeric field (alias for decimal).
+   * @param precision - Total number of digits
+   * @param scale - Number of digits after the decimal point
+   * @returns FieldBuilder instance for method chaining
+   */
+  numeric(precision: number, scale: number): FieldBuilder {
+    return new FieldBuilder('numeric', undefined, precision, scale);
+  },
+
+  /**
+   * Creates a single-precision floating point field.
+   * @returns FieldBuilder instance for method chaining
+   */
+  real(): FieldBuilder {
+    return new FieldBuilder('real');
+  },
+
+  /**
+   * Creates a double-precision floating point field.
+   * @returns FieldBuilder instance for method chaining
+   */
+  double(): FieldBuilder {
+    return new FieldBuilder('double');
+  },
+
+  // String types
+
+  /**
+   * Creates a variable-length character field.
+   * @param length - Maximum length of the string
+   * @returns FieldBuilder instance for method chaining
+   * @example t.varchar(255)
+   */
+  varchar(length: number): FieldBuilder {
+    return new FieldBuilder('varchar', length);
+  },
+
+  /**
+   * Creates a fixed-length character field.
+   * @param length - Fixed length of the string
+   * @returns FieldBuilder instance for method chaining
+   */
+  char(length: number): FieldBuilder {
+    return new FieldBuilder('char', length);
+  },
+
+  /**
+   * Creates an unlimited text field.
+   * @returns FieldBuilder instance for method chaining
+   */
+  text(): FieldBuilder {
+    return new FieldBuilder('text');
+  },
+
+  // Date/Time types
+
+  /**
+   * Creates a date-only field (no time component).
+   * @returns FieldBuilder instance for method chaining
+   */
+  date(): FieldBuilder {
+    return new FieldBuilder('date');
+  },
+
+  /**
+   * Creates a time-only field (no date component).
+   * @returns FieldBuilder instance for method chaining
+   */
+  time(): FieldBuilder {
+    return new FieldBuilder('time');
+  },
+
+  /**
+   * Creates a timestamp field (date and time without timezone).
+   * @returns FieldBuilder instance for method chaining
+   */
+  timestamp(): FieldBuilder {
+    return new FieldBuilder('timestamp');
+  },
+
+  /**
+   * Creates a timestamp field with timezone support.
+   * @returns FieldBuilder instance for method chaining
+   */
+  timestamptz(): FieldBuilder {
+    return new FieldBuilder('timestamptz');
+  },
+
+  // Other types
+
+  /**
+   * Creates a boolean field (true/false).
+   * @returns FieldBuilder instance for method chaining
+   */
+  boolean(): FieldBuilder {
+    return new FieldBuilder('boolean');
+  },
+
+  /**
+   * Creates a UUID field (universally unique identifier).
+   * @returns FieldBuilder instance for method chaining
+   */
+  uuid(): FieldBuilder {
+    return new FieldBuilder('uuid');
+  },
+
+  /**
+   * Creates a JSON field for storing structured data.
+   * @returns FieldBuilder instance for method chaining
+   */
+  json(): FieldBuilder {
+    return new FieldBuilder('json');
+  },
+
+  /**
+   * 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');
+  },
+
+  // Relationships
+
+  /**
+   * Creates a foreign key reference to another table.
+   * @param table - The referenced table name
+   * @param column - The referenced column name
+   * @returns ForeignKeyBuilder instance for method chaining
+   * @example t.foreignKey('User', 'id').notNull()
+   */
+  foreignKey(table: string, column: string): ForeignKeyBuilder {
+    return new ForeignKeyBuilder(table, column);
+  },
+};

package/src/types.ts

@@ -0,0 +1,107 @@
+import type { Faker } from '@faker-js/faker';
+
+/**
+ * A generator function or Faker.js method path for generating field values.
+ *
+ * @example
+ * ```typescript
+ * // Using Faker.js method path
+ * 'internet.email'
+ *
+ * // Using custom function
+ * (faker) => faker.helpers.arrayElement(['red', 'blue', 'green'])
+ * ```
+ */
+export type Generator = string | ((faker: Faker) => any);
+
+/**
+ * Configuration for a database field, defining its type, constraints, and generation rules.
+ */
+export interface FieldConfig {
+  /** The SQL-like type of the field (e.g., 'varchar', 'integer', 'uuid') */
+  type: string;
+
+  /** Maximum length for string types */
+  length?: number;
+
+  /** Precision for numeric types */
+  precision?: number;
+
+  /** Scale (decimal places) for numeric types */
+  scale?: number;
+
+  /** Whether this field is a primary key */
+  primaryKey?: boolean;
+
+  /** Whether values must be unique across all records */
+  unique?: boolean;
+
+  /** Whether null values are not allowed */
+  notNull?: boolean;
+
+  /** Whether null values are allowed (default: true) */
+  nullable?: boolean;
+
+  /** Default value for the field. Use 'now' for current timestamp */
+  default?: any;
+
+  /** Minimum value for numeric types */
+  min?: number;
+
+  /** Maximum value for numeric types */
+  max?: number;
+
+  /** Array of allowed values for enum fields */
+  enum?: any[];
+
+  /** Foreign key reference to another table */
+  foreignKey?: { table: string; column: string };
+
+  /** Custom generator function or Faker.js method path */
+  generator?: Generator;
+}
+
+/**
+ * Configuration for a database table, including field definitions and record count.
+ */
+export interface TableConfig {
+  /** Number of records to generate for this table */
+  $count?: number;
+
+  /** Field definitions - can be FieldConfig objects or FieldBuilder instances */
+  [fieldName: string]: FieldConfig | FieldBuilderLike | number | undefined;
+}
+
+/**
+ * Interface for objects that can be converted to FieldConfig.
+ * Allows FieldBuilder instances to be used directly in schemas.
+ */
+export interface FieldBuilderLike {
+  /** Converts the builder to a FieldConfig object */
+  toConfig(): FieldConfig;
+}
+
+/**
+ * Complete schema definition mapping table names to their configurations.
+ *
+ * @example
+ * ```typescript
+ * const schema: Schema = {
+ *   User: {
+ *     $count: 100,
+ *     id: t.bigserial().primaryKey(),
+ *     email: t.varchar(255).unique().notNull(),
+ *     age: t.integer().min(18).max(100)
+ *   },
+ *   Post: {
+ *     $count: 500,
+ *     id: t.bigserial().primaryKey(),
+ *     user_id: t.foreignKey('User', 'id'),
+ *     title: t.varchar(200)
+ *   }
+ * };
+ * ```
+ */
+export interface Schema {
+  [tableName: string]: TableConfig;
+}

package/src/validator.ts

@@ -0,0 +1,231 @@
+import type { Schema, FieldConfig, TableConfig } from './types';
+
+/**
+ * Represents a validation error found in a schema.
+ */
+export interface ValidationError {
+  /** The table where the error occurred */
+  table: string;
+
+  /** The field where the error occurred (if applicable) */
+  field?: string;
+
+  /** Human-readable error message */
+  message: string;
+}
+
+/**
+ * Validates database schemas for common errors and inconsistencies.
+ *
+ * Checks for:
+ * - Missing primary keys
+ * - Invalid foreign key references
+ * - Circular dependencies
+ * - Invalid constraints (e.g., min > max)
+ * - Empty enums
+ * - Invalid $count values
+ *
+ * @example
+ * ```typescript
+ * const validator = new SchemaValidator();
+ * const errors = validator.validate(schema);
+ *
+ * if (errors.length > 0) {
+ *   console.error('Schema validation failed:');
+ *   errors.forEach(err => {
+ *     console.error(`  ${err.table}.${err.field}: ${err.message}`);
+ *   });
+ * }
+ * ```
+ */
+export class SchemaValidator {
+  private errors: ValidationError[] = [];
+
+  /**
+   * Validates a complete schema and returns any errors found.
+   *
+   * @param schema - The schema to validate
+   * @returns Array of validation errors (empty if valid)
+   *
+   * @example
+   * ```typescript
+   * const errors = validator.validate(schema);
+   * if (errors.length === 0) {
+   *   console.log('Schema is valid!');
+   * }
+   * ```
+   */
+  validate(schema: Schema): ValidationError[] {
+    this.errors = [];
+
+    // Check for empty schema
+    if (Object.keys(schema).length === 0) {
+      this.errors.push({
+        table: '',
+        message: 'Schema is empty',
+      });
+      return this.errors;
+    }
+
+    // Validate each table
+    for (const [tableName, tableConfig] of Object.entries(schema)) {
+      this.validateTable(tableName, tableConfig, schema);
+    }
+
+    // Check for circular dependencies
+    this.checkCircularDependencies(schema);
+
+    return this.errors;
+  }
+
+  private validateTable(tableName: string, tableConfig: TableConfig, schema: Schema): void {
+    // Check if $count is valid
+    if (tableConfig.$count !== undefined && (tableConfig.$count < 0 || !Number.isInteger(tableConfig.$count))) {
+      this.errors.push({
+        table: tableName,
+        message: `Invalid $count: ${tableConfig.$count}. Must be a non-negative integer.`,
+      });
+    }
+
+    const fields = Object.entries(tableConfig).filter(([key]) => key !== '$count');
+
+    if (fields.length === 0) {
+      this.errors.push({
+        table: tableName,
+        message: 'Table has no fields defined',
+      });
+      return;
+    }
+
+    // Check if there's at least one primary key
+    const hasPrimaryKey = fields.some(([_, config]) => {
+      const fieldConfig = this.toFieldConfig(config);
+      return fieldConfig?.primaryKey;
+    });
+
+    if (!hasPrimaryKey) {
+      this.errors.push({
+        table: tableName,
+        message: 'Table must have at least one primary key',
+      });
+    }
+
+    // Validate each field
+    for (const [fieldName, fieldConfig] of fields) {
+      const config = this.toFieldConfig(fieldConfig);
+      if (config) {
+        this.validateField(tableName, fieldName, config, schema);
+      }
+    }
+  }
+
+  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;
+  }
+
+  private validateField(tableName: string, fieldName: string, fieldConfig: FieldConfig, schema: Schema): void {
+    // Validate foreign key references
+    if (fieldConfig.foreignKey) {
+      const { table: refTable, column: refColumn } = fieldConfig.foreignKey;
+
+      if (!schema[refTable]) {
+        this.errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `Foreign key references non-existent table '${refTable}'`,
+        });
+      } else {
+        const refTableConfig = schema[refTable];
+        const refFields = Object.entries(refTableConfig).filter(([key]) => key !== '$count');
+        const refFieldExists = refFields.some(([name]) => name === refColumn);
+
+        if (!refFieldExists) {
+          this.errors.push({
+            table: tableName,
+            field: fieldName,
+            message: `Foreign key references non-existent column '${refColumn}' in table '${refTable}'`,
+          });
+        }
+      }
+    }
+
+    // Validate min/max constraints
+    if (fieldConfig.min !== undefined && fieldConfig.max !== undefined) {
+      if (fieldConfig.min > fieldConfig.max) {
+        this.errors.push({
+          table: tableName,
+          field: fieldName,
+          message: `Min value (${fieldConfig.min}) cannot be greater than max value (${fieldConfig.max})`,
+        });
+      }
+    }
+
+    // Validate enum
+    if (fieldConfig.enum && fieldConfig.enum.length === 0) {
+      this.errors.push({
+        table: tableName,
+        field: fieldName,
+        message: 'Enum must have at least one value',
+      });
+    }
+
+    // Validate conflicting constraints
+    if (fieldConfig.notNull && fieldConfig.nullable) {
+      this.errors.push({
+        table: tableName,
+        field: fieldName,
+        message: 'Field cannot be both notNull and nullable',
+      });
+    }
+  }
+
+  private checkCircularDependencies(schema: Schema): void {
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    const hasCycle = (tableName: string, path: string[]): boolean => {
+      visited.add(tableName);
+      recursionStack.add(tableName);
+
+      const tableConfig = schema[tableName];
+      if (!tableConfig) return false;
+
+      const fields = Object.entries(tableConfig).filter(([key]) => key !== '$count');
+
+      for (const [_, fieldConfig] of fields) {
+        const config = this.toFieldConfig(fieldConfig);
+        if (config?.foreignKey) {
+          const refTable = config.foreignKey.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);
+      return false;
+    };
+
+    for (const tableName of Object.keys(schema)) {
+      if (!visited.has(tableName)) {
+        hasCycle(tableName, [tableName]);
+      }
+    }
+  }
+}