@stravigor/core 0.1.0

package/src/schema/field_builder.ts

@@ -0,0 +1,155 @@
+import type { PostgreSQLType } from './postgres.ts'
+import type { FieldDefinition, FieldValidator } from './field_definition.ts'
+
+/** Initial options that the type builder can pass at construction time. */
+interface FieldBuilderOptions {
+  length?: number
+  precision?: number
+  scale?: number
+  references?: string
+  enumValues?: string[]
+}
+
+/**
+ * Fluent builder for a single field definition.
+ *
+ * Created by the `t` type builder; collects modifiers, validators,
+ * and type parameters, then exposes the result as a {@link FieldDefinition}.
+ *
+ * @example
+ * t.varchar(255).email().unique().required()
+ */
+export default class FieldBuilder {
+  private def: FieldDefinition
+
+  constructor(pgType: PostgreSQLType, options?: FieldBuilderOptions) {
+    this.def = {
+      pgType,
+      required: false,
+      nullable: false,
+      unique: false,
+      primaryKey: false,
+      index: false,
+      sensitive: false,
+      isArray: false,
+      arrayDimensions: 1,
+      length: options?.length,
+      precision: options?.precision,
+      scale: options?.scale,
+      references: options?.references,
+      enumValues: options?.enumValues,
+      validators: [],
+    }
+  }
+
+  // === Modifiers ===
+
+  /** Mark the field as NOT NULL. */
+  required(): this {
+    this.def.required = true
+    return this
+  }
+
+  /** Mark the field as explicitly nullable. */
+  nullable(): this {
+    this.def.nullable = true
+    return this
+  }
+
+  /** Add a UNIQUE constraint. */
+  unique(): this {
+    this.def.unique = true
+    return this
+  }
+
+  /** Set the column's DEFAULT value. */
+  default(value: unknown): this {
+    this.def.defaultValue = value
+    return this
+  }
+
+  /** Mark the field as a primary key. */
+  primaryKey(): this {
+    this.def.primaryKey = true
+    return this
+  }
+
+  /** Add a database index on this field. */
+  index(): this {
+    this.def.index = true
+    return this
+  }
+
+  /** Mark the field as containing sensitive data. */
+  sensitive(): this {
+    this.def.sensitive = true
+    return this
+  }
+
+  /** Convert this field to a PostgreSQL array type. */
+  array(dimensions: number = 1): this {
+    this.def.isArray = true
+    this.def.arrayDimensions = dimensions
+    return this
+  }
+
+  // === Validators ===
+
+  /** Minimum value/length validator. */
+  min(value: number): this {
+    this.def.validators.push({ type: 'min', params: { value } })
+    return this
+  }
+
+  /** Maximum value/length validator. */
+  max(value: number): this {
+    this.def.validators.push({ type: 'max', params: { value } })
+    return this
+  }
+
+  /** Email format validator. */
+  email(): this {
+    this.def.validators.push({ type: 'email' })
+    return this
+  }
+
+  /** URL format validator. */
+  url(): this {
+    this.def.validators.push({ type: 'url' })
+    return this
+  }
+
+  /** Regex pattern validator. */
+  regex(pattern: string | RegExp): this {
+    const source = pattern instanceof RegExp ? pattern.source : pattern
+    this.def.validators.push({ type: 'regex', params: { pattern: source } })
+    return this
+  }
+
+  /** String length validator (exact or range). */
+  length(min: number, max?: number): this {
+    this.def.validators.push({ type: 'length', params: { min, max } })
+    return this
+  }
+
+  /** Numeric precision. Also sets the type parameter for SQL generation. */
+  precision(p: number): this {
+    this.def.precision = p
+    this.def.validators.push({ type: 'precision', params: { value: p } })
+    return this
+  }
+
+  /** Numeric scale. Also sets the type parameter for SQL generation. */
+  scale(s: number): this {
+    this.def.scale = s
+    this.def.validators.push({ type: 'scale', params: { value: s } })
+    return this
+  }
+
+  // === Accessors ===
+
+  /** Return the finalized field definition. */
+  toDefinition(): FieldDefinition {
+    return { ...this.def, validators: [...this.def.validators] }
+  }
+}

package/src/schema/field_definition.ts

