#15215 Rename 'shredder' API to something closer to garbage collection

Author: eyalroth

packages/jest-circus/src/state.ts

@@ -6,7 +6,7 @@
  */
 
 import type {Circus, Global} from '@jest/types';
-import {setGlobal, setNotShreddable} from 'jest-util';
+import {protectProperties, setGlobal} from 'jest-util';
 import eventHandler from './eventHandler';
 import formatNodeAssertErrors from './formatNodeAssertErrors';
 import {EVENT_HANDLERS, STATE_SYM} from './types';
@@ -44,7 +44,7 @@ export const getState = (): Circus.State =>
   (globalThis as Global.Global)[STATE_SYM] as Circus.State;
 export const setState = (state: Circus.State): Circus.State => {
   setGlobal(globalThis, STATE_SYM, state);
-  setNotShreddable(state, [
+  protectProperties(state, [
     'hasFocusedTests',
     'hasStarted',
     'includeTestLocationInResult',

packages/jest-environment-node/src/index.ts

@@ -15,10 +15,10 @@ import {LegacyFakeTimers, ModernFakeTimers} from '@jest/fake-timers';
 import type {Global} from '@jest/types';
 import {ModuleMocker} from 'jest-mock';
 import {
+  canDeleteProperties,
+  deleteProperties,
   installCommonGlobals,
-  isShreddable,
-  setNotShreddable,
-  shred,
+  protectProperties,
 } from 'jest-util';
 
 type Timer = {
@@ -235,8 +235,8 @@ export const TestEnvironment = NodeEnvironment;
  * Creates a new empty global object and wraps it with a {@link Proxy}.
  *
  * The purpose is to register any property set on the global object,
- * and {@link #shred} them at environment teardown, to clean up memory and
- * prevent leaks.
+ * and {@link #deleteProperties} on them at environment teardown,
+ * to clean up memory and prevent leaks.
  */
 class GlobalProxy implements ProxyHandler<typeof globalThis> {
   private global: typeof globalThis = Object.create(
@@ -257,16 +257,16 @@ class GlobalProxy implements ProxyHandler<typeof globalThis> {
 
   /**
    * Marks that the environment setup has completed, and properties set on
-   * the global object from now on should be shredded at teardown.
+   * the global object from now on should be deleted at teardown.
    */
   envSetupCompleted(): void {
     this.isEnvSetup = true;
   }
 
   /**
-   * Shreds any property that was set on the global object, except for:
+   * Deletes any property that was set on the global object, except for:
    * 1. Properties that were set before {@link #envSetupCompleted} was invoked.
-   * 2. Properties protected by {@link #setNotShreddable}.
+   * 2. Properties protected by {@link #protectProperties}.
    */
   clear(): void {
     for (const {property, value} of [
@@ -278,10 +278,10 @@ class GlobalProxy implements ProxyHandler<typeof globalThis> {
     ]) {
       /*
        * react-native invoke its custom `performance` property after env teardown.
-       * its setup file should use `setNotShreddable` to prevent this.
+       * its setup file should use `protectProperties` to prevent this.
        */
       if (property !== 'performance') {
-        shred(value);
+        deleteProperties(value);
       }
     }
     this.propertyToValue.clear();
@@ -332,8 +332,8 @@ class GlobalProxy implements ProxyHandler<typeof globalThis> {
   private register(property: string | symbol, value: unknown) {
     const currentValue = this.propertyToValue.get(property);
     if (value !== currentValue) {
-      if (!this.isEnvSetup && isShreddable(value)) {
-        setNotShreddable(value);
+      if (!this.isEnvSetup && canDeleteProperties(value)) {
+        protectProperties(value);
       }
       if (currentValue) {
         this.leftovers.push({property, value: currentValue});

packages/jest-repl/src/cli/runtime-cli.ts

@@ -99,9 +99,9 @@ export async function run(
       },
       {console: customConsole, docblockPragmas: {}, testPath: filePath},
     );
-    setGlobal(environment.global, 'console', customConsole, false);
-    setGlobal(environment.global, 'jestProjectConfig', projectConfig, false);
-    setGlobal(environment.global, 'jestGlobalConfig', globalConfig, false);
+    setGlobal(environment.global, 'console', customConsole, 'retain');
+    setGlobal(environment.global, 'jestProjectConfig', projectConfig, 'retain');
+    setGlobal(environment.global, 'jestGlobalConfig', globalConfig, 'retain');
 
     const runtime = new Runtime(
       projectConfig,

packages/jest-runner/src/runTest.ts

@@ -184,7 +184,7 @@ async function runTestInternal(
     ? new LeakDetector(environment)
     : null;
 
-  setGlobal(environment.global, 'console', testConsole, false);
+  setGlobal(environment.global, 'console', testConsole, 'retain');
 
   const runtime = new Runtime(
     projectConfig,

packages/jest-util/src/shredder.ts renamed to packages/jest-util/src/garbage-collection-utils.ts

@@ -5,17 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const NO_SHRED_AFTER_TEARDOWN = Symbol.for('$$jest-no-shred');
+const PROTECT_PROPERTY = Symbol.for('$$jest-protect-from-deletion');
 
 /**
  * Deletes all the properties from the given value (if it's an object),
- * unless the value was protected via {@link #setNotShreddable}.
+ * unless the value was protected via {@link #protectProperties}.
  *
  * @param value the given value.
  */
-export function shred(value: unknown): void {
-  if (isShreddable(value)) {
-    const protectedProperties = Reflect.get(value, NO_SHRED_AFTER_TEARDOWN);
+export function deleteProperties(value: unknown): void {
+  if (canDeleteProperties(value)) {
+    const protectedProperties = Reflect.get(value, PROTECT_PROPERTY);
     if (!Array.isArray(protectedProperties) || protectedProperties.length > 0) {
       for (const key of Reflect.ownKeys(value)) {
         if (!protectedProperties?.includes(key)) {
@@ -27,28 +27,28 @@ export function shred(value: unknown): void {
 }
 
 /**
- * Protects the given value from being shredded by {@link #shred}.
+ * Protects the given value from being deleted by {@link #deleteProperties}.
  *
  * @param value The given value.
  * @param properties If the array contains any property,
  * then only these properties will not be deleted; otherwise if the array is empty,
  * all properties will not be deleted.
  */
-export function setNotShreddable<T extends object>(
+export function protectProperties<T extends object>(
   value: T,
   properties: Array<keyof T> = [],
 ): boolean {
-  if (isShreddable(value)) {
-    return Reflect.set(value, NO_SHRED_AFTER_TEARDOWN, properties);
+  if (canDeleteProperties(value)) {
+    return Reflect.set(value, PROTECT_PROPERTY, properties);
   }
   return false;
 }
 
 /**
- * Whether the given value is possible to be shredded.
+ * Whether the given value has properties that can be deleted (regardless of protection).
  *
  * @param value The given value.
  */
-export function isShreddable(value: unknown): value is object {
+export function canDeleteProperties(value: unknown): value is object {
   return value !== null && ['object', 'function'].includes(typeof value);
 }

packages/jest-util/src/index.ts

@@ -29,4 +29,8 @@ export {default as tryRealpath} from './tryRealpath';
 export {default as requireOrImportModule} from './requireOrImportModule';
 export {default as invariant} from './invariant';
 export {default as isNonNullable} from './isNonNullable';
-export {isShreddable, setNotShreddable, shred} from './shredder';
+export {
+  canDeleteProperties,
+  protectProperties,
+  deleteProperties,
+} from './garbage-collection-utils';

packages/jest-util/src/setGlobal.ts

@@ -6,16 +6,19 @@
  */
 
 import type {Global} from '@jest/types';
-import {isShreddable, setNotShreddable} from './shredder';
+import {
+  canDeleteProperties,
+  protectProperties,
+} from './garbage-collection-utils';
 
 export default function setGlobal(
   globalToMutate: typeof globalThis | Global.Global,
   key: string | symbol,
   value: unknown,
-  shredAfterTeardown = true,
+  afterTeardown: 'clean' | 'retain' = 'clean',
 ): void {
   Reflect.set(globalToMutate, key, value);
-  if (!shredAfterTeardown && isShreddable(value)) {
-    setNotShreddable(value);
+  if (afterTeardown === 'retain' && canDeleteProperties(value)) {
+    protectProperties(value);
   }
 }