@faasjs/react 8.0.0-beta.27 → 8.0.0-beta.29

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { Component, cloneElement, createContext, forwardRef, useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/generateId/index.ts
+//#region src/generate-id/index.ts
 /**
 * Generate a random identifier with an optional prefix.
 *
@@ -23,7 +23,7 @@ function generateId(prefix = "", length = 18) {
 	return `${prefix}${Date.now().toString(36).padStart(8, "0")}${Math.random().toString(36).substring(2, length - 6).padEnd(length - 8, "0")}`;
 }
 //#endregion
-//#region src/browser/index.ts
+//#region src/browser/response.ts
 /**
 * Wrapper class for HTTP responses from FaasJS functions.
 *
@@ -31,113 +31,6 @@ function generateId(prefix = "", length = 18) {
 * body, and parsed data. Automatically handles JSON serialization and status code defaults.
 *
 * @template T - The type of the data property for type-safe response handling
-*
-* @property {number} status - The HTTP status code of the response.
-*   Defaults to 200 if data or body is provided, 204 if neither is present.
-* @property {ResponseHeaders} headers - The response headers as a key-value object.
-*   Empty object if no headers were provided.
-* @property {any} body - The raw response body as a string or object.
-*   If data is provided without body, body is automatically set to JSON.stringify(data).
-* @property {T} [data] - The parsed JSON data from the response.
-*   Optional property that contains the response payload when JSON is provided.
-*
-* Notes:
-* - status defaults to 200 if data or body is present, 204 otherwise
-* - body is automatically populated from data if not explicitly provided
-* - headers defaults to an empty object if not provided
-* - Use generic type parameter T for type-safe data access
-* - Commonly used as the return type from client.action() method
-* - Can be used in mock handlers to return structured responses
-* - The data property is optional and may be undefined for responses without data
-*
-* @example Create successful response with data
-* ```ts
-* const response = new Response({
-*   status: 200,
-*   data: {
-*     id: 123,
-*     name: 'John Doe'
-*   }
-* })
-* console.log(response.status) // 200
-* console.log(response.data.name) // 'John Doe'
-* ```
-*
-* @example Create response with type safety
-* ```ts
-* interface User {
-*   id: number
-*   name: string
-*   email: string
-* }
-*
-* const response = new Response<User>({
-*   data: {
-*     id: 123,
-*     name: 'John',
-*     email: 'john@example.com'
-*   }
-* })
-* // TypeScript knows response.data.name is a string
-* ```
-*
-* @example Create response with headers
-* ```ts
-* const response = new Response({
-*   status: 201,
-*   data: { created: true },
-*   headers: {
-*     'Content-Type': 'application/json',
-*     'x-faasjs-request-id': 'req-123',
-*     'X-Cache-Key': 'user-123'
-*   }
-* })
-* ```
-*
-* @example Create response with custom body
-* ```ts
-* const response = new Response({
-*   status: 200,
-*   body: JSON.stringify({ custom: 'format' }),
-*   headers: { 'Content-Type': 'application/json' }
-* })
-* ```
-*
-* @example Create empty response (204 No Content)
-* ```ts
-* const response = new Response()
-* // status: 204, headers: {}, body: undefined, data: undefined
-* ```
-*
-* @example Create error response
-* ```ts
-* const response = new Response({
-*   status: 404,
-*   data: {
-*     error: {
-*       message: 'User not found',
-*       code: 'USER_NOT_FOUND'
-*     }
-*   }
-* })
-* ```
-*
-* @example Use in mock handler
-* ```ts
-* setMock(async (action, params) => {
-*   if (action === 'user') {
-*     return new Response({
-*       status: 200,
-*       data: { id: params.id, name: 'Mock User' }
-*     })
-*   }
-*   return new Response({ status: 404, data: { error: 'Not found' } })
-* })
-* ```
-*
-* @see {@link ResponseProps} for response property type.
-* @see {@link ResponseError} for error response handling.
-* @see {@link FaasBrowserClient.action} for method returning Response.
 */
 var Response = class {
 	/**
@@ -158,13 +51,6 @@ var Response = class {
 	data;
 	/**
 	* Create a wrapped response object.
-	*
-	* @param {ResponseProps<T>} [props] - Response properties including status, headers, body, and data.
-	* @param {number} [props.status] - HTTP status code. Defaults to `200` when `data` or `body` exists, otherwise `204`.
-	* @param {ResponseHeaders} [props.headers] - Response headers keyed by header name.
-	* @param {any} [props.body] - Raw response body to expose without additional parsing.
-	* @param {T} [props.data] - Parsed response payload to expose on `response.data`.
-	* @returns {Response<T>} Wrapped response instance.
 	*/
 	constructor(props = {}) {
 		this.status = props.status || (props.data || props.body ? 200 : 204);
@@ -179,96 +65,6 @@ var Response = class {
 *
 * Extends the built-in Error class to provide additional information about failed requests,
 * including HTTP status code, response headers, response body, and the original error.
-*
-* @augments Error
-*
-* @property {number} status - The HTTP status code of the failed response. Defaults to 500 if not provided.
-* @property {ResponseHeaders} headers - The response headers from the failed request.
-* @property {any} body - The response body containing error details or the original error if available.
-* @property {Error} [originalError] - The original Error object if this ResponseError was created from another Error.
-*
-* @example Basic error with message
-* ```ts
-* throw new ResponseError('User not found')
-* // or inside action method:
-* catch (error) {
-*   throw new ResponseError(error.message)
-* }
-* ```
-*
-* @example Error from existing Error
-* ```ts
-* try {
-*   await someOperation()
-* } catch (error) {
-*   throw new ResponseError(error, {
-*     status: 500,
-*     headers: { 'X-Error-Type': 'internal' }
-*   })
-* }
-* ```
-*
-* @example Error with complete response details
-* ```ts
-* throw new ResponseError({
-*   message: 'Validation failed',
-*   status: 400,
-*   headers: { 'X-Error-Code': 'VALIDATION_ERROR' },
-*   body: {
-*     error: {
-*       message: 'Validation failed',
-*       fields: ['email', 'password']
-*     }
-*   }
-* })
-* ```
-*
-* @example Handling ResponseError in client
-* ```ts
-* try {
-*   const response = await client.action('user', { id: 123 })
-*   console.log(response.data)
-* } catch (error) {
-*   if (error instanceof ResponseError) {
-*     console.error(`Request failed: ${error.message}`)
-*     console.error(`Status: ${error.status}`)
-*     if (error.body) {
-*       console.error('Error details:', error.body)
-*     }
-*     if (error.headers['x-faasjs-request-id']) {
-*       console.error('Request ID:', error.headers['x-faasjs-request-id'])
-*     }
-*   }
-* }
-* ```
-*
-* @example Throwing ResponseError from mock
-* ```ts
-* setMock(async (action, params) => {
-*   if (action === 'login') {
-*     if (!params.email || !params.password) {
-*       throw new ResponseError({
-*         message: 'Email and password are required',
-*         status: 400,
-*         body: { error: 'missing_fields' }
-*       })
-*     }
-*     return { data: { token: 'abc123' } }
-*   }
-* })
-* ```
-*
-* Notes:
-* - ResponseError is automatically thrown by the action method when the server returns an error (status >= 400)
-* - The error message from server responses is extracted from body.error.message if available
-* - When created from an Error object, the original error is preserved in the originalError property
-* - The status property defaults to 500 if not explicitly provided
-* - Use instanceof ResponseError to distinguish FaasJS errors from other JavaScript errors
-* - The body property can contain structured error information from the server response
-*
-* @see {@link FaasBrowserClient.action} for how ResponseError is thrown in requests.
-* @see {@link ResponseProps} for the structure of response data.
-* @see {@link setMock} for mocking errors in tests.
 */
 var ResponseError = class extends Error {
 	/**
@@ -306,127 +102,15 @@ var ResponseError = class extends Error {
 		if (props.originalError) this.originalError = props.originalError;
 	}
 };
+//#endregion
+//#region src/browser/mock.ts
 let mock = null;
 /**
 * Set the global mock handler used by all {@link FaasBrowserClient} instances.
-*
-* @param {MockHandler | ResponseProps | Response | null | undefined} handler - Mock handler, can be:
-*   - MockHandler function: receives (action, params, options) and returns response data
-*   - ResponseProps object: static response data
-*   - Response instance: pre-configured Response object
-*   - null or undefined: clear mock
-*
-* @example Reset in Vitest shared setup
-* ```ts
-* import { afterEach } from 'vitest'
-*
-* afterEach(() => {
-*   setMock(null)
-* })
-* ```
-*
-* @example Use ResponseProps object
-* ```ts
-* setMock({
-*   data: { name: 'FaasJS' },
-* })
-*
-* setMock({
-*   status: 500,
-*   data: { message: 'Internal Server Error' },
-* })
-* ```
-*
-* @example Use MockHandler function
-* ```ts
-* setMock(async (action) => {
-*   if (action === '/pages/users/get') {
-*     return { data: { id: 1, name: 'FaasJS' } }
-*   }
-*
-*   return { status: 404, data: { message: 'Not Found' } }
-* })
-*
-* const response = await client.action('/pages/users/get')
-* ```
-*
-* @example Branch by action and params
-* ```ts
-* setMock(async (action, params) => {
-*   if (action === '/pages/users/get' && params?.id === 1) {
-*     return { data: { id: 1, name: 'Admin' } }
-*   }
-*
-*   if (action === '/pages/users/get' && params?.id === 2) {
-*     return { data: { id: 2, name: 'Editor' } }
-*   }
-*
-*   return { status: 404, data: { message: 'User not found' } }
-* })
-* ```
-*
-* @example Use Response instance
-* ```ts
-* setMock(new Response({
-*   status: 200,
-*   data: { result: 'success' }
-* }))
-* ```
-*
-* @example Streaming response
-* ```ts
-* setMock({
-*   body: new ReadableStream({
-*     start(controller) {
-*       controller.enqueue(new TextEncoder().encode('hello'))
-*       controller.enqueue(new TextEncoder().encode(' world'))
-*       controller.close()
-*     },
-*   }),
-* })
-* ```
-*
-* @example Clear mock
-* ```ts
-* setMock(null)
-* ```
-*
-* @example Handle errors
-* ```ts
-* setMock(async () => {
-*   throw new Error('Internal error')
-* })
-* // This will reject with ResponseError
-* ```
 */
 function setMock(handler) {
 	mock = handler;
 }
-function buildActionUrl(action, baseUrl, options, requestId) {
-	return `${(options?.baseUrl || baseUrl) + action.toLowerCase()}?_=${requestId}`;
-}
-function buildActionOptions(defaultOptions, options, params, requestId) {
-	const resolvedOptions = {
-		method: "POST",
-		headers: { "Content-Type": "application/json; charset=UTF-8" },
-		mode: "cors",
-		credentials: "include",
-		body: JSON.stringify(params),
-		...defaultOptions,
-		...options || Object.create(null)
-	};
-	if (!resolvedOptions.headers["X-FaasJS-Request-Id"] && !resolvedOptions.headers["x-faasjs-request-id"]) resolvedOptions.headers["X-FaasJS-Request-Id"] = requestId;
-	return resolvedOptions;
-}
-async function runBeforeRequest(action, params, options) {
-	if (!options.beforeRequest) return;
-	await options.beforeRequest({
-		action,
-		params,
-		options,
-		headers: options.headers
-	});
-}
 function normalizeMockResponse(response) {
 	if (response instanceof Error) throw new ResponseError(response);
 	if (response instanceof Response) {
@@ -454,10 +138,36 @@ function normalizeMockResponse(response) {
 	return new Response(response || {});
 }
 async function resolveMockResponse(action, params, options) {
-	console.debug(`[FaasJS] Mock request: ${action} %j`, params);
 	if (typeof mock === "function") return normalizeMockResponse(await mock(action, params, options));
 	return normalizeMockResponse(mock);
 }
+//#endregion
+//#region src/browser/helpers.ts
+function buildActionUrl(action, baseUrl, options, requestId) {
+	return `${(options?.baseUrl || baseUrl) + action.toLowerCase()}?_=${requestId}`;
+}
+function buildActionOptions(defaultOptions, options, params, requestId) {
+	const resolvedOptions = {
+		method: "POST",
+		headers: { "Content-Type": "application/json; charset=UTF-8" },
+		mode: "cors",
+		credentials: "include",
+		body: JSON.stringify(params),
+		...defaultOptions,
+		...options || Object.create(null)
+	};
+	if (!resolvedOptions.headers["X-FaasJS-Request-Id"] && !resolvedOptions.headers["x-faasjs-request-id"]) resolvedOptions.headers["X-FaasJS-Request-Id"] = requestId;
+	return resolvedOptions;
+}
+async function runBeforeRequest(action, params, options) {
+	if (!options.beforeRequest) return;
+	await options.beforeRequest({
+		action,
+		params,
+		options,
+		headers: options.headers
+	});
+}
 function toResponseHeaders(headers) {
 	const responseHeaders = {};
 	for (const [key, value] of headers) responseHeaders[key] = value;
@@ -513,74 +223,10 @@ async function parseFetchResponse(response) {
 	if (response.status >= 200 && response.status < 300) return parseSuccessfulResponse(response.status, headers, text);
 	return parseFailedResponse(response.status, headers, text);
 }
+//#endregion
+//#region src/browser/client.ts
 /**
 * Browser client for FaasJS - provides HTTP client functionality for making API requests from web applications.
-*
-* @template PathOrData - Type parameter extending FaasActionUnionType for type-safe requests
-*
-* Features:
-* - Type-safe API requests with TypeScript support
-* - Built-in mock support for testing
-* - Custom request function support
-* - Request/response hooks (beforeRequest)
-* - Automatic error handling with ResponseError
-* - Streaming support for large responses
-* - Multiple instance support with unique IDs
-*
-* Notes:
-* - All requests are POST requests by default
-* - Automatically adds X-FaasJS-Request-Id header for request tracking
-* - baseUrl must end with '/' (will throw Error if not)
-* - Supports global mock via setMock() for testing all instances
-*
-* @example Basic usage
-* ```ts
-* import { FaasBrowserClient } from '@faasjs/react'
-*
-* const client = new FaasBrowserClient('http://localhost:8080/')
-* const response = await client.action('func', { key: 'value' })
-* console.log(response.data)
-* ```
-*
-* @example With custom headers and options
-* ```ts
-* const client = new FaasBrowserClient('https://api.example.com/', {
-*   headers: { 'X-API-Key': 'secret' },
-*   beforeRequest: async ({ action, params, headers }) => {
-*     console.log(`Calling ${action} with params:`, params)
-*   }
-* })
-* ```
-*
-* @example Multiple instances
-* ```ts
-* const apiClient = new FaasBrowserClient('https://api.example.com/')
-* const localClient = new FaasBrowserClient('http://localhost:3000/')
-*
-* const apiData = await apiClient.action('users')
-* const localData = await localClient.action('data')
-* ```
-*
-* @example Error handling
-* ```ts
-* const client = new FaasBrowserClient('https://api.example.com/')
-*
-* try {
-*   const response = await client.action('user', { id: 123 })
-*   console.log(response.data)
-* } catch (error) {
-*   if (error instanceof ResponseError) {
-*     console.error(`Request failed: ${error.message}`, error.status)
-*   } else {
-*     console.error('Unexpected error:', error)
-*   }
-* }
-* ```
-*
-* @throws {Error} When baseUrl does not end with '/'
-*
-* @see {@link setMock} for testing support.
-* @see {@link ResponseError} for error handling.
 */
 var FaasBrowserClient = class {
 	/**
@@ -597,172 +243,15 @@ var FaasBrowserClient = class {
 	defaultOptions;
 	/**
 	* Creates a new FaasBrowserClient instance.
-	*
-	* @param {BaseUrl} [baseUrl] - Base URL for all API requests. Must end with `/`. Defaults to `/` for relative requests.
-	* @param {Options} [options] - Default request options such as headers, hooks, request override, or stream mode.
-	* See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
-	* `request`, `baseUrl`, and `stream`.
-	*
-	* @example Basic initialization
-	* ```ts
-	* const client = new FaasBrowserClient('/')
-	* ```
-	*
-	* @example With API endpoint
-	* ```ts
-	* const client = new FaasBrowserClient('https://api.example.com/')
-	* ```
-	*
-	* @example With custom headers
-	* ```ts
-	* const client = new FaasBrowserClient('https://api.example.com/', {
-	*   headers: {
-	*     'Authorization': 'Bearer token123',
-	*     'X-Custom-Header': 'value'
-	*   }
-	* })
-	* ```
-	*
-	* @example With beforeRequest hook
-	* ```ts
-	* const client = new FaasBrowserClient('https://api.example.com/', {
-	*   beforeRequest: async ({ action, params, headers }) => {
-	*     console.log(`Requesting ${action}`, params)
-	*     // Modify headers before request
-	*     headers['X-Timestamp'] = Date.now().toString()
-	*   }
-	* })
-	* ```
-	*
-	* @example With custom request function
-	* ```ts
-	* import axios from 'axios'
-	*
-	* const client = new FaasBrowserClient('/', {
-	*   request: async (url, options) => {
-	*     const response = await axios.post(url, options.body, {
-	*       headers: options.headers
-	*     })
-	*     return new Response({
-	*       status: response.status,
-	*       headers: response.headers,
-	*       data: response.data
-	*     })
-	*   }
-	* })
-	* ```
-	*
-	* @throws {Error} When `baseUrl` does not end with `/`
 	*/
 	constructor(baseUrl = "/", options = Object.create(null)) {
 		if (baseUrl && !baseUrl.endsWith("/")) throw Error("[FaasJS] baseUrl should end with /");
 		this.id = `FBC-${generateId()}`;
 		this.baseUrl = baseUrl;
 		this.defaultOptions = options;
-		console.debug(`[FaasJS] Initialize with baseUrl: ${this.baseUrl}`);
 	}
 	/**
 	* Makes a request to a FaasJS function.
-	*
-	* @template PathOrData - The function path or data type for type safety
-	* @param {FaasAction<PathOrData>} action - The function path to call. Converted to lowercase when constructing the URL.
-	*   Must be a non-empty string.
-	* @param {FaasParams<PathOrData>} [params] - The parameters to send to the function. Will be serialized as JSON.
-	*   Optional if the function accepts no parameters.
-	* @param {Options} [options] - Optional request options that override client defaults.
-	*   Supports headers, beforeRequest hook, custom request function, baseUrl override, and streaming mode.
-	*   See {@link Options} for supported request fields such as `headers`, `beforeRequest`,
-	*   `request`, `baseUrl`, and `stream`.
-	*
-	* @returns {Promise<Response<FaasData<PathOrData>>>} A promise resolving to the wrapped FaasJS response. When `options.stream`
-	*   is `true`, the runtime returns the native fetch response so callers can read the stream.
-	*
-	* @throws {Error} When action is not provided or is empty
-	* @throws {ResponseError} When the server returns an error response (status >= 400 or body.error exists)
-	* @throws {Error} When the request fails before a response is received
-	*
-	* Notes:
-	* - All requests are POST requests by default
-	* - Action path is automatically converted to lowercase
-	* - A unique request ID is generated for each request and sent in X-FaasJS-Request-Id header
-	* - Headers are merged from client defaults and request options (request options take precedence)
-	* - If a global mock is set via setMock(), it will be used instead of making real requests
-	* - If a custom request function is provided in options, it will be used instead of fetch
-	* - When stream option is true, returns the native fetch Response instead of a wrapped Response
-	* - Response body is automatically parsed as JSON when possible
-	* - Server errors (body.error) are automatically converted to ResponseError
-	*
-	* @example Basic request
-	* ```ts
-	* const response = await client.action('user', { id: 123 })
-	* console.log(response.data)
-	* ```
-	*
-	* @example With no parameters
-	* ```ts
-	* const response = await client.action('status')
-	* console.log(response.data.status)
-	* ```
-	*
-	* @example With custom options
-	* ```ts
-	* const response = await client.action('data', {
-	*   limit: 10,
-	*   offset: 0
-	* }, {
-	*   headers: { 'X-Custom-Header': 'value' }
-	* })
-	* ```
-	*
-	* @example Streaming large response
-	* ```ts
-	* const response = await client.action('stream', {
-	*   format: 'json'
-	* }, {
-	*   stream: true
-	* })
-	* // response is native fetch Response with streaming support
-	* const reader = response.body.getReader()
-	* ```
-	*
-	* @example With type safety
-	* ```ts
-	* interface UserData {
-	*   id: number
-	*   name: string
-	*   email: string
-	* }
-	*
-	* const response = await client.action<UserData>('user', { id: 123 })
-	* console.log(response.data.name) // TypeScript knows it's a string
-	* ```
-	*
-	* @example Handling errors
-	* ```ts
-	* try {
-	*   const response = await client.action('user', { id: 123 })
-	*   console.log(response.data)
-	* } catch (error) {
-	*   if (error instanceof ResponseError) {
-	*     console.error(`Server error: ${error.message}`, error.status)
-	*     if (error.body) console.error('Error details:', error.body)
-	*   } else {
-	*     console.error('Network error:', error)
-	*   }
-	* }
-	* ```
-	*
-	* @example Chaining requests
-	* ```ts
-	* const userId = await client.action('createUser', {
-	*   name: 'John',
-	*   email: 'john@example.com'
-	* })
-	*
-	* const profile = await client.action('getProfile', {
-	*   userId: userId.data.id
-	* })
-	* ```
 	*/
 	async action(action, params, options) {
 		if (!action) throw Error("[FaasJS] action required");
@@ -1262,7 +751,7 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 				if (typeof e?.message === "string" && e.message.toLowerCase().includes("aborted")) return;
 				if (!failedOnceRef.current && typeof e?.message === "string" && e.message.includes("Failed to fetch")) {
 					failedOnceRef.current = true;
-					console.warn(`FaasReactClient: ${e.message} retry...`);
+					console.warn(`[FaasJS] FaasReactClient: ${e.message} retry...`);
 					run();
 					return;
 				}
@@ -1348,8 +837,8 @@ function useFaasRequest({ action, defaultParams, options, beforeSend, onSuccess,
 *
 * @param {FaasAction<PathOrData>} action - Action path to invoke.
 * @param {FaasParams<PathOrData>} defaultParams - Params used for the initial request and future reloads.
-* @param {useFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, polling, and base URL overrides.
-* See the `useFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
+* @param {UseFaasOptions<PathOrData>} [options] - Optional hook configuration such as controlled data, skip logic, debounce timing, polling, and base URL overrides.
+* See the `UseFaasOptions` type for `params`, `data`, `setData`, `skip`, `debounce`, `polling`, and `baseUrl`.
 * @returns {FaasDataInjection<PathOrData>} Request state and helper methods described by {@link FaasDataInjection}.
 *
 * @example
@@ -1512,13 +1001,13 @@ function FaasReactClient(options = { baseUrl: "/" }) {
 function getClient(host) {
 	const client = clients[host || Object.keys(clients)[0]];
 	if (!client) {
-		console.warn("FaasReactClient is not initialized manually, use default.");
+		console.warn("[FaasJS] FaasReactClient is not initialized manually, use default.");
 		return FaasReactClient();
 	}
 	return client;
 }
 //#endregion
-//#region src/constant/index.ts
+//#region src/constants/index.ts
 /**
 * Returns a constant value that is created by the given function.
 *
@@ -1653,7 +1142,7 @@ function OptionalWrapper(props) {
 }
 OptionalWrapper.displayName = "OptionalWrapper";
 //#endregion
-//#region src/splittingState/index.tsx
+//#region src/splitting-state/index.tsx
 /**
 * Create local state entries and matching setters for each key in an object.
 *
@@ -1682,7 +1171,7 @@ function useSplittingState(initialStates) {
 	return states;
 }
 //#endregion
-//#region src/splittingContext/index.tsx
+//#region src/splitting-context/index.tsx
 /**
 * Create a context whose keys can be consumed independently.
 *