🌱 Flow Core Seed

Ultra-minimal framework foundation for the Flow ecosystem

🎯 Philosophy

Flow Core Seed provides only 4 immutable interfaces that will never change, enabling unlimited ecosystem growth through separate extension packages.

🌱 Seed (this package) → 🌳 Ecosystem

🚀 Core Interfaces

1. IFlowStep<TIn, TOut> - Universal Processing Unit

interface IFlowStep<TIn, TOut> {
  readonly id: string;
  readonly name: string;
  
  process(input: TIn, context: IFlowContext): Promise<FlowResult<TOut>>;
  validate?(input: TIn): FlowResult<boolean>;
  dispose?(): Promise<void>;
}

2. IFlowContext - Execution Environment

interface IFlowContext {
  readonly id: string;
  readonly timestamp: number;
  readonly metadata: Readonly<Record<string, unknown>>;
  
  get<T>(key: string): T | undefined;
  set<T>(key: string, value: T): void;
  has(key: string): boolean;
  delete(key: string): boolean;
  
  emit(event: string, data?: unknown): void;
  readonly isDisposed: boolean;
}

3. FlowResult<T, E> - Result Pattern

type FlowResult<T, E = FlowError> = 
  | { readonly success: true; readonly data: T }
  | { readonly success: false; readonly error: E };

// Utilities
const result = success(data);        // Create success
const error = failure(flowError);    // Create failure
if (isSuccess(result)) { /* ... */ } // Type-safe checking

4. IFlowObserver - Observability

interface IFlowObserver {
  onStepStart?(step: IFlowStep<unknown, unknown>, context: IFlowContext): void;
  onStepComplete?<T>(step: IFlowStep<unknown, T>, result: FlowResult<T>, context: IFlowContext): void;
  onStepError?(step: IFlowStep<unknown, unknown>, error: FlowError, context: IFlowContext): void;
  onContextEvent?(context: IFlowContext, event: string, data?: unknown): void;
}

📦 Installation

npm install @codechu/flow-core-seed

🌊 Flow Ecosystem

The seed enables unlimited extension packages:

• @codechu/flow-pipeline - Step chaining and composition
• @codechu/flow-streaming - Circular buffers and streams
• @codechu/flow-validation - Input/output validation
• @codechu/flow-config - Configuration management
• @codechu/flow-metrics - Advanced observability
• @codechu/flow-testing - Testing utilities
• @codechu/flow-parsers - YAML, JSON, CSV parsers

✅ Guarantees

• 🔒 Never Breaking: These 4 interfaces are final and immutable
• 🚫 No Exceptions: Result pattern eliminates throw/try/catch in core
• 📏 Minimal Size: <5KB minified + gzipped
• 🔗 Zero Dependencies: No external dependencies
• ⚡ High Performance: Minimal overhead, maximum flexibility
• 🧩 Fully Composable: Steps combine in infinite ways

🛠️ Usage Example

import { 
  IFlowStep, 
  IFlowContext, 
  FlowResult, 
  success, 
  failure, 
  flowError 
} from '@codechu/flow-core-seed';

// Define a step
class UppercaseStep implements IFlowStep<string, string> {
  readonly id = 'uppercase';
  readonly name = 'Uppercase Transform';
  
  async process(input: string, context: IFlowContext): Promise<FlowResult<string>> {
    try {
      context.emit('processing', { input });
      const result = input.toUpperCase();
      return success(result);
    } catch (err) {
      return failure(flowError('UPPERCASE_ERROR', 'Failed to uppercase', err as Error));
    }
  }
}

🏗️ Architecture Benefits

1. 🌱 Organic Growth: Extensions grow as separate packages
2. 🎯 Single Responsibility: Each interface has one clear purpose
3. 🔄 Result Pattern: Elegant error handling without exceptions
4. 👀 Built-in Observability: Monitoring without complexity
5. 🧩 Infinite Composition: Steps combine in unlimited ways
6. ⚡ Zero Overhead: Minimal framework, maximum power

📄 License

MIT © Codechu - Obarlik

The seed that grows into the entire Flow ecosystem 🌱→🌳