@kb-labs/workflow-constants 1.1.0

package/README.md

@@ -0,0 +1,207 @@
+# @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
+
+```typescript
+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
+
+```typescript
+import { EVENT_NAMES } from '@kb-labs/workflow-constants';
+
+eventBus.publish(EVENT_NAMES.run.started, data);
+```
+
+### Example 3: Create Redis Key Factory
+
+```typescript
+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](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+MIT © KB Labs

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+declare const RUN_STATES: readonly ["queued", "running", "success", "failed", "cancelled", "skipped", "dlq"];
+declare const JOB_STATES: readonly ["queued", "running", "success", "failed", "cancelled", "skipped", "interrupted"];
+declare const STEP_STATES: readonly ["queued", "running", "success", "failed", "cancelled", "skipped", "dlq", "waiting_approval"];
+declare const JOB_PRIORITIES: readonly ["high", "normal", "low"];
+
+type RunState = (typeof RUN_STATES)[number];
+type JobState = (typeof JOB_STATES)[number];
+type StepState = (typeof STEP_STATES)[number];
+type JobPriority = (typeof JOB_PRIORITIES)[number];
+declare const EVENT_NAMES: {
+    readonly run: {
+        readonly created: "run.created";
+        readonly started: "run.started";
+        readonly updated: "run.updated";
+        readonly finished: "run.finished";
+        readonly cancelled: "run.cancelled";
+        readonly failed: "run.failed";
+    };
+    readonly job: {
+        readonly queued: "job.queued";
+        readonly started: "job.started";
+        readonly updated: "job.updated";
+        readonly succeeded: "job.succeeded";
+        readonly failed: "job.failed";
+        readonly cancelled: "job.cancelled";
+        readonly skipped: "job.skipped";
+    };
+    readonly step: {
+        readonly queued: "step.queued";
+        readonly started: "step.started";
+        readonly updated: "step.updated";
+        readonly succeeded: "step.succeeded";
+        readonly failed: "step.failed";
+        readonly cancelled: "step.cancelled";
+        readonly skipped: "step.skipped";
+        readonly waitingApproval: "step.waitingApproval";
+    };
+    readonly log: {
+        readonly appended: "log.appended";
+    };
+};
+type WorkflowEventName = (typeof EVENT_NAMES)['run'][keyof (typeof EVENT_NAMES)['run']] | (typeof EVENT_NAMES)['job'][keyof (typeof EVENT_NAMES)['job']] | (typeof EVENT_NAMES)['step'][keyof (typeof EVENT_NAMES)['step']] | (typeof EVENT_NAMES)['log'][keyof (typeof EVENT_NAMES)['log']];
+interface RedisKeyFactory {
+    namespace: string;
+    idempotency(key: string): string;
+    concurrency(group: string): string;
+    run(runId: string): string;
+    artifacts(runId: string): string;
+    jobQueue(priority?: JobPriority): string;
+    runEvents(runId: string): string;
+    eventChannel(): string;
+    lock(name: string): string;
+}
+interface RedisKeyFactoryOptions {
+    namespace?: string;
+}
+declare const DEFAULT_REDIS_NAMESPACE = "kb";
+declare const WORKFLOW_REDIS_CHANNEL = "kb:wf:events";
+declare function createRedisKeyFactory(options?: RedisKeyFactoryOptions): RedisKeyFactory;
+declare const IDEMPOTENCY_TTL_ENV = "KB_WF_IDEMP_TTL_MS";
+declare const CONCURRENCY_TTL_ENV = "KB_WF_CONC_TTL_MS";
+declare const REDIS_URL_ENV = "KB_REDIS_URL";
+declare const REDIS_MODE_ENV = "KB_REDIS_MODE";
+declare const REDIS_NAMESPACE_ENV = "KB_REDIS_NAMESPACE";
+type RedisMode = 'standalone' | 'cluster' | 'sentinel';
+
+export { CONCURRENCY_TTL_ENV, DEFAULT_REDIS_NAMESPACE, EVENT_NAMES, IDEMPOTENCY_TTL_ENV, JOB_PRIORITIES, JOB_STATES, type JobPriority, type JobState, REDIS_MODE_ENV, REDIS_NAMESPACE_ENV, REDIS_URL_ENV, RUN_STATES, type RedisKeyFactory, type RedisKeyFactoryOptions, type RedisMode, type RunState, STEP_STATES, type StepState, WORKFLOW_REDIS_CHANNEL, type WorkflowEventName, createRedisKeyFactory };

package/dist/index.js

@@ -0,0 +1,79 @@
+// src/index.ts
+var RUN_STATES = ["queued", "running", "success", "failed", "cancelled", "skipped", "dlq"];
+var JOB_STATES = ["queued", "running", "success", "failed", "cancelled", "skipped", "interrupted"];
+var STEP_STATES = [...RUN_STATES, "waiting_approval"];
+var JOB_PRIORITIES = ["high", "normal", "low"];
+var EVENT_NAMES = {
+  run: {
+    created: "run.created",
+    started: "run.started",
+    updated: "run.updated",
+    finished: "run.finished",
+    cancelled: "run.cancelled",
+    failed: "run.failed"
+  },
+  job: {
+    queued: "job.queued",
+    started: "job.started",
+    updated: "job.updated",
+    succeeded: "job.succeeded",
+    failed: "job.failed",
+    cancelled: "job.cancelled",
+    skipped: "job.skipped"
+  },
+  step: {
+    queued: "step.queued",
+    started: "step.started",
+    updated: "step.updated",
+    succeeded: "step.succeeded",
+    failed: "step.failed",
+    cancelled: "step.cancelled",
+    skipped: "step.skipped",
+    waitingApproval: "step.waitingApproval"
+  },
+  log: {
+    appended: "log.appended"
+  }
+};
+var DEFAULT_REDIS_NAMESPACE = "kb";
+var WORKFLOW_REDIS_CHANNEL = "kb:wf:events";
+function createRedisKeyFactory(options = {}) {
+  const namespace = options.namespace?.replace(/[:\s]+/g, ":").replace(/:+$/, "") || DEFAULT_REDIS_NAMESPACE;
+  const wfNs = `${namespace}:wf`;
+  return {
+    namespace: wfNs,
+    idempotency(key) {
+      return `${wfNs}:idemp:${key}`;
+    },
+    concurrency(group) {
+      return `${wfNs}:conc:${group}`;
+    },
+    run(runId) {
+      return `${wfNs}:runs:${runId}`;
+    },
+    artifacts(runId) {
+      return `${wfNs}:artifacts:${runId}`;
+    },
+    jobQueue(priority = "normal") {
+      return `${wfNs}:queue:jobs:${priority}`;
+    },
+    runEvents(runId) {
+      return `${wfNs}:events:runs:${runId}`;
+    },
+    eventChannel() {
+      return WORKFLOW_REDIS_CHANNEL;
+    },
+    lock(name) {
+      return `${wfNs}:locks:${name}`;
+    }
+  };
+}
+var IDEMPOTENCY_TTL_ENV = "KB_WF_IDEMP_TTL_MS";
+var CONCURRENCY_TTL_ENV = "KB_WF_CONC_TTL_MS";
+var REDIS_URL_ENV = "KB_REDIS_URL";
+var REDIS_MODE_ENV = "KB_REDIS_MODE";
+var REDIS_NAMESPACE_ENV = "KB_REDIS_NAMESPACE";
+
+export { CONCURRENCY_TTL_ENV, DEFAULT_REDIS_NAMESPACE, EVENT_NAMES, IDEMPOTENCY_TTL_ENV, JOB_PRIORITIES, JOB_STATES, REDIS_MODE_ENV, REDIS_NAMESPACE_ENV, REDIS_URL_ENV, RUN_STATES, STEP_STATES, WORKFLOW_REDIS_CHANNEL, createRedisKeyFactory };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["const RUN_STATES = ['queued', 'running', 'success', 'failed', 'cancelled', 'skipped', 'dlq'] as const\nconst JOB_STATES = ['queued', 'running', 'success', 'failed', 'cancelled', 'skipped', 'interrupted'] as const\nconst STEP_STATES = [...RUN_STATES, 'waiting_approval'] as const\nconst JOB_PRIORITIES = ['high', 'normal', 'low'] as const\n\nexport { RUN_STATES, JOB_STATES, STEP_STATES, JOB_PRIORITIES }\n\nexport type RunState = (typeof RUN_STATES)[number]\nexport type JobState = (typeof JOB_STATES)[number]\nexport type StepState = (typeof STEP_STATES)[number]\nexport type JobPriority = (typeof JOB_PRIORITIES)[number]\n\nexport const EVENT_NAMES = {\n  run: {\n    created: 'run.created',\n    started: 'run.started',\n    updated: 'run.updated',\n    finished: 'run.finished',\n    cancelled: 'run.cancelled',\n    failed: 'run.failed',\n  },\n  job: {\n    queued: 'job.queued',\n    started: 'job.started',\n    updated: 'job.updated',\n    succeeded: 'job.succeeded',\n    failed: 'job.failed',\n    cancelled: 'job.cancelled',\n    skipped: 'job.skipped',\n  },\n  step: {\n    queued: 'step.queued',\n    started: 'step.started',\n    updated: 'step.updated',\n    succeeded: 'step.succeeded',\n    failed: 'step.failed',\n    cancelled: 'step.cancelled',\n    skipped: 'step.skipped',\n    waitingApproval: 'step.waitingApproval',\n  },\n  log: {\n    appended: 'log.appended',\n  },\n} as const\n\nexport type WorkflowEventName =\n  | (typeof EVENT_NAMES)['run'][keyof (typeof EVENT_NAMES)['run']]\n  | (typeof EVENT_NAMES)['job'][keyof (typeof EVENT_NAMES)['job']]\n  | (typeof EVENT_NAMES)['step'][keyof (typeof EVENT_NAMES)['step']]\n  | (typeof EVENT_NAMES)['log'][keyof (typeof EVENT_NAMES)['log']]\n\nexport interface RedisKeyFactory {\n  namespace: string\n  idempotency(key: string): string\n  concurrency(group: string): string\n  run(runId: string): string\n  artifacts(runId: string): string\n  jobQueue(priority?: JobPriority): string\n  runEvents(runId: string): string\n  eventChannel(): string\n  lock(name: string): string\n}\n\nexport interface RedisKeyFactoryOptions {\n  namespace?: string\n}\n\nexport const DEFAULT_REDIS_NAMESPACE = 'kb'\nexport const WORKFLOW_REDIS_CHANNEL = 'kb:wf:events'\n\nexport function createRedisKeyFactory(\n  options: RedisKeyFactoryOptions = {},\n): RedisKeyFactory {\n  const namespace =\n    options.namespace?.replace(/[:\\s]+/g, ':').replace(/:+$/, '') ||\n    DEFAULT_REDIS_NAMESPACE\n  const wfNs = `${namespace}:wf`\n\n  return {\n    namespace: wfNs,\n    idempotency(key: string) {\n      return `${wfNs}:idemp:${key}`\n    },\n    concurrency(group: string) {\n      return `${wfNs}:conc:${group}`\n    },\n    run(runId: string) {\n      return `${wfNs}:runs:${runId}`\n    },\n    artifacts(runId: string) {\n      return `${wfNs}:artifacts:${runId}`\n    },\n    jobQueue(priority: JobPriority = 'normal') {\n      return `${wfNs}:queue:jobs:${priority}`\n    },\n    runEvents(runId: string) {\n      return `${wfNs}:events:runs:${runId}`\n    },\n    eventChannel() {\n      return WORKFLOW_REDIS_CHANNEL\n    },\n    lock(name: string) {\n      return `${wfNs}:locks:${name}`\n    },\n  }\n}\n\nexport const IDEMPOTENCY_TTL_ENV = 'KB_WF_IDEMP_TTL_MS'\nexport const CONCURRENCY_TTL_ENV = 'KB_WF_CONC_TTL_MS'\nexport const REDIS_URL_ENV = 'KB_REDIS_URL'\nexport const REDIS_MODE_ENV = 'KB_REDIS_MODE'\nexport const REDIS_NAMESPACE_ENV = 'KB_REDIS_NAMESPACE'\n\nexport type RedisMode = 'standalone' | 'cluster' | 'sentinel'\n\n\n\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kb-labs/workflow-constants",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Shared constants for the KB Labs workflow engine.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm clean && tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint . --ignore-pattern 'dist/**'",
+    "lint:fix": "eslint . --fix --ignore-pattern 'dist/**'",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "@typescript-eslint/eslint-plugin": "^8",
+    "@typescript-eslint/parser": "^8",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}