@rangka/core 0.0.1

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

@@ -0,0 +1,175 @@
+import { describe, it, expect } from 'vitest';
+import {
+  ServiceRegistry,
+  ServiceCircularDependencyError,
+  ServiceNotFoundError,
+  DuplicateServiceError,
+} from '../registry.js';
+import type { ServiceDefinition, ServiceContext } from '../types.js';
+
+const baseContext: Omit<ServiceContext, 'service'> = {
+  db: {} as ServiceContext['db'],
+  schema: {} as ServiceContext['schema'],
+  enqueue: async () => {},
+  events: { emit: async () => {}, on: () => {} },
+  config: {},
+};
+
+describe('ServiceRegistry', () => {
+  it('registers and retrieves a service', () => {
+    const registry = new ServiceRegistry();
+    const def: ServiceDefinition = {
+      name: 'notifications',
+      factory: () => ({
+        send: async (msg: unknown) => msg,
+      }),
+    };
+
+    registry.register(def);
+    expect(registry.has('notifications')).toBe(true);
+
+    const instance = registry.get('notifications', baseContext);
+    expect(instance.send).toBeTypeOf('function');
+  });
+
+  it('returns the same instance on repeated get (lazy singleton)', () => {
+    const registry = new ServiceRegistry();
+    let callCount = 0;
+    registry.register({
+      name: 'counter',
+      factory: () => {
+        callCount++;
+        return { count: () => callCount };
+      },
+    });
+
+    const a = registry.get('counter', baseContext);
+    const b = registry.get('counter', baseContext);
+    expect(a).toBe(b);
+    expect(callCount).toBe(1);
+  });
+
+  it('throws on duplicate registration', () => {
+    const registry = new ServiceRegistry();
+    registry.register({ name: 'svc', factory: () => ({}) });
+
+    expect(() => registry.register({ name: 'svc', factory: () => ({}) })).toThrow(
+      DuplicateServiceError,
+    );
+  });
+
+  it('throws when getting an unregistered service', () => {
+    const registry = new ServiceRegistry();
+
+    expect(() => registry.get('nonexistent', baseContext)).toThrow(ServiceNotFoundError);
+  });
+
+  it('detects circular dependencies at registration time', () => {
+    const registry = new ServiceRegistry();
+    registry.register({ name: 'a', deps: ['b'], factory: () => ({}) });
+    registry.register({ name: 'b', deps: ['c'], factory: () => ({}) });
+    registry.register({ name: 'c', deps: ['a'], factory: () => ({}) });
+
+    expect(() => registry.detectCircularDependencies()).toThrow(ServiceCircularDependencyError);
+  });
+
+  it('does not throw for valid dependency graph', () => {
+    const registry = new ServiceRegistry();
+    registry.register({ name: 'a', deps: ['b'], factory: () => ({}) });
+    registry.register({ name: 'b', deps: ['c'], factory: () => ({}) });
+    registry.register({ name: 'c', factory: () => ({}) });
+
+    expect(() => registry.detectCircularDependencies()).not.toThrow();
+  });
+
+  it('injects dependencies via service() in context', () => {
+    const registry = new ServiceRegistry();
+    registry.register({
+      name: 'logger',
+      factory: () => ({ log: (msg: unknown) => `logged: ${msg}` }),
+    });
+    registry.register({
+      name: 'mailer',
+      deps: ['logger'],
+      factory: (ctx: ServiceContext) => ({
+        send: (to: unknown) => {
+          const logger = ctx.service('logger');
+          return (logger as any).log(`email to ${to}`);
+        },
+      }),
+    });
+
+    const mailer = registry.get('mailer', baseContext);
+    expect(mailer.send('user@test.com')).toBe('logged: email to user@test.com');
+  });
+
+  it('resolves deep dependency chains', () => {
+    const registry = new ServiceRegistry();
+    registry.register({
+      name: 'c',
+      factory: () => ({ value: () => 42 }),
+    });
+    registry.register({
+      name: 'b',
+      deps: ['c'],
+      factory: (ctx) => ({ value: () => (ctx.service('c') as any).value() + 1 }),
+    });
+    registry.register({
+      name: 'a',
+      deps: ['b'],
+      factory: (ctx) => ({ value: () => (ctx.service('b') as any).value() + 1 }),
+    });
+
+    const a = registry.get('a', baseContext);
+    expect(a.value()).toBe(44);
+  });
+
+  it('detects circular dependency at runtime during resolution', () => {
+    const registry = new ServiceRegistry();
+    registry.register({
+      name: 'x',
+      deps: ['y'],
+      factory: (ctx) => {
+        ctx.service('y');
+        return {};
+      },
+    });
+    registry.register({
+      name: 'y',
+      deps: ['x'],
+      factory: (ctx) => {
+        ctx.service('x');
+        return {};
+      },
+    });
+
+    expect(() => registry.get('x', baseContext)).toThrow(ServiceCircularDependencyError);
+  });
+
+  it('reset clears cached instances', () => {
+    const registry = new ServiceRegistry();
+    let callCount = 0;
+    registry.register({
+      name: 'svc',
+      factory: () => {
+        callCount++;
+        return {};
+      },
+    });
+
+    registry.get('svc', baseContext);
+    expect(callCount).toBe(1);
+
+    registry.reset();
+    registry.get('svc', baseContext);
+    expect(callCount).toBe(2);
+  });
+
+  it('getAll returns all definitions', () => {
+    const registry = new ServiceRegistry();
+    registry.register({ name: 'a', factory: () => ({}) });
+    registry.register({ name: 'b', factory: () => ({}) });
+
+    expect(registry.getAll()).toHaveLength(2);
+  });
+});

