# @nxgt/janus-kit 中文文档

规范地址：https://npmcn.com/package/%40nxgt/janus-kit/

版本：0\.1\.36
npm 元数据更新时间：2026-11-02T00:53:38.880Z
中文译文更新时间：2026-11-02T02:26:57.768Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40nxgt/janus-kit
原文对照：https://npmcn.com/package/%40nxgt/janus-kit/?lang=original
源码仓库：https://github.com/softistx/nxgt-janus

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

- 包体积（解压后）：129 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：mongodb \>=7\.0\.0 \<8，typescript ^6\.0\.3 \|\| ^7\.0\.0，@nxgt/janus ^0\.36\.0，@nxgt/mongo \>=0\.17\.0 \<1，@nxgt/redis \>=0\.3\.1 \<1，drizzle-orm \>=1\.0\.0-rc\.4 \<2，@nxgt/drizzle \>=0\.6\.1 \<1，@nxgt/janus-mongo ^0\.13\.0，@nxgt/janus-drizzle ^0\.12\.1，@nxgt/janus-telemetry ^0\.14\.7
- 首次发布：2026-09-26T04:59:37.123Z
- 最新版本发布：2026-11-02T00:53:38.701Z
- 已发布版本数：37（近 12 个月 37 个）

## 中文简介

@nxgt/janus连接在一个调用中，每个数据库有一个子路径——PostgreSQL通过Drizzle， MongoDB——在Redis中有会话，遥测，健康检查和关闭

## 安装

```sh
npm install @nxgt/janus-kit
```

也可以使用：`pnpm add @nxgt/janus-kit`、`yarn add @nxgt/janus-kit`、`bun add @nxgt/janus-kit`

## README

# @nxgt / janus-kit

