@intrig/react 0.0.15-27 → 0.0.15-29

package/_virtual/_rollupPluginBabelHelpers.js

@@ -0,0 +1,11 @@
+function _extends() {
+  return _extends = Object.assign ? Object.assign.bind() : function (n) {
+    for (var e = 1; e < arguments.length; e++) {
+      var t = arguments[e];
+      for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]);
+    }
+    return n;
+  }, _extends.apply(null, arguments);
+}
+
+export { _extends as extends };

package/extra.js

@@ -0,0 +1,131 @@
+import { isSuccess, isError, isValidationError, init, pending, success, error } from './network-state.js';
+import { useRef, useEffect, useCallback, useId, useMemo, useState } from 'react';
+import { useIntrigContext } from './intrig-context.js';
+
+/**
+ * Converts a given hook into a promise-based function.
+ *
+ * @param {IntrigHook<P, B, T>} hook - The hook function to be converted.
+ * @param {string} [key='default'] - An optional key to uniquely identify the hook instance.
+ *
+ * @return {[(...params: Parameters<ReturnType<IntrigHook<P, B, T>>[1]>) => Promise<T>, () => void]}
+ * Returns a tuple containing a function that invokes the hook as a promise and a function to clear the state.
+ */
+
+// **Implementation**
+function useAsPromise(hook, options) {
+  // <- Compatible return type
+  const resolveRef = useRef(() => {
+    // intentionally kept empty
+  });
+  const rejectRef = useRef(() => {
+    // intentionally kept empty
+  });
+  const [state, dispatch, clear] = hook(options);
+  useEffect(() => {
+    if (isSuccess(state)) {
+      resolveRef.current == null || resolveRef.current(state.data);
+      clear();
+    } else if (isError(state)) {
+      rejectRef.current == null || rejectRef.current(state.error);
+      clear();
+    }
+  }, [state]);
+  const promiseFn = useCallback((...args) => {
+    return new Promise((resolve, reject) => {
+      resolveRef.current = resolve;
+      rejectRef.current = reject;
+      const dispatchState = dispatch(...args);
+      if (isValidationError(dispatchState)) {
+        reject(dispatchState.error);
+      }
+    });
+  }, [dispatch]);
+  return [promiseFn, clear];
+}
+
+/**
+ * A custom hook that manages and returns the network state of a promise-based function,
+ * providing a way to execute the function and clear its state.
+ *
+ * @param fn The promise-based function whose network state is to be managed. It should be a function that returns a promise.
+ * @param key An optional identifier for the network state. Defaults to 'default'.
+ * @return A tuple containing the current network state, a function to execute the promise, and a function to clear the state.
+ */
+function useAsNetworkState(fn, key = 'default') {
+  var _context$state3;
+  const id = useId();
+  const context = useIntrigContext();
+  const networkState = useMemo(() => {
+    var _context$state, _context$state2;
+    return (_context$state = (_context$state2 = context.state) == null ? void 0 : _context$state2[`promiseState:${id}:${key}}`]) != null ? _context$state : init();
+  }, [(_context$state3 = context.state) == null ? void 0 : _context$state3[`promiseState:${id}:${key}}`]]);
+  const dispatch = useCallback(state => {
+    context.dispatch({
+      key,
+      operation: id,
+      source: 'promiseState',
+      state
+    });
+  }, [key, context.dispatch]);
+  const execute = useCallback((...args) => {
+    dispatch(pending());
+    return fn(...args).then(data => {
+      dispatch(success(data));
+    }, e => {
+      dispatch(error(e));
+    });
+  }, []);
+  const clear = useCallback(() => {
+    dispatch(init());
+  }, []);
+  return [networkState, execute, clear];
+}
+
+/**
+ * A custom hook that resolves the value from the provided hook's state and updates it whenever the state changes.
+ *
+ * @param {IntrigHook<P, B, T>} hook - The hook that provides the state to observe and resolve data from.
+ * @param options
+ * @return {T | undefined} The resolved value from the hook's state or undefined if the state is not successful.
+ */
+
+// **Implementation**
+function useResolvedValue(hook, options) {
+  const [value, setValue] = useState();
+  const [state] = hook(options); // Ensure compatibility with different hook types
+
+  useEffect(() => {
+    if (isSuccess(state)) {
+      setValue(state.data);
+    } else {
+      setValue(undefined);
+    }
+  }, [state]);
+  return value;
+}
+
+/**
+ * A custom hook that resolves and caches the value from a successful state provided by the given hook.
+ * The state is updated only when it is in a successful state.
+ *
+ * @param {IntrigHook<P, B, T>} hook - The hook that provides the state to observe and cache data from.
+ * @param options
+ * @return {T | undefined} The cached value from the hook's state or undefined if the state is not successful.
+ */
+
+// **Implementation**
+function useResolvedCachedValue(hook, options) {
+  const [cachedValue, setCachedValue] = useState();
+  const [state] = hook(options); // Ensure compatibility with different hook types
+
+  useEffect(() => {
+    if (isSuccess(state)) {
+      setCachedValue(state.data);
+    }
+    // Do not clear cached value if state is unsuccessful
+  }, [state]);
+  return cachedValue;
+}
+
+export { useAsNetworkState, useAsPromise, useResolvedCachedValue, useResolvedValue };

