react-refresh 0.18.0: getFamilyByID

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.getFamilyByID 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.getFamilyByID

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:e034bceab94cb0d587053c30cc3034844eb7254956544940591dbdbd86917d8e","contract":["react-refresh.getFamilyByID returns undefined for unregistered family IDs","react-refresh.getFamilyByID returns a family object containing current component type when registered","react-refresh.getFamilyByID returns the identical family reference across multiple lookups","react-refresh.getFamilyByID reflects updated component in family.current after registration update and performReactRefresh","react-refresh.getFamilyByID retrieves derived family IDs for wrapped memo and forwardRef components"],"goal":"verify react-refresh.getFamilyByID in pkg:npm/react-refresh@0.18.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.18.0"],"schemaVersion":1,"symbols":["react-refresh.getFamilyByID"]},"contractCommand":["node","test/contract.cjs"],"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.getFamilyByID"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-refresh-getfamilybyid",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-refresh-getfamilybyid",
      "version": "1.0.0",
      "license": "MIT-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-getfamilybyid",
  "version": "1.0.0",
  "private": true,
  "description": "verify react-refresh.getFamilyByID in pkg:npm/react-refresh@0.18.0",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "react-refresh": "0.18.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify react-refresh.getFamilyByID in pkg:npm/react-refresh@0.18.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/react-refresh@0.18.0"
  ],
  "symbols": [
    "react-refresh.getFamilyByID"
  ]
}

'use strict';

// Ensure development environment for react-refresh runtime
if (!process.env.NODE_ENV) {
  process.env.NODE_ENV = 'development';
}

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

/**
 * Retrieves the family object for a given ID using react-refresh getFamilyByID.
 * @param {string} id - The identifier of the component family.
 * @returns {object|undefined} The family object { current: Function|object } or undefined.
 */
function getFamilyByID(id) {
  return RefreshRuntime.getFamilyByID(id);
}

/**
 * Registers a component type with an identifier in the react-refresh runtime.
 * @param {Function|object} type - The component function or memo/forwardRef object.
 * @param {string} id - Unique identifier for the component.
 */
function registerComponent(type, id) {
  RefreshRuntime.register(type, id);
}

/**
 * Checks whether a family has been registered for a given ID.
 * @param {string} id - The identifier to check.
 * @returns {boolean} True if family exists.
 */
function hasFamily(id) {
  return RefreshRuntime.getFamilyByID(id) !== undefined;
}

/**
 * Retrieves the current component reference associated with a family ID.
 * @param {string} id - The identifier of the family.
 * @returns {Function|object|undefined} The current component type, or undefined.
 */
function getFamilyCurrent(id) {
  const family = RefreshRuntime.getFamilyByID(id);
  return family ? family.current : undefined;
}

/**
 * Triggers react-refresh to flush pending updates and update family.current.
 * @returns {object|null} Update object with updatedFamilies and staleFamilies.
 */
function performRefresh() {
  return RefreshRuntime.performReactRefresh();
}

module.exports = {
  RefreshRuntime,
  getFamilyByID,
  registerComponent,
  hasFamily,
  getFamilyCurrent,
  performRefresh,
};

'use strict';

const assert = require('node:assert/strict');
const RefreshRuntime = require('react-refresh/runtime');
const {
  getFamilyByID,
  registerComponent,
  hasFamily,
  getFamilyCurrent,
  performRefresh,
} = require('../src/index.js');

