react-flow-z 1.0.0-z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delpi.Kye
+
+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,223 @@
+# 🌊 react-flow-z
+
+[![NPM](https://img.shields.io/npm/v/react-flow-z.svg)](https://www.npmjs.com/package/react-flow-z) ![Downloads](https://img.shields.io/npm/dt/react-flow-z.svg)
+
+<a href="https://codesandbox.io/p/sandbox/vkl64l" target="_blank">LIVE EXAMPLE</a>
+
+---
+
+`react-flow-z` is a **small, framework-agnostic async flow runtime**.
+
+It focuses on **how async logic runs**, not:
+- how state is stored
+- how UI renders
+- or how effects are magically managed
+
+> This library is about **orchestration**, not reactivity.
+
+---
+
+## Why react-flow-z
+
+- Typed async execution pipeline
+- Immutable flow composition
+- Abort & cancellation via `AbortController`
+- Async orchestration operators: `debounce` · `retry` · `timeout` · `switchMap` ·` parallel`
+- Control flow: `filter` · `take` · `conditional execution`
+- Pause / resume execution
+- Framework-agnostic core
+- Optional React hook (`useFlow`)
+
+---
+
+## Installation
+
+```bash
+npm install react-flow-z
+```
+
+---
+
+## Basic Usage
+
+```ts
+import { Flow } from "react-flow-z"
+
+new Flow()
+  .debounce(300)
+  .switchMap(q => fetch(`/search?q=${q}`))
+  .tap(res => console.log(res))
+  .run("hello")
+```
+
+---
+
+## Cancellation
+
+```ts
+const flow = new Flow()
+  .step(async (v, _, signal) => {
+    await sleep(1000, signal)
+    return v
+  })
+
+flow.run(1)
+flow.cancel()
+```
+
+---
+
+## Pause / Resume
+
+```ts
+flow.pause()
+
+setTimeout(() => {
+  flow.resumeFlow()
+}, 1000)
+```
+
+---
+
+## React Integration
+
+```ts
+import { useFlow } from "react-flow-z"
+
+useFlow(
+  keyword,
+  flow =>
+    flow
+      .debounce(300)
+      .switchMap(search)
+      .tap(setResult)
+      .catch(() => []),
+  {}
+)
+```
+
+---
+
+## Search posts (official example)
+
+#### ✅ Pattern 1: Flow instance (recommended)
+
+##### searchFlow.ts
+```ts
+import { Flow } from "react-flow-z"
+
+export const searchFlow = new Flow()
+  .onStart(() => console.log("loading..."))
+  .debounce(300)
+  .filter((q: string) => q.length > 0)
+  .switchMap(async (q: string) => {
+    const res = await fetch(
+      `https://jsonplaceholder.typicode.com/posts?q=${q}`
+    )
+    if (!res.ok) throw new Error("network error")
+    return res.json()
+  })
+  .onDone(() => console.log("done"))
+  .onError(err => console.error(err))
+
+// searchFlow.run("r")
+// searchFlow.run("re")
+// searchFlow.run("react")
+```
+
+##### React usage
+```ts
+function SearchExample() {
+  const [q, setQ] = useState("")
+  const [posts, setPosts] = useState<any[]>([])
+
+  useEffect(() => {
+    searchFlow
+      .tap(setPosts)
+      .catch(() => [])
+      .run(q)
+  }, [q])
+
+  return (
+    <>
+      <input
+        value={q}
+        onChange={e => setQ(e.target.value)}
+        placeholder="Search posts..."
+      />
+      <ul>
+        {posts.map(p => (
+          <li key={p.id}>{p.title}</li>
+        ))}
+      </ul>
+    </>
+  )
+}
+
+```
+
+---
+
+#### ✅ Pattern 2: One-off Flow execution
+
+##### Submit form – prevent double submit (leading)
+
+```ts
+import { Flow } from "react-flow-z"
+
+export function runSearch(q: string) {
+  return new Flow()
+    .debounce(300)
+    .filter(Boolean)
+    .switchMap(async query => {
+      const res = await fetch(
+        `https://jsonplaceholder.typicode.com/posts?q=${query}`
+      )
+      if (!res.ok) throw new Error("network error")
+      return res.json()
+    })
+    .run(q)
+}
+
+```
+
+---
+
+## Philosophy
+
+- Explicit over implicit
+- Async/await over streams
+- No global state
+- No magic scheduling
+- You own execution
+
+---
+
+## Compare high-level
+
+| Point                  | react-flow-z  | RxJS  | Redux-Saga | XState   | React Query |
+| ---------------------- | ------------  | ----- | ---------- | -------  | ----------- |
+| Async orchestration    | ✅            | ✅     | ✅         | 🟡       | ❌          |
+| Debounce / cancel      | ✅            | ✅     | 🟡         | 🟡       | ❌          |
+| Execution-first design | ✅            | ❌     | 🟡         | ❌       | ❌          |
+| Framework-agnostic     | ✅            | ✅     | ❌         | 🟡       | ❌          |
+| Learning curve         | ⭐ easy       | ⭐⭐⭐  | ⭐⭐       | ⭐⭐⭐    | ⭐          |
+
+---
+
+### What react-flow-z is NOT
+
+- ❌ Not a state manager
+- ❌ Not a reactive signal system
+- ❌ Not a data cache like React Query
+- ❌ Not a stream library like RxJS
+
+If you only need data fetching → use React Query  
+If you need event streams → use RxJS  
+If you need **explicit async execution with cancel / debounce / queue** → react-flow-z
+
+---
+
+## License
+
+MIT

package/build/flow-system/Flow.d.ts

@@ -0,0 +1,55 @@
+export type Step<I, O, Context> = (input: I, context: Context, signal: AbortSignal) => O | Promise<O>;
+export type Condition<T> = (v: T) => boolean;
+export type CancelHandler = () => void;
+export type TypedFlow<I, O, Context> = Flow<Context> & {
+    run(input?: I): Promise<O | undefined>;
+    step<N>(fn: Step<O, N, Context>): TypedFlow<I, N, Context>;
+    tap(fn: (v: O, context: Context) => void): TypedFlow<I, O, Context>;
+    filter(cond: Condition<O>): TypedFlow<I, O, Context>;
+    debounce(ms: number): TypedFlow<I, O, Context>;
+    throttle(ms: number): TypedFlow<I, O, Context>;
+    leading(ms: number): TypedFlow<I, O, Context>;
+    switchMap<N>(fn: Step<O, N, Context>): TypedFlow<I, N, Context>;
+    exhaustMap<N>(fn: Step<O, N, Context>): TypedFlow<I, N, Context>;
+    retry(times: number): TypedFlow<I, O, Context>;
+    timeout(ms: number): TypedFlow<I, O, Context>;
+    catch(fn: (e: any, context: Context) => O | Promise<O>): TypedFlow<I, O, Context>;
+    take(n: number): TypedFlow<I, O, Context>;
+};
+export declare class Flow<Context = {}> {
+    private readonly ctx;
+    static SKIP: symbol;
+    private ops;
+    private paused?;
+    private resume;
+    private controller;
+    private cancelHandlers;
+    private onStartHandlers;
+    private onDoneHandlers;
+    private onErrorHandlers;
+    private initialInput?;
+    constructor(ctx?: Context);
+    static from<I, Context = {}>(input: I, context?: Context): TypedFlow<I, I, Context>;
+    run(input?: unknown): Promise<any>;
+    onStart(fn: () => void): this;
+    onDone(fn: () => void): this;
+    onError(fn: (e: any) => void): this;
+    onCancel(fn: CancelHandler): this;
+    cancel(): void;
+    pause(): this;
+    resumeFlow(): this;
+    private waitIfPaused;
+    context(): Context;
+    step(fn: Step<any, any, Context>): any;
+    tap(fn: (v: any, context: Context) => void): any;
+    filter(cond: Condition<any>): any;
+    debounce(ms: number): any;
+    leading(ms: number): any;
+    throttle(ms: number): any;
+    take(n: number): any;
+    switchMap(fn: Step<any, any, Context>): any;
+    exhaustMap(fn: Step<any, any, Context>): any;
+    retry(times: number): this;
+    timeout(ms: number): this;
+    catch(fn: (e: any, context: Context) => any): this;
+}

package/build/flow-system/types.d.ts

@@ -0,0 +1,3 @@
+export type Step<I, O, Context> = (input: I, context: Context, signal: AbortSignal) => O | Promise<O>;
+export type Condition<T> = (v: T) => boolean;
+export type CancelHandler = () => void;

package/build/flow-system/useFlow.d.ts

@@ -0,0 +1,7 @@
+import { TypedFlow } from "./Flow";
+export declare function useFlow<I, O = I, Context = {}>(source: I, builder: (f: TypedFlow<I, I, Context>) => TypedFlow<I, O, Context>, context?: Context): {
+    cancel: () => void;
+    pause: () => void;
+    resume: () => void;
+    flow: TypedFlow<I, O, Context> | null;
+};

package/build/flow-system/utils.d.ts

@@ -0,0 +1 @@
+export declare const sleep: (ms: number, signal: AbortSignal) => Promise<void>;

package/build/index.cjs.js

@@ -0,0 +1 @@
+"use strict";var t=require("react");const r=(t,r)=>new Promise((e,s)=>{const n=setTimeout(e,t);r.addEventListener("abort",()=>{clearTimeout(n),s("aborted")})});class e{constructor(t={}){this.ctx=t,this.ops=[],this.controller=null,this.cancelHandlers=[],this.onStartHandlers=[],this.onDoneHandlers=[],this.onErrorHandlers=[]}static from(t,r){const s=new e(r);return s.initialInput=t,s}async run(t){var r;const s=void 0!==t?t:this.initialInput;if(void 0===s)throw Error("Flow.run: missing input");null===(r=this.controller)||void 0===r||r.abort(),this.controller=new AbortController,this.onStartHandlers.forEach(t=>t());let n=s;try{for(const t of this.ops){if(this.controller.signal.aborted)return;await this.waitIfPaused(),n=await t(n,this.ctx,this.controller.signal)}return this.onDoneHandlers.forEach(t=>t()),n}catch(t){if(t===e.SKIP)return;throw this.onErrorHandlers.forEach(r=>r(t)),t}}onStart(t){return this.onStartHandlers.push(t),this}onDone(t){return this.onDoneHandlers.push(t),this}onError(t){return this.onErrorHandlers.push(t),this}onCancel(t){return this.cancelHandlers.push(t),this}cancel(){var t;null===(t=this.controller)||void 0===t||t.abort(),this.cancelHandlers.forEach(t=>t())}pause(){return this.paused||(this.paused=new Promise(t=>this.resume=t)),this}resumeFlow(){return this.paused&&(this.resume(),this.paused=void 0),this}async waitIfPaused(){this.paused&&await this.paused}context(){return this.ctx}step(t){return this.ops.push(t),this}tap(t){return this.step((r,e)=>(t(r,e),r))}filter(t){return this.step(r=>{if(!t(r))throw e.SKIP;return r})}debounce(t){return this.step(async(e,s,n)=>(await r(t,n),e))}leading(t){let r=!1;return this.step(async s=>{if(r)throw e.SKIP;return r=!0,setTimeout(()=>r=!1,t),s})}throttle(t){return this.leading(t)}take(t){let r=0;return this.step(s=>{if(++r>t)throw e.SKIP;return s})}switchMap(t){let r=null;return this.step(async(e,s,n)=>(null==r||r.abort(),r=new AbortController,n.addEventListener("abort",()=>null==r?void 0:r.abort()),t(e,s,r.signal)))}exhaustMap(t){let r=!1;return this.step(async(s,n,i)=>{if(r)throw e.SKIP;r=!0;try{return await t(s,n,i)}finally{r=!1}})}retry(t){const r=this.ops.pop();if(!r)return this;return this.ops.push(async(e,s,n)=>{let i=0;for(;;)try{return await r(e,s,n)}catch(r){if(++i>t)throw r}}),this}timeout(t){const e=this.ops.pop();if(!e)return this;return this.ops.push((s,n,i)=>Promise.race([e(s,n,i),r(t,i).then(()=>{throw Error("timeout")})])),this}catch(t){const r=this.ops.pop();if(!r)return this;return this.ops.push(async(e,s,n)=>{try{return await r(e,s,n)}catch(r){return t(r,s)}}),this}}e.SKIP=Symbol("FLOW_SKIP"),exports.Flow=e,exports.sleep=r,exports.useFlow=function(r,s,n){const i=t.useRef(null),o=t.useRef(null!=n?n:{});return o.current=null!=n?n:o.current,t.useEffect(()=>{var t;null===(t=i.current)||void 0===t||t.cancel();const n=e.from(r,o.current),a=s(n);return i.current=a,a.run(),()=>a.cancel()},[r,s]),{cancel:t.useCallback(()=>{var t;null===(t=i.current)||void 0===t||t.cancel()},[]),pause:t.useCallback(()=>{var t;null===(t=i.current)||void 0===t||t.pause()},[]),resume:t.useCallback(()=>{var t;null===(t=i.current)||void 0===t||t.resumeFlow()},[]),flow:i.current}};

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export { Flow } from "./flow-system/Flow";
+export { useFlow } from "./flow-system/useFlow";
+export type { Step, Condition, CancelHandler } from "./flow-system/types";
+export { sleep } from "./flow-system/utils";

package/build/index.esm.js

@@ -0,0 +1 @@
+import{useRef as t,useEffect as r,useCallback as n}from"react";const e=(t,r)=>new Promise((n,e)=>{const s=setTimeout(n,t);r.addEventListener("abort",()=>{clearTimeout(s),e("aborted")})});class s{constructor(t={}){this.ctx=t,this.ops=[],this.controller=null,this.cancelHandlers=[],this.onStartHandlers=[],this.onDoneHandlers=[],this.onErrorHandlers=[]}static from(t,r){const n=new s(r);return n.initialInput=t,n}async run(t){var r;const n=void 0!==t?t:this.initialInput;if(void 0===n)throw Error("Flow.run: missing input");null===(r=this.controller)||void 0===r||r.abort(),this.controller=new AbortController,this.onStartHandlers.forEach(t=>t());let e=n;try{for(const t of this.ops){if(this.controller.signal.aborted)return;await this.waitIfPaused(),e=await t(e,this.ctx,this.controller.signal)}return this.onDoneHandlers.forEach(t=>t()),e}catch(t){if(t===s.SKIP)return;throw this.onErrorHandlers.forEach(r=>r(t)),t}}onStart(t){return this.onStartHandlers.push(t),this}onDone(t){return this.onDoneHandlers.push(t),this}onError(t){return this.onErrorHandlers.push(t),this}onCancel(t){return this.cancelHandlers.push(t),this}cancel(){var t;null===(t=this.controller)||void 0===t||t.abort(),this.cancelHandlers.forEach(t=>t())}pause(){return this.paused||(this.paused=new Promise(t=>this.resume=t)),this}resumeFlow(){return this.paused&&(this.resume(),this.paused=void 0),this}async waitIfPaused(){this.paused&&await this.paused}context(){return this.ctx}step(t){return this.ops.push(t),this}tap(t){return this.step((r,n)=>(t(r,n),r))}filter(t){return this.step(r=>{if(!t(r))throw s.SKIP;return r})}debounce(t){return this.step(async(r,n,s)=>(await e(t,s),r))}leading(t){let r=!1;return this.step(async n=>{if(r)throw s.SKIP;return r=!0,setTimeout(()=>r=!1,t),n})}throttle(t){return this.leading(t)}take(t){let r=0;return this.step(n=>{if(++r>t)throw s.SKIP;return n})}switchMap(t){let r=null;return this.step(async(n,e,s)=>(null==r||r.abort(),r=new AbortController,s.addEventListener("abort",()=>null==r?void 0:r.abort()),t(n,e,r.signal)))}exhaustMap(t){let r=!1;return this.step(async(n,e,i)=>{if(r)throw s.SKIP;r=!0;try{return await t(n,e,i)}finally{r=!1}})}retry(t){const r=this.ops.pop();if(!r)return this;return this.ops.push(async(n,e,s)=>{let i=0;for(;;)try{return await r(n,e,s)}catch(r){if(++i>t)throw r}}),this}timeout(t){const r=this.ops.pop();if(!r)return this;return this.ops.push((n,s,i)=>Promise.race([r(n,s,i),e(t,i).then(()=>{throw Error("timeout")})])),this}catch(t){const r=this.ops.pop();if(!r)return this;return this.ops.push(async(n,e,s)=>{try{return await r(n,e,s)}catch(r){return t(r,e)}}),this}}function i(e,i,o){const a=t(null),u=t(null!=o?o:{});u.current=null!=o?o:u.current,r(()=>{var t;null===(t=a.current)||void 0===t||t.cancel();const r=s.from(e,u.current),n=i(r);return a.current=n,n.run(),()=>n.cancel()},[e,i]);return{cancel:n(()=>{var t;null===(t=a.current)||void 0===t||t.cancel()},[]),pause:n(()=>{var t;null===(t=a.current)||void 0===t||t.pause()},[]),resume:n(()=>{var t;null===(t=a.current)||void 0===t||t.resumeFlow()},[]),flow:a.current}}s.SKIP=Symbol("FLOW_SKIP");export{s as Flow,e as sleep,i as useFlow};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "react-flow-z",
+  "version": "1.0.0-z",
+  "description": "A lightweight async flow runtime for orchestrating side effects with explicit control over cancellation, debounce, throttling, and execution order.",
+  "license": "MIT",
+  "author": "Delpi.Kye",
+  "sideEffects": false,
+  "type": "module",
+  "main": "build/index.cjs.js",
+  "module": "build/index.esm.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.esm.js",
+      "require": "./build/index.cjs.js"
+    }
+  },
+  "files": ["build"],
+  "scripts": {
+    "clean": "rimraf build",
+    "dev": "rollup -c -w",
+    "build": "rollup -c",
+    "cb": "npm run clean && npm run build",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run cb"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/delpikye-v/react-flow.git"
+  },
+  "homepage": "https://github.com/delpikye-v/react-flow#readme",
+  "bugs": {
+    "url": "https://github.com/delpikye-v/react-flow/issues"
+  },
+  "keywords": [
+    "async-flow",
+    "async-runtime",
+    "side-effects",
+    "effect-orchestration",
+    "cancellation",
+    "debounce",
+    "throttle",
+    "takeLatest",
+    "queue",
+    "abort-controller",
+    "flow-control",
+    "headless",
+    "framework-agnostic",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "react": ">=16.8"
+  },
+  "devDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@types/react": "^18.2.0",
+
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.12.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}