@rangka/core 0.0.1

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

@@ -0,0 +1,107 @@
+import type { TranslatedFilter } from '../model-api/filter-translator.js';
+import { toBool, isNil } from '../helpers/coerce.js';
+
+export function applyInMemoryFilters(
+  records: Record<string, unknown>[],
+  filters: TranslatedFilter[],
+): Record<string, unknown>[] {
+  return records.filter((record) => {
+    for (const { field, operator, value } of filters) {
+      const fieldValue = record[field];
+
+      switch (operator) {
+        case 'eq':
+          if (fieldValue !== value) return false;
+          break;
+        case 'neq':
+          if (fieldValue === value) return false;
+          break;
+        case 'gt':
+          if (!(fieldValue! > value!)) return false;
+          break;
+        case 'gte':
+          if (!(fieldValue! >= value!)) return false;
+          break;
+        case 'lt':
+          if (!(fieldValue! < value!)) return false;
+          break;
+        case 'lte':
+          if (!(fieldValue! <= value!)) return false;
+          break;
+        case 'in':
+          if (!(value as unknown[]).includes(fieldValue)) return false;
+          break;
+        case 'notIn':
+          if ((value as unknown[]).includes(fieldValue)) return false;
+          break;
+        case 'contains':
+          if (
+            typeof fieldValue !== 'string' ||
+            !fieldValue.toLowerCase().includes((value as string).toLowerCase())
+          )
+            return false;
+          break;
+        case 'startsWith':
+          if (
+            typeof fieldValue !== 'string' ||
+            !fieldValue.toLowerCase().startsWith((value as string).toLowerCase())
+          )
+            return false;
+          break;
+        case 'endsWith':
+          if (
+            typeof fieldValue !== 'string' ||
+            !fieldValue.toLowerCase().endsWith((value as string).toLowerCase())
+          )
+            return false;
+          break;
+        case 'is':
+        case 'isnull':
+          if (isNil(value) || toBool(value)) {
+            if (!isNil(fieldValue)) return false;
+          } else {
+            if (isNil(fieldValue)) return false;
+          }
+          break;
+        case 'like':
+          if (
+            typeof fieldValue !== 'string' ||
+            !fieldValue.toLowerCase().includes((value as string).toLowerCase())
+          )
+            return false;
+          break;
+      }
+    }
+    return true;
+  });
+}
+
+export function applyInMemorySort(
+  records: Record<string, unknown>[],
+  sorts: Array<{ field: string; direction: 'asc' | 'desc' }>,
+): Record<string, unknown>[] {
+  if (sorts.length === 0) return records;
+
+  return [...records].sort((a, b) => {
+    for (const { field, direction } of sorts) {
+      const aVal = a[field];
+      const bVal = b[field];
+
+      if (aVal === bVal) continue;
+      if (aVal == null) return direction === 'asc' ? -1 : 1;
+      if (bVal == null) return direction === 'asc' ? 1 : -1;
+
+      const cmp = aVal < bVal ? -1 : 1;
+      return direction === 'asc' ? cmp : -cmp;
+    }
+    return 0;
+  });
+}
+
+export function applyInMemoryPagination(
+  records: Record<string, unknown>[],
+  limit: number,
+  offset: number,
+): Record<string, unknown>[] {
+  return records.slice(offset, offset + limit);
+}

package/src/external-model/index.ts

@@ -0,0 +1,7 @@
+export { defineExternalModel } from './define.js';
+export { mapAdapterResponse, reverseMapForWrite, resolveFieldValue } from './field-mapper.js';
+export { evaluateComputedFields } from './computed-fields.js';
+export { externalModelToResolved } from './schema-converter.js';
+export type { ExternalModelConfig, ExternalFieldConfig, ComputedFieldConfig } from './types.js';
+export { ExternalModelOps } from './external-model-ops.js';
+export type { ExternalModelOpsConfig } from './external-model-ops.js';

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

