{"id":11403,"library":"nlcst-search","title":"NLCST Phrase Search Utility","description":"nlcst-search is a utility designed to locate specific word patterns and phrases within Natural Language Concrete Syntax Tree (NLCST) structures. It provides a programmatic way to search text that has been parsed into an NLCST tree, useful for linguistic analysis, linting, or text transformation tasks. The package currently sits at a stable version 4.0.0 and is actively maintained as part of the `unified` collective. Major versions typically signify significant shifts, such as environment compatibility updates (e.g., Node.js versions) or module system changes (e.g., ESM adoption). Key differentiators include its tight integration with the `nlcst` ecosystem, robust pattern matching with normalization options (casing, apostrophes, dashes), and support for wildcards. It ships with full TypeScript type definitions, ensuring a strong developer experience.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/nlcst-search","tags":["javascript","unist","nlcst","nlcst-util","util","utility","pattern","search","typescript"],"install":[{"cmd":"npm install nlcst-search","lang":"bash","label":"npm"},{"cmd":"yarn add nlcst-search","lang":"bash","label":"yarn"},{"cmd":"pnpm add nlcst-search","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used to convert matched NLCST nodes back into readable strings in examples and applications.","package":"nlcst-to-string","optional":false},{"reason":"The `search` function internally uses `nlcst-normalize` for processing patterns, and its options (like `allowApostrophes`, `allowDashes`) are directly passed to it.","package":"nlcst-normalize","optional":false}],"imports":[{"note":"The package is ESM-only since v3. Use named import syntax.","wrong":"const search = require('nlcst-search')","symbol":"search","correct":"import { search } from 'nlcst-search'"},{"note":"TypeScript type for the match handler function.","symbol":"Handler","correct":"import type { Handler } from 'nlcst-search'"},{"note":"TypeScript type for the configuration object passed to `search`.","symbol":"Options","correct":"import type { Options } from 'nlcst-search'"}],"quickstart":{"code":"import { search } from 'nlcst-search'\nimport { toString } from 'nlcst-to-string'\n\nconst tree = {\n  type: 'SentenceNode',\n  children: [\n    {\n      type: 'WordNode',\n      children: [\n        {type: 'TextNode', value: 'Don'},\n        {type: 'PunctuationNode', value: '’'},\n        {type: 'TextNode', value: 't'}\n      ]\n    },\n    {type: 'WhiteSpaceNode', value: ' '},\n    {\n      type: 'WordNode',\n      children: [{type: 'TextNode', value: 'do'}]\n    },\n    {type: 'WhiteSpaceNode', value: ' '},\n    {\n      type: 'WordNode',\n      children: [\n        {type: 'TextNode', value: 'Block'},\n        {type: 'PunctuationNode', value: '-'},\n        {type: 'TextNode', value: 'level'}\n      ]\n    }\n  ]\n}\n\nconsole.log('Searching for \"dont\":')\nsearch(tree, ['dont'], function(nodes) {\n  console.log(`Found: \"${toString(nodes)}\"`);\n});\n\nconsole.log('\\nSearching for \"do blocklevel\" with a wildcard:')\nsearch(tree, ['do *level'], function(nodes) {\n  console.log(`Found: \"${toString(nodes)}\"`);\n});","lang":"typescript","description":"This quickstart demonstrates how to import `search` and `toString` (from `nlcst-to-string`), define an example NLCST tree, and then use `search` to find single words and multi-word phrases, including patterns with wildcards, logging the matched text."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher. Alternatively, use an older version of `nlcst-search` if constrained by Node.js version.","message":"Version 4.0.0 and above require Node.js 16 or newer. Older Node.js versions are not supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your project to use ES modules (`import ... from '...'`) or dynamically import the package if still primarily using CommonJS (`const { search } = await import('nlcst-search')`).","message":"Since version 3.0.0, `nlcst-search` is an ESM-only package. CommonJS `require()` syntax is no longer supported for direct import.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Change `search(tree, phrases, handler, allowApostrophes)` to `search(tree, phrases, handler, {allowApostrophes: boolean})`.","message":"In version 4.0.0, the `allowApostrophes` option can no longer be passed as a separate overload argument. It must now be provided within the `options` object.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update TypeScript definitions or type annotations from `PhrasesList` to `Array<string>`.","message":"Version 4.0.0 removed the `PhrasesList` type; it is now simply `Array<string>`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure the `phrases` argument is always an `Array<string>`, where each string represents a phrase to search for.","message":"Version 4.0.0 removed support for passing an object as the `phrases` argument; it now strictly expects an `Array<string>`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your TypeScript configuration is compatible, or update `@types/nlcst` if you are using it explicitly.","message":"Version 2.0.0 introduced TypeScript types. Projects not expecting TypeScript or having conflicting type definitions might experience issues.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use ES module `import` syntax: `import { search } from 'nlcst-search'`.","cause":"Attempting to `require()` an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you are using named import: `import { search } from 'nlcst-search'`.","cause":"Incorrect import syntax (e.g., trying to use `import search from 'nlcst-search'` for a named export) or package not resolving correctly due to `exports` field issues.","error":"TypeError: search is not a function"},{"fix":"Pass `allowApostrophes` within the options object: `search(tree, phrases, handler, { allowApostrophes: true })`.","cause":"Using the old overload syntax for `allowApostrophes` in `nlcst-search@4`.","error":"TypeError: options.allowApostrophes is not a boolean"}],"ecosystem":"npm"}