# @classytic/primitives 中文文档

规范地址：https://npmcn.com/package/%40classytic/primitives/

版本：0\.37\.0
npm 元数据更新时间：2026-11-06T08:08:04.351Z
中文译文更新时间：2026-11-09T23:58:34.150Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40classytic/primitives
原文对照：https://npmcn.com/package/%40classytic/primitives/?lang=original
项目主页：https://www.npmjs.com/package/@classytic/primitives
源码仓库：https://github.com/classytic/primitives

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

- 包体积（解压后）：864 kB，155 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-04-21T15:25:01.862Z
- 最新版本发布：2026-11-06T08:08:04.129Z
- 近 30 天下载量：3403（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

框架-不可知类型Script原始相通于经典套件——钱,事,花相相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相.

## 安装

```sh
npm install @classytic/primitives
```

也可以使用：`pnpm add @classytic/primitives`、`yarn add @classytic/primitives`、`bun add @classytic/primitives`

## README

# @ 经典/原始

[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)

框架-不可知类型Script原始相通 Classytic 包共享. 零运行时间依赖关系. 仅限无害环境管理。 节点22+.

这些是每个经典套件的共同点: `Money`, (中文(简体) ), `DomainEvent`, (中文(简体) ), `OperationContext`,多形态的参考文献。 当a 软件包重复其中的一个形状, 它漂移—— 这个软件包存在所以它 没有.

> **0.3.0)的加农合同搬迁.** 三个模块搬出 `@classytic/repo-core` 因此,包和弧 看见一个真理的来源 而不是 两个:
> 
> -   **倾斜** (单位:千美元)`OffsetPaginationResult`, (中文(简体) ), `KeysetPaginationResult`, (中文(简体) ), `AggregatePaginationResult`, (中文(简体) ), `PaginationResult`, (中文(简体) ), `toCanonicalList()`页:1 `@classytic/repo-core/pagination`。 。 。 .
> -   **租户配置** (单位:千美元)`TenantConfig`, (中文(简体) ), `TenantStrategy`, (中文(简体) ), `TenantFieldType`, (中文(简体) ), `resolveTenantConfig`, (中文(简体) ), `DEFAULT_TENANT_CONFIG`, (中文(简体) ), `ResolvedTenantConfig`页:1 `@classytic/repo-core/tenant`蒙戈基特和斯克利特基特的电影 `MultiTenantOptions extends Pick<TenantConfig, ...>`。 。 。 .
> -   **错误合同** (单位:千美元)`HttpError` 可抛出, `ErrorContract` 电线形状, `ErrorDetail`, (中文(简体) ), `ErrorCode`, (中文(简体) ), `ERROR_CODES`, (中文(简体) ), `toErrorContract()`, (中文(简体) ), `statusToErrorCode()`页:1 `@classytic/repo-core/errors`。 。 。 . `ArcError implements HttpError`。 。 。 .
> 
> 事情在这里. `@classytic/primitives/events` 仍为克尼克 来源 `EventMeta`, (中文(简体) ), `DomainEvent`, (中文(简体) ), `EventHandler`, (中文(简体) ), `EventLogger`, (中文(简体) ), `EventTransport`, (中文(简体) ), `DeadLetteredEvent`, (中文(简体) ), `PublishManyResult`, (中文(简体) ), `createEvent`, (中文(简体) ), `createChildEvent`, (中文(简体) ), `matchEventPattern`弧 2.12 只再出口 运行时间 `MemoryEventTransport`。 。 。 .

## 安装

```bash
npm install @classytic/primitives
```

## 使用

偏爱 **子路径导入** ——每个关切都是自己的入门点,类型去除 在编译时间,运行时间的帮助是很小的.

```ts
import { addMoney, fromMajor, type Money } from '@classytic/primitives/money';
import { createEvent, type DomainEvent, type EventTransport } from '@classytic/primitives/events';
import type { OperationContext } from '@classytic/primitives/context';
import { allocate, type SplitResult } from '@classytic/primitives/split-allocation';
// Tenant config, error contracts, and pagination now live in repo-core:
import { resolveTenantConfig, type TenantConfig } from '@classytic/repo-core/tenant';
import type { HttpError, ErrorContract } from '@classytic/repo-core/errors';
import type {
  OffsetPaginationResult, KeysetPaginationResult, AggregatePaginationResult,
} from '@classytic/repo-core/pagination';
```

