@rangka/core 0.0.1

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

@@ -0,0 +1,284 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ExternalQueryExecutor } from '../query-executor.js';
+import type { DataAdapter, AdapterCapability } 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('ExternalQueryExecutor', () => {
+  describe('execGet', () => {
+    it('returns null when adapter returns null', async () => {
+      const adapter = makeAdapter({
+        async get() {
+          return null;
+        },
+      });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read'],
+      });
+
+      expect(await executor.execGet('non-existent')).toBeNull();
+    });
+
+    it('returns mapped record', async () => {
+      const adapter = makeAdapter({
+        async get() {
+          return { id: 'cus_1', email: 'a@b.com', metadata: { company_name: 'Acme' } };
+        },
+      });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read'],
+      });
+
+      const result = await executor.execGet('cus_1');
+      expect(result).toEqual({ id: 'cus_1', email: 'a@b.com', name: 'Acme' });
+    });
+
+    it('evaluates computed fields', 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 adapter = makeAdapter({
+        async get() {
+          return { id: '1', name: 'alice' };
+        },
+      });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'test.Model',
+        fields,
+        capabilities: ['read'],
+      });
+
+      const result = await executor.execGet('1');
+      expect(result?.upper).toBe('ALICE');
+    });
+
+    it('passes model name to adapter', async () => {
+      const get = vi.fn().mockResolvedValue({ id: '1' });
+      const adapter = makeAdapter({ get });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: { id: { type: 'string' } },
+        capabilities: ['read'],
+      });
+
+      await executor.execGet('cus_1');
+      expect(get).toHaveBeenCalledWith('billing.Customer', 'cus_1');
+    });
+  });
+
+  describe('execList', () => {
+    it('calls adapter.list when capability is available', async () => {
+      const list = vi.fn().mockResolvedValue({
+        data: [
+          { id: '1', email: 'a@b.com', metadata: { company_name: 'A' } },
+          { id: '2', email: 'c@d.com', metadata: { company_name: 'B' } },
+        ],
+        total: 2,
+      });
+      const adapter = makeAdapter({ list });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'list'],
+      });
+
+      const result = await executor.execList({
+        filters: [],
+        sorts: [],
+        fieldNames: [],
+      });
+
+      expect(result.data).toHaveLength(2);
+      expect(result.data[0]).toEqual({ id: '1', email: 'a@b.com', name: 'A' });
+      expect(result.total).toBe(2);
+    });
+
+    it('passes filters to adapter when filter capability exists', async () => {
+      const list = vi.fn().mockResolvedValue({ data: [], total: 0 });
+      const adapter = makeAdapter({ list });
+      const capabilities: AdapterCapability[] = ['read', 'list', 'filter'];
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities,
+      });
+
+      await executor.execList({
+        filters: [{ field: 'email', operator: 'eq', value: 'test@test.com' }],
+        sorts: [],
+        fieldNames: [],
+      });
+
+      expect(list).toHaveBeenCalledWith(
+        'billing.Customer',
+        expect.objectContaining({
+          filters: [{ field: 'email', operator: 'eq', value: 'test@test.com' }],
+        }),
+      );
+    });
+
+    it('applies in-memory filter when adapter lacks filter capability', async () => {
+      const list = vi.fn().mockResolvedValue({
+        data: [
+          { id: '1', email: 'alice@acme.com', metadata: { company_name: 'Acme' } },
+          { id: '2', email: 'bob@other.com', metadata: { company_name: 'Other' } },
+        ],
+        total: 2,
+      });
+      const adapter = makeAdapter({ list });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'list'],
+      });
+
+      const result = await executor.execList({
+        filters: [{ field: 'email', operator: 'contains', value: 'acme' }],
+        sorts: [],
+        fieldNames: [],
+      });
+
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].email).toBe('alice@acme.com');
+    });
+
+    it('applies in-memory sort when adapter lacks sort capability', async () => {
+      const list = vi.fn().mockResolvedValue({
+        data: [
+          { id: '2', email: 'b@b.com', metadata: { company_name: 'B' } },
+          { id: '1', email: 'a@a.com', metadata: { company_name: 'A' } },
+        ],
+        total: 2,
+      });
+      const adapter = makeAdapter({ list });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'list'],
+      });
+
+      const result = await executor.execList({
+        filters: [],
+        sorts: [{ field: 'email', direction: 'asc' }],
+        fieldNames: [],
+      });
+
+      expect(result.data[0].email).toBe('a@a.com');
+      expect(result.data[1].email).toBe('b@b.com');
+    });
+
+    it('returns empty data when no list capability', async () => {
+      const adapter = makeAdapter();
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read'],
+      });
+
+      const result = await executor.execList({
+        filters: [],
+        sorts: [],
+        fieldNames: [],
+      });
+
+      expect(result.data).toEqual([]);
+      expect(result.total).toBe(0);
+    });
+
+    it('uses default limit of 25', async () => {
+      const list = vi.fn().mockResolvedValue({ data: [], total: 0 });
+      const adapter = makeAdapter({ list });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'list'],
+      });
+
+      await executor.execList({ filters: [], sorts: [], fieldNames: [] });
+      expect(list).toHaveBeenCalledWith(
+        'billing.Customer',
+        expect.objectContaining({ pageSize: 25 }),
+      );
+    });
+
+    it('respects custom limit', async () => {
+      const list = vi.fn().mockResolvedValue({ data: [], total: 0 });
+      const adapter = makeAdapter({ list });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: baseFields,
+        capabilities: ['read', 'list'],
+      });
+
+      await executor.execList({ filters: [], sorts: [], fieldNames: [], limitVal: 10 });
+      expect(list).toHaveBeenCalledWith(
+        'billing.Customer',
+        expect.objectContaining({ pageSize: 10 }),
+      );
+    });
+  });
+
+  describe('execCount', () => {
+    it('returns total from list result', async () => {
+      const list = vi.fn().mockResolvedValue({ data: [{ id: '1' }, { id: '2' }], total: 50 });
+      const adapter = makeAdapter({ list });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: { id: { type: 'string' } },
+        capabilities: ['read', 'list'],
+      });
+
+      const count = await executor.execCount({ filters: [], sorts: [], fieldNames: [] });
+      expect(count).toBe(50);
+    });
+
+    it('falls back to data length when total not provided', async () => {
+      const list = vi.fn().mockResolvedValue({ data: [{ id: '1' }, { id: '2' }] });
+      const adapter = makeAdapter({ list });
+      const executor = new ExternalQueryExecutor({
+        adapter,
+        modelName: 'billing.Customer',
+        fields: { id: { type: 'string' } },
+        capabilities: ['read', 'list'],
+      });
+
+      const count = await executor.execCount({ filters: [], sorts: [], fieldNames: [] });
+      expect(count).toBe(2);
+    });
+  });
+});

