@avelonjs/conformance 0.1.0

package/src/fakes/database.ts

@@ -0,0 +1,612 @@
+import {
+  Conflict,
+  Invalid,
+  type DatabaseDriver,
+  type DatabaseTransaction,
+  type MigrationPlan,
+  type MigrationStatus,
+  type OrderTerm,
+  type Predicate,
+  type QueryIR,
+  type QueryResult,
+  type RelationLoad,
+  type TransactionSurface,
+} from '@avelonjs/core'
+
+const capabilities = {
+  transactions: true,
+  rowSecurity: false,
+  maxRelationDepth: 2,
+  fullTextSearch: false,
+  upsert: true,
+  returning: true,
+  windowFunctions: false,
+  jsonOperators: false,
+} as const
+
+const schema = {
+  assay_users: ['id', 'email', 'name', 'age', 'nickname'],
+  assay_profiles: ['id', 'user_id', 'bio'],
+  assay_posts: ['id', 'user_id', 'title', 'score', 'published_at'],
+  assay_comments: ['id', 'post_id', 'body', 'position'],
+  assay_reactions: ['id', 'comment_id', 'kind'],
+  users: ['id', 'email', 'name'],
+  posts: [
+    'id',
+    'user_id',
+    'title',
+    'body',
+    'published_at',
+    'created_at',
+    'updated_at',
+    'deleted_at',
+  ],
+  subscribers: ['id', 'email', 'created_at'],
+} as const
+
+const uniqueColumns = {
+  assay_users: [['id'], ['email']],
+  assay_profiles: [['id'], ['user_id']],
+  assay_posts: [['id']],
+  assay_comments: [['id']],
+  assay_reactions: [['id']],
+  users: [['id'], ['email']],
+  posts: [['id']],
+  subscribers: [['id'], ['email']],
+} as const
+
+type TableName = keyof typeof schema
+type Row = Record<string, unknown>
+type TruthValue = boolean | null
+
+const tableNames = Object.keys(schema) as TableName[]
+
+function invalid(message: string, field: string, detail: string): Invalid {
+  return new Invalid(message, { metadata: { fields: { [field]: [detail] } } })
+}
+
+function emptyTables(): Record<TableName, Row[]> {
+  return Object.fromEntries(tableNames.map((table) => [table, [] as Row[]])) as Record<
+    TableName,
+    Row[]
+  >
+}
+
+function isTableName(table: string): table is TableName {
+  return Object.hasOwn(schema, table)
+}
+
+function hasColumn(table: TableName, column: string): boolean {
+  return schema[table].some((candidate) => candidate === column)
+}
+
+function cloneRow(row: Row): Row {
+  return structuredClone(row)
+}
+
+function compare(left: unknown, op: QueryIRCompareOp, right: unknown): TruthValue {
+  if (left === null || left === undefined || right === null || right === undefined) return null
+
+  switch (op) {
+    case '=':
+      return left === right
+    case '!=':
+      return left !== right
+    case '<':
+      return relationalCompare(left, right, (result) => result < 0)
+    case '<=':
+      return relationalCompare(left, right, (result) => result <= 0)
+    case '>':
+      return relationalCompare(left, right, (result) => result > 0)
+    case '>=':
+      return relationalCompare(left, right, (result) => result >= 0)
+    case 'like':
+      return like(left, right, false)
+    case 'ilike':
+      return like(left, right, true)
+  }
+}
+
+type QueryIRCompareOp = Extract<Predicate, { kind: 'compare' }>['op']
+
+function relationalCompare(
+  left: unknown,
+  right: unknown,
+  predicate: (result: number) => boolean,
+): boolean {
+  if (typeof left === 'number' && typeof right === 'number') return predicate(left - right)
+  if (typeof left === 'string' && typeof right === 'string')
+    return predicate(left.localeCompare(right))
+  return false
+}
+
+function like(left: unknown, right: unknown, insensitive: boolean): boolean {
+  if (typeof left !== 'string' || typeof right !== 'string') return false
+  const escaped = right.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = `^${escaped.replaceAll('%', '.*').replaceAll('_', '.')}$`
+  return new RegExp(pattern, insensitive ? 'i' : undefined).test(left)
+}
+
+function not(value: TruthValue): TruthValue {
+  return value === null ? null : !value
+}
+
+function and(values: readonly TruthValue[]): TruthValue {
+  if (values.includes(false)) return false
+  if (values.includes(null)) return null
+  return true
+}
+
+function or(values: readonly TruthValue[]): TruthValue {
+  if (values.includes(true)) return true
+  if (values.includes(null)) return null
+  return false
+}
+
+function evaluate(row: Row, predicate: Predicate): TruthValue {
+  switch (predicate.kind) {
+    case 'const':
+      return predicate.value
+    case 'compare':
+      return compare(row[predicate.column], predicate.op, predicate.value)
+    case 'null': {
+      const result = row[predicate.column] === null || row[predicate.column] === undefined
+      return predicate.negated ? !result : result
+    }
+    case 'in': {
+      if (predicate.values.length === 0) return predicate.negated
+      const value = row[predicate.column]
+      if (value === null || value === undefined) return null
+      if (predicate.values.some((candidate) => candidate === value)) return !predicate.negated
+      const result: TruthValue = predicate.values.some((candidate) => candidate === null)
+        ? null
+        : false
+      return predicate.negated ? not(result) : result
+    }
+    case 'and':
+      return and(predicate.predicates.map((entry) => evaluate(row, entry)))
+    case 'or':
+      return or(predicate.predicates.map((entry) => evaluate(row, entry)))
+    case 'not':
+      return not(evaluate(row, predicate.predicate))
+  }
+}
+
+function constant(predicate: Predicate): boolean | undefined {
+  switch (predicate.kind) {
+    case 'const':
+      return predicate.value
+    case 'in':
+      return predicate.values.length === 0 ? predicate.negated : undefined
+    case 'not': {
+      const value = constant(predicate.predicate)
+      return value === undefined ? undefined : !value
+    }
+    case 'and': {
+      const values = predicate.predicates.map(constant)
+      if (values.includes(false)) return false
+      return values.every((value) => value === true) ? true : undefined
+    }
+    case 'or': {
+      const values = predicate.predicates.map(constant)
+      if (values.includes(true)) return true
+      return values.every((value) => value === false) ? false : undefined
+    }
+    default:
+      return undefined
+  }
+}
+
+function isConstantFalse(query: QueryIR): boolean {
+  return [...query.where, ...(query.ward ? [query.ward] : [])].some(
+    (predicate) => constant(predicate) === false,
+  )
+}
+
+function validatePredicate(table: TableName, predicate: Predicate): void {
+  switch (predicate.kind) {
+    case 'compare':
+    case 'null':
+    case 'in':
+      validateColumn(table, predicate.column, 'predicate')
+      return
+    case 'and':
+    case 'or':
+      predicate.predicates.forEach((entry) => validatePredicate(table, entry))
+      return
+    case 'not':
+      validatePredicate(table, predicate.predicate)
+      return
+    case 'const':
+      return
+  }
+}
+
+function validateColumn(table: TableName, column: string, field: string): void {
+  if (!hasColumn(table, column)) {
+    throw invalid(`Unknown column ${column} on ${table}.`, field, `Unknown identifier: ${column}`)
+  }
+}
+
+function validateColumns(table: TableName, columns: readonly string[] | '*', field: string): void {
+  if (columns === '*') return
+  columns.forEach((column) => validateColumn(table, column, field))
+}
+
+function validateOrder(table: TableName, order: readonly OrderTerm[]): void {
+  order.forEach((term) => validateColumn(table, term.column, 'order'))
+}
+
+function validateRelation(parentTable: TableName, relation: RelationLoad, depth: number): void {
+  if (depth > capabilities.maxRelationDepth) {
+    throw invalid(
+      `Relation depth ${depth} exceeds the declared maximum.`,
+      'relations',
+      `Maximum relation depth is ${capabilities.maxRelationDepth}`,
+    )
+  }
+  if (!isTableName(relation.table)) {
+    throw invalid(`Unknown relation table ${relation.table}.`, 'relations', 'Unknown identifier')
+  }
+  const relatedTable = relation.table
+  validateColumn(parentTable, relation.localKey, 'relations')
+  validateColumn(relatedTable, relation.foreignKey, 'relations')
+  validateColumns(relatedTable, relation.select, 'relations')
+  validateOrder(relatedTable, relation.order)
+  if (relation.where) validatePredicate(relatedTable, relation.where)
+  if (relation.limit !== undefined && (!Number.isInteger(relation.limit) || relation.limit < 0)) {
+    throw invalid('Relation limit must be a non-negative integer.', 'relations', 'Invalid limit')
+  }
+  relation.relations.forEach((nested) => validateRelation(relatedTable, nested, depth + 1))
+}
+
+function validateValues(
+  table: TableName,
+  values: QueryIR['values'],
+): asserts values is Row | Row[] {
+  if (values === undefined || (Array.isArray(values) && values.length === 0)) {
+    throw invalid('Write operations require values.', 'values', 'Expected one or more rows')
+  }
+  const rows = Array.isArray(values) ? values : [values]
+  rows.forEach((row) =>
+    Object.keys(row).forEach((column) => validateColumn(table, column, 'values')),
+  )
+}
+
+function validateQuery(query: QueryIR): TableName {
+  if (!isTableName(query.table)) {
+    throw invalid(`Unknown table ${query.table}.`, 'table', 'Unknown identifier')
+  }
+  const table = query.table
+  validateColumns(table, query.select, 'select')
+  query.where.forEach((predicate) => validatePredicate(table, predicate))
+  if (query.ward) validatePredicate(table, query.ward)
+  validateOrder(table, query.order)
+  query.relations.forEach((relation) => {
+    validateRelation(table, relation, 1)
+  })
+  if (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit < 0)) {
+    throw invalid('Limit must be a non-negative integer.', 'limit', 'Invalid limit')
+  }
+  if (query.offset !== undefined && (!Number.isInteger(query.offset) || query.offset < 0)) {
+    throw invalid('Offset must be a non-negative integer.', 'offset', 'Invalid offset')
+  }
+
+  if (query.mode === 'count') {
+    const hasProjection = query.select === '*' || query.select.length > 0
+    if (
+      hasProjection ||
+      query.relations.length > 0 ||
+      query.order.length > 0 ||
+      query.limit !== undefined ||
+      query.offset !== undefined ||
+      query.returning !== undefined
+    ) {
+      throw invalid(
+        'Count queries cannot carry result shaping.',
+        'mode',
+        'Use an empty select, relations, and order with no limit, offset, or returning',
+      )
+    }
+  }
+
+  if (query.returning !== undefined) validateColumns(table, query.returning, 'returning')
+
+  if (query.mode === 'insert' || query.mode === 'update' || query.mode === 'upsert') {
+    validateValues(table, query.values)
+  }
+  if (query.mode === 'update' && Array.isArray(query.values)) {
+    throw invalid('Update values must be one object.', 'values', 'Expected one row')
+  }
+  if (query.mode === 'upsert') {
+    if (!query.conflict) {
+      throw invalid('Upsert requires a conflict target.', 'conflict', 'Required for upsert')
+    }
+    query.conflict.columns.forEach((column) => validateColumn(table, column, 'conflict'))
+    if (query.conflict.update !== '*') {
+      query.conflict.update.forEach((column) => validateColumn(table, column, 'conflict'))
+    }
+  }
+  return table
+}
+
+function matches(row: Row, query: Pick<QueryIR, 'where' | 'ward'>): boolean {
+  const predicates = query.ward ? [...query.where, query.ward] : query.where
+  return and(predicates.map((predicate) => evaluate(row, predicate))) === true
+}
+
+function compareRows(left: Row, right: Row, order: readonly OrderTerm[]): number {
+  for (const term of order) {
+    const leftValue = left[term.column]
+    const rightValue = right[term.column]
+    const leftNull = leftValue === null || leftValue === undefined
+    const rightNull = rightValue === null || rightValue === undefined
+    if (leftNull || rightNull) {
+      if (leftNull && rightNull) continue
+      const nullResult = term.nulls === 'first' ? -1 : 1
+      return leftNull ? nullResult : -nullResult
+    }
+    const result = relationalCompare(leftValue, rightValue, (comparison) => comparison < 0)
+      ? -1
+      : relationalCompare(leftValue, rightValue, (comparison) => comparison > 0)
+        ? 1
+        : 0
+    if (result !== 0) return term.direction === 'asc' ? result : -result
+  }
+  return 0
+}
+
+function project(row: Row, columns: readonly string[] | '*'): Row {
+  if (columns === '*') return cloneRow(row)
+  return Object.fromEntries(columns.map((column) => [column, row[column]]))
+}
+
+/** In-memory database reference implementation used by conformance and application tests. */
+export class FakeDatabase
+  implements DatabaseDriver<typeof capabilities, { roundTrips: number }>, TransactionSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured connection name. */
+  readonly instance = 'default'
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #tables: Record<TableName, Row[]> = emptyTables()
+
+  #roundTrips = 0
+
+  /** Number of operations that reached the in-memory backing store. */
+  get roundTrips(): number {
+    return this.#roundTrips
+  }
+
+  /** Returns an observable representation of the in-memory client. */
+  raw(): { roundTrips: number } {
+    return { roundTrips: this.#roundTrips }
+  }
+
+  /** Compiles and executes one query against the in-memory tables. */
+  async execute<TRow = Record<string, unknown>>(query: QueryIR): Promise<QueryResult<TRow>> {
+    const result = await this.#execute(query)
+    // `TRow` is selected by the caller at the contract's hydration boundary.
+    return result as QueryResult<TRow>
+  }
+
+  async #execute(query: QueryIR): Promise<QueryResult> {
+    const table = validateQuery(query)
+    if (isConstantFalse(query)) {
+      return query.mode === 'count'
+        ? { rows: [], affected: 0, count: 0 }
+        : { rows: [], affected: 0 }
+    }
+
+    this.#roundTrips += 1
+    switch (query.mode) {
+      case 'select':
+        return { rows: this.#select(table, query), affected: 0 }
+      case 'count':
+        return {
+          // Count is scalar metadata, not a selected or affected row set.
+          rows: [],
+          affected: 0,
+          count: this.#tables[table].filter((row) => matches(row, query)).length,
+        }
+      case 'insert':
+        return this.#insert(table, query)
+      case 'update':
+        return this.#update(table, query)
+      case 'delete':
+        return this.#delete(table, query)
+      case 'upsert':
+        return this.#upsert(table, query)
+    }
+  }
+
+  #select(table: TableName, query: QueryIR): Row[] {
+    let rows = this.#tables[table].filter((row) => matches(row, query)).map(cloneRow)
+    if (query.order.length > 0) rows.sort((left, right) => compareRows(left, right, query.order))
+    if (query.offset !== undefined) rows = rows.slice(query.offset)
+    if (query.limit !== undefined) rows = rows.slice(0, query.limit)
+    return rows
+      .map((row) => this.#loadRelations(row, query.relations))
+      .map((row) => {
+        const selected = project(row, query.select)
+        query.relations.forEach((relation) => {
+          selected[relation.relation] = row[relation.relation]
+        })
+        return selected
+      })
+  }
+
+  #loadRelations(parent: Row, relations: readonly RelationLoad[]): Row {
+    const loaded = cloneRow(parent)
+    for (const relation of relations) {
+      if (!isTableName(relation.table)) {
+        throw invalid(
+          `Unknown relation table ${relation.table}.`,
+          'relations',
+          'Unknown identifier',
+        )
+      }
+      const table = relation.table
+      let rows = this.#tables[table]
+        .filter((row) => row[relation.foreignKey] === parent[relation.localKey])
+        .filter((row) => !relation.where || evaluate(row, relation.where) === true)
+        .map(cloneRow)
+      if (relation.order.length > 0) {
+        rows.sort((left, right) => compareRows(left, right, relation.order))
+      }
+      if (relation.limit !== undefined) rows = rows.slice(0, relation.limit)
+      rows = rows
+        .map((row) => this.#loadRelations(row, relation.relations))
+        .map((row) => {
+          const selected = project(row, relation.select)
+          relation.relations.forEach((nested) => {
+            selected[nested.relation] = row[nested.relation]
+          })
+          return selected
+        })
+      loaded[relation.relation] = relation.kind === 'hasMany' ? rows : (rows[0] ?? null)
+    }
+    return loaded
+  }
+
+  #rowsFromValues(values: QueryIR['values']): Row[] {
+    if (values === undefined) {
+      throw invalid('Write operations require values.', 'values', 'Expected one or more rows')
+    }
+    return (Array.isArray(values) ? values : [values]).map(cloneRow)
+  }
+
+  #assertUnique(table: TableName, candidate: Row, ignored?: Row): void {
+    for (const columns of uniqueColumns[table]) {
+      const conflict = this.#tables[table].find(
+        (row) =>
+          row !== ignored &&
+          columns.every(
+            (column) => candidate[column] !== undefined && candidate[column] === row[column],
+          ),
+      )
+      if (conflict) {
+        throw new Conflict(`Unique value already exists on ${table}.`, {
+          metadata: { resource: table, key: columns.join(',') },
+        })
+      }
+    }
+  }
+
+  #writeResult(rows: readonly Row[], returning: QueryIR['returning']): QueryResult {
+    return {
+      rows: returning === undefined ? [] : rows.map((row) => project(row, returning)),
+      affected: rows.length,
+    }
+  }
+
+  #insert(table: TableName, query: QueryIR): QueryResult {
+    const rows = this.#rowsFromValues(query.values)
+    rows.forEach((row) => this.#assertUnique(table, row))
+    this.#tables[table].push(...rows.map(cloneRow))
+    return this.#writeResult(rows, query.returning)
+  }
+
+  #update(table: TableName, query: QueryIR): QueryResult {
+    if (query.values === undefined || Array.isArray(query.values)) {
+      throw invalid('Update values must be one object.', 'values', 'Expected one row')
+    }
+    const values = query.values
+    const rows = this.#tables[table].filter((row) => matches(row, query))
+    rows.forEach((row) => {
+      const candidate = { ...row, ...values }
+      this.#assertUnique(table, candidate, row)
+      Object.assign(row, values)
+    })
+    return this.#writeResult(rows, query.returning)
+  }
+
+  #delete(table: TableName, query: QueryIR): QueryResult {
+    const deleted: Row[] = []
+    this.#tables[table] = this.#tables[table].filter((row) => {
+      if (!matches(row, query)) return true
+      deleted.push(row)
+      return false
+    })
+    return this.#writeResult(deleted, query.returning)
+  }
+
+  #upsert(table: TableName, query: QueryIR): QueryResult {
+    if (!query.conflict) {
+      throw invalid('Upsert requires a conflict target.', 'conflict', 'Required for upsert')
+    }
+    const conflict = query.conflict
+    const written = this.#rowsFromValues(query.values).map((values) => {
+      const existing = this.#tables[table].find((row) =>
+        conflict.columns.every((column) => row[column] === values[column]),
+      )
+      if (!existing) {
+        this.#assertUnique(table, values)
+        this.#tables[table].push(cloneRow(values))
+        return values
+      }
+      const updateColumns =
+        conflict.update === '*'
+          ? Object.keys(values).filter((column) => !conflict.columns.includes(column))
+          : conflict.update
+      const updates = Object.fromEntries(updateColumns.map((column) => [column, values[column]]))
+      const candidate = { ...existing, ...updates }
+      this.#assertUnique(table, candidate, existing)
+      Object.assign(existing, updates)
+      return existing
+    })
+    return this.#writeResult(written, query.returning)
+  }
+
+  /** Invokes a deterministic fake routine or rejects an unknown routine as invalid input. */
+  async rpc<TResult = unknown>(
+    routine: string,
+    args: Readonly<Record<string, unknown>>,
+  ): Promise<TResult> {
+    if (routine !== 'assay_echo') {
+      // Missing routines indicate deployment drift; mapping them to NotFound would become a false 404.
+      throw invalid(`Unknown routine ${routine}.`, 'routine', routine)
+    }
+    return structuredClone(args) as TResult
+  }
+
+  /** Returns the empty migration plan used by the in-memory implementation. */
+  async plan(): Promise<MigrationPlan> {
+    return { id: 'fake', migrations: [], steps: [] }
+  }
+
+  /** Applies no migrations and returns no statuses. */
+  async apply(): Promise<readonly MigrationStatus[]> {
+    return []
+  }
+
+  /** Rolls back no migrations and returns no statuses. */
+  async rollback(_steps?: number): Promise<readonly MigrationStatus[]> {
+    return []
+  }
+
+  /** Returns no migration statuses. */
+  async status(): Promise<readonly MigrationStatus[]> {
+    return []
+  }
+
+  /** Runs a callback atomically against a snapshot of the in-memory tables. */
+  async transaction<TResult>(
+    callback: (transaction: DatabaseTransaction) => Promise<TResult>,
+  ): Promise<TResult> {
+    const snapshot = structuredClone(this.#tables)
+    try {
+      return await callback(this)
+    } catch (error: unknown) {
+      for (const table of tableNames) {
+        this.#tables[table] = snapshot[table]
+      }
+      throw error
+    }
+  }
+}

