@faasjs/react 8.0.0-beta.7 → 8.0.0-beta.9

package/dist/index.mjs

@@ -1,7 +1,667 @@
-import { FaasBrowserClient } from "@faasjs/browser";
 import { Component, cloneElement, createContext, forwardRef, useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 
+//#region src/generateId.ts
+/**
+* Generate random id with prefix
+*
+* @param prefix prefix of id
+* @param length length of id without prefix, range is 8 ~ 18, default is 18
+*
+* @example
+* ```ts
+* generateId('prefix-') // prefix-1z3b4c5d6e
+* ```
+*/
+function generateId(prefix = "", length = 18) {
+	if (length < 8 || length > 18) throw new Error("Length must be 8 ~ 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.ts
+/**
+* Wrapper class for HTTP responses from FaasJS functions.
+*
+* Provides a consistent interface for handling server responses with status code, headers,
+* 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.
+*
+* @param {ResponseProps<T>} [props] - Response properties including status, headers, body, and data.
+*   All properties are optional with sensible defaults.
+*
+* @remarks
+* - 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-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 ResponseProps for response property type
+* @see ResponseError for error response handling
+* @see FaasBrowserClient.action for method returning Response
+*/
+var Response = class {
+	status;
+	headers;
+	body;
+	data;
+	constructor(props = {}) {
+		this.status = props.status || (props.data || props.body ? 200 : 204);
+		this.headers = props.headers || {};
+		this.body = props.body;
+		if (props.data !== void 0) this.data = props.data;
+		if (props.data && !props.body) this.body = JSON.stringify(props.data);
+	}
+};
+/**
+* Custom error class for handling HTTP response errors from FaasJS requests.
+*
+* 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.
+*
+* @class ResponseError
+* @extends {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.
+*
+* @param {string | Error | ResponseErrorProps} data - The error message, an Error object, or a ResponseErrorProps object.
+* @param {Omit<ResponseErrorProps, 'message' | 'originalError'>} [options] - Additional options for the error (status, headers, body).
+*
+* @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-Request-Id']) {
+*       console.error('Request ID:', error.headers['X-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' } }
+*   }
+* })
+* ```
+*
+* @remarks
+* - 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 FaasBrowserClient.action for how ResponseError is thrown in requests
+* @see ResponseProps for the structure of response data
+* @see setMock for mocking errors in tests
+*/
+var ResponseError = class extends Error {
+	status;
+	headers;
+	body;
+	originalError;
+	constructor(data, options) {
+		let props;
+		if (typeof data === "string") props = {
+			message: data,
+			...options
+		};
+		else if (data instanceof Error || data?.constructor?.name?.includes("Error")) props = {
+			message: data.message,
+			originalError: data,
+			...options
+		};
+		else props = data;
+		super(props.message);
+		this.status = props.status || 500;
+		this.headers = props.headers || {};
+		this.body = props.body || props.originalError || { error: { message: props.message } };
+	}
+};
+let mock = null;
+/**
+* Set global mock handler for testing. Mock affects all FaasBrowserClient instances.
+*
+* @param 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 Use MockHandler function
+* ```ts
+* setMock(async (action, params, options) => {
+*   if (action === 'user') {
+*     return { data: { name: 'John' } }
+*   }
+*   return { status: 404, data: { error: 'Not found' } }
+* })
+*
+* const response = await client.action('user')
+* ```
+*
+* @example Use ResponseProps object
+* ```ts
+* setMock({
+*   status: 200,
+*   data: { result: 'success' },
+*   headers: { 'X-Custom': 'value' }
+* })
+* ```
+*
+* @example Use Response instance
+* ```ts
+* setMock(new Response({
+*   status: 200,
+*   data: { result: 'success' }
+* }))
+* ```
+*
+* @example Clear mock
+* ```ts
+* setMock(null)
+* // or
+* setMock(undefined)
+* ```
+*
+* @example Handle errors
+* ```ts
+* setMock(async () => {
+*   throw new Error('Internal error')
+* })
+* // This will reject with ResponseError
+* ```
+*/
+function setMock(handler) {
+	mock = handler;
+}
+/**
+* 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
+*
+* @remarks
+* - 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 setMock for testing support
+* @see ResponseError for error handling
+*/
+var FaasBrowserClient = class {
+	id;
+	baseUrl;
+	defaultOptions;
+	/**
+	* Creates a new FaasBrowserClient instance.
+	*
+	* @param baseUrl - Base URL for all API requests. Must end with '/'. Defaults to '/' for relative requests.
+	*   @throws {Error} If baseUrl does not end with '/'
+	* @param options - Configuration options for the client.
+	*   Supports default headers, beforeRequest hook, custom request function,
+	*   baseUrl override, and streaming mode.
+	*
+	* @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 action - The function path to call. Converted to lowercase when constructing the URL.
+	*   Must be a non-empty string.
+	* @param params - The parameters to send to the function. Will be serialized as JSON.
+	*   Optional if the function accepts no parameters.
+	* @param options - Optional request options that override client defaults.
+	*   Supports headers, beforeRequest hook, custom request function, baseUrl override, and streaming mode.
+	*
+	* @returns A Promise that resolves to a Response object containing status, headers, body, and data.
+	*   The data property is typed based on the PathOrData generic parameter.
+	*
+	* @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 {NetworkError} When network request fails
+	*
+	* @remarks
+	* - 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<{
+	*   action: 'user'
+	*   params: { id: number }
+	*   data: 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.data) console.error('Error details:', error.data)
+	*   } 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");
+		const id = `F-${generateId()}`;
+		const url = `${(options?.baseUrl || this.baseUrl) + action.toLowerCase()}?_=${id}`;
+		if (!params) params = Object.create(null);
+		if (!options) options = Object.create(null);
+		const parsedOptions = {
+			method: "POST",
+			headers: { "Content-Type": "application/json; charset=UTF-8" },
+			mode: "cors",
+			credentials: "include",
+			body: JSON.stringify(params),
+			...this.defaultOptions,
+			...options
+		};
+		if (!parsedOptions.headers["X-FaasJS-Request-Id"] && !parsedOptions.headers["x-faasjs-request-id"]) parsedOptions.headers["X-FaasJS-Request-Id"] = id;
+		if (parsedOptions.beforeRequest) await parsedOptions.beforeRequest({
+			action,
+			params,
+			options: parsedOptions,
+			headers: parsedOptions.headers
+		});
+		if (mock) {
+			console.debug(`[FaasJS] Mock request: ${action} %j`, params);
+			if (typeof mock === "function") {
+				const response = await mock(action, params, parsedOptions);
+				if (response instanceof Error) return Promise.reject(new ResponseError(response));
+				if (response instanceof Response) return response;
+				return new Response(response || {});
+			}
+			if (mock instanceof Response) return mock;
+			return new Response(mock || {});
+		}
+		if (parsedOptions.request) return parsedOptions.request(url, parsedOptions);
+		if (parsedOptions.stream) return fetch(url, parsedOptions);
+		return fetch(url, parsedOptions).then(async (response) => {
+			const headers = {};
+			for (const values of response.headers) headers[values[0]] = values[1];
+			return response.text().then((res) => {
+				if (response.status >= 200 && response.status < 300) {
+					if (!res) return new Response({
+						status: response.status,
+						headers
+					});
+					const body = JSON.parse(res);
+					if (body.error?.message) return Promise.reject(new ResponseError({
+						message: body.error.message,
+						status: response.status,
+						headers,
+						body
+					}));
+					return new Response({
+						status: response.status,
+						headers,
+						body,
+						data: body.data
+					});
+				}
+				try {
+					const body = JSON.parse(res);
+					if (body.error?.message) return Promise.reject(new ResponseError({
+						message: body.error.message,
+						status: response.status,
+						headers,
+						body
+					}));
+					return Promise.reject(new ResponseError({
+						message: res,
+						status: response.status,
+						headers,
+						body
+					}));
+				} catch (_) {
+					return Promise.reject(new ResponseError({
+						message: res,
+						status: response.status,
+						headers,
+						body: res
+					}));
+				}
+			});
+		});
+	}
+};
+
+//#endregion
 //#region src/equal.ts
 const AsyncFunction = (async () => {}).constructor;
 /**
@@ -1003,4 +1663,4 @@ function usePrevious(value) {
 }
 
 //#endregion
-export { ErrorBoundary, FaasDataWrapper, FaasReactClient, FormContainer as Form, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormInput, FormItem, OptionalWrapper, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+export { ErrorBoundary, FaasBrowserClient, FaasDataWrapper, FaasReactClient, FormContainer as Form, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormInput, FormItem, OptionalWrapper, Response, ResponseError, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };