ResolveSpec/clients/resolvespec-js/src/__tests__/headerspec.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { buildHeaders, encodeHeaderValue, decodeHeaderValue, HeaderSpecClient, getHeaderSpecClient } from '../headerspec/client';
import type { Options, ClientConfig, APIResponse } from '../common/types';

describe('buildHeaders (extended restheadspec options)', () => {
    it('should set X-Preload-Where when all preloads share one where', () => {
        const h = buildHeaders({
            preload: [
                { relation: 'Items', columns: ['id'], where: 'active = true' },
                { relation: 'Tags', where: 'active = true' },
            ],
        });
        expect(h['X-Preload']).toBe('Items:id|Tags');
        expect(h['X-Preload-Where']).toBe('active = true');
    });

    it('should use numbered headers for mixed where clauses', () => {
        const h = buildHeaders({
            preload: [
                { relation: 'Items', where: 'a = 1' },
                { relation: 'Category' },
                { relation: 'Tags', where: 'b = 2' },
            ],
        });
        expect(h['X-Preload']).toBe('Category');
        expect(h['X-Preload-Where']).toBeUndefined();
        expect(h['X-Preload-1']).toBe('Items');
        expect(h['X-Preload-1-Where']).toBe('a = 1');
        expect(h['X-Preload-2']).toBe('Tags');
        expect(h['X-Preload-2-Where']).toBe('b = 2');
    });

    it('should set expand, joins, or-sql, search cols, advsql', () => {
        const h = buildHeaders({
            expand: [{ relation: 'Dept', columns: ['id', 'name'] }, { relation: 'Role' }],
            custom_sql_joins: ['LEFT JOIN a ON a.id = b.id', 'INNER JOIN c ON c.id = b.cid'],
            custom_sql_or: ['x = 1', 'y = 2'],
            search_columns: ['name', 'email'],
            advanced_sql: { total: 'a + b' },
        });
        expect(h['X-Expand']).toBe('Dept:id,name|Role');
        expect(h['X-Custom-SQL-Join']).toBe('LEFT JOIN a ON a.id = b.id|INNER JOIN c ON c.id = b.cid');
        expect(h['X-Custom-SQL-Or']).toBe('x = 1 OR y = 2');
        expect(h['X-SearchCols']).toBe('name,email');
        expect(h['X-AdvSQL-total']).toBe('a + b');
    });

    it('should set boolean flags, pk row and response format', () => {
        const h = buildHeaders({
            clean_json: true,
            distinct: true,
            skip_count: true,
            skip_cache: false,
            atomic_transaction: true,
            single_record_as_object: false,
            pk_row: '42',
            response_format: 'detail',
        });
        expect(h['X-Clean-JSON']).toBe('true');
        expect(h['X-Distinct']).toBe('true');
        expect(h['X-SkipCount']).toBe('true');
        expect(h['X-SkipCache']).toBe('false');
        expect(h['X-Transaction-Atomic']).toBe('true');
        expect(h['X-Single-Record-As-Object']).toBe('false');
        expect(h['X-PKRow']).toBe('42');
        expect(h['X-DetailApi']).toBe('true');
    });

    it('should set spatial and vector filters as JSON', () => {
        const h = buildHeaders({
            filters: [
                { column: 'geom', operator: 'st_dwithin', value: { geom: 'POINT(0 0)', distance: 5 }, logic_operator: 'OR' },
                { column: 'emb', operator: 'cosine_within', value: { vector: [1, 2], distance: 0.3 } },
            ],
        });
        expect(JSON.parse(h['X-SpatialFilter-geom'])).toEqual({
            op: 'st_dwithin', value: { geom: 'POINT(0 0)', distance: 5 }, logic: 'or',
        });
        expect(JSON.parse(h['X-VectorFilter-emb']).op).toBe('cosine_within');
    });

    it('should set vector search headers', () => {
        const h = buildHeaders({
            vector_search: { column: 'emb', vector: [0.1, 0.2], metric: 'cosine', as: 'dist', direction: 'desc' },
        });
        expect(h['X-Vector-Search-emb']).toBe('cosine');
        expect(h['X-Vector-Search-Vector']).toBe('[0.1,0.2]');
        expect(h['X-Vector-Search-As']).toBe('dist');
        expect(h['X-Vector-Search-Dir']).toBe('desc');
    });

    it('should encode X-Files as ZIP_ JSON', () => {
        const xf = { tablename: 'users', prefix: 'USR', limit: 10 };
        const h = buildHeaders({ xfiles: xf });
        expect(h['X-Files'].startsWith('ZIP_')).toBe(true);
        expect(JSON.parse(decodeHeaderValue(h['X-Files']))).toEqual(xf);
    });
});