@@ -0,0 +1,71 @@
+import type { DataAdapter, AdapterCapability } from '../plugins/types.js';
+import type { ExternalFieldConfig } from './types.js';
+import { reverseMapForWrite, mapAdapterResponse } from './field-mapper.js';
+import { evaluateComputedFields } from './computed-fields.js';
+
+export class CapabilityNotSupportedError extends Error {
+  constructor(
+    public readonly adapterName: string,
+    public readonly operation: string,
+  ) {
+    super(`Adapter "${adapterName}" does not support operation "${operation}"`);
+    this.name = 'CapabilityNotSupportedError';
+  }
+}
+
+export interface ExternalMutationOptions {
+  adapter: DataAdapter;
+  adapterName: string;
+  modelName: string;
+  fields: Record<string, ExternalFieldConfig>;
+  capabilities: AdapterCapability[];
+}
+
+export class ExternalMutationExecutor {
+  private readonly adapter: DataAdapter;
+  private readonly adapterName: string;
+  private readonly modelName: string;
+  private readonly fields: Record<string, ExternalFieldConfig>;
+  private readonly capabilities: Set<AdapterCapability>;
+
+  constructor(options: ExternalMutationOptions) {
+    this.adapter = options.adapter;
+    this.adapterName = options.adapterName;
+    this.modelName = options.modelName;
+    this.fields = options.fields;
+    this.capabilities = new Set(options.capabilities);
+  }
+
+  async create(data: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (!this.capabilities.has('create') || !this.adapter.create) {
+      throw new CapabilityNotSupportedError(this.adapterName, 'create');
+    }
+
+    const mapped = reverseMapForWrite(data, this.fields);
+    const raw = await this.adapter.create(this.modelName, mapped);
+    return this.transformRecord(raw);
+  }
+
+  async update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (!this.capabilities.has('update') || !this.adapter.update) {
+      throw new CapabilityNotSupportedError(this.adapterName, 'update');
+    }
+
+    const mapped = reverseMapForWrite(data, this.fields);
+    const raw = await this.adapter.update(this.modelName, id, mapped);
+    return this.transformRecord(raw);
+  }
+
+  async delete(id: string): Promise<void> {
+    if (!this.capabilities.has('delete') || !this.adapter.delete) {
+      throw new CapabilityNotSupportedError(this.adapterName, 'delete');
+    }
+
+    await this.adapter.delete(this.modelName, id);
+  }
+
+  private transformRecord(raw: Record<string, unknown>): Record<string, unknown> {
+    const mapped = mapAdapterResponse(raw, this.fields);
+    return evaluateComputedFields(mapped, this.fields);
+  }
+}

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

