@happyvertical/smrt-tenancy

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 4.7万

自动租户隔离和强制执行的SMRT生产准备多租房框架

中文使用文档
文档目录16 节
  1. 安装
  2. 使用量
  3. API 密码
  4. 账单关系
  5. 装饰者
  6. 背景运行器
  7. 上下文访问器
  8. 错误
  9. 截取器
  10. 框架适应器
  11. 书记官处(高级)
  12. 测试
  13. 依赖关系
  14. 许可证
  15. 授权租户/全球名单如下:
  16. 授权等级读取范围

@happyvertical/ smrt- 租借

S-m-r-t的多重租借,同时使用Async LocalStorage上下文传播,自动查询过滤,以及租户身份证人口.

安装

pnpm install @happyvertical/smrt-tenancy

使用量

import { enableTenancy, TenantScoped, tenantId, withTenant } from '@happyvertical/smrt-tenancy';
import { smrt, SmrtObject } from '@happyvertical/smrt-core';

// 1. Enable tenancy globally (once at app startup)
enableTenancy();

// 2. Mark classes as tenant-scoped
@smrt()
@TenantScoped({ mode: 'optional' })
class Document extends SmrtObject {
  @tenantId({ nullable: true })
  tenantId: string | null = null;

  title: string = '';
}

// 3. Wrap operations in tenant context
await withTenant({ tenantId: 'tenant-123' }, async () => {
  const docs = await collection.list({ where: { status: 'active' } });
  // Executes: WHERE tenant_id = 'tenant-123' AND status = 'active'
});

API 密码

账单关系

计费亲子关系与 @happyvertical/smrt-users 租户 等级。 重新指定转售者或改变谁付费并不重新识别 租户获得许可,不得移动其记录。 没有账单的房客 关系是自费的。 每个孩子最多有一个关系 billingOwnerMode 实值 self 或者说 reseller,而所有者来源于此 单行。 租户UUID在存储和查询前实现常态化为小写. 因此,转卖商可以管理一个自负盈亏的孩子.

import {
  BillingRelationshipService,
  withSystemContext,
} from '@happyvertical/smrt-tenancy';

const billing = await BillingRelationshipService.create({
  db,
  // Resolve IDs against the application's tenant directory (for example,
  // smrt-users TenantCollection). The tenancy package does not own Tenant.
  tenantExists: async (id) => Boolean(await tenants.get({ id })),
});

await withSystemContext(() =>
  billing.setRelationship({
    childTenantId: childId,
    resellerTenantId: resellerId,
    billingOwnerMode: 'reseller',
  }),
);

const ownerId = await withSystemContext(() =>
  billing.resolveBillingOwner(childId),
);
const billedChildren = await withSystemContext(() =>
  billing.listChildrenBilledTo(ownerId),
);

setRelationship() 在 a 中更改父目录和默认所有者 交易。 设置 billingOwnerMode: 'self' 保持回售父目录 让孩子自己付钱. clearRelationship() 删除亲子关系 将孩子返回到自控状态。 循环和自我父母制被拒绝. 关系变化在支持的 SQL 适配器上序列化; PostgreSQL 使用咨询交易锁。 本地 SQLite、 DuckDB 和 PostgreSQL 是 支持; 拒绝远程 LibSQL 是因为其作者无法共享 正在处理中的图锁。 新的 _smrt_billing_relationships 图表 必须通过正常程序应用 smrt db:migrate 部署流动.

生成的API,MCP,以及这些行的CLI突变表面被禁用. BillingRelationship 仅仅是因为 s -m -r -t 消费者注册,才成为根导出 从软件包根导入每个已公布的显示模式; 保存它 直接绕过服务的租户、周期和授权检查. BillingRelationshipCollection 不导出。 来电者用之. 没有 authorize 调回,突变需要明确的系统上下文. 阅读仅限于儿童、其再销售者或系统上下文;主机可能 提供 authorize 用于额外许可检查的访问。 供应租户 解决者,不取决于打电话者目前的租户范围 操作故意跨越租户,并在 主机在允许关系变化前的回调 .

装饰者

导出说明
TenantScoped(options?)阶级装饰. 模式 : 'required' (违约)或 'optional'
tenantId(options?)租户身份证栏的财产装饰

背景运行器

导出说明
withTenant(ctx, fn)向租户运行代码
withTenantSync(ctx, fn)同步变体
withSystemContext(fn)所有租户检查(管理/移民)
withSuperAdminBypass(fn)保持租户的上下文; 仅跳过租户的强制执行 allowSuperAdminBypass: true
enterTenantContext(ctx)输入上下文而不回调( 对于中间软件)

上下文访问器

导出说明
getCurrentTenant()获取当前租户上下文( 可能未定义)
getTenantId()获取租户身份字符串( 可能未定义)
requireTenant()获取租户的背景或丢弃
requireTenantId()取得租户身份证或扔出
hasTenantContext()检查租户的背景
isSystemContext()检查系统上下文
isSuperAdminBypass()检查超级管理员绕行是否活动
TenantContextAsync 本地软件集实例(先进使用)