package/src/services/index.ts

@@ -0,0 +1,13 @@
+export {
+  ServiceRegistry,
+  ServiceCircularDependencyError,
+  ServiceNotFoundError,
+  DuplicateServiceError,
+} from './registry.js';
+export type {
+  ServiceDefinition,
+  ServiceFactory,
+  ServiceInstance,
+  ServiceDependency,
+  ServiceContext,
+} from './types.js';

package/src/services/registry.ts

@@ -0,0 +1,156 @@
+import type { ServiceDefinition, ServiceInstance, ServiceContext } from './types.js';
+
+// --- Error types ---
+
+export class ServiceCircularDependencyError extends Error {
+  constructor(public readonly cycle: string[]) {
+    super(`Circular service dependency detected: ${cycle.join(' → ')}`);
+    this.name = 'ServiceCircularDependencyError';
+  }
+}
+
+export class ServiceNotFoundError extends Error {
+  constructor(public readonly serviceName: string) {
+    super(`Service "${serviceName}" is not registered`);
+    this.name = 'ServiceNotFoundError';
+  }
+}
+
+export class DuplicateServiceError extends Error {
+  constructor(public readonly serviceName: string) {
+    super(`Service "${serviceName}" is already registered`);
+    this.name = 'DuplicateServiceError';
+  }
+}
+
+// --- Registry ---
+
+/**
+ * Manages service definitions and lazily-created singleton instances.
+ * Services declare dependencies by name; the registry resolves them on first access.
+ */
+export class ServiceRegistry {
+  /** Registered service blueprints (name -> definition). */
+  private definitions = new Map<string, ServiceDefinition>();
+
+  /** Cached singleton instances, created on first `get()` call. */
+  private instances = new Map<string, ServiceInstance>();
+
+  /** Tracks which services are mid-resolution to detect runtime cycles. */
+  private resolving = new Set<string>();
+
+  // --- Registration & lookup ---
+
+  /** Register a service definition. Throws if the name is already taken. */
+  register(definition: ServiceDefinition): void {
+    if (this.definitions.has(definition.name)) {
+      throw new DuplicateServiceError(definition.name);
+    }
+    this.definitions.set(definition.name, definition);
+  }
+
+  /** Check whether a service name has been registered. */
+  has(name: string): boolean {
+    return this.definitions.has(name);
+  }
+
+  /** Return the raw definition for a service, or undefined if not registered. */
+  getDefinition(name: string): ServiceDefinition | undefined {
+    return this.definitions.get(name);
+  }
+
+  /** Return all registered definitions. */
+  getAll(): ServiceDefinition[] {
+    return [...this.definitions.values()];
+  }
+
+  // --- Dependency validation ---
+
+  /**
+   * Walk the full dependency graph up-front and throw if any cycle exists.
+   * Uses depth-first traversal with a recursion stack to detect back-edges.
+   */
+  detectCircularDependencies(): void {
+    const fullyVisited = new Set<string>();
+    const currentPath = new Set<string>();
+
+    const visit = (serviceName: string, ancestors: string[]): void => {
+      // Back-edge: we've looped back to a node already on the current path.
+      if (currentPath.has(serviceName)) {
+        const cycleStart = ancestors.indexOf(serviceName);
+        throw new ServiceCircularDependencyError([...ancestors.slice(cycleStart), serviceName]);
+      }
+
+      // Already fully explored from a previous traversal root -- skip.
+      if (fullyVisited.has(serviceName)) return;
+
+      currentPath.add(serviceName);
+      ancestors.push(serviceName);
+
+      const definition = this.definitions.get(serviceName);
+      if (definition?.deps) {
+        for (const dependency of definition.deps) {
+          visit(dependency, ancestors);
+        }
+      }
+
+      ancestors.pop();
+      currentPath.delete(serviceName);
+      fullyVisited.add(serviceName);
+    };
+
+    for (const serviceName of this.definitions.keys()) {
+      visit(serviceName, []);
+    }
+  }
+
+  // --- Resolution ---
+
+  /**
+   * Resolve a service by name: return the cached instance or create it via its factory.
+   * Dependencies are resolved recursively through the same mechanism.
+   */
+  get(name: string, baseContext: Omit<ServiceContext, 'service'>): ServiceInstance {
+    // Return cached singleton if already instantiated.
+    const cached = this.instances.get(name);
+    if (cached) return cached;
+
+    const definition = this.definitions.get(name);
+    if (!definition) {
+      throw new ServiceNotFoundError(name);
+    }
+
+    // Guard against runtime circular resolution (e.g. A -> B -> A).
+    if (this.resolving.has(name)) {
+      throw new ServiceCircularDependencyError([...this.resolving, name]);
+    }
+
+    this.resolving.add(name);
+    try {
+      const instance = this.createInstance(definition, baseContext);
+      this.instances.set(name, instance);
+      return instance;
+    } finally {
+      this.resolving.delete(name);
+    }
+  }
+
+  /** Discard all cached instances (definitions remain registered). */
+  reset(): void {
+    this.instances.clear();
+  }
+
+  // --- Private helpers ---
+
+  /** Invoke a service factory with a context that can resolve sibling services. */
+  private createInstance(
+    definition: ServiceDefinition,
+    baseContext: Omit<ServiceContext, 'service'>,
+  ): ServiceInstance {
+    const context: ServiceContext = {
+      ...baseContext,
+      service: (dependencyName: string) => this.get(dependencyName, baseContext),
+    };
+    return definition.factory(context);
+  }
+}

