react-pipeline-runner 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 tonylus
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# react-pipeline-runner
+
+A lightweight React hook for running async actions sequentially with abort support, error handling, and resume capability.
+
+## Installation
+
+```bash
+npm install react-pipeline-runner
+```
+
+## Features
+
+- Sequential execution of sync/async actions
+- AbortController support for cancellation
+- Resume from failed step
+- TypeScript-first with intelligent ID inference
+- Discriminated union for type-safe state handling
+- Automatic cleanup on unmount
+- Zero dependencies (except React 18+)
+
+## Basic Usage
+
+```tsx
+import { usePipeline } from 'react-pipeline-runner'
+
+function MyComponent() {
+  const pipeline = usePipeline([
+    async (signal) => {
+      await fetch('/api/step1', { signal })
+    },
+    async (signal) => {
+      await fetch('/api/step2', { signal })
+    },
+    async () => {
+      console.log('Step 3 - no signal needed')
+    },
+  ])
+
+  return (
+    <div>
+      <p>State: {pipeline.state}</p>
+      
+      {pipeline.state === 'idle' && (
+        <button onClick={pipeline.start}>Start</button>
+      )}
+      
+      {pipeline.state === 'running' && (
+        <>
+          <p>Running step {pipeline.current.index + 1}...</p>
+          <button onClick={pipeline.stop}>Cancel</button>
+        </>
+      )}
+      
+      {pipeline.state === 'failed' && (
+        <>
+          <p>Error at step {pipeline.current.index + 1}: {String(pipeline.current.error)}</p>
+          <button onClick={pipeline.resume}>Retry</button>
+          <button onClick={pipeline.stop}>Abandon</button>
+        </>
+      )}
+      
+      {pipeline.state === 'completed' && (
+        <p>Done!</p>
+      )}
+    </div>
+  )
+}
+```
+
+## Steps with IDs
+
+You can assign IDs to steps for better tracking. TypeScript will automatically infer the ID types.
+
+```tsx
+const pipeline = usePipeline([
+  { id: 'fetch-user', action: async () => fetchUser() },
+  { id: 'validate', action: () => validateData() },
+  async () => doSomethingWithoutId(),
+  { id: 'save', action: async () => saveData() },
+])
+
+if (pipeline.state === 'running') {
+  console.log('Current step:', pipeline.current.id)
+  // TypeScript knows: id is 'fetch-user' | 'validate' | 'save' | undefined
+}
+```
+
+## Auto-run
+
+Start the pipeline automatically when the component mounts:
+
+```tsx
+const pipeline = usePipeline(
+  [step1, step2, step3],
+  { autorun: true }
+)
+```
+
+## API
+
+### `usePipeline(steps, options?)`
+
+#### Parameters
+
+- `steps` - Array of actions. Each action can be:
+  - A function: `(signal?: AbortSignal) => Promise<unknown> | unknown`
+  - An object: `{ id: string, action: (signal?: AbortSignal) => Promise<unknown> | unknown }`
+- `options` - Optional configuration:
+  - `autorun?: boolean` - Start pipeline on mount (default: `false`)
+
+#### Returns (Discriminated Union)
+
+The hook returns a discriminated union based on `state`:
+
+| State | `current` | Description |
+|-------|-----------|-------------|
+| `'idle'` | `undefined` | Not started or stopped |
+| `'running'` | `CurrentStatus` | Executing steps |
+| `'failed'` | `CurrentStatus` | Stopped on error |
+| `'completed'` | `undefined` | All steps done |
+
+**Methods:**
+
+- `start()` - Start from beginning. Returns `true` if started, `false` if running or failed.
+- `stop()` - Cancel and reset to idle. Returns `true` if was running or failed, `false` otherwise.
+- `resume()` - Retry failed step. Returns `true` if was failed, `false` otherwise.
+
+**State transitions:**
+
+| State | `start()` | `stop()` | `resume()` |
+|-------|-----------|----------|------------|
+| `idle` | ✅ starts | ❌ false | ❌ false |
+| `running` | ❌ false | ✅ → idle | ❌ false |
+| `failed` | ❌ false | ✅ → idle | ✅ retries |
+| `completed` | ✅ restarts | ❌ false | ❌ false |
+
+**CurrentStatus:**
+
+```ts
+{
+  index: number              // Step index (0-based)
+  id: string | undefined     // Step ID if provided
+  state: 'running' | 'failed'
+  error: unknown | undefined // Error if failed
+}
+```
+
+## Type Safety
+
+Thanks to discriminated unions, TypeScript narrows the `current` type based on `state`:
+
+```tsx
+if (pipeline.state === 'failed') {
+  // TypeScript knows current is defined!
+  console.log(pipeline.current.error) // ✅ No need for && pipeline.current
+}
+
+if (pipeline.state === 'idle') {
+  pipeline.current.index // ❌ Compile error - current is undefined
+}
+```
+
+## AbortController Support
+
+Each action receives an optional `AbortSignal`. Use it to make your actions cancellable:
+
+```tsx
+async (signal) => {
+  // Fetch automatically aborts when signal fires
+  const response = await fetch('/api/data', { signal })
+  return response.json()
+}
+```
+
+When `stop()` is called or the component unmounts, the signal is aborted automatically.
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+type PipelineAction = (signal?: AbortSignal) => Promise<unknown> | unknown;
+interface PipelineStepWithId {
+    id: string;
+    action: PipelineAction;
+}
+type PipelineStep = PipelineAction | PipelineStepWithId;
+interface PipelineOptions {
+    autorun?: boolean;
+}
+type PipelineState = 'idle' | 'running' | 'failed' | 'completed';
+type StepState = 'running' | 'failed';
+interface CurrentStatus<TIds extends string | undefined> {
+    index: number;
+    id: TIds;
+    state: StepState;
+    error: unknown | undefined;
+}
+interface PipelineMethods {
+    start: () => boolean;
+    stop: () => boolean;
+    resume: () => boolean;
+}
+type PipelineIdle = PipelineMethods & {
+    state: 'idle';
+    current: undefined;
+};
+type PipelineRunning<TIds extends string | undefined> = PipelineMethods & {
+    state: 'running';
+    current: CurrentStatus<TIds>;
+};
+type PipelineFailed<TIds extends string | undefined> = PipelineMethods & {
+    state: 'failed';
+    current: CurrentStatus<TIds>;
+};
+type PipelineCompleted = PipelineMethods & {
+    state: 'completed';
+    current: undefined;
+};
+type PipelineResult<TIds extends string | undefined> = PipelineIdle | PipelineRunning<TIds> | PipelineFailed<TIds> | PipelineCompleted;
+type ExtractStepId<T> = T extends {
+    id: infer Id extends string;
+} ? Id : undefined;
+type ExtractAllIds<T extends readonly PipelineStep[]> = ExtractStepId<T[number]>;
+
+/**
+ * Runs a list of actions sequentially with support for abort, resume, and error handling.
+ */
+declare function usePipeline<const T extends readonly PipelineStep[]>(steps: T, options?: PipelineOptions): PipelineResult<ExtractAllIds<T>>;
+
+export { type CurrentStatus, type PipelineAction, type PipelineOptions, type PipelineResult, type PipelineState, type PipelineStep, type PipelineStepWithId, type StepState, usePipeline };