package/src/fakes/flags.ts

@@ -0,0 +1,67 @@
+import { Invalid, type FlagCapabilities, type FlagContext, type FlagDriver } from '@avelonjs/core'
+
+interface FakeFlagsRaw {
+  readonly evaluations: number
+}
+
+class FakeFlagsBase<TCapabilities extends FlagCapabilities> implements FlagDriver<
+  TCapabilities,
+  FakeFlagsRaw
+> {
+  readonly name = 'fake'
+  readonly instance: string
+  readonly capabilities: TCapabilities
+  #evaluations = 0
+
+  constructor(capabilities: TCapabilities, instance = 'default') {
+    this.capabilities = capabilities
+    this.instance = instance
+  }
+
+  raw(): FakeFlagsRaw {
+    return { evaluations: this.#evaluations }
+  }
+
+  async evaluate<TValue>(
+    key: string,
+    defaultValue: TValue,
+    context?: FlagContext,
+  ): Promise<TValue> {
+    this.#evaluations += 1
+    if (context && !this.capabilities.targeting) {
+      throw new Invalid('Targeting context is not supported by this flag driver.', {
+        metadata: { fields: { context: ['Targeting is not declared by this driver.'] } },
+      })
+    }
+
+    const configured: unknown =
+      key === 'assay.enabled'
+        ? true
+        : key === 'assay.variant'
+          ? 'treatment'
+          : key === 'assay.targeted'
+            ? context?.actorId === 'actor-enabled'
+            : undefined
+    return configured === undefined ? defaultValue : (configured as TValue)
+  }
+}
+
+const targetingCapabilities = { targeting: true } as const
+
+/** In-memory feature-flag reference implementation with targeting enabled. */
+export class FakeFlags extends FakeFlagsBase<typeof targetingCapabilities> {
+  /** Creates an isolated targeted flag connection. */
+  constructor(instance = 'default') {
+    super(targetingCapabilities, instance)
+  }
+}
+
+const noTargetingCapabilities = { targeting: false } as const
+
+/** In-memory feature-flag reference implementation without targeting. */
+export class FakeFlagsWithoutTargeting extends FakeFlagsBase<typeof noTargetingCapabilities> {
+  /** Creates an isolated untargeted flag connection. */
+  constructor(instance = 'default') {
+    super(noTargetingCapabilities, instance)
+  }
+}