@rangka/core 0.0.1

package/src/model-api/__tests__/extended-api.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ModelQueryBuilder } from '../query-builder.js';
+import type { SchemaRegistry } from '../../schema/registry.js';
+import type { ResolvedModel } from '../../schema/types.js';
+import type { RequestContext } from '../../auth/types.js';
+import { KyselyModelOps } from '../../db/model-ops.js';
+
+function makeModel(qualifiedName: string, traits: string[] = []): ResolvedModel {
+  return {
+    qualifiedName,
+    app: 'test',
+    module: qualifiedName.split('.')[0],
+    name: qualifiedName.split('.')[1],
+    auditLog: false,
+    traits,
+    fields: [
+      { name: 'id', config: { type: 'string' }, provenance: { source: 'base' } },
+      { name: 'name', config: { type: 'string', required: true }, provenance: { source: 'base' } },
+      { name: 'status', config: { type: 'string' }, provenance: { source: 'base' } },
+      {
+        name: 'created_by',
+        config: { type: 'string' },
+        provenance: { source: 'trait', trait: 'timestamped' },
+      },
+    ],
+    indexes: [],
+  } as ResolvedModel;
+}
+
+function makeRegistry(models: ResolvedModel[]): SchemaRegistry {
+  return {
+    getModel: (qn: string) => models.find((m) => m.qualifiedName === qn),
+    getAllModels: () => models,
+    getRelationshipsForModel: () => [],
+    getFieldsForModel: (qn: string) => models.find((m) => m.qualifiedName === qn)?.fields ?? [],
+  } as unknown as SchemaRegistry;
+}
+
+function makeMockDbAdapter(records: Record<string, unknown>[] = []): any {
+  const buildQuery = () => {
+    const q: any = {
+      _wheres: [],
+      _limit: undefined,
+      _offset: undefined,
+      _values: null,
+      _set: null,
+    };
+    q.select = vi.fn((..._args: any[]) => {
+      q._hasSelect = true;
+      return q;
+    });
+    q.selectAll = vi.fn(() => q);
+    q.where = vi.fn((field: string, op: string, value: any) => {
+      q._wheres.push({ field, op, value });
+      return q;
+    });
+    q.orderBy = vi.fn(() => q);
+    q.limit = vi.fn((n: number) => {
+      q._limit = n;
+      return q;
+    });
+    q.offset = vi.fn((n: number) => {
+      q._offset = n;
+      return q;
+    });
+    q.execute = vi.fn(async () => {
+      let data = [...records];
+      for (const w of q._wheres) {
+        if (w.op === '=') data = data.filter((r: any) => r[w.field] === w.value);
+        if (w.op === 'is' && w.value === null) data = data.filter((r: any) => r[w.field] == null);
+      }
+      const offset = q._offset ?? 0;
+      const limit = q._limit ?? data.length;
+      return data.slice(offset, offset + limit);
+    });
+    q.executeTakeFirst = vi.fn(async () => {
+      let data = [...records];
+      for (const w of q._wheres) {
+        if (w.op === '=') data = data.filter((r: any) => r[w.field] === w.value);
+        if (w.op === 'is' && w.value === null) data = data.filter((r: any) => r[w.field] == null);
+      }
+      if (q._hasSelect && !q._selectAll) return { count: String(data.length) };
+      return data[0] ?? undefined;
+    });
+    q.executeTakeFirstOrThrow = vi.fn(async () => {
+      const result = await q.executeTakeFirst();
+      if (!result) throw new Error('No result');
+      return result;
+    });
+    q.values = vi.fn((v: any) => {
+      q._values = v;
+      return q;
+    });
+    q.set = vi.fn((v: any) => {
+      q._set = v;
+      return q;
+    });
+    q.returningAll = vi.fn(() => q);
+    return q;
+  };
+
+  return {
+    selectFrom: vi.fn(() => buildQuery()),
+    insertInto: vi.fn(() => {
+      const q = buildQuery();
+      q.executeTakeFirstOrThrow = vi.fn(async () => ({ id: 'new-1', ...q._values }));
+      return q;
+    }),
+    updateTable: vi.fn(() => {
+      const q = buildQuery();
+      q.executeTakeFirstOrThrow = vi.fn(async () => ({ id: 'up-1', ...q._set }));
+      return q;
+    }),
+    deleteFrom: vi.fn(() => buildQuery()),
+  };
+}
+
+describe('ModelQueryBuilder extended API', () => {
+  const model = makeModel('sales.Order');
+  const registry = makeRegistry([model]);
+
+  function createBuilder(db: any, m: ResolvedModel = model, r: SchemaRegistry = registry) {
+    const ops = new KyselyModelOps({ db, model: m, registry: r });
+    return new ModelQueryBuilder(ops, m, r);
+  }
+
+  describe('page()', () => {
+    it('sets page for execWithMeta', async () => {
+      const records = Array.from({ length: 30 }, (_, i) => ({
+        id: `r${i}`,
+        name: `R${i}`,
+        status: 'a',
+      }));
+      const db = makeMockDbAdapter(records);
+
+      const result = await createBuilder(db).page(2).limit(10).execWithMeta();
+      expect(result.meta.page).toBe(2);
+      expect(result.meta.limit).toBe(10);
+    });
+  });
+
+  describe('includeArchived()', () => {
+    it('includes archived records for soft_delete model', async () => {
+      const softModel = makeModel('sales.Order', ['soft_delete']);
+      const records = [
+        { id: '1', name: 'Active', status: 'a', archived_at: null },
+        { id: '2', name: 'Archived', status: 'a', archived_at: '2026-01-01' },
+      ];
+      const db = makeMockDbAdapter(records);
+      const registry2 = makeRegistry([softModel]);
+
+      const withArchived = await createBuilder(db, softModel, registry2).includeArchived().exec();
+
+      const without = await createBuilder(db, softModel, registry2).exec();
+
+      expect(withArchived.data).toHaveLength(2);
+      expect(without.data).toHaveLength(1);
+    });
+  });
+
+  describe('withAuth()', () => {
+    it('applies scope filters from auth context', async () => {
+      const records = [
+        { id: '1', name: 'A', status: 'a', created_by: 'u1' },
+        { id: '2', name: 'B', status: 'a', created_by: 'u2' },
+      ];
+      const db = makeMockDbAdapter(records);
+
+      const auth: RequestContext = {
+        scopeFilters: [{ field: 'created_by', operator: 'eq', value: 'u1' }],
+      };
+
+      const result = await createBuilder(db).withAuth(auth).exec();
+
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].created_by).toBe('u1');
+    });
+
+    it('does not apply scopes when unscoped', async () => {
+      const records = [
+        { id: '1', name: 'A', status: 'a', created_by: 'u1' },
+        { id: '2', name: 'B', status: 'a', created_by: 'u2' },
+      ];
+      const db = makeMockDbAdapter(records);
+
+      const auth: RequestContext = {
+        scopeFilters: [{ field: 'created_by', operator: 'eq', value: 'u1' }],
+      };
+
+      const result = await createBuilder(db).withAuth(auth).unscoped().exec();
+
+      expect(result.data).toHaveLength(2);
+    });
+  });
+
+  describe('filterRaw()', () => {
+    it('accepts pre-translated filter tuples', async () => {
+      const records = [
+        { id: '1', name: 'Alpha', status: 'active' },
+        { id: '2', name: 'Beta', status: 'draft' },
+      ];
+      const db = makeMockDbAdapter(records);
+
+      const result = await createBuilder(db)
+        .filterRaw([{ field: 'status', operator: 'eq', value: 'active' }])
+        .exec();
+
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0].name).toBe('Alpha');
+    });
+  });
+
+  describe('execWithMeta()', () => {
+    it('returns data with pagination metadata', async () => {
+      const records = Array.from({ length: 50 }, (_, i) => ({
+        id: `r${i}`,
+        name: `R${i}`,
+        status: 'a',
+      }));
+      const db = makeMockDbAdapter(records);
+
+      const result = await createBuilder(db).limit(10).page(1).execWithMeta();
+
+      expect(result.data).toHaveLength(10);
+      expect(result.meta.total).toBe(50);
+      expect(result.meta.page).toBe(1);
+      expect(result.meta.limit).toBe(10);
+      expect(result.meta.totalPages).toBe(5);
+    });
+
+    it('calculates totalPages correctly with remainder', async () => {
+      const records = Array.from({ length: 7 }, (_, i) => ({
+        id: `r${i}`,
+        name: `R${i}`,
+        status: 'a',
+      }));
+      const db = makeMockDbAdapter(records);
+
+      const result = await createBuilder(db).limit(3).execWithMeta();
+
+      expect(result.meta.totalPages).toBe(3);
+    });
+  });
+});

