# @canary-flags/core 中文文档

规范地址：https://npmcn.com/package/%40canary-flags/core/

版本：1\.1\.3
npm 元数据更新时间：2026-04-27T23:57:38.728Z
中文译文更新时间：2026-11-09T21:19:12.612Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40canary-flags/core
原文对照：https://npmcn.com/package/%40canary-flags/core/?lang=original

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

- 包体积（解压后）：46.9 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-07-27T23:40:15.206Z
- 最新版本发布：2026-04-27T23:57:38.581Z
- 近 30 天下载量：1723（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 10 个）

## 中文简介

一个强大的功能旗和配置管理库,用于JavaScript/TypeScript应用程序. CanaryCore提供了灵活,事件驱动的系统,用于管理地物旗,配置值,和运行时间覆盖.

## 安装

```sh
npm install @canary-flags/core
```

也可以使用：`pnpm add @canary-flags/core`、`yarn add @canary-flags/core`、`bun add @canary-flags/core`

## README

# 卡纳里公司

一个强大的功能旗和配置管理库,用于JavaScript/TypeScript应用程序. CanaryCore提供了灵活,事件驱动的系统,用于管理地物旗,配置值,和运行时间覆盖.

## 特征

-   🚀 **特性旗管理** - 动态启用/残疾特性
-   ⚡ **运行时间覆盖** - 不重启运行时覆盖值
-   📡 **事件驱动** - 实时监听配置变化
-   🔄 **配置合并** - 合并多个来源的配置
-   🎯 **类型安全** - 具有类型安全值的完整类型脚本支持
-   🧪 **测试支持** - 易于嘲笑和测试公用事业

## 安装

```bash
npm install @canary-flags/core
# or
yarn add @canary-flags/core
```

## 基本用途

### 创建加那利核心实例

```typescript
import CanaryCore from '@canary-flags/core'

// Create an empty instance
const canary = new CanaryCore()

// Create with initial configuration
const canary = new CanaryCore([
  { name: 'new-feature', value: true },
  { name: 'beta-mode', value: false }
])

// Create with overrides
const canary = new CanaryCore(undefined, {
  'new-feature': true,
  'beta-mode': true
})
```

### 设定和获得价值

```typescript
// Assign a value to a feature
canary.assign('my-feature', true)

// Get a feature value
const isEnabled = canary.get('my-feature') // true

// Override a value (takes precedence over assigned value)
canary.assign('my-feature', false)
canary.override('my-feature', true)
const value = canary.get('my-feature') // true (override takes precedence)
```

### 配置管理

```typescript
// Set a complete feature configuration
canary.config('advanced-feature', {
  name: 'advanced-feature',
  value: 'enabled',
  variants: ['disabled', 'enabled', 'premium'],
  metadata: {
    description: 'Advanced feature with multiple variants'
  }
})

// Get the full feature configuration
const config = canary.getFeature('advanced-feature')
// Returns: { name: 'advanced-feature', value: 'enabled', variants: [...], metadata: {...} }

// Initialize multiple features at once
canary.initializeConfig([
  { name: 'feature-1', value: true },
  { name: 'feature-2', value: 'beta' },
  { name: 'feature-3', value: 42 }
])
```

## 高级特性

### 事件系统

CanaryCore 建于 EventEmitter 上, 并提供配置更改的实时通知 :

```typescript
// Listen to specific feature changes
canary.on('assign:my-feature', (value, instance) => {
  console.log(`my-feature assigned to: ${value}`)
})

canary.on('override:my-feature', (value, instance) => {
  console.log(`my-feature overridden to: ${value}`)
})

canary.on('config:my-feature', (config) => {
  console.log('my-feature configuration updated:', config)
})

// Listen to any override
canary.on('override', (key, value, instance) => {
  console.log(`Feature ${key} changed to: ${value}`)
})

// Listen to effective value changes
canary.on('change', (key, value, instance) => {
  console.log(`Feature ${key} changed to: ${value}`)
})

// Listen to bulk/catch-all changes
canary.on('change:bulk', (instance) => {
  console.log('Refresh from core state')
})

// Listen to reset events
canary.on('reset', (instance) => {
  console.log('All overrides have been reset')
})
```

### 运行时间覆盖

```typescript
// Override multiple values at once
canary.overrideValues({
  'feature-1': true,
  'feature-2': 'enabled',
  'feature-3': 100
})

// Check if a feature has an override
const hasOverride = canary.hasOverride('my-feature') // boolean

// Reset all overrides
canary.reset()

// Check if a feature has an assignment
const hasAssignment = canary.hasAssignment('my-feature') // boolean
```

### 合并配置

```typescript
// Create a child configuration
const childCore = new CanaryCore([
  { name: 'child-feature', value: true },
  { name: 'shared-feature', value: 'child-value' }
])

// Merge child into parent
canary.merge(childCore)

// Child values take precedence over existing values
```