package/src/external-model/__tests__/schema-converter.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect } from 'vitest';
+import { externalModelToResolved } from '../schema-converter.js';
+import type { ExternalModelConfig } from '../types.js';
+
+describe('externalModelToResolved', () => {
+  const baseConfig: ExternalModelConfig = {
+    name: 'Customer',
+    source: 'stripe',
+    label: 'Stripe Customer',
+    fields: {
+      id: { type: 'string' },
+      email: { type: 'string' },
+      name: { type: 'string', from: 'metadata.company_name' },
+    },
+  };
+
+  it('produces correct qualifiedName', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.qualifiedName).toBe('billing.Customer');
+  });
+
+  it('sets source from config', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.source).toBe('stripe');
+  });
+
+  it('sets app and module', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.app).toBe('billing-app');
+    expect(model.module).toBe('billing');
+  });
+
+  it('sets name and label', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.name).toBe('Customer');
+    expect(model.label).toBe('Stripe Customer');
+  });
+
+  it('has empty traits', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.traits).toEqual([]);
+  });
+
+  it('has empty indexes', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.indexes).toEqual([]);
+  });
+
+  it('sets auditLog to false', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.auditLog).toBe(false);
+  });
+
+  it('converts fields to ResolvedField array', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    expect(model.fields).toHaveLength(3);
+
+    const idField = model.fields.find((f) => f.name === 'id');
+    expect(idField).toEqual({
+      name: 'id',
+      config: { type: 'string', label: undefined, required: undefined },
+      provenance: { source: 'base' },
+    });
+  });
+
+  it('preserves field type and label', () => {
+    const config: ExternalModelConfig = {
+      name: 'Invoice',
+      source: 'stripe',
+      fields: {
+        amount: { type: 'decimal', label: 'Amount', required: true },
+      },
+    };
+
+    const { model } = externalModelToResolved(config, 'app', 'billing');
+    const amountField = model.fields.find((f) => f.name === 'amount');
+    expect(amountField?.config).toEqual({ type: 'decimal', label: 'Amount', required: true });
+  });
+
+  it('sets provenance to base for all fields', () => {
+    const { model } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+    for (const field of model.fields) {
+      expect(field.provenance).toEqual({ source: 'base' });
+    }
+  });
+
+  it('handles config without label', () => {
+    const config: ExternalModelConfig = {
+      name: 'Product',
+      source: 'shopify',
+      fields: { id: { type: 'string' } },
+    };
+
+    const { model } = externalModelToResolved(config, 'app', 'store');
+    expect(model.label).toBeUndefined();
+  });
+
+  describe('relationships', () => {
+    it('returns empty relationships when no relationship fields', () => {
+      const { relationships } = externalModelToResolved(baseConfig, 'billing-app', 'billing');
+      expect(relationships).toEqual([]);
+    });
+
+    it('extracts link relationships from fields', () => {
+      const config: ExternalModelConfig = {
+        name: 'Invoice',
+        source: 'stripe',
+        fields: {
+          id: { type: 'string' },
+          order: {
+            type: 'string',
+            from: 'metadata.order_id',
+            relationship: { type: 'link', model: 'sales.Order' },
+          },
+        },
+      };
+
+      const { relationships } = externalModelToResolved(config, 'app', 'billing');
+      expect(relationships).toHaveLength(1);
+      expect(relationships[0]).toEqual({
+        type: 'link',
+        from: 'billing.Invoice',
+        field: 'order',
+        to: 'sales.Order',
+        foreignKey: undefined,
+      });
+    });
+
+    it('extracts hasMany relationships with foreignKey', () => {
+      const config: ExternalModelConfig = {
+        name: 'Customer',
+        source: 'stripe',
+        fields: {
+          id: { type: 'string' },
+          invoices: {
+            type: 'json',
+            relationship: { type: 'hasMany', model: 'billing.Invoice', foreignKey: 'customer_id' },
+          },
+        },
+      };
+
+      const { relationships } = externalModelToResolved(config, 'app', 'billing');
+      expect(relationships).toHaveLength(1);
+      expect(relationships[0]).toEqual({
+        type: 'hasMany',
+        from: 'billing.Customer',
+        field: 'invoices',
+        to: 'billing.Invoice',
+        foreignKey: 'customer_id',
+      });
+    });
+
+    it('extracts multiple relationships', () => {
+      const config: ExternalModelConfig = {
+        name: 'Order',
+        source: 'stripe',
+        fields: {
+          id: { type: 'string' },
+          customer: {
+            type: 'string',
+            relationship: { type: 'link', model: 'billing.Customer' },
+          },
+          items: {
+            type: 'json',
+            relationship: { type: 'hasMany', model: 'billing.LineItem', foreignKey: 'order_id' },
+          },
+        },
+      };
+
+      const { relationships } = externalModelToResolved(config, 'app', 'billing');
+      expect(relationships).toHaveLength(2);
+    });
+  });
+});

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