package/src/model-api/__tests__/filter-applier.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from 'vitest';
+import {
+  Kysely,
+  DummyDriver,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+} from 'kysely';
+import { applyModelFilters } from '../filter-applier.js';
+import type { TranslatedFilter } from '../filter-translator.js';
+
+function createTestDb() {
+  return new Kysely<any>({
+    dialect: {
+      createAdapter: () => new PostgresAdapter(),
+      createDriver: () => new DummyDriver(),
+      createIntrospector: (db: any) => new PostgresIntrospector(db),
+      createQueryCompiler: () => new PostgresQueryCompiler(),
+    },
+  });
+}
+
+function compileQuery(db: Kysely<any>, filters: TranslatedFilter[]) {
+  let query = db.selectFrom('test_table').selectAll();
+  query = applyModelFilters(query, filters);
+  return query.compile();
+}
+
+describe('applyModelFilters', () => {
+  const db = createTestDb();
+
+  describe('eq operator', () => {
+    it('generates = clause', () => {
+      const compiled = compileQuery(db, [{ field: 'status', operator: 'eq', value: 'active' }]);
+      expect(compiled.sql).toContain('"status" = $1');
+      expect(compiled.parameters).toEqual(['active']);
+    });
+  });
+
+  describe('neq operator', () => {
+    it('generates != clause', () => {
+      const compiled = compileQuery(db, [{ field: 'status', operator: 'neq', value: 'cancelled' }]);
+      expect(compiled.sql).toContain('"status" != $1');
+      expect(compiled.parameters).toEqual(['cancelled']);
+    });
+  });
+
+  describe('gt operator', () => {
+    it('generates > clause', () => {
+      const compiled = compileQuery(db, [{ field: 'total', operator: 'gt', value: 100 }]);
+      expect(compiled.sql).toContain('"total" > $1');
+      expect(compiled.parameters).toEqual([100]);
+    });
+  });
+
+  describe('gte operator', () => {
+    it('generates >= clause', () => {
+      const compiled = compileQuery(db, [{ field: 'total', operator: 'gte', value: 100 }]);
+      expect(compiled.sql).toContain('"total" >= $1');
+      expect(compiled.parameters).toEqual([100]);
+    });
+  });
+
+  describe('lt operator', () => {
+    it('generates < clause', () => {
+      const compiled = compileQuery(db, [{ field: 'total', operator: 'lt', value: 50 }]);
+      expect(compiled.sql).toContain('"total" < $1');
+      expect(compiled.parameters).toEqual([50]);
+    });
+  });
+
+  describe('lte operator', () => {
+    it('generates <= clause', () => {
+      const compiled = compileQuery(db, [{ field: 'total', operator: 'lte', value: 50 }]);
+      expect(compiled.sql).toContain('"total" <= $1');
+      expect(compiled.parameters).toEqual([50]);
+    });
+  });
+
+  describe('in operator', () => {
+    it('generates IN clause', () => {
+      const compiled = compileQuery(db, [
+        { field: 'status', operator: 'in', value: ['a', 'b', 'c'] },
+      ]);
+      expect(compiled.sql).toContain('"status" in ($1, $2, $3)');
+      expect(compiled.parameters).toEqual(['a', 'b', 'c']);
+    });
+
+    it('generates false condition for empty array', () => {
+      const compiled = compileQuery(db, [{ field: 'status', operator: 'in', value: [] }]);
+      expect(compiled.sql).toContain('1 = 0');
+    });
+  });
+
+  describe('notIn operator', () => {
+    it('generates NOT IN clause', () => {
+      const compiled = compileQuery(db, [
+        { field: 'status', operator: 'notIn', value: ['x', 'y'] },
+      ]);
+      expect(compiled.sql).toContain('"status" not in ($1, $2)');
+      expect(compiled.parameters).toEqual(['x', 'y']);
+    });
+
+    it('is no-op for empty array', () => {
+      const compiled = compileQuery(db, [{ field: 'status', operator: 'notIn', value: [] }]);
+      expect(compiled.sql).not.toContain('not in');
+    });
+  });
+
+  describe('contains operator', () => {
+    it('generates ILIKE with % wrapping', () => {
+      const compiled = compileQuery(db, [
+        { field: 'email', operator: 'contains', value: '@acme.com' },
+      ]);
+      expect(compiled.sql).toContain('"email" ilike $1');
+      expect(compiled.parameters).toEqual(['%@acme.com%']);
+    });
+
+    it('escapes % and _ in the value', () => {
+      const compiled = compileQuery(db, [
+        { field: 'name', operator: 'contains', value: '100%_test' },
+      ]);
+      expect(compiled.parameters).toEqual(['%100\\%\\_test%']);
+    });
+  });
+
+  describe('startsWith operator', () => {
+    it('generates ILIKE with trailing %', () => {
+      const compiled = compileQuery(db, [{ field: 'name', operator: 'startsWith', value: 'John' }]);
+      expect(compiled.sql).toContain('"name" ilike $1');
+      expect(compiled.parameters).toEqual(['John%']);
+    });
+  });
+
+  describe('endsWith operator', () => {
+    it('generates ILIKE with leading %', () => {
+      const compiled = compileQuery(db, [{ field: 'email', operator: 'endsWith', value: '.org' }]);
+      expect(compiled.sql).toContain('"email" ilike $1');
+      expect(compiled.parameters).toEqual(['%.org']);
+    });
+  });
+
+  describe('is null operator', () => {
+    it('generates IS NULL', () => {
+      const compiled = compileQuery(db, [{ field: 'deleted_at', operator: 'is', value: null }]);
+      expect(compiled.sql).toContain('"deleted_at" is null');
+    });
+
+    it('generates IS NOT NULL for "not_null"', () => {
+      const compiled = compileQuery(db, [
+        { field: 'deleted_at', operator: 'is', value: 'not_null' },
+      ]);
+      expect(compiled.sql).toContain('"deleted_at" is not null');
+    });
+  });
+
+  describe('multiple filters', () => {
+    it('chains as AND conditions', () => {
+      const compiled = compileQuery(db, [
+        { field: 'status', operator: 'eq', value: 'active' },
+        { field: 'total', operator: 'gt', value: 100 },
+        { field: 'deleted_at', operator: 'is', value: null },
+      ]);
+      expect(compiled.sql).toContain('"status" = $1');
+      expect(compiled.sql).toContain('"total" > $2');
+      expect(compiled.sql).toContain('"deleted_at" is null');
+      expect(compiled.parameters).toEqual(['active', 100]);
+    });
+  });
+
+  describe('no filters', () => {
+    it('returns query unchanged for empty array', () => {
+      const compiled = compileQuery(db, []);
+      expect(compiled.sql).not.toContain('where');
+    });
+  });
+});

