@phreshos/react 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# `@phreshos/react`
+
+The React SDK adapts `@phreshos/client` to React. It is not another domain
+authority and does not define Program, Process, Endpoint, Client, Server, or
+Window objects.
+
+## Package status
+
+This package is one component of a larger architecture that is still under
+active testing. The architecture's components will be released in stages as
+their contracts and integrations are verified.
+
+`@phreshos/react` is not intended to be used on its own. It adapts the Client
+SDK to React and therefore requires both `@phreshos/client` and React as peer
+dependencies.
+
+It provides two kinds of adapter:
+
+- `CurrentProvider` resolves the Client SDK's current Program, Process, parent,
+  and Window, then exposes them synchronously through `useProgram()`,
+  `useProcess()`, `useParent()`, and `useWindow()`.
+- `useSubscribe()` and `useObserve()` own persistent ordinary-event
+  registrations for one mounted React consumer.
+- `useObserveAsks()` adapts an Endpoint traffic surface's question observation,
+  while `useObserveAnswers()` adapts a Server traffic surface's answer
+  observation.
+
+All four hooks retain the latest value returned by their projector.
+
+```tsx
+import { current } from "@phreshos/client"
+import {
+  CurrentProvider,
+  useProgram,
+  useSubscribe
+} from "@phreshos/react"
+
+function Counter() {
+  const program = useProgram()
+
+  const count = useSubscribe(current, "count", message => {
+    return Number(message.payload)
+  })
+
+  return <p>{program.name}: {count ?? 0}</p>
+}
+
+export default function App() {
+  return (
+    <CurrentProvider fallback={<p>Loading…</p>} waitServer>
+      <Counter />
+    </CurrentProvider>
+  )
+}
+```
+
+Each hook calls the registration's returned cleanup when the component no
+longer consumes it. Projectors may return a value or Promise; only the latest
+invocation may update the hook state. Projector failures are never converted
+into communication, logged, or suppressed by the SDK; they remain local to the
+React application.
+
+React is a peer dependency, so this package never installs or bundles a second
+copy into an application.

package/dist/current-provider.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import { type Process, type Program, type Window } from "@phreshos/client";
+/**
+ * Resolves the current domain handles before rendering its children.
+ *
+ * The provider owns no domain state. It only turns asynchronous Client SDK
+ * navigation into synchronous React context for the hooks below it.
+ */
+export default function CurrentProvider({ children, fallback, waitServer }: CurrentProviderProperties): string | number | bigint | boolean | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").FunctionComponentElement<import("react").ProviderProps<Readonly<{
+    program: Program;
+    process: Process;
+    parent: Process | null;
+    window: Window;
+}> | null>> | null | undefined;
+/** Returns the current Program from the nearest {@link CurrentProvider}. */
+export declare function useProgram(): Program;
+/** Returns the current Process from the nearest {@link CurrentProvider}. */
+export declare function useProcess(): Process;
+/** Returns the current Process's visible parent from the nearest provider. */
+export declare function useParent(): Process | null;
+/** Returns the current Window from the nearest {@link CurrentProvider}. */
+export declare function useWindow(): Window;
+/** Properties accepted by {@link CurrentProvider}. */
+export interface CurrentProviderProperties {
+    /** Content rendered after every current handle has resolved. */
+    readonly children: ReactNode;
+    /** Content rendered while current handles or optional Server readiness resolve. */
+    readonly fallback: ReactNode;
+    /**
+     * Waits for the Process's Server before rendering children.
+     * `true` uses the default ten-second deadline; a number sets milliseconds.
+     */
+    readonly waitServer?: boolean | number;
+}

package/dist/current-provider.js

@@ -0,0 +1,64 @@
+import { createContext, createElement, useContext, useEffect, useState } from "react";
+import { current } from "@phreshos/client";
+const CurrentContext = createContext(null);
+/**
+ * Resolves the current domain handles before rendering its children.
+ *
+ * The provider owns no domain state. It only turns asynchronous Client SDK
+ * navigation into synchronous React context for the hooks below it.
+ */
+export default function CurrentProvider({ children, fallback, waitServer = false }) {
+    const [resolution, setResolution] = useState({ status: "pending" });
+    useEffect(() => {
+        let active = true;
+        setResolution({ status: "pending" });
+        void resolveCurrent(waitServer).then(value => {
+            if (active)
+                setResolution({ status: "ready", value });
+        }, error => {
+            if (active)
+                setResolution({ status: "error", error });
+        });
+        return () => { active = false; };
+    }, [waitServer]);
+    if (resolution.status === "pending")
+        return fallback;
+    if (resolution.status === "error")
+        throw resolution.error;
+    return createElement(CurrentContext.Provider, { value: resolution.value }, children);
+}
+async function resolveCurrent(waitServer) {
+    const serverReady = typeof waitServer === "number"
+        ? current.server.waitReady(waitServer)
+        : waitServer ? current.server.waitReady() : undefined;
+    const [program, process, parent] = await Promise.all([
+        current.program(),
+        current.process(),
+        current.parent(),
+        serverReady
+    ]);
+    const window = await current.window();
+    return { program, process, parent, window };
+}
+/** Returns the current Program from the nearest {@link CurrentProvider}. */
+export function useProgram() {
+    return useCurrent().program;
+}
+/** Returns the current Process from the nearest {@link CurrentProvider}. */
+export function useProcess() {
+    return useCurrent().process;
+}
+/** Returns the current Process's visible parent from the nearest provider. */
+export function useParent() {
+    return useCurrent().parent;
+}
+/** Returns the current Window from the nearest {@link CurrentProvider}. */
+export function useWindow() {
+    return useCurrent().window;
+}
+function useCurrent() {
+    const value = useContext(CurrentContext);
+    if (!value)
+        throw new Error("Current hooks must be used inside CurrentProvider");
+    return value;
+}

