@tstdl/base 0.93.138 → 0.93.140

package/rxjs-utils/README.md

@@ -0,0 +1,262 @@
+# rxjs-utils
+
+A collection of custom RxJS operators, Observable creators, and utilities designed to enhance reactive programming workflows. This module provides tools for type safety, advanced retry strategies, timing and scheduling, progressive data emission, and integration with reactive signals.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Type Casting](#type-casting)
+  - [Retry with Backoff](#retry-with-backoff)
+  - [Timing Observables](#timing-observables)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Progressive Array Emission](#progressive-array-emission)
+  - [Lifecycle Teardown](#lifecycle-teardown)
+  - [Signal Integration](#signal-integration)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type Safety Operators**: Explicitly cast observable types for better TypeScript inference.
+- **Retry Strategies**: Robust `retryBackoff` operators supporting exponential backoff and custom handling logic.
+- **Timing Sources**: Observables wrapping `requestAnimationFrame`, `requestIdleCallback`, `setImmediate`, and `process.nextTick`.
+- **Progressive Loading**: `slowArray` operators to emit array chunks over time (useful for rendering large lists).
+- **Lifecycle Hooks**: `teardown` operator to access the last emitted value or error when a subscription ends.
+- **Signal Integration**: `untrack` operator to prevent RxJS subscriptions from tracking dependencies within Signal effects.
+
+## Core Concepts
+
+### Robust Retries
+
+Standard RxJS `retry` is often too aggressive (immediate retry). `retryBackoff` implements delays (constant, linear, or exponential) between retries to prevent overwhelming failing services.
+
+### Scheduling & Timing
+
+Instead of using `interval` or `timer` for everything, this module provides specific observables for the browser's render loop (`animationFrame$`), idle periods (`idle$`), and Node.js event loop phases (`nextTick$`, `immediate$`).
+
+### Progressive Data
+
+When dealing with large datasets in a UI, emitting the entire array at once can freeze the interface. `slowArray` allows you to emit an initial chunk and then progressively add more items, smoothing out the rendering process.
+
+## 🚀 Basic Usage
+
+### Type Casting
+
+Use `cast` to assert a more specific type for an Observable, or `forceCast` to cast from `unknown`.
+
+```ts
+import { cast, forceCast } from '@tstdl/base/rxjs-utils';
+import { of } from 'rxjs';
+
+interface User {
+  id: string;
+  name: string;
+}
+interface Admin extends User {
+  permissions: string[];
+}
+
+const user$ = of({ id: '1', name: 'Alice', permissions: ['root'] } as User);
+const admin$ = of({ id: '1', name: 'Alice', permissions: ['root'] } as Admin);
+
+// Safe upcast: Admin to User (Admin extends User)
+const userFromAdmin$ = admin$.pipe(cast<Admin, User>());
+
+// Force cast: unknown to User
+const unknown$ = of<unknown>({ id: '2', name: 'Bob' });
+const forcedUser$ = unknown$.pipe(forceCast<User>());
+```
+
+### Retry with Backoff
+
+Handle temporary failures with exponential backoff.
+
+```ts
+import { retryBackoff } from '@tstdl/base/rxjs-utils';
+import { HttpClient } from '@tstdl/base/http/client'; // Example http client
+import { inject } from '@tstdl/base/injector';
+
+const http = inject(HttpClient);
+
+http
+  .get('https://api.example.com/data')
+  .pipe(
+    // Retry up to 3 times
+    // Initial delay 500ms, increasing exponentially
+    retryBackoff(3, {
+      strategy: 'exponential',
+      initialDelay: 500,
+      maximumDelay: 5000,
+    }),
+  )
+  .subscribe({
+    next: (response) => console.log('Success:', response),
+    error: (err) => console.error('Failed after retries:', err),
+  });
+```
+
+### Timing Observables
+
+Use specific schedulers for performance-critical tasks.
+
+```ts
+import { animationFrame$, idle$ } from '@tstdl/base/rxjs-utils';
+
+// Run logic on every animation frame (recursive)
+const renderLoop$ = animationFrame$.subscribe(() => {
+  // Update canvas or DOM
+});
+
+// Run logic only when the browser is idle
+const backgroundTask$ = idle$.subscribe((deadline) => {
+  console.log('Browser is idle, time remaining:', deadline.timeRemaining());
+});
+```
+
+## 🔧 Advanced Topics
+
+### Progressive Array Emission
+
+Use `slowArray` to emit a large array in chunks. This is useful for "infinite scroll" behavior or rendering large lists without blocking the main thread.
+
+```ts
+import { slowArray } from '@tstdl/base/rxjs-utils';
+
+const largeData = Array.from({ length: 1000 }, (_, i) => i);
+
+slowArray(largeData, {
+  delay: 0, // Start immediately
+  initialSize: 20, // Emit first 20 items immediately
+  interval: 50, // Add more items every 50ms
+  size: 10, // Add 10 items per interval
+}).subscribe((currentArray) => {
+  // currentArray grows: [0..19] -> [0..29] -> [0..39] ...
+  console.log(`Rendered ${currentArray.length} items`);
+});
+```
+
+To handle a stream of incoming arrays (e.g., from a search result that updates), use the `persistentSlowArray` operator. It maintains the current "chunk size" even when the underlying source array changes.
+
+```ts
+import { persistentSlowArray } from '@tstdl/base/rxjs-utils';
+import { fromEvent, map, debounceTime } from 'rxjs';
+
+// Imagine a search input emitting new results
+const searchResults$ = fromEvent(input, 'input').pipe(
+  debounceTime(300),
+  switchMap(q => fetchResults(q)), // returns Observable<Item[]>
+  persistentSlowArray({
+    interval: 100,
+    size: 5,
+    initialSize: 10
+  })
+);
+```
+
+### Lazy Initial Values
+
+Use `startWithProvider` when you need to emit an initial value that must be calculated at the exact moment of subscription (e.g., a timestamp or a value from another service).
+
+```ts
+import { startWithProvider } from '@tstdl/base/rxjs-utils';
+import { of } from 'rxjs';
+
+const source$ = of('event 1', 'event 2').pipe(
+  startWithProvider(() => `Started at ${new Date().toISOString()}`)
+);
+```
+
+### Lifecycle Teardown
+
+The `teardown` operator allows you to execute logic when the stream ends (completes, errors, or unsubscribes), with access to the last emitted value and the error (if any).
+
+```ts
+import { teardown } from '@tstdl/base/rxjs-utils';
+import { interval } from 'rxjs';
+
+const sub = interval(1000)
+  .pipe(
+    teardown((lastValue, error) => {
+      if (error) {
+        console.error('Stream crashed at:', lastValue, error);
+      } else {
+        console.log('Stream cleaned up. Last value was:', lastValue);
+      }
+    }),
+  )
+  .subscribe();
+
+setTimeout(() => sub.unsubscribe(), 2500);
+// Output after 2.5s: "Stream cleaned up. Last value was: 1"
+```
+
+### Signal Integration
+
+When using RxJS inside a reactive context (like `@tstdl/base/signals` effects), subscriptions might accidentally become dependencies. `untrack` wraps the subscription callbacks to prevent this.
+
+```ts
+import { untrack } from '@tstdl/base/rxjs-utils';
+import { effect } from '@tstdl/base/signals';
+import { interval } from 'rxjs';
+
+effect(() => {
+  // This subscription will NOT cause the effect to re-run
+  // when the observable emits, because the subscriber logic is untracked.
+  const sub = interval(1000)
+    .pipe(untrack())
+    .subscribe((val) => {
+      console.log(val);
+    });
+
+  return () => sub.unsubscribe();
+});
+```
+
+## 📚 API
+
+### Operators
+
+| Function                                          | Description                                                                                                     |
+| :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
+| `cast<Input, Output>()`                           | Casts an Observable from `Input` type to `Output` type (checked).                                               |
+| `forceCast<Output>()`                             | Casts an Observable from `unknown` to `Output` type.                                                            |
+| `noopOperator<T>()`                               | An operator that does nothing and passes values through unchanged.                                              |
+| `rejectErrors<T>()`                               | Suppresses errors from the source observable (stops emission on error without notifying downstream).            |
+| `retryBackoff<T>(count, options)`                 | Retries the source observable on error with a specified backoff strategy.                                       |
+| `retryBackoffHandled<T>(count, options, handler)` | Similar to `retryBackoff`, but allows a custom handler function to determine behavior or side effects on retry. |
+| `persistentSlowArray<T>(options)`                 | Operator version of `slowArray`. Emits growing arrays from a source array emission.                             |
+| `startWithProvider<T, D>(provider)`               | Like `startWith`, but accepts a function to lazily generate the initial value.                                  |
+| `teardown<T>(fn)`                                 | Registers a callback to run on finalization, receiving the last value and error.                                |
+| `untrack<T>()`                                    | Wraps subscription handlers in `untracked()` to prevent signal dependency tracking.                             |
+
+### Observable Creators
+
+| Function                       | Description                                                                      |
+| :----------------------------- | :------------------------------------------------------------------------------- |
+| `noop<T>(source)`              | Returns the source observable as is.                                             |
+| `slowArray<T>(array, options)` | Creates an observable that emits the provided array in growing chunks over time. |
+| `singleIdle$`                  | Emits once when the browser is idle (via `requestIdleCallback`).                 |
+| `idle$`                        | Emits repeatedly when the browser is idle.                                       |
+| `singleAnimationFrame$`        | Emits once on the next animation frame.                                          |
+| `animationFrame$`              | Emits repeatedly on every animation frame.                                       |
+| `singleImmediate$`             | Emits once via `setImmediate` (Node.js/Polyfill).                                |
+| `immediate$`                   | Emits repeatedly via `setImmediate`.                                             |
+| `microtask$`                   | Emits once via `queueMicrotask`.                                                 |
+| `singleNextTick$`              | Emits once via `process.nextTick`.                                               |
+| `nextTick$`                    | Emits repeatedly via `process.nextTick`.                                         |
+
+### Types
+
+| Type               | Description                                                                                                   |
+| :----------------- | :------------------------------------------------------------------------------------------------------------ |
+| `SlowArrayOptions` | Configuration for `slowArray` (`delay`, `initialSize`, `interval`, `size`).                                   |
+| `BackoffOptions`   | Configuration for retry backoff (`strategy`, `initialDelay`, `maximumDelay`, `increase`, `jitter`).           |
+| `BackoffStrategy`  | Either `'linear'` or `'exponential'`.                                                                         |
+| `IdleDeadline`     | The object passed to `idle$` subscribers, containing `timeRemaining()` and `didTimeout`. (native JS type)     |
+
+## 🏁 Platform Compatibility
+
+- **Browser**: Full support for all operators and observables, including `animationFrame$` and `idle$`.
+- **Node.js**: Full support, though `animationFrame$` and `idle$` require polyfills if used. `nextTick$` and `immediate$` are native to Node.js.
+- **Workers**: Support varies depending on the availability of `requestAnimationFrame` and `requestIdleCallback`.

package/schema/README.md

@@ -0,0 +1,342 @@
+# @tstdl/base/schema
+
+A powerful, TypeScript-first schema declaration and validation library. Define data structures once using builder functions or class decorators and get static types, runtime validation, and OpenAPI specifications for free.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Builder Functions](#builder-functions)
+  - [Class Decorators](#class-decorators)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Class-based Schemas](#class-based-schemas)
+  - [Type Coercion](#type-coercion)
+  - [Object Utilities](#object-utilities)
+  - [Recursive Schemas](#recursive-schemas)
+  - [OpenAPI Generation](#openapi-generation)
+  - [Function & Method Schemas](#function--method-schemas)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Type Safety**: Automatically infers TypeScript types directly from your schemas.
+- **Dual API**: Define schemas using functional builders or class decorators.
+- **Runtime Validation**: Robust validation for API payloads, configuration, and user input.
+- **Type Coercion**: Automatically convert input data (e.g., strings to numbers) during parsing.
+- **Detailed Error Reporting**: JSON-path based error reporting to pinpoint exactly where validation failed.
+- **OpenAPI Support**: Generate OpenAPI v3 schema definitions from your code.
+- **Reflection**: Leverages TypeScript metadata to infer schemas from class properties.
+- **Extensible**: Supports custom transformations and complex types like `Uint8Array` and `ReadableStream`.
+
+## Core Concepts
+
+The library provides two primary ways to define schemas. Both produce a `Schema` object that can be used for validation.
+
+### Builder Functions
+
+Ideal for defining data shapes on the fly, for API contracts, or when you don't need a class instance.
+
+```typescript
+import { object, string, number } from '@tstdl/base/schema';
+
+const userSchema = object({
+  name: string(),
+  age: number(),
+});
+```
+
+### Class Decorators
+
+Ideal for domain models where you want the class to serve as both the type definition and the validation schema. This requires `experimentalDecorators` and `emitDecoratorMetadata` in your `tsconfig.json`.
+
+```typescript
+import { Class, StringProperty, NumberProperty } from '@tstdl/base/schema';
+
+@Class()
+class User {
+  @StringProperty()
+  name: string;
+
+  @NumberProperty()
+  age: number;
+}
+```
+
+## 🚀 Basic Usage
+
+The `Schema` class provides static methods to validate and parse data.
+
+```typescript
+import { Schema, object, string, number, array, optional, SchemaError } from '@tstdl/base/schema';
+
+// 1. Define a schema
+const productSchema = object({
+  id: string(),
+  name: string(),
+  price: number({ minimum: 0 }),
+  tags: array(string()),
+  description: optional(string()),
+});
+
+// 2. Infer the TypeScript type (optional, but useful)
+type Product = Schema.Output<typeof productSchema>;
+
+// 3. Validate data
+const rawData = {
+  id: 'prod_123',
+  name: 'Super Widget',
+  price: 29.99,
+  tags: ['gadget', 'new'],
+};
+
+try {
+  // .parse() returns the typed value if valid, or throws SchemaError
+  const product = Schema.parse(productSchema, rawData);
+  console.log(`Validated product: ${product.name}`);
+} catch (error) {
+  if (error instanceof SchemaError) {
+    console.error('Validation failed:', error.message);
+  }
+}
+
+// .validate() returns a boolean
+const isValid = Schema.validate(productSchema, { id: 123 }); // false
+```
+
+## 🔧 Advanced Topics
+
+### Class-based Schemas
+
+You can use decorators to define schemas directly on your classes. The class constructor itself becomes a valid schema object.
+
+```typescript
+import { Schema, Class, StringProperty, NumberProperty, Array, Integer } from '@tstdl/base/schema';
+
+@Class()
+class User {
+  @StringProperty()
+  id: string;
+
+  @StringProperty()
+  username: string;
+
+  @Integer({ minimum: 18 })
+  age: number;
+
+  @Array(String)
+  roles: string[];
+}
+
+const input = {
+  id: 'u1',
+  username: 'admin',
+  age: 25,
+  roles: ['admin', 'editor'],
+};
+
+// Pass the Class constructor to Schema methods
+const user = Schema.parse(User, input);
+
+console.log(user instanceof User); // true
+console.log(user.username); // 'admin'
+```
+
+### Type Coercion
+
+When handling data from sources like query strings or form data, types are often strings. Enable `coerce` to automatically convert them.
+
+```typescript
+import { Schema, object, number, boolean, date } from '@tstdl/base/schema';
+
+const querySchema = object({
+  page: number({ integer: true }),
+  active: boolean(),
+  from: date(),
+});
+
+const rawQuery = {
+  page: '5',
+  active: 'true',
+  from: '2023-10-27',
+};
+
+// Enable coercion in the options
+const parsed = Schema.parse(querySchema, rawQuery, { coerce: true });
+
+console.log(typeof parsed.page); // 'number'
+console.log(typeof parsed.active); // 'boolean'
+console.log(parsed.from instanceof Date); // true
+```
+
+### Object Utilities
+
+Compose new schemas from existing ones using utilities similar to TypeScript's utility types.
+
+```typescript
+import { object, string, number, pick, omit, partial, assign } from '@tstdl/base/schema';
+
+const baseUser = object({
+  id: string(),
+  name: string(),
+  email: string(),
+  age: number(),
+});
+
+// Pick specific fields
+const userSummary = pick(baseUser, ['id', 'name']);
+
+// Omit sensitive fields
+const publicUser = omit(baseUser, ['email']);
+
+// Make all fields optional (e.g., for patch updates)
+const patchUser = partial(baseUser);
+
+// Merge schemas
+const timestampedUser = assign(
+  baseUser,
+  object({
+    createdAt: number(),
+    updatedAt: number(),
+  }),
+);
+```
+
+### Recursive Schemas
+
+Use `deferred` to define schemas that reference themselves, useful for tree structures.
+
+```typescript
+import { Schema, object, string, array, optional, deferred } from '@tstdl/base/schema';
+
+type Category = {
+  name: string;
+  children?: Category[];
+};
+
+const categorySchema = object({
+  name: string(),
+  children: optional(array(deferred(() => categorySchema))),
+});
+
+const tree = {
+  name: 'Root',
+  children: [{ name: 'Child A' }, { name: 'Child B', children: [{ name: 'Grandchild B.1' }] }],
+};
+
+const validTree = Schema.parse(categorySchema, tree);
+```
+
+### OpenAPI Generation
+
+Convert your schemas into OpenAPI v3 compatible JSON schema objects. This is perfect for generating API documentation automatically.
+
+```typescript
+import { object, string, integer, enumeration } from '@tstdl/base/schema';
+import { convertToOpenApiSchema } from '@tstdl/base/schema/converters';
+
+enum Status {
+  Active = 'active',
+  Inactive = 'inactive',
+}
+
+const apiResponseSchema = object({
+  id: string({ description: 'Unique identifier' }),
+  count: integer({ minimum: 0 }),
+  status: enumeration(Status),
+});
+
+const openApiSpec = convertToOpenApiSchema(apiResponseSchema);
+console.log(JSON.stringify(openApiSpec, null, 2));
+```
+
+### Function & Method Schemas
+
+You can define schemas for functions and class methods, validating both arguments and return values.
+
+```typescript
+import { Method, StringProperty, Integer } from '@tstdl/base/schema';
+
+class Calculator {
+  @Method([Integer(), Integer()], Integer())
+  add(a: number, b: number): number {
+    return a + b;
+  }
+}
+```
+
+## 📚 API
+
+### Static Methods
+
+| Method                                     | Description                                                                         |
+| :----------------------------------------- | :---------------------------------------------------------------------------------- |
+| `Schema.parse(schema, value, options?)`    | Validates and returns the typed value. Throws `SchemaError` on failure.             |
+| `Schema.validate(schema, value, options?)` | Returns `true` if valid, `false` otherwise.                                         |
+| `Schema.assert(schema, value, options?)`   | Asserts that `value` matches the schema (TypeScript type guard). Throws on failure. |
+| `Schema.test(schema, value, options?)`     | Returns a result object `{ valid: boolean, value?: T, error?: SchemaError }`.       |
+
+### Schema Builders
+
+| Function                  | Description                                                 |
+| :------------------------ | :---------------------------------------------------------- |
+| `string(options?)`        | Schema for strings. Supports regex pattern, min/max length. |
+| `number(options?)`        | Schema for numbers. Supports min/max.                       |
+| `integer(options?)`       | Schema for integers.                                        |
+| `boolean(options?)`       | Schema for booleans.                                        |
+| `date(options?)`          | Schema for `Date` objects.                                  |
+| `bigint(options?)`        | Schema for `bigint` values.                                 |
+| `symbol(options?)`        | Schema for `symbol` values.                                 |
+| `regexp(options?)`        | Schema for `RegExp` objects.                                |
+| `object(props, options?)` | Schema for objects with defined properties.                 |
+| `record(key, value)`      | Schema for objects/dictionaries with arbitrary keys.        |
+| `array(item, options?)`   | Schema for arrays.                                          |
+| `uint8Array(options?)`    | Schema for `Uint8Array`. Supports base64/hex coercion.      |
+| `readableStream()`        | Schema for `ReadableStream`.                                |
+| `enumeration(enum)`       | Schema for TypeScript enums or array of values.             |
+| `literal(value)`          | Schema for exact primitive values.                          |
+| `union(...schemas)`       | Schema matching any one of the provided schemas.            |
+| `instance(Class)`         | Schema checking `instanceof`.                               |
+| `any()`                   | Allows any value (use carefully).                           |
+| `unknown()`               | Allows any value but types it as `unknown`.                 |
+| `never()`                 | Allows no values.                                           |
+| `func(...)`               | Schema for functions.                                       |
+
+### Modifiers & Utilities
+
+| Function                 | Description                                          |
+| :----------------------- | :--------------------------------------------------- |
+| `optional(schema)`       | Allows `undefined`.                                  |
+| `nullable(schema)`       | Allows `null`.                                       |
+| `defaulted(schema, val)` | Provides a default value if input is null/undefined. |
+| `oneOrMany(schema)`      | Accepts a single item or an array of items.          |
+| `deferred(() => schema)` | Defers schema resolution (for recursion).            |
+| `transform(schema, fn)`  | Transforms the value after validation.               |
+| `pick(schema, keys)`     | Creates a new object schema with picked keys.        |
+| `omit(schema, keys)`     | Creates a new object schema without specified keys.  |
+| `partial(schema)`        | Makes all object properties optional.                |
+| `assign(...schemas)`     | Merges multiple object schemas.                      |
+
+### Decorators
+
+| Decorator            | Description                                          |
+| :------------------- | :--------------------------------------------------- |
+| `@Class(options?)`   | Marks a class as a schema source.                    |
+| `@Property(schema?)` | Defines a property schema.                           |
+| `@StringProperty()`  | Shortcut for `string()`.                             |
+| `@NumberProperty()`  | Shortcut for `number()`.                             |
+| `@Integer()`         | Shortcut for `integer()`.                            |
+| `@BooleanProperty()` | Shortcut for `boolean()`.                            |
+| `@DateProperty()`    | Shortcut for `date()`.                               |
+| `@Array(schema)`     | Shortcut for `array()`.                              |
+| `@Optional(schema?)` | Marks property as optional.                          |
+| `@Nullable(schema?)` | Marks property as nullable.                          |
+| `@Enumeration(enum)` | Shortcut for `enumeration()`.                        |
+| `@Method(...)`       | Defines schema for method arguments and return type. |
+| `@Parameter(name)`   | Defines schema/name for a parameter.                 |
+
+### Converters
+
+| Function                         | Description                                       |
+| :------------------------------- | :------------------------------------------------ |
+| `convertToOpenApiSchema(schema)` | Converts a schema to an OpenAPI v3 schema object. |