有故意的,有故意的,没有故意的 **无根管** - 一个管子迫使节点无害环境管理 加载器和 TypeScript 编译器在单一方便下行走每个模块 导入,可使 CI 慢化,并将未使用的代码拖入消费者的图表。 使用 仅导入子路径 .

## 里面的东西

| 子路径 | 船舶 |
| --- | --- |
| `/money` | `Money`, (中文(简体) ), `fromMajor`, (中文(简体) ), `toMajor`, (中文(简体) ), `addMoney`, (中文(简体) ), `subtractMoney`, (中文(简体) ), `multiplyMoney`, (中文(简体) ), `sumMoney`, (中文(简体) ), `equalsMoney`, (中文(简体) ), `compareMoney`, (中文(简体) ), `negateMoney`, (中文(简体) ), `absMoney`, (中文(简体) ), `isMoney`, (中文(简体) ), `CurrencyMismatchError` |
| `/currency` | `CurrencyCode` 品牌, `CURRENCIES`, (中文(简体) ), `MINOR_UNIT_FACTOR`, (中文(简体) ), `minorUnitFactor`, (中文(简体) ), `isKnownCurrency`, (中文(简体) ), `toCurrencyCode`, (中文(简体) ), `currencyCode`, (中文(简体) ), `isCurrencyCode`, (中文(简体) ), `InvalidCurrencyCodeError`, (中文(简体) ), `CurrencyMismatchError`, (中文(简体) ), `FxSnapshot`, (中文(简体) ), `convertWithSnapshot`, (中文(简体) ), `reverseWithSnapshot`, (中文(简体) ), `FxRounding` |
| `/address` | `Address`, (中文(简体) ), `ContactAddress`, (中文(简体) ), `GeoPoint`, (中文(简体) ), `GeoJsonPoint`, (中文(简体) ), `toGeoJsonPoint`, (中文(简体) ), `fromGeoJsonPoint` |
| `/period` | `DateRange`, (中文(简体) ), `Period`, (中文(简体) ), `isDateRange`, (中文(简体) ), `isWithin`, (中文(简体) ), `rangeDurationMs`, (中文(简体) ), `rangesOverlap`, (中文(简体) ), `DateRangeError` —— 说 **外加时区分辨率**数字 : `resolvePeriod`, (中文(简体) ), `resolveDay`, (中文(简体) ), `resolveMonth`, (中文(简体) ), `resolveQuarter`, (中文(简体) ), `resolveYear`, (中文(简体) ), `resolveDateSpan`, (中文(简体) ), `dayStart`, (中文(简体) ), `periodOf`, (中文(简体) ), `parsePeriod`, (中文(简体) ), `formatPeriod`, (中文(简体) ), `granularityOf`, (中文(简体) ), `periodTimeZone`, (中文(简体) ), `inclusiveEnd`, (中文(简体) ), `PeriodError` |
| `/reference` | `ExternalRef`, (中文(简体) ), `ObjectIdLike`, (中文(简体) ), `IdLike`, (中文(简体) ), `DocumentRef`, (中文(简体) ), `idToString`, (中文(简体) ), `isExternalRef` |
| `/context` | `OperationContext`, (中文(简体) ), `ActorRef` |
| `/events` | `DomainEvent`, (中文(简体) ), `EventMeta`, (中文(简体) ), `EventHandler`, (中文(简体) ), `EventLogger`, (中文(简体) ), `EventTransport`, (中文(简体) ), `DeadLetteredEvent`, (中文(简体) ), `PublishManyResult`, (中文(简体) ), `createEvent`, (中文(简体) ), `createChildEvent`, (中文(简体) ), `matchEventPattern` |
| `/result` | `Result<T, E>`, (中文(简体) ), `ok`, (中文(简体) ), `err`, (中文(简体) ), `isOk`, (中文(简体) ), `isErr`, (中文(简体) ), `mapResult`, (中文(简体) ), `mapError`, (中文(简体) ), `unwrap` |
| `/brand` | `Brand<T, B>`, (中文(简体) ), `Prettify`, (中文(简体) ), `DeepPartial`, (中文(简体) ), `DeepReadonly`, (中文(简体) ), `RequireKeys`, (中文(简体) ), `OptionalKeys`, (中文(简体) ), `Nullable`, (中文(简体) ), `KeysMatching`, (中文(简体) ), `NonEmptyArray` |
| `/split-allocation` | `allocate`, (中文(简体) ), `isBalanced`, (中文(简体) ), `SplitAllocationError`, (中文(简体) ), `SplitMethod`, (中文(简体) ), `SplitSubject`, (中文(简体) ), `SplitPart`, (中文(简体) ), `SplitResult` |
| `/idempotency` | `decideClaim`, (中文(简体) ), `completeClaim`, (中文(简体) ), `renewLease`, (中文(简体) ), `identityKey`, (中文(简体) ), `sameIdentity`, (中文(简体) ), `fingerprintRequest`, (中文(简体) ), `newLeaseToken`, (中文(简体) ), `isLeaseExpired`, (中文(简体) ), `holdsLease`, (中文(简体) ), `isInFlight`, (中文(简体) ), `DEFAULT_LEASE_MS`, (中文(简体) ), `IdempotencyClaim`, (中文(简体) ), `ClaimOutcome`, (中文(简体) ), `ClaimResult`, (中文(简体) ), `ClaimState`, (中文(简体) ), `IdempotencyIdentity`, (中文(简体) ), `IdempotencyError` |
| `/approval` | `createChain`, (中文(简体) ), `applyDecision`, (中文(简体) ), `skipStep`, (中文(简体) ), `nextPendingStep`, (中文(简体) ), `pendingSteps`, (中文(简体) ), `isApproved`, (中文(简体) ), `assertApproved`, (中文(简体) ), `assertApprovedIfPresent`, (中文(简体) ), `isRejected`, (中文(简体) ), `isPending`, (中文(简体) ), `decisionCount`, (中文(简体) ), `chainToJson`, (中文(简体) ), `ApprovalChainJson`, (中文(简体) ), `ApprovalError`, (中文(简体) ), `ApprovalChain`, (中文(简体) ), `ApprovalStep`, (中文(简体) ), `ApprovalDecision`, (中文(简体) ), `Approver`, (中文(简体) ), `ApprovalThreshold` |
| `/cadence` | `nextOccurrence`, (中文(简体) ), `occurrencesBetween`, (中文(简体) ), `validateCadence`, (中文(简体) ), `CadenceError`, (中文(简体) ), `Cadence`, (中文(简体) ), `DailyCadence`, (中文(简体) ), `WeeklyCadence`, (中文(简体) ), `MonthlyCadence`, (中文(简体) ), `YearlyCadence`, (中文(简体) ), `CronCadence`, (中文(简体) ), `IsoWeekday` |
| `/hold` | `addHold`, (中文(简体) ), `resolveHold`, (中文(简体) ), `activeHolds`, (中文(简体) ), `resolvedHolds`, (中文(简体) ), `isOnHold`, (中文(简体) ), `hasActiveHoldOfCode`, (中文(简体) ), `HoldError`, (中文(简体) ), `HoldReason`, (中文(简体) ), `HoldActor` |
| `/sla` | `breachedAt`, (中文(简体) ), `remainingMs`, (中文(简体) ), `elapsedMs`, (中文(简体) ), `isBreached`, (中文(简体) ), `consumedFraction`, (中文(简体) ), `validateSLA`, (中文(简体) ), `SLAError`, (中文(简体) ), `SLA`, (中文(简体) ), `BreachPolicy` |
| `/timezone` | 民事日期和区`civilDateOf`, (中文(简体) ), `civilDateToInstant`, (中文(简体) ), `addCivilDays`, (中文(简体) ), `addCivilMonths`,.)加上每天的墙钟窗口: `WallTime`, (中文(简体) ), `WallWindow`, (中文(简体) ), `parseWallTime`, (中文(简体) ), `wallTimeOf`, (中文(简体) ), `wallInstant`, (中文(简体) ), `resolveWallWindow`, (中文(简体) ), `wallWindowAt`, (中文(简体) ), `wallWindowStartsBetween` (过夜,DST-精确,半开) |
| `/identifier` | `cleanIdentifier` (隐形标记被去掉,NFKC,数字到ASCII,修剪), `asciiDigits` (每个Unicode小数), `stripInvisible` (单位:千美元)`\p{Cf}`贴上的工作人员号码、国家身份证、电子邮件 |
| `/concurrency` | `mapBounded(items, concurrency, fn)` (工人池,定出结果,在飞行中结算后迅速失效;); `NaN` 货币投出, `chunked(items, size)` |

