Skip to content

neuralline/cyre

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CYRE

Neural Line - Reactive Event Manager
C.Y.R.E ~/SAYER/
Version 4.6.0

The fastest, most reliable reactive state/event management library with industry-leading performance and zero-error. A unique channel-based architecture that runs both in Node and Browser. It's designed for 24/7 operation with advanced protection mechanisms like "Breath system". Task schedule with TimeKeeper etc... and its 60k. bEvolved from the original Quantum-Inception clock project (2016).

npm version Performance Reliability Features

Performance Highlights

CYRE delivers industry-leading performance with zero-error reliability:

  • 18,602 ops/sec - Basic operations (2-3x faster than Redux/RxJS)
  • 18,248 ops/sec - Concurrent load with 10 workers
  • 0.054ms - Average execution latency
  • 0.000% - Error rate across 23,100+ operations
  • 5.37MB - Memory usage for 5,000 operations (10-20x more efficient)

Quick Start

npm install cyre
pnpm add cyre
import {cyre} from 'cyre'

// 1. Create channel with default payload
cyre.action({id: 'user-login', payload: {status: 'idle'}})

// 2. Subscribe to the channel by it's id
cyre.on('user-login', payload => {
  console.log('User login:', payload)
  return {success: true, timestamp: Date.now()}
})

// 3. send to channel
await cyre.call('user-login', {userId: 123, email: 'user@example.com'})

Why CYRE?

Performance Leader

  • 3x faster than Redux for basic operations
  • 2x faster than RxJS for complex workflows
  • Sub-millisecond execution times (0.054ms average)
  • Perfect concurrent scaling (98% efficiency maintained)

Zero-Error Reliability

  • 100% success rate across all features
  • 0.000% error rate in production scenarios
  • Hardware-level precision (0.2ms timing accuracy)
  • Perfect protection systems (throttling, debouncing, change detection)

Advanced Features

  • Built-in protections (throttle, debounce, change detection)
  • IntraLink chains (2,770 links/sec processing)
  • Precise scheduling (delay/repeat with sub-ms accuracy)
  • Reactive streams (RxJS-compatible operators)
  • State machines (XState-compatible patterns)

Core Features

Action-Based Architecture

// Create channels with built-in protections
cyre.action({
  id: 'api-call',
  throttle: 1000, // Rate limiting
  debounce: 300, // Call collapsing
  detectChanges: true, // Skip unchanged payloads
  priority: {level: 'high'}
})

cyre.on('api-call', async payload => {
  const result = await fetch('/api/data', {
    method: 'POST',
    body: JSON.stringify(payload)
  })
  return await result.json()
})

// Calls are automatically protected
await cyre.call('api-call', {query: 'search terms'})

Timing & Scheduling

// Precise timing control
cyre.action({
  id: 'health-check',
  delay: 1000, // Initial delay
  interval: 5000, // Repeat interval
  repeat: 10 // Total executions
})

// Timeline: Wait 1s → Execute → Wait 5s → Execute → ... (10 total)

IntraLink Chain Reactions

// Automatic chain reactions
cyre.on('validate-data', payload => {
  const isValid = validate(payload)

  // Return IntraLink to trigger next action
  return {
    id: isValid ? 'process-data' : 'handle-error',
    payload: {...payload, isValid}
  }
})

cyre.on('process-data', payload => {
  // Processing logic
  return {processed: true, result: payload}
})

React Integration

useCyre Hook

import {useCyre} from 'cyre'

function UserProfile() {
  const userChannel = useCyre({
    name: 'user-profile',
    protection: {
      debounce: 300,
      detectChanges: true
    },
    initialPayload: {userId: null}
  })

  React.useEffect(() => {
    const subscription = userChannel.on(userData => {
      console.log('User updated:', userData)
      return {handled: true}
    })

    return () => subscription.unsubscribe()
  }, [])

  const updateUser = userData => {
    userChannel.call(userData)
  }

  return (
    <button onClick={() => updateUser({id: 123, name: 'John'})}>
      Update User
    </button>
  )
}

