@strav/database 0.1.0

package/src/orm/decorators.ts

@@ -0,0 +1,290 @@
+import 'reflect-metadata'
+import EncryptionManager from '@stravigor/kernel/encryption/encryption_manager'
+
+const PRIMARY_KEY = Symbol('orm:primary')
+const REFERENCE_KEY = Symbol('orm:references')
+const REFERENCE_META_KEY = Symbol('orm:reference_meta')
+const ASSOCIATE_KEY = Symbol('orm:associates')
+const CAST_KEY = Symbol('orm:casts')
+const ENCRYPT_KEY = Symbol('orm:encrypted')
+const ULID_KEY = Symbol('orm:ulid')
+
+// ---------------------------------------------------------------------------
+// @primary
+// ---------------------------------------------------------------------------
+
+/**
+ * Property decorator that marks a field as the primary key.
+ * BaseModel reads this metadata to build queries with the correct PK column.
+ */
+export function primary(target: any, propertyKey: string) {
+  Reflect.defineMetadata(PRIMARY_KEY, propertyKey, target.constructor)
+}
+
+/** Get the primary key property name (camelCase) for a model class. Defaults to 'id'. */
+export function getPrimaryKey(target: Function): string {
+  return Reflect.getMetadata(PRIMARY_KEY, target) ?? 'id'
+}
+
+// ---------------------------------------------------------------------------
+// @reference
+// ---------------------------------------------------------------------------
+
+export interface ReferenceOptions {
+  model: string
+  foreignKey: string
+  targetPK: string
+}
+
+export interface ReferenceMetadata extends ReferenceOptions {
+  property: string
+}
+
+/**
+ * Property decorator that marks a field as a reference object.
+ * Reference properties are excluded from database persistence (dehydrate).
+ *
+ * Can be used as a bare decorator or with options for load() support.
+ *
+ * @example
+ * // Bare (backward-compatible):
+ * @reference
+ * declare widget: Widget
+ *
+ * // With options (supports load()):
+ * @reference({ model: 'User', foreignKey: 'userId', targetPK: 'id' })
+ * declare user: User
+ */
+export function reference(targetOrOptions: any, propertyKey?: string): any {
+  if (propertyKey !== undefined) {
+    // Bare decorator: @reference
+    addReferenceProperty(targetOrOptions, propertyKey)
+    return
+  }
+
+  // Factory: @reference({ model, foreignKey, targetPK })
+  const options = targetOrOptions as ReferenceOptions
+  return function (target: any, propertyKey: string) {
+    addReferenceProperty(target, propertyKey)
+
+    const metas: ReferenceMetadata[] = [
+      ...(Reflect.getMetadata(REFERENCE_META_KEY, target.constructor) ?? []),
+    ]
+    metas.push({ property: propertyKey, ...options })
+    Reflect.defineMetadata(REFERENCE_META_KEY, metas, target.constructor)
+  }
+}
+
+function addReferenceProperty(target: any, propertyKey: string): void {
+  const refs: string[] = [...(Reflect.getMetadata(REFERENCE_KEY, target.constructor) ?? [])]
+  refs.push(propertyKey)
+  Reflect.defineMetadata(REFERENCE_KEY, refs, target.constructor)
+}
+
+/** Get the list of reference property names for a model class. */
+export function getReferences(target: Function): string[] {
+  return Reflect.getMetadata(REFERENCE_KEY, target) ?? []
+}
+
+/** Get rich @reference metadata (only present when options were used). */
+export function getReferenceMeta(target: Function): ReferenceMetadata[] {
+  return Reflect.getMetadata(REFERENCE_META_KEY, target) ?? []
+}
+
+// ---------------------------------------------------------------------------
+// @associate
+// ---------------------------------------------------------------------------
+
+export interface AssociateOptions {
+  through: string
+  foreignKey: string
+  otherKey: string
+  model: string
+  targetPK: string
+}
+
+export interface AssociateMetadata extends AssociateOptions {
+  property: string
+}
+
+/**
+ * Property decorator that marks a field as a many-to-many association.
+ * Associates are loaded via pivot table queries and excluded from dehydrate.
+ *
+ * @example
+ * @associate({ through: 'team_user', foreignKey: 'team_id', otherKey: 'user_pid', model: 'User', targetPK: 'pid' })
+ * declare members: User[]
+ */
+export function associate(options: AssociateOptions) {
+  return function (target: any, propertyKey: string) {
+    const assocs: AssociateMetadata[] = [
+      ...(Reflect.getMetadata(ASSOCIATE_KEY, target.constructor) ?? []),
+    ]
+    assocs.push({ property: propertyKey, ...options })
+    Reflect.defineMetadata(ASSOCIATE_KEY, assocs, target.constructor)
+  }
+}
+
+/** Get all @associate metadata for a model class. */
+export function getAssociates(target: Function): AssociateMetadata[] {
+  return Reflect.getMetadata(ASSOCIATE_KEY, target) ?? []
+}
+
+// ---------------------------------------------------------------------------
+// @cast
+// ---------------------------------------------------------------------------
+
+export interface CastDefinition {
+  get: (dbValue: unknown) => unknown
+  set: (appValue: unknown) => unknown
+}
+
+const BUILT_IN_CASTS: Record<string, CastDefinition> = {
+  json: {
+    get: v => (typeof v === 'string' ? JSON.parse(v) : v),
+    set: v => JSON.stringify(v),
+  },
+  boolean: {
+    get: v => {
+      if (typeof v === 'boolean') return v
+      if (typeof v === 'number') return v !== 0
+      if (typeof v === 'string') return v === 'true' || v === '1'
+      return Boolean(v)
+    },
+    set: v => Boolean(v),
+  },
+  number: {
+    get: v => Number(v),
+    set: v => Number(v),
+  },
+  integer: {
+    get: v => Math.trunc(Number(v)),
+    set: v => Math.trunc(Number(v)),
+  },
+  string: {
+    get: v => String(v),
+    set: v => String(v),
+  },
+  bigint: {
+    get: v => {
+      if (typeof v === 'bigint')
+        return v <= Number.MAX_SAFE_INTEGER && v >= Number.MIN_SAFE_INTEGER ? Number(v) : String(v)
+      return Number(v)
+    },
+    set: v => (typeof v === 'bigint' ? String(v) : v),
+  },
+}
+
+/**
+ * Property decorator that defines type casting between DB and application values.
+ * Applied automatically during hydration (DB → model) and dehydration (model → DB).
+ *
+ * @example
+ * // Bare (defaults to JSON):
+ * @cast
+ * declare state: CanvasState
+ *
+ * // Named built-in type ('json' | 'boolean' | 'number' | 'integer' | 'string'):
+ * @cast('json')
+ * declare metadata: SomeType
+ *
+ * // Custom get/set:
+ * @cast({ get: (v) => new Money(v as number), set: (v: Money) => v.toCents() })
+ * declare price: Money
+ */
+export function cast(targetOrTypeOrDef: any, propertyKey?: string): any {
+  if (propertyKey !== undefined) {
+    // Bare decorator: @cast
+    addCastMetadata(targetOrTypeOrDef, propertyKey, BUILT_IN_CASTS.json!)
+    return
+  }
+
+  // Factory with string type: @cast('json')
+  if (typeof targetOrTypeOrDef === 'string') {
+    const castDef = BUILT_IN_CASTS[targetOrTypeOrDef]
+    if (!castDef) {
+      throw new Error(
+        `Unknown cast type "${targetOrTypeOrDef}". Available: ${Object.keys(BUILT_IN_CASTS).join(', ')}`
+      )
+    }
+    return function (target: any, propertyKey: string) {
+      addCastMetadata(target, propertyKey, castDef)
+    }
+  }
+
+  // Factory with custom { get, set }: @cast({ get: ..., set: ... })
+  const def = targetOrTypeOrDef as CastDefinition
+  return function (target: any, propertyKey: string) {
+    addCastMetadata(target, propertyKey, def)
+  }
+}
+
+function addCastMetadata(target: any, propertyKey: string, castDef: CastDefinition): void {
+  const casts = new Map<string, CastDefinition>(
+    Reflect.getMetadata(CAST_KEY, target.constructor) ?? []
+  )
+  casts.set(propertyKey, castDef)
+  Reflect.defineMetadata(CAST_KEY, casts, target.constructor)
+}
+
+/** Get all @cast metadata for a model class as a Map<propertyName, CastDefinition>. */
+export function getCasts(target: Function): Map<string, CastDefinition> {
+  return Reflect.getMetadata(CAST_KEY, target) ?? new Map()
+}
+
+// ---------------------------------------------------------------------------
+// @encrypt
+// ---------------------------------------------------------------------------
+
+/**
+ * Property decorator that encrypts a field before database storage and
+ * decrypts it on hydration. Uses AES-256-GCM via EncryptionManager.
+ *
+ * The database column **must** be TEXT to avoid truncating the encrypted payload.
+ *
+ * Internally registers a CastDefinition so hydrateFrom/dehydrate handle it
+ * automatically. Encrypted fields are excluded from toJSON() output.
+ *
+ * @example
+ * @encrypt
+ * declare ssn: string
+ */
+export function encrypt(target: any, propertyKey: string) {
+  addCastMetadata(target, propertyKey, {
+    get: v => EncryptionManager.decrypt(v as string),
+    set: v => EncryptionManager.encrypt(String(v)),
+  })
+
+  const fields: string[] = [...(Reflect.getMetadata(ENCRYPT_KEY, target.constructor) ?? [])]
+  fields.push(propertyKey)
+  Reflect.defineMetadata(ENCRYPT_KEY, fields, target.constructor)
+}
+
+/** Get the list of @encrypt-decorated property names for a model class. */
+export function getEncrypted(target: Function): string[] {
+  return Reflect.getMetadata(ENCRYPT_KEY, target) ?? []
+}
+
+// ---------------------------------------------------------------------------
+// @ulid
+// ---------------------------------------------------------------------------
+
+/**
+ * Property decorator that marks a field as a ULID (Universally Unique
+ * Lexicographically Sortable Identifier). ULIDs are auto-generated during
+ * insert if the field value is not set.
+ *
+ * @example
+ * @ulid
+ * declare id: string
+ */
+export function ulid(target: any, propertyKey: string) {
+  const fields: string[] = [...(Reflect.getMetadata(ULID_KEY, target.constructor) ?? [])]
+  fields.push(propertyKey)
+  Reflect.defineMetadata(ULID_KEY, fields, target.constructor)
+}
+
+/** Get the list of @ulid-decorated property names for a model class. */
+export function getUlids(target: Function): string[] {
+  return Reflect.getMetadata(ULID_KEY, target) ?? []
+}

