@greendrake/util 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @greendrake/util
+
+Framework-free, Node-safe TypeScript utilities: a payload-typed event emitter, timing primitives, retry orchestration, a staleness detector, comparators, `fetch` helpers, locale and browser helpers, and small misc functions. Ships as TypeScript source (`src/main.ts`) with no build step and no `.d.ts`; `sideEffects: false`.
+
+## Install
+
+```sh
+bun add @greendrake/util
+```
+
+`npm install @greendrake/util` works equally.
+
+## Emitter
+
+`Emitter<E extends EventMap>`, where `EventMap = Record<string, unknown[]>` maps each event name to its argument tuple. Meant for composition (`Retrier` and `StalenessDetector` below extend it). `on`/`once` return the unsubscribe function; `off` detaches a listener from both kinds; `emit` calls the `on` listeners, then drains the `once` set.
+
+```ts
+import { Emitter } from '@greendrake/util'
+
+interface Events {
+    hit: [count: number]
+    flat: []
+    [key: string]: unknown[]
+}
+
+const e = new Emitter<Events>()
+const off = e.on('hit', n => console.log(n))
+e.once('flat', () => {})
+e.emit('hit', 1)
+off()
+```
+
+## Timing
+
+- `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.
+
+```ts
+import { Debouncer, Delayed, TimeOutPromise } from '@greendrake/util'
+
+const debouncer = new Debouncer(300)
+const proceed = await debouncer.fire()
+if (proceed()) {
+    // commit
+}
+
+const delayed = new Delayed()
+delayed.go('save', () => save(), 1000)
+delayed.cancel('save')
+
+await TimeOutPromise.wait(50)
+```
+
+## Retry
+
+`Retrier<T>` (extends `Emitter<RetrierEvents>`): `run()` resolves with the first accepted result, rethrows an error its `shouldRetry` gate declares fatal, and rejects with `RetryStopped` once `stop()` is called (`stopped` getter). Status is observable via events; rendering it is the consumer's concern.
+
+`RetrierOptions<T>`:
+
+- `attempt: () => Promise<T>`
+- `accept?: (result: T) => boolean` — a resolved attempt whose result is not accepted counts as a failure and schedules a retry.
+- `shouldRetry?: (error: unknown) => boolean` — return false to make the error fatal.
+- `delaySeconds?: number | ((retryIndex: number) => number)` — seconds between attempts, a constant or a function of the 0-based retry index; default 4.
+
+`RetrierEvents`: `trying: []` before each attempt; `waiting: [secondsLeft: number]` once per second while waiting, counting down.
+
+```ts
+import { fetchJson, NetworkError, Retrier, RetryStopped } from '@greendrake/util'
+
+const retrier = new Retrier({
+    attempt: () => fetchJson<Status>('/status'),
+    accept: status => status.ready,
+    shouldRetry: e => e instanceof NetworkError,
+    delaySeconds: i => Math.min(30, 2 ** i)
+})
+retrier.on('waiting', s => console.log(`retry in ${s}s`))
+try {
+    const status = await retrier.run()
+} catch (e) {
+    if (e instanceof RetryStopped) {
+        // stop() was called
+    }
+}
+```
+
+## Staleness
+
+`StalenessDetector(ttlMs)` (extends `Emitter<StalenessEvents>`): a renewable freshness flag for push data streams. `renew()` on every inbound datum keeps `isFresh` true; when no renewal arrives within `ttlMs` the flag drops. `fresh` and `stale` fire only on transitions. `dispose()` clears the pending timer.
+
+```ts
+import { StalenessDetector } from '@greendrake/util'
+
+const staleness = new StalenessDetector(10_000)
+staleness.on('stale', () => showOfflineBadge())
+staleness.on('fresh', () => hideOfflineBadge())
+socket.onmessage = () => staleness.renew()
+```
+
+## Comparators
+
+`Comparator<T> = (a: T, b: T) => number`, for `Array.prototype.sort`.
+
+- `byProp(prop, descending?)` — orders by a property using `===`/`>`.
+- `byPreset(prop, preset: string[])` — orders by position in a preset list, case-insensitive; values missing from the preset tie with everything and so defer to the next comparator.
+- `composeComparators(...comparators)` — tie-breaking composition: later comparators apply only where earlier ones tie.
+
+```ts
+import { byPreset, byProp, composeComparators } from '@greendrake/util'
+
+interface Item {
+    kind: string
+    n: number
+}
+
+items.sort(composeComparators<Item>(byPreset('kind', ['grid', 'solar']), byProp('n', true)))
+```
+
+## Fetch
+
+- `safeFetch(...args)` — same signature as `fetch`; a rejection (DNS failure, connection refused, TLS/CORS rejection, device offline) is rethrown as `NetworkError`. A non-2xx status resolves normally, as with `fetch`.
+- `fetchJson<T>(url, init?)` — `safeFetch`, then `HttpError` on non-2xx, else the parsed JSON body as `T`.
+- `NetworkError` — `name` `'NetworkError'`; message taken from the wrapped error, which is kept as `cause`. Transport-level failures elsewhere (an abnormal WebSocket close, say) can extend it so one `instanceof` check classifies all of them.
+- `HttpError` — `status`, `statusText`; message `"<status> <statusText>"`.
+
+```ts
+import { fetchJson, HttpError, NetworkError } from '@greendrake/util'
+
+try {
+    const user = await fetchJson<User>('/api/me')
+} catch (e) {
+    if (e instanceof NetworkError) {
+        // transport failure, e.cause holds the browser error
+    }
+    if (e instanceof HttpError && e.status === 401) {
+        // sign in
+    }
+}
+```
+
+## Locale
+
+- `RTL_LANGUAGES: readonly string[]` — ISO 639-1 subtags of right-to-left scripts: `ar`, `fa`, `he`, `ur`, `ps`, `sd`, `ug`, `yi`.
+- `isRTLLocale(tag)` — true when the tag's language subtag (the text before the first `-`) is in `RTL_LANGUAGES`.
+
+```ts
+import { isRTLLocale } from '@greendrake/util'
+
+document.documentElement.dir = isRTLLocale(navigator.language) ? 'rtl' : 'ltr'
+```
+
+## DOM and geolocation
+
+Importable in Node; these touch `document`, `window` and `navigator` only when called.
+
+- `getReadyStatePromise()` — resolves when `document.readyState` reaches `'complete'` (immediately if it already has); one shared promise per module instance.
+- `hasFinePointer()` — `matchMedia('(hover: hover) and (pointer: fine)')`: true where the primary input is a mouse or trackpad rather than a finger. Serves as a proxy for "focusing a field will not raise an on-screen keyboard", which no platform exposes directly.
+- `toggleFullscreen(el)` — requests fullscreen for `el`, or exits fullscreen if `el` is already the fullscreen element. Returns false without acting where `document.fullscreenEnabled` is false (iPhone Safari), leaving the caller to pick a substitute.
+- `getUserLocation(): Promise<UserLocation>` — `navigator.geolocation.getCurrentPosition` with `timeout: LOCATION_TIMEOUT_MS` (5000) and `maximumAge: LOCATION_MAX_AGE_MS` (60000); resolves `{ latitude, longitude }`, rejects with the geolocation error, or with `Error('Location unknown')` when the position carries no coords. The two constants are exported so an app that obtains the position from a platform API instead uses the same numbers.
+
+```ts
+import { getReadyStatePromise, getUserLocation, hasFinePointer, toggleFullscreen } from '@greendrake/util'
+
+await getReadyStatePromise()
+if (hasFinePointer()) input.focus()
+if (!toggleFullscreen(viewer)) openOverlayInstead()
+const { latitude, longitude } = await getUserLocation()
+```
+
+## Misc
+
+- `randomString(prefix?)` — `prefix` followed by a base-36 fragment of `Math.random()`.
+- `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.
+- `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`.
+- `createDeferred<T = void>()` — a `Deferred<T>`: `{ promise, resolve, reject }`.
+
+```ts
+import { createDeferred, humanFileSize, humanSeconds, isEmpty } from '@greendrake/util'
+
+humanSeconds(3661) // '1h 1m'
+humanFileSize(1536) // '1.5 KiB'
+humanFileSize(1536, true) // '1.5 kB'
+isEmpty({}) // true
+isEmpty([], true) // false
+
+const ready = createDeferred<string>()
+ready.resolve('ok')
+await ready.promise
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "@greendrake/util",
+    "version": "0.1.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>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "util"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/util#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "typescript": "6.0.3"
+    }
+}

package/src/Emitter.ts

@@ -0,0 +1,43 @@
+export type EventMap = Record<string, unknown[]>
+
+type AnyListener = (...args: unknown[]) => void
+
+// Payload-typed event emitter used by composition (never inheritance of a god
+// base class). `on` returns the unsubscribe function so callers — Vue
+// components in particular — can detach in one line on teardown.
+export class Emitter<E extends EventMap> {
+    #listeners = new Map<keyof E, Set<AnyListener>>()
+    #onceListeners = new Map<keyof E, Set<AnyListener>>()
+
+    on<K extends keyof E>(event: K, listener: (...args: E[K]) => void): () => void {
+        return this.#add(this.#listeners, event, listener)
+    }
+
+    once<K extends keyof E>(event: K, listener: (...args: E[K]) => void): () => void {
+        return this.#add(this.#onceListeners, event, listener)
+    }
+
+    #add<K extends keyof E>(map: Map<keyof E, Set<AnyListener>>, event: K, listener: (...args: E[K]) => void): () => void {
+        let set = map.get(event)
+        if (!set) {
+            set = new Set()
+            map.set(event, set)
+        }
+        set.add(listener as AnyListener)
+        return () => this.off(event, listener)
+    }
+
+    off<K extends keyof E>(event: K, listener: (...args: E[K]) => void): void {
+        this.#listeners.get(event)?.delete(listener as AnyListener)
+        this.#onceListeners.get(event)?.delete(listener as AnyListener)
+    }
+
+    emit<K extends keyof E>(event: K, ...args: E[K]): void {
+        this.#listeners.get(event)?.forEach(l => l(...args))
+        const once = this.#onceListeners.get(event)
+        if (once) {
+            this.#onceListeners.delete(event)
+            once.forEach(l => l(...args))
+        }
+    }
+}

package/src/Retrier.ts

@@ -0,0 +1,99 @@
+import { Emitter } from './Emitter'
+import { TimeOutPromise } from './timing'
+
+export class RetryStopped extends Error {
+    constructor() {
+        super('Retrier stopped')
+        this.name = 'RetryStopped'
+    }
+}
+
+export interface RetrierOptions<T> {
+    attempt: () => Promise<T>
+    // Result gate: a resolved attempt whose result is not accepted counts as a
+    // failure and schedules a retry.
+    accept?: (result: T) => boolean
+    // Error gate: return false to make the error fatal (rethrown from run()).
+    shouldRetry?: (error: unknown) => boolean
+    // Seconds to wait between attempts: a constant, or a function of the
+    // 0-based retry index for backoff schedules.
+    delaySeconds?: number | ((retryIndex: number) => number)
+}
+
+export interface RetrierEvents {
+    trying: []
+    // Emitted once per second while waiting for the next attempt, counting down.
+    waiting: [secondsLeft: number]
+    [key: string]: unknown[]
+}
+
+const DEFAULT_DELAY_SECONDS = 4
+
+// Retry orchestration: run() resolves with the first accepted result, rethrows
+// errors its gate declares fatal, and rejects with RetryStopped when stop() is
+// called. Status is observable via typed events — rendering (message strings,
+// reactive refs) is entirely the consumer's concern.
+export class Retrier<T> extends Emitter<RetrierEvents> {
+    #options: RetrierOptions<T>
+    #stopped = false
+    #pendingWait?: TimeOutPromise
+
+    constructor(options: RetrierOptions<T>) {
+        super()
+        this.#options = options
+    }
+
+    get stopped(): boolean {
+        return this.#stopped
+    }
+
+    async run(): Promise<T> {
+        let retryIndex = 0
+        while (true) {
+            if (this.#stopped) {
+                throw new RetryStopped()
+            }
+            this.emit('trying')
+            try {
+                const result = await this.#options.attempt()
+                if (this.#options.accept && !this.#options.accept(result)) {
+                    throw new Error('Unacceptable result')
+                }
+                return result
+            } catch (e) {
+                if (this.#stopped) {
+                    throw new RetryStopped()
+                }
+                if (this.#options.shouldRetry && !this.#options.shouldRetry(e)) {
+                    throw e
+                }
+                await this.#wait(retryIndex)
+                retryIndex++
+            }
+        }
+    }
+
+    async #wait(retryIndex: number): Promise<void> {
+        const { delaySeconds } = this.#options
+        const delay = typeof delaySeconds === 'function' ? delaySeconds(retryIndex) : (delaySeconds ?? DEFAULT_DELAY_SECONDS)
+        let remainingMs = delay * 1000
+        let secondsLeft = Math.ceil(delay)
+        while (remainingMs > 0 && !this.#stopped) {
+            this.emit('waiting', secondsLeft)
+            const chunk = Math.min(1000, remainingMs)
+            this.#pendingWait = new TimeOutPromise(chunk)
+            try {
+                await this.#pendingWait.promise
+            } catch {
+                // cancelled by stop(); the run() loop re-checks #stopped
+            }
+            remainingMs -= chunk
+            secondsLeft--
+        }
+    }
+
+    stop(): void {
+        this.#stopped = true
+        this.#pendingWait?.cancel()
+    }
+}

package/src/StalenessDetector.ts

@@ -0,0 +1,46 @@
+import { Emitter } from './Emitter'
+
+export interface StalenessEvents {
+    fresh: []
+    stale: []
+    [key: string]: unknown[]
+}
+
+// Renewable freshness flag for push data streams: renew() on every inbound
+// datum keeps `isFresh` true; when no renewal arrives within ttlMs the flag
+// drops and 'stale' fires. Events fire only on transitions.
+export class StalenessDetector extends Emitter<StalenessEvents> {
+    #ttlMs: number
+    #timeout?: ReturnType<typeof setTimeout>
+    #fresh = false
+
+    constructor(ttlMs: number) {
+        super()
+        this.#ttlMs = ttlMs
+    }
+
+    get isFresh(): boolean {
+        return this.#fresh
+    }
+
+    renew(): void {
+        if (this.#timeout) {
+            clearTimeout(this.#timeout)
+        }
+        if (!this.#fresh) {
+            this.#fresh = true
+            this.emit('fresh')
+        }
+        this.#timeout = setTimeout(() => {
+            this.#fresh = false
+            this.emit('stale')
+        }, this.#ttlMs)
+    }
+
+    dispose(): void {
+        if (this.#timeout) {
+            clearTimeout(this.#timeout)
+            this.#timeout = undefined
+        }
+    }
+}

package/src/compare.ts

@@ -0,0 +1,34 @@
+export type Comparator<T> = (a: T, b: T) => number
+
+// Tie-breaking composition: later comparators apply only where earlier ones tie.
+export const composeComparators =
+    <T>(...comparators: Comparator<T>[]): Comparator<T> =>
+    (a, b) => {
+        for (const compare of comparators) {
+            const result = compare(a, b)
+            if (result !== 0) {
+                return result
+            }
+        }
+        return 0
+    }
+
+export const byProp = <T, K extends keyof T>(prop: K, descending?: boolean): Comparator<T> => {
+    const direction = descending ? -1 : 1
+    return (a, b) => {
+        const aVal = a[prop]
+        const bVal = b[prop]
+        return aVal === bVal ? 0 : aVal > bVal ? direction : -direction
+    }
+}
+
+// Order by position in a preset list (case-insensitive); values missing from
+// the preset tie with everything (defer to the next comparator).
+export const byPreset = <T, K extends keyof T>(prop: K, preset: string[]): Comparator<T> => {
+    const indexByValue = new Map(preset.map((key, i) => [key.toLowerCase(), i]))
+    return (a, b) => {
+        const iA = indexByValue.get(String(a[prop]).toLowerCase())
+        const iB = indexByValue.get(String(b[prop]).toLowerCase())
+        return iA === undefined || iB === undefined || iA === iB ? 0 : iA > iB ? 1 : -1
+    }
+}

package/src/dom.ts

@@ -0,0 +1,43 @@
+// Puts the element in fullscreen, or leaves fullscreen if it is already the one
+// in it. Returns false without doing anything where the browser has no element
+// fullscreen at all — iPhone Safari, whose only fullscreen is the native video
+// player — leaving the caller to decide on a substitute.
+export const toggleFullscreen = (el: Element): boolean => {
+    if (!document.fullscreenEnabled) {
+        return false
+    }
+    void (document.fullscreenElement === el ? document.exitFullscreen() : el.requestFullscreen())
+    return true
+}
+
+// True where the primary input is a precise pointer that can hover — a mouse or
+// trackpad, not a finger.
+//
+// Callers use it as a proxy for "focusing a field will not raise an on-screen
+// keyboard", which no platform exposes directly (navigator.virtualKeyboard is
+// Chromium-only and governs overlay policy, not availability). The proxy holds
+// for a touchscreen laptop — physical keyboard, so nothing pops up — and fails
+// only for a touch device driven by a bare mouse with no keyboard attached.
+export const hasFinePointer = (): boolean => window.matchMedia('(hover: hover) and (pointer: fine)').matches
+
+let readyStatePromise: Promise<void> | undefined
+
+// Resolves when document.readyState reaches 'complete' (immediately if it
+// already has). Browser-only at call time; safe to import in Node.
+export const getReadyStatePromise = (): Promise<void> => {
+    if (!readyStatePromise) {
+        readyStatePromise =
+            document.readyState === 'complete'
+                ? Promise.resolve()
+                : new Promise<void>(resolve => {
+                      const listener = (): void => {
+                          if (document.readyState === 'complete') {
+                              document.removeEventListener('readystatechange', listener)
+                              resolve()
+                          }
+                      }
+                      document.addEventListener('readystatechange', listener)
+                  })
+    }
+    return readyStatePromise
+}

package/src/geo.ts

@@ -0,0 +1,26 @@
+export interface UserLocation {
+    latitude: number
+    longitude: number
+}
+
+// How long to wait for a fix, and how stale a cached one may be. One decision,
+// not two that agree by coincidence, and exported because it is not this
+// function's alone: an app that asks a platform for the position instead of the
+// browser is producing the same user-visible behaviour and takes the same
+// numbers. Without a timeout the W3C default is Infinity — devices that never
+// complete a fix (OS location services off, no positioning source) would leave
+// the promise hanging forever. A cached fix both speeds up the common case and
+// avoids spurious timeouts where a fresh one takes longer than the wait.
+export const LOCATION_TIMEOUT_MS = 5000
+export const LOCATION_MAX_AGE_MS = 60000
+
+export const getUserLocation = async (): Promise<UserLocation> => {
+    const result = await new Promise<GeolocationPosition>((resolve, reject) => navigator.geolocation.getCurrentPosition(resolve, reject, { timeout: LOCATION_TIMEOUT_MS, maximumAge: LOCATION_MAX_AGE_MS }))
+    if (!result.coords) {
+        throw new Error('Location unknown')
+    }
+    return {
+        latitude: result.coords.latitude,
+        longitude: result.coords.longitude
+    }
+}

package/src/locale.ts

@@ -0,0 +1,11 @@
+// Right-to-left scripts, by ISO 639-1 language subtag. A document's direction
+// follows its locale, and `dir` on <html> is what makes a layout's logical
+// properties resolve the other way round.
+//
+// Here rather than in the app that renders: the direction is decided twice per
+// load — once by the inline bootstrap snippet a build generates, before any
+// bundle parses, and again when the catalogue activates — and the two must not
+// be able to disagree.
+export const RTL_LANGUAGES: readonly string[] = ['ar', 'fa', 'he', 'ur', 'ps', 'sd', 'ug', 'yi']
+
+export const isRTLLocale = (tag: string): boolean => RTL_LANGUAGES.includes(tag.split('-')[0])

package/src/main.ts

@@ -0,0 +1,10 @@
+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 { 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 { getReadyStatePromise, hasFinePointer, toggleFullscreen } from './dom'
+export { getUserLocation, LOCATION_TIMEOUT_MS, LOCATION_MAX_AGE_MS, type UserLocation } from './geo'
+export { RTL_LANGUAGES, isRTLLocale } from './locale'

package/src/misc.ts

@@ -0,0 +1,85 @@
+export const randomString = (prefix?: string): string => `${prefix || ''}${Math.random().toString(36).substring(2)}`
+
+export const dClone = <T>(data: T): T => JSON.parse(JSON.stringify(data))
+
+const isEmptyObject = (o: unknown): boolean => !!o && (o as object).constructor === Object && Object.keys(o as object).length === 0
+
+export const isEmpty = (o: unknown, emptyArraysAreNotEmpty?: boolean): boolean => [null, undefined, '', NaN].includes(o as null) || (Array.isArray(o) && !o.length && !emptyArraysAreNotEmpty) || isEmptyObject(o)
+
+export const arrayRemove = <T>(a: T[], el: T): void => {
+    const index = a.indexOf(el)
+    if (index > -1) {
+        a.splice(index, 1)
+    }
+}
+
+export const capitalise = (s: string): string => (s ? s.charAt(0).toUpperCase() + s.slice(1) : '')
+
+// Compact human duration, two most significant units: 3661s → "1h 1m".
+export const humanSeconds = (seconds: number): string => {
+    const levels: [number, string][] = [
+        [Math.floor(seconds / 31536000), 'y'],
+        [Math.floor((seconds % 31536000) / 86400), 'd'],
+        [Math.floor(((seconds % 31536000) % 86400) / 3600), 'h'],
+        [Math.floor((((seconds % 31536000) % 86400) % 3600) / 60), 'm'],
+        [(((seconds % 31536000) % 86400) % 3600) % 60, 's']
+    ]
+    const parts: string[] = []
+    for (const [value, unit] of levels) {
+        if (value === 0) continue
+        parts.push(`${value}${unit}`)
+        if (parts.length === 2) break
+    }
+    return parts.join(' ')
+}
+
+export const humanFileSize = (bytes: number, si = false, dp = 1): string => {
+    const thresh = si ? 1000 : 1024
+    if (Math.abs(bytes) < thresh) {
+        return bytes + ' B'
+    }
+    const units = si ? ['kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'] : ['KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB']
+    let u = -1
+    const r = 10 ** dp
+    let size = bytes
+    do {
+        size /= thresh
+        ++u
+    } while (Math.round(Math.abs(size) * r) / r >= thresh && u < units.length - 1)
+    return size.toFixed(dp) + ' ' + units[u]
+}
+
+const mimeByExtension: Record<string, string> = {
+    heic: 'image/heic',
+    heif: 'image/heif',
+    avif: 'image/avif',
+    webp: 'image/webp'
+}
+
+// File.type is empty when the OS has no registered association (common for
+// HEIC on non-Apple platforms) — fall back to the extension map.
+export const fileMime = (file: File): string => {
+    if (file.type) return file.type
+    const ext = file.name.split('.').pop()?.toLowerCase()
+    return (ext && mimeByExtension[ext]) || 'application/octet-stream'
+}
+
+export interface Deferred<T> {
+    promise: Promise<T>
+    resolve: (value: T | PromiseLike<T>) => void
+    reject: (reason?: unknown) => void
+}
+
+export const createDeferred = <T = void>(): Deferred<T> => {
+    let resolve!: (value: T | PromiseLike<T>) => void
+    let reject!: (reason?: unknown) => void
+    const promise = new Promise<T>((res, rej) => {
+        resolve = res
+        reject = rej
+    })
+    return {
+        promise,
+        resolve,
+        reject
+    }
+}

package/src/net.ts

@@ -0,0 +1,43 @@
+// Thrown when a request fails at the network/transport layer — DNS failure,
+// connection refused, TLS/CORS rejection, or the device being offline. fetch()
+// rejects only in these cases; a non-2xx HTTP status resolves normally, so
+// this never masks a server error response. The wrapped browser error is kept
+// as `cause` so its message ("Failed to fetch" / "Load failed") and stack
+// remain available for diagnostics. Transport-level failures elsewhere (e.g.
+// an abnormal WebSocket close) extend this class so consumers classify all of
+// them with one instanceof check.
+export class NetworkError extends Error {
+    constructor(cause: unknown) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause })
+        this.name = 'NetworkError'
+    }
+}
+
+export class HttpError extends Error {
+    readonly status: number
+    readonly statusText: string
+
+    constructor(status: number, statusText: string) {
+        super(`${status} ${statusText}`)
+        this.name = 'HttpError'
+        this.status = status
+        this.statusText = statusText
+    }
+}
+
+export const safeFetch = async (...args: Parameters<typeof fetch>): Promise<Response> => {
+    try {
+        return await fetch(...args)
+    } catch (e) {
+        throw new NetworkError(e)
+    }
+}
+
+// Typed JSON GET/…: NetworkError on transport failure, HttpError on non-2xx.
+export const fetchJson = async <T>(url: string, init?: RequestInit): Promise<T> => {
+    const response = await safeFetch(url, init)
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText)
+    }
+    return (await response.json()) as T
+}

package/src/timing.ts

@@ -0,0 +1,91 @@
+export class TimeOutPromise {
+    #timeout: ReturnType<typeof setTimeout>
+    #reject: (reason?: unknown) => void
+    isResolved = false
+    promise: Promise<void>
+
+    constructor(ms: number) {
+        this.#reject = () => {}
+        this.#timeout = setTimeout(() => {}, 0)
+        this.promise = new Promise<void>((resolve, reject) => {
+            this.#reject = reject
+            this.#timeout = setTimeout(() => {
+                resolve()
+                this.isResolved = true
+            }, ms)
+        })
+    }
+
+    cancel(): void {
+        if (!this.isResolved) {
+            clearTimeout(this.#timeout)
+            this.#reject()
+        }
+    }
+
+    static async wait(ms: number): Promise<void> {
+        await new this(ms).promise
+    }
+}
+
+// Counter/proceed debouncing: `fire()` waits the delay and returns a `proceed`
+// predicate that is true only if no later fire (or cancel) superseded this one.
+//    const proceed = await debouncer.fire()
+//    if (proceed()) { ...commit... }
+export class Debouncer {
+    #ms: number
+    #counter = 0
+
+    constructor(ms: number) {
+        this.#ms = ms
+    }
+
+    // ms overrides the constructed default for this call only — lets a caller
+    // vary the delay per fire (e.g. a shorter debounce when the action is cheap).
+    async fire(ms?: number): Promise<() => boolean> {
+        this.#counter++
+        const c = this.#counter
+        const delay = ms ?? this.#ms
+        if (delay) {
+            await TimeOutPromise.wait(delay)
+        }
+        return () => c === this.#counter
+    }
+
+    // Invalidate any in-flight fire(): bumping the counter makes every pending
+    // proceed() return false, so an action debounced before cancel() never commits.
+    cancel(): void {
+        this.#counter++
+    }
+}
+
+// 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.
+export class Delayed {
+    #timeouts = new Map<string, ReturnType<typeof setTimeout>>()
+
+    go(name: string, fn: () => void, ms: number): void {
+        this.cancel(name)
+        this.#timeouts.set(
+            name,
+            setTimeout(() => {
+                this.#timeouts.delete(name)
+                fn()
+            }, ms)
+        )
+    }
+
+    cancel(name: string): void {
+        const timeout = this.#timeouts.get(name)
+        if (timeout !== undefined) {
+            clearTimeout(timeout)
+            this.#timeouts.delete(name)
+        }
+    }
+
+    cancelAll(): void {
+        this.#timeouts.forEach(t => clearTimeout(t))
+        this.#timeouts.clear()
+    }
+}