# jslt-js 中文文档

规范地址：https://npmcn.com/package/jslt-js/

版本：0\.4\.0
npm 元数据更新时间：2026-11-03T20:07:27.542Z
中文译文更新时间：2026-11-04T00:46:32.425Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/jslt-js
原文对照：https://npmcn.com/package/jslt-js/?lang=original
项目主页：https://github.com/amkraev697642/jslt-js#readme
源码仓库：https://github.com/amkraev697642/jslt-js

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

- 包体积（解压后）：541 kB，81 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-07-03T06:33:15.614Z
- 最新版本发布：2026-11-03T20:07:27.315Z
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Schibsted JSLT的JavaScript端口- JSON查询和转换语言([https://github.com/schibsted/jslt](https://github.com/schibsted/jslt)）

## 安装

```sh
npm install jslt-js
```

也可以使用：`pnpm add jslt-js`、`yarn add jslt-js`、`bun add jslt-js`

## README

# jslt-js

JavaScript端口 [JSLT](https://github.com/schibsted/jslt) - JSON查询和转换语言。 忠实地翻译Java引擎：相同的语法，相同的内置程序，相同的语义。 同构（浏览器+ Node.js），零运行时依赖。

**[在操场上试试](https://amkraev697642.github.io/jslt-playground/)** -具有语法高亮显示、错误标记和可共享链接的实时xslt编辑器。

## 对于Java开发人员

如果你知道Java xslt库，这直接映射：

| Java | JS |
| --- | --- |
| `Parser.compileString(source)` | `compile(source, name)` |
| `expression.apply(input)` | `expr.applyInput(fromJS(input))` |
| `expression.apply(variables, input)` | `expr.applyVariables(vars, fromJS(input))` |
| `new ObjectMapper().readTree(json)` | `readTree(json)` |
| 杰克逊 `JsonNode` 树 | `JsonNode` 树形（API形状相同） |
| `toJson()` | `toJS()` |

## 快速启动

```js
import { compile, fromJS, toJS } from "jslt-js";

const expr = compile(`.name + " wins"`, "example.jslt");
const result = toJS(expr.applyInput(fromJS({ name: "Alice" })));
// → "Alice wins"
```

## 安装

```sh
npm install jslt-js          # ESM (Node 18+, browsers)
```

**浏览器(经典脚本/ `file://` /没有捆绑器)：** 使用预构建的IIFE -它设置 `globalThis.JSLT` (与ESM API的形状相同，包括 `extensions`）：

```html
<script src="https://cdn.jsdelivr.net/npm/jslt-js@0.1.8/dist/jslt-bundle.js"></script>
<script>
  const expr = JSLT.compile('{"hi": .name}');
  console.log(JSLT.toJS(expr.applyInput(JSLT.fromJS({ name: "Ada" }))));
</script>
```

做。 **不** 依靠 `https://esm.sh/jslt-js@…?bundle` 对于浏览器-旧的发布被拉出 `node:crypto` 到图中。更喜欢 `dist/jslt-bundle.js` (或ESM from `jslt-js@0.1.8+`）.

CJS使用者(`require()`）：

```js
const { compile, fromJS, toJS } = require("jslt-js");
```

CJS构建在 `dist/jslt.cjs` 并通过。自动选择 `exports` 字段。

## API

### `compile(source, sourceName, options?)`

解析和编译xslt模板。返回一个 `ExpressionImpl`。

```js
const expr = compile(source, "my-transform.jslt", {
  resolver: { resolve: (name) => fs.readFileSync(name, "utf8") },
  functions: myCustomFunctions,   // array of Function objects
});
```

**选项:**

| 选项 | 类型 | 描述 |
| --- | --- | --- |
| `resolver` | `{ resolve(name): string }` | 按名称加载导入的模块 |
| `functions` | `Function[]` | 自定义/扩展函数注册 |
| `objectFilter` | `JsonFilter` 或 `string` | 哪些对象值保存在输出对象中。默认滴 `null`， `{}` 和 `[]`． 字符串是返回的JSLT表达式 `true` 来保存值，就像在Java中一样 `Parser.withObjectFilter(String)` |

#### 对象关键字过滤器

缺省情况下，对象键的值为 `null`， `{}` 或 `[]` 从输出中省略。要改变这一点，请通过 `objectFilter`：

```js
import { compile, TrueJsonFilter } from "jslt-js";

compile(source, name, { objectFilter: new TrueJsonFilter() });   // keep every key
compile(source, name, { objectFilter: "true" });                 // same, as a JSLT expression
compile(source, name, { objectFilter: ". != null" });            // drop only nulls
```

`DefaultJsonFilter`， `TrueJsonFilter`， `JsltJsonFilter` （包装编译后的表达式）和 `JsonFilter` 导出基类。

### `expr.applyInput(inputNode)`

将编译后的表达式应用于 `JsonNode` 输入。

### `expr.applyVariables(vars, inputNode)`

应用于外部变量。 `vars` 是一个纯JS对象映射变量名称 `JsonNode` 价值观:

```js
expr.applyVariables({ foo: fromJS(42) }, fromJS(null));
```

### `fromJS(value)` / `toJS(node)`

在普通JS值和内部代码之间进行转换 `JsonNode` 树。 `toJS` 安全吗？ `JSON.stringify` 大整数从 `BigInt` 当他们适合一个JS号码。

### `readTree(jsonString)`

将JSON字符串解析为a `JsonNode`． 相当于杰克逊的 `ObjectMapper.readTree` 在大多数情况下。 **注意:** 使用 `JSON.parse` 在内部，所以整值浮点数(`"42.0"`)回来 `IntNode(42)` -相同类型擦除限制 和任何JS JSON解析器一样。xslt表达式和模板不受影响，因为引擎对文字使用自己的类型感知词法分析器。

## 进口

JSLT `import` 语句通过 `resolver` 选择:

```js
// File-system resolver (Node only)
import { readFileSync } from "fs";
import { resolve, dirname } from "path";

const jsltDir = dirname(jsltFilePath);
const opts = {
  resolver: { resolve: (name) => readFileSync(resolve(jsltDir, name), "utf8") },
};
const expr = compile(source, jsltFilePath, opts);
```

## 扩展函数

注册自定义函数的方式与Java相同 `Parser.withFunctions`：

```js
const myFn = {
  getName: () => "greet",
  getMinArguments: () => 1,
  getMaxArguments: () => 1,
  call: (_input, [nameNode]) => fromJS("Hello " + nameNode.asText()),
};

const expr = compile(`. | greet(.name)`, "t.jslt", { functions: [myFn] });
```

该库附带了一个可选择的扩展包。这些都不是普通的xslt函数，也没有重用内置名称(stock `flatten()` 递归并接受一个参数stock `sum()` 抛出一个非数字，所以包的版本是 `flattened()` 和 `summed()`）：

| 函数 | 结果 |
| --- | --- |
| `flattened(a, b, ...)` | 数组参数连接起来，深一层；非数组跳过 |
| `summed(array)` | 数字元素的和； `null` If不是数组或none是数字 |
| `enumerate(array)` | `[{i, v}, ...]` |
| `range(n)` | `[0, 1, ..., n-1]`;如果缺失、非数字或非正数，则为空 `n` |
| `money(x)` | `x` 四舍五入的：四舍五入一半到2个小数点； `null` 对于一个非数字 |
| `fullName(first, last)` | `"LAST/FIRST"` 从修剪过的字符串中大写； `null` 如果两个都是空的 |
| `base64Decode(s)` | 来自Base64的UTF-8文本； `null` 对于空白或无效的输入 |
| `distinct(array)` | 没有重复的元素（JSON相等），保留第一次出现； `[]` 对于非数组 |
| `minOf(array)` / `maxOf(array)` | 最小/最大元素，忽略空值；全数字或全字符串，否则 `null` (股票 `min()`/`max()` 取两个参数) |

它们反映了Java主机的自定义函数，并根据相同的函数进行检查 `test/resources/function-parity.json`。

```js
import { extensions } from "jslt-js/extensions";

const expr = compile(source, name, { functions: extensions });
```

## CLI

```sh
npx jslt [--extensions] <transform.jslt> [input.json|-]
```

读取JSON `input.json` 或stdin。 `--extensions` 加载内置扩展包。导入解析相对于 `<transform.jslt>`的目录。

```sh
echo '{"name":"Alice"}' | jslt greet.jslt -
cat booking.json | jslt --extensions ext.jslt -
```

## 构建

```sh
npm run build     # → dist/jslt-bundle.js (browser global) + dist/jslt.cjs (Node CJS)
```

浏览器包暴露了 `globalThis.JSLT` 完整的API，包括扩展。

## 测试

```sh
npm test
```

运行单元测试和上游一致性fixture (`query-tests.json`， `function-tests.json`， `function-declaration-tests.yaml`等), 供应商从 [schibsted / jslt](https://github.com/schibsted/jslt) ——看 `test/resources/SOURCE.md` 对于确切的上游提交。

**一致性套件是此端口的主要正确性契约，而不是附带的测试。** 下面的每个文件 `src/` 是排队吗 `// Port of X.java` 翻译;“它是否不加更改地通过上游fixture”定义了与Java引擎的奇偶性，并且 这可以通过重新同步来针对未来的上游版本进行重新验证 `test/resources/`。

所有上游的合格装置都以零跳过通过。YAML fixture需要 `js-yaml` (devDependency)。

## 平价笔记

-   **数值类型**：与Jackson完全匹配 `IntNode`/`LongNode`/`BigIntegerNode`/`DoubleNode` 与十字头式 `equals` （Jackson 2.6+语义）。
-   **`parse-time`/`format-time`**：通过 `Intl.DateTimeFormat`． 支持Java SimpleDateFormat令牌(`yyyy MM dd HH mm ss S/SS/SSS z Z X`）. 返回/接受自Unix纪元以来的秒数（双精度），与Java相同。
-   **实验模块**： `import "http://jslt.schibsted.com/2018/experimental"` 开箱即用-提供 `group-by`。
-   **`FunctionWrapper`**：未移植-在Java中，它封装了静态 `Method` 通过反射。在JS中，任何带有 `{getName, getMinArguments, getMaxArguments, call}` 已经是一个xslt函数，不需要包装器。
-   **`parse-url`**：通过WHATWG URL实现。省略了 `path` 当原始URL没有显式路径（匹配）时 `java.net.URL.getPath()` 返回 `""`）.
-   从Java API延迟： `ClasspathResourceResolver`， `FileSystemResourceResolver` (使用 `resolver` 选项)，以及REPL/playground。

## 生态系统

JSLT有一个小而多样的生态系统，由几个作者创建，包括本端口的作者。状态截止到2026年10月，因此请查看每个项目的当前状态。

### 实现

| 项目 | 语言 | 笔记 |
| --- | --- | --- |
| [schibsted / jslt](https://github.com/schibsted/jslt) | Java | 参考实现和语言定义。该端口跟踪其一致性装置。 |
| **jslt-js** (回购) | JavaScript | 纯JavaScript浏览器和Node，没有本地代码；通过上游一致性套件。 |
| [jslt2](https://github.com/tonysparks/jslt2) | Java | 基于vm的实现，在上游README中提到。 |
| [jslt-node](https://www.npmjs.com/package/jslt-node) | Rust、Node绑定 | 基于Rust实现的本地N-API插件；它的README称其为概念验证。 |

### 工具和IDE插件

-   **[JSLT演示](http://www.garshol.priv.no/jslt-demo)** （[源](https://github.com/schibsted/jslt/tree/master/playground))：上游项目的游乐场，它在服务器上运行Java引擎
-   **[jslt-editor](https://github.com/amkraev697642/jslt-editor)**一个可嵌入的CodeMirror 6编辑器，具有高亮显示、补全、悬停文档、格式化和错误标记。
-   **[jslt-intellij-plugin](https://github.com/fuchsst/jslt-intellij-plugin)**： IntelliJ ide；突出显示、导航、重命名、验证和执行对话框。
-   **[jslt-lang](https://marketplace.visualstudio.com/items?itemName=jarno-rajala.jslt-lang)**： Visual Studio Code的语法高亮显示，在Visual Studio Marketplace上。
-   **[jslt-language-server](https://github.com/amkraev697642/jslt-language-server)**： LSP服务器（诊断、补全、悬停、格式化），用于任何使用LSP的编辑器。
-   **[jslt-playground](https://github.com/amkraev697642/jslt-playground)** （[打开它](https://amkraev697642.github.io/jslt-playground/))：纯JS实现，在浏览器中运行，带有用于导入、JSON或XML输入和输出以及可共享链接的选项卡。
-   **[jslt.tmbundle](https://github.com/amkraev697642/jslt.tmbundle)**: TextMate软件;突出显示，符号列表，片段，“检查语法”和“应用到JSON”操作。
-   **[Pygments](https://pygments.org/)**提供了一个JSLT词法分析器 `.jslt` 文件，Python和文档工具。
-   **[vscode-jslt](https://github.com/amkraev697642/vscode-jslt)**： Visual Studio Code和fork (Cursor, VSCodium)；高亮显示，实时错误检查，完成，悬停文档，格式化，片段和“JSLT：应用到JSON文件…”

### 与Java库一起使用

列于 [上游的自述](https://github.com/schibsted/jslt#more-information): [Apache Camel xslt组件](https://camel.apache.org/components/latest/jslt-component.html)， [Apache NiFi](https://nifi.apache.org/) 作为处理器， [Kafka Connect在Willhaben.at进行转换](https://tech.willhaben.at/kafka-connect-custom-single-message-transform-using-jslt-2fc57ae98395)， [用于业务自动化的IBM Cloud Pak](https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/21.0.x?topic=specification-event-selectors-transformers) 和 [针形事件溯源框架](https://github.com/json-event-sourcing/pincette-jes)。

### 了解更多

[关于语言设计的演讲](https://vimeo.com/289470470) （[幻灯片](https://www.slideshare.net/larsga/jslt-json-querying-and-transformation)), [一篇论文](https://arxiv.org/abs/1908.10754) 描述了Schibsted是如何使用xslt的。

## 常见问题

### jslt-js 是什么？

Schibsted JSLT的JavaScript端口- JSON查询和转换语言\(https://github\.com/schibsted/jslt）

### 如何安装 jslt-js？

在项目目录运行 npm install jslt-js，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 jslt，可以用 npx jslt 直接运行。

### jslt-js 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/jslt-js 是否存在。

### jslt-js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### jslt-js 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### jslt-js 可以商用吗？

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

### jslt-js 还在维护吗？

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