package/dist/event-result.d.ts

@@ -0,0 +1,19 @@
+import type { Cleanup } from "@phreshos/client";
+/** A persistent SDK registration consumed by the React adapter. */
+export type Connect<Message> = (receive: (message: Message) => void) => Cleanup;
+/** Retains only the latest projected event value for one mounted hook. */
+export default function useEventResult<Message, Result>(connect: Connect<Message>, project: (message: Message) => Result): Awaited<Result> | undefined;
+/** Bridges one persistent SDK registration into a React external store. */
+export declare class EventResult<Message> {
+    project: (message: Message) => unknown;
+    private readonly connect;
+    private readonly listeners;
+    private value;
+    private stop;
+    private invocation;
+    constructor(connect: Connect<Message>);
+    readonly snapshot: () => unknown;
+    readonly subscribe: (listener: () => void) => () => void;
+    private readonly receive;
+    private update;
+}

package/dist/event-result.js

@@ -0,0 +1,58 @@
+import { useEffectEvent, useMemo, useSyncExternalStore } from "react";
+/** Retains only the latest projected event value for one mounted hook. */
+export default function useEventResult(connect, project) {
+    const latestProject = useEffectEvent(project);
+    const state = useMemo(() => new EventResult(connect), [connect]);
+    state.project = latestProject;
+    return useSyncExternalStore(state.subscribe, state.snapshot, state.snapshot);
+}
+/** Bridges one persistent SDK registration into a React external store. */
+export class EventResult {
+    project = () => undefined;
+    connect;
+    listeners = new Set();
+    value;
+    stop = null;
+    invocation = 0;
+    constructor(connect) {
+        this.connect = connect;
+    }
+    snapshot = () => this.value;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        if (!this.stop)
+            this.stop = this.connect(this.receive);
+        return () => {
+            this.listeners.delete(listener);
+            if (this.listeners.size > 0)
+                return;
+            this.invocation++;
+            this.stop?.();
+            this.stop = null;
+        };
+    };
+    receive = (message) => {
+        const invocation = ++this.invocation;
+        const result = this.project(message);
+        if (isPromiseLike(result)) {
+            void Promise.resolve(result).then(value => {
+                if (invocation === this.invocation)
+                    this.update(value);
+            });
+        }
+        else
+            this.update(result);
+    };
+    update(value) {
+        if (Object.is(this.value, value))
+            return;
+        this.value = value;
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+function isPromiseLike(value) {
+    return (typeof value === "object" && value !== null || typeof value === "function")
+        && "then" in value
+        && typeof value.then === "function";
+}

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+export { default as CurrentProvider, useParent, useProcess, useProgram, useWindow, type CurrentProviderProperties } from "./current-provider.js";
+export { default as useSubscribe } from "./use-subscribe.js";
+export { default as useObserve } from "./use-observe.js";
+export { default as useObserveAsks, type AskObservable } from "./use-observe-asks.js";
+export { default as useObserveAnswers, type AnswerObservable } from "./use-observe-answers.js";

package/dist/main.js

@@ -0,0 +1,5 @@
+export { default as CurrentProvider, useParent, useProcess, useProgram, useWindow } from "./current-provider.js";
+export { default as useSubscribe } from "./use-subscribe.js";
+export { default as useObserve } from "./use-observe.js";
+export { default as useObserveAsks } from "./use-observe-asks.js";
+export { default as useObserveAnswers } from "./use-observe-answers.js";

package/dist/use-observe-answers.d.ts

@@ -0,0 +1,10 @@
+import type { AnswerCapture, AnswerObserver, Cleanup } from "@phreshos/client";
+/** Any Server traffic surface capable of observing its outgoing answers. */
+export type AnswerObservable = Readonly<{
+    observeAnswers<Result = unknown>(observer: AnswerObserver<Result>): Cleanup;
+}>;
+/**
+ * Observes answers in one Server's traffic while mounted and retains the
+ * latest projected result.
+ */
+export default function useObserveAnswers<Answer, Result>(target: AnswerObservable, project: (capture: AnswerCapture<Answer>) => Result): Awaited<Result> | undefined;

package/dist/use-observe-answers.js

@@ -0,0 +1,10 @@
+import { useCallback } from "react";
+import useEventResult from "./event-result.js";
+/**
+ * Observes answers in one Server's traffic while mounted and retains the
+ * latest projected result.
+ */
+export default function useObserveAnswers(target, project) {
+    const connect = useCallback((receive) => target.observeAnswers(receive), [target]);
+    return useEventResult(connect, project);
+}

package/dist/use-observe-asks.d.ts

@@ -0,0 +1,10 @@
+import type { AskCapture, AskObserver, Cleanup } from "@phreshos/client";
+/** Any Endpoint traffic surface capable of observing its outgoing questions. */
+export type AskObservable = Readonly<{
+    observeAsks<Payload = unknown>(observer: AskObserver<Payload>): Cleanup;
+}>;
+/**
+ * Observes questions in one Endpoint's traffic while mounted and retains the
+ * latest projected result.
+ */
+export default function useObserveAsks<Payload, Result>(target: AskObservable, project: (capture: AskCapture<Payload>) => Result): Awaited<Result> | undefined;

package/dist/use-observe-asks.js

@@ -0,0 +1,10 @@
+import { useCallback } from "react";
+import useEventResult from "./event-result.js";
+/**
+ * Observes questions in one Endpoint's traffic while mounted and retains the
+ * latest projected result.
+ */
+export default function useObserveAsks(target, project) {
+    const connect = useCallback((receive) => target.observeAsks(receive), [target]);
+    return useEventResult(connect, project);
+}

package/dist/use-observe.d.ts

@@ -0,0 +1,3 @@
+import type { Captures, Subscribable } from "@phreshos/client";
+/** Observes all events while mounted and retains the latest projected result. */
+export default function useObserve<Events extends object, Fallback, Result>(target: Subscribable<Events, Fallback>, project: (capture: Captures<Events, Fallback>) => Result): Awaited<Result> | undefined;

package/dist/use-observe.js

@@ -0,0 +1,7 @@
+import { useCallback } from "react";
+import useEventResult from "./event-result.js";
+/** Observes all events while mounted and retains the latest projected result. */
+export default function useObserve(target, project) {
+    const connect = useCallback((receive) => target.observe(receive), [target]);
+    return useEventResult(connect, project);
+}

package/dist/use-subscribe.d.ts

@@ -0,0 +1,17 @@
+import type { EventMessage, EventName, Subscribable } from "@phreshos/client";
+type OpenEvent = string & {};
+type AvailableEvent<Events extends object, Fallback> = EventName<Events> | ([Fallback] extends [never] ? never : OpenEvent);
+type CompatibleEvent<Events extends object, Fallback, Narrowed> = {
+    [Event in EventName<Events>]: Narrowed extends Events[Event] ? Event : never;
+}[EventName<Events>] | ([
+    Fallback
+] extends [never] ? never : Narrowed extends Fallback ? OpenEvent : never);
+/**
+ * Subscribes while mounted and retains the latest projected result.
+ *
+ * The target supplies known message types. An explicit generic or callback
+ * annotation may narrow that type, but cannot replace it incompatibly.
+ */
+export default function useSubscribe<Narrowed, Events extends object, Fallback, Result>(target: Subscribable<Events, Fallback>, event: CompatibleEvent<Events, Fallback, Narrowed>, project: (message: Narrowed) => Result): Awaited<Result> | undefined;
+export default function useSubscribe<Events extends object, Fallback, Event extends AvailableEvent<Events, Fallback>, Result>(target: Subscribable<Events, Fallback>, event: Event, project: (message: EventMessage<Events, Fallback, Event>) => Result): Awaited<Result> | undefined;
+export {};

package/dist/use-subscribe.js

@@ -0,0 +1,9 @@
+import { useCallback } from "react";
+import useEventResult from "./event-result.js";
+export default function useSubscribe(target, event, project) {
+    const connect = useCallback((receive) => {
+        const subscribe = target.subscribe;
+        return subscribe(event, receive);
+    }, [target, event]);
+    return useEventResult(connect, project);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@phreshos/react",
+  "version": "0.1.0",
+  "description": "React adapters for the Client SDK.",
+  "type": "module",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsc --noEmit false --outDir dist --rootDir source",
+    "prepack": "node --run build"
+  },
+  "peerDependencies": {
+    "@phreshos/client": "^0.1.0",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@phreshos/client": "0.1.0",
+    "@types/react": "^19.2.18",
+    "react": "^19.2.8",
+    "typescript": "^6.0.3"
+  }
+}