{"id":11404,"library":"nlcst-normalize","title":"NLCST Normalize Utility","description":"nlcst-normalize is a utility within the unified ecosystem, specifically designed for working with Natural Language Concrete Syntax Tree (NLCST) nodes. Its primary function is to serialize and clean words, making them easier to compare consistently. The current stable version is 4.0.0. The package generally follows a release cadence tied to Node.js LTS versions, dropping support for unmaintained Node.js versions with major releases. Key differentiators include its integration with the broader unified collective for natural language processing, its ability to normalize various word forms (e.g., smart vs. straight apostrophes) and handle specific punctuation like hyphens and apostrophes based on configurable options. This makes it particularly useful for tasks such as building keyword matchers or creating indexes where slight variations in word formatting need to be reconciled.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/nlcst-normalize","tags":["javascript","unist","nlcst","nlcst-util","util","utility","normalize","typescript"],"install":[{"cmd":"npm install nlcst-normalize","lang":"bash","label":"npm"},{"cmd":"yarn add nlcst-normalize","lang":"bash","label":"yarn"},{"cmd":"pnpm add nlcst-normalize","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"nlcst-normalize is an ESM-only package since v3.0.0. CommonJS 'require' is not supported.","wrong":"const normalize = require('nlcst-normalize').normalize","symbol":"normalize","correct":"import { normalize } from 'nlcst-normalize'"},{"note":"For TypeScript, 'Options' is a type and should be imported using 'import type'.","wrong":"import { Options } from 'nlcst-normalize'","symbol":"Options","correct":"import type { Options } from 'nlcst-normalize'"},{"note":"When using in Deno or browsers via esm.sh, ensure you specify the version in the URL.","wrong":"import {normalize} from 'nlcst-normalize'","symbol":"normalize (Deno/Browser)","correct":"import {normalize} from 'https://esm.sh/nlcst-normalize@4'"}],"quickstart":{"code":"import { normalize } from 'nlcst-normalize';\n\n// Normalize simple strings\nconsole.log(normalize(\"Don't\")); // => 'dont'\nconsole.log(normalize('Don’t')); // => 'dont'\n\n// Normalize with options to retain specific punctuation\nconsole.log(normalize('Don’t', { allowApostrophes: true })); // => 'don\\'t'\nconsole.log(normalize('Block-level')); // => 'blocklevel'\nconsole.log(normalize('Block-level', { allowDashes: true })); // => 'block-level'\n\n// Normalize an NLCST WordNode object\nconst wordNode = {\n  type: 'WordNode',\n  children: [\n    { type: 'TextNode', value: 'Example' },\n    { type: 'PunctuationNode', value: '-' },\n    { type: 'TextNode', value: 'word' }\n  ]\n};\nconsole.log(normalize(wordNode)); // => 'exampleword'\n","lang":"typescript","description":"This quickstart demonstrates how to use the `normalize` function with various string inputs, including options to control punctuation stripping, and how to pass an NLCST `WordNode` object for normalization."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. For projects that cannot upgrade, consider using nlcst-normalize@^3.","message":"Version 4.0.0 of nlcst-normalize requires Node.js version 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your codebase to use ECMAScript Modules (ESM) syntax with `import` statements. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in package.json or using `.mjs` file extensions).","message":"nlcst-normalize switched to being an ESM-only package starting from version 3.0.0. CommonJS `require()` statements will fail.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your TypeScript code to use `Options` instead of `NormalizeOptions` when defining or importing the configuration type.","message":"Version 4.0.0 removed the `NormalizeOptions` type. The correct type for configuration is now `Options`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If you need to preserve apostrophes or hyphens, pass `{ allowApostrophes: true }` or `{ allowDashes: true }` respectively in the options object to the `normalize` function.","message":"When normalizing, smart apostrophes (`’`) are always converted to straight apostrophes (`'`) and then removed by default, along with hyphens (`-`), unless `allowApostrophes` or `allowDashes` options are explicitly set to `true`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { normalize } = require('nlcst-normalize')` to `import { normalize } from 'nlcst-normalize'`.","cause":"Attempting to use `require()` to import nlcst-normalize in a module context where only ESM is supported.","error":"TypeError: require is not a function"},{"fix":"Always import symbols directly from the main package entry point: `import { normalize } from 'nlcst-normalize'`.","cause":"Attempting to import from a non-public, internal path of the package, which is disallowed due to the `exports` field in package.json.","error":"Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/index.js' is not defined by \"exports\" in ..."},{"fix":"Replace `NormalizeOptions` with `Options` in your TypeScript type imports and declarations.","cause":"Using the deprecated `NormalizeOptions` type after upgrading to version 4.0.0 or later.","error":"Property 'NormalizeOptions' does not exist on type 'typeof import(\"nlcst-normalize\")'"}],"ecosystem":"npm"}