react-refresh 0.18.0: performReactRefresh

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify react-refresh.performReactRefresh in pkg:npm/react-refresh@0.18.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react-refresh@0.18.0
Demonstrate these symbols/APIs:
  - react-refresh.performReactRefresh
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:834e555f3e7071e37b57f7c07a373db5055987d7e95f4ac9d57f679693d173bb","constraints":{"executionContext":"node"},"contract":["react-refresh exports performReactRefresh as a function","performReactRefresh returns null when there are no pending component updates","performReactRefresh processes registered component updates and returns updatedFamilies set containing the updated component family","performReactRefresh sets updated component family current reference to newly registered component type","performReactRefresh classifies component families with changed hook signatures into staleFamilies set"],"goal":"verify react-refresh.performReactRefresh in pkg:npm/react-refresh@0.18.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.18.0"],"schemaVersion":1,"symbols":["react-refresh.performReactRefresh"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/react-refresh@0.18.0"],"schemaVersion":1,"subject":"pkg:npm/react-refresh@0.18.0","symbols":["react-refresh.performReactRefresh"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-refresh-perform",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-refresh-perform",
      "version": "1.0.0",
      "dependencies": {
        "react-refresh": "0.18.0"
      }
    },
    "node_modules/react-refresh": {
      "version": "0.18.0",
      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.18.0.tgz",
      "integrity": "sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

{
  "name": "sample-react-refresh-perform",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of react-refresh performReactRefresh",
  "main": "src/index.js",
  "dependencies": {
    "react-refresh": "0.18.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify react-refresh.performReactRefresh in pkg:npm/react-refresh@0.18.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/react-refresh@0.18.0"
  ],
  "symbols": [
    "react-refresh.performReactRefresh"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const RefreshRuntime = require('react-refresh');

/**
 * Performs a React Refresh update cycle.
 * @returns {object|null} The refresh update object containing updatedFamilies and staleFamilies, or null if no updates pending.
 */
function triggerRefresh() {
  return RefreshRuntime.performReactRefresh();
}

/**
 * Registers a component type with a specific identifier family.
 * @param {Function|object} type - Component type.
 * @param {string} id - Component identifier.
 */
function registerComponent(type, id) {
  RefreshRuntime.register(type, id);
}

/**
 * Sets the hook signature for a component type.
 * @param {Function|object} type - Component type.
 * @param {string} key - Signature key.
 * @param {boolean} [forceReset=false] - Whether to force a full reset.
 */
function setComponentSignature(type, key, forceReset) {
  RefreshRuntime.setSignature(type, key, forceReset);
}

module.exports = {
  triggerRefresh,
  registerComponent,
  setComponentSignature,
  RefreshRuntime
};

import assert from 'node:assert';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  triggerRefresh,
  registerComponent,
  setComponentSignature,
  RefreshRuntime
} = require('../src/index.js');

// 1. Export verification
assert.strictEqual(
  typeof RefreshRuntime.performReactRefresh,
  'function',
  'react-refresh exports performReactRefresh as a function'
);

// 2. Returns null when no updates are pending
const initialResult = triggerRefresh();
assert.strictEqual(
  initialResult,
  null,
  'performReactRefresh returns null when there are no pending component updates'
);

// 3. Registering component updates and processing them via performReactRefresh
function HeaderV1() {
  return 'Header version 1';
}
registerComponent(HeaderV1, 'HeaderComponentId');

// Before an update is registered to the same ID, performReactRefresh still returns null
assert.strictEqual(
  triggerRefresh(),
  null,
  'performReactRefresh returns null before an updated version is registered'
);

function HeaderV2() {
  return 'Header version 2';
}
registerComponent(HeaderV2, 'HeaderComponentId');

// Now performReactRefresh processes the pending update
const updateResult = triggerRefresh();
assert.ok(
  updateResult !== null && typeof updateResult === 'object',
  'performReactRefresh returns an update object when pending updates exist'
);
assert.ok(
  updateResult.updatedFamilies instanceof Set,
  'performReactRefresh update object contains updatedFamilies Set'
);
assert.ok(
  updateResult.staleFamilies instanceof Set,
  'performReactRefresh update object contains staleFamilies Set'
);
assert.strictEqual(
  updateResult.updatedFamilies.size,
  1,
  'updatedFamilies contains exactly 1 updated family'
);
assert.strictEqual(
  updateResult.staleFamilies.size,
  0,
  'staleFamilies is empty for simple compatible updates'
);

// 4. Component family current reference is updated to new type
const updatedFamily = [...updateResult.updatedFamilies][0];
assert.strictEqual(
  updatedFamily.current,
  HeaderV2,
  'performReactRefresh sets updated component family current reference to newly registered component type'
);

// Subsequent call returns null because pending updates were flushed
assert.strictEqual(
  triggerRefresh(),
  null,
  'performReactRefresh returns null immediately after pending updates are flushed'
);

// 5. Signature changes cause family to be classified into staleFamilies
function NavV1() {
  return 'Nav version 1';
}
registerComponent(NavV1, 'NavComponentId');
setComponentSignature(NavV1, 'sig-v1');

function NavV2() {
  return 'Nav version 2';
}
registerComponent(NavV2, 'NavComponentId');
setComponentSignature(NavV2, 'sig-v2');

const staleUpdateResult = triggerRefresh();
assert.ok(
  staleUpdateResult !== null,
  'performReactRefresh returns update object for signature update'
);
assert.strictEqual(
  staleUpdateResult.staleFamilies.size,
  1,
  'performReactRefresh classifies component families with changed hook signatures into staleFamilies set'
);
assert.strictEqual(
  staleUpdateResult.updatedFamilies.size,
  0,
  'updatedFamilies is empty when component signature changed'
);

console.log('Contract assertions for react-refresh.performReactRefresh passed.');