@reause/rxjs 0.1.2

package/dist/index.js

@@ -0,0 +1,471 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { BehaviorSubject, from } from "rxjs";
+//#region toObserver/index.tsx
+/**
+* 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`.
+*/
+function toObserver(target) {
+	if (typeof target === "function") return { next: (val) => {
+		target(val);
+	} };
+	return { next: (val) => {
+		target.current = val;
+	} };
+}
+//#endregion
+//#region useExtractedObservable/index.tsx
+/**
+* Shared empty dependency array — a stable identity so the default `deps`
+* never re-creates the effect dependency list.
+*/
+const EMPTY_DEPS$1 = [];
+/**
+* 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
+*/
+function useExtractedObservable(value, extractor, options) {
+	const { initialValue, onError, onComplete, deps = EMPTY_DEPS$1 } = options !== null && options !== void 0 ? options : {};
+	const [state, setState] = useState(initialValue);
+	const resolvedValue = value;
+	const extractorRef = useRef(extractor);
+	extractorRef.current = extractor;
+	const onErrorRef = useRef(onError);
+	onErrorRef.current = onError;
+	const onCompleteRef = useRef(onComplete);
+	onCompleteRef.current = onComplete;
+	const effectDeps = [resolvedValue, ...deps];
+	useEffect(() => {
+		if (resolvedValue === null || resolvedValue === void 0) return;
+		const cleanups = [];
+		let closed = false;
+		const onCleanup = (cleanupFn) => {
+			cleanups.push(cleanupFn);
+		};
+		const subscription = extractorRef.current(resolvedValue, onCleanup).subscribe({
+			next: (val) => setState(() => val),
+			error: onErrorRef.current,
+			complete: onCompleteRef.current
+		});
+		return () => {
+			if (closed) return;
+			closed = true;
+			cleanups.splice(0, cleanups.length).forEach((cleanupFn) => cleanupFn());
+			subscription.unsubscribe();
+		};
+	}, effectDeps);
+	return state;
+}
+//#endregion
+//#region useFrom/index.tsx
+/**
+* Observable-like: an object or function exposing a `subscribe` method (an
+* rxjs `Observable`, `Subject`, `BehaviorSubject`, ...).
+*/
+function isObservableLike(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.subscribe === "function";
+}
+/**
+* Promise-like: an object or function exposing a `then` method.
+*/
+function isPromiseLike(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+/**
+* 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
+*/
+function useFrom(value) {
+	const subjectRef = useRef(null);
+	if (subjectRef.current === null) subjectRef.current = new BehaviorSubject(value);
+	const subject = subjectRef.current;
+	const observableRef = useRef(null);
+	if (observableRef.current === null) observableRef.current = subject.asObservable();
+	const observable = observableRef.current;
+	const valueRef = useRef(value);
+	valueRef.current = value;
+	const prevValueRef = useRef(value);
+	useEffect(() => {
+		const subject = subjectRef.current;
+		if (subject === null) return;
+		if (subject.isStopped) {
+			const nextSubject = new BehaviorSubject(valueRef.current);
+			subjectRef.current = nextSubject;
+			observableRef.current = nextSubject.asObservable();
+			return () => nextSubject.complete();
+		}
+		return () => subject.complete();
+	}, []);
+	useEffect(() => {
+		const subject = subjectRef.current;
+		if (subject === null || subject.isStopped) return;
+		const previous = prevValueRef.current;
+		prevValueRef.current = value;
+		if (!Object.is(previous, value)) subject.next(value);
+	}, [value]);
+	if (isObservableLike(value) || isPromiseLike(value)) return from(value);
+	return observable;
+}
+//#endregion
+//#region useObservable/index.tsx
+/**
+* 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
+*/
+function useObservable(observable, options) {
+	const { initialValue, onError } = options !== null && options !== void 0 ? options : {};
+	const [value, setValue] = useState(initialValue);
+	const observableRef = useRef(observable);
+	observableRef.current = observable;
+	const onErrorRef = useRef(onError);
+	onErrorRef.current = onError;
+	useEffect(() => {
+		const subscription = observableRef.current.subscribe({
+			next: (val) => setValue(val),
+			error: onErrorRef.current
+		});
+		return () => subscription.unsubscribe();
+	}, []);
+	return [value, setValue];
+}
+//#endregion
+//#region useSubject/index.tsx
+/**
+* Runtime counterpart of the `BehaviorSubject` overload: only a
+* `BehaviorSubject` replays a current value, so only it can seed the state.
+*/
+function isBehaviorSubject(subject) {
+	return subject instanceof BehaviorSubject;
+}
+function useSubject(subject, options) {
+	const { onError } = options !== null && options !== void 0 ? options : {};
+	const [value, setValue] = useState(() => isBehaviorSubject(subject) ? subject.value : void 0);
+	const valueRef = useRef(value);
+	const onErrorRef = useRef(onError);
+	onErrorRef.current = onError;
+	const subjectRef = useRef(subject);
+	const writeValue = useCallback((next) => {
+		const nextValue = typeof next === "function" ? next(valueRef.current) : next;
+		valueRef.current = nextValue;
+		subjectRef.current.next(nextValue);
+	}, []);
+	useEffect(() => {
+		const subscription = subjectRef.current.subscribe({
+			next: (val) => {
+				valueRef.current = val;
+				setValue(val);
+			},
+			error: onErrorRef.current
+		});
+		return () => subscription.unsubscribe();
+	}, []);
+	return [value, writeValue];
+}
+//#endregion
+//#region useSubscription/index.tsx
+/**
+* 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
+*/
+function useSubscription(subscription) {
+	useEffect(() => {
+		return () => subscription.unsubscribe();
+	}, []);
+}
+//#endregion
+//#region useWatchExtractedObservable/index.tsx
+/**
+* Shared empty dependency array — a stable identity so the default `deps`
+* never re-creates the effect dependency list.
+*/
+const EMPTY_DEPS = [];
+/**
+* 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) })
+*/
+function useWatchExtractedObservable(value, extractor, callback, options) {
+	const { deps = EMPTY_DEPS, onError, onComplete } = options !== null && options !== void 0 ? options : {};
+	const resolvedValue = value;
+	const extractorRef = useRef(extractor);
+	extractorRef.current = extractor;
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	const onErrorRef = useRef(onError);
+	onErrorRef.current = onError;
+	const onCompleteRef = useRef(onComplete);
+	onCompleteRef.current = onComplete;
+	const subscriptionRef = useRef(null);
+	const teardownRef = useRef(null);
+	const stoppedRef = useRef(false);
+	const stop = useCallback(() => {
+		var _teardownRef$current;
+		stoppedRef.current = true;
+		(_teardownRef$current = teardownRef.current) === null || _teardownRef$current === void 0 || _teardownRef$current.call(teardownRef);
+		teardownRef.current = null;
+	}, []);
+	const effectDeps = [resolvedValue, ...deps];
+	useEffect(() => {
+		if (stoppedRef.current) return;
+		if (resolvedValue === null || resolvedValue === void 0) return;
+		const cleanups = [];
+		let closed = false;
+		const onCleanup = (cleanupFn) => {
+			cleanups.push(cleanupFn);
+		};
+		const subscription = extractorRef.current(resolvedValue, onCleanup).subscribe({
+			next: (snapshot) => callbackRef.current(snapshot),
+			error: onErrorRef.current,
+			complete: onCompleteRef.current
+		});
+		subscriptionRef.current = subscription;
+		const teardown = () => {
+			if (closed) return;
+			closed = true;
+			cleanups.splice(0, cleanups.length).forEach((cleanupFn) => cleanupFn());
+			subscription.unsubscribe();
+			if (subscriptionRef.current === subscription) subscriptionRef.current = null;
+		};
+		teardownRef.current = teardown;
+		return () => {
+			teardown();
+			if (teardownRef.current === teardown) teardownRef.current = null;
+		};
+	}, effectDeps);
+	return { stop };
+}
+//#endregion
+export { toObserver, useExtractedObservable, useFrom, useObservable, useSubject, useSubscription, useWatchExtractedObservable };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@reause/rxjs",
+  "type": "module",
+  "version": "0.1.2",
+  "description": "RxJS reactive functions for reause — React port of @vueuse/rxjs",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "unpkg": "./dist/index.iife.min.js",
+  "jsdelivr": "./dist/index.iife.min.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "rxjs": ">=6.0.0"
+  },
+  "dependencies": {
+    "@reause/shared": "0.1.2"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}