NLCST Emoji Modifier

Common errors

• TypeError: emojiModifier is not a function

  cause Attempting to use CommonJS `require()` syntax to import `nlcst-emoji-modifier` which is an ESM-only package.
  fix Convert your file to an ES module (e.g., by adding `"type": "module"` to `package.json` or renaming to `.mjs`) and use `import { emojiModifier } from 'nlcst-emoji-modifier'`.

• SyntaxError: Cannot use import statement outside a module

  cause Using ES module `import` syntax in a CommonJS context without proper configuration.
  fix Ensure your Node.js environment or build setup treats your files as ES modules. This might involve setting `"type": "module"` in your `package.json` or explicitly using `.mjs` file extensions.

• Error [ERR_REQUIRE_ESM]: require() of ES Module [path] not supported. Instead change the require of [path] to a dynamic import() or change 'type': 'module' in your package.json or use a .mjs extension.

  cause Trying to `require()` this package (ESM-only) from a CommonJS module.
  fix You must use `import()` or convert your consuming module to ESM. For example, `import { emojiModifier } from 'nlcst-emoji-modifier'`.

• Property 'Emoticon' does not exist on type 'typeof import("nlcst-emoji-modifier")'

  cause TypeScript error when trying to import the `Emoticon` type from `nlcst-emoji-modifier` after version 6.0.0.
  fix The `Emoticon` type was moved. Import it from `nlcst-emoticon-modifier` instead: `import type { Emoticon } from 'nlcst-emoticon-modifier'`.

• UnhandledPromiseRejectionWarning: Error: [Error message about Node.js version]

  cause Running `nlcst-emoji-modifier` v6.0.0+ on an unsupported Node.js version (<16).
  fix Upgrade your Node.js runtime to version 16 or newer. Verify your `package.json` `engines` field if distributing your package.

Warnings

• breaking Version 6.0.0 requires Node.js 16 or higher. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js environment to version 16 or newer. For projects requiring older Node.js, pin `nlcst-emoji-modifier` to `<6.0.0`.
• breaking The package transitioned to ESM-only starting from v5.0.0, and explicitly uses the `exports` field since v6.0.0. This significantly changes how it's imported.
  Fix: Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` files) and use `import { emojiModifier } from 'nlcst-emoji-modifier'` instead of `require()`.
• breaking The `Emoticon` TypeScript type was removed from `nlcst-emoji-modifier` in v6.0.0. It is now exported by `nlcst-emoticon-modifier`.
  Fix: Update your type imports to `import type { Emoticon } from 'nlcst-emoticon-modifier'`. You may need to install `nlcst-emoticon-modifier` if you haven't already.
• breaking The `emojiModifier` function now explicitly yields `undefined` (returns nothing). If you were relying on a return value, your code will need adjustment.
  Fix: Modify your code to expect `undefined` from `emojiModifier` and adjust subsequent logic accordingly. The modifier operates by side-effect on the passed `node`.
• breaking Version 4.0.0 updated `unist-util-visit`, which could be a breaking change for TypeScript users who didn't explicitly expect TypeScript in their dependents.
  Fix: Review your TypeScript configurations and usages of `unist-util-visit` within your dependency tree, ensuring compatibility with its v2.0.0 API.
• gotcha This utility is a low-level NLCST modifier. For a higher-level, easier-to-use abstraction that integrates this and other related utilities, consider `retext-emoji`.
  Fix: Evaluate if `retext-emoji` better suits your needs for general emoji processing in `retext` pipelines, as it wraps `nlcst-emoji-modifier`.

Install

• npm install nlcst-emoji-modifier npm
• yarn add nlcst-emoji-modifier yarn
• pnpm add nlcst-emoji-modifier pnpm

Imports

• emojiModifier
  wrong:

  const emojiModifier = require('nlcst-emoji-modifier')

  correct:

  import { emojiModifier } from 'nlcst-emoji-modifier'

  The package is ESM-only since v5.0.0, and Node.js 16+ is required since v6.0.0. CommonJS `require` will result in errors.
• Emoticon
  wrong:

  import type { Emoticon } from 'nlcst-emoji-modifier'

  correct:

  import type { Emoticon } from 'nlcst-emoticon-modifier'

  Since v6.0.0, the `Emoticon` type has been moved to the `nlcst-emoticon-modifier` package. Attempting to import it from `nlcst-emoji-modifier` will fail.
• emojiModifier (Deno/Browser)

  import {emojiModifier} from 'https://esm.sh/nlcst-emoji-modifier@6'

  For Deno and browser environments, use `esm.sh` with the major version specifier for direct module imports.

Quickstart

This example demonstrates how to integrate `nlcst-emoji-modifier` into a `ParseEnglish` pipeline to tokenize emoji and gemoji shortcodes as `EmoticonNode`s.

import {emojiModifier} from 'nlcst-emoji-modifier'
import {ParseEnglish} from 'parse-english'
import {inspect} from 'unist-util-inspect'

const english = new ParseEnglish()
english.tokenizeSentencePlugins.unshift(emojiModifier)

console.log(inspect(english.parse('It’s raining :cat:s and :dog:s.')))

// Expected output (simplified):
// RootNode
// └─ ParagraphNode
//    └─ SentenceNode
//       ├─ WordNode: "It’s"
//       ├─ WhiteSpaceNode: " "
//       ├─ WordNode: "raining"
//       ├─ WhiteSpaceNode: " "
//       ├─ EmoticonNode: ":cat:"
//       ├─ WordNode: "s"
//       ├─ WhiteSpaceNode: " "
//       ├─ WordNode: "and"
//       ├─ WhiteSpaceNode: " "
//       ├─ EmoticonNode: ":dog:"
//       └─ WordNode: "s."