npm - @radically-straightforward/utilities - Versions diffs - 0.0.2 → 1.0.0 - Mend

@radically-straightforward/utilities 0.0.2 → 1.0.0

Files changed (11) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,15 @@
 # Changelog
+## 1.0.0 · 2024-01-06
+- Added `backgroundJob()`.
+- Added `sleep()`.
+- Added `randomString()`.
+## 0.0.3 · 2024-01-05
+- Made `intern()` more strict in terms of types and provide auxiliary types for it.
 ## 0.0.2 · 2024-01-05
 - **Breaking Change:** Modified `intern()` to be shallow, which may be easier to reason about and faster.

package/README.md CHANGED Viewed

@@ -11,33 +11,141 @@ $ npm install @radically-straightforward/utilities
 ## Usage
 ```typescript
-import * as node from "@radically-straightforward/utilities";
+import * as utilities from "@radically-straightforward/utilities";
 ```
 <!-- DOCUMENTATION START: ./source/index.mts -->
+### `backgroundJob()`
+```typescript
+export function backgroundJob(
+  {
+    interval,
+    intervalVariance = 0.1,
+  }: {
+    interval: number;
+    intervalVariance?: number;
+  },
+  job: () => void | Promise<void>,
+): {
+  run: () => void;
+  stop: () => void;
+};
+```
+Start a background job that runs every `interval`.
+This is different from `setInterval()` in the following ways:
+1. The interval counts **between** jobs, so slow background jobs don’t get called concurrently:
+   ```
+   setInterval()
+   | SLOW BACKGROUND JOB |
+   | INTERVAL | SLOW BACKGROUND JOB |
+              | INTERVAL | ...
+   backgroundJob()
+   | SLOW BACKGROUND JOB | INTERVAL | SLOW BACKGROUND JOB | INTERVAL | ...
+   ```
+2. We introduce a random `intervalVariance` to avoid many background jobs from starting at the same time and overloading the machine.
+3. You may use `backgroundJob.run()` to force the background job to run right away. If the background job is already running, calling `backgroundJob.run()` schedules it to run again as soon as possible (not waiting the interval).
+4. You may use `backgroundJob.stop()` to stop the background job. If the background job is running, it will finish but it will not be scheduled to run again. This is similar to how an HTTP server may terminate gracefully by stopping accepting new requests but finishing responding to existing requests. After a job has been stopped, you may not `backgroundJob.run()` it again (calling `backgroundJob.run()` has no effect).
+**Example**
+```javascript
+import * as utilities from "@radically-straightforward/utilities";
+import * as node from "@radically-straightforward/node";
+const backgroundJob = utilities.backgroundJob(
+  { interval: 3 * 1000 },
+  async () => {
+    console.log("backgroundJob(): Running background job...");
+    await utilities.sleep(3 * 1000);
+    console.log("backgroundJob(): ...finished running background job.");
+  },
+);
+console.log(
+  "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+);
+process.on("SIGTSTP", () => {
+  backgroundJob.run();
+});
+await node.shouldTerminate();
+backgroundJob.stop();
+```
+### `sleep()`
+```typescript
+export function sleep(duration: number): Promise<void>;
+```
+A promisified version of `setTimeout()`. It doesn’t offer a way to `clearTimeout()`. Useful in the browser—in Node.js you’re better served by [`timersPromises.setTimeout()`](https://nodejs.org/dist/latest-v21.x/docs/api/timers.html#timerspromisessettimeoutdelay-value-options).
+### `randomString()`
+```typescript
+export function randomString(): string;
+```
+A fast random string generator. The generated strings are 10 or 11 characters in length. The generated strings include the characters `[0-9a-z]`. The generated strings are **not** cryptographically secure—if you need that, then use [`crypto-random-string`](https://npm.im/crypto-random-string).
+### `Intern`
+```typescript
+export type Intern<Type> = Readonly<
+  Type & {
+    [internSymbol]: true;
+  }
+>;
+```
+Utility type for `intern()`.
+### `InternInnerValue`
+```typescript
+export type InternInnerValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | symbol
+  | undefined
+  | null
+  | Intern<unknown>;
+```
+Utility type for `intern()`.
 ### `intern()`
 ```typescript
 export function intern<
   T extends
-    | Array<unknown>
+    | Array<InternInnerValue>
     | {
-        [key: string]: unknown;
+        [key: string]: InternInnerValue;
       },
->(value: T): T;
+>(value: T): Intern<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
+```typescript
 import { intern as $ } from "@radically-straightforward/utilities";
 [1] === [1]; // => false
 $([1]) === $([1]); // => true
 {
-  const map = new Map();
+  const map = new Map<number[], number>();
   map.set([1], 1);
   map.set([1], 2);
   map.size; // => 2
@@ -45,7 +153,7 @@ $([1]) === $([1]); // => true
 }
 {
-  const map = new Map();
+  const map = new Map<utilities.Intern<number[]>, number>();
   map.set($([1]), 1);
   map.set($([1]), 2);
   map.size; // => 1
@@ -53,7 +161,7 @@ $([1]) === $([1]); // => true
 }
 {
-  const set = new Set();
+  const set = new Set<number[]>();
   set.add([1]);
   set.add([1]);
   set.size; // => 2
@@ -61,7 +169,7 @@ $([1]) === $([1]); // => true
 }
 {
-  const set = new Set();
+  const set = new Set<utilities.Intern<number[]>>();
   set.add($([1]));
   set.add($([1]));
   set.size; // => 1
@@ -79,7 +187,9 @@ $([1]) === $([1]); // => true
 > **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
+> **Note:** Interned objects do not preserve the order of the attributes: `$({ a: 1, b: 2 }) === $({ b: 2, a: 1 })`.
+> **Note:** The pool of interned values is available as `intern.pool`. The interned values are kept with `WeakRef`s to allow them to be garbage collected when they aren’t referenced anywhere else anymore. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
 **Related Work**

package/build/index.d.mts CHANGED Viewed

@@ -1,14 +1,86 @@
 /**
- * [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:
+ * Start a background job that runs every `interval`.
+ *
+ * This is different from `setInterval()` in the following ways:
+ *
+ * 1. The interval counts **between** jobs, so slow background jobs don’t get called concurrently:
+ *
+ *    ```
+ *    setInterval()
+ *    | SLOW BACKGROUND JOB |
+ *    | INTERVAL | SLOW BACKGROUND JOB |
+ *               | INTERVAL | ...
+ *
+ *    backgroundJob()
+ *    | SLOW BACKGROUND JOB | INTERVAL | SLOW BACKGROUND JOB | INTERVAL | ...
+ *    ```
+ *
+ * 2. We introduce a random `intervalVariance` to avoid many background jobs from starting at the same time and overloading the machine.
+ *
+ * 3. You may use `backgroundJob.run()` to force the background job to run right away. If the background job is already running, calling `backgroundJob.run()` schedules it to run again as soon as possible (not waiting the interval).
+ *
+ * 4. You may use `backgroundJob.stop()` to stop the background job. If the background job is running, it will finish but it will not be scheduled to run again. This is similar to how an HTTP server may terminate gracefully by stopping accepting new requests but finishing responding to existing requests. After a job has been stopped, you may not `backgroundJob.run()` it again (calling `backgroundJob.run()` has no effect).
+ *
+ * **Example**
  *
  * ```javascript
+ * import * as utilities from "@radically-straightforward/utilities";
+ * import * as node from "@radically-straightforward/node";
+ *
+ * const backgroundJob = utilities.backgroundJob(
+ *   { interval: 3 * 1000 },
+ *   async () => {
+ *     console.log("backgroundJob(): Running background job...");
+ *     await utilities.sleep(3 * 1000);
+ *     console.log("backgroundJob(): ...finished running background job.");
+ *   },
+ * );
+ * console.log(
+ *   "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+ * );
+ * process.on("SIGTSTP", () => {
+ *   backgroundJob.run();
+ * });
+ * await node.shouldTerminate();
+ * backgroundJob.stop();
+ * ```
+ */
+export declare function backgroundJob({ interval, intervalVariance, }: {
+    interval: number;
+    intervalVariance?: number;
+}, job: () => void | Promise<void>): {
+    run: () => void;
+    stop: () => void;
+};
+/**
+ * A promisified version of `setTimeout()`. It doesn’t offer a way to `clearTimeout()`. Useful in the browser—in Node.js you’re better served by [`timersPromises.setTimeout()`](https://nodejs.org/dist/latest-v21.x/docs/api/timers.html#timerspromisessettimeoutdelay-value-options).
+ */
+export declare function sleep(duration: number): Promise<void>;
+/**
+ * A fast random string generator. The generated strings are 10 or 11 characters in length. The generated strings include the characters `[0-9a-z]`. The generated strings are **not** cryptographically secure—if you need that, then use [`crypto-random-string`](https://npm.im/crypto-random-string).
+ */
+export declare function randomString(): string;
+/**
+ * Utility type for `intern()`.
+ */
+export type Intern<Type> = Readonly<Type & {
+    [internSymbol]: true;
+}>;
+/**
+ * Utility type for `intern()`.
+ */
+export type InternInnerValue = string | number | bigint | boolean | symbol | undefined | null | Intern<unknown>;
+/**
+ * [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:
+ *
+ * ```typescript
  * import { intern as $ } from "@radically-straightforward/utilities";
  *
  * [1] === [1]; // => false
  * $([1]) === $([1]); // => true
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<number[], number>();
  *   map.set([1], 1);
  *   map.set([1], 2);
  *   map.size; // => 2
@@ -16,7 +88,7 @@
  * }
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<utilities.Intern<number[]>, number>();
  *   map.set($([1]), 1);
  *   map.set($([1]), 2);
  *   map.size; // => 1
@@ -24,7 +96,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -32,7 +104,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -50,7 +122,9 @@
  *
  * > **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
+ * > **Note:** Interned objects do not preserve the order of the attributes: `$({ a: 1, b: 2 }) === $({ b: 2, a: 1 })`.
+ *
+ * > **Note:** The pool of interned values is available as `intern.pool`. The interned values are kept with `WeakRef`s to allow them to be garbage collected when they aren’t referenced anywhere else anymore. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
  *
  * **Related Work**
  *
@@ -98,18 +172,24 @@
  * - <https://twitter.com/swannodette/status/1067962983924539392>
  * - <https://gist.github.com/modernserf/c000e62d40f678cf395e3f360b9b0e43>
  */
-export declare function intern<T extends Array<unknown> | {
-    [key: string]: unknown;
-}>(value: T): T;
+export declare function intern<T extends Array<InternInnerValue> | {
+    [key: string]: InternInnerValue;
+}>(value: T): Intern<T>;
 export declare namespace intern {
-    var interned: symbol;
-    var pools: {
-        tuple: Map<Symbol, WeakRef<any>>;
-        record: Map<Symbol, WeakRef<any>>;
+    var pool: {
+        tuple: Map<Symbol, WeakRef<Readonly<InternInnerValue[] & {
+            [internSymbol]: true;
+        }>>>;
+        record: Map<Symbol, WeakRef<Readonly<{
+            [key: string]: InternInnerValue;
+        } & {
+            [internSymbol]: true;
+        }>>>;
     };
     var finalizationRegistry: FinalizationRegistry<{
         type: "tuple" | "record";
         key: Symbol;
     }>;
 }
+export declare const internSymbol: unique symbol;
 //# sourceMappingURL=index.d.mts.map

package/build/index.d.mts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../source/index.mts"],"names":[],"mappings":"AAAA~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG~~;AACH,wBAAgB,MAAM,CAAC,CAAC,~~SAAS~~,KAAK,CAAC,OAAO,CAAC,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,~~OAAO~~,CAAA;CAAE,~~EAC1E~~,KAAK,EAAE,CAAC,~~GACP~~,CAAC,~~CA2CH~~;yBA7Ce,MAAM"}
1	+ {"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../source/index.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,aAAa,CAC3B,EACE,QAAQ,EACR,gBAAsB,GACvB,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,GAAG,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC9B;IAAE,GAAG,EAAE,MAAM,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAuCvC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,GAAG;IAAE,CAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,SAAS,GACT,IAAI,GACJ,MAAM,CAAC,OAAO,CAAC,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,wBAAgB,MAAM,CACpB,CAAC,SAAS,KAAK,CAAC,gBAAgB,CAAC,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,EACvE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CA2CrB;yBA7Ce,MAAM;;;;;;;;;;;;;;;;AA+CtB,eAAO,MAAM,YAAY,eAAmB,CAAC"}

package/build/index.mjs CHANGED Viewed

@@ -1,14 +1,106 @@
 /**
- * [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:
+ * Start a background job that runs every `interval`.
+ *
+ * This is different from `setInterval()` in the following ways:
+ *
+ * 1. The interval counts **between** jobs, so slow background jobs don’t get called concurrently:
+ *
+ *    ```
+ *    setInterval()
+ *    | SLOW BACKGROUND JOB |
+ *    | INTERVAL | SLOW BACKGROUND JOB |
+ *               | INTERVAL | ...
+ *
+ *    backgroundJob()
+ *    | SLOW BACKGROUND JOB | INTERVAL | SLOW BACKGROUND JOB | INTERVAL | ...
+ *    ```
+ *
+ * 2. We introduce a random `intervalVariance` to avoid many background jobs from starting at the same time and overloading the machine.
+ *
+ * 3. You may use `backgroundJob.run()` to force the background job to run right away. If the background job is already running, calling `backgroundJob.run()` schedules it to run again as soon as possible (not waiting the interval).
+ *
+ * 4. You may use `backgroundJob.stop()` to stop the background job. If the background job is running, it will finish but it will not be scheduled to run again. This is similar to how an HTTP server may terminate gracefully by stopping accepting new requests but finishing responding to existing requests. After a job has been stopped, you may not `backgroundJob.run()` it again (calling `backgroundJob.run()` has no effect).
+ *
+ * **Example**
  *
  * ```javascript
+ * import * as utilities from "@radically-straightforward/utilities";
+ * import * as node from "@radically-straightforward/node";
+ *
+ * const backgroundJob = utilities.backgroundJob(
+ *   { interval: 3 * 1000 },
+ *   async () => {
+ *     console.log("backgroundJob(): Running background job...");
+ *     await utilities.sleep(3 * 1000);
+ *     console.log("backgroundJob(): ...finished running background job.");
+ *   },
+ * );
+ * console.log(
+ *   "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+ * );
+ * process.on("SIGTSTP", () => {
+ *   backgroundJob.run();
+ * });
+ * await node.shouldTerminate();
+ * backgroundJob.stop();
+ * ```
+ */
+export function backgroundJob({ interval, intervalVariance = 0.1, }, job) {
+    let state = "initial";
+    let timeout = undefined;
+    async function run() {
+        state = "running";
+        await job();
+        if (state === "running" || state === "runningAndMarkedForRerun") {
+            timeout = setTimeout(run, state === "runningAndMarkedForRerun"
+                ? 0
+                : interval + interval * intervalVariance * Math.random());
+            state = "sleeping";
+        }
+    }
+    run();
+    return {
+        run: () => {
+            switch (state) {
+                case "sleeping":
+                    clearTimeout(timeout);
+                    run();
+                    break;
+                case "running":
+                    state = "runningAndMarkedForRerun";
+                    break;
+            }
+        },
+        stop: () => {
+            if (state === "sleeping")
+                clearTimeout(timeout);
+            state = "stopped";
+        },
+    };
+}
+/**
+ * A promisified version of `setTimeout()`. It doesn’t offer a way to `clearTimeout()`. Useful in the browser—in Node.js you’re better served by [`timersPromises.setTimeout()`](https://nodejs.org/dist/latest-v21.x/docs/api/timers.html#timerspromisessettimeoutdelay-value-options).
+ */
+export function sleep(duration) {
+    return new Promise((resolve) => setTimeout(resolve, duration));
+}
+/**
+ * A fast random string generator. The generated strings are 10 or 11 characters in length. The generated strings include the characters `[0-9a-z]`. The generated strings are **not** cryptographically secure—if you need that, then use [`crypto-random-string`](https://npm.im/crypto-random-string).
+ */
+export function randomString() {
+    return Math.random().toString(36).slice(2);
+}
+/**
+ * [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:
+ *
+ * ```typescript
  * import { intern as $ } from "@radically-straightforward/utilities";
  *
  * [1] === [1]; // => false
  * $([1]) === $([1]); // => true
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<number[], number>();
  *   map.set([1], 1);
  *   map.set([1], 2);
  *   map.size; // => 2
@@ -16,7 +108,7 @@
  * }
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<utilities.Intern<number[]>, number>();
  *   map.set($([1]), 1);
  *   map.set($([1]), 2);
  *   map.size; // => 1
@@ -24,7 +116,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -32,7 +124,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -50,7 +142,9 @@
  *
  * > **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
+ * > **Note:** Interned objects do not preserve the order of the attributes: `$({ a: 1, b: 2 }) === $({ b: 2, a: 1 })`.
+ *
+ * > **Note:** The pool of interned values is available as `intern.pool`. The interned values are kept with `WeakRef`s to allow them to be garbage collected when they aren’t referenced anywhere else anymore. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
  *
  * **Related Work**
  *
@@ -107,7 +201,7 @@ export function intern(value) {
                 throw new Error(`Failed to intern value.`);
             })();
     const keys = Object.keys(value);
-    for (const internWeakRef of intern.pools[type].values()) {
+    for (const internWeakRef of intern.pool[type].values()) {
         const internValue = internWeakRef.deref();
         if (internValue === undefined ||
             keys.length !== Object.keys(internValue).length)
@@ -125,111 +219,21 @@ export function intern(value) {
             "undefined",
         ].includes(typeof innerValue) ||
             innerValue === null ||
-            innerValue[intern.interned] === true))
+            innerValue[internSymbol] === true))
             throw new Error(`Failed to intern value because of non-interned inner value.`);
     const key = Symbol();
-    value[intern.interned] = true;
+    value[internSymbol] = true;
     Object.freeze(value);
-    intern.pools[type].set(key, new WeakRef(value));
+    intern.pool[type].set(key, new WeakRef(value));
     intern.finalizationRegistry.register(value, { type, key });
     return value;
 }
-intern.interned = Symbol("interned");
-intern.pools = {
+export const internSymbol = Symbol("intern");
+intern.pool = {
     tuple: new Map(),
     record: new Map(),
 };
 intern.finalizationRegistry = new FinalizationRegistry(({ type, key }) => {
-    intern.pools[type].delete(key);
+    intern.pool[type].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 CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.mjs","sourceRoot":"","sources":["../source/index.mts"],"names":[],"mappings":"AAAA~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG~~;AACH,MAAM,UAAU,MAAM,~~CACpB~~,KAAQ;~~IAER~~,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAC/B,CAAC,CAAC,OAAO;QACT,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAC3C,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,CAAC,GAAG,EAAE;gBACJ,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC7C,CAAC,CAAC,EAAE,CAAC;IACX,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,KAAK,MAAM,aAAa,IAAI,MAAM,CAAC,~~KAAK~~,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;~~QACxD~~,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,EAAE,CAAC;QAC1C,IACE,WAAW,KAAK,SAAS;YACzB,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM;YAE/C,SAAS;QACX,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAE,KAAa,CAAC,GAAG,CAAC,~~KAAK~~,~~WAAW~~,CAAC,GAAG,CAAC,CAAC;~~YAC/D~~,OAAO,~~WAAW~~,CAAC;~~IACvB~~,CAAC;IACD,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;QAC3C,IACE,CAAC,CACC;YACE,QAAQ;YACR,QAAQ;YACR,QAAQ;YACR,SAAS;YACT,QAAQ;YACR,WAAW;SACZ,CAAC,QAAQ,CAAC,OAAO,UAAU,CAAC;YAC7B,UAAU,KAAK,IAAI;YAClB,UAAkB,CAAC,~~MAAM~~,CAAC,~~QAAQ,CAAC,~~KAAK,IAAI,~~CAC9C~~;YAED,MAAM,IAAI,KAAK,CACb,6DAA6D,CAC9D,CAAC;IACN,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACpB,KAAa,CAAC,~~MAAM~~,CAAC,~~QAAQ,CAAC,~~GAAG,IAAI,CAAC;~~IACvC~~,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrB,MAAM,CAAC,~~KAAK~~,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,~~KAAK~~,CAAC,CAAC,CAAC;~~IAChD~~,MAAM,CAAC,oBAAoB,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3D,OAAO,~~KAAK~~,CAAC;~~AACf~~,CAAC;AAED,MAAM,CAAC,~~QAAQ~~,GAAG,MAAM,CAAC,~~UAAU~~,CAAC,CAAC;~~AAErC~~,MAAM,CAAC,~~KAAK~~,GAAG;~~IACb~~,KAAK,EAAE,IAAI,GAAG,~~EAAwB~~;~~IACtC~~,MAAM,EAAE,IAAI,GAAG,~~EAAwB~~;~~CACxC~~,CAAC;AAEF,MAAM,CAAC,oBAAoB,GAAG,IAAI,oBAAoB,CAGnD,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE;IACnB,MAAM,CAAC,~~KAAK~~,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;~~AACjC~~,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"}
1	+ {"version":3,"file":"index.mjs","sourceRoot":"","sources":["../source/index.mts"],"names":[],"mappings":"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"}

package/build/index.test.mjs CHANGED Viewed

@@ -1,10 +1,42 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import * as node from "@radically-straightforward/node";
+import * as utilities from "./index.mjs";
 import { intern as $ } from "./index.mjs";
+test("backgroundJob()", {
+    ...(!process.stdin.isTTY
+        ? {
+            skip: "Run interactive test with ‘node ./build/index.test.mjs’.",
+        }
+        : {}),
+}, async () => {
+    const backgroundJob = utilities.backgroundJob({ interval: 3 * 1000 }, async () => {
+        console.log("backgroundJob(): Running background job...");
+        await utilities.sleep(3 * 1000);
+        console.log("backgroundJob(): ...finished running background job.");
+    });
+    console.log("backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...");
+    process.on("SIGTSTP", () => {
+        backgroundJob.run();
+    });
+    await node.shouldTerminate();
+    backgroundJob.stop();
+});
+test("sleep()", async () => {
+    const before = Date.now();
+    await utilities.sleep(1000);
+    assert(Date.now() - before >= 1000);
+});
+test("randomString()", () => {
+    const randomString = utilities.randomString();
+    assert(10 <= randomString.length && randomString.length <= 11);
+    assert.match(randomString, /^[0-9a-z]+$/);
+});
 test("intern()", () => {
-    // @ts-ignore
+    // @ts-expect-error
     assert(([1] === [1]) === false);
     assert($([1]) === $([1]));
+    assert($({ a: 1, b: 2 }) === $({ b: 2, a: 1 }));
     assert($([1]) !== $([2]));
     {
         const map = new Map();
@@ -35,34 +67,13 @@ test("intern()", () => {
         assert(set.has($([1])));
     }
     assert.throws(() => {
+        // @ts-expect-error
         $([1, {}]);
     });
     assert($([1, $({})]) === $([1, $({})]));
     assert.throws(() => {
+        // @ts-expect-error
         $([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 CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.test.mjs","sourceRoot":"","sources":["../source/index.test.mts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;~~AAExC~~,OAAO,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,aAAa,CAAC;AAE1C,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE;IACpB,~~aAAa~~;~~IACb~~,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;IAChC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1B,CAAC;QACC,MAAM,GAAG,GAAG,IAAI,GAAG,~~EAAE~~,CAAC;~~QACtB~~,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAChB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAChB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACxC,CAAC;IAED,CAAC;QACC,MAAM,GAAG,GAAG,IAAI,GAAG,~~EAAE~~,CAAC;~~QACtB~~,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACnB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACnB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC;IAED,CAAC;QACC,MAAM,GAAG,GAAG,IAAI,GAAG,~~EAAE~~,CAAC;~~QACtB~~,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACb,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,CAAC;QACC,MAAM,GAAG,GAAG,IAAI,GAAG,~~EAAE~~,CAAC;~~QACtB~~,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE;QACjB,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACb,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAExC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE;QACjB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ;AACR,uBAAuB;AACvB,MAAM;AACN,+BAA+B;AAC/B,YAAY;AACZ,8EAA8E;AAC9E,YAAY;AACZ,eAAe;AACf,OAAO;AACP,kBAAkB;AAClB,+EAA+E;AAC/E,mEAAmE;AACnE,UAAU;AACV,oCAAoC;AACpC,6BAA6B;AAC7B,UAAU;AACV,mBAAmB;AACnB,0FAA0F;AAC1F,SAAS;AACT,oCAAoC;AACpC,4BAA4B;AAC5B,OAAO;AACP,KAAK"}
1	+ {"version":3,"file":"index.test.mjs","sourceRoot":"","sources":["../source/index.test.mts"],"names":[],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@radically-straightforward/utilities",
-  "version": "0.0.2",
+  "version": "1.0.0",
   "description": "🛠️ Utilities for Node.js and the browser",
   "keywords": [
     "node",
@@ -29,6 +29,7 @@
   },
   "devDependencies": {
     "@radically-straightforward/documentation": "^1.0.1",
+    "@radically-straightforward/node": "^2.0.1",
     "@radically-straightforward/tsconfig": "^1.0.0",
     "@types/node": "^20.10.6",
     "prettier": "^3.1.1",

package/source/index.mts CHANGED Viewed

@@ -1,14 +1,140 @@
 /**
- * [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:
+ * Start a background job that runs every `interval`.
+ *
+ * This is different from `setInterval()` in the following ways:
+ *
+ * 1. The interval counts **between** jobs, so slow background jobs don’t get called concurrently:
+ *
+ *    ```
+ *    setInterval()
+ *    | SLOW BACKGROUND JOB |
+ *    | INTERVAL | SLOW BACKGROUND JOB |
+ *               | INTERVAL | ...
+ *
+ *    backgroundJob()
+ *    | SLOW BACKGROUND JOB | INTERVAL | SLOW BACKGROUND JOB | INTERVAL | ...
+ *    ```
+ *
+ * 2. We introduce a random `intervalVariance` to avoid many background jobs from starting at the same time and overloading the machine.
+ *
+ * 3. You may use `backgroundJob.run()` to force the background job to run right away. If the background job is already running, calling `backgroundJob.run()` schedules it to run again as soon as possible (not waiting the interval).
+ *
+ * 4. You may use `backgroundJob.stop()` to stop the background job. If the background job is running, it will finish but it will not be scheduled to run again. This is similar to how an HTTP server may terminate gracefully by stopping accepting new requests but finishing responding to existing requests. After a job has been stopped, you may not `backgroundJob.run()` it again (calling `backgroundJob.run()` has no effect).
+ *
+ * **Example**
  *
  * ```javascript
+ * import * as utilities from "@radically-straightforward/utilities";
+ * import * as node from "@radically-straightforward/node";
+ *
+ * const backgroundJob = utilities.backgroundJob(
+ *   { interval: 3 * 1000 },
+ *   async () => {
+ *     console.log("backgroundJob(): Running background job...");
+ *     await utilities.sleep(3 * 1000);
+ *     console.log("backgroundJob(): ...finished running background job.");
+ *   },
+ * );
+ * console.log(
+ *   "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+ * );
+ * process.on("SIGTSTP", () => {
+ *   backgroundJob.run();
+ * });
+ * await node.shouldTerminate();
+ * backgroundJob.stop();
+ * ```
+ */
+export function backgroundJob(
+  {
+    interval,
+    intervalVariance = 0.1,
+  }: { interval: number; intervalVariance?: number },
+  job: () => void | Promise<void>,
+): { run: () => void; stop: () => void } {
+  let state:
+    | "initial"
+    | "running"
+    | "runningAndMarkedForRerun"
+    | "sleeping"
+    | "stopped" = "initial";
+  let timeout: any = undefined;
+  async function run() {
+    state = "running";
+    await job();
+    if (state === "running" || state === "runningAndMarkedForRerun") {
+      timeout = setTimeout(
+        run,
+        (state as any) === "runningAndMarkedForRerun"
+          ? 0
+          : interval + interval * intervalVariance * Math.random(),
+      );
+      state = "sleeping";
+    }
+  }
+  run();
+  return {
+    run: () => {
+      switch (state) {
+        case "sleeping":
+          clearTimeout(timeout);
+          run();
+          break;
+        case "running":
+          state = "runningAndMarkedForRerun";
+          break;
+      }
+    },
+    stop: () => {
+      if (state === "sleeping") clearTimeout(timeout);
+      state = "stopped";
+    },
+  };
+}
+/**
+ * A promisified version of `setTimeout()`. It doesn’t offer a way to `clearTimeout()`. Useful in the browser—in Node.js you’re better served by [`timersPromises.setTimeout()`](https://nodejs.org/dist/latest-v21.x/docs/api/timers.html#timerspromisessettimeoutdelay-value-options).
+ */
+export function sleep(duration: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, duration));
+}
+/**
+ * A fast random string generator. The generated strings are 10 or 11 characters in length. The generated strings include the characters `[0-9a-z]`. The generated strings are **not** cryptographically secure—if you need that, then use [`crypto-random-string`](https://npm.im/crypto-random-string).
+ */
+export function randomString(): string {
+  return Math.random().toString(36).slice(2);
+}
+/**
+ * Utility type for `intern()`.
+ */
+export type Intern<Type> = Readonly<Type & { [internSymbol]: true }>;
+/**
+ * Utility type for `intern()`.
+ */
+export type InternInnerValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | symbol
+  | undefined
+  | null
+  | Intern<unknown>;
+/**
+ * [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:
+ *
+ * ```typescript
  * import { intern as $ } from "@radically-straightforward/utilities";
  *
  * [1] === [1]; // => false
  * $([1]) === $([1]); // => true
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<number[], number>();
  *   map.set([1], 1);
  *   map.set([1], 2);
  *   map.size; // => 2
@@ -16,7 +142,7 @@
  * }
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<utilities.Intern<number[]>, number>();
  *   map.set($([1]), 1);
  *   map.set($([1]), 2);
  *   map.size; // => 1
@@ -24,7 +150,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -32,7 +158,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -50,7 +176,9 @@
  *
  * > **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
+ * > **Note:** Interned objects do not preserve the order of the attributes: `$({ a: 1, b: 2 }) === $({ b: 2, a: 1 })`.
+ *
+ * > **Note:** The pool of interned values is available as `intern.pool`. The interned values are kept with `WeakRef`s to allow them to be garbage collected when they aren’t referenced anywhere else anymore. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned values that have been garbage collected.
  *
  * **Related Work**
  *
@@ -98,9 +226,9 @@
  * - <https://twitter.com/swannodette/status/1067962983924539392>
  * - <https://gist.github.com/modernserf/c000e62d40f678cf395e3f360b9b0e43>
  */
-export function intern<T extends Array<unknown> | { [key: string]: unknown }>(
-  value: T,
-): T {
+export function intern<
+  T extends Array<InternInnerValue> | { [key: string]: InternInnerValue },
+>(value: T): Intern<T> {
   const type = Array.isArray(value)
     ? "tuple"
     : typeof value === "object" && value !== null
@@ -109,15 +237,15 @@ export function intern<T extends Array<unknown> | { [key: string]: unknown }>(
           throw new Error(`Failed to intern value.`);
         })();
   const keys = Object.keys(value);
-  for (const internWeakRef of intern.pools[type].values()) {
+  for (const internWeakRef of intern.pool[type].values()) {
     const internValue = internWeakRef.deref();
     if (
       internValue === undefined ||
       keys.length !== Object.keys(internValue).length
     )
       continue;
-    if (keys.every((key) => (value as any)[key] === internValue[key]))
-      return internValue;
+    if (keys.every((key) => (value as any)[key] === (internValue as any)[key]))
+      return internValue as any;
   }
   for (const innerValue of Object.values(value))
     if (
@@ -131,121 +259,33 @@ export function intern<T extends Array<unknown> | { [key: string]: unknown }>(
           "undefined",
         ].includes(typeof innerValue) ||
         innerValue === null ||
-        (innerValue as any)[intern.interned] === true
+        (innerValue as any)[internSymbol] === true
       )
     )
       throw new Error(
         `Failed to intern value because of non-interned inner value.`,
       );
   const key = Symbol();
-  (value as any)[intern.interned] = true;
+  (value as any)[internSymbol] = true;
   Object.freeze(value);
-  intern.pools[type].set(key, new WeakRef(value));
+  intern.pool[type].set(key, new WeakRef(value as any));
   intern.finalizationRegistry.register(value, { type, key });
-  return value;
+  return value as any;
 }
-intern.interned = Symbol("interned");
+export const internSymbol = Symbol("intern");
-intern.pools = {
-  tuple: new Map<Symbol, WeakRef<any>>(),
-  record: new Map<Symbol, WeakRef<any>>(),
+intern.pool = {
+  tuple: new Map<Symbol, WeakRef<Intern<InternInnerValue[]>>>(),
+  record: new Map<
+    Symbol,
+    WeakRef<Intern<{ [key: string]: InternInnerValue }>>
+  >(),
 };
 intern.finalizationRegistry = new FinalizationRegistry<{
   type: "tuple" | "record";
   key: Symbol;
 }>(({ type, key }) => {
-  intern.pools[type].delete(key);
+  intern.pool[type].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 CHANGED Viewed

@@ -1,16 +1,60 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import * as node from "@radically-straightforward/node";
 import * as utilities from "./index.mjs";
 import { intern as $ } from "./index.mjs";
+test(
+  "backgroundJob()",
+  {
+    ...(!process.stdin.isTTY
+      ? {
+          skip: "Run interactive test with ‘node ./build/index.test.mjs’.",
+        }
+      : {}),
+  },
+  async () => {
+    const backgroundJob = utilities.backgroundJob(
+      { interval: 3 * 1000 },
+      async () => {
+        console.log("backgroundJob(): Running background job...");
+        await utilities.sleep(3 * 1000);
+        console.log("backgroundJob(): ...finished running background job.");
+      },
+    );
+    console.log(
+      "backgroundJob(): Press ⌃Z to force background job to run and ⌃C to continue...",
+    );
+    process.on("SIGTSTP", () => {
+      backgroundJob.run();
+    });
+    await node.shouldTerminate();
+    backgroundJob.stop();
+  },
+);
+test("sleep()", async () => {
+  const before = Date.now();
+  await utilities.sleep(1000);
+  assert(Date.now() - before >= 1000);
+});
+test("randomString()", () => {
+  const randomString = utilities.randomString();
+  assert(10 <= randomString.length && randomString.length <= 11);
+  assert.match(randomString, /^[0-9a-z]+$/);
+});
 test("intern()", () => {
-  // @ts-ignore
+  // @ts-expect-error
   assert(([1] === [1]) === false);
   assert($([1]) === $([1]));
+  assert($({ a: 1, b: 2 }) === $({ b: 2, a: 1 }));
   assert($([1]) !== $([2]));
   {
-    const map = new Map();
+    const map = new Map<number[], number>();
     map.set([1], 1);
     map.set([1], 2);
     assert.equal(map.size, 2);
@@ -18,7 +62,7 @@ test("intern()", () => {
   }
   {
-    const map = new Map();
+    const map = new Map<utilities.Intern<number[]>, number>();
     map.set($([1]), 1);
     map.set($([1]), 2);
     assert.equal(map.size, 1);
@@ -26,7 +70,7 @@ test("intern()", () => {
   }
   {
-    const set = new Set();
+    const set = new Set<number[]>();
     set.add([1]);
     set.add([1]);
     assert.equal(set.size, 2);
@@ -34,7 +78,7 @@ test("intern()", () => {
   }
   {
-    const set = new Set();
+    const set = new Set<utilities.Intern<number[]>>();
     set.add($([1]));
     set.add($([1]));
     assert.equal(set.size, 1);
@@ -42,35 +86,13 @@ test("intern()", () => {
   }
   assert.throws(() => {
+    // @ts-expect-error
     $([1, {}]);
   });
   assert($([1, $({})]) === $([1, $({})]));
   assert.throws(() => {
+    // @ts-expect-error
     $([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();
-//   },
-// );