@clagradi/effect-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,180 @@
+# effect-runtime
+
+`@clagradi/effect-runtime` is a tiny React 18+ primitive that makes async effects safer than raw `useEffect`.
+
+## Install
+
+```bash
+npm i @clagradi/effect-runtime
+```
+
+## API
+
+```ts
+export function useEvent<T extends (...args: any[]) => any>(fn: T): T;
+
+type EffectTaskScope = {
+	signal: AbortSignal;
+	runId: number;
+	isActive(): boolean;
+	commit(fn: () => void): void;
+	onCleanup(fn: () => void): void;
+};
+
+type EffectTask =
+	(scope: EffectTaskScope) =>
+		void | (() => void) | Promise<void | (() => void)>;
+
+export function useEffectTask(
+	task: EffectTask,
+	deps: any[],
+	options?: { layout?: boolean; onError?: (err: unknown) => void; debugName?: string }
+): void;
+```
+
+## Quickstart
+
+### Example 1: fetch with `signal` + anti-race `commit`
+
+```tsx
+import { useState } from 'react';
+import { useEffectTask } from '@clagradi/effect-runtime';
+
+export function UserCard({ userId }: { userId: string }) {
+	const [name, setName] = useState('loading...');
+
+	useEffectTask(
+		async ({ signal, commit }) => {
+			const response = await fetch(`/api/users/${userId}`, { signal });
+			const user = (await response.json()) as { name: string };
+
+			commit(() => {
+				setName(user.name);
+			});
+		},
+		[userId]
+	);
+
+	return <div>{name}</div>;
+}
+```
+
+### Example 2: interval with `useEvent`
+
+```tsx
+import { useState } from 'react';
+import { useEffectTask, useEvent } from '@clagradi/effect-runtime';
+
+export function Counter() {
+	const [count, setCount] = useState(0);
+	const onTick = useEvent(() => setCount((value) => value + 1));
+
+	useEffectTask(({ onCleanup }) => {
+		const handle = setInterval(() => onTick(), 1000);
+		onCleanup(() => clearInterval(handle));
+	}, []);
+
+	return <span>{count}</span>;
+}
+```
+
+### Example 3: subscription with `onCleanup`
+
+```tsx
+import { useEffectTask } from '@clagradi/effect-runtime';
+
+type Subscription = { unsubscribe: () => void };
+declare function subscribeToRoom(roomId: string, cb: (msg: string) => void): Subscription;
+
+export function RoomFeed({ roomId }: { roomId: string }) {
+	useEffectTask(({ onCleanup }) => {
+		const sub = subscribeToRoom(roomId, (msg) => {
+			console.log(msg);
+		});
+
+		onCleanup(() => sub.unsubscribe());
+	}, [roomId]);
+
+	return null;
+}
+```
+
+## Why better than useEffect
+
+- Per-run `AbortController` (auto-abort on rerun/unmount)
+- `commit()` anti-race guard for stale async completions
+- Multiple cleanups with LIFO execution via `onCleanup()`
+- Late async cleanup is never lost (executes immediately if resolved after dispose)
+- `useEvent` gives stable identity + latest closure
+
+## Caveats
+
+- This is not a data-fetching cache layer (not React Query/SWR).
+- No SSR orchestration/caching features.
+
+## Release checklist
+
+1. Run package checks:
+
+	 ```bash
+	 npm run typecheck
+	 npm run test
+	 npm run build
+	 ```
+
+2. Create a package tarball:
+
+	 ```bash
+	 npm pack
+	 ```
+
+3. Install locally in a separate app (use either method):
+
+	 ```bash
+	 # from repo folder path
+	 npm i /absolute/path/to/UseEffectState
+
+	 # from generated tarball
+	 npm i /absolute/path/to/UseEffectState/clagradi-effect-runtime-0.1.0.tgz
+	 ```
+
+4. Verify in the consumer app:
+
+	 - `import { useEffectTask, useEvent } from '@clagradi/effect-runtime'` resolves.
+	 - TypeScript picks up package types from `dist/index.d.ts` (run `npm run typecheck`).
+
+## Publishing to npm
+
+1. Check package name availability:
+
+	 ```bash
+	 npm view @clagradi/effect-runtime
+	 # 404 => available
+	 ```
+
+2. Login:
+
+	 ```bash
+	 npm login
+	 ```
+
+3. Publish the package:
+
+	 ```bash
+	 npm publish --access public
+	 ```
+
+	 Scoped packages default to private. Always pass `--access public` for public releases.
+
+4. Versioning:
+
+	 ```bash
+	 npm version patch # or minor / major
+	 git push
+	 git push --tags
+	 ```
+
+5. Tag/release strategy:
+
+	 - CI publish runs when pushing a tag matching `v*` (for example `v0.1.0`) or when a GitHub Release is published.
+	 - The publish workflow uses `npm publish --provenance --access public` with `NODE_AUTH_TOKEN=${{ secrets.NPM_TOKEN }}`.

