@rangka/core 0.0.1

package/src/fixtures/loader.ts

@@ -0,0 +1,196 @@
+import { createHash } from 'crypto';
+import type { FixtureDefinition, FixtureLoadResult, FixtureRef } from './types.js';
+
+// --- Hashing ---
+
+/** Produces a short deterministic hash of a record for change detection. */
+function computeHash(record: Record<string, unknown>): string {
+  const sortedKeys = Object.keys(record).sort();
+  const json = JSON.stringify(record, sortedKeys);
+  return createHash('sha256').update(json).digest('hex').slice(0, 16);
+}
+
+// --- Reference resolution ---
+
+/** Type guard: checks whether a field value is a cross-model reference. */
+function isRef(value: unknown): value is FixtureRef {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'ref' in value &&
+    'key' in value &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    typeof (value as any).ref === 'string' &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    typeof (value as any).key === 'string'
+  );
+}
+
+/**
+ * Infers the lookup field name for a reference when none is explicitly provided.
+ * E.g. model "tenant.role" -> lookup field "role_code".
+ */
+function inferLookupField(model: string): string {
+  const segments = model.split('.');
+  const modelName = segments[segments.length - 1];
+  return `${modelName}_code`;
+}
+
+/**
+ * Parses a reference key string into its lookup field and value.
+ *
+ * Format: "field:value" uses the explicit field, otherwise the field is
+ * inferred from the referenced model name.
+ */
+function parseRefKey(
+  refKey: string,
+  refModel: string,
+): { lookupField: string; lookupValue: string } {
+  if (refKey.includes(':')) {
+    const [lookupField, lookupValue] = refKey.split(':');
+    return { lookupField, lookupValue };
+  }
+  return { lookupField: inferLookupField(refModel), lookupValue: refKey };
+}
+
+/**
+ * Resolves all FixtureRef values in a record into actual foreign-key IDs
+ * by querying the database for the referenced rows.
+ */
+async function resolveRefs(
+  record: Record<string, unknown>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any,
+): Promise<Record<string, unknown>> {
+  const resolved = { ...record };
+
+  for (const [field, value] of Object.entries(resolved)) {
+    if (!isRef(value)) continue;
+
+    const tableName = value.ref.replace('.', '_');
+    const { lookupField, lookupValue } = parseRefKey(value.key, value.ref);
+
+    const rows = await db
+      .selectFrom(tableName)
+      .select('id')
+      .where(lookupField, '=', lookupValue)
+      .execute();
+
+    resolved[field] = rows.length > 0 ? rows[0].id : null;
+  }
+
+  return resolved;
+}
+
+// --- Core loader ---
+
+/**
+ * Converts a model name (e.g. "tenant.user") into its database table name.
+ */
+function toTableName(model: string): string {
+  return model.replace('.', '_');
+}
+
+/**
+ * Inserts or updates a single fixture record depending on whether it already
+ * exists and whether it has changed since the last load.
+ */
+async function upsertFixtureRecord(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any,
+  tableName: string,
+  definition: FixtureDefinition,
+  record: Record<string, unknown>,
+  options: { force?: boolean },
+): Promise<'inserted' | 'skipped'> {
+  const keyValue = record[definition.key] as string;
+  const fixtureHash = computeHash(record);
+
+  const existingRows = await db
+    .selectFrom(tableName)
+    .selectAll()
+    .where(definition.key, '=', keyValue)
+    .execute();
+
+  // New record: insert it.
+  if (existingRows.length === 0) {
+    const resolved = await resolveRefs(record, db);
+    await db
+      .insertInto(tableName)
+      .values({
+        ...resolved,
+        _fixture_source: definition.model,
+        _fixture_hash: fixtureHash,
+      })
+      .execute();
+    return 'inserted';
+  }
+
+  // Force mode: always overwrite.
+  if (options.force) {
+    const resolved = await resolveRefs(record, db);
+    await db
+      .updateTable(tableName)
+      .set({
+        ...resolved,
+        _fixture_source: definition.model,
+        _fixture_hash: fixtureHash,
+      })
+      .where(definition.key, '=', keyValue)
+      .execute();
+    return 'inserted';
+  }
+
+  // Existing record: update only if the fixture hash has changed.
+  const existingHash = existingRows[0]._fixture_hash;
+  const hasChanged = existingHash && existingHash !== fixtureHash;
+
+  if (!hasChanged) {
+    return 'skipped';
+  }
+
+  const resolved = await resolveRefs(record, db);
+  await db
+    .updateTable(tableName)
+    .set({
+      ...resolved,
+      _fixture_hash: fixtureHash,
+    })
+    .where(definition.key, '=', keyValue)
+    .execute();
+  return 'inserted';
+}
+
+/**
+ * Loads an array of fixture definitions into the database.
+ *
+ * Each record is inserted if new, updated if its content hash changed,
+ * or skipped if unchanged. Pass `options.force` to always overwrite.
+ */
+export async function loadFixtures(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  db: any,
+  definitions: FixtureDefinition[],
+  options?: { force?: boolean },
+): Promise<FixtureLoadResult> {
+  let inserted = 0;
+  let skipped = 0;
+  let total = 0;
+
+  for (const definition of definitions) {
+    const tableName = toTableName(definition.model);
+
+    for (const record of definition.records) {
+      total++;
+      const result = await upsertFixtureRecord(db, tableName, definition, record, options ?? {});
+
+      if (result === 'inserted') {
+        inserted++;
+      } else {
+        skipped++;
+      }
+    }
+  }
+
+  return { inserted, skipped, total };
+}