@@ -0,0 +1,15 @@
+import type { ExternalFieldConfig } from './types.js';
+
+export function evaluateComputedFields(
+  record: Record<string, unknown>,
+  fields: Record<string, ExternalFieldConfig>,
+): Record<string, unknown> {
+  const result = { ...record };
+
+  for (const [fieldName, config] of Object.entries(fields)) {
+    if (!config.computed) continue;
+    result[fieldName] = config.computed.compute(result);
+  }
+
+  return result;
+}

package/src/external-model/define.ts

@@ -0,0 +1,5 @@
+import type { ExternalModelConfig } from './types.js';
+
+export function defineExternalModel(config: ExternalModelConfig): ExternalModelConfig {
+  return config;
+}

package/src/external-model/external-model-ops.ts

@@ -0,0 +1,108 @@
+import type { ModelOps, QueryState, QueryResult, QueryResultWithMeta } from '../model-api/types.js';
+import type { RequestContext } from '../auth/types.js';
+import type { DataAdapter, AdapterCapability } from '../plugins/types.js';
+import type { ExternalFieldConfig } from './types.js';
+import { ExternalQueryExecutor } from './query-executor.js';
+import { ExternalMutationExecutor, CapabilityNotSupportedError } from './mutation-executor.js';
+
+export { CapabilityNotSupportedError };
+
+export interface ExternalModelOpsConfig {
+  adapter: DataAdapter;
+  adapterName: string;
+  modelName: string;
+  fields: Record<string, ExternalFieldConfig>;
+  capabilities: AdapterCapability[];
+}
+
+export class ExternalModelOps implements ModelOps {
+  private readonly queryExecutor: ExternalQueryExecutor;
+  private readonly mutationExecutor: ExternalMutationExecutor;
+
+  constructor(config: ExternalModelOpsConfig) {
+    this.queryExecutor = new ExternalQueryExecutor({
+      adapter: config.adapter,
+      modelName: config.modelName,
+      fields: config.fields,
+      capabilities: config.capabilities,
+    });
+    this.mutationExecutor = new ExternalMutationExecutor({
+      adapter: config.adapter,
+      adapterName: config.adapterName,
+      modelName: config.modelName,
+      fields: config.fields,
+      capabilities: config.capabilities,
+    });
+  }
+
+  async find(state: QueryState): Promise<QueryResult> {
+    const result = await this.queryExecutor.execList({
+      filters: state.filters,
+      sorts: state.sorts,
+      fieldNames: state.fieldNames,
+      limitVal: state.limitVal,
+      offsetVal: state.offsetVal,
+      pageVal: state.pageVal,
+    });
+    return { data: result.data, total: result.total, hasMore: result.hasMore };
+  }
+
+  async findWithMeta(state: QueryState): Promise<QueryResultWithMeta> {
+    const limit = state.limitVal ?? 25;
+    const page = state.pageVal ?? 1;
+    const result = await this.queryExecutor.execList({
+      filters: state.filters,
+      sorts: state.sorts,
+      fieldNames: state.fieldNames,
+      limitVal: limit,
+      pageVal: page,
+    });
+    const total = result.total ?? result.data.length;
+    const totalPages = Math.ceil(total / limit);
+    return { data: result.data, meta: { total, page, limit, totalPages } };
+  }
+
+  async findOne(state: QueryState): Promise<Record<string, unknown> | null> {
+    const result = await this.queryExecutor.execList({
+      filters: state.filters,
+      sorts: state.sorts,
+      fieldNames: state.fieldNames,
+      limitVal: 1,
+    });
+    return result.data[0] ?? null;
+  }
+
+  async count(state: QueryState): Promise<number> {
+    return this.queryExecutor.execCount({
+      filters: state.filters,
+      sorts: state.sorts,
+      fieldNames: state.fieldNames,
+    });
+  }
+
+  async get(id: string): Promise<Record<string, unknown> | null> {
+    return this.queryExecutor.execGet(id);
+  }
+
+  async create(
+    data: Record<string, unknown>,
+    _auth?: RequestContext,
+  ): Promise<Record<string, unknown>> {
+    return this.mutationExecutor.create(data);
+  }
+
+  async update(
+    id: string,
+    data: Record<string, unknown>,
+    _auth?: RequestContext,
+  ): Promise<Record<string, unknown>> {
+    return this.mutationExecutor.update(id, data);
+  }
+
+  async delete(id: string, _auth?: RequestContext): Promise<Record<string, unknown>> {
+    const record = await this.get(id);
+    if (!record) throw new Error(`Record not found: ${id}`);
+    await this.mutationExecutor.delete(id);
+    return record;
+  }
+}

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

