@go-go-scope/adapter-react 2.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thelinuxlich (Alisson Cavalcante Agiani)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @go-go-scope/adapter-react
+
+React hooks for go-go-scope. Provides reactive integration with React's hooks API.
+
+## Installation
+
+```bash
+npm install @go-go-scope/adapter-react
+```
+
+## Usage
+
+```tsx
+import { useScope, useTask, useChannel } from '@go-go-scope/adapter-react';
+
+function UserProfile({ userId }: { userId: string }) {
+  // Create a reactive scope
+  const scope = useScope({ name: "UserProfile" });
+
+  // Execute tasks with reactive state
+  const { data, error, isLoading, execute } = useTask(
+    async () => {
+      const response = await fetch(`/api/users/${userId}`);
+      return response.json();
+    },
+    { immediate: true }
+  );
+
+  // Use channels for communication
+  const channel = useChannel<string>();
+
+  const sendMessage = async () => {
+    await channel.send("Hello!");
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h1>{data?.name}</h1>
+      <p>Latest message: {channel.latest}</p>
+      <button onClick={sendMessage}>Send Message</button>
+    </div>
+  );
+}
+```
+
+## API
+
+### `useScope(options?)`
+Creates a reactive scope that auto-disposes on component unmount.
+
+### `useTask(factory, options?)`
+Creates a reactive task with `data`, `error`, `isLoading`, `isReady`, and `execute()`.
+
+### `useParallel(factories, options?)`
+Executes tasks in parallel with progress tracking.
+
+### `useChannel(options?)`
+Creates a reactive channel for Go-style communication.
+
+### `useBroadcast()`
+Creates a reactive broadcast channel for pub/sub patterns.
+
+### `usePolling(factory, options)`
+Creates a reactive polling mechanism.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,289 @@
+import { Result, Scope } from 'go-go-scope';
+export { BroadcastChannel, Channel, Result, Scope } from 'go-go-scope';
+
+/**
+ * React hooks for go-go-scope
+ *
+ * Provides React hooks integration with go-go-scope's structured concurrency.
+ * All hooks automatically clean up when components unmount.
+ *
+ * @example
+ * ```tsx
+ * import { useScope, useTask, useChannel } from "@go-go-scope/adapter-react";
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   // Auto-disposing scope
+ *   const scope = useScope({ name: "UserProfile" });
+ *
+ *   // Reactive task with states
+ *   const { data, error, isLoading, execute } = useTask(
+ *     async () => fetchUser(userId),
+ *     { immediate: true }
+ *   );
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   return <div>Hello, {data?.name}</div>;
+ * }
+ * ```
+ */
+
+/**
+ * Options for useScope hook
+ */
+interface UseScopeOptions {
+    /** Scope name for debugging */
+    name?: string;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * React hook that creates a reactive scope.
+ * The scope automatically disposes when the component unmounts.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const s = useScope({ name: "MyComponent" });
+ *
+ *   const handleClick = async () => {
+ *     const [err, result] = await s.task(() => fetchData());
+ *     // Handle result...
+ *   };
+ *
+ *   return <button onClick={handleClick}>Fetch</button>;
+ * }
+ * ```
+ */
+declare function useScope(options?: UseScopeOptions): Scope<Record<string, unknown>>;
+/**
+ * Options for useTask hook
+ */
+interface UseTaskOptions<T> {
+    /** Task name for debugging */
+    name?: string;
+    /** Whether to execute immediately */
+    immediate?: boolean;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Retry options */
+    retry?: {
+        maxRetries?: number;
+        delay?: number;
+    };
+    /** Initial data value */
+    initialData?: T;
+}
+/**
+ * State returned by useTask hook
+ */
+interface TaskState<T> {
+    /** Current data (undefined if not loaded) */
+    data: T | undefined;
+    /** Error if task failed */
+    error: Error | undefined;
+    /** Whether task is currently running */
+    isLoading: boolean;
+    /** Whether task has been executed */
+    isReady: boolean;
+    /** Execute the task */
+    execute: () => Promise<Result<Error, T>>;
+}
+/**
+ * React hook for executing tasks with structured concurrency.
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { data, error, isLoading } = useTask(
+ *     async () => fetchUser(userId),
+ *     { immediate: true }
+ *   );
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   return <div>{data?.name}</div>;
+ * }
+ * ```
+ */
+declare function useTask<T>(factory: (signal: AbortSignal) => Promise<T>, options?: UseTaskOptions<T>): TaskState<T>;
+/**
+ * Options for useParallel hook
+ */
+interface UseParallelOptions {
+    /** Concurrency limit */
+    concurrency?: number;
+    /** Whether to execute immediately */
+    immediate?: boolean;
+}
+/**
+ * State returned by useParallel hook
+ */
+interface ParallelState<T> {
+    /** Results from all tasks */
+    results: (T | undefined)[];
+    /** Errors from failed tasks */
+    errors: (Error | undefined)[];
+    /** Whether any task is running */
+    isLoading: boolean;
+    /** Progress percentage (0-100) */
+    progress: number;
+    /** Execute all tasks */
+    execute: () => Promise<Result<Error, T>[]>;
+}
+/**
+ * React hook for executing tasks in parallel.
+ *
+ * @example
+ * ```tsx
+ * function Dashboard() {
+ *   const factories = [
+ *     () => fetchUsers(),
+ *     () => fetchPosts(),
+ *     () => fetchComments(),
+ *   ];
+ *
+ *   const { results, isLoading, progress } = useParallel(factories, {
+ *     concurrency: 2,
+ *     immediate: true
+ *   });
+ *
+ *   if (isLoading) return <progress value={progress} max="100" />;
+ *
+ *   const [users, posts, comments] = results;
+ *   return <DashboardView {...{ users, posts, comments }} />;
+ * }
+ * ```
+ */
+declare function useParallel<T>(factories: (() => Promise<T>)[], options?: UseParallelOptions): ParallelState<T>;
+/**
+ * Options for useChannel hook
+ */
+interface UseChannelOptions {
+    /** Buffer size */
+    bufferSize?: number;
+    /** Maximum history to keep */
+    historySize?: number;
+}
+/**
+ * State returned by useChannel hook
+ */
+interface ChannelState<T> {
+    /** Latest received value */
+    latest: T | undefined;
+    /** History of values */
+    history: readonly T[];
+    /** Whether channel is closed */
+    isClosed: boolean;
+    /** Send a value */
+    send: (value: T) => Promise<void>;
+    /** Close the channel */
+    close: () => void;
+}
+/**
+ * React hook for Go-style channel communication.
+ *
+ * @example
+ * ```tsx
+ * function Chat() {
+ *   const ch = useChannel<string>();
+ *
+ *   const handleSubmit = async (message: string) => {
+ *     await ch.send(message);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Latest: {ch.latest}</p>
+ *       <ul>
+ *         {ch.history.map((msg, i) => <li key={i}>{msg}</li>)}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useChannel<T>(options?: UseChannelOptions): ChannelState<T>;
+/**
+ * State returned by useBroadcast hook
+ */
+interface BroadcastState<T> {
+    /** Latest broadcasted value */
+    latest: T | undefined;
+    /** Subscribe to broadcasts */
+    subscribe: (callback: (value: T) => void) => {
+        unsubscribe: () => void;
+    };
+    /** Broadcast a value */
+    broadcast: (value: T) => void;
+}
+/**
+ * React hook for pub/sub broadcast channels.
+ *
+ * @example
+ * ```tsx
+ * function EventBus() {
+ *   const bus = useBroadcast<string>();
+ *
+ *   useEffect(() => {
+ *     const sub = bus.subscribe((msg) => console.log(msg));
+ *     return () => sub.unsubscribe();
+ *   }, []);
+ *
+ *   return <button onClick={() => bus.broadcast("Hello!")}>Send</button>;
+ * }
+ * ```
+ */
+declare function useBroadcast<T>(): BroadcastState<T>;
+/**
+ * Options for usePolling hook
+ */
+interface UsePollingOptions {
+    /** Interval in milliseconds */
+    interval: number;
+    /** Whether to start immediately */
+    immediate?: boolean;
+    /** Continue when tab is hidden */
+    continueOnHidden?: boolean;
+}
+/**
+ * State returned by usePolling hook
+ */
+interface PollingState<T> {
+    /** Latest data */
+    data: T | undefined;
+    /** Error if polling failed */
+    error: Error | undefined;
+    /** Whether currently polling */
+    isPolling: boolean;
+    /** Number of polls completed */
+    pollCount: number;
+    /** Start polling */
+    start: () => void;
+    /** Stop polling */
+    stop: () => void;
+}
+/**
+ * React hook for polling data at intervals.
+ *
+ * @example
+ * ```tsx
+ * function LiveData() {
+ *   const { data, isPolling, stop } = usePolling(
+ *     async () => fetchLatestData(),
+ *     { interval: 5000, immediate: true }
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       <p>{data}</p>
+ *       {isPolling && <button onClick={stop}>Stop</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function usePolling<T>(factory: () => Promise<T>, options: UsePollingOptions): PollingState<T>;
+
+export { useBroadcast, useChannel, useParallel, usePolling, useScope, useTask };
+export type { BroadcastState, ChannelState, ParallelState, PollingState, TaskState, UseChannelOptions, UseParallelOptions, UsePollingOptions, UseScopeOptions, UseTaskOptions };

package/dist/index.mjs

@@ -0,0 +1,262 @@
+import { scope, BroadcastChannel } from 'go-go-scope';
+import { useRef, useEffect, useState, useCallback } from 'react';
+
+function useScope(options = {}) {
+  const scopeRef = useRef(null);
+  if (!scopeRef.current) {
+    scopeRef.current = scope({
+      name: options.name,
+      timeout: options.timeout
+    });
+  }
+  useEffect(() => {
+    return () => {
+      scopeRef.current?.[Symbol.asyncDispose]().catch(() => {
+      });
+    };
+  }, []);
+  return scopeRef.current;
+}
+function useTask(factory, options = {}) {
+  const s = useScope({ name: options.name ?? "useTask" });
+  const [data, setData] = useState(options.initialData);
+  const [error, setError] = useState(void 0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isReady, setIsReady] = useState(false);
+  const execute = useCallback(async () => {
+    setIsLoading(true);
+    setError(void 0);
+    try {
+      const [err, result] = await s.task(
+        async ({ signal }) => await factory(signal),
+        {
+          timeout: options.timeout,
+          retry: options.retry
+        }
+      );
+      if (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setData(void 0);
+        return [err, void 0];
+      }
+      setData(result);
+      setIsReady(true);
+      return [void 0, result];
+    } finally {
+      setIsLoading(false);
+    }
+  }, [s, factory, options.timeout, options.retry]);
+  useEffect(() => {
+    if (options.immediate) {
+      execute();
+    }
+  }, []);
+  return {
+    data,
+    error,
+    isLoading,
+    isReady,
+    execute
+  };
+}
+function useParallel(factories, options = {}) {
+  const s = useScope({ name: "useParallel" });
+  const [results, setResults] = useState([]);
+  const [errors, setErrors] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [progress, setProgress] = useState(0);
+  const execute = useCallback(async () => {
+    setIsLoading(true);
+    setProgress(0);
+    setResults(new Array(factories.length).fill(void 0));
+    setErrors(new Array(factories.length).fill(void 0));
+    try {
+      const taskFactories = factories.map((factory, index) => {
+        return async () => {
+          const [err, result] = await s.task(async () => await factory());
+          if (err) {
+            setErrors((prev) => {
+              const next = [...prev];
+              next[index] = err instanceof Error ? err : new Error(String(err));
+              return next;
+            });
+          } else {
+            setResults((prev) => {
+              const next = [...prev];
+              next[index] = result;
+              return next;
+            });
+          }
+          setProgress(Math.round((index + 1) / factories.length * 100));
+          return [err, result];
+        };
+      });
+      return await s.parallel(taskFactories, {
+        concurrency: options.concurrency
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [s, factories, options.concurrency]);
+  useEffect(() => {
+    if (options.immediate) {
+      execute();
+    }
+  }, []);
+  return {
+    results,
+    errors,
+    isLoading,
+    progress,
+    execute
+  };
+}
+function useChannel(options = {}) {
+  const s = useScope({ name: "useChannel" });
+  const chRef = useRef(null);
+  if (!chRef.current) {
+    chRef.current = s.channel(options.bufferSize ?? 0);
+  }
+  const [latest, setLatest] = useState(void 0);
+  const [history, setHistory] = useState([]);
+  const [isClosed, setIsClosed] = useState(false);
+  useEffect(() => {
+    const ch = chRef.current;
+    const receiveLoop = async () => {
+      for await (const value of ch) {
+        setLatest(value);
+        setHistory((prev) => [...prev.slice(-(options.historySize ?? 100)), value]);
+      }
+      setIsClosed(true);
+    };
+    receiveLoop();
+    return () => {
+      ch.close();
+    };
+  }, [options.historySize]);
+  const send = useCallback(
+    async (value) => {
+      await chRef.current.send(value);
+    },
+    []
+  );
+  const close = useCallback(() => {
+    chRef.current.close();
+  }, []);
+  return {
+    latest,
+    history,
+    isClosed,
+    send,
+    close
+  };
+}
+function useBroadcast() {
+  const [latest, setLatest] = useState(void 0);
+  const bcRef = useRef(null);
+  const listenersRef = useRef(/* @__PURE__ */ new Set());
+  if (!bcRef.current) {
+    bcRef.current = new BroadcastChannel();
+  }
+  useEffect(() => {
+    const bc = bcRef.current;
+    const receiveLoop = async () => {
+      for await (const value of bc.subscribe()) {
+        setLatest(value);
+        listenersRef.current.forEach((listener) => listener(value));
+      }
+    };
+    receiveLoop();
+    return () => {
+      bc.close();
+    };
+  }, []);
+  const subscribe = useCallback((callback) => {
+    listenersRef.current.add(callback);
+    return {
+      unsubscribe: () => {
+        listenersRef.current.delete(callback);
+      }
+    };
+  }, []);
+  const broadcastFn = useCallback((value) => {
+    bcRef.current.send(value).catch(() => {
+    });
+    setLatest(value);
+  }, []);
+  return {
+    latest,
+    subscribe,
+    broadcast: broadcastFn
+  };
+}
+function usePolling(factory, options) {
+  const s = useScope({ name: "usePolling" });
+  const [data, setData] = useState(void 0);
+  const [error, setError] = useState(void 0);
+  const [isPolling, setIsPolling] = useState(false);
+  const [pollCount, setPollCount] = useState(0);
+  const pollerRef = useRef(null);
+  const start = useCallback(() => {
+    if (!isPolling && !pollerRef.current) {
+      pollerRef.current = s.poll(
+        async () => {
+          try {
+            const value = await factory();
+            return { success: true, value };
+          } catch (e) {
+            return { success: false, error: e };
+          }
+        },
+        (result) => {
+          if (result.success) {
+            setData(result.value);
+            setPollCount((c) => c + 1);
+          } else {
+            setError(result.error instanceof Error ? result.error : new Error(String(result.error)));
+          }
+        },
+        { interval: options.interval }
+      );
+      setIsPolling(true);
+    }
+  }, [s, factory, options.interval, isPolling]);
+  const stop = useCallback(() => {
+    if (isPolling && pollerRef.current) {
+      pollerRef.current.stop();
+      setIsPolling(false);
+      pollerRef.current = null;
+    }
+  }, [isPolling]);
+  useEffect(() => {
+    if (options.immediate !== false) {
+      start();
+    }
+    return () => {
+      stop();
+    };
+  }, []);
+  useEffect(() => {
+    if (!options.continueOnHidden && typeof document !== "undefined") {
+      const handler = () => {
+        if (document.hidden) {
+          stop();
+        } else if (options.immediate !== false) {
+          start();
+        }
+      };
+      document.addEventListener("visibilitychange", handler);
+      return () => document.removeEventListener("visibilitychange", handler);
+    }
+  }, [options.continueOnHidden, options.immediate, start, stop]);
+  return {
+    data,
+    error,
+    isPolling,
+    pollCount,
+    start,
+    stop
+  };
+}
+
+export { useBroadcast, useChannel, useParallel, usePolling, useScope, useTask };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@go-go-scope/adapter-react",
+  "version": "2.7.0",
+  "description": "React hooks for go-go-scope",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "keywords": [
+    "go-go-scope",
+    "react",
+    "hooks",
+    "react-hooks",
+    "concurrency"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "author": "thelinuxlich",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "go-go-scope": "2.7.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^24",
+    "@types/react": "^18.3.0",
+    "jsdom": "^24.0.0",
+    "pkgroll": "^2.26.3",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "go-go-scope": "2.7.0"
+  },
+  "scripts": {
+    "build": "pkgroll --clean-dist",
+    "lint": "biome check --write src/",
+    "test": "vitest run",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}