Channel Composition

Reactive Streams

State Machines

Monitoring & Debugging


Advanced Usage Examples

Buffer Usage in cyre.action

cyre.action({
  id: 'batch-upload',
  buffer: {window: 1000, strategy: 'append', maxSize: 10}
})

cyre.on('batch-upload', batch => {
  // batch is an array of payloads collected within 1s or up to 10 items
  uploadBatchToServer(batch)
})

// Calls within 1s are batched
cyre.call('batch-upload', {file: 'a.txt'})
cyre.call('batch-upload', {file: 'b.txt'})

Advanced Dispatching

cyre.action({
  id: 'multi-handler',
  dispatch: 'race' // Only the fastest handler result is used
})

cyre.on('multi-handler', async payload => {
  await delay(100)
  return 'slow handler'
})
cyre.on('multi-handler', async payload => {
  await delay(10)
  return 'fast handler'
})

const result = await cyre.call('multi-handler', {data: 1})
// result.payload === 'fast handler'

// Waterfall example
cyre.action({
  id: 'waterfall-demo',
  dispatch: 'waterfall'
})
cyre.on('waterfall-demo', payload => payload + 1)
cyre.on('waterfall-demo', payload => payload * 2)
const res = await cyre.call('waterfall-demo', 3) // (3+1)*2 = 8

Handler Removal & Statistics

const handler = payload => doSomething(payload)
cyre.on('removable', handler)
// ...
cyre.removeHandler('removable', handler) // Removes the handler
const stats = cyre.getHandlerStats('removable')
console.log(stats.handlerCount) // 0 if removed

Direct Use of cyre.payloadState

cyre.action({id: 'user-update', payload: {name: 'Alice'}})

// Get current payload
const current = cyre.payloadState.get('user-update')
// Set new payload
cyre.payloadState.set('user-update', {name: 'Bob'})
// Check if changed
const changed = cyre.payloadState.hasChanged('user-update', {name: 'Bob'})

(Optional) Orchestration Example

cyre.action({id: 'step1'})
cyre.action({id: 'step2'})

cyre.on('step1', payload => {
  // ...
  return {id: 'step2', payload: {...payload, step1: true}}
})

// Orchestrate a workflow
await cyre.call('step1', {start: true})

Multi-Handler Channels: 1-to-Many .on Handlers

Cyre supports multiple .on handlers per channel, enabling powerful event-driven workflows. Each channel can have many subscribers, and you can control how handlers are dispatched:

  • Parallel Dispatch: All handlers are invoked concurrently (default for async handlers).
  • Sequential Dispatch: Handlers are invoked in registration order, each waiting for the previous to complete (useful for ordered side effects).
// Register multiple handlers for the same channel
cyre.on('user-login', payload => {
  // Handler 1
  logLogin(payload)
})

cyre.on('user-login', async payload => {
  // Handler 2 (async)
  await sendAnalytics(payload)
})

// By default, async handlers run in parallel. For sequential execution:
cyre.action({
  id: 'user-login',
  sequential: true // Ensures handlers run one after another
})

Handler Techniques: Factory vs Outpost

  • Factory Handlers: Main business logic handlers, ideally kept outside your application codebase to avoid reloads and app errors. Organize all factory handlers in a single location/directory, and prefer a 1-to-1 relationship between channel and handler. These are responsible for core processing, validation, and transformation of data.
  • Outpost Handlers: Instead of polling or awaiting, outpost .on handlers reactively receive payloads/signals and interpret them as local environment changes (e.g., updating UI, state, or triggering side effects). Outpost handlers are located inside your app, support a 1-to-many relationship, and are best suited for delivery, UI updates, and actions—not for core business logic.
// Factory handler (pure)
cyre.on('data-validate', payload => validateData(payload))

