@rangka/core 0.0.1

package/src/model-api/query-builder.ts

@@ -0,0 +1,155 @@
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { ResolvedModel } from '../schema/types.js';
+import type { RequestContext } from '../auth/types.js';
+import type {
+  FilterExpression,
+  IncludeResolver,
+  ModelOps,
+  ModelQuery,
+  QueryResult,
+  QueryResultWithMeta,
+  QueryState,
+  TranslatedFilter,
+} from './types.js';
+import { translateFilters } from './filter-translator.js';
+
+export type { QueryState } from './types.js';
+
+export class ModelQueryBuilder implements ModelQuery {
+  private readonly ops: ModelOps;
+  private readonly model: ResolvedModel;
+  private readonly registry: SchemaRegistry;
+  private readonly includeResolver?: IncludeResolver;
+  private readonly state: QueryState;
+
+  constructor(
+    ops: ModelOps,
+    model: ResolvedModel,
+    registry: SchemaRegistry,
+    includeResolver?: IncludeResolver,
+    state?: QueryState,
+  ) {
+    this.ops = ops;
+    this.model = model;
+    this.registry = registry;
+    this.includeResolver = includeResolver;
+    this.state = state ?? {
+      filters: [],
+      sorts: [],
+      fieldNames: [],
+      includes: [],
+      unscopedFlag: false,
+      includeArchivedFlag: false,
+    };
+  }
+
+  private clone(patch: Partial<QueryState>): ModelQueryBuilder {
+    return new ModelQueryBuilder(this.ops, this.model, this.registry, this.includeResolver, {
+      ...this.state,
+      ...patch,
+    });
+  }
+
+  filter(conditions: FilterExpression): ModelQueryBuilder {
+    const translated = translateFilters(conditions);
+    return this.clone({ filters: [...this.state.filters, ...translated] });
+  }
+
+  filterRaw(filters: TranslatedFilter[]): ModelQueryBuilder {
+    return this.clone({ filters: [...this.state.filters, ...filters] });
+  }
+
+  sort(field: string, direction: 'asc' | 'desc' = 'asc'): ModelQueryBuilder {
+    return this.clone({ sorts: [...this.state.sorts, { field, direction }] });
+  }
+
+  limit(count: number): ModelQueryBuilder {
+    return this.clone({ limitVal: count });
+  }
+
+  offset(count: number): ModelQueryBuilder {
+    return this.clone({ offsetVal: count });
+  }
+
+  page(num: number): ModelQueryBuilder {
+    return this.clone({ pageVal: num });
+  }
+
+  include(relation: string): ModelQueryBuilder {
+    if (this.state.includes.includes(relation)) return this;
+    return this.clone({ includes: [...this.state.includes, relation] });
+  }
+
+  fields(fieldNames: string[]): ModelQueryBuilder {
+    return this.clone({ fieldNames });
+  }
+
+  unscoped(): ModelQueryBuilder {
+    return this.clone({ unscopedFlag: true });
+  }
+
+  includeArchived(): ModelQueryBuilder {
+    return this.clone({ includeArchivedFlag: true });
+  }
+
+  search(term: string, fields: string[]): ModelQueryBuilder {
+    if (!term || fields.length === 0) return this;
+    return this.clone({ searchTerm: term, searchFields: fields });
+  }
+
+  withAuth(auth: RequestContext): ModelQueryBuilder {
+    return this.clone({ auth });
+  }
+
+  isUnscoped(): boolean {
+    return this.state.unscopedFlag;
+  }
+
+  getIncludes(): string[] {
+    return this.state.includes;
+  }
+
+  compile(): unknown {
+    return this.ops.compile?.(this.state) ?? this.state;
+  }
+
+  compileCount(): unknown {
+    return this.ops.compileCount?.(this.state) ?? this.state;
+  }
+
+  async exec(): Promise<QueryResult> {
+    const result = await this.ops.find(this.state);
+    if (this.state.includes.length > 0 && this.includeResolver) {
+      await this.includeResolver.resolve(
+        result.data,
+        this.state.includes,
+        this.model.qualifiedName,
+      );
+    }
+    return result;
+  }
+
+  async execWithMeta(): Promise<QueryResultWithMeta> {
+    const result = await this.ops.findWithMeta(this.state);
+    if (this.state.includes.length > 0 && this.includeResolver) {
+      await this.includeResolver.resolve(
+        result.data,
+        this.state.includes,
+        this.model.qualifiedName,
+      );
+    }
+    return result;
+  }
+
+  async first(): Promise<Record<string, unknown> | null> {
+    const result = await this.ops.findOne(this.state);
+    if (result && this.state.includes.length > 0 && this.includeResolver) {
+      await this.includeResolver.resolve([result], this.state.includes, this.model.qualifiedName);
+    }
+    return result;
+  }
+
+  async count(): Promise<number> {
+    return this.ops.count(this.state);
+  }
+}

