@rangka/core 0.1.0 → 0.1.2

package/src/plugins/loader.ts

@@ -1,126 +0,0 @@
-import type {
-  PluginDefinition,
-  PluginBootContext,
-  DataAdapter,
-  PluginLifecycleEvent,
-  LifecycleHandler,
-} from './types.js';
-import { AdapterRegistry } from './adapter-registry.js';
-import { PluginLifecycleManager } from './lifecycle.js';
-
-export class DuplicatePluginError extends Error {
-  constructor(public readonly pluginName: string) {
-    super(`Plugin "${pluginName}" is already registered`);
-    this.name = 'DuplicatePluginError';
-  }
-}
-
-export class PluginConfigError extends Error {
-  constructor(
-    public readonly pluginName: string,
-    public readonly field: string,
-  ) {
-    super(`Plugin "${pluginName}" requires config field "${field}"`);
-    this.name = 'PluginConfigError';
-  }
-}
-
-export class MissingAdapterImplementationError extends Error {
-  constructor(
-    public readonly pluginName: string,
-    public readonly adapterName: string,
-  ) {
-    super(
-      `Plugin "${pluginName}" declares adapter "${adapterName}" in provides but did not implement it during boot`,
-    );
-    this.name = 'MissingAdapterImplementationError';
-  }
-}
-
-export interface LoadPluginsOptions {
-  plugins: PluginDefinition[];
-  config?: Record<string, Record<string, unknown>>;
-}
-
-export interface LoadPluginsResult {
-  adapterRegistry: AdapterRegistry;
-  lifecycleManager: PluginLifecycleManager;
-}
-
-export async function loadPlugins(options: LoadPluginsOptions): Promise<LoadPluginsResult> {
-  const { plugins, config = {} } = options;
-  const adapterRegistry = new AdapterRegistry();
-  const lifecycleManager = new PluginLifecycleManager();
-
-  const seen = new Set<string>();
-  for (const plugin of plugins) {
-    if (seen.has(plugin.name)) {
-      throw new DuplicatePluginError(plugin.name);
-    }
-    seen.add(plugin.name);
-  }
-
-  for (const plugin of plugins) {
-    const pluginConfig = resolveConfig(plugin, config[plugin.name] ?? {});
-    const implemented = new Set<string>();
-
-    const adapterProxies: Record<string, { implement(impl: DataAdapter): void }> = {};
-    if (plugin.provides?.adapters) {
-      for (const decl of plugin.provides.adapters) {
-        adapterProxies[decl.name] = {
-          implement(impl: DataAdapter) {
-            adapterRegistry.register(decl.name, impl);
-            implemented.add(decl.name);
-          },
-        };
-      }
-    }
-
-    const ctx: PluginBootContext = {
-      config: pluginConfig,
-      adapters: adapterProxies,
-      on(event: PluginLifecycleEvent, handler: LifecycleHandler) {
-        lifecycleManager.register(event, handler);
-      },
-    };
-
-    await plugin.boot(ctx);
-
-    if (plugin.provides?.adapters) {
-      for (const decl of plugin.provides.adapters) {
-        if (!implemented.has(decl.name)) {
-          throw new MissingAdapterImplementationError(plugin.name, decl.name);
-        }
-      }
-    }
-  }
-
-  return { adapterRegistry, lifecycleManager };
-}
-
-function resolveConfig(
-  plugin: PluginDefinition,
-  userConfig: Record<string, unknown>,
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-
-  if (!plugin.config) return userConfig;
-
-  for (const [key, schema] of Object.entries(plugin.config)) {
-    if (userConfig[key] !== undefined) {
-      result[key] = userConfig[key];
-    } else if (schema.default !== undefined) {
-      result[key] = schema.default;
-    } else if (schema.required) {
-      throw new PluginConfigError(plugin.name, key);
-    }
-  }
-
-  for (const [key, value] of Object.entries(userConfig)) {
-    if (!(key in result)) {
-      result[key] = value;
-    }
-  }
-
-  return result;
-}

package/src/plugins/types.ts

