vovk 3.5.1 → 4.0.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to `vovk` are documented here. This file is the canonical record: noteworthy changes only, one short line each, linked to the pull request or commit that made them. GitHub Releases are not used.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 4.0.0-beta.0 - unreleased
+
+A cleanup major: removals and renames, no new APIs.
+
+### Removed
+
+- `toolsByName`: `deriveTools` returns the tools array only ([#28](https://github.com/finom/vovk/pull/28))
+- `VovkTool`, `createTool`, `parameters`, `type` and `inputSchemas`: replaced by the `StandardToolV0` convention ([#27](https://github.com/finom/vovk/pull/27))
+- `vovk/createRPC` and `vovk/createValidateOnClient` subpath aliases: use `vovk/create-rpc` and `vovk/create-validate-on-client` ([b7dc4b2](https://github.com/finom/vovk/commit/b7dc4b2a))
+- Dead `nestjs-operation-id` name-strategy literals ([3f84c25](https://github.com/finom/vovk/commit/3f84c253))
+
+### Changed
+
+- `HttpStatus.TOO_MANY_TRequestS` renamed to `TOO_MANY_REQUESTS` ([c739e4b](https://github.com/finom/vovk/commit/c739e4bc))
+- Production error responses carry no internal detail; `onError` still receives the full error ([d0be248](https://github.com/finom/vovk/commit/d0be2482), [419cf7f](https://github.com/finom/vovk/commit/419cf7f6))
+- A declared `contentType` is enforced even without a body schema; disabling body validation opts out ([444644b](https://github.com/finom/vovk/commit/444644b8), [27edb95](https://github.com/finom/vovk/commit/27edb95e))
+
+### Fixed
+
+- Stacked decorators all run: HTTP routes dispatch through the outermost wrapper ([18ce506](https://github.com/finom/vovk/commit/18ce5063))
+- Prototype members such as `constructor` no longer resolve as route handlers ([8fa67bb](https://github.com/finom/vovk/commit/8fa67bb0))
+- The route match cache is scoped to its handlers map, fixing cross-method poisoning ([6db95ff](https://github.com/finom/vovk/commit/6db95ff5))
+- Path params are percent-encoded, and an encoded slash stays inside its param ([d2d9046](https://github.com/finom/vovk/commit/d2d90464), [0cb5aa4](https://github.com/finom/vovk/commit/0cb5aa40))
+- Chained `withDefaults` deep-merges instead of replacing nested options ([4f53fc7](https://github.com/finom/vovk/commit/4f53fc78))
+- `Headers` instances and `init.signal` survive RPC options ([fc61920](https://github.com/finom/vovk/commit/fc619204))
+- Streaming: mid-stream errors reach `onError`, the error envelope stays out of `onIterate`, an abandoned iterator releases the stream ([b440310](https://github.com/finom/vovk/commit/b4403106), [06e99fa](https://github.com/finom/vovk/commit/06e99faa), [06b9c00](https://github.com/finom/vovk/commit/06b9c007))
+- Falsy handler output (`false`, `0`, `''`, `null`) is accepted when an output schema is set ([dc8c6a3](https://github.com/finom/vovk/commit/dc8c6a38))
+- Derived tools materialize `Response` and generator results, and failures reach `onError` ([7b7f1b8](https://github.com/finom/vovk/commit/7b7f1b87), [ff18ee5](https://github.com/finom/vovk/commit/ff18ee5d))
+- Derived path/query parameters and `components.schemas` merge with user-declared ones ([d86bae0](https://github.com/finom/vovk/commit/d86bae0b), [6a174ac](https://github.com/finom/vovk/commit/6a174ac1))
+- Malformed `x-meta` responds 400, `x-meta` is allowed in default CORS headers, non-ASCII meta is escaped ([5327a32](https://github.com/finom/vovk/commit/5327a327), [e34acae](https://github.com/finom/vovk/commit/e34acaea), [be58398](https://github.com/finom/vovk/commit/be583983))
+
+### Security
+
+- `x-tsType` is stripped from third-party OpenAPI specs on ingestion; a crafted value could inject executable code into the generated client ([c5e63cd](https://github.com/finom/vovk/commit/c5e63cd7))
+- Query parsing hardened: prototype-polluting keys dropped, pairs split at the first `=`, a large index cannot size a huge array ([46aaadf](https://github.com/finom/vovk/commit/46aaadf7), [03522f3](https://github.com/finom/vovk/commit/03522f3f), [14bbc17](https://github.com/finom/vovk/commit/14bbc179))
+- A non-index bracket key such as `?a[-1]=x` no longer discards the value; it becomes an object key, matching `qs`
+
+### Upgrading from 3.x
+
+1. Replace `HttpStatus.TOO_MANY_TRequestS` with `HttpStatus.TOO_MANY_REQUESTS`.
+2. Replace imports from `vovk/createRPC` and `vovk/createValidateOnClient` with `vovk/create-rpc` and `vovk/create-validate-on-client`.
+3. If you destructured `toolsByName` from `deriveTools`, build the map yourself from the returned array.
+4. If you used `createTool` / `VovkTool` / `inputSchemas`, move to the `StandardToolV0` shape.
+5. If you relied on error responses carrying internal messages in production, read them from `onError` instead.
+6. The composed client no longer comes from the `vovk-client` package; see the `vovk-cli` changelog.
+
+## 3.7.0 - 2026-06-11
+
+- Kebab-case file naming and subpath exports across packages; camelCase aliases such as `vovk/createRPC` kept for compatibility ([#23](https://github.com/finom/vovk/pull/23))
+
+## 3.5.0 - 2026-06-10
+
+- `openAPIMixin.filterOperations` and `pruneComponents`: generate only the operations you call and drop components nothing references ([#22](https://github.com/finom/vovk/pull/22))
+
+## 3.4.0 - 2026-05-30
+
+- Merged `inputSchema`, one Standard Schema for body, query and params; per-slot `inputSchemas` deprecated ([#16](https://github.com/finom/vovk/pull/16))
+- `VovkTool` follows the `standard-tool` convention, and `execute` takes per-call `meta` ([#18](https://github.com/finom/vovk/pull/18), [#19](https://github.com/finom/vovk/pull/19), [#20](https://github.com/finom/vovk/pull/20))
+
+## 3.2.2 - 2026-04-03
+
+- Fetcher `onSuccess`/`onError` assignable after initialization ([#3](https://github.com/finom/vovk/pull/3)), the `VovkInput` type ([#1](https://github.com/finom/vovk/pull/1)), and `.fn` LPC calls inside Next.js server actions ([#2](https://github.com/finom/vovk/pull/2))
+
+## 3.1.3 - 2026-03-21
+
+- `decorate()` and `static prefix`: controllers and procedures without decorator syntax ([docs](https://vovk.dev/decorator-overview))
+
+Earlier history predates this changelog; see the git tags.

package/dist/client/create-rpc.d.ts

@@ -0,0 +1,13 @@
+import type { VovkHandlerSchema } from '../internal.js';
+import type { VovkFetcher, VovkFetcherOptions, VovkRPCModule } from '../types/client.js';
+import type { VovkRequest } from '../types/request.js';
+import type { KnownAny } from '../types/utils.js';
+import type { CombinedSpec } from '../types/validation.js';
+export type { CombinedSpec, VovkHandlerSchema, VovkRequest };
+/**
+ * Creates a client-side RPC module for interacting with server-side controllers.
+ * @see https://vovk.dev/typescript
+ */
+export declare const createRPC: <T, OPTS extends Record<string, KnownAny> = Record<string, never>>(givenSchema: unknown, segmentName: string, rpcModuleName: string, givenFetcher?: VovkFetcher<OPTS> | Promise<{
+    fetcher: VovkFetcher<OPTS>;
+}>, options?: VovkFetcherOptions<OPTS>) => VovkRPCModule<T, OPTS>;

package/dist/client/create-rpc.js

@@ -0,0 +1,145 @@
+import { deepExtend } from '../utils/deep-extend.js';
+import { defaultHandler } from './default-handler.js';
+import { defaultStreamHandler } from './default-stream-handler.js';
+import { fetcher as defaultFetcher } from './fetcher.js';
+import { serializeQuery } from './serialize-query.js';
+const trimPath = (path) => path.trim().replace(/^\/|\/$/g, '');
+const getHandlerPath = (endpoint, params, query) => {
+    let result = endpoint;
+    const queryStr = query ? serializeQuery(query) : null;
+    for (const [key, value] of Object.entries(params ?? {})) {
+        // encode so a value stays one path segment, the callback form also keeps $& from being a replacement pattern
+        result = result.replaceAll(`{${key}}`, () => encodeURIComponent(String(value)));
+    }
+    return `${result}${queryStr ? `?${queryStr}` : ''}`;
+};
+/**
+ * Creates a client-side RPC module for interacting with server-side controllers.
+ * @see https://vovk.dev/typescript
+ */
+export const createRPC = (givenSchema, segmentName, rpcModuleName, givenFetcher, options) => {
+    const schema = givenSchema; // fixes incompatibilities with JSON module
+    // fetcher ??= defaultFetcher as NonNullable<typeof fetcher>;
+    const segmentNamePath = options?.segmentNameOverride ?? segmentName;
+    const segmentSchema = schema.segments[segmentName];
+    if (!segmentSchema)
+        throw new Error(`Unable to create RPC module. Segment schema is missing for segment "${segmentName}".`);
+    let controllerSchema = schema.segments[segmentName]?.controllers[rpcModuleName];
+    const client = {};
+    if (!controllerSchema) {
+        console.warn(`🐺 Unable to create RPC module. Controller schema is missing for module "${rpcModuleName}" from segment "${segmentName}". Assuming that schema is not ready yet and a segment is importing an uncompiled RPC module.`);
+        controllerSchema = {
+            rpcModuleName,
+            prefix: '',
+            handlers: {},
+        };
+    }
+    const controllerPrefix = trimPath(controllerSchema.prefix ?? '');
+    const forceApiRoot = segmentSchema.forceApiRoot;
+    const configRootEntry = schema.meta?.config?.rootEntry;
+    const originalApiRoot = forceApiRoot ?? options?.apiRoot ?? (configRootEntry ? `/${configRootEntry}` : '/api');
+    for (const [staticMethodName, handlerSchema] of Object.entries(controllerSchema.handlers ?? {})) {
+        const { path, httpMethod, validation } = handlerSchema;
+        const getURL = ({ apiRoot, params, query } = {}) => {
+            apiRoot = apiRoot ?? originalApiRoot;
+            const endpoint = [
+                apiRoot.startsWith('http://') || apiRoot.startsWith('https://') || apiRoot.startsWith('/') ? '' : '/',
+                apiRoot,
+                forceApiRoot ? '' : segmentNamePath,
+                getHandlerPath([controllerPrefix, path].filter(Boolean).join('/'), params, query),
+            ]
+                .filter(Boolean)
+                .join('/')
+                .replace(/([^:])\/+/g, '$1/'); // replace // by / but not for protocols (http://, https://)
+            return endpoint;
+        };
+        const handler = (async (input = {}) => {
+            const optionsResolvedValidateOnClient = options?.validateOnClient instanceof Promise
+                ? (await options?.validateOnClient)?.validateOnClient
+                : options?.validateOnClient;
+            const fetcher = givenFetcher instanceof Promise
+                ? (await givenFetcher).fetcher
+                : (givenFetcher ?? defaultFetcher);
+            const validate = async (validationInput, { endpoint, }) => {
+                const validateOnClient = input.validateOnClient ?? optionsResolvedValidateOnClient;
+                if (validateOnClient && validation) {
+                    if (typeof validateOnClient !== 'function') {
+                        throw new Error('validateOnClient must be a function');
+                    }
+                    return ((await validateOnClient({ ...validationInput }, validation, { fullSchema: schema, endpoint })) ??
+                        validationInput);
+                }
+                return validationInput;
+            };
+            const internalOptions = {
+                name: staticMethodName,
+                httpMethod: httpMethod,
+                getURL,
+                validate,
+                defaultHandler,
+                defaultStreamHandler,
+                schema: handlerSchema,
+            };
+            let processedBody = input.body;
+            if ((validation?.body?.['x-contentType']?.includes('multipart/form-data') ||
+                validation?.body?.['x-contentType']?.includes('application/x-www-form-urlencoded')) &&
+                input.body &&
+                !(input.body instanceof FormData || input.body instanceof URLSearchParams || input.body instanceof Blob)) {
+                processedBody = new FormData();
+                for (const [key, value] of Object.entries(input.body)) {
+                    if (Array.isArray(value)) {
+                        value.forEach((item) => {
+                            processedBody.append(key, item);
+                        });
+                    }
+                    else {
+                        processedBody.append(key, value);
+                    }
+                }
+            }
+            else {
+                processedBody = input.body;
+            }
+            const internalInput = {
+                ...deepExtend({}, options, {
+                    validateOnClient: optionsResolvedValidateOnClient,
+                }, input),
+                body: processedBody ?? null,
+                query: input.query ?? {},
+                params: input.params ?? {},
+            };
+            if (!fetcher)
+                throw new Error('Fetcher is not provided');
+            const [respData, resp] = await fetcher(internalOptions, internalInput);
+            return input.transform ? input.transform(respData, resp) : respData;
+        });
+        // TODO use Object.freeze, Object.seal or Object.defineProperty to avoid mutation
+        handler.schema = handlerSchema;
+        handler.controllerSchema = controllerSchema;
+        handler.segmentSchema = segmentSchema;
+        handler.fullSchema = schema;
+        handler.isRPC = true;
+        handler.apiRoot = originalApiRoot;
+        handler.getURL = getURL;
+        handler.queryKey = (key) => [
+            handler.segmentSchema.segmentName,
+            handler.controllerSchema.prefix ?? '',
+            handler.controllerSchema.rpcModuleName,
+            handler.schema.path,
+            handler.schema.httpMethod,
+            ...(key ?? []),
+        ];
+        // @ts-expect-error TODO
+        client[staticMethodName] = handler;
+    }
+    Object.defineProperty(client, 'withDefaults', {
+        value: (newOptions) => {
+            // deep merge to match per-call option merging, so chained defaults don't clobber nested keys
+            return createRPC(schema, segmentName, rpcModuleName, givenFetcher, deepExtend({}, options, newOptions));
+        },
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return client;
+};

package/dist/client/default-handler.d.ts

@@ -0,0 +1,6 @@
+import type { VovkHandlerSchema } from '../types/core.js';
+export declare const DEFAULT_ERROR_MESSAGE = "Unknown error at defaultHandler";
+export declare const defaultHandler: ({ response, schema }: {
+    response: Response;
+    schema: VovkHandlerSchema;
+}) => Promise<unknown>;

package/dist/client/default-handler.js

@@ -0,0 +1,25 @@
+import { HttpException } from '../core/http-exception.js';
+export const DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultHandler';
+// Helper function to get a value from an object using dot notation path
+const getNestedValue = (obj, path) => {
+    return path.split('.').reduce((o, key) => (o && typeof o === 'object' ? o[key] : undefined), obj);
+};
+export const defaultHandler = async ({ response, schema }) => {
+    let result;
+    try {
+        result = await response.json();
+    }
+    catch (e) {
+        // handle parsing errors
+        throw new HttpException(response.status, e?.message ?? DEFAULT_ERROR_MESSAGE);
+    }
+    if (!response.ok) {
+        const errorKey = schema.operationObject && 'x-errorMessageKey' in schema.operationObject
+            ? schema.operationObject['x-errorMessageKey']
+            : 'message';
+        // handle server errors
+        const errorResponse = result;
+        throw new HttpException(response.status, getNestedValue(errorResponse, errorKey) ?? DEFAULT_ERROR_MESSAGE, errorResponse?.cause ?? JSON.stringify(result));
+    }
+    return result;
+};

package/dist/client/default-stream-handler.d.ts

@@ -0,0 +1,12 @@
+import type { VovkStreamAsyncIterable } from '../types/client.js';
+import '../utils/shim.js';
+export declare const DEFAULT_ERROR_MESSAGE = "An unknown error at the default stream handler";
+/** ReadableStream of JSON Lines to VovkStreamAsyncIterable, reusable outside HTTP contexts. @see https://vovk.dev/jsonlines */
+export declare const readableStreamToAsyncIterable: <T = unknown>({ readableStream, abortController, }: {
+    readableStream: ReadableStream<Uint8Array | string>;
+    abortController?: AbortController;
+}) => Omit<VovkStreamAsyncIterable<T>, "abortController" | "status">;
+export declare const defaultStreamHandler: ({ response, abortController, }: {
+    response: Response;
+    abortController: AbortController;
+}) => VovkStreamAsyncIterable<unknown>;

package/dist/client/default-stream-handler.js

@@ -0,0 +1,290 @@
+import { HttpException } from '../core/http-exception.js';
+import { HttpStatus } from '../types/enums.js';
+import '../utils/shim.js';
+export const DEFAULT_ERROR_MESSAGE = 'An unknown error at the default stream handler';
+/** ReadableStream of JSON Lines to VovkStreamAsyncIterable, reusable outside 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;
+    // consumers currently iterating, the last one to leave early releases the connection
+    let activeIterators = 0;
+    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) {
+                // the error envelope is a control message, not data, subscribers must not see it
+                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;
+                }
+                subscribers.forEach((cb) => {
+                    if (!abortController?.signal.aborted)
+                        cb(data, iterationIndex);
+                });
+                iterationIndex++;
+                if (!abortController?.signal.aborted) {
+                    cachedItems.push(data);
+                    notifyWaiters();
+                }
+            }
+            return false;
+        };
+        try {
+            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 (true) {
+                    newlineIdx = buffer.indexOf('\n');
+                    if (newlineIdx === -1)
+                        break;
+                    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);
+            }
+        }
+        finally {
+            streamExhausted = true;
+            notifyWaiters();
+        }
+    };
+    // --- Async iterator ---
+    async function* asyncIterator() {
+        if (!primaryStarted) {
+            primaryStarted = true;
+            void runPrimaryReader();
+        }
+        activeIterators++;
+        let index = 0;
+        try {
+            while (true) {
+                // Check error first
+                if (streamError && index >= errorIndex) {
+                    throw streamError;
+                }
+                // Clean exit on abort without error
+                if (abortController?.signal.aborted && isAbortedWithoutError) {
+                    return;
+                }
+                // Yield from cache if available
+                if (index < cachedItems.length) {
+                    yield cachedItems[index++];
+                    continue;
+                }
+                // Stream finished
+                if (streamExhausted) {
+                    return;
+                }
+                // 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;
+                    }
+                    if (abortController?.signal.aborted && isAbortedWithoutError) {
+                        resolve({ value: undefined, done: true });
+                        return;
+                    }
+                    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;
+            }
+        }
+        finally {
+            activeIterators--;
+            // a consumer that stopped early must release the connection, same as dispose does
+            if (activeIterators === 0 && !streamExhausted)
+                disposeStream('Stream iteration stopped');
+        }
+    }
+    // --- 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 {
+        asPromise,
+        // abortController,
+        [Symbol.asyncIterator]: asyncIterator,
+        [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);
+        },
+    };
+};
+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,5 +1,5 @@
-import { HttpException } from '../core/HttpException.js';
-import type { VovkFetcherOptions, VovkFetcher } from '../types/client.js';
+import { HttpException } from '../core/http-exception.js';
+import type { VovkFetcher, VovkFetcherOptions } 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 };

package/dist/client/fetcher.js

@@ -1,7 +1,48 @@
+import { HttpException } from '../core/http-exception.js';
 import { HttpStatus } from '../types/enums.js';
-import { HttpException } from '../core/HttpException.js';
-import { fileNameToDisposition } from '../utils/fileNameToDisposition.js';
+import { fileNameToDisposition } from '../utils/file-name-to-disposition.js';
 export const DEFAULT_ERROR_MESSAGE = 'Unknown error at default fetcher';
+// header values must be ByteString, escape non-ASCII as \uXXXX which JSON.parse reads natively
+const toAsciiJson = (value) => JSON.stringify(value).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+// invokes emitError once for errors that surface during stream consumption, after the fetcher has returned
+function wrapStreamErrors(stream, emitError) {
+    let emitted = false;
+    const emitOnce = async (error) => {
+        if (emitted)
+            return;
+        emitted = true;
+        await emitError(error);
+    };
+    const getIterator = stream[Symbol.asyncIterator].bind(stream);
+    const asPromise = stream.asPromise.bind(stream);
+    return Object.assign(stream, {
+        [Symbol.asyncIterator]: () => {
+            const iterator = getIterator();
+            return {
+                next: async () => {
+                    try {
+                        return await iterator.next();
+                    }
+                    catch (error) {
+                        await emitOnce(error);
+                        throw error;
+                    }
+                },
+                return: iterator.return?.bind(iterator),
+                throw: iterator.throw?.bind(iterator),
+            };
+        },
+        asPromise: async () => {
+            try {
+                return await asPromise();
+            }
+            catch (error) {
+                await emitOnce(error);
+                throw error;
+            }
+        },
+    });
+}
 /**
  * Creates a customizable fetcher function for client requests.
  * @see https://vovk.dev/imports
@@ -62,7 +103,7 @@ export function createFetcher({ prepareRequestInit, transformResponse, onSuccess
                 accept: 'application/jsonl, application/json',
                 ...(resolvedContentType ? { 'content-type': resolvedContentType } : {}),
                 ...(resolvedFileName ? { 'content-disposition': fileNameToDisposition(resolvedFileName) } : {}),
-                ...(meta ? { 'x-meta': JSON.stringify(meta) } : {}),
+                ...(meta ? { 'x-meta': toAsciiJson(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()) : {};
@@ -87,7 +128,10 @@ export function createFetcher({ prepareRequestInit, transformResponse, onSuccess
                 requestInit.body = JSON.stringify(body);
             }
             const abortController = new AbortController();
-            requestInit.signal = abortController.signal;
+            // keep the internal controller for stream disposal but let a user-provided init.signal abort too
+            requestInit.signal = init?.signal
+                ? AbortSignal.any([abortController.signal, init.signal])
+                : abortController.signal;
             requestInit = prepareRequestInit ? await prepareRequestInit(requestInit, inputOptions) : requestInit;
             try {
                 response = await fetch(endpoint, requestInit);
@@ -103,7 +147,12 @@ export function createFetcher({ prepareRequestInit, transformResponse, onSuccess
             }
             const contentType = interpretAs ?? response.headers.get('content-type');
             if (contentType?.startsWith('application/jsonl')) {
-                respData = defaultStreamHandler({ response, abortController });
+                // route mid-stream errors to onError callbacks, which otherwise never see them
+                respData = wrapStreamErrors(defaultStreamHandler({ response, abortController }), async (error) => {
+                    for (const cb of onErrorCallbacks) {
+                        await cb(error, inputOptions, { response, init: requestInit, respData, schema });
+                    }
+                });
             }
             else if (contentType?.startsWith('application/json')) {
                 respData = await defaultHandler({ response, schema });