// Outpost handler (side effect)
cyre.on('data-validate', payload => {
  reportValidation(payload)
  // No return needed
})

New: Buffer Operator

The buffer operator allows you to collect and process events in batches, reducing overhead and enabling batch workflows.

import {createStream} from 'cyre'

const stream = createStream()
  .buffer(5) // Collects 5 events before emitting as an array
  .map(batch => processBatch(batch))

stream.subscribe(batchResult => {
  // Handle processed batch
})

// Emit events
stream.next(event1)
stream.next(event2)
// ...
  • Use buffer(timeMs) to emit batches based on time windows.
  • Combine with other operators for advanced stream processing.

🛡️ Built-in Protection Systems

Throttle Protection

cyre.action({
  id: 'api-request',
  throttle: 1000 // Max 1 request per second
})

// Automatic rate limiting - excess calls rejected gracefully

Debounce Protection

cyre.action({
  id: 'search-input',
  debounce: 300 // Collapse rapid calls to single execution
})

// 90% call collapsing efficiency with perfect timing accuracy

Change Detection

cyre.action({
  id: 'state-update',
  detectChanges: true // Skip execution if payload unchanged
})

// Automatic payload comparison using deep equality

System Breathing

CYRE includes an adaptive "breathing" system that automatically adjusts performance based on system stress:

  • Normal operation: 200ms base rate
  • Under stress: Automatic rate adjustment
  • Recovery mode: Critical actions only
  • Self-healing: Gradual return to normal operation

Monitoring & Debugging

Performance Metrics

// Channel-specific metrics
const actionMetrics = cyre.getMetrics()

Debug Tools

// Enable debug mode for detailed logging
cyre.action({
  id: 'debug-action',
  log: true // Enable detailed execution logging
})

// Get system health status
const isHealthy = cyre.isHealthy()
const breathingState = cyre.getBreathingState()

Testing & Reliability

CYRE includes comprehensive test suites following industry standards:

Reliability Metrics

  • 23,100+ operations tested across all scenarios
  • 0.000% error rate in production simulations
  • 100% success rate for all advanced features
  • Perfect protection system activation rates

Performance Validation

  • Industry-standard benchmarks (React/Redux/RxJS methodology)
  • Statistical rigor (P95/P99 percentiles, warmup phases)
  • Cross-validation of all timing and throughput calculations
  • Memory leak detection and cleanup verification

API Reference

Core Methods

// Channel management
cyre.action(config: IO | IO[])           // Register one or more channels
cyre.on(id: string, handler: Function)   // Subscribe handler(s) to a channel
cyre.call(id: string, payload?: any)     // Trigger a channel/action
cyre.forget(id: string)                  // Remove a channel and its handlers
cyre.get(id: string)                     // Get the current channel payload by id. will include {req,res}

// System & State Control
cyre.init()                              // Initialize the system
cyre.clear()                             // Clear all channels, handlers, and state
cyre.reset()                             // Alias for clear, resets all state
cyre.pause(id?: string)                  // Pause all or specific channels
cyre.resume(id?: string)                 // Resume all or specific channels
cyre.lock()               // Lock/unlock the system
cyre.shutdown()                          // Full system shutdown

// Metrics & Monitoring
cyre.getMetrics(channelId?: string)      // Get system or channel-specific metrics
cyre.status()                           // Returns if system is hibernating

// Advanced/Experimental
// cyre.payloadState                       // Direct access to dual payload state system
// cyre.orchestration                      // Orchestration engine for complex workflows
// cyre.schedule                           // Scheduling utility for advanced timing
// cyre.path()                             // Path system for hierarchical channel addressing (stub)

React Hooks & Utilities

import {useCyre, useGroup, useBranch, useCollective, log} from 'cyre'
  • useCyre: React hook for channel integration
  • useGroup: React hook for group/channel management
  • useBranch: React hook for branch system
  • useCollective: React hook for collective channel patterns
  • log: Utility logger

