vovk 3.0.0-draft.98 → 3.0.0

package/README.md

@@ -1,24 +1,33 @@
-<p align="center"> 
-  <picture>
-    <source width="300" media="(prefers-color-scheme: dark)" srcset="https://vovk.dev/vovk-logo-white.svg">
-    <source width="300" media="(prefers-color-scheme: light)" srcset="https://vovk.dev/vovk-logo.svg">
-    <img width="300" alt="vovk" src="https://vovk.dev/vovk-logo.svg">
-  </picture><br>
-  <strong>REST + RPC = ♥️</strong>
-</p>
-
 <p align="center">
-  Back-end meta-framework for <a href="https://nextjs.org/docs/app">Next.js</a>
+  <a href="https://vovk.dev">
+    <picture>
+      <source width="300" media="(prefers-color-scheme: dark)" srcset="https://vovk.dev/vovk-logo-white.svg">
+      <source width="300" media="(prefers-color-scheme: light)" srcset="https://vovk.dev/vovk-logo.svg">
+      <img width="300" alt="vovk" src="https://vovk.dev/vovk-logo.svg">
+    </picture>
+  </a>
+  <br>
+  <strong>Back-end Framework for Next.js App Router</strong>
+  <br />
+  <a href="https://vovk.dev/">Documentation</a>
+  &nbsp;&nbsp;
+  <a href="https://vovk.dev/quick-install">Quick Start</a>
+  &nbsp;&nbsp;
+  <a href="https://vovk.dev/performance">Performance</a>
 </p>
 
 ---
 
 ## vovk [![npm version](https://badge.fury.io/js/vovk.svg)](https://www.npmjs.com/package/vovk)
 