@@ -1,76 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
-export type AdapterCapability =
-  | 'read'
-  | 'list'
-  | 'filter'
-  | 'sort'
-  | 'create'
-  | 'update'
-  | 'delete';
-
-export interface FilterExpression {
-  field: string;
-  operator: string;
-  value: unknown;
-}
-
-export interface ListQuery {
-  page?: number;
-  pageSize?: number;
-  sort?: { field: string; direction: 'asc' | 'desc' };
-  filters?: FilterExpression[];
-}
-
-export interface ListResult {
-  data: Record<string, unknown>[];
-  total?: number;
-  hasMore?: boolean;
-}
-
-export interface DataAdapter {
-  get(model: string, id: string): Promise<Record<string, unknown> | null>;
-  list?(model: string, query: ListQuery): Promise<ListResult>;
-  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<void>;
-  filter?(model: string, filters: FilterExpression[]): Promise<ListResult>;
-  batchGet?(model: string, ids: string[]): Promise<Record<string, unknown>[]>;
-}
-
-export type PluginLifecycleEvent =
-  | 'beforeBoot'
-  | 'afterBoot'
-  | 'beforeRequest'
-  | 'afterRequest'
-  | 'beforeShutdown';
-
-export interface PluginConfigField {
-  type: string;
-  required?: boolean;
-  default?: unknown;
-}
-
-export interface PluginProvides {
-  adapters?: Array<{ name: string; capabilities: AdapterCapability[] }>;
-}
-
-export interface PluginBootContext {
-  config: Record<string, unknown>;
-  adapters: Record<string, { implement(impl: DataAdapter): void }>;
-  on(event: PluginLifecycleEvent, handler: (...args: any[]) => Promise<void>): void;
-}
-
-export interface PluginDefinition {
-  name: string;
-  version: string;
-  config?: Record<string, PluginConfigField>;
-  provides?: PluginProvides;
-  boot(ctx: PluginBootContext): void | Promise<void>;
-}
-
-export type LifecycleHandler = (...args: any[]) => Promise<void>;

package/src/plugins/validator.ts

@@ -1,141 +0,0 @@
-import type { AdapterRegistry } from './adapter-registry.js';
-import type { AdapterCapability, PluginDefinition } from './types.js';
-import type { ResolvedModel } from '../schema/types.js';
-
-export interface PluginValidationError {
-  type:
-    | 'MISSING_ADAPTER_IMPL'
-    | 'UNRESOLVED_SOURCE'
-    | 'CONFIG_REQUIRED'
-    | 'DUPLICATE_PLUGIN'
-    | 'CAPABILITY_VIOLATION';
-  plugin?: string;
-  model?: string;
-  message: string;
-}
-
-export interface ValidationResult {
-  valid: boolean;
-  errors: PluginValidationError[];
-  warnings: string[];
-}
-
-export function validatePluginSetup(
-  adapterRegistry: AdapterRegistry,
-  externalModels: ResolvedModel[],
-  pluginDefinitions: PluginDefinition[],
-  adapterCapabilities?: Record<string, AdapterCapability[]>,
-): ValidationResult {
-  const errors: PluginValidationError[] = [];
-  const warnings: string[] = [];
-
-  checkDuplicatePlugins(pluginDefinitions, errors);
-  checkAdapterImplementations(pluginDefinitions, adapterRegistry, errors);
-  checkExternalModelSources(externalModels, adapterRegistry, errors);
-  checkCapabilityViolations(externalModels, adapterCapabilities ?? {}, errors);
-  checkBatchGetSupport(externalModels, adapterRegistry, warnings);
-
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings,
-  };
-}
-
-function checkDuplicatePlugins(plugins: PluginDefinition[], errors: PluginValidationError[]): void {
-  const seen = new Set<string>();
-  for (const plugin of plugins) {
-    if (seen.has(plugin.name)) {
-      errors.push({
-        type: 'DUPLICATE_PLUGIN',
-        plugin: plugin.name,
-        message: `Duplicate plugin name: "${plugin.name}"`,
-      });
-    }
-    seen.add(plugin.name);
-  }
-}
-
-function checkAdapterImplementations(
-  plugins: PluginDefinition[],
-  adapterRegistry: AdapterRegistry,
-  errors: PluginValidationError[],
-): void {
-  for (const plugin of plugins) {
-    if (!plugin.provides?.adapters) continue;
-    for (const decl of plugin.provides.adapters) {
-      if (!adapterRegistry.has(decl.name)) {
-        errors.push({
-          type: 'MISSING_ADAPTER_IMPL',
-          plugin: plugin.name,
-          message: `Plugin "${plugin.name}" declares adapter "${decl.name}" but it is not registered`,
-        });
-      }
-    }
-  }
-}
-
-function checkExternalModelSources(
-  models: ResolvedModel[],
-  adapterRegistry: AdapterRegistry,
-  errors: PluginValidationError[],
-): void {
-  for (const model of models) {
-    if (!model.source) continue;
-    if (!adapterRegistry.has(model.source)) {
-      errors.push({
-        type: 'UNRESOLVED_SOURCE',
-        model: model.qualifiedName,
-        message: `External model "${model.qualifiedName}" references adapter "${model.source}" which is not registered`,
-      });
-    }
-  }
-}
-
-function checkBatchGetSupport(
-  models: ResolvedModel[],
-  adapterRegistry: AdapterRegistry,
-  warnings: string[],
-): void {
-  for (const model of models) {
-    if (!model.source) continue;
-    if (!adapterRegistry.has(model.source)) continue;
-
-    const adapter = adapterRegistry.get(model.source);
-    if (!adapter.batchGet) {
-      warnings.push(
-        `Adapter "${model.source}" used by "${model.qualifiedName}" does not implement batchGet. Relationship resolution will use N+1 get calls.`,
-      );
-    }
-  }
-}
-
-function checkCapabilityViolations(
-  models: ResolvedModel[],
-  adapterCapabilities: Record<string, AdapterCapability[]>,
-  errors: PluginValidationError[],
-): void {
-  for (const model of models) {
-    if (!model.source) continue;
-    const declared = adapterCapabilities[model.source];
-    if (!declared) continue;
-
-    const capabilities = new Set(declared);
-
-    if (!capabilities.has('read')) {
-      errors.push({
-        type: 'CAPABILITY_VIOLATION',
-        model: model.qualifiedName,
-        message: `External model "${model.qualifiedName}" uses adapter "${model.source}" which does not declare the required "read" capability`,
-      });
-    }
-
-    if (!capabilities.has('list')) {
-      errors.push({
-        type: 'CAPABILITY_VIOLATION',
-        model: model.qualifiedName,
-        message: `External model "${model.qualifiedName}" uses adapter "${model.source}" which does not declare "list" capability. List endpoints will not be generated.`,
-      });
-    }
-  }
-}

