@radically-straightforward/utilities 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -1 +1,13 @@
 # Changelog
+
+## 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.
+
+## 0.0.1 · 2024-01-04
+
+- Preliminary release with `intern()`.

package/README.md

@@ -11,27 +11,61 @@ $ 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 -->
 
+### `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 WeakKey>(value: T): T;
+export function intern<
+  T extends
+    | Array<InternInnerValue>
+    | {
+        [key: string]: InternInnerValue;
+      },
+>(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
@@ -39,7 +73,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
@@ -47,7 +81,7 @@ $([1]) === $([1]); // => true
 }
 
 {
-  const set = new Set();
+  const set = new Set<number[]>();
   set.add([1]);
   set.add([1]);
   set.size; // => 2
@@ -55,7 +89,7 @@ $([1]) === $([1]); // => true
 }
 
 {
-  const set = new Set();
+  const set = new Set<utilities.Intern<number[]>>();
   set.add($([1]));
   set.add($([1]));
   set.size; // => 1
@@ -65,23 +99,23 @@ $([1]) === $([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.
+> **Node:** Inner values must be either primitives or interned values themselves, for example, `$([1, $({})])` is valid, but `$([1, {}])` is not.
+
+> **Node:** Currently only arrays (tuples) and objects (records) may be interned. In the future we may support more types, for example, `Map`, `Set`, regular expressions, and so forth.
 
-> **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:** You must not mutate an interned value. Interned values are [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) to prevent mutation.
 
 > **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.
+> **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned 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.
+A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()`.
 
 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.
 
@@ -123,10 +157,4 @@ Similar to `collections-deep-equal` but either incomplete, or lacking type defin
 - <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

@@ -1,14 +1,24 @@
+/**
+ * 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:
  *
- * ```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
@@ -16,7 +26,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 +34,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -32,7 +42,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -42,23 +52,23 @@
  *
  * > **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.
+ * > **Node:** Inner values must be either primitives or interned values themselves, for example, `$([1, $({})])` is valid, but `$([1, {}])` is not.
+ *
+ * > **Node:** Currently only arrays (tuples) and objects (records) may be interned. In the future we may support more types, for example, `Map`, `Set`, regular expressions, and so forth.
  *
- * > **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:** You must not mutate an interned value. Interned values are [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) to prevent mutation.
  *
  * > **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.
+ * > **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned 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.
+ * A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()`.
  *
  * 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.
  *
@@ -99,17 +109,25 @@
  * - <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 function intern<T extends Array<InternInnerValue> | {
+    [key: string]: InternInnerValue;
+}>(value: T): Intern<T>;
 export declare namespace intern {
-    var isEqual: (value: any, other: any) => boolean;
-    var pool: Map<Symbol, WeakRef<any>>;
-    var finalizationRegistry: FinalizationRegistry<Symbol>;
+    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

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

@@ -1,16 +1,14 @@
-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
+ * ```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
@@ -18,7 +16,7 @@ import deepFreeze from "deep-freeze-es6";
  * }
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<utilities.Intern<number[]>, number>();
  *   map.set($([1]), 1);
  *   map.set($([1]), 2);
  *   map.size; // => 1
@@ -26,7 +24,7 @@ import deepFreeze from "deep-freeze-es6";
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -34,7 +32,7 @@ import deepFreeze from "deep-freeze-es6";
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -44,23 +42,23 @@ import deepFreeze from "deep-freeze-es6";
  *
  * > **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.
+ * > **Node:** Inner values must be either primitives or interned values themselves, for example, `$([1, $({})])` is valid, but `$([1, {}])` is not.
  *
- * > **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.
+ * > **Node:** Currently only arrays (tuples) and objects (records) may be interned. In the future we may support more types, for example, `Map`, `Set`, regular expressions, and so forth.
+ *
+ * > **Note:** You must not mutate an interned value. Interned values are [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) to prevent mutation.
  *
  * > **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.
+ * > **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned 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.
+ * A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()`.
  *
  * 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.
  *
@@ -101,29 +99,50 @@ import deepFreeze from "deep-freeze-es6";
  * - <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 type = Array.isArray(value)
+        ? "tuple"
+        : typeof value === "object" && value !== null
+            ? "record"
+            : (() => {
+                throw new Error(`Failed to intern value.`);
+            })();
+    const keys = Object.keys(value);
+    for (const internWeakRef of intern.pool[type].values()) {
         const internValue = internWeakRef.deref();
-        if (intern.isEqual(value, internValue))
+        if (internValue === undefined ||
+            keys.length !== Object.keys(internValue).length)
+            continue;
+        if (keys.every((key) => value[key] === internValue[key]))
             return internValue;
     }
+    for (const innerValue of Object.values(value))
+        if (!([
+            "string",
+            "number",
+            "bigint",
+            "boolean",
+            "symbol",
+            "undefined",
+        ].includes(typeof innerValue) ||
+            innerValue === null ||
+            innerValue[internSymbol] === true))
+            throw new Error(`Failed to intern value because of non-interned inner value.`);
     const key = Symbol();
-    deepFreeze(value);
-    intern.pool.set(key, new WeakRef(value));
-    intern.finalizationRegistry.register(value, key);
+    value[internSymbol] = true;
+    Object.freeze(value);
+    intern.pool[type].set(key, new WeakRef(value));
+    intern.finalizationRegistry.register(value, { type, key });
     return value;
 }
-intern.isEqual = lodash.isEqual;
-intern.pool = new Map();
-intern.finalizationRegistry = new FinalizationRegistry((key) => {
-    intern.pool.delete(key);
+export const internSymbol = Symbol("intern");
+intern.pool = {
+    tuple: new Map(),
+    record: new Map(),
+};
+intern.finalizationRegistry = new FinalizationRegistry(({ type, key }) => {
+    intern.pool[type].delete(key);
 });
 /*
 

package/build/index.mjs.map

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

package/build/index.test.mjs

@@ -2,9 +2,11 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { intern as $ } from "./index.mjs";
 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();
         map.set([1], 1);
@@ -33,8 +35,13 @@ test("intern()", () => {
         assert.equal(set.size, 1);
         assert(set.has($([1])));
     }
-    assert.notEqual($([1]), $([2]));
     assert.throws(() => {
+        // @ts-expect-error
+        $([1, {}]);
+    });
+    assert($([1, $({})]) === $([1, $({})]));
+    assert.throws(() => {
+        // @ts-expect-error
         $([1])[0] = 2;
     });
 });

package/build/index.test.mjs.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radically-straightforward/utilities",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "🛠️ Utilities for Node.js and the browser",
   "keywords": [
     "node",
@@ -27,14 +27,9 @@
     "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"

package/source/index.mts

@@ -1,17 +1,32 @@
-import lodash from "lodash";
-import deepFreeze from "deep-freeze-es6";
+/**
+ * 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:
  *
- * ```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
@@ -19,7 +34,7 @@ import deepFreeze from "deep-freeze-es6";
  * }
  *
  * {
- *   const map = new Map();
+ *   const map = new Map<utilities.Intern<number[]>, number>();
  *   map.set($([1]), 1);
  *   map.set($([1]), 2);
  *   map.size; // => 1
@@ -27,7 +42,7 @@ import deepFreeze from "deep-freeze-es6";
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -35,7 +50,7 @@ import deepFreeze from "deep-freeze-es6";
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -45,23 +60,23 @@ import deepFreeze from "deep-freeze-es6";
  *
  * > **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.
+ * > **Node:** Inner values must be either primitives or interned values themselves, for example, `$([1, $({})])` is valid, but `$([1, {}])` is not.
  *
- * > **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.
+ * > **Node:** Currently only arrays (tuples) and objects (records) may be interned. In the future we may support more types, for example, `Map`, `Set`, regular expressions, and so forth.
+ *
+ * > **Note:** You must not mutate an interned value. Interned values are [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) to prevent mutation.
  *
  * > **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.
+ * > **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`. There’s a `FinalizationRegistry` at `intern.finalizationRegistry` that cleans up interned 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.
+ * A proposal to include immutable objects (Records) and immutable arrays (Tuples) in JavaScript. This subsumes most of the need for `intern()`.
  *
  * 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.
  *
@@ -102,31 +117,69 @@ import deepFreeze from "deep-freeze-es6";
  * - <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()) {
+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
+      ? "record"
+      : (() => {
+          throw new Error(`Failed to intern value.`);
+        })();
+  const keys = Object.keys(value);
+  for (const internWeakRef of intern.pool[type].values()) {
     const internValue = internWeakRef.deref();
-    if (intern.isEqual(value, internValue)) return internValue;
+    if (
+      internValue === undefined ||
+      keys.length !== Object.keys(internValue).length
+    )
+      continue;
+    if (keys.every((key) => (value as any)[key] === (internValue as any)[key]))
+      return internValue as any;
   }
+  for (const innerValue of Object.values(value))
+    if (
+      !(
+        [
+          "string",
+          "number",
+          "bigint",
+          "boolean",
+          "symbol",
+          "undefined",
+        ].includes(typeof innerValue) ||
+        innerValue === null ||
+        (innerValue as any)[internSymbol] === true
+      )
+    )
+      throw new Error(
+        `Failed to intern value because of non-interned inner value.`,
+      );
   const key = Symbol();
-  deepFreeze(value);
-  intern.pool.set(key, new WeakRef(value));
-  intern.finalizationRegistry.register(value, key);
-  return value;
+  (value as any)[internSymbol] = true;
+  Object.freeze(value);
+  intern.pool[type].set(key, new WeakRef(value as any));
+  intern.finalizationRegistry.register(value, { type, key });
+  return value as any;
 }
 
-intern.isEqual = lodash.isEqual;
+export const internSymbol = Symbol("intern");
 
-intern.pool = 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<Symbol>((key) => {
-  intern.pool.delete(key);
+intern.finalizationRegistry = new FinalizationRegistry<{
+  type: "tuple" | "record";
+  key: Symbol;
+}>(({ type, key }) => {
+  intern.pool[type].delete(key);
 });
 
 /*

package/source/index.test.mts

@@ -4,12 +4,15 @@ import * as utilities from "./index.mjs";
 import { intern as $ } from "./index.mjs";
 
 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);
@@ -17,7 +20,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);
@@ -25,7 +28,7 @@ test("intern()", () => {
   }
 
   {
-    const set = new Set();
+    const set = new Set<number[]>();
     set.add([1]);
     set.add([1]);
     assert.equal(set.size, 2);
@@ -33,16 +36,21 @@ test("intern()", () => {
   }
 
   {
-    const set = new Set();
+    const set = new Set<utilities.Intern<number[]>>();
     set.add($([1]));
     set.add($([1]));
     assert.equal(set.size, 1);
     assert(set.has($([1])));
   }
 
-  assert.notEqual($([1]), $([2]));
+  assert.throws(() => {
+    // @ts-expect-error
+    $([1, {}]);
+  });
+  assert($([1, $({})]) === $([1, $({})]));
 
   assert.throws(() => {
+    // @ts-expect-error
     $([1])[0] = 2;
   });
 });