@rangka/core 0.0.1

package/src/external-model/__tests__/computed-fields.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateComputedFields } from '../computed-fields.js';
+import type { ExternalFieldConfig } from '../types.js';
+
+describe('evaluateComputedFields', () => {
+  it('computes a field from existing mapped fields', () => {
+    const record = { name: 'Acme', email: 'acme@test.com' };
+    const fields: Record<string, ExternalFieldConfig> = {
+      name: { type: 'string' },
+      email: { type: 'string' },
+      displayName: {
+        type: 'string',
+        computed: {
+          depends: ['name', 'email'],
+          compute: (r) => r.name || r.email,
+        },
+      },
+    };
+
+    const result = evaluateComputedFields(record, fields);
+    expect(result.displayName).toBe('Acme');
+  });
+
+  it('uses fallback when primary depends field is missing', () => {
+    const record = { name: undefined, email: 'acme@test.com' };
+    const fields: Record<string, ExternalFieldConfig> = {
+      name: { type: 'string' },
+      email: { type: 'string' },
+      displayName: {
+        type: 'string',
+        computed: {
+          depends: ['name', 'email'],
+          compute: (r) => r.name || r.email,
+        },
+      },
+    };
+
+    const result = evaluateComputedFields(record, fields);
+    expect(result.displayName).toBe('acme@test.com');
+  });
+
+  it('does not modify non-computed fields', () => {
+    const record = { name: 'Acme', email: 'a@b.com' };
+    const fields: Record<string, ExternalFieldConfig> = {
+      name: { type: 'string' },
+      email: { type: 'string' },
+    };
+
+    const result = evaluateComputedFields(record, fields);
+    expect(result).toEqual({ name: 'Acme', email: 'a@b.com' });
+  });
+
+  it('handles numeric computed fields', () => {
+    const record = { quantity: 5, price: 10 };
+    const fields: Record<string, ExternalFieldConfig> = {
+      quantity: { type: 'int' },
+      price: { type: 'decimal' },
+      total: {
+        type: 'decimal',
+        computed: {
+          depends: ['quantity', 'price'],
+          compute: (r) => (r.quantity as number) * (r.price as number),
+        },
+      },
+    };
+
+    const result = evaluateComputedFields(record, fields);
+    expect(result.total).toBe(50);
+  });
+
+  it('computed fields can access other computed fields (order dependent)', () => {
+    const record = { firstName: 'John', lastName: 'Doe' };
+    const fields: Record<string, ExternalFieldConfig> = {
+      firstName: { type: 'string' },
+      lastName: { type: 'string' },
+      fullName: {
+        type: 'string',
+        computed: {
+          depends: ['firstName', 'lastName'],
+          compute: (r) => `${r.firstName} ${r.lastName}`,
+        },
+      },
+    };
+
+    const result = evaluateComputedFields(record, fields);
+    expect(result.fullName).toBe('John Doe');
+  });
+
+  it('does not mutate the original record', () => {
+    const record = { name: 'Acme' };
+    const fields: Record<string, ExternalFieldConfig> = {
+      name: { type: 'string' },
+      upper: {
+        type: 'string',
+        computed: {
+          depends: ['name'],
+          compute: (r) => (r.name as string).toUpperCase(),
+        },
+      },
+    };
+
+    evaluateComputedFields(record, fields);
+    expect(record).toEqual({ name: 'Acme' });
+    expect(record).not.toHaveProperty('upper');
+  });
+});

