@radically-straightforward/utilities 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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.

package/README.md

@@ -11,33 +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
-    | 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 +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
@@ -53,7 +81,7 @@ $([1]) === $([1]); // => true
 }
 
 {
-  const set = new Set();
+  const set = new Set<number[]>();
   set.add([1]);
   set.add([1]);
   set.size; // => 2
@@ -61,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
@@ -79,6 +107,8 @@ $([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:** 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**

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
@@ -50,6 +60,8 @@
  *
  * > **Note:** Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.
  *
+ * > **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**
@@ -98,18 +110,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

@@ -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"}
+{"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,14 +1,14 @@
 /**
  * [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 +16,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 +24,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -32,7 +32,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -50,6 +50,8 @@
  *
  * > **Note:** Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.
  *
+ * > **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**
@@ -107,7 +109,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,22 +127,22 @@ 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);
 });
 /*
 

package/build/index.mjs.map

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

package/build/index.test.mjs

@@ -2,9 +2,10 @@ 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();
@@ -35,10 +36,12 @@ test("intern()", () => {
         assert(set.has($([1])));
     }
     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":"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"}
+{"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.2",
+  "version": "0.0.3",
   "description": "🛠️ Utilities for Node.js and the browser",
   "keywords": [
     "node",

package/source/index.mts

@@ -1,14 +1,32 @@
+/**
+ * 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 +34,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 +42,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<number[]>();
  *   set.add([1]);
  *   set.add([1]);
  *   set.size; // => 2
@@ -32,7 +50,7 @@
  * }
  *
  * {
- *   const set = new Set();
+ *   const set = new Set<utilities.Intern<number[]>>();
  *   set.add($([1]));
  *   set.add($([1]));
  *   set.size; // => 1
@@ -50,6 +68,8 @@
  *
  * > **Note:** Interning a value is a costly operation which grows more expensive as you intern more values. Only intern values when really necessary.
  *
+ * > **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**
@@ -98,9 +118,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 +129,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,32 +151,35 @@ 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);
 });
 
 /*

package/source/index.test.mts

@@ -4,13 +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);
@@ -18,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);
@@ -26,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);
@@ -34,7 +36,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,11 +44,13 @@ test("intern()", () => {
   }
 
   assert.throws(() => {
+    // @ts-expect-error
     $([1, {}]);
   });
   assert($([1, $({})]) === $([1, $({})]));
 
   assert.throws(() => {
+    // @ts-expect-error
     $([1])[0] = 2;
   });
 });