@@ -0,0 +1,66 @@
+import type { PostgreSQLType } from './postgres.ts'
+
+/**
+ * A single validation constraint.
+ * Code generators read these to produce runtime validation rules.
+ */
+export interface FieldValidator {
+  type: 'min' | 'max' | 'email' | 'url' | 'regex' | 'length' | 'precision' | 'scale'
+  params?: Record<string, unknown>
+}
+
+/**
+ * Serializable description of a single schema field.
+ *
+ * Produced by the {@link FieldBuilder} fluent chain, consumed by
+ * code generators, migration engines, and validators.
+ */
+export interface FieldDefinition {
+  /** The resolved PostgreSQL column type (e.g. 'varchar', 'integer', 'jsonb'). */
+  pgType: PostgreSQLType
+
+  /** Whether the field is NOT NULL. */
+  required: boolean
+
+  /** Whether the field explicitly allows NULL. */
+  nullable: boolean
+
+  /** Whether the field has a UNIQUE constraint. */
+  unique: boolean
+
+  /** Default value expression (literal or SQL expression string). */
+  defaultValue?: unknown
+
+  /** Whether the field is a primary key. */
+  primaryKey: boolean
+
+  /** Whether the field should have a database index. */
+  index: boolean
+
+  /** Whether the field contains sensitive data (excluded from logs/serialization). */
+  sensitive: boolean
+
+  /** Whether the field is an array. If true, pgType describes the element type. */
+  isArray: boolean
+
+  /** Array dimensions (1 = one-dimensional, 2 = two-dimensional, etc.). */
+  arrayDimensions: number
+
+  /** Maximum length for varchar/char, or bit length for bit types. */
+  length?: number
+
+  /** Precision for decimal/numeric types. */
+  precision?: number
+
+  /** Scale for decimal/numeric types. */
+  scale?: number
+
+  /** For reference fields: the name of the referenced table/schema. */
+  references?: string
+
+  /** For enum fields: the list of allowed string values. */
+  enumValues?: string[]
+
+  /** Validation constraints collected from the fluent chain. */
+  validators: FieldValidator[]
+}

package/src/schema/index.ts

@@ -0,0 +1,21 @@
+export { default as defineSchema } from './define_schema.ts'
+export { default as defineAssociation } from './define_association.ts'
+export { default as t } from './type_builder.ts'
+export { default as FieldBuilder } from './field_builder.ts'
+export { default as SchemaRegistry } from './registry.ts'
+export { default as RepresentationBuilder } from './representation_builder.ts'
+export { toSnakeCase, serialToIntegerType } from './naming.ts'
+export type { FieldDefinition, FieldValidator } from './field_definition.ts'
+export { Archetype } from './types.ts'
+export type { SchemaDefinition, SchemaInput } from './types.ts'
+export type {
+  DatabaseRepresentation,
+  TableDefinition,
+  ColumnDefinition,
+  EnumDefinition,
+  ForeignKeyConstraint,
+  PrimaryKeyConstraint,
+  UniqueConstraint,
+  IndexDefinition,
+  DefaultValue,
+} from './database_representation.ts'

package/src/schema/naming.ts

@@ -0,0 +1,19 @@
+import type { PostgreSQLType } from './postgres.ts'
+
+export { toSnakeCase } from '../helpers/strings.ts'
+
+/**
+ * Map a serial/bigserial/smallserial pgType to the corresponding integer type
+ * used for foreign key columns. All other types pass through unchanged.
+ *
+ * @example
+ * serialToIntegerType('serial')    // 'integer'
+ * serialToIntegerType('bigserial') // 'bigint'
+ * serialToIntegerType('uuid')      // 'uuid'
+ */
+export function serialToIntegerType(pgType: PostgreSQLType): PostgreSQLType {
+  if (pgType === 'serial') return 'integer'
+  if (pgType === 'bigserial') return 'bigint'
+  if (pgType === 'smallserial') return 'smallint'
+  return pgType
+}

package/src/schema/postgres.ts

