@greendrake/util 0.7.0 → 0.8.0

package/README.md

@@ -35,9 +35,14 @@ off()
 - `TimeOutPromise(ms)` — `promise` resolves after `ms`; `isResolved`; `cancel()` clears the timer and rejects the promise (with `undefined`) while it is pending. `TimeOutPromise.wait(ms)` is the one-shot form.
 - `Debouncer(ms)` — `fire(ms?)` waits the delay (the argument overrides the constructed default for that call only) and resolves with a `proceed` predicate that is true only if no later `fire()` or `cancel()` superseded this one. `cancel()` invalidates every in-flight `fire()`.
 - `Delayed` — named-timeout registry: `go(name, fn, ms)` schedules `fn`, replacing a pending timeout of the same name; `cancel(name)`; `cancelAll()`. Instance-scoped, so equal names in unrelated instances cannot collide.
+- `coalesced(run)` — returns `pull()`: one run at a time, and at most one more queued behind it however many times it is pulled meanwhile, for work whose every request asks the same question (read this again, rebuild that). Each pull settles with the outcome of the run that covers it — the one it started, or the one queued behind a run already going, never the run in progress, which may have begun before whatever prompted the pull. A run that throws synchronously rejects like any other; the slot is freed and handed to the queued run before the finished run's pulls settle. The outcome is the puller's to handle.
 
 ```ts
-import { Debouncer, Delayed, TimeOutPromise } from '@greendrake/util'
+import { Debouncer, Delayed, TimeOutPromise, coalesced } from '@greendrake/util'
+
+const refresh = coalesced(() => loadView())
+source.on('changed', () => void refresh().catch(report))
+const current = await refresh() // never a view read before this call
 
 const debouncer = new Debouncer(300)
 const proceed = await debouncer.fire()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/util",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "description": "Framework-free, Node-safe utilities: typed event emitter, timing, retry, staleness, comparators, fetch helpers, misc",
     "license": "MIT",
     "author": "Eugene Greendrake <eugene@greendrake.nz>",

package/src/main.ts

@@ -1,6 +1,6 @@
 export { Emitter, type EventMap } from './Emitter'
 export { randomString, dClone, isEmpty, arrayRemove, arraysEqual, capitalise, humanSeconds, humanFileSize, fileMime, configuration, createDeferred, type Deferred } from './misc'
-export { TimeOutPromise, Debouncer, Delayed } from './timing'
+export { TimeOutPromise, Debouncer, Delayed, coalesced } from './timing'
 export { Retrier, RetryStopped, type RetrierOptions, type RetrierEvents } from './Retrier'
 export { StalenessDetector, type StalenessEvents } from './StalenessDetector'
 export { composeComparators, byProp, byPreset, type Comparator } from './compare'

package/src/timing.ts

@@ -1,3 +1,5 @@
+import { createDeferred, type Deferred } from './misc'
+
 export class TimeOutPromise {
     #timeout: ReturnType<typeof setTimeout>
     #reject: (reason?: unknown) => void
@@ -59,6 +61,60 @@ export class Debouncer {
     }
 }
 
+// One run at a time, and at most one more behind it however many times it is
+// pulled meanwhile — for work whose every request asks the same question (read
+// this again, rebuild that), so the answer to the last request is the answer to
+// all of them. A pull settles with the outcome of the run that covers it: the
+// one it started, or the one queued behind a run already going. Never the run
+// in progress, which may have begun before whatever prompted the pull.
+//    const refresh = coalesced(() => load())
+//    store.on('changed', () => void refresh().catch(report))
+// The outcome is the puller's: a pull nobody handles rejects unhandled like any
+// other promise. Whatever the outcome, the slot is freed.
+export const coalesced = <T>(run: () => T | Promise<T>): (() => Promise<T>) => {
+    let running = false
+    // The run queued behind the current one, as every pull covered by it holds it.
+    let queued: Deferred<T> | null = null
+
+    // The slot is passed on before the finished run's pulls are settled, so
+    // whoever they wake finds the queued run already under way rather than a
+    // slot about to change hands.
+    const finish = (): void => {
+        running = false
+        const next = queued
+        queued = null
+        if (next) start(next)
+    }
+
+    const start = (covering: Deferred<T>): void => {
+        running = true
+        // `new Promise(resolve => resolve(run()))` rather than
+        // Promise.resolve(run()): it puts the call inside the promise, so a run
+        // that throws synchronously is a rejection like any other instead of
+        // escaping with the slot still held, which would wedge every later pull.
+        void new Promise<T>(resolve => resolve(run())).then(
+            value => {
+                finish()
+                covering.resolve(value)
+            },
+            (error: unknown) => {
+                finish()
+                covering.reject(error)
+            }
+        )
+    }
+
+    return () => {
+        if (running) {
+            queued ??= createDeferred<T>()
+            return queued.promise
+        }
+        const covering = createDeferred<T>()
+        start(covering)
+        return covering.promise
+    }
+}
+
 // Named-timeout registry: scheduling under an existing name replaces the
 // pending timeout. Instance-scoped — each consumer creates its own registry,
 // so equal names in unrelated consumers cannot collide.