jrx 0.0.1 → 0.1.0

package/README.md

@@ -17,6 +17,19 @@ npm install jrx
 - Composable reactive utilities
 - Browser and Node.js compatible
 
+## API Overview
+
+- [`makeRenderLoop()`](#makerenderloop) - Render loops with automatic 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()`
@@ -49,11 +62,13 @@ dispose()
 
 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 +84,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 +104,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 +118,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,6 +235,8 @@ 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'
 
@@ -249,7 +290,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 +311,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/computed.d.ts

@@ -0,0 +1,3 @@
+export default function computed<T, Deps extends any[] = unknown[]>(fn: () => T, getDeps?: () => Deps): {
+    readonly value: T;
+};

package/computed.js

@@ -0,0 +1,17 @@
+export default function computed(fn, getDeps) {
+    let cached;
+    let lastDeps;
+    let first = true;
+    return {
+        get value() {
+            if (!getDeps)
+                return fn();
+            const deps = getDeps();
+            if (!first && deps.length === lastDeps.length && deps.every((dep, idx) => Object.is(dep, lastDeps[idx])))
+                return cached;
+            first = false;
+            lastDeps = deps;
+            return (cached = fn());
+        },
+    };
+}

package/index.d.ts

@@ -6,6 +6,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

@@ -44,6 +44,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.1",
+	"version": "0.1.0",
 	"type": "module",
 	"scripts": {
-		"prepublishOnly": "npx tsc index.ts retry.ts --target esnext --declaration --moduleResolution node",
+		"prepublishOnly": "npx tsc index.ts retry.ts computed.ts --target esnext --declaration --moduleResolution node",
 		"test": "node --test tests/*.test.ts",
 		"test:coverage": "node --test --experimental-test-coverage tests/*.test.ts"
 	},