### 自定义调用

```typescript
// Set custom evaluation callback
canary.onEvaluateFlag = (key, config) => {
  console.log(`Feature ${key} evaluated:`, config?.value)
  // Custom logic here
}

// Set custom toggle callback
canary.toggle = () => {
  console.log('Toggle called')
  // Custom toggle logic
}

// Check if callbacks are set
const hasCallback = canary.hasOnEvaluateFlag // boolean
```

## 数据类型

CanaryCore 支持特性值的各种数据类型:

```typescript
// Boolean flags
canary.assign('boolean-feature', true)

// String values
canary.assign('string-feature', 'enabled')

// Numeric values
canary.assign('numeric-feature', 42)

// Null and undefined
canary.assign('null-feature', null)
canary.assign('undefined-feature', undefined)
```

## 备选案文

地物可以有预定义的变体:

```typescript
// Boolean variants (default)
canary.config('simple-flag', {
  name: 'simple-flag',
  value: true
  // variants: [false, true] (default)
})

// String variants
canary.config('theme-feature', {
  name: 'theme-feature',
  value: 'dark',
  variants: ['light', 'dark', 'auto']
})

// Numeric variants
canary.config('timeout-feature', {
  name: 'timeout-feature',
  value: 5000,
  variants: [1000, 5000, 10000]
})
```

## 获取器和状态

```typescript
// Get all current overrides
const overrides = canary.overrides
// Returns: { 'feature-1': true, 'feature-2': 'enabled' }

// Get all feature values (including overrides)
const selections = canary.selections
// Returns: { 'feature-1': true, 'feature-2': 'enabled', 'feature-3': false }

// Get all assignments (without overrides)
const assignments = canary._assignments
// Returns: [true, 'enabled', false]
```

## 处理错误

```typescript
// Handle non-existent features gracefully
const value = canary.get('non-existent') // undefined

// Check if feature exists before using
if (canary.hasAssignment('my-feature')) {
  const value = canary.get('my-feature')
  // Use value safely
}
```

## 业绩考量

-   CanaryCore 使用 O(1) 特性查看图
-   活动听众打电话时自动清理 `destroy()`
-   配置合并被优化以避免不必要的更新
-   对于典型的地物标志方案来说,内存使用最少

## API 参考

### 构造器

```typescript
new CanaryCore(configArray?: CanaryStoreEntry[], overrides?: Overrides)
```

### 核心方法

-   `assign(key: string, value: CanaryValue): CanaryCore`
-   `override(key: string, value: CanaryValue): CanaryCore`
-   `get(key: string): CanaryValue`
-   `config(key: string, entry: CanaryStoreEntry): CanaryCore`
-   `getFeature(key: string): CanaryStoreEntry | undefined`
-   `hasOverride(key: string): boolean`
-   `hasAssignment(key: string): boolean`
-   `reset(): CanaryCore`
-   `merge(childCore: CanaryCore): CanaryCore`
-   `clear(): void`
-   `destroy(): void`

### 计数器

-   `overrides: Overrides`
-   `selections: { [key: string]: CanaryValue }`
-   `hasOnEvaluateFlag: boolean`

### 设置

-   `onEvaluateFlag: (key: string, config?: CanaryStoreEntry) => void`
-   `toggle: () => void`

### 活动

-   `assign:${key}` - 指定一个特性时予以允许
-   `override:${key}` - 当一个特性被推翻时被允许
-   `config:${key}` - 更新特性配置时发出通知
-   `change` - 当一个特性的有效值改变时,被确认
-   `change:bulk` - 为可能影响多种特性的作业提供包罗万象的散装/验证信号
-   `reset` - 全部重置后即发出

## 类型脚本

```typescript
interface CanaryStoreEntry {
  name: string
  value: CanaryValue
  variants?: [true, false] | [false, true] | string[] | number[]
  override?: CanaryValue
  metadata?: {
    description: string
  }
}

type CanaryValue = boolean | string | number | null | undefined

interface Overrides {
  [key: string]: CanaryValue
}
```

## 许可证

麻省理工学院

## 常见问题

### @canary-flags/core 是什么？

一个强大的功能旗和配置管理库,用于JavaScript/TypeScript应用程序\. CanaryCore提供了灵活,事件驱动的系统,用于管理地物旗,配置值,和运行时间覆盖\.

### 如何安装 @canary-flags/core？

在项目目录运行 npm install @canary-flags/core，或使用 pnpm add / yarn add / bun add。

### @canary-flags/core 支持 TypeScript 吗？

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

### @canary-flags/core 支持 ESM 还是 CommonJS？

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

### @canary-flags/core 可以商用吗？

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

### @canary-flags/core 的下载量有多少？

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

### @canary-flags/core 还在维护吗？

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