@rangka/core 0.0.1

package/src/db/model-ops.ts

@@ -0,0 +1,281 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { sql, type Kysely } from 'kysely';
+import type { ResolvedModel } from '../schema/types.js';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { RequestContext } from '../auth/types.js';
+import type { ModelOps, QueryState, QueryResult, QueryResultWithMeta } from '../model-api/types.js';
+import { applyModelFilters, applySearchFilter } from './filter-applier.js';
+import { applyScopeEnforcement } from './scope-enforcer.js';
+import { modelToTableName } from './field-mapper.js';
+import { toCount } from '../helpers/coerce.js';
+import { NotFoundError } from '../errors.js';
+
+interface DbLike {
+  selectFrom(table: string): any;
+  insertInto(table: string): any;
+  updateTable(table: string): any;
+  deleteFrom(table: string): any;
+}
+
+export interface KyselyModelOpsConfig {
+  db: Kysely<any> | DbLike;
+  model: ResolvedModel;
+  registry: SchemaRegistry;
+  auth?: RequestContext;
+  tableName?: string;
+}
+
+export class KyselyModelOps implements ModelOps {
+  private readonly db: DbLike;
+  private readonly model: ResolvedModel;
+  private readonly registry: SchemaRegistry;
+  private readonly defaultAuth?: RequestContext;
+  private readonly tableName: string;
+
+  constructor(config: KyselyModelOpsConfig) {
+    this.db = config.db as DbLike;
+    this.model = config.model;
+    this.registry = config.registry;
+    this.defaultAuth = config.auth;
+    this.tableName = config.tableName ?? config.model.qualifiedName;
+  }
+
+  async find(state: QueryState): Promise<QueryResult> {
+    let query = this.buildBaseQuery(state);
+    query = this.applySelect(query, state);
+    query = this.applySorts(query, state);
+    query = this.applyPagination(query, state);
+    const data = await query.execute();
+    return { data: data as Record<string, unknown>[] };
+  }
+
+  async findWithMeta(state: QueryState): Promise<QueryResultWithMeta> {
+    const limit = state.limitVal ?? 25;
+    const page = state.pageVal ?? 1;
+    const offset = state.offsetVal ?? (page - 1) * limit;
+
+    let countQuery = this.buildBaseQuery(state);
+    countQuery = countQuery.select(sql`count(*)`.as('count'));
+    const countResult = await countQuery.executeTakeFirst();
+    const total = toCount(countResult);
+    const totalPages = Math.ceil(total / limit);
+
+    let query = this.buildBaseQuery(state);
+    query = this.applySelect(query, state);
+    query = this.applySorts(query, state);
+    query = query.limit(limit).offset(offset);
+    const data = await query.execute();
+
+    return {
+      data: data as Record<string, unknown>[],
+      meta: { total, page, limit, totalPages },
+    };
+  }
+
+  async findOne(state: QueryState): Promise<Record<string, unknown> | null> {
+    let query = this.buildBaseQuery(state);
+    query = this.applySelect(query, state);
+    query = this.applySorts(query, state);
+    query = query.limit(1);
+    const result = await query.executeTakeFirst();
+    return (result as Record<string, unknown>) ?? null;
+  }
+
+  async count(state: QueryState): Promise<number> {
+    let query = this.buildBaseQuery(state);
+    query = query.select(sql`count(*)`.as('count'));
+    const result = await query.executeTakeFirst();
+    return toCount(result);
+  }
+
+  async get(id: string): Promise<Record<string, unknown> | null> {
+    let query = this.db.selectFrom(this.tableName).selectAll().where('id', '=', id);
+    if (this.model.traits.includes('soft_delete')) {
+      query = query.where('archived_at', 'is', null);
+    }
+    const result = await query.executeTakeFirst();
+    return (result as Record<string, unknown>) ?? null;
+  }
+
+  async create(
+    data: Record<string, unknown>,
+    _auth?: RequestContext,
+  ): Promise<Record<string, unknown>> {
+    await this.assignSequenceValues(data);
+
+    const record = await this.db
+      .insertInto(this.tableName)
+      .values(data)
+      .returningAll()
+      .executeTakeFirstOrThrow();
+
+    return record as Record<string, unknown>;
+  }
+
+  async update(
+    id: string,
+    data: Record<string, unknown>,
+    _auth?: RequestContext,
+  ): Promise<Record<string, unknown>> {
+    await this.getOrThrow(id);
+
+    const record = await this.db
+      .updateTable(this.tableName)
+      .set(data)
+      .where('id', '=', id)
+      .returningAll()
+      .executeTakeFirstOrThrow();
+
+    return record as Record<string, unknown>;
+  }
+
+  async delete(id: string, _auth?: RequestContext): Promise<Record<string, unknown>> {
+    const record = await this.getOrThrow(id);
+
+    await this.cascadeDeleteChildren(id);
+
+    if (this.model.traits.includes('soft_delete')) {
+      await this.db
+        .updateTable(this.tableName)
+        .set({ archived_at: new Date().toISOString() })
+        .where('id', '=', id)
+        .execute();
+    } else {
+      await this.db.deleteFrom(this.tableName).where('id', '=', id).execute();
+    }
+
+    return record;
+  }
+
+  withTransaction(trx: unknown): ModelOps {
+    return new KyselyModelOps({
+      db: trx as DbLike,
+      model: this.model,
+      registry: this.registry,
+      auth: this.defaultAuth,
+      tableName: modelToTableName(this.model.qualifiedName),
+    });
+  }
+
+  compile(state: QueryState): unknown {
+    let query = this.buildBaseQuery(state);
+    query = this.applySelect(query, state);
+    query = this.applySorts(query, state);
+    query = this.applyPagination(query, state);
+    return query.compile();
+  }
+
+  compileCount(state: QueryState): unknown {
+    let query = this.buildBaseQuery(state);
+    query = query.select(sql`count(*)`.as('count'));
+    return query.compile();
+  }
+
+  private buildBaseQuery(state: QueryState) {
+    let query = this.db.selectFrom(this.tableName);
+
+    if (this.model.traits.includes('soft_delete') && !state.includeArchivedFlag) {
+      query = query.where('archived_at', 'is', null);
+    }
+
+    query = applyModelFilters(query, state.filters);
+
+    if (state.searchTerm && state.searchFields && state.searchFields.length > 0) {
+      query = applySearchFilter(query, state.searchTerm, state.searchFields);
+    }
+
+    if (!state.unscopedFlag && state.auth) {
+      query = applyScopeEnforcement(query, state.auth, {
+        model: this.model,
+        checkOwnership: true,
+      });
+    }
+
+    return query;
+  }
+
+  private applySelect(query: any, state: QueryState) {
+    return state.fieldNames.length > 0 ? query.select(state.fieldNames) : query.selectAll();
+  }
+
+  private applySorts(query: any, state: QueryState) {
+    for (const { field, direction } of state.sorts) {
+      query = query.orderBy(field, direction);
+    }
+    return query;
+  }
+
+  private applyPagination(query: any, state: QueryState) {
+    if (state.limitVal !== undefined) {
+      query = query.limit(state.limitVal);
+    }
+    if (state.offsetVal !== undefined) {
+      query = query.offset(state.offsetVal);
+    } else if (state.pageVal !== undefined) {
+      const limit = state.limitVal ?? 25;
+      const offset = (state.pageVal - 1) * limit;
+      if (state.limitVal === undefined) query = query.limit(limit);
+      query = query.offset(offset);
+    }
+    return query;
+  }
+
+  private async assignSequenceValues(data: Record<string, unknown>): Promise<void> {
+    const sequenceFields = this.model.fields.filter(
+      (f) => f.config.type === 'sequence' && !data[f.name],
+    );
+    if (sequenceFields.length === 0) return;
+
+    for (const field of sequenceFields) {
+      const config = field.config as { prefix?: string; digits?: number };
+      const result = await (this.db as any)
+        .insertInto('naming_sequence')
+        .values({ model: this.model.qualifiedName, field: field.name, next_val: 1 })
+        .onConflict((oc: any) =>
+          oc
+            .columns(['model', 'field'])
+            .doUpdateSet({ next_val: sql`naming_sequence.next_val + 1` }),
+        )
+        .returning('next_val')
+        .executeTakeFirstOrThrow();
+
+      const num = String(result.next_val);
+      const padded = config.digits ? num.padStart(config.digits, '0') : num;
+      data[field.name] = (config.prefix ?? '') + padded;
+    }
+  }
+
+  private async cascadeDeleteChildren(parentId: string): Promise<void> {
+    const childrenFields = this.model.fields.filter((f) => f.config.type === 'children');
+    if (childrenFields.length === 0) return;
+
+    for (const field of childrenFields) {
+      const config = field.config as { model: string; foreignKey: string };
+      const qualifiedChild = config.model.includes('.')
+        ? config.model
+        : `${this.model.module}.${config.model}`;
+      const childTable = modelToTableName(qualifiedChild);
+      const childModel = this.registry.getModel(qualifiedChild);
+      const isSoftDelete = childModel?.traits.includes('soft_delete');
+
+      if (isSoftDelete) {
+        await (this.db as any)
+          .updateTable(childTable)
+          .set({ archived_at: new Date().toISOString() })
+          .where(config.foreignKey, '=', parentId)
+          .execute();
+      } else {
+        await (this.db as any)
+          .deleteFrom(childTable)
+          .where(config.foreignKey, '=', parentId)
+          .execute();
+      }
+    }
+  }
+
+  private async getOrThrow(id: string): Promise<Record<string, unknown>> {
+    const record = await this.get(id);
+    if (!record) throw new NotFoundError(`Record not found: ${id}`);
+    return record;
+  }
+}

