@octanejs/mobx 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,30 @@
+# @octanejs/mobx
+
+MobX bindings for Octane. The package re-exports the framework-independent
+`mobx` core and implements the `mobx-react-lite` function-component surface with
+Octane hooks.
+
+```tsrx
+import { makeAutoObservable, observer } from '@octanejs/mobx';
+
+const store = makeAutoObservable({ count: 0 });
+
+const Counter = observer(function Counter(props: { store: typeof store }) @{
+	<button onClick={() => props.store.count++}>{props.store.count as string}</button>
+});
+```
+
+## Supported
+
+- MobX core exports
+- `observer`
+- `useObserver`
+- `Observer`
+- `useLocalObservable`
+- `enableStaticRendering` and `isUsingStaticRendering`
+
+## Intentional v1 limits
+
+This binding targets compiled Octane function components. React class
+components, legacy `Provider`/`inject`, `forwardRef` compatibility options,
+React-specific batching, and React DevTools integration are not included.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@octanejs/mobx",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "MobX bindings for Octane, reusing the MobX core with Octane-native observer hooks and components.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/mobx"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "mobx": "6.16.1"
+  },
+  "peerDependencies": {
+    "octane": "0.1.19"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "octane": "0.1.19"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project mobx --project mobx-ssr"
+  }
+}

package/src/ObserverComponent.ts

@@ -0,0 +1,21 @@
+import type { ComponentBody } from 'octane';
+import { useObserverWithSlot } from './useObserver';
+
+export type ObserverProps = {
+	children?: () => unknown;
+	render?: () => unknown;
+};
+
+const observerSlot = Symbol('@octanejs/mobx:Observer');
+
+export const Observer: ComponentBody<ObserverProps> = ({ children, render }) => {
+	if (children && render) {
+		console.error('MobX Observer: Do not use children and render at the same time.');
+	}
+	const component = children || render;
+	return typeof component === 'function'
+		? useObserverWithSlot(component, 'Observer', observerSlot)
+		: null;
+};
+
+(Observer as ComponentBody<ObserverProps> & { displayName?: string }).displayName = 'Observer';

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from 'mobx';
+export { Observer } from './ObserverComponent';
+export type { ObserverProps } from './ObserverComponent';
+export { observer } from './observer';
+export type { ObserverComponent } from './observer';
+export {
+	enableStaticRendering,
+	isUsingStaticRendering,
+	useStaticRendering,
+} from './staticRendering';
+export { useLocalObservable } from './useLocalObservable';
+export { useObserver } from './useObserver';

package/src/internal.ts

@@ -0,0 +1,26 @@
+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) {
+			bare = Symbol.for(`@octanejs/mobx:${tag}`);
+			bareTagCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+
+	let child = byTag.get(tag);
+	if (child === undefined) {
+		child = Symbol(`${slot.description ?? '@octanejs/mobx'}:${tag}`);
+		byTag.set(tag, child);
+	}
+	return child;
+}

package/src/observer.ts

@@ -0,0 +1,36 @@
+import { memo } from 'octane';
+import type { ComponentBody } from 'octane';
+import { isUsingStaticRendering } from './staticRendering';
+import { useObserverWithSlot } from './useObserver';
+
+const OBSERVED = Symbol.for('@octanejs/mobx/observed');
+
+export type ObserverComponent<P> = ComponentBody<P> & {
+	displayName?: string;
+};
+
+export function observer<P>(baseComponent: ComponentBody<P>): ObserverComponent<P> {
+	const observedBase = baseComponent as ObserverComponent<P>;
+	if ((observedBase as ObserverComponent<P> & { [OBSERVED]?: true })[OBSERVED]) {
+		throw new Error(
+			'[@octanejs/mobx] You are trying to apply observer to an already observed component.',
+		);
+	}
+	if (isUsingStaticRendering()) return observedBase;
+
+	const baseComponentName = observedBase.displayName || observedBase.name || 'observed';
+	const hookSlot = Symbol(`@octanejs/mobx:observer:${baseComponentName}`);
+	const observerComponent: ObserverComponent<P> = (props, scope, extra) =>
+		useObserverWithSlot(() => baseComponent(props, scope, extra), baseComponentName, hookSlot);
+
+	observerComponent.displayName = observedBase.displayName;
+	if (Object.getOwnPropertyDescriptor(observerComponent, 'name')?.configurable) {
+		Object.defineProperty(observerComponent, 'name', {
+			value: observedBase.name,
+			configurable: true,
+		});
+	}
+	const memoized = memo(observerComponent) as ObserverComponent<P>;
+	Object.defineProperty(memoized, OBSERVED, { value: true });
+	return memoized;
+}

package/src/staticRendering.ts

