@strav/database 0.1.0

package/src/schema/representation_builder.ts

@@ -0,0 +1,482 @@
+import { Archetype } from './types'
+import type { SchemaDefinition } from './types'
+import type { FieldDefinition } from './field_definition'
+import type { PostgreSQLCustomType, PostgreSQLType } from './postgres'
+import type {
+  DatabaseRepresentation,
+  TableDefinition,
+  ColumnDefinition,
+  EnumDefinition,
+  ForeignKeyConstraint,
+  PrimaryKeyConstraint,
+  UniqueConstraint,
+  IndexDefinition,
+  DefaultValue,
+} from './database_representation'
+import { toSnakeCase, serialToIntegerType } from './naming'
+
+/** Timestamp columns each archetype receives automatically. */
+const TIMESTAMP_RULES: Record<
+  Archetype,
+  { created_at: boolean; updated_at: boolean; deleted_at: boolean }
+> = {
+  [Archetype.Entity]: { created_at: true, updated_at: true, deleted_at: true },
+  [Archetype.Component]: { created_at: true, updated_at: true, deleted_at: false },
+  [Archetype.Attribute]: { created_at: true, updated_at: true, deleted_at: true },
+  [Archetype.Association]: { created_at: true, updated_at: true, deleted_at: false },
+  [Archetype.Event]: { created_at: true, updated_at: false, deleted_at: false },
+  [Archetype.Reference]: { created_at: true, updated_at: true, deleted_at: false },
+  [Archetype.Configuration]: { created_at: true, updated_at: true, deleted_at: false },
+  [Archetype.Contribution]: { created_at: true, updated_at: true, deleted_at: true },
+}
+
+/** Archetypes that have a parent FK (dependent archetypes except association). */
+const PARENT_FK_ARCHETYPES: Set<Archetype> = new Set([
+  Archetype.Component,
+  Archetype.Attribute,
+  Archetype.Event,
+  Archetype.Configuration,
+  Archetype.Contribution,
+])
+
+/** Resolved primary key info for a schema. */
+interface PKInfo {
+  name: string
+  pgType: PostgreSQLType
+}
+
+/**
+ * Transforms a set of {@link SchemaDefinition}s into a {@link DatabaseRepresentation}.
+ *
+ * Schemas must be provided in dependency order (from {@link SchemaRegistry.resolve}).
+ */
+export default class RepresentationBuilder {
+  private schemas: Map<string, SchemaDefinition>
+
+  constructor(schemas: SchemaDefinition[]) {
+    this.schemas = new Map(schemas.map(s => [s.name, s]))
+  }
+
+  build(): DatabaseRepresentation {
+    const enums = this.collectEnums()
+    const tables: TableDefinition[] = []
+
+    for (const schema of this.schemas.values()) {
+      tables.push(this.buildTable(schema))
+    }
+
+    return { enums, tables }
+  }
+
+  private buildTable(schema: SchemaDefinition): TableDefinition {
+    const columns: ColumnDefinition[] = []
+    const foreignKeys: ForeignKeyConstraint[] = []
+    const uniqueConstraints: UniqueConstraint[] = []
+    const indexes: IndexDefinition[] = []
+
+    // 1. Primary key
+    const pk = this.addPrimaryKey(schema, columns)
+
+    // 2. Parent FK (for dependent archetypes)
+    this.addParentFK(schema, columns, foreignKeys, indexes)
+
+    // 3. Association FKs
+    this.addAssociationFKs(schema, columns, foreignKeys, uniqueConstraints, indexes)
+
+    // 4. User-defined fields (non-reference fields)
+    // 5. Reference fields resolved to FK columns
+    this.addUserFields(schema, columns, foreignKeys, indexes)
+
+    // 6. Timestamps
+    this.addTimestamps(schema, columns)
+
+    // 7. NOT NULL defaults (skip FK columns — they must never have defaults)
+    this.applyNotNullDefaults(columns, foreignKeys)
+
+    return {
+      name: toSnakeCase(schema.name),
+      archetype: schema.archetype,
+      columns,
+      primaryKey: pk,
+      foreignKeys,
+      uniqueConstraints,
+      indexes,
+    }
+  }
+
+  /**
+   * Add the primary key column. Returns the PK constraint or null for associations.
+   */
+  private addPrimaryKey(
+    schema: SchemaDefinition,
+    columns: ColumnDefinition[]
+  ): PrimaryKeyConstraint | null {
+    if (schema.archetype === Archetype.Association) return null
+
+    // Check if developer specified a PK
+    for (const [fieldName, fieldDef] of Object.entries(schema.fields)) {
+      if (fieldDef.primaryKey) {
+        const colName = toSnakeCase(fieldName)
+        columns.push(this.fieldToColumn(colName, fieldDef))
+        return { columns: [colName] }
+      }
+    }
+
+    // Auto-add default: id serial
+    columns.push({
+      name: 'id',
+      pgType: 'serial',
+      notNull: true,
+      unique: true,
+      primaryKey: true,
+      autoIncrement: true,
+      index: false,
+      sensitive: false,
+      isArray: false,
+      arrayDimensions: 1,
+    })
+
+    return { columns: ['id'] }
+  }
+
+  /**
+   * Add parent FK columns for dependent archetypes.
+   */
+  private addParentFK(
+    schema: SchemaDefinition,
+    columns: ColumnDefinition[],
+    foreignKeys: ForeignKeyConstraint[],
+    indexes: IndexDefinition[]
+  ): void {
+    if (!schema.parents?.length || !PARENT_FK_ARCHETYPES.has(schema.archetype)) return
+
+    for (const parentName of schema.parents) {
+      const parentSchema = this.schemas.get(parentName)
+      if (!parentSchema) continue
+
+      const parentPK = this.findPrimaryKey(parentSchema)
+      const fkColName = `${toSnakeCase(parentName)}_${toSnakeCase(parentPK.name)}`
+      const fkColType = serialToIntegerType(parentPK.pgType)
+
+      columns.push({
+        name: fkColName,
+        pgType: fkColType,
+        notNull: true,
+        unique: false,
+        primaryKey: false,
+        autoIncrement: false,
+        index: true,
+        sensitive: false,
+        isArray: false,
+        arrayDimensions: 1,
+      })
+
+      foreignKeys.push({
+        columns: [fkColName],
+        referencedTable: toSnakeCase(parentName),
+        referencedColumns: [toSnakeCase(parentPK.name)],
+        onDelete: 'CASCADE',
+        onUpdate: 'CASCADE',
+      })
+
+      indexes.push({ columns: [fkColName], unique: false })
+    }
+  }
+
+  /**
+   * Add FK columns for both sides of an association.
+   */
+  private addAssociationFKs(
+    schema: SchemaDefinition,
+    columns: ColumnDefinition[],
+    foreignKeys: ForeignKeyConstraint[],
+    uniqueConstraints: UniqueConstraint[],
+    indexes: IndexDefinition[]
+  ): void {
+    if (schema.archetype !== Archetype.Association || !schema.associates) return
+
+    const fkColNames: string[] = []
+
+    for (const entityName of schema.associates) {
+      const entitySchema = this.schemas.get(entityName)
+      if (!entitySchema) continue
+
+      const entityPK = this.findPrimaryKey(entitySchema)
+      const fkColName = `${toSnakeCase(entityName)}_${toSnakeCase(entityPK.name)}`
+      const fkColType = serialToIntegerType(entityPK.pgType)
+
+      fkColNames.push(fkColName)
+
+      columns.push({
+        name: fkColName,
+        pgType: fkColType,
+        notNull: true,
+        unique: false,
+        primaryKey: false,
+        autoIncrement: false,
+        index: true,
+        sensitive: false,
+        isArray: false,
+        arrayDimensions: 1,
+      })
+
+      foreignKeys.push({
+        columns: [fkColName],
+        referencedTable: toSnakeCase(entityName),
+        referencedColumns: [toSnakeCase(entityPK.name)],
+        onDelete: 'CASCADE',
+        onUpdate: 'CASCADE',
+      })
+
+      indexes.push({ columns: [fkColName], unique: false })
+    }
+
+    // Composite unique on the FK pair (also add the backing index PostgreSQL creates)
+    if (fkColNames.length === 2) {
+      uniqueConstraints.push({ columns: fkColNames })
+      indexes.push({ columns: fkColNames, unique: true })
+    }
+  }
+
+  /**
+   * Add user-defined fields. Reference fields are resolved to proper FK columns.
+   */
+  private addUserFields(
+    schema: SchemaDefinition,
+    columns: ColumnDefinition[],
+    foreignKeys: ForeignKeyConstraint[],
+    indexes: IndexDefinition[]
+  ): void {
+    const associateSet = new Set(schema.associates ?? [])
+
+    for (const [fieldName, fieldDef] of Object.entries(schema.fields)) {
+      // Skip PK fields — already handled
+      if (fieldDef.primaryKey) continue
+
+      if (fieldDef.references) {
+        // Skip reference fields that duplicate an association FK
+        if (associateSet.has(fieldDef.references)) continue
+
+        this.addReferenceColumn(fieldName, fieldDef, columns, foreignKeys, indexes)
+      } else {
+        columns.push(this.fieldToColumn(toSnakeCase(fieldName), fieldDef))
+
+        if (fieldDef.index) {
+          indexes.push({ columns: [toSnakeCase(fieldName)], unique: false })
+        }
+        if (fieldDef.unique) {
+          indexes.push({ columns: [toSnakeCase(fieldName)], unique: true })
+        }
+      }
+    }
+  }
+
+  /**
+   * Resolve a reference field into a proper FK column.
+   */
+  private addReferenceColumn(
+    fieldName: string,
+    fieldDef: FieldDefinition,
+    columns: ColumnDefinition[],
+    foreignKeys: ForeignKeyConstraint[],
+    indexes: IndexDefinition[]
+  ): void {
+    const refSchema = this.schemas.get(fieldDef.references!)
+    if (!refSchema) return
+
+    const refPK = this.findPrimaryKey(refSchema)
+    const fkColName = `${toSnakeCase(fieldName)}_${toSnakeCase(refPK.name)}`
+    const fkColType = serialToIntegerType(refPK.pgType)
+
+    columns.push({
+      name: fkColName,
+      pgType: fkColType,
+      notNull: fieldDef.required,
+      unique: fieldDef.unique,
+      primaryKey: false,
+      autoIncrement: false,
+      index: true,
+      sensitive: fieldDef.sensitive,
+      isArray: false,
+      arrayDimensions: 1,
+    })
+
+    foreignKeys.push({
+      columns: [fkColName],
+      referencedTable: toSnakeCase(fieldDef.references!),
+      referencedColumns: [toSnakeCase(refPK.name)],
+      onDelete: fieldDef.required ? 'RESTRICT' : 'SET NULL',
+      onUpdate: 'CASCADE',
+    })
+
+    indexes.push({ columns: [fkColName], unique: false })
+  }
+
+  /**
+   * Add timestamp columns per archetype rules, skipping any already present.
+   */
+  private addTimestamps(schema: SchemaDefinition, columns: ColumnDefinition[]): void {
+    const rules = TIMESTAMP_RULES[schema.archetype]
+    if (!rules) return
+
+    const existing = new Set(columns.map(c => c.name))
+
+    if (rules.created_at && !existing.has('created_at')) {
+      columns.push(this.makeTimestampColumn('created_at', true))
+    }
+    if (rules.updated_at && !existing.has('updated_at')) {
+      columns.push(this.makeTimestampColumn('updated_at', true))
+    }
+    if (rules.deleted_at && !existing.has('deleted_at')) {
+      columns.push(this.makeTimestampColumn('deleted_at', false))
+    }
+  }
+
+  /**
+   * Assign default values to NOT NULL columns that lack one.
+   * FK columns are excluded — they must never receive automatic defaults.
+   */
+  private applyNotNullDefaults(
+    columns: ColumnDefinition[],
+    foreignKeys: ForeignKeyConstraint[]
+  ): void {
+    const fkColumns = new Set(foreignKeys.flatMap(fk => fk.columns))
+
+    for (const col of columns) {
+      if (!col.notNull) continue
+      if (col.defaultValue !== undefined) continue
+      if (col.autoIncrement) continue
+      if (fkColumns.has(col.name)) continue
+
+      const pgType = typeof col.pgType === 'string' ? col.pgType : null
+      if (!pgType) continue
+
+      const def = this.inferDefault(pgType)
+      if (def) col.defaultValue = def
+    }
+  }
+
+  /**
+   * Infer a sensible default for a given PostgreSQL type.
+   */
+  private inferDefault(pgType: string): DefaultValue | undefined {
+    switch (pgType) {
+      case 'uuid':
+        return { kind: 'expression', sql: 'gen_random_uuid()' }
+      case 'timestamp':
+      case 'timestamptz':
+        return { kind: 'expression', sql: 'CURRENT_TIMESTAMP' }
+      case 'boolean':
+        return { kind: 'literal', value: false }
+      case 'smallint':
+      case 'integer':
+      case 'bigint':
+      case 'real':
+      case 'double_precision':
+      case 'decimal':
+      case 'numeric':
+      case 'money':
+        return { kind: 'literal', value: 0 }
+      case 'varchar':
+      case 'character_varying':
+      case 'char':
+      case 'character':
+      case 'text':
+        return { kind: 'literal', value: '' }
+      case 'json':
+      case 'jsonb':
+        return { kind: 'literal', value: '{}' }
+      default:
+        return undefined
+    }
+  }
+
+  // --- Helpers ---
+
+  /**
+   * Find the primary key of a schema. Falls back to the auto-generated default.
+   */
+  private findPrimaryKey(schema: SchemaDefinition): PKInfo {
+    for (const [fieldName, fieldDef] of Object.entries(schema.fields)) {
+      if (fieldDef.primaryKey) {
+        return { name: fieldName, pgType: fieldDef.pgType }
+      }
+    }
+    return { name: 'id', pgType: 'serial' }
+  }
+
+  /**
+   * Convert a FieldDefinition to a ColumnDefinition.
+   */
+  private fieldToColumn(name: string, fieldDef: FieldDefinition): ColumnDefinition {
+    return {
+      name,
+      pgType: fieldDef.pgType,
+      notNull: fieldDef.required || fieldDef.primaryKey,
+      defaultValue:
+        fieldDef.defaultValue !== undefined
+          ? { kind: 'literal', value: fieldDef.defaultValue as string | number | boolean | null }
+          : undefined,
+      unique: fieldDef.unique,
+      primaryKey: fieldDef.primaryKey,
+      autoIncrement: isSerial(fieldDef.pgType),
+      index: fieldDef.index,
+      sensitive: fieldDef.sensitive,
+      isArray: fieldDef.isArray,
+      arrayDimensions: fieldDef.arrayDimensions,
+      length: fieldDef.length,
+      precision: fieldDef.precision,
+      scale: fieldDef.scale,
+      isUlid: fieldDef.isUlid,
+    }
+  }
+
+  /**
+   * Create a timestamp column definition.
+   */
+  private makeTimestampColumn(name: string, notNull: boolean): ColumnDefinition {
+    return {
+      name,
+      pgType: 'timestamptz',
+      notNull,
+      defaultValue: notNull ? { kind: 'expression', sql: 'CURRENT_TIMESTAMP' } : undefined,
+      unique: false,
+      primaryKey: false,
+      autoIncrement: false,
+      index: false,
+      sensitive: false,
+      isArray: false,
+      arrayDimensions: 1,
+    }
+  }
+
+  /**
+   * Collect all enum definitions from all schemas, deduped by name.
+   */
+  private collectEnums(): EnumDefinition[] {
+    const enums: EnumDefinition[] = []
+    const seen = new Set<string>()
+
+    for (const schema of this.schemas.values()) {
+      for (const fieldDef of Object.values(schema.fields)) {
+        if (isCustomType(fieldDef.pgType) && fieldDef.pgType.values?.length) {
+          const enumName = fieldDef.pgType.name
+          if (enumName && !seen.has(enumName)) {
+            seen.add(enumName)
+            enums.push({ name: enumName, values: fieldDef.pgType.values })
+          }
+        }
+      }
+    }
+
+    return enums
+  }
+}
+
+function isCustomType(pgType: unknown): pgType is PostgreSQLCustomType {
+  return typeof pgType === 'object' && pgType !== null && (pgType as any).type === 'custom'
+}
+
+function isSerial(pgType: PostgreSQLType): boolean {
+  return pgType === 'serial' || pgType === 'bigserial' || pgType === 'smallserial'
+}

