string-convert-indexes

Convert between native JS string character indexes and grapheme-count-based indexes

Install

This package is pure ESM. If you're not ready yet, install an older version of this program, 4.1.0 (npm i string-convert-indexes@4.1.0).

1npm i string-convert-indexes

Quick Take

1import { strict as assert } from "assert";
2
3import { nativeToUnicode, unicodeToNative } from "string-convert-indexes";
4
5// CONVERTING NATIVE JS INDEXES TO UNICODE-CHAR-COUNT-BASED
6// 𝌆 - \uD834\uDF06
7
8// at index 1, we have low surrogate, that's still grapheme index zero
9assert.equal(nativeToUnicode("\uD834\uDF06aa", "1"), "0");
10// notice it's retained as string. The same type as input is retained!
11
12// at index 2, we have first letter a - that's second index, counting graphemes
13assert.equal(nativeToUnicode("\uD834\uDF06aa", 3), 2);
14
15// convert many indexes at once - any nested data structure is fine:
16assert.deepEqual(nativeToUnicode("\uD834\uDF06aa", [1, 0, 2, 3]), [0, 0, 1, 2]);
17
18// numbers from an AST-like complex structure are still picked out and converted:
19assert.deepEqual(nativeToUnicode("\uD834\uDF06aa", [1, "0", [[[2]]], 3]), [
20  0, // notice matching type is retained
21  "0", // notice matching type is retained
22  [[[1]]],
23  2,
24]);
25
26// CONVERTING UNICODE-CHAR-COUNT-BASED TO NATIVE JS INDEXES
27// 𝌆 - \uD834\uDF06
28
29assert.deepEqual(unicodeToNative("\uD834\uDF06aa", [0, 1, 2]), [0, 2, 3]);
30
31assert.deepEqual(unicodeToNative("\uD834\uDF06aa", [1, 0, 2]), [2, 0, 3]);
32
33assert.throws(() => unicodeToNative("\uD834\uDF06aa", [1, 0, 2, 3]));
34// throws an error!
35// that's because there's no character (counting Unicode characters) with index 3
36// we have only three Unicode characters, so indexes go only up until 2

Documentation

Please visit codsen.com for a full description of the API.

Contributing

To report bugs or request features or assistance, raise an issue on GitHub.

Licence

MIT License.

Copyright © 2010-2025 Roy Revelt and other contributors.