package/src/fixtures/registry.ts

@@ -0,0 +1,125 @@
+import type { FixtureDefinition, RegisteredFixture } from './types.js';
+
+/**
+ * Stores fixture definitions keyed by model name.
+ * Fixtures can be retrieved in dependency-sorted order for safe loading.
+ */
+export class FixtureRegistry {
+  private readonly fixtures: Map<string, RegisteredFixture[]> = new Map();
+
+  /** Validate and store a fixture definition. */
+  register(definition: FixtureDefinition): void {
+    const errors = this.validate(definition);
+    if (errors.length > 0) {
+      throw new Error(`Invalid fixture for "${definition.model}": ${errors.join('; ')}`);
+    }
+
+    const existing = this.fixtures.get(definition.model) ?? [];
+    existing.push({ model: definition.model, definition });
+    this.fixtures.set(definition.model, existing);
+  }
+
+  getForModel(model: string): RegisteredFixture[] {
+    return this.fixtures.get(model) ?? [];
+  }
+
+  getAll(): RegisteredFixture[] {
+    const all: RegisteredFixture[] = [];
+    for (const fixtures of this.fixtures.values()) {
+      all.push(...fixtures);
+    }
+    return all;
+  }
+
+  getAllModels(): string[] {
+    return Array.from(this.fixtures.keys());
+  }
+
+  /** Return all definitions sorted so dependencies load first. */
+  getLoadOrder(): FixtureDefinition[] {
+    const allDefinitions = this.getAll().map((f) => f.definition);
+    return this.topologicalSort(allDefinitions);
+  }
+
+  /**
+   * Get fixtures for a specific variant. Variant fixtures override base (no-variant)
+   * fixtures on a per-model basis. Results are dependency-sorted.
+   */
+  getForVariant(variant: string | undefined): FixtureDefinition[] {
+    const allDefinitions = this.getAll().map((f) => f.definition);
+
+    if (!variant) {
+      return allDefinitions.filter((f) => !f.variant);
+    }
+
+    // Start with base fixtures, then let variant fixtures override per-model
+    const fixtureByModel = new Map<string, FixtureDefinition>();
+    for (const fixture of allDefinitions) {
+      if (!fixture.variant) {
+        fixtureByModel.set(fixture.model, fixture);
+      }
+    }
+    for (const fixture of allDefinitions) {
+      if (fixture.variant === variant) {
+        fixtureByModel.set(fixture.model, fixture);
+      }
+    }
+
+    return this.topologicalSort(Array.from(fixtureByModel.values()));
+  }
+
+  /**
+   * Sort definitions so that each fixture's dependencies appear before it.
+   * Uses depth-first traversal with visited tracking.
+   */
+  private topologicalSort(definitions: FixtureDefinition[]): FixtureDefinition[] {
+    const definitionByModel = new Map<string, FixtureDefinition>();
+    for (const def of definitions) {
+      definitionByModel.set(def.model, def);
+    }
+
+    const visited = new Set<string>();
+    const sorted: FixtureDefinition[] = [];
+
+    const visit = (model: string) => {
+      if (visited.has(model)) return;
+      visited.add(model);
+
+      const def = definitionByModel.get(model);
+      if (!def) return;
+
+      // Visit dependencies first
+      if (def.depends) {
+        for (const dependency of def.depends) {
+          visit(dependency);
+        }
+      }
+
+      sorted.push(def);
+    };
+
+    for (const model of definitionByModel.keys()) {
+      visit(model);
+    }
+
+    return sorted;
+  }
+
+  private validate(definition: FixtureDefinition): string[] {
+    const errors: string[] = [];
+
+    if (!definition.model || definition.model.trim().length === 0) {
+      errors.push('Fixture model must not be empty');
+    }
+
+    if (!definition.key || definition.key.trim().length === 0) {
+      errors.push('Fixture key must not be empty');
+    }
+
+    if (!definition.records || definition.records.length === 0) {
+      errors.push('Fixture must have at least one record');
+    }
+
+    return errors;
+  }
+}