package/src/db/scope-enforcer.ts

@@ -0,0 +1,37 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { ResolvedModel } from '../schema/types.js';
+import type { RequestContext } from '../auth/types.js';
+
+export interface ScopeEnforcementOptions {
+  model?: ResolvedModel;
+  checkOwnership?: boolean;
+}
+
+export function applyScopeEnforcement(
+  query: any,
+  auth: RequestContext | undefined,
+  options?: ScopeEnforcementOptions,
+): any {
+  if (!auth) return query;
+
+  let result = query;
+
+  if (auth.scopeFilters && auth.scopeFilters.length > 0) {
+    for (const filter of auth.scopeFilters) {
+      const operator = filter.operator === 'in' ? 'in' : '=';
+      result = result.where(filter.field, operator, filter.value);
+    }
+  }
+
+  if (options?.checkOwnership && options.model && auth.permissions && auth.user) {
+    const modelPerms = auth.permissions.models[options.model.qualifiedName];
+    if (modelPerms && modelPerms.read === 'own') {
+      const hasCreatedBy = options.model.fields.some((f) => f.name === 'created_by');
+      if (hasCreatedBy) {
+        result = result.where('created_by', '=', auth.user.id);
+      }
+    }
+  }
+
+  return result;
+}

package/src/db/types.ts