[`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus) 一通电话： PostgreSQL的用户和权限 [`@nxgt/janus-drizzle`](https://www.npmjs.com/package/@nxgt/janus-drizzle) 或者在MongoDB中 [`@nxgt/janus-mongo`](https://www.npmjs.com/package/@nxgt/janus-mongo)，会话和一次性令牌 复述,通过 [`@nxgt/janus-redis`](https://www.npmjs.com/package/@nxgt/janus-redis)遥测，健康检查 最后。

```ts
import { janus, scryptHasher } from '@nxgt/janus';
import { defineModel, permissions } from '@nxgt/janus/permissions';
import { connectKit, defineConfig } from '@nxgt/janus-kit/drizzle';
import { z } from 'zod';

export const kit = await connectKit(
  defineConfig({
    postgres: { url: process.env.JANUS_DATABASE_URL! }, // Janus's own database
    redis: { url: process.env.REDIS_URL! },             // optional: sessions and tokens
    telemetry: true,                                    // optional: @nxgt/janus-telemetry
    auth: (adapters) =>
      janus({
        user: z.object({ email: z.email(), name: z.string() }),
        password: { login: 'email' },
        hasher: scryptHasher(),
        ...adapters, // { store, relations }
      }),
    access: ({ relations, auth }) =>
      permissions({
        model: defineModel({
          subjects: auth.types,
          types: {
            document: {
              related: { owners: ['user'], viewers: ['user'] },
              permits: { view: ['owners', 'viewers'] },
            },
          },
        }),
        store: relations,
      }),
  }),
);

const current = await kit.auth.authenticate(request); // null when signed out
if (current) await kit.access.can(current.user, 'view', { type: 'document', id: 'd1' });
const health = await kit.ping(); // { ok, postgres, redis } — never throws
await kit.close();
```

**你还在写 `janus()` 和 `permissions()`**，在两个函数中，所以 它们推断的每个类型都是在你写它们的地方推断出来的： `kit.auth.signIn` 获取您的登录字段， `kit.access.can` 你的权限。工具包交给他们 存储，打开和关闭连接，并在启动时检查什么 否则第一次登录就会失败。

> **0\. x。** 一个小版本仍然可能改变表面；更新日志告诉我们该怎么做。

## 安装

```sh
bun add @nxgt/janus-kit @nxgt/janus @nxgt/redis zod
bun add @nxgt/janus-drizzle @nxgt/drizzle drizzle-orm   # for @nxgt/janus-kit/drizzle
bun add @nxgt/janus-mongo @nxgt/mongo mongodb           # for @nxgt/janus-kit/mongo
bun add @nxgt/janus-telemetry @nxgt/telemetry           # only for telemetry: true
bun add -d @types/bun                                   # the kit's types name Bun's RedisOptions
```

所需的对等体，无论子路径：

-   `@nxgt/janus`；
-   `@nxgt/redis` `>=0.3.1 <1`, `zod` 这是它所需要的，即使有 数据库中的会话：工具包的类型命名其连接；
-   `typescript` 6或7。

同行的 `@nxgt/janus-kit/drizzle` -可选的 `package.json`，所以。 另一个子路径上的应用程序不安装它们，但这是必需的 一:

-   `@nxgt/janus-drizzle`：您的模式文件导入 `defineJanusTables` 从它 要创建表，必须与工具包的store查询相同的定义；
-   `@nxgt/drizzle` `>=0.6.1 <1` 和 `drizzle-orm` 1.0(从 `1.0.0-rc.4`), PostgreSQL。

同行的 `@nxgt/janus-kit/mongo`，可选方式相同：

-   `@nxgt/janus-mongo`： `syncMongoAdapter` 创建集合和 Kit的store必须查询相同的定义；
-   `@nxgt/mongo` `>=0.17.0 <1` 和 `mongodb` 7.

这个 `@nxgt/*` 在每个CI上测试楼层，而不是声明楼层：在楼层作业中 运行，套件的mongo规格和类型检查运行 `@nxgt/mongo` 0.17.0, 它的整个套件和类型检查 `@nxgt/redis` 0.3.1, `@nxgt/drizzle` 0.6.1 和 `@nxgt/telemetry` 0.2.1.

`@nxgt/janus-telemetry` 是否可选对等体，仅在何时加载 `telemetry` 是 `true`;它需要 `@nxgt/telemetry` `>=0.2.1 <1` 作为自己的同伴。 `@nxgt/janus-redis` 是一个依赖项：您的代码永远不会导入它。

它继续运行 **包子** 只有：工具包打开PostgreSQL在Bun的 `SQL` 和复述, 在包的 `RedisClient`． 它需要PostgreSQL 15或更高版本，或MongoDB 副本集，以及Redis 7.0或更高版本。就像 `@nxgt/janus`，它期望 `"moduleResolution": "bundler"`.

## 子路径

**一个工具包，每个数据库一个子路径。** 这个包裹有 **没有根条目**,所以 导入将数据库命名为： `import … from '@nxgt/janus-kit'` 失败与 `TS2307`． 复述、遥测 `ping` 和 `close` 子路径是相同的吗 你使用。

| 子路径 | 数据库 | 数据库键 | 什么 `connectKit` 支票 |
| --- | --- | --- | --- |
| `@nxgt/janus-kit/drizzle` | PostgreSQL,通过 `@nxgt/janus-drizzle` | `postgres` | 雅努斯的五张表是存在的 |
| `@nxgt/janus-kit/mongo` | MongoDB,通过 `@nxgt/janus-mongo` | `mongo` | Janus的四个集合及其索引存在；其他任何不同都是警告 |

在MongoDB上，上面的例子只改变了第一行：

```ts
import { connectKit, defineConfig } from '@nxgt/janus-kit/mongo';

export const kit = await connectKit(
  defineConfig({
    mongo: { url: process.env.JANUS_MONGO_URL! }, // mongodb://…/janus — the path names the database
    redis: { url: process.env.REDIS_URL! },
    auth: (adapters) => janus({ /* … */ ...adapters }),
  }),
);
kit.db; // the Db; (await kit.ping()).mongo
```

## API

两个子路径导出相同的名称；它们的不同之处在于数据库键和 什么 `db` 是多少。

| 出口 | 它是什么？ |
| --- | --- |
| `defineConfig(config)` | 检查配置并回答，冻结。它不连接任何东西，也不读取任何环境变量。怎么扔了一个 `TypeError` 这里是应用程序开始的地方。 |
| `connectKit(config)` | 再次检查配置，打开数据库和Redis，检查Janus的表或集合，构建 `auth` 和 `access`，并回答了问题。失败，并伴有 `Error` 命名要做什么- a `TypeError` 对于它无法读取的URL -关闭它打开的内容。 |
| `Kit` | 什么 `connectKit` 答案: `auth`； `access` 当配置; `db`例如，Drizzle实例或MongoDB `Db`； `redis`，连接或 `undefined`； `ping(options?)`； `close()`;和 `[Symbol.asyncDispose]`. |
| `KitConfig`， `RedisConfig`, `PostgresConfig` 从 `/drizzle` 或者 `MongoConfig` 从 `/mongo` | 配置的类型。 |
| `Adapters`， `AccessWiring` | 什么 `auth` 和 `access` 给出: `{ store, relations }`, `{ relations, auth }`. |
| `Health`， `PingResult` | 什么 `ping` 答案: `{ ok, postgres, redis? }` 或者 `{ ok, mongo, redis? }`,每个 `{ ok: true, latencyMs }` 或者 `{ ok: false, error }`. |

## 配置

| 关键 |  |  |
| --- | --- | --- |
| `postgres` | 上需要 `/drizzle` | `{ url }` 在Janus数据库中，a `postgres://` 或者 `postgresql://` URL，工具包打开和关闭它；或 `{ db }`你打开的Drizzle实例 **从来没有关闭** 靠工具箱。 `tables`：当表在自己的PostgreSQL模式中时，你的模式文件导出什么。 |
| `mongo` | 上需要 `/mongo` | `{ url, clientOptions? }` 在Janus数据库中，a `mongodb://` 或者 `mongodb+srv://` URL，其路径命名工具包打开时使用的数据库 `serverSelectionTimeoutMS: 5_000` 和关闭;或 `{ db }`,一个 `Db` 你打开, **从来没有关闭** 靠工具箱。 |
| `redis` | 可选 | `{ url, prefix?, clientOptions? }`，这是工具箱打开的地方 `enableOfflineQueue: false` 和关闭;或 `{ connection, prefix? }`，它永远不会关闭。如果没有，会话和令牌将留在数据库中。 |
| `telemetry` | 可选 | `true` 包装 `auth` 与 `instrumentJanus` 和 `access` 与 `instrumentPermissions`. |
| `auth` | 要求 | `(adapters) => janus({ …, ...adapters })`. |
| `access` | 可选 | `({ relations, auth }) => permissions({ model, store: relations })`． 缺席，工具包没有 `access`, `kit.access` 不编译。 |

