rxfy 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Observable, BehaviorSubject } from 'rxjs';
-import PQueue from 'p-queue';
+import { z } from 'zod';
 
 type IAtom<T> = Observable<T> & {
     get: () => T;
@@ -15,6 +15,47 @@ declare class Atom<T> extends Observable<T> implements IAtom<T> {
 }
 declare function createAtom<T>(value: T): Atom<T>;
 
+type ILens<TSource, TTarget> = {
+    get: (source: TSource) => TTarget;
+    set: (current: TTarget, source: TSource) => TSource;
+};
+declare class Lens<TSource, TTarget> extends Observable<TTarget> implements IAtom<TTarget> {
+    private subject$;
+    private sub;
+    private subCount;
+    private source$;
+    private lens;
+    constructor(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>);
+    set: (value: TTarget) => void;
+    get: () => TTarget;
+    modify: (fn: (val: TTarget) => TTarget) => void;
+}
+declare function createLens<TSource, TTarget>(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>): Lens<TSource, TTarget>;
+declare function keyLens<TSource, TTarget extends keyof TSource>(key: TTarget): ILens<TSource, TSource[TTarget]>;
+
+/** Extracts the key type from an entity's `id` field; falls back to `string` for plain string IDs. */
+type EntityKey<T> = T extends {
+    id: infer TKey extends string;
+} ? TKey : string;
+type ModelDescriptor<T, TKey extends string = string> = {
+    readonly _key: symbol;
+    /** Stable string identity for SSR dehydration — symbols cannot cross the server/client boundary. */
+    readonly name?: string;
+    readonly schema: z.ZodType<T, z.ZodTypeDef, any>;
+    readonly getKey: (item: T) => TKey;
+};
+type FieldDescriptor<TShape> = {
+    readonly _shape?: TShape;
+    readonly kind: "single" | "array";
+    readonly model: ModelDescriptor<any, any>;
+};
+declare function createModel<TOutput, TKey extends string, TDef extends z.ZodTypeDef = z.ZodTypeDef, TInput = TOutput>(schema: z.ZodType<TOutput, TDef, TInput>, opts: {
+    getKey: (item: TOutput) => TKey;
+    name?: string;
+}): ModelDescriptor<TOutput, TKey>;
+declare function array<T, TKey extends string>(model: ModelDescriptor<T, TKey>): FieldDescriptor<T[]>;
+declare function single<T, TKey extends string>(model: ModelDescriptor<T, TKey>): FieldDescriptor<T>;
+
 declare enum StatusEnum {
     IDLE = "IDLE",
     PENDING = "PENDING",
@@ -44,55 +85,154 @@ declare function createPending<Result>(): IWrapped<Result, StatusEnum.PENDING>;
 declare function createFulfilled<Result>(value: Result): IWrapped<Result, StatusEnum.FULFILLED>;
 declare function createRejected<Result>(error: unknown): IWrapped<Result, StatusEnum.REJECTED>;
 
-type IBranded<TBrand, TData> = {
-    brand: TBrand;
-    value: TData;
+type QueryCache = {
+    /** Get-or-create the query's status Atom, seeded IDLE. Shared per key → dedup. Note: TValue is an unchecked assertion — the cache stores Atom<IWrapped<unknown>> internally, matching how peek works. */
+    getQuery: <TValue = unknown>(key: string) => Atom<IWrapped<TValue>>;
+    /** Current value without creating a cell — used by serialization and sync reads. */
+    peek: <TValue = unknown>(key: string) => IWrapped<TValue> | undefined;
+    delete: (key: string) => void;
+    /** Terminal-state entries (FULFILLED/REJECTED) for serialization. */
+    entries: () => [string, IWrapped<unknown>][];
+    /** In-flight promise slot — SSR Suspense throws and server-side request dedup. Never serialized. */
+    getPromise: (key: string) => Promise<unknown> | undefined;
+    setPromise: (key: string, promise: Promise<unknown>) => void;
+    inflight: () => Promise<unknown>[];
 };
-declare function toBranded<TBrand extends string, TData>(brand: TBrand, value: TData): IBranded<TBrand, TData>;
-declare function isBranded<TBrand extends string, TData>(brand: TBrand, val: any): val is IBranded<TBrand, TData>;
-type IEdgeState<TData> = IWrapped<TData>;
-type IEdgeJS<TData> = IBranded<"edge", IEdgeState<TData>>;
-type IEdge<TData> = {
-    subject$: IAtom<IEdgeState<TData>>;
-    toObservable: () => Observable<TData>;
-    next: () => Promise<IWrapped<TData, StatusEnum.FULFILLED | StatusEnum.REJECTED>>;
+declare function createQueryCache(): QueryCache;
+
+type ModelStore<T> = {
+    get: (key: EntityKey<T>) => Observable<T>;
+    set: (key: string, val: T) => void;
+    setMany: (items: T[]) => void;
+    /** Synchronous read of the latest value — used by denormalization and dehydration. */
+    getValue: (key: string) => T | undefined;
+    valueEntries: () => [string, T][];
+    /**
+     * Writable handle over a single entity's cell — for field Lenses and form binding.
+     * Assumes the entity is already loaded; returns `undefined` typed as `T` if the key has not been set.
+     */
+    entity: (key: EntityKey<T>) => IAtom<T>;
+    /**
+     * Emits a key the first time its entity becomes present (the first `set`); updates to an existing
+     * entity do not re-emit. New subscribers replay the keys already present, so a late subscriber
+     * still learns about everything in the store. Lets a live-update layer track exactly what the
+     * store holds without each query wiring its ids in by hand.
+     */
+    added$: Observable<string>;
 };
-declare function createEdge<TData>(state$: IAtom<IEdgeState<TData>>, queue: PQueue, loader: () => Observable<TData>): IEdge<TData>;
+type IModelRegistry = {
+    model: <T>(descriptor: ModelDescriptor<T>) => ModelStore<T>;
+    /** SSR query cache — fulfilled/rejected entries keyed by state key + params. */
+    queries: QueryCache;
+    namedStores: () => ReadonlyMap<string, ModelStore<any>>;
+    stores: () => {
+        descriptor: ModelDescriptor<any>;
+        store: ModelStore<any>;
+    }[];
+    /** Queue entities for a named model; seeds the store now if it exists, or on first creation otherwise. */
+    stashHydration: (name: string, entities: Record<string, unknown>) => void;
+    /**
+     * Every entity added to any *named* store, tagged with that store's `name` (the half of a
+     * `name:key` topic). Unnamed stores are skipped — there's no name to address them by. Replays
+     * what's already in the registry to new subscribers, and follows stores created after subscribe.
+     * A live-update client can drive its subscriptions straight off this instead of per-query wiring.
+     */
+    added$: Observable<{
+        name: string;
+        key: string;
+    }>;
+};
+declare function createModelStore<T>(descriptor: ModelDescriptor<T>): ModelStore<T>;
+declare function createModelRegistry(): IModelRegistry;
+
+/** Deterministic JSON.stringify — object keys sorted recursively so server and client produce identical cache keys. */
+declare function stableStringify(value: unknown): string;
 
-type IMapJS = IBranded<"map", {
-    [K in string]: IMapJS | IEdgeJS<unknown>;
-}>;
-type IStoreState = {
-    [K in string]: IStoreStateJS | IMapJS | IEdgeJS<unknown>;
+type SerializedError = {
+    name: string;
+    message: string;
 };
-type IStoreStateJS = IBranded<"store", IStoreState>;
-type IFactory<TData> = {
-    get: (key: string) => IEdge<TData>;
+declare function serializeError(error: unknown): SerializedError;
+declare function rehydrateError(serialized: SerializedError): Error;
+/** JSON for inline <script> embedding — escapes "<" so payloads cannot break out of the script tag. */
+declare function serializeForHtml(value: unknown): string;
+/** Wire form of a settled query — only terminal states cross the server/client boundary. */
+type SerializedWrapped<TValue = unknown> = {
+    type: StatusEnum.FULFILLED;
+    value: TValue;
+} | {
+    type: StatusEnum.REJECTED;
+    error: SerializedError;
 };
-type IStore<TState extends IStoreStateJS> = {
-    state$: IAtom<TState>;
-    collect: () => Promise<void>;
-    node: (name: string) => IStore<IStoreStateJS>;
-    factory: <TData>(name: string, loader: (key: string) => Observable<TData>) => IFactory<TData>;
-    factoryBatch: <TData>(name: string, batch: (key: string[]) => Observable<Record<string, TData>>) => IFactory<TData>;
+/** In-memory IWrapped → wire form. Returns undefined for IDLE/PENDING (never serialized). */
+declare function serializeWrapped<TValue>(wrapped: IWrapped<TValue>): SerializedWrapped<TValue> | undefined;
+/** Wire form → in-memory IWrapped carrying a live Error. */
+declare function deserializeWrapped<TValue>(entry: SerializedWrapped<TValue>): IWrapped<TValue>;
+
+type DehydratedState = {
+    queries: Record<string, SerializedWrapped>;
+    models: Record<string, Record<string, unknown>>;
 };
-declare function createState(val: IStoreState): IStoreStateJS;
-declare function createStore<TState extends IStoreStateJS>(queue: PQueue, state$: IAtom<TState>): IStore<TState>;
+/** Serializes the registry's query cache (ids) and named model stores (entities) to a JSON-safe snapshot. */
+declare function dehydrate(registry: IModelRegistry): DehydratedState;
+/** Ingests a dehydrated snapshot: model entities → stores (via stash), query entries → cache. */
+declare function hydrate(registry: IModelRegistry, state: DehydratedState): void;
+/**
+ * Complete inline <script> tag pushing a snapshot onto window.__RXFY_SSR__ — the queue
+ * StoreProvider drains automatically on the client, so no client-side wiring is needed.
+ * Inject it into the served HTML before the client entry script.
+ */
+declare function hydrationScript(state: DehydratedState): string;
 
-type ILens<TSource, TTarget> = {
-    get: (source: TSource) => TTarget;
-    set: (current: TTarget, source: TSource) => TSource;
+/**
+ * Marks an observable as emitting synchronously on subscribe — safe for usePending's render-time probe.
+ * Mutates the target via a symbol property; the target must be an extensible object (rxfy-created
+ * observables always are). Intended for rxfy-internal call sites, not arbitrary user observables.
+ */
+declare function markSync<T extends object>(target: T): T;
+/** True if the observable was flagged by markSync as emitting synchronously on subscribe. */
+declare function isSyncMarked(target: object): boolean;
+/** Attaches the owning handle's reload() so consumers can invalidate the query cache via getAttachedReload. */
+declare function attachReload<T extends object>(target: T, reload: () => void): T;
+/** Returns the reload callback set by attachReload, if any. */
+declare function getAttachedReload(target: object): (() => void) | undefined;
+
+type FieldsMap = Record<string, FieldDescriptor<any>>;
+type ShapeFromFields<T extends FieldsMap> = {
+    [K in keyof T]: T[K] extends FieldDescriptor<infer S> ? S : never;
 };
-declare class Lens<TSource, TTarget> extends Observable<TTarget> implements IAtom<TTarget> {
-    private subject$;
-    private sub;
-    private subCount;
-    constructor(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>);
-    set: (value: TTarget) => void;
-    get: () => TTarget;
-    modify: (fn: (val: TTarget) => TTarget) => void;
-}
-declare function createLens<TSource, TTarget>(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>): Lens<TSource, TTarget>;
-declare function keyLens<TSource, TTarget extends keyof TSource>(key: TTarget): ILens<TSource, TSource[TTarget]>;
+/** The normalized shape data$ emits: array fields become entity key arrays, single fields become entity keys. */
+type QueryShapeOf<TShape> = {
+    [K in keyof TShape]: TShape[K] extends readonly (infer Item)[] ? EntityKey<Item>[] : EntityKey<TShape[K]>;
+};
+type MutationDefs<TShape> = {
+    [key: string]: (prev: TShape, ...args: any[]) => TShape;
+};
+type StateDescriptor<TParams, TShape, TMutations extends MutationDefs<TShape> = Record<never, never>> = {
+    /** Stable string identity for the SSR query cache. States without a key opt out of SSR caching. */
+    readonly key?: string;
+    readonly paramsSchema: z.ZodType<TParams, z.ZodTypeDef, any>;
+    readonly fields: {
+        [K in keyof TShape]: FieldDescriptor<TShape[K]>;
+    };
+    readonly mutations: TMutations;
+};
+declare function defineState<TParams, TFields extends FieldsMap>(def: {
+    key?: string;
+    params: z.ZodType<TParams, z.ZodTypeDef, any>;
+    model: TFields;
+    mutations?: undefined;
+}): StateDescriptor<TParams, ShapeFromFields<TFields>, Record<never, never>>;
+declare function defineState<TParams, TFields extends FieldsMap, TMutations extends MutationDefs<ShapeFromFields<TFields>>>(def: {
+    key?: string;
+    params: z.ZodType<TParams, z.ZodTypeDef, any>;
+    model: TFields;
+    mutations: TMutations;
+}): StateDescriptor<TParams, ShapeFromFields<TFields>, TMutations>;
+
+/** Splits a denormalized fetch result: entities → model stores, ids → returned query shape. */
+declare function normalizeResult<TShape>(registry: IModelRegistry, fields: FieldsMap, value: TShape): QueryShapeOf<TShape>;
+/** Rebuilds the fetch shape from ids by reading store value maps — reducers always see the freshest entities. */
+declare function denormalizeValue<TShape>(registry: IModelRegistry, fields: FieldsMap, ids: QueryShapeOf<TShape>): TShape;
 
-export { Atom, type IAtom, type IBranded, type IEdge, type IEdgeJS, type IEdgeState, type ILens, type IWrapped, Lens, StatusEnum, createAtom, createEdge, createFulfilled, createIdle, createLens, createPending, createRejected, createState, createStore, isBranded, keyLens, toBranded };
+export { Atom, type DehydratedState, type EntityKey, type FieldDescriptor, type FieldsMap, type IAtom, type ILens, type IModelRegistry, type IWrapped, Lens, type ModelDescriptor, type ModelStore, type MutationDefs, type QueryCache, type QueryShapeOf, type SerializedError, type SerializedWrapped, type ShapeFromFields, type StateDescriptor, StatusEnum, array, attachReload, createAtom, createFulfilled, createIdle, createLens, createModel, createModelRegistry, createModelStore, createPending, createQueryCache, createRejected, defineState, dehydrate, denormalizeValue, deserializeWrapped, getAttachedReload, hydrate, hydrationScript, isSyncMarked, keyLens, markSync, normalizeResult, rehydrateError, serializeError, serializeForHtml, serializeWrapped, single, stableStringify };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Observable, BehaviorSubject } from 'rxjs';
-import PQueue from 'p-queue';
+import { z } from 'zod';
 
 type IAtom<T> = Observable<T> & {
     get: () => T;
@@ -15,6 +15,47 @@ declare class Atom<T> extends Observable<T> implements IAtom<T> {
 }
 declare function createAtom<T>(value: T): Atom<T>;
 
+type ILens<TSource, TTarget> = {
+    get: (source: TSource) => TTarget;
+    set: (current: TTarget, source: TSource) => TSource;
+};
+declare class Lens<TSource, TTarget> extends Observable<TTarget> implements IAtom<TTarget> {
+    private subject$;
+    private sub;
+    private subCount;
+    private source$;
+    private lens;
+    constructor(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>);
+    set: (value: TTarget) => void;
+    get: () => TTarget;
+    modify: (fn: (val: TTarget) => TTarget) => void;
+}
+declare function createLens<TSource, TTarget>(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>): Lens<TSource, TTarget>;
+declare function keyLens<TSource, TTarget extends keyof TSource>(key: TTarget): ILens<TSource, TSource[TTarget]>;
+
+/** Extracts the key type from an entity's `id` field; falls back to `string` for plain string IDs. */
+type EntityKey<T> = T extends {
+    id: infer TKey extends string;
+} ? TKey : string;
+type ModelDescriptor<T, TKey extends string = string> = {
+    readonly _key: symbol;
+    /** Stable string identity for SSR dehydration — symbols cannot cross the server/client boundary. */
+    readonly name?: string;
+    readonly schema: z.ZodType<T, z.ZodTypeDef, any>;
+    readonly getKey: (item: T) => TKey;
+};
+type FieldDescriptor<TShape> = {
+    readonly _shape?: TShape;
+    readonly kind: "single" | "array";
+    readonly model: ModelDescriptor<any, any>;
+};
+declare function createModel<TOutput, TKey extends string, TDef extends z.ZodTypeDef = z.ZodTypeDef, TInput = TOutput>(schema: z.ZodType<TOutput, TDef, TInput>, opts: {
+    getKey: (item: TOutput) => TKey;
+    name?: string;
+}): ModelDescriptor<TOutput, TKey>;
+declare function array<T, TKey extends string>(model: ModelDescriptor<T, TKey>): FieldDescriptor<T[]>;
+declare function single<T, TKey extends string>(model: ModelDescriptor<T, TKey>): FieldDescriptor<T>;
+
 declare enum StatusEnum {
     IDLE = "IDLE",
     PENDING = "PENDING",
@@ -44,55 +85,154 @@ declare function createPending<Result>(): IWrapped<Result, StatusEnum.PENDING>;
 declare function createFulfilled<Result>(value: Result): IWrapped<Result, StatusEnum.FULFILLED>;
 declare function createRejected<Result>(error: unknown): IWrapped<Result, StatusEnum.REJECTED>;
 
-type IBranded<TBrand, TData> = {
-    brand: TBrand;
-    value: TData;
+type QueryCache = {
+    /** Get-or-create the query's status Atom, seeded IDLE. Shared per key → dedup. Note: TValue is an unchecked assertion — the cache stores Atom<IWrapped<unknown>> internally, matching how peek works. */
+    getQuery: <TValue = unknown>(key: string) => Atom<IWrapped<TValue>>;
+    /** Current value without creating a cell — used by serialization and sync reads. */
+    peek: <TValue = unknown>(key: string) => IWrapped<TValue> | undefined;
+    delete: (key: string) => void;
+    /** Terminal-state entries (FULFILLED/REJECTED) for serialization. */
+    entries: () => [string, IWrapped<unknown>][];
+    /** In-flight promise slot — SSR Suspense throws and server-side request dedup. Never serialized. */
+    getPromise: (key: string) => Promise<unknown> | undefined;
+    setPromise: (key: string, promise: Promise<unknown>) => void;
+    inflight: () => Promise<unknown>[];
 };
-declare function toBranded<TBrand extends string, TData>(brand: TBrand, value: TData): IBranded<TBrand, TData>;
-declare function isBranded<TBrand extends string, TData>(brand: TBrand, val: any): val is IBranded<TBrand, TData>;
-type IEdgeState<TData> = IWrapped<TData>;
-type IEdgeJS<TData> = IBranded<"edge", IEdgeState<TData>>;
-type IEdge<TData> = {
-    subject$: IAtom<IEdgeState<TData>>;
-    toObservable: () => Observable<TData>;
-    next: () => Promise<IWrapped<TData, StatusEnum.FULFILLED | StatusEnum.REJECTED>>;
+declare function createQueryCache(): QueryCache;
+
+type ModelStore<T> = {
+    get: (key: EntityKey<T>) => Observable<T>;
+    set: (key: string, val: T) => void;
+    setMany: (items: T[]) => void;
+    /** Synchronous read of the latest value — used by denormalization and dehydration. */
+    getValue: (key: string) => T | undefined;
+    valueEntries: () => [string, T][];
+    /**
+     * Writable handle over a single entity's cell — for field Lenses and form binding.
+     * Assumes the entity is already loaded; returns `undefined` typed as `T` if the key has not been set.
+     */
+    entity: (key: EntityKey<T>) => IAtom<T>;
+    /**
+     * Emits a key the first time its entity becomes present (the first `set`); updates to an existing
+     * entity do not re-emit. New subscribers replay the keys already present, so a late subscriber
+     * still learns about everything in the store. Lets a live-update layer track exactly what the
+     * store holds without each query wiring its ids in by hand.
+     */
+    added$: Observable<string>;
 };
-declare function createEdge<TData>(state$: IAtom<IEdgeState<TData>>, queue: PQueue, loader: () => Observable<TData>): IEdge<TData>;
+type IModelRegistry = {
+    model: <T>(descriptor: ModelDescriptor<T>) => ModelStore<T>;
+    /** SSR query cache — fulfilled/rejected entries keyed by state key + params. */
+    queries: QueryCache;
+    namedStores: () => ReadonlyMap<string, ModelStore<any>>;
+    stores: () => {
+        descriptor: ModelDescriptor<any>;
+        store: ModelStore<any>;
+    }[];
+    /** Queue entities for a named model; seeds the store now if it exists, or on first creation otherwise. */
+    stashHydration: (name: string, entities: Record<string, unknown>) => void;
+    /**
+     * Every entity added to any *named* store, tagged with that store's `name` (the half of a
+     * `name:key` topic). Unnamed stores are skipped — there's no name to address them by. Replays
+     * what's already in the registry to new subscribers, and follows stores created after subscribe.
+     * A live-update client can drive its subscriptions straight off this instead of per-query wiring.
+     */
+    added$: Observable<{
+        name: string;
+        key: string;
+    }>;
+};
+declare function createModelStore<T>(descriptor: ModelDescriptor<T>): ModelStore<T>;
+declare function createModelRegistry(): IModelRegistry;
+
+/** Deterministic JSON.stringify — object keys sorted recursively so server and client produce identical cache keys. */
+declare function stableStringify(value: unknown): string;
 
-type IMapJS = IBranded<"map", {
-    [K in string]: IMapJS | IEdgeJS<unknown>;
-}>;
-type IStoreState = {
-    [K in string]: IStoreStateJS | IMapJS | IEdgeJS<unknown>;
+type SerializedError = {
+    name: string;
+    message: string;
 };
-type IStoreStateJS = IBranded<"store", IStoreState>;
-type IFactory<TData> = {
-    get: (key: string) => IEdge<TData>;
+declare function serializeError(error: unknown): SerializedError;
+declare function rehydrateError(serialized: SerializedError): Error;
+/** JSON for inline <script> embedding — escapes "<" so payloads cannot break out of the script tag. */
+declare function serializeForHtml(value: unknown): string;
+/** Wire form of a settled query — only terminal states cross the server/client boundary. */
+type SerializedWrapped<TValue = unknown> = {
+    type: StatusEnum.FULFILLED;
+    value: TValue;
+} | {
+    type: StatusEnum.REJECTED;
+    error: SerializedError;
 };
-type IStore<TState extends IStoreStateJS> = {
-    state$: IAtom<TState>;
-    collect: () => Promise<void>;
-    node: (name: string) => IStore<IStoreStateJS>;
-    factory: <TData>(name: string, loader: (key: string) => Observable<TData>) => IFactory<TData>;
-    factoryBatch: <TData>(name: string, batch: (key: string[]) => Observable<Record<string, TData>>) => IFactory<TData>;
+/** In-memory IWrapped → wire form. Returns undefined for IDLE/PENDING (never serialized). */
+declare function serializeWrapped<TValue>(wrapped: IWrapped<TValue>): SerializedWrapped<TValue> | undefined;
+/** Wire form → in-memory IWrapped carrying a live Error. */
+declare function deserializeWrapped<TValue>(entry: SerializedWrapped<TValue>): IWrapped<TValue>;
+
+type DehydratedState = {
+    queries: Record<string, SerializedWrapped>;
+    models: Record<string, Record<string, unknown>>;
 };
-declare function createState(val: IStoreState): IStoreStateJS;
-declare function createStore<TState extends IStoreStateJS>(queue: PQueue, state$: IAtom<TState>): IStore<TState>;
+/** Serializes the registry's query cache (ids) and named model stores (entities) to a JSON-safe snapshot. */
+declare function dehydrate(registry: IModelRegistry): DehydratedState;
+/** Ingests a dehydrated snapshot: model entities → stores (via stash), query entries → cache. */
+declare function hydrate(registry: IModelRegistry, state: DehydratedState): void;
+/**
+ * Complete inline <script> tag pushing a snapshot onto window.__RXFY_SSR__ — the queue
+ * StoreProvider drains automatically on the client, so no client-side wiring is needed.
+ * Inject it into the served HTML before the client entry script.
+ */
+declare function hydrationScript(state: DehydratedState): string;
 
-type ILens<TSource, TTarget> = {
-    get: (source: TSource) => TTarget;
-    set: (current: TTarget, source: TSource) => TSource;
+/**
+ * Marks an observable as emitting synchronously on subscribe — safe for usePending's render-time probe.
+ * Mutates the target via a symbol property; the target must be an extensible object (rxfy-created
+ * observables always are). Intended for rxfy-internal call sites, not arbitrary user observables.
+ */
+declare function markSync<T extends object>(target: T): T;
+/** True if the observable was flagged by markSync as emitting synchronously on subscribe. */
+declare function isSyncMarked(target: object): boolean;
+/** Attaches the owning handle's reload() so consumers can invalidate the query cache via getAttachedReload. */
+declare function attachReload<T extends object>(target: T, reload: () => void): T;
+/** Returns the reload callback set by attachReload, if any. */
+declare function getAttachedReload(target: object): (() => void) | undefined;
+
+type FieldsMap = Record<string, FieldDescriptor<any>>;
+type ShapeFromFields<T extends FieldsMap> = {
+    [K in keyof T]: T[K] extends FieldDescriptor<infer S> ? S : never;
 };
-declare class Lens<TSource, TTarget> extends Observable<TTarget> implements IAtom<TTarget> {
-    private subject$;
-    private sub;
-    private subCount;
-    constructor(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>);
-    set: (value: TTarget) => void;
-    get: () => TTarget;
-    modify: (fn: (val: TTarget) => TTarget) => void;
-}
-declare function createLens<TSource, TTarget>(source$: IAtom<TSource>, lens: ILens<TSource, TTarget>): Lens<TSource, TTarget>;
-declare function keyLens<TSource, TTarget extends keyof TSource>(key: TTarget): ILens<TSource, TSource[TTarget]>;
+/** The normalized shape data$ emits: array fields become entity key arrays, single fields become entity keys. */
+type QueryShapeOf<TShape> = {
+    [K in keyof TShape]: TShape[K] extends readonly (infer Item)[] ? EntityKey<Item>[] : EntityKey<TShape[K]>;
+};
+type MutationDefs<TShape> = {
+    [key: string]: (prev: TShape, ...args: any[]) => TShape;
+};
+type StateDescriptor<TParams, TShape, TMutations extends MutationDefs<TShape> = Record<never, never>> = {
+    /** Stable string identity for the SSR query cache. States without a key opt out of SSR caching. */
+    readonly key?: string;
+    readonly paramsSchema: z.ZodType<TParams, z.ZodTypeDef, any>;
+    readonly fields: {
+        [K in keyof TShape]: FieldDescriptor<TShape[K]>;
+    };
+    readonly mutations: TMutations;
+};
+declare function defineState<TParams, TFields extends FieldsMap>(def: {
+    key?: string;
+    params: z.ZodType<TParams, z.ZodTypeDef, any>;
+    model: TFields;
+    mutations?: undefined;
+}): StateDescriptor<TParams, ShapeFromFields<TFields>, Record<never, never>>;
+declare function defineState<TParams, TFields extends FieldsMap, TMutations extends MutationDefs<ShapeFromFields<TFields>>>(def: {
+    key?: string;
+    params: z.ZodType<TParams, z.ZodTypeDef, any>;
+    model: TFields;
+    mutations: TMutations;
+}): StateDescriptor<TParams, ShapeFromFields<TFields>, TMutations>;
+
+/** Splits a denormalized fetch result: entities → model stores, ids → returned query shape. */
+declare function normalizeResult<TShape>(registry: IModelRegistry, fields: FieldsMap, value: TShape): QueryShapeOf<TShape>;
+/** Rebuilds the fetch shape from ids by reading store value maps — reducers always see the freshest entities. */
+declare function denormalizeValue<TShape>(registry: IModelRegistry, fields: FieldsMap, ids: QueryShapeOf<TShape>): TShape;
 
-export { Atom, type IAtom, type IBranded, type IEdge, type IEdgeJS, type IEdgeState, type ILens, type IWrapped, Lens, StatusEnum, createAtom, createEdge, createFulfilled, createIdle, createLens, createPending, createRejected, createState, createStore, isBranded, keyLens, toBranded };
+export { Atom, type DehydratedState, type EntityKey, type FieldDescriptor, type FieldsMap, type IAtom, type ILens, type IModelRegistry, type IWrapped, Lens, type ModelDescriptor, type ModelStore, type MutationDefs, type QueryCache, type QueryShapeOf, type SerializedError, type SerializedWrapped, type ShapeFromFields, type StateDescriptor, StatusEnum, array, attachReload, createAtom, createFulfilled, createIdle, createLens, createModel, createModelRegistry, createModelStore, createPending, createQueryCache, createRejected, defineState, dehydrate, denormalizeValue, deserializeWrapped, getAttachedReload, hydrate, hydrationScript, isSyncMarked, keyLens, markSync, normalizeResult, rehydrateError, serializeError, serializeForHtml, serializeWrapped, single, stableStringify };