@okikio/observables 1.0.2

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/queue.d.ts

@@ -0,0 +1,201 @@
+/**
+ * A lightweight circular-buffer queue for the library's hot paths.
+ *
+ * This entrypoint exposes the small FIFO data structure that backs replay,
+ * buffering, and event fan-out inside the Observable runtime. It keeps
+ * enqueue/dequeue work O(1) by moving `head` and `tail` pointers around a fixed
+ * array instead of repeatedly calling `Array.shift()`, which has to move every
+ * remaining element one slot to the left.
+ *
+ * Use this module when you need predictable queue performance and explicit
+ * capacity control. It is especially useful for buffers that grow and shrink
+ * frequently, where repeated array reindexing would turn steady traffic into an
+ * unnecessary O(n) cost.
+ *
+ * @example
+ * ```
+ * import { createQueue, enqueue, dequeue, peek } from './queue.ts';
+ *
+ * const taskQueue = createQueue<string>(100);  // capacity of 100
+ * enqueue(taskQueue, 'process-order-123');     // add task
+ * enqueue(taskQueue, 'send-email-456');        // add another
+ *
+ * console.log(peek(taskQueue));                // 'process-order-123' (doesn't remove)
+ * console.log(dequeue(taskQueue));             // 'process-order-123' (removes and returns)
+ *
+ * clear(taskQueue);                            // empty the queue instantly
+ * ```
+ *
+ * @module
+ */
+/**
+ * Represents a circular buffer-based queue for efficient FIFO operations.
+ *
+ * @template T - The type of elements stored in the queue
+ */
+import "./_dnt.polyfills.js";
+export interface Queue<T> {
+    /** The backing array that holds queue elements */
+    items: T[];
+    /** Index pointing to the front element (next to dequeue) */
+    head: number;
+    /** Index pointing to where the next element will be added */
+    tail: number;
+    /** Current number of elements in the queue */
+    size: number;
+    /** Maximum capacity of the queue */
+    capacity: number;
+}
+/**
+ * Creates a new empty queue with the specified capacity.
+ *
+ * The queue uses a circular buffer internally, which means operations
+ * like enqueue and dequeue run in constant O(1) time regardless of
+ * queue size.
+ *
+ * @param capacity - Maximum number of elements the queue can hold (default: 1000)
+ * @returns A new empty queue ready for use
+ *
+ * @example
+ * ```
+ * const messageQueue = createQueue<string>(50);   // for messages
+ * const numberQueue = createQueue<number>();      // uses default capacity
+ * ```
+ */
+export declare function createQueue<T>(capacity?: number): Queue<T>;
+/**
+ * Adds an element to the back of the queue (FIFO: last in, first served).
+ * Runs in O(1) constant time.
+ *
+ * @param queue - The target queue
+ * @param item - Element to add to the queue
+ * @throws Error if the queue is at capacity
+ *
+ * @example
+ * ```
+ * enqueue(userQueue, { id: 123, name: 'Alice' });
+ * enqueue(userQueue, { id: 124, name: 'Bob' });
+ * ```
+ */
+export declare function enqueue<T>(queue: Queue<T>, item: T): void;
+/**
+ * Removes and returns the front element from the queue (FIFO: first in, first out).
+ * Runs in O(1) constant time.
+ *
+ * @param queue - The target queue
+ * @returns The front element, or undefined if queue is empty
+ *
+ * @example
+ * ```
+ * const nextTask = dequeue(taskQueue);
+ * if (nextTask) {
+ *   console.log('Processing:', nextTask);
+ * }
+ * ```
+ */
+export declare function dequeue<T>(queue: Queue<T>): T | undefined;
+/**
+ * Returns the front element without removing it from the queue.
+ * Useful for checking what's next without consuming it.
+ * Runs in O(1) constant time.
+ *
+ * @param queue - The target queue
+ * @returns The front element, or undefined if queue is empty
+ *
+ * @example
+ * ```
+ * const nextInLine = peek(queue);
+ * if (nextInLine?.priority === 'urgent') {
+ *   // handle urgent task immediately
+ *   dequeue(queue);
+ * }
+ * ```
+ */
+export declare function peek<T>(queue: Queue<T>): T | undefined;
+/**
+ * Checks if the queue contains no elements.
+ *
+ * @param queue - The target queue
+ * @returns true if the queue is empty, false otherwise
+ */
+export declare function isEmpty<T>(queue: Queue<T>): boolean;
+/**
+ * Checks if the queue has reached its maximum capacity.
+ *
+ * @param queue - The target queue
+ * @returns true if the queue is full, false otherwise
+ */
+export declare function isFull<T>(queue: Queue<T>): boolean;
+/**
+ * Returns the current number of elements in the queue.
+ *
+ * @param queue - The target queue
+ * @returns Current queue size (0 to capacity)
+ */
+export declare function getSize<T>(queue: Queue<T>): number;
+/**
+ * Returns how many more elements can be added before hitting capacity.
+ *
+ * @param queue - The target queue
+ * @returns Number of available slots
+ *
+ * @example
+ * ```
+ * if (remainingSpace(queue) < 10) {
+ *   console.warn('Queue nearly full, consider processing items');
+ * }
+ * ```
+ */
+export declare function remainingSpace<T>(queue: Queue<T>): number;
+/**
+ * Empties the queue instantly using the `.length = 0` optimization[87][90].
+ * This immediately releases all object references for garbage collection,
+ * making it much faster than dequeuing items one by one.
+ *
+ * Runs in O(1) constant time regardless of queue size.
+ *
+ * @param queue - The target queue
+ *
+ * @example
+ * ```
+ * // Instead of: while (!isEmpty(queue)) dequeue(queue);  // O(n)
+ * clear(queue);  // O(1) - much faster!
+ * ```
+ */
+export declare function clear<T>(queue: Queue<T>): void;
+/**
+ * Creates a new array containing all queue elements in order (front to back).
+ * Useful for debugging, logging, or when you need array methods.
+ *
+ * Note: This is O(n) operation - use sparingly in performance-critical code.
+ *
+ * @param queue - The source queue
+ * @returns New array with queue elements in FIFO order
+ *
+ * @example
+ * ```
+ * const queueSnapshot = toArray(queue);
+ * console.log('Current queue:', queueSnapshot.join(' -> '));
+ *
+ * // Process without modifying original queue
+ * const urgentItems = queueSnapshot.filter(item => item.priority === 'urgent');
+ * ```
+ */
+export declare function toArray<T>(queue: Queue<T>): T[];
+/**
+ * Applies a function to each element in the queue without modifying it.
+ * Elements are visited in FIFO order (front to back).
+ *
+ * @param queue - The target queue
+ * @param callback - Function to call for each element
+ *
+ * @example
+ * ```
+ * // Log all pending tasks
+ * forEach(taskQueue, (task, index) => {
+ *   console.log(`Task ${index + 1}: ${task.description}`);
+ * });
+ * ```
+ */
+export declare function forEach<T>(queue: Queue<T>, callback: (item: T, index: number) => void): void;
+//# sourceMappingURL=queue.d.ts.map