@@ -0,0 +1,109 @@
+// Complete PostgreSQL type system
+export type PostgreSQLType =
+  | PostgreSQLNumericTypes
+  | PostgreSQLMonetaryTypes
+  | PostgreSQLCharacterTypes
+  | PostgreSQLBinaryTypes
+  | PostgreSQLDateTimeTypes
+  | PostgreSQLBooleanTypes
+  | PostgreSQLUUIDTypes
+  | PostgreSQLNetworkTypes
+  | PostgreSQLBitStringTypes
+  | PostgreSQLTextSearchTypes
+  | PostgreSQLJSONTypes
+  | PostgreSQLGeometricTypes
+  | PostgreSQLRangeTypes
+  | PostgreSQLXMLTypes
+  | PostgreSQLArrayType
+  | PostgreSQLCustomType
+
+/** Integer, arbitrary precision, floating-point, and auto-incrementing types. */
+export type PostgreSQLNumericTypes =
+  | 'smallint'
+  | 'integer'
+  | 'bigint'
+  | 'decimal'
+  | 'numeric'
+  | 'real'
+  | 'double_precision'
+  | 'smallserial'
+  | 'serial'
+  | 'bigserial'
+
+/** Currency amounts with locale-aware formatting. */
+export type PostgreSQLMonetaryTypes = 'money'
+
+/** Fixed-length, variable-length, and unlimited text. */
+export type PostgreSQLCharacterTypes =
+  | 'character_varying'
+  | 'varchar'
+  | 'character'
+  | 'char'
+  | 'text'
+
+/** Raw binary data (byte array). */
+export type PostgreSQLBinaryTypes = 'bytea'
+
+/** Dates, times, timestamps, and intervals. */
+export type PostgreSQLDateTimeTypes =
+  | 'timestamp'
+  | 'timestamptz'
+  | 'date'
+  | 'time'
+  | 'timetz'
+  | 'interval'
+
+/** True/false logical value. */
+export type PostgreSQLBooleanTypes = 'boolean'
+
+/** RFC 4122 universally unique identifiers. */
+export type PostgreSQLUUIDTypes = 'uuid'
+
+/** IPv4/IPv6 addresses, CIDR blocks, and MAC addresses. */
+export type PostgreSQLNetworkTypes = 'inet' | 'cidr' | 'macaddr' | 'macaddr8'
+
+/** Fixed-length and variable-length bit strings. */
+export type PostgreSQLBitStringTypes = 'bit' | 'bit_varying'
+
+/** Full-text search document and query representations. */
+export type PostgreSQLTextSearchTypes = 'tsvector' | 'tsquery'
+
+/** JSON data stored as text or decomposed binary. */
+export type PostgreSQLJSONTypes = 'json' | 'jsonb'
+
+/** XML document data. */
+export type PostgreSQLXMLTypes = 'xml'
+
+/** 2D geometric primitives: points, lines, segments, boxes, paths, polygons, and circles. */
+export type PostgreSQLGeometricTypes =
+  | 'point'
+  | 'line'
+  | 'lseg'
+  | 'box'
+  | 'path'
+  | 'polygon'
+  | 'circle'
+
+/** Ranges over integer, numeric, timestamp, and date values. */
+export type PostgreSQLRangeTypes =
+  | 'int4range'
+  | 'int8range'
+  | 'numrange'
+  | 'tsrange'
+  | 'tstzrange'
+  | 'daterange'
+
+/** Typed multi-dimensional array of any non-array PostgreSQL type. */
+export interface PostgreSQLArrayType {
+  type: 'array'
+  element: Exclude<PostgreSQLType, PostgreSQLArrayType>
+  dimensions?: number
+}
+
+/** User-defined type, enum, or domain. */
+export interface PostgreSQLCustomType {
+  type: 'custom'
+  name: string // Custom type name or enum name
+  definition?: string // For inline enum definitions
+  values?: string[] // For enum types - the actual values array
+}

package/src/schema/registry.ts