package/src/model-api/scope-enforcer.ts

@@ -0,0 +1,3 @@
+export { applyScopeEnforcement } from '../db/scope-enforcer.js';
+export type { ScopeEnforcementOptions } from '../db/scope-enforcer.js';
+export { stripHiddenFields, enforceReadOnly } from './field-access.js';

package/src/model-api/types.ts

@@ -0,0 +1,139 @@
+export interface FilterOperators {
+  eq?: unknown;
+  neq?: unknown;
+  gt?: unknown;
+  gte?: unknown;
+  lt?: unknown;
+  lte?: unknown;
+  in?: unknown[];
+  notIn?: unknown[];
+  contains?: string;
+  startsWith?: string;
+  endsWith?: string;
+  is?: null | 'not_null';
+}
+
+export type FilterValue = unknown | FilterOperators;
+
+export type FilterExpression = Record<string, FilterValue>;
+
+export interface PaginationMeta {
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}
+
+export interface QueryResult {
+  data: Record<string, unknown>[];
+  total?: number;
+  hasMore?: boolean;
+}
+
+export interface QueryResultWithMeta {
+  data: Record<string, unknown>[];
+  meta: PaginationMeta;
+}
+
+import type { RequestContext } from '../auth/types.js';
+
+export interface TranslatedFilter {
+  field: string;
+  operator: string;
+  value: unknown;
+}
+
+export interface QueryState {
+  filters: TranslatedFilter[];
+  sorts: Array<{ field: string; direction: 'asc' | 'desc' }>;
+  limitVal?: number;
+  offsetVal?: number;
+  pageVal?: number;
+  fieldNames: string[];
+  includes: string[];
+  unscopedFlag: boolean;
+  includeArchivedFlag: boolean;
+  auth?: RequestContext;
+  searchTerm?: string;
+  searchFields?: string[];
+}
+
+export interface ModelOps {
+  find(state: QueryState): Promise<QueryResult>;
+  findWithMeta(state: QueryState): Promise<QueryResultWithMeta>;
+  findOne(state: QueryState): Promise<Record<string, unknown> | null>;
+  count(state: QueryState): Promise<number>;
+  get(id: string): Promise<Record<string, unknown> | null>;
+  create(data: Record<string, unknown>, auth?: RequestContext): Promise<Record<string, unknown>>;
+  update(
+    id: string,
+    data: Record<string, unknown>,
+    auth?: RequestContext,
+  ): Promise<Record<string, unknown>>;
+  delete(id: string, auth?: RequestContext): Promise<Record<string, unknown>>;
+  withTransaction?(trx: unknown): ModelOps;
+  compile?(state: QueryState): unknown;
+  compileCount?(state: QueryState): unknown;
+}
+
+export interface IncludeResolver {
+  resolve(
+    records: Record<string, unknown>[],
+    includes: string[],
+    sourceModel: string,
+  ): Promise<void>;
+}
+
+export interface ModelQuery {
+  filter(conditions: FilterExpression): ModelQuery;
+  filterRaw(filters: TranslatedFilter[]): ModelQuery;
+  sort(field: string, direction?: 'asc' | 'desc'): ModelQuery;
+  limit(count: number): ModelQuery;
+  offset(count: number): ModelQuery;
+  page(num: number): ModelQuery;
+  include(relation: string): ModelQuery;
+  fields(fieldNames: string[]): ModelQuery;
+  search(term: string, fields: string[]): ModelQuery;
+  unscoped(): ModelQuery;
+  includeArchived(): ModelQuery;
+  withAuth(auth: import('../auth/types.js').RequestContext): ModelQuery;
+  exec(): Promise<QueryResult>;
+  execWithMeta(): Promise<QueryResultWithMeta>;
+  first(): Promise<Record<string, unknown> | null>;
+  count(): Promise<number>;
+}
+
+export interface ModelAccess {
+  get(model: string, id: string): Promise<Record<string, unknown> | null>;
+  query(model: string): ModelQuery;
+  create(model: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+  update(
+    model: string,
+    id: string,
+    data: Record<string, unknown>,
+  ): Promise<Record<string, unknown>>;
+  delete(model: string, id: string): Promise<Record<string, unknown>>;
+}
+
+export interface ModelAccessOptions {
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  db: {
+    selectFrom(table: string): any;
+    insertInto(table: string): any;
+    updateTable(table: string): any;
+    deleteFrom(table: string): any;
+  };
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+  registry: import('../schema/registry.js').SchemaRegistry;
+  hookRegistry?: import('../hooks/registry.js').HookRegistry;
+  auth?: import('../auth/types.js').RequestContext;
+  serviceRegistry?: import('../services/registry.js').ServiceRegistry;
+  eventBus?: import('../events/bus.js').EventBus;
+  config?: Record<string, unknown>;
+  adapterRegistry?: import('../plugins/adapter-registry.js').AdapterRegistry;
+  externalModelFields?: Record<
+    string,
+    Record<string, import('../external-model/types.js').ExternalFieldConfig>
+  >;
+  adapterCapabilities?: Record<string, import('../plugins/types.js').AdapterCapability[]>;
+}

package/src/plugins/__tests__/adapter-registry.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import {
+  AdapterRegistry,
+  AdapterNotFoundError,
+  DuplicateAdapterError,
+} from '../adapter-registry.js';
+import type { DataAdapter } from '../types.js';
+
+function makeAdapter(overrides?: Partial<DataAdapter>): DataAdapter {
+  return {
+    async get(_model: string, _id: string) {
+      return { id: '1' };
+    },
+    ...overrides,
+  };
+}
+
+describe('AdapterRegistry', () => {
+  describe('register', () => {
+    it('registers an adapter', () => {
+      const registry = new AdapterRegistry();
+      const adapter = makeAdapter();
+      registry.register('stripe', adapter);
+      expect(registry.has('stripe')).toBe(true);
+    });
+
+    it('throws DuplicateAdapterError on duplicate name', () => {
+      const registry = new AdapterRegistry();
+      registry.register('stripe', makeAdapter());
+      expect(() => registry.register('stripe', makeAdapter())).toThrow(DuplicateAdapterError);
+      expect(() => registry.register('stripe', makeAdapter())).toThrow(
+        'Adapter "stripe" is already registered',
+      );
+    });
+
+    it('allows different names', () => {
+      const registry = new AdapterRegistry();
+      registry.register('stripe', makeAdapter());
+      registry.register('hubspot', makeAdapter());
+      expect(registry.has('stripe')).toBe(true);
+      expect(registry.has('hubspot')).toBe(true);
+    });
+  });
+
+  describe('get', () => {
+    it('returns the registered adapter', () => {
+      const registry = new AdapterRegistry();
+      const adapter = makeAdapter();
+      registry.register('stripe', adapter);
+      expect(registry.get('stripe')).toBe(adapter);
+    });
+
+    it('throws AdapterNotFoundError for unknown name', () => {
+      const registry = new AdapterRegistry();
+      expect(() => registry.get('unknown')).toThrow(AdapterNotFoundError);
+      expect(() => registry.get('unknown')).toThrow('Adapter "unknown" is not registered');
+    });
+  });
+
+  describe('has', () => {
+    it('returns false for unregistered adapter', () => {
+      const registry = new AdapterRegistry();
+      expect(registry.has('stripe')).toBe(false);
+    });
+
+    it('returns true after registration', () => {
+      const registry = new AdapterRegistry();
+      registry.register('stripe', makeAdapter());
+      expect(registry.has('stripe')).toBe(true);
+    });
+  });
+
+  describe('getAll', () => {
+    it('returns empty array when no adapters registered', () => {
+      const registry = new AdapterRegistry();
+      expect(registry.getAll()).toEqual([]);
+    });
+
+    it('returns all registered adapters with names', () => {
+      const registry = new AdapterRegistry();
+      const stripe = makeAdapter();
+      const hubspot = makeAdapter();
+      registry.register('stripe', stripe);
+      registry.register('hubspot', hubspot);
+
+      const all = registry.getAll();
+      expect(all).toHaveLength(2);
+      expect(all).toContainEqual({ name: 'stripe', adapter: stripe });
+      expect(all).toContainEqual({ name: 'hubspot', adapter: hubspot });
+    });
+  });
+});

package/src/plugins/__tests__/lifecycle.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest';
+import { PluginLifecycleManager } from '../lifecycle.js';
+import type { PluginLifecycleEvent } from '../types.js';
+
+describe('PluginLifecycleManager', () => {
+  describe('register and emit', () => {
+    it('calls registered handler on emit', async () => {
+      const manager = new PluginLifecycleManager();
+      const handler = vi.fn().mockResolvedValue(undefined);
+      manager.register('afterBoot', handler);
+
+      await manager.emit('afterBoot');
+      expect(handler).toHaveBeenCalledOnce();
+    });
+
+    it('passes arguments to handler', async () => {
+      const manager = new PluginLifecycleManager();
+      const handler = vi.fn().mockResolvedValue(undefined);
+      manager.register('beforeRequest', handler);
+
+      await manager.emit('beforeRequest', { url: '/api/test' });
+      expect(handler).toHaveBeenCalledWith({ url: '/api/test' });
+    });
+
+    it('calls multiple handlers in registration order', async () => {
+      const manager = new PluginLifecycleManager();
+      const order: number[] = [];
+
+      manager.register('afterBoot', async () => {
+        order.push(1);
+      });
+      manager.register('afterBoot', async () => {
+        order.push(2);
+      });
+      manager.register('afterBoot', async () => {
+        order.push(3);
+      });
+
+      await manager.emit('afterBoot');
+      expect(order).toEqual([1, 2, 3]);
+    });
+
+    it('does nothing when no handlers for event', async () => {
+      const manager = new PluginLifecycleManager();
+      await expect(manager.emit('beforeShutdown')).resolves.toBeUndefined();
+    });
+
+    it('supports all lifecycle events', async () => {
+      const manager = new PluginLifecycleManager();
+      const events: PluginLifecycleEvent[] = [
+        'beforeBoot',
+        'afterBoot',
+        'beforeRequest',
+        'afterRequest',
+        'beforeShutdown',
+      ];
+
+      for (const event of events) {
+        const handler = vi.fn().mockResolvedValue(undefined);
+        manager.register(event, handler);
+        await manager.emit(event);
+        expect(handler).toHaveBeenCalledOnce();
+      }
+    });
+
+    it('awaits async handlers sequentially', async () => {
+      const manager = new PluginLifecycleManager();
+      const order: number[] = [];
+
+      manager.register('afterBoot', async () => {
+        await new Promise((r) => setTimeout(r, 10));
+        order.push(1);
+      });
+      manager.register('afterBoot', async () => {
+        order.push(2);
+      });
+
+      await manager.emit('afterBoot');
+      expect(order).toEqual([1, 2]);
+    });
+  });
+
+  describe('getHandlers', () => {
+    it('returns empty array for unregistered event', () => {
+      const manager = new PluginLifecycleManager();
+      expect(manager.getHandlers('beforeBoot')).toEqual([]);
+    });
+
+    it('returns registered handlers', () => {
+      const manager = new PluginLifecycleManager();
+      const handler = vi.fn().mockResolvedValue(undefined);
+      manager.register('afterBoot', handler);
+      expect(manager.getHandlers('afterBoot')).toEqual([handler]);
+    });
+  });
+});