package/src/schema/__tests__/registry-models-by-module.test.ts

@@ -1,58 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { SchemaRegistry } from '../registry.js';
-import type { ResolvedModel } from '../types.js';
-
-function makeModel(module: string, name: string): ResolvedModel {
-  return {
-    qualifiedName: `${module}.${name}`,
-    app: 'test',
-    module,
-    name,
-    auditLog: false,
-    traits: [],
-    fields: [{ name: 'id', config: { type: 'string' }, provenance: { source: 'base' } }],
-    indexes: [],
-  };
-}
-
-describe('SchemaRegistry.getModelsByModule', () => {
-  it('returns empty map for empty registry', () => {
-    const registry = new SchemaRegistry([]);
-    const result = registry.getModelsByModule();
-    expect(result.size).toBe(0);
-  });
-
-  it('groups models by module', () => {
-    const models = [
-      makeModel('sales', 'invoice'),
-      makeModel('sales', 'customer'),
-      makeModel('accounting', 'journal_entry'),
-    ];
-    const registry = new SchemaRegistry(models);
-    const result = registry.getModelsByModule();
-
-    expect(result.size).toBe(2);
-    expect(result.get('sales')).toHaveLength(2);
-    expect(result.get('accounting')).toHaveLength(1);
-  });
-
-  it('preserves model data', () => {
-    const models = [makeModel('sales', 'invoice')];
-    const registry = new SchemaRegistry(models);
-    const result = registry.getModelsByModule();
-    const salesModels = result.get('sales')!;
-    expect(salesModels[0].qualifiedName).toBe('sales.invoice');
-    expect(salesModels[0].name).toBe('invoice');
-  });
-
-  it('handles single module with multiple models', () => {
-    const models = [
-      makeModel('hr', 'employee'),
-      makeModel('hr', 'department'),
-      makeModel('hr', 'leave_request'),
-    ];
-    const registry = new SchemaRegistry(models);
-    const result = registry.getModelsByModule();
-    expect(result.get('hr')).toHaveLength(3);
-  });
-});

package/src/schema/registry.ts