## 设计

### 货币——整数小单位,总是

```ts
import { fromMajor, addMoney, toMajor } from '@classytic/primitives/money';

const subtotal = fromMajor(19.99, 'USD');     // { amount: 1999, currency: 'USD' }
const shipping = fromMajor(5.00,  'USD');     // { amount: 500,  currency: 'USD' }
const total    = addMoney(subtotal, shipping); // { amount: 2499, currency: 'USD' }
toMajor(total);                                // 24.99
```

`Money.amount` 总是货币小单位的整数—— `1` =一个 美元1分,日元1分,科威特第纳尔1分。 混合货币抛出 `CurrencyMismatchError`这消除了浮起的漂移 当每个软件包卷起时 `{ amount: number, currency: string }`。 。 。 .

### 域事件——结构与Arc相同

```ts
import { createEvent, type EventTransport } from '@classytic/primitives/events';

const event = createEvent('order:placed', { orderId: 'ord_123' }, {
  organizationId: ctx.organizationId,
  userId: ctx.actorId,
  correlationId: ctx.correlationId,
});

await transport.publish(event);
```

形状匹配 `@classytic/arc`是因为 `DomainEvent` 完全——任何弧形运输 (memory, Redis pub/sub, Redis Streams, Kafka) 插件插入到一个期待的包中 此接口没有适配器 。 见PACKAGE RULES.md 第11节.

