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

package/dist/index.cjs

@@ -1,8 +1,668 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-let _faasjs_browser = require("@faasjs/browser");
 let react = require("react");
 let react_jsx_runtime = require("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;
 /**
@@ -309,7 +969,7 @@ const clients = {};
 */
 function FaasReactClient({ baseUrl, options: clientOptions, onError } = { baseUrl: "/" }) {
 	const resolvedBaseUrl = baseUrl ?? "/";
-	const client = new _faasjs_browser.FaasBrowserClient(resolvedBaseUrl, clientOptions);
+	const client = new FaasBrowserClient(resolvedBaseUrl, clientOptions);
 	function withBaseUrl(options) {
 		if (options?.baseUrl) return options;
 		return {
@@ -1005,6 +1665,7 @@ function usePrevious(value) {
 
 //#endregion
 exports.ErrorBoundary = ErrorBoundary;
+exports.FaasBrowserClient = FaasBrowserClient;
 exports.FaasDataWrapper = FaasDataWrapper;
 exports.FaasReactClient = FaasReactClient;
 exports.Form = FormContainer;
@@ -1015,10 +1676,14 @@ exports.FormDefaultRules = FormDefaultRules;
 exports.FormInput = FormInput;
 exports.FormItem = FormItem;
 exports.OptionalWrapper = OptionalWrapper;
+exports.Response = Response;
+exports.ResponseError = ResponseError;
 exports.createSplittingContext = createSplittingContext;
 exports.equal = equal;
 exports.faas = faas;
+exports.generateId = generateId;
 exports.getClient = getClient;
+exports.setMock = setMock;
 exports.useConstant = useConstant;
 exports.useEqualCallback = useEqualCallback;
 exports.useEqualEffect = useEqualEffect;