@radically-straightforward/utilities 0.0.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

package/README.md

@@ -0,0 +1,132 @@
+# Radically Straightforward · Utilities
+
+**🛠️ Utilities for Node.js and the browser**
+
+## Installation
+
+```console
+$ npm install @radically-straightforward/utilities
+```
+
+## Usage
+
+```typescript
+import * as node from "@radically-straightforward/utilities";
+```
+
+<!-- DOCUMENTATION START: ./source/index.mts -->
+
+### `intern()`
+
+```typescript
+export function intern<T extends WeakKey>(value: T): T;
+```
+
+[Interning](<https://en.wikipedia.org/wiki/Interning_(computer_science)>) a value makes it unique across the program, which is useful for checking equality with `===` (reference equality), using it as a key in a `Map`, adding it to a `Set`, and so forth:
+
+```javascript
+import { intern as $ } from "@radically-straightforward/utilities";
+
+[1] === [1]; // => false
+$([1]) === $([1]); // => true
+
+{
+  const map = new Map();
+  map.set([1], 1);
+  map.set([1], 2);
+  map.size; // => 2
+  map.get([1]); // => undefined
+}
+
+{
+  const map = new Map();
+  map.set($([1]), 1);
+  map.set($([1]), 2);
+  map.size; // => 1
+  map.get($([1])); // => 2
+}
+
+{
+  const set = new Set();
+  set.add([1]);
+  set.add([1]);
+  set.size; // => 2
+  set.has([1]); // => false
+}
+
+{
+  const set = new Set();
+  set.add($([1]));
+  set.add($([1]));
+  set.size; // => 1
+  set.has($([1])); // => true
+}
+```
+
+> **Note:** We recommend that you alias `intern as $` when importing it to make your code less noisy.
+
+> **Note:** The default notion of equality used to intern values is [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual). You may change that by overriding `intern.isEqual: (value: any, other: any) => boolean` before using `intern()` for the first time.
+>
+> In particular, note that `intern()` uses a notion of equality that is deep: it compares, for example, objects within objects by value. This is more ergonomic, because it means that you only have to call `intern()` on the outer object, for example, `$({ a: { b: 2 } })` instead of `$({ a: $({ b: 2 }) })`. But this is slower.
+>
+> You may replace the notion of equality with shallow equality and use the `$({ a: $({ b: 2 }) })` pattern to speed things up. That is, for example, [what React does](https://legacy.reactjs.org/docs/react-api.html#reactpurecomponent). It’s also what the [**JavaScript Records & Tuples Proposal**](https://github.com/tc39/proposal-record-tuple) includes as of January 2024, so it may make your code easier to adapt in the future.
+
+> **Note:** You must not mutate an interned value. Interned values are deeply [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) with [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) to prevent you from mutating them.
+
+> **Note:** Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.
+
+> **Note:** The pool of interned values is available as `intern.pool: Map<Symbol, WeakRef<any>>`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up values that have been garbage collected.
+
+**Related Work**
+
+**[JavaScript Records & Tuples Proposal](https://github.com/tc39/proposal-record-tuple)**
+
+A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()` even though it doesn’t cover `Map`s, `Set`s, regular expressions, and so forth.
+
+It includes a [polyfill](https://github.com/bloomberg/record-tuple-polyfill) which works very similarly to `intern()` but requires different functions for different data types.
+
+**[`collections-deep-equal`](https://npm.im/collections-deep-equal)**
+
+A previous solution to this problem which took a different approach: Instead of interning the values and allowing you to use JavaScript’s `Map`s and `Set`s, `collections-deep-equal` extends `Map`s and `Set`s with a different notion of equality.
+
+`collections-deep-equal` doesn’t address the issue of comparing values with `===` (reference equality).
+
+`collections-deep-equal` does more work on every manipulation of the data structure, for example, when looking up a key in a `Map`, so it may be slower.
+
+`collections-deep-equal` has different intern pools for each `Map` and `Set` instead of `intern()`’s single global intern pool, which may be advantageous because smaller pools may be faster to traverse.
+
+**[Immutable.js](https://npm.im/immutable), [`collections`](https://npm.im/collections), [`mori`](https://npm.im/mori), [TypeScript Collections](https://npm.im/typescript-collections), [`prelude-ts`](https://npm.im/prelude-ts), [`collectable`](https://npm.im/collectable), and so forth**
+
+Similar to `collections-deep-equal`, these libraries implement their own data structures instead of relying on JavaScript’s `Map`s and `Set`s. Some of them go a step further and add their own notions of objects and arrays, which requires you to convert your values back and forth, may not show up nicely in the JavaScript inspector, may be less ergonomic to use with TypeScript, and so forth.
+
+The advantage of these libraries over interning is that they may be faster.
+
+**[`immer`](https://npm.im/immer) and [`icepick`](https://npm.im/icepick)**
+
+Introduce a new way to create values based on existing values.
+
+**[`seamless-immutable`](https://npm.im/seamless-immutable)**
+
+Modifies existing values more profoundly than freezing.
+
+**[`es6-array-map`](https://npm.im/es6-array-map), [`valuecollection`](https://npm.im/valuecollection), [`@strong-roots-capital/map-objects`](https://npm.im/@strong-roots-capital/map-objects), and so forth**
+
+Similar to `collections-deep-equal` but either incomplete, or lacking type definitions, and so forth.
+
+**Other**
+
+- <https://2ality.com/2015/01/es6-maps-sets.html#why-can’t-i-configure-how-maps-and-sets-compare-keys-and-values%3F>
+- <https://stackoverflow.com/questions/21838436/map-using-tuples-or-objects>
+- <https://esdiscuss.org/topic/maps-with-object-keys>
+- <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+- <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+- <https://twitter.com/swannodette/status/1067962983924539392>
+- <https://gist.github.com/modernserf/c000e62d40f678cf395e3f360b9b0e43>
+
+**Implementation Notes**
+
+- Besides [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual) we also considered defaulting to [Node.js’s notion of deep equality](https://nodejs.org/dist/latest-v21.x/docs/api/util.html#utilisdeepstrictequalval1-val2) with the [`deep-equal`](https://npm.im/package/deep-equal) polyfill for the browser.
+
+- Besides [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) we also considered doing the deep freezing with [`deep-freeze-strict`](https://npm.im/deep-freeze-strict), [`deep-freeze-node`](https://npm.im/deep-freeze-node), and [`deep-freeze`](https://npm.im/deep-freeze).
+
+<!-- DOCUMENTATION END: ./source/index.mts -->

package/build/index.d.mts

@@ -0,0 +1,115 @@
+/**
+ * [Interning](<https://en.wikipedia.org/wiki/Interning_(computer_science)>) a value makes it unique across the program, which is useful for checking equality with `===` (reference equality), using it as a key in a `Map`, adding it to a `Set`, and so forth:
+ *
+ * ```javascript
+ * import { intern as $ } from "@radically-straightforward/utilities";
+ *
+ * [1] === [1]; // => false
+ * $([1]) === $([1]); // => true
+ *
+ * {
+ *   const map = new Map();
+ *   map.set([1], 1);
+ *   map.set([1], 2);
+ *   map.size; // => 2
+ *   map.get([1]); // => undefined
+ * }
+ *
+ * {
+ *   const map = new Map();
+ *   map.set($([1]), 1);
+ *   map.set($([1]), 2);
+ *   map.size; // => 1
+ *   map.get($([1])); // => 2
+ * }
+ *
+ * {
+ *   const set = new Set();
+ *   set.add([1]);
+ *   set.add([1]);
+ *   set.size; // => 2
+ *   set.has([1]); // => false
+ * }
+ *
+ * {
+ *   const set = new Set();
+ *   set.add($([1]));
+ *   set.add($([1]));
+ *   set.size; // => 1
+ *   set.has($([1])); // => true
+ * }
+ * ```
+ *
+ * > **Note:** We recommend that you alias `intern as $` when importing it to make your code less noisy.
+ *
+ * > **Note:** The default notion of equality used to intern values is [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual). You may change that by overriding `intern.isEqual: (value: any, other: any) => boolean` before using `intern()` for the first time.
+ * >
+ * > In particular, note that `intern()` uses a notion of equality that is deep: it compares, for example, objects within objects by value. This is more ergonomic, because it means that you only have to call `intern()` on the outer object, for example, `$({ a: { b: 2 } })` instead of `$({ a: $({ b: 2 }) })`. But this is slower.
+ * >
+ * > You may replace the notion of equality with shallow equality and use the `$({ a: $({ b: 2 }) })` pattern to speed things up. That is, for example, [what React does](https://legacy.reactjs.org/docs/react-api.html#reactpurecomponent). It’s also what the [**JavaScript Records & Tuples Proposal**](https://github.com/tc39/proposal-record-tuple) includes as of January 2024, so it may make your code easier to adapt in the future.
+ *
+ * > **Note:** You must not mutate an interned value. Interned values are deeply [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) with [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) to prevent you from mutating them.
+ *
+ * > **Note:** Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.
+ *
+ * > **Note:** The pool of interned values is available as `intern.pool: Map<Symbol, WeakRef<any>>`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up values that have been garbage collected.
+ *
+ * **Related Work**
+ *
+ * **[JavaScript Records & Tuples Proposal](https://github.com/tc39/proposal-record-tuple)**
+ *
+ * A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()` even though it doesn’t cover `Map`s, `Set`s, regular expressions, and so forth.
+ *
+ * It includes a [polyfill](https://github.com/bloomberg/record-tuple-polyfill) which works very similarly to `intern()` but requires different functions for different data types.
+ *
+ * **[`collections-deep-equal`](https://npm.im/collections-deep-equal)**
+ *
+ * A previous solution to this problem which took a different approach: Instead of interning the values and allowing you to use JavaScript’s `Map`s and `Set`s, `collections-deep-equal` extends `Map`s and `Set`s with a different notion of equality.
+ *
+ * `collections-deep-equal` doesn’t address the issue of comparing values with `===` (reference equality).
+ *
+ * `collections-deep-equal` does more work on every manipulation of the data structure, for example, when looking up a key in a `Map`, so it may be slower.
+ *
+ * `collections-deep-equal` has different intern pools for each `Map` and `Set` instead of `intern()`’s single global intern pool, which may be advantageous because smaller pools may be faster to traverse.
+ *
+ * **[Immutable.js](https://npm.im/immutable), [`collections`](https://npm.im/collections), [`mori`](https://npm.im/mori), [TypeScript Collections](https://npm.im/typescript-collections), [`prelude-ts`](https://npm.im/prelude-ts), [`collectable`](https://npm.im/collectable), and so forth**
+ *
+ * Similar to `collections-deep-equal`, these libraries implement their own data structures instead of relying on JavaScript’s `Map`s and `Set`s. Some of them go a step further and add their own notions of objects and arrays, which requires you to convert your values back and forth, may not show up nicely in the JavaScript inspector, may be less ergonomic to use with TypeScript, and so forth.
+ *
+ * The advantage of these libraries over interning is that they may be faster.
+ *
+ * **[`immer`](https://npm.im/immer) and [`icepick`](https://npm.im/icepick)**
+ *
+ * Introduce a new way to create values based on existing values.
+ *
+ * **[`seamless-immutable`](https://npm.im/seamless-immutable)**
+ *
+ * Modifies existing values more profoundly than freezing.
+ *
+ * **[`es6-array-map`](https://npm.im/es6-array-map), [`valuecollection`](https://npm.im/valuecollection), [`@strong-roots-capital/map-objects`](https://npm.im/@strong-roots-capital/map-objects), and so forth**
+ *
+ * Similar to `collections-deep-equal` but either incomplete, or lacking type definitions, and so forth.
+ *
+ * **Other**
+ *
+ * - <https://2ality.com/2015/01/es6-maps-sets.html#why-can’t-i-configure-how-maps-and-sets-compare-keys-and-values%3F>
+ * - <https://stackoverflow.com/questions/21838436/map-using-tuples-or-objects>
+ * - <https://esdiscuss.org/topic/maps-with-object-keys>
+ * - <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+ * - <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+ * - <https://twitter.com/swannodette/status/1067962983924539392>
+ * - <https://gist.github.com/modernserf/c000e62d40f678cf395e3f360b9b0e43>
+ *
+ * **Implementation Notes**
+ *
+ * - Besides [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual) we also considered defaulting to [Node.js’s notion of deep equality](https://nodejs.org/dist/latest-v21.x/docs/api/util.html#utilisdeepstrictequalval1-val2) with the [`deep-equal`](https://npm.im/package/deep-equal) polyfill for the browser.
+ *
+ * - Besides [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) we also considered doing the deep freezing with [`deep-freeze-strict`](https://npm.im/deep-freeze-strict), [`deep-freeze-node`](https://npm.im/deep-freeze-node), and [`deep-freeze`](https://npm.im/deep-freeze).
+ */
+export declare function intern<T extends WeakKey>(value: T): T;
+export declare namespace intern {
+    var isEqual: (value: any, other: any) => boolean;
+    var pool: Map<Symbol, WeakRef<any>>;
+    var finalizationRegistry: FinalizationRegistry<Symbol>;
+}
+//# sourceMappingURL=index.d.mts.map

package/build/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../source/index.mts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAUrD;yBAVe,MAAM"}

package/build/index.mjs

@@ -0,0 +1,218 @@
+import lodash from "lodash";
+import deepFreeze from "deep-freeze-es6";
+/**
+ * [Interning](<https://en.wikipedia.org/wiki/Interning_(computer_science)>) a value makes it unique across the program, which is useful for checking equality with `===` (reference equality), using it as a key in a `Map`, adding it to a `Set`, and so forth:
+ *
+ * ```javascript
+ * import { intern as $ } from "@radically-straightforward/utilities";
+ *
+ * [1] === [1]; // => false
+ * $([1]) === $([1]); // => true
+ *
+ * {
+ *   const map = new Map();
+ *   map.set([1], 1);
+ *   map.set([1], 2);
+ *   map.size; // => 2
+ *   map.get([1]); // => undefined
+ * }
+ *
+ * {
+ *   const map = new Map();
+ *   map.set($([1]), 1);
+ *   map.set($([1]), 2);
+ *   map.size; // => 1
+ *   map.get($([1])); // => 2
+ * }
+ *
+ * {
+ *   const set = new Set();
+ *   set.add([1]);
+ *   set.add([1]);
+ *   set.size; // => 2
+ *   set.has([1]); // => false
+ * }
+ *
+ * {
+ *   const set = new Set();
+ *   set.add($([1]));
+ *   set.add($([1]));
+ *   set.size; // => 1
+ *   set.has($([1])); // => true
+ * }
+ * ```
+ *
+ * > **Note:** We recommend that you alias `intern as $` when importing it to make your code less noisy.
+ *
+ * > **Note:** The default notion of equality used to intern values is [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual). You may change that by overriding `intern.isEqual: (value: any, other: any) => boolean` before using `intern()` for the first time.
+ * >
+ * > In particular, note that `intern()` uses a notion of equality that is deep: it compares, for example, objects within objects by value. This is more ergonomic, because it means that you only have to call `intern()` on the outer object, for example, `$({ a: { b: 2 } })` instead of `$({ a: $({ b: 2 }) })`. But this is slower.
+ * >
+ * > You may replace the notion of equality with shallow equality and use the `$({ a: $({ b: 2 }) })` pattern to speed things up. That is, for example, [what React does](https://legacy.reactjs.org/docs/react-api.html#reactpurecomponent). It’s also what the [**JavaScript Records & Tuples Proposal**](https://github.com/tc39/proposal-record-tuple) includes as of January 2024, so it may make your code easier to adapt in the future.
+ *
+ * > **Note:** You must not mutate an interned value. Interned values are deeply [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) with [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) to prevent you from mutating them.
+ *
+ * > **Note:** Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.
+ *
+ * > **Note:** The pool of interned values is available as `intern.pool: Map<Symbol, WeakRef<any>>`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up values that have been garbage collected.
+ *
+ * **Related Work**
+ *
+ * **[JavaScript Records & Tuples Proposal](https://github.com/tc39/proposal-record-tuple)**
+ *
+ * A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()` even though it doesn’t cover `Map`s, `Set`s, regular expressions, and so forth.
+ *
+ * It includes a [polyfill](https://github.com/bloomberg/record-tuple-polyfill) which works very similarly to `intern()` but requires different functions for different data types.
+ *
+ * **[`collections-deep-equal`](https://npm.im/collections-deep-equal)**
+ *
+ * A previous solution to this problem which took a different approach: Instead of interning the values and allowing you to use JavaScript’s `Map`s and `Set`s, `collections-deep-equal` extends `Map`s and `Set`s with a different notion of equality.
+ *
+ * `collections-deep-equal` doesn’t address the issue of comparing values with `===` (reference equality).
+ *
+ * `collections-deep-equal` does more work on every manipulation of the data structure, for example, when looking up a key in a `Map`, so it may be slower.
+ *
+ * `collections-deep-equal` has different intern pools for each `Map` and `Set` instead of `intern()`’s single global intern pool, which may be advantageous because smaller pools may be faster to traverse.
+ *
+ * **[Immutable.js](https://npm.im/immutable), [`collections`](https://npm.im/collections), [`mori`](https://npm.im/mori), [TypeScript Collections](https://npm.im/typescript-collections), [`prelude-ts`](https://npm.im/prelude-ts), [`collectable`](https://npm.im/collectable), and so forth**
+ *
+ * Similar to `collections-deep-equal`, these libraries implement their own data structures instead of relying on JavaScript’s `Map`s and `Set`s. Some of them go a step further and add their own notions of objects and arrays, which requires you to convert your values back and forth, may not show up nicely in the JavaScript inspector, may be less ergonomic to use with TypeScript, and so forth.
+ *
+ * The advantage of these libraries over interning is that they may be faster.
+ *
+ * **[`immer`](https://npm.im/immer) and [`icepick`](https://npm.im/icepick)**
+ *
+ * Introduce a new way to create values based on existing values.
+ *
+ * **[`seamless-immutable`](https://npm.im/seamless-immutable)**
+ *
+ * Modifies existing values more profoundly than freezing.
+ *
+ * **[`es6-array-map`](https://npm.im/es6-array-map), [`valuecollection`](https://npm.im/valuecollection), [`@strong-roots-capital/map-objects`](https://npm.im/@strong-roots-capital/map-objects), and so forth**
+ *
+ * Similar to `collections-deep-equal` but either incomplete, or lacking type definitions, and so forth.
+ *
+ * **Other**
+ *
+ * - <https://2ality.com/2015/01/es6-maps-sets.html#why-can’t-i-configure-how-maps-and-sets-compare-keys-and-values%3F>
+ * - <https://stackoverflow.com/questions/21838436/map-using-tuples-or-objects>
+ * - <https://esdiscuss.org/topic/maps-with-object-keys>
+ * - <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+ * - <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+ * - <https://twitter.com/swannodette/status/1067962983924539392>
+ * - <https://gist.github.com/modernserf/c000e62d40f678cf395e3f360b9b0e43>
+ *
+ * **Implementation Notes**
+ *
+ * - Besides [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual) we also considered defaulting to [Node.js’s notion of deep equality](https://nodejs.org/dist/latest-v21.x/docs/api/util.html#utilisdeepstrictequalval1-val2) with the [`deep-equal`](https://npm.im/package/deep-equal) polyfill for the browser.
+ *
+ * - Besides [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) we also considered doing the deep freezing with [`deep-freeze-strict`](https://npm.im/deep-freeze-strict), [`deep-freeze-node`](https://npm.im/deep-freeze-node), and [`deep-freeze`](https://npm.im/deep-freeze).
+ */
+export function intern(value) {
+    for (const internWeakRef of intern.pool.values()) {
+        const internValue = internWeakRef.deref();
+        if (intern.isEqual(value, internValue))
+            return internValue;
+    }
+    const key = Symbol();
+    deepFreeze(value);
+    intern.pool.set(key, new WeakRef(value));
+    intern.finalizationRegistry.register(value, key);
+    return value;
+}
+intern.isEqual = lodash.isEqual;
+intern.pool = new Map();
+intern.finalizationRegistry = new FinalizationRegistry((key) => {
+    intern.pool.delete(key);
+});
+/*
+
+
+Math.random().toString(36).slice(2)
+
+
+
+
+https://npm.im/package/p-timeout
+https://npm.im/package/delay
+https://npm.im/package/sleep-promise
+https://npm.im/package/promise-timeout
+https://npm.im/package/sleep
+https://npm.im/package/timeout-as-promise
+https://npm.im/package/delayed
+https://npm.im/package/sleep-async
+https://npm.im/package/promise.timeout
+
+*/
+// /**
+//     - Remove uses of `node:timers/promises`?
+//  *
+//  * TODO: In universal JavaScript, implement a way to **canonicalize** objects using deepEquals to be used in Sets and as Map keys (then deprecate `collections-deep-equal`).
+//  *   - value objects
+//  *   - https://lodash.com/docs/4.17.15#isEqual
+//  * TODO: Implement using setTimeout and let it be usable in client-side JavaScript as well.
+//  * TODO: Explain the differences between this and `setInterval()` (wait for completion before setting the next scheduler, and force a job to run)
+//  *
+//  * Start a background job that runs every given `interval`.
+//  *
+//  * You may use `backgroundJob.run()` to force the background job to run right away.
+//  *
+//  * **Note:** If a background job is running when `backgroundJob.continue()` is called.
+//  *
+//  * You may use `backgroundJob.stop()` to stop the background job.
+//  *
+//  * **Note:** If a background job is running when `backgroundJob.stop()` is called, then that background job is run to completion, but a future background job run is not scheduled. This is similar to how an HTTP server may stop  finish processing existing requests but don’t accept new requests.
+//  *
+//  * **Note:** The `intervalVariance` prevents many background jobs from starting at the same and overloading the machine.
+//  *
+//  * **Example**
+//  *
+//  * ```javascript
+//  * import * as node from "@radically-straightforward/node";
+//  *
+//  * const backgroundJob = node.backgroundJob({ interval: 3 * 1000 }, () => {
+//  *   console.log("backgroundJob(): Running background job...");
+//  * });
+//  * process.on("SIGTSTP", () => {
+//  *   backgroundJob.run();
+//  * });
+//  * console.log(
+//  *   "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+//  * );
+//  * await node.shouldTerminate();
+//  * backgroundJob.stop();
+//  * ```
+//  */
+// export function backgroundJob(
+//   {
+//     interval,
+//     intervalVariance = 0.1,
+//   }: { interval: number; intervalVariance?: number },
+//   function_: () => void | Promise<void>,
+// ): { run: () => void; stop: () => void } {
+//   let shouldContinue = true;
+//   let abortController = new AbortController();
+//   (async () => {
+//     while (shouldContinue) {
+//       await function_();
+//       await timers
+//         .setTimeout(
+//           interval + interval * intervalVariance * Math.random(),
+//           undefined,
+//           { signal: abortController.signal },
+//         )
+//         .catch(() => {});
+//       abortController = new AbortController();
+//     }
+//   })();
+//   return {
+//     run: () => {
+//       abortController.abort();
+//     },
+//     stop: () => {
+//       shouldContinue = false;
+//       abortController.abort();
+//     },
+//   };
+// }
+//# sourceMappingURL=index.mjs.map

package/build/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../source/index.mts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,UAAU,MAAM,iBAAiB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,MAAM,UAAU,MAAM,CAAoB,KAAQ;IAChD,KAAK,MAAM,aAAa,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC;QAC1C,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC;YAAE,OAAO,WAAW,CAAC;IAC7D,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,KAAK,CAAC,CAAC;IAClB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACzC,MAAM,CAAC,oBAAoB,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACjD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;AAEhC,MAAM,CAAC,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;AAE9C,MAAM,CAAC,oBAAoB,GAAG,IAAI,oBAAoB,CAAS,CAAC,GAAG,EAAE,EAAE;IACrE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;EAkBE;AACF,MAAM;AACN,+CAA+C;AAC/C,KAAK;AACL,+KAA+K;AAC/K,uBAAuB;AACvB,iDAAiD;AACjD,8FAA8F;AAC9F,oJAAoJ;AACpJ,KAAK;AACL,8DAA8D;AAC9D,KAAK;AACL,sFAAsF;AACtF,KAAK;AACL,yFAAyF;AACzF,KAAK;AACL,oEAAoE;AACpE,KAAK;AACL,ySAAyS;AACzS,KAAK;AACL,2HAA2H;AAC3H,KAAK;AACL,iBAAiB;AACjB,KAAK;AACL,mBAAmB;AACnB,8DAA8D;AAC9D,KAAK;AACL,8EAA8E;AAC9E,kEAAkE;AAClE,SAAS;AACT,mCAAmC;AACnC,4BAA4B;AAC5B,SAAS;AACT,kBAAkB;AAClB,yFAAyF;AACzF,QAAQ;AACR,mCAAmC;AACnC,2BAA2B;AAC3B,SAAS;AACT,MAAM;AACN,iCAAiC;AACjC,MAAM;AACN,gBAAgB;AAChB,8BAA8B;AAC9B,wDAAwD;AACxD,2CAA2C;AAC3C,6CAA6C;AAC7C,+BAA+B;AAC/B,iDAAiD;AACjD,mBAAmB;AACnB,+BAA+B;AAC/B,2BAA2B;AAC3B,qBAAqB;AACrB,uBAAuB;AACvB,oEAAoE;AACpE,uBAAuB;AACvB,gDAAgD;AAChD,YAAY;AACZ,4BAA4B;AAC5B,iDAAiD;AACjD,QAAQ;AACR,UAAU;AACV,aAAa;AACb,mBAAmB;AACnB,iCAAiC;AACjC,SAAS;AACT,oBAAoB;AACpB,gCAAgC;AAChC,iCAAiC;AACjC,SAAS;AACT,OAAO;AACP,IAAI"}

package/build/index.test.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.mts.map

package/build/index.test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.mts","sourceRoot":"","sources":["../source/index.test.mts"],"names":[],"mappings":""}

package/build/index.test.mjs

@@ -0,0 +1,64 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { intern as $ } from "./index.mjs";
+test("intern()", () => {
+    // @ts-ignore
+    assert(([1] === [1]) === false);
+    assert($([1]) === $([1]));
+    {
+        const map = new Map();
+        map.set([1], 1);
+        map.set([1], 2);
+        assert.equal(map.size, 2);
+        assert.equal(map.get([1]), undefined);
+    }
+    {
+        const map = new Map();
+        map.set($([1]), 1);
+        map.set($([1]), 2);
+        assert.equal(map.size, 1);
+        assert.equal(map.get($([1])), 2);
+    }
+    {
+        const set = new Set();
+        set.add([1]);
+        set.add([1]);
+        assert.equal(set.size, 2);
+        assert(set.has([1]) === false);
+    }
+    {
+        const set = new Set();
+        set.add($([1]));
+        set.add($([1]));
+        assert.equal(set.size, 1);
+        assert(set.has($([1])));
+    }
+    assert.notEqual($([1]), $([2]));
+    assert.throws(() => {
+        $([1])[0] = 2;
+    });
+});
+// test(
+//   "backgroundJob()",
+//   {
+//     ...(!process.stdin.isTTY
+//       ? {
+//           skip: "Run interactive test with ‘node ./build/index.test.mjs’.",
+//         }
+//       : {}),
+//   },
+//   async () => {
+//     const backgroundJob = node.backgroundJob({ interval: 3 * 1000 }, () => {
+//       console.log("backgroundJob(): Running background job...");
+//     });
+//     process.on("SIGTSTP", () => {
+//       backgroundJob.run();
+//     });
+//     console.log(
+//       "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+//     );
+//     await node.shouldTerminate();
+//     backgroundJob.stop();
+//   },
+// );
+//# sourceMappingURL=index.test.mjs.map

package/build/index.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.mjs","sourceRoot":"","sources":["../source/index.test.mts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@radically-straightforward/utilities",
+  "version": "0.0.1",
+  "description": "🛠️ Utilities for Node.js and the browser",
+  "keywords": [
+    "node",
+    "browser",
+    "utilities"
+  ],
+  "homepage": "https://github.com/leafac/radically-straightforward",
+  "repository": "https://github.com/leafac/radically-straightforward",
+  "bugs": "https://github.com/leafac/radically-straightforward/issues",
+  "funding": [
+    "https://patreon.com/leafac",
+    "https://github.com/sponsors/leafac",
+    "https://paypal.me/LeandroFacchinettiEU",
+    "https://btc.com/34KJBgtaFYMtDqpSgMayw9qiKWg2GQXA9M"
+  ],
+  "author": "Leandro Facchinetti <radically-straightforward@leafac.com> (https://leafac.com)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": "./build/index.mjs",
+  "types": "./build/index.d.mts",
+  "scripts": {
+    "prepare": "tsc && documentation",
+    "test": "npm run prepare && node --test && prettier --check \"./README.md\" --check \"./package.json\" --check \"./tsconfig.json\" --check \"./source/**/*.mts\""
+  },
+  "dependencies": {
+    "deep-freeze-es6": "^3.0.2",
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "@radically-straightforward/documentation": "^1.0.1",
+    "@radically-straightforward/tsconfig": "^1.0.0",
+    "@types/lodash": "^4.14.202",
+    "@types/node": "^20.10.6",
+    "prettier": "^3.1.1",
+    "typescript": "^5.3.3"
+  },
+  "prettier": {}
+}

package/source/index.mts

@@ -0,0 +1,221 @@
+import lodash from "lodash";
+import deepFreeze from "deep-freeze-es6";
+
+/**
+ * [Interning](<https://en.wikipedia.org/wiki/Interning_(computer_science)>) a value makes it unique across the program, which is useful for checking equality with `===` (reference equality), using it as a key in a `Map`, adding it to a `Set`, and so forth:
+ *
+ * ```javascript
+ * import { intern as $ } from "@radically-straightforward/utilities";
+ *
+ * [1] === [1]; // => false
+ * $([1]) === $([1]); // => true
+ *
+ * {
+ *   const map = new Map();
+ *   map.set([1], 1);
+ *   map.set([1], 2);
+ *   map.size; // => 2
+ *   map.get([1]); // => undefined
+ * }
+ *
+ * {
+ *   const map = new Map();
+ *   map.set($([1]), 1);
+ *   map.set($([1]), 2);
+ *   map.size; // => 1
+ *   map.get($([1])); // => 2
+ * }
+ *
+ * {
+ *   const set = new Set();
+ *   set.add([1]);
+ *   set.add([1]);
+ *   set.size; // => 2
+ *   set.has([1]); // => false
+ * }
+ *
+ * {
+ *   const set = new Set();
+ *   set.add($([1]));
+ *   set.add($([1]));
+ *   set.size; // => 1
+ *   set.has($([1])); // => true
+ * }
+ * ```
+ *
+ * > **Note:** We recommend that you alias `intern as $` when importing it to make your code less noisy.
+ *
+ * > **Note:** The default notion of equality used to intern values is [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual). You may change that by overriding `intern.isEqual: (value: any, other: any) => boolean` before using `intern()` for the first time.
+ * >
+ * > In particular, note that `intern()` uses a notion of equality that is deep: it compares, for example, objects within objects by value. This is more ergonomic, because it means that you only have to call `intern()` on the outer object, for example, `$({ a: { b: 2 } })` instead of `$({ a: $({ b: 2 }) })`. But this is slower.
+ * >
+ * > You may replace the notion of equality with shallow equality and use the `$({ a: $({ b: 2 }) })` pattern to speed things up. That is, for example, [what React does](https://legacy.reactjs.org/docs/react-api.html#reactpurecomponent). It’s also what the [**JavaScript Records & Tuples Proposal**](https://github.com/tc39/proposal-record-tuple) includes as of January 2024, so it may make your code easier to adapt in the future.
+ *
+ * > **Note:** You must not mutate an interned value. Interned values are deeply [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) with [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) to prevent you from mutating them.
+ *
+ * > **Note:** Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.
+ *
+ * > **Note:** The pool of interned values is available as `intern.pool: Map<Symbol, WeakRef<any>>`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up values that have been garbage collected.
+ *
+ * **Related Work**
+ *
+ * **[JavaScript Records & Tuples Proposal](https://github.com/tc39/proposal-record-tuple)**
+ *
+ * A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()` even though it doesn’t cover `Map`s, `Set`s, regular expressions, and so forth.
+ *
+ * It includes a [polyfill](https://github.com/bloomberg/record-tuple-polyfill) which works very similarly to `intern()` but requires different functions for different data types.
+ *
+ * **[`collections-deep-equal`](https://npm.im/collections-deep-equal)**
+ *
+ * A previous solution to this problem which took a different approach: Instead of interning the values and allowing you to use JavaScript’s `Map`s and `Set`s, `collections-deep-equal` extends `Map`s and `Set`s with a different notion of equality.
+ *
+ * `collections-deep-equal` doesn’t address the issue of comparing values with `===` (reference equality).
+ *
+ * `collections-deep-equal` does more work on every manipulation of the data structure, for example, when looking up a key in a `Map`, so it may be slower.
+ *
+ * `collections-deep-equal` has different intern pools for each `Map` and `Set` instead of `intern()`’s single global intern pool, which may be advantageous because smaller pools may be faster to traverse.
+ *
+ * **[Immutable.js](https://npm.im/immutable), [`collections`](https://npm.im/collections), [`mori`](https://npm.im/mori), [TypeScript Collections](https://npm.im/typescript-collections), [`prelude-ts`](https://npm.im/prelude-ts), [`collectable`](https://npm.im/collectable), and so forth**
+ *
+ * Similar to `collections-deep-equal`, these libraries implement their own data structures instead of relying on JavaScript’s `Map`s and `Set`s. Some of them go a step further and add their own notions of objects and arrays, which requires you to convert your values back and forth, may not show up nicely in the JavaScript inspector, may be less ergonomic to use with TypeScript, and so forth.
+ *
+ * The advantage of these libraries over interning is that they may be faster.
+ *
+ * **[`immer`](https://npm.im/immer) and [`icepick`](https://npm.im/icepick)**
+ *
+ * Introduce a new way to create values based on existing values.
+ *
+ * **[`seamless-immutable`](https://npm.im/seamless-immutable)**
+ *
+ * Modifies existing values more profoundly than freezing.
+ *
+ * **[`es6-array-map`](https://npm.im/es6-array-map), [`valuecollection`](https://npm.im/valuecollection), [`@strong-roots-capital/map-objects`](https://npm.im/@strong-roots-capital/map-objects), and so forth**
+ *
+ * Similar to `collections-deep-equal` but either incomplete, or lacking type definitions, and so forth.
+ *
+ * **Other**
+ *
+ * - <https://2ality.com/2015/01/es6-maps-sets.html#why-can’t-i-configure-how-maps-and-sets-compare-keys-and-values%3F>
+ * - <https://stackoverflow.com/questions/21838436/map-using-tuples-or-objects>
+ * - <https://esdiscuss.org/topic/maps-with-object-keys>
+ * - <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+ * - <https://medium.com/@modernserf/the-tyranny-of-triple-equals-de46cc0c5723>
+ * - <https://twitter.com/swannodette/status/1067962983924539392>
+ * - <https://gist.github.com/modernserf/c000e62d40f678cf395e3f360b9b0e43>
+ *
+ * **Implementation Notes**
+ *
+ * - Besides [Lodash’s `isEqual()`](https://lodash.com/docs/4.17.15#isEqual) we also considered defaulting to [Node.js’s notion of deep equality](https://nodejs.org/dist/latest-v21.x/docs/api/util.html#utilisdeepstrictequalval1-val2) with the [`deep-equal`](https://npm.im/package/deep-equal) polyfill for the browser.
+ *
+ * - Besides [`deep-freeze-es6`](https://npm.im/deep-freeze-es6) we also considered doing the deep freezing with [`deep-freeze-strict`](https://npm.im/deep-freeze-strict), [`deep-freeze-node`](https://npm.im/deep-freeze-node), and [`deep-freeze`](https://npm.im/deep-freeze).
+ */
+export function intern<T extends WeakKey>(value: T): T {
+  for (const internWeakRef of intern.pool.values()) {
+    const internValue = internWeakRef.deref();
+    if (intern.isEqual(value, internValue)) return internValue;
+  }
+  const key = Symbol();
+  deepFreeze(value);
+  intern.pool.set(key, new WeakRef(value));
+  intern.finalizationRegistry.register(value, key);
+  return value;
+}
+
+intern.isEqual = lodash.isEqual;
+
+intern.pool = new Map<Symbol, WeakRef<any>>();
+
+intern.finalizationRegistry = new FinalizationRegistry<Symbol>((key) => {
+  intern.pool.delete(key);
+});
+
+/*
+
+
+Math.random().toString(36).slice(2)
+
+
+
+
+https://npm.im/package/p-timeout
+https://npm.im/package/delay
+https://npm.im/package/sleep-promise
+https://npm.im/package/promise-timeout
+https://npm.im/package/sleep
+https://npm.im/package/timeout-as-promise
+https://npm.im/package/delayed
+https://npm.im/package/sleep-async
+https://npm.im/package/promise.timeout
+
+*/
+// /**
+//     - Remove uses of `node:timers/promises`?
+//  *
+//  * TODO: In universal JavaScript, implement a way to **canonicalize** objects using deepEquals to be used in Sets and as Map keys (then deprecate `collections-deep-equal`).
+//  *   - value objects
+//  *   - https://lodash.com/docs/4.17.15#isEqual
+//  * TODO: Implement using setTimeout and let it be usable in client-side JavaScript as well.
+//  * TODO: Explain the differences between this and `setInterval()` (wait for completion before setting the next scheduler, and force a job to run)
+//  *
+//  * Start a background job that runs every given `interval`.
+//  *
+//  * You may use `backgroundJob.run()` to force the background job to run right away.
+//  *
+//  * **Note:** If a background job is running when `backgroundJob.continue()` is called.
+//  *
+//  * You may use `backgroundJob.stop()` to stop the background job.
+//  *
+//  * **Note:** If a background job is running when `backgroundJob.stop()` is called, then that background job is run to completion, but a future background job run is not scheduled. This is similar to how an HTTP server may stop  finish processing existing requests but don’t accept new requests.
+//  *
+//  * **Note:** The `intervalVariance` prevents many background jobs from starting at the same and overloading the machine.
+//  *
+//  * **Example**
+//  *
+//  * ```javascript
+//  * import * as node from "@radically-straightforward/node";
+//  *
+//  * const backgroundJob = node.backgroundJob({ interval: 3 * 1000 }, () => {
+//  *   console.log("backgroundJob(): Running background job...");
+//  * });
+//  * process.on("SIGTSTP", () => {
+//  *   backgroundJob.run();
+//  * });
+//  * console.log(
+//  *   "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+//  * );
+//  * await node.shouldTerminate();
+//  * backgroundJob.stop();
+//  * ```
+//  */
+// export function backgroundJob(
+//   {
+//     interval,
+//     intervalVariance = 0.1,
+//   }: { interval: number; intervalVariance?: number },
+//   function_: () => void | Promise<void>,
+// ): { run: () => void; stop: () => void } {
+//   let shouldContinue = true;
+//   let abortController = new AbortController();
+//   (async () => {
+//     while (shouldContinue) {
+//       await function_();
+//       await timers
+//         .setTimeout(
+//           interval + interval * intervalVariance * Math.random(),
+//           undefined,
+//           { signal: abortController.signal },
+//         )
+//         .catch(() => {});
+//       abortController = new AbortController();
+//     }
+//   })();
+//   return {
+//     run: () => {
+//       abortController.abort();
+//     },
+//     stop: () => {
+//       shouldContinue = false;
+//       abortController.abort();
+//     },
+//   };
+// }

package/source/index.test.mts

@@ -0,0 +1,72 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import * as utilities from "./index.mjs";
+import { intern as $ } from "./index.mjs";
+
+test("intern()", () => {
+  // @ts-ignore
+  assert(([1] === [1]) === false);
+  assert($([1]) === $([1]));
+
+  {
+    const map = new Map();
+    map.set([1], 1);
+    map.set([1], 2);
+    assert.equal(map.size, 2);
+    assert.equal(map.get([1]), undefined);
+  }
+
+  {
+    const map = new Map();
+    map.set($([1]), 1);
+    map.set($([1]), 2);
+    assert.equal(map.size, 1);
+    assert.equal(map.get($([1])), 2);
+  }
+
+  {
+    const set = new Set();
+    set.add([1]);
+    set.add([1]);
+    assert.equal(set.size, 2);
+    assert(set.has([1]) === false);
+  }
+
+  {
+    const set = new Set();
+    set.add($([1]));
+    set.add($([1]));
+    assert.equal(set.size, 1);
+    assert(set.has($([1])));
+  }
+
+  assert.notEqual($([1]), $([2]));
+
+  assert.throws(() => {
+    $([1])[0] = 2;
+  });
+});
+
+// test(
+//   "backgroundJob()",
+//   {
+//     ...(!process.stdin.isTTY
+//       ? {
+//           skip: "Run interactive test with ‘node ./build/index.test.mjs’.",
+//         }
+//       : {}),
+//   },
+//   async () => {
+//     const backgroundJob = node.backgroundJob({ interval: 3 * 1000 }, () => {
+//       console.log("backgroundJob(): Running background job...");
+//     });
+//     process.on("SIGTSTP", () => {
+//       backgroundJob.run();
+//     });
+//     console.log(
+//       "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+//     );
+//     await node.shouldTerminate();
+//     backgroundJob.stop();
+//   },
+// );

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@radically-straightforward/tsconfig",
+  "compilerOptions": {
+    "rootDir": "./source/",
+    "outDir": "./build/"
+  }
+}