@@ -0,0 +1,98 @@
+export interface ColumnDefinition {
+  name: string;
+  type: string;
+  nullable: boolean;
+  defaultValue?: string;
+  primaryKey?: boolean;
+}
+
+export interface ForeignKeyDefinition {
+  name: string;
+  column: string;
+  referencedTable: string;
+  referencedColumn: string;
+}
+
+export interface CheckConstraintDefinition {
+  name: string;
+  column: string;
+  expression: string;
+}
+
+export interface IndexDefinition {
+  name: string;
+  table: string;
+  columns: string[];
+  unique: boolean;
+  where?: string;
+}
+
+export interface TableDefinition {
+  name: string;
+  columns: ColumnDefinition[];
+  foreignKeys: ForeignKeyDefinition[];
+  checkConstraints: CheckConstraintDefinition[];
+  indexes: IndexDefinition[];
+}
+
+export interface DesiredState {
+  tables: TableDefinition[];
+}
+
+export interface ActualColumn {
+  name: string;
+  type: string;
+  nullable: boolean;
+  defaultValue: string | null;
+}
+
+export interface ActualForeignKey {
+  name: string;
+  column: string;
+  referencedTable: string;
+  referencedColumn: string;
+}
+
+export interface ActualIndex {
+  name: string;
+  columns: string[];
+  unique: boolean;
+}
+
+export interface ActualCheckConstraint {
+  name: string;
+  column: string;
+  expression: string;
+}
+
+export interface ActualTable {
+  name: string;
+  columns: ActualColumn[];
+  foreignKeys: ActualForeignKey[];
+  indexes: ActualIndex[];
+  checkConstraints: ActualCheckConstraint[];
+}
+
+export interface ActualState {
+  tables: ActualTable[];
+}
+
+export type DdlOperationType =
+  | 'CREATE_TABLE'
+  | 'ADD_COLUMN'
+  | 'ALTER_COLUMN_TYPE'
+  | 'ADD_FOREIGN_KEY'
+  | 'ADD_CHECK_CONSTRAINT'
+  | 'CREATE_INDEX'
+  | 'DROP_COLUMN'
+  | 'DROP_TABLE'
+  | 'DROP_FOREIGN_KEY'
+  | 'DROP_INDEX';
+
+export interface DdlOperation {
+  type: DdlOperationType;
+  table: string;
+  sql: string;
+  destructive: boolean;
+  detail?: string;
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+export class AppError extends Error {
+  public readonly statusCode: number;
+  public readonly code: string;
+  public readonly details?: unknown;
+
+  constructor(statusCode: number, code: string, message: string, details?: unknown) {
+    super(message);
+    this.name = 'AppError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class BadRequestError extends AppError {
+  constructor(code: string, message: string, details?: unknown) {
+    super(400, code, message, details);
+    this.name = 'BadRequestError';
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message: string) {
+    super(401, 'UNAUTHORIZED', message);
+    this.name = 'UnauthorizedError';
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(code: string, message: string, details?: unknown) {
+    super(403, code, message, details);
+    this.name = 'ForbiddenError';
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message: string) {
+    super(404, 'NOT_FOUND', message);
+    this.name = 'NotFoundError';
+  }
+}

package/src/events/__tests__/bus.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi } from 'vitest';
+import { EventBus } from '../bus.js';
+
+describe('EventBus', () => {
+  it('registers listeners via on()', () => {
+    const bus = new EventBus();
+    const handler = vi.fn();
+
+    bus.on('order.created', handler);
+
+    expect(bus.hasListeners('order.created')).toBe(true);
+    expect(bus.getListeners('order.created')).toHaveLength(1);
+  });
+
+  it('supports multiple listeners per event', () => {
+    const bus = new EventBus();
+    const h1 = vi.fn();
+    const h2 = vi.fn();
+
+    bus.on('order.created', h1);
+    bus.on('order.created', h2);
+
+    expect(bus.getListeners('order.created')).toHaveLength(2);
+  });
+
+  it('returns false for events with no listeners', () => {
+    const bus = new EventBus();
+    expect(bus.hasListeners('nothing')).toBe(false);
+    expect(bus.getListeners('nothing')).toHaveLength(0);
+  });
+
+  it('getAllEvents returns all registered event names', () => {
+    const bus = new EventBus();
+    bus.on('a', vi.fn());
+    bus.on('b', vi.fn());
+    bus.on('c', vi.fn());
+
+    const events = bus.getAllEvents();
+    expect(events).toContain('a');
+    expect(events).toContain('b');
+    expect(events).toContain('c');
+  });
+
+  describe('sync emit', () => {
+    it('calls listeners inline with { sync: true }', async () => {
+      const bus = new EventBus();
+      const handler = vi.fn().mockResolvedValue(undefined);
+
+      bus.on('test.event', handler);
+      await bus.emit('test.event', { id: 1 }, { sync: true });
+
+      expect(handler).toHaveBeenCalledWith({ id: 1 });
+    });
+
+    it('calls multiple listeners in order', async () => {
+      const bus = new EventBus();
+      const order: number[] = [];
+
+      bus.on('test', async () => {
+        order.push(1);
+      });
+      bus.on('test', async () => {
+        order.push(2);
+      });
+
+      await bus.emit('test', {}, { sync: true });
+      expect(order).toEqual([1, 2]);
+    });
+
+    it('does nothing if no listeners registered', async () => {
+      const bus = new EventBus();
+      await expect(bus.emit('unknown', {}, { sync: true })).resolves.toBeUndefined();
+    });
+  });
+
+  describe('async emit', () => {
+    it('throws if db not set', async () => {
+      const bus = new EventBus();
+      bus.on('test', vi.fn());
+
+      await expect(bus.emit('test', {})).rejects.toThrow('database not set');
+    });
+
+    it('emitWithTrx in sync mode calls handlers directly', async () => {
+      const bus = new EventBus();
+      const handler = vi.fn().mockResolvedValue(undefined);
+      bus.on('test', handler);
+
+      const mockTrx = {} as any;
+      await bus.emitWithTrx('test', { data: 'hi' }, mockTrx, { sync: true });
+
+      expect(handler).toHaveBeenCalledWith({ data: 'hi' });
+    });
+  });
+
+  describe('listener source tracking', () => {
+    it('stores source on listener', () => {
+      const bus = new EventBus();
+      bus.on('test', vi.fn(), 'sales-module');
+
+      const listeners = bus.getListeners('test');
+      expect(listeners[0].source).toBe('sales-module');
+    });
+  });
+});

package/src/events/bus.ts

@@ -0,0 +1,89 @@
+import type { Kysely } from 'kysely';
+import { enqueue } from '../jobs/enqueue.js';
+import type { EventListener } from './types.js';
+
+/**
+ * Simple pub/sub event bus that supports two dispatch modes:
+ * - sync: invoke listeners directly in sequence
+ * - async (default): enqueue the event as a background job via the database
+ */
+export class EventBus {
+  private readonly listeners: Map<string, EventListener[]> = new Map();
+  private db: Kysely<unknown> | null = null;
+
+  /** Provide the database connection used for async event dispatch. */
+  setDb(db: Kysely<unknown>): void {
+    this.db = db;
+  }
+
+  /** Register a listener for a specific event. */
+  on(event: string, handler: (payload: unknown) => Promise<void>, source?: string): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event)!.push({ event, handler, source });
+  }
+
+  /**
+   * Emit an event. By default, the event is enqueued as a background job.
+   * Pass { sync: true } to invoke listeners immediately in sequence.
+   */
+  async emit(event: string, payload: unknown, options?: { sync?: boolean }): Promise<void> {
+    if (options?.sync) {
+      await this.dispatchSync(event, payload);
+    } else {
+      await this.dispatchAsync(event, payload);
+    }
+  }
+
+  /**
+   * Emit an event within an existing database transaction.
+   * Sync mode invokes listeners directly; async mode enqueues via the transaction.
+   */
+  async emitWithTrx(
+    event: string,
+    payload: unknown,
+    trx: Kysely<unknown>,
+    options?: { sync?: boolean },
+  ): Promise<void> {
+    if (options?.sync) {
+      await this.dispatchSync(event, payload);
+    } else {
+      await enqueue(trx, `__event:${event}`, payload);
+    }
+  }
+
+  /** Return all listeners registered for a given event. */
+  getListeners(event: string): EventListener[] {
+    return this.listeners.get(event) ?? [];
+  }
+
+  /** Return the names of all events that have at least one listener. */
+  getAllEvents(): string[] {
+    return Array.from(this.listeners.keys());
+  }
+
+  /** Check whether any listeners are registered for a given event. */
+  hasListeners(event: string): boolean {
+    const eventListeners = this.listeners.get(event);
+    return !!eventListeners && eventListeners.length > 0;
+  }
+
+  // --- Private dispatch methods ---
+
+  /** Invoke all listeners for an event synchronously, one after another. */
+  private async dispatchSync(event: string, payload: unknown): Promise<void> {
+    const eventListeners = this.listeners.get(event) ?? [];
+    for (const listener of eventListeners) {
+      await listener.handler(payload);
+    }
+  }
+
+  /** Enqueue the event as a background job via the database. */
+  private async dispatchAsync(event: string, payload: unknown): Promise<void> {
+    if (!this.db) {
+      throw new Error('EventBus: database not set. Call setDb() before emitting async events.');
+    }
+    await enqueue(this.db, `__event:${event}`, payload);
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export type { EventListener, EventBusConfig } from './types.js';
+export { EventBus } from './bus.js';

package/src/events/types.ts

@@ -0,0 +1,9 @@
+export interface EventListener {
+  event: string;
+  handler: (payload: unknown) => Promise<void>;
+  source?: string;
+}
+
+export interface EventBusConfig {
+  sync?: boolean;
+}