package/src/external-model/__tests__/field-mapper.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'vitest';
+import { resolveFieldValue, mapAdapterResponse, reverseMapForWrite } from '../field-mapper.js';
+
+describe('resolveFieldValue', () => {
+  it('resolves top-level field', () => {
+    expect(resolveFieldValue({ name: 'Acme' }, 'name')).toBe('Acme');
+  });
+
+  it('resolves nested field with dot notation', () => {
+    const record = { address: { street: '123 Main St', city: 'Springfield' } };
+    expect(resolveFieldValue(record, 'address.street')).toBe('123 Main St');
+  });
+
+  it('resolves deeply nested field', () => {
+    const record = { subscription: { plan: { id: 'pro' } } };
+    expect(resolveFieldValue(record, 'subscription.plan.id')).toBe('pro');
+  });
+
+  it('returns undefined for missing top-level field', () => {
+    expect(resolveFieldValue({}, 'name')).toBeUndefined();
+  });
+
+  it('returns undefined for missing nested path', () => {
+    expect(resolveFieldValue({ a: {} }, 'a.b.c')).toBeUndefined();
+  });
+
+  it('returns undefined when intermediate is null', () => {
+    expect(resolveFieldValue({ a: null }, 'a.b')).toBeUndefined();
+  });
+
+  it('returns undefined when intermediate is a primitive', () => {
+    expect(resolveFieldValue({ a: 'string' }, 'a.b')).toBeUndefined();
+  });
+
+  it('handles numeric values', () => {
+    expect(resolveFieldValue({ count: 0 }, 'count')).toBe(0);
+  });
+
+  it('handles false values', () => {
+    expect(resolveFieldValue({ active: false }, 'active')).toBe(false);
+  });
+});
+
+describe('mapAdapterResponse', () => {
+  it('maps fields with 1:1 naming', () => {
+    const raw = { id: '1', email: 'test@example.com' };
+    const fields = {
+      id: { type: 'string' as const },
+      email: { type: 'string' as const },
+    };
+
+    expect(mapAdapterResponse(raw, fields)).toEqual({
+      id: '1',
+      email: 'test@example.com',
+    });
+  });
+
+  it('maps fields using from property', () => {
+    const raw = { metadata: { company_name: 'Acme Corp' } };
+    const fields = {
+      name: { type: 'string' as const, from: 'metadata.company_name' },
+    };
+
+    expect(mapAdapterResponse(raw, fields)).toEqual({ name: 'Acme Corp' });
+  });
+
+  it('handles mixed direct and mapped fields', () => {
+    const raw = { id: 'cus_123', email: 'a@b.com', metadata: { company_name: 'X' } };
+    const fields = {
+      id: { type: 'string' as const },
+      email: { type: 'string' as const },
+      name: { type: 'string' as const, from: 'metadata.company_name' },
+    };
+
+    expect(mapAdapterResponse(raw, fields)).toEqual({
+      id: 'cus_123',
+      email: 'a@b.com',
+      name: 'X',
+    });
+  });
+
+  it('skips computed fields', () => {
+    const raw = { name: 'Acme', email: 'a@b.com' };
+    const fields = {
+      name: { type: 'string' as const },
+      email: { type: 'string' as const },
+      displayName: {
+        type: 'string' as const,
+        computed: {
+          depends: ['name', 'email'],
+          compute: (r: Record<string, unknown>) => r.name || r.email,
+        },
+      },
+    };
+
+    const result = mapAdapterResponse(raw, fields);
+    expect(result).toEqual({ name: 'Acme', email: 'a@b.com' });
+    expect(result).not.toHaveProperty('displayName');
+  });
+
+  it('returns undefined for missing source fields', () => {
+    const raw = {};
+    const fields = {
+      name: { type: 'string' as const, from: 'metadata.company_name' },
+    };
+
+    expect(mapAdapterResponse(raw, fields)).toEqual({ name: undefined });
+  });
+});
+
+describe('reverseMapForWrite', () => {
+  it('maps 1:1 fields directly', () => {
+    const data = { email: 'new@test.com' };
+    const fields = { email: { type: 'string' as const } };
+
+    expect(reverseMapForWrite(data, fields)).toEqual({ email: 'new@test.com' });
+  });
+
+  it('reverse maps fields with from to nested structure', () => {
+    const data = { name: 'Acme Corp' };
+    const fields = {
+      name: { type: 'string' as const, from: 'metadata.company_name' },
+    };
+
+    expect(reverseMapForWrite(data, fields)).toEqual({
+      metadata: { company_name: 'Acme Corp' },
+    });
+  });
+
+  it('skips computed fields', () => {
+    const data = { name: 'Acme', displayName: 'Acme Corp' };
+    const fields = {
+      name: { type: 'string' as const },
+      displayName: {
+        type: 'string' as const,
+        computed: { depends: ['name'], compute: (r: Record<string, unknown>) => r.name },
+      },
+    };
+
+    expect(reverseMapForWrite(data, fields)).toEqual({ name: 'Acme' });
+  });
+
+  it('skips fields not in schema', () => {
+    const data = { name: 'Acme', unknown: 'value' };
+    const fields = { name: { type: 'string' as const } };
+
+    expect(reverseMapForWrite(data, fields)).toEqual({ name: 'Acme' });
+  });
+
+  it('builds nested objects for deep paths', () => {
+    const data = { plan: 'pro' };
+    const fields = {
+      plan: { type: 'string' as const, from: 'subscription.plan.id' },
+    };
+
+    expect(reverseMapForWrite(data, fields)).toEqual({
+      subscription: { plan: { id: 'pro' } },
+    });
+  });
+});

package/src/external-model/__tests__/in-memory-ops.test.ts