async function testContract() {
  // 1. react-refresh.getFamilyByID returns undefined for unregistered family IDs
  assert.strictEqual(RefreshRuntime.getFamilyByID('NonExistentComponent'), undefined);
  assert.strictEqual(RefreshRuntime.getFamilyByID(''), undefined);
  assert.strictEqual(getFamilyByID('AnotherUnknownID'), undefined);
  assert.strictEqual(hasFamily('UnknownID'), false);
  assert.strictEqual(getFamilyCurrent('UnknownID'), undefined);

  // 2. react-refresh.getFamilyByID returns a family object containing current component type when registered
  function Header() {
    return 'header-content';
  }
  RefreshRuntime.register(Header, 'Header#1');

  const familyDirect = RefreshRuntime.getFamilyByID('Header#1');
  assert.ok(familyDirect, 'family object must exist');
  assert.strictEqual(typeof familyDirect, 'object', 'family must be an object');
  assert.strictEqual(familyDirect.current, Header, 'family.current must reference registered component');

  function Footer() {
    return 'footer-content';
  }
  registerComponent(Footer, 'Footer#1');
  const familyHelper = getFamilyByID('Footer#1');
  assert.ok(familyHelper, 'helper getFamilyByID must return family');
  assert.strictEqual(familyHelper.current, Footer, 'family.current must match Footer component');
  assert.strictEqual(hasFamily('Footer#1'), true, 'hasFamily helper must return true');
  assert.strictEqual(getFamilyCurrent('Footer#1'), Footer, 'getFamilyCurrent helper must return Footer');

  // 3. react-refresh.getFamilyByID returns the identical family reference across multiple lookups
  const lookup1 = RefreshRuntime.getFamilyByID('Header#1');
  const lookup2 = RefreshRuntime.getFamilyByID('Header#1');
  assert.strictEqual(lookup1, lookup2, 'repeated getFamilyByID calls must return identical object reference');
  assert.strictEqual(getFamilyByID('Footer#1'), familyHelper, 'helper lookup must return identical reference');

  // 4. react-refresh.getFamilyByID reflects updated component in family.current after registration update and performReactRefresh
  function HeaderUpdated() {
    return 'header-content-v2';
  }
  RefreshRuntime.register(HeaderUpdated, 'Header#1');
  // Before refresh is flushed, family.current holds previous version
  assert.strictEqual(familyDirect.current, Header, 'family.current stays on previous version before performReactRefresh');

  const refreshResult = RefreshRuntime.performReactRefresh();
  assert.ok(refreshResult, 'performReactRefresh must return refresh update object');
  assert.strictEqual(familyDirect.current, HeaderUpdated, 'family.current must update to new component version after refresh');
  assert.strictEqual(RefreshRuntime.getFamilyByID('Header#1'), familyDirect, 'family reference must remain stable across updates');

  function FooterUpdated() {
    return 'footer-content-v2';
  }
  registerComponent(FooterUpdated, 'Footer#1');
  performRefresh();
  assert.strictEqual(getFamilyCurrent('Footer#1'), FooterUpdated, 'getFamilyCurrent must return updated Footer component');

  // 5. react-refresh.getFamilyByID retrieves derived family IDs for wrapped memo and forwardRef components
  const REACT_MEMO_TYPE = Symbol.for('react.memo');
  const REACT_FORWARD_REF_TYPE = Symbol.for('react.forward_ref');

  function BaseButton(props) {
    return props.label;
  }
  const MemoButton = {
    $$typeof: REACT_MEMO_TYPE,
    type: BaseButton,
  };
  RefreshRuntime.register(MemoButton, 'MemoButton');

  const memoFamily = RefreshRuntime.getFamilyByID('MemoButton');
  const innerMemoFamily = RefreshRuntime.getFamilyByID('MemoButton$type');
  assert.ok(memoFamily, 'memo component family must exist');
  assert.strictEqual(memoFamily.current, MemoButton, 'memo family.current must reference MemoButton');
  assert.ok(innerMemoFamily, 'inner memo component family must exist with $type suffix');
  assert.strictEqual(innerMemoFamily.current, BaseButton, 'inner memo family.current must reference BaseButton');

  function BaseInput(props, ref) {
    return null;
  }
  const ForwardRefInput = {
    $$typeof: REACT_FORWARD_REF_TYPE,
    render: BaseInput,
  };
  registerComponent(ForwardRefInput, 'ForwardRefInput');

  const forwardRefFamily = getFamilyByID('ForwardRefInput');
  const innerRenderFamily = getFamilyByID('ForwardRefInput$render');
  assert.ok(forwardRefFamily, 'forwardRef family must exist');
  assert.strictEqual(forwardRefFamily.current, ForwardRefInput, 'forwardRef family.current must reference ForwardRefInput');
  assert.ok(innerRenderFamily, 'inner render family must exist with $render suffix');
  assert.strictEqual(innerRenderFamily.current, BaseInput, 'inner render family.current must reference BaseInput');

  console.log('Contract assertions verified successfully.');
}

testContract().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});