package/esm/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;GAIG;AACH,OAAO,qBAAqB,CAAC;AAE7B,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,kDAAkD;IAClD,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAE,MAAa,GAAG,KAAK,CAAC,CAAC,CAAC,CAQhE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAUzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAWzD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAEtD;AAMD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAEzD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAS9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAc/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACzC,IAAI,CAON"}

package/esm/queue.js

@@ -0,0 +1,273 @@
+/**
+ * A lightweight circular-buffer queue for the library's hot paths.
+ *
+ * This entrypoint exposes the small FIFO data structure that backs replay,
+ * buffering, and event fan-out inside the Observable runtime. It keeps
+ * enqueue/dequeue work O(1) by moving `head` and `tail` pointers around a fixed
+ * array instead of repeatedly calling `Array.shift()`, which has to move every
+ * remaining element one slot to the left.
+ *
+ * Use this module when you need predictable queue performance and explicit
+ * capacity control. It is especially useful for buffers that grow and shrink
+ * frequently, where repeated array reindexing would turn steady traffic into an
+ * unnecessary O(n) cost.
+ *
+ * @example
+ * ```
+ * import { createQueue, enqueue, dequeue, peek } from './queue.ts';
+ *
+ * const taskQueue = createQueue<string>(100);  // capacity of 100
+ * enqueue(taskQueue, 'process-order-123');     // add task
+ * enqueue(taskQueue, 'send-email-456');        // add another
+ *
+ * console.log(peek(taskQueue));                // 'process-order-123' (doesn't remove)
+ * console.log(dequeue(taskQueue));             // 'process-order-123' (removes and returns)
+ *
+ * clear(taskQueue);                            // empty the queue instantly
+ * ```
+ *
+ * @module
+ */
+///////////////////////
+// Core Data Types   //
+///////////////////////
+/**
+ * Represents a circular buffer-based queue for efficient FIFO operations.
+ *
+ * @template T - The type of elements stored in the queue
+ */
+import "./_dnt.polyfills.js";
+/**
+ * Advances a circular-buffer index by one slot and wraps back to `0` at the end.
+ *
+ * This keeps the same O(1) behavior as `% capacity`, but avoids paying modulo
+ * cost for arbitrary capacities in the queue hot path. It is private because
+ * it only exists to speed up internal queue pointer movement.
+ */
+function advanceIndex(index, capacity) {
+    const next = index + 1;
+    return next === capacity ? 0 : next;
+}
+////////////////////////////
+// Factory & Core Setup   //
+////////////////////////////
+/**
+ * Creates a new empty queue with the specified capacity.
+ *
+ * The queue uses a circular buffer internally, which means operations
+ * like enqueue and dequeue run in constant O(1) time regardless of
+ * queue size.
+ *
+ * @param capacity - Maximum number of elements the queue can hold (default: 1000)
+ * @returns A new empty queue ready for use
+ *
+ * @example
+ * ```
+ * const messageQueue = createQueue<string>(50);   // for messages
+ * const numberQueue = createQueue<number>();      // uses default capacity
+ * ```
+ */
+export function createQueue(capacity = 1000) {
+    return {
+        items: new Array(capacity),
+        head: 0,
+        tail: 0,
+        size: 0,
+        capacity,
+    };
+}
+/////////////////////////
+// Core Queue Operations //
+/////////////////////////
+/**
+ * Adds an element to the back of the queue (FIFO: last in, first served).
+ * Runs in O(1) constant time.
+ *
+ * @param queue - The target queue
+ * @param item - Element to add to the queue
+ * @throws Error if the queue is at capacity
+ *
+ * @example
+ * ```
+ * enqueue(userQueue, { id: 123, name: 'Alice' });
+ * enqueue(userQueue, { id: 124, name: 'Bob' });
+ * ```
+ */
+export function enqueue(queue, item) {
+    if (isFull(queue)) {
+        throw new Error(`Queue overflow: cannot add item, capacity ${queue.capacity} reached`);
+    }
+    queue.items[queue.tail] = item;
+    queue.tail = advanceIndex(queue.tail, queue.capacity);
+    queue.size++;
+}
+/**
+ * Removes and returns the front element from the queue (FIFO: first in, first out).
+ * Runs in O(1) constant time.
+ *
+ * @param queue - The target queue
+ * @returns The front element, or undefined if queue is empty
+ *
+ * @example
+ * ```
+ * const nextTask = dequeue(taskQueue);
+ * if (nextTask) {
+ *   console.log('Processing:', nextTask);
+ * }
+ * ```
+ */
+export function dequeue(queue) {
+    if (isEmpty(queue)) {
+        return undefined;
+    }
+    const item = queue.items[queue.head];
+    queue.items[queue.head] = undefined; // help garbage collector
+    queue.head = advanceIndex(queue.head, queue.capacity);
+    queue.size--;
+    return item;
+}
+/**
+ * Returns the front element without removing it from the queue.
+ * Useful for checking what's next without consuming it.
+ * Runs in O(1) constant time.
+ *
+ * @param queue - The target queue
+ * @returns The front element, or undefined if queue is empty
+ *
+ * @example
+ * ```
+ * const nextInLine = peek(queue);
+ * if (nextInLine?.priority === 'urgent') {
+ *   // handle urgent task immediately
+ *   dequeue(queue);
+ * }
+ * ```
+ */
+export function peek(queue) {
+    return isEmpty(queue) ? undefined : queue.items[queue.head];
+}
+////////////////////////////////
+// Utility & Status Functions //
+////////////////////////////////
+/**
+ * Checks if the queue contains no elements.
+ *
+ * @param queue - The target queue
+ * @returns true if the queue is empty, false otherwise
+ */
+export function isEmpty(queue) {
+    return queue.size === 0;
+}
+/**
+ * Checks if the queue has reached its maximum capacity.
+ *
+ * @param queue - The target queue
+ * @returns true if the queue is full, false otherwise
+ */
+export function isFull(queue) {
+    return queue.size >= queue.capacity;
+}
+/**
+ * Returns the current number of elements in the queue.
+ *
+ * @param queue - The target queue
+ * @returns Current queue size (0 to capacity)
+ */
+export function getSize(queue) {
+    return queue.size;
+}
+/**
+ * Returns how many more elements can be added before hitting capacity.
+ *
+ * @param queue - The target queue
+ * @returns Number of available slots
+ *
+ * @example
+ * ```
+ * if (remainingSpace(queue) < 10) {
+ *   console.warn('Queue nearly full, consider processing items');
+ * }
+ * ```
+ */
+export function remainingSpace(queue) {
+    return queue.capacity - queue.size;
+}
+/////////////////////////////
+// Advanced Utility Functions //
+/////////////////////////////
+/**
+ * Empties the queue instantly using the `.length = 0` optimization[87][90].
+ * This immediately releases all object references for garbage collection,
+ * making it much faster than dequeuing items one by one.
+ *
+ * Runs in O(1) constant time regardless of queue size.
+ *
+ * @param queue - The target queue
+ *
+ * @example
+ * ```
+ * // Instead of: while (!isEmpty(queue)) dequeue(queue);  // O(n)
+ * clear(queue);  // O(1) - much faster!
+ * ```
+ */
+export function clear(queue) {
+    // Fast array truncation - instantly releases references for GC[87][90]
+    queue.items.length = 0;
+    queue.items.length = queue.capacity; // restore original capacity
+    // Reset pointers
+    queue.head = 0;
+    queue.tail = 0;
+    queue.size = 0;
+}
+/**
+ * Creates a new array containing all queue elements in order (front to back).
+ * Useful for debugging, logging, or when you need array methods.
+ *
+ * Note: This is O(n) operation - use sparingly in performance-critical code.
+ *
+ * @param queue - The source queue
+ * @returns New array with queue elements in FIFO order
+ *
+ * @example
+ * ```
+ * const queueSnapshot = toArray(queue);
+ * console.log('Current queue:', queueSnapshot.join(' -> '));
+ *
+ * // Process without modifying original queue
+ * const urgentItems = queueSnapshot.filter(item => item.priority === 'urgent');
+ * ```
+ */
+export function toArray(queue) {
+    if (isEmpty(queue)) {
+        return [];
+    }
+    const result = new Array(queue.size);
+    let index = queue.head;
+    for (let i = 0; i < queue.size; i++) {
+        result[i] = queue.items[index];
+        index = advanceIndex(index, queue.capacity);
+    }
+    return result;
+}
+/**
+ * Applies a function to each element in the queue without modifying it.
+ * Elements are visited in FIFO order (front to back).
+ *
+ * @param queue - The target queue
+ * @param callback - Function to call for each element
+ *
+ * @example
+ * ```
+ * // Log all pending tasks
+ * forEach(taskQueue, (task, index) => {
+ *   console.log(`Task ${index + 1}: ${task.description}`);
+ * });
+ * ```
+ */
+export function forEach(queue, callback) {
+    let index = queue.head;
+    for (let i = 0; i < queue.size; i++) {
+        callback(queue.items[index], i);
+        index = advanceIndex(index, queue.capacity);
+    }
+}

