@alepha/react 0.11.3 → 0.11.4

package/src/hooks/useAction.ts

@@ -0,0 +1,467 @@
+import {
+  DateTimeProvider,
+  type DurationLike,
+  type Interval,
+  type Timeout,
+} from "@alepha/datetime";
+import {
+  type DependencyList,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { useAlepha } from "./useAlepha.ts";
+import { useInject } from "./useInject.ts";
+
+/**
+ * Hook for handling async actions with automatic error handling and event emission.
+ *
+ * By default, prevents concurrent executions - if an action is running and you call it again,
+ * the second call will be ignored. Use `debounce` option to delay execution instead.
+ *
+ * Emits lifecycle events:
+ * - `react:action:begin` - When action starts
+ * - `react:action:success` - When action completes successfully
+ * - `react:action:error` - When action throws an error
+ * - `react:action:end` - Always emitted at the end
+ *
+ * @example Basic usage
+ * ```tsx
+ * const action = useAction({
+ *   handler: async (data) => {
+ *     await api.save(data);
+ *   }
+ * }, []);
+ *
+ * <button onClick={() => action.run(data)} disabled={action.loading}>
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example With debounce (search input)
+ * ```tsx
+ * const search = useAction({
+ *   handler: async (query: string) => {
+ *     await api.search(query);
+ *   },
+ *   debounce: 300 // Wait 300ms after last call
+ * }, []);
+ *
+ * <input onChange={(e) => search.run(e.target.value)} />
+ * ```
+ *
+ * @example Run on component mount
+ * ```tsx
+ * const fetchData = useAction({
+ *   handler: async () => {
+ *     const data = await api.getData();
+ *     return data;
+ *   },
+ *   runOnInit: true // Runs once when component mounts
+ * }, []);
+ * ```
+ *
+ * @example Run periodically (polling)
+ * ```tsx
+ * const pollStatus = useAction({
+ *   handler: async () => {
+ *     const status = await api.getStatus();
+ *     return status;
+ *   },
+ *   runEvery: 5000 // Run every 5 seconds
+ * }, []);
+ *
+ * // Or with duration tuple
+ * const pollStatus = useAction({
+ *   handler: async () => {
+ *     const status = await api.getStatus();
+ *     return status;
+ *   },
+ *   runEvery: [30, 'seconds'] // Run every 30 seconds
+ * }, []);
+ * ```
+ *
+ * @example With AbortController
+ * ```tsx
+ * const fetch = useAction({
+ *   handler: async (url, { signal }) => {
+ *     const response = await fetch(url, { signal });
+ *     return response.json();
+ *   }
+ * }, []);
+ * // Automatically cancelled on unmount or when new request starts
+ * ```
+ *
+ * @example With error handling
+ * ```tsx
+ * const deleteAction = useAction({
+ *   handler: async (id: string) => {
+ *     await api.delete(id);
+ *   },
+ *   onError: (error) => {
+ *     if (error.code === 'NOT_FOUND') {
+ *       // Custom error handling
+ *     }
+ *   }
+ * }, []);
+ *
+ * {deleteAction.error && <div>Error: {deleteAction.error.message}</div>}
+ * ```
+ *
+ * @example Global error handling
+ * ```tsx
+ * // In your root app setup
+ * alepha.events.on("react:action:error", ({ error }) => {
+ *   toast.danger(error.message);
+ *   Sentry.captureException(error);
+ * });
+ * ```
+ */
+export function useAction<Args extends any[], Result = void>(
+  options: UseActionOptions<Args, Result>,
+  deps: DependencyList,
+): UseActionReturn<Args, Result> {
+  const alepha = useAlepha();
+  const dateTimeProvider = useInject(DateTimeProvider);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | undefined>();
+  const isExecutingRef = useRef(false);
+  const debounceTimerRef = useRef<Timeout | undefined>(undefined);
+  const abortControllerRef = useRef<AbortController | undefined>(undefined);
+  const isMountedRef = useRef(true);
+  const intervalRef = useRef<Interval | undefined>(undefined);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      isMountedRef.current = false;
+
+      // clear debounce timer
+      if (debounceTimerRef.current) {
+        dateTimeProvider.clearTimeout(debounceTimerRef.current);
+        debounceTimerRef.current = undefined;
+      }
+
+      // clear interval
+      if (intervalRef.current) {
+        dateTimeProvider.clearInterval(intervalRef.current);
+        intervalRef.current = undefined;
+      }
+
+      // abort in-flight request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+        abortControllerRef.current = undefined;
+      }
+    };
+  }, []);
+
+  const executeAction = useCallback(
+    async (...args: Args): Promise<Result | undefined> => {
+      // Prevent concurrent executions
+      if (isExecutingRef.current) {
+        return;
+      }
+
+      // Abort previous request if still running
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      // Create new AbortController for this request
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+
+      isExecutingRef.current = true;
+      setLoading(true);
+      setError(undefined);
+
+      await alepha.events.emit("react:action:begin", {
+        type: "custom",
+        id: options.id,
+      });
+
+      try {
+        // Pass abort signal as last argument to handler
+        const result = await options.handler(...args, {
+          signal: abortController.signal,
+        } as any);
+
+        // Only update state if still mounted and not aborted
+        if (!isMountedRef.current || abortController.signal.aborted) {
+          return;
+        }
+
+        await alepha.events.emit("react:action:success", {
+          type: "custom",
+          id: options.id,
+        });
+
+        if (options.onSuccess) {
+          await options.onSuccess(result);
+        }
+
+        return result;
+      } catch (err) {
+        // Ignore abort errors
+        if (err instanceof Error && err.name === "AbortError") {
+          return;
+        }
+
+        // Only update state if still mounted
+        if (!isMountedRef.current) {
+          return;
+        }
+
+        const error = err as Error;
+        setError(error);
+
+        await alepha.events.emit("react:action:error", {
+          type: "custom",
+          id: options.id,
+          error,
+        });
+
+        if (options.onError) {
+          await options.onError(error);
+        } else {
+          // Re-throw if no custom error handler
+          throw error;
+        }
+      } finally {
+        isExecutingRef.current = false;
+        setLoading(false);
+
+        await alepha.events.emit("react:action:end", {
+          type: "custom",
+          id: options.id,
+        });
+
+        // Clean up abort controller
+        if (abortControllerRef.current === abortController) {
+          abortControllerRef.current = undefined;
+        }
+      }
+    },
+    [...deps, options.id, options.onError, options.onSuccess],
+  );
+
+  const handler = useCallback(
+    async (...args: Args): Promise<Result | undefined> => {
+      if (options.debounce) {
+        // clear existing timer
+        if (debounceTimerRef.current) {
+          dateTimeProvider.clearTimeout(debounceTimerRef.current);
+        }
+
+        // Set new timer
+        return new Promise((resolve) => {
+          debounceTimerRef.current = dateTimeProvider.createTimeout(
+            async () => {
+              const result = await executeAction(...args);
+              resolve(result);
+            },
+            options.debounce ?? 0,
+          );
+        });
+      }
+
+      return executeAction(...args);
+    },
+    [executeAction, options.debounce],
+  );
+
+  const cancel = useCallback(() => {
+    // clear debounce timer
+    if (debounceTimerRef.current) {
+      dateTimeProvider.clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+    }
+
+    // abort in-flight request
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+      abortControllerRef.current = undefined;
+    }
+
+    // reset state
+    if (isMountedRef.current) {
+      isExecutingRef.current = false;
+      setLoading(false);
+    }
+  }, []);
+
+  // Run action on mount if runOnInit is true
+  useEffect(() => {
+    if (options.runOnInit) {
+      handler(...([] as any));
+    }
+  }, []);
+
+  // Run action periodically if runEvery is specified
+  useEffect(() => {
+    if (!options.runEvery) {
+      return;
+    }
+
+    // Set up interval
+    intervalRef.current = dateTimeProvider.createInterval(
+      () => handler(...([] as any)),
+      options.runEvery,
+      true,
+    );
+
+    // cleanup on unmount or when runEvery changes
+    return () => {
+      if (intervalRef.current) {
+        dateTimeProvider.clearInterval(intervalRef.current);
+        intervalRef.current = undefined;
+      }
+    };
+  }, [handler, options.runEvery]);
+
+  return {
+    run: handler,
+    loading,
+    error,
+    cancel,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Context object passed as the last argument to action handlers.
+ * Contains an AbortSignal that can be used to cancel the request.
+ */
+export interface ActionContext {
+  /**
+   * AbortSignal that can be passed to fetch or other async operations.
+   * The signal will be aborted when:
+   * - The component unmounts
+   * - A new action is triggered (cancels previous)
+   * - The cancel() method is called
+   *
+   * @example
+   * ```tsx
+   * const action = useAction({
+   *   handler: async (url, { signal }) => {
+   *     const response = await fetch(url, { signal });
+   *     return response.json();
+   *   }
+   * }, []);
+   * ```
+   */
+  signal: AbortSignal;
+}
+
+export interface UseActionOptions<Args extends any[] = any[], Result = any> {
+  /**
+   * The async action handler function.
+   * Receives the action arguments plus an ActionContext as the last parameter.
+   */
+  handler: (...args: [...Args, ActionContext]) => Promise<Result>;
+
+  /**
+   * Custom error handler. If provided, prevents default error re-throw.
+   */
+  onError?: (error: Error) => void | Promise<void>;
+
+  /**
+   * Custom success handler.
+   */
+  onSuccess?: (result: Result) => void | Promise<void>;
+
+  /**
+   * Optional identifier for this action (useful for debugging/analytics)
+   */
+  id?: string;
+
+  /**
+   * Debounce delay in milliseconds. If specified, the action will only execute
+   * after the specified delay has passed since the last call. Useful for search inputs
+   * or other high-frequency events.
+   *
+   * @example
+   * ```tsx
+   * // Execute search 300ms after user stops typing
+   * const search = useAction({ handler: search, debounce: 300 }, [])
+   * ```
+   */
+  debounce?: number;
+
+  /**
+   * If true, the action will be executed once when the component mounts.
+   *
+   * @example
+   * ```tsx
+   * const fetchData = useAction({
+   *   handler: async () => await api.getData(),
+   *   runOnInit: true
+   * }, []);
+   * ```
+   */
+  runOnInit?: boolean;
+
+  /**
+   * If specified, the action will be executed periodically at the given interval.
+   * The interval is specified as a DurationLike value (number in ms, Duration object, or [number, unit] tuple).
+   *
+   * @example
+   * ```tsx
+   * // Run every 5 seconds
+   * const poll = useAction({
+   *   handler: async () => await api.poll(),
+   *   runEvery: 5000
+   * }, []);
+   * ```
+   *
+   * @example
+   * ```tsx
+   * // Run every 1 minute
+   * const poll = useAction({
+   *   handler: async () => await api.poll(),
+   *   runEvery: [1, 'minute']
+   * }, []);
+   * ```
+   */
+  runEvery?: DurationLike;
+}
+
+export interface UseActionReturn<Args extends any[], Result> {
+  /**
+   * Execute the action with the provided arguments.
+   *
+   * @example
+   * ```tsx
+   * const action = useAction({ handler: async (data) => { ... } }, []);
+   * action.run(data);
+   * ```
+   */
+  run: (...args: Args) => Promise<Result | undefined>;
+
+  /**
+   * Loading state - true when action is executing.
+   */
+  loading: boolean;
+
+  /**
+   * Error state - contains error if action failed, undefined otherwise.
+   */
+  error?: Error;
+
+  /**
+   * Cancel any pending debounced action or abort the current in-flight request.
+   *
+   * @example
+   * ```tsx
+   * const action = useAction({ ... }, []);
+   *
+   * <button onClick={action.cancel} disabled={!action.loading}>
+   *   Cancel
+   * </button>
+   * ```
+   */
+  cancel: () => void;
+}

package/src/hooks/useActive.ts

@@ -17,13 +17,7 @@ export const useActive = (args: string | UseActiveOptions): UseActiveHook => {
   const options: UseActiveOptions =
     typeof args === "string" ? { href: args } : { ...args, href: args.href };
   const href = options.href;
-
-  let isActive =
-    current === href || current === `${href}/` || `${current}/` === href;
-
-  if (options.startWith && !isActive) {
-    isActive = current.startsWith(href);
-  }
+  const isActive = router.isActive(href, options);
 
   return {
     isPending,

package/src/hooks/useEvents.ts

@@ -0,0 +1,51 @@
+import type { Async, Hook, Hooks } from "@alepha/core";
+import { type DependencyList, useEffect } from "react";
+import { useAlepha } from "./useAlepha.ts";
+
+/**
+ * Allow subscribing to multiple Alepha events. See {@link Hooks} for available events.
+ *
+ * useEvents is fully typed to ensure correct event callback signatures.
+ *
+ * @example
+ * ```tsx
+ * useEvents(
+ *   {
+ *     "react:transition:begin": (ev) => {
+ *       console.log("Transition began to:", ev.to);
+ *     },
+ *     "react:transition:error": {
+ *       priority: "first",
+ *       callback: (ev) => {
+ *         console.error("Transition error:", ev.error);
+ *       },
+ *     },
+ *   },
+ *   [],
+ * );
+ * ```
+ */
+export const useEvents = (opts: UseEvents, deps: DependencyList) => {
+  const alepha = useAlepha();
+
+  useEffect(() => {
+    if (!alepha.isBrowser()) {
+      return;
+    }
+
+    const subs: Function[] = [];
+    for (const [name, hook] of Object.entries(opts)) {
+      subs.push(alepha.events.on(name as any, hook as any));
+    }
+
+    return () => {
+      for (const clear of subs) {
+        clear();
+      }
+    };
+  }, deps);
+};
+
+type UseEvents = {
+  [T in keyof Hooks]?: Hook<T> | ((payload: Hooks[T]) => Async<void>);
+};

package/src/index.browser.ts

@@ -1,4 +1,5 @@
 import { $module } from "@alepha/core";
+import { AlephaDateTime } from "@alepha/datetime";
 import { AlephaServer } from "@alepha/server";
 import { AlephaServerLinks } from "@alepha/server-links";
 import { $page } from "./descriptors/$page.ts";
@@ -6,6 +7,7 @@ import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
 import { ReactBrowserRendererProvider } from "./providers/ReactBrowserRendererProvider.ts";
 import { ReactBrowserRouterProvider } from "./providers/ReactBrowserRouterProvider.ts";
 import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
+import { ReactPageService } from "./services/ReactPageService.ts";
 import { ReactRouter } from "./services/ReactRouter.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -26,9 +28,11 @@ export const AlephaReact = $module({
     ReactBrowserProvider,
     ReactRouter,
     ReactBrowserRendererProvider,
+    ReactPageService,
   ],
   register: (alepha) =>
     alepha
+      .with(AlephaDateTime)
       .with(AlephaServer)
       .with(AlephaServerLinks)
       .with(ReactPageProvider)

package/src/index.shared.ts

@@ -8,13 +8,14 @@ export * from "./contexts/AlephaContext.ts";
 export * from "./contexts/RouterLayerContext.ts";
 export * from "./descriptors/$page.ts";
 export * from "./errors/Redirection.ts";
+export * from "./hooks/useAction.ts";
 export * from "./hooks/useActive.ts";
 export * from "./hooks/useAlepha.ts";
 export * from "./hooks/useClient.ts";
+export * from "./hooks/useEvents.ts";
 export * from "./hooks/useInject.ts";
 export * from "./hooks/useQueryParams.ts";
 export * from "./hooks/useRouter.ts";
-export * from "./hooks/useRouterEvents.ts";
 export * from "./hooks/useRouterState.ts";
 export * from "./hooks/useSchema.ts";
 export * from "./hooks/useStore.ts";

package/src/index.ts

@@ -1,4 +1,5 @@
 import { $module } from "@alepha/core";
+import { AlephaDateTime } from "@alepha/datetime";
 import { AlephaServer, type ServerRequest } from "@alepha/server";
 import { AlephaServerCache } from "@alepha/server-cache";
 import { AlephaServerLinks } from "@alepha/server-links";
@@ -10,6 +11,8 @@ import {
   type ReactRouterState,
 } from "./providers/ReactPageProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
+import { ReactPageServerService } from "./services/ReactPageServerService.ts";
+import { ReactPageService } from "./services/ReactPageService.ts";
 import { ReactRouter } from "./services/ReactRouter.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -27,34 +30,92 @@ declare module "@alepha/core" {
   }
 
   interface Hooks {
+    /**
+     * Fires when the React application is starting to be rendered on the server.
+     */
     "react:server:render:begin": {
       request?: ServerRequest;
       state: ReactRouterState;
     };
+    /**
+     * Fires when the React application has been rendered on the server.
+     */
     "react:server:render:end": {
       request?: ServerRequest;
       state: ReactRouterState;
       html: string;
     };
     // -----------------------------------------------------------------------------------------------------------------
+    /**
+     * Fires when the React application is being rendered on the browser.
+     */
     "react:browser:render": {
       root: HTMLElement;
       element: ReactNode;
       state: ReactRouterState;
       hydration?: ReactHydrationState;
     };
+    // -----------------------------------------------------------------------------------------------------------------
+    // TOP LEVEL: All user actions (forms, transitions, custom actions)
+    /**
+     * Fires when a user action is starting.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:begin": {
+      type: string;
+      id?: string;
+    };
+    /**
+     * Fires when a user action has succeeded.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:success": {
+      type: string;
+      id?: string;
+    };
+    /**
+     * Fires when a user action has failed.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:error": {
+      type: string;
+      id?: string;
+      error: Error;
+    };
+    /**
+     * Fires when a user action has completed, regardless of success or failure.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:end": {
+      type: string;
+      id?: string;
+    };
+    // -----------------------------------------------------------------------------------------------------------------
+    // SPECIFIC: Route transitions
+    /**
+     * Fires when a route transition is starting.
+     */
     "react:transition:begin": {
       previous: ReactRouterState;
       state: ReactRouterState;
       animation?: PageAnimation;
     };
+    /**
+     * Fires when a route transition has succeeded.
+     */
     "react:transition:success": {
       state: ReactRouterState;
     };
+    /**
+     * Fires when a route transition has failed.
+     */
     "react:transition:error": {
       state: ReactRouterState;
       error: Error;
     };
+    /**
+     * Fires when a route transition has completed, regardless of success or failure.
+     */
     "react:transition:end": {
       state: ReactRouterState;
     };
@@ -76,12 +137,23 @@ declare module "@alepha/core" {
 export const AlephaReact = $module({
   name: "alepha.react",
   descriptors: [$page],
-  services: [ReactServerProvider, ReactPageProvider, ReactRouter],
+  services: [
+    ReactServerProvider,
+    ReactPageProvider,
+    ReactRouter,
+    ReactPageService,
+    ReactPageServerService,
+  ],
   register: (alepha) =>
     alepha
+      .with(AlephaDateTime)
       .with(AlephaServer)
       .with(AlephaServerCache)
       .with(AlephaServerLinks)
+      .with({
+        provide: ReactPageService,
+        use: ReactPageServerService,
+      })
       .with(ReactServerProvider)
       .with(ReactPageProvider)
       .with(ReactRouter),