@@ -0,0 +1,157 @@
+import { readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import type { SchemaDefinition } from './types.ts'
+import type { DatabaseRepresentation } from './database_representation.ts'
+import RepresentationBuilder from './representation_builder.ts'
+
+/**
+ * Discovers, stores, validates, and provides dependency-ordered
+ * access to all schema definitions in the application.
+ *
+ * @example
+ * const registry = new SchemaRegistry()
+ * await registry.discover('database/schemas')
+ * registry.validate()
+ * const ordered = registry.resolve() // topologically sorted
+ */
+export default class SchemaRegistry {
+  private schemas = new Map<string, SchemaDefinition>()
+
+  /** Register a single schema definition. */
+  register(schema: SchemaDefinition): this {
+    if (this.schemas.has(schema.name)) {
+      throw new Error(`Schema "${schema.name}" is already registered`)
+    }
+    this.schemas.set(schema.name, schema)
+    return this
+  }
+
+  /** Retrieve a schema by name. */
+  get(name: string): SchemaDefinition | undefined {
+    return this.schemas.get(name)
+  }
+
+  /** Check whether a schema with the given name exists. */
+  has(name: string): boolean {
+    return this.schemas.has(name)
+  }
+
+  /** Return all registered schemas as an array. */
+  all(): SchemaDefinition[] {
+    return Array.from(this.schemas.values())
+  }
+
+  /**
+   * Scan a directory for schema files and register all discovered schemas.
+   * Each `.ts` file must default-export a {@link SchemaDefinition}.
+   */
+  async discover(schemasPath: string): Promise<void> {
+    const absPath = resolve(schemasPath)
+    let files: string[]
+    try {
+      files = readdirSync(absPath)
+    } catch {
+      throw new Error(`Schemas directory not found: ${schemasPath}`)
+    }
+
+    for (const file of files) {
+      if (!file.endsWith('.ts')) continue
+      const filePath = join(absPath, file)
+      const mod = await import(filePath)
+      const schema: SchemaDefinition = mod.default
+      if (!schema || !schema.name) {
+        throw new Error(`Schema file "${file}" does not export a valid SchemaDefinition`)
+      }
+      this.register(schema)
+    }
+  }
+
+  /**
+   * Validate all schemas: check that every reference and parent
+   * points to a registered schema.
+   */
+  validate(): void {
+    for (const schema of this.schemas.values()) {
+      if (schema.parent && !this.schemas.has(schema.parent)) {
+        throw new Error(
+          `Schema "${schema.name}" references parent "${schema.parent}" which is not registered`
+        )
+      }
+
+      if (schema.associates) {
+        for (const assoc of schema.associates) {
+          if (!this.schemas.has(assoc)) {
+            throw new Error(
+              `Schema "${schema.name}" associates with "${assoc}" which is not registered`
+            )
+          }
+        }
+      }
+
+      for (const [fieldName, fieldDef] of Object.entries(schema.fields)) {
+        if (fieldDef.references && !this.schemas.has(fieldDef.references)) {
+          throw new Error(
+            `Schema "${schema.name}" field "${fieldName}" references "${fieldDef.references}" which is not registered`
+          )
+        }
+      }
+    }
+  }
+
+  /**
+   * Return schemas in dependency order (topological sort).
+   * Schemas with no dependencies come first.
+   * Throws if a circular dependency is detected.
+   */
+  resolve(): SchemaDefinition[] {
+    const visited = new Set<string>()
+    const visiting = new Set<string>()
+    const sorted: SchemaDefinition[] = []
+
+    const visit = (name: string, path: string[]) => {
+      if (visited.has(name)) return
+      if (visiting.has(name)) {
+        throw new Error(`Circular dependency detected: ${[...path, name].join(' -> ')}`)
+      }
+
+      visiting.add(name)
+      const schema = this.schemas.get(name)!
+      for (const dep of this.getDependencies(schema)) {
+        visit(dep, [...path, name])
+      }
+      visiting.delete(name)
+      visited.add(name)
+      sorted.push(schema)
+    }
+
+    for (const name of this.schemas.keys()) {
+      visit(name, [])
+    }
+
+    return sorted
+  }
+
+  /**
+   * Generate the {@link DatabaseRepresentation} from all registered schemas.
+   * Must be called after {@link validate} to ensure all references are resolvable.
+   */
+  buildRepresentation(): DatabaseRepresentation {
+    const ordered = this.resolve()
+    return new RepresentationBuilder(ordered).build()
+  }
+
+  /** Collect all schema names that the given schema depends on. */
+  private getDependencies(schema: SchemaDefinition): string[] {
+    const deps = new Set<string>()
+
+    if (schema.parent) deps.add(schema.parent)
+    if (schema.associates) {
+      for (const assoc of schema.associates) deps.add(assoc)
+    }
+    for (const fieldDef of Object.values(schema.fields)) {
+      if (fieldDef.references) deps.add(fieldDef.references)
+    }
+
+    return Array.from(deps)
+  }
+}