@systemfsoftware/effect-atom-react 0.5.0

package/dist/index.mjs

@@ -0,0 +1,614 @@
+import * as Atom from "@systemfsoftware/effect-atom/Atom";
+import * as AtomRegistry from "@systemfsoftware/effect-atom/Registry";
+import * as AsyncResult from "@systemfsoftware/effect-atom/Result";
+import * as Cause from "effect/Cause";
+import "effect/Effect";
+import * as React from "react";
+import * as Scheduler from "scheduler";
+import * as Hydration from "@systemfsoftware/effect-atom/Hydration";
+//#region src/RegistryContext.ts
+/**
+* React context and provider for the Atom registry used by Effect Atom hooks.
+* The registry stores atom values, schedules update work, and cleans up unused
+* atoms. Sharing one registry through React context lets components in the same
+* subtree read and write the same atom state.
+*
+* @since 4.0.0
+*/
+/**
+* Schedules Atom registry work with React's scheduler at low priority and
+* returns a cancellation function for the scheduled task.
+*
+* @category context
+* @since 4.0.0
+*/
+function scheduleTask(f) {
+	const node = Scheduler.unstable_scheduleCallback(Scheduler.unstable_LowPriority, f);
+	return () => Scheduler.unstable_cancelCallback(node);
+}
+/**
+* Provides a React context that supplies the `AtomRegistry` used by Atom hooks and
+* hydration helpers, defaulting to a standalone registry when no provider is
+* present.
+*
+* **When to use**
+*
+* Use to supply an existing `AtomRegistry` through React context when hooks or
+* hydration helpers need to share registry state that is managed outside
+* `RegistryProvider`.
+*
+* @see {@link RegistryProvider} for creating and providing a registry for a React subtree
+*
+* @category context
+* @since 4.0.0
+*/
+const RegistryContext = React.createContext(AtomRegistry.make({
+	scheduleTask,
+	defaultIdleTTL: 400
+}));
+/**
+* Provides a stable `AtomRegistry` to a React subtree, optionally seeding
+* initial atom values and overriding registry scheduling or idle settings.
+*
+* **When to use**
+*
+* Use to scope atom state, scheduling, and idle cleanup to a React subtree.
+*
+* **Details**
+*
+* The provider creates one `AtomRegistry` with `AtomRegistry.make`, passes it
+* through `RegistryContext.Provider`, and forwards `initialValues`,
+* `scheduleTask`, `timeoutResolution`, and `defaultIdleTTL` only when that
+* registry is created.
+*
+* **Gotchas**
+*
+* Option changes after the first render do not rebuild the registry. When the
+* provider unmounts, registry disposal is delayed briefly and canceled if the
+* provider remounts before the timeout fires.
+*
+* @see {@link RegistryContext} for the React context supplied by this provider
+*
+* @category context
+* @since 4.0.0
+*/
+const RegistryProvider = (options) => {
+	const ref = React.useRef(null);
+	if (ref.current === null) ref.current = { registry: AtomRegistry.make({
+		scheduleTask: options.scheduleTask ?? scheduleTask,
+		initialValues: options.initialValues,
+		timeoutResolution: options.timeoutResolution,
+		defaultIdleTTL: options.defaultIdleTTL
+	}) };
+	React.useEffect(() => {
+		const current = ref.current;
+		if (current?.timeout !== void 0) clearTimeout(current.timeout);
+		return () => {
+			if (ref.current === null) return;
+			ref.current.timeout = setTimeout(() => {
+				ref.current?.registry.dispose();
+				ref.current = null;
+			}, 500);
+		};
+	}, [ref]);
+	return React.createElement(RegistryContext.Provider, { value: ref.current.registry }, options?.children);
+};
+//#endregion
+//#region src/Hooks.ts
+/**
+* React hooks for working with Effect atoms from components. The hooks read,
+* write, mount, refresh, and subscribe to atoms from `RegistryContext`, handle
+* `AsyncResult` atoms with React Suspense, and expose helpers for reading and
+* deriving `AtomRef` values.
+*
+* @since 4.0.0
+*/
+function useStore(registry, atom) {
+	const subscribe = React.useMemo(() => (onStoreChange) => registry.subscribe(atom, () => onStoreChange()), [registry, atom]);
+	return React.useSyncExternalStore(subscribe, () => registry.get(atom), () => Atom.getServerValue(atom, registry));
+}
+const initialValuesSet = /* @__PURE__ */ new WeakMap();
+/**
+* Seeds initial atom values in the current React atom registry.
+*
+* **When to use**
+*
+* Use to seed atom values from a React component after the current registry
+* already exists.
+*
+* **Gotchas**
+*
+* Each atom is initialized at most once for a given registry by this hook, so
+* later calls for the same atom in that registry are ignored.
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomInitialValues = (initialValues) => {
+	const registry = React.useContext(RegistryContext);
+	let set = initialValuesSet.get(registry);
+	if (set === void 0) {
+		set = /* @__PURE__ */ new WeakSet();
+		initialValuesSet.set(registry, set);
+	}
+	for (const [atom, value] of initialValues) if (!set.has(atom)) {
+		set.add(atom);
+		registry.setInitialValue(atom, value);
+	}
+};
+/**
+* Subscribes to an atom in the current React registry and returns its current
+* value, optionally mapped through a selector.
+*
+* **When to use**
+*
+* Use when a React component needs to render from an atom value without also
+* returning a setter.
+*
+* **Details**
+*
+* When a selector is provided, the hook maps the atom before subscribing so the
+* component reads the selected value from the current `RegistryContext`.
+*
+* @see {@link useAtom} for reading and updating a writable atom from one component
+* @see {@link useAtomRef} for reading an `AtomRef` directly
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomValue = (atom, f) => {
+	const registry = React.useContext(RegistryContext);
+	if (f) return useStore(registry, React.useMemo(() => Atom.map(atom, f), [atom, f]));
+	return useStore(registry, atom);
+};
+function mountAtom(registry, atom) {
+	React.useEffect(() => registry.mount(atom), [atom, registry]);
+}
+/**
+* Mounts an atom in the current React registry for the lifetime of the
+* component.
+*
+* **When to use**
+*
+* Use to keep an atom mounted from a React component without reading, writing,
+* or refreshing it.
+*
+* **Details**
+*
+* The hook uses the current `RegistryContext` and releases the mount through
+* React effect cleanup when the component unmounts or when the registry or atom
+* dependency changes.
+*
+* @see {@link useAtomSet} for mounting a writable atom while returning a setter
+* @see {@link useAtomRefresh} for mounting an atom while returning a refresh callback
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomMount = (atom) => {
+	mountAtom(React.useContext(RegistryContext), atom);
+};
+/**
+* Mounts a writable atom and returns a setter without subscribing to its value.
+*
+* **When to use**
+*
+* Use when a React component needs to update a writable atom without rendering
+* from that atom's value.
+*
+* The hook mounts the atom and returns a setter that writes a complete value.
+* For updates computed from the current value use `useAtomUpdate`.
+*
+* @see {@link useAtom} for reading and updating the same writable atom
+* @see {@link useAtomSetResult} for a setter that resolves once the write settles
+* @see {@link useAtomUpdate} for a setter that applies an updater function
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomSet = (atom) => {
+	const registry = React.useContext(RegistryContext);
+	mountAtom(registry, atom);
+	return React.useCallback((value) => {
+		registry.set(atom, value);
+	}, [registry, atom]);
+};
+/**
+* Mounts a writable `AsyncResult` atom and returns a setter whose returned
+* effect resolves to the settled success value.
+*
+* **When to use**
+*
+* Use when a component writes to an `AsyncResult` atom and needs to know when
+* the write has been applied, so a save button can show a confirming state or
+* report a failure.
+*
+* The hook mounts the atom and returns a setter that writes a new value and
+* returns the effect of the atom leaving its initial state, failing with the
+* write result's cause when the write fails.
+*
+* @see {@link useAtomSet} for writing without waiting for settlement
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomSetResult = (atom) => {
+	const registry = React.useContext(RegistryContext);
+	mountAtom(registry, atom);
+	return React.useCallback((value) => {
+		registry.set(atom, value);
+		return AtomRegistry.getResult(registry, atom, { suspendOnWaiting: true });
+	}, [registry, atom]);
+};
+/**
+* Mounts a writable atom and returns an updater that applies a function to the
+* current value.
+*
+* **When to use**
+*
+* Use when a component needs to update a writable atom from its current value,
+* such as incrementing a counter, without subscribing to the atom.
+*
+* @see {@link useAtomSet} for writing a complete value
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomUpdate = (atom) => {
+	const registry = React.useContext(RegistryContext);
+	mountAtom(registry, atom);
+	return React.useCallback((f) => {
+		registry.update(atom, f);
+	}, [registry, atom]);
+};
+/**
+* Mounts an atom and returns a callback that refreshes it in the current React
+* registry.
+*
+* **When to use**
+*
+* Use to expose a React callback that requests a refresh for an atom without
+* reading or writing its value.
+*
+* **Details**
+*
+* The hook uses the current `RegistryContext`, mounts the atom for the
+* component lifetime, and returns a callback that calls `registry.refresh`.
+*
+* @see {@link useAtomMount} for mounting an atom without returning a refresh callback
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomRefresh = (atom) => {
+	const registry = React.useContext(RegistryContext);
+	mountAtom(registry, atom);
+	return React.useCallback(() => {
+		registry.refresh(atom);
+	}, [registry, atom]);
+};
+/**
+* Subscribes to a writable atom and returns its current value together with a
+* setter for updating it.
+*
+* **When to use**
+*
+* Use when a React component needs both to render the current value of a
+* writable atom and update it from the same component.
+*
+* @see {@link useAtomValue} for subscribing to an atom without a setter
+* @see {@link useAtomSet} for updating a writable atom without subscribing to its value
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtom = (atom) => {
+	const registry = React.useContext(RegistryContext);
+	return [useStore(registry, atom), React.useCallback((value) => registry.set(atom, value), [registry, atom])];
+};
+const atomPromiseMap = {
+	suspendOnWaiting: /* @__PURE__ */ new WeakMap(),
+	default: /* @__PURE__ */ new WeakMap()
+};
+function atomToPromise(registry, atom, suspendOnWaiting) {
+	const registries = suspendOnWaiting ? atomPromiseMap.suspendOnWaiting : atomPromiseMap.default;
+	let map = registries.get(registry);
+	if (map === void 0) {
+		map = /* @__PURE__ */ new WeakMap();
+		registries.set(registry, map);
+	}
+	const cached = map.get(atom);
+	if (cached !== void 0) return cached;
+	const { promise, resolve } = Promise.withResolvers();
+	let settled = false;
+	const dispose = registry.subscribe(atom, (result) => {
+		if (settled || AsyncResult.isInitial(result) || suspendOnWaiting && result.waiting) return;
+		settled = true;
+		dispose();
+		resolve();
+		map.delete(atom);
+	});
+	map.set(atom, promise);
+	return promise;
+}
+function atomResultOrSuspend(registry, atom, suspendOnWaiting) {
+	const value = useStore(registry, atom);
+	if (AsyncResult.isInitial(value) || suspendOnWaiting && value.waiting) throw atomToPromise(registry, atom, suspendOnWaiting);
+	return value;
+}
+/**
+* Reads an `AsyncResult` atom through React Suspense, suspending while the
+* result is initial or configured as waiting.
+*
+* **When to use**
+*
+* Use when a React component should render only after an `AsyncResult` atom has
+* left its initial state, with loading delegated to a Suspense boundary.
+*
+* **Details**
+*
+* `suspendOnWaiting` defaults to `false`. When `includeFailure` is `true`, a
+* failure result is returned instead of being thrown.
+*
+* **Gotchas**
+*
+* Without `includeFailure`, failure results are thrown with
+* `Cause.squash(result.cause)`, so callers need an error boundary for failures.
+*
+* @see {@link useAtomValue} for reading the raw `AsyncResult` value without Suspense
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomSuspense = (atom, options) => {
+	const result = atomResultOrSuspend(React.useContext(RegistryContext), atom, options?.suspendOnWaiting ?? false);
+	if (AsyncResult.isFailure(result)) {
+		if (options?.includeFailure) return result;
+		throw Cause.squash(result.cause);
+	}
+	return result;
+};
+/**
+* Subscribes a callback to an atom in the current React registry for the
+* component lifetime.
+*
+* **When to use**
+*
+* Use when a React component needs to run a callback for atom changes without
+* reading the atom value during render.
+*
+* **Details**
+*
+* The subscription is installed in a React effect and cleaned up on unmount or
+* dependency change. When `options.immediate` is enabled, the callback receives
+* the current value when the effect subscribes.
+*
+* @see {@link useAtomValue} for reading an atom value during render instead of running a callback
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomSubscribe = (atom, f, options) => {
+	const registry = React.useContext(RegistryContext);
+	const fRef = React.useRef(f);
+	fRef.current = f;
+	React.useEffect(() => registry.subscribe(atom, (value) => fRef.current(value), options), [
+		registry,
+		atom,
+		options?.immediate
+	]);
+};
+/**
+* Subscribes to an atom ref and returns its latest value.
+*
+* **When to use**
+*
+* Use when a React component should render from an `AtomRef.ReadonlyRef`
+* directly instead of reading an atom through the current registry.
+*
+* **Details**
+*
+* The hook subscribes with `ref.subscribe`, triggers re-renders through React
+* state, and returns the current `ref.value`.
+*
+* @see {@link useAtomValue} for reading an `Atom` from the current registry
+* @see {@link useAtomRefPropValue} for reading a property ref value
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomRef = (ref) => {
+	const [, setValue] = React.useState(ref.value);
+	React.useEffect(() => ref.subscribe(setValue), [ref]);
+	return ref.value;
+};
+/**
+* Returns a memoized atom ref for a property of another atom ref.
+*
+* **When to use**
+*
+* Use to derive an `AtomRef` for one property of an object-shaped atom ref.
+*
+* **Details**
+*
+* The hook memoizes `ref.prop(prop)` for the `[ref, prop]` dependency pair and
+* returns the property ref so callers can read, set, update, or subscribe to
+* that nested property.
+*
+* @see {@link useAtomRef} for subscribing to an atom ref value
+* @see {@link useAtomRefPropValue} for subscribing directly to a property value
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomRefProp = (ref, prop) => React.useMemo(() => ref.prop(prop), [ref, prop]);
+/**
+* Subscribes to a property ref derived from an atom ref and returns its current
+* value.
+*
+* **When to use**
+*
+* Use when a React component needs only the current value of one property from
+* an object-shaped `AtomRef`.
+*
+* **Details**
+*
+* The hook composes `useAtomRefProp(ref, prop)` with `useAtomRef`, so the
+* property ref is memoized for the `[ref, prop]` pair and then subscribed
+* through `ref.subscribe`.
+*
+* @see {@link useAtomRefProp} for returning the property ref directly
+* @see {@link useAtomRef} for subscribing to a whole atom ref value
+*
+* @category hooks
+* @since 4.0.0
+*/
+const useAtomRefPropValue = (ref, prop) => useAtomRef(useAtomRefProp(ref, prop));
+//#endregion
+//#region src/ReactHydration.ts
+/**
+* React helpers for applying dehydrated Effect Atom state to a React subtree.
+* The `HydrationBoundary` component reads the nearest `RegistryContext`,
+* hydrates new Atom values before children render, and delays updates for
+* existing Atom values until after commit so React transitions do not update
+* the current UI too early.
+*
+* @since 4.0.0
+*/
+/**
+* Provides a React hydration boundary that loads dehydrated Atom values into
+* the current Atom registry.
+*
+* **When to use**
+*
+* Use to apply dehydrated Atom state to a React subtree that reads from the
+* nearest `RegistryContext`.
+*
+* **Details**
+*
+* New Atom values are hydrated during render so descendants can read them
+* immediately, while values for existing Atoms are deferred until after commit
+* so transition data does not update the current UI before React accepts it.
+*
+* @see {@link Hydration.dehydrate} for producing dehydrated Atom state
+* @see {@link Hydration.hydrate} for lower-level non-React hydration
+*
+* @category components
+* @since 4.0.0
+*/
+const HydrationBoundary = ({ children, state }) => {
+	const registry = React.useContext(RegistryContext);
+	const hydrationQueue = React.useMemo(() => {
+		if (state) {
+			const dehydratedAtoms = Array.from(state);
+			const nodes = registry.getNodes();
+			const newDehydratedAtoms = [];
+			const existingDehydratedAtoms = [];
+			for (const dehydratedAtom of dehydratedAtoms) if (!nodes.get(dehydratedAtom.key)) newDehydratedAtoms.push(dehydratedAtom);
+			else existingDehydratedAtoms.push(dehydratedAtom);
+			if (newDehydratedAtoms.length > 0) Hydration.hydrate(registry, newDehydratedAtoms);
+			if (existingDehydratedAtoms.length > 0) return existingDehydratedAtoms;
+		}
+	}, [registry, state]);
+	React.useEffect(() => {
+		if (hydrationQueue) Hydration.hydrate(registry, hydrationQueue);
+	}, [registry, hydrationQueue]);
+	return React.createElement(React.Fragment, {}, children);
+};
+//#endregion
+//#region src/ScopedAtom.ts
+/**
+* React helpers for creating Atom instances that belong to one component
+* subtree. `make` returns a scoped atom with a provider, context, and `use`
+* accessor. Each provider creates its own Atom once, so different subtrees can
+* use the same scoped atom definition without sharing state.
+*
+* @since 4.0.0
+*/
+/**
+* Type identifier for ScopedAtom.
+*
+* **Details**
+*
+* Used as the computed property key and marker value stored on `ScopedAtom`
+* objects.
+*
+* @category type IDs
+* @since 4.0.0
+*/
+const TypeId = "~@effect/atom-react/ScopedAtom";
+/**
+* Creates a ScopedAtom from a factory function.
+*
+* **When to use**
+*
+* Use to create an atom instance that is owned by a React provider and scoped
+* to a component subtree.
+*
+* **Details**
+*
+* The returned scoped atom includes a `Provider`, `Context`, and `use`
+* accessor. The provider creates the atom once for its lifetime, passing the
+* `value` prop to the factory when the scoped atom expects input.
+*
+* **Gotchas**
+*
+* `use` must run under the matching provider. Changing the provider `value`
+* prop after mount does not recreate the atom.
+*
+* **Example** (Creating a scoped atom with input)
+*
+* ```ts import.meta.vitest
+* import { make, useAtomValue } from "@effect/atom-react"
+* import { Atom } from "effect/unstable/reactivity"
+* import * as React from "react"
+* import { renderToStaticMarkup } from "react-dom/server"
+*
+* const User = make((name: string) => Atom.make(name))
+*
+* function UserName() {
+*   const atom = User.use()
+*   const value = useAtomValue(atom)
+*   return React.createElement("span", null, value)
+* }
+*
+* export function App() {
+*   return React.createElement(
+*     User.Provider,
+*     { value: "Ada" },
+*     React.createElement(UserName)
+*   )
+* }
+*
+* renderToStaticMarkup(React.createElement(App)) // => "<span>Ada</span>"
+* ```
+*
+* @category constructors
+* @since 4.0.0
+*/
+const make = (f) => {
+	const Context = React.createContext(void 0);
+	const use = () => {
+		const atom = React.useContext(Context);
+		if (atom === void 0) throw new Error("ScopedAtom used outside of its Provider");
+		return atom;
+	};
+	const hasNoParameters = (factory) => factory.length === 0;
+	const Provider = (props) => {
+		const atom = React.useRef(null);
+		if (atom.current === null) {
+			if (hasNoParameters(f)) atom.current = f();
+			else if (props.value !== void 0) atom.current = f(props.value);
+			else throw new Error("ScopedAtom Provider requires a value");
+		}
+		return React.createElement(Context.Provider, { value: atom.current }, props.children);
+	};
+	return {
+		[TypeId]: TypeId,
+		use,
+		Provider,
+		Context
+	};
+};
+//#endregion
+export { HydrationBoundary, RegistryContext, RegistryProvider, TypeId, make, scheduleTask, useAtom, useAtomInitialValues, useAtomMount, useAtomRef, useAtomRefProp, useAtomRefPropValue, useAtomRefresh, useAtomSet, useAtomSetResult, useAtomSubscribe, useAtomSuspense, useAtomUpdate, useAtomValue };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@systemfsoftware/effect-atom-react",
+  "license": "Apache-2.0",
+  "version": "0.5.0",
+  "author": "Ryan Lee <drdgvhbh@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/systemfsoftware/systemfsoftware.git",
+    "directory": "packages/effect-atom/atom-react"
+  },
+  "homepage": "https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/effect-atom/atom-react#readme",
+  "bugs": "https://github.com/systemfsoftware/systemfsoftware/issues",
+  "description": "React bindings for effect-atom — forked under systemfsoftware from tim-smart/effect-atom.",
+  "keywords": [
+    "effect",
+    "effect-ts",
+    "atom",
+    "react",
+    "reactive",
+    "state"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@systemfsoftware/effect-atom": "^0.5.3"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.108",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "scheduler": "*"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-rc.108",
+    "@systemfsoftware/arethetypeswrong-cli": "^1.1.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@types/scheduler": "^0.26.0",
+    "@vitest/browser": "4.1.10",
+    "@vitest/browser-playwright": "4.1.10",
+    "@vitest/coverage-istanbul": "4.1.10",
+    "effect": "4.0.0-rc.108",
+    "oxlint": "^1.77.0",
+    "playwright": "1.62.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-error-boundary": "^6.1.2",
+    "rimraf": "^6.1.3",
+    "scheduler": "^0.27.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^7",
+    "vitest": "^4.1.10",
+    "@systemfsoftware/oxlint-config": "^0.1.0",
+    "@systemfsoftware/tsconfig": "^1.3.1",
+    "@systemfsoftware/vitest-config": "^0.1.0",
+    "@systemfsoftware/effect-gherkin-spec": "^0.5.1"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsdown && pnpm dts:check",
+    "typecheck": "tsc --noEmit --incremental",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "f=${OXLINT_FORMAT:-${AGENT:+agent}}; oxlint . --config oxlint.config.ts --format=${f:-default}",
+    "lint:tsgo": "effect-tsgo diagnostics --project tsconfig.json --format ${TSGO_FORMAT:-text}",
+    "attw": "attw --pack .",
+    "dts:check": "tsc --noEmit -p tsconfig.dts.json"
+  }
+}