rxfy-react 0.2.0 → 1.0.0

package/dist/index.d.ts

@@ -1,32 +1,82 @@
 import * as react from 'react';
-import { IEdge, StatusEnum } from 'rxfy';
-
-declare function useEdge<TData>(edge: IEdge<TData>): ({
-    type: StatusEnum.IDLE;
-} & {
-    type: StatusEnum;
-}) | ({
-    type: StatusEnum.PENDING;
-} & {
-    type: StatusEnum;
-}) | ({
-    type: StatusEnum.REJECTED;
-    error: unknown;
-} & {
-    type: StatusEnum;
-}) | ({
-    type: StatusEnum.FULFILLED;
-    value: TData;
-} & {
-    type: StatusEnum;
-});
-type IEdgeProps<TData> = {
-    edge: IEdge<TData>;
-    children: IRenderFn<TData>;
-    rejected?: IRenderFn<unknown>;
-    pending?: React.ReactNode;
+import { PropsWithChildren } from 'react';
+import { IWrapped, StatusEnum, IModelRegistry, DehydratedState, IAtom, ModelDescriptor, ModelStore, MutationDefs, QueryShapeOf, StateDescriptor } from 'rxfy';
+import { Observable } from 'rxjs';
+
+type IRenderable<TData> = React.ReactNode | ((data: TData) => React.ReactNode);
+
+type ObservableLike<T> = Observable<T> | T;
+/**
+ * Tracks an observable as an IWrapped status for rendering.
+ *
+ * Contract: `source$` must be referentially stable across renders (memoize it, e.g. from
+ * useStateData or useMemo). A new identity restarts the pipeline from PENDING — intended for
+ * genuine source changes (new params / reload), but an observable created inline in render
+ * restarts every render and never settles.
+ *
+ * Reload is not part of the status object; trigger it via the StateHandle's reload()
+ * or getAttachedReload(source$).
+ */
+declare function usePending<T>(source$: ObservableLike<T>, getDefaultValue?: () => T): IWrapped<T, StatusEnum.PENDING | StatusEnum.FULFILLED | StatusEnum.REJECTED>;
+
+type IPendingProps<T> = {
+    value$: ObservableLike<T>;
+    pending?: IRenderable<void>;
+    rejected?: IRenderable<IWrapped<T, StatusEnum.REJECTED>>;
+    children: IRenderable<T>;
+    getDefaultValue?: () => T;
+};
+declare function Pending<T>({ value$, rejected, pending, children, getDefaultValue, }: IPendingProps<T>): react.ReactNode;
+
+declare const ModelRegistryContext: react.Context<IModelRegistry | null>;
+declare function useModelRegistry(): IModelRegistry;
+
+/**
+ * Two-pass SSR for strict renderToString environments (the Apollo getDataFromTree pattern):
+ * render → await fetches that suspended into the registry's query cache → render again,
+ * until a pass completes with nothing in flight. Each waterfall level costs one extra pass.
+ */
+declare function collectStateData(registry: IModelRegistry, render: () => string): Promise<string>;
+
+/** True when the app opted into SSR — gates useStateData's server-side Suspense behavior. */
+declare const SsrContext: react.Context<boolean>;
+declare global {
+    interface Window {
+        /** Push protocol for streamed hydration chunks (see rxfy-react/next HydrationStream). */
+        __RXFY_SSR__?: DehydratedState[];
+    }
+}
+type StoreProviderProps = PropsWithChildren<{
+    /** Enables server-side fetch-and-suspend in useStateData. Pass the same value on server and client. */
+    ssr?: boolean;
+    /** Per-request registry created by server code so it can dehydrate after rendering. */
+    registry?: IModelRegistry;
+    /** Snapshot from dehydrate() for prop-based hydration (buffered/two-pass SSR). */
+    dehydratedState?: DehydratedState;
+}>;
+declare function StoreProvider({ children, ssr, registry: external, dehydratedState }: StoreProviderProps): react.JSX.Element;
+
+/**
+ * Binds an IAtom (entity handle, field Lens, or plain Atom) to React as `[value, set]`.
+ * `atom$` must be referentially stable across renders — memoize it (e.g. a Lens via useMemo).
+ */
+declare function useAtom<T>(atom$: IAtom<T>): [T, (value: T) => void];
+
+declare function useModelStore<T>(descriptor: ModelDescriptor<T>): ModelStore<T>;
+
+declare function useObservable<T>(observable: Observable<T>, initialValue: T): T;
+declare function useObservable<T>(observable: Observable<T>): T | undefined;
+
+type BoundMutations<TShape, TMutations extends MutationDefs<TShape>> = {
+    [K in keyof TMutations]: TMutations[K] extends (prev: TShape, ...args: infer A) => TShape ? (...args: A) => void : never;
+};
+type StateHandle<TShape, TMutations extends MutationDefs<TShape> = Record<never, never>> = {
+    /** Normalized query state — entity ids only. Read entity data through model stores. */
+    readonly data$: Observable<QueryShapeOf<TShape>>;
+    readonly set: (value: TShape | ((prev: TShape) => TShape)) => void;
+    readonly reload: () => void;
+    readonly mutations: BoundMutations<TShape, TMutations>;
 };
-declare function Edge<TData>({ edge, children, rejected, pending }: IEdgeProps<TData>): react.ReactNode;
-type IRenderFn<TData> = React.ReactNode | ((data: TData) => React.ReactNode);
+declare function useStateData<TParams, TShape, TMutations extends MutationDefs<TShape>>(state: StateDescriptor<TParams, TShape, TMutations>, fetchFn: (params: TParams, signal: AbortSignal) => Promise<TShape>, params: TParams): StateHandle<TShape, TMutations>;
 
-export { Edge, type IRenderFn, useEdge };
+export { type BoundMutations, type IPendingProps, ModelRegistryContext, type ObservableLike, Pending, SsrContext, type StateHandle, StoreProvider, type StoreProviderProps, collectStateData, useAtom, useModelRegistry, useModelStore, useObservable, usePending, useStateData };