@@ -0,0 +1,247 @@
+import { describe, it, expect } from 'vitest';
+import {
+  applyInMemoryFilters,
+  applyInMemorySort,
+  applyInMemoryPagination,
+} from '../in-memory-ops.js';
+import type { TranslatedFilter } from '../../model-api/filter-translator.js';
+
+describe('applyInMemoryFilters', () => {
+  const records = [
+    { id: '1', name: 'Alice', age: 30, email: 'alice@acme.com', status: 'active' },
+    { id: '2', name: 'Bob', age: 25, email: 'bob@test.org', status: 'inactive' },
+    { id: '3', name: 'Charlie', age: 35, email: 'charlie@acme.com', status: 'active' },
+    { id: '4', name: 'Diana', age: 28, email: null, status: null },
+  ];
+
+  describe('eq operator', () => {
+    it('filters by exact match', () => {
+      const filters: TranslatedFilter[] = [{ field: 'status', operator: 'eq', value: 'active' }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(2);
+      expect(result.map((r) => r.name)).toEqual(['Alice', 'Charlie']);
+    });
+
+    it('handles numeric equality', () => {
+      const filters: TranslatedFilter[] = [{ field: 'age', operator: 'eq', value: 25 }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('Bob');
+    });
+  });
+
+  describe('neq operator', () => {
+    it('excludes matching records', () => {
+      const filters: TranslatedFilter[] = [{ field: 'status', operator: 'neq', value: 'active' }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(2);
+      expect(result.map((r) => r.name)).toEqual(['Bob', 'Diana']);
+    });
+  });
+
+  describe('comparison operators', () => {
+    it('gt filters greater than', () => {
+      const filters: TranslatedFilter[] = [{ field: 'age', operator: 'gt', value: 28 }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result.map((r) => r.name)).toEqual(['Alice', 'Charlie']);
+    });
+
+    it('gte includes boundary', () => {
+      const filters: TranslatedFilter[] = [{ field: 'age', operator: 'gte', value: 28 }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result.map((r) => r.name)).toEqual(['Alice', 'Charlie', 'Diana']);
+    });
+
+    it('lt filters less than', () => {
+      const filters: TranslatedFilter[] = [{ field: 'age', operator: 'lt', value: 28 }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result.map((r) => r.name)).toEqual(['Bob']);
+    });
+
+    it('lte includes boundary', () => {
+      const filters: TranslatedFilter[] = [{ field: 'age', operator: 'lte', value: 28 }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result.map((r) => r.name)).toEqual(['Bob', 'Diana']);
+    });
+  });
+
+  describe('in / notIn operators', () => {
+    it('in matches values in array', () => {
+      const filters: TranslatedFilter[] = [
+        { field: 'name', operator: 'in', value: ['Alice', 'Bob'] },
+      ];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(2);
+    });
+
+    it('notIn excludes values in array', () => {
+      const filters: TranslatedFilter[] = [
+        { field: 'name', operator: 'notIn', value: ['Alice', 'Bob'] },
+      ];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result.map((r) => r.name)).toEqual(['Charlie', 'Diana']);
+    });
+  });
+
+  describe('string operators', () => {
+    it('contains matches substring (case-insensitive)', () => {
+      const filters: TranslatedFilter[] = [{ field: 'email', operator: 'contains', value: 'acme' }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result.map((r) => r.name)).toEqual(['Alice', 'Charlie']);
+    });
+
+    it('startsWith matches prefix (case-insensitive)', () => {
+      const filters: TranslatedFilter[] = [{ field: 'name', operator: 'startsWith', value: 'al' }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('Alice');
+    });
+
+    it('endsWith matches suffix (case-insensitive)', () => {
+      const filters: TranslatedFilter[] = [{ field: 'email', operator: 'endsWith', value: '.org' }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('Bob');
+    });
+
+    it('contains returns false for non-string fields', () => {
+      const filters: TranslatedFilter[] = [{ field: 'age', operator: 'contains', value: '3' }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe('null check operators', () => {
+    it('is null matches null values', () => {
+      const filters: TranslatedFilter[] = [{ field: 'email', operator: 'is', value: null }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('Diana');
+    });
+
+    it('is not_null matches non-null values', () => {
+      const filters: TranslatedFilter[] = [{ field: 'email', operator: 'is', value: 'not_null' }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(3);
+    });
+
+    it('isnull true matches null values', () => {
+      const filters: TranslatedFilter[] = [{ field: 'status', operator: 'isnull', value: true }];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('Diana');
+    });
+  });
+
+  describe('multiple filters (AND)', () => {
+    it('applies all filters', () => {
+      const filters: TranslatedFilter[] = [
+        { field: 'status', operator: 'eq', value: 'active' },
+        { field: 'age', operator: 'gt', value: 30 },
+      ];
+      const result = applyInMemoryFilters(records, filters);
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe('Charlie');
+    });
+  });
+
+  describe('empty input', () => {
+    it('returns all records with empty filters', () => {
+      const result = applyInMemoryFilters(records, []);
+      expect(result).toHaveLength(4);
+    });
+
+    it('returns empty array for empty records', () => {
+      const filters: TranslatedFilter[] = [{ field: 'name', operator: 'eq', value: 'test' }];
+      const result = applyInMemoryFilters([], filters);
+      expect(result).toEqual([]);
+    });
+  });
+});
+
+describe('applyInMemorySort', () => {
+  const records = [
+    { id: '1', name: 'Charlie', age: 35 },
+    { id: '2', name: 'Alice', age: 30 },
+    { id: '3', name: 'Bob', age: 25 },
+    { id: '4', name: 'Alice', age: 28 },
+  ];
+
+  it('sorts ascending by string field', () => {
+    const result = applyInMemorySort(records, [{ field: 'name', direction: 'asc' }]);
+    expect(result.map((r) => r.name)).toEqual(['Alice', 'Alice', 'Bob', 'Charlie']);
+  });
+
+  it('sorts descending by string field', () => {
+    const result = applyInMemorySort(records, [{ field: 'name', direction: 'desc' }]);
+    expect(result.map((r) => r.name)).toEqual(['Charlie', 'Bob', 'Alice', 'Alice']);
+  });
+
+  it('sorts by numeric field', () => {
+    const result = applyInMemorySort(records, [{ field: 'age', direction: 'asc' }]);
+    expect(result.map((r) => r.age)).toEqual([25, 28, 30, 35]);
+  });
+
+  it('sorts by multiple fields', () => {
+    const result = applyInMemorySort(records, [
+      { field: 'name', direction: 'asc' },
+      { field: 'age', direction: 'desc' },
+    ]);
+    expect(result.map((r) => ({ name: r.name, age: r.age }))).toEqual([
+      { name: 'Alice', age: 30 },
+      { name: 'Alice', age: 28 },
+      { name: 'Bob', age: 25 },
+      { name: 'Charlie', age: 35 },
+    ]);
+  });
+
+  it('handles null values (nulls first in asc)', () => {
+    const data = [
+      { id: '1', name: 'Bob' },
+      { id: '2', name: null },
+      { id: '3', name: 'Alice' },
+    ];
+    const result = applyInMemorySort(data, [{ field: 'name', direction: 'asc' }]);
+    expect(result.map((r) => r.name)).toEqual([null, 'Alice', 'Bob']);
+  });
+
+  it('returns same order with no sorts', () => {
+    const result = applyInMemorySort(records, []);
+    expect(result).toEqual(records);
+  });
+
+  it('does not mutate original array', () => {
+    const original = [...records];
+    applyInMemorySort(records, [{ field: 'age', direction: 'asc' }]);
+    expect(records).toEqual(original);
+  });
+});
+
+describe('applyInMemoryPagination', () => {
+  const records = Array.from({ length: 10 }, (_, i) => ({ id: String(i + 1), index: i }));
+
+  it('returns first page', () => {
+    const result = applyInMemoryPagination(records, 3, 0);
+    expect(result.map((r) => r.index)).toEqual([0, 1, 2]);
+  });
+
+  it('returns second page', () => {
+    const result = applyInMemoryPagination(records, 3, 3);
+    expect(result.map((r) => r.index)).toEqual([3, 4, 5]);
+  });
+
+  it('returns partial last page', () => {
+    const result = applyInMemoryPagination(records, 3, 9);
+    expect(result.map((r) => r.index)).toEqual([9]);
+  });
+
+  it('returns empty when offset exceeds length', () => {
+    const result = applyInMemoryPagination(records, 3, 20);
+    expect(result).toEqual([]);
+  });
+
+  it('returns all records when limit exceeds length', () => {
+    const result = applyInMemoryPagination(records, 100, 0);
+    expect(result).toHaveLength(10);
+  });
+});

package/src/external-model/__tests__/mutation-executor.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ExternalMutationExecutor, CapabilityNotSupportedError } from '../mutation-executor.js';
+import type { DataAdapter } from '../../plugins/types.js';
+import type { ExternalFieldConfig } from '../types.js';
+
+function makeAdapter(overrides?: Partial<DataAdapter>): DataAdapter {
+  return {
+    async get(_model, _id) {
+      return null;
+    },
+    ...overrides,
+  };
+}
+
+const baseFields: Record<string, ExternalFieldConfig> = {
+  id: { type: 'string' },
+  email: { type: 'string' },
+  name: { type: 'string', from: 'metadata.company_name' },
+};
+
+describe('ExternalMutationExecutor', () => {
+  describe('create', () => {
+    it('calls adapter.create with reverse-mapped data', async () => {
+      const create = vi.fn().mockResolvedValue({
+        id: 'cus_1',
+        email: 'a@b.com',
+        metadata: { company_name: 'Acme' },
+      });
+      const adapter = makeAdapter({ create });
+      const executor = new ExternalMutationExecutor({
+        adapter,
+        adapterName: 'stripe',
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'create'],
+      });
+
+      const result = await executor.create({ email: 'a@b.com', name: 'Acme' });
+
+      expect(create).toHaveBeenCalledWith('billing.Customer', {
+        email: 'a@b.com',
+        metadata: { company_name: 'Acme' },
+      });
+      expect(result).toEqual({ id: 'cus_1', email: 'a@b.com', name: 'Acme' });
+    });
+
+    it('throws CapabilityNotSupportedError when create not supported', async () => {
+      const adapter = makeAdapter();
+      const executor = new ExternalMutationExecutor({
+        adapter,
+        adapterName: 'stripe',
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read'],
+      });
+
+      await expect(executor.create({ email: 'test' })).rejects.toThrow(CapabilityNotSupportedError);
+      await expect(executor.create({ email: 'test' })).rejects.toThrow(
+        'Adapter "stripe" does not support operation "create"',
+      );
+    });
+
+    it('evaluates computed fields on response', async () => {
+      const fields: Record<string, ExternalFieldConfig> = {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        upper: {
+          type: 'string',
+          computed: { depends: ['name'], compute: (r) => (r.name as string).toUpperCase() },
+        },
+      };
+      const create = vi.fn().mockResolvedValue({ id: '1', name: 'alice' });
+      const adapter = makeAdapter({ create });
+      const executor = new ExternalMutationExecutor({
+        adapter,
+        adapterName: 'test',
+        modelName: 'test.Model',
+        fields,
+        capabilities: ['read', 'create'],
+      });
+
+      const result = await executor.create({ name: 'alice' });
+      expect(result.upper).toBe('ALICE');
+    });
+  });
+
+  describe('update', () => {
+    it('calls adapter.update with reverse-mapped data', async () => {
+      const update = vi.fn().mockResolvedValue({
+        id: 'cus_1',
+        email: 'new@b.com',
+        metadata: { company_name: 'NewCo' },
+      });
+      const adapter = makeAdapter({ update });
+      const executor = new ExternalMutationExecutor({
+        adapter,
+        adapterName: 'stripe',
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'update'],
+      });
+
+      const result = await executor.update('cus_1', { email: 'new@b.com', name: 'NewCo' });
+
+      expect(update).toHaveBeenCalledWith('billing.Customer', 'cus_1', {
+        email: 'new@b.com',
+        metadata: { company_name: 'NewCo' },
+      });
+      expect(result).toEqual({ id: 'cus_1', email: 'new@b.com', name: 'NewCo' });
+    });
+
+    it('throws CapabilityNotSupportedError when update not supported', async () => {
+      const adapter = makeAdapter();
+      const executor = new ExternalMutationExecutor({
+        adapter,
+        adapterName: 'stripe',
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read'],
+      });
+
+      await expect(executor.update('1', { email: 'test' })).rejects.toThrow(
+        CapabilityNotSupportedError,
+      );
+    });
+  });
+
+  describe('delete', () => {
+    it('calls adapter.delete', async () => {
+      const del = vi.fn().mockResolvedValue(undefined);
+      const adapter = makeAdapter({ delete: del });
+      const executor = new ExternalMutationExecutor({
+        adapter,
+        adapterName: 'stripe',
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'delete'],
+      });
+
+      await executor.delete('cus_1');
+      expect(del).toHaveBeenCalledWith('billing.Customer', 'cus_1');
+    });
+
+    it('throws CapabilityNotSupportedError when delete not supported', async () => {
+      const adapter = makeAdapter();
+      const executor = new ExternalMutationExecutor({
+        adapter,
+        adapterName: 'stripe',
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read'],
+      });
+
+      await expect(executor.delete('cus_1')).rejects.toThrow(CapabilityNotSupportedError);
+      await expect(executor.delete('cus_1')).rejects.toThrow(
+        'Adapter "stripe" does not support operation "delete"',
+      );
+    });
+  });
+});