@greendrake/util 0.6.0 → 0.7.0

package/README.md

@@ -173,10 +173,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.7.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 { randomString, dClone, isEmpty, arrayRemove, arraysEqual, capitalise, humanSeconds, humanFileSize, fileMime, configuration, 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 { 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/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]