错误

TenantContextError (缺少必要的上下文), TenantIsolationError (租户不匹配).

截取器

导出说明
enableTenancy()全球登记租户拦截器
disableTenancy()删除租户拦截器
isTenancyEnabled()检查租赁是否有效
createTenantInterceptor(options?)手动创建截取器

框架适应器

导出说明
createSvelteKitHandle(options)SvelteKit 钩子.server.ts 处理器
createExpressMiddleware(options)显示中间软件
createCliContext(options)CLI 语境 run(), (中文(简体) ), runWithTenant(), (中文(简体) ), runAsSystem()

书记官处(高级)

导出说明
isTenantScopedClass(name)检查一个班级是否为租户范围
getTenantScopedConfig(name)获得一个班级的租户配置
getAllTenantScopedClasses()列出所有登记的租户类别
registerTenantScopedClass()在程序上注册一个类
unregisterTenantScopedClass()从注册中删除一个类
clearTenantScopedRegistry()清除所有注册

测试

导出说明
setupTestTenancy(options?)启用测试租赁
resetTenancy()清理测试之间的租赁状态
createTestTenantContext(ctx, fn)在租户上下文中运行测试代码
testTenantIsolation(tenantIds, fn)核实租户之间的隔离
assertTenantContextRequired(fn)自动操作需要上下文
assertTenantIsolationViolation(fn)自动操作违反隔离

依赖关系

  • @happyvertical/smrt-core -- Smrt对象、Smrt Collection、全球干扰器
  • @happyvertical/sql -- 数据库操作
  • @happyvertical/utils -- 公用事业职能

可选同伴 : svelte, (中文(简体) ), @happyvertical/smrt-users, (中文(简体) ), @happyvertical/smrt-svelte

许可证

麻省理工学院

授权租户/全球名单如下:

withTenantGlobalRead(tenantId, callback) 许可列表 - 家庭读取名称 房客加全球一行 验证了打电话者的房客 它保存着 业务截取器的原始角色、权限和系统状态;它确实 不把普通呼叫器变成系统呼叫器。 内地租房 beforeList 把这个范围钩入每个已有的上游分支,并重新检查身份 如果巢穴代码改变租户。 点读取,原始查询和写作 保留他们的 普通警卫 能力是当地合成的,在例外情况下恢复,而且 不影响同时提出的请求。 真正的系统/超级管理呼叫者保留 已存在的绕行行为。 使用范围化的集合读取在调用回调中 .

授权等级读取范围

主机使用自有设备 TenantCollection.withTenantCatalogReadScope() 或者说 withTenantHierarchyContext() API 输入 @happyvertical/smrt-users状态 enableTenancy() 执行和肯定服务器侧授权人。 目录 范围允许自我、祖先和全球行;树下范围只允许 (原始内容存档于2013-10-12). Professioned root and genders. 参见用户包的分级租借量docs.

runTenantHierarchyReadScope() 财务报告和审定财务报表 getTenantHierarchyReadScope() 被信任 用于拥有软件包的管道,而不是主机授权入口。 那个跑者 检查执行是启用的,但不授权行为者或得出 等级。 不从请求输入构建范围 .

在范围中,只允许列入清单的租户范围 -- -- 家庭阅读 过滤器仍然缩小。 点 get() 保留主动租户的上游, 包括窝式超级管理员绕道 租户范围保存、删除和原始 拒绝询问,包括明确的未结选入。 演员开关和 巢形瞄准镜闭合失败. 回调不会改变演员/会议权限, postgreSQL RLS 仍然是另一个限制。 这些收藏钩是 不是沙盒直接数据库访问或没有租赁的模型。 在范围之外, 正常选择的超admin绕行行为不变.

消费者在启动时可以加强已经租户范围包模型 ObjectRegistry.registerOverride(qualifiedName, { tenancy: { mode: 'required' } })。 。 。 . 这项政策在重新登记后仍然有效,并优先于 可选择的直接租户登记,包括当一个后人继承 登记。 它保留申报的租地 过滤器/人口设置;不能引入租赁或改变方案。 继续 允许租房拦截器。 明确系统/超级管理员上下文 已存在的旁接语义。 见Smrt-core的消费者跑步时间限制合同.

版本与发布记录

@happyvertical/smrt-tenancy 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-tenancy 的常见问题

@happyvertical/smrt-tenancy 是什么?

自动租户隔离和强制执行的SMRT生产准备多租房框架

如何安装 @happyvertical/smrt-tenancy?

在项目目录运行 npm install @happyvertical/smrt-tenancy,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-tenancy 支持 TypeScript 吗?

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

@happyvertical/smrt-tenancy 支持 ESM 还是 CommonJS?

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

@happyvertical/smrt-tenancy 可以商用吗?

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

@happyvertical/smrt-tenancy 的下载量有多少?

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

@happyvertical/smrt-tenancy 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。