Registry / devops / broccoli-persistent-filter

broccoli-persistent-filter

library3.1.3jsnpmunverified

A base class for Broccoli plugins that map input files to output files with a persistent disk cache. Current stable version is 3.1.3 (released 2021). It extends the Broccoli filter concept by caching processed results across builds, enabling fast restarts. Key differentiators: built-in async/concurrency support, dependency invalidation tracking, and configurable input/output encoding. Unlike plain broccoli-filter, it persists cached results to disk to avoid reprocessing unchanged files between builds, making it suitable for large projects with slow transforms.

devops testing

npm install broccoli-persistent-filter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BROCCOLI-PERSISTEN

broccoli-persistent-filter

devopsjavascriptv3.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Filter

✓ import Filter from 'broccoli-persistent-filter'

✗ const Filter = require('broccoli-persistent-filter').Filter

The package exports a single default export (the Filter class). Named export 'Filter' does not exist.

FilterOptions

✓ import type { FilterOptions } from 'broccoli-persistent-filter'

✗ import { FilterOptions } from 'broccoli-persistent-filter'

FilterOptions is a TypeScript type, not a runtime export. Use `import type` to avoid runtime errors.

Filter (CommonJS)

✓ const Filter = require('broccoli-persistent-filter')

✗ const { Filter } = require('broccoli-persistent-filter')

CommonJS require returns the class directly, not a named export.

Shows how to subclass Filter, implement processString, and use constructor options to transform .txt files to .js.

Debug

Known issues

breakingIn version 3.x, the `persist` option no longer exists; persistent caching is always enabled.

fix

Remove any `persist` option from constructor. Caching is automatic.

affects: >=3.0.0

gotchaThe `processString` method must return a string or an object with an `output` property. Returning an object without `output` will cause undefined content.

fix

Ensure your object has an `output` property: `return { output: transformedContent };`

affects: >=1.0.0

deprecatedThe `Cache` class and related cache management APIs (clearCache, etc.) are deprecated and may be removed in future versions.

fix

Avoid directly interacting with the cache. Rely on built-in persistent caching.

affects: >=2.0.0

gotchaUsing `async: true` with `concurrency` option requires `processString` to return a Promise. Older code returning synchronous values may cause undefined behavior.

fix

Wrap synchronous return values in `Promise.resolve()` or make `processString` async.

affects: >=3.0.0

breakingNode.js versions lower than 10 are not supported starting from version 3.0.0.

fix

Upgrade Node.js to 10.x or newer.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Class extends value undefined is not a constructor or null

CommonJS require incorrectly destructured (importing { Filter } instead of Filter directly).

fix

Change to const Filter = require('broccoli-persistent-filter');

Error: 'processString' must return a string or an object with an 'output' property.

processString returned an object without an 'output' property.

fix

Add 'output' property to the returned object: return { output: myContent };

Error: The 'extensions' option is required

You did not provide a list of extensions to process, or the provided list is empty.

fix

Add extensions option: 'extensions': ['js', 'ts']

Upgrade

Version history

3.1.3latest on npm

Audit

Dependencies

broccoli-pluginrequiredbroccoli-persistent-filter extends broccoli-plugin for the core Broccoli plugin infrastructure (constructor, input/output paths, etc.)

fs-tree-diffrequiredUsed internally to compute file system changes (patch tree) for cache invalidation

hash-for-deprequiredUsed to hash dependencies for cache key generation

symlink-or-copyrequiredUsed to create symlinks or copy files for cache restoration

debugoptionalUsed for debug logging (enabled via DEBUG=broccoli-persistent-filter)

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stefanpenner/broccoli-persistent-filter ↗

packagebroccoli-persistent-filter ↗

homepagehttps://github.com/stefanpenner/broccoli-persistent-filter#readme ↗