vovk 3.0.0-draft.98 → 3.0.0

package/dist/client/defaultStreamHandler.js

@@ -1,82 +1,279 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultStreamHandler = exports.DEFAULT_ERROR_MESSAGE = void 0;
-const types_1 = require("../types");
-const HttpException_1 = require("../HttpException");
-require("../utils/shim");
-exports.DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultStreamHandler';
-const defaultStreamHandler = async (response) => {
-    if (!response.ok) {
-        let result;
+import { HttpStatus } from '../types/enums.js';
+import { HttpException } from '../core/HttpException.js';
+import '../utils/shim.js';
+export const DEFAULT_ERROR_MESSAGE = 'An unknown error at the default stream handler';
+/**
+ * Converts a ReadableStream of JSON Lines into a VovkStreamAsyncIterable.
+ * This is the core streaming logic extracted for reuse outside of HTTP contexts.
+ * @see https://vovk.dev/jsonlines
+ */
+export const readableStreamToAsyncIterable = ({ readableStream, abortController, }) => {
+    const reader = readableStream.getReader();
+    const subscribers = new Set();
+    // State
+    let isAbortedWithoutError = false;
+    let streamExhausted = false;
+    let streamError = null;
+    let errorIndex = -1;
+    let primaryStarted = false;
+    const cachedItems = [];
+    const waiters = [];
+    // --- Helper functions ---
+    const notifyWaiters = () => {
+        for (let i = waiters.length - 1; i >= 0; i--) {
+            const waiter = waiters[i];
+            let handled = false;
+            if (streamError && waiter.index >= errorIndex) {
+                waiter.reject(streamError);
+                handled = true;
+            }
+            else if (waiter.index < cachedItems.length) {
+                waiter.resolve({ value: cachedItems[waiter.index], done: false });
+                handled = true;
+            }
+            else if (streamExhausted || (abortController?.signal.aborted && isAbortedWithoutError)) {
+                waiter.resolve({ value: undefined, done: true });
+                handled = true;
+            }
+            if (handled) {
+                waiters.splice(i, 1);
+            }
+        }
+    };
+    const setStreamError = (error) => {
+        errorIndex = cachedItems.length;
+        streamError = error;
+        notifyWaiters();
+    };
+    const disposeStream = (reason) => {
+        isAbortedWithoutError = true;
+        streamExhausted = true;
+        notifyWaiters();
+        abortController?.abort(reason);
+        reader.cancel().catch(() => { });
+    };
+    // --- Primary reader ---
+    const runPrimaryReader = async () => {
+        let buffer = '';
+        let iterationIndex = 0;
+        // Returns true if the stream should stop (error encountered)
+        const processLine = (line) => {
+            let data;
+            try {
+                data = JSON.parse(line);
+            }
+            catch {
+                return false;
+            }
+            if (data) {
+                subscribers.forEach((cb) => {
+                    if (!abortController?.signal.aborted)
+                        cb(data, iterationIndex);
+                });
+                iterationIndex++;
+                if (typeof data === 'object' && data !== null && 'isError' in data && 'reason' in data) {
+                    const upcomingError = data.reason;
+                    abortController?.abort(upcomingError);
+                    const error = typeof upcomingError === 'string' ? new Error(upcomingError) : upcomingError;
+                    setStreamError(error);
+                    return true;
+                }
+                else if (!abortController?.signal.aborted) {
+                    cachedItems.push(data);
+                    notifyWaiters();
+                }
+            }
+            return false;
+        };
         try {
-            result = await response.json();
+            while (true) {
+                if (abortController?.signal.aborted && isAbortedWithoutError) {
+                    break;
+                }
+                let value;
+                let done;
+                try {
+                    ({ value, done } = await reader.read());
+                    if (done)
+                        break;
+                }
+                catch (error) {
+                    if (error?.name === 'AbortError' && isAbortedWithoutError) {
+                        break;
+                    }
+                    const err = new Error('JSONLines stream error. ' + String(error));
+                    err.cause = error;
+                    setStreamError(err);
+                    return;
+                }
+                const chunk = typeof value === 'string'
+                    ? value
+                    : typeof value === 'number'
+                        ? String.fromCharCode(value)
+                        : new TextDecoder().decode(value);
+                buffer += chunk;
+                let newlineIdx;
+                while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+                    if (abortController?.signal.aborted && isAbortedWithoutError) {
+                        break;
+                    }
+                    const line = buffer.slice(0, newlineIdx);
+                    buffer = buffer.slice(newlineIdx + 1);
+                    if (!line)
+                        continue;
+                    if (processLine(line))
+                        return;
+                }
+                if (abortController?.signal.aborted && isAbortedWithoutError) {
+                    break;
+                }
+            }
+            // Process any remaining data in the buffer (last line without trailing newline)
+            const remaining = buffer.trim();
+            if (remaining) {
+                processLine(remaining);
+            }
         }
-        catch {
-            // ignore parsing errors
+        finally {
+            streamExhausted = true;
+            notifyWaiters();
         }
-        // handle server errors
-        throw new HttpException_1.HttpException(response.status, result.message ?? exports.DEFAULT_ERROR_MESSAGE);
-    }
-    if (!response.body)
-        throw new HttpException_1.HttpException(types_1.HttpStatus.NULL, 'Stream body is falsy. Check your controller code.');
-    const reader = response.body.getReader();
-    // if streaming is too rapid, we need to make sure that the loop is stopped
-    let canceled = false;
+    };
+    // --- Async iterator ---
     async function* asyncIterator() {
-        let prepend = '';
+        if (!primaryStarted) {
+            primaryStarted = true;
+            void runPrimaryReader();
+        }
+        let index = 0;
         while (true) {
-            let value;
-            let done = false;
-            try {
-                ({ value, done } = await reader.read());
+            // Check error first
+            if (streamError && index >= errorIndex) {
+                throw streamError;
+            }
+            // Clean exit on abort without error
+            if (abortController?.signal.aborted && isAbortedWithoutError) {
+                return;
             }
-            catch (error) {
-                await reader.cancel();
-                const err = new Error('Stream error. ' + String(error));
-                err.cause = error;
-                throw err;
+            // Yield from cache if available
+            if (index < cachedItems.length) {
+                yield cachedItems[index++];
+                continue;
             }
-            if (done) {
+            // Stream finished
+            if (streamExhausted) {
                 return;
             }
-            // typeof value === 'number' is a workaround for React Native
-            const string = typeof value === 'number' ? String.fromCharCode(value) : new TextDecoder().decode(value);
-            prepend += string;
-            const lines = prepend.split('\n').filter(Boolean);
-            for (const line of lines) {
-                let data;
-                try {
-                    data = JSON.parse(line);
-                    prepend = '';
+            // Wait for next item or completion
+            const result = await new Promise((resolve, reject) => {
+                // Re-check state inside promise to handle race conditions
+                if (streamError && index >= errorIndex) {
+                    reject(streamError);
+                    return;
                 }
-                catch {
-                    break;
+                if (abortController?.signal.aborted && isAbortedWithoutError) {
+                    resolve({ value: undefined, done: true });
+                    return;
                 }
-                if (data) {
-                    if ('isError' in data && 'reason' in data) {
-                        const upcomingError = data.reason;
-                        await reader.cancel();
-                        if (typeof upcomingError === 'string') {
-                            throw new Error(upcomingError);
-                        }
-                        throw upcomingError;
-                    }
-                    else if (!canceled) {
-                        yield data;
-                    }
+                if (index < cachedItems.length) {
+                    resolve({ value: cachedItems[index], done: false });
+                    return;
+                }
+                if (streamExhausted) {
+                    resolve({ value: undefined, done: true });
+                    return;
                 }
+                waiters.push({ index, resolve, reject });
+            });
+            if (result.done) {
+                return;
             }
+            index++;
+            yield result.value;
         }
     }
+    // --- Public API ---
+    const asPromise = async () => {
+        const items = [];
+        for await (const item of asyncIterator()) {
+            items.push(item);
+        }
+        return items;
+    };
+    const abortSilently = (reason) => {
+        isAbortedWithoutError = true;
+        streamExhausted = true;
+        notifyWaiters();
+        abortController?.abort(reason);
+        reader.cancel().catch(() => { });
+    };
     return {
-        status: response.status,
+        asPromise,
+        // abortController,
         [Symbol.asyncIterator]: asyncIterator,
-        [Symbol.dispose]: () => reader.cancel(),
-        [Symbol.asyncDispose]: () => reader.cancel(),
-        cancel: () => {
-            canceled = true;
-            return reader.cancel();
+        [Symbol.dispose]: () => disposeStream('Stream disposed'),
+        [Symbol.asyncDispose]: async () => disposeStream('Stream async disposed'),
+        abortSilently,
+        onIterate: (cb) => {
+            if (abortController?.signal.aborted)
+                return () => { };
+            subscribers.add(cb);
+            return () => subscribers.delete(cb);
         },
     };
 };
-exports.defaultStreamHandler = defaultStreamHandler;
+export const defaultStreamHandler = ({ response, abortController, }) => {
+    // Handle error responses by creating a stream that fails on first iteration
+    if (!response.ok) {
+        let cachedError = null;
+        let errorParsed = false;
+        // Parse error asynchronously and cache it
+        void response
+            .json()
+            .then((res) => {
+            cachedError = new HttpException(response.status, res.message ?? DEFAULT_ERROR_MESSAGE);
+        })
+            .catch((e) => {
+            cachedError = new HttpException(response.status, e.message ?? DEFAULT_ERROR_MESSAGE, e);
+        })
+            .finally(() => {
+            errorParsed = true;
+        });
+        const getError = async () => {
+            // Wait for error to be parsed
+            while (!errorParsed) {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+            return cachedError ?? new HttpException(response.status, DEFAULT_ERROR_MESSAGE);
+        };
+        const errorIterator = () => ({
+            async next() {
+                throw await getError();
+            },
+        });
+        const noop = () => { };
+        return {
+            status: response.status,
+            asPromise: async () => {
+                throw await getError();
+            },
+            abortController,
+            [Symbol.asyncIterator]: errorIterator,
+            [Symbol.dispose]: noop,
+            [Symbol.asyncDispose]: async () => { },
+            abortSilently: noop,
+            onIterate: () => noop,
+        };
+    }
+    if (!response.body) {
+        throw new HttpException(HttpStatus.NULL, 'Stream body is falsy');
+    }
+    return {
+        status: response.status,
+        abortController,
+        ...readableStreamToAsyncIterable({
+            readableStream: response.body,
+            abortController,
+        }),
+    };
+};

package/dist/client/fetcher.d.ts

@@ -1,3 +1,41 @@
-import type { VovkDefaultFetcherOptions, VovkClientFetcher } from './types';
-export declare const DEFAULT_ERROR_MESSAGE = "Unknown error at the defaultFetcher";
-export declare const fetcher: VovkClientFetcher<VovkDefaultFetcherOptions>;
+import { HttpException } from '../core/HttpException.js';
+import type { VovkFetcherOptions, VovkFetcher } from '../types/client.js';
+import type { VovkHandlerSchema } from '../types/core.js';
+export declare const DEFAULT_ERROR_MESSAGE = "Unknown error at default fetcher";
+export type { VovkFetcher };
+/**
+ * Creates a customizable fetcher function for client requests.
+ * @see https://vovk.dev/imports
+ */
+export declare function createFetcher<T>({ prepareRequestInit, transformResponse, onSuccess, onError, }?: {
+    prepareRequestInit?: (init: RequestInit, options: VovkFetcherOptions<T>) => RequestInit | Promise<RequestInit>;
+    transformResponse?: (respData: unknown, options: VovkFetcherOptions<T>, info: {
+        response: Response;
+        init: RequestInit;
+        schema: VovkHandlerSchema;
+    }) => unknown | Promise<unknown>;
+    onSuccess?: (respData: unknown, options: VovkFetcherOptions<T>, info: {
+        response: Response;
+        init: RequestInit;
+        schema: VovkHandlerSchema;
+    }) => void | Promise<void>;
+    onError?: (error: HttpException, options: VovkFetcherOptions<T>, info: {
+        response: Response | null;
+        init: RequestInit | null;
+        respData: unknown | null;
+        schema: VovkHandlerSchema;
+    }) => void | Promise<void>;
+}): VovkFetcher<VovkFetcherOptions<T>>;
+/**
+ * Default fetcher implementation for client requests.
+ * @see https://vovk.dev/imports
+ */
+export declare const fetcher: VovkFetcher<{
+    apiRoot?: string;
+    disableClientValidation?: boolean;
+    validateOnClient?: import("../index.js").VovkValidateOnClient<unknown> | Promise<{
+        validateOnClient: import("../index.js").VovkValidateOnClient<unknown>;
+    }> | undefined;
+    interpretAs?: string;
+    init?: RequestInit;
+}>;

package/dist/client/fetcher.js

@@ -1,64 +1,129 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fetcher = exports.DEFAULT_ERROR_MESSAGE = void 0;
-const types_1 = require("../types");
-const HttpException_1 = require("../HttpException");
-exports.DEFAULT_ERROR_MESSAGE = 'Unknown error at the defaultFetcher';
-// defaultFetcher uses HttpException class to throw errors of fake HTTP status 0 if client-side error occurs
-// For normal HTTP errors, it uses message and status code from the response of VovkErrorResponse type
-const fetcher = async ({ httpMethod, getEndpoint, validate, defaultHandler, defaultStreamHandler }, { params, query, body, apiRoot = '/api', ...options }) => {
-    const endpoint = getEndpoint({ apiRoot, params, query });
-    if (!options.disableClientValidation) {
+import { HttpStatus } from '../types/enums.js';
+import { HttpException } from '../core/HttpException.js';
+import { fileNameToDisposition } from '../utils/fileNameToDisposition.js';
+export const DEFAULT_ERROR_MESSAGE = 'Unknown error at default fetcher';
+/**
+ * Creates a customizable fetcher function for client requests.
+ * @see https://vovk.dev/imports
+ */
+export function createFetcher({ prepareRequestInit, transformResponse, onSuccess, onError, } = {}) {
+    // fetcher uses HttpException class to throw errors of fake HTTP status 0 if client-side error occurs
+    // For normal HTTP errors, it uses message and status code from the response of VovkErrorResponse type
+    const newFetcher = async ({ httpMethod, getURL, validate, defaultHandler, defaultStreamHandler, schema }, inputOptions) => {
+        let response = null;
+        let respData = null;
+        let requestInit = null;
         try {
-            await validate({ body, query, params, endpoint });
+            const { meta, apiRoot, disableClientValidation, init, interpretAs } = inputOptions;
+            let { body, query, params } = inputOptions;
+            const endpoint = getURL({ apiRoot, params, query });
+            const unusedParams = Array.from(new URL(endpoint.startsWith('/') ? `http://localhost${endpoint}` : endpoint).pathname.matchAll(/\{([^}]+)\}/g)).map((m) => m[1]);
+            if (unusedParams.length) {
+                throw new HttpException(HttpStatus.NULL, `Unused params: ${unusedParams.join(', ')} in ${endpoint}`, {
+                    body,
+                    query,
+                    params,
+                    endpoint,
+                });
+            }
+            if (!disableClientValidation) {
+                try {
+                    ({ body, query, params } = (await validate(inputOptions, { endpoint })) ?? { body, query, params });
+                }
+                catch (e) {
+                    // if HttpException is thrown, rethrow it
+                    if (e instanceof HttpException)
+                        throw e;
+                    // otherwise, throw HttpException with status 0
+                    throw new HttpException(HttpStatus.NULL, e.message ?? DEFAULT_ERROR_MESSAGE, {
+                        body,
+                        query,
+                        params,
+                        endpoint,
+                    });
+                }
+            }
+            const resolvedContentType = body instanceof FormData
+                ? undefined // browser sets multipart/form-data with boundary automatically
+                : body instanceof URLSearchParams
+                    ? 'application/x-www-form-urlencoded'
+                    : typeof body === 'string'
+                        ? 'text/plain'
+                        : body instanceof Blob
+                            ? body.type || 'application/octet-stream'
+                            : body instanceof ArrayBuffer || body instanceof Uint8Array
+                                ? 'application/octet-stream'
+                                : 'application/json';
+            const resolvedFileName = body instanceof File ? body.name : undefined;
+            // Default headers (lowercase keys)
+            const defaultHeaders = {
+                accept: 'application/jsonl, application/json',
+                ...(resolvedContentType ? { 'content-type': resolvedContentType } : {}),
+                ...(resolvedFileName ? { 'content-disposition': fileNameToDisposition(resolvedFileName) } : {}),
+                ...(meta ? { 'x-meta': JSON.stringify(meta) } : {}),
+            };
+            // Normalize user headers to lowercase keys via Headers API (handles plain objects, arrays, and Headers instances)
+            const userHeaders = init?.headers ? Object.fromEntries(new Headers(init.headers).entries()) : {};
+            requestInit = {
+                method: httpMethod,
+                ...init,
+                headers: { ...defaultHeaders, ...userHeaders },
+            };
+            if (body instanceof FormData || body instanceof URLSearchParams) {
+                requestInit.body = body;
+            }
+            else if (body instanceof Blob) {
+                requestInit.body = body;
+            }
+            else if (body instanceof ArrayBuffer || body instanceof Uint8Array) {
+                requestInit.body = body;
+            }
+            else if (typeof body === 'string') {
+                requestInit.body = body;
+            }
+            else if (body) {
+                requestInit.body = JSON.stringify(body);
+            }
+            const abortController = new AbortController();
+            requestInit.signal = abortController.signal;
+            requestInit = prepareRequestInit ? await prepareRequestInit(requestInit, inputOptions) : requestInit;
+            try {
+                response = await fetch(endpoint, requestInit);
+            }
+            catch (e) {
+                // handle network errors
+                throw new HttpException(HttpStatus.NULL, (e?.message ?? DEFAULT_ERROR_MESSAGE) + ' ' + endpoint, {
+                    body,
+                    query,
+                    params,
+                    endpoint,
+                });
+            }
+            const contentType = interpretAs ?? response.headers.get('content-type');
+            if (contentType?.startsWith('application/jsonl')) {
+                respData = defaultStreamHandler({ response, abortController });
+            }
+            else if (contentType?.startsWith('application/json')) {
+                respData = await defaultHandler({ response, schema });
+            }
+            else {
+                respData = response;
+            }
+            respData = transformResponse
+                ? await transformResponse(respData, inputOptions, { response, init: requestInit, schema })
+                : respData;
+            await onSuccess?.(respData, inputOptions, { response, init: requestInit, schema });
+            return [respData, response];
         }
-        catch (e) {
-            // if HttpException is thrown, rethrow it
-            if (e instanceof HttpException_1.HttpException)
-                throw e;
-            // otherwise, throw HttpException with status 0
-            throw new HttpException_1.HttpException(types_1.HttpStatus.NULL, e.message ?? exports.DEFAULT_ERROR_MESSAGE, {
-                body,
-                query,
-                params,
-                endpoint,
-            });
+        catch (error) {
+            await onError?.(error, inputOptions, { response, init: requestInit, respData, schema });
+            throw error;
         }
-    }
-    const init = {
-        method: httpMethod,
-        ...options,
-        headers: {
-            ...options.headers,
-            accept: 'application/jsonl, application/json',
-        },
     };
-    if (body instanceof FormData) {
-        init.body = body;
-    }
-    else if (body) {
-        init.body = JSON.stringify(body);
-    }
-    let response;
-    try {
-        response = await fetch(endpoint, init);
-    }
-    catch (e) {
-        // handle network errors
-        throw new HttpException_1.HttpException(types_1.HttpStatus.NULL, e?.message ?? exports.DEFAULT_ERROR_MESSAGE, {
-            body,
-            query,
-            params,
-            endpoint,
-        });
-    }
-    const contentType = response.headers.get('content-type');
-    if (contentType?.startsWith('application/json')) {
-        return defaultHandler(response);
-    }
-    if (contentType?.startsWith('text/plain') && contentType.includes('x-format=jsonlines')) {
-        return defaultStreamHandler(response);
-    }
-    return response;
-};
-exports.fetcher = fetcher;
+    return newFetcher;
+}
+/**
+ * Default fetcher implementation for client requests.
+ * @see https://vovk.dev/imports
+ */
+export const fetcher = createFetcher();

package/dist/client/progressive.d.ts

@@ -0,0 +1,15 @@
+import type { VovkStreamAsyncIterable } from '../types/client.js';
+import type { VovkYieldType } from '../types/inference.js';
+import type { KnownAny } from '../types/utils.js';
+type UnionToIntersection<U> = (U extends KnownAny ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type PromisifyProperties<T> = {
+    [K in keyof T]: Promise<T[K]>;
+};
+type TransformUnionToPromises<T> = PromisifyProperties<UnionToIntersection<T>>;
+/**
+ * Implements progressive fetching by returning a proxy object where each property is a promise
+ * that resolves when the corresponding value is available from the stream.
+ * @see https://vovk.dev/jsonlines
+ */
+export declare function progressive<T extends (...args: KnownAny[]) => Promise<VovkStreamAsyncIterable<KnownAny>>>(fn: T, ...args: undefined extends Parameters<T>[0] ? [arg?: Parameters<T>[0]] : [arg: Parameters<T>[0]]): TransformUnionToPromises<VovkYieldType<T>>;
+export {};

package/dist/client/progressive.js

@@ -0,0 +1,56 @@
+/**
+ * Implements progressive fetching by returning a proxy object where each property is a promise
+ * that resolves when the corresponding value is available from the stream.
+ * @see https://vovk.dev/jsonlines
+ */
+export function progressive(fn, ...args) {
+    const [arg] = args;
+    const reg = {};
+    void fn(arg)
+        .then(async (result) => {
+        for await (const item of result) {
+            for (const [key, value] of Object.entries(item)) {
+                if (key in reg) {
+                    if (!reg[key].isSettled) {
+                        reg[key].isSettled = true;
+                        reg[key].resolve(value);
+                    }
+                }
+                else {
+                    const { promise, resolve, reject } = Promise.withResolvers();
+                    reg[key] = { resolve, reject, promise, isSettled: true };
+                    reg[key].resolve(value);
+                }
+            }
+        }
+        Object.keys(reg).forEach((key) => {
+            if (reg[key].isSettled)
+                return;
+            reg[key].isSettled = true;
+            reg[key].reject(new Error(`The connection was closed without sending a value for "${key}"`));
+        });
+        return result;
+    })
+        .catch((error) => {
+        Object.keys(reg).forEach((key) => {
+            if (reg[key].isSettled)
+                return;
+            reg[key].isSettled = true;
+            reg[key].reject(error);
+        });
+        return error;
+    });
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (prop in reg) {
+                return reg[prop].promise;
+            }
+            const { promise, resolve, reject } = Promise.withResolvers();
+            reg[prop] = { resolve, reject, promise, isSettled: false };
+            return promise;
+        },
+        ownKeys: () => {
+            throw new Error('Getting own keys is not possible as they are dynamically created');
+        },
+    });
+}

package/dist/{utils → client}/serializeQuery.d.ts

@@ -1,4 +1,4 @@
-import type { KnownAny } from '../types';
+import type { KnownAny } from '../types/utils.js';
 /**
  * Serialize a nested object (including arrays, arrays of objects, etc.)
  * into a bracket-based query string.
@@ -10,4 +10,4 @@ import type { KnownAny } from '../types';
  * @param obj - The input object to be serialized
  * @returns   - A bracket-based query string (without leading "?")
  */
-export default function serializeQuery(obj: Record<string, KnownAny>): string;
+export declare function serializeQuery(obj: Record<string, KnownAny>): string;