# @balena/pinejs 中文文档

规范地址：https://npmcn.com/package/%40balena/pinejs/

版本：25\.0\.8
npm 元数据更新时间：2026-11-11T01:00:39.365Z
中文译文更新时间：2026-11-11T01:01:49.842Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：4.8 MB，274 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.22\.1 \|\| ^26\.12\.1
- 运行依赖：39 个
- 首次发布：2020-06-05T12:59:53.684Z
- 最新版本发布：2026-11-11T01:00:38.923Z
- 近 30 天下载量：35455（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：2585（近 12 个月 566 个）

## 中文简介

![](https://raw.githubusercontent.com/balena-io/pinejs/master/pinejs.png)

## 安装

```sh
npm install @balena/pinejs
```

也可以使用：`pnpm add @balena/pinejs`、`yarn add @balena/pinejs`、`bun add @balena/pinejs`

## README

![](https://raw.githubusercontent.com/balena-io/pinejs/master/pinejs.png)  
  

[![npm version](https://badge.fury.io/js/@balena%2Fpinejs.svg)](https://badge.fury.io/js/@balena%2Fpinejs)

Pine.js是一个由规则驱动的精密API引擎,它使您能够在结构化的英语子集中定义规则. 使用这些规则是为了让Pine.js生成一个数据库计划以及相关的 [OData 数据](http://www.odata.org/) API (英语). 这使得快速地创建,更新和维护后端非常容易,同时将逻辑保持为易于理解的形式,同时提供更新和维护这种逻辑向前发展的能力.

《规则》在下文中作了说明 _SBVR 软件_ 格式,代表"商业词汇和商业规则的语义". SBVR提供了一种在自然语言中捕捉规格并用形式逻辑来代表它们的方法,因此它们可以被机器处理.

SBVR的基本成分如下:

-   术语 - 这些是您数据模型的原子元素,通过 `Term: [Term Name]`。一般而言,这些映射到关系数据库中的表格,或者其他表格的属性.
-   事实类型 - 这些定义 _关系_ 在不同术语之间和这些术语的属性之间,例如:. `Fact type: pilot can fly plane` 或者说 `Fact type: pilot is experienced` - 这些 _有点_ 映射到关系数据库中的字段和外键.
-   规则 - 这些定义 _逻辑限制_ sBVR和Pine.js本身最强大的方面。 规则对关系数据库的制约进行松散的映射,但将其延伸至能够穿行表格的制约,一般比数据库的制约强得多. 举个例子. `Rule: It is obligatory that each pilot can fly at least 1 plane`. SBVR规则的表达能力远远超过了简单的SQL DDL,并具有"一阶逻辑"的全能.

为了了解SBVR是如何工作的,访问 [sbvr 实验室](http://www.sbvr.co/),详细情况请查看 [SBVR 光谱](http://www.omg.org/spec/SBVR/)。 。 。 .

作为@balena/pinejs包的一部分,安装了下列工具:

-   sbvr-编译器:可以通过SBVR链将SBVR编译为SQL, eg `npx sbvr-compiler test.sbvr`
-   odata-编译器:可用于通过从OData链到SQL的OData URL编译, eg `npx odata-compiler test.sbvr /test`

两个工具都使用Pine.js的一些主要依赖:

-   抽象 sql 编译器
-   lf-to-abstract-sql 函数
-   sbvr-parser 软件
-   数据参数
-   odata-to-abstract-sql 数据转换

上面的软件包是用 `OMeta` 并被编入Javascript. 下列资源为人们更好地了解OMeta和上述依赖性奠定了良好的起点:

-   [OMeta 纸张](http://www.tinlizzie.org/~awarth/papers/dls07.pdf)
-   [OMeta 幻灯片](http://www.tinlizzie.org/ometa/dls07-slides.pdf)
-   [OMeta-js简介](http://b-studios.de/ometa-js/)
-   [OMeta 工作空间](http://tinlizzie.org/ometa-js/#OMeta_Tutorial)
-   [相关博客文章](http://codeofrob.com/entries/ometa-odata-odear---polishing-it-off.html)

下列论文也有助于理解Pine.js的主要概念:

-   [SBVR 到 SQL 编译器](http://ceur-ws.org/Vol-649/paper7.pdf)
-   [从 SBVR 规则生成 SQL 查询](http://link.springer.com/chapter/10.1007%2F978-3-642-16289-3_12)

/docs文件夹内的文件还提供了Pine.js主要概念的大致概况,特别是:

-   [文件/资料](https://npmcn.com/package/%40balena/pinejs/docs/Migrations.md):提供pinejs执行给定的SBVR模型之前执行的sql查询或Javascript函数的信息.
-   [文件/手册](https://npmcn.com/package/%40balena/pinejs/docs/Hooks.md): 当请求API呼叫时,您可以执行的功能,以便执行自定义代码.
-   [文件/项目](https://npmcn.com/package/%40balena/pinejs/docs/ProjectConfig.md):提供有关创建和配置项目的信息.
-   [文件/类型.md](https://npmcn.com/package/%40balena/pinejs/docs/Types.md):各种系统中的定义和声明类型.
-   [文件/序列-图表/](https://npmcn.com/package/%40balena/pinejs/docs/sequence-diagrams): 提供对主要进程如何执行的广阔概述,包括OData请求解析,响应处理等. (序列图可被描绘为: [互联网档案馆的存檔,存档日期2013-10-02. websequencediagrams.com](https://www.websequencediagrams.com/)(中文(简体) )

一个可以用Pine.js,其主要依赖和上述工具在balena的开发环境内进行实验.

### 从何而去

首先用 Pine.js 创建您的第一个应用程序 。 跳转到 [获得开始的引导](https://github.com/balena-io/pinejs/blob/master/docs/GettingStarted.md)。 。 。 .

## 存储文件和其他大对象

应用程序可以在两种类型中选择保存文件内容或另一个大对象: `File` 或者说 `WebResource`当使用时 `File`,PineJS使用类似二进制数据类型保存数据库中的内容 `BYTEA` 或者说 `BLOB`当使用时 `WebResource`,PineJS将二进制内容保存在外部存储服务上,然后将元数据,包括内容公开URL写入数据库. 客户端应用程序使用 `WebResource` `href` 获取内容.

请注意: `WebResource` 这项工作仍在进行中,因此有一些局限性。 例如(但不限于):

-   过滤特定文件名或大小
-   删除文件可能失败, 需要手动删除文件的存储

## 常见问题

### 如何安装 @balena/pinejs？

在项目目录运行 npm install @balena/pinejs，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sbvr-compiler、odata-compiler、abstract-sql-compiler，可以用 npx sbvr-compiler 直接运行。

### @balena/pinejs 支持 TypeScript 吗？

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

### @balena/pinejs 支持 ESM 还是 CommonJS？

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

### @balena/pinejs 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^24\.22\.1 \|\| ^26\.12\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @balena/pinejs 可以商用吗？

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

### @balena/pinejs 的下载量有多少？

根据 npm 官方下载统计，@balena/pinejs 在 2026/10/08 – 2026/11/06 这 30 天内被下载 35,455 次，日均约 1,182 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @balena/pinejs 还在维护吗？

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