@reause/rxjs 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hairyf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,461 @@
+import { Dispatch, SetStateAction } from "react";
+import { BehaviorSubject, NextObserver, Observable, ObservableInput, Subject } from "rxjs";
+//#region toObserver/index.d.ts
+/**
+ * A write sink `toObserver` can push emissions into.
+ *
+ * - a ref-like object (`{ current }` — `useRef`'s return value, a
+ *   `RefObject<T>`, or any hand-written `{ current: T }` holder);
+ * - a setter function (`(value: T) => void` — the second tuple member of
+ *   `useState`, or a `useReducer` dispatch).
+ *
+ * Plain values are deliberately NOT accepted: writing to a value is
+ * meaningless, so the target is always something that can receive a write.
+ */
+export type ObserverTarget<T> = {
+  current: T;
+} | ((value: T) => void);
+/**
+ * Sugar function converting a write sink into an RxJS
+ * [Observer](https://rxjs.dev/guide/observer).
+ *
+ * Map from @vueuse/rxjs `toObserver`
+ * (`source/vueuse/packages/rxjs/toObserver/index.ts`). Upstream is
+ * `toObserver<T>(value: Ref<T>): NextObserver<T>` — it returns an observer
+ * whose only method is `next`, which synchronously writes the emission into
+ * `value.value`.
+ *
+ * Adjustment for React: a `useRef` write never schedules a re-render, so a
+ * 1:1 mirror accepting only a Vue-style `Ref` would silently pin consumers to
+ * non-rendering state. The reause version therefore accepts either a
+ * ref-like object (`{ current }`, written through `.current`) or a setter
+ * function (`(value: T) => void`, called directly) — pass a `useState` setter
+ * when the UI must update, or a `useRef` when the latest value only needs to
+ * be read later. Everything else matches upstream: the returned observer has
+ * ONLY `next` (no `error`/`complete`), each emission is written synchronously,
+ * and `toObserver` itself has no side effects.
+ *
+ * The parameter is named `target` (upstream `value`) because it is a write
+ * sink, not a value — there is no Vue-style ref object exposed to users.
+ *
+ * @__NO_SIDE_EFFECTS__
+ *
+ * @example
+ * const [count, setCount] = useState(0)
+ * interval(1000).pipe(take(3)).subscribe(toObserver(setCount)) // re-renders
+ *
+ * @example
+ * const count = useRef(0)
+ * interval(1000).pipe(take(3)).subscribe(toObserver(count)) // no re-render
+ * count.current // latest emission
+ *
+ * @param target - A ref-like `{ current }` object or a setter function.
+ * @returns An RxJS `NextObserver<T>` whose `next` writes into `target`.
+ */
+export declare function toObserver<T>(target: ObserverTarget<T>): NextObserver<T>;
+//#endregion
+//#region useObservable/index.d.ts
+/**
+ * Options for `useObservable`.
+ */
+export interface UseObservableOptions<I> {
+  /**
+   * Error handler forwarded to the `Observable` subscription. Without it RxJS
+   * treats any error in the supplied `Observable` as an "unhandled error": it
+   * is rethrown on a new call stack and reported to `window.onerror` (or
+   * `process.on('error')`), exactly like upstream.
+   */
+  onError?: (err: unknown) => void;
+  /**
+   * The value that should be set if the observable has not emitted.
+   *
+   * @default undefined
+   */
+  initialValue?: I | undefined;
+}
+/**
+ * Return of `useObservable`: a writable `[value, setValue]` tuple (upstream
+ * returns a single `Readonly<Ref<H | I>>`).
+ */
+export type UseObservableReturn<H, I = undefined> = [value: H | I, setValue: Dispatch<SetStateAction<H | I>>];
+/**
+ * Use an RxJS [`Observable`](https://rxjs.dev/guide/observable), return a
+ * controllable state, and automatically unsubscribe from it when the component
+ * is unmounted.
+ *
+ * Map from @vueuse/rxjs `useObservable`
+ * (`source/vueuse/packages/rxjs/useObservable/`): every emission is written
+ * into the state and `options.initialValue` is used until the first one
+ * arrives. A failing `Observable` is forwarded to `options.onError`; without a
+ * handler RxJS reports the error as unhandled instead of swallowing it.
+ *
+ * React divergences:
+ * - upstream returns a `Readonly<Ref<H | I>>`; the React port returns a
+ *   useState-like `[value, setValue]` writable tuple (hairyf/reause#174), so
+ *   the state can also be set from React code — a later emission overwrites it
+ *   again. Setting a new value re-renders.
+ * - upstream's `tryOnScopeDispose` becomes the effect cleanup: the subscription
+ *   is created once when the component mounts and unsubscribed on unmount.
+ * - the `observable` argument is read through a latest-value ref and is **not**
+ *   part of the effect dependencies — a new identity on a later render does not
+ *   re-subscribe, matching upstream (Vue creates the subscription once during
+ *   `setup`). `useObservable(interval(1000), { initialValue: 0 })` therefore
+ *   keeps one live interval across re-renders instead of restarting it on every
+ *   render.
+ * - `initialValue` is the `useState` initial value, so it only applies to the
+ *   first render; `onError` is read when the subscription is created.
+ *
+ * @see https://vueuse.org/rxjs/useObservable/
+ * @example
+ * const [count, setCount] = useObservable(interval(1000), { initialValue: 0 })
+ * // count is 0 until the first emission
+ */
+export declare function useObservable<H, I = undefined>(observable: Observable<H>, options?: UseObservableOptions<I | undefined>): UseObservableReturn<H, I>;
+//#endregion
+//#region useWatchExtractedObservable/index.d.ts
+/**
+ * Register a cleanup callback for the current extractor run. Mirrors Vue's
+ * `watch` cleanup hook: the registered callbacks run before the next
+ * subscription is created and when the hook is torn down (`stop()` /
+ * unmount).
+ */
+export type OnCleanup = (cleanupFn: () => void) => void;
+/**
+ * Extracts the `Observable` to watch from the resolved source value.
+ *
+ * Note the parameter list is `(value, onCleanup)` — upstream's extractor also
+ * receives Vue's `oldValue` between the two; React has no previous-value
+ * tracking for arbitrary sources, so that argument is intentionally absent
+ * (see the JSDoc of {@link useWatchExtractedObservable}).
+ */
+export type WatchExtractedObservableExtractor<Value, E> = (value: NonNullable<Value>, onCleanup: OnCleanup) => Observable<E>;
+export interface UseWatchExtractedObservableOptions {
+  /**
+   * Extra React effect dependencies — the React substitute for Vue's
+   * reactive tracking (same convention as `useAsync`'s `options.deps`,
+   * `packages/core/useAsync/index.tsx`). The resolved source value's
+   * identity is always compared as well, so a new source object re-extracts
+   * even without `deps`. Defaults to `[]`.
+   */
+  deps?: unknown[];
+  /**
+   * Error handler forwarded to the `Observable` subscription. Without it
+   * RxJS treats an error as unhandled and rethrows it asynchronously
+   * (upstream parity).
+   */
+  onError?: (err: unknown) => void;
+  /** Called when the watched `Observable` completes. */
+  onComplete?: () => void;
+}
+export interface UseWatchExtractedObservableReturn {
+  /**
+   * Stop watching: runs the pending `onCleanup` callbacks, unsubscribes the
+   * active subscription and detaches the hook permanently (upstream's
+   * `WatchHandle`). Idempotent — later `deps` / source changes no longer
+   * subscribe.
+   */
+  stop: () => void;
+}
+/**
+ * Watch the values of an RxJS [`Observable`](https://rxjs.dev/guide/observable)
+ * extracted from a source value — React port of VueUse's
+ * `watchExtractedObservable`.
+ *
+ * Map from @vueuse/rxjs `watchExtractedObservable`
+ * (`source/vueuse/packages/rxjs/watchExtractedObservable/`): whenever the
+ * resolved source value changes, the previous subscription is unsubscribed
+ * and `extractor` derives a new `Observable`, whose emissions are forwarded
+ * to `callback`. Automatically unsubscribes when the source changes and when
+ * the component unmounts.
+ *
+ * React adaptation (upstream's Vue reactivity graph is replaced):
+ *
+ * - `value` is a read-only value source and takes a plain
+ *   `Value | null | undefined` (upstream: `T | WatchSource<T>`; resolve a
+ *   React ref or getter at the call site). There
+ *   is no reactive graph: the effect re-runs when the value's
+ *   identity changes **or** when `options.deps` change (upstream re-runs
+ *   whenever the tracked source mutates). A source object mutated **in place**
+ *   therefore does not re-trigger — pass a new identity or list the mutation
+ *   inputs in `deps`. `deps` is the React substitute for Vue's reactive
+ *   tracking, the same convention as `useAsync`'s `options.deps`
+ *   (`packages/core/useAsync/index.tsx`).
+ * - The extractor is `(value, onCleanup) => Observable<E>`: upstream also
+ *   passes Vue's `oldValue` as the second argument, which has no React
+ *   equivalent (React keeps no previous-value tracking) and is dropped.
+ * - Upstream returns a `WatchHandle` function; the React hook returns
+ *   `{ stop }` (§2B object return — no state-like writable pair). `stop` is a
+ *   stable `useCallback`, idempotent, and — like the `WatchHandle` — permanent:
+ *   it tears down the current subscription, runs the pending `onCleanup`
+ *   callbacks, and prevents later `deps` / source changes from subscribing
+ *   again.
+ * - `onCleanup` parity: callbacks registered through the `onCleanup` argument
+ *   are collected per run and invoked before the next subscription is created
+ *   (upstream's Vue `watch` runs the previous cleanup before the watcher body
+ *   unsubscribes) and on unmount / `stop()`. They run before the subscription
+ *   is unsubscribed, mirroring upstream's ordering.
+ * - A `null` / `undefined` resolved value subscribes to nothing and drops any
+ *   previous subscription (upstream parity).
+ * - `extractor`, `callback`, `onError` and `onComplete` are read through
+ *   latest-value refs, so inline identities never re-subscribe; only the
+ *   resolved source value and `deps` do.
+ *
+ * @see https://vueuse.org/watchExtractedObservable/
+ * @example
+ * const player = useRef<AudioPlayer | null>(null)
+ * const [progress, setProgress] = useState(0)
+ *
+ * useWatchExtractedObservable(player, p => p.progress$, (percentage) => {
+ *   setProgress(percentage * 100)
+ * }, { onError: err => console.error(err) })
+ */
+export declare function useWatchExtractedObservable<Value, E>(value: Value | null | undefined, extractor: WatchExtractedObservableExtractor<Value, E>, callback: (snapshot: E) => void, options?: UseWatchExtractedObservableOptions): UseWatchExtractedObservableReturn;
+//#endregion
+//#region useExtractedObservable/index.d.ts
+/**
+ * Options for `useExtractedObservable`.
+ *
+ * Upstream `UseExtractedObservableOptions` extends `UseObservableOptions`
+ * with `onComplete`; the React port reuses the same option names (`onError`,
+ * `initialValue`) from `useObservable` and adds `deps`, the substitute for
+ * Vue's reactive tracking (see {@link useExtractedObservable}).
+ */
+export interface UseExtractedObservableOptions<E> extends UseObservableOptions<E> {
+  /** Called when the extracted `Observable` completes. */
+  onComplete?: () => void;
+  /**
+   * Extra React effect dependencies — the React substitute for Vue's
+   * reactive tracking (same convention as `useAsync`'s `options.deps`,
+   * `packages/core/useAsync/index.tsx`). The resolved source value's identity
+   * is always compared as well, so a new source object re-extracts even
+   * without `deps`. Defaults to `[]`.
+   */
+  deps?: unknown[];
+}
+/**
+ * Extracts the `Observable` to subscribe to from the resolved source value.
+ *
+ * Note the parameter list is `(value, onCleanup)` — upstream's extractor also
+ * receives Vue's `oldValue` between the two; React has no previous-value
+ * tracking for arbitrary sources, so that argument is intentionally absent
+ * (see the JSDoc of {@link useExtractedObservable}). The signature is shared
+ * with the sibling `useWatchExtractedObservable`
+ * (`packages/rxjs/useWatchExtractedObservable/index.tsx`).
+ */
+export type ExtractedObservableExtractor<Value, E> = (value: NonNullable<Value>, onCleanup: OnCleanup) => Observable<E>;
+/**
+ * Use an RxJS [`Observable`](https://rxjs.dev/guide/observable) as extracted
+ * from one or more hooks, and automatically unsubscribe from it when the
+ * component is unmounted.
+ *
+ * Map from @vueuse/rxjs `useExtractedObservable`
+ * (`source/vueuse/packages/rxjs/useExtractedObservable/`): whenever the
+ * resolved source value changes, the previous subscription is unsubscribed
+ * and `extractor` derives a new `Observable` from the new value, whose
+ * emissions become the hook's value. Unsubscribing happens both on a source
+ * change and on unmount.
+ *
+ * React adaptation (upstream's Vue reactivity graph is replaced):
+ *
+ * - `value` is a read-only value source and takes a plain
+ *   `Value | null | undefined` (upstream: `T | WatchSource<T>`, i.e. a
+ *   reactive object, an array of sources or a getter). Resolve a React ref or
+ *   getter at the call site; a list of sources is passed as a plain array and
+ *   re-extracts when a new array identity arrives. There is no reactive graph:
+ *   the effect re-runs when the value's identity changes **or** when
+ *   `options.deps` change (upstream re-runs whenever any tracked source
+ *   mutates), so a source object mutated **in place** needs a new identity or
+ *   the mutation inputs listed in `deps`.
+ * - the extractor is `(value, onCleanup) => Observable<E>`: upstream also
+ *   passes Vue's `oldValue` as the second argument, which has no React
+ *   equivalent (React keeps no previous-value tracking) and is dropped.
+ * - upstream returns a `DeepReadonly<ShallowRef<E>>`; the React port returns
+ *   the value directly (a readonly ref holds no writable value, so the
+ *   structure is mirrored — §2 return rules). `initialValue` narrows the
+ *   returned type to `E | I` (`I` being the `initialValue` type and
+ *   defaulting to `undefined`), the same trick as `useObservable`.
+ * - upstream's `watch` options (`immediate` / `deep` / `flush`) are dropped:
+ *   the effect always extracts on mount (`immediate: true`, upstream's
+ *   default) and re-extracts on identity / `deps` changes — React has no
+ *   flush scheduler to configure. Pass `initialValue` to seed the value
+ *   before the first extraction settles.
+ * - `initialValue` is the `useState` initial value, so it only applies to the
+ *   first render — a later source change keeps the last emitted value
+ *   (upstream's `obsRef` is never reset either), and a nullish source
+ *   subscribes to nothing and drops the previous subscription.
+ * - `onCleanup` parity: callbacks registered through the `onCleanup` argument
+ *   are collected per run and invoked before the next subscription is created,
+ *   before the previous subscription is unsubscribed (upstream's Vue `watch`
+ *   runs the previous cleanup before the watcher body), and on unmount.
+ * - `extractor`, `onError` and `onComplete` are read through latest-value refs,
+ *   so inline identities never re-subscribe; only the resolved source value
+ *   and `deps` do.
+ * - the option values are handed to the observer directly, so an absent
+ *   `onError` leaves the error slot `undefined` and RxJS reports the error as
+ *   unhandled instead of swallowing it (upstream parity).
+ * - SSR-safe: nothing touches `window` / `document`, and the subscription only
+ *   exists inside the mount effect.
+ *
+ * @see https://vueuse.org/rxjs/useExtractedObservable/
+ * @example
+ * const [start, setStart] = useState(0)
+ * const count = useExtractedObservable(start, start => interval(1000).pipe(
+ *   startWith(start),
+ *   scan((total, next) => next + total),
+ * ), { initialValue: 0 })
+ * // count is 0 until the first emission, then keeps accumulating
+ */
+export declare function useExtractedObservable<Value, E, I = undefined>(value: Value | null | undefined, extractor: ExtractedObservableExtractor<Value, E>, options?: UseExtractedObservableOptions<E | I>): E | I;
+//#endregion
+//#region useFrom/index.d.ts
+/**
+ * Create an [`Observable`](https://rxjs.dev/guide/observable) from either an
+ * rxjs `ObservableInput` (forwarded to RxJS's
+ * [`from()`](https://rxjs.dev/api/index/function/from) unchanged) or a plain
+ * value that re-emits whenever it changes across renders.
+ *
+ * Map from @vueuse/rxjs `from`
+ * (`source/vueuse/packages/rxjs/from/`): upstream branches on Vue's `isRef`
+ * and `watch`es the ref; React has no reactive refs, so the port branches on
+ * observable-/promise-likeness and pushes plain values through an internal
+ * effect instead.
+ *
+ * Branch discriminator (runtime):
+ * - a value with a `subscribe` function (Observable-like) or a `then` function
+ *   (Promise-like) is passed straight to rxjs `from(value)` — upstream parity.
+ * - any other plain value is wrapped in a `BehaviorSubject` seeded with the
+ *   current render value: subscribing immediately receives the current value
+ *   (the mapped `immediate` semantics), and the Observable re-emits whenever
+ *   the value changes across renders.
+ *
+ * React divergences:
+ * - upstream's `Ref<T>` branch becomes the plain-value re-emit branch. The
+ *   subject and its `asObservable()` wrapper are held in refs, so the returned
+ *   Observable keeps a stable identity across renders and downstream
+ *   subscriptions are not rebuilt by re-renders.
+ * - upstream's `WatchOptions` (`immediate` / `deep` / `flush`) is dropped —
+ *   React has no Vue `watch`. `immediate` is covered by the seeded
+ *   `BehaviorSubject` (subscribing receives the current value immediately);
+ *   `deep` / `flush` are not mapped — handle extra control at the call site
+ *   with rxjs operators or effect dependencies.
+ * - the value source is a plain `T` only — never a getter, `State<T>` or
+ *   `RefOrValue` (AGENTS.md §2).
+ * - on unmount the subject is completed: subscriptions stop and no further
+ *   emissions are delivered. In dev, React StrictMode remounts effects and
+ *   runs that cleanup, which completes the subject; the mount effect detects
+ *   the stopped subject and reseeds it, so re-emission survives the simulated
+ *   unmount/remount cycle.
+ *
+ * @see https://vueuse.org/rxjs/from/
+ * @example
+ * const [count, setCount] = useState(0)
+ * const count$ = useFrom(count)
+ * // count$ emits 0 immediately; setCount(1) re-emits 1
+ * @example
+ * const values$ = useFrom(of(1, 2)) // ObservableInput: rxjs from() passthrough
+ */
+export declare function useFrom<T>(value: ObservableInput<T> | T): Observable<T>;
+//#endregion
+//#region useSubject/index.d.ts
+/**
+ * Options for `useSubject`.
+ *
+ * Upstream `UseSubjectOptions` is `useObservable`'s options minus
+ * `initialValue`: a `BehaviorSubject` seeds the state with its own current
+ * value and a plain `Subject` starts out `undefined`, so there is nothing for
+ * the caller to supply.
+ */
+export type UseSubjectOptions<I = undefined> = Omit<UseObservableOptions<I>, 'initialValue'>;
+/**
+ * Return of `useSubject`: a writable `[value, setValue]` tuple (upstream
+ * returns a single `Ref<H>` / `Ref<H | undefined>`).
+ */
+export type UseSubjectReturn<H> = [value: H, setValue: Dispatch<SetStateAction<H>>];
+/**
+ * Bind an RxJS [`Subject`](https://rxjs.dev/guide/subject) to a controllable
+ * state and propagate value changes both ways.
+ *
+ * Map from @vueuse/rxjs `useSubject`
+ * (`source/vueuse/packages/rxjs/useSubject/`): the state is initialized from a
+ * `BehaviorSubject`'s current value (or `undefined` for a plain `Subject`),
+ * every emission is written into the state, and writing through the returned
+ * setter is pushed back into the subject.
+ *
+ * React divergences:
+ * - upstream returns a `Ref<H>` / `Ref<H | undefined>` that the caller mutates
+ *   directly; the React port returns a `useState`-like writable
+ *   `[value, setValue]` tuple (hairyf/reause#218).
+ * - `setValue` calls `subject.next(...)` — it does **not** set React state
+ *   directly. Upstream keeps two writable places (`value.value` and the
+ *   subject, bridged by `watch`); here the subject is the single source of
+ *   truth, so a write is observable by every other subscriber of the subject
+ *   and the exposed value follows the emission that comes back through the
+ *   subscription. Unlike upstream's `watch` — which skips an unchanged
+ *   primitive — the write is forwarded unconditionally, so `setValue(current)`
+ *   still calls `subject.next(current)` and other subscribers see it
+ *   (hairyf/reause#218).
+ * - the setter accepts a functional update (`useState` parity, hairyf/reause#174);
+ *   it is resolved against the latest value seen by the hook, so two functional
+ *   updates in the same tick compose instead of both reading the same stale
+ *   value.
+ * - upstream's `tryOnScopeDispose` becomes the effect cleanup: the subscription
+ *   is created once when the component mounts and unsubscribed on unmount.
+ * - the `subject` argument is deliberately **not** an effect dependency — a new
+ *   identity on a later render neither re-subscribes (Vue's `tryOnScopeDispose`
+ *   also registers exactly once, during `setup`) nor re-targets `setValue`,
+ *   which keeps writing into the subject the hook is subscribed to.
+ * - `onError` is read when the subscription is created.
+ * - SSR-safe: nothing touches `window` / `document`, and the subscription is
+ *   only created in the mount effect.
+ *
+ * @see https://vueuse.org/rxjs/useSubject/
+ * @example
+ * const subject = new BehaviorSubject('initial')
+ * const [value, setValue] = useSubject(subject)
+ * // value is 'initial'; setValue('next') pushes 'next' into the subject
+ */
+export declare function useSubject<H>(subject: BehaviorSubject<H>, options?: UseSubjectOptions): UseSubjectReturn<H>;
+export declare function useSubject<H>(subject: Subject<H>, options?: UseSubjectOptions): UseSubjectReturn<H | undefined>;
+//#endregion
+//#region useSubscription/index.d.ts
+/**
+ * Anything with an RxJS-style `unsubscribe` — upstream types the argument as
+ * `Unsubscribable`, which is written structurally here because `rxjs@6` (the
+ * version this package resolves, `rxjs` stays a `>=6.0.0` peer) keeps that
+ * interface in `rxjs/internal/types` instead of re-exporting it from the
+ * package root. A structural type accepts `rxjs@6`'s and `rxjs@7`'s
+ * `Unsubscribable` / `Subscription` alike and keeps the peer range honest.
+ */
+export interface UnsubscribableLike {
+  unsubscribe: () => void;
+}
+/**
+ * Use an RxJS [`Subscription`](https://rxjs.dev/guide/subscription) without
+ * worrying about unsubscribing from it or creating memory leaks.
+ *
+ * Map from @vueuse/rxjs `useSubscription`
+ * (`source/vueuse/packages/rxjs/useSubscription/`): the subscription is handed
+ * to the hook and torn down automatically when the component unmounts, so the
+ * call site never needs its own cleanup.
+ *
+ * React divergences:
+ * - upstream's `tryOnScopeDispose(() => subscription.unsubscribe())` becomes
+ *   the effect cleanup: the subscription lives from mount until unmount. There
+ *   is no state, so the hook returns nothing (upstream parity).
+ * - like `useObservable` (`packages/rxjs/useObservable/index.tsx`), the
+ *   argument is deliberately **not** an effect dependency — a new `subscription`
+ *   identity on a later render does not re-subscribe (Vue's
+ *   `tryOnScopeDispose` also registers exactly once, during `setup`). Create
+ *   the subscription with `useState`'s lazy initializer, `useRef` or a module
+ *   scope when the surrounding component re-renders.
+ * - SSR-safe: nothing touches `window` / `document`, and the cleanup only runs
+ *   on real unmount.
+ *
+ * @see https://vueuse.org/rxjs/useSubscription/
+ * @example
+ * const [count, setCount] = useState(0)
+ * useSubscription(interval(1000).subscribe(() => setCount(c => c + 1)))
+ * // unsubscribes when the component unmounts
+ */
+export declare function useSubscription(subscription: UnsubscribableLike): void;
+//#endregion