package/src/orm/index.ts

@@ -0,0 +1,3 @@
+export { default as BaseModel } from './base_model'
+export { primary, reference, associate, cast, encrypt, ulid } from './decorators'
+export type { CastDefinition } from './decorators'

package/src/providers/database_provider.ts

@@ -0,0 +1,25 @@
+import ServiceProvider from '@stravigor/kernel/core/service_provider'
+import type Application from '@stravigor/kernel/core/application'
+import Database from '../database/database'
+
+export default class DatabaseProvider extends ServiceProvider {
+  readonly name = 'database'
+  override readonly dependencies = ['config']
+
+  private db: Database | null = null
+
+  override register(app: Application): void {
+    app.singleton(Database)
+  }
+
+  override boot(app: Application): void {
+    this.db = app.resolve(Database)
+  }
+
+  override async shutdown(): Promise<void> {
+    if (this.db) {
+      await this.db.close()
+      this.db = null
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1 @@
+export { default as DatabaseProvider } from './database_provider'

package/src/schema/database_representation.ts

@@ -0,0 +1,124 @@
+import type { PostgreSQLType } from './postgres'
+import type { Archetype } from './types'
+
+/**
+ * Represents the full database schema derived from all registered SchemaDefinitions.
+ * Contains all enum types and table definitions in dependency order.
+ */
+export interface DatabaseRepresentation {
+  /** PostgreSQL enum types that must be created before tables. */
+  enums: EnumDefinition[]
+  /** Table definitions in dependency order. */
+  tables: TableDefinition[]
+}
+
+/**
+ * A PostgreSQL CREATE TYPE ... AS ENUM definition.
+ */
+export interface EnumDefinition {
+  /** Enum type name (e.g. 'order_status'). */
+  name: string
+  /** Allowed values. */
+  values: string[]
+}
+
+/**
+ * A PostgreSQL table definition.
+ */
+export interface TableDefinition {
+  /** Table name in snake_case, not pluralized. */
+  name: string
+  /** The archetype this table was derived from (absent when introspected from DB). */
+  archetype?: Archetype
+  /** Ordered list of columns. */
+  columns: ColumnDefinition[]
+  /** Primary key constraint, or null for associations. */
+  primaryKey: PrimaryKeyConstraint | null
+  /** Foreign key constraints. */
+  foreignKeys: ForeignKeyConstraint[]
+  /** Unique constraints (beyond individual column UNIQUE). */
+  uniqueConstraints: UniqueConstraint[]
+  /** Index definitions. */
+  indexes: IndexDefinition[]
+}
+
+/**
+ * A single column in a table.
+ */
+export interface ColumnDefinition {
+  /** Column name in snake_case. */
+  name: string
+  /** PostgreSQL column type. */
+  pgType: PostgreSQLType
+  /** Whether the column is NOT NULL. */
+  notNull: boolean
+  /** Default value (literal or SQL expression). */
+  defaultValue?: DefaultValue
+  /** Whether the column has a UNIQUE constraint. */
+  unique: boolean
+  /** Whether the column is part of the primary key. */
+  primaryKey: boolean
+  /** Whether the column is auto-incrementing (serial). */
+  autoIncrement: boolean
+  /** Whether the column should be indexed. */
+  index: boolean
+  /** Whether the column contains sensitive data (app-level, absent when introspected). */
+  sensitive?: boolean
+  /** Whether this is an array column. */
+  isArray: boolean
+  /** Array dimensions. */
+  arrayDimensions: number
+  /** Max length for varchar/char. */
+  length?: number
+  /** Precision for decimal/numeric. */
+  precision?: number
+  /** Scale for decimal/numeric. */
+  scale?: number
+  /** Whether this field is a ULID (stored as char(26)). */
+  isUlid?: boolean
+}
+
+/**
+ * A default value for a column — either a literal value or a SQL expression.
+ */
+export type DefaultValue =
+  | { kind: 'literal'; value: string | number | boolean | null }
+  | { kind: 'expression'; sql: string }
+
+/**
+ * A primary key constraint (single or composite).
+ */
+export interface PrimaryKeyConstraint {
+  columns: string[]
+}
+
+/**
+ * A foreign key constraint.
+ */
+export interface ForeignKeyConstraint {
+  /** Column(s) in this table. */
+  columns: string[]
+  /** Referenced table. */
+  referencedTable: string
+  /** Referenced column(s). */
+  referencedColumns: string[]
+  /** ON DELETE behavior. */
+  onDelete: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION'
+  /** ON UPDATE behavior. */
+  onUpdate: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION'
+}
+
+/**
+ * A unique constraint across one or more columns.
+ */
+export interface UniqueConstraint {
+  columns: string[]
+}
+
+/**
+ * An index definition.
+ */
+export interface IndexDefinition {
+  columns: string[]
+  unique: boolean
+}

package/src/schema/define_association.ts

@@ -0,0 +1,60 @@
+import { Archetype } from './types'
+import type { SchemaDefinition } from './types'
+import type FieldBuilder from './field_builder'
+import defineSchema from './define_schema'
+
+interface AssociationOptions {
+  as?: Record<string, string>
+  fields?: Record<string, FieldBuilder>
+}
+
+/**
+ * Define an association (many-to-many junction) schema between two entities.
+ *
+ * Automatically sets archetype to `'association'`, generates the table name
+ * as `{entityA}_{entityB}`, and records the two associates.
+ *
+ * Only specify additional pivot fields — the FK columns to both entities
+ * are injected automatically by the {@link RepresentationBuilder}.
+ *
+ * @example
+ * // With named properties on each entity model:
+ * export default defineAssociation(['team', 'user'], {
+ *   as: { team: 'members', user: 'teams' },
+ *   fields: {
+ *     role: t.enum(['admin', 'developer', 'tester']),
+ *   },
+ * })
+ *
+ * // Legacy shorthand (fields only, no model properties):
+ * export default defineAssociation(['team', 'user'], {
+ *   role: t.enum(['admin', 'developer', 'tester']),
+ * })
+ */
+export default function defineAssociation(
+  entities: [string, string],
+  options: AssociationOptions | Record<string, FieldBuilder> = {}
+): SchemaDefinition {
+  const [entityA, entityB] = entities
+
+  let fields: Record<string, FieldBuilder>
+  let as: Record<string, string> | undefined
+
+  if (isAssociationOptions(options)) {
+    fields = options.fields ?? {}
+    as = options.as
+  } else {
+    fields = options
+  }
+
+  return defineSchema(`${entityA}_${entityB}`, {
+    archetype: Archetype.Association,
+    associates: [entityA, entityB],
+    as,
+    fields,
+  })
+}
+
+function isAssociationOptions(obj: unknown): obj is AssociationOptions {
+  return typeof obj === 'object' && obj !== null && ('as' in obj || 'fields' in obj)
+}

package/src/schema/define_schema.ts

@@ -0,0 +1,46 @@
+import { Archetype } from './types'
+import type { SchemaInput, SchemaDefinition } from './types'
+import type { FieldDefinition } from './field_definition'
+import type { PostgreSQLCustomType } from './postgres'
+
+/**
+ * Define a data schema for the application.
+ *
+ * Resolves all {@link FieldBuilder} instances into {@link FieldDefinition}s,
+ * assigns proper enum names, and returns a {@link SchemaDefinition}.
+ *
+ * @example
+ * export default defineSchema('user', {
+ *   archetype: Archetype.Entity,
+ *   fields: {
+ *     email: t.varchar().email().unique().required(),
+ *     role:  t.enum(['user', 'admin']).default('user'),
+ *   },
+ * })
+ */
+export default function defineSchema(name: string, input: SchemaInput): SchemaDefinition {
+  const fields: Record<string, FieldDefinition> = {}
+
+  for (const [fieldName, builder] of Object.entries(input.fields)) {
+    const def = builder.toDefinition()
+
+    if (isCustomType(def.pgType) && def.pgType.values?.length) {
+      def.pgType = { ...def.pgType, name: `${name}_${fieldName}` }
+    }
+
+    fields[fieldName] = def
+  }
+
+  return {
+    name,
+    archetype: input.archetype ?? Archetype.Entity,
+    parents: input.parents,
+    associates: input.associates,
+    as: input.as,
+    fields,
+  }
+}
+
+function isCustomType(pgType: unknown): pgType is PostgreSQLCustomType {
+  return typeof pgType === 'object' && pgType !== null && (pgType as any).type === 'custom'
+}

package/src/schema/domain_discovery.ts

@@ -0,0 +1,83 @@
+import { readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/**
+ * Discovers available domains by scanning the database/schemas directory.
+ *
+ * Domains are subdirectories under database/schemas/.
+ * The 'public' domain always exists (system schemas).
+ * Other domains represent business domains (tenant, factory, marketing, etc.).
+ */
+
+/** Validate that a domain name is safe for use in PostgreSQL table names */
+export function validateDomainName(domainName: string): void {
+  // Allow alphanumeric characters and underscores only
+  if (!/^[a-z][a-z0-9_]*$/i.test(domainName)) {
+    throw new Error(`Invalid domain name: ${domainName}. Must start with a letter and contain only letters, numbers, and underscores.`)
+  }
+
+  // Prevent SQL injection and reserved words
+  const reservedWords = ['public', 'information_schema', 'pg_catalog', 'pg_toast']
+  if (reservedWords.includes(domainName.toLowerCase()) && domainName.toLowerCase() !== 'public') {
+    throw new Error(`Domain name '${domainName}' is reserved and cannot be used.`)
+  }
+}
+
+/** Discover available domains from the filesystem */
+export function discoverDomains(schemasPath: string = 'database/schemas'): string[] {
+  const basePath = resolve(schemasPath)
+
+  let entries: string[]
+  try {
+    entries = readdirSync(basePath, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name)
+  } catch {
+    // If schemas directory doesn't exist, return just public
+    return ['public']
+  }
+
+  // Validate all discovered domain names
+  for (const domainName of entries) {
+    validateDomainName(domainName)
+  }
+
+  // Ensure public is always included and comes first
+  const domains = new Set(entries)
+  domains.add('public')
+
+  // Sort with public first, then alphabetically
+  return Array.from(domains).sort((a, b) => {
+    if (a === 'public') return -1
+    if (b === 'public') return 1
+    return a.localeCompare(b)
+  })
+}
+
+/** Check if a specific domain exists */
+export function domainExists(domainName: string, schemasPath: string = 'database/schemas'): boolean {
+  validateDomainName(domainName)
+
+  if (domainName === 'public') {
+    return true // public always exists conceptually
+  }
+
+  const domainPath = join(resolve(schemasPath), domainName)
+  try {
+    const stat = readdirSync(domainPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Get the migration tracking table name for a domain */
+export function getMigrationTableName(domain: string): string {
+  validateDomainName(domain)
+
+  if (domain === 'public') {
+    return '_strav_migrations'
+  }
+
+  return `_strav_${domain}_migrations`
+}