package/src/schema/type_builder.ts

@@ -0,0 +1,115 @@
+import type { PostgreSQLCustomType } from './postgres'
+import FieldBuilder from './field_builder'
+
+/**
+ * Type builder for schema field definitions.
+ *
+ * Provides factory methods for every PostgreSQL data type.
+ * Each method returns a {@link FieldBuilder} with the correct pgType pre-configured.
+ *
+ * @example
+ * import { t } from '@stravigor/database/schema'
+ * t.varchar(255).email().unique().required()
+ * t.integer().default(0)
+ * t.jsonb().nullable()
+ */
+const t = {
+  // --- Numeric Types ---
+  smallint: () => new FieldBuilder('smallint'),
+  integer: () => new FieldBuilder('integer'),
+  bigint: () => new FieldBuilder('bigint'),
+  decimal: (precision?: number, scale?: number) =>
+    new FieldBuilder('decimal', { precision, scale }),
+  numeric: (precision?: number, scale?: number) =>
+    new FieldBuilder('numeric', { precision, scale }),
+  real: () => new FieldBuilder('real'),
+  double: () => new FieldBuilder('double_precision'),
+  smallserial: () => new FieldBuilder('smallserial'),
+  serial: () => new FieldBuilder('serial'),
+  bigserial: () => new FieldBuilder('bigserial'),
+
+  // --- Monetary ---
+  money: () => new FieldBuilder('money'),
+
+  // --- Character Types ---
+  varchar: (length?: number) => new FieldBuilder('varchar', { length }),
+  /** Alias for {@link varchar}. */
+  string: (length?: number) => new FieldBuilder('varchar', { length }),
+  char: (length?: number) => new FieldBuilder('char', { length }),
+  text: () => new FieldBuilder('text'),
+
+  // --- Binary ---
+  bytea: () => new FieldBuilder('bytea'),
+
+  // --- Date/Time ---
+  timestamp: () => new FieldBuilder('timestamp'),
+  timestamptz: () => new FieldBuilder('timestamptz'),
+  date: () => new FieldBuilder('date'),
+  time: () => new FieldBuilder('time'),
+  timetz: () => new FieldBuilder('timetz'),
+  interval: () => new FieldBuilder('interval'),
+
+  // --- Boolean ---
+  boolean: () => new FieldBuilder('boolean'),
+
+  // --- UUID ---
+  uuid: () => new FieldBuilder('uuid'),
+
+  // --- Geometric Types ---
+  point: () => new FieldBuilder('point'),
+  line: () => new FieldBuilder('line'),
+  lseg: () => new FieldBuilder('lseg'),
+  box: () => new FieldBuilder('box'),
+  path: () => new FieldBuilder('path'),
+  polygon: () => new FieldBuilder('polygon'),
+  circle: () => new FieldBuilder('circle'),
+
+  // --- Network Address Types ---
+  inet: () => new FieldBuilder('inet'),
+  cidr: () => new FieldBuilder('cidr'),
+  macaddr: () => new FieldBuilder('macaddr'),
+  macaddr8: () => new FieldBuilder('macaddr8'),
+
+  // --- Bit String Types ---
+  bit: (length?: number) => new FieldBuilder('bit', { length }),
+  varbit: (length?: number) => new FieldBuilder('bit_varying', { length }),
+
+  // --- Text Search Types ---
+  tsvector: () => new FieldBuilder('tsvector'),
+  tsquery: () => new FieldBuilder('tsquery'),
+
+  // --- JSON Types ---
+  json: () => new FieldBuilder('json'),
+  jsonb: () => new FieldBuilder('jsonb'),
+
+  // --- Range Types ---
+  int4range: () => new FieldBuilder('int4range'),
+  int8range: () => new FieldBuilder('int8range'),
+  numrange: () => new FieldBuilder('numrange'),
+  tsrange: () => new FieldBuilder('tsrange'),
+  tstzrange: () => new FieldBuilder('tstzrange'),
+  daterange: () => new FieldBuilder('daterange'),
+
+  // --- XML ---
+  xml: () => new FieldBuilder('xml'),
+
+  // --- Enum ---
+  /** Create a PostgreSQL enum type with the given allowed values. */
+  enum: (values: string[]) => {
+    const customType: PostgreSQLCustomType = { type: 'custom', name: '', values }
+    return new FieldBuilder(customType, { enumValues: values })
+  },
+
+  /** Foreign key reference to another schema. Column type defaults to UUID. */
+  reference: (table: string) => new FieldBuilder('uuid', { references: table }),
+
+  /** ULID (Universally Unique Lexicographically Sortable Identifier) stored as char(26). */
+  ulid: () => {
+    const builder = new FieldBuilder('char', { length: 26 })
+    // Mark this as a ULID type internally
+    ;(builder as any)._isUlid = true
+    return builder
+  },
+}
+
+export default t

package/src/schema/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Schema DSL Types - Complete PostgreSQL type support
+ */
+import type { FieldDefinition } from './field_definition'
+import type FieldBuilder from './field_builder'
+
+export enum Archetype {
+  Entity = 'entity',
+  Component = 'component',
+  Attribute = 'attribute',
+  Association = 'association',
+  Event = 'event',
+  Reference = 'reference',
+  Configuration = 'configuration',
+  Contribution = 'contribution',
+}
+
+/** The input shape that users pass to {@link defineSchema}. */
+export interface SchemaInput {
+  archetype?: Archetype
+  parents?: string[]
+  associates?: string[]
+  as?: Record<string, string>
+  fields: Record<string, FieldBuilder>
+}
+
+/** The resolved schema stored in the registry. */
+export interface SchemaDefinition {
+  name: string
+  archetype: Archetype
+  parents?: string[]
+  associates?: string[]
+  as?: Record<string, string>
+  fields: Record<string, FieldDefinition>
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}