@kb-labs/workflow-constants

Shared constants for the KB Labs workflow engine.

Vision & Purpose

@kb-labs/workflow-constants provides shared constants for the KB Labs workflow engine. It includes state constants, event names, status enums, and Redis key factories.

Core Goals

• State Constants: Workflow, job, and step state definitions
• Event Names: Event type constants for workflow events
• Status Enums: Status and state enumerations
• Redis Key Factory: Redis key generation utilities

Package Status

• Version: 0.1.0
• Stage: Stable
• Status: Production Ready ✅

Architecture

High-Level Overview

Workflow Constants
    │
    ├──► State Constants
    ├──► Event Names
    ├──► Priority Constants
    └──► Redis Key Factory

Key Components

1. Constants (index.ts): All constants and utilities

✨ Features

• State constants for workflow, job, and step states
• Event names for workflow events
• Priority constants for job priorities
• Redis key factory for key generation
• Environment variable constants for configuration

📦 API Reference

Main Exports

Constants

• RUN_STATES: Workflow run states
• JOB_STATES: Job execution states
• STEP_STATES: Step execution states
• JOB_PRIORITIES: Job priority levels
• EVENT_NAMES: Event type names

Types

• RunState: Run state type
• JobState: Job state type
• StepState: Step state type
• JobPriority: Job priority type
• WorkflowEventName: Workflow event name type
• RedisMode: Redis mode type

Functions

• createRedisKeyFactory(options): Create Redis key factory

Constants

• DEFAULT_REDIS_NAMESPACE: Default Redis namespace
• WORKFLOW_REDIS_CHANNEL: Workflow Redis channel
• IDEMPOTENCY_TTL_ENV: Idempotency TTL environment variable
• CONCURRENCY_TTL_ENV: Concurrency TTL environment variable
• REDIS_URL_ENV: Redis URL environment variable
• REDIS_MODE_ENV: Redis mode environment variable
• REDIS_NAMESPACE_ENV: Redis namespace environment variable

🔧 Configuration

Configuration Options

RedisKeyFactoryOptions

• namespace: Redis namespace (default: 'kb')

Environment Variables

• KB_WF_IDEMP_TTL_MS: Idempotency TTL in milliseconds
• KB_WF_CONC_TTL_MS: Concurrency TTL in milliseconds
• KB_REDIS_URL: Redis connection URL
• KB_REDIS_MODE: Redis mode (standalone/cluster/sentinel)
• KB_REDIS_NAMESPACE: Redis namespace

🔗 Dependencies

Runtime Dependencies

None (pure constants package)

Development Dependencies

• @kb-labs/devkit (link:../../../kb-labs-devkit): DevKit presets
• @types/node (^24.3.3): Node.js types
• tsup (^8.5.0): TypeScript bundler
• typescript (^5.6.3): TypeScript compiler
• vitest (^3.2.4): Test runner

🧪 Testing

Test Structure

src/__tests__/
└── (tests to be added)

Test Coverage

• Current Coverage: ~0% (tests to be added)
• Target Coverage: 90%

📈 Performance

Performance Characteristics

• Time Complexity: O(1) for all operations
• Space Complexity: O(1)
• Bottlenecks: None

🔒 Security

Security Considerations

• Key Factory: Secure key generation
• Namespace Validation: Namespace validation

Known Vulnerabilities

• None

🐛 Known Issues & Limitations

Known Issues

• None currently

Limitations

• Fixed Constants: Constants are fixed (no dynamic configuration)

Future Improvements

• Dynamic Constants: Configurable constants support

🔄 Migration & Breaking Changes

Migration from Previous Versions

No breaking changes in current version (0.1.0).

Breaking Changes in Future Versions

• None planned

📚 Examples

Example 1: Use State Constants

import { RUN_STATES, StepState } from '@kb-labs/workflow-constants';

if (run.state === RUN_STATES.RUNNING) {
  // ...
}

const stepState: StepState = StepState.SUCCESS;

Example 2: Use Event Names

import { EVENT_NAMES } from '@kb-labs/workflow-constants';

eventBus.publish(EVENT_NAMES.run.started, data);

Example 3: Create Redis Key Factory

import { createRedisKeyFactory } from '@kb-labs/workflow-constants';

const keys = createRedisKeyFactory({ namespace: 'kb' });
const runKey = keys.run('run-123');
const queueKey = keys.jobQueue('high');

🤝 Contributing

See CONTRIBUTING.md for development guidelines.

📄 License

MIT © KB Labs