add grapheme-counter entry for fast counting (#135)

* add grapheme-counter entry for fast counting

extracted the shared category tables and pair-rule machine into an
internal grapheme-core module, and adds `unicode-segmenter/grapheme-counter`

* udpate bundle stats using UPDATE_README skill

Author: cometkim

.changeset/grapheme-counter-entry.md

@@ -0,0 +1,11 @@
+---
+"unicode-segmenter": minor
+---
+
+Add `unicode-segmenter/grapheme-counter`, a standalone fast counter for extended grapheme clusters.
+
+`countGraphemes()` from the new entry returns exactly the same result as the one in `unicode-segmenter/grapheme`, but runs the boundary rules directly without allocating segment objects or slicing strings:
+
+- 4\~7x faster counting on V8, ~4x on Hermes, with zero allocation
+- Standalone entry (4,852 bytes minified, 2,353 bytes gzipped); doesn't carry the segmenter code, and the segmenter entry doesn't carry the counter - even without tree-shaking
+- The `countGraphemes()` wrapper in `unicode-segmenter/grapheme` is unchanged and stays as the convenience API

.claude/skills/benchmark/SKILL.md

@@ -21,6 +21,8 @@ This library's priorities, in order: bundle size, runtime perf, memory footprint
 
 Benchmarks import `src/*.js` directly — no build step needed, current checkout state is what gets measured.
 
+Bundle-stats env options: `PRINT_FORMAT=markdown` prints a README-ready markdown table instead of `console.table`; `UPDATE_README=true` rewrites the matching README comparison table in place (rows/columns matched by name ignoring `*` footnote marks, which are preserved; hand-maintained cells like Unicode®/ESM? and the `Intl.Segmenter` row are untouched).
+
 ## Interpreting results
 
 - **Compare ratios within a run, not absolute ns across runs.** Apple Silicon clock scaling (3.7–4.5 GHz observed on M4 Pro) swings absolute numbers ±20% between runs. Each perf run includes the competitors, so the `summary` "x faster than" lines are the stable signal.

README.md

@@ -36,6 +36,7 @@ Unicode® Standard Annex \#29 - [Revision 47](https://www.unicode.org/reports/tr
 Entries for Unicode text segmentation.
 
 - [`unicode-segmenter/grapheme`](#export-unicode-segmentergrapheme): Segments and counts **extended grapheme clusters**
+- [`unicode-segmenter/grapheme-counter`](#export-unicode-segmentergrapheme-counter): Standalone fast counter for **extended grapheme clusters**
 - [`unicode-segmenter/intl-adapter`](#export-unicode-segmenterintl-adapter): [`Intl.Segmenter`] adapter
 - [`unicode-segmenter/intl-polyfill`](#export-unicode-segmenterintl-polyfill): [`Intl.Segmenter`] polyfill
 
@@ -93,6 +94,8 @@ countGraphemes('a̐éö̲');
 > `countGraphemes()` is a small wrapper around `graphemeSegments()`.
 > 
 > If you need it more than once at a time, consider memoization or use `graphemeSegments()` or `splitGraphemes()` once instead.
+>
+> If counting is on your hot path, use the standalone [`unicode-segmenter/grapheme-counter`](#export-unicode-segmentergrapheme-counter) entry instead.
 
 #### Example: Build an advanced grapheme matcher
 
@@ -122,6 +125,31 @@ function* matchEmoji(str) {
 
 Or build even more advanced one like an Unicode-aware [TTY string width](https://github.com/cometkim/unicode-string-width) utility.
 
+### Export `unicode-segmenter/grapheme-counter`
+
+A standalone counter for extended grapheme clusters.
+
+The result is identical to `countGraphemes()` of `unicode-segmenter/grapheme`, but it runs the boundary rules directly without allocating segment objects or slicing strings, so counting is 4+ times faster and zero heap usage.
+
+It is a separate entry so that counting doesn't have to carry the segmenter code, and vice versa.
+
+#### Example: Count graphemes fast
+
+```js
+import { countGraphemes } from 'unicode-segmenter/grapheme-counter';
+
+countGraphemes('👋 안녕!');
+// => 5
+```
+
+> [!NOTE]
+> The counter module contains duplicate code from `graphemeSegments()`.
+> 
+> If you want a smaller bundle size and performance multipliers are not very important, use the `unicode-segmenter/grapheme` module instead.
+>
+> Full Segmenter is already optimized enough.
+
+
 ### Export `unicode-segmenter/intl-adapter`
 
 [`Intl.Segmenter`] API adapter (only `granularity: "grapheme"` available yet)
@@ -214,14 +242,16 @@ Since [Hermes doesn't support the `Intl.Segmenter` API](https://github.com/faceb
 
 #### JS Bundle Stats
 
-| Name                         | Unicode® | ESM? |   Size    | Size (min) | Size (min+gzip) | Size (min+br) | Size (min+zstd) |
-|------------------------------|----------|------|----------:|-----------:|----------------:|--------------:|----------------:|
-| `unicode-segmenter/grapheme` |   17.0.0 |   ✔️ |     9,032 |      5,175 |           2,507 |         2,254 |           2,551 |
-| `graphemer`                  |   15.0.0 |   ✖️ ️|   410,435 |     95,104 |          15,752 |        10,660 |          15,911 |
-| `grapheme-splittetr`         |   10.0.0 |   ✖️ |   122,254 |     23,682 |           7,852 |         4,802 |           6,753 |
-| `@formatjs/intl-segmenter`*  |   17.0.0 |   ✖️ |   268,301 |    176,759 |          45,988 |        31,701 |          45,370 |
-| `unicode-segmentation`*      |   15.1.0 |    - |    56,529 |     52,439 |          24,108 |        17,343 |          24,375 |
-| `Intl.Segmenter`*            |        - |    - |         0 |          0 |               0 |             0 |               0 |
+| Name                                            | Unicode® | ESM? |    Size | Size (min) | Size (min+gzip) | Size (min+br) | Size (min+zstd) |
+|-------------------------------------------------|----------|------|--------:|-----------:|----------------:|--------------:|----------------:|
+| `unicode-segmenter/grapheme`                    | 17.0.0   | ✔️   |   9,009 |      5,171 |           2,497 |         2,249 |           2,544 |
+| `unicode-segmenter/grapheme-counter`            | 17.0.0   | ✔️   |   7,912 |      4,852 |           2,353 |         2,120 |           2,396 |
+| `unicode-segmenter/grapheme + grapheme-counter` | 17.0.0   | ✔️   |   9,985 |      5,489 |           2,571 |         2,310 |           2,612 |
+| `graphemer`                                     | 15.0.0   | ✖️  ️ | 410,435 |     95,104 |          15,752 |        10,660 |          15,911 |
+| `grapheme-splitter`                             | 10.0.0   | ✖️   | 122,254 |     23,682 |           7,852 |         4,802 |           6,753 |
+| `@formatjs/intl-segmenter`*                     | 17.0.0   | ✖️   | 268,301 |    176,759 |          45,988 |        31,701 |          45,370 |
+| `unicode-segmentation`*                         | 15.1.0   | -    |  56,529 |     52,439 |          24,108 |        17,343 |          24,375 |
+| `Intl.Segmenter`*                               | -        | -    |       0 |          0 |               0 |             0 |               0 |
 
 * `@formatjs/intl-segmenter` handles grapheme, word, and sentence, but it's not tree-shakable.
 * `unicode-segmentation` size contains only minimum WASM binary and its bindings to execute benchmarking. It will increases to expose more features.
@@ -230,12 +260,14 @@ Since [Hermes doesn't support the `Intl.Segmenter` API](https://github.com/faceb
 
 #### Hermes Bytecode Stats
 
-| Name                         | Bytecode size | Bytecode size (gzip)* |
-|------------------------------|--------------:|----------------------:|
-| `unicode-segmenter/grapheme` |        19,354 |                10,713 |
-| `graphemer`                  |       134,085 |                31,770 |
-| `grapheme-splitter`          |        63,942 |                19,165 |
-| `@formatjs/intl-segmenter`   |       329,547 |               136,751 |
+| Name                                            | Bytecode size | Bytecode size (gzip)* |
+|-------------------------------------------------|--------------:|----------------------:|
+| `unicode-segmenter/grapheme`                    |        19,721 |                10,874 |
+| `unicode-segmenter/grapheme-counter`            |        18,210 |                10,069 |
+| `unicode-segmenter/grapheme + grapheme-counter` |        20,667 |                11,371 |
+| `graphemer`                                     |       134,085 |                31,770 |
+| `grapheme-splitter`                             |        63,942 |                19,165 |
+| `@formatjs/intl-segmenter`                      |       329,547 |               136,751 |
 
 * The installation size contains _compressed_ assets.
 

benchmark/_helper.js

@@ -1,6 +1,9 @@
+import * as fs from 'node:fs/promises';
 import * as zlib from 'node:zlib';
 import { promisify } from 'node:util';
 
+import prettyBytes from 'pretty-bytes';
+
 let gzip = promisify(zlib.gzip);
 let brotli = promisify(zlib.brotliCompress);
 let zstd = promisify(zlib.zstdCompress);
@@ -42,3 +45,140 @@ export async function reportHermesStats(name, bin) {
     'Bytecode size (gzip)': byteLength(await gzip(bin)),
   };
 }
+
+/**
+ * Print stat reports as a table.
+ *
+ * Defaults to `console.table`; set `PRINT_FORMAT=markdown` to emit a
+ * README-ready markdown table instead (names in backticks, numbers
+ * comma-formatted and right-aligned).
+ */
+export function printStats(reports) {
+  if (process.env.PRINT_FORMAT !== 'markdown') {
+    console.table(reports);
+    return;
+  }
+
+  let columns = [];
+  for (let report of reports) {
+    for (let key of Object.keys(report)) {
+      if (!columns.includes(key)) columns.push(key);
+    }
+  }
+
+  let rows = reports.map(report => columns.map((key, i) => {
+    let value = report[key];
+    if (value == null) return '';
+    if (typeof value === 'number') return value.toLocaleString('en-US');
+    return i === 0 ? `\`${value}\`` : String(value);
+  }));
+
+  let widths = columns.map((key, i) => {
+    return Math.max(key.length, ...rows.map(row => row[i].length));
+  });
+
+  let lines = [
+    `| ${columns.map((key, i) => key.padEnd(widths[i])).join(' | ')} |`,
+    `|${widths.map((w, i) => i === 0 ? '-'.repeat(w + 2) : `${'-'.repeat(w + 1)}:`).join('|')}|`,
+    ...rows.map(row => {
+      return `| ${row.map((cell, i) => i === 0 ? cell.padEnd(widths[i]) : cell.padStart(widths[i])).join(' | ')} |`;
+    }),
+  ];
+  console.log(lines.join('\n'));
+}
+
+/**
+ * Update a stats table in README.md with fresh report values, when
+ * `UPDATE_README=true`.
+ *
+ * The table is located by its `#### <section>` heading. Rows are
+ * matched by library name and columns by header text, both ignoring
+ * the `*` footnote marks, which are preserved as-is. Cells with no
+ * matching report column (e.g. Unicode®, ESM?) and rows with no
+ * matching report (e.g. `Intl.Segmenter`) are left untouched.
+ *
+ * @param {Array<Record<string, unknown>>} reports
+ * @param {string} section heading text, e.g. 'JS Bundle Stats'
+ */
+export async function updateReadmeStats(reports, section) {
+  if (process.env.UPDATE_README !== 'true') return;
+
+  let readmeUrl = new URL('../README.md', import.meta.url);
+  let source = await fs.readFile(readmeUrl, 'utf-8');
+  let lines = source.split('\n');
+
+  let headingPattern = new RegExp(
+    `^#{1,6}\\s+${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
+  );
+  let heading = lines.findIndex(line => headingPattern.test(line));
+  let head = heading < 0
+    ? -1
+    : lines.findIndex((line, i) => i > heading && line.trimStart().startsWith('|'));
+  if (head < 0) {
+    console.warn(`README: no "${section}" table found, skipped`);
+    return;
+  }
+  let end = head + 1;
+  while (end < lines.length && lines[end].trimStart().startsWith('|')) end += 1;
+
+  let split = line => line.trim().replace(/^\||\|$/g, '').split('|').map(cell => cell.trim());
+  let stripMark = text => text.replace(/\*+$/, '').trim();
+
+  let header = split(lines[head]);
+  let aligns = split(lines[head + 1]).map(cell => {
+    return cell.endsWith(':') ? (cell.startsWith(':') ? 'center' : 'right') : 'left';
+  });
+  let body = lines.slice(head + 2, end).map(split);
+  let colKeys = header.map(stripMark);
+
+  let byName = new Map(reports.map(report => [String(report.name), report]));
+  for (let report of reports) {
+    // e.g. the 'unicode-segmentation (wasm-bindgen)' report matches
+    // the `unicode-segmentation` row
+    let alias = String(report.name).replace(/\s*\([^)]*\)$/, '');
+    if (!byName.has(alias)) byName.set(alias, report);
+  }
+
+  let matched = new Set();
+  for (let row of body) {
+    let report = byName.get(stripMark(row[0]).replace(/`/g, '').trim());
+    if (!report) continue;
+    matched.add(report);
+    for (let i = 1; i < header.length; i++) {
+      let value = report[colKeys[i]];
+      if (value === undefined) continue;
+      row[i] = typeof value === 'number' ? value.toLocaleString('en-US') : String(value);
+    }
+  }
+  for (let report of reports) {
+    if (!matched.has(report)) {
+      console.warn(`README: no "${section}" row for '${report.name}'; add it manually`);
+    }
+  }
+
+  let widths = header.map((cell, i) => {
+    return Math.max(cell.length, 3, ...body.map(row => (row[i] ?? '').length));
+  });
+  let pad = (cell, i) => aligns[i] === 'right' ? cell.padStart(widths[i]) : cell.padEnd(widths[i]);
+  let render = row => `| ${header.map((_, i) => pad(row[i] ?? '', i)).join(' | ')} |`;
+  let separator = `|${widths.map((w, i) => {
+    if (aligns[i] === 'right') return `${'-'.repeat(w + 1)}:`;
+    if (aligns[i] === 'center') return `:${'-'.repeat(w)}:`;
+    return '-'.repeat(w + 2);
+  }).join('|')}|`;
+
+  let next = [
+    ...lines.slice(0, head),
+    render(header),
+    separator,
+    ...body.map(render),
+    ...lines.slice(end),
+  ].join('\n');
+
+  if (next === source) {
+    console.log(`README: "${section}" table is up to date`);
+    return;
+  }
+  await fs.writeFile(readmeUrl, next);
+  console.log(`README: updated "${section}" table`);
+}

benchmark/emoji/bundle-stats.js

@@ -3,7 +3,7 @@
 import * as path from 'node:path';
 import { build } from 'esbuild';
 
-import { reportBundleStats } from '../_helper.js';
+import { printStats, reportBundleStats } from '../_helper.js';
 
 let baseDir = import.meta.dirname;
 
@@ -37,4 +37,4 @@ let reports = await Promise.all(
   }),
 );
 
-console.table(reports);
+printStats(reports);

benchmark/general/bundle-stats.js

@@ -3,7 +3,7 @@
 import * as path from 'node:path';
 import { build } from 'esbuild';
 
-import { reportBundleStats } from '../_helper.js';
+import { printStats, reportBundleStats } from '../_helper.js';
 
 let baseDir = import.meta.dirname;
 
@@ -35,4 +35,4 @@ let reports = await Promise.all(
   }),
 );
 
-console.table(reports);
+printStats(reports);

benchmark/grapheme/bundle-entries/unicode-segmenter-both.js

@@ -0,0 +1,10 @@
+// Importing both entries shares `grapheme-core.js`; the counter adds
+// only its counting loop on top of the segmenter.
+export {
+  graphemeSegments,
+  splitGraphemes,
+  countGraphemes,
+} from '../../../src/grapheme.js';
+export {
+  countGraphemes as countGraphemesFast,
+} from '../../../src/grapheme-counter.js';

benchmark/grapheme/bundle-entries/unicode-segmenter-counter.js

@@ -0,0 +1,3 @@
+export {
+  countGraphemes,
+} from '../../../src/grapheme-counter.js';

benchmark/grapheme/bundle-stats-hermes.js

@@ -2,7 +2,7 @@ import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
 import Metro from 'metro';
 import { $ } from 'zx';
-import { reportHermesStats } from '../_helper.js';
+import { printStats, reportHermesStats, updateReadmeStats } from '../_helper.js';
 
 let baseDir = import.meta.dirname;
 
@@ -18,6 +18,8 @@ let config = await Metro.loadConfig(undefined, {
 
 let libs = [
   ['unicode-segmenter/grapheme', 'bundle-entries/unicode-segmenter.js'],
+  ['unicode-segmenter/grapheme-counter', 'bundle-entries/unicode-segmenter-counter.js'],
+  ['unicode-segmenter/grapheme + grapheme-counter', 'bundle-entries/unicode-segmenter-both.js'],
   ['graphemer', 'bundle-entries/graphemer.js'],
   ['grapheme-splitter', 'bundle-entries/grapheme-splitter.js'],
   ['@formatjs/intl-segmenter', 'bundle-entries/formatjs-intl-segmenter.js'],
@@ -47,4 +49,5 @@ for (let lib of libs) {
   );
 }
 
-console.table(reports);
+printStats(reports);
+await updateReadmeStats(reports, 'Hermes Bytecode Stats');

benchmark/grapheme/bundle-stats.js

@@ -4,12 +4,14 @@ import * as path from 'node:path';
 import { build } from 'esbuild';
 import { getBinary as getBinary_unicode_segmentation } from 'unicode-segmentation-wasm/wasm';
 
-import { reportBundleStats, reportWasmBindingStats } from '../_helper.js';
+import { printStats, reportBundleStats, reportWasmBindingStats, updateReadmeStats } from '../_helper.js';
 
 let baseDir = import.meta.dirname;
 
 let libs = [
   ['unicode-segmenter/grapheme', 'bundle-entries/unicode-segmenter.js'],
+  ['unicode-segmenter/grapheme-counter', 'bundle-entries/unicode-segmenter-counter.js'],
+  ['unicode-segmenter/grapheme + grapheme-counter', 'bundle-entries/unicode-segmenter-both.js'],
   ['graphemer', 'bundle-entries/graphemer.js'],
   ['grapheme-splitter', 'bundle-entries/grapheme-splitter.js'],
   ['@formatjs/intl-segmenter', 'bundle-entries/formatjs-intl-segmenter.js'],
@@ -63,4 +65,5 @@ let reports = await Promise.all(
   reports.push(bindingReport);
 }
 
-console.table(reports);
+printStats(reports);
+await updateReadmeStats(reports, 'JS Bundle Stats');