Registry / data / nlcst-search

nlcst-search

library4.0.0jsnpmunverified

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.

data ai-ml

npm install nlcst-search

github ↗package ↗

INSTALL

IMPORT

SIG · NLCST-SEARCH

nlcst-search

datajavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { search } from 'nlcst-search'

✗ const search = require('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`.

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)}"`); });

Debug

Known issues

breakingVersion 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.

affects: >=4.0.0

breakingSince 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')`).

affects: >=3.0.0

breakingIn 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})`.

affects: >=4.0.0

breakingVersion 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>`.

affects: >=4.0.0

breakingVersion 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.

affects: >=4.0.0

breakingVersion 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.

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

fix

Use ES module `import` syntax: `import { search } from 'nlcst-search'`.

TypeError: search is not a function

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

Using the old overload syntax for `allowApostrophes` in `nlcst-search@4`.

fix

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

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

nlcst-to-stringrequiredCommonly used to convert matched NLCST nodes back into readable strings in examples and applications.

nlcst-normalizerequiredThe `search` function internally uses `nlcst-normalize` for processing patterns, and its options (like `allowApostrophes`, `allowDashes`) are directly passed to it.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/nlcst-search ↗

packagehttps://www.npmjs.com/package/nlcst-search ↗