@@ -1,93 +0,0 @@
-import type { ResolvedModel, ResolvedField, ModelRelationship, ExtensionSource } from './types.js';
-import { buildRelationships } from './relationships.js';
-
-/**
- * Central registry providing lookup access to all resolved models,
- * their relationships, and extension metadata.
- */
-export class SchemaRegistry {
-  private readonly modelMap: Map<string, ResolvedModel>;
-  private readonly relationships: ModelRelationship[];
-  private readonly extensionSourceMap: Map<string, ExtensionSource[]>;
-
-  constructor(models: ResolvedModel[]) {
-    this.modelMap = new Map();
-    for (const model of models) {
-      this.modelMap.set(model.qualifiedName, model);
-    }
-    this.relationships = buildRelationships(models);
-    this.extensionSourceMap = this.buildExtensionSourceMap(models);
-  }
-
-  /** Retrieve a single model by its fully qualified name (e.g. "sales.Invoice"). */
-  getModel(qualifiedName: string): ResolvedModel | undefined {
-    return this.modelMap.get(qualifiedName);
-  }
-
-  /** Return all registered models. */
-  getAllModels(): ResolvedModel[] {
-    return Array.from(this.modelMap.values());
-  }
-
-  /** Return the field definitions for a given model. */
-  getFieldsForModel(qualifiedName: string): ResolvedField[] {
-    const model = this.modelMap.get(qualifiedName);
-    if (!model) return [];
-    return model.fields;
-  }
-
-  /** Return all computed relationships across the schema. */
-  getRelationships(): ModelRelationship[] {
-    return this.relationships;
-  }
-
-  /** Return relationships originating from a specific model. */
-  getRelationshipsForModel(qualifiedName: string): ModelRelationship[] {
-    return this.relationships.filter((r) => r.from === qualifiedName);
-  }
-
-  /** Return extension source metadata for a model (which apps contributed fields). */
-  getExtensionSources(qualifiedName: string): ExtensionSource[] {
-    return this.extensionSourceMap.get(qualifiedName) ?? [];
-  }
-
-  /** Group all models by their module name. */
-  getModelsByModule(): Map<string, ResolvedModel[]> {
-    const moduleToModels = new Map<string, ResolvedModel[]>();
-    for (const model of this.modelMap.values()) {
-      const group = moduleToModels.get(model.module) ?? [];
-      group.push(model);
-      moduleToModels.set(model.module, group);
-    }
-    return moduleToModels;
-  }
-
-  /**
-   * Builds a map from model name to the list of apps that extended it with extra fields.
-   */
-  private buildExtensionSourceMap(models: ResolvedModel[]): Map<string, ExtensionSource[]> {
-    const map = new Map<string, ExtensionSource[]>();
-
-    for (const model of models) {
-      const extensionFields = model.fields.filter((f) => f.provenance.source === 'extension');
-      if (extensionFields.length === 0) continue;
-
-      // Group extension fields by the app that contributed them
-      const fieldsByApp = new Map<string, string[]>();
-      for (const field of extensionFields) {
-        const contributingApp = field.provenance.app!;
-        const fieldNames = fieldsByApp.get(contributingApp) ?? [];
-        fieldNames.push(field.name);
-        fieldsByApp.set(contributingApp, fieldNames);
-      }
-
-      const sources: ExtensionSource[] = [];
-      for (const [app, fields] of fieldsByApp) {
-        sources.push({ app, fields });
-      }
-      map.set(model.qualifiedName, sources);
-    }
-
-    return map;
-  }
-}

package/src/schema/relationships.ts

@@ -1,93 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { ResolvedModel, ModelRelationship } from './types.js';
-
-/**
- * Scans all models for relational fields and produces a flat list of relationships.
- */
-export function buildRelationships(models: ResolvedModel[]): ModelRelationship[] {
-  const relationships: ModelRelationship[] = [];
-
-  for (const model of models) {
-    for (const field of model.fields) {
-      const relationship = fieldToRelationship(field.config, field.name, model, models);
-      if (relationship) {
-        relationships.push(relationship);
-      }
-    }
-  }
-
-  return relationships;
-}
-
-/**
- * Converts a single field config into a ModelRelationship, or returns null
- * if the field is not a relational type.
- */
-function fieldToRelationship(
-  config: any,
-  fieldName: string,
-  sourceModel: ResolvedModel,
-  allModels: ResolvedModel[],
-): ModelRelationship | null {
-  const from = sourceModel.qualifiedName;
-
-  switch (config.type) {
-    case 'link': {
-      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
-      return { type: 'link', from, field: fieldName, to: targetModel };
-    }
-    case 'hasMany': {
-      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
-      return {
-        type: 'hasMany',
-        from,
-        field: fieldName,
-        to: targetModel,
-        foreignKey: config.foreignKey,
-      };
-    }
-    case 'children': {
-      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
-      return {
-        type: 'children',
-        from,
-        field: fieldName,
-        to: targetModel,
-        foreignKey: config.foreignKey,
-      };
-    }
-    case 'manyToMany': {
-      const targetModel = resolveModelName(config.model, sourceModel.module, allModels);
-      const throughModel = resolveModelName(config.through, sourceModel.module, allModels);
-      return { type: 'manyToMany', from, field: fieldName, to: targetModel, through: throughModel };
-    }
-    case 'dynamicLink': {
-      return {
-        type: 'dynamicLink',
-        from,
-        field: fieldName,
-        to: '*',
-        modelField: config.modelField,
-      };
-    }
-    default:
-      return null;
-  }
-}
-
-/**
- * Resolves an unqualified model name (e.g. "Invoice") to its fully qualified form
- * (e.g. "accounting.Invoice") by checking the current app first, then all models.
- */
-function resolveModelName(name: string, currentModule: string, models: ResolvedModel[]): string {
-  if (name.includes('.')) return name;
-
-  const qualifiedInCurrentModule = `${currentModule}.${name}`;
-  const foundInCurrentModule = models.find((m) => m.qualifiedName === qualifiedInCurrentModule);
-  if (foundInCurrentModule) return qualifiedInCurrentModule;
-
-  const foundElsewhere = models.find((m) => m.name === name);
-  if (foundElsewhere) return foundElsewhere.qualifiedName;
-
-  return qualifiedInCurrentModule;
-}

package/src/schema/types.ts

@@ -1,43 +0,0 @@
-import type { FieldConfig, ModelConfig, ScopeConfig } from '@rangka/shared';
-
-export interface FieldProvenance {
-  source: 'base' | 'trait' | 'extension';
-  app?: string;
-  trait?: string;
-}
-
-export interface ResolvedField {
-  name: string;
-  config: FieldConfig;
-  provenance: FieldProvenance;
-}
-
-export interface ResolvedModel {
-  qualifiedName: string;
-  app: string;
-  module: string;
-  name: string;
-  label?: string;
-  naming?: ModelConfig['naming'];
-  scope?: ScopeConfig;
-  auditLog: boolean;
-  traits: string[];
-  fields: ResolvedField[];
-  indexes: ModelConfig['indexes'];
-  source?: string;
-}
-
-export interface ModelRelationship {
-  type: 'link' | 'hasMany' | 'children' | 'manyToMany' | 'dynamicLink';
-  from: string;
-  field: string;
-  to: string;
-  foreignKey?: string;
-  through?: string;
-  modelField?: string;
-}
-
-export interface ExtensionSource {
-  app: string;
-  fields: string[];
-}

package/src/services/__tests__/integration.test.ts

@@ -1,63 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { ServiceRegistry } from '../registry.js';
-import { HookRegistry } from '../../hooks/registry.js';
-import { executeHookPipeline } from '../../hooks/executor.js';
-import { SchemaRegistry } from '../../schema/registry.js';
-import { EventBus } from '../../events/bus.js';
-
-describe('hook → service → db integration', () => {
-  it('hook calls ctx.service() which accesses ctx.db', async () => {
-    const serviceRegistry = new ServiceRegistry();
-    const dbCalls: string[] = [];
-
-    serviceRegistry.register({
-      name: 'pricing',
-      factory: (_ctx) => ({
-        getDiscount: async (customerId: unknown) => {
-          dbCalls.push(`query:${customerId}`);
-          return 0.1;
-        },
-      }),
-    });
-
-    const hookRegistry = new HookRegistry();
-    hookRegistry.register(
-      'sales.order',
-      {
-        beforeSave: async (doc: any, ctx: any) => {
-          const pricing = ctx.service('pricing') as any;
-          const discount = await pricing.getDiscount(doc.customer_id);
-          doc.discount = discount;
-        },
-      },
-      'sales',
-    );
-
-    const schema = new SchemaRegistry([]);
-    const eventBus = new EventBus();
-    const auth = { user: { id: '1' }, roles: ['Admin'], scopes: {} } as any;
-
-    const mockTrx = {
-      transaction: () => ({
-        execute: async (fn: any) => fn(mockTrx),
-      }),
-    } as any;
-
-    const chain = hookRegistry.getChain('sales.order')!;
-    const result = await executeHookPipeline({
-      model: 'sales.order',
-      operation: 'create',
-      chain,
-      doc: { customer_id: 'cust-1', total: 100 } as any,
-      db: mockTrx,
-      schema,
-      auth,
-      eventBus,
-      serviceRegistry,
-      execute: async (doc) => doc,
-    });
-
-    expect(result.discount).toBe(0.1);
-    expect(dbCalls).toEqual(['query:cust-1']);
-  });
-});