@intrig/next 1.0.7 → 1.0.10

package/src/intrig-provider.tsx

@@ -0,0 +1,454 @@
+"use client"
+import {
+  createContext,
+  PropsWithChildren,
+  useCallback,
+  useContext,
+  useMemo,
+  useReducer,
+  useState,
+} from 'react';
+import {
+  error,
+  ErrorState,
+  ErrorWithContext,
+  init, IntrigHook,
+  isError,
+  isPending,
+  NetworkAction,
+  NetworkState,
+  pending,
+  Progress,
+  success
+} from './network-state';
+import axios, {
+  Axios,
+  AxiosProgressEvent,
+  AxiosRequestConfig,
+  CreateAxiosDefaults,
+  isAxiosError,
+} from 'axios';
+import { ZodSchema } from 'zod';
+import logger from './logger'
+
+import {Context, RequestType, GlobalState} from './intrig-context';
+
+/**
+ * Handles state updates for network requests based on the provided action.
+ *
+ * @param {GlobalState} state - The current state of the application.
+ * @param {NetworkAction<unknown>} action - The action containing source, operation, key, and state.
+ * @return {GlobalState} - The updated state after applying the action.
+ */
+function requestReducer(
+  state: GlobalState,
+  action: NetworkAction<unknown, unknown>
+): GlobalState {
+  return {
+    ...state,
+    [`${action.source}:${action.operation}:${action.key}`]: action.state,
+  };
+}
+
+export interface DefaultConfigs extends CreateAxiosDefaults {
+  debounceDelay?: number;
+}
+
+export interface IntrigProviderProps {
+  configs?: DefaultConfigs;
+  children: React.ReactNode;
+  initState?: GlobalState;
+}
+
+/**
+ * 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.
+ */
+export function IntrigProvider({
+                                 children,
+                                 configs = {},
+                                 initState = {},
+                               }: IntrigProviderProps) {
+  const [state, dispatch] = useReducer(requestReducer, initState);
+
+  const axiosInstance: Axios = useMemo(() => {
+    return axios.create({
+      ...(configs ?? {}),
+    });
+  }, [configs]);
+
+  const contextValue = useMemo(() => {
+    async function execute<T, E = unknown>(request: RequestType, dispatch: (state: NetworkState<T, E>) => void, schema: ZodSchema<T> | undefined, errorSchema: ZodSchema<E> | undefined) {
+      try {
+        dispatch(pending());
+        const response = await axiosInstance.request(request);
+
+        if (response.status >= 200 && response.status < 300) {
+          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 {
+          const { data } = errorSchema?.safeParse(response.data ?? {}) ?? {};
+          //todo: handle error validation error.
+          dispatch(
+            error(data ?? response.data ?? response.statusText, response.status)
+          );
+        }
+      } catch (e: any) {
+        if (isAxiosError(e)) {
+          const { data } = errorSchema?.safeParse(e.response?.data ?? {}) ?? {};
+          dispatch(error(data ?? e.response?.data, e.response?.status, request));
+        } else {
+          dispatch(error(e));
+        }
+      }
+    }
+
+    return {
+      state,
+      dispatch,
+      filteredState: state,
+      configs,
+      execute,
+    };
+  }, [state, axiosInstance]);
+
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+export interface StubType {
+  <P, B, T>(hook: IntrigHook<P, B, T>, fn: (params: P, body: B, dispatch: (state: NetworkState<T>) => void) => Promise<void>): void
+}
+
+export type WithStubSupport<T> = T & {
+  stubs?: (stub: StubType) => void;
+}
+
+export interface IntrigProviderStubProps {
+  configs?: DefaultConfigs;
+  stubs?: (stub: StubType) => void;
+  children: React.ReactNode;
+}
+
+export function IntrigProviderStub({ children, configs = {}, stubs = () => {} }: IntrigProviderStubProps) {
+  const [state, dispatch] = useReducer(requestReducer, {} as GlobalState);
+
+  const collectedStubs = useMemo(() => {
+    const fns: Record<string, (params: any, body: any, dispatch: (state: NetworkState<any>) => void) => Promise<void>> = {};
+    function stub<P, B, T>(hook: IntrigHook<P, B, T>, fn: (params: P, body: B, dispatch: (state: NetworkState<T>) => void) => Promise<void>) {
+      fns[hook.key] = fn;
+    }
+    stubs(stub);
+    return fns
+  }, [stubs]);
+
+  const contextValue = useMemo(() => {
+
+    async function execute<T>(request: RequestType, dispatch: (state: NetworkState<T>) => void, schema: ZodSchema<T> | undefined) {
+      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 <Context.Provider value={contextValue}>
+    {children}
+  </Context.Provider>
+}
+
+export interface StatusTrapProps {
+  type: 'pending' | 'error' | 'pending + error';
+  propagate?: boolean;
+}
+
+/**
+ * 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.
+ */
+export function StatusTrap({
+                             children,
+                             type,
+                             propagate = true,
+                           }: PropsWithChildren<StatusTrapProps>) {
+  const ctx = useContext(Context);
+
+  const [requests, setRequests] = useState<string[]>([]);
+
+  const shouldHandleEvent = useCallback(
+    (state: NetworkState) => {
+      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: NetworkAction<any, any>) => {
+      if (!event.handled) {
+        if (shouldHandleEvent(event.state)) {
+          setRequests((prev) => [...prev, event.key]);
+          if (!propagate) {
+            ctx.dispatch({
+              ...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 (
+    <Context.Provider
+      value={{
+        ...ctx,
+        dispatch,
+        filteredState,
+      }}
+    >
+      {children}
+    </Context.Provider>
+  );
+}
+
+export interface NetworkStateProps<T, E = unknown> {
+  key: string;
+  operation: string;
+  source: string;
+  schema?: ZodSchema<T>;
+  errorSchema?: ZodSchema<E>;
+  debounceDelay?: number;
+}
+
+/**
+ * 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.
+ */
+export function useNetworkState<T, E = unknown>({
+                                                  key,
+                                                  operation,
+                                                  source,
+                                                  schema,
+                                                  errorSchema,
+                                                  debounceDelay: requestDebounceDelay,
+                                                }: NetworkStateProps<T>): [
+  NetworkState<T, E>,
+  (request: RequestType) => void,
+  clear: () => void,
+  (state: NetworkState<T, E>) => void
+] {
+  const context = useContext(Context);
+
+  const [abortController, setAbortController] = useState<AbortController>();
+
+  const networkState = useMemo(() => {
+    logger.info(`Updating status ${key} ${operation} ${source}`);
+    logger.debug(`⇦`, context.state?.[`${source}:${operation}:${key}`])
+    return (
+      (context.state?.[`${source}:${operation}:${key}`] as NetworkState<T>) ??
+      init()
+    );
+  }, [context.state?.[`${source}:${operation}:${key}`]]);
+
+  const dispatch = useCallback(
+    (state: NetworkState<T>) => {
+      context.dispatch({ key, operation, source, state });
+    },
+    [key, operation, source, context.dispatch]
+  );
+
+  const debounceDelay = useMemo(() => {
+    return requestDebounceDelay ?? context.configs?.debounceDelay ?? 0;
+  }, [context.configs, requestDebounceDelay]);
+
+  const execute = useCallback(
+    async (request: RequestType) => {
+      logger.info(`Executing request ${key} ${operation} ${source}`);
+      logger.debug(`⇨`, request)
+
+      const abortController = new AbortController();
+      setAbortController(abortController);
+
+      const requestConfig: RequestType = {
+        ...request,
+        onUploadProgress(event: AxiosProgressEvent) {
+          dispatch(
+            pending({
+              type: 'upload',
+              loaded: event.loaded,
+              total: event.total,
+            })
+          );
+          request.onUploadProgress?.(event);
+        },
+        onDownloadProgress(event: AxiosProgressEvent) {
+          dispatch(
+            pending({
+              type: 'download',
+              loaded: event.loaded,
+              total: event.total,
+            })
+          );
+          request.onDownloadProgress?.(event);
+        },
+        signal: abortController.signal,
+      };
+
+      await context.execute(requestConfig, dispatch, schema, errorSchema);
+    },
+    [networkState, context.dispatch, axios]
+  );
+
+  const deboundedExecute = useMemo(
+    () => debounce(execute, 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?.abort();
+      return undefined;
+    });
+  }, [dispatch, abortController]);
+
+  return [networkState, deboundedExecute, clear, dispatch];
+}
+
+function debounce<T extends (...args: any[]) => void>(func: T, delay: number) {
+  let timeoutId: any;
+
+  return (...args: Parameters<T>) => {
+    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.
+ */
+export 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 {
+          ...(state as ErrorState<unknown>),
+          source,
+          operation,
+          key,
+        } satisfies ErrorWithContext;
+      });
+  }, [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.
+ */
+export function useCentralPendingState() {
+  const ctx = useContext(Context);
+
+  const result: NetworkState = useMemo(() => {
+    const pendingStates = Object.values(ctx.filteredState).filter(isPending);
+    if (!pendingStates.length) {
+      return init();
+    }
+
+    const progress = pendingStates
+      .filter((a) => a.progress)
+      .reduce(
+        (progress, current) => {
+          return {
+            total: progress.total + (current.progress?.total ?? 0),
+            loaded: progress.loaded + (current.progress?.loaded ?? 0),
+          };
+        },
+        { total: 0, loaded: 0 } satisfies Progress
+      );
+    return pending(progress.total ? progress : undefined);
+  }, [ctx.filteredState]);
+
+  return result;
+}

package/src/logger.ts

@@ -0,0 +1,13 @@
+import log from 'loglevel';
+
+// Set the default logging level (can be overridden via environment variables)
+log.setLevel(process.env.LOG_LEVEL as log.LogLevelDesc || 'error');
+
+const logWrapper = {
+  info: (msg: string, meta?: object) => meta ? log.info(msg, meta) : log.info(msg),
+  warn: (msg: string, meta?: object) => meta ? log.warn(msg, meta) : log.warn(msg),
+  error: (msg: string, meta?: object) => meta ? log.error(msg, meta) : log.error(msg),
+  debug: (msg: string, meta?: object) => meta ? log.debug(msg, meta) : log.debug(msg),
+};
+
+export default logWrapper;

package/src/media-type-utils.ts

@@ -0,0 +1,184 @@
+import { ZodSchema } from 'zod';
+import { XMLParser } from 'fast-xml-parser';
+
+type Encoders = {
+  [k: string]: <T>(request: T,
+                   mediaType: string,
+                   schema: ZodSchema) => Promise<any>;
+};
+
+const encoders: Encoders = {};
+
+export function encode<T>(request: T, mediaType: string, schema: ZodSchema) {
+  if (encoders[mediaType]) {
+    return encoders[mediaType](request, mediaType, schema);
+  }
+  return request;
+}
+
+encoders['application/json'] = async (request) => {
+  return request;
+}
+
+function appendFormData(
+  formData: FormData,
+  data: any,
+  parentKey: string
+): void {
+  if (data instanceof Blob || typeof data === 'string') {
+    formData.append(parentKey, data);
+  } else if (data !== null && typeof data === 'object') {
+    if (Array.isArray(data)) {
+      data.forEach((item: any) => {
+        const key = `${parentKey}`;
+        appendFormData(formData, item, key);
+      });
+    } else {
+      Object.keys(data).forEach((key: string) => {
+        const newKey = parentKey ? `${parentKey}[${key}]` : key;
+        appendFormData(formData, data[key], newKey);
+      });
+    }
+  } else {
+    formData.append(parentKey, data == null ? '' : String(data));
+  }
+}
+
+
+encoders['multipart/form-data'] = async (request) => {
+  const _request = request as Record<string, any>;
+  const formData = new FormData();
+  Object.keys(_request).forEach((key: string) => {
+    appendFormData(formData, _request[key], key);
+  });
+  return formData;
+}
+
+encoders['application/octet-stream'] = async (request) => {
+  return request;
+}
+
+encoders['application/x-www-form-urlencoded'] = async (request) => {
+  const formData = new FormData();
+  for (const key in request) {
+    const value = request[key];
+    formData.append(key, value instanceof Blob || typeof value === 'string' ? value : String(value));
+  }
+  return formData;
+}
+
+type Transformers = {
+  [k: string]: <T>(
+    request: Request,
+    mediaType: string,
+    schema: ZodSchema
+  ) => Promise<T>;
+};
+
+const transformers: Transformers = {};
+
+export function transform<T>(
+  request: Request,
+  mediaType: string,
+  schema: ZodSchema
+): Promise<T> {
+  if (transformers[mediaType]) {
+    return transformers[mediaType](request, mediaType, schema);
+  }
+  throw new Error(`Unsupported media type: ` + mediaType);
+}
+
+transformers['application/json'] = async (request, mediaType, schema) => {
+  return schema.parse(await request.json());
+};
+
+transformers['multipart/form-data'] = async (request, mediaType, schema) => {
+  const formData = await request.formData();
+  const content: Record<string, any> = {};
+  formData.forEach((value, key) => {
+    if (content[key]) {
+      if (!(content[key] instanceof Array)) {
+        content[key] = [content[key]];
+      }
+      content[key].push(value);
+    } else {
+      content[key] = value
+    }
+  });
+  return schema.parse(content);
+};
+
+transformers['application/octet-stream'] = async (
+  request,
+  mediaType,
+  schema
+) => {
+  return schema.parse(
+    new Blob([await request.arrayBuffer()], {
+      type: 'application/octet-stream',
+    })
+  );
+};
+
+transformers['application/x-www-form-urlencoded'] = async (
+  request,
+  mediaType,
+  schema
+) => {
+  const formData = await request.formData();
+  const content: Record<string, any> = {};
+  formData.forEach((value, key) => (content[key] = value));
+  return schema.parse(content);
+};
+
+transformers['application/xml'] = async (request, mediaType, schema) => {
+  const xmlParser = new XMLParser();
+  const content = await xmlParser.parse(await request.text());
+  return schema.parse(await content);
+};
+
+transformers['text/plain'] = async (request, mediaType, schema) => {
+  return schema.parse(await request.text());
+};
+
+transformers['text/html'] = async (request, mediaType, schema) => {
+  return schema.parse(await request.text());
+};
+
+transformers['text/css'] = async (request, mediaType, schema) => {
+  return schema.parse(await request.text());
+};
+
+transformers['text/javascript'] = async (request, mediaType, schema) => {
+  return schema.parse(await request.text());
+};
+
+type ResponseTransformers = {
+  [k: string]: <T>(
+    data: any,
+    mediaType: string,
+    schema: ZodSchema
+  ) => Promise<T>;
+};
+
+const responseTransformers: ResponseTransformers = {};
+
+responseTransformers['application/json'] = async (data, mediaType, schema) => {
+  return schema.parse(data);
+};
+
+responseTransformers['application/xml'] = async (data, mediaType, schema) => {
+  const parsed = new XMLParser().parse(data);
+  return schema.parse(parsed);
+}
+
+export async function transformResponse<T>(
+  data: any,
+  mediaType: string,
+  schema: ZodSchema
+): Promise<T> {
+  if (responseTransformers[mediaType]) {
+    return await responseTransformers[mediaType](data, mediaType, schema);
+  }
+  return data
+}