### 租户联合会——迁至 `@classytic/repo-core/tenant`

```ts
import { resolveTenantConfig } from '@classytic/repo-core/tenant';

const tenant = resolveTenantConfig(config.tenant);
// { enabled: true, tenantField: 'organizationId', fieldType: 'objectId',
//   ref: 'organization', contextKey: 'organizationId', required: true }
```

蒙哥基特语 `MultiTenantOptions` 和sqlitekit的等同两个 `extends Pick<TenantConfig, ...>` 从repo-core——通过解析的配置 直接进入 `multiTenantPlugin(resolved)`。 。 。 .

### 外部参考文献——多形态,无框架

```ts
interface ExternalRef {
  sourceId: string;
  sourceModel: string;
}
```

对于跨越信任界限的参考文献(另一个软件包,另一个服务, Friede, Postgres)——与主机对接 `SourceBridge`为 ObjectId,UUID,花脸身份证,任何东西。 见PACKAGE RULES.md 第7节.

## 什么不是这里(目的)

-   **鼠类类型** ——使用 `ObjectIdLike` 从 `/reference`。任何乌鸦 `Types.ObjectId` 满足它的结构.
-   **交易/ 顺序/ 墨盒形状** - 这些是域类型,不是 原始的 原始的 原始的 他们住在各自的包裹里.
-   **错误子类** - 抛出平地 `Error`s; 主机将其序列化为 `ErrorContract` (从) `@classytic/repo-core/errors`在 HTTP 边界 通过 `toErrorContract(err)`。 。 。 .
-   **运行时货币数据库** 在应用层装白名单 需要一个. `MINOR_UNIT_FACTOR` 涵盖普通案件.

## 许可证

麻省理工学院

## 常见问题

### @classytic/primitives 是什么？

框架-不可知类型Script原始相通于经典套件——钱,事,花相相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相\.

### 如何安装 @classytic/primitives？

在项目目录运行 npm install @classytic/primitives，或使用 pnpm add / yarn add / bun add。

### @classytic/primitives 支持 TypeScript 吗？

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

### @classytic/primitives 支持 ESM 还是 CommonJS？

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

### @classytic/primitives 需要什么版本的 Node\.js？

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

### @classytic/primitives 可以商用吗？

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

### @classytic/primitives 的下载量有多少？

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

### @classytic/primitives 还在维护吗？

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