char-regex 1.0.2: match grapheme clusters and emoji sequences with regex

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: match grapheme clusters and emoji sequences with regex
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/char-regex@1.0.2
Demonstrate these symbols/APIs:
  - charRegex

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:bc5ffb5d99e13b539739599b5d9973fa1feada868144040bff0355578eb6512e","contract":["charRegex returns a regular expression with global flag enabled","charRegex matches standard ASCII letters and numbers individually","charRegex matches emoji with skin tone modifiers as a single character","charRegex matches regional indicator flag sequences as a single character","charRegex matches zero-width joiner (ZWJ) family and composite emoji sequences as a single character","charRegex matches characters with combining diacritical marks as a single character","charRegex correctly counts grapheme clusters in mixed multi-byte text"],"goal":"match grapheme clusters and emoji sequences with regex","kind":"HOW","packages":["pkg:npm/char-regex@1.0.2"],"schemaVersion":1,"symbols":["charRegex"]},"contractCommand":["node","test/contract.js"],"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/char-regex@1.0.2"],"schemaVersion":1,"subject":"pkg:npm/char-regex@1.0.2","symbols":["charRegex"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-char-regex",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-char-regex",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "char-regex": "1.0.2"
      }
    },
    "node_modules/char-regex": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/char-regex/-/char-regex-1.0.2.tgz",
      "integrity": "sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==",
      "license": "MIT",
      "engines": {
        "node": ">=10"
      }
    }
  }
}

{
  "name": "sample-char-regex",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for char-regex",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "char-regex": "1.0.2"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "match grapheme clusters and emoji sequences with regex",
  "kind": "HOW",
  "packages": [
    "pkg:npm/char-regex@1.0.2"
  ],
  "symbols": [
    "charRegex"
  ]
}

'use strict';

const charRegex = require('char-regex');

/**
 * Splits a string into an array of individual grapheme cluster characters.
 * @param {string} input
 * @returns {string[]}
 */
function splitCharacters(input) {
  if (typeof input !== 'string') {
    return [];
  }
  const regex = charRegex();
  return input.match(regex) || [];
}

/**
 * Counts the number of grapheme cluster characters in a string.
 * @param {string} input
 * @returns {number}
 */
function countCharacters(input) {
  return splitCharacters(input).length;
}

module.exports = {
  charRegex,
  splitCharacters,
  countCharacters
};

'use strict';

const assert = require('assert');
const charRegex = require('char-regex');
const { splitCharacters, countCharacters } = require('../src/index.js');

// 1. charRegex returns a regular expression with global flag enabled
{
  const regex = charRegex();
  assert(regex instanceof RegExp);
  assert.strictEqual(regex.global, true);
}

// 2. charRegex matches standard ASCII letters and numbers individually
{
  const str = 'hello 123';
  const matches = str.match(charRegex());
  assert.deepStrictEqual(matches, ['h', 'e', 'l', 'l', 'o', ' ', '1', '2', '3']);
  assert.deepStrictEqual(splitCharacters(str), ['h', 'e', 'l', 'l', 'o', ' ', '1', '2', '3']);
}

// 3. charRegex matches emoji with skin tone modifiers as a single character
{
  const str = '❤️👊🏽';
  const matches = str.match(charRegex());
  assert.deepStrictEqual(matches, ['❤️', '👊🏽']);
  assert.deepStrictEqual(splitCharacters(str), ['❤️', '👊🏽']);
  assert.strictEqual(countCharacters(str), 2);
}

// 4. charRegex matches regional indicator flag sequences as a single character
{
  const flag = '🇺🇸';
  const matches = flag.match(charRegex());
  assert.deepStrictEqual(matches, ['🇺🇸']);
  assert.strictEqual(countCharacters(flag), 1);
  assert.strictEqual(flag.length > 1, true);
}

// 5. charRegex matches zero-width joiner (ZWJ) family and composite emoji sequences as a single character
{
  const family = '👨‍👩‍👧‍👦';
  const matches = family.match(charRegex());
  assert.deepStrictEqual(matches, ['👨‍👩‍👧‍👦']);
  assert.strictEqual(countCharacters(family), 1);
}

// 6. charRegex matches characters with combining diacritical marks as a single character
{
  const combined = 'e\u0301';
  const matches = combined.match(charRegex());
  assert.deepStrictEqual(matches, ['e\u0301']);
  assert.strictEqual(countCharacters(combined), 1);
}

// 7. charRegex correctly counts grapheme clusters in mixed multi-byte text
{
  const text = '👨‍👩‍👧‍👦 hello 🇺🇸 ❤️👊🏽';
  const characters = splitCharacters(text);
  assert.strictEqual(characters.length, 12);
  assert.strictEqual(countCharacters(text), 12);
  assert.deepStrictEqual(splitCharacters(''), []);
  assert.strictEqual(countCharacters(''), 0);
  assert.deepStrictEqual(splitCharacters(null), []);
  assert.strictEqual(countCharacters(null), 0);
}

console.log('Contract tests passed successfully.');