@@ -0,0 +1,66 @@
+import type { ExternalFieldConfig } from './types.js';
+
+export function resolveFieldValue(record: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = record;
+
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+export function mapAdapterResponse(
+  raw: Record<string, unknown>,
+  fields: Record<string, ExternalFieldConfig>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [fieldName, config] of Object.entries(fields)) {
+    if (config.computed) continue;
+
+    const sourcePath = config.from ?? fieldName;
+    result[fieldName] = resolveFieldValue(raw, sourcePath);
+  }
+
+  return result;
+}
+
+export function reverseMapForWrite(
+  data: Record<string, unknown>,
+  fields: Record<string, ExternalFieldConfig>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [fieldName, value] of Object.entries(data)) {
+    const config = fields[fieldName];
+    if (!config || config.computed) continue;
+
+    const targetPath = config.from ?? fieldName;
+
+    if (targetPath.includes('.')) {
+      setNestedValue(result, targetPath, value);
+    } else {
+      result[targetPath] = value;
+    }
+  }
+
+  return result;
+}
+
+function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split('.');
+  let current: Record<string, unknown> = obj;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (current[part] == null || typeof current[part] !== 'object') {
+      current[part] = {};
+    }
+    current = current[part] as Record<string, unknown>;
+  }
+
+  current[parts[parts.length - 1]] = value;
+}