`adapters` 是 `{ store, relations }`：来自数据库的用户、会话和 当连接时，从Redis中获取令牌，以及关系存储，因此删除用户 删除所有命名它们的元组。 [配置指南](https://npmcn.com/package/%40nxgt/janus-kit/docs/guide/configuration.md) 有每个钥匙的详细信息。

## 陷阱

-   **雅努斯的表格来自你的迁移。** `connectKit` 检查所有 其中五个已经存在，但拒绝以其他方式开始，并指名道姓。创建它们 drizzle-kit,从 `defineJanusTables()`,因为 [`@nxgt/janus-drizzle`的指导](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-drizzle/docs/guide/database.md) 所示。
-   **在他们自己的PostgreSQL模式中，pass `postgres.tables`.** 没有它, 工具包查找，商店查询， `users` 在连接中 `search_path`： `public`，其中您的应用程序可能有 `users` 它的 自己的。
-   **Janus的收藏来自 `syncMongoAdapter`**，部署步骤。 `connectKit` 将它们与 `@nxgt/janus-mongo`的定义，写作 什么都没有。丢失的集合或索引拒绝启动：MongoDB会 在第一次写入时创建一个缺失集合 **没有唯一索引 在登录**． 一个验证器、一个选项或一个索引的选项只有警告不同 （`JANUS_KIT_COLLECTIONS_DRIFTED`)，因此回滚仍然开始。
-   **`kit.auth.collectExpired()` 答案 `UNSUPPORTED` 在 `/mongo`**：一个TTL 索引删除失效的会话和令牌。在PostgreSQL上安排它 只有，它删除了这两个。
-   **路径中没有数据库的MongoDB URL使用 `test`**，司机的。 违约。在URL中命名Janus的数据库： `mongodb://…/janus`.
-   **如果MongoDB在5秒后没有回答，则会失败**测量的；测量的 装备的 `serverSelectionTimeoutMS`在美国，司机的工资是30美元。一个请求 在复制集期间，选举可以失败而不是等待；通过 `clientOptions: { serverSelectionTimeoutMS }` 等待更长时间。
-   **Redis在启动时关闭，大约需要31秒才能失败**测量: Bun的客户端重新尝试它的第一个连接。在运行时，工具包 `enableOfflineQueue: false` 使中断立即失败。
-   **你交什么，你就交什么。** 一、 `db` 或者一个 `connection` 从 配置是开放的 `kit.close()`.
-   **`@nxgt/mongo` 每个URL共享一个客户端**,因为 `@nxgt/redis` 下面: 用其他选项连接到Janus的MongoDB URL被拒绝。
-   **`@nxgt/redis` 每个URL共享一个客户端。** 如果您的应用程序连接 到相同的Redis URL， `connectRedis` 拒绝的 第二。给Janus一个自己的URL，比如另一个数据库号，或者 通过 `{ connection }`.

