feat: data oriented package

.changeset/public-streets-pull.md

@@ -0,0 +1,5 @@
+---
+"@certes/ordo": minor
+---
+
+add ordo package

.changeset/tangy-actors-stop.md

@@ -0,0 +1,11 @@
+---
+"@certes/composition": patch
+"@certes/combinator": patch
+"@certes/common": patch
+"@certes/logic": patch
+"@certes/lazy": patch
+"@certes/list": patch
+"@certes/ordo": patch
+---
+
+Import readme warning addition (warranted the patch bump)

.gitignore

@@ -10,6 +10,7 @@ node_modules
 # Vitest
 .vitest
 coverage
+bench
 
 # TypeScript cache
 *.tsbuildinfo

packages/combinator/README.md

@@ -2,6 +2,17 @@
 
 Type-safe, pure functional combinators for TypeScript. A comprehensive collection of classical combinatory logic primitives for composable, point-free programming.
 
+> [!CAUTION]
+> ### ⚠️ Active Development & Alpha Status
+> This repository is currently undergoing **active development**.
+>
+> **Until `1.0.0` release:**
+> * **Stability:** APIs are subject to breaking changes without prior notice.
+> * **Releases:** Current releases (tags/npm packages) are strictly for **testing and integration feedback**.
+> * **Production:** Do not use this software in production environments where data integrity or high availability is required.
+
+---
+
 ## Installation
 ```bash
 npm install @certes/combinator

packages/common/README.md

@@ -2,6 +2,17 @@
 
 Common utility functions for functional programming patterns in TypeScript.
 
+> [!CAUTION]
+> ### ⚠️ Active Development & Alpha Status
+> This repository is currently undergoing **active development**.
+>
+> **Until `1.0.0` release:**
+> * **Stability:** APIs are subject to breaking changes without prior notice.
+> * **Releases:** Current releases (tags/npm packages) are strictly for **testing and integration feedback**.
+> * **Production:** Do not use this software in production environments where data integrity or high availability is required.
+
+---
+
 ## Installation
 ```bash
 npm install @certes/common

packages/composition/README.md

@@ -2,6 +2,17 @@
 
 Type-safe function composition utilities for TypeScript.
 
+> [!CAUTION]
+> ### ⚠️ Active Development & Alpha Status
+> This repository is currently undergoing **active development**.
+>
+> **Until `1.0.0` release:**
+> * **Stability:** APIs are subject to breaking changes without prior notice.
+> * **Releases:** Current releases (tags/npm packages) are strictly for **testing and integration feedback**.
+> * **Production:** Do not use this software in production environments where data integrity or high availability is required.
+
+---
+
 ## Installation
 ```bash
 npm install @certes/composition

packages/lazy/README.md

@@ -2,6 +2,17 @@
 
 Type-safe, reusable lazy iteration utilities for TypeScript. A comprehensive collection of curried functions for composable, memory-efficient data processing.
 
+> [!CAUTION]
+> ### ⚠️ Active Development & Alpha Status
+> This repository is currently undergoing **active development**.
+>
+> **Until `1.0.0` release:**
+> * **Stability:** APIs are subject to breaking changes without prior notice.
+> * **Releases:** Current releases (tags/npm packages) are strictly for **testing and integration feedback**.
+> * **Production:** Do not use this software in production environments where data integrity or high availability is required.
+
+---
+
 ## Installation
 ```bash
 npm install @certes/lazy
