react-action-z 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 delpikye-v
+
+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,490 @@
+# ⚡ react-action-z
+
+[![NPM](https://img.shields.io/npm/v/react-action-z.svg)](https://www.npmjs.com/package/react-action-z) ![Downloads](https://img.shields.io/npm/dt/react-action-z.svg)
+
+<a href="https://codesandbox.io/p/sandbox/hgk4hx" target="_blank">LIVE EXAMPLE</a>
+
+Unified async action layer for React.
+
+> Run async functions as **actions**, not boilerplate.
+> Actions run only when you call run() — never automatically.
+
+---
+
+# Why react-action-z?
+
+- ⚡ Unified async actions
+- 🧠 Built-in loading / error state
+- 🔁 Retry support
+- 🧩 Middleware system
+- 🌍 Global action state
+- 🧾 Full TypeScript support
+
+Traditional async UI code:
+
+```ts
+const [loading, setLoading] = useState(false)
+const [error, setError] = useState(null)
+
+async function login(data) {
+  try {
+    setLoading(true)
+    const result = await api.login(data)
+  } catch (err) {
+    setError(err)
+  } finally {
+    setLoading(false)
+  }
+}
+```
+
+React Action:
+
+```ts
+const login = useAction(api.login)
+
+await login.run(data)
+```
+
+UI state automatically available:
+
+```ts
+login.loading
+login.data
+login.error
+```
+
+---
+
+# Installation
+
+```bash
+npm install react-action-z
+```
+
+---
+
+# Basic Usage
+
+```ts
+import { useAction } from "react-action-z"
+
+const login = useAction(api.login)
+
+await login.run({
+  email,
+  password
+})
+```
+
+State is automatically managed:
+
+```ts
+login.loading
+login.data
+login.error
+```
+
+UI example:
+
+```tsx
+<button disabled={login.loading}>
+  {login.loading ? "Loading..." : "Login"}
+</button>
+```
+
+---
+
+# Example with JSONPlaceholder
+
+Example using the free API from JSONPlaceholder.
+
+Fetch a user from:
+
+```
+https://jsonplaceholder.typicode.com/users/1
+```
+
+---
+
+## API
+
+```ts
+async function fetchUser(id: number) {
+  const res = await fetch(
+    `https://jsonplaceholder.typicode.com/users/${id}`
+  )
+
+  if (!res.ok) {
+    throw new Error("Failed to fetch user")
+  }
+
+  return res.json()
+}
+```
+
+---
+
+## React Component
+
+```tsx
+import React from "react"
+import { useAction } from "react-action-z"
+
+async function fetchUser(id: number) {
+  const res = await fetch(
+    `https://jsonplaceholder.typicode.com/users/${id}`
+  )
+
+  if (!res.ok) {
+    throw new Error("Failed to fetch user")
+  }
+
+  return res.json()
+}
+
+export default function UserExample() {
+
+  const getUser = useAction(fetchUser)
+
+  return (
+    <div>
+
+      <button
+        onClick={() => getUser.run(1)}
+        disabled={getUser.loading}
+      >
+        {getUser.loading ? "Loading..." : "Load User"}
+      </button>
+
+      {getUser.error && (
+        <p>Error loading user</p>
+      )}
+
+      {getUser.data && (
+        <div style={{ marginTop: 20 }}>
+          <h3>{getUser.data.name}</h3>
+          <p>{getUser.data.email}</p>
+          <p>{getUser.data.phone}</p>
+        </div>
+      )}
+
+    </div>
+  )
+}
+```
+
+---
+
+## Result
+
+Click the button:
+
+```
+Load User
+```
+
+The action automatically manages:
+
+```
+loading
+data
+error
+```
+
+Example returned data:
+
+```json
+{
+  "id": 1,
+  "name": "Leanne Graham",
+  "username": "Bret",
+  "email": "Sincere@april.biz",
+  "phone": "1-770-736-8031"
+}
+```
+
+---
+
+# Action API
+
+```ts
+const action = useAction(fn, options)
+```
+
+Return value:
+
+```ts
+action.run(...)
+action.loading
+action.data
+action.error
+action.reset()
+```
+
+---
+
+# Options
+
+```ts
+useAction(api.login, {
+  retry: 2,
+  strategy: "replace",
+  key: "login",
+  optimistic: (data) => {},
+  onSuccess: (data) => {},
+  onError: (err) => {}
+})
+```
+
+| option      | description         |
+|-------------|---------------------|
+| retry       | retry on failure    |
+| strategy    | concurrency control |
+| key         | global action key   |
+| optimistic  | optimistic update   |
+| onSuccess   | success callback    |
+| onError     | error callback      |
+
+---
+
+# Concurrency Strategy
+
+```ts
+useAction(api.save, {
+  strategy: "ignore"
+})
+```
+
+| strategy | behavior                          |
+|----------|-----------------------------------|
+| replace  | only latest result updates state  |
+| ignore   | ignore if running                 |
+| parallel | allow multiple runs               |
+
+Example:
+
+```ts
+const save = useAction(api.save, {
+  strategy: "ignore"
+})
+```
+
+Prevent double submit.
+
+---
+
+# Retry
+
+Automatically retry failed requests.
+
+```ts
+const fetchUser = useAction(api.fetchUser, {
+  retry: 2
+})
+```
+
+Behavior:
+
+```text
+attempt 1
+attempt 2
+attempt 3
+```
+
+---
+
+# Optimistic Update
+
+Apply UI update before request finishes.
+
+```ts
+const updateUser = useAction(api.updateUser, {
+  optimistic: (data) => {
+    setUser(data)
+  }
+})
+```
+
+This improves UI responsiveness.
+
+---
+
+# Global Action State
+
+Actions can share state across components.
+
+```ts
+import { useAction } from "react-action-z"
+
+const login = useAction(api.login, {
+  key: "login"
+})
+
+export function LoginButton() {
+  return (
+    <button
+      disabled={login.loading}
+      onClick={() => login.run({ email, password })}
+    >
+      {login.loading ? "Logging in..." : "Login"}
+    </button>
+  )
+}
+```
+
+Access anywhere:
+
+```ts
+// GlobalSpinner.tsx
+
+import { useGlobalAction } from "react-action-z"
+
+export function GlobalSpinner() {
+
+  const login = useGlobalAction("login")
+
+  if (!login.loading) return null
+
+  return <div>Authenticating...</div>
+}
+```
+
+Result:
+- LoginButton triggers action
+- GlobalSpinner reacts automatically
+
+---
+
+# Middleware
+
+React Action supports middleware similar to Redux.
+
+```ts
+import { createActionClient } from "react-action-z"
+
+createActionClient({
+  middleware: [
+    async (context, next) => {
+      console.log("action:", context.key)
+      return next()
+    }
+  ]
+})
+```
+
+Middleware context:
+
+```ts
+{
+  key?: string
+  args: any[]
+}
+```
+
+Use cases:
+
+- logging
+- analytics
+- metrics
+- debugging
+
+---
+
+# Reset State
+
+Reset action state manually.
+
+```ts
+login.reset()
+```
+
+Result:
+
+```ts
+{
+  loading: false
+  data: null
+  error: null
+}
+```
+
+---
+
+# Example
+
+```ts
+const createPost = useAction(api.createPost, {
+  retry: 1
+})
+
+async function handleSubmit(data) {
+  await createPost.run(data)
+}
+```
+
+UI:
+
+```tsx
+<button disabled={createPost.loading}>
+  Publish
+</button>
+
+{createPost.error && <p>Error</p>}
+```
+
+---
+
+# Comparison
+
+| Criteria            | react-action-z | React state |
+|---------------------|----------------|-------------|
+| Async state         | ✅             | manual      |
+| Retry               | ✅             | manual      |
+| Global action state | ✅             | ❌          |
+| Middleware          | ✅             | ❌          |
+| Optimistic update   | ✅             | manual      |
+| Boilerplate         | minimal        | high        |
+
+---
+
+# Architecture
+
+```text
+Component
+    ↓
+useAction()
+    ↓
+Action Runner
+    ↓
+Middleware
+    ↓
+Async Function
+    ↓
+State Update
+```
+
+---
+
+# Philosophy
+
+React Action treats async functions as **first-class UI actions**.
+
+Instead of manually managing:
+
+- loading
+- error
+- retries
+- concurrency
+
+You simply run actions:
+
+```ts
+action.run()
+```
+
+---
+
+# License
+
+MIT

package/build/core/client.d.ts

@@ -0,0 +1,5 @@
+import type { Middleware } from "./middleware";
+export declare function createActionClient(options: {
+    middleware?: Middleware[];
+}): void;
+export declare function getGlobalMiddleware(): Middleware[];

package/build/core/middleware.d.ts

@@ -0,0 +1,6 @@
+export type MiddlewareContext = {
+    key?: string;
+    args: any[];
+};
+export type Middleware = (context: MiddlewareContext, next: () => Promise<any>) => Promise<any>;
+export declare function runMiddleware(context: MiddlewareContext, middleware: Middleware[], fn: () => Promise<any>): Promise<any>;

package/build/core/store.d.ts

@@ -0,0 +1,9 @@
+type ActionState<TResult> = {
+    loading: boolean;
+    data: TResult | null;
+    error: any;
+};
+export declare function setGlobalState(key: string, state: ActionState<any>): void;
+export declare function subscribe(key: string, fn: Function): () => void;
+export declare function getGlobalState(key: string): ActionState<any> | undefined;
+export {};

package/build/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { useAction } from "./useAction";
+export { useActionStatus } from "./useActionStatus";
+export { useGlobalAction } from "./useGlobalAction";

package/build/hooks/useAction.d.ts

@@ -0,0 +1,21 @@
+import type { Middleware } from "../core/middleware";
+type AsyncFn<TArgs extends any[], TResult> = (...args: TArgs) => Promise<TResult>;
+type Strategy = "replace" | "ignore" | "parallel";
+type ActionOptions<TArgs extends any[], TResult> = {
+    key?: string;
+    retry?: number;
+    retryDelay?: number;
+    strategy?: Strategy;
+    optimistic?: (...args: TArgs) => void;
+    middleware?: Middleware[];
+    onSuccess?: (data: TResult) => void;
+    onError?: (err: any) => void;
+};
+export declare function useAction<TArgs extends any[], TResult>(fn: AsyncFn<TArgs, TResult>, options?: ActionOptions<TArgs, TResult>): {
+    loading: boolean;
+    data: TResult | null;
+    error: any;
+    run: (...args: TArgs) => Promise<any>;
+    reset: () => void;
+};
+export {};

package/build/hooks/useActionStatus.d.ts

@@ -0,0 +1,5 @@
+export declare function useActionStatus<TData = any>(action: {
+    loading: boolean;
+    data: TData | null;
+    error: any;
+}, field?: "loading" | "data" | "error"): any;

package/build/hooks/useGlobalAction.d.ts

@@ -0,0 +1,7 @@
+type ActionState<TResult = any> = {
+    loading: boolean;
+    data: TResult | null;
+    error: any;
+};
+export declare function useGlobalAction<TResult = any>(key: string): ActionState<TResult>;
+export {};

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./hooks";
+export { createActionClient } from "./core/client";
+export { logger } from "./middleware/logger";
+export type { Middleware } from "./core/middleware";

package/build/index.esm.js

@@ -0,0 +1 @@
+import{useState as r,useRef as t,useCallback as n,useEffect as e}from"react";let o=[];function a(r){o=r.middleware||[]}const c=new Map,l=new Map;function i(r,t){c.set(r,t);const n=l.get(r);n&&n.forEach(r=>r(t))}async function u(r,t,n,e){try{return await r(...t)}catch(a){if(n>0)return await(o=e,new Promise(r=>setTimeout(r,o))),u(r,t,n-1,e);throw a}var o}function s(e,a={}){const{key:c,retry:l=0,retryDelay:s=500,strategy:d="replace",optimistic:g,middleware:f=[],onSuccess:y,onError:w}=a,[m,p]=r({loading:!1,data:null,error:null}),h=t(!1),k=t(0),D=n(async(...r)=>{if("ignore"===d&&h.current)return;const t=++k.current;"parallel"!==d&&(h.current=!0),g?.(...r),p(r=>({...r,loading:!0,error:null}));const n={key:c,args:r};try{const a=await function(r,t,n){let e=-1;const o=a=>{if(a<=e)return Promise.reject();e=a;const c=t[a];return c?c(r,()=>o(a+1)):n()};return o(0)}(n,[...o,...f],()=>u(e,r,l,s));if("replace"!==d||t===k.current){const r={loading:!1,data:a,error:null};p(r),c&&i(c,r),y?.(a)}return a}catch(r){if("replace"!==d||t===k.current){const t={loading:!1,data:null,error:r};p(t),c&&i(c,t),w?.(r)}throw r}finally{"parallel"!==d&&(h.current=!1)}},[e,l,s,d,g,f,c]),E=n(()=>{const r={loading:!1,data:null,error:null};p(r),c&&i(c,r)},[c]);return{loading:m.loading,data:m.data,error:m.error,run:D,reset:E}}function d(r,t){return t?r[t]:{loading:r.loading,data:r.data,error:r.error}}function g(t){const[n,o]=r(function(r){return c.get(r)}(t)||{loading:!1,data:null,error:null});return e(()=>function(r,t){return l.has(r)||l.set(r,new Set),l.get(r).add(t),()=>{l.get(r).delete(t)}}(t,o),[t]),n}function f(){return async(r,t)=>{const n=Date.now();console.log("[react-action] start:",r.key,r.args);try{const e=await t();return console.log("[react-action] success:",r.key,"time:",Date.now()-n,"ms"),e}catch(t){throw console.error("[react-action] error:",r.key,t),t}}}export{a as createActionClient,f as logger,s as useAction,d as useActionStatus,g as useGlobalAction};

package/build/index.js

@@ -0,0 +1 @@
+"use strict";var r=require("react");let t=[];const e=new Map,n=new Map;function a(r,t){e.set(r,t);const a=n.get(r);a&&a.forEach(r=>r(t))}async function o(r,t,e,n){try{return await r(...t)}catch(c){if(e>0)return await(a=n,new Promise(r=>setTimeout(r,a))),o(r,t,e-1,n);throw c}var a}exports.createActionClient=function(r){t=r.middleware||[]},exports.logger=function(){return async(r,t)=>{const e=Date.now();console.log("[react-action] start:",r.key,r.args);try{const n=await t();return console.log("[react-action] success:",r.key,"time:",Date.now()-e,"ms"),n}catch(t){throw console.error("[react-action] error:",r.key,t),t}}},exports.useAction=function(e,n={}){const{key:c,retry:l=0,retryDelay:s=500,strategy:u="replace",optimistic:i,middleware:d=[],onSuccess:g,onError:f}=n,[y,w]=r.useState({loading:!1,data:null,error:null}),p=r.useRef(!1),h=r.useRef(0),m=r.useCallback(async(...r)=>{if("ignore"===u&&p.current)return;const n=++h.current;"parallel"!==u&&(p.current=!0),i?.(...r),w(r=>({...r,loading:!0,error:null}));const y={key:c,args:r};try{const i=await function(r,t,e){let n=-1;const a=o=>{if(o<=n)return Promise.reject();n=o;const c=t[o];return c?c(r,()=>a(o+1)):e()};return a(0)}(y,[...t,...d],()=>o(e,r,l,s));if("replace"!==u||n===h.current){const r={loading:!1,data:i,error:null};w(r),c&&a(c,r),g?.(i)}return i}catch(r){if("replace"!==u||n===h.current){const t={loading:!1,data:null,error:r};w(t),c&&a(c,t),f?.(r)}throw r}finally{"parallel"!==u&&(p.current=!1)}},[e,l,s,u,i,d,c]),k=r.useCallback(()=>{const r={loading:!1,data:null,error:null};w(r),c&&a(c,r)},[c]);return{loading:y.loading,data:y.data,error:y.error,run:m,reset:k}},exports.useActionStatus=function(r,t){return t?r[t]:{loading:r.loading,data:r.data,error:r.error}},exports.useGlobalAction=function(t){const[a,o]=r.useState(function(r){return e.get(r)}(t)||{loading:!1,data:null,error:null});return r.useEffect(()=>function(r,t){return n.has(r)||n.set(r,new Set),n.get(r).add(t),()=>{n.get(r).delete(t)}}(t,o),[t]),a};

package/build/middleware/logger.d.ts

@@ -0,0 +1,2 @@
+import type { Middleware } from "../core/middleware";
+export declare function logger(): Middleware;

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "react-action-z",
+  "version": "0.0.1",
+  "description": "Turn async functions into UI actions. Handle loading, error, retry, and concurrency automatically.",
+  "author": "Delpi.Kye",
+  "license": "MIT",
+  "type": "module",
+
+  "main": "./build/index.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.js"
+    }
+  },
+
+  "files": [
+    "build"
+  ],
+
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "rimraf build && rollup -c",
+    "watch": "rollup -c -w",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/delpikye-v/react-action-z.git"
+  },
+  "homepage": "https://github.com/delpikye-v/react-action-z#readme",
+  "bugs": {
+    "url": "https://github.com/delpikye-v/react-action-z/issues"
+  },
+  "keywords": [
+    "react",
+    "react-hooks",
+    "async-actions",
+    "react-async",
+    "react-mutation",
+    "react-state",
+    "react-data",
+    "async-state",
+    "optimistic-ui",
+    "react-utils",
+    "react-library",
+    "frontend",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "rimraf": "^5.0.5",
+    "rollup": "^3.29.4",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tslib": "^2.6.2",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}