React support (#6)

* Add explicit support for React-specific objects

* Semver bump

* Remove obsolete commented code

Author: marcusdarmstrong

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.2.0] - 2024-04-29
+
+- MINOR: Add explicit support for React-specific objects in `readOnly`
+
 ## [2.1.0] - 2024-04-24
 
 - MINOR: Accept inline non-function wrapped parameters to `readOnly`

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifetimes/eslint-plugin",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": "Marcus Armstrong <marcusdarmstrong@gmail.com>",
   "homepage": "https://github.com/marcusdarmstrong/lifetimes",
   "repository": "github:marcusdarmstrong/lifetimes",

packages/eslint-plugin/package.json

@@ -1,6 +1,8 @@
 import assert from "node:assert";
 import { test } from "node:test";
 
+import { lazy, createElement } from "react";
+
 import {
   readOnly,
   requestLocal,
@@ -118,6 +120,41 @@ test("readOnly", async (t) => {
     }, "cannot be modified");
   });
 
+  await t.test("ignores lazy react components", () => {
+    function LazyComponent() {
+      return createElement("span");
+    }
+
+    const lazyRenderable = readOnly(() =>
+      lazy(() => Promise.resolve({ default: LazyComponent })),
+    );
+
+    // Prototype is the only TS-writable property defined on this type.
+    assert(
+      (lazyRenderable.prototype = Function),
+      "lazy components can be written",
+    );
+
+    // This is a typescript assertion.
+    createElement(lazyRenderable);
+  });
+
+  await t.test("ignores react elements", () => {
+    const elm = readOnly(createElement("div"));
+    // @ts-expect-error: React internally mutates this property. We need to assert that we haven't prevented it from doing so.
+    assert((elm._store.foo = "bar"), "react elements can be written");
+
+    function Component() {
+      return "hello world";
+    }
+
+    // These are typescript assertions.
+    createElement(readOnly(() => Component));
+
+    // @ts-expect-error: Components, as callables, need to be passed to `readOnly` with a closure wrapper.
+    readOnly<typeof Component>(Component);
+  });
+
   await t.test("arrays", () => {
     const arr = readOnly(() => [1, 2, 3, 4, 5, [6, 7]] as const);
     assert(arr[0], "can be read");

packages/lifetimes/lifetimes.test.ts

@@ -1,6 +1,8 @@
 import type { AsyncLocalStorage } from "node:async_hooks";
 import { createScope } from "#scope";
 
+import type { ReactElement } from "react";
+
 const MUTABLE_SET_METHODS = new Set<string | symbol>([
   "add",
   "delete",
@@ -26,13 +28,22 @@ const MUTABLE_DATE_METHODS = new Set<string | symbol>([
   "setYear",
 ]);
 
-function immutableProxy<T>(value: T): T {
+function isReactObject(value: unknown): boolean {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    "$$typeof" in value
+  );
+}
+
+function immutableProxy<T>(value: T): Immutable<T> {
   if (
+    isReactObject(value) ||
     (typeof value !== "object" && typeof value !== "function") ||
     value === null
   ) {
     // Primitive values are implicitly immutable.
-    return value;
+    return value as Immutable<T>;
   }
 
   if (value instanceof Promise) {
@@ -41,13 +52,7 @@ function immutableProxy<T>(value: T): T {
     );
   }
 
-  // This effectively prevents mutation of arrays and objects.
   Object.preventExtensions(value);
-  Reflect.ownKeys(value).forEach((property) => {
-    Object.defineProperty(value, property, {
-      writable: false,
-    });
-  });
 
   return new Proxy(value, {
     get(target, property, receiver) {
@@ -69,30 +74,28 @@ function immutableProxy<T>(value: T): T {
           : returnValue,
       );
     },
-  });
+  }) as Immutable<T>;
 }
 
-function makeImmutable<T>(value: T): T {
+function makeImmutable<T>(value: T): Immutable<T> {
   if (
     value instanceof Promise ||
     value instanceof Set ||
     value instanceof Map ||
-    value instanceof Date
+    value instanceof Date ||
+    isReactObject(value)
   ) {
     return immutableProxy(value);
   }
 
   if (typeof value === "object" && value !== null) {
-    Object.preventExtensions(value);
     Reflect.ownKeys(value).forEach((property) => {
-      Object.defineProperty(value, property, {
-        writable: false,
-      });
       makeImmutable(value[property as keyof typeof value]);
     });
+    Object.freeze(value);
   }
 
-  return value;
+  return value as Immutable<T>;
 }
 
 export type ReadonlyDate = Readonly<
@@ -124,24 +127,26 @@ export type Immutable<T> = T extends (...args: infer Ks) => infer V
       ? ReadonlySet<Immutable<S>>
       : T extends Map<infer K, infer V>
         ? ReadonlyMap<Immutable<K>, Immutable<V>>
-        : {
-            readonly [K in keyof T]: Immutable<T[K]>;
-          };
-
-function isCallable(value: unknown): value is (...args: unknown[]) => unknown {
+        : T extends ReactElement<unknown>
+          ? T
+          : {
+              readonly [K in keyof T]: Immutable<T[K]>;
+            };
+
+function isCallable<T>(
+  value: ReadOnlyInitializer<T>,
+): value is ClosureInitializer<T> {
   return typeof value === "function";
 }
 
-export function readOnly<T>(
-  initializer: () => T extends Promise<unknown> ? never : T,
-): Immutable<T>;
-export function readOnly<T>(
-  initializer: T extends (...args: unknown[]) => unknown
+type ClosureInitializer<T> = () => T extends Promise<unknown> ? never : T;
+type InlineInitializer<T> = T extends (...args: unknown[]) => unknown
+  ? never
+  : T extends Promise<unknown>
     ? never
-    : T extends Promise<unknown>
-      ? never
-      : T,
-): Immutable<T>;
+    : T;
+
+type ReadOnlyInitializer<T> = ClosureInitializer<T> | InlineInitializer<T>;
 
 /**
  * Mark the lifetime of a provided block of code as "forever" with safety
@@ -151,7 +156,7 @@ export function readOnly<T>(
  * @return The provided callback's return value, frozen, and wrapped in a
  *  readOnly-enforcing Proxy.
  */
-export function readOnly<T>(initializer: T | (() => T)): T {
+export function readOnly<T>(initializer: ReadOnlyInitializer<T>): Immutable<T> {
   if (isCallable(initializer)) {
     return makeImmutable(initializer());
   }

packages/lifetimes/lifetimes.ts

@@ -1,6 +1,6 @@
 {
   "name": "lifetimes",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A utility for explicit specification and enforcement of module scope variable lifetimes",
   "license": "MIT",
   "author": "Marcus Armstrong <marcusdarmstrong@gmail.com>",
@@ -43,11 +43,13 @@
     "@tsconfig/strictest": "2.0.3",
     "@tsconfig/node16": "16.1.1",
     "@types/node": "20.11.24",
+    "@types/react": "18.2.79",
     "@typescript-eslint/eslint-plugin": "7.1.1",
     "@typescript-eslint/parser": "7.1.1",
     "eslint": "8.57.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-prettier": "5.1.3",
+    "react": "18.2.0",
     "rollup": "4.12.0",
     "typescript": "5.3.3"
   },

packages/lifetimes/package.json

@@ -44,5 +44,5 @@ export default [{
   output: output("test"),
   plugins: plugins("node"),
   // plugin-node-resolve uses an out-of-date builtins list.
-  external: ["node:test"],
+  external: ["node:test", "react"],
 }];