package/esm/symbol.d.ts

@@ -0,0 +1,60 @@
+/**
+ * > Inspired by https://jsr.io/@nick/dispose/1.1.0/symbol.ts
+ *
+ * Extensions to the global Symbol constructor for interoperability with
+ * Observable.
+ *
+ * This interface extends the standard Symbol constructor with well-known
+ * symbols needed for Observable interoperability and resource cleanup:
+ *
+ * 1. `Symbol.observable`: For Observable interoperability (TC39 proposal)
+ *
+ * These symbols enable our implementation to work with:
+ * - Other Observable libraries via Symbol.observable
+ *
+ * @example
+ * ```ts
+ * // Using Symbol.observable for interop
+ * const myObservable = {
+ *   [Symbol.observable]() {
+ *     return new Observable(observer => {
+ *       observer.next('Hello');
+ *       observer.complete();
+ *     });
+ *   }
+ * };
+ * ```
+ *
+ * @module
+ */
+export interface SymbolConstructor extends Omit<typeof globalThis.Symbol, "observable"> {
+    /**
+     * Well-known symbol for Observable interoperability.
+     *
+     * This symbol allows any object to define how it converts to an Observable.
+     * Objects with a `[Symbol.observable]()` method can be passed directly to
+     * `Observable.from()` and will be properly converted.
+     *
+     * This is analogous to how `Symbol.iterator` enables iteration interop.
+     *
+     * @see {@link https://github.com/tc39/proposal-observable | TC39 Observable proposal}
+     */
+    readonly observable: unique symbol;
+}
+/**
+ * Provides a cross-platform Symbol implementation with Observable
+ * and resource management symbols.
+ *
+ * This implementation:
+ * 1. Uses the native Symbol if available
+ * 2. Falls back to a polyfill if Symbol is not supported
+ * 3. Adds our special symbols if they don't exist natively
+ *
+ * The polyfill is lightweight and provides basic Symbol functionality
+ * for environments that don't support it natively.
+ *
+ * Note: The polyfill does not implement the full Symbol specification
+ * and is intended only for basic interoperability in legacy environments.
+ */
+export declare const Symbol: SymbolConstructor;
+//# sourceMappingURL=symbol.d.ts.map