package/src/model-api/__tests__/filter-translator.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect } from 'vitest';
+import { translateFilters } from '../filter-translator.js';
+
+describe('translateFilters', () => {
+  describe('simple equality (shorthand)', () => {
+    it('treats plain value as eq operator', () => {
+      const result = translateFilters({ status: 'confirmed' });
+      expect(result).toEqual([{ field: 'status', operator: 'eq', value: 'confirmed' }]);
+    });
+
+    it('handles numeric equality', () => {
+      const result = translateFilters({ amount: 100 });
+      expect(result).toEqual([{ field: 'amount', operator: 'eq', value: 100 }]);
+    });
+
+    it('handles boolean equality', () => {
+      const result = translateFilters({ active: true });
+      expect(result).toEqual([{ field: 'active', operator: 'eq', value: true }]);
+    });
+
+    it('handles multiple fields as AND', () => {
+      const result = translateFilters({ status: 'confirmed', total: 500 });
+      expect(result).toEqual([
+        { field: 'status', operator: 'eq', value: 'confirmed' },
+        { field: 'total', operator: 'eq', value: 500 },
+      ]);
+    });
+  });
+
+  describe('explicit eq operator', () => {
+    it('handles { eq: value }', () => {
+      const result = translateFilters({ status: { eq: 'draft' } });
+      expect(result).toEqual([{ field: 'status', operator: 'eq', value: 'draft' }]);
+    });
+  });
+
+  describe('neq operator', () => {
+    it('handles { neq: value }', () => {
+      const result = translateFilters({ status: { neq: 'cancelled' } });
+      expect(result).toEqual([{ field: 'status', operator: 'neq', value: 'cancelled' }]);
+    });
+  });
+
+  describe('comparison operators', () => {
+    it('handles gt', () => {
+      const result = translateFilters({ total: { gt: 100 } });
+      expect(result).toEqual([{ field: 'total', operator: 'gt', value: 100 }]);
+    });
+
+    it('handles gte', () => {
+      const result = translateFilters({ total: { gte: 100 } });
+      expect(result).toEqual([{ field: 'total', operator: 'gte', value: 100 }]);
+    });
+
+    it('handles lt', () => {
+      const result = translateFilters({ total: { lt: 50 } });
+      expect(result).toEqual([{ field: 'total', operator: 'lt', value: 50 }]);
+    });
+
+    it('handles lte', () => {
+      const result = translateFilters({ total: { lte: 50 } });
+      expect(result).toEqual([{ field: 'total', operator: 'lte', value: 50 }]);
+    });
+
+    it('handles multiple operators on same field (range)', () => {
+      const result = translateFilters({ createdAt: { gte: '2026-01-01', lt: '2026-02-01' } });
+      expect(result).toEqual([
+        { field: 'createdAt', operator: 'gte', value: '2026-01-01' },
+        { field: 'createdAt', operator: 'lt', value: '2026-02-01' },
+      ]);
+    });
+  });
+
+  describe('array operators', () => {
+    it('handles in', () => {
+      const result = translateFilters({ status: { in: ['confirmed', 'shipped'] } });
+      expect(result).toEqual([
+        { field: 'status', operator: 'in', value: ['confirmed', 'shipped'] },
+      ]);
+    });
+
+    it('handles notIn', () => {
+      const result = translateFilters({ status: { notIn: ['cancelled', 'refunded'] } });
+      expect(result).toEqual([
+        { field: 'status', operator: 'notIn', value: ['cancelled', 'refunded'] },
+      ]);
+    });
+
+    it('handles empty array for in', () => {
+      const result = translateFilters({ status: { in: [] } });
+      expect(result).toEqual([{ field: 'status', operator: 'in', value: [] }]);
+    });
+  });
+
+  describe('string operators', () => {
+    it('handles contains', () => {
+      const result = translateFilters({ email: { contains: '@acme.com' } });
+      expect(result).toEqual([{ field: 'email', operator: 'contains', value: '@acme.com' }]);
+    });
+
+    it('handles startsWith', () => {
+      const result = translateFilters({ name: { startsWith: 'John' } });
+      expect(result).toEqual([{ field: 'name', operator: 'startsWith', value: 'John' }]);
+    });
+
+    it('handles endsWith', () => {
+      const result = translateFilters({ email: { endsWith: '.org' } });
+      expect(result).toEqual([{ field: 'email', operator: 'endsWith', value: '.org' }]);
+    });
+
+    it('handles string with SQL wildcards (escapes them)', () => {
+      const result = translateFilters({ name: { contains: '100%' } });
+      expect(result).toEqual([{ field: 'name', operator: 'contains', value: '100%' }]);
+    });
+  });
+
+  describe('null checks', () => {
+    it('handles { is: null }', () => {
+      const result = translateFilters({ deletedAt: { is: null } });
+      expect(result).toEqual([{ field: 'deletedAt', operator: 'is', value: null }]);
+    });
+
+    it('handles { is: "not_null" }', () => {
+      const result = translateFilters({ deletedAt: { is: 'not_null' } });
+      expect(result).toEqual([{ field: 'deletedAt', operator: 'is', value: 'not_null' }]);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns empty array for empty filter object', () => {
+      const result = translateFilters({});
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array for undefined input', () => {
+      const result = translateFilters(undefined as unknown as Record<string, unknown>);
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array for null input', () => {
+      const result = translateFilters(null as unknown as Record<string, unknown>);
+      expect(result).toEqual([]);
+    });
+
+    it('throws on unknown operator', () => {
+      expect(() => translateFilters({ status: { banana: 'yes' } as any })).toThrow(
+        /unknown filter operator.*banana/i,
+      );
+    });
+
+    it('handles filter value of 0 as equality (not falsy)', () => {
+      const result = translateFilters({ count: 0 });
+      expect(result).toEqual([{ field: 'count', operator: 'eq', value: 0 }]);
+    });
+
+    it('handles filter value of empty string as equality', () => {
+      const result = translateFilters({ name: '' });
+      expect(result).toEqual([{ field: 'name', operator: 'eq', value: '' }]);
+    });
+
+    it('handles filter value of null as shorthand for is null', () => {
+      const result = translateFilters({ deletedAt: null });
+      expect(result).toEqual([{ field: 'deletedAt', operator: 'is', value: null }]);
+    });
+  });
+
+  describe('complex combinations', () => {
+    it('handles multiple fields with mixed operators', () => {
+      const result = translateFilters({
+        status: { in: ['confirmed', 'shipped'] },
+        total: { gt: 100 },
+        email: { contains: '@acme.com' },
+        active: true,
+      });
+      expect(result).toHaveLength(4);
+      expect(result).toContainEqual({
+        field: 'status',
+        operator: 'in',
+        value: ['confirmed', 'shipped'],
+      });
+      expect(result).toContainEqual({ field: 'total', operator: 'gt', value: 100 });
+      expect(result).toContainEqual({ field: 'email', operator: 'contains', value: '@acme.com' });
+      expect(result).toContainEqual({ field: 'active', operator: 'eq', value: true });
+    });
+  });
+});