describe('buildHeaders', () => {
    it('should set X-Select-Fields for columns', () => {
        const h = buildHeaders({ columns: ['id', 'name', 'email'] });
        expect(h['X-Select-Fields']).toBe('id,name,email');
    });

    it('should set X-Not-Select-Fields for omit_columns', () => {
        const h = buildHeaders({ omit_columns: ['secret', 'internal'] });
        expect(h['X-Not-Select-Fields']).toBe('secret,internal');
    });

    it('should set X-FieldFilter for eq AND filters', () => {
        const h = buildHeaders({
            filters: [{ column: 'status', operator: 'eq', value: 'active' }],
        });
        expect(h['X-FieldFilter-status']).toBe('active');
    });

    it('should set X-SearchOp for non-eq AND filters', () => {
        const h = buildHeaders({
            filters: [{ column: 'age', operator: 'gte', value: 18 }],
        });
        expect(h['X-SearchOp-greaterthanorequal-age']).toBe('18');
    });

    it('should set X-SearchOr for OR filters', () => {
        const h = buildHeaders({
            filters: [{ column: 'name', operator: 'contains', value: 'test', logic_operator: 'OR' }],
        });
        expect(h['X-SearchOr-contains-name']).toBe('test');
    });

    it('should set X-Sort with direction prefixes', () => {
        const h = buildHeaders({
            sort: [
                { column: 'name', direction: 'asc' },
                { column: 'created_at', direction: 'DESC' },
            ],
        });
        expect(h['X-Sort']).toBe('+name,-created_at');
    });

    it('should set X-Limit and X-Offset', () => {
        const h = buildHeaders({ limit: 25, offset: 50 });
        expect(h['X-Limit']).toBe('25');
        expect(h['X-Offset']).toBe('50');
    });

    it('should set cursor pagination headers', () => {
        const h = buildHeaders({ cursor_forward: 'abc', cursor_backward: 'xyz' });
        expect(h['X-Cursor-Forward']).toBe('abc');
        expect(h['X-Cursor-Backward']).toBe('xyz');
    });

    it('should set X-Preload with pipe-separated relations', () => {
        const h = buildHeaders({
            preload: [
                { relation: 'Items', columns: ['id', 'name'] },
                { relation: 'Category' },
            ],
        });
        expect(h['X-Preload']).toBe('Items:id,name|Category');
    });

    it('should set X-Fetch-RowNumber', () => {
        const h = buildHeaders({ fetch_row_number: '42' });
        expect(h['X-Fetch-RowNumber']).toBe('42');
    });

    it('should set X-CQL-SEL for computed columns', () => {
        const h = buildHeaders({
            computedColumns: [
                { name: 'total', expression: 'price * qty' },
            ],
        });
        expect(h['X-CQL-SEL-total']).toBe('price * qty');
    });

    it('should set X-Custom-SQL-W for custom operators', () => {
        const h = buildHeaders({
            customOperators: [
                { name: 'active', sql: "status = 'active'" },
                { name: 'verified', sql: "verified = true" },
            ],
        });
        expect(h['X-Custom-SQL-W']).toBe("status = 'active' AND verified = true");
    });

    it('should return empty object for empty options', () => {
        const h = buildHeaders({});
        expect(Object.keys(h)).toHaveLength(0);
    });

    it('should handle between filter with array value', () => {
        const h = buildHeaders({
            filters: [{ column: 'price', operator: 'between', value: [10, 100] }],
        });
        expect(h['X-SearchOp-between-price']).toBe('10,100');
    });

    it('should handle is_null filter with null value', () => {
        const h = buildHeaders({
            filters: [{ column: 'deleted_at', operator: 'is_null', value: null }],
        });
        expect(h['X-SearchOp-empty-deleted_at']).toBe('');
    });

    it('should handle in filter with array value', () => {
        const h = buildHeaders({
            filters: [{ column: 'id', operator: 'in', value: [1, 2, 3] }],
        });
        expect(h['X-SearchOp-in-id']).toBe('1,2,3');
    });
});