package/src/services/types.ts

@@ -0,0 +1,27 @@
+import type { FrameworkContext, ServiceInstance } from '@rangka/shared';
+
+export interface ServiceDependency {
+  name: string;
+}
+
+export interface ServiceDefinition {
+  name: string;
+  deps?: string[];
+  factory: ServiceFactory;
+}
+
+export type ServiceFactory = (ctx: ServiceContext) => ServiceInstance;
+
+export type { ServiceInstance };
+
+export interface ServiceContext {
+  db: FrameworkContext['db'];
+  schema: FrameworkContext['schema'];
+  enqueue: FrameworkContext['enqueue'];
+  events: FrameworkContext['events'];
+  config: FrameworkContext['config'];
+  models?: FrameworkContext['models'];
+  auth?: FrameworkContext['auth'];
+  scope?: FrameworkContext['scope'];
+  service: (name: string) => ServiceInstance;
+}

package/src/validation/__tests__/field-validator.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect } from 'vitest';
+import { validateFields } from '../field-validator.js';
+import type { ResolvedModel, ResolvedField } from '../../schema/types.js';
+import type { FieldConfig } from '@rangka/shared';
+
+function makeModel(fields: ResolvedField[]): ResolvedModel {
+  return {
+    app: 'test',
+    module: 'test',
+    name: 'item',
+    qualifiedName: 'test.item',
+    auditLog: false,
+    traits: [],
+    fields,
+    indexes: [],
+  };
+}
+
+function field(name: string, config: Partial<FieldConfig> & { type: string }): ResolvedField {
+  return { name, config: config as FieldConfig, provenance: { source: 'base' } };
+}
+
+describe('validateFields', () => {
+  describe('minLength / maxLength', () => {
+    const model = makeModel([
+      field('name', { type: 'string', validation: { minLength: 3, maxLength: 50 } }),
+    ]);
+
+    it('passes when string length is within bounds', () => {
+      expect(validateFields(model, { name: 'hello' }, 'create')).toEqual([]);
+    });
+
+    it('fails when string is too short', () => {
+      const result = validateFields(model, { name: 'ab' }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].field).toBe('name');
+      expect(result[0].rule).toBe('minLength');
+    });
+
+    it('fails when string is too long', () => {
+      const result = validateFields(model, { name: 'a'.repeat(51) }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].field).toBe('name');
+      expect(result[0].rule).toBe('maxLength');
+    });
+  });
+
+  describe('min / max', () => {
+    const model = makeModel([field('quantity', { type: 'int', validation: { min: 0, max: 100 } })]);
+
+    it('passes when number is within bounds', () => {
+      expect(validateFields(model, { quantity: 50 }, 'create')).toEqual([]);
+    });
+
+    it('fails when number is below min', () => {
+      const result = validateFields(model, { quantity: -1 }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].field).toBe('quantity');
+      expect(result[0].rule).toBe('min');
+    });
+
+    it('fails when number is above max', () => {
+      const result = validateFields(model, { quantity: 101 }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].field).toBe('quantity');
+      expect(result[0].rule).toBe('max');
+    });
+
+    it('passes at exact boundaries', () => {
+      expect(validateFields(model, { quantity: 0 }, 'create')).toEqual([]);
+      expect(validateFields(model, { quantity: 100 }, 'create')).toEqual([]);
+    });
+  });
+
+  describe('pattern', () => {
+    const model = makeModel([
+      field('code', { type: 'string', validation: { pattern: '^[A-Z]{3}-\\d+$' } }),
+    ]);
+
+    it('passes when value matches pattern', () => {
+      expect(validateFields(model, { code: 'ABC-123' }, 'create')).toEqual([]);
+    });
+
+    it('fails when value does not match pattern', () => {
+      const result = validateFields(model, { code: 'abc-123' }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].field).toBe('code');
+      expect(result[0].rule).toBe('pattern');
+    });
+  });
+
+  describe('format', () => {
+    const model = makeModel([
+      field('email', { type: 'string', validation: { format: 'email' } }),
+      field('website', { type: 'string', validation: { format: 'url' } }),
+      field('ref', { type: 'string', validation: { format: 'uuid' } }),
+    ]);
+
+    it('passes valid email', () => {
+      expect(validateFields(model, { email: 'user@example.com' }, 'create')).toEqual([]);
+    });
+
+    it('fails invalid email', () => {
+      const result = validateFields(model, { email: 'not-an-email' }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].rule).toBe('format');
+    });
+
+    it('passes valid url', () => {
+      expect(validateFields(model, { website: 'https://example.com' }, 'create')).toEqual([]);
+    });
+
+    it('fails invalid url', () => {
+      const result = validateFields(model, { website: 'not-a-url' }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].rule).toBe('format');
+    });
+
+    it('passes valid uuid', () => {
+      expect(
+        validateFields(model, { ref: '550e8400-e29b-41d4-a716-446655440000' }, 'create'),
+      ).toEqual([]);
+    });
+
+    it('fails invalid uuid', () => {
+      const result = validateFields(model, { ref: 'not-a-uuid' }, 'create');
+      expect(result).toHaveLength(1);
+      expect(result[0].rule).toBe('format');
+    });
+
+    it('ignores unknown format', () => {
+      const m = makeModel([
+        field('x', { type: 'string', validation: { format: 'unknown_format' } }),
+      ]);
+      expect(validateFields(m, { x: 'anything' }, 'create')).toEqual([]);
+    });
+  });
+
+  describe('custom message', () => {
+    it('uses custom message when provided', () => {
+      const model = makeModel([
+        field('age', {
+          type: 'int',
+          validation: { min: 18, message: 'Must be at least 18 years old' },
+        }),
+      ]);
+      const result = validateFields(model, { age: 10 }, 'create');
+      expect(result[0].message).toBe('Must be at least 18 years old');
+    });
+  });
+
+  describe('update operation', () => {
+    const model = makeModel([
+      field('name', { type: 'string', validation: { minLength: 3 } }),
+      field('quantity', { type: 'int', validation: { min: 0 } }),
+    ]);
+
+    it('only validates fields present in body', () => {
+      expect(validateFields(model, { quantity: 5 }, 'update')).toEqual([]);
+    });
+
+    it('validates fields that are present', () => {
+      const result = validateFields(model, { name: 'ab' }, 'update');
+      expect(result).toHaveLength(1);
+      expect(result[0].field).toBe('name');
+    });
+
+    it('skips null/undefined fields', () => {
+      expect(validateFields(model, { name: undefined }, 'update')).toEqual([]);
+      expect(validateFields(model, { name: null }, 'update')).toEqual([]);
+    });
+  });
+
+  describe('fields without validation config', () => {
+    const model = makeModel([field('title', { type: 'string' }), field('count', { type: 'int' })]);
+
+    it('skips fields without validation', () => {
+      expect(validateFields(model, { title: '', count: -999 }, 'create')).toEqual([]);
+    });
+  });
+
+  describe('multiple violations', () => {
+    const model = makeModel([
+      field('name', { type: 'string', validation: { minLength: 3 } }),
+      field('quantity', { type: 'int', validation: { min: 0 } }),
+    ]);
+
+    it('returns all violations at once', () => {
+      const result = validateFields(model, { name: 'ab', quantity: -1 }, 'create');
+      expect(result).toHaveLength(2);
+      expect(result.map((v) => v.field)).toContain('name');
+      expect(result.map((v) => v.field)).toContain('quantity');
+    });
+  });
+});