package/index.js

@@ -0,0 +1,4 @@
+export { IntrigProvider, IntrigProviderStub, StatusTrap, useCentralError, useCentralPendingState, useNetworkState, useTransitionCall } from './intrig-provider.js';
+export { error, init, isError, isInit, isNetworkError, isPending, isRequestValidationError, isResponseValidationError, isSuccess, isSuccessfulDispatch, isValidationError, networkError, pending, requestValidationError, responseValidationError, success, successfulDispatch, validationError } from './network-state.js';
+export { useAsNetworkState, useAsPromise, useResolvedCachedValue, useResolvedValue } from './extra.js';
+export { encode, transform, transformResponse } from './media-type-utils.js';

package/intrig-context.js

@@ -0,0 +1,34 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Defines the ContextType interface for managing global state, dispatching actions,
+ * and holding a collection of Axios instances.
+ *
+ * @interface ContextType
+ * @property {GlobalState} state - The global state of the application.
+ * @property {React.Dispatch<NetworkAction<unknown>>} dispatch - The dispatch function to send network actions.
+ * @property {Record<string, AxiosInstance>} axios - A record of Axios instances for making HTTP requests.
+ */
+
+/**
+ * Context object created using `createContext` function. Provides a way to share state, dispatch functions,
+ * and axios instance across components without having to pass props down manually at every level.
+ *
+ * @type {ContextType}
+ */
+const Context = /*#__PURE__*/createContext({
+  state: {},
+  filteredState: {},
+  dispatch() {
+    // intentionally kept empty
+  },
+  configs: {},
+  async execute() {
+    // intentionally kept empty
+  }
+});
+function useIntrigContext() {
+  return useContext(Context);
+}
+
+export { Context, useIntrigContext };

package/intrig-provider.js

