@tstdl/base 0.93.139 → 0.93.141

package/document-management/tests/document-statistics.service.test.js

@@ -9,7 +9,6 @@ import { DocumentValidationExecution, DocumentValidationExecutionState, Document
 import { DocumentWorkflow, DocumentWorkflowState, DocumentWorkflowStep } from '../models/document-workflow.model.js';
 import { DocumentApproval } from '../models/document.model.js';
 import { configureDocumentManagement } from '../server/configure.js';
-import { migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCategoryTypeService } from '../server/services/document-category-type.service.js';
 import { DocumentCollectionService } from '../server/services/document-collection.service.js';
 import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
@@ -29,7 +28,7 @@ describe('DocumentStatisticsService', () => {
     const tenantId = crypto.randomUUID();
     beforeAll(async () => {
         ({ injector, database } = await setupIntegrationTest({
-            modules: { taskQueue: true },
+            modules: { taskQueue: true, documentManagement: true },
             orm: { schema },
         }));
         const mockObjectStorage = {
@@ -56,8 +55,8 @@ describe('DocumentStatisticsService', () => {
             fileObjectStorageModule: 'documents',
             fileUploadObjectStorageModule: 'document-uploads',
             filePreviewObjectStorageModule: 'document-previews',
+            injector,
         });
-        await runInInjectionContext(injector, migrateDocumentManagementSchema);
         documentService = await injector.resolveAsync(DocumentService);
         statsService = await injector.resolveAsync(DocumentStatisticsService);
         collectionService = await injector.resolveAsync(DocumentCollectionService);
@@ -288,7 +287,7 @@ describe('DocumentStatisticsService', () => {
             const stats = await statsService.getStatistics(tenantId, {
                 includeTotalCount: true,
                 collectionIds: [collection1.id],
-                categoryIds: [category1.id]
+                categoryIds: [category1.id],
             });
             expect(stats.totalCount).toBe(1); // Only Doc 1 matches both
         });
@@ -310,7 +309,7 @@ describe('DocumentStatisticsService', () => {
                 includeMimeTypeDistribution: true,
                 includeStorageUsage: true,
                 includeDataQuality: true,
-                collectionIds: [collection.id]
+                collectionIds: [collection.id],
             });
             expect(stats.totalCount).toBe(1);
             expect(stats.typeBreakdown?.[type.id]).toBe(1);
@@ -328,7 +327,7 @@ describe('DocumentStatisticsService', () => {
             const stats = await statsService.getStatistics(tenantId, {
                 includeTotalCount: true,
                 includeMimeTypeDistribution: true,
-                collectionIds: [collection.id]
+                collectionIds: [collection.id],
             });
             expect(stats.totalCount).toBe(1);
         });
@@ -346,7 +345,7 @@ describe('DocumentStatisticsService', () => {
             const stats = await statsService.getStatistics(tenantId, {
                 includeMimeTypeDistribution: true,
                 collectionIds: [collection.id],
-                categoryIds: [category.id]
+                categoryIds: [category.id],
             });
             expect(Object.keys(stats.mimeTypeDistribution ?? {}).length).toBeGreaterThan(0);
         });
@@ -366,7 +365,7 @@ describe('DocumentStatisticsService', () => {
             const stats = await statsService.getStatistics(tenantId, {
                 includeTagUsage: true,
                 collectionIds: [collection.id],
-                categoryIds: [category.id]
+                categoryIds: [category.id],
             });
             expect(stats.tagUsage?.[tag.id]).toBe(1);
         });
@@ -410,7 +409,7 @@ describe('DocumentStatisticsService', () => {
             });
             const stats = await statsService.getStatistics(tenantId, {
                 includeValidationFailures: true,
-                collectionIds: [collection.id]
+                collectionIds: [collection.id],
             });
             expect(stats.validationFailures).toBe(1);
         });
@@ -459,7 +458,7 @@ describe('DocumentStatisticsService', () => {
             const stats = await statsService.getStatistics(tenantId, {
                 includeValidationFailures: true,
                 collectionIds: [collection.id],
-                categoryIds: [category.id]
+                categoryIds: [category.id],
             });
             expect(stats.validationFailures).toBe(1);
         });
@@ -476,7 +475,7 @@ describe('DocumentStatisticsService', () => {
             }, new Uint8Array([1]));
             const stats = await statsService.getStatistics(tenantId, {
                 includeTypeBreakdown: true,
-                collectionIds: [collection.id]
+                collectionIds: [collection.id],
             });
             expect(stats.typeBreakdown?.[type.id]).toBe(1);
         });
@@ -488,7 +487,7 @@ describe('DocumentStatisticsService', () => {
                 includeStorageUsage: true,
                 includeTotalPages: true,
                 includeValidationFailures: true,
-                collectionIds: []
+                collectionIds: [],
             });
             expect(stats.totalCount).toBe(0);
             expect(stats.storageUsage).toBe(0);

package/document-management/tests/document-validation-ai-overrides.test.js

@@ -32,7 +32,6 @@ describe('AiValidationExecutor Overrides', () => {
     };
     beforeAll(async () => {
         ({ injector } = await setupIntegrationTest({
-            orm: { schema: 'document_management' },
             modules: { messageBus: true, signals: true, objectStorage: true },
         }));
         runInInjectionContext(injector, () => {

package/document-management/tests/document.service.test.js

@@ -6,7 +6,7 @@ import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
 import { DocumentWorkflowState, DocumentWorkflowStep } from '../models/document-workflow.model.js';
 import { DocumentApproval } from '../models/document.model.js';
 import { configureDocumentManagement } from '../server/configure.js';
-import { DocumentManagementConfiguration, migrateDocumentManagementSchema } from '../server/module.js';
+import { DocumentManagementConfiguration } from '../server/module.js';
 import { DocumentCollectionService } from '../server/services/document-collection.service.js';
 import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentWorkflowService } from '../server/services/document-workflow.service.js';
@@ -22,7 +22,7 @@ describe('DocumentService', () => {
     const tenantId = crypto.randomUUID();
     beforeAll(async () => {
         ({ injector, database } = await setupIntegrationTest({
-            modules: { taskQueue: true },
+            modules: { taskQueue: true, documentManagement: true },
             orm: { schema },
         }));
         const mockObjectStorage = {
@@ -49,8 +49,8 @@ describe('DocumentService', () => {
             fileObjectStorageModule: 'documents',
             fileUploadObjectStorageModule: 'document-uploads',
             filePreviewObjectStorageModule: 'document-previews',
+            injector,
         });
-        await runInInjectionContext(injector, migrateDocumentManagementSchema);
         documentService = await injector.resolveAsync(DocumentService);
         workflowService = await injector.resolveAsync(DocumentWorkflowService);
         collectionService = await injector.resolveAsync(DocumentCollectionService);

package/document-management/tests/enum-helpers.test.js

@@ -7,7 +7,6 @@ import { TaskQueue } from '../../task-queue/index.js';
 import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
 import { DocumentPropertyDataType } from '../models/document-property.model.js';
 import { configureDocumentManagement } from '../server/configure.js';
-import { migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCategoryTypeService } from '../server/services/document-category-type.service.js';
 import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentManagementService } from '../server/services/document-management.service.js';
@@ -24,7 +23,7 @@ describe('Document Management Extended Suite', () => {
     const otherTenantId = crypto.randomUUID();
     beforeAll(async () => {
         ({ injector, database } = await setupIntegrationTest({
-            modules: { taskQueue: false, messageBus: true },
+            modules: { taskQueue: false, messageBus: true, documentManagement: true },
             orm: { schema },
         }));
         injector.register(GenkitModuleOptions, { useValue: {} });
@@ -52,8 +51,8 @@ describe('Document Management Extended Suite', () => {
             fileObjectStorageModule: 'documents',
             fileUploadObjectStorageModule: 'document-uploads',
             filePreviewObjectStorageModule: 'document-previews',
+            injector,
         });
-        await runInInjectionContext(injector, migrateDocumentManagementSchema);
         documentManagementService = await injector.resolveAsync(DocumentManagementService);
         categoryTypeService = await injector.resolveAsync(DocumentCategoryTypeService);
         propertyService = await injector.resolveAsync(DocumentPropertyService);

package/dom/README.md

@@ -0,0 +1,213 @@
+# DOM Utilities
+
+A collection of browser-specific utilities for file interactions and reactive DOM observation. This module bridges standard DOM APIs with RxJS Observables and Signals to provide a modern, declarative developer experience for handling file downloads, uploads, and element observation.
+
+## Table of Contents
+
+1.  [✨ Features](#-features)
+2.  [Core Concepts](#core-concepts)
+3.  [🚀 Basic Usage](#-basic-usage)
+    - [File Download](#file-download)
+    - [File Selection](#file-selection)
+    - [Reactive Resize Observation](#reactive-resize-observation)
+4.  [🔧 Advanced Topics](#-advanced-topics)
+    - [Using Signals for Observation](#using-signals-for-observation)
+    - [Media Query Observation](#media-query-observation)
+    - [Touch Event Streams](#touch-event-streams)
+    - [Mutation & Performance Observation](#mutation--performance-observation)
+5.  [📚 API](#-api)
+
+## ✨ Features
+
+- **Programmatic File Download**: Trigger browser downloads from `Blob` or `File` objects without manual DOM manipulation.
+- **File Selection Dialog**: Open the native file picker programmatically and await the result.
+- **Reactive Observers**: RxJS Observable and Signal wrappers for standard browser observers:
+  - `IntersectionObserver` (Visibility)
+  - `ResizeObserver` (Dimensions)
+  - `MutationObserver` (DOM Tree Changes)
+  - `PerformanceObserver` (Metrics)
+  - `matchMedia` (Media Queries)
+- **Touch Event Stream**: Normalized observable stream for touch interactions.
+
+## Core Concepts
+
+### File Handling
+
+Standard HTML file inputs and download links often require imperative DOM manipulation (e.g., creating a hidden `<a>` tag, clicking it, and removing it). This module abstracts these patterns into simple function calls (`downloadFile`, `openFileSelectDialog`).
+
+### Reactive Observation
+
+Modern browser APIs like `ResizeObserver` and `IntersectionObserver` rely on callbacks. This module converts these APIs into **RxJS Observables** (suffixed with `$`) and **Signals** (no suffix). This allows you to compose DOM events with other asynchronous streams or use them directly in signal-based UI frameworks.
+
+The implementation handles resource management automatically. For example, `observeIntersection$` uses a caching mechanism to share underlying `IntersectionObserver` instances across multiple subscriptions with identical configurations.
+
+## 🚀 Basic Usage
+
+### File Download
+
+Trigger a download for a generated Blob.
+
+```ts
+import { downloadFile } from '@tstdl/base/dom';
+
+const content = new Blob(['Hello, World!'], { type: 'text/plain' });
+
+// Triggers a download of "hello.txt" in the browser
+downloadFile(content, 'hello.txt');
+```
+
+### File Selection
+
+Open a file dialog and await the user's selection.
+
+```ts
+import { openFileSelectDialog } from '@tstdl/base/dom';
+
+async function handleUpload() {
+  // Opens the native file picker
+  const files = await openFileSelectDialog({
+    accept: ['.jpg', '.png', 'image/jpeg'],
+    multiple: true,
+  });
+
+  if (files) {
+    console.log(`User selected ${files.length} files.`);
+    files.forEach((file) => console.log(file.name));
+  } else {
+    console.log('User cancelled the dialog.');
+  }
+}
+```
+
+### Reactive Resize Observation
+
+Observe changes to an element's size using RxJS.
+
+```ts
+import { observeResize$ } from '@tstdl/base/dom';
+
+const element = document.querySelector('#my-component')!;
+
+const subscription = observeResize$(element).subscribe((entry) => {
+  const { width, height } = entry.contentRect;
+  console.log(`New size: ${width}x${height}`);
+});
+
+// Cleanup when done
+// subscription.unsubscribe();
+```
+
+## 🔧 Advanced Topics
+
+### Using Signals for Observation
+
+For state-driven applications, you can use the Signal variants of the observers. These provide the current state synchronously.
+
+```ts
+import { observeIntersection } from '@tstdl/base/dom';
+import { effect } from '@tstdl/base/signals'; // Assuming a signal effect implementation
+
+const element = document.querySelector('#lazy-image')!;
+
+// Returns a Signal<IntersectionObserverEntry | undefined>
+const intersectionSignal = observeIntersection(element, { threshold: 0.5 });
+
+effect(() => {
+  const entry = intersectionSignal();
+  if (entry?.isIntersecting) {
+    console.log('Element is at least 50% visible!');
+    // Load image logic here...
+  }
+});
+```
+
+### Media Query Observation
+
+Reactively track media query matches (e.g., dark mode or viewport width).
+
+```ts
+import { observeMediaQuery$ } from '@tstdl/base/dom';
+
+// RxJS Observable
+observeMediaQuery$('(prefers-color-scheme: dark)').subscribe((isDark) => {
+  console.log('Dark mode is:', isDark ? 'Enabled' : 'Disabled');
+});
+
+// Or as a Signal
+import { observeMediaQuery } from '@tstdl/base/dom';
+const isMobile = observeMediaQuery('(max-width: 768px)');
+```
+
+### Touch Event Streams
+
+Normalize touch events (`start`, `move`, `end`, `cancel`) into a single observable stream. This is useful for building custom gestures.
+
+```ts
+import { observeTouch$ } from '@tstdl/base/dom';
+
+const canvas = document.querySelector('canvas')!;
+
+observeTouch$(canvas).subscribe((event) => {
+  if (event.start) {
+    console.log('Touch started at', event.start.touches[0].clientX);
+  }
+  if (event.move) {
+    // Handle drag
+  }
+  if (event.end) {
+    console.log('Touch ended');
+  }
+});
+```
+
+### Mutation & Performance Observation
+
+Observe DOM tree changes or performance metrics.
+
+```ts
+import { observeMutation$, observePerformance$ } from '@tstdl/base/dom';
+
+// Mutation Observer
+const list = document.querySelector('ul')!;
+observeMutation$(list, { childList: true }).subscribe((records) => {
+  console.log('List changed:', records);
+});
+
+// Performance Observer
+observePerformance$({ entryTypes: ['resource'] }).subscribe((list) => {
+  const entries = list.getEntries();
+  entries.forEach((entry) => console.log(`Resource loaded: ${entry.name}`));
+});
+```
+
+## 📚 API
+
+### File Utilities
+
+| Function                                                  | Description                                                                          |
+| :-------------------------------------------------------- | :----------------------------------------------------------------------------------- |
+| `downloadFile(content: Blob \| File, fileName?: string)`  | Triggers a browser download for the provided content.                                |
+| `openFileSelectDialog(options?: FileSelectDialogOptions)` | Opens a file selection dialog and returns a Promise resolving to `File[]` or `null`. |
+
+### Reactive Observers (RxJS & Signals)
+
+| Function                                  | Return Type                                      | Description                                               |
+| :---------------------------------------- | :----------------------------------------------- | :-------------------------------------------------------- |
+| `observeIntersection$(element, options?)` | `Observable<IntersectionObserverEntry>`          | Observes element intersection changes.                    |
+| `observeIntersection(element, options?)`  | `Signal<IntersectionObserverEntry \| undefined>` | Signal version of intersection observer.                  |
+| `observeResize$(element, options?)`       | `Observable<ResizeObserverEntry>`                | Observes element resize events.                           |
+| `observeResize(element, options?)`        | `Signal<ResizeObserverEntry \| undefined>`       | Signal version of resize observer.                        |
+| `observeMediaQuery$(query)`               | `Observable<boolean>`                            | Observes media query match status.                        |
+| `observeMediaQuery(query)`                | `Signal<boolean>`                                | Signal version of media query observer.                   |
+| `observeMutation$(nodes, options?)`       | `Observable<MutationRecord[]>`                   | Observes DOM mutations.                                   |
+| `observePerformance$(inits?, options?)`   | `Observable<PerformanceObserverEntryListLike>`   | Observes performance entries.                             |
+| `observeTouch$(element, options?)`        | `Observable<TouchEvents>`                        | Observes touch events (`start`, `move`, `end`, `cancel`). |
+
+### Types
+
+| Type                        | Description                                                              |
+| :-------------------------- | :----------------------------------------------------------------------- |
+| `FileSelectDialogOptions`   | Options for file selection (`accept`, `multiple`, `capture`).            |
+| `TouchEvents`               | Object containing optional `start`, `move`, `end`, `cancel` TouchEvents. |
+| `ObserveMutationOptions`    | Extends `MutationObserverInit` with optional triggers.                   |
+| `ObservePerformanceOptions` | Options for performance observation triggers.                            |

package/enumerable/README.md

@@ -0,0 +1,259 @@
+# Enumerable
+
+A powerful, fluent, LINQ-inspired library for querying, transforming, and manipulating synchronous and asynchronous iterables in TypeScript. It unifies array processing, generators, and streams under a single, lazy-evaluation API.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Asynchronous Streams](#asynchronous-streams)
+  - [Parallel Processing](#parallel-processing)
+  - [RxJS Observables](#rxjs-observables)
+  - [Multiplexing Streams](#multiplexing-streams)
+  - [Event Loop Interruption](#event-loop-interruption)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Fluent Interface**: Chain methods like `.filter()`, `.map()`, and `.reduce()` for readable and expressive data pipelines.
+- **Lazy Evaluation**: Operations are deferred until results are materialized, optimizing performance and memory usage.
+- **Unified API**: Consistent methods for both synchronous (`Enumerable`) and asynchronous (`AsyncEnumerable`) data sources.
+- **Parallel Execution**: Built-in support for concurrent processing in asynchronous streams (`parallelMap`, `parallelFilter`, `parallelTap`) to speed up I/O-bound tasks.
+- **Rich Toolset**: Includes advanced operations like `group`, `distinct`, `batch`, `pairwise`, `throttle`, and `retry`.
+- **Interoperability**: Seamlessly convert between Arrays, Sets, Generators, Promises, and RxJS Observables.
+- **Event Loop Friendly**: Built-in methods to yield control back to the event loop during heavy processing (`interruptEvery`, `interruptPerSecond`).
+
+## Core Concepts
+
+### `Enumerable<T>`
+
+Wraps standard synchronous iterables (Arrays, Sets, Maps, Generators). It executes operations synchronously and lazily. No iteration happens until a terminal method (like `toArray`, `first`, or `reduce`) is called.
+
+### `AsyncEnumerable<T>`
+
+Wraps asynchronous iterables (`AsyncIterable`, `Promise<Iterable>`, `Observable`). It allows you to process streams of data over time. It supports **concurrency** control, allowing you to process multiple items in parallel while maintaining a simple fluent chain.
+
+## 🚀 Basic Usage
+
+### Synchronous Data Processing
+
+```typescript
+import { Enumerable } from '@tstdl/base/enumerable';
+
+const users = [
+  { id: 1, name: 'Alice', age: 30, active: true },
+  { id: 2, name: 'Bob', age: 25, active: false },
+  { id: 3, name: 'Charlie', age: 35, active: true },
+];
+
+const names = Enumerable.from(users)
+  .filter((u) => u.active)
+  .sort((a, b) => a.age - b.age)
+  .map((u) => u.name)
+  .toArray();
+
+console.log(names); // ['Alice', 'Charlie']
+```
+
+### Grouping Data
+
+Easily group data into Maps or Arrays.
+
+```typescript
+import { Enumerable } from '@tstdl/base/enumerable';
+
+const numbers = [1, 2, 3, 4, 5, 6];
+
+// Group by even/odd
+const grouped = Enumerable.from(numbers).groupToMap((n) => (n % 2 === 0 ? 'even' : 'odd'));
+
+console.log(grouped.get('even')); // [2, 4, 6]
+console.log(grouped.get('odd')); // [1, 3, 5]
+```
+
+## 🔧 Advanced Topics
+
+### Asynchronous Streams
+
+`AsyncEnumerable` works natively with async generators and APIs.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+async function* fetchPages() {
+  yield [1, 2, 3];
+  await new Promise((r) => setTimeout(r, 100));
+  yield [4, 5, 6];
+}
+
+const total = await AsyncEnumerable.from(fetchPages())
+  .mapMany((page) => page) // Flatten arrays
+  .filter((n) => n % 2 === 0)
+  .reduce((sum, n) => sum + n, 0);
+
+console.log(total); // 12 (2 + 4 + 6)
+```
+
+### Parallel Processing
+
+Process async tasks concurrently to improve throughput. This is ideal for batch API calls or file processing.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+const ids = [1, 2, 3, 4, 5];
+
+const results = await AsyncEnumerable.from(ids)
+  .parallelMap(3, true, async (id) => {
+    // Simulate network request with concurrency of 3
+    // 'true' ensures output order matches input order
+    const data = await fetch(`https://api.example.com/items/${id}`);
+    return data.json();
+  })
+  .toArray();
+```
+
+### RxJS Observables
+
+Convert RxJS Observables directly into `AsyncEnumerable` to use LINQ-style operators on streams.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+import { interval } from 'rxjs';
+import { take } from 'rxjs/operators';
+
+const observable = interval(100).pipe(take(5));
+
+await AsyncEnumerable.fromObservable(observable)
+  .map((n) => n * 2)
+  .forEach((n) => console.log(n));
+// Output: 0, 2, 4, 6, 8
+```
+
+### Multiplexing Streams
+
+Split a single async source into multiple independent consumers. This is useful when you need to process the same stream in different ways simultaneously.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+const source = AsyncEnumerable.fromRange(1, 5);
+
+// Create 2 independent branches from the source
+const [branchA, branchB] = source.multiplex(2);
+
+const taskA = branchA.filter((n) => n % 2 === 0).toArray();
+
+const taskB = branchB.map((n) => n * 10).toArray();
+
+const [evens, multiplied] = await Promise.all([taskA, taskB]);
+
+console.log(evens); // [2, 4]
+console.log(multiplied); // [10, 20, 30, 40, 50]
+```
+
+### Event Loop Interruption
+
+When processing large datasets asynchronously, you may want to prevent blocking the event loop for too long. `AsyncEnumerable` provides methods to automatically yield control back to the event loop.
+
+```typescript
+import { AsyncEnumerable } from '@tstdl/base/enumerable';
+
+const largeDataset = AsyncEnumerable.fromRange(1, 1_000_000);
+
+await largeDataset
+  .interruptEvery(1000) // Yield control every 1000 items
+  .forEach((item) => {
+    // Heavy processing
+  });
+
+await largeDataset
+  .interruptPerSecond(60) // Ensure the event loop is yielded at least 60 times per second
+  .forEach((item) => {
+    // Heavy processing
+  });
+```
+
+## 📚 API
+
+### Static Creation Methods
+
+| Class             | Method                  | Description                                                                    |
+| :---------------- | :---------------------- | :----------------------------------------------------------------------------- |
+| `Enumerable`      | `from(source)`          | Creates an `Enumerable` from an `Iterable`.                                    |
+| `Enumerable`      | `fromDeferred(factory)` | Creates an `Enumerable` that calls the factory function when iteration starts. |
+| `Enumerable`      | `fromRange(from, to)`   | Creates an `Enumerable` of numbers in a range (inclusive).                     |
+| `AsyncEnumerable` | `from(source)`          | Creates an `AsyncEnumerable` from an `AnyIterable` (sync or async).            |
+| `AsyncEnumerable` | `fromDeferred(factory)` | Creates an `AsyncEnumerable` from a factory returning an iterable or promise.  |
+| `AsyncEnumerable` | `fromObservable(obs)`   | Creates an `AsyncEnumerable` from an RxJS `Observable`.                        |
+| `AsyncEnumerable` | `fromRange(from, to)`   | Creates an `AsyncEnumerable` of numbers in a range.                            |
+
+### Common Methods (Sync & Async)
+
+These methods exist on both `Enumerable` and `AsyncEnumerable`. Async versions return `Promise` for terminal operations and `AsyncEnumerable` for transformations.
+
+| Category           | Method                    | Description                                                                              |
+| :----------------- | :------------------------ | :--------------------------------------------------------------------------------------- |
+| **Filtering**      | `filter(predicate)`       | Filters elements based on a predicate.                                                   |
+|                    | `filterNullOrUndefined()` | Removes `null` and `undefined` values.                                                   |
+|                    | `distinct(selector?)`     | Returns distinct elements (optionally by key).                                           |
+|                    | `take(count)`             | Takes the first `N` elements.                                                            |
+|                    | `skip(count)`             | Skips the first `N` elements.                                                            |
+|                    | `takeWhile(yieldLast, p)` | Takes elements while the predicate is true.                                              |
+|                    | `takeUntil(signal)`       | Takes elements until a `CancellationSignal` is triggered.                                |
+|                    | `while(predicate)`        | Iterates while the predicate is true.                                                    |
+| **Transformation** | `map(mapper)`             | Projects each element into a new form.                                                   |
+|                    | `mapMany(mapper)`         | Projects each element to an iterable and flattens the result.                            |
+|                    | `batch(size)`             | Groups elements into arrays of a specific size.                                          |
+|                    | `pairwise()`              | Emits the previous and current element as a tuple `[prev, curr]`.                        |
+|                    | `materialize()`           | Converts the sequence into a sequence of `Notification` objects (next, error, complete). |
+|                    | `metadata()`              | Wraps elements with metadata (index, isFirst, isLast).                                   |
+| **Set Operations** | `concat(...iterables)`    | Concatenates multiple iterables.                                                         |
+|                    | `difference(other, sel?)` | Returns elements present in source but not in other.                                     |
+|                    | `differenceMany(its, s?)` | Returns elements present in source but not in any of the others.                         |
+|                    | `defaultIfEmpty(default)` | Returns a default value if the sequence is empty.                                        |
+| **Aggregation**    | `reduce(reducer, init?)`  | Aggregates the sequence into a single value.                                             |
+|                    | `toArray()`               | Materializes the sequence into an array.                                                 |
+|                    | `toSet()`                 | Materializes the sequence into a Set.                                                    |
+|                    | `group(selector)`         | Groups elements into `[Key, T[]]` pairs.                                                 |
+|                    | `groupSingle(selector)`   | Groups elements into `[Key, T]` pairs (last wins).                                       |
+|                    | `groupToMap(selector)`    | Groups elements into a `Map<Key, T[]>`.                                                  |
+|                    | `groupToSingleMap(sel)`   | Groups elements into a `Map<Key, T>` (last wins).                                        |
+| **Inspection**     | `all(predicate)`          | Checks if all elements satisfy the predicate.                                            |
+|                    | `any(predicate)`          | Checks if any element satisfies the predicate.                                           |
+|                    | `includes(value)`         | Checks if the sequence contains a specific value.                                        |
+|                    | `first(predicate?)`       | Returns the first element (throws if empty).                                             |
+|                    | `firstOrDefault(def, p?)` | Returns the first element or a default value.                                            |
+|                    | `last(predicate?)`        | Returns the last element.                                                                |
+|                    | `lastOrDefault(def, p?)`  | Returns the last element or a default value.                                             |
+|                    | `single(predicate?)`      | Returns the only element (throws if not exactly one).                                    |
+|                    | `singleOrDefault(def, p)` | Returns the single element or a default value.                                           |
+| **Sorting**        | `sort(comparator?)`       | Sorts the sequence lazily.                                                               |
+|                    | `sortToArray(comparator?)`| Sorts the sequence and returns an array immediately.                                     |
+| **Side Effects**   | `tap(action)`             | Executes an action for each element without modifying the stream.                        |
+|                    | `forEach(action)`         | Iterates over the sequence (terminal operation).                                         |
+|                    | `drain()`                 | Consumes the entire sequence and discards results.                                       |
+| **Utility**        | `assert(predicate)`       | Verifies that each element satisfies the predicate, throws otherwise.                    |
+|                    | `cast<TNew>()`            | Casts the sequence to a new type (unsafe).                                               |
+|                    | `forceCast<TNew>()`       | Force casts the sequence to a new type (unsafe).                                         |
+|                    | `toAsync()`               | Converts the sequence to an `AsyncEnumerable`.                                           |
+|                    | `toIterator()`            | Returns the underlying iterator.                                                         |
+
+### Async-Only Methods (`AsyncEnumerable`)
+
+| Method                                              | Description                                                                              |
+| :-------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| `parallelMap(concurrency, keepOrder, mapper)`       | Maps elements concurrently.                                                              |
+| `parallelFilter(concurrency, keepOrder, predicate)` | Filters elements concurrently.                                                           |
+| `parallelTap(concurrency, keepOrder, action)`       | Taps elements concurrently.                                                              |
+| `parallelForEach(concurrency, action)`              | Iterates elements concurrently.                                                          |
+| `parallelGroup(concurrency, selector)`              | Groups elements concurrently (returns `Promise<Map>`).                                   |
+| `interruptEvery(value)`                             | Yields control to the event loop every `N` elements.                                     |
+| `interruptPerSecond(value)`                         | Yields control to the event loop `N` times per second.                                   |
+| `throttle(delayOrFunction)`                         | Limits the rate of emission.                                                             |
+| `retry(throwOnFalse, predicate)`                    | Retries the source sequence on error based on a predicate.                               |
+| `multiplex(count, buffer?)`                         | Splits the stream into multiple independent streams.                                     |
+| `buffer(size)`                                      | Buffers elements and emits them as soon as they are available (flow control).            |
+| `toSync()`                                          | Resolves the entire async sequence into a synchronous `Enumerable` (returns `Promise`).  |