package/dist/index.cjs

@@ -0,0 +1,145 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useEffectTask: () => useEffectTask,
+  useEvent: () => useEvent
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useEvent.ts
+var import_react = require("react");
+function useEvent(fn) {
+  const fnRef = (0, import_react.useRef)(fn);
+  fnRef.current = fn;
+  const stableFn = (0, import_react.useCallback)((...args) => {
+    return fnRef.current(...args);
+  }, []);
+  return stableFn;
+}
+
+// src/useEffectTask.ts
+var import_react2 = require("react");
+function isPromise(value) {
+  return typeof value?.then === "function";
+}
+function isAbortError(error) {
+  return error instanceof DOMException && (error.name === "AbortError" || error.code === DOMException.ABORT_ERR);
+}
+function reportError(error, signal, options) {
+  if (signal.aborted || isAbortError(error)) {
+    return;
+  }
+  if (options?.onError) {
+    options.onError(error);
+    return;
+  }
+  const runtime = globalThis;
+  if (runtime.process?.env?.NODE_ENV !== "production") {
+    console.error(
+      `[useEffectTask${options?.debugName ? `:${options.debugName}` : ""}]`,
+      error
+    );
+  }
+}
+function useEffectTask(task, deps, options) {
+  const runIdRef = (0, import_react2.useRef)(0);
+  const latestTask = useEvent(task);
+  const selectedEffect = options?.layout ? import_react2.useLayoutEffect : import_react2.useEffect;
+  selectedEffect(() => {
+    const runId = ++runIdRef.current;
+    const controller = new AbortController();
+    const cleanupStack = [];
+    let taskCleanup;
+    let disposed = false;
+    const isActive = () => {
+      return !controller.signal.aborted && runIdRef.current === runId && !disposed;
+    };
+    const runCleanup = (cleanup) => {
+      if (!cleanup) {
+        return;
+      }
+      try {
+        cleanup();
+      } catch (error) {
+        reportError(error, controller.signal, options);
+      }
+    };
+    const dispose = () => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      controller.abort();
+      for (let index = cleanupStack.length - 1; index >= 0; index -= 1) {
+        runCleanup(cleanupStack[index]);
+      }
+      cleanupStack.length = 0;
+      runCleanup(taskCleanup);
+      taskCleanup = void 0;
+    };
+    const scope = {
+      signal: controller.signal,
+      runId,
+      isActive,
+      commit: (fn) => {
+        if (!isActive()) {
+          return;
+        }
+        fn();
+      },
+      onCleanup: (fn) => {
+        if (disposed) {
+          runCleanup(fn);
+          return;
+        }
+        cleanupStack.push(fn);
+      }
+    };
+    try {
+      const output = latestTask(scope);
+      if (isPromise(output)) {
+        output.then((resolvedCleanup) => {
+          if (typeof resolvedCleanup !== "function") {
+            return;
+          }
+          if (disposed || !isActive()) {
+            runCleanup(resolvedCleanup);
+            return;
+          }
+          taskCleanup = resolvedCleanup;
+        }).catch((error) => {
+          reportError(error, controller.signal, options);
+        });
+      } else if (typeof output === "function") {
+        taskCleanup = output;
+      }
+    } catch (error) {
+      reportError(error, controller.signal, options);
+    }
+    return dispose;
+  }, deps);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useEffectTask,
+  useEvent
+});

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+declare function useEvent<T extends (...args: any[]) => any>(fn: T): T;
+
+type EffectTaskCleanup = () => void;
+interface EffectTaskScope {
+    signal: AbortSignal;
+    runId: number;
+    isActive: () => boolean;
+    commit: (fn: () => void) => void;
+    onCleanup: (fn: EffectTaskCleanup) => void;
+}
+interface UseEffectTaskOptions {
+    layout?: boolean;
+    onError?: (err: unknown) => void;
+    debugName?: string;
+}
+type EffectTask = (scope: EffectTaskScope) => void | EffectTaskCleanup | Promise<void | EffectTaskCleanup>;
+declare function useEffectTask(task: EffectTask, deps: any[], options?: UseEffectTaskOptions): void;
+
+export { type EffectTask, type EffectTaskCleanup, type EffectTaskScope, type UseEffectTaskOptions, useEffectTask, useEvent };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+declare function useEvent<T extends (...args: any[]) => any>(fn: T): T;
+
+type EffectTaskCleanup = () => void;
+interface EffectTaskScope {
+    signal: AbortSignal;
+    runId: number;
+    isActive: () => boolean;
+    commit: (fn: () => void) => void;
+    onCleanup: (fn: EffectTaskCleanup) => void;
+}
+interface UseEffectTaskOptions {
+    layout?: boolean;
+    onError?: (err: unknown) => void;
+    debugName?: string;
+}
+type EffectTask = (scope: EffectTaskScope) => void | EffectTaskCleanup | Promise<void | EffectTaskCleanup>;
+declare function useEffectTask(task: EffectTask, deps: any[], options?: UseEffectTaskOptions): void;
+
+export { type EffectTask, type EffectTaskCleanup, type EffectTaskScope, type UseEffectTaskOptions, useEffectTask, useEvent };

