NLCST Phrase Search Utility

4.0.0 · active · verified Sun Apr 19

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.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to `require()` an ESM-only package.

fix Use ES module `import` syntax: `import { search } from 'nlcst-search'`.
```
TypeError: search is not a function
```
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.

fix Ensure you are using named import: `import { search } from 'nlcst-search'`.
```
TypeError: options.allowApostrophes is not a boolean
```
cause Using the old overload syntax for `allowApostrophes` in `nlcst-search@4`.

fix Pass `allowApostrophes` within the options object: `search(tree, phrases, handler, { allowApostrophes: true })`.

Warnings

breaking Version 4.0.0 and above require Node.js 16 or newer. Older Node.js versions are not supported.
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.
breaking Since version 3.0.0, `nlcst-search` is an ESM-only package. CommonJS `require()` syntax is no longer supported for direct import.
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')`).
breaking 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.
Fix: Change `search(tree, phrases, handler, allowApostrophes)` to `search(tree, phrases, handler, {allowApostrophes: boolean})`.
breaking Version 4.0.0 removed the `PhrasesList` type; it is now simply `Array<string>`.
Fix: Update TypeScript definitions or type annotations from `PhrasesList` to `Array<string>`.
breaking Version 4.0.0 removed support for passing an object as the `phrases` argument; it now strictly expects an `Array<string>`.
Fix: Ensure the `phrases` argument is always an `Array<string>`, where each string represents a phrase to search for.
breaking Version 2.0.0 introduced TypeScript types. Projects not expecting TypeScript or having conflicting type definitions might experience issues.
Fix: Ensure your TypeScript configuration is compatible, or update `@types/nlcst` if you are using it explicitly.

Install

npm install nlcst-search npm
yarn add nlcst-search yarn
pnpm add nlcst-search pnpm

Imports

search
wrong:
```
const search = require('nlcst-search')
```
correct:
```
import { search } from 'nlcst-search'
```
The package is ESM-only since v3. Use named import syntax.
Handler
```
import type { Handler } from 'nlcst-search'
```
TypeScript type for the match handler function.
Options
```
import type { Options } from 'nlcst-search'
```
TypeScript type for the configuration object passed to `search`.

Quickstart

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.

import { search } from 'nlcst-search'
import { toString } from 'nlcst-to-string'

const tree = {
  type: 'SentenceNode',
  children: [
    {
      type: 'WordNode',
      children: [
        {type: 'TextNode', value: 'Don'},
        {type: 'PunctuationNode', value: '’'},
        {type: 'TextNode', value: 't'}
      ]
    },
    {type: 'WhiteSpaceNode', value: ' '},
    {
      type: 'WordNode',
      children: [{type: 'TextNode', value: 'do'}]
    },
    {type: 'WhiteSpaceNode', value: ' '},
    {
      type: 'WordNode',
      children: [
        {type: 'TextNode', value: 'Block'},
        {type: 'PunctuationNode', value: '-'},
        {type: 'TextNode', value: 'level'}
      ]
    }
  ]
}

console.log('Searching for "dont":')
search(tree, ['dont'], function(nodes) {
  console.log(`Found: "${toString(nodes)}"`);
});

console.log('\nSearching for "do blocklevel" with a wildcard:')
search(tree, ['do *level'], function(nodes) {
  console.log(`Found: "${toString(nodes)}"`);
});

view raw JSON →