package/src/fixtures/types.ts

@@ -0,0 +1,33 @@
+export interface FixtureRef {
+  ref: string;
+  key: string;
+}
+
+export interface FixtureDefinition {
+  model: string;
+  key: string;
+  variant?: string;
+  depends?: string[];
+  records: Array<Record<string, unknown>>;
+}
+
+export type FixtureStatus = 'pending' | 'loaded' | 'skipped';
+
+export interface FixtureRecord {
+  model: string;
+  key: string;
+  keyValue: string;
+  fixtureHash: string;
+  status: FixtureStatus;
+}
+
+export interface RegisteredFixture {
+  model: string;
+  definition: FixtureDefinition;
+}
+
+export interface FixtureLoadResult {
+  inserted: number;
+  skipped: number;
+  total: number;
+}

package/src/helpers/assert-ownership.ts

@@ -0,0 +1,19 @@
+import type { ResolvedModel } from '../schema/types.js';
+import type { ResolvedPermissions } from '../auth/types.js';
+import { isOwnerOnly, modelHasCreatedBy } from '../auth/model-permissions.js';
+import { ForbiddenError } from '../errors.js';
+
+export function assertOwnership(
+  permissions: ResolvedPermissions | undefined,
+  model: ResolvedModel,
+  record: Record<string, unknown>,
+  userId: string | undefined,
+  operation: 'read' | 'write' | 'delete',
+): void {
+  if (!isOwnerOnly(permissions, model.qualifiedName, operation)) return;
+
+  if (!modelHasCreatedBy(model) || record.created_by !== userId) {
+    const action = operation === 'delete' ? 'delete' : 'update';
+    throw new ForbiddenError('FORBIDDEN', `You can only ${action} records you created`);
+  }
+}

package/src/helpers/coerce.ts

@@ -0,0 +1,28 @@
+/**
+ * Type coercion helpers for normalizing values from query params,
+ * database results, and other loosely-typed boundaries.
+ */
+
+export function toBool(value: unknown): boolean {
+  return value === true || value === 'true' || value === 1 || value === '1';
+}
+
+export function toInt(value: unknown, fallback: number = 0): number {
+  if (isNil(value) || value === '') return fallback;
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.trunc(value);
+  }
+  const parsed = Number(value);
+  if (isNaN(parsed) || !Number.isFinite(parsed)) return fallback;
+  return Math.trunc(parsed);
+}
+
+export function isNil(value: unknown): value is null | undefined {
+  return value === null || value === undefined;
+}
+
+export function toCount(result: unknown): number {
+  if (isNil(result)) return 0;
+  const raw = typeof result === 'object' ? (result as Record<string, unknown>).count : result;
+  return toInt(raw, 0);
+}

package/src/helpers/stamping.ts