@@ -0,0 +1,100 @@
+import type { DataAdapter, ListQuery } from '../plugins/types.js';
+import type { ExternalFieldConfig } from './types.js';
+import type { TranslatedFilter } from '../model-api/filter-translator.js';
+import { mapAdapterResponse } from './field-mapper.js';
+import { evaluateComputedFields } from './computed-fields.js';
+import {
+  applyInMemoryFilters,
+  applyInMemorySort,
+  applyInMemoryPagination,
+} from './in-memory-ops.js';
+import type { AdapterCapability } from '../plugins/types.js';
+
+export interface ExternalQueryOptions {
+  adapter: DataAdapter;
+  modelName: string;
+  fields: Record<string, ExternalFieldConfig>;
+  capabilities: AdapterCapability[];
+}
+
+export interface ExternalQueryState {
+  filters: TranslatedFilter[];
+  sorts: Array<{ field: string; direction: 'asc' | 'desc' }>;
+  limitVal?: number;
+  offsetVal?: number;
+  pageVal?: number;
+  fieldNames: string[];
+}
+
+export class ExternalQueryExecutor {
+  private readonly adapter: DataAdapter;
+  private readonly modelName: string;
+  private readonly fields: Record<string, ExternalFieldConfig>;
+  private readonly capabilities: Set<AdapterCapability>;
+
+  constructor(options: ExternalQueryOptions) {
+    this.adapter = options.adapter;
+    this.modelName = options.modelName;
+    this.fields = options.fields;
+    this.capabilities = new Set(options.capabilities);
+  }
+
+  async execGet(id: string): Promise<Record<string, unknown> | null> {
+    const raw = await this.adapter.get(this.modelName, id);
+    if (!raw) return null;
+    return this.transformRecord(raw);
+  }
+
+  async execList(
+    state: ExternalQueryState,
+  ): Promise<{ data: Record<string, unknown>[]; total?: number; hasMore?: boolean }> {
+    const limit = state.limitVal ?? 25;
+    const page = state.pageVal ?? 1;
+
+    if (this.capabilities.has('list')) {
+      const query: ListQuery = { pageSize: limit, page };
+
+      if (state.filters.length > 0 && this.capabilities.has('filter')) {
+        query.filters = state.filters.map((f) => ({
+          field: f.field,
+          operator: f.operator,
+          value: f.value,
+        }));
+      }
+
+      if (state.sorts.length > 0 && this.capabilities.has('sort')) {
+        query.sort = state.sorts[0];
+      }
+
+      const result = await this.adapter.list!(this.modelName, query);
+      let data = result.data.map((r) => this.transformRecord(r));
+
+      if (state.filters.length > 0 && !this.capabilities.has('filter')) {
+        data = applyInMemoryFilters(data, state.filters);
+      }
+
+      if (state.sorts.length > 0 && !this.capabilities.has('sort')) {
+        data = applyInMemorySort(data, state.sorts);
+      }
+
+      if (!this.capabilities.has('filter') || !this.capabilities.has('sort')) {
+        data = applyInMemoryPagination(data, limit, 0);
+      }
+
+      return { data, total: result.total, hasMore: result.hasMore };
+    }
+
+    // Fallback: no list capability, fetch all via repeated get (not practical for real use)
+    return { data: [], total: 0 };
+  }
+
+  async execCount(state: ExternalQueryState): Promise<number> {
+    const result = await this.execList(state);
+    return result.total ?? result.data.length;
+  }
+
+  private transformRecord(raw: Record<string, unknown>): Record<string, unknown> {
+    const mapped = mapAdapterResponse(raw, this.fields);
+    return evaluateComputedFields(mapped, this.fields);
+  }
+}

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

@@ -0,0 +1,53 @@
+import type { ResolvedModel, ResolvedField, ModelRelationship } from '../schema/types.js';
+import type { ExternalModelConfig } from './types.js';
+
+export interface ExternalModelConversionResult {
+  model: ResolvedModel;
+  relationships: ModelRelationship[];
+}
+
+export function externalModelToResolved(
+  config: ExternalModelConfig,
+  app: string,
+  module: string,
+): ExternalModelConversionResult {
+  const qualifiedName = `${module}.${config.name}`;
+
+  const fields: ResolvedField[] = Object.entries(config.fields).map(([name, fieldConfig]) => ({
+    name,
+    config: {
+      type: fieldConfig.type,
+      label: fieldConfig.label,
+      required: fieldConfig.required,
+    },
+    provenance: { source: 'base' as const },
+  }));
+
+  const relationships: ModelRelationship[] = [];
+  for (const [fieldName, fieldConfig] of Object.entries(config.fields)) {
+    if (!fieldConfig.relationship) continue;
+
+    relationships.push({
+      type: fieldConfig.relationship.type,
+      from: qualifiedName,
+      field: fieldName,
+      to: fieldConfig.relationship.model,
+      foreignKey: fieldConfig.relationship.foreignKey,
+    });
+  }
+
+  const model: ResolvedModel = {
+    qualifiedName,
+    app,
+    module,
+    name: config.name,
+    label: config.label,
+    auditLog: false,
+    traits: [],
+    fields,
+    indexes: [],
+    source: config.source,
+  };
+
+  return { model, relationships };
+}