@@ -0,0 +1,407 @@
+import { extends as _extends } from './_virtual/_rollupPluginBabelHelpers.js';
+import { useReducer, useMemo, useContext, useState, useCallback, useRef, useEffect } from 'react';
+import { isPending, isError, init, pending, isSuccess, error, success } from './network-state.js';
+import axios, { isAxiosError } from 'axios';
+import { logger } from './logger.js';
+import { flushSync } from 'react-dom';
+import { createParser } from 'eventsource-parser';
+import { Context } from './intrig-context.js';
+import { jsx } from 'react/jsx-runtime';
+
+function requestReducer(state, action) {
+  return _extends({}, state, {
+    [`${action.source}:${action.operation}:${action.key}`]: action.state
+  });
+}
+
+/**
+ * IntrigProvider is a context provider component that sets up global state management
+ * and provides Axios instances for API requests.
+ *
+ * @param {Object} props - The properties object.
+ * @param {React.ReactNode} props.children - The child components to be wrapped by the provider.
+ * @param {Object} [props.configs={}] - Configuration object for Axios instances.
+ * @param {Object} [props.configs.defaults={}] - Default configuration for Axios.
+ * @param {Object} [props.configs.petstore={}] - Configuration specific to the petstore API.
+ * @return {JSX.Element} A context provider component that wraps the provided children.
+ */
+function IntrigProvider({
+  children,
+  configs = {}
+}) {
+  const [state, dispatch] = useReducer(requestReducer, {});
+  const axiosInstances = useMemo(() => {
+    return {};
+  }, [configs]);
+  const contextValue = useMemo(() => {
+    async function execute(request, dispatch, schema, errorSchema) {
+      try {
+        dispatch(pending());
+        const response = await axiosInstances[request.source].request(request);
+        if (response.status >= 200 && response.status < 300) {
+          var _response$headers;
+          if ((_response$headers = response.headers) != null && (_response$headers = _response$headers['content-type']) != null && _response$headers.includes('text/event-stream')) {
+            const reader = response.data.getReader();
+            const decoder = new TextDecoder();
+            let lastMessage;
+            const parser = createParser({
+              onEvent(message) {
+                let decoded = message.data;
+                try {
+                  let parsed = JSON.parse(decoded);
+                  if (schema) {
+                    const validated = schema.safeParse(parsed);
+                    if (!validated.success) {
+                      dispatch(error(validated.error.issues, response.status, request));
+                      return;
+                    }
+                    parsed = validated.data;
+                  }
+                  decoded = parsed;
+                } catch (e) {
+                  console.error(e);
+                }
+                lastMessage = decoded;
+                flushSync(() => dispatch(pending(undefined, decoded)));
+              }
+            });
+            while (true) {
+              const {
+                done,
+                value
+              } = await reader.read();
+              if (done) {
+                flushSync(() => dispatch(success(lastMessage)));
+                break;
+              }
+              parser.feed(decoder.decode(value, {
+                stream: true
+              }));
+            }
+          } else if (schema) {
+            const data = schema.safeParse(response.data);
+            if (!data.success) {
+              dispatch(error(data.error.issues, response.status, request));
+              return;
+            }
+            dispatch(success(data.data));
+          } else {
+            dispatch(success(response.data));
+          }
+        } else {
+          var _errorSchema$safePars, _response$data, _ref;
+          const {
+            data
+          } = (_errorSchema$safePars = errorSchema == null ? void 0 : errorSchema.safeParse((_response$data = response.data) != null ? _response$data : {})) != null ? _errorSchema$safePars : {};
+          //todo: handle error validation error.
+          dispatch(error((_ref = data != null ? data : response.data) != null ? _ref : response.statusText, response.status));
+        }
+      } catch (e) {
+        if (isAxiosError(e)) {
+          var _errorSchema$safePars2, _e$response$data, _e$response, _e$response2, _e$response3;
+          const {
+            data
+          } = (_errorSchema$safePars2 = errorSchema == null ? void 0 : errorSchema.safeParse((_e$response$data = (_e$response = e.response) == null ? void 0 : _e$response.data) != null ? _e$response$data : {})) != null ? _errorSchema$safePars2 : {};
+          dispatch(error(data != null ? data : (_e$response2 = e.response) == null ? void 0 : _e$response2.data, (_e$response3 = e.response) == null ? void 0 : _e$response3.status, request));
+        } else {
+          dispatch(error(e));
+        }
+      }
+    }
+    return {
+      state,
+      dispatch,
+      filteredState: state,
+      configs,
+      execute
+    };
+  }, [state, axiosInstances]);
+  return /*#__PURE__*/jsx(Context.Provider, {
+    value: contextValue,
+    children: children
+  });
+}
+function IntrigProviderStub({
+  children,
+  configs = {},
+  stubs = () => {
+    // intentionally kept empty
+  }
+}) {
+  const [state, dispatch] = useReducer(requestReducer, {});
+  const collectedStubs = useMemo(() => {
+    const fns = {};
+    function stub(hook, fn) {
+      fns[hook.key] = fn;
+    }
+    stubs(stub);
+    return fns;
+  }, [stubs]);
+  const contextValue = useMemo(() => {
+    async function execute(request, dispatch, schema) {
+      const stub = collectedStubs[request.key];
+      if (stub) {
+        try {
+          await stub(request.params, request.data, dispatch);
+        } catch (e) {
+          dispatch(error(e));
+        }
+      } else {
+        dispatch(init());
+      }
+    }
+    return {
+      state,
+      dispatch,
+      filteredState: state,
+      configs,
+      execute
+    };
+  }, [state, dispatch, configs, collectedStubs]);
+  return /*#__PURE__*/jsx(Context.Provider, {
+    value: contextValue,
+    children: children
+  });
+}
+/**
+ * StatusTrap component is used to track and manage network request states.
+ *
+ * @param {Object} props - The properties object.
+ * @param {React.ReactNode} props.children - The child elements to be rendered.
+ * @param {string} props.type - The type of network state to handle ("error", "pending", "pending + error").
+ * @param {boolean} [props.propagate=true] - Whether to propagate the event to the parent context.
+ * @return {React.ReactElement} The context provider component with filtered state and custom dispatch.
+ */
+function StatusTrap({
+  children,
+  type,
+  propagate = true
+}) {
+  const ctx = useContext(Context);
+  const [requests, setRequests] = useState([]);
+  const shouldHandleEvent = useCallback(state => {
+    switch (type) {
+      case 'error':
+        return isError(state);
+      case 'pending':
+        return isPending(state);
+      case 'pending + error':
+        return isPending(state) || isError(state);
+      default:
+        return false;
+    }
+  }, [type]);
+  const dispatch = useCallback(event => {
+    if (!event.handled) {
+      if (shouldHandleEvent(event.state)) {
+        setRequests(prev => [...prev, event.key]);
+        if (!propagate) {
+          ctx.dispatch(_extends({}, event, {
+            handled: true
+          }));
+          return;
+        }
+      } else {
+        setRequests(prev => prev.filter(k => k !== event.key));
+      }
+    }
+    ctx.dispatch(event);
+  }, [ctx, propagate, shouldHandleEvent]);
+  const filteredState = useMemo(() => {
+    return Object.fromEntries(Object.entries(ctx.state).filter(([key]) => requests.includes(key)));
+  }, [ctx.state, requests]);
+  return /*#__PURE__*/jsx(Context.Provider, {
+    value: _extends({}, ctx, {
+      dispatch,
+      filteredState
+    }),
+    children: children
+  });
+}
+/**
+ * useNetworkState is a custom hook that manages the network state within the specified context.
+ * It handles making network requests, dispatching appropriate states based on the request lifecycle,
+ * and allows aborting ongoing requests.
+ *
+ * @param {Object} params - The parameters required to configure and use the network state.
+ * @param {string} params.key - A unique identifier for the network request.
+ * @param {string} params.operation - The operation type related to the request.
+ * @param {string} params.source - The source or endpoint for the network request.
+ * @param {Object} params.schema - The schema used for validating the response data.
+ * @param {number} [params.debounceDelay] - The debounce delay for executing the network request.
+ *
+ * @return {[NetworkState<T>, (request: AxiosRequestConfig) => void, () => void]}
+ *          Returns a state object representing the current network state,
+ *          a function to execute the network request, and a function to clear the request.
+ */
+function useNetworkState({
+  key,
+  operation,
+  source,
+  schema,
+  errorSchema,
+  debounceDelay: requestDebounceDelay
+}) {
+  var _context$state3;
+  const context = useContext(Context);
+  const [abortController, setAbortController] = useState();
+  const networkState = useMemo(() => {
+    var _context$state, _ref2, _context$state2;
+    logger.info(`Updating status ${key} ${operation} ${source}`);
+    logger.debug('<=', (_context$state = context.state) == null ? void 0 : _context$state[`${source}:${operation}:${key}`]);
+    return (_ref2 = (_context$state2 = context.state) == null ? void 0 : _context$state2[`${source}:${operation}:${key}`]) != null ? _ref2 : init();
+  }, [JSON.stringify((_context$state3 = context.state) == null ? void 0 : _context$state3[`${source}:${operation}:${key}`])]);
+  const dispatch = useCallback(state => {
+    context.dispatch({
+      key,
+      operation,
+      source,
+      state
+    });
+  }, [key, operation, source, context.dispatch]);
+  const debounceDelay = useMemo(() => {
+    var _ref3, _context$configs;
+    return (_ref3 = requestDebounceDelay != null ? requestDebounceDelay : (_context$configs = context.configs) == null ? void 0 : _context$configs.debounceDelay) != null ? _ref3 : 0;
+  }, [context.configs, requestDebounceDelay]);
+  const execute = useCallback(async request => {
+    logger.info(`Executing request ${key} ${operation} ${source}`);
+    logger.debug('=>', request);
+    const abortController = new AbortController();
+    setAbortController(abortController);
+    const requestConfig = _extends({}, request, {
+      onUploadProgress(event) {
+        dispatch(pending({
+          type: 'upload',
+          loaded: event.loaded,
+          total: event.total
+        }));
+        request.onUploadProgress == null || request.onUploadProgress(event);
+      },
+      onDownloadProgress(event) {
+        dispatch(pending({
+          type: 'download',
+          loaded: event.loaded,
+          total: event.total
+        }));
+        request.onDownloadProgress == null || request.onDownloadProgress(event);
+      },
+      signal: abortController.signal
+    });
+    await context.execute(requestConfig, dispatch, schema, errorSchema);
+  }, [networkState, context.dispatch, axios]);
+  const deboundedExecute = useMemo(() => debounce(execute, debounceDelay != null ? debounceDelay : 0), [execute]);
+  const clear = useCallback(() => {
+    logger.info(`Clearing request ${key} ${operation} ${source}`);
+    dispatch(init());
+    setAbortController(abortController => {
+      logger.info(`Aborting request ${key} ${operation} ${source}`);
+      abortController == null || abortController.abort();
+      return undefined;
+    });
+  }, [dispatch, abortController]);
+  return [networkState, deboundedExecute, clear, dispatch];
+}
+function debounce(func, delay) {
+  let timeoutId;
+  return (...args) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      func(...args);
+    }, delay);
+  };
+}
+
+/**
+ * Handles central error extraction from the provided context.
+ * It filters the state to retain error states and maps them to a structured error object with additional context information.
+ * @return {Object[]} An array of objects representing the error states with context information such as source, operation, and key.
+ */
+function useCentralError() {
+  const ctx = useContext(Context);
+  return useMemo(() => {
+    return Object.entries(ctx.filteredState).filter(([, state]) => isError(state)).map(([k, state]) => {
+      const [source, operation, key] = k.split(':');
+      return _extends({}, state, {
+        source,
+        operation,
+        key
+      });
+    });
+  }, [ctx.filteredState]);
+}
+
+/**
+ * Uses central pending state handling by aggregating pending states from context.
+ * It calculates the overall progress of pending states if any, or returns an initial state otherwise.
+ *
+ * @return {NetworkState} The aggregated network state based on the pending states and their progress.
+ */
+function useCentralPendingState() {
+  const ctx = useContext(Context);
+  const result = useMemo(() => {
+    const pendingStates = Object.values(ctx.filteredState).filter(isPending);
+    if (!pendingStates.length) {
+      return init();
+    }
+    const progress = pendingStates.filter(a => a.progress).reduce((progress, current) => {
+      var _current$progress$tot, _current$progress, _current$progress$loa, _current$progress2;
+      return {
+        total: progress.total + ((_current$progress$tot = (_current$progress = current.progress) == null ? void 0 : _current$progress.total) != null ? _current$progress$tot : 0),
+        loaded: progress.loaded + ((_current$progress$loa = (_current$progress2 = current.progress) == null ? void 0 : _current$progress2.loaded) != null ? _current$progress$loa : 0)
+      };
+    }, {
+      total: 0,
+      loaded: 0
+    });
+    return pending(progress.total ? progress : undefined);
+  }, [ctx.filteredState]);
+  return result;
+}
+
+/**
+ * A hook for making transient calls that can be aborted and validated against schemas.
+ * Returns a promise-based call function and an abort function.
+ *
+ * @param schema - Optional Zod schema for validating the response
+ * @param errorSchema - Optional Zod schema for validating error responses
+ * @returns A tuple of [call function, abort function]
+ */
+function useTransitionCall({
+  schema,
+  errorSchema
+}) {
+  const ctx = useContext(Context);
+  const controller = useRef(undefined);
+  const schemaRef = useRef(schema);
+  const errorSchemaRef = useRef(errorSchema);
+  useEffect(() => {
+    schemaRef.current = schema;
+    errorSchemaRef.current = errorSchema;
+  });
+  const call = useCallback(async request => {
+    var _controller$current;
+    (_controller$current = controller.current) == null || _controller$current.abort();
+    const abort = new AbortController();
+    controller.current = abort;
+    return new Promise((resolve, reject) => {
+      ctx.execute(_extends({}, request, {
+        signal: abort.signal
+      }), state => {
+        if (isSuccess(state)) {
+          resolve(state.data);
+        } else if (isError(state)) {
+          reject(state.error);
+        }
+      }, schemaRef.current, errorSchemaRef.current);
+    });
+  }, [ctx]);
+  const abort = useCallback(() => {
+    var _controller$current2;
+    (_controller$current2 = controller.current) == null || _controller$current2.abort();
+  }, []);
+  return [call, abort];
+}
+
+export { IntrigProvider, IntrigProviderStub, StatusTrap, useCentralError, useCentralPendingState, useNetworkState, useTransitionCall };

