@suzukihayate/graphemes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hayate Suzuki (鈴木颯)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# graphemes
+
+Emoji- and grapheme-aware string helpers, so `length`, `slice`, `truncate` and `reverse` don't break emoji, flags, skin tones or ZWJ sequences (👨‍👩‍👧‍👦).
+
+In JavaScript, `'a👍b'.length` is `4`, and naive `slice`/`reverse` can split an emoji in half. `graphemes` counts and cuts by **user-perceived characters** using `Intl.Segmenter` (with a code-point fallback). Zero dependencies.
+
+## Install
+```bash
+npm install @suzukihayate/graphemes
+```
+
+## Usage
+```js
+import { length, slice, truncate, reverse, toGraphemes, at } from '@suzukihayate/graphemes';
+
+length('a👍b');          // 3   (native .length is 4)
+length('👨‍👩‍👧‍👦');         // 1   (a single ZWJ grapheme)
+
+slice('a👍b😀c', 1, 3);  // "👍b"
+reverse('a👍b');         // "b👍a"  (emoji stays intact)
+truncate('a👍b😀c', 3);  // "a👍…"  (no broken emoji)
+at('a👍b', 1);           // "👍"
+
+toGraphemes('a👍b');     // ["a", "👍", "b"]
+```
+
+## API
+- `toGraphemes(str)` → `string[]`
+- `length(str)` → grapheme count
+- `slice(str, start?, end?)` → grapheme-based slice (negative indices ok)
+- `at(str, index)` → grapheme at index (supports negative)
+- `reverse(str)` → reverse by graphemes
+- `truncate(str, max, { ellipsis? })` → truncate to ≤ `max` graphemes incl. ellipsis
+
+> Uses `Intl.Segmenter` when available (Node 16+, modern browsers). Falls back to code points otherwise.
+
+## Test
+```bash
+node --test
+```
+
+## License
+MIT © 2026 Hayate Suzuki

package/index.d.ts

@@ -0,0 +1,17 @@
+/** Split a string into grapheme clusters (user-perceived characters). */
+export function toGraphemes(str: string): string[];
+/** Number of grapheme clusters. */
+export function length(str: string): number;
+/** Slice by grapheme index (negative indices count from the end). */
+export function slice(str: string, start?: number, end?: number): string;
+/** Grapheme at the given index (supports negative). */
+export function at(str: string, index: number): string | undefined;
+/** Reverse a string by graphemes. */
+export function reverse(str: string): string;
+/** Truncate to at most `max` graphemes (including the ellipsis). */
+export function truncate(str: string, max: number, opts?: { ellipsis?: string }): string;
+declare const _default: {
+  toGraphemes: typeof toGraphemes; length: typeof length; slice: typeof slice;
+  at: typeof at; reverse: typeof reverse; truncate: typeof truncate;
+};
+export default _default;

package/index.js

@@ -0,0 +1,65 @@
+// graphemes — Emoji- and grapheme-aware string helpers, so length/slice/truncate
+// don't break emoji, flags, skin tones or ZWJ sequences (👨‍👩‍👧‍👦).
+// Uses Intl.Segmenter when available, with a code-point fallback. Zero dependencies.
+
+const hasSegmenter = typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function';
+const segmenter = hasSegmenter ? new Intl.Segmenter(undefined, { granularity: 'grapheme' }) : null;
+
+/**
+ * Split a string into an array of grapheme clusters (user-perceived characters).
+ * @param {string} str
+ * @returns {string[]}
+ */
+export function toGraphemes(str) {
+  const s = String(str);
+  if (segmenter) {
+    const out = [];
+    for (const { segment } of segmenter.segment(s)) out.push(segment);
+    return out;
+  }
+  // Fallback: code points (handles surrogate pairs, but not full ZWJ clusters)
+  return Array.from(s);
+}
+
+/** Number of grapheme clusters (what a human would count as characters). */
+export function length(str) {
+  return toGraphemes(str).length;
+}
+
+/**
+ * Slice by grapheme index (negative indices count from the end).
+ * @param {string} str
+ * @param {number} [start]
+ * @param {number} [end]
+ */
+export function slice(str, start, end) {
+  return toGraphemes(str).slice(start, end).join('');
+}
+
+/** Grapheme at the given index (supports negative). */
+export function at(str, index) {
+  const g = toGraphemes(str);
+  const i = index < 0 ? g.length + index : index;
+  return g[i];
+}
+
+/** Reverse a string by graphemes (keeps emoji/ZWJ sequences intact). */
+export function reverse(str) {
+  return toGraphemes(str).reverse().join('');
+}
+
+/**
+ * Truncate to at most `max` graphemes (including the ellipsis).
+ * @param {string} str
+ * @param {number} max total grapheme budget
+ * @param {{ ellipsis?: string }} [opts]
+ */
+export function truncate(str, max, opts = {}) {
+  const { ellipsis = '…' } = opts;
+  const g = toGraphemes(str);
+  if (g.length <= max) return str;
+  const keep = Math.max(0, max - length(ellipsis));
+  return g.slice(0, keep).join('') + ellipsis;
+}
+
+export default { toGraphemes, length, slice, at, reverse, truncate };

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@suzukihayate/graphemes",
+  "version": "0.1.0",
+  "description": "Emoji- and grapheme-aware string helpers (length, slice, truncate, reverse) using Intl.Segmenter. Zero dependencies.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts", "default": "./index.js" } },
+  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test" },
+  "keywords": ["grapheme", "emoji", "unicode", "string", "length", "truncate", "slice", "segmenter", "zero-dependency"],
+  "repository": { "type": "git", "url": "git+https://github.com/HaYaTedonn/graphemes.git" },
+  "author": "Hayate Suzuki",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "sideEffects": false
+}