## 文档

-   [指南](https://npmcn.com/package/%40nxgt/janus-kit/docs/README.md)：每个键的配置，健康检查； 和关闭
-   [故障排除](https://npmcn.com/package/%40nxgt/janus-kit/docs/troubleshooting.md)：查看您看到的错误信息
-   [路线图](https://npmcn.com/package/%40nxgt/janus-kit/docs/roadmap.md)下一步是什么，以及什么是没有计划的

## 类型安全，计数

16个貌似合理的错误被编译器拒绝了，每个错误都有一个 `@ts-expect-error` 箱子：10英寸 `test/types/kit.ts`在PostgreSQL上，

-   `kit.access` 在没有配置的工具包上 `access`；
-   用户类型 `auth` 没有；
-   模型不具备的权限；
-   两个 `postgres.url` 和 `postgres.db`；
-   两个 `redis.url` 和 `redis.connection`；
-   `redis.clientOptions` 旁边一个 `connection` 已经打开,
-   `postgres.schema` 而不是里面的表格；
-   没有的配置 `auth`；
-   `postgres` 既无 `url` 也不 `db`；
-   `telemetry` 作为一个字符串，作为一个环境变量读；

6英寸 `test/types/mongo.ts`， over MongoDB：

-   `kit.access` 在没有配置的工具包上 `access`；
-   `ping()`的 `postgres` 在MongoDB工具包上，它回答 `mongo`；
-   两个 `mongo.url` 和 `mongo.db`；
-   `mongo.clientOptions` 旁边一个 `Db` 其客户端已经打开；
-   这个 `postgres` 给MongoDB工具包的关键；
-   `mongo` 既无 `url` 也不 `db`.

## 执照

麻省理工学院

## 常见问题

### @nxgt/janus-kit 是什么？

@nxgt/janus连接在一个调用中，每个数据库有一个子路径——PostgreSQL通过Drizzle， MongoDB——在Redis中有会话，遥测，健康检查和关闭

### 如何安装 @nxgt/janus-kit？

在项目目录运行 npm install @nxgt/janus-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^6\.0\.3 \|\| ^7\.0\.0）、@nxgt/janus（^0\.36\.0）、@nxgt/redis（\>=0\.3\.1 \<1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @nxgt/janus-kit 支持 TypeScript 吗？

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

### @nxgt/janus-kit 支持 ESM 还是 CommonJS？

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

### @nxgt/janus-kit 可以商用吗？

@nxgt/janus-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @nxgt/janus-kit 还在维护吗？

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