reqon-dsl 0.2.0

package/dist/interpreter/http.test.js

@@ -0,0 +1,299 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { HttpClient, BearerAuthProvider, OAuth2AuthProvider } from './http.js';
+describe('HttpClient', () => {
+    let originalFetch;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        vi.useRealTimers();
+    });
+    describe('buildUrl', () => {
+        it('constructs URL with base and path', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let capturedUrl = '';
+            globalThis.fetch = vi.fn(async (url) => {
+                capturedUrl = url.toString();
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({ method: 'GET', path: '/users' });
+            expect(capturedUrl).toBe('https://api.example.com/users');
+        });
+        it('handles trailing slash on base URL', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com/' });
+            let capturedUrl = '';
+            globalThis.fetch = vi.fn(async (url) => {
+                capturedUrl = url.toString();
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({ method: 'GET', path: '/users' });
+            expect(capturedUrl).toBe('https://api.example.com/users');
+        });
+        it('handles path without leading slash', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let capturedUrl = '';
+            globalThis.fetch = vi.fn(async (url) => {
+                capturedUrl = url.toString();
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({ method: 'GET', path: 'users' });
+            expect(capturedUrl).toBe('https://api.example.com/users');
+        });
+        it('adds query parameters to URL', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let capturedUrl = '';
+            globalThis.fetch = vi.fn(async (url) => {
+                capturedUrl = url.toString();
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({
+                method: 'GET',
+                path: '/users',
+                query: { page: '1', limit: '10' },
+            });
+            expect(capturedUrl).toBe('https://api.example.com/users?page=1&limit=10');
+        });
+    });
+    describe('headers', () => {
+        it('sets default Content-Type and Accept headers', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let capturedHeaders = {};
+            globalThis.fetch = vi.fn(async (_url, init) => {
+                capturedHeaders = Object.fromEntries(Object.entries(init?.headers || {}));
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({ method: 'GET', path: '/users' });
+            expect(capturedHeaders['Content-Type']).toBe('application/json');
+            expect(capturedHeaders['Accept']).toBe('application/json');
+        });
+        it('merges config headers', async () => {
+            const client = new HttpClient({
+                baseUrl: 'https://api.example.com',
+                headers: { 'X-Custom': 'value' },
+            });
+            let capturedHeaders = {};
+            globalThis.fetch = vi.fn(async (_url, init) => {
+                capturedHeaders = Object.fromEntries(Object.entries(init?.headers || {}));
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({ method: 'GET', path: '/users' });
+            expect(capturedHeaders['X-Custom']).toBe('value');
+        });
+        it('request headers override config headers', async () => {
+            const client = new HttpClient({
+                baseUrl: 'https://api.example.com',
+                headers: { 'X-Custom': 'config' },
+            });
+            let capturedHeaders = {};
+            globalThis.fetch = vi.fn(async (_url, init) => {
+                capturedHeaders = Object.fromEntries(Object.entries(init?.headers || {}));
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({
+                method: 'GET',
+                path: '/users',
+                headers: { 'X-Custom': 'request' },
+            });
+            expect(capturedHeaders['X-Custom']).toBe('request');
+        });
+        it('adds Authorization header when auth provider is set', async () => {
+            const auth = new BearerAuthProvider('test-token');
+            const client = new HttpClient({
+                baseUrl: 'https://api.example.com',
+                auth,
+            });
+            let capturedHeaders = {};
+            globalThis.fetch = vi.fn(async (_url, init) => {
+                capturedHeaders = Object.fromEntries(Object.entries(init?.headers || {}));
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await client.request({ method: 'GET', path: '/users' });
+            expect(capturedHeaders['Authorization']).toBe('Bearer test-token');
+        });
+    });
+    describe('calculateDelay', () => {
+        it('calculates exponential backoff delay', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            const delays = [];
+            let callCount = 0;
+            globalThis.fetch = vi.fn(async () => {
+                callCount++;
+                if (callCount < 3) {
+                    throw new Error('Network error');
+                }
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            const requestPromise = client.request({ method: 'GET', path: '/users' }, { maxAttempts: 3, backoff: 'exponential', initialDelay: 1000 });
+            // First retry delay: ~1000ms (1000 * 2^0)
+            await vi.advanceTimersByTimeAsync(1000);
+            // Second retry delay: ~2000ms (1000 * 2^1)
+            await vi.advanceTimersByTimeAsync(2000);
+            await requestPromise;
+            expect(callCount).toBe(3);
+        });
+        it('calculates linear backoff delay', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let callCount = 0;
+            globalThis.fetch = vi.fn(async () => {
+                callCount++;
+                if (callCount < 3) {
+                    throw new Error('Network error');
+                }
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            const requestPromise = client.request({ method: 'GET', path: '/users' }, { maxAttempts: 3, backoff: 'linear', initialDelay: 1000 });
+            // Advance through all retries with buffer for jitter
+            await vi.advanceTimersByTimeAsync(5000);
+            await requestPromise;
+            expect(callCount).toBe(3);
+        });
+        it('calculates constant backoff delay', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let callCount = 0;
+            globalThis.fetch = vi.fn(async () => {
+                callCount++;
+                if (callCount < 3) {
+                    throw new Error('Network error');
+                }
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            const requestPromise = client.request({ method: 'GET', path: '/users' }, { maxAttempts: 3, backoff: 'constant', initialDelay: 1000 });
+            // Both retries should use ~1000ms
+            await vi.advanceTimersByTimeAsync(1100);
+            await vi.advanceTimersByTimeAsync(1100);
+            await requestPromise;
+            expect(callCount).toBe(3);
+        });
+    });
+    describe('retry behavior', () => {
+        it('retries on 5xx server errors', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let callCount = 0;
+            globalThis.fetch = vi.fn(async () => {
+                callCount++;
+                if (callCount < 2) {
+                    return new Response(JSON.stringify({ error: 'Server error' }), { status: 500 });
+                }
+                return new Response(JSON.stringify({ data: 'success' }), { status: 200 });
+            });
+            const requestPromise = client.request({ method: 'GET', path: '/users' }, { maxAttempts: 3, backoff: 'constant', initialDelay: 100 });
+            await vi.advanceTimersByTimeAsync(150);
+            const result = await requestPromise;
+            expect(callCount).toBe(2);
+            expect(result.status).toBe(200);
+        });
+        it('respects Retry-After header on 429', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let callCount = 0;
+            globalThis.fetch = vi.fn(async () => {
+                callCount++;
+                if (callCount < 2) {
+                    const headers = new Headers();
+                    headers.set('Retry-After', '5'); // 5 seconds
+                    return new Response(JSON.stringify({}), { status: 429, headers });
+                }
+                return new Response(JSON.stringify({ data: 'success' }), { status: 200 });
+            });
+            const requestPromise = client.request({ method: 'GET', path: '/users' }, { maxAttempts: 3, backoff: 'exponential', initialDelay: 1000 });
+            // Should wait 5 seconds as specified in Retry-After
+            await vi.advanceTimersByTimeAsync(5000);
+            const result = await requestPromise;
+            expect(callCount).toBe(2);
+            expect(result.status).toBe(200);
+        });
+        it('throws after max retry attempts', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            globalThis.fetch = vi.fn(async () => {
+                throw new Error('Network error');
+            });
+            const requestPromise = client.request({ method: 'GET', path: '/users' }, { maxAttempts: 3, backoff: 'constant', initialDelay: 100 });
+            // Advance through all retries (need more time for async operations)
+            await vi.advanceTimersByTimeAsync(500);
+            await expect(requestPromise).rejects.toThrow('Network error');
+        });
+    });
+    describe('response handling', () => {
+        it('parses JSON response body', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            const responseData = { id: 1, name: 'Test' };
+            globalThis.fetch = vi.fn(async () => {
+                return new Response(JSON.stringify(responseData), { status: 200 });
+            });
+            const result = await client.request({
+                method: 'GET',
+                path: '/users/1',
+            });
+            expect(result.data).toEqual(responseData);
+        });
+        it('returns response headers', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            globalThis.fetch = vi.fn(async () => {
+                const headers = new Headers();
+                headers.set('X-Total-Count', '100');
+                return new Response(JSON.stringify({}), { status: 200, headers });
+            });
+            const result = await client.request({ method: 'GET', path: '/users' });
+            expect(result.headers['x-total-count']).toBe('100');
+        });
+        it('sends request body as JSON', async () => {
+            const client = new HttpClient({ baseUrl: 'https://api.example.com' });
+            let capturedBody;
+            globalThis.fetch = vi.fn(async (_url, init) => {
+                capturedBody = init?.body;
+                return new Response(JSON.stringify({}), { status: 201 });
+            });
+            await client.request({
+                method: 'POST',
+                path: '/users',
+                body: { name: 'Test', email: 'test@example.com' },
+            });
+            expect(capturedBody).toBe(JSON.stringify({ name: 'Test', email: 'test@example.com' }));
+        });
+    });
+});
+describe('BearerAuthProvider', () => {
+    it('returns the configured token', async () => {
+        const provider = new BearerAuthProvider('my-token');
+        const token = await provider.getToken();
+        expect(token).toBe('my-token');
+    });
+});
+describe('OAuth2AuthProvider', () => {
+    it('returns the access token', async () => {
+        const provider = new OAuth2AuthProvider({
+            accessToken: 'access-token',
+        });
+        const token = await provider.getToken();
+        expect(token).toBe('access-token');
+    });
+    it('throws when refreshToken called without required config', async () => {
+        const provider = new OAuth2AuthProvider({
+            accessToken: 'access-token',
+        });
+        await expect(provider.refreshToken()).rejects.toThrow('Cannot refresh token: missing refresh token or endpoint');
+    });
+    it('refreshes token using token endpoint', async () => {
+        const originalFetch = globalThis.fetch;
+        const provider = new OAuth2AuthProvider({
+            accessToken: 'old-token',
+            refreshToken: 'refresh-token',
+            tokenEndpoint: 'https://auth.example.com/token',
+            clientId: 'client-id',
+            clientSecret: 'client-secret',
+        });
+        globalThis.fetch = vi.fn(async () => {
+            return new Response(JSON.stringify({
+                access_token: 'new-token',
+                refresh_token: 'new-refresh-token',
+            }), { status: 200 });
+        });
+        const newToken = await provider.refreshToken();
+        expect(newToken).toBe('new-token');
+        // Token should be updated internally
+        const currentToken = await provider.getToken();
+        expect(currentToken).toBe('new-token');
+        globalThis.fetch = originalFetch;
+    });
+});

package/dist/interpreter/index.d.ts

@@ -0,0 +1,7 @@
+export { MissionExecutor, type ExecutionResult, type ExecutionError, type ExecutorConfig, type ProgressCallbacks, type ExecutionStartEvent, type ExecutionCompleteEvent, type StageStartEvent, type StageCompleteEvent, } from './executor.js';
+export { HttpClient, BearerAuthProvider, OAuth2AuthProvider, type HttpClientConfig, type AuthProvider } from './http.js';
+export { createContext, childContext, getVariable, setVariable, type ExecutionContext } from './context.js';
+export { evaluate, evaluateToString, interpolatePath } from './evaluator.js';
+export { FetchHandler, type FetchHandlerDeps, type FetchResult } from './fetch-handler.js';
+export { type PaginationStrategy, type PaginationContext, type PageResult, createPaginationStrategy, OffsetPaginationStrategy, PageNumberPaginationStrategy, CursorPaginationStrategy, } from './pagination.js';
+export { SkipSignal, RetrySignal, JumpSignal, QueueSignal, NoMatchError, AbortError, } from './signals.js';

package/dist/interpreter/index.js

@@ -0,0 +1,7 @@
+export { MissionExecutor, } from './executor.js';
+export { HttpClient, BearerAuthProvider, OAuth2AuthProvider } from './http.js';
+export { createContext, childContext, getVariable, setVariable } from './context.js';
+export { evaluate, evaluateToString, interpolatePath } from './evaluator.js';
+export { FetchHandler } from './fetch-handler.js';
+export { createPaginationStrategy, OffsetPaginationStrategy, PageNumberPaginationStrategy, CursorPaginationStrategy, } from './pagination.js';
+export { SkipSignal, RetrySignal, JumpSignal, QueueSignal, NoMatchError, AbortError, } from './signals.js';

package/dist/interpreter/pagination.d.ts

@@ -0,0 +1,63 @@
+import type { PaginationConfig } from '../ast/nodes.js';
+/**
+ * Context for pagination operations
+ */
+export interface PaginationContext {
+    page: number;
+    cursor?: string;
+    pageSize: number;
+}
+/**
+ * Result from extracting page data
+ */
+export interface PageResult {
+    items: unknown[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+/**
+ * Strategy interface for different pagination types
+ */
+export interface PaginationStrategy {
+    /** Build query parameters for the current page */
+    buildQuery(ctx: PaginationContext): Record<string, string>;
+    /** Extract results and determine if more pages exist */
+    extractResults(response: unknown, ctx: PaginationContext): PageResult;
+}
+/** Clear the array field cache (useful for testing) */
+export declare function clearPaginationCache(): void;
+/**
+ * Offset-based pagination (e.g., offset=100, offset=200)
+ */
+export declare class OffsetPaginationStrategy implements PaginationStrategy {
+    private config;
+    private cacheKey;
+    constructor(config: PaginationConfig);
+    buildQuery(ctx: PaginationContext): Record<string, string>;
+    extractResults(response: unknown, ctx: PaginationContext): PageResult;
+}
+/**
+ * Page number pagination (e.g., page=1, page=2)
+ */
+export declare class PageNumberPaginationStrategy implements PaginationStrategy {
+    private config;
+    private cacheKey;
+    constructor(config: PaginationConfig);
+    buildQuery(ctx: PaginationContext): Record<string, string>;
+    extractResults(response: unknown, ctx: PaginationContext): PageResult;
+}
+/**
+ * Cursor-based pagination (e.g., cursor=abc123)
+ */
+export declare class CursorPaginationStrategy implements PaginationStrategy {
+    private config;
+    private cacheKey;
+    private cachedArrayField;
+    constructor(config: PaginationConfig);
+    buildQuery(ctx: PaginationContext): Record<string, string>;
+    extractResults(response: unknown, ctx: PaginationContext): PageResult;
+}
+/**
+ * Create the appropriate pagination strategy based on config
+ */
+export declare function createPaginationStrategy(config: PaginationConfig): PaginationStrategy;

package/dist/interpreter/pagination.js

@@ -0,0 +1,155 @@
+import { extractNestedValue } from '../utils/path.js';
+/** Cache for discovered array field keys to avoid repeated lookups */
+const arrayFieldCache = new Map();
+/**
+ * Extract items array from response and determine if more pages exist
+ * Shared utility for offset and page-based pagination strategies
+ * Caches the discovered array field for subsequent pages
+ */
+function extractItemsFromResponse(response, pageSize, cacheKey) {
+    if (!response || typeof response !== 'object') {
+        return { items: [], hasMore: false };
+    }
+    const data = response;
+    // Check cache first if we have a cache key
+    if (cacheKey) {
+        const cachedField = arrayFieldCache.get(cacheKey);
+        if (cachedField !== undefined) {
+            if (cachedField === null) {
+                return { items: [], hasMore: false };
+            }
+            const items = data[cachedField];
+            if (Array.isArray(items)) {
+                return {
+                    items,
+                    hasMore: items.length >= pageSize,
+                };
+            }
+        }
+    }
+    // Search for array field
+    for (const key of Object.keys(data)) {
+        if (Array.isArray(data[key])) {
+            const items = data[key];
+            // Cache the discovered field
+            if (cacheKey) {
+                arrayFieldCache.set(cacheKey, key);
+            }
+            return {
+                items,
+                hasMore: items.length >= pageSize,
+            };
+        }
+    }
+    // Cache negative result
+    if (cacheKey) {
+        arrayFieldCache.set(cacheKey, null);
+    }
+    return { items: [], hasMore: false };
+}
+/** Clear the array field cache (useful for testing) */
+export function clearPaginationCache() {
+    arrayFieldCache.clear();
+}
+/**
+ * Offset-based pagination (e.g., offset=100, offset=200)
+ */
+export class OffsetPaginationStrategy {
+    config;
+    cacheKey;
+    constructor(config) {
+        this.config = config;
+        this.cacheKey = `offset:${config.param}`;
+    }
+    buildQuery(ctx) {
+        return {
+            [this.config.param]: String(ctx.page * ctx.pageSize),
+        };
+    }
+    extractResults(response, ctx) {
+        return extractItemsFromResponse(response, ctx.pageSize, this.cacheKey);
+    }
+}
+/**
+ * Page number pagination (e.g., page=1, page=2)
+ */
+export class PageNumberPaginationStrategy {
+    config;
+    cacheKey;
+    constructor(config) {
+        this.config = config;
+        this.cacheKey = `page:${config.param}`;
+    }
+    buildQuery(ctx) {
+        return {
+            [this.config.param]: String(ctx.page + 1), // 1-indexed
+        };
+    }
+    extractResults(response, ctx) {
+        return extractItemsFromResponse(response, ctx.pageSize, this.cacheKey);
+    }
+}
+/**
+ * Cursor-based pagination (e.g., cursor=abc123)
+ */
+export class CursorPaginationStrategy {
+    config;
+    cacheKey;
+    cachedArrayField = null;
+    constructor(config) {
+        this.config = config;
+        this.cacheKey = `cursor:${config.param}`;
+    }
+    buildQuery(ctx) {
+        if (ctx.cursor) {
+            return { [this.config.param]: ctx.cursor };
+        }
+        return {};
+    }
+    extractResults(response, ctx) {
+        if (!response || typeof response !== 'object') {
+            return { items: [], hasMore: false };
+        }
+        const data = response;
+        // Extract items - use cached field if available
+        let items = [];
+        if (this.cachedArrayField !== null && Array.isArray(data[this.cachedArrayField])) {
+            items = data[this.cachedArrayField];
+        }
+        else {
+            for (const key of Object.keys(data)) {
+                if (Array.isArray(data[key])) {
+                    items = data[key];
+                    this.cachedArrayField = key;
+                    break;
+                }
+            }
+        }
+        // Extract next cursor
+        let nextCursor;
+        if (this.config.cursorPath) {
+            const cursorValue = extractNestedValue(data, this.config.cursorPath);
+            nextCursor = cursorValue ? String(cursorValue) : undefined;
+        }
+        return {
+            items,
+            hasMore: !!nextCursor,
+            nextCursor,
+        };
+    }
+}
+/**
+ * Create the appropriate pagination strategy based on config
+ */
+export function createPaginationStrategy(config) {
+    switch (config.type) {
+        case 'offset':
+            return new OffsetPaginationStrategy(config);
+        case 'page':
+            return new PageNumberPaginationStrategy(config);
+        case 'cursor':
+            return new CursorPaginationStrategy(config);
+        default:
+            throw new Error(`Unknown pagination type: ${config.type}`);
+    }
+}

package/dist/interpreter/progress.test.d.ts

@@ -0,0 +1 @@
+export {};