@okikio/observables 1.0.2

package/script/observable.d.ts

@@ -0,0 +1,1610 @@
+/**
+ * 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 type { ObservableProtocol, SpecObservable, SpecSubscription } from "./_spec.js";
+import type { Observer, Subscription } from "./_types.js";
+import { ObservableError } from "./error.js";
+import { Symbol } from "./symbol.js";
+/**
+ * Teardown function returned by the *subscriber* when it needs to release
+ * resources (DOM handlers, sockets…).
+ *
+ * A *teardown* function or object returned from the subscriber to release
+ * resources when a subscription terminates.
+ *
+ * - `() => void` – plain cleanup callback.
+ * - `{ unsubscribe() }` – imperative cancel method.
+ * - `{ [Symbol.dispose](): void }` – synchronous disposable.
+ * - `{ [Symbol.asyncDispose](): Promise<void> }` – async disposable.
+ * - `undefined | null` – nothing to clean up.
+ *
+ * **Timing Note**: Cleanup is captured and called **even if** `observer.error()` or
+ * `observer.complete()` is called synchronously before your subscriber returns.
+ *
+ * @example
+ * ```ts
+ * new Observable(observer => {
+ *   const timer = setInterval(() => observer.next(Date.now()), 1000);
+ *   // Return teardown function
+ *   return () => clearInterval(timer);
+ * });
+ * ```
+ *
+ * @example Multi-resource cleanup
+ * ```ts
+ * new Observable(observer => {
+ *   const timer = setInterval(tick, 1000);
+ *   const ws = new WebSocket(url);
+ *   const sub = other.subscribe(observer);
+ *
+ *   return () => {
+ *     clearInterval(timer);
+ *     ws.close();
+ *     sub.unsubscribe();
+ *   };
+ * });
+ */
+export type Teardown = (() => void) | SpecSubscription | AsyncDisposable | Disposable | null | undefined | void;
+/**
+ * Internal state associated with each Subscription.
+ * Using a dedicated state object stored in a WeakMap gives us:
+ * 1. A single source of truth for subscription state
+ * 2. No circular references that might leak memory
+ * 3. Clean separation between public interface and internal state
+ */
+export interface StateMap<T> {
+    /** True once subscription is closed via unsubscribe, error, or complete */
+    closed: boolean;
+    /** Reference to the observer; nulled on closure to prevent memory leaks */
+    observer: Observer<T> | null;
+    /** Function or object returned by subscriber; used for resource cleanup */
+    cleanup: Teardown;
+    /** AbortSignal's abort event handler */
+    removeAbortHandler?: (() => void) | null;
+}
+/**
+ * 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 declare const SubscriptionStateMap: WeakMap<Subscription, StateMap<unknown>>;
+/**
+ * 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 declare function createSubscription<T>(observer: Observer<T>, opts?: {
+    signal?: AbortSignal;
+} | null): Subscription;
+/**
+ * Mark subscription as closed and return observer reference.
+ * Does NOT perform cleanup - that happens later.
+ */
+export declare function markSubscriptionClosed<T>(state: StateMap<T> | undefined | null, returnObserver: true): Observer<T> | null;
+/**
+ * Marks a subscription as closed when the caller does not need the observer.
+ */
+export declare function markSubscriptionClosed<T>(state: StateMap<T> | undefined | null, returnObserver: false): undefined | null;
+/**
+ * Marks a subscription as closed and optionally returns the detached observer.
+ */
+export declare function markSubscriptionClosed<T>(state: StateMap<T> | undefined | null, returnObserver?: boolean): Observer<T> | undefined | null;
+/**
+ * Perform cleanup if available. Safe to call multiple times.
+ */
+export declare function performSubscriptionCleanup(subscription: Subscription, state?: StateMap<unknown> | null): void;
+/**
+ * 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 declare function closeSubscription(subscription: Subscription, stateMap?: StateMap<unknown> | undefined | null): Observer<unknown> | null | void;
+/**
+ * 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 declare class SubscriptionObserver<T> {
+    #private;
+    /**
+     * 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(): boolean;
+    /**
+     * Creates a new SubscriptionObserver attached to the given subscription.
+     *
+     * @param subscription - The subscription that created this observer
+     */
+    constructor(subscription?: Subscription | null);
+    /**
+     * 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: T): void;
+    /**
+     * 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: unknown): void;
+    /**
+     * 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(): void;
+    /**
+     * Returns a standard string tag for the object.
+     * Used by Object.prototype.toString.
+     */
+    get [Symbol.toStringTag](): "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 declare class Observable<T> implements AsyncIterable<T>, SpecObservable<T>, ObservableProtocol<T> {
+    #private;
+    /**
+     * 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: (obs: SubscriptionObserver<T>) => Teardown);
+    /**
+     * 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
+     */
+    [Symbol.observable](): Observable<T>;
+    /**
+     * Subscribes to this Observable with an observer object.
+     *
+     * This method creates a subscription that:
+     * 1. Executes the subscriber function to begin producing values
+     * 2. Delivers those values to the observer's callbacks
+     * 3. Returns a subscription object for cancellation
+     *
+     * **What happens**: Creates subscription → calls observer.start() → executes subscriber function →
+     * stores cleanup → returns subscription for cancellation.
+     *
+     * Subscription Lifecycle:
+     * - Starts immediately and synchronously
+     * - Continues until explicitly cancelled or completed/errored
+     * - Guarantees proper resource cleanup on termination
+     *
+     * **Error handling**: If you provide an error callback, it catches all stream errors.
+     * If not, errors become unhandled Promise rejections.
+     *
+     * **Memory warning**: Infinite Observables need manual `unsubscribe()` or `using` blocks.
+     * If the Observable never calls `complete()` or `error()`,
+     * resources will not be automatically released unless you call
+     * `unsubscribe()` manually.
+     *
+     * For long-lived subscriptions, consider:
+     * 1. Using a `using` block with this subscription
+     * 2. Setting up a timeout or take-until condition
+     * 3. Explicitly calling `unsubscribe()` when no longer needed
+     *
+     * @param observer - Object with next/error/complete callbacks
+     * @param opts.signal - Optional AbortSignal to close subscription
+     * @returns Subscription object that can be used to cancel the subscription
+     *
+     * @example Observer object
+     * ```ts
+     * const subscription = observable.subscribe({
+     *   next(value) { console.log('Received:', value) },
+     *   error(err) { console.error('Error:', err) },
+     *   complete() { console.log('Done!') }
+     * });
+     *
+     * // Later, to cancel:
+     * subscription.unsubscribe();
+     * ```
+     *
+     * @example Two ways to subscribe
+     * ```ts
+     * // Observer object (recommended)
+     * obs.subscribe({
+     *   start(sub) { console.log('Started, can call sub.unsubscribe()'); },
+     *   next(val) { console.log('Value:', val); },
+     *   error(err) { console.error('Error:', err); },
+     *   complete() { console.log('Done'); }
+     * });
+     *
+     * // Separate functions
+     * obs.subscribe(
+     *   val => console.log(val),
+     *   err => console.error(err),
+     *   () => console.log('done')
+     * );
+     * ```
+     */
+    subscribe(observer: Observer<T>, opts?: {
+        signal?: AbortSignal;
+    }): Subscription;
+    /**
+     * Subscribes to this Observable with callback functions.
+     *
+     * Convenience overload that wraps the callbacks in an Observer object.
+     * See the documentation for the observer-based overload for details
+     * on subscription behavior.
+     *
+     * This method creates a subscription that:
+     * 1. Executes the subscriber function to begin producing values
+     * 2. Delivers those values to the observer's callbacks
+     * 3. Returns a subscription object for cancellation
+     *
+     * **What happens**: Creates subscription → calls observer.start() → executes subscriber function →
+     * stores cleanup → returns subscription for cancellation.
+     *
+     * Subscription Lifecycle:
+     * - Starts immediately and synchronously
+     * - Continues until explicitly cancelled or completed/errored
+     * - Guarantees proper resource cleanup on termination
+     *
+     * **Error handling**: If you provide an error callback, it catches all stream errors.
+     * If not, errors become unhandled Promise rejections.
+     *
+     * **Memory warning**: Infinite Observables need manual `unsubscribe()` or `using` blocks.
+     * If the Observable never calls `complete()` or `error()`,
+     * resources will not be automatically released unless you call
+     * `unsubscribe()` manually.
+     *
+     * For long-lived subscriptions, consider:
+     * 1. Using a `using` block with this subscription
+     * 2. Setting up a timeout or take-until condition
+     * 3. Explicitly calling `unsubscribe()` when no longer needed
+     *
+     * @param next - Function to handle each emitted value
+     * @param error - Optional function to handle errors
+     * @param complete - Optional function to handle completion
+     * @param opts.signal - Optional AbortSignal to close subscription
+     * @returns Subscription object that can be used to cancel the subscription
+     *
+     * @example
+     * ```ts
+     * const subscription = observable.subscribe(
+     *   value => console.log('Received:', value),
+     *   err => console.error('Error:', err),
+     *   () => console.log('Done!')
+     * );
+     * ```
+     *
+     * @example Two ways to subscribe
+     * ```ts
+     * // Observer object (recommended)
+     * obs.subscribe({
+     *   start(sub) { console.log('Started, can call sub.unsubscribe()'); },
+     *   next(val) { console.log('Value:', val); },
+     *   error(err) { console.error('Error:', err); },
+     *   complete() { console.log('Done'); }
+     * });
+     *
+     * // Separate functions
+     * obs.subscribe(
+     *   val => console.log(val),
+     *   err => console.error(err),
+     *   () => console.log('done')
+     * );
+     * ```
+     */
+    subscribe(next: (value: T) => void, error?: (e: unknown) => void, complete?: () => void, opts?: {
+        signal?: AbortSignal;
+    }): 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
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Converts this Observable into an AsyncGenerator with backpressure control.
+     *
+     * **Why use this**: Control buffer size to prevent memory issues when producer is faster than consumer.
+     * Uses ReadableStream internally for efficient buffering.
+     *
+     * 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.
+     *
+     * **Buffer sizing**:
+     * - Small (1-10): Memory-constrained environments, large data items
+     * - Medium (10-100): Most applications, good balance
+     * - Large (100+): High-throughput scenarios, small items
+     *
+     * **Error handling**: Errors are sent through value channel (not stream errors) to ensure
+     * all buffered values are processed before error is thrown.
+     *
+     * @param options - Configuration options for the pull operation
+     * @param options.strategy.highWaterMark - Max items to buffer before applying backpressure (default: 64)
+     * @returns Async generator that yields values and slows the producer when the
+     *          buffer is full.
+     *
+     * @example Memory-efficient processing
+     * ```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));
+     * }
+     *
+     * // Large items, tiny buffer
+     * for await (const item of largeDataStream.pull({ strategy: { highWaterMark: 1 } })) {
+     *   await processLargeItem(item); // Producer pauses when buffer full
+     * }
+     *
+     * // High throughput, large buffer
+     * for await (const event of fastStream.pull({ strategy: { highWaterMark: 1000 } })) {
+     *   await processFast(event);
+     * }
+     * ```
+     */
+    pull(opts?: Parameters<typeof pull>[1] & {
+        ignoreError?: true;
+    }): AsyncGenerator<T>;
+    /**
+     * Returns pulled values while preserving `ObservableError` objects in the
+     * yielded value channel.
+     */
+    pull(opts?: Parameters<typeof pull>[1] & {
+        ignoreError?: false;
+    }): AsyncGenerator<T | ObservableError>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    static readonly from: typeof 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!
+     * ```
+     */
+    static readonly of: typeof 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));
+     * }
+     * ```
+     */
+    static readonly pull: typeof pull;
+    /**
+     * Standard string tag for the object.
+     * Used by Object.prototype.toString.
+     */
+    get [Symbol.toStringTag](): "Observable";
+}
+/**
+ * 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 declare function of<T>(this: unknown, ...items: T[]): Observable<T>;
+/**
+ * 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 declare function from<T>(this: unknown, input: SpecObservable<T> | Iterable<T> | AsyncIterable<T> | PromiseLike<T> | ArrayLike<T>, { throwError }?: {
+    throwError?: boolean | undefined;
+}): Observable<T>;
+/**
+ * Converts an Observable into an AsyncGenerator with backpressure control.
+ *
+ * This function bridges the gap between push-based Observables and
+ * pull-based async iteration, allowing consumers to:
+ * 1. Process values at their own pace
+ * 2. Use standard async iteration patterns (for-await-of)
+ * 3. Control buffering behavior to prevent memory issues
+ *
+ * ## How It Works
+ * Observable → ReadableStream (for buffering) → AsyncGenerator
+ *
+ * **Key features**:
+ * - Automatic backpressure when consumer slower than producer
+ * - Configurable buffer size via highWaterMark
+ * - Proper cleanup on early termination
+ * - Errors sent through value channel to preserve buffered items
+ *
+ * Implementation details:
+ * - Uses ReadableStream as the backpressure mechanism
+ * - Connects the Observable to the stream as a source
+ * - Returns an AsyncGenerator that yields values from the stream
+ * - Handles proper cleanup on early termination
+ *
+ * Instead of using ReadableStream's error mechanism, this implementation uses a special
+ * approach to error handling: errors are wrapped in `ObservableError` objects and
+ * sent through the normal value channel. This ensures all values emitted before an error
+ * are properly processed in order before the error is thrown.
+ *
+ * ## Key Benefits
+ *
+ * 1. **Controlled Processing**: Process values at your own pace rather than being overwhelmed
+ * 2. **Proper Backpressure**: When your consumer is slow, the producer automatically slows down
+ * 3. **Complete Error Handling**: Errors don't cause queued values to be lost
+ * 4. **Resource Safety**: Automatically cleans up subscriptions, even with early termination
+ * 5. **Memory Efficiency**: Controls buffer size to prevent memory issues with fast producers
+ * 6. **Iterator Integration**: Natural integration with other async iteration tools
+ *
+ * @param observable - Source Observable to pull values from
+ * @param options - Configuration options for the ReadableStream
+ * @param options.strategy - Queuing strategy that controls how backpressure is applied
+ * @param options.strategy.highWaterMark - Buffer size before backpressure (default: 64)
+ *
+ * @returns An AsyncGenerator that yields values from the Observable at the consumer's pace
+ *
+ * @example Basic usage with for-await-of loop:
+ * ```ts
+ * const numbers = Observable.of(1, 2, 3, 4, 5);
+ *
+ * // Process each value at your own pace
+ * for await (const num of pull(numbers)) {
+ *   console.log(`Processing ${num}`);
+ *   await someTimeConsumingOperation(num);
+ * }
+ * // Output:
+ * // Processing 1
+ * // Processing 2
+ * // Processing 3
+ * // Processing 4
+ * // Processing 5
+ *
+ * const fast = new Observable(obs => {
+ *   let count = 0;
+ *   const id = setInterval(() => obs.next(count++), 10); // 100/sec
+ *   return () => clearInterval(id);
+ * });
+ *
+ * // Slow consumer with small buffer
+ * for await (const n of pull(fast, { strategy: { highWaterMark: 5 } })) {
+ *   console.log(n);
+ *   await new Promise(r => setTimeout(r, 1000)); // 1/sec - producer slows down
+ * }
+ * ```
+ *
+ * @example Handling errors while ensuring all prior values are processed:
+ * ```ts
+ * // Observable that emits values then errors
+ * const source = new Observable(observer => {
+ *   observer.next(1);
+ *   observer.next(2);
+ *   observer.error(new Error("Something went wrong"));
+ *   // Even though an error occurred, both 1 and 2 will be processed
+ * });
+ *
+ * try {
+ *   for await (const value of pull(source)) {
+ *     console.log(`Got value: ${value}`);
+ *   }
+ * } catch (err) {
+ *   console.error(`Error caught: ${err.message}`);
+ * }
+ *
+ * // Output:
+ * // Got value: 1
+ * // Got value: 2
+ * // Error caught: Something went wrong
+ * ```
+ *
+ * @example Controlling buffer size for memory efficiency:
+ * ```ts
+ * // Create a producer that emits values rapidly
+ * const fastProducer = new Observable(observer => {
+ *   let count = 0;
+ *   const interval = setInterval(() => {
+ *     observer.next(count++);
+ *     if (count > 1000) {
+ *       clearInterval(interval);
+ *       observer.complete();
+ *     }
+ *   }, 1);
+ *   return () => clearInterval(interval);
+ * });
+ *
+ * // Limit buffer to just 5 items to prevent memory issues
+ * for await (const num of pull(fastProducer, {
+ *   strategy: { highWaterMark: 5 }
+ * })) {
+ *   console.log(`Processing ${num}`);
+ *   // Slow consumer - producer will pause when buffer fills
+ *   await new Promise(r => setTimeout(r, 100));
+ * }
+ * ```
+ */
+export declare function pull<T>(this: unknown, observable: SpecObservable<T>, opts?: {
+    strategy?: QueuingStrategy<T | ObservableError>;
+    throwError?: true;
+}): AsyncGenerator<T>;
+/**
+ * Converts an Observable into an AsyncGenerator that yields both values and
+ * wrapped `ObservableError` objects when `throwError` is disabled.
+ */
+export declare function pull<T>(this: unknown, observable: SpecObservable<T>, opts?: {
+    strategy?: QueuingStrategy<T | ObservableError>;
+    throwError?: false;
+}): AsyncGenerator<T | ObservableError>;
+/**
+ * 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 declare function isObservable<T = unknown>(value: unknown): value is Observable<T>;
+/**
+ * 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 declare function isSpecObservable<T = unknown>(value: unknown): value is SpecObservable<T>;
+//# sourceMappingURL=observable.d.ts.map