@@ -39,6 +50,149 @@ const evens = filter((x: number) => x % 2 === 0)([1, 2, 3, 4, 5, 6]);
 [...evens]; // [2, 4, 6]
 ```
 
+## When to Use Lazy vs Native
+
+### Use Lazy Evaluation When:
+
+#### Early Termination
+
+When you only need a subset of results:
+
+```typescript
+// ✅ Lazy: only processes 10 elements
+const firstTenEvens = pipe(
+  largeArray,
+  lazyMap(square),
+  lazyFilter(isEven),
+  take(10),
+  collect
+);
+
+// ❌ Native: processes ALL elements before slicing
+const firstTenEvens = largeArray
+  .map(square)      // Processes all elements
+  .filter(isEven)   // Filters all elements
+  .slice(0, 10);    // Then takes 10
+```
+
+#### Memory-Constrained Environments
+
+Lazy evaluation uses O(1) memory for transformations:
+
+```typescript
+// ✅ Lazy: constant memory usage
+const processed = pipe(
+  hugeDataset,
+  lazyMap(transform1),    // No intermediate array
+  lazyMap(transform2),    // No intermediate array
+  lazyFilter(predicate),  // No intermediate array
+  take(1000),
+  collect                  // Only final 1000 items in memory
+);
+
+// ❌ Native: O(n) memory for each step
+const processed = hugeDataset
+  .map(transform1)    // Creates array of _n_ items
+  .map(transform2)    // Creates another array of _n_ items
+  .filter(predicate)  // Creates another array
+  .slice(0, 1000);
+```
+
+#### Working with Infinite or Unknown-Size Streams
+
+```typescript
+// ✅ Lazy: can handle infinite sequences
+const fibonacci = iterate(
+  ([a, b]: [number, number]) => [b, a + b]
+)([0, 1]);
+
+const first100Fibs = pipe(
+  fibonacci,
+  map(([a]) => a),
+  take(100),
+  collect
+);
+
+// ❌ Native: impossible with infinite sequences
+```
+
+#### Complex Pipelines with Selective Processing
+
+When combining multiple operations where most elements get filtered out:
+
+```typescript
+// ✅ Lazy: faster for selective processing
+const errorLogs = pipe(
+  millionLogs,
+  lazyFilter(log => log.level === 'ERROR'),  // Only processes until 100 found
+  lazyMap(enrichLog),
+  take(100),
+  collect
+);
+```
+
+### Use Native Array Methods When:
+
+#### Processing All Elements
+
+When you need every element, native methods are optimized:
+
+```typescript
+// ✅ Native: faster for full consumption
+const doubled = smallArray.map(x => x * 2);
+
+// ❌ Lazy: overhead without benefit
+const doubled = collect(lazyMap(x => x * 2)(smallArray));
+```
+
+#### Simple Operations on Small Arrays (<1000 elements)
+
+The overhead of lazy evaluation isn't worth it for small datasets:
+
+```typescript
+// ✅ Native: simpler and faster for small arrays
+const result = [1, 2, 3, 4, 5]
+  .map(x => x * 2)
+  .filter(x => x > 5);
+
+// ❌ Lazy: unnecessary complexity
+const result = pipe(
+  [1, 2, 3, 4, 5],
+  lazyMap(x => x * 2),
+  lazyFilter(x => x > 5),
+  collect
+);
+```
+
+#### Random Access Needed
+
+When you need index-based access:
+
+```typescript
+// ✅ Native: O(1) index access
+const processed = array.map(transform);
+console.log(processed[500]);  // Instant access
+
+// ❌ Lazy: must iterate to index
+const processed = lazyMap(transform)(array);
+// No way to access element 500 without iterating
+```
+
+### Quick Decision Matrix
+
+| Scenario | Use Lazy? | Performance Gain |
+|----------|-----------|------------------|
+| Need first N results | ✅ Yes | 100x-10,000x |
+| Process until condition | ✅ Yes | 100x-3,000x |
+| Large dataset, small output | ✅ Yes | 10x-150x |
+| Infinite sequences | ✅ Yes | Only option |
+| Memory constraints | ✅ Yes | O(1) vs O(n) |
+| Process all elements | ❌ No | 2x-20x slower |
+| Small arrays (<1000) | ❌ No | 10x-20x slower |
+| Multiple iterations | ❌ No | Recomputes each time |
+| Need random access | ❌ No | Not supported |
+| Simple single operation | ❌ No | 3x-20x slower |
+
 ## API Reference
 
 ### Generators
@@ -195,25 +349,6 @@ collect(take(10)(map(([a]: [number, number]) => a)(fibs)));
 // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
 ```
 
-## Performance
-
-| Aspect | Characteristic |
-|--------|----------------|
-| **Evaluation** | Lazy — elements processed on demand |
-| **Memory** | O(1) for most operations |
-| **Reusability** | All iterables can be iterated multiple times |
-| **Short-circuit** | Operations like `take`, `find` stop early |
-
-```typescript
-// Only processes 3 elements, not 1 million
-const result = pipe(
-  filter((x: number) => x % 2 === 0),
-  take(3),
-  collect
-)(range(1, 1_000_000));
-// [2, 4, 6]
-```
-
 ## License
 
 MIT

packages/lazy/src/helpers/take-eager/index.ts

@@ -1,4 +1,4 @@
-import { compose } from '@certes/composition';
+import { compose } from '@certes/composition/compose';
 import { collect } from '@/helpers/collect';
 import { take } from '@/iterators/take';