@okikio/observables 1.0.2

package/esm/observable.js

@@ -0,0 +1,1970 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _SubscriptionObserver_state, _SubscriptionObserver_subscription, _Observable_subscribeFn;
+// @filename: observable.ts
+/**
+ * A **spec-faithful** yet ergonomic TC39-inspired Observable implementation with detailed TSDocs and examples.
+ *
+ * A **push‑based stream abstraction** for events, data, and long‑running
+ * operations. Think of it as a **multi‑value Promise** that keeps sending
+ * values until you tell it to stop.
+ *
+ * ## Why This Exists
+ * Apps juggle many async sources, mouse clicks, HTTP requests, timers,
+ * WebSockets, file watchers. Before Observables you glued those together with a
+ * mish‑mash of callbacks, Promises, `EventTarget`s and async iterators, each
+ * with different rules for cleanup and error handling. **Observables give you
+ * one mental model** for subscription → cancellation → propagation → teardown.
+ *
+ * ## ✨ Feature Highlights
+ * - **Unified push + pull** – use callbacks *or* `for await … of` on the same
+ *   stream.
+ * - **Cold by default** – each subscriber gets an independent execution (great
+ *   for predictable side‑effects).
+ * - **Deterministic teardown** – return a function/`unsubscribe`/`[Symbol.dispose]`
+ *   and it *always* runs once, even if the observable errors synchronously.
+ * - **Back‑pressure helper** – `pull()` converts to an `AsyncGenerator` backed
+ *   by `ReadableStream` so the producer slows down when the consumer lags.
+ * - **Tiny surface** – <1 kB min+gzip of logic; treeshakes cleanly.
+ *
+ * ## Error Propagation Policy
+ * 1. **Local catch** – If your observer supplies an `error` callback, **all**
+ *    upstream errors funnel there.
+ * 2. **Unhandled‑rejection style** – If no `error` handler is provided the
+ *    exception is re‑thrown on the micro‑task queue (same timing semantics as
+ *    an unhandled Promise rejection).
+ * 3. **Observer callback failures** – Exceptions thrown inside `next()` or
+ *    `complete()` are routed to `error()` if present, otherwise bubble as in
+ *    (2).
+ * 4. **Errors inside `error()`** – A second‑level failure is *always* queued to
+ *    the micro‑task queue to avoid infinite recursion.
+ *
+ * ## Edge‑Cases & Gotchas
+ * - `subscribe()` can synchronously call `complete()`/`error()` and still have
+ *   its teardown captured – **ordering is guaranteed**.
+ * - Subscribing twice to a *cold* observable triggers two side‑effects (e.g.
+ *   two HTTP requests). Share the source if you want fan‑out.
+ * - Infinite streams leak unless you call `unsubscribe()` or wrap them in a
+ *   `using` block.
+ * - The helper `pull()` encodes thrown errors as `ObservableError` *values* so
+ *   buffered items are not lost – remember to `instanceof` check if you rely
+ *   on it.
+ *
+ * @example Common Patterns
+ * ```ts
+ * // DOM events → Observable
+ * const clicks = new Observable<Event>(obs => {
+ *   const h = (e: Event) => obs.next(e);
+ *   button.addEventListener("click", h);
+ *   return () => button.removeEventListener("click", h);
+ * });
+ *
+ * // HTTP polling every 5 s
+ * const poll = new Observable<Response>(obs => {
+ *   const id = setInterval(async () => {
+ *     try { obs.next(await fetch("/api/data")); }
+ *     catch (e) { obs.error(e); }
+ *   }, 5000);
+ *   return () => clearInterval(id);
+ * });
+ *
+ * // WebSocket stream with graceful close
+ * const live = new Observable<string>(obs => {
+ *   const ws = new WebSocket("wss://example.com");
+ *   ws.onmessage = e => obs.next(e.data);
+ *   ws.onerror   = e => obs.error(e);
+ *   ws.onclose   = () => obs.complete();
+ *   return () => ws.close();
+ * });
+ * ```
+ *
+ * @example Basic subscription:
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * // Emit 1,2,3 then complete
+ * const subscription = Observable.of(1, 2, 3).subscribe({
+ *   start(sub) { console.log('Subscribed'); },
+ *   next(val)  { console.log('Value:', val); },
+ *   complete() { console.log('Complete'); }
+ * });
+ *
+ * // Cancel manually if needed
+ * subscription.unsubscribe();
+ * ```
+ *
+ * @example Resource-safe usage with `using` statement:
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * {
+ *   using subscription = Observable.of(1, 2, 3).subscribe({
+ *     next(val) { console.log('Value:', val); }
+ *   });
+ *
+ *   // Code that uses the subscription
+ *   doSomething();
+ *
+ * } // Subscription automatically unsubscribed at block end
+ * ```
+ *
+ * @example Simple async iteration:
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * (async () => {
+ *   for await (const x of Observable.of('a', 'b', 'c')) {
+ *     console.log(x);
+ *   }
+ * })();
+ * ```
+ *
+ * @example Pull with backpressure:
+ * ```ts
+ * import { Observable } from './observable.ts';
+ *
+ * const nums = Observable.from([1,2,3,4,5]);
+ * (async () => {
+ *   for await (const n of nums.pull({ strategy: { highWaterMark: 2 } })) {
+ *     console.log('Pulled:', n);
+ *     await new Promise(r => setTimeout(r, 1000)); // Slow consumer
+ *   }
+ * })();
+ * ```
+ *
+ * ## Spec Compliance & Notable Deviations
+ * | Area                       | Proposal Behaviour                     | This Library                                                                            |
+ * |----------------------------|----------------------------------------|-----------------------------------------------------------------------------------------|
+ * | `subscribe` parameters     | Only **observer object**               | Adds `(next, error?, complete?)` triple‑param overload.                                 |
+ * | Teardown shape             | Function or `{ unsubscribe() }`        | Also honours `[Symbol.dispose]` **and** `[Symbol.asyncDispose]`.                        |
+ * | Pull‑mode iteration        | *Not in spec*                          | `pull()` helper returns an `AsyncGenerator` with `ReadableStream`‑backed back‑pressure. |
+ * | Error propagation in pull  | Stream **error** ends iteration        | Error encoded as `ObservableError` value so buffered items drain first.                 |
+ * | `Symbol.toStringTag`       | Optional                               | Provided for `Observable` and `SubscriptionObserver`.                                   |
+ *
+ * Anything not listed above matches the TC39 draft (**May 2025**).
+ *
+ * ## Lifecycle State Machine
+ * ```text
+ * (inactive) --subscribe()--> [  active  ]
+ *     ^                         |  next()
+ *     |   unsubscribe()/error() |  complete()
+ *     |<------------------------|  (closed)
+ * ```
+ * *Teardown executes exactly once on the leftward arrow.*
+ *
+ * @example Type‑Parameter Primer
+ * ```ts
+ * Observable<number>                     // counter
+ * Observable<Response>                   // fetch responses
+ * Observable<{x:number;y:number}>        // mouse coords
+ * Observable<never>                      // signal‑only (no payload)
+ * Observable<string | ErrorPayload>      // unions are fine
+ * ```
+ *
+ * @example Interop Cheat‑Sheet
+ * ```ts
+ * // Promise → Observable (single value then complete)
+ * Observable.from(fetch("/api"));
+ *
+ * // Observable → async iterator (back‑pressure aware)
+ * for await (const chunk of obs) {
+ *   processChunk(chunk);
+ * }
+ *
+ * // Observable → Promise (first value only)
+ * const first = (await obs.pull().next()).value;
+ * ```
+ *
+ * ## Performance Cookbook (pull())
+ * | Producer speed | Consumer speed | Suggested `highWaterMark` | Notes                                   |
+ * |---------------:|---------------:|--------------------------:|-----------------------------------------|
+ * | 🔥 Very fast   | 🐢 Slow         | 1‑8                       | Minimal RAM; heavy throttling.          |
+ * | ⚡ Fast         | 🚶 Moderate     | 16‑64 (default 64)        | Good balance for most apps.             |
+ * | 🚀 Bursty      | 🚀 Bursty       | 128‑512                   | Smooths spikes at the cost of memory.   |
+ *
+ * ➜ If RSS climbs steadily, halve `highWaterMark`; if you’re dropping messages
+ * under load, raise it (RAM permitting).
+ *
+ * ## Memory Management
+ *
+ * **Critical**: Infinite Observables need manual cleanup via `unsubscribe()` or `using` blocks
+ * to prevent memory leaks. Finite Observables auto-cleanup on complete/error.
+ *
+ * @example Quick start - DOM events
+ * ```ts
+ * const clicks = new Observable(observer => {
+ *   const handler = e => observer.next(e);
+ *   button.addEventListener('click', handler);
+ *   return () => button.removeEventListener('click', handler);
+ * });
+ *
+ * using subscription = clicks.subscribe(event => console.log('Clicked!'));
+ * // Auto-cleanup when leaving scope
+ * ```
+ *
+ * @example Network with backpressure
+ * ```ts
+ * const dataStream = new Observable(observer => {
+ *   const ws = new WebSocket('ws://api.com/live');
+ *   ws.onmessage = e => observer.next(JSON.parse(e.data));
+ *   ws.onerror = e => observer.error(e);
+ *   return () => ws.close();
+ * });
+ *
+ * // Consume at controlled pace
+ * for await (const data of dataStream.pull({ strategy: { highWaterMark: 10 } })) {
+ *   await processSlowly(data); // Producer pauses when buffer fills
+ * }
+ * ```
+ *
+ * @example Testing & Debugging Tips
+ * ```ts
+ * import { expect, test } from "jsr:@libs/testing@^5";
+ *
+ * test("emits three ticks then completes", async () => {
+ *   const ticks = Observable.of(1, 2, 3);
+ *   const out: number[] = [];
+ *   for await (const n of ticks) out.push(n);
+ *   expect(out).toEqual([1, 2, 3]);
+ * });
+ *
+ * // Quick console probe
+ * obs.subscribe(v => console.log("[OBS]", v));
+ * ```
+ *
+ * ## FAQ
+ * - **Why does my network request fire twice?** Cold observables run once per
+ *   subscribe. Reuse a single subscription or share the source.
+ * - **Why does `next()` throw after `complete()`?** The stream is closed; calls
+ *   are ignored by design.
+ * - **Memory leak on interval** ,  Infinite streams require `unsubscribe()` or
+ *   `using`.
+ *
+ * @module
+ */
+import "./_dnt.polyfills.js";
+import { assertObservableError, ObservableError } from "./error.js";
+import { Symbol } from "./symbol.js";
+/**
+ * Central registry of subscription state.
+ *
+ * Using a WeakMap allows us to:
+ * 1. Associate state with subscription objects without extending them
+ * 2. Let the garbage collector automatically clean up entries when subscriptions are no longer referenced
+ * 3. Hide implementation details from users
+ */
+export const SubscriptionStateMap = new WeakMap();
+/**
+ * Creates a new Subscription object with properly initialized state.
+ *
+ * We validate observer methods early, ensuring type errors are caught
+ * at subscription time rather than during event emission.
+ *
+ * The returned Subscription includes support for:
+ * - Manual cancellation via `unsubscribe()`
+ * - Automatic cleanup via `using` blocks (Symbol.dispose)
+ * - Async cleanup contexts (Symbol.asyncDispose)
+ *
+ * @throws TypeError if observer methods are present but not functions
+ * @internal
+ */
+export function createSubscription(observer, opts) {
+    // Observer's methods should be functions if they exist
+    if (observer.next !== undefined && typeof observer.next !== "function") {
+        throw new TypeError("Observer.next must be a function");
+    }
+    if (observer.error !== undefined && typeof observer.error !== "function") {
+        throw new TypeError("Observer.error must be a function");
+    }
+    if (observer.complete !== undefined && typeof observer.complete !== "function") {
+        throw new TypeError("Observer.complete must be a function");
+    }
+    // Create a local statemap to speed up access during hot-paths
+    const stateMap = {
+        closed: false,
+        observer,
+        cleanup: null,
+        removeAbortHandler: null,
+    };
+    /* -------------------------------------------------------------------
+     * Create the Subscription facade (spec: CreateSubscription()).
+     * ------------------------------------------------------------------- */
+    const subscription = {
+        get [Symbol.toStringTag]() {
+            return "Subscription";
+        },
+        /**
+         * Returns whether this subscription is closed.
+         *
+         * A subscription becomes closed after:
+         * - Explicit call to unsubscribe()
+         * - Error notification
+         * - Complete notification
+         *
+         * Once closed, no further events will be delivered to the observer,
+         * and resources associated with the subscription are released.
+         */
+        get closed() {
+            return stateMap.closed;
+        },
+        /**
+         * Cancels the subscription and releases resources.
+         *
+         * - Safe to call multiple times (idempotent)
+         * - Synchronously performs cleanup
+         * - Marks subscription as closed
+         * - Prevents further observer notifications
+         *
+         * This is the primary method for consumers to explicitly
+         * terminate a subscription when they no longer need it.
+         */
+        unsubscribe() {
+            closeSubscription(this, stateMap);
+        },
+        // Support `using` disposal for automatic resource management
+        [Symbol.dispose]() {
+            this.unsubscribe();
+        },
+        // Support async disposal patterns
+        [Symbol.asyncDispose]() {
+            return Promise.resolve(this.unsubscribe());
+        },
+    };
+    // Adds support for unsubscribing via AbortSignals
+    const abortHandler = () => subscription?.unsubscribe();
+    const removeAbortHandler = () => opts?.signal?.removeEventListener("abort", abortHandler);
+    opts?.signal?.addEventListener?.("abort", abortHandler, { once: true });
+    stateMap.removeAbortHandler = removeAbortHandler;
+    // Initialize shared state
+    SubscriptionStateMap.set(subscription, stateMap);
+    return subscription;
+}
+export function markSubscriptionClosed(state, returnObserver = false) {
+    if (!state || state.closed)
+        return null;
+    // Capture observer BEFORE marking closed (for spec compliance)
+    const observer = state.observer;
+    // Mark as closed (this is what SubscriptionClosed checks)
+    state.closed = true;
+    state.observer = null;
+    // Return observer if requested (enables spec-compliant error/complete)
+    if (returnObserver)
+        return observer;
+}
+/**
+ * Perform cleanup if available. Safe to call multiple times.
+ */
+export function performSubscriptionCleanup(subscription, state) {
+    if (!state)
+        return;
+    // Cache cleanup, abort signal and the abort handler before clearing
+    let cleanup = state.cleanup;
+    let removeAbortHandler = state.removeAbortHandler;
+    // Only clean if we have something to clean
+    if (!cleanup && !removeAbortHandler)
+        return;
+    // Clear references first
+    state.cleanup = null;
+    state.removeAbortHandler = null;
+    // Remove the abort handler
+    removeAbortHandler?.();
+    // Run teardown (existing logic preserved)
+    try {
+        cleanupSubscription(cleanup);
+    }
+    finally {
+        SubscriptionStateMap.delete(subscription);
+        cleanup = null;
+        removeAbortHandler = null;
+    }
+}
+/**
+ * Marks a subscription as closed and schedules necessary cleanup.
+ *
+ * This is the centralized implementation for all subscription termination paths:
+ * - Manual unsubscribe()
+ * - Observer.error()
+ * - Observer.complete()
+ *
+ * The function ensures:
+ * 1. Idempotency (safe to call multiple times)
+ * 2. Cleanup happens exactly once
+ * 3. State is properly cleared to prevent memory leaks
+ * 4. WeakMap entry is removed to aid garbage collection
+ *
+ * @param subscription - The subscription to close
+ * @internal
+ */
+export function closeSubscription(subscription, stateMap) {
+    const state = stateMap ?? SubscriptionStateMap.get(subscription);
+    const closed = markSubscriptionClosed(state);
+    if (closed === null)
+        return;
+    // If we have an observer, perform cleanup
+    performSubscriptionCleanup(subscription, state);
+}
+/**
+ * Handles the actual cleanup process for a subscription.
+ *
+ * The spec allows three different types of cleanup values:
+ * 1. Function: Called directly
+ * 2. Object with unsubscribe method: unsubscribe() is called
+ * 3. (deviate from spec) Object with Symbol.dispose/asyncDispose: dispose() is called
+ *
+ * Any errors during cleanup are reported asynchronously to prevent
+ * them from disrupting the unsubscribe flow.
+ *
+ * @param cleanup - Function or object to perform cleanup
+ * @internal
+ */
+function cleanupSubscription(cleanup) {
+    let temp = cleanup;
+    cleanup = null;
+    if (!temp)
+        return;
+    try {
+        if (typeof temp === "function")
+            temp();
+        else if (typeof temp === "object") {
+            if (typeof temp.unsubscribe === "function") {
+                temp.unsubscribe();
+            }
+            else if (typeof temp[Symbol.asyncDispose] === "function") {
+                temp[Symbol.asyncDispose]();
+            }
+            else if (typeof temp[Symbol.dispose] === "function") {
+                temp[Symbol.dispose]();
+            }
+        }
+    }
+    catch (err) {
+        // Report cleanup errors asynchronously to avoid disrupting the unsubscribe flow
+        queueMicrotask(() => {
+            throw err;
+        });
+    }
+    temp = null;
+}
+/**
+ * Wraps an observer with key guarantees required by the Observable specification.
+ *
+ * SubscriptionObserver is a critical component that ensures:
+ *
+ * 1. The observer contract is honored correctly
+ * 2. Notifications stop after a subscription is closed
+ * 3. Error/complete notifications properly terminate the subscription
+ * 4. Observer methods are called with the correct `this` context
+ * 5. Errors are properly propagated according to spec
+ *
+ * This wrapper acts as the intermediary between the Observable producer
+ * and the consumer-provided Observer.
+ *
+ * @typeParam T - The type of values delivered by the parent Observable.
+ */
+export class SubscriptionObserver {
+    /**
+     * Returns whether this observer's subscription is closed.
+     *
+     * Uses the single source of truth for closed state from SubscriptionStateMap.
+     * This property is used by subscriber functions to check if they should
+     * continue delivering events.
+     *
+     * @example
+     * ```ts
+     * const timer = new Observable(observer => {
+     *   const id = setInterval(() => {
+     *     if (!observer.closed) {
+     *       observer.next(Date.now());
+     *     }
+     *   }, 1000);
+     *   return () => clearInterval(id);
+     * });
+     * ```
+     */
+    get closed() {
+        const state = __classPrivateFieldGet(this, _SubscriptionObserver_state, "f");
+        if (!state)
+            return true;
+        return state.closed ?? true;
+    }
+    /**
+     * Creates a new SubscriptionObserver attached to the given subscription.
+     *
+     * @param subscription - The subscription that created this observer
+     */
+    constructor(subscription) {
+        /** Cached state map to improve perf. */
+        _SubscriptionObserver_state.set(this, void 0);
+        /** Reference to the subscription that created this observer */
+        _SubscriptionObserver_subscription.set(this, null);
+        __classPrivateFieldSet(this, _SubscriptionObserver_subscription, subscription, "f");
+        if (subscription) {
+            __classPrivateFieldSet(this, _SubscriptionObserver_state, SubscriptionStateMap.get(subscription), "f");
+            if (!__classPrivateFieldGet(this, _SubscriptionObserver_state, "f"))
+                throw new Error("Subscription state not found");
+        }
+    }
+    /**
+     * Delivers the next value to the observer if the subscription is open.
+     *
+     * This is typically the "hot path" in an Observable implementation,
+     * as it's called for every emitted value. Key behaviors:
+     *
+     * 1. Silently returns if subscription is closed (no errors)
+     * 2. Properly preserves observer's `this` context
+     * 3. Catches and handles errors thrown from observer.next
+     * 4. Forwards errors to observer.error when available
+     *
+     * Performance Considerations:
+     * - Minimizes property access chains
+     * - Early returns for closed subscriptions
+     * - Type checking to avoid calling non-functions
+     *
+     * @param value - The value to deliver to the observer
+     *
+     * @example
+     * ```ts
+     * // Inside a subscriber function:
+     * observer.next(42);  // Delivers value to consumer
+     * ```
+     *
+     * > Note: Error-propagation policy
+     * > ─────────────────────────────
+     * > * If the *observer supplies its own `error()` handler*,
+     * >   that handler is considered the “catch-block” for the stream.
+     * >     ↳  Any exception that happens *inside* the user’s `next()` /
+     * >         `complete()` callbacks is forwarded to `error(err)` **once**.
+     * >     ↳  If `error()` itself throws, we still delegate to `HostReportErrors` (≈ “unhandled-promise rejection”)
+     * >         (i.e. `queueMicrotask`), exactly as the proposal specifies.
+     * >
+     * > * If the observer does **not** implement `error()`, we fall back to the
+     * >   spec’s `HostReportErrors` behaviour (queueMicrotask + throw) so the host
+     * >   surfaces the error just like an uncaught Promise rejection.
+     * >
+     * > Rationale – Think of `error()` as the moral equivalent of a `.catch()`
+     * > on a Promise.  Once a catch exists, the host no longer warns about
+     * > “unhandled” rejections; we mirror that mental model here.
+     * >
+     * > Spec reference – This diverges slightly from stage-1, which still
+     * > invokes HostReportErrors if the *error handler itself* throws.  We
+     * > intentionally suppress that extra surfacing for the reasons above.
+     */
+    next(value) {
+        const state = __classPrivateFieldGet(this, _SubscriptionObserver_state, "f");
+        if (!state || state.closed)
+            return;
+        // Fast-path optimization to avoid long request chains
+        const observer = state.observer;
+        if (!observer)
+            return;
+        const nextFn = observer.next;
+        if (typeof nextFn !== "function")
+            return;
+        try {
+            nextFn.call(observer, value);
+        }
+        catch (err) {
+            const errorFn = observer.error;
+            if (typeof errorFn === "function") {
+                try {
+                    errorFn.call(observer, err);
+                }
+                catch (err) {
+                    queueMicrotask(() => {
+                        throw err;
+                    });
+                }
+            } // Either a user callback or HostReportErrors emulation (queueMicrotask).
+            else {
+                queueMicrotask(() => {
+                    throw err;
+                });
+            }
+        }
+    }
+    /**
+     * Delivers an error notification to the observer, then closes the subscription.
+     *
+     * Error is a terminal operation - after calling it:
+     * 1. The subscription is immediately marked as closed
+     * 2. Resources are released via unsubscribe()
+     * 3. No further notifications will be delivered
+     *
+     * Error Handling:
+     * - If observer.error exists, the error is delivered there
+     * - If observer.error throws, the error is reported asynchronously
+     * - If no error handler exists, the error is reported asynchronously
+     *
+     * > Note: Even for "silent" errors (no error handler), we still close
+     * the subscription and report the error to the host.
+     *
+     * ##
+     *
+     * @example Important Timing Consideration
+     * When this method is called during the subscriber function execution (before it returns),
+     * there's a potential race condition with cleanup functions.
+     *
+     * Consider:
+     * ```ts
+     * new Observable(observer => {
+     *   observer.error(new Error()); // Triggers unsubscribe here
+     *   return () => cleanupResources(); // But this hasn't been returned yet!
+     * });
+     * ```
+     *
+     * Our implementation handles this by:
+     * 1. Marking the subscription as closed immediately
+     * 2. Scheduling actual cleanup in a microtask to ensure the teardown function
+     *    has time to be captured and stored
+     *
+     * This ensures resources are properly cleaned up even when error/complete
+     * is called synchronously during subscription setup.
+     *
+     * @param err - The error to deliver
+     *
+     * @example
+     * ```ts
+     * // Inside a subscriber function:
+     * try {
+     *   doRiskyOperation();
+     * } catch (err) {
+     *   observer.error(err);  // Terminates the subscription with error
+     * }
+     * ```
+     *
+     * > Note: {@link SubscriptionObserver.next | Review the error propagation policy in `next()` on how errors propagate, the behaviour is not obvious on first glance.}
+     */
+    error(err) {
+        const state = __classPrivateFieldGet(this, _SubscriptionObserver_state, "f");
+        // Mark closed and get observer in one call
+        const observer = markSubscriptionClosed(state, true);
+        if (observer === null)
+            return;
+        const errorFn = observer?.error;
+        if (typeof errorFn === "function") {
+            try {
+                errorFn.call(observer, err);
+            }
+            catch (innerErr) {
+                queueMicrotask(() => {
+                    throw innerErr;
+                });
+            }
+        } // No error handler, delegate to host
+        else {
+            queueMicrotask(() => {
+                throw err;
+            });
+        }
+        // Perform cleanup after marking closed
+        performSubscriptionCleanup(__classPrivateFieldGet(this, _SubscriptionObserver_subscription, "f"), state);
+        // Clear reference
+        __classPrivateFieldSet(this, _SubscriptionObserver_subscription, null, "f");
+    }
+    /**
+     * Signals successful completion of the observable sequence.
+     *
+     * Complete is a terminal operation - after calling it:
+     * 1. The subscription is immediately marked as closed
+     * 2. Resources are released via unsubscribe()
+     * 3. No further notifications will be delivered
+     *
+     * If observer.complete throws an error:
+     * - The error is forwarded to observer.error if available
+     * - Otherwise, it's reported asynchronously to the host
+     *
+     * @example
+     * ```ts
+     * // Inside a subscriber function:
+     * observer.next(1);
+     * observer.next(2);
+     * observer.complete();  // Terminates the subscription normally
+     * ```
+     *
+     * > Note: {@link SubscriptionObserver.next | Review the error propagation policy in `next()` on how errors propagate, the behaviour is not obvious on first glance.}
+     */
+    complete() {
+        const state = __classPrivateFieldGet(this, _SubscriptionObserver_state, "f");
+        if (!state || state.closed)
+            return;
+        // Mark closed and get observer in one call
+        const observer = markSubscriptionClosed(state, true);
+        if (observer === null)
+            return;
+        const completeFn = observer?.complete;
+        if (typeof completeFn === "function") {
+            try {
+                completeFn.call(observer);
+            }
+            catch (err) {
+                const errorFn = observer?.error;
+                if (typeof errorFn === "function") {
+                    try {
+                        errorFn.call(observer, err);
+                    }
+                    catch (innerErr) {
+                        queueMicrotask(() => {
+                            throw innerErr;
+                        });
+                    }
+                } // Either a user callback or HostReportErrors emulation (queueMicrotask).
+                else {
+                    queueMicrotask(() => {
+                        throw err;
+                    });
+                }
+            }
+        }
+        // Perform cleanup after marking closed
+        performSubscriptionCleanup(__classPrivateFieldGet(this, _SubscriptionObserver_subscription, "f"), state);
+        // Clear reference
+        __classPrivateFieldSet(this, _SubscriptionObserver_subscription, null, "f");
+    }
+    /**
+     * Returns a standard string tag for the object.
+     * Used by Object.prototype.toString.
+     */
+    get [(_SubscriptionObserver_state = new WeakMap(), _SubscriptionObserver_subscription = new WeakMap(), Symbol.toStringTag)]() {
+        return "Subscription Observer";
+    }
+}
+/**
+ * Observale - A push-based stream for handling async data over time.
+ *
+ * **What it is**: Like a "smart Promise" that can emit multiple values and provides
+ * unified patterns for resource management, error handling, and subscription lifecycle.
+ *
+ * Observable is the central type in this library, representing a push-based
+ * source of values that can be subscribed to. It delivers values to observers
+ * and provides lifecycle guarantees around subscription and cleanup.
+ *
+ * Key guarantees:
+ * 1. Lazy execution - nothing happens until `subscribe()` is called
+ * 2. Multiple independent subscriptions to the same Observable
+ * 3. Each subscriber executes and cleans up independently.
+ * 4. Cleanups are deterministic one‑time resource disposal, the occur when subscriptions are cancelled, error or complete
+ *
+ * Extensions beyond the TC39 proposal:
+ * - Pull API via AsyncIterable interface
+ * - Using/await using support via Symbol.dispose/asyncDispose
+ *
+ * Gotchas:
+ * - Two subscribers → two side‑effects on a cold stream.
+ * - Remember to cancel infinite observables.
+ * - Calling `next()` after `complete()` is a no‑op.
+ * - Errors in observer callbacks go to error handler if provided, else global reporting.
+ * - Synchronous completion during subscribe still captures cleanup functions.
+ *
+ * @typeParam T - Type of values emitted by this Observable
+ */
+export class Observable {
+    /**
+     * Creates a new Observable with the given subscriber function.
+     *
+     * **Important**: This just stores your function - nothing executes until `subscribe()` is called.
+     * Think of it like writing a recipe vs actually cooking.
+     *
+     * The subscriber function is the heart of an Observable. It:
+     * 1. Is called once per subscription (not at Observable creation time)
+     * 2. Receives a SubscriptionObserver to send values through
+     * 3. Can optionally return a cleanup function or subscription
+     *
+     * Nothing happens when an Observable is created - execution only
+     * begins when subscribe() is called.
+     *
+     * @param subscribeFn - Function that implements the Observable's behavior
+     *
+     * Your subscriber function receives a `SubscriptionObserver` to:
+     * - `observer.next(value)` - Emit a value
+     * - `observer.error(err)` - Emit error (terminates)
+     * - `observer.complete()` - Signal completion (terminates)
+     * - `observer.closed` - Check if subscription is still active
+     *
+     * @throws TypeError if subscribeFn is not a function
+     * @throws TypeError if Observable is called without "new"
+     *
+     * @example Timer with cleanup
+     * ```ts
+     * // Timer that emits the current timestamp every second
+     * const timer = new Observable(observer => {
+     *   console.log('Subscription started!');
+     *   const id = setInterval(() => {
+     *     observer.next(Date.now());
+     *   }, 1000);
+     *
+     *   // Return cleanup function
+     *   return () => {
+     *     console.log('Cleaning up timer');
+     *     clearInterval(id);
+     *   };
+     * });
+     * ```
+     *
+     * @example Async operation with error handling
+     * ```ts
+     * const fetch = new Observable(observer => {
+     *   const controller = new AbortController();
+     *
+     *   fetch('/api/data', { signal: controller.signal })
+     *     .then(res => res.json())
+     *     .then(data => {
+     *       observer.next(data);
+     *       observer.complete();
+     *     })
+     *     .catch(err => observer.error(err));
+     *
+     *   return () => controller.abort(); // Cleanup
+     * });
+     * ```
+     */
+    constructor(subscribeFn) {
+        /** The subscriber function provided when the Observable was created */
+        _Observable_subscribeFn.set(this, void 0);
+        if (typeof subscribeFn !== "function") {
+            throw new TypeError("Observable initializer must be a function");
+        }
+        // Add check for constructor invocation
+        if (!(this instanceof Observable)) {
+            throw new TypeError("Observable must be called with new");
+        }
+        __classPrivateFieldSet(this, _Observable_subscribeFn, subscribeFn, "f");
+    }
+    /**
+     * Returns this Observable (required for interoperability).
+     *
+     * This method implements the TC39 Symbol.observable protocol,
+     * which allows foreign Observable implementations to recognize
+     * and interoperate with this implementation.
+     *
+     * @returns This Observable instance
+     */
+    [(_Observable_subscribeFn = new WeakMap(), Symbol.observable)]() {
+        return this;
+    }
+    /**
+     * Implementation of subscribe method (handles both overloads).
+     */
+    subscribe(observerOrNext, errorOrOpts, complete, _opts) {
+        // Check for invalid this context
+        if (this === null || this === undefined) {
+            throw new TypeError('Cannot read property "subscribe" of null or undefined');
+        }
+        /* -------------------------------------------------------------------
+         * 1.  Normalise the observer – mirrors spec step 4.
+         * ------------------------------------------------------------------- */
+        const observer = (typeof observerOrNext === "function"
+            ? {
+                next: observerOrNext,
+                error: errorOrOpts,
+                complete,
+            }
+            : observerOrNext) ?? {}; // ← spec-compliant fallback for null / primitives
+        // Additional options to pass along AbortSignal (part of the WCIG Observables Spec., thought to implement it for convinence reasons)
+        const opts = (typeof observerOrNext === "function"
+            ? _opts
+            : errorOrOpts) ?? {};
+        /* -------------------------------------------------------------------
+         * 2.  Create the Subscription facade (spec: CreateSubscription()).
+         * ------------------------------------------------------------------- */
+        const subscription = createSubscription(observer, opts);
+        /* -------------------------------------------------------------------
+         * 3.  Wrap user observer so we enforce closed-state.
+         * ------------------------------------------------------------------- */
+        const subObserver = new SubscriptionObserver(subscription);
+        /* -------------------------------------------------------------------
+         * 4.  Call observer.start(subscription) – (spec step 10).
+         * ------------------------------------------------------------------- */
+        try {
+            observer.start?.(subscription);
+            if (subscription?.closed)
+                return subscription; // spec step 10.d
+        }
+        catch (err) {
+            // WarnIfAbrupt: report, but return closed subscription
+            // Queue in a micro-task so it surfaces *after* current job,
+            // matching the spec’s “report later” intent.
+            queueMicrotask(() => {
+                // 1. Print to console for visibility
+                console.error(err);
+                // 2. Re-throw so debuggers break (optional, but common)
+                throw err;
+            });
+            subscription?.unsubscribe?.();
+            return subscription;
+        }
+        /* -------------------------------------------------------------------
+         * 5.  Execute the user subscriber and capture its cleanup (spec step 12-16).
+         * ------------------------------------------------------------------- */
+        try {
+            let cleanup = __classPrivateFieldGet(this, _Observable_subscribeFn, "f")?.call(undefined, subObserver) ?? null;
+            // Validate the cleanup value if provided
+            if (cleanup !== undefined && cleanup !== null) {
+                if (!(typeof cleanup === "function" ||
+                    typeof cleanup?.unsubscribe === "function" ||
+                    typeof cleanup?.[Symbol.dispose] === "function" ||
+                    typeof cleanup?.[Symbol.asyncDispose] ===
+                        "function")) {
+                    throw new TypeError("Expected subscriber to return a function, an unsubscribe object, a disposable with a [Symbol.dispose] method, an async-disposable with a [Symbol.asyncDispose] method, or undefined/null");
+                }
+            }
+            // Store the cleanup function in the subscription state
+            const state = SubscriptionStateMap.get(subscription);
+            if (state && cleanup)
+                state.cleanup = cleanup;
+            /**
+             * Handle the case where complete/error was called synchronously during the subscribe function.
+             * This is a critical edge case that requires special handling - when the observer
+             * calls `error()` or `complete()` before the subscribe function returns, we need to ensure
+             * that any teardown function returned by the subscriber is still executed properly.
+             *
+             * The returned teardown wouldn't have been available when `unsubscribe()` was initially
+             * triggered by error/complete, so we need to handle it manually here.
+             *
+             * @example
+             * ```ts
+             * const errorObservable = new Observable(observer => {
+             *   observer.error(new Error("test error")); // Will auto-unsubscribe (but teardown hasn't been defined yet)
+             *   log.push("after error"); // This should still run
+             *
+             *   // Teardown now defined but now the subscription has been closedn
+             *   // but resources being used haven't actually been disposed yet
+             *   return () => {
+             *     log.push("error teardown");
+             *   };
+             * });
+             * ```
+             *
+             * `observer.error` fires before the teardown function is defined, so we would need to manually cleanup ourselves
+             * by manually running the teardown function
+             */
+            if (subscription.closed && cleanup) {
+                cleanupSubscription(cleanup);
+            }
+            cleanup = null;
+        }
+        catch (err) {
+            // 6) If their subscribeFn throws, send that as an error notification
+            subObserver.error(err);
+        }
+        // 7) Finally, hand back the Subscription so callers can cancel whenever they like
+        return subscription;
+    }
+    /**
+     * Enables `for await ... of observable` syntax for direct async iteration.
+     *
+     * This method allows Observables to be used in any context that accepts an AsyncIterable,
+     * implementing the "pull" mode of consuming an Observable.
+     *
+     * Uses default buffer size of 64 items.
+     *
+     * The implementation delegates to the `pull()` function which:
+     * 1. Converts push-based events to pull-based async iteration
+     * 2. Applies backpressure with ReadableStream
+     * 3. Handles proper cleanup on early termination
+     *
+     * @returns An AsyncIterator that yields values from this Observable
+     *
+     * @example
+     * ```ts
+     * const observable = Observable.of(1, 2, 3);
+     *
+     * // Using for-await-of directly on an Observable
+     * for await (const value of observable) {
+     *   console.log(value); // Logs 1, 2, 3
+     * }
+     * ```
+     */
+    async *[Symbol.asyncIterator]() {
+        yield* pull(this);
+    }
+    pull(opts) {
+        return pull(this, opts);
+    }
+    /**
+     * Standard string tag for the object.
+     * Used by Object.prototype.toString.
+     */
+    get [Symbol.toStringTag]() {
+        return "Observable";
+    }
+}
+/**
+ * Converts Promise, an iterable, async iterable, or Observable-like object to an Observable.
+ *
+ * This static method is a key part of the Observable interoperability mechanism,
+ * handling multiple input types in a consistent way.
+ *
+ * **Handles**:
+ * - Arrays, Sets, Maps → sync emission
+ * - Async generators → values over time
+ * - Symbol.observable objects → delegates to their implementation
+ *
+ * Behavior depends on the input type:
+ * 1. Objects with Symbol.observable - Delegates to their implementation
+ * 2. Synchronous iterables - Emits all values then completes
+ * 3. Asynchronous iterables - Emits values as they arrive then completes
+ * 4. Promise - Emits a single value (the resovled value) then completes
+ *
+ * Unlike Promise.resolve, Observable.from will not return the input unchanged
+ * if it's already an Observable, unless it's an instance of the exact same
+ * constructor. This ensures consistent behavior across different Observable
+ * implementations.
+ *
+ * @param input - The object to convert to an Observable
+ * @returns A new Observable that emits values from the input
+ *
+ * @example
+ * ```ts
+ * // From an array
+ * Observable.from([1, 2, 3]).subscribe({
+ *   next: val => console.log(val) // 1, 2, 3
+ * });
+ *
+ * // From a Promise
+ * Observable.from(Promise.resolve("result")).subscribe({
+ *   next: val => console.log(val) // "result"
+ * });
+ *
+ * // From another Observable-like object
+ * const foreign = {
+ *   [Symbol.observable]() {
+ *     return new Observable(obs => {
+ *       obs.next("hello");
+ *       obs.complete();
+ *     });
+ *   }
+ * };
+ * Observable.from(foreign).subscribe({
+ *   next: val => console.log(val) // "hello"
+ * });
+ * ```
+ */
+Object.defineProperty(Observable, "from", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: from
+});
+/**
+ * Creates an Observable that synchronously emits the given values then completes.
+ *
+ * This is a convenience method for creating simple Observables that:
+ * 1. Emit a fixed set of values synchronously
+ * 2. Complete immediately after emitting all values
+ * 3. Never error
+ *
+ * It's the Observable equivalent of `Promise.resolve()` for single values
+ * or `[].values()` for multiple values.
+ *
+ * @param items - Values to emit
+ * @returns A new Observable that emits the given values then completes
+ *
+ * @example
+ * ```ts
+ * // Create and subscribe
+ * Observable.of(1, 2, 3).subscribe({
+ *   next: val => console.log(val), // Logs 1, 2, 3
+ *   complete: () => console.log('Done!')
+ * });
+ *
+ * // Output:
+ * // 1
+ * // 2
+ * // 3
+ * // Done!
+ * ```
+ */
+Object.defineProperty(Observable, "of", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: of
+});
+/**
+ * Converts a Observable into an AsyncGenerator with backpressure control.
+ *
+ * This method provides more control over async iteration than the default
+ * Symbol.asyncIterator implementation, allowing consumers to:
+ *
+ * 1. Specify a queuing strategy with a custom highWaterMark
+ * 2. Control buffering behavior when the producer is faster than the consumer
+ * 3. Apply backpressure to prevent memory issues with fast producers
+ *
+ * The implementation uses ReadableStream internally to manage buffering
+ * and backpressure, pausing the producer when the buffer fills up.
+ *
+ * @param options - Configuration options for the pull operation
+ * @returns An AsyncGenerator that yields values from this Observable
+ *
+ * @example
+ * ```ts
+ * // Buffer up to 5 items before applying backpressure
+ * for await (const value of observable.pull({
+ *   strategy: { highWaterMark: 5 }
+ * })) {
+ *   console.log(value);
+ *   // Slow consumer - producer will pause when buffer fills
+ *   await new Promise(r => setTimeout(r, 1000));
+ * }
+ * ```
+ */
+Object.defineProperty(Observable, "pull", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: pull
+});
+/**
+ * Cached empty observable handler
+ * @internal
+ */
+function EMPTY(obs) {
+    obs.complete();
+}
+/**
+ * Creates an Observable that synchronously emits the given values then completes.
+ *
+ * This standalone function implements the Observable.of static method while
+ * properly supporting subclassing. It's the Observable equivalent of:
+ * - `Array.of()` for collections
+ * - `Promise.resolve()` for single values
+ *
+ * Key behaviors:
+ * 1. Emits values synchronously when subscribed
+ * 2. Completes immediately after all values are emitted
+ * 3. Never errors
+ * 4. Respects the constructor it was called on for subclassing
+ *
+ * @param items - Values to emit
+ * @returns A new Observable that emits the given values then completes
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * of(1, 2, 3).subscribe({
+ *   next: x => console.log(x),
+ *   complete: () => console.log('Done!')
+ * });
+ * // Output: 1, 2, 3, Done!
+ *
+ * // Subclassing support
+ * class MyObservable extends Observable<number> {
+ *   // Custom methods...
+ * }
+ *
+ * // Creates a MyObservable instance
+ * const mine = MyObservable.of(1, 2, 3);
+ * ```
+ */
+export function of(...items) {
+    const Constructor = typeof this === "function"
+        ? this
+        : Observable;
+    const len = items.length;
+    // Pre-defined handlers for common cases to avoid creating new closures
+    switch (len) {
+        case 0:
+            return new Constructor(EMPTY);
+        case 1:
+            return new Constructor((obs) => {
+                obs.next(items[0]);
+                obs.complete();
+            });
+        case 2:
+            return new Constructor((obs) => {
+                obs.next(items[0]);
+                obs.next(items[1]);
+                obs.complete();
+            });
+        case 3:
+            return new Constructor((obs) => {
+                obs.next(items[0]);
+                obs.next(items[1]);
+                obs.next(items[2]);
+                obs.complete();
+            });
+        default:
+            // For arrays > 3 items, balance between code size and performance
+            return new Constructor((obs) => {
+                // Based on benchmarking:
+                // - Arrays < 100: simple loop is fine (method call dominates)
+                // - Arrays >= 100: unrolling provides measurable benefit
+                if (len < 100) {
+                    for (let i = 0; i < len; i++) {
+                        obs.next(items[i]);
+                    }
+                }
+                else {
+                    // Unroll by 8 for large arrays (2.8x speedup)
+                    let i = 0;
+                    const limit = len - (len % 8);
+                    for (; i < limit; i += 8) {
+                        obs.next(items[i]);
+                        obs.next(items[i + 1]);
+                        obs.next(items[i + 2]);
+                        obs.next(items[i + 3]);
+                        obs.next(items[i + 4]);
+                        obs.next(items[i + 5]);
+                        obs.next(items[i + 6]);
+                        obs.next(items[i + 7]);
+                    }
+                    // Handle remainder
+                    for (; i < len; i++) {
+                        obs.next(items[i]);
+                    }
+                }
+                obs.complete();
+            });
+    }
+}
+/**
+ * Converts an Observable-like, sync iterable, or async iterable into an Observable.
+ *
+ * This is the standalone implementation of Observable.from, supporting:
+ * - Objects with Symbol.observable (Observable-like)
+ * - Regular iterables (arrays, Maps, Sets, generators)
+ * - Async iterables (async generators, ReadableStreams)
+ *
+ * Conversion follows these rules:
+ * 1. For Symbol.observable objects: delegates to their implementation
+ * 2. For Promises: resolves and emits the promise's value
+ * 3. For iterables: synchronously emits all values, then completes
+ * 4. For async iterables: emits values as they arrive, then completes
+ *
+ * This function properly supports subclassing, preserving the constructor
+ * it was called on.
+ *
+ * @throws TypeError if input is null, undefined, or not convertible
+ *
+ * @example
+ * ```ts
+ * // From array
+ * from([1, 2, 3]).subscribe(x => console.log(x));
+ * // Output: 1, 2, 3
+ *
+ * // From Promise
+ * from(Promise.resolve('done')).subscribe(x => console.log(x));
+ * // Output: 'done'
+ *
+ * // From Map
+ * from(new Map([['a', 1], ['b', 2]])).subscribe(x => console.log(x));
+ * // Output: ['a', 1], ['b', 2]
+ *
+ * // From another Observable implementation
+ * const foreign = {
+ *   [Symbol.observable]() {
+ *     return { subscribe: observer => {
+ *       observer.next('hello');
+ *       observer.complete();
+ *       return { unsubscribe() {} };
+ *     }};
+ *   }
+ * };
+ * from(foreign).subscribe(x => console.log(x));
+ * // Output: 'hello'
+ * ```
+ */
+export function from(input, { throwError = true } = {}) {
+    if (input === null || input === undefined) {
+        throw new TypeError("Cannot convert undefined or null to Observable");
+    }
+    const Constructor = typeof this === "function"
+        ? this
+        : Observable;
+    // Faster implementation of iteration for array-like values
+    const arr = input;
+    if (Array.isArray(input) || typeof arr.length === "number") {
+        const len = arr.length;
+        // Optimize for small arrays
+        if (len === 0)
+            return new Constructor(EMPTY);
+        if (len === 1) {
+            return new Constructor((obs) => {
+                if (throwError)
+                    assertObservableError(arr[0], obs);
+                obs.next(arr[0]);
+                obs.complete();
+            });
+        }
+        // Type check to ensure it's actually array-like
+        return new Constructor((obs) => {
+            try {
+                // Typed arrays: no bounds checking needed, direct iteration
+                // Small arrays: simple loop with early exit checks
+                if (len < 100 || ArrayBuffer.isView(arr)) {
+                    for (let i = 0; i < len; i++) {
+                        if (throwError)
+                            assertObservableError(arr[i]);
+                        obs.next(arr[i]);
+                        if (obs.closed)
+                            return;
+                    }
+                }
+                else {
+                    // Large arrays: unroll with less frequent closed checks
+                    let i = 0;
+                    const limit = len - (len % 8);
+                    // Check closed once per 8 items (balanced approach)
+                    for (; i < limit; i += 8) {
+                        if (throwError) {
+                            assertObservableError(arr[i]);
+                            assertObservableError(arr[i + 1]);
+                            assertObservableError(arr[i + 2]);
+                            assertObservableError(arr[i + 3]);
+                            assertObservableError(arr[i + 4]);
+                            assertObservableError(arr[i + 5]);
+                            assertObservableError(arr[i + 6]);
+                            assertObservableError(arr[i + 7]);
+                        }
+                        obs.next(arr[i]);
+                        obs.next(arr[i + 1]);
+                        obs.next(arr[i + 2]);
+                        obs.next(arr[i + 3]);
+                        obs.next(arr[i + 4]);
+                        obs.next(arr[i + 5]);
+                        obs.next(arr[i + 6]);
+                        obs.next(arr[i + 7]);
+                        if (obs.closed)
+                            return;
+                    }
+                    // Handle remainder with checks
+                    for (; i < len; i++) {
+                        if (throwError)
+                            assertObservableError(arr[i]);
+                        obs.next(arr[i]);
+                        if (obs.closed)
+                            return;
+                    }
+                }
+            }
+            catch (err) {
+                obs.error(err);
+            }
+            obs.complete();
+        });
+    }
+    // Case 1 – object with @@observable
+    const observableFn = input[Symbol.observable];
+    if (typeof observableFn === "function") {
+        const observable = observableFn.call(input);
+        // Validate the result has a subscribe method
+        if (!observable || typeof observable.subscribe !== "function") {
+            throw new TypeError("Object returned from [Symbol.observable]() does not implement subscribe method");
+        }
+        // Return directly if it's already an instance of the target constructor
+        if (observable instanceof Constructor)
+            return observable;
+        // Otherwise, wrap it to ensure consistent behavior
+        return new Constructor((observer) => {
+            const sub = observable.subscribe(observer);
+            return () => sub?.unsubscribe?.();
+        });
+    }
+    // Fast implementation for Set & Maps which are generally optimized
+    // by the runtime when using `for..of` loops
+    if (input instanceof Set || input instanceof Map) {
+        const collection = input;
+        const size = collection.size;
+        if (size === 0)
+            return new Constructor(EMPTY);
+        return new Constructor((obs) => {
+            // For...of is optimized for Sets in V8
+            for (const item of collection) {
+                if (throwError)
+                    assertObservableError(item, obs);
+                obs.next(item);
+                if (obs.closed)
+                    return;
+            }
+            obs.complete();
+        });
+    }
+    // Case 2 – promise
+    const promise = input;
+    if (typeof promise.then === "function") {
+        return new Constructor((obs) => {
+            promise.then((value) => {
+                if (throwError)
+                    assertObservableError(value, obs);
+                obs.next(value);
+                obs.complete();
+            }, 
+            // Error during iteration
+            (err) => obs.error(err));
+        });
+    }
+    // Case 3 – synchronous iterable
+    const iteratorFn = input[Symbol.iterator];
+    if (typeof iteratorFn === "function") {
+        return new Constructor((obs) => {
+            const iterator = iteratorFn.call(input);
+            try {
+                for (let step = iterator.next(); !step.done; step = iterator.next()) {
+                    if (throwError)
+                        assertObservableError(step.value);
+                    obs.next(step.value);
+                    // If subscription was closed during iteration, clean up and exit
+                    if (obs.closed)
+                        break;
+                }
+                obs.complete();
+            }
+            catch (err) {
+                obs.error(err);
+            }
+            return () => {
+                if (typeof iterator?.return === "function") {
+                    try {
+                        iterator.return(); // IteratorClose
+                    }
+                    catch (err) {
+                        queueMicrotask(() => {
+                            throw err;
+                        });
+                    }
+                }
+            };
+        });
+    }
+    // Case 4 – async iterable
+    const asyncIteratorFn = input[Symbol.asyncIterator];
+    if (typeof asyncIteratorFn === "function") {
+        return new Constructor((obs) => {
+            const asyncIterator = asyncIteratorFn.call(input);
+            // Start consuming the async iterable
+            (async () => {
+                try {
+                    for (let step = await asyncIterator.next(); !step.done; step = await asyncIterator.next()) {
+                        if (throwError)
+                            assertObservableError(step.value);
+                        obs.next(step.value);
+                        // If subscription was closed during iteration, clean up and exit
+                        if (obs.closed)
+                            break;
+                    }
+                    // Normal completion
+                    obs.complete();
+                }
+                catch (err) {
+                    // Error during iteration
+                    obs.error(err);
+                }
+            })();
+            return () => {
+                if (typeof asyncIterator?.return === "function") {
+                    try {
+                        asyncIterator.return(); // IteratorClose
+                    }
+                    catch (err) {
+                        queueMicrotask(() => {
+                            throw err;
+                        });
+                    }
+                }
+            };
+        });
+    }
+    throw new TypeError("Input is not Observable, Iterable, AsyncIterable, Promise, or ReadableStream");
+}
+export async function* pull(observable, { strategy = { highWaterMark: 64 }, throwError = true } = {}) {
+    const obs = observable?.[Symbol.observable]?.();
+    let sub = null;
+    // Create a ReadableStream that will buffer values from the Observable
+    const stream = new ReadableStream({
+        start: (ctrl) => {
+            // Subscribe to the Observable and connect it to the stream
+            sub = obs?.subscribe({
+                // Normal values flow directly into the stream
+                next: (v) => ctrl.enqueue(v),
+                // Errors are wrapped as special values rather than using stream.error()
+                // This ensures values emitted before the error are still processed
+                error: (e) => {
+                    ctrl.enqueue(ObservableError.from(e, "observable:pull"));
+                    sub = null;
+                },
+                // Close the stream when the Observable completes
+                complete: () => {
+                    ctrl.close();
+                    sub = null;
+                },
+            });
+        },
+        // Clean up the subscription if the stream is cancelled
+        // This happens when the AsyncGenerator is terminated early
+        cancel: () => {
+            sub?.unsubscribe();
+            sub = null;
+        },
+    }, strategy);
+    // Get a reader for the stream and yield values as they become available
+    const reader = stream.getReader();
+    try {
+        while (true) {
+            // Wait for the next value (with backpressure automatically applied)
+            const { value, done } = await reader.read();
+            // If we received a wrapped error, unwrap and throw it
+            if (throwError)
+                assertObservableError(value);
+            // If the stream is done (Observable completed), exit the loop
+            if (done)
+                break;
+            // Otherwise, yield the value to the consumer
+            yield value;
+        }
+    }
+    finally {
+        // Ensure resources are cleaned up even if iteration is terminated early
+        // This guarantees no memory leaks, even with break or thrown exceptions
+        reader.releaseLock();
+        await stream.cancel();
+    }
+}
+/**
+ * Checks if a value is an Observable instance from this library.
+ *
+ * When working with different Observable implementations or mixed data types, you often need
+ * to verify what kind of object you're dealing with. This function provides a reliable way to
+ * check if something is specifically an instance of our Observable class, which is helpful
+ * for type safety and ensuring you can use all the methods available on our implementation.
+ *
+ * **Why This Function Exists**:
+ *
+ * In JavaScript ecosystems, you might encounter different Observable implementations - RxJS,
+ * this library, custom implementations, or objects that just happen to have a `subscribe` method.
+ * Without a proper way to distinguish between them, you'd have to either:
+ * - Risk calling methods that don't exist (crashes your app)
+ * - Write defensive code with lots of property checks (clutters your logic)
+ * - Use duck typing that might give false positives (unreliable)
+ *
+ * This function eliminates those problems by giving you a definitive answer: "Is this an
+ * Observable from our library?" If yes, you know exactly what methods and properties are
+ * available.
+ *
+ * **How It Relates to Other Checks**:
+ *
+ * Think of this as the strict cousin of `isSpecObservable()`. While `isSpecObservable()`
+ * asks "can I subscribe to this?" this function asks "is this specifically our Observable?"
+ *
+ * Use `isObservable()` when you need to ensure you're working with our exact implementation,
+ * and `isSpecObservable()` when you just need something subscribable.
+ *
+ * **Performance Story**:
+ *
+ * This function uses `instanceof`, which modern JavaScript engines optimize very well. It's
+ * essentially a pointer comparison under the hood, making it extremely fast and suitable for
+ * use in performance-critical code paths.
+ *
+ * The performance characteristics are:
+ * - Single `instanceof` check (optimized by JavaScript engines)
+ * - No method calls or property access required
+ * - Safe to use in tight loops or frequently called functions
+ * - Memory efficient (no allocations, just a boolean return)
+ *
+ * **Common Ways to Use This Function**:
+ *
+ * ```typescript
+ * // Scenario 1: Type-safe method access
+ * function processObservable(input: unknown) {
+ *   if (isObservable(input)) {
+ *     // TypeScript now knows input is Observable<unknown>
+ *     const generator = input.pull({ strategy: { highWaterMark: 10 } });
+ *     return generator; // Can safely use our specific methods
+ *   }
+ *
+ *   throw new Error('Expected an Observable from this library');
+ * }
+ *
+ * // Scenario 2: Library interoperability
+ * function convertToOurObservable(source: unknown): Observable<any> {
+ *   if (isObservable(source)) {
+ *     return source; // Already our type, no conversion needed
+ *   }
+ *
+ *   if (isSpecObservable(source)) {
+ *     return Observable.from(source); // Convert from other implementation
+ *   }
+ *
+ *   throw new Error('Cannot convert to Observable');
+ * }
+ *
+ * // Scenario 3: Filtering mixed arrays
+ * const mixedSources = [rxjsObservable, ourObservable, promise, array];
+ * const ourObservables = mixedSources.filter(isObservable);
+ * // ourObservables is now Observable[] with full type safety
+ *
+ * // Scenario 4: Defensive programming
+ * function subscribeToSource(source: unknown) {
+ *   if (isObservable(source)) {
+ *     // We know exactly what methods are available
+ *     return source.subscribe({ next: console.log });
+ *   } else if (isSpecObservable(source)) {
+ *     // Different Observable implementation, but still subscribable
+ *     return source.subscribe({ next: console.log });
+ *   } else {
+ *     throw new Error('Source is not observable');
+ *   }
+ * }
+ * ```
+ *
+ * **What Makes This Function Reliable**:
+ *
+ * Unlike duck typing (checking for the presence of methods), this function is precise:
+ * - Returns true only for actual instances of our Observable class
+ * - Handles inheritance correctly (subclasses return true)
+ * - Never gives false positives from look-alike objects
+ * - Works correctly across different module loading scenarios
+ *
+ * **Edge Cases Handled**:
+ * - `null` and `undefined` → false (not Observables)
+ * - Objects with `subscribe` methods → false (unless they're actually our Observable)
+ * - Subclasses of Observable → true (proper inheritance support)
+ * - Cross-frame instances → true (same constructor reference)
+ *
+ * **When to Use This vs Other Options**:
+ *
+ * Choose `isObservable()` when:
+ * - You need to access methods specific to our Observable implementation
+ * - You're building type guards for strict type checking
+ * - You need to distinguish between different Observable libraries
+ * - You're doing performance-critical filtering of mixed object types
+ *
+ * Choose `isSpecObservable()` instead when:
+ * - You just need something that can be subscribed to
+ * - You want maximum compatibility with other Observable implementations
+ * - You're building generic utilities that work with any Observable-like object
+ *
+ * @template T - The expected type for the Observable's emitted values
+ * @param value - Any value that might or might not be our Observable
+ * @returns true if the value is an instance of our Observable class, false otherwise
+ *
+ * @example Simple type checking
+ * ```typescript
+ * const maybeObservable: unknown = getDataSource();
+ *
+ * if (isObservable(maybeObservable)) {
+ *   // TypeScript knows maybeObservable is Observable<unknown>
+ *   const subscription = maybeObservable.subscribe(console.log);
+ *
+ *   // Can also use our specific methods
+ *   for await (const value of maybeObservable.pull()) {
+ *     console.log('Pulled:', value);
+ *   }
+ * } else {
+ *   console.log('Not our Observable implementation');
+ * }
+ * ```
+ *
+ * @example Building a conversion utility
+ * ```typescript
+ * function ensureOurObservable<T>(source: unknown): Observable<T> {
+ *   if (isObservable<T>(source)) {
+ *     return source; // Already the right type
+ *   }
+ *
+ *   if (isSpecObservable<T>(source)) {
+ *     // Convert from another Observable implementation
+ *     return new Observable<T>(observer => {
+ *       const sub = source.subscribe(observer);
+ *       return () => sub.unsubscribe();
+ *     });
+ *   }
+ *
+ *   // Try to convert from other types
+ *   return Observable.from(source as any);
+ * }
+ * ```
+ *
+ * @example Library integration
+ * ```typescript
+ * // Function that works with any Observable but optimizes for ours
+ * function processStream<T>(stream: unknown): AsyncGenerator<T> {
+ *   if (isObservable<T>(stream)) {
+ *     // Use our optimized pull method
+ *     return stream.pull();
+ *   } else if (isSpecObservable<T>(stream)) {
+ *     // Convert and then use our method
+ *     return Observable.from(stream).pull();
+ *   } else {
+ *     throw new Error('Expected an Observable-like object');
+ *   }
+ * }
+ * ```
+ */
+export function isObservable(value) {
+    // This is a straightforward instanceof check
+    // Works reliably across module boundaries and handles inheritance correctly
+    return value instanceof Observable;
+}
+/**
+ * Checks if a value conforms to the Observable specification protocol.
+ *
+ * When building applications that work with multiple Observable implementations, you need a way
+ * to identify objects that can be subscribed to, regardless of which specific library created
+ * them. This function provides that capability by checking for the core Observable protocol
+ * rather than specific implementation details.
+ *
+ * **Why This Function Exists**:
+ *
+ * The Observable ecosystem includes many implementations - RxJS, this library, Zen Observable,
+ * and others. Each has its own class structure, but they all follow the same basic protocol:
+ * having a `[Symbol.observable]()` method that returns an object with a `subscribe()` method.
+ *
+ * Without this function, you'd need to write complex checks to determine if something is
+ * subscribable, leading to:
+ * - Fragile duck typing that breaks with edge cases
+ * - Verbose property checking that clutters your code
+ * - Missing compatibility with new Observable implementations
+ * - Inconsistent behavior across different parts of your application
+ *
+ * This function solves those problems by implementing the official Observable protocol check.
+ *
+ * **How It Relates to Other Checks**:
+ *
+ * Think of this as the diplomatic cousin of `isObservable()`. While `isObservable()` checks
+ * for our specific implementation, this function asks "do you speak the Observable protocol?"
+ * It's designed for interoperability and maximum compatibility.
+ *
+ * The relationship between these functions is:
+ * - `isObservable()` → "Are you our exact Observable class?"
+ * - `isSpecObservable()` → "Can I subscribe to you using the standard protocol?"
+ *
+ * **Performance Story**:
+ *
+ * This function is more complex than `isObservable()` because it needs to check multiple
+ * properties and call a method. However, it's still quite efficient:
+ *
+ * - Fast property access for Symbol.observable
+ * - Single method call to get the subscribable object
+ * - Type checking for the subscribe method
+ * - Early returns for non-objects to avoid unnecessary work
+ *
+ * While not as fast as `instanceof`, it's still suitable for most use cases. If you're in a
+ * performance-critical path and know you're only dealing with our Observable implementation,
+ * prefer `isObservable()`.
+ *
+ * **Common Ways to Use This Function**:
+ *
+ * ```typescript
+ * // Scenario 1: Cross-library compatibility
+ * import { Observable as RxObservable } from 'rxjs';
+ * import { Observable as OurObservable } from './observable.ts';
+ *
+ * function processAnyObservable<T>(source: unknown): Promise<T[]> {
+ *   if (isSpecObservable<T>(source)) {
+ *     // Works with RxJS, our Observable, or any other spec-compliant implementation
+ *     const results: T[] = [];
+ *
+ *     return new Promise((resolve, reject) => {
+ *       source.subscribe({
+ *         next: value => results.push(value),
+ *         error: reject,
+ *         complete: () => resolve(results)
+ *       });
+ *     });
+ *   }
+ *
+ *   throw new Error('Source must be Observable-like');
+ * }
+ *
+ * // Scenario 2: Building generic utilities
+ * function toArray<T>(source: unknown): Promise<T[]> {
+ *   if (isSpecObservable<T>(source)) {
+ *     return new Promise((resolve, reject) => {
+ *       const items: T[] = [];
+ *       source.subscribe({
+ *         next: item => items.push(item),
+ *         error: reject,
+ *         complete: () => resolve(items)
+ *       });
+ *     });
+ *   }
+ *
+ *   // Fallback for other iterable types
+ *   if (Array.isArray(source)) return Promise.resolve([...source]);
+ *
+ *   throw new Error('Cannot convert to array');
+ * }
+ *
+ * // Scenario 3: Input validation in APIs
+ * function subscribeToStream<T>(
+ *   stream: unknown,
+ *   handler: (value: T) => void
+ * ): () => void {
+ *   if (!isSpecObservable<T>(stream)) {
+ *     throw new TypeError('Expected an Observable-like object');
+ *   }
+ *
+ *   const subscription = stream.subscribe({ next: handler });
+ *   return () => subscription.unsubscribe();
+ * }
+ *
+ * // Scenario 4: Filtering and type narrowing
+ * const mixedSources: unknown[] = [
+ *   rxjsObservable,
+ *   ourObservable,
+ *   { subscribe() { return { unsubscribe() {} }; } }, // Custom implementation
+ *   "not observable",
+ *   42
+ * ];
+ *
+ * const observableSources = mixedSources.filter(isSpecObservable);
+ * // observableSources is now Array<{ subscribe: Function, [Symbol.observable]: Function }>
+ * ```
+ *
+ * **What Makes This Function Robust**:
+ *
+ * This function implements the official Observable protocol checking:
+ * 1. Verifies the object has `Symbol.observable` method
+ * 2. Calls that method to get the subscribable object
+ * 3. Ensures the result has a working `subscribe` method
+ * 4. Handles errors gracefully (returns false rather than throwing)
+ *
+ * **Edge Cases Handled**:
+ * - `null` and `undefined` → false (not objects)
+ * - Objects without `Symbol.observable` → false (not Observable protocol)
+ * - `Symbol.observable` that throws → false (graceful error handling)
+ * - `Symbol.observable` returning non-objects → false (invalid protocol)
+ * - Objects with `subscribe` but no `Symbol.observable` → false (incomplete protocol)
+ *
+ * **When to Use This vs Other Options**:
+ *
+ * Choose `isSpecObservable()` when:
+ * - Building libraries that should work with any Observable implementation
+ * - You need maximum compatibility across the Observable ecosystem
+ * - You're creating utilities for consuming streams regardless of their origin
+ * - You want to follow the official Observable specification strictly
+ *
+ * Choose `isObservable()` instead when:
+ * - You need methods specific to our Observable implementation
+ * - Performance is critical and you know the expected types
+ * - You're working within a single Observable implementation ecosystem
+ * - You need compile-time guarantees about available methods
+ *
+ * @template T - The expected type for values emitted by the Observable
+ * @param value - Any value that might conform to the Observable protocol
+ * @returns true if the value implements the Observable specification, false otherwise
+ *
+ * @example Cross-library compatibility
+ * ```typescript
+ * import { Observable as RxObservable } from 'rxjs';
+ * import { Observable as OurObservable } from './observable.ts';
+ *
+ * const sources = [
+ *   new RxObservable(sub => sub.next(1)),
+ *   new OurObservable(obs => obs.next(2)),
+ *   { subscribe() { return { unsubscribe() {} }; } } // Custom
+ * ];
+ *
+ * // Process any Observable-like object
+ * sources.forEach(source => {
+ *   if (isSpecObservable(source)) {
+ *     console.log('Can subscribe to this source');
+ *     source.subscribe({ next: console.log });
+ *   }
+ * });
+ * ```
+ *
+ * @example Building a universal Observable utility
+ * ```typescript
+ * function first<T>(source: unknown): Promise<T> {
+ *   if (!isSpecObservable<T>(source)) {
+ *     return Promise.reject(new Error('Source must be Observable'));
+ *   }
+ *
+ *   return new Promise((resolve, reject) => {
+ *     const subscription = source.subscribe({
+ *       next: value => {
+ *         subscription.unsubscribe();
+ *         resolve(value);
+ *       },
+ *       error: reject,
+ *       complete: () => reject(new Error('Observable completed without emitting'))
+ *     });
+ *   });
+ * }
+ *
+ * // Works with any Observable implementation
+ * const result1 = await first(rxjsObservable);
+ * const result2 = await first(ourObservable);
+ * ```
+ *
+ * @example Input validation for APIs
+ * ```typescript
+ * interface StreamProcessor<T> {
+ *   process(stream: unknown): AsyncGenerator<T>;
+ * }
+ *
+ * class UniversalProcessor<T> implements StreamProcessor<T> {
+ *   async* process(stream: unknown): AsyncGenerator<T> {
+ *     if (isSpecObservable<T>(stream)) {
+ *       // Convert any Observable to async generator
+ *       const observable = stream[Symbol.observable]();
+ *
+ *       let resolve: (value: IteratorResult<T>) => void;
+ *       let reject: (error: any) => void;
+ *       let promise = new Promise<IteratorResult<T>>((res, rej) => {
+ *         resolve = res;
+ *         reject = rej;
+ *       });
+ *
+ *       const subscription = observable.subscribe({
+ *         next: value => {
+ *           resolve({ value, done: false });
+ *           promise = new Promise<IteratorResult<T>>((res, rej) => {
+ *             resolve = res;
+ *             reject = rej;
+ *           });
+ *         },
+ *         error: reject,
+ *         complete: () => resolve({ value: undefined as any, done: true })
+ *       });
+ *
+ *       try {
+ *         while (true) {
+ *           const result = await promise;
+ *           if (result.done) break;
+ *           yield result.value;
+ *         }
+ *       } finally {
+ *         subscription.unsubscribe();
+ *       }
+ *     } else {
+ *       throw new Error('Input must implement Observable protocol');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function isSpecObservable(value) {
+    // Early return for non-objects
+    if (value === null || value === undefined || typeof value !== "object") {
+        return false;
+    }
+    try {
+        // Check if the object has the Symbol.observable method
+        const observableMethod = value[Symbol.observable];
+        if (typeof observableMethod !== "function") {
+            return false;
+        }
+        // Call the method to get the subscribable object
+        const subscribable = observableMethod.call(value);
+        // Verify the result has a subscribe method
+        return (subscribable !== null &&
+            subscribable !== undefined &&
+            typeof subscribable === "object" &&
+            typeof subscribable.subscribe === "function");
+    }
+    catch {
+        // If any step throws, it's not a valid Observable
+        return false;
+    }
+}