@octanejs/rxjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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/README.md

@@ -0,0 +1,34 @@
+# @octanejs/rxjs
+
+[React-RxJS](https://github.com/re-rxjs/react-rxjs) bindings for
+[octane](https://github.com/octanejs/octane).
+
+The package reuses RxJS and `@rx-state/core`, replacing only the React hook and
+component layer. Most applications can migrate by changing imports:
+
+```tsx
+import { bind } from '@octanejs/rxjs';
+import { interval } from 'rxjs';
+
+const [useSeconds] = bind(interval(1000), 0);
+
+function Clock() @{
+  const seconds = useSeconds();
+  <output>{seconds as any}</output>
+}
+```
+
+The root entry exports the core binding API. `@octanejs/rxjs/utils` mirrors the
+complete framework-neutral `@react-rxjs/utils` surface.
+
+## Intentional differences
+
+- A `StateObservable` is not itself a renderable JSX node. Render its value with
+  `useStateObservable` or the hook returned by `bind`.
+- `@react-rxjs/dom` is not ported. Its only API wraps ReactDOM's legacy
+  `unstable_batchedUpdates`; octane batches observable updates natively.
+- A state observable without a default value must be read inside `Subscribe`,
+  matching React-RxJS's subscription ownership contract.
+
+The implementation is based on upstream commit
+`330f4c329f635c577e39655bd46c0d80a13f3a41`.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@octanejs/rxjs",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "RxJS bindings for the octane renderer, based on React-RxJS.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/rxjs"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "status.json"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./utils": "./src/utils/index.ts"
+  },
+  "dependencies": {
+    "@rx-state/core": "0.1.4"
+  },
+  "peerDependencies": {
+    "rxjs": "^7.8.2",
+    "octane": "0.1.21"
+  },
+  "devDependencies": {
+    "@react-rxjs/core": "0.10.8",
+    "@react-rxjs/utils": "0.9.7",
+    "@tsrx/react": "^0.2.56",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "rxjs": "^7.8.2",
+    "vitest": "^4.1.10",
+    "octane": "0.1.21"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/Subscribe.tsrx

@@ -0,0 +1,87 @@
+import { Suspense, useEffect, useRef } from 'octane';
+import { liftSuspense } from '@rx-state/core';
+import { Subscription } from 'rxjs';
+import type { OctaneNode } from 'octane';
+import type { StateObservable } from '@rx-state/core';
+import type { Observable } from 'rxjs';
+import { SubscriptionContext } from './context.ts';
+
+type Props = {
+	children?: OctaneNode;
+	source$?: Observable<unknown>;
+	fallback?: OctaneNode;
+};
+
+const EMPTY = Symbol('empty');
+
+export function Subscribe(props: Props) @{
+	const owner = useRef<
+		| {
+				children: Subscription;
+				source: Observable<unknown> | undefined;
+				sourceSubscription: Subscription | null;
+				add: (source: StateObservable<unknown>) => void;
+		  }
+		| null
+	>(null);
+
+	if (!owner.current) {
+		const children = new Subscription();
+		owner.current = {
+			children,
+			source: undefined,
+			sourceSubscription: null,
+			add(source) {
+				let synchronousError: unknown = EMPTY;
+				let synchronous = true;
+				children.add(
+					liftSuspense()(source).subscribe({
+						error(error) {
+							if (synchronous) synchronousError = error;
+						},
+					}),
+				);
+				synchronous = false;
+				if (synchronousError !== EMPTY) throw synchronousError;
+			},
+		};
+	}
+
+	if (owner.current.source !== props.source$) {
+		owner.current.sourceSubscription?.unsubscribe();
+		owner.current.source = props.source$;
+		owner.current.sourceSubscription = props.source$
+			? liftSuspense()(props.source$).subscribe({
+					// The owned source subscription exists only to keep the source
+					// active. Consumers surface observable errors through their own
+					// subscriptions, so do not also report them as unhandled here.
+					error() {},
+				})
+			: null;
+	}
+
+	useEffect(
+		() => () => {
+			owner.current?.sourceSubscription?.unsubscribe();
+			owner.current?.children.unsubscribe();
+			owner.current = null;
+		},
+		[],
+	);
+
+	@if (props.fallback === undefined) {
+		<SubscriptionContext.Provider
+			value={owner.current.add}
+		>{props.children}</SubscriptionContext.Provider>
+	} @else {
+		<Suspense fallback={props.fallback}>
+			<SubscriptionContext.Provider
+				value={owner.current.add}
+			>{props.children}</SubscriptionContext.Provider>
+		</Suspense>
+	}
+}
+
+export function RemoveSubscribe(props: { children?: OctaneNode }) @{
+	<SubscriptionContext.Provider value={null}>{props.children}</SubscriptionContext.Provider>
+}

package/src/bind.ts

@@ -0,0 +1,41 @@
+import { state } from '@rx-state/core';
+import type { DefaultedStateObservable, StateObservable, SUSPENSE } from '@rx-state/core';
+import type { Observable } from 'rxjs';
+import { splitSlot } from './internal.ts';
+import { useStateObservable } from './useStateObservable.ts';
+
+type AddStopArg<A extends unknown[]> = number extends A['length']
+	? A
+	: [...args: A, _stop?: undefined];
+type Value<T> = Exclude<T, typeof SUSPENSE>;
+
+export function bind<T>(observable: Observable<T>): [() => Value<T>, StateObservable<T>];
+export function bind<T>(
+	observable: Observable<T>,
+	defaultValue: T,
+): [() => Value<T>, DefaultedStateObservable<T>];
+export function bind<A extends unknown[], T>(
+	factory: (...args: A) => Observable<T>,
+): [(...args: AddStopArg<A>) => Value<T>, (...args: AddStopArg<A>) => StateObservable<T>];
+export function bind<A extends unknown[], T>(
+	factory: (...args: A) => Observable<T>,
+	defaultValue: T | ((...args: A) => T),
+): [(...args: AddStopArg<A>) => Value<T>, (...args: AddStopArg<A>) => DefaultedStateObservable<T>];
+export function bind(source: unknown, defaultValue?: unknown): readonly [unknown, unknown] {
+	const hasDefault = arguments.length > 1;
+	if (typeof source === 'function') {
+		const bound = hasDefault
+			? state(source as (...args: unknown[]) => Observable<unknown>, defaultValue)
+			: state(source as (...args: unknown[]) => Observable<unknown>);
+		const useBound = (...runtimeArgs: unknown[]) => {
+			const [args, slot] = splitSlot(runtimeArgs);
+			return useStateObservable(bound(...args), slot, args);
+		};
+		return [useBound, bound] as const;
+	}
+	const bound = hasDefault
+		? state(source as Observable<unknown>, defaultValue)
+		: state(source as Observable<unknown>);
+	const useBound = (slot?: symbol) => useStateObservable(bound, slot);
+	return [useBound, bound] as const;
+}

package/src/context.ts

@@ -0,0 +1,6 @@
+import { createContext, useContext } from 'octane';
+import type { StateObservable } from '@rx-state/core';
+
+export type SubscribeState = (source: StateObservable<unknown>) => void;
+export const SubscriptionContext = createContext<SubscribeState | null>(null);
+export const useSubscription = () => useContext(SubscriptionContext);

package/src/index.ts

@@ -0,0 +1,16 @@
+export type {
+	AddStopArg,
+	DefaultedStateObservable,
+	EmptyObservableError,
+	NoSubscribersError,
+	PipeState,
+	StateObservable,
+	StatePromise,
+	WithDefaultOperator,
+} from '@rx-state/core';
+export { liftSuspense, sinkSuspense, SUSPENSE, withDefault } from '@rx-state/core';
+export { bind } from './bind.ts';
+export { shareLatest } from './shareLatest.ts';
+export { state } from './state.ts';
+export { RemoveSubscribe, Subscribe } from './Subscribe.tsrx';
+export { useStateObservable } from './useStateObservable.ts';

package/src/internal.ts

@@ -0,0 +1,23 @@
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) bareTagCache.set(tag, (bare = Symbol.for(`:rxjs:${tag}`)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let derived = byTag.get(tag);
+	if (derived === undefined) {
+		byTag.set(tag, (derived = Symbol.for(`${slot.description ?? ''}:rxjs:${tag}`)));
+	}
+	return derived;
+}
+
+export function splitSlot(args: unknown[]): [unknown[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? tail : undefined;
+	return [slot === undefined ? args : args.slice(0, -1), slot];
+}

package/src/shareLatest.ts

@@ -0,0 +1,10 @@
+import { ReplaySubject, share } from 'rxjs';
+import type { MonoTypeOperatorFunction } from 'rxjs';
+
+export const shareLatest = <T>(): MonoTypeOperatorFunction<T> =>
+	share<T>({
+		connector: () => new ReplaySubject<T>(1),
+		resetOnError: true,
+		resetOnComplete: true,
+		resetOnRefCountZero: true,
+	});

package/src/state.ts

@@ -0,0 +1 @@
+export { state } from '@rx-state/core';

package/src/useStateObservable.ts

@@ -0,0 +1,88 @@
+import { liftSuspense, NoSubscribersError, StatePromise } from '@rx-state/core';
+import { useReducer, useRef, useSyncExternalStore } from 'octane';
+import type { DefaultedStateObservable, StateObservable, SUSPENSE } from '@rx-state/core';
+import { useSubscription } from './context.ts';
+import { subSlot } from './internal.ts';
+
+type Value<T> = Exclude<T, typeof SUSPENSE>;
+type VoidCallback = () => void;
+
+interface ObservableRef<T> {
+	source: StateObservable<T>;
+	subscribe: (callback: VoidCallback) => VoidCallback;
+	getSnapshot: () => Value<T>;
+}
+
+export function useStateObservable<T>(
+	source: StateObservable<T>,
+	slot?: symbol,
+	identity?: readonly unknown[],
+): Value<T> {
+	const subscription = useSubscription();
+	const identityRef = useRef<readonly unknown[] | StateObservable<T>>(
+		identity ?? source,
+		subSlot(slot, 'identity'),
+	);
+	const previousIdentity = identityRef.current;
+	if (
+		identity &&
+		(!Array.isArray(previousIdentity) ||
+			previousIdentity.length !== identity.length ||
+			identity.some((value, index) => (previousIdentity as readonly unknown[])[index] !== value))
+	) {
+		identityRef.current = identity;
+	}
+	const sourceIdentity = identityRef.current;
+	const errorRef = useRef<
+		{ source: readonly unknown[] | StateObservable<T>; error: unknown } | undefined
+	>(undefined, subSlot(slot, 'error'));
+	const [, rerender] = useReducer((count: number) => count + 1, 0, subSlot(slot, 'error-update'));
+	const callbackRef = useRef<ObservableRef<T> | undefined>(undefined, subSlot(slot, 'callbacks'));
+
+	if (!callbackRef.current) {
+		const getSnapshot = () => {
+			const current = callbackRef.current!.source as DefaultedStateObservable<T>;
+			if (!current.getRefCount() && !current.getDefaultValue) {
+				if (!subscription) throw new Error('Missing Subscribe!');
+				subscription(current);
+			}
+			const value = current.getValue();
+			if (value instanceof StatePromise) {
+				throw value.catch((error) => {
+					if (error instanceof NoSubscribersError) return error;
+					throw error;
+				});
+			}
+			return value as Value<T>;
+		};
+		callbackRef.current = {
+			source: null as unknown as StateObservable<T>,
+			subscribe: () => () => {},
+			getSnapshot,
+		};
+	}
+
+	const ref = callbackRef.current;
+	if (ref.source !== source) {
+		ref.source = source;
+		ref.subscribe = (notify) => {
+			const active = liftSuspense()(source).subscribe({
+				next: notify,
+				error: (error) => {
+					errorRef.current = { source: sourceIdentity, error };
+					rerender(0);
+				},
+			});
+			return () => active.unsubscribe();
+		};
+	}
+
+	const value = useSyncExternalStore(
+		ref.subscribe,
+		ref.getSnapshot,
+		ref.getSnapshot,
+		subSlot(slot, 'store'),
+	);
+	if (errorRef.current?.source === sourceIdentity) throw errorRef.current.error;
+	return value;
+}

package/src/utils/combineKeys.ts

@@ -0,0 +1,116 @@
+import { KeyChanges } from './partitionByKey';
+import { Observable, Subscription } from 'rxjs';
+
+export interface MapWithChanges<K, V> extends Map<K, V> {
+	changes: Set<K>;
+}
+
+/**
+ * Creates a stream that combines the result of the streams from each key of the input stream.
+ *
+ * @param keys$ Stream of the list of keys to subscribe to.
+ * @param getInner$ Function that returns the stream for each key.
+ * @returns An stream with a map containing the latest value from the stream of each key.
+ */
+export const combineKeys = <K, T>(
+	keys$: Observable<Iterable<K> | KeyChanges<K>>,
+	getInner$: (key: K) => Observable<T>,
+): Observable<MapWithChanges<K, T>> =>
+	new Observable((observer) => {
+		const innerSubscriptions = new Map<K, Subscription>();
+		let changes = new Set<K>();
+		const currentValue = new Map<K, T>();
+		let updatingSource = false;
+		let isPristine = true;
+
+		const next = () => {
+			if (!updatingSource) {
+				const result = Object.assign(currentValue, {
+					changes,
+				});
+				changes = new Set<K>();
+				isPristine = false;
+				observer.next(result);
+			}
+		};
+
+		const subscription = keys$.subscribe(
+			(nextKeysArr) => {
+				updatingSource = true;
+
+				const keys = new Set(inputIsKeyChanges(nextKeysArr) ? nextKeysArr.keys : nextKeysArr);
+
+				if (inputIsKeyChanges(nextKeysArr)) {
+					if (nextKeysArr.type === 'remove') {
+						keys.forEach((key) => {
+							const sub = innerSubscriptions.get(key);
+							if (!sub) return;
+							sub.unsubscribe();
+							innerSubscriptions.delete(key);
+							if (currentValue.has(key)) {
+								changes.add(key);
+								currentValue.delete(key);
+							}
+						});
+						// Keys after this block is the list of keys to add. Clear it.
+						keys.clear();
+					}
+				} else {
+					innerSubscriptions.forEach((sub, key) => {
+						if (!keys.has(key)) {
+							sub.unsubscribe();
+							innerSubscriptions.delete(key);
+							if (currentValue.has(key)) {
+								changes.add(key);
+								currentValue.delete(key);
+							}
+						} else {
+							keys.delete(key);
+						}
+					});
+				}
+
+				keys.forEach((key) => {
+					innerSubscriptions.set(
+						key,
+						getInner$(key).subscribe(
+							(x) => {
+								if (!currentValue.has(key) || currentValue.get(key) !== x) {
+									changes.add(key);
+									currentValue.set(key, x);
+									next();
+								}
+							},
+							(e) => {
+								observer.error(e);
+							},
+						),
+					);
+				});
+
+				updatingSource = false;
+				// If there are no changes but the nextKeys are an empty iterator
+				// and we have never emitted before, that means that the first
+				// value that keys$ has emitted is an empty iterator, therefore
+				// we should emit an empy Map
+				if (changes.size || (isPristine && !keys.size)) next();
+			},
+			(e) => {
+				observer.error(e);
+			},
+			() => {
+				observer.complete();
+			},
+		);
+
+		return () => {
+			subscription.unsubscribe();
+			innerSubscriptions.forEach((sub) => {
+				sub.unsubscribe();
+			});
+		};
+	});
+
+function inputIsKeyChanges<K>(input: Iterable<K> | KeyChanges<K>): input is KeyChanges<K> {
+	return 'type' in input && 'keys' in input;
+}

package/src/utils/contextBinder.ts

@@ -0,0 +1,39 @@
+import { Observable } from 'rxjs';
+import { SUSPENSE } from '@rx-state/core';
+import { bind } from '../bind.ts';
+
+type SubstractTuples<A1, A2> = A2 extends [unknown, ...infer Rest2]
+	? A1 extends [unknown, ...infer Rest1]
+		? SubstractTuples<Rest1, Rest2>
+		: []
+	: A1;
+
+const execSelf = <T>(fn: () => T) => fn();
+
+/**
+ * Returns a version of bind where its hook will have the first parameters bound
+ * the results of the provided functions
+ *
+ * @param {...React.Context} context - The React.Context that should be bound to the hook.
+ */
+export function contextBinder<
+	A extends (() => any)[],
+	OT extends {
+		[K in keyof A]: A[K] extends () => infer V ? V : unknown;
+	},
+>(
+	...args: A
+): <AA extends any[], T, ARGS extends [...OT, ...AA]>(
+	getObservable: (...args: ARGS) => Observable<T>,
+	defaultValue?: T | undefined,
+) => [
+	(...args: SubstractTuples<ARGS, OT>) => Exclude<T, typeof SUSPENSE>,
+	(...args: ARGS) => Observable<T>,
+];
+export function contextBinder(...args: any[]) {
+	const useArgs = () => args.map(execSelf);
+	return function () {
+		const [hook, getter] = bind.apply(null, arguments as any) as any;
+		return [(...args: any[]) => (hook as any)(...useArgs(), ...args), getter];
+	} as any;
+}

package/src/utils/createKeyedSignal.ts

@@ -0,0 +1,83 @@
+import { GroupedObservable, Observable, Observer } from 'rxjs';
+
+/**
+ * Creates a "keyed" signal. It's sugar for splitting the Observer and the Observable of a keyed signal.
+ *
+ * @returns [1, 2]
+ * 1. The getter function that returns the GroupedObservable<T, T>
+ * 2. The emitter function.
+ */
+export function createKeyedSignal<T>(): [(key: T) => GroupedObservable<T, T>, (key: T) => void];
+
+/**
+ * Creates a "keyed" signal. It's sugar for splitting the Observer and the Observable of a keyed signal.
+ *
+ * @param keySelector a function that extracts the key from the emitted value
+ * @returns [1, 2]
+ * 1. The getter function that returns the GroupedObservable<K, T>
+ * 2. The emitter function.
+ */
+export function createKeyedSignal<K, T>(): [
+	(key: K) => GroupedObservable<K, T>,
+	(key: K, value: T) => void,
+];
+
+/**
+ * Creates a "keyed" signal. It's sugar for splitting the Observer and the Observable of a keyed signal.
+ *
+ * @param keySelector a function that extracts the key from the emitted value
+ * @returns [1, 2]
+ * 1. The getter function that returns the GroupedObservable<K, T>
+ * 2. The emitter function.
+ */
+export function createKeyedSignal<K, T>(
+	keySelector: (signal: T) => K,
+): [(key: K) => GroupedObservable<K, T>, (signal: T) => void];
+
+/**
+ * Creates a "keyed" signal. It's sugar for splitting the Observer and the Observable of a keyed signal.
+ *
+ * @param keySelector a function that extracts the key from the emitted value
+ * @param mapper a function that maps the arguments of the emitter function to the value of the GroupedObservable
+ * @returns [1, 2]
+ * 1. The getter function that returns the GroupedObservable<K, T>
+ * 2. The emitter function (...args: any[]) => T.
+ */
+export function createKeyedSignal<K, T, A extends any[]>(
+	keySelector: (signal: T) => K,
+	mapper: (...args: A) => T,
+): [(key: K) => GroupedObservable<K, T>, (...args: A) => void];
+
+export function createKeyedSignal<K, T, A extends any[]>(
+	keySelector?: (signal: T) => K,
+	mapper?: (...args: A) => T,
+): [(key: K) => GroupedObservable<K, T>, (...args: A) => void] {
+	const observersMap = new Map<K, Set<Observer<T>>>();
+
+	return [
+		(key: K) => {
+			const res = new Observable<T>((observer) => {
+				if (!observersMap.has(key)) {
+					observersMap.set(key, new Set());
+				}
+				const set = observersMap.get(key)!;
+				set.add(observer);
+				return () => {
+					set.delete(observer);
+					if (set.size === 0) {
+						observersMap.delete(key);
+					}
+				};
+			}) as GroupedObservable<K, T>;
+			(res as any).key = key;
+			return res;
+		},
+		(...args: A) => {
+			const payload = mapper ? mapper(...args) : args.length === 2 ? args[1] : args[0];
+			const key = keySelector ? keySelector(payload) : args[0];
+			observersMap.get(key)?.forEach((o) => {
+				o.next(payload);
+			});
+		},
+	];
+}

package/src/utils/createListener.ts

@@ -0,0 +1,24 @@
+import { Observable } from 'rxjs';
+import { createSignal } from './createSignal';
+
+/** @deprecated createListener is deprecated and it will be removed in the next version, please use createSignal. */
+export function createListener<A extends unknown[], T>(
+	mapper: (...args: A) => T,
+): [Observable<T>, (...args: A) => void];
+
+/** @deprecated createListener is deprecated and it will be removed in the next version, please use createSignal. */
+export function createListener(): [Observable<void>, () => void];
+
+/** @deprecated createListener is deprecated and it will be removed in the next version, please use createSignal. */
+export function createListener<T>(): [Observable<T>, (payload: T) => void];
+
+/**
+ * Creates a void signal. It's sugar for splitting the Observer and the Observable of a signal.
+ *
+ * @returns [1, 2]
+ * 1. The Observable
+ * 2. The emitter function.
+ */
+export function createListener(...args: any[]) {
+	return (createSignal as any)(...args);
+}

package/src/utils/createSignal.ts

@@ -0,0 +1,39 @@
+import { identity, Observable, Subject } from 'rxjs';
+
+/**
+ * Creates a signal. It's sugar for splitting the Observer and the Observable of a signal.
+ *
+ * @param mapper a mapper function, for mapping the arguments of the emitter function into
+ * the value of the Observable.
+ * @returns [1, 2]
+ * 1. The Observable<T>
+ * 2. The emitter function.
+ */
+export function createSignal<A extends unknown[], T>(
+	mapper: (...args: A) => T,
+): [Observable<T>, (...args: A) => void];
+
+/**
+ * Creates a void signal. It's sugar for splitting the Observer and the Observable of a signal.
+ *
+ * @returns [1, 2]
+ * 1. The Observable<void>
+ * 2. The emitter function.
+ */
+export function createSignal(): [Observable<void>, () => void];
+
+/**
+ * Creates a signal. It's sugar for splitting the Observer and the Observable of a signal.
+ *
+ * @returns [1, 2]
+ * 1. The Observable<T>
+ * 2. The emitter function.
+ */
+export function createSignal<T>(): [Observable<T>, (payload: T) => void];
+
+export function createSignal<A extends unknown[], T>(
+	mapper: (...args: A) => T = identity as any,
+): [Observable<T>, (...args: A) => void] {
+	const subject = new Subject<T>();
+	return [subject.asObservable(), (...args: A) => subject.next(mapper(...args))];
+}

package/src/utils/index.ts

@@ -0,0 +1,14 @@
+export { combineKeys } from './combineKeys';
+export type { MapWithChanges } from './combineKeys';
+export { contextBinder } from './contextBinder';
+export { createKeyedSignal } from './createKeyedSignal';
+export { createListener } from './createListener';
+export { createSignal } from './createSignal';
+export { mergeWithKey } from './mergeWithKey';
+export { partitionByKey } from './partitionByKey';
+export type { KeyChanges } from './partitionByKey';
+export { selfDependant, selfDependent } from './selfDependent';
+export { suspend } from './suspend';
+export { suspended } from './suspended';
+export { switchMapSuspended } from './switchMapSuspended';
+export { toKeySet } from './toKeySet';

package/src/utils/internal-utils.ts

@@ -0,0 +1,26 @@
+import { Observable } from 'rxjs';
+
+export const defaultStart =
+	<T, D>(value: D) =>
+	(source$: Observable<T>) =>
+		new Observable<T | D>((observer) => {
+			let emitted = false;
+			const subscription = source$.subscribe(
+				(x) => {
+					emitted = true;
+					observer.next(x);
+				},
+				(e) => {
+					observer.error(e);
+				},
+				() => {
+					observer.complete();
+				},
+			);
+
+			if (!emitted) {
+				observer.next(value);
+			}
+
+			return subscription;
+		});

package/src/utils/mergeWithKey.ts

@@ -0,0 +1,26 @@
+import { merge, Observable, ObservableInput, from, SchedulerLike } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+/**
+ * Emits the values from all the streams of the provided object, in a result
+ * which provides the key of the stream of that emission.
+ *
+ * @param input object of streams
+ */
+export const mergeWithKey: <
+	O extends { [P in keyof any]: ObservableInput<any> },
+	OT extends {
+		[K in keyof O]: O[K] extends ObservableInput<infer V> ? { type: K; payload: V } : unknown;
+	},
+>(
+	x: O,
+	concurrent?: number,
+	scheduler?: SchedulerLike,
+) => Observable<OT[keyof O]> = (input, ...optionalArgs) =>
+	merge<any[]>(
+		...(Object.entries(input)
+			.map(
+				([type, stream]) => from(stream).pipe(map((payload) => ({ type, payload }) as any)) as any,
+			)
+			.concat(optionalArgs) as any[]),
+	);

package/src/utils/partitionByKey.ts

@@ -0,0 +1,216 @@
+import { shareLatest } from '../shareLatest.ts';
+import { GroupedObservable, identity, noop, Observable, Subject, Subscription } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+export interface KeyChanges<K> {
+	type: 'add' | 'remove';
+	keys: Iterable<K>;
+}
+
+/**
+ * Groups the elements from the source stream by using `keySelector`, returning
+ * a stream of the active keys, and a function to get the stream of a specific group
+ *
+ * @param stream Input stream
+ * @param keySelector Function that specifies the key for each element in `stream`
+ * @param streamSelector Function to apply to each resulting group
+ * @returns [1, 2]
+ * 1. A function that accepts a key and returns the stream for the group of that key.
+ * 2. A stream of KeyChanges, an object that describes what keys have been added or deleted.
+ */
+export function partitionByKey<T, K, R>(
+	stream: Observable<T>,
+	keySelector: (value: T) => K,
+	streamSelector: (grouped: Observable<T>, key: K) => Observable<R>,
+): [(key: K) => GroupedObservable<K, R>, Observable<KeyChanges<K>>];
+
+/**
+ * Groups the elements from the source stream by using `keySelector`, returning
+ * a stream of the active keys, and a function to get the stream of a specific group
+ *
+ * @param stream Input stream
+ * @param keySelector Function that specifies the key for each element in `stream`
+ * @returns [1, 2]
+ * 1. A function that accepts a key and returns the stream for the group of that key.
+ * 2. A stream of KeyChanges, an object that describes what keys have been added or deleted.
+ */
+export function partitionByKey<T, K>(
+	stream: Observable<T>,
+	keySelector: (value: T) => K,
+): [(key: K) => GroupedObservable<K, T>, Observable<KeyChanges<K>>];
+
+export function partitionByKey<T, K, R>(
+	stream: Observable<T>,
+	keySelector: (value: T) => K,
+	streamSelector?: (grouped: Observable<T>, key: K) => Observable<R>,
+): [(key: K) => GroupedObservable<K, R>, Observable<KeyChanges<K>>] {
+	const groupedObservables$ = new Observable<{
+		groups: Map<K, InnerGroup<T, K, R>>;
+		changes: KeyChanges<K>;
+	}>((subscriber) => {
+		const groups: Map<K, InnerGroup<T, K, R>> = new Map();
+
+		let sourceCompleted = false;
+		const finalize =
+			(type: 'error' | 'complete') =>
+			(...args: any[]) => {
+				sourceCompleted = true;
+				if (groups.size) {
+					groups.forEach((g) => (g.source[type] as any)(...args));
+				} else {
+					subscriber[type](...args);
+				}
+			};
+
+		const sub = stream.subscribe(
+			(x) => {
+				const key = keySelector(x);
+				if (groups.has(key)) return groups.get(key)!.source.next(x);
+
+				let pendingFirstAdd = true;
+				const emitFirstAdd = () => {
+					if (pendingFirstAdd) {
+						pendingFirstAdd = false;
+						subscriber.next({
+							groups,
+							changes: {
+								type: 'add',
+								keys: [key],
+							},
+						});
+					}
+				};
+
+				const subject = new Subject<T>();
+				let pendingFirstVal = true;
+				const emitFirstValue = () => {
+					if (pendingFirstVal) {
+						pendingFirstVal = false;
+						subject.next(x);
+					}
+				};
+
+				const shared$ = shareLatest()((streamSelector || identity)(subject, key));
+				const res = new Observable((observer) => {
+					incRefcount();
+					const subscription = shared$.subscribe(observer);
+					subscription.add(decRefcount);
+					emitFirstValue();
+					return subscription;
+				}) as any as GroupedObservable<K, R>;
+				(res as any).key = key;
+
+				const innerGroup: InnerGroup<T, K, R> = {
+					source: subject,
+					observable: res,
+					subscription: new Subscription(),
+				};
+				groups.set(key, innerGroup);
+
+				innerGroup.subscription = shared$.subscribe(
+					noop,
+					(e) => subscriber.error(e),
+					() => {
+						groups.delete(key);
+						emitFirstAdd();
+						subscriber.next({
+							groups,
+							changes: {
+								type: 'remove',
+								keys: [key],
+							},
+						});
+
+						if (groups.size === 0 && sourceCompleted) {
+							subscriber.complete();
+						}
+					},
+				);
+				emitFirstAdd();
+				emitFirstValue();
+			},
+			finalize('error'),
+			finalize('complete'),
+		);
+
+		return () => {
+			sub.unsubscribe();
+			groups.forEach((g) => {
+				g.source.unsubscribe();
+				g.subscription.unsubscribe();
+			});
+		};
+	}).pipe(shareLatest());
+
+	let refCount = 0;
+	let sub: Subscription | undefined;
+	function incRefcount() {
+		refCount++;
+		if (refCount === 1) {
+			sub = groupedObservables$.subscribe();
+		}
+	}
+	function decRefcount() {
+		refCount--;
+		if (refCount === 0) {
+			sub?.unsubscribe();
+		}
+	}
+
+	return [
+		(key: K) => getGroupedObservable(groupedObservables$.pipe(map(({ groups }) => groups)), key),
+		groupedObservables$.pipe(
+			map((m, i): KeyChanges<K> => {
+				if (i === 0) {
+					// Replay all the previously added keys
+					return {
+						type: 'add',
+						keys: m.groups.keys(),
+					};
+				}
+				return m.changes;
+			}),
+		),
+	];
+}
+
+interface InnerGroup<T, K, R> {
+	source: Subject<T>;
+	observable: GroupedObservable<K, R>;
+	subscription: Subscription;
+}
+
+const getGroupedObservable = <K, T>(source$: Observable<Map<K, InnerGroup<any, K, T>>>, key: K) => {
+	const result = new Observable<T>((observer) => {
+		let innerSub: Subscription | undefined;
+		let outerSub: Subscription | undefined;
+		let foundSynchronously = false;
+		outerSub = source$.subscribe(
+			(n) => {
+				const innerGroup = n.get(key);
+				if (innerGroup && !innerSub) {
+					innerSub = innerGroup.observable.subscribe(observer);
+					outerSub?.unsubscribe();
+					foundSynchronously = true;
+				}
+			},
+			(e) => {
+				observer.error(e);
+			},
+			() => {
+				observer.complete();
+			},
+		);
+		if (foundSynchronously) {
+			outerSub.unsubscribe();
+			outerSub = undefined;
+		}
+
+		return () => {
+			innerSub?.unsubscribe();
+			outerSub?.unsubscribe();
+		};
+	}) as GroupedObservable<K, T>;
+	(result as any).key = key;
+	return result;
+};

package/src/utils/selfDependent.ts

@@ -0,0 +1,34 @@
+import { Observable, Subject, MonoTypeOperatorFunction, BehaviorSubject } from 'rxjs';
+import { switchAll, tap } from 'rxjs/operators';
+
+/**
+ * A creation operator that helps at creating observables that have circular
+ * dependencies
+ *
+ * @returns [1, 2]
+ * 1. The inner subject as an Observable
+ * 2. A pipable operator that taps into the inner Subject
+ */
+export const selfDependent = <T>(): [Observable<T>, () => MonoTypeOperatorFunction<T>] => {
+	const activeSubject: BehaviorSubject<Subject<T>> = new BehaviorSubject(new Subject<T>());
+	return [
+		activeSubject.pipe(switchAll()),
+		() =>
+			tap({
+				next: (v) => activeSubject.value.next(v),
+				error: (e) => {
+					activeSubject.value.error(e);
+					activeSubject.next(new Subject<T>());
+				},
+				complete: () => {
+					activeSubject.value.complete();
+					activeSubject.next(new Subject<T>());
+				},
+			}) as MonoTypeOperatorFunction<T>,
+	];
+};
+
+/**
+ * @deprecated renamed to `selfDependent`
+ */
+export const selfDependant = selfDependent;

package/src/utils/suspend.ts

@@ -0,0 +1,12 @@
+import { ObservableInput, from, Observable } from 'rxjs';
+import { SUSPENSE } from '@rx-state/core';
+import { defaultStart } from './internal-utils';
+
+/**
+ * A RxJS creation operator that prepends a SUSPENSE on the source observable.
+ *
+ * @param source$ Source observable
+ */
+export const suspend: <T>(source$: ObservableInput<T>) => Observable<T | typeof SUSPENSE> = <T>(
+	source$: ObservableInput<T>,
+) => defaultStart(SUSPENSE)(from(source$)) as any;

package/src/utils/suspended.ts

@@ -0,0 +1,8 @@
+import { suspend } from './suspend';
+import { OperatorFunction } from 'rxjs';
+import { SUSPENSE } from '@rx-state/core';
+
+/**
+ * A RxJS pipeable operator that prepends a SUSPENSE on the source observable.
+ */
+export const suspended = <T>(): OperatorFunction<T, T | typeof SUSPENSE> => suspend;

package/src/utils/switchMapSuspended.ts

@@ -0,0 +1,15 @@
+import { ObservableInput, OperatorFunction, ObservedValueOf, pipe } from 'rxjs';
+import { switchMap } from 'rxjs/operators';
+import { suspend } from './suspend';
+import { SUSPENSE } from '@rx-state/core';
+
+/**
+ * Same behaviour as rxjs' `switchMap`, but prepending every new event with
+ * SUSPENSE.
+ *
+ * @param fn Projection function
+ */
+export const switchMapSuspended = <T, O extends ObservableInput<any>>(
+	project: (value: T, index: number) => O,
+): OperatorFunction<T, ObservedValueOf<O> | typeof SUSPENSE> =>
+	pipe(switchMap((x, index) => suspend(project(x, index))));

package/src/utils/toKeySet.ts

@@ -0,0 +1,32 @@
+import { Observable, OperatorFunction } from 'rxjs';
+import { KeyChanges } from './partitionByKey';
+
+/**
+ * Operator function that maps a stream of KeyChanges into a Set that contains
+ * the active keys.
+ */
+export function toKeySet<K>(): OperatorFunction<KeyChanges<K>, Set<K>> {
+	return (source$) =>
+		new Observable<Set<K>>((observer) => {
+			const result = new Set<K>();
+			let pristine = true;
+			const subscription = source$.subscribe({
+				next({ type, keys }) {
+					const action = type === 'add' ? type : 'delete';
+					for (let k of keys) {
+						result[action](k);
+					}
+					observer.next(result);
+					pristine = false;
+				},
+				error(e) {
+					observer.error(e);
+				},
+				complete() {
+					observer.complete();
+				},
+			});
+			if (pristine) observer.next(result);
+			return subscription;
+		});
+}

package/status.json

@@ -0,0 +1,13 @@
+{
+  "upstream": {
+    "package": "@react-rxjs/core + @react-rxjs/utils",
+    "version": "0.10.8 / 0.9.7"
+  },
+  "surface": "Core bind/state/Subscribe APIs and the complete @react-rxjs/utils surface.",
+  "divergences": [
+    "StateObservable values are not JSX nodes; render them through useStateObservable or bind.",
+    "@react-rxjs/dom is omitted because octane batches updates without ReactDOM.unstable_batchedUpdates."
+  ],
+  "ssr": "useSyncExternalStore supplies the state snapshot during server rendering; browser-only ReactDOM batching helpers are intentionally absent.",
+  "verified": "2026-07-30"
+}