npm package: @obarlik/flow-core-seed
Description: 🌱 Flow Core Seed - Ultra-minimal framework foundation with 4 immutable interfaces for Flow ecosystem
Author: Codechu - Obarlik
Latest version: 1.0.0

# 🌱 Flow Core Seed

**Ultra-minimal framework foundation for the Flow ecosystem**

[![npm version](https://badge.fury.io/js/%40obarlik%2Fflow-core-seed.svg)](https://badge.fury.io/js/%40obarlik%2Fflow-core-seed)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🎯 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
```typescript
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
```typescript
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
```typescript
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
```typescript
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

```bash
npm install @obarlik/flow-core-seed
```

## 🌊 Flow Ecosystem

The seed enables unlimited extension packages:

- `@obarlik/flow-pipeline` - Step chaining and composition
- `@obarlik/flow-streaming` - Circular buffers and streams  
- `@obarlik/flow-validation` - Input/output validation
- `@obarlik/flow-config` - Configuration management
- `@obarlik/flow-metrics` - Advanced observability
- `@obarlik/flow-testing` - Testing utilities
- `@obarlik/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

```typescript
import { 
  IFlowStep, 
  IFlowContext, 
  FlowResult, 
  success, 
  failure, 
  flowError 
} from '@obarlik/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](https://codechu.com) - [Obarlik](https://github.com/obarlik)

---

**The seed that grows into the entire Flow ecosystem** 🌱→🌳