@greendrake/util 0.6.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()
@@ -173,10 +178,13 @@ const { latitude, longitude } = await getUserLocation()
 - `dClone(data)` — deep clone via a JSON round-trip (JSON-representable data only).
 - `isEmpty(o, emptyArraysAreNotEmpty?)` — true for `null`, `undefined`, `''`, `NaN`, an empty array (unless the flag is set) and an empty plain object.
 - `arrayRemove(a, el)` — removes the first occurrence of `el` in place.
+- `arraysEqual(a, b, same = Object.is)` — same length and `same` holds element-wise, in order.
 - `capitalise(s)` — upper-cases the first character.
 - `humanSeconds(seconds)` — compact duration, two most significant units: `3661` → `'1h 1m'`.
 - `humanFileSize(bytes, si = false, dp = 1)` — binary units (`KiB`, `MiB`, …) by default, decimal units (`kB`, `MB`, …) with `si`; `dp` decimal places.
 - `fileMime(file)` — `File.type`, falling back to an extension map (`heic`, `heif`, `avif`, `webp`) when the OS reports none, then `application/octet-stream`.
+- `Declared<Map, Tag, Value>` (type) — the union a host's declaration map discriminates, one member per key: the key under `Tag`, its type under `Value` (absent for a key declared `never`); `{ [Tag]: string; [Value]?: unknown }` while the map is undeclared. For a package exporting an empty interface for its host to augment.
+- `configuration<T>(owner)` — a package's boot-time configuration: `{ configure, get }`, where `get` throws under `owner`'s name until the host has called `configure`.
 - `createDeferred<T = void>()` — a `Deferred<T>`: `{ promise, resolve, reject }`.
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/util",
-    "version": "0.6.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>",
@@ -38,7 +38,7 @@
     },
     "prettier": "@greendrake/dev-config/prettier",
     "devDependencies": {
-        "@greendrake/dev-config": "0.6.0",
+        "@greendrake/dev-config": "0.7.0",
         "typescript": "6.0.3"
     }
 }

package/src/main.ts

@@ -1,8 +1,9 @@
 export { Emitter, type EventMap } from './Emitter'
-export { randomString, dClone, isEmpty, arrayRemove, capitalise, humanSeconds, humanFileSize, fileMime, createDeferred, type Deferred } from './misc'
-export { TimeOutPromise, Debouncer, Delayed } from './timing'
+export { randomString, dClone, isEmpty, arrayRemove, arraysEqual, capitalise, humanSeconds, humanFileSize, fileMime, configuration, createDeferred, type Deferred } from './misc'
+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'
 export { NetworkError, HttpError, safeFetch, fetchJson } from './net'
 export { RTL_LANGUAGES, isRTLLocale } from './locale'
+export type { Declared } from './types'

package/src/misc.ts

@@ -13,6 +13,10 @@ export const arrayRemove = <T>(a: T[], el: T): void => {
     }
 }
 
+// Same length, and `same` holds element-wise in order (the equal lengths make
+// every b[i] an element).
+export const arraysEqual = <T>(a: readonly T[], b: readonly T[], same: (x: T, y: T) => boolean = Object.is): boolean => a.length === b.length && a.every((x, i) => same(x, b[i] as T))
+
 export const capitalise = (s: string): string => (s ? s.charAt(0).toUpperCase() + s.slice(1) : '')
 
 // Compact human duration, two most significant units: 3661s → "1h 1m".
@@ -70,6 +74,22 @@ export interface Deferred<T> {
     reject: (reason?: unknown) => void
 }
 
+// A package's boot-time configuration: `configure` for the host to call once,
+// and `get` for the package to read it through — throwing, under `owner`'s
+// name, while the host has not.
+export const configuration = <T>(owner: string): { configure: (value: T) => void; get: () => T } => {
+    let current: T | undefined
+    return {
+        configure: value => {
+            current = value
+        },
+        get: () => {
+            if (current === undefined) throw new Error(`${owner}: used before it is configured`)
+            return current
+        }
+    }
+}
+
 export const createDeferred = <T = void>(): Deferred<T> => {
     let resolve!: (value: T | PromiseLike<T>) => void
     let reject!: (reason?: unknown) => void

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.

package/src/types.ts

@@ -0,0 +1,6 @@
+// The union a host's declaration map discriminates, one member per key: the
+// key under `Tag`, and the key's type under `Value` — absent for a key declared
+// `never`. Undeclared (an empty map), any string tags it and its value is
+// unknown. The map is an interface a package exports empty for the host to
+// augment, so the package's own code compiles against the undeclared form.
+export type Declared<Map, Tag extends PropertyKey, Value extends PropertyKey> = [keyof Map] extends [never] ? { [P in Tag]: string } & { [P in Value]?: unknown } : { [K in keyof Map]: { [P in Tag]: K } & ([Map[K]] extends [never] ? unknown : { [P in Value]: Map[K] }) }[keyof Map]