package/dist/index.js

@@ -0,0 +1,117 @@
+// src/useEvent.ts
+import { useCallback, useRef } from "react";
+function useEvent(fn) {
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+  const stableFn = useCallback((...args) => {
+    return fnRef.current(...args);
+  }, []);
+  return stableFn;
+}
+
+// src/useEffectTask.ts
+import { useEffect, useLayoutEffect, useRef as useRef2 } from "react";
+function isPromise(value) {
+  return typeof value?.then === "function";
+}
+function isAbortError(error) {
+  return error instanceof DOMException && (error.name === "AbortError" || error.code === DOMException.ABORT_ERR);
+}
+function reportError(error, signal, options) {
+  if (signal.aborted || isAbortError(error)) {
+    return;
+  }
+  if (options?.onError) {
+    options.onError(error);
+    return;
+  }
+  const runtime = globalThis;
+  if (runtime.process?.env?.NODE_ENV !== "production") {
+    console.error(
+      `[useEffectTask${options?.debugName ? `:${options.debugName}` : ""}]`,
+      error
+    );
+  }
+}
+function useEffectTask(task, deps, options) {
+  const runIdRef = useRef2(0);
+  const latestTask = useEvent(task);
+  const selectedEffect = options?.layout ? useLayoutEffect : useEffect;
+  selectedEffect(() => {
+    const runId = ++runIdRef.current;
+    const controller = new AbortController();
+    const cleanupStack = [];
+    let taskCleanup;
+    let disposed = false;
+    const isActive = () => {
+      return !controller.signal.aborted && runIdRef.current === runId && !disposed;
+    };
+    const runCleanup = (cleanup) => {
+      if (!cleanup) {
+        return;
+      }
+      try {
+        cleanup();
+      } catch (error) {
+        reportError(error, controller.signal, options);
+      }
+    };
+    const dispose = () => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      controller.abort();
+      for (let index = cleanupStack.length - 1; index >= 0; index -= 1) {
+        runCleanup(cleanupStack[index]);
+      }
+      cleanupStack.length = 0;
+      runCleanup(taskCleanup);
+      taskCleanup = void 0;
+    };
+    const scope = {
+      signal: controller.signal,
+      runId,
+      isActive,
+      commit: (fn) => {
+        if (!isActive()) {
+          return;
+        }
+        fn();
+      },
+      onCleanup: (fn) => {
+        if (disposed) {
+          runCleanup(fn);
+          return;
+        }
+        cleanupStack.push(fn);
+      }
+    };
+    try {
+      const output = latestTask(scope);
+      if (isPromise(output)) {
+        output.then((resolvedCleanup) => {
+          if (typeof resolvedCleanup !== "function") {
+            return;
+          }
+          if (disposed || !isActive()) {
+            runCleanup(resolvedCleanup);
+            return;
+          }
+          taskCleanup = resolvedCleanup;
+        }).catch((error) => {
+          reportError(error, controller.signal, options);
+        });
+      } else if (typeof output === "function") {
+        taskCleanup = output;
+      }
+    } catch (error) {
+      reportError(error, controller.signal, options);
+    }
+    return dispose;
+  }, deps);
+}
+export {
+  useEffectTask,
+  useEvent
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@clagradi/effect-runtime",
+  "version": "0.1.0",
+  "description": "Better async effect primitive for React 18+",
+  "license": "MIT",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.13.10",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}