# @filter-enginez/core 中文文档

规范地址：https://npmcn.com/package/%40filter-enginez/core/

版本：0\.2\.0
npm 元数据更新时间：2026-11-01T00:06:29.277Z
中文译文更新时间：2026-11-01T03:52:25.788Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40filter-enginez/core
原文对照：https://npmcn.com/package/%40filter-enginez/core/?lang=original
项目主页：https://filterenginez.com/
源码仓库：https://github.com/mlilli/filter-enginez

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：879 kB，218 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：roaring-wasm ^1\.1\.0
- 首次发布：2026-10-13T05:01:15.392Z
- 最新版本发布：2026-11-01T00:06:28.901Z
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

面向TypeScript的分面搜索和过滤引擎：规则，和/或/不组合，过滤器组，JSON配置，撤销/重做devtools，咆哮位图，r树，贝叶斯建议和MinHash相似度加速。在浏览器、Node和Web work中运行

## 安装

```sh
npm install @filter-enginez/core
```

也可以使用：`pnpm add @filter-enginez/core`、`yarn add @filter-enginez/core`、`bun add @filter-enginez/core`

## README

# @filter-enginez /核心

过滤器引擎-规则，组成，devtools，内部存储，动作日志，四种命名的CS算法（咆哮） 位图，r树，贝叶斯共生，MinHash + LSH)。同构：运行在浏览器、Node、Cloudflare Workers、Deno、 运行时。

## 安装

```bash
pnpm add @filter-enginez/core
```

位图加速使用 `roaring-wasm`，一个可选的对等依赖项：core不需要它就可以运行，而安装core则不能 安装它。要启用位图，请将其安装在core旁边并等待 `initializeBitmapAcceleration()` 一次启动(见 快速入门)：

```bash
pnpm add roaring-wasm
```

没有它, `initializeBitmapAcceleration()` 拒绝。 `FilterEngineModeError` 谁的代码是 `MODE_ACCELERATION_PEER_MISSING` 它的信息是安装命令，引擎继续过滤它的 具有相同结果的谓词路径。引擎中没有任何东西为你调用它，所以从不调用的应用程序不需要任何东西 更多。

Sub-exports: `@filter-enginez/core/keyboard/browser`， `@filter-enginez/core/similarity`， `@filter-enginez/core/storage/browser`， `@filter-enginez/core/suggestions`.

`similarity` 和 `suggestions` 单独的入口点是故意的：导入它们是可选择的，所以不导入它们 使他们的字节远离你的构建。

## 快速启动

```ts
import { createFilterEngine, initializeBitmapAcceleration, InSetRule, RangeRule } from '@filter-enginez/core';
import { type Wine, wines } from '@filter-enginez/mock-data/wine';

// Await this once at startup, with roaring-wasm installed. It loads roaring-wasm, which an app that
// never calls it does not bundle. The Roaring-Bitmap path stays OFF until it resolves —
// silently, so an app whose WASM asset is still in flight keeps working rather than
// throwing. Skipping it costs roughly 40x on a 10k corpus and raises no warning.
await initializeBitmapAcceleration();

const engine = createFilterEngine<Wine>({ sourceData: wines });

engine.addRule('price', new RangeRule('priceUsd', { min: 20, max: 60 }));
engine.addRule('varietal', new InSetRule('varietal', ['Merlot', 'Syrah']));

engine.getResults(); // every wine passing BOTH rules
engine.getResultCount(); // cheaper when you only need the number
```

规则和共同。将某一方面的规则命名为一组(`engine.addGroup({ id, filterIds })`）; 对于任何 其他OR / NOT，与 `and` / `or` / `not` 并将结果传递给 `engine.setExpression(...)`。位图路径 用于连词，所以是一个表达式或an `'or'` Group是按项计算的，结果是一样的。

## 错误

引擎产生的每一个错误都是a `FilterEngineError` 具有只读、机器可读的特点 `code`。四个子类名称 〇家庭 `FilterEngineConfigError` （配置文档、选项对象或绑定无效）， `FilterEngineRuleError` (规则类或序列化规则不可用； `RuleRegistryError` 扩展), `FilterEngineModeError` (例如 `addRule()` 当设置表达式时)和 `FilterEngineDestroyedError` 之后的任何方法 `destroy()`）. 一个包裹 失败是标准 `cause`。代码联合也被导出(`FilterEngineErrorCode` 每班一个)，所以a `switch` 在 `error.code` 检查穷竭性。

```ts
import { createFilterEngine, type FilterEngineConfig, FilterEngineError } from '@filter-enginez/core';

declare const sharedConfig: FilterEngineConfig;

const engine = createFilterEngine({ sourceData: [] });

try {
  engine.loadConfig(sharedConfig);
} catch (error) {
  if (!(error instanceof FilterEngineError)) {
    throw error;
  }
  console.warn(`Ignoring a config the engine refused: ${error.code}`, error.cause);
}
```

完整的代码表，以及每次抛出时的代码表 `docs/architecture.md` §2.5引擎存储库。

## 文档

的引擎存储库中有消费者指南 `docs/guides/`：

-   `extending_rules.md` -编写自定义 `FilterRule` 在序列化中幸存下来
-   `json_config.md` -将过滤器声明为数据，以及为什么该格式可以安全地从租户接受
-   `acceleration_tuning.md` -这五个是什么？ `acceleration` 切换是值得的，有衡量的
-   `worker_offload.md` -在Web Worker中运行引擎

项目之家，有六个现场演示： [https://filterenginez.com](https://filterenginez.com/)。文档站点: [https://docs.filterenginez.com](https://docs.filterenginez.com/).

apache - 2.0。看到 `LICENSE.md` 和 `NOTICE.md`，两者都包含在此包中。

## 常见问题

### @filter-enginez/core 是什么？

面向TypeScript的分面搜索和过滤引擎：规则，和/或/不组合，过滤器组，JSON配置，撤销/重做devtools，咆哮位图，r树，贝叶斯建议和MinHash相似度加速。在浏览器、Node和Web work中运行

### 如何安装 @filter-enginez/core？

在项目目录运行 npm install @filter-enginez/core，或使用 pnpm add / yarn add / bun add。

### @filter-enginez/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @filter-enginez/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @filter-enginez/core 可以商用吗？

@filter-enginez/core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @filter-enginez/core 还在维护吗？

最新版本 0\.2\.0 发布于 2026/11/01（2 天前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。