@tstdl/base 0.93.138 → 0.93.140

package/cookie/README.md

@@ -0,0 +1,161 @@
+# @tstdl/base/cookie
+
+A lightweight, type-safe utility module for handling HTTP cookies. It provides functions to parse `Cookie` header strings into usable maps and to format `Set-Cookie` header strings with support for modern attributes like `SameSite`, `Partitioned`, and `Priority`.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+  - [Parsing Cookies](#parsing-cookies)
+  - [Formatting Set-Cookie](#formatting-set-cookie)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Modern Cookie Attributes](#modern-cookie-attributes)
+  - [Expiration and Max-Age](#expiration-and-max-age)
+  - [Deleting Cookies](#deleting-cookies)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Robust Parsing**: Converts raw `Cookie` header strings into a standard JavaScript `Map`. Supports quoted values and automatic decoding.
+- **Comprehensive Formatting**: Generates `Set-Cookie` strings supporting standard and modern attributes.
+- **Automatic Encoding**: Handles URL encoding and decoding of cookie values automatically.
+- **Modern Standards**: Supports `Partitioned` (CHIPS), `Priority`, and `SameSite` attributes.
+- **Type Safety**: Fully typed options for compile-time safety.
+
+## Core Concepts
+
+HTTP Cookies are small pieces of data stored on the user's device. They are exchanged between the client and server via HTTP headers.
+
+1.  **Parsing (`Cookie` Header)**: When a browser sends a request, it includes cookies in a single string (e.g., `name=value; name2=value2`). This module parses that string into a key-value map for easy access.
+2.  **Formatting (`Set-Cookie` Header)**: To store a cookie on the client, the server sends a `Set-Cookie` header. This string includes the name, value, and various directives (attributes) that control the cookie's scope, security, and lifetime.
+
+## 🚀 Basic Usage
+
+### Parsing Cookies
+
+Use `parseCookieString` to convert a raw cookie header string (typically found in `req.headers.cookie`) into a `Map`.
+
+```ts
+import { parseCookieString } from '@tstdl/base/cookie';
+
+// Simulating a raw header string received from a browser
+const rawCookieHeader = 'session_id=abc-123; theme=dark; user_preferences="%7B%22notifications%22%3Atrue%7D"';
+
+const cookies = parseCookieString(rawCookieHeader);
+
+// Access values
+const sessionId = cookies.get('session_id'); // 'abc-123'
+const theme = cookies.get('theme'); // 'dark'
+
+// Values are automatically URL-decoded and quotes are stripped
+const userPrefs = cookies.get('user_preferences'); // '{"notifications":true}'
+
+if (cookies.has('session_id')) {
+  console.log('Session active:', sessionId);
+}
+```
+
+### Formatting Set-Cookie
+
+Use `formatSetCookie` to generate the string value for a `Set-Cookie` HTTP response header.
+
+```ts
+import { formatSetCookie } from '@tstdl/base/cookie';
+
+// Create a secure, HTTP-only session cookie
+const setCookieHeader = formatSetCookie('session_id', 'xyz-secret-token', {
+  path: '/',
+  httpOnly: true,
+  secure: true,
+  sameSite: 'strict',
+});
+
+console.log(setCookieHeader);
+// Output: session_id=xyz-secret-token; Path=/; HttpOnly; SameSite=Strict; Secure
+```
+
+## 🔧 Advanced Topics
+
+### Modern Cookie Attributes
+
+The module supports modern attributes required for specific browser behaviors, such as `Partitioned` (for CHIPS) and `Priority`.
+
+```ts
+import { formatSetCookie } from '@tstdl/base/cookie';
+
+const crossSiteCookie = formatSetCookie('widget_session', '123', {
+  path: '/',
+  secure: true,
+  // Required for cookies sent in cross-site contexts (e.g., iframes)
+  sameSite: 'none',
+  // Cookies Having Independent Partitioned State (CHIPS)
+  partitioned: true,
+  // Hint to the browser about the cookie's importance
+  priority: 'high',
+});
+
+console.log(crossSiteCookie);
+// Output: widget_session=123; Path=/; SameSite=None; Priority=High; Secure; Partitioned
+```
+
+### Expiration and Max-Age
+
+You can define the lifetime of a cookie using either `expires` (absolute date) or `maxAge` (relative seconds).
+
+```ts
+import { formatSetCookie } from '@tstdl/base/cookie';
+
+// Using Max-Age (in seconds)
+const oneHourCookie = formatSetCookie('temp_data', 'foo', {
+  maxAge: 3600, // 1 hour
+});
+
+// Using Expires (Date object or timestamp in milliseconds)
+const nextWeek = new Date();
+nextWeek.setDate(nextWeek.getDate() + 7);
+
+const persistentCookie = formatSetCookie('permanent_data', 'bar', {
+  expires: nextWeek,
+});
+```
+
+### Deleting Cookies
+
+To delete a cookie, you should set its expiration to the past or its `maxAge` to 0.
+
+```ts
+import { formatSetCookie } from '@tstdl/base/cookie';
+
+// Option 1: Set maxAge to 0
+const deleteCookie1 = formatSetCookie('session_id', '', {
+  maxAge: 0,
+});
+
+// Option 2: Set expires to a date in the past
+const deleteCookie2 = formatSetCookie('session_id', '', {
+  expires: new Date(0),
+});
+```
+
+## 📚 API
+
+| Name                | Type                                                                  | Description                                                                            |
+| :------------------ | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
+| `formatSetCookie`   | `(name: string, value: string, options?: SetCookieOptions) => string` | Formats a cookie name, value, and options into a `Set-Cookie` header string.           |
+| `parseCookieString` | `(cookieString: string) => Map<string, string>`                       | Parses a `Cookie` header string into a Map of key-value pairs. Values are URL-decoded. |
+| `SetCookieOptions`  | `Type`                                                                | Configuration object for cookie attributes.                                            |
+
+### SetCookieOptions
+
+| Property      | Type                          | Description                                                                                     |
+| :------------ | :---------------------------- | :---------------------------------------------------------------------------------------------- |
+| `domain`      | `string`                      | Specifies the domain for which the cookie is valid.                                             |
+| `expires`     | `Date \| number`              | Date or timestamp (in milliseconds) when the cookie expires.                                     |
+| `httpOnly`    | `boolean`                     | If true, the cookie is inaccessible to the JavaScript `Document.cookie` API.                    |
+| `maxAge`      | `number`                      | Number of seconds until the cookie expires.                                                     |
+| `partitioned` | `boolean`                     | If true, sets the `Partitioned` attribute (CHIPS). Requires `secure` to be true.                 |
+| `path`        | `string`                      | Specifies the path for which the cookie is valid.                                               |
+| `sameSite`    | `'strict' \| 'lax' \| 'none'` | Controls whether the cookie is sent with cross-site requests.                                   |
+| `priority`    | `'low' \| 'medium' \| 'high'` | Hints at the priority of the cookie for browser retention.                                      |
+| `secure`      | `boolean`                     | If true, the cookie is only sent to the server when a request is made with the `https:` scheme. |

package/css/README.md

@@ -0,0 +1,157 @@
+# CSS
+
+A utility module for programmatically managing CSS variables (custom properties) using the modern Constructable Stylesheets API. It provides a type-safe, disposable interface for dynamic theming and runtime style manipulation without the overhead of managing `<style>` tags or inline styles.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+- [🚀 Basic Usage](#-basic-usage)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [Scoped Selectors](#scoped-selectors)
+  - [Namespacing with Prefixes](#namespacing-with-prefixes)
+  - [Batch Operations & Cleanup](#batch-operations--cleanup)
+  - [Lifecycle Management (Disposal)](#lifecycle-management-disposal)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Constructable Stylesheets**: Leverages `document.adoptedStyleSheets` for performant style application.
+- **Scoped Variables**: Apply variables globally (`:root`) or target specific CSS selectors.
+- **Automatic Prefixing**: Automatically handles the `--` syntax for custom properties.
+- **Batch Updates**: Set multiple variables simultaneously.
+- **Disposable**: Implements the `Disposable` interface for automatic cleanup of stylesheets.
+- **Type Safe**: Written in TypeScript for robust development.
+
+## Core Concepts
+
+This module abstracts the **CSS Object Model (CSSOM)** to simplify the management of CSS Custom Properties.
+
+Instead of appending `<style>` elements to the DOM or manipulating the `style` attribute of individual elements, this module creates a `CSSStyleSheet` in memory and adopts it into the document. This approach is generally more performant for global or shared styles (like themes) and keeps the DOM clean.
+
+The `CssVariables` class manages a single CSS rule within a dedicated stylesheet. You can define the **selector** (where the variables apply) and an optional **prefix** (to namespace your variables).
+
+## 🚀 Basic Usage
+
+The most common use case is setting global theme variables on the `:root` selector.
+
+```ts
+import { cssVariables } from '@tstdl/base/css';
+
+// Create a manager for :root variables
+const theme = cssVariables();
+
+// Set a variable (automatically adds '--' if missing)
+theme.set('primary-color', '#3498db');
+theme.set('font-size', '16px');
+
+// Read a value
+const color = theme.get('primary-color');
+console.log(color); // " #3498db" (note: browser may add whitespace)
+
+// The styles are now active in the document
+```
+
+## 🔧 Advanced Topics
+
+### Scoped Selectors
+
+You can restrict the CSS variables to a specific selector, such as a class name or an ID. This is useful for component-specific theming.
+
+```ts
+import { cssVariables } from '@tstdl/base/css';
+
+// Apply variables only to elements with the class .dark-mode-container
+const darkTheme = cssVariables('.dark-mode-container');
+
+darkTheme.set('background', '#000000');
+darkTheme.set('text', '#ffffff');
+```
+
+### Namespacing with Prefixes
+
+To avoid collisions or group related variables, you can provide a prefix. The module handles the double hyphen syntax automatically.
+
+```ts
+import { cssVariables } from '@tstdl/base/css';
+
+// Variables will be prefixed with '--my-app-'
+const appSettings = cssVariables(':root', 'my-app-');
+
+// Sets '--my-app-spacing'
+appSettings.set('spacing', '1rem');
+
+// Sets '--my-app-header-height'
+appSettings.set('header-height', '64px');
+```
+
+### Batch Operations & Cleanup
+
+Use `setMany` to apply multiple variables at once using an object or an array of entries. You can also delete specific variables or clear the entire rule.
+
+```ts
+import { cssVariables } from '@tstdl/base/css';
+
+const theme = cssVariables();
+
+// Batch update
+theme.setMany({
+  'color-primary': 'blue',
+  'color-secondary': 'green',
+  'border-radius': '4px',
+});
+
+// Delete a single variable
+theme.delete('color-secondary');
+
+// Clear all variables in this manager
+theme.clear();
+```
+
+### Lifecycle Management (Disposal)
+
+The `CssVariables` class implements the `Disposable` interface (`Symbol.dispose`). When the object is disposed, the underlying stylesheet is removed from `document.adoptedStyleSheets`, effectively reverting the changes.
+
+This is particularly useful with the TypeScript `using` keyword (or manual `dispose` calls) for temporary styles.
+
+```ts
+import { cssVariables } from '@tstdl/base/css';
+
+function applyTemporaryTheme() {
+  // 'using' ensures the stylesheet is removed when the scope exits
+  using tempTheme = cssVariables();
+
+  tempTheme.set('overlay-color', 'rgba(0,0,0,0.5)');
+
+  // ... perform operations with the theme active ...
+} // tempTheme is disposed here, removing the CSS variables from the document
+```
+
+## 📚 API
+
+### Functions
+
+| Function                           | Description                                                                                              |
+| :--------------------------------- | :------------------------------------------------------------------------------------------------------- |
+| `cssVariables(selector?, prefix?)` | Factory function to create a new `CssVariables` instance. Defaults to `:root` selector and empty prefix. |
+
+### Classes
+
+#### `CssVariables`
+
+Implements `Disposable`.
+
+| Method             | Signature                                                                             | Description                                                                       |
+| :----------------- | :------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------- |
+| `constructor`      | `(selector: string \| null, prefix?: string)`                                         | Creates a new stylesheet adopted by the document. `selector` defaults to `:root`. |
+| `set`              | `(name: string, value: string): void`                                                 | Sets a CSS variable. Automatically handles the `--` prefix.                       |
+| `setMany`          | `(variables: Record<string, string> \| readonly (readonly [string, string])[]): void` | Sets multiple variables at once.                                                  |
+| `get`              | `(name: string): string \| null`                                                      | Retrieves the value of a CSS variable. Returns `null` if not set.                 |
+| `delete`           | `(name: string): void`                                                                | Removes a CSS variable from the rule.                                             |
+| `clear`            | `(): void`                                                                            | Clears all properties from the rule.                                              |
+| `[Symbol.dispose]` | `(): void`                                                                            | Removes the stylesheet from the document.                                         |
+
+| Property   | Type     | Description                                 |
+| :--------- | :------- | :------------------------------------------ |
+| `selector` | `string` | The CSS selector targeted by this instance. |
+| `prefix`   | `string` | The prefix applied to variable names.       |

package/data-structures/README.md

@@ -0,0 +1,320 @@
+# @tstdl/base/data-structures
+
+A comprehensive library of advanced, observable, and strongly-typed data structures for TypeScript, providing powerful alternatives to native collections with reactive capabilities.
+
+## Table of Contents
+
+- [✨ Features](#-features)
+- [Core Concepts](#core-concepts)
+  - [Collection Hierarchy](#collection-hierarchy)
+  - [Observability](#observability)
+- [🚀 Basic Usage](#-basic-usage)
+  - [ArrayList](#arraylist)
+  - [MapDictionary](#mapdictionary)
+  - [SetCollection](#setcollection)
+- [🔧 Advanced Topics](#-advanced-topics)
+  - [CircularBuffer](#circularbuffer)
+  - [SortedArrayList](#sortedarraylist)
+  - [Multi-Key Collections](#multi-key-collections)
+  - [Weak Reference Maps](#weak-reference-maps)
+  - [ContextDataMap](#contextdatamap)
+  - [Native Adapters](#native-adapters)
+- [📚 API](#-api)
+
+## ✨ Features
+
+- **Observable State**: Track changes, size, and emptiness via RxJS Observables (`size$`, `change$`) and Signals (`$size`, `$observe`).
+- **Rich Collection Set**: Includes Lists (Array, Sorted, Linked), Dictionaries, Sets, Circular Buffers, and LRU Caches.
+- **Specialized Maps**: Advanced implementations like `MultiKeyMap` (nested keys), `IterableWeakMap` (iterable weak keys), and `WeakRefMap` (weak values).
+- **Native Compatibility**: Seamlessly adapt custom structures to standard `Map` and `Set` interfaces using `asMap()` and `asSet()`.
+- **Type Safety**: Built with rigorous TypeScript generics to ensure type safety across all operations.
+
+## Core Concepts
+
+### Collection Hierarchy
+
+The module is built on a robust hierarchy of abstract base classes:
+
+- **`Collection<T>`**: The root of the hierarchy. Provides observability (`size$`, `change$`, `$size`, `$observe`) and standard methods like `add`, `clear`, and `items()`.
+- **`List<T>`**: Extends `Collection` for ordered, indexed data. Adds `at(index)`, `indexOf(item)`, `removeAt(index)`, and `set(index, item)`.
+- **`Dictionary<K, V>`**: Extends `Collection` for key-value pairs. Adds `get(key)`, `set(key, value)`, `has(key)`, and `delete(key)`.
+- **`DistinctCollection<T>`**: Extends `Collection` for unique values (Sets). Adds `has(value)` and `delete(value)`.
+
+### Observability
+
+All data structures in this library are reactive. You can subscribe to changes or use signals for efficient UI updates or side effects.
+
+```typescript
+import { ArrayList } from '@tstdl/base/data-structures';
+
+const list = new ArrayList<string>();
+
+// RxJS Observable
+list.size$.subscribe((size) => console.log(`Size: ${size}`));
+
+// Signal (if using a signal-compatible environment)
+console.log(list.$isEmpty());
+
+list.add('Hello'); // Triggers updates
+```
+
+## 🚀 Basic Usage
+
+### ArrayList
+
+A general-purpose, resizeable array implementation of `List`.
+
+```typescript
+import { ArrayList } from '@tstdl/base/data-structures';
+
+const list = new ArrayList<string>(['alpha', 'beta']);
+
+list.add('gamma');
+list.prepend('omega');
+
+console.log(list.at(0)); // 'omega'
+console.log(list.toArray()); // ['omega', 'alpha', 'beta', 'gamma']
+
+list.remove('alpha');
+```
+
+### MapDictionary
+
+A `Dictionary` backed by the native `Map`, offering O(1) access times.
+
+```typescript
+import { MapDictionary } from '@tstdl/base/data-structures';
+
+const dict = new MapDictionary<number, string>();
+
+dict.set(1, 'One');
+dict.set(2, 'Two');
+
+if (dict.has(1)) {
+  console.log(dict.get(1)); // 'One'
+}
+
+for (const [key, value] of dict) {
+  console.log(`${key}: ${value}`);
+}
+```
+
+### SetCollection
+
+A `DistinctCollection` backed by the native `Set`, ensuring unique values.
+
+```typescript
+import { SetCollection } from '@tstdl/base/data-structures';
+
+const set = new SetCollection<number>();
+
+set.add(1);
+set.add(1); // Duplicate ignored
+set.add(2);
+
+console.log(set.size); // 2
+```
+
+## 🔧 Advanced Topics
+
+### CircularBuffer
+
+A fixed-size buffer that overwrites the oldest elements when full. Useful for logs, history, or streaming data. It exposes specific observables for overflow events.
+
+```typescript
+import { CircularBuffer } from '@tstdl/base/data-structures';
+
+const buffer = new CircularBuffer<string>(3);
+
+// React to overflows
+buffer.overflow$.subscribe((dropped) => {
+  console.warn(`Buffer full! Dropped: ${dropped}`);
+});
+
+buffer.add('A');
+buffer.add('B');
+buffer.add('C');
+buffer.add('D'); // Triggers overflow$, 'A' is dropped
+
+console.log(buffer.toArray()); // ['B', 'C', 'D']
+```
+
+### LinkedList
+
+A doubly linked list that provides O(1) insertions and removals when holding a reference to a node.
+
+```typescript
+import { LinkedList } from '@tstdl/base/data-structures';
+
+const list = new LinkedList<string>();
+
+const nodeA = list.add('A');
+const nodeB = list.add('B');
+
+// O(1) insertion at specific position
+list.addAfterNode(nodeA, 'new item');
+
+// Access nodes directly
+console.log(list.firstNode?.item); // 'A'
+console.log(nodeB.previous?.item); // 'new item'
+
+console.log(list.toArray()); // ['A', 'new item', 'B']
+```
+
+### SortedArrayList
+
+A list that maintains its elements in sorted order using a comparator. Binary search is used for insertions and lookups.
+
+```typescript
+import { SortedArrayList } from '@tstdl/base/data-structures';
+
+const scores = new SortedArrayList<number>([], (a, b) => a - b);
+
+scores.add(10);
+scores.add(5);
+scores.add(20);
+
+console.log(scores.toArray()); // [5, 10, 20]
+
+// Fast lookup using binary search
+const index = scores.fastIndexOf(10); // 1
+```
+
+### Multi-Key Collections
+
+`MultiKeyMap` and `MultiKeySet` allow using arrays of values as keys. This is useful for coordinate systems, composite keys, or hierarchical data.
+
+#### MultiKeyMap
+
+```typescript
+import { MultiKeyMap } from '@tstdl/base/data-structures';
+
+const grid = new MultiKeyMap<[number, number], string>();
+
+grid.set([0, 0], 'Origin');
+grid.set([10, 5], 'Target');
+
+console.log(grid.get([0, 0])); // 'Origin'
+console.log(grid.has([1, 1])); // false
+
+// Flat access API (alternative syntax)
+grid.setFlat(2, 2, 'Waypoint');
+console.log(grid.getFlat(2, 2)); // 'Waypoint'
+```
+
+#### MultiKeySet
+
+```typescript
+import { MultiKeySet } from '@tstdl/base/data-structures';
+
+const matrix = new MultiKeySet<[number, number, number]>();
+
+matrix.add([1, 2, 3]);
+matrix.add([1, 2, 3]); // Duplicate ignored
+
+console.log(matrix.size); // 1
+console.log(matrix.has([1, 2, 3])); // true
+
+// Flat access
+matrix.addFlat(4, 5, 6);
+```
+
+### Cache
+
+A simple LRU (Least Recently Used) cache with configurable capacity. It automatically evicts the least recently accessed items when the limit is reached.
+
+```typescript
+import { Cache } from '@tstdl/base/data-structures';
+
+const cache = new Cache<string, object>(100); // Capacity: 100 items
+
+cache.set('user:1', { name: 'Alice' });
+
+// Accessing an item marks it as recently used
+const user = cache.get('user:1');
+
+// Adjusting capacity at runtime evicts items if necessary
+cache.capacity = 50;
+
+cache.delete('user:1');
+```
+
+### Weak Reference Maps
+
+- **`IterableWeakMap`**: A `WeakMap` that allows iteration. It uses `WeakRef` and `FinalizationRegistry` to track keys and clean up internal references when keys are garbage collected.
+- **`WeakRefMap`**: A map where _values_ are held weakly. Useful for caching large objects that can be reconstructed if memory is tight.
+
+```typescript
+import { IterableWeakMap } from '@tstdl/base/data-structures';
+
+let key: object | null = { id: 1 };
+const map = new IterableWeakMap<object, string>();
+
+map.set(key, 'Metadata');
+
+// Unlike native WeakMap, we can iterate
+for (const [k, v] of map) {
+  console.log(v); // 'Metadata'
+}
+
+key = null; // Key is now eligible for GC. Map will eventually be empty.
+```
+
+### ContextDataMap
+
+A utility map for storing arbitrary context data, often used in request processing or dependency injection scopes. Supports merging data.
+
+```typescript
+import { ContextDataMap } from '@tstdl/base/data-structures';
+
+const context = new ContextDataMap();
+
+context.set('user', { id: 1, name: 'Alice' });
+context.set('config', { theme: 'dark' });
+
+// Merge data into existing key
+context.set('config', { lang: 'en' }, true);
+
+console.log(context.get('config')); // { theme: 'dark', lang: 'en' }
+```
+
+### Native Adapters
+
+If you need to pass a `Dictionary` to a function expecting a `Map`, or a `DistinctCollection` to a function expecting a `Set`, use the adapter methods. These create lightweight wrappers without copying data.
+
+```typescript
+import { MapDictionary } from '@tstdl/base/data-structures';
+
+const dict = new MapDictionary<string, number>();
+const nativeMap: Map<string, number> = dict.asMap();
+
+nativeMap.set('foo', 123); // Updates the underlying Dictionary
+```
+
+## 📚 API
+
+| Class                   | Type               | Description                                                 |
+| :---------------------- | :----------------- | :---------------------------------------------------------- |
+| `ArrayList<T>`          | List               | Dynamic array implementation backed by native Array.        |
+| `SortedArrayList<T>`    | List               | Auto-sorted list using a comparator and binary search.      |
+| `LinkedList<T>`         | List               | Doubly linked list implementation.                          |
+| `CircularBuffer<T>`     | Collection         | Fixed-size buffer that overwrites oldest items on overflow. |
+| `MapDictionary<K, V>`   | Dictionary         | Key-value collection backed by native `Map`.                |
+| `ArrayDictionary<K, V>` | Dictionary         | Key-value collection backed by parallel arrays.             |
+| `MultiKeyMap<K[], V>`   | Dictionary         | Map using arrays as composite keys.                         |
+| `IterableWeakMap<K, V>` | Dictionary         | `WeakMap` that supports iteration and size tracking.        |
+| `WeakRefMap<K, V>`      | Dictionary         | Map where values are held via `WeakRef`.                    |
+| `SetCollection<T>`      | DistinctCollection | Unique value collection backed by native `Set`.             |
+| `MultiKeySet<T[]>`      | DistinctCollection | Set using arrays as unique composite values.                |
+| `Cache<K, V>`           | Class              | Simple LRU (Least Recently Used) cache.                     |
+| `ContextDataMap`        | Class              | Map for storing and merging arbitrary context data.         |
+| `IndexOutOfBoundsError` | Error              | Thrown when accessing invalid list indices.                 |
+
+### Abstract Base Classes
+
+| Class                   | Description                                                 |
+| :---------------------- | :---------------------------------------------------------- |
+| `Collection<T>`         | Base class for all data structures. Provides observability. |
+| `List<T>`               | Base for ordered, indexed collections.                      |
+| `Dictionary<K, V>`      | Base for key-value collections.                             |
+| `DistinctCollection<T>` | Base for unique value collections (Sets).                   |