@@ -0,0 +1,28 @@
+import type { ResolvedModel } from '../schema/types.js';
+
+export function stampCreate(
+  body: Record<string, unknown>,
+  model: ResolvedModel,
+  auth?: { user?: { id: string } | null },
+): void {
+  if (!model.traits.includes('timestamped')) return;
+  const now = new Date().toISOString();
+  body.created_at = now;
+  body.updated_at = now;
+  if (auth?.user?.id) {
+    body.created_by = auth.user.id;
+    body.updated_by = auth.user.id;
+  }
+}
+
+export function stampUpdate(
+  body: Record<string, unknown>,
+  model: ResolvedModel,
+  auth?: { user?: { id: string } | null },
+): void {
+  if (!model.traits.includes('timestamped')) return;
+  body.updated_at = new Date().toISOString();
+  if (auth?.user?.id) {
+    body.updated_by = auth.user.id;
+  }
+}

package/src/helpers/validation.ts

@@ -0,0 +1,14 @@
+import type { ResolvedModel } from '../schema/types.js';
+
+export function findMissingRequiredFields(
+  model: ResolvedModel,
+  body: Record<string, unknown>,
+): string[] {
+  const missing: string[] = [];
+  for (const field of model.fields) {
+    if ('required' in field.config && field.config.required && body[field.name] === undefined) {
+      missing.push(field.name);
+    }
+  }
+  return missing;
+}

package/src/hooks/__tests__/context.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { createHookContext } from '../context.js';
+import type { SchemaRegistry } from '../../schema/registry.js';
+import type { RequestContext } from '../../auth/types.js';
+
+function mockSchema(): SchemaRegistry {
+  return { getAllModels: () => [] } as unknown as SchemaRegistry;
+}
+
+function mockAuth(): RequestContext {
+  return {
+    user: { id: '1', email: 'test@test.com' },
+    roles: ['Admin'],
+    scopeFilters: [],
+  } as unknown as RequestContext;
+}
+
+describe('createHookContext', () => {
+  it('returns context with db, schema, and auth', () => {
+    const trx = { fake: 'transaction' };
+    const schema = mockSchema();
+    const auth = mockAuth();
+
+    const ctx = createHookContext({ trx, schema, auth });
+
+    expect(ctx.db).toBe(trx);
+    expect(ctx.schema).toBe(schema);
+    expect(ctx.auth.user).toEqual(auth.user);
+    expect(ctx.auth.roles).toEqual(auth.roles);
+  });
+
+  it('enqueue calls the enqueue function with the trx', async () => {
+    const ctx = createHookContext({ trx: {}, schema: mockSchema(), auth: mockAuth() });
+    // Without a real db, it will throw a type error from kysely - confirms wiring is in place
+    await expect(ctx.enqueue('test-job', {})).rejects.toThrow();
+  });
+
+  it('service throws when no serviceRegistry provided', () => {
+    const ctx = createHookContext({ trx: {}, schema: mockSchema(), auth: mockAuth() });
+    expect(() => ctx.service('test-service')).toThrow('ServiceRegistry not available');
+  });
+
+  it('service resolves via serviceRegistry when provided', () => {
+    const mockRegistry = {
+      get: (name: string) => ({ greet: () => `hello from ${name}` }),
+    } as any;
+    const ctx = createHookContext({
+      trx: {},
+      schema: mockSchema(),
+      auth: mockAuth(),
+      serviceRegistry: mockRegistry,
+    });
+    const svc = ctx.service('greeter') as any;
+    expect(svc.greet()).toBe('hello from greeter');
+  });
+
+  it('events.emit is a no-op without eventBus', async () => {
+    const ctx = createHookContext({ trx: {}, schema: mockSchema(), auth: mockAuth() });
+    await expect(ctx.events.emit('test-event', {})).resolves.toBeUndefined();
+  });
+
+  it('events.emit delegates to eventBus when provided', async () => {
+    const emitWithTrx = async () => {};
+    const mockBus = { emitWithTrx } as any;
+    const ctx = createHookContext({
+      trx: {},
+      schema: mockSchema(),
+      auth: mockAuth(),
+      eventBus: mockBus,
+    });
+    await expect(ctx.events.emit('test-event', {})).resolves.toBeUndefined();
+  });
+});