package/esm/symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.d.ts","sourceRoot":"","sources":["../src/symbol.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,iBACf,SAAQ,IAAI,CAAC,OAAO,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC;IACpD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,MAAM,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,EAAE,iBAIiB,CAAC"}

package/esm/symbol.js

@@ -0,0 +1,132 @@
+/**
+ * Provides a cross-platform Symbol implementation with Observable
+ * and resource management symbols.
+ *
+ * This implementation:
+ * 1. Uses the native Symbol if available
+ * 2. Falls back to a polyfill if Symbol is not supported
+ * 3. Adds our special symbols if they don't exist natively
+ *
+ * The polyfill is lightweight and provides basic Symbol functionality
+ * for environments that don't support it natively.
+ *
+ * Note: The polyfill does not implement the full Symbol specification
+ * and is intended only for basic interoperability in legacy environments.
+ */
+export const Symbol = (globalThis.Symbol ??
+    ((description) => ({
+        description,
+        toString: () => `Symbol(${description})`,
+    })));
+/**
+ * Adds Symbol.dispose if it doesn't exist natively.
+ *
+ * Symbol.dispose enables automatic resource cleanup using the `using` declaration.
+ * When a variable declared with `using` goes out of scope, its `[Symbol.dispose]()`
+ * method is called automatically, ensuring cleanup happens even if errors occur.
+ *
+ * @example Basic resource cleanup with using
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * {
+ *   using subscription = Observable.of(1, 2, 3).subscribe({
+ *     next: (val) => console.log('Value:', val)
+ *   });
+ *
+ *   // Use the subscription here
+ *   // ...
+ * } // subscription.unsubscribe() called automatically at block end
+ * ```
+ *
+ * @example Automatic cleanup on error
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * function processData() {
+ *   using sub = Observable.from(dataStream).subscribe({
+ *     next: (data) => processItem(data)
+ *   });
+ *
+ *   if (invalidCondition) {
+ *     throw new Error('Processing failed');
+ *   }
+ *   // sub.unsubscribe() called even if error thrown
+ * }
+ * ```
+ */
+if (typeof globalThis.Symbol === "function" &&
+    typeof Symbol.dispose !== "symbol") {
+    Reflect.defineProperty(Symbol, "dispose", {
+        // deno-lint-ignore no-explicit-any
+        value: Symbol("Symbol.dispose"),
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+}
+/**
+ * Adds Symbol.asyncDispose if it doesn't exist natively.
+ *
+ * Symbol.asyncDispose enables automatic async resource cleanup using `await using`.
+ * When a variable declared with `await using` goes out of scope, its
+ * `[Symbol.asyncDispose]()` method is called and awaited automatically,
+ * ensuring async cleanup (like closing connections) happens safely.
+ *
+ * @example Async resource cleanup with await using
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * async function streamData() {
+ *   await using sub = Observable.of(1, 2, 3).subscribe({
+ *     next: async (data) => await saveData(data)
+ *   });
+ *
+ *   // Use the subscription here
+ *   // ...
+ * } // sub.unsubscribe() (or async dispose) awaited automatically at block end
+ * ```
+ *
+ * @example Guaranteed async cleanup on error
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * async function fetchAndProcess() {
+ *   await using sub = Observable.from(apiStream).subscribe({
+ *     next: async (item) => await processAsync(item)
+ *   });
+ *
+ *   if (errorCondition) {
+ *     throw new Error('Failed');
+ *   }
+ *   // Async cleanup guaranteed even if error thrown
+ * }
+ * ```
+ */
+if (typeof globalThis.Symbol === "function" &&
+    typeof Symbol.asyncDispose !== "symbol") {
+    Reflect.defineProperty(Symbol, "asyncDispose", {
+        // deno-lint-ignore no-explicit-any
+        value: Symbol("Symbol.asyncDispose"),
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+}
+/**
+ * Adds Symbol.observable if it doesn't exist natively.
+ *
+ * This ensures Symbol.observable is available for Observable
+ * interoperability, even in environments that don't support
+ * it natively.
+ */
+if (typeof globalThis.Symbol === "function" &&
+    typeof Symbol.observable !== "symbol") {
+    Reflect.defineProperty(Symbol, "observable", {
+        // deno-lint-ignore no-explicit-any
+        value: Symbol("Symbol.observable"),
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+}