@uploadista/react 0.0.15-beta.2 → 0.0.15-beta.4

package/dist/{use-uploadista-client--ivZPO88.d.mts → use-uploadista-client-CRUhyWoy.d.mts}

@@ -1,6 +1,6 @@
-import { BrowserUploadInput, FlowUploadOptions, UploadistaClientOptions, createUploadistaClient } from "@uploadista/client-browser";
-import { FlowUploadState, FlowUploadStatus, UploadMetrics, UploadState, UploadStatus } from "@uploadista/client-core";
 import { UploadFile } from "@uploadista/core/types";
+import { FlowUploadState, FlowUploadStatus, UploadMetrics, UploadState, UploadStatus } from "@uploadista/client-core";
+import { BrowserUploadInput, FlowUploadOptions, UploadistaClientOptions, createUploadistaClient } from "@uploadista/client-browser";
 
 //#region src/hooks/use-drag-drop.d.ts
 interface DragDropOptions {
@@ -209,8 +209,8 @@ interface UseFlowUploadReturn<TOutput = UploadFile> {
  * The flow engine processes the uploaded file through a DAG of nodes, which can
  * perform operations like image optimization, storage saving, webhooks, etc.
  *
- * Must be used within an UploadistaProvider. Flow events (node start/end, flow complete)
- * are automatically subscribed through the provider context.
+ * Must be used within FlowManagerProvider (which must be within UploadistaProvider).
+ * Flow events are automatically routed by the provider to the appropriate manager.
  *
  * @template TOutput - Type of the final result from the flow (defaults to UploadFile)
  * @param options - Flow upload configuration including flow ID and event handlers
@@ -684,4 +684,4 @@ interface UseUploadistaClientReturn {
 declare function useUploadistaClient(options: UseUploadistaClientOptions): UseUploadistaClientReturn;
 //#endregion
 export { useFlowUpload as _, MultiUploadState as a, UseDragDropReturn as b, useMultiUpload as c, UseUploadOptions as d, UseUploadReturn as f, UseFlowUploadReturn as g, FlowUploadStatus as h, MultiUploadOptions as i, UploadState as l, FlowUploadState as m, UseUploadistaClientReturn as n, UploadItem as o, useUpload as p, useUploadistaClient as r, UseMultiUploadReturn as s, UseUploadistaClientOptions as t, UploadStatus as u, DragDropOptions as v, useDragDrop as x, DragDropState as y };
-//# sourceMappingURL=use-uploadista-client--ivZPO88.d.mts.map
+//# sourceMappingURL=use-uploadista-client-CRUhyWoy.d.mts.map

package/dist/use-uploadista-client-CRUhyWoy.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-uploadista-client-CRUhyWoy.d.mts","names":[],"sources":["../src/hooks/use-drag-drop.ts","../src/hooks/use-flow-upload.ts","../src/hooks/use-upload.ts","../src/hooks/use-multi-upload.ts","../src/hooks/use-uploadista-client.ts"],"sourcesContent":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uploadista/react",
   "type": "module",
-  "version": "0.0.15-beta.2",
+  "version": "0.0.15-beta.4",
   "description": "React client for Uploadista",
   "license": "MIT",
   "author": "Uploadista",
@@ -22,16 +22,16 @@
   "dependencies": {
     "react": "19.2.0",
     "react-dom": "19.2.0",
-    "@uploadista/core": "0.0.15-beta.2",
-    "@uploadista/client-core": "0.0.15-beta.2",
-    "@uploadista/client-browser": "0.0.15-beta.2"
+    "@uploadista/core": "0.0.15-beta.4",
+    "@uploadista/client-core": "0.0.15-beta.4",
+    "@uploadista/client-browser": "0.0.15-beta.4"
   },
   "devDependencies": {
     "@types/react": "19.2.4",
     "@types/react-dom": "19.2.3",
     "tsdown": "0.16.4",
     "vitest": "4.0.8",
-    "@uploadista/typescript-config": "0.0.15-beta.2"
+    "@uploadista/typescript-config": "0.0.15-beta.4"
   },
   "scripts": {
     "build": "tsdown",

package/src/components/uploadista-provider.tsx

@@ -2,6 +2,7 @@
 import type { UploadistaEvent } from "@uploadista/client-browser";
 import type React from "react";
 import { createContext, useCallback, useContext, useMemo, useRef } from "react";
+import { FlowManagerProvider } from "../contexts/flow-manager-context";
 import {
   type UseUploadistaClientOptions,
   type UseUploadistaClientReturn,
@@ -16,10 +17,10 @@ import {
  * @property baseUrl - API base URL for uploads
  * @property storageId - Default storage identifier
  * @property chunkSize - Upload chunk size in bytes
- * @property onEvent - Global event handler for all upload events
  * @property ... - All other UploadistaClientOptions
  */
-export interface UploadistaProviderProps extends UseUploadistaClientOptions {
+export interface UploadistaProviderProps
+  extends Omit<UseUploadistaClientOptions, "onEvent"> {
   /**
    * Children components that will have access to the upload client
    */
@@ -53,9 +54,6 @@ const UploadistaContext = createContext<UploadistaContextValue | null>(null);
  *       baseUrl="https://api.example.com"
  *       storageId="my-storage"
  *       chunkSize={1024 * 1024} // 1MB chunks
- *       onEvent={(event) => {
- *         console.log('Global upload event:', event);
- *       }}
  *     >
  *       <UploadInterface />
  *     </UploadistaProvider>
@@ -89,34 +87,21 @@ export function UploadistaProvider({
     new Set(),
   );
 
-  // Wrap the original onEvent to broadcast to subscribers
-  const wrappedOnEvent = useCallback(
-    (event: UploadistaEvent) => {
-      console.log("[UploadistaProvider] Received event:", event);
-
-      // Call original handler if provided
-      options.onEvent?.(event);
-
-      // Broadcast to all subscribers
-      console.log(
-        "[UploadistaProvider] Broadcasting to",
-        eventSubscribersRef.current.size,
-        "subscribers",
-      );
-      eventSubscribersRef.current.forEach((handler) => {
-        try {
-          handler(event);
-        } catch (err) {
-          console.error("Error in event subscriber:", err);
-        }
-      });
-    },
-    [options.onEvent],
-  );
+  // Event handler that broadcasts to all subscribers
+  const handleEvent = useCallback((event: UploadistaEvent) => {
+    // Broadcast to all subscribers
+    eventSubscribersRef.current.forEach((handler) => {
+      try {
+        handler(event);
+      } catch (err) {
+        console.error("Error in event subscriber:", err);
+      }
+    });
+  }, []);
 
   const uploadClient = useUploadistaClient({
     ...options,
-    onEvent: wrappedOnEvent,
+    onEvent: handleEvent,
   });
 
   const subscribeToEvents = useCallback(
@@ -140,7 +125,7 @@ export function UploadistaProvider({
 
   return (
     <UploadistaContext.Provider value={contextValue}>
-      {children}
+      <FlowManagerProvider>{children}</FlowManagerProvider>
     </UploadistaContext.Provider>
   );
 }

package/src/contexts/flow-manager-context.tsx

@@ -0,0 +1,230 @@
+import type { UploadistaEvent } from "@uploadista/client-browser";
+import {
+  FlowManager,
+  type FlowManagerCallbacks,
+  type FlowUploadState,
+} from "@uploadista/client-core";
+import { EventType, type FlowEvent } from "@uploadista/core/flow";
+import { UploadEventType } from "@uploadista/core/types";
+import type { ReactNode } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+} from "react";
+import { useUploadistaContext } from "../components/uploadista-provider";
+import type { FlowUploadOptions } from "@uploadista/client-browser";
+
+/**
+ * Type guard to check if an event is a flow event
+ */
+function isFlowEvent(event: UploadistaEvent): event is FlowEvent {
+  const flowEvent = event as FlowEvent;
+  return (
+    flowEvent.eventType === EventType.FlowStart ||
+    flowEvent.eventType === EventType.FlowEnd ||
+    flowEvent.eventType === EventType.FlowError ||
+    flowEvent.eventType === EventType.NodeStart ||
+    flowEvent.eventType === EventType.NodeEnd ||
+    flowEvent.eventType === EventType.NodePause ||
+    flowEvent.eventType === EventType.NodeResume ||
+    flowEvent.eventType === EventType.NodeError
+  );
+}
+
+/**
+ * Internal manager registry entry with ref counting
+ */
+interface ManagerEntry<TOutput> {
+  manager: FlowManager<unknown, TOutput>;
+  refCount: number;
+  flowId: string;
+}
+
+/**
+ * Context value providing access to flow managers
+ */
+interface FlowManagerContextValue {
+  /**
+   * Get or create a flow manager for the given flow ID.
+   * Increments ref count - must call releaseManager when done.
+   *
+   * @param flowId - Unique identifier for the flow
+   * @param callbacks - Callbacks for state changes and lifecycle events
+   * @param options - Flow configuration options
+   * @returns FlowManager instance
+   */
+  getManager: <TOutput = unknown>(
+    flowId: string,
+    callbacks: FlowManagerCallbacks<TOutput>,
+    options: FlowUploadOptions<TOutput>,
+  ) => FlowManager<unknown, TOutput>;
+
+  /**
+   * Release a flow manager reference.
+   * Decrements ref count and cleans up when reaching zero.
+   *
+   * @param flowId - Unique identifier for the flow to release
+   */
+  releaseManager: (flowId: string) => void;
+}
+
+const FlowManagerContext = createContext<FlowManagerContextValue | undefined>(
+  undefined,
+);
+
+/**
+ * Props for FlowManagerProvider
+ */
+interface FlowManagerProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Provider that manages FlowManager instances with ref counting and event routing.
+ * Ensures managers persist across component re-renders and are only cleaned up
+ * when all consuming components unmount.
+ *
+ * This provider should be nested inside UploadistaProvider to access the upload client
+ * and event subscription system.
+ *
+ * @example
+ * ```tsx
+ * <UploadistaProvider baseUrl="https://api.example.com" storageId="default">
+ *   <FlowManagerProvider>
+ *     <App />
+ *   </FlowManagerProvider>
+ * </UploadistaProvider>
+ * ```
+ */
+export function FlowManagerProvider({ children }: FlowManagerProviderProps) {
+  const { client, subscribeToEvents } = useUploadistaContext();
+  const managersRef = useRef(
+    new Map<string, ManagerEntry<unknown>>(),
+  );
+
+  // Subscribe to all events and route to appropriate managers
+  useEffect(() => {
+    const unsubscribe = subscribeToEvents((event: UploadistaEvent) => {
+      // Route flow events to all managers (they filter by jobId internally)
+      if (isFlowEvent(event)) {
+        for (const entry of managersRef.current.values()) {
+          entry.manager.handleFlowEvent(event);
+        }
+        return;
+      }
+
+      // Route upload progress events to all managers
+      if (
+        "type" in event &&
+        event.type === UploadEventType.UPLOAD_PROGRESS &&
+        "data" in event
+      ) {
+        const uploadEvent = event as {
+          type: UploadEventType;
+          uploadId: string;
+          data: { progress: number; total: number | null };
+        };
+
+        for (const entry of managersRef.current.values()) {
+          entry.manager.handleUploadProgress(
+            uploadEvent.uploadId,
+            uploadEvent.data.progress,
+            uploadEvent.data.total,
+          );
+        }
+      }
+    });
+
+    return unsubscribe;
+  }, [subscribeToEvents]);
+
+  const getManager = useCallback(
+    <TOutput,>(
+      flowId: string,
+      callbacks: FlowManagerCallbacks<TOutput>,
+      options: FlowUploadOptions<TOutput>,
+    ): FlowManager<unknown, TOutput> => {
+      const existing = managersRef.current.get(flowId);
+
+      if (existing) {
+        // Increment ref count for existing manager
+        existing.refCount++;
+        return existing.manager as FlowManager<unknown, TOutput>;
+      }
+
+      // Create new manager using client from hook scope
+      const flowUploadFn = (
+        input: unknown,
+        flowConfig: FlowUploadOptions<TOutput>["flowConfig"],
+        internalOptions: unknown,
+      ) => {
+        return client.uploadWithFlow(input, flowConfig, internalOptions);
+      };
+
+      const manager = new FlowManager<unknown, TOutput>(
+        flowUploadFn,
+        callbacks,
+        options,
+      );
+
+      managersRef.current.set(flowId, {
+        manager: manager as FlowManager<unknown, unknown>,
+        refCount: 1,
+        flowId,
+      });
+
+      return manager;
+    },
+    [client],
+  );
+
+  const releaseManager = useCallback((flowId: string) => {
+    const existing = managersRef.current.get(flowId);
+    if (!existing) return;
+
+    existing.refCount--;
+
+    // Clean up when no more refs
+    if (existing.refCount <= 0) {
+      existing.manager.cleanup();
+      managersRef.current.delete(flowId);
+    }
+  }, []);
+
+  return (
+    <FlowManagerContext.Provider value={{ getManager, releaseManager }}>
+      {children}
+    </FlowManagerContext.Provider>
+  );
+}
+
+/**
+ * Hook to access the FlowManager context.
+ * Must be used within a FlowManagerProvider.
+ *
+ * @returns FlowManager context value with getManager and releaseManager functions
+ * @throws Error if used outside of FlowManagerProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { getManager, releaseManager } = useFlowManagerContext();
+ *   // Use to create managers...
+ * }
+ * ```
+ */
+export function useFlowManagerContext(): FlowManagerContextValue {
+  const context = useContext(FlowManagerContext);
+
+  if (context === undefined) {
+    throw new Error(
+      "useFlowManagerContext must be used within a FlowManagerProvider. " +
+        "Make sure to wrap your component tree with <FlowManagerProvider>.",
+    );
+  }
+
+  return context;
+}

package/src/hooks/event-utils.ts

@@ -0,0 +1,44 @@
+import type { UploadistaEvent } from "@uploadista/client-browser";
+import { EventType, type FlowEvent } from "@uploadista/core/flow";
+import { UploadEventType, type UploadEvent } from "@uploadista/core/types";
+
+/**
+ * Type guard to check if an event is a flow event
+ */
+export function isFlowEvent(event: UploadistaEvent): event is FlowEvent {
+  if (!("eventType" in event)) return false;
+  const e = event as { eventType: unknown };
+  return (
+    e.eventType === EventType.JobStart ||
+    e.eventType === EventType.JobEnd ||
+    e.eventType === EventType.FlowStart ||
+    e.eventType === EventType.FlowEnd ||
+    e.eventType === EventType.FlowError ||
+    e.eventType === EventType.FlowPause ||
+    e.eventType === EventType.FlowCancel ||
+    e.eventType === EventType.NodeStart ||
+    e.eventType === EventType.NodeEnd ||
+    e.eventType === EventType.NodePause ||
+    e.eventType === EventType.NodeResume ||
+    e.eventType === EventType.NodeError ||
+    e.eventType === EventType.NodeStream ||
+    e.eventType === EventType.NodeResponse
+  );
+}
+
+/**
+ * Type guard to check if an event is an upload event
+ */
+export function isUploadEvent(event: UploadistaEvent): event is UploadEvent {
+  if (!("type" in event)) return false;
+  const e = event as { type: unknown };
+  return (
+    e.type === UploadEventType.UPLOAD_STARTED ||
+    e.type === UploadEventType.UPLOAD_PROGRESS ||
+    e.type === UploadEventType.UPLOAD_COMPLETE ||
+    e.type === UploadEventType.UPLOAD_FAILED ||
+    e.type === UploadEventType.UPLOAD_VALIDATION_SUCCESS ||
+    e.type === UploadEventType.UPLOAD_VALIDATION_FAILED ||
+    e.type === UploadEventType.UPLOAD_VALIDATION_WARNING
+  );
+}

package/src/hooks/index.ts

@@ -1,3 +1,19 @@
+// Event Hooks
+export { isFlowEvent, isUploadEvent } from "./event-utils";
+export { useUploadistaEvents } from "./use-uploadista-events";
+export type { UseFlowEventsOptions } from "./use-flow-events";
+export { useFlowEvents } from "./use-flow-events";
+export type {
+  UploadFailedEventData,
+  UploadFileEventData,
+  UploadProgressEventData,
+  UploadValidationFailedEventData,
+  UploadValidationSuccessEventData,
+  UploadValidationWarningEventData,
+  UseUploadEventsOptions,
+} from "./use-upload-events";
+export { useUploadEvents } from "./use-upload-events";
+
 // Flow Upload Hooks
 
 // Upload Hooks

package/src/hooks/use-flow-events.ts

@@ -0,0 +1,140 @@
+import type {
+  FlowEventFlowCancel,
+  FlowEventFlowEnd,
+  FlowEventFlowError,
+  FlowEventFlowPause,
+  FlowEventFlowStart,
+  FlowEventJobEnd,
+  FlowEventJobStart,
+  FlowEventNodeEnd,
+  FlowEventNodeError,
+  FlowEventNodePause,
+  FlowEventNodeResume,
+  FlowEventNodeStart,
+} from "@uploadista/core/flow";
+import { EventType } from "@uploadista/core/flow";
+import { useEffect } from "react";
+import { useUploadistaContext } from "../components/uploadista-provider";
+import { isFlowEvent } from "./event-utils";
+
+/**
+ * Options for handling flow execution events.
+ *
+ * All callbacks are optional - only provide handlers for events you care about.
+ */
+export interface UseFlowEventsOptions {
+  /** Called when a job starts execution */
+  onJobStart?: (event: FlowEventJobStart) => void;
+  /** Called when a job completes (success or failure) */
+  onJobEnd?: (event: FlowEventJobEnd) => void;
+  /** Called when a flow begins execution */
+  onFlowStart?: (event: FlowEventFlowStart) => void;
+  /** Called when a flow completes successfully */
+  onFlowEnd?: (event: FlowEventFlowEnd) => void;
+  /** Called when a flow encounters an error */
+  onFlowError?: (event: FlowEventFlowError) => void;
+  /** Called when a flow is paused by user request */
+  onFlowPause?: (event: FlowEventFlowPause) => void;
+  /** Called when a flow is cancelled by user request */
+  onFlowCancel?: (event: FlowEventFlowCancel) => void;
+  /** Called when a node starts processing */
+  onNodeStart?: (event: FlowEventNodeStart) => void;
+  /** Called when a node completes successfully */
+  onNodeEnd?: (event: FlowEventNodeEnd) => void;
+  /** Called when a node pauses (waiting for additional data) */
+  onNodePause?: (event: FlowEventNodePause) => void;
+  /** Called when a paused node resumes execution */
+  onNodeResume?: (event: FlowEventNodeResume) => void;
+  /** Called when a node encounters an error */
+  onNodeError?: (event: FlowEventNodeError) => void;
+}
+
+/**
+ * Structured hook for handling flow execution events with type-safe callbacks.
+ *
+ * This hook provides a clean API for listening to specific flow events without
+ * needing to manually filter events or use type guards.
+ *
+ * Must be used within UploadistaProvider.
+ *
+ * @param options - Object with optional callbacks for each flow event type
+ *
+ * @example
+ * ```tsx
+ * import { useFlowEvents } from '@uploadista/react';
+ *
+ * function FlowMonitor() {
+ *   useFlowEvents({
+ *     onFlowStart: (event) => {
+ *       console.log('Flow started:', event.flowId);
+ *     },
+ *     onNodeStart: (event) => {
+ *       console.log('Node started:', event.nodeName);
+ *     },
+ *     onNodeEnd: (event) => {
+ *       console.log('Node completed:', event.nodeName, event.result);
+ *     },
+ *     onFlowEnd: (event) => {
+ *       console.log('Flow completed with outputs:', event.outputs);
+ *     },
+ *     onFlowError: (event) => {
+ *       console.error('Flow failed:', event.error);
+ *     },
+ *   });
+ *
+ *   return <div>Monitoring flow execution...</div>;
+ * }
+ * ```
+ */
+export function useFlowEvents(options: UseFlowEventsOptions): void {
+  const { subscribeToEvents } = useUploadistaContext();
+
+  useEffect(() => {
+    const unsubscribe = subscribeToEvents((event) => {
+      // Only handle flow events
+      if (!isFlowEvent(event)) return;
+
+      // Route to appropriate callback based on event type
+      switch (event.eventType) {
+        case EventType.JobStart:
+          options.onJobStart?.(event);
+          break;
+        case EventType.JobEnd:
+          options.onJobEnd?.(event);
+          break;
+        case EventType.FlowStart:
+          options.onFlowStart?.(event);
+          break;
+        case EventType.FlowEnd:
+          options.onFlowEnd?.(event);
+          break;
+        case EventType.FlowError:
+          options.onFlowError?.(event);
+          break;
+        case EventType.FlowPause:
+          options.onFlowPause?.(event);
+          break;
+        case EventType.FlowCancel:
+          options.onFlowCancel?.(event);
+          break;
+        case EventType.NodeStart:
+          options.onNodeStart?.(event);
+          break;
+        case EventType.NodeEnd:
+          options.onNodeEnd?.(event);
+          break;
+        case EventType.NodePause:
+          options.onNodePause?.(event);
+          break;
+        case EventType.NodeResume:
+          options.onNodeResume?.(event);
+          break;
+        case EventType.NodeError:
+          options.onNodeError?.(event);
+          break;
+      }
+    });
+
+    return unsubscribe;
+  }, [subscribeToEvents, options]);
+}