@emeryld/rrroutes-client 2.2.6 → 2.2.8

package/dist/routesV3.client.types.d.ts

@@ -102,12 +102,16 @@ type ParamsOf<L extends AnyLeaf> = InferParams<L>;
 type QueryOf<L extends AnyLeaf> = InferQuery<L>;
 type BodyOf<L extends AnyLeaf> = InferBody<L>;
 type OnReceive<L extends AnyLeaf> = (data: OutputOf<L>) => void;
+type OnReceiveRegistrar<L extends AnyLeaf> = (listener: OnReceive<L>) => () => void;
+type UseEndpointResult<L extends AnyLeaf, Result> = Result & {
+    onReceive: OnReceiveRegistrar<L>;
+};
 /** Variadic args consumed by the direct fetch helper: optional args + body. */
-export type MutationFetchArgs<L extends AnyLeaf> = [...ArgsTuple<L>, BodyOf<L>];
+export type MutationFetchArgs<L extends AnyLeaf> = Prettify<[...ArgsTuple<L>, BodyOf<L>]>;
 /** Signature for the fetch helper returned by mutation builds. */
 export type MutationFetcher<L extends AnyLeaf> = (...args: MutationFetchArgs<L>) => Promise<OutputOf<L>>;
 /** Fetch args for GET endpoints (optionally include a body when a schema exists). */