describe('encodeHeaderValue / decodeHeaderValue', () => {
    it('should round-trip encode/decode', () => {
        const original = 'some complex value with spaces & symbols!';
        const encoded = encodeHeaderValue(original);
        expect(encoded.startsWith('ZIP_')).toBe(true);
        const decoded = decodeHeaderValue(encoded);
        expect(decoded).toBe(original);
    });

    it('should round-trip UTF-8 values', () => {
        const original = 'café ☕ 你好';
        expect(decodeHeaderValue(encodeHeaderValue(original))).toBe(original);
    });

    it('should decode __ prefixed values', () => {
        const encoded = '__' + btoa('hello');
        expect(decodeHeaderValue(encoded)).toBe('hello');
    });

    it('should decode UTF-8 values with the __ prefix', () => {
        const bytes = new TextEncoder().encode('café ☕');
        const binary = Array.from(bytes, (byte) => String.fromCharCode(byte)).join('');
        expect(decodeHeaderValue('__' + btoa(binary))).toBe('café ☕');
    });

    it('should return plain values as-is', () => {
        expect(decodeHeaderValue('plain')).toBe('plain');
    });
});

describe('HeaderSpecClient', () => {
    const config: ClientConfig = { baseUrl: 'http://localhost:3000', token: 'tok' };

    function mockFetch<T>(data: APIResponse<T>, ok = true) {
        return vi.fn().mockResolvedValue({
            ok,
            headers: new Headers(),
            json: () => Promise.resolve(data),
        });
    }

    beforeEach(() => {
        vi.restoreAllMocks();
    });

    it('read() sends GET with headers from options', async () => {
        globalThis.fetch = mockFetch({ success: true, data: [{ id: 1 }] });
        const client = new HeaderSpecClient(config);

        await client.read('public', 'users', undefined, {
            columns: ['id', 'name'],
            limit: 10,
        });

        const [url, opts] = (globalThis.fetch as any).mock.calls[0];
        expect(url).toBe('http://localhost:3000/public/users');
        expect(opts.method).toBe('GET');
        expect(opts.headers['X-Select-Fields']).toBe('id,name');
        expect(opts.headers['X-Limit']).toBe('10');
        expect(opts.headers['Authorization']).toBe('Bearer tok');
    });

    it('read() with id appends to URL', async () => {
        globalThis.fetch = mockFetch({ success: true, data: {} });
        const client = new HeaderSpecClient(config);

        await client.read('public', 'users', '42');

        const [url] = (globalThis.fetch as any).mock.calls[0];
        expect(url).toBe('http://localhost:3000/public/users/42');
    });

    it('create() sends POST with body and headers', async () => {
        globalThis.fetch = mockFetch({ success: true, data: { id: 1 } });
        const client = new HeaderSpecClient(config);

        await client.create('public', 'users', { name: 'Test' });

        const [url, opts] = (globalThis.fetch as any).mock.calls[0];
        expect(opts.method).toBe('POST');
        expect(JSON.parse(opts.body)).toEqual({ name: 'Test' });
    });

    it('update() sends PUT with id in URL', async () => {
        globalThis.fetch = mockFetch({ success: true, data: {} });
        const client = new HeaderSpecClient(config);

        await client.update('public', 'users', '1', { name: 'Updated' }, {
            filters: [{ column: 'active', operator: 'eq', value: true }],
        });

        const [url, opts] = (globalThis.fetch as any).mock.calls[0];
        expect(url).toBe('http://localhost:3000/public/users/1');
        expect(opts.method).toBe('PUT');
        expect(opts.headers['X-FieldFilter-active']).toBe('true');
    });

    it('delete() sends DELETE', async () => {
        globalThis.fetch = mockFetch({ success: true, data: undefined as any });
        const client = new HeaderSpecClient(config);

        await client.delete('public', 'users', '1');

        const [url, opts] = (globalThis.fetch as any).mock.calls[0];
        expect(url).toBe('http://localhost:3000/public/users/1');
        expect(opts.method).toBe('DELETE');
    });

    it('throws on non-ok response', async () => {
        globalThis.fetch = mockFetch(
            { success: false, data: null as any, error: { code: 'err', message: 'fail' } },
            false
        );
        const client = new HeaderSpecClient(config);

        await expect(client.read('public', 'users')).rejects.toThrow('fail');
    });
});

describe('getHeaderSpecClient singleton', () => {
    it('returns same instance for same baseUrl', () => {
        const a = getHeaderSpecClient({ baseUrl: 'http://hs-singleton:3000' });
        const b = getHeaderSpecClient({ baseUrl: 'http://hs-singleton:3000' });
        expect(a).toBe(b);
    });

    it('returns different instances for different baseUrls', () => {
        const a = getHeaderSpecClient({ baseUrl: 'http://hs-singleton-a:3000' });
        const b = getHeaderSpecClient({ baseUrl: 'http://hs-singleton-b:3000' });
        expect(a).not.toBe(b);
    });
});