@@ -0,0 +1,12 @@
+let staticRendering = false;
+
+export function enableStaticRendering(enable: boolean): void {
+	staticRendering = enable;
+}
+
+/** @deprecated Use enableStaticRendering instead. */
+export const useStaticRendering = enableStaticRendering;
+
+export function isUsingStaticRendering(): boolean {
+	return staticRendering;
+}

package/src/useLocalObservable.ts

@@ -0,0 +1,28 @@
+import { observable } from 'mobx';
+import type { AnnotationsMap } from 'mobx';
+import { useState } from 'octane';
+import { subSlot } from './internal';
+
+export function useLocalObservable<TStore extends Record<string, unknown>>(
+	initializer: () => TStore,
+	annotations?: AnnotationsMap<TStore, never>,
+): TStore;
+export function useLocalObservable<TStore extends Record<string, unknown>>(
+	initializer: () => TStore,
+	annotations?: AnnotationsMap<TStore, never> | symbol,
+	...rest: [slot?: symbol]
+): TStore {
+	const slot =
+		typeof rest[rest.length - 1] === 'symbol'
+			? rest[rest.length - 1]
+			: typeof annotations === 'symbol'
+				? annotations
+				: undefined;
+	return useState(
+		() =>
+			observable(initializer(), typeof annotations === 'symbol' ? undefined : annotations, {
+				autoBind: true,
+			}),
+		subSlot(slot, 'local-observable'),
+	)[0];
+}

package/src/useObserver.ts

@@ -0,0 +1,116 @@
+import { Reaction } from 'mobx';
+import { useRef, useSyncExternalStore } from 'octane';
+import { subSlot } from './internal';
+import { isUsingStaticRendering } from './staticRendering';
+
+type ObserverAdministration = {
+	reaction: Reaction | null;
+	onStoreChange: (() => void) | null;
+	stateVersion: symbol;
+	name: string;
+	subscribe: (onStoreChange: () => void) => () => void;
+	getSnapshot: () => symbol;
+};
+
+const observerFinalizationRegistry = new FinalizationRegistry<ObserverAdministration>((adm) => {
+	adm.reaction?.dispose();
+	adm.reaction = null;
+	adm.onStoreChange = null;
+});
+
+function createReaction(adm: ObserverAdministration): void {
+	adm.reaction = new Reaction(`observer${adm.name}`, () => {
+		adm.stateVersion = Symbol();
+		adm.onStoreChange?.();
+	});
+}
+
+function runObserver<T>(render: () => T, baseComponentName: string, slot: symbol | undefined): T {
+	if (isUsingStaticRendering()) return render();
+
+	const admRef = useRef<ObserverAdministration | null>(null, subSlot(slot, 'administration'));
+
+	if (admRef.current === null) {
+		const adm: ObserverAdministration = {
+			reaction: null,
+			onStoreChange: null,
+			stateVersion: Symbol(),
+			name: baseComponentName,
+			subscribe(onStoreChange) {
+				observerFinalizationRegistry.unregister(adm);
+				adm.onStoreChange = onStoreChange;
+				if (adm.reaction === null) {
+					createReaction(adm);
+					adm.stateVersion = Symbol();
+				}
+				return () => {
+					adm.onStoreChange = null;
+					adm.reaction?.dispose();
+					adm.reaction = null;
+				};
+			},
+			getSnapshot() {
+				return adm.stateVersion;
+			},
+		};
+		admRef.current = adm;
+	}
+
+	const adm = admRef.current;
+	if (adm.reaction === null) {
+		createReaction(adm);
+		observerFinalizationRegistry.register(admRef, adm, adm);
+	}
+
+	useSyncExternalStore(
+		adm.subscribe,
+		adm.getSnapshot,
+		adm.getSnapshot,
+		subSlot(slot, 'external-store'),
+	);
+
+	let result!: T;
+	let error: unknown;
+	let didThrow = false;
+	const reaction = adm.reaction;
+	if (reaction === null) {
+		throw new Error('[@octanejs/mobx] Observer reaction was disposed during render.');
+	}
+	reaction.track(() => {
+		try {
+			result = render();
+		} catch (caught) {
+			didThrow = true;
+			error = caught;
+		}
+	});
+	if (didThrow) throw error;
+	return result;
+}
+
+export function useObserver<T>(render: () => T, baseComponentName?: string): T;
+export function useObserver<T>(
+	render: () => T,
+	baseComponentName: string | symbol = 'observed',
+	...rest: [slot?: symbol]
+): T {
+	const slot =
+		typeof rest[rest.length - 1] === 'symbol'
+			? rest[rest.length - 1]
+			: typeof baseComponentName === 'symbol'
+				? baseComponentName
+				: undefined;
+	return runObserver(
+		render,
+		typeof baseComponentName === 'string' ? baseComponentName : 'observed',
+		slot,
+	);
+}
+
+export function useObserverWithSlot<T>(
+	render: () => T,
+	baseComponentName: string,
+	slot: symbol,
+): T {
+	return runObserver(render, baseComponentName, slot);
+}