jrx 0.3.0-alpha.5 → 0.3.0-alpha.7

package/README.md

@@ -28,14 +28,33 @@ npm i jrx
 - [`makeReset()`](#makereset) - Create a resettable `DisposableStack`
 - [`makeAsyncReset()`](#makeasyncreset) - Create a resettable `AsyncDisposableStack`
 - [`makeRenderLoop()`](#makerenderloop) - Render loops with automatic cleanup
-- [`makeInterval(cb, ms)`](#makeintervalcb-ms) - Repeating intervals with cleanup
-- [`makeIntervalAsync(cb, ms)`](#makeintervalasynccb-ms) - Async intervals with cancellation
-- [`makeAnimationFrame(cb)`](#makeanimationframecb) - Single animation frame with cleanup
-- [`makeAnimationFrameLoop(cb)`](#makeanimationframeloopcb) - Animation frame loops
-- [`makeTimeout(cb, ms)`](#maketimeoutcb-ms) - Timeouts with cleanup
-- [`makeTransition(cb, durationMs)`](#maketransitioncb-durationms) - Progress-based animations
+- [`createInterval(cb, ms)`](#createIntervalcb-ms) - Repeating intervals with cleanup
+- [`createIntervalAsync(cb, ms)`](#createIntervalasynccb-ms) - Async intervals with cancellation
+- [`createAnimationFrame(cb)`](#createAnimationFramecb) - Single animation frame with cleanup
+- [`createAnimationFrameLoop(cb)`](#createAnimationFrameloopcb) - Animation frame loops
+- [`createTimeout(cb, ms)`](#createTimeoutcb-ms) - Timeouts with cleanup
+- [`createTransition(cb, durationMs)`](#createTransitioncb-durationms) - Progress-based animations
 - [`computed(fn, getDeps?)`](#computedfn-getdeps) - Memoized computed values
 - [`retry(cb, backoffSec?)`](#retrycb-backoffsec) - Retry with exponential backoff
+- [`assignDispose(value, disposable)`](#assigndisposevalue-disposable) - Attach a `Symbol.dispose` to any value
+
+## Naming convention
+
+Functions prefixed with `create*` return a `Disposable` object. The returned object can be passed to [`DisposableStack.use()`](https://github.com/tc39/proposal-explicit-resource-management) or bound with the `using` keyword for automatic cleanup.
+
+```typescript
+import {createInterval, createTimeout} from 'jrx'
+
+// With DisposableStack.use()
+using stack = new DisposableStack()
+stack.use(createInterval(() => console.log('tick'), 1000))
+stack.use(createTimeout(() => console.log('done'), 5000))
+// Both are disposed when `stack` goes out of scope
+
+// Or directly with `using`
+using interval = createInterval(() => console.log('tick'), 1000)
+// Disposed when the enclosing block exits
+```
 
 ## API
 
@@ -95,16 +114,16 @@ requestAnimationFrame(loop)
 handle[Symbol.dispose]()
 ```
 
-### `makeInterval(cb, ms)`
+### `createInterval(cb, ms)`
 
 Creates a repeating interval with cleanup. The callback can optionally return a `Disposable` that is disposed before the next invocation. Returns a `Disposable`.
 
 **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 {makeInterval} from 'jrx'
+import {createInterval} from 'jrx'
 
-const handle = makeInterval(() => {
+const handle = createInterval(() => {
   console.log('Tick') // Called immediately, then every 1000ms after completion
 
   // Optional: return a Disposable for cleanup
@@ -119,16 +138,16 @@ const handle = makeInterval(() => {
 handle[Symbol.dispose]()
 ```
 
-### `makeIntervalAsync(cb, ms)`
+### `createIntervalAsync(cb, ms)`
 
-Async version of `makeInterval`. Waits for the callback to complete before scheduling the next invocation. Returns a `Disposable`.
+Async version of `createInterval`. Waits for the callback to complete before scheduling the next invocation. Returns a `Disposable`.
 
 **Note:** The callback fires **immediately** on first call, then waits `ms` milliseconds **after** the previous async callback completes.
 
 ```typescript
-import {makeIntervalAsync} from 'jrx'
+import {createIntervalAsync} from 'jrx'
 
-const handle = makeIntervalAsync(async () => {
+const handle = createIntervalAsync(async () => {
   // Called immediately, then 5000ms after each completion
   await fetchData()
   processData()
@@ -137,14 +156,14 @@ const handle = makeIntervalAsync(async () => {
 handle[Symbol.dispose]()
 ```
 
-### `makeAnimationFrame(cb)`
+### `createAnimationFrame(cb)`
 
 Executes a callback on the next animation frame with cleanup. Returns a `Disposable`.
 
 ```typescript
-import {makeAnimationFrame} from 'jrx'
+import {createAnimationFrame} from 'jrx'
 
-const handle = makeAnimationFrame((now) => {
+const handle = createAnimationFrame((now) => {
   updateAnimation(now)
 
   // Optional: return a Disposable for cleanup
@@ -159,14 +178,14 @@ const handle = makeAnimationFrame((now) => {
 handle[Symbol.dispose]()
 ```
 
-### `makeAnimationFrameLoop(cb)`
+### `createAnimationFrameLoop(cb)`
 
 Creates a continuous `requestAnimationFrame` loop with cleanup. Returns a `Disposable`.
 
 ```typescript
-import {makeAnimationFrameLoop} from 'jrx'
+import {createAnimationFrameLoop} from 'jrx'
 
-const handle = makeAnimationFrameLoop((now) => {
+const handle = createAnimationFrameLoop((now) => {
   updateAnimation(now)
 
   // Optional: return a Disposable for cleanup
@@ -181,14 +200,14 @@ const handle = makeAnimationFrameLoop((now) => {
 handle[Symbol.dispose]()
 ```
 
-### `makeTimeout(cb, ms)`
+### `createTimeout(cb, ms)`
 
 Creates a timeout with cleanup. Returns a `Disposable`.
 
 ```typescript
-import {makeTimeout} from 'jrx'
+import {createTimeout} from 'jrx'
 
-const handle = makeTimeout(() => {
+const handle = createTimeout(() => {
   console.log('Timeout fired')
 }, 1000)
 
@@ -196,14 +215,14 @@ const handle = makeTimeout(() => {
 handle[Symbol.dispose]()
 ```
 
-### `makeTransition(cb, durationMs)`
+### `createTransition(cb, durationMs)`
 
 Creates an animation transition with progress tracking (0 to 1). Returns a `Disposable`.
 
 ```typescript
-import {makeTransition} from 'jrx'
+import {createTransition} from 'jrx'
 
-const handle = makeTransition((progress) => {
+const handle = createTransition((progress) => {
   element.style.opacity = progress.toString()
 
   // Optional: return a Disposable for cleanup
@@ -287,18 +306,53 @@ const data = await r // undefined
 - `cb`: Callback that returns `Disposable & (T | Promise<T>)`. Receives `{ resetBackoff() }` to reset the backoff counter.
 - `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]`
 
+### `assignDispose(value, disposable)`
+
+Attaches a `Symbol.dispose` to an existing value (object, function, array, promise, etc.) that delegates to a given `Disposable`. Returns the same value, now also typed as `Disposable`.
+
+This is useful when a function needs to return a meaningful value **and** be disposable — for example, returning a promise, a function, or a tuple from a factory while still allowing the caller to clean up the underlying resources.
+
+```typescript
+import {assignDispose} from 'jrx'
+
+function makeThing() {
+  using stack = new DisposableStack()
+  stack.defer(() => console.log('cleanup'))
+
+  const obj = {value: 42}
+  return assignDispose(obj, stack.move())
+}
+```
+
+Async factory — wrap an in-flight promise so the caller can dispose the underlying resources mid-flight:
+
+```typescript
+import {assignDispose} from 'jrx'
+
+function loadThing() {
+  const stack = new DisposableStack()
+  return assignDispose(
+    (async () => {
+      const res = await fetch('/api/data', {signal: stack.adopt(new AbortController(), c => c.abort()).signal})
+      return await res.json()
+    })(),
+    stack,
+  )
+}
+```
+
 ## Cleanup Pattern
 
 All effect functions return a `Disposable` object that stops the effect and runs any pending cleanup:
 
 ```typescript
-import {makeInterval, makeTimeout, makeAnimationFrame, makeTransition} from 'jrx'
+import {createInterval, createTimeout, createAnimationFrame, createTransition} from 'jrx'
 
 // Each function returns a Disposable
-const interval = makeInterval(() => console.log('tick'), 1000)
-const timeout = makeTimeout(() => console.log('timeout'), 5000)
-const raf = makeAnimationFrame((now) => render(now))
-const transition = makeTransition((p) => console.log(p), 1000)
+const interval = createInterval(() => console.log('tick'), 1000)
+const timeout = createTimeout(() => console.log('timeout'), 5000)
+const raf = createAnimationFrame((now) => render(now))
+const transition = createTransition((p) => console.log(p), 1000)
 
 // Call [Symbol.dispose]() to stop the effect
 interval[Symbol.dispose]()

package/index.d.ts

@@ -9,21 +9,24 @@ export declare function makeRenderLoop(): {
         [Symbol.dispose](): void;
     };
 };
-export declare function makeInterval(cb: () => undefined | Disposable, ms: number): {
+export declare function createInterval(cb: () => undefined | Disposable, ms: number): {
     [Symbol.dispose](): void;
 };
-export declare function makeIntervalAsync(cb: () => void | Disposable | Promise<void>, ms: number): {
+export declare function createIntervalAsync(cb: () => void | Disposable | Promise<void>, ms: number): {
     [Symbol.dispose](): void;
 };
-export declare function makeAnimationFrame(cb: (now: DOMHighResTimeStamp) => undefined | Disposable): {
+export declare function createAnimationFrame(cb: (now: DOMHighResTimeStamp) => undefined | Disposable): {
     [Symbol.dispose](): void;
 };
-export declare function makeAnimationFrameLoop(cb: (now: DOMHighResTimeStamp) => undefined | Disposable): {
+export declare function createAnimationFrameLoop(cb: (now: DOMHighResTimeStamp) => undefined | Disposable): {
     [Symbol.dispose](): void;
 };
-export declare function makeTimeout(cb: () => void, ms: number): {
+export declare function createTimeout(cb: () => void, ms: number): {
     [Symbol.dispose](): void;
 };
-export declare function makeTransition(cb: (progress: number) => undefined | Disposable, durationMs: number): {
+export declare function createTransition(cb: (progress: number) => undefined | Disposable, durationMs: number): {
     [Symbol.dispose](): void;
 };
+export declare function assignDispose<T extends object>(value: T, disposable: Disposable): T & {
+    [Symbol.dispose]: () => void;
+};

package/index.js

@@ -33,7 +33,7 @@ export function makeRenderLoop() {
         },
     };
 }
-export function makeInterval(cb, ms) {
+export function createInterval(cb, ms) {
     const reset = makeReset();
     let timeout;
     wrapper();
@@ -48,7 +48,7 @@ export function makeInterval(cb, ms) {
         timeout = setTimeout(wrapper, ms);
     }
 }
-export function makeIntervalAsync(cb, ms) {
+export function createIntervalAsync(cb, ms) {
     const reset = makeReset();
     let timeout;
     void wrapper();
@@ -65,7 +65,7 @@ export function makeIntervalAsync(cb, ms) {
             timeout = setTimeout(wrapper, ms);
     }
 }
-export function makeAnimationFrame(cb) {
+export function createAnimationFrame(cb) {
     const stack = new DisposableStack();
     const raf = requestAnimationFrame(now => {
         if (stack.disposed)
@@ -79,7 +79,7 @@ export function makeAnimationFrame(cb) {
         },
     };
 }
-export function makeAnimationFrameLoop(cb) {
+export function createAnimationFrameLoop(cb) {
     const reset = makeReset();
     let raf = requestAnimationFrame(wrapper);
     return {
@@ -93,7 +93,7 @@ export function makeAnimationFrameLoop(cb) {
         raf = requestAnimationFrame(wrapper);
     }
 }
-export function makeTimeout(cb, ms) {
+export function createTimeout(cb, ms) {
     const timeout = setTimeout(cb, ms);
     return {
         [Symbol.dispose]() {
@@ -101,7 +101,7 @@ export function makeTimeout(cb, ms) {
         },
     };
 }
-export function makeTransition(cb, durationMs) {
+export function createTransition(cb, durationMs) {
     const reset = makeReset();
     let start;
     let raf = requestAnimationFrame(wrapper);
@@ -128,3 +128,8 @@ export function makeTransition(cb, durationMs) {
         }
     }
 }
+export function assignDispose(value, disposable) {
+    return Object.assign(value, {
+        [Symbol.dispose]: disposable[Symbol.dispose].bind(disposable),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jrx",
-	"version": "0.3.0-alpha.5",
+	"version": "0.3.0-alpha.7",
 	"type": "module",
 	"scripts": {
 		"prepublishOnly": "npx tsc",