package/dist/index.js

@@ -0,0 +1,2 @@
+import*as t from'react';function R(e){let[p,f]=t.useState(e),n=t.useRef(e),r=t.useCallback(a=>{n.current=a,f(a);},[]);return [p,n,r]}function P(e){return typeof e=="object"&&e!==null&&"action"in e}function A(e){return P(e)?e.action:e}function E(e){if(P(e))return e.id}function h(e,p){let[f,n,r]=R("idle"),[a,c]=t.useState(void 0),d=t.useRef(0),u=t.useRef(null),o=t.useCallback(async x=>{r("running"),u.current=new AbortController;let l=u.current.signal;for(let i=x;i<e.length;i++){if(l.aborted)return;let y=e[i],I=A(y),S=E(y);d.current=i,c({index:i,id:S,state:"running",error:void 0});try{await I(l);}catch(C){if(l.aborted)return;r("failed"),c({index:i,id:S,state:"failed",error:C});return}}l.aborted||(r("completed"),c(void 0));},[e]),T=t.useCallback(()=>n.current==="running"||n.current==="failed"?false:(o(0),true),[o]),b=t.useCallback(()=>n.current!=="running"&&n.current!=="failed"?false:(u.current?.abort(),u.current=null,r("idle"),c(void 0),true),[]),m=t.useCallback(()=>n.current!=="failed"?false:(o(d.current),true),[o]);return t.useEffect(()=>(p?.autorun&&T(),()=>{u.current?.abort();}),[]),{state:f,current:a,start:T,stop:b,resume:m}}export{h as usePipeline};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/usePipeline.ts"],"names":["useStateRef","initialValue","state","setState","s","ref","setValue","value","isStepWithId","step","getStepAction","getStepId","usePipeline","steps","options","stateRef","current","setCurrent","currentIndexRef","abortControllerRef","runFromIndex","startIndex","signal","action","id","error","start","stop","resume"],"mappings":"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","file":"index.js","sourcesContent":["import * as React from 'react'\n\n//\n\n/**\n * Combines useState and useRef - state for React reactivity, ref for immediate access in async callbacks.\n */\nexport function useStateRef<T>(initialValue: T) {\n  const [state, setState] = React.useState(initialValue);\n  const ref = React.useRef(initialValue);\n\n  const setValue = React.useCallback((value: T) => {\n    ref.current = value;\n    setState(value);\n  }, []);\n\n  return [state, ref, setValue] as const;\n}\n","import * as React from 'react'\n\nimport type * as Types from './types'\nimport * as Utils from './utils'\n\n//\n\nfunction isStepWithId(step: Types.PipelineStep): step is Types.PipelineStepWithId {\n  return typeof step === 'object' && step !== null && 'action' in step;\n}\n\nfunction getStepAction(step: Types.PipelineStep): Types.PipelineAction {\n  if (isStepWithId(step))\n    return step.action;\n\n  return step;\n}\n\nfunction getStepId<T extends Types.PipelineStep>(step: T): Types.ExtractStepId<T> {\n  if (isStepWithId(step))\n    return step.id as Types.ExtractStepId<T>;\n\n  return undefined as Types.ExtractStepId<T>;\n}\n\n//\n\n/**\n * Runs a list of actions sequentially with support for abort, resume, and error handling.\n */\nexport function usePipeline<const T extends readonly Types.PipelineStep[]>(\n  steps: T,\n  options?: Types.PipelineOptions\n): Types.PipelineResult<Types.ExtractAllIds<T>> {\n  type TIds = Types.ExtractAllIds<T>\n\n  const [state, stateRef, setState] = Utils.useStateRef<Types.PipelineState>('idle');\n  const [current, setCurrent] = React.useState<Types.CurrentStatus<TIds> | undefined>(undefined);\n\n  const currentIndexRef = React.useRef<number>(0);\n  const abortControllerRef = React.useRef<AbortController | null>(null);\n\n  //\n\n  const runFromIndex = React.useCallback(async (startIndex: number) => {\n    setState('running');\n\n    abortControllerRef.current = new AbortController();\n    const signal = abortControllerRef.current.signal;\n\n    for (let i = startIndex; i < steps.length; i++) {\n      if (signal.aborted)\n        return;\n\n      const step = steps[i];\n      const action = getStepAction(step);\n      const id = getStepId(step) as TIds;\n\n      currentIndexRef.current = i;\n      setCurrent({ index: i, id, state: 'running', error: undefined });\n\n      try {\n        await action(signal);\n      }\n      catch (error) {\n        if (signal.aborted)\n          return;\n\n        setState('failed');\n        setCurrent({ index: i, id, state: 'failed', error });\n        return;\n      }\n    }\n\n    if (signal.aborted)\n      return;\n\n    setState('completed');\n    setCurrent(undefined);\n  }, [steps]);\n\n  //\n\n  const start = React.useCallback(() => {\n    if (stateRef.current === 'running' || stateRef.current === 'failed')\n      return false;\n\n    runFromIndex(0);\n    return true;\n  }, [runFromIndex]);\n\n  const stop = React.useCallback(() => {\n    if (stateRef.current !== 'running' && stateRef.current !== 'failed')\n      return false;\n\n    abortControllerRef.current?.abort();\n    abortControllerRef.current = null;\n\n    setState('idle');\n    setCurrent(undefined);\n\n    return true;\n  }, []);\n\n  const resume = React.useCallback(() => {\n    if (stateRef.current !== 'failed')\n      return false;\n\n    runFromIndex(currentIndexRef.current);\n    return true;\n  }, [runFromIndex]);\n\n  //\n\n  React.useEffect(() => {\n    if (options?.autorun)\n      start();\n\n    return () => {\n      abortControllerRef.current?.abort();\n    };\n  }, []);\n\n  //\n\n  return { state, current, start, stop, resume } as Types.PipelineResult<TIds>;\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "react-pipeline-runner",
+  "version": "0.1.0",
+  "description": "Lightweight React hook for running async actions sequentially with abort support and resume capability",
+  "keywords": [
+    "react",
+    "hook",
+    "pipeline",
+    "async",
+    "sequential",
+    "queue",
+    "runner"
+  ],
+  "author": "tonylus",
+  "license": "ISC",
+  "repository": "https://github.com/TonylusMark1/react-pipeline-runner",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.3.2",
+    "@types/react": "^19.0.0",
+    "happy-dom": "^20.8.4",
+    "react": "^19.2.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.3",
+    "vitest": "^4.1.0"
+  }
+}