-The main library with [zero dependencies](https://bundlephobia.com/result?p=vovk) that's going to be used in production. It provides a wrapper for Next.js API routes, internal RPC API, utilities and types.
+The Vovk.ts runtime library with [100% self-composition](https://bundlephobia.com/result?p=vovk). It provides a wrapper for Next.js API routes, client-side tooling, utilities and types.
 
 ```sh
-npm install vovk
+npm install vovk openapi3-ts
 ```
 
-For more information, please visit the [getting started guide](https://vovk.dev/getting-started) or check out the [Vovk.ts examples](https://vovk-examples.vercel.app/).
+## Links
+
+- Docs: https://vovk.dev
+- Quick Start: https://vovk.dev/quick-install
+- Manual install: https://vovk.dev/manual-install

package/bin/index.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+
+console.warn(
+  `\x1b[33m🐺 Vovk CLI requires vovk-cli package. Running npx vovk-cli@latest ${process.argv.slice(2).join(' ')} instead.\x1b[0m`
+);
+
+spawn('npx', ['vovk-cli@latest', ...process.argv.slice(2)], { stdio: 'inherit' }).on('exit', (code) => {
+  process.exit(code);
+});

package/dist/client/createRPC.d.ts

@@ -1,3 +1,13 @@
-import type { KnownAny, VovkFullSchema } from '../types';
-import type { VovkClientOptions, VovkClient, VovkDefaultFetcherOptions } from './types';
-export declare const createRPC: <T, OPTS extends Record<string, KnownAny> = VovkDefaultFetcherOptions>(fullSchema: VovkFullSchema, segmentName: string, controllerName: string, options?: VovkClientOptions<OPTS>) => VovkClient<T, OPTS>;
+import type { VovkHandlerSchema } from '../internal.js';
+import type { VovkRequest } from '../types/request.js';
+import type { VovkRPCModule, VovkFetcher, VovkFetcherOptions } from '../types/client.js';
+import type { CombinedSpec } from '../types/validation.js';
+import type { KnownAny } from '../types/utils.js';
+export type { VovkHandlerSchema, VovkRequest, CombinedSpec };
+/**
+ * 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/createRPC.js

@@ -1,85 +1,147 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRPC = void 0;
-const fetcher_1 = require("./fetcher");
-const defaultHandler_1 = require("./defaultHandler");
-const defaultStreamHandler_1 = require("./defaultStreamHandler");
-const serializeQuery_1 = __importDefault(require("../utils/serializeQuery"));
+import { fetcher as defaultFetcher } from './fetcher.js';
+import { defaultHandler } from './defaultHandler.js';
+import { defaultStreamHandler } from './defaultStreamHandler.js';
+import { serializeQuery } from './serializeQuery.js';
+import { deepExtend } from '../utils/deepExtend.js';
 const trimPath = (path) => path.trim().replace(/^\/|\/$/g, '');
 const getHandlerPath = (endpoint, params, query) => {
     let result = endpoint;
-    const queryStr = query ? (0, serializeQuery_1.default)(query) : null;
+    const queryStr = query ? serializeQuery(query) : null;
     for (const [key, value] of Object.entries(params ?? {})) {
-        result = result.replace(`:${key}`, value);
+        result = result.replace(`{${key}}`, value);
     }
-    return `${result}${queryStr ? '?' : ''}${queryStr}`;
+    return `${result}${queryStr ? `?${queryStr}` : ''}`;
 };
-const createRPC = (fullSchema, segmentName, controllerName, options) => {
-    const segmentSchema = fullSchema.segments[segmentName];
+/**
+ * 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 object. Segment schema is missing. Check client template.`);
-    const controllerSchema = fullSchema.segments[segmentName]?.controllers[controllerName];
+        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)
-        throw new Error(`Unable to create RPC object. Controller schema is missing. Check client template.`);
+    if (!controllerSchema) {
+        // eslint-disable-next-line no-console
+        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 { fetcher: settingsFetcher = fetcher_1.fetcher } = options ?? {};
-    for (const [staticMethodName, handlerSchema] of Object.entries(controllerSchema.handlers)) {
+    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 getEndpoint = ({ apiRoot, params, query, }) => {
-            const mainPrefix = (apiRoot.startsWith('http://') || apiRoot.startsWith('https://') || apiRoot.startsWith('/') ? '' : '/') +
-                (apiRoot.endsWith('/') ? apiRoot : `${apiRoot}/`) +
-                (segmentName ? `${segmentName}/` : '');
-            return mainPrefix + getHandlerPath([controllerPrefix, path].filter(Boolean).join('/'), params, query);
+        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 = (input = {}) => {
-            const fetcher = input.fetcher ?? settingsFetcher;
-            const validate = async ({ body, query, params, endpoint, }) => {
-                const validateOnClient = input.validateOnClient ?? options?.validateOnClient;
-                if (validateOnClient) {
+        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');
                     }
-                    await validateOnClient({ body, query, params, endpoint }, validation ?? {}, fullSchema);
+                    return ((await validateOnClient({ ...validationInput }, validation, { fullSchema: schema, endpoint })) ??
+                        validationInput);
                 }
+                return validationInput;
             };
             const internalOptions = {
                 name: staticMethodName,
                 httpMethod: httpMethod,
-                getEndpoint,
+                getURL,
                 validate,
-                defaultHandler: defaultHandler_1.defaultHandler,
-                defaultStreamHandler: defaultStreamHandler_1.defaultStreamHandler,
+                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 (value instanceof Array) {
+                        value.forEach((item) => {
+                            processedBody.append(key, item);
+                        });
+                    }
+                    else {
+                        processedBody.append(key, value);
+                    }
+                }
+            }
+            else {
+                processedBody = input.body;
+            }
             const internalInput = {
-                ...options?.defaultOptions,
-                ...input,
-                body: input.body ?? null,
+                ...deepExtend({}, options, {
+                    validateOnClient: optionsResolvedValidateOnClient,
+                }, input),
+                body: processedBody ?? null,
                 query: input.query ?? {},
                 params: input.params ?? {},
-                // TS workaround
-                fetcher: undefined,
-                validateOnClient: undefined,
             };
-            delete internalInput.fetcher;
-            delete internalInput.validateOnClient;
             if (!fetcher)
                 throw new Error('Fetcher is not provided');
-            const fetcherPromise = fetcher(internalOptions, internalInput);
-            if (!(fetcherPromise instanceof Promise))
-                return Promise.resolve(fetcherPromise);
-            return input.transform ? fetcherPromise.then(input.transform) : fetcherPromise;
-        };
+            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 = fullSchema;
+        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) => {
+            return createRPC(schema, segmentName, rpcModuleName, givenFetcher, {
+                ...options,
+                ...newOptions,
+            });
+        },
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
     return client;
 };
-exports.createRPC = createRPC;

package/dist/client/defaultHandler.d.ts

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

package/dist/client/defaultHandler.js

@@ -1,22 +1,25 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultHandler = exports.DEFAULT_ERROR_MESSAGE = void 0;
-const HttpException_1 = require("../HttpException");
-exports.DEFAULT_ERROR_MESSAGE = 'Unknown error at defaultHandler';
-const defaultHandler = async (response) => {
+import { HttpException } from '../core/HttpException.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_1.HttpException(response.status, e?.message ?? exports.DEFAULT_ERROR_MESSAGE);
+        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_1.HttpException(response.status, errorResponse?.message ?? exports.DEFAULT_ERROR_MESSAGE, errorResponse?.cause);
+        throw new HttpException(response.status, getNestedValue(errorResponse, errorKey) ?? DEFAULT_ERROR_MESSAGE, errorResponse?.cause ?? JSON.stringify(result));
     }
     return result;
 };
-exports.defaultHandler = defaultHandler;

package/dist/client/defaultStreamHandler.d.ts

@@ -1,4 +1,16 @@
-import type { VovkStreamAsyncIterable } from './types';
-import '../utils/shim';
-export declare const DEFAULT_ERROR_MESSAGE = "Unknown error at defaultStreamHandler";
-export declare const defaultStreamHandler: (response: Response) => Promise<VovkStreamAsyncIterable<unknown>>;
+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";
+/**
+ * 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 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>;