Channel/Action Configuration (IO options)

interface IO {
  id: string // Channel identifier (required)
  payload?: any // Initial/default payload
  path?: string // Hierarchical path for organization
  group?: string
  tags?: string[]
  description?: string
  version?: string

  // Protections
  required?: boolean
  throttle?: number
  debounce?: number
  maxWait?: number
  detectChanges?: boolean
  block?: boolean
  buffer?: { window: number, strategy?: 'overwrite' | 'append' | 'ignore', maxSize?: number }

  // Scheduling
  interval?: number
  repeat?: number | boolean
  delay?: number

  // Execution
  dispatch?: 'single' | 'parallel' | 'sequential' | 'race' | 'waterfall'
  errorStrategy?: 'fail-fast' | 'continue' | 'retry'
  collectResults?: 'first' | 'last' | 'all' | boolean
  dispatchTimeout?: number

  // Pipeline
  schema?: Schema<any>
  condition?: (payload: any) => boolean
  selector?: (payload: any) => any
  transform?: (payload: any) => any

  // Priority
  priority?: { level: string, ... }

  // Auth
  auth?: { mode: 'token' | 'context' | 'group' | 'disabled', ... }

  // Logging
  log?: boolean
}

Multi-Handler & Dispatching

  • Multiple .on handlers per channel, with smart operator selection:
    • Default: parallel for async, single for sync
    • User can force: dispatch: 'sequential' | 'race' | 'waterfall' | 'parallel'
  • Handler types: Factory (pure) and Outpost (side-effect)
  • Handler removal and stats supported

Buffer Operator

  • buffer: { window: number, strategy?: 'overwrite' | 'append' | 'ignore', maxSize?: number }
  • Batches calls within a time window or by count

🔮 Advanced Use Cases

High-Performance APIs

// Rate-limited API with automatic retry
cyre.action({
  id: 'api-with-retry',
  throttle: 100, // 10 requests/sec max
  repeat: 3, // Retry up to 3 times
  priority: {level: 'high'}
})

Real-time Data Processing

// Stream processing with backpressure
const dataStream = createStream()
  .throttle(16) // 60fps processing rate
  .map(processRealTimeData)
  .filter(data => data.isComplete)
  .subscribe(updateUI)

Complex Workflows

// Multi-step workflow with error handling
const workflow = cyreCompose(
  [validationChannel, authenticationChannel, processingChannel, auditChannel],
  {
    continueOnError: false,
    timeout: 30000
  }
)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/neeuraline/cyre.git
cd cyre
npm install
npm test
npm run benchmark  # Run performance tests

License

MIT License - see LICENSE file for details.

Roadmap

  • Multi-subscriber support - Single action, multiple handlers
  • Queue option - Call queuing until subscribers ready
  • Enhanced React integration - Custom ID support for useCyre
  • State persistence - Automatic save/restore functionality

📞 Support


Philosophy

Cyre follows these core principles:

  • Precision: Accurate timing and reliable event handling
  • Protection: Natural rate limiting through breathing system
  • Performance: System-aware optimization and stress management
  • Adaptability: Self-adjusting to system conditions
  • Predictability: Consistent behavior with clear execution rules
  • Horizontal architecture: Independent channels that expand horizontally

Origins

Originally evolved from the Quantum-Inception clock project (2016), Cyre has grown into a full-featured event management system while maintaining its quantum timing heritage. The latest evolution introduces Schema, hooks, and standardized execution behavior to provide a more predictable and powerful developer experience.

Q0.0U0.0A0.0N0.0T0.0U0.0M0 - I0.0N0.0C0.0E0.0P0.0T0.0I0.0O0.0N0.0S0
Expands HORIZONTALLY as your project grow

CYRE - Neural Line Reactive Event Manager
The fastest, most reliable reactive state management for modern applications.