package/src/external-model/types.ts

@@ -0,0 +1,32 @@
+export interface ExternalFieldMapping {
+  from?: string;
+}
+
+export interface ComputedFieldConfig {
+  depends: string[];
+  compute: (record: Record<string, unknown>) => unknown;
+}
+
+export interface ExternalRelationshipConfig {
+  type: 'link' | 'hasMany';
+  model: string;
+  from?: string;
+  foreignKey?: string;
+}
+
+export interface ExternalFieldConfig {
+  type: 'string' | 'int' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'json';
+  label?: string;
+  required?: boolean;
+  from?: string;
+  computed?: ComputedFieldConfig;
+  relationship?: ExternalRelationshipConfig;
+}
+
+export interface ExternalModelConfig {
+  name: string;
+  source: string;
+  module?: string;
+  label?: string;
+  fields: Record<string, ExternalFieldConfig>;
+}

package/src/fixtures/__tests__/fixtures.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect } from 'vitest';
+import { FixtureRegistry } from '../registry.js';
+import { loadFixtures } from '../loader.js';
+import type { FixtureDefinition } from '../types.js';
+
+describe('FixtureRegistry', () => {
+  it('registers and retrieves fixtures', () => {
+    const registry = new FixtureRegistry();
+    registry.register({
+      model: 'accounting.account',
+      key: 'account_code',
+      records: [{ account_code: '1000', name: 'Assets' }],
+    });
+    expect(registry.getForModel('accounting.account')).toHaveLength(1);
+  });
+
+  it('rejects fixture with empty model', () => {
+    const registry = new FixtureRegistry();
+    expect(() => registry.register({ model: '', key: 'code', records: [{ code: '1' }] })).toThrow(
+      'model must not be empty',
+    );
+  });
+
+  it('rejects fixture with no records', () => {
+    const registry = new FixtureRegistry();
+    expect(() => registry.register({ model: 'x.y', key: 'code', records: [] })).toThrow(
+      'at least one record',
+    );
+  });
+
+  it('resolves dependency order', () => {
+    const registry = new FixtureRegistry();
+    registry.register({
+      model: 'accounting.tax',
+      key: 'name',
+      depends: ['accounting.account'],
+      records: [{ name: 'VAT' }],
+    });
+    registry.register({
+      model: 'accounting.account',
+      key: 'code',
+      records: [{ code: '1000' }],
+    });
+
+    const order = registry.getLoadOrder();
+    const models = order.map((f) => f.model);
+    expect(models.indexOf('accounting.account')).toBeLessThan(models.indexOf('accounting.tax'));
+  });
+
+  it('filters by variant with fallback to default', () => {
+    const registry = new FixtureRegistry();
+    registry.register({
+      model: 'accounting.account',
+      key: 'code',
+      records: [{ code: '1000', name: 'Default' }],
+    });
+    registry.register({
+      model: 'accounting.account',
+      key: 'code',
+      variant: 'ID',
+      records: [{ code: '1-1000', name: 'Indonesia' }],
+    });
+    registry.register({
+      model: 'accounting.tax',
+      key: 'name',
+      records: [{ name: 'VAT' }],
+    });
+
+    const filtered = registry.getForVariant('ID');
+    const models = filtered.map((f) => f.model);
+    expect(models).toContain('accounting.account');
+    expect(models).toContain('accounting.tax');
+    // Should use ID variant for account
+    const accountFixture = filtered.find((f) => f.model === 'accounting.account');
+    expect(accountFixture?.records[0].name).toBe('Indonesia');
+  });
+});
+
+describe('Fixture Loader', () => {
+  function createMockDb() {
+    const tables: Record<string, any[]> = {};
+
+    const db: any = {
+      selectFrom: (table: string) => {
+        const rows = tables[table] ?? [];
+        const filters: Array<{ col: string; val: any }> = [];
+        const builder: any = {
+          selectAll: () => builder,
+          select: () => builder,
+          where: (col: string, op: string, val: any) => {
+            filters.push({ col, val });
+            return builder;
+          },
+          execute: async () => {
+            return rows.filter((r) => filters.every((f) => r[f.col] === f.val));
+          },
+        };
+        return builder;
+      },
+      insertInto: (table: string) => ({
+        values: (data: any) => ({
+          execute: async () => {
+            if (!tables[table]) tables[table] = [];
+            tables[table].push({ id: `id-${tables[table].length + 1}`, ...data });
+          },
+        }),
+      }),
+      updateTable: (table: string) => ({
+        set: (data: any) => ({
+          where: (col: string, op: string, val: any) => ({
+            execute: async () => {
+              const rows = tables[table] ?? [];
+              const row = rows.find((r) => r[col] === val);
+              if (row) Object.assign(row, data);
+            },
+          }),
+        }),
+      }),
+    };
+
+    return { db, tables };
+  }
+
+  it('inserts new records', async () => {
+    const { db, tables } = createMockDb();
+    const defs: FixtureDefinition[] = [
+      {
+        model: 'accounting.account',
+        key: 'account_code',
+        records: [
+          { account_code: '1000', name: 'Assets' },
+          { account_code: '2000', name: 'Liabilities' },
+        ],
+      },
+    ];
+
+    const result = await loadFixtures(db, defs);
+    expect(result.inserted).toBe(2);
+    expect(result.skipped).toBe(0);
+    expect(tables['accounting_account']).toHaveLength(2);
+  });
+
+  it('skips user-modified records (no fixture hash)', async () => {
+    const { db, tables } = createMockDb();
+    tables['accounting_account'] = [
+      { account_code: '1000', name: 'User Modified', _fixture_hash: undefined },
+    ];
+
+    const defs: FixtureDefinition[] = [
+      {
+        model: 'accounting.account',
+        key: 'account_code',
+        records: [{ account_code: '1000', name: 'Assets' }],
+      },
+    ];
+
+    const result = await loadFixtures(db, defs);
+    expect(result.skipped).toBe(1);
+    expect(tables['accounting_account'][0].name).toBe('User Modified');
+  });
+
+  it('force mode overwrites existing records', async () => {
+    const { db, tables } = createMockDb();
+    tables['accounting_account'] = [{ account_code: '1000', name: 'Old', _fixture_hash: null }];
+
+    const defs: FixtureDefinition[] = [
+      {
+        model: 'accounting.account',
+        key: 'account_code',
+        records: [{ account_code: '1000', name: 'Updated' }],
+      },
+    ];
+
+    const result = await loadFixtures(db, defs, { force: true });
+    expect(result.inserted).toBe(1);
+    expect(tables['accounting_account'][0].name).toBe('Updated');
+  });
+
+  it('resolves ref fields to record IDs', async () => {
+    const { db, tables } = createMockDb();
+    tables['accounting_account'] = [
+      { id: 'acct-uuid', account_code: '2100', name: 'Tax Payable', _fixture_hash: 'x' },
+    ];
+
+    const defs: FixtureDefinition[] = [
+      {
+        model: 'accounting.tax',
+        key: 'name',
+        records: [
+          {
+            name: 'VAT 11%',
+            rate: 11,
+            account: { ref: 'accounting.account', key: '2100' },
+          },
+        ],
+      },
+    ];
+
+    const result = await loadFixtures(db, defs);
+    expect(result.inserted).toBe(1);
+    expect(tables['accounting_tax'][0].account).toBe('acct-uuid');
+  });
+});

package/src/fixtures/index.ts

@@ -0,0 +1,10 @@
+export { FixtureRegistry } from './registry.js';
+export { loadFixtures } from './loader.js';
+export type {
+  FixtureDefinition,
+  FixtureRef,
+  FixtureRecord,
+  FixtureStatus,
+  FixtureLoadResult,
+  RegisteredFixture,
+} from './types.js';