package/logger.js

@@ -0,0 +1,41 @@
+import log from 'loglevel';
+
+var _env, _ref, _ref2;
+
+// Extend the global interfaces
+
+// 1) Build-time default via Vite (if available)
+//    Cast import.meta to any to avoid TS errors if env isn't typed
+const buildDefault = typeof import.meta !== 'undefined' ? (_env = import.meta.env) == null ? void 0 : _env.VITE_LOG_LEVEL : undefined;
+
+// 2) Stored default in localStorage
+const storedLevel = typeof localStorage !== 'undefined' ? localStorage.getItem('LOG_LEVEL') : null;
+
+// Determine initial log level: build-time → stored → 'error'
+const defaultLevel = (_ref = (_ref2 = buildDefault) != null ? _ref2 : storedLevel) != null ? _ref : 'error';
+
+// Apply initial level
+log.setLevel(defaultLevel);
+
+// Expose a console setter to change level at runtime
+if (typeof window !== 'undefined') {
+  window.setLogLevel = level => {
+    log.setLevel(level);
+    try {
+      localStorage.setItem('LOG_LEVEL', String(level));
+    } catch (_unused) {
+      // ignore if storage is unavailable
+    }
+    console.log(`✏️  loglevel set to '${level}'`);
+  };
+}
+
+// Consistent wrapper API
+const logger = {
+  info: (msg, meta) => meta ? log.info(msg, meta) : log.info(msg),
+  warn: (msg, meta) => meta ? log.warn(msg, meta) : log.warn(msg),
+  error: (msg, meta) => meta ? log.error(msg, meta) : log.error(msg),
+  debug: (msg, meta) => meta ? log.debug(msg, meta) : log.debug(msg)
+};
+
+export { logger as default, logger };