卡纳里公司

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

特征

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

安装

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

基本用途

创建加那利核心实例

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
})

设定和获得价值

// 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)

配置管理

// 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 上, 并提供配置更改的实时通知 :

// 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')
})

运行时间覆盖

// 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

合并配置

// 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

自定义调用

// 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 支持特性值的各种数据类型:

// 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)

备选案文

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

// 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]
})

获取器和状态

// 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]

处理错误

// 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 参考

构造器

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 - 全部重置后即发出

类型脚本

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
}

许可证

麻省理工学院