jrx 0.0.2 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@ A lightweight TypeScript library for managing side effects, subscriptions, and a
 ## Installation
 
 ```bash
-npm install jrx
+npm i jrx
 ```
 
 ## Features
@@ -17,6 +17,20 @@ npm install jrx
 - Composable reactive utilities
 - Browser and Node.js compatible
 
+## API Overview
+
+- [`makeRenderLoop()`](#makerenderloop) - Render loops with automatic cleanup
+- [`addEvtListener(target, event, handler, option?)`](#addevtlistenertarget-event-handler-option) - Event listeners with cleanup
+- [`addInterval(cb, ms)`](#addintervalcb-ms) - Repeating intervals with cleanup
+- [`addIntervalAsync(cb, ms)`](#addintervalasynccb-ms) - Async intervals with cancellation
+- [`addRequestAnimationFrame(cb)`](#addrequestanimationframecb) - Single animation frame with cleanup
+- [`addRequestAnimationFrameLoop(cb)`](#addrequestanimationframeloopcb) - Animation frame loops
+- [`addSubs(subs, cb, options?)`](#addsubssubs-cb-options) - Multiple subscription management
+- [`addTimeout(cb, ms)`](#addtimeoutcb-ms) - Timeouts with cleanup
+- [`addTransition(cb, durationMs)`](#addtransitioncb-durationms) - Progress-based animations
+- [`computed(fn, getDeps?)`](#computedfn-getdeps) - Memoized computed values
+- [`retry(cb, options?)`](#retrycb-options) - Async retry with exponential backoff
+
 ## API
 
 ### `makeRenderLoop()`
@@ -45,15 +59,39 @@ requestAnimationFrame(loop)
 dispose()
 ```
 
+### `addEvtListener(target, event, handler, option?)`
+
+Adds an event listener to a target and returns a disposer that removes it. Works with any object that implements `addEventListener`/`removeEventListener` (DOM elements, `window`, `document`, etc.).
+
+```typescript
+import { addEvtListener } from 'jrx'
+
+// Basic usage
+const dispose = addEvtListener(window, 'resize', (e) => {
+  console.log('Window resized', e)
+})
+
+// With options
+const dispose2 = addEvtListener(element, 'click', (e) => {
+  console.log('Clicked', e)
+}, { capture: true })
+
+// Cleanup
+dispose()
+dispose2()
+```
+
 ### `addInterval(cb, ms)`
 
 Creates a repeating interval with cleanup. The callback can optionally return a cleanup function that runs before the next invocation.
 
+**Note:** The callback fires **immediately** on first call, then waits `ms` milliseconds **after** the previous callback completes. This is not a fixed-rate timer.
+
 ```typescript
 import { addInterval } from 'jrx'
 
 const dispose = addInterval(() => {
-  console.log('Tick')
+  console.log('Tick') // Called immediately, then every 1000ms after completion
 
   // Optional: return cleanup function
   return () => {
@@ -69,10 +107,13 @@ dispose()
 
 Async version of `addInterval`. Waits for the callback to complete before scheduling the next invocation.
 
+**Note:** The callback fires **immediately** on first call, then waits `ms` milliseconds **after** the previous async callback completes.
+
 ```typescript
 import { addIntervalAsync } from 'jrx'
 
 const dispose = addIntervalAsync(async (disposer) => {
+  // Called immediately, then 5000ms after each completion
   await fetchData()
 
   // Check if disposed during async operation
@@ -86,7 +127,7 @@ dispose()
 
 ### `addRequestAnimationFrame(cb)`
 
-Creates a `requestAnimationFrame` loop with cleanup.
+Executes a callback on the next animation frame with cleanup.
 
 ```typescript
 import { addRequestAnimationFrame } from 'jrx'
@@ -100,6 +141,27 @@ const dispose = addRequestAnimationFrame((now) => {
   }
 })
 
+// Cancel if needed before the frame fires
+dispose()
+```
+
+### `addRequestAnimationFrameLoop(cb)`
+
+Creates a continuous `requestAnimationFrame` loop with cleanup.
+
+```typescript
+import { addRequestAnimationFrameLoop } from 'jrx'
+
+const dispose = addRequestAnimationFrameLoop((now) => {
+  updateAnimation(now)
+
+  // Optional: return cleanup function
+  return () => {
+    cleanupAnimation()
+  }
+})
+
+// Stop the loop
 dispose()
 ```
 
@@ -196,8 +258,10 @@ console.log(value2.value) // Recomputed: 12
 
 Retries an async operation with exponential backoff on failure.
 
+**Default backoff:** `[5, 5, 10, 10, 20, 20, 40, 40, 60, -1]` seconds (where `-1` means retry forever with 60s delay)
+
 ```typescript
-import retry from 'jrx/retry'
+import {retry} from 'jrx'
 
 // Basic usage - retries with default backoff
 const result = await retry(async (disposer, { resetBackoff }) => {
@@ -249,7 +313,8 @@ console.log(data) // T | undefined
 ```
 
 **Options:**
-- `backoffSec`: Array of retry delays in seconds. Use `-1` for infinite retries with the last delay. Default: `[5, 5, 10, 10, 20, 20, 40, 40, 60, -1]`
+- `backoffSec`: Array of retry delays in seconds. Use `-1` for infinite retries with the last delay.
+  - Default: `[5, 5, 10, 10, 20, 20, 40, 40, 60, -1]`
 - `disposer`: Optional disposer for cancellation. When provided, the return type is `T | undefined`. Otherwise, the return type is `T`.
 
 **Callback parameters:**
@@ -269,7 +334,7 @@ const disposer = makeDisposer()
 // Collect disposers
 disposer.add(addInterval(() => console.log('tick'), 1000))
 disposer.add(addTimeout(() => console.log('timeout'), 5000))
-disposer.add(addRequestAnimationFrame((now) => render(now)))
+disposer.add(addRequestAnimationFrameLoop((now) => render(now)))
 
 // Cleanup all at once
 disposer.dispose()

package/addEvtListener.d.ts

@@ -0,0 +1,15 @@
+type IEventHandler<Target extends {
+    addEventListener(event: string, handler: any, option?: any): any;
+}, EventName> = Target['addEventListener'] extends (event: EventName, handler: infer Handler, ...args: any[]) => any ? Handler extends (...params: any[]) => any ? Handler : never : never;
+type IEventOption<Target extends {
+    addEventListener(event: string, handler: any, option?: any): any;
+}, EventName, Handler> = Target['addEventListener'] extends (event: EventName, handler: Handler, option: infer Option) => any ? Option : never;
+export default function addEvtListener<Target extends {
+    addEventListener(event: string, handler: any, option?: any): any;
+    removeEventListener(event: string, handler: any, option?: any): any;
+}, EventName extends Parameters<Target['addEventListener']>[0], Handler extends IEventHandler<Target, EventName>>(target: Target, event: EventName, handler: Handler, option?: IEventOption<Target, EventName, Handler>): () => void;
+export default function addEvtListener<Target extends {
+    addEventListener(event: string, handler: any, option?: any): any;
+    removeEventListener(event: string, handler: any, option?: any): any;
+}, EventName extends Parameters<Target['addEventListener']>[0]>(target: Target, event: EventName, handler: (...args: any[]) => any, option?: IEventOption<Target, EventName, IEventHandler<Target, EventName>>): () => void;
+export {};

package/addEvtListener.js

@@ -0,0 +1,6 @@
+export default function addEvtListener(target, event, handler, option) {
+    target.addEventListener(event, handler, option);
+    return function removeEvtListener() {
+        return target.removeEventListener(event, handler, option);
+    };
+}

package/index.d.ts

@@ -1,4 +1,8 @@
 import { type Disposer } from 'jdisposer';
+import retry from './retry.js';
+import computed from './computed.js';
+import addEvtListener from './addEvtListener.js';
+export { retry, computed, addEvtListener };
 export declare function makeRenderLoop(): {
     loop(this: void, time: DOMHighResTimeStamp): void;
     setLoop(this: void, loop: (time: DOMHighResTimeStamp) => void | (() => void)): () => void;
@@ -6,6 +10,7 @@ export declare function makeRenderLoop(): {
 export declare function addInterval(cb: () => void | (() => any), ms: number): () => void;
 export declare function addIntervalAsync(cb: (disposer: Disposer) => void | (() => any) | Promise<void> | Promise<() => any>, ms: number): () => void;
 export declare function addRequestAnimationFrame(cb: (now: DOMHighResTimeStamp) => void | (() => any)): () => void;
+export declare function addRequestAnimationFrameLoop(cb: (now: DOMHighResTimeStamp) => void | (() => any)): () => void;
 export declare function addSubs<Subs extends any[]>(subs: Subs, cb: () => void | (() => void), { now }?: {
     now?: boolean;
 }): (this: void) => void;

package/index.js

@@ -1,4 +1,8 @@
 import { makeDisposer, makeReset } from 'jdisposer';
+import retry from './retry.js';
+import computed from './computed.js';
+import addEvtListener from './addEvtListener.js';
+export { retry, computed, addEvtListener };
 export function makeRenderLoop() {
     let loop_;
     const reset = makeReset();
@@ -44,6 +48,14 @@ export function addIntervalAsync(cb, ms) {
     }
 }
 export function addRequestAnimationFrame(cb) {
+    const disposer = makeDisposer();
+    const raf = requestAnimationFrame(now => disposer.add(cb(now)));
+    return () => {
+        disposer.dispose();
+        cancelAnimationFrame(raf);
+    };
+}
+export function addRequestAnimationFrameLoop(cb) {
     const reset = makeReset();
     let raf = requestAnimationFrame(wrapper);
     return () => {

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "jrx",
-	"version": "0.0.2",
+	"version": "0.2.0",
 	"type": "module",
 	"scripts": {
-		"prepublishOnly": "npx tsc index.ts retry.ts computed.ts --target esnext --declaration --moduleResolution node",
+		"prepublishOnly": "npx tsc",
 		"test": "node --test tests/*.test.ts",
 		"test:coverage": "node --test --experimental-test-coverage tests/*.test.ts"
 	},
@@ -11,14 +11,6 @@
 		".": {
 			"types": "./index.d.ts",
 			"import": "./index.js"
-		},
-		"./retry": {
-			"types": "./retry.d.ts",
-			"import": "./retry.js"
-		},
-		"./computed": {
-			"types": "./computed.d.ts",
-			"import": "./computed.js"
 		}
 	},
 	"repository": {
@@ -31,7 +23,9 @@
 		"retry.js",
 		"retry.d.ts",
 		"computed.js",
-		"computed.d.ts"
+		"computed.d.ts",
+		"addEvtListener.js",
+		"addEvtListener.d.ts"
 	],
 	"devDependencies": {
 		"@types/node": "^25.2.1",