package/src/validation/field-validator.ts

@@ -0,0 +1,113 @@
+import type { ResolvedModel } from '../schema/types.js';
+import type { ValidationConfig } from '@rangka/shared';
+import { isNil } from '../helpers/coerce.js';
+
+export interface FieldViolation {
+  field: string;
+  rule: string;
+  message: string;
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\/.+/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const FORMAT_VALIDATORS: Record<string, (value: string) => boolean> = {
+  email: (v) => EMAIL_RE.test(v),
+  url: (v) => URL_RE.test(v),
+  uuid: (v) => UUID_RE.test(v),
+};
+
+export function validateFields(
+  model: ResolvedModel,
+  body: Record<string, unknown>,
+  operation: 'create' | 'update',
+): FieldViolation[] {
+  const violations: FieldViolation[] = [];
+
+  for (const field of model.fields) {
+    if (!('validation' in field.config)) continue;
+    const validation = (field.config as { validation?: ValidationConfig }).validation;
+    if (!validation) continue;
+
+    const value = body[field.name];
+
+    if (isNil(value)) {
+      if (operation === 'update') continue;
+      continue;
+    }
+
+    const fieldViolations = validateValue(field.name, value, validation);
+    violations.push(...fieldViolations);
+  }
+
+  return violations;
+}
+
+function validateValue(
+  fieldName: string,
+  value: unknown,
+  config: ValidationConfig,
+): FieldViolation[] {
+  const violations: FieldViolation[] = [];
+
+  if (typeof value === 'string') {
+    if (config.minLength !== undefined && value.length < config.minLength) {
+      violations.push({
+        field: fieldName,
+        rule: 'minLength',
+        message: config.message ?? `${fieldName} must be at least ${config.minLength} characters`,
+      });
+    }
+
+    if (config.maxLength !== undefined && value.length > config.maxLength) {
+      violations.push({
+        field: fieldName,
+        rule: 'maxLength',
+        message: config.message ?? `${fieldName} must be at most ${config.maxLength} characters`,
+      });
+    }
+
+    if (config.pattern !== undefined) {
+      const re = new RegExp(config.pattern);
+      if (!re.test(value)) {
+        violations.push({
+          field: fieldName,
+          rule: 'pattern',
+          message: config.message ?? `${fieldName} does not match the required pattern`,
+        });
+      }
+    }
+
+    if (config.format !== undefined) {
+      const validator = FORMAT_VALIDATORS[config.format];
+      if (validator && !validator(value)) {
+        violations.push({
+          field: fieldName,
+          rule: 'format',
+          message: config.message ?? `${fieldName} must be a valid ${config.format}`,
+        });
+      }
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (config.min !== undefined && value < config.min) {
+      violations.push({
+        field: fieldName,
+        rule: 'min',
+        message: config.message ?? `${fieldName} must be at least ${config.min}`,
+      });
+    }
+
+    if (config.max !== undefined && value > config.max) {
+      violations.push({
+        field: fieldName,
+        rule: 'max',
+        message: config.message ?? `${fieldName} must be at most ${config.max}`,
+      });
+    }
+  }
+
+  return violations;
+}

package/src/validation/index.ts

@@ -0,0 +1 @@
+export { validateFields, type FieldViolation } from './field-validator.js';

package/src/widgets/index.ts

@@ -0,0 +1,3 @@
+export { WidgetRegistry } from './widget-registry.js';
+export { validatePageBody } from './slot-validator.js';
+export type { SlotValidationError } from './slot-validator.js';