-type QueryFetchArgs<L extends AnyLeaf> = BodyOf<L> extends never ? ArgsTuple<L> : ArgsTuple<L> | [...ArgsTuple<L>, BodyOf<L>];
+type QueryFetchArgs<L extends AnyLeaf> = BodyOf<L> extends never ? ArgsTuple<L> : Prettify<ArgsTuple<L> | [...ArgsTuple<L>, BodyOf<L>]>;
 /** Optional metadata provided when building a helper (used for debug filtering). */
 export type BuildMeta<Names extends string = string> = {
     /**
@@ -117,11 +121,11 @@ export type BuildMeta<Names extends string = string> = {
     name?: Names;
 };
 /** Object shape the user passes to hooks and helpers (params/query are optional). */
-export type ArgsFor<L extends AnyLeaf> = (ParamsOf<L> extends never ? {} : {
+export type ArgsFor<L extends AnyLeaf> = Prettify<(ParamsOf<L> extends never ? {} : {
     params: ParamsOf<L>;
 }) & (QueryOf<L> extends never ? {} : {
     query: QueryOf<L>;
-});
+})>;
 /** Variadic tuple representation that omits the argument entirely when not needed. */
 export type ArgsTuple<L extends AnyLeaf> = keyof ArgsFor<L> extends never ? [] : [args: ArgsFor<L>];
 /** Cache data shape for setData(...) */
@@ -130,6 +134,7 @@ type ArgsFromTuple<L extends AnyLeaf, T extends ArgsTuple<L>> = T extends [infer
 type ParamsFromArgs<L extends AnyLeaf, T extends ArgsTuple<L>> = ArgsFromTuple<L, T> extends {
     params: infer P;
 } ? P : undefined;
+type SetDataArgs<L extends AnyLeaf> = Prettify<[updater: Updater<DataShape<L>>, ...ArgsTuple<L>]>;
 type QueryFromArgs<L extends AnyLeaf, T extends ArgsTuple<L>> = ArgsFromTuple<L, T> extends {
     query: infer Q;
 } ? Q : undefined;
@@ -161,13 +166,10 @@ export type MutationBuildOptionsFor<L extends AnyLeaf> = Omit<UseMutationOptions
 };
 /** Build options narrowed to the method/feed shape of the leaf. */
 export type BuildOptionsFor<L extends AnyLeaf> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteBuildOptionsFor<L> : QueryBuildOptionsFor<L> : MutationBuildOptionsFor<L>;
-type UseEndpointOptionsFor<L extends AnyLeaf> = {
-    onReceive?: OnReceive<L>;
-};
-export type UseEndpointArgs<L extends AnyLeaf, O> = keyof ArgsFor<L> extends never ? [options?: O] : [args: ArgsFor<L>, options?: O];
-export type QueryUseEndpointOptionsFor<L extends AnyLeaf> = UseEndpointOptionsFor<L>;
-export type InfiniteUseEndpointOptionsFor<L extends AnyLeaf> = UseEndpointOptionsFor<L>;
-export type MutationUseEndpointOptionsFor<L extends AnyLeaf> = UseEndpointOptionsFor<L>;
+export type UseEndpointArgs<L extends AnyLeaf> = ArgsTuple<L>;
+export type QueryUseEndpointResultFor<L extends AnyLeaf> = UseEndpointResult<L, UseQueryResult<OutputOf<L>, unknown>>;
+export type InfiniteUseEndpointResultFor<L extends AnyLeaf> = UseEndpointResult<L, UseInfiniteQueryResult<InfiniteData<OutputOf<L>>, unknown>>;
+export type MutationUseEndpointResultFor<L extends AnyLeaf> = UseEndpointResult<L, UseMutationResult<OutputOf<L>, unknown, BodyOf<L>, unknown>>;
 /** Shared capabilities exposed by every built endpoint helper. */
 export type BuiltCommon<L extends AnyLeaf> = {
     /**
@@ -186,7 +188,7 @@ export type BuiltCommon<L extends AnyLeaf> = {
      * @param updater New value or function applied to existing cache data.
      * @param rest Optional params/query tuple for the leaf.
      */
-    setData: (...args: [updater: Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => DataShape<L> | undefined;
+    setData: (...args: SetDataArgs<L>) => DataShape<L> | undefined;
 };
 /** Hook+helpers for a standard GET endpoint. */
 export type BuiltQuery<L extends AnyLeaf> = BuiltCommon<L> & {
@@ -194,7 +196,7 @@ export type BuiltQuery<L extends AnyLeaf> = BuiltCommon<L> & {
      * React hook bound to the GET leaf.
      * @param args Optional params/query tuple for the leaf.
      */
-    useEndpoint: (...args: UseEndpointArgs<L, QueryUseEndpointOptionsFor<L>>) => UseQueryResult<OutputOf<L>, unknown>;
+    useEndpoint: (...args: UseEndpointArgs<L>) => QueryUseEndpointResultFor<L>;
     /**
      * Direct fetch helper mirroring the query hook without touching the cache.
      * @param args Optional params/query tuple for the leaf.
@@ -207,7 +209,7 @@ export type BuiltInfinite<L extends AnyLeaf> = BuiltCommon<L> & {
      * React hook bound to an infinite GET leaf.
      * @param args Optional params/query tuple for the leaf.
      */
-    useEndpoint: (...args: UseEndpointArgs<L, InfiniteUseEndpointOptionsFor<L>>) => UseInfiniteQueryResult<InfiniteData<OutputOf<L>>, unknown>;
+    useEndpoint: (...args: UseEndpointArgs<L>) => InfiniteUseEndpointResultFor<L>;
     /**
      * Direct fetch helper for a single page of the feed (pass cursor in query args).
      * @param args Optional params/query tuple for the leaf.
@@ -220,7 +222,7 @@ export type BuiltMutation<L extends AnyLeaf> = BuiltCommon<L> & {
      * React hook bound to a mutation leaf.
      * @param args Optional params/query tuple for the leaf.
      */
-    useEndpoint: (...args: UseEndpointArgs<L, MutationUseEndpointOptionsFor<L>>) => UseMutationResult<OutputOf<L>, unknown, BodyOf<L>, unknown>;
+    useEndpoint: (...args: UseEndpointArgs<L>) => MutationUseEndpointResultFor<L>;
     /**
      * Direct fetch helper that bypasses React Query, useful for server actions or scripts.
      * Pass params/query first (if required), followed by the body payload.

package/dist/sockets/socket.client.context.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { Socket } from 'socket.io-client';
 import { SocketClient, SocketClientOptions, ClientCtx, ServerEnvelope } from './socket.client.index';
-import { EventMap, SocketConnectionConfig, Payload, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import { EventMap, SocketConnectionConfigOutput, Payload, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 /** === Provider-side debug === */
 type HookDebugReason = 'init' | 'change';
 type HookDebugValue = string | number | boolean | null | undefined;
@@ -33,13 +33,13 @@ export type SocketProviderDebugOptions = {
     [P in SocketProviderDebugEvent['type']]?: boolean;
 };
 /** === Types for runtime socket injection === */
-type BaseOptions<T extends EventMap, C extends SocketConnectionConfig> = Omit<SocketClientOptions<T, C>, 'socket'>;
+type BaseOptions<T extends EventMap, C extends SocketConnectionConfigOutput> = Omit<SocketClientOptions<T, C>, 'socket'>;
 type ProviderRuntimeSocket = {
     socket: Socket | null;
 } | {
     getSocket: () => Socket | Promise<Socket>;
 };
-export declare function buildSocketProvider<T extends EventMap, C extends SocketConnectionConfig>(args: {
+export declare function buildSocketProvider<T extends EventMap, C extends SocketConnectionConfigOutput>(args: {
     events: T;
     options: Omit<BaseOptions<T, C>, 'debug'> & {
         debug: BaseOptions<T, C>['debug'] & SocketProviderDebugOptions;
@@ -52,9 +52,9 @@ export declare function buildSocketProvider<T extends EventMap, C extends Socket
     useSocketClient: () => SocketClient<T, C>;
     useSocketConnection: <K extends keyof T & string>(p: Parameters<typeof useSocketConnection<T, K, C>>[0]) => void;
 };
-export declare function useSocketClient<T extends EventMap, C extends SocketConnectionConfig>(): SocketClient<T, C>;
+export declare function useSocketClient<T extends EventMap, C extends SocketConnectionConfigOutput>(): SocketClient<T, C>;
 type Rooms = string[] | string | undefined;
-export type UseSocketConnectionArgs<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfig> = {
+export type UseSocketConnectionArgs<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfigOutput> = {
     event: K;
     rooms?: Rooms;
     onMessage: (payload: Payload<T, K>, meta: {
@@ -67,5 +67,5 @@ export type UseSocketConnectionArgs<T extends EventMap, K extends keyof T & stri
     joinMeta: SocketSchemaOutput<C['joinMetaMessage']>;
     leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>;
 };
-export declare function useSocketConnection<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfig>(args: UseSocketConnectionArgs<T, K, C>): void;
+export declare function useSocketConnection<T extends EventMap, K extends keyof T & string, C extends SocketConnectionConfigOutput>(args: UseSocketConnectionArgs<T, K, C>): void;
 export {};

package/dist/sockets/socket.client.index.d.ts

@@ -1,4 +1,4 @@
-import type { EventMap, SocketConnectionConfig, Payload, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import type { EventMap, SocketConnectionConfigOutput, Payload, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 import type { MaybeSocket, SysEventMap } from './socket.client.sys';
 import { SocketClientDebugEvent } from './socket.client.debug';
 export type ServerEnvelope<T extends EventMap, K extends keyof T & string> = {
@@ -43,7 +43,7 @@ export type HeartbeatClientOptions = {
     /** Give up waiting for pong after this many ms. Default 7_500. */
     timeoutMs?: number;
 };
-export type SocketClientOptions<T extends EventMap = EventMap, C extends SocketConnectionConfig = SocketConnectionConfig> = {
+export type SocketClientOptions<T extends EventMap = EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> = {
     /** Inject an existing socket.io-client Socket. Can be null while bootstrapping. */
     socket: MaybeSocket;
     config: C;
@@ -52,7 +52,7 @@ export type SocketClientOptions<T extends EventMap = EventMap, C extends SocketC
     heartbeat?: HeartbeatClientOptions;
     sys: SysEventMap<T, C>;
 };
-export declare class SocketClient<T extends EventMap, C extends SocketConnectionConfig = SocketConnectionConfig> {
+export declare class SocketClient<T extends EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> {
     readonly socket: MaybeSocket;
     private readonly events;
     private readonly environment;
@@ -116,4 +116,3 @@ export declare class SocketClient<T extends EventMap, C extends SocketConnection
 }
 export * from './socket.client.context';
 export * from './socket.client.sys';
-export * from './socketedRoute/socket.client.helper';

package/dist/sockets/socket.client.sys.d.ts

@@ -1,9 +1,9 @@
 import type { Socket } from 'socket.io-client';
 import { z } from 'zod';
-import type { EventMap, SocketConnectionConfig, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import type { EventMap, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 import { SocketClient } from './socket.client.index';
 export type MaybeSocket = Socket | null;
-export type SysEventMap<T extends EventMap, C extends SocketConnectionConfig = SocketConnectionConfig> = {
+export type SysEventMap<T extends EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> = {
     'sys:connect': (args: {
         socket: Socket;
         client: SocketClient<T, C>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/rrroutes-client",
-  "version": "2.2.6",
+  "version": "2.2.8",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -30,7 +30,7 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.2.0",
-    "@types/react": "^18.3.26",
+    "@types/react": "^18.3.27",
     "@types/react-native": "^0.73.0"
   },
   "scripts": {

package/dist/sockets/socketedRoute/socket.client.helper.d.ts

@@ -1,121 +0,0 @@
-import type { AnyLeaf, InferOutput, EventMap as ContractEventMap, SocketSchemaOutput, Payload, SocketConnectionConfigOutput } from '@emeryld/rrroutes-contract';
-import type { BuildMeta, BuildOptionsFor, ArgsFor, DataShape, InfiniteUseEndpointOptionsFor, QueryUseEndpointOptionsFor, RouterBuilder } from '../../routesV3.client.types';
-import type { ClientCtx, ServerEnvelope, SocketClient } from '../socket.client.index';
-/** Narrow to GET leaves. */
-type GetLeaf = AnyLeaf & {
-    method: 'get';
-};
-type PageOf<L extends GetLeaf> = InferOutput<L>;
-type SocketedRouteDebugEventBase = {
-    name?: string;
-};
-export type SocketedRouteDebugEvent<Ev extends string = string> = (SocketedRouteDebugEventBase & {
-    type: 'build';
-    routeKey: string;
-    socketEvent: Ev;
-    options?: unknown;
-}) | (SocketedRouteDebugEventBase & {
-    type: 'subscribe';
-    phase: 'start' | 'stop';
-    routeKey: string;
-    socketEvent: Ev;
-}) | (SocketedRouteDebugEventBase & {
-    type: 'receive';
-    routeKey: string;
-    socketEvent: Ev;
-    payload?: unknown;
-    envelope?: {
-        eventName: Ev;
-        sentAt?: string | Date;
-        sentTo?: string[];
-        metadata?: Record<string, unknown>;
-    };
-}) | (SocketedRouteDebugEventBase & {
-    type: 'onReceive';
-    routeKey: string;
-    socketEvent: Ev;
-    page?: unknown;
-    rooms?: string[];
-}) | (SocketedRouteDebugEventBase & {
-    type: 'rooms';
-    phase: 'derive' | 'join' | 'leave';
-    routeKey: string;
-    socketEvent: Ev;
-    rooms: string[];
-    prev?: string[];
-    meta?: unknown;
-    reason?: string;
-    source?: 'hydrate' | 'onReceive';
-}) | (SocketedRouteDebugEventBase & {
-    type: 'setData';
-    routeKey: string;
-    socketEvent: Ev;
-    args?: unknown;
-}) | (SocketedRouteDebugEventBase & {
-    type: 'render';
-    render: number;
-    routeKey: string;
-    socketEvent: Ev;
-    changed?: string[];
-    rooms?: string[];
-}) | (SocketedRouteDebugEventBase & {
-    type: 'effect';
-    effect: 'rooms' | 'subscribe';
-    phase: 'run' | 'cleanup';
-    changedDeps?: string[];
-    rooms?: string[];
-});
-export type SocketedRouteDebugOptions<Ev extends string = string> = {
-    verbose?: boolean;
-    only?: string[];
-    logger?: (e: SocketedRouteDebugEvent<Ev>) => void;
-} & {
-    [P in SocketedRouteDebugEvent['type']]?: boolean;
-};
-type SocketedHandlers<L extends GetLeaf, E extends ContractEventMap, K extends keyof E & string, C extends SocketConnectionConfigOutput> = {
-    /**
-     * Derive the full set of rooms to join based on a newly received payload plus
-     * the current active room list. Return the complete desired list (not a delta).
-     */
-    onReceiveRooms?: (page: PageOf<L>, activeRooms: string[]) => string[];
-    /**
-     * Update the cached route data when a socket message arrives.
-     * Return the next cache value (or undefined to keep it unchanged).
-     */
-    handleMessage: (prev: DataShape<L> | undefined, payload: Payload<E, K>, meta: {
-        envelope: ServerEnvelope<E, K>;
-        ctx: ClientCtx;
-    }) => DataShape<L> | undefined;
-    /** Meta payloads for join/leave messages. */
-    joinMeta: SocketSchemaOutput<C['joinMetaMessage']>;
-    leaveMeta: SocketSchemaOutput<C['leaveMetaMessage']>;
-};
-type GetRoutesOf<R extends Record<PropertyKey, AnyLeaf>> = {
-    [K in keyof R as R[K] extends GetLeaf ? K : never]: R[K] extends GetLeaf ? R[K] : never;
-};
-type OptionsForGet<L extends GetLeaf> = L['cfg']['feed'] extends true ? InfiniteUseEndpointOptionsFor<L> : QueryUseEndpointOptionsFor<L>;
-export type SocketedRouteHook<Routes extends Record<PropertyKey, GetLeaf>, Names extends string, Events extends ContractEventMap, C extends SocketConnectionConfigOutput> = <K extends keyof Routes & string, Ev extends keyof Events & string>(params: {
-    routeKey: K;
-    socketEvent: Ev;
-    handlers: SocketedHandlers<Routes[K], Events, Ev, C>;
-    buildOptions?: BuildOptionsFor<Routes[K]>;
-    buildMeta?: BuildMeta<Names>;
-    debug?: SocketedRouteDebugOptions<Ev>;
-    useOptions?: {
-        args?: ArgsFor<Routes[K]>;
-        options?: OptionsForGet<Routes[K]>;
-    };
-}) => {
-    data: DataShape<Routes[K]> | undefined;
-    rooms: string[];
-};
-/**
-  * Build a hook that wires a GET route (feed or standard) to a socket event:
-  * - Keeps React Query cache in sync when socket messages arrive.
-  * - Derives and joins rooms from the route’s responses.
-  */
-export declare function createSocketedRouteHook<Routes extends Record<PropertyKey, AnyLeaf>, Names extends string, Events extends ContractEventMap, C extends SocketConnectionConfigOutput>(args: {
-    buildRoute: RouterBuilder<Routes, Names>;
-    useClient?: () => SocketClient<Events, C>;
-}): SocketedRouteHook<GetRoutesOf<Routes>, Names, Events, C>;
-export {};