@ably/ai-transport 0.1.0 → 0.3.0

package/src/react/use-active-turns.ts

@@ -1,72 +0,0 @@
-/**
- * useActiveTurns: reactive view of active turns on the channel,
- * keyed by clientId.
- *
- * Subscribes to transport tree turn lifecycle events and maintains a
- * Map<clientId, Set<turnId>> that updates on every turn start/end.
- *
- * Uses tree (not view) so that all turns are tracked — including remote
- * turns whose messages haven't arrived yet.
- *
- * Generic — works with any codec, not tied to Vercel types.
- */
-
-import { useContext, useEffect, useState } from 'react';
-
-import { EVENT_TURN_START } from '../constants.js';
-import type { ClientTransport, TurnLifecycleEvent } from '../core/transport/types.js';
-import { NearestTransportContext } from './contexts/transport-context.js';
-
-/**
- * Returns a reactive Map of all active turns on the channel, keyed by clientId.
- * Updates when turns start or end. When `transport` is omitted, uses the nearest
- * {@link TransportProvider}'s transport via context.
- * @param props - Options including optional `transport`.
- * @param props.transport - Transport to track turns for; defaults to the nearest provider.
- * @returns A Map where keys are clientIds and values are Sets of active turnIds.
- */
-export const useActiveTurns = <TEvent, TMessage>({
-  transport,
-}: { transport?: ClientTransport<TEvent, TMessage> | null } = {}): Map<string, Set<string>> => {
-  const nearestSlot = useContext(NearestTransportContext);
-  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-  const resolved = (transport ?? nearestSlot?.transport) as ClientTransport<TEvent, TMessage> | undefined;
-
-  const [turns, setTurns] = useState<Map<string, Set<string>>>(() => new Map());
-
-  useEffect(() => {
-    if (!resolved) return;
-
-    // Initialize from current state
-    setTurns(resolved.tree.getActiveTurnIds());
-
-    const unsubscribe = resolved.tree.on('turn', (event: TurnLifecycleEvent) => {
-      setTurns((prev) => {
-        const next = new Map(prev);
-
-        if (event.type === EVENT_TURN_START) {
-          const set = new Set(next.get(event.clientId));
-          set.add(event.turnId);
-          next.set(event.clientId, set);
-        } else {
-          const existing = next.get(event.clientId);
-          if (existing) {
-            const updated = new Set(existing);
-            updated.delete(event.turnId);
-            if (updated.size === 0) {
-              next.delete(event.clientId);
-            } else {
-              next.set(event.clientId, updated);
-            }
-          }
-        }
-
-        return next;
-      });
-    });
-
-    return unsubscribe;
-  }, [resolved]);
-
-  return turns;
-};

package/src/react/use-client-transport.ts

@@ -1,197 +0,0 @@
-/**
- * useClientTransport — read a ClientTransport from the nearest TransportProvider.
- *
- * The transport is created by {@link TransportProvider}, which also wraps the subtree
- * with Ably's `ChannelProvider`. This hook is a thin context reader — it does not
- * create or manage transport state.
- *
- * **Provider lookup**
- * - Omit `channelName` to use the innermost `TransportProvider` in the tree.
- * - Pass `channelName` to look up a specific provider by name.
- * - Pass `skip: true` to receive a stub transport that throws on any access —
- *   safe to hold in state before auth or other conditions are ready.
- *
- * **Error handling**
- * - When no matching provider is found, or when the provider's `createClientTransport`
- *   call threw, `transportError` is set on the returned object instead of throwing.
- *   The component can render an error state without an error boundary.
- * - Pass `onError` to receive post-construction transport errors (e.g. send failures,
- *   channel continuity loss) without wiring `transport.on('error', ...)` manually.
- */
-
-import * as Ably from 'ably';
-import { useContext, useEffect, useRef } from 'react';
-
-import type { ClientTransport, Tree, View } from '../core/transport/types.js';
-import { ErrorCode } from '../errors.js';
-import { NearestTransportContext, TransportContext } from './contexts/transport-context.js';
-
-const SKIPPED_TRANSPORT: ClientTransport<unknown, unknown> = {
-  get tree(): Tree<unknown> {
-    throw new Ably.ErrorInfo('unable to access tree; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  get view(): View<unknown, unknown> {
-    throw new Ably.ErrorInfo('unable to access view; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  createView: (): View<unknown, unknown> => {
-    throw new Ably.ErrorInfo('unable to create view; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  cancel: () => {
-    throw new Ably.ErrorInfo('unable to cancel; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  stageEvents: () => {
-    throw new Ably.ErrorInfo('unable to stage events; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  stageMessage: () => {
-    throw new Ably.ErrorInfo('unable to stage message; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  waitForTurn: () => {
-    throw new Ably.ErrorInfo('unable to wait for turn; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  on: () => {
-    throw new Ably.ErrorInfo('unable to subscribe; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  close: () => {
-    throw new Ably.ErrorInfo('unable to close; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-};
-
-/**
- * Return value of {@link useClientTransport}.
- *
- * `transport` is always a valid object. When `skip` is `true`, when no provider was
- * found, or when the provider's transport construction failed, `transport` is a stub
- * that throws {@link Ably.ErrorInfo} on every access.
- * Check `transportError` before using `transport` to avoid those throws.
- */
-export interface ClientTransportHandle<TEvent, TMessage> {
-  /**
-   * The resolved transport.
-   *
-   * A throwing stub when `skip` is `true`, when no matching {@link TransportProvider}
-   * was found in the tree, or when transport construction failed.
-   */
-  transport: ClientTransport<TEvent, TMessage>;
-  /**
-   * Set when no matching {@link TransportProvider} was found, when transport
-   * construction failed, and `skip` is `false`.
-   * `undefined` when the transport resolved successfully or when `skip` is `true`.
-   */
-  transportError?: Ably.ErrorInfo | undefined;
-}
-
-/**
- * Read a {@link ClientTransport} from the nearest {@link TransportProvider}.
- *
- * Returns `{ transport, transportError }`. When no provider is found or transport
- * construction failed, `transportError` is set and `transport` is a stub that throws
- * on access — the hook never throws during render.
- *
- * Pass `onError` to subscribe to post-construction transport errors
- * (e.g. {@link ErrorCode.TransportSendFailed}, {@link ErrorCode.ChannelContinuityLost})
- * without calling `transport.on('error', …)` manually. The subscription is
- * created when the transport resolves and removed on unmount.
- * @param props - Hook options.
- * @param props.channelName - Look up a specific provider by channel name; omit for the nearest.
- * @param props.skip - When `true`, return the stub transport immediately without reading context.
- * @param props.onError - Called whenever the resolved transport emits an error event.
- * @returns `{ transport, transportError }`.
- */
-export const useClientTransport = <TEvent, TMessage>({
-  channelName,
-  skip,
-  onError,
-}: {
-  /**
-   * Channel name passed to the enclosing {@link TransportProvider}.
-   * Omit to use the nearest provider in the tree.
-   */
-  channelName?: string;
-  /**
-   * When `true`, skip context lookup and return a stub transport that throws on
-   * any access. Use when a condition (auth, feature flag) is not yet resolved.
-   */
-  skip?: boolean;
-  /**
-   * Called whenever the resolved transport emits an error event.
-   * The subscription is established once the transport resolves and
-   * automatically removed on unmount or when the transport changes.
-   */
-  onError?: (error: Ably.ErrorInfo) => void;
-} = {}): ClientTransportHandle<TEvent, TMessage> => {
-  const registry = useContext(TransportContext);
-  const nearestSlot = useContext(NearestTransportContext);
-  const errorCallbackRef = useRef(onError);
-  errorCallbackRef.current = onError;
-
-  // Compute the transport for the onError subscription *before* any conditional
-  // returns to satisfy React's rules of hooks (no hooks in branches).
-  // Erased generics — this ref is only used in the useEffect below.
-  const resolvedForEffect: ClientTransport<unknown, unknown> | undefined = skip
-    ? undefined
-    : channelName === undefined
-      ? nearestSlot?.transport
-      : registry[channelName]?.transport;
-
-  useEffect(() => {
-    if (!resolvedForEffect) return;
-    return resolvedForEffect.on('error', (errorInfo) => {
-      errorCallbackRef.current?.(errorInfo);
-    });
-  }, [resolvedForEffect]);
-
-  if (skip) {
-    return {
-      transport: SKIPPED_TRANSPORT as unknown as ClientTransport<TEvent, TMessage>,
-    };
-  }
-
-  if (channelName !== undefined) {
-    const slot = registry[channelName];
-    if (slot) {
-      if (slot.transport) {
-        // CAST: TransportContext stores transports with erased generics.
-        // The caller is responsible for using type parameters matching those of the TransportProvider.
-        return {
-          transport: slot.transport as unknown as ClientTransport<TEvent, TMessage>,
-        };
-      }
-      // Provider exists but construction failed.
-      return {
-        transport: SKIPPED_TRANSPORT as unknown as ClientTransport<TEvent, TMessage>,
-        transportError: slot.error,
-      };
-    }
-    return {
-      transport: SKIPPED_TRANSPORT as unknown as ClientTransport<TEvent, TMessage>,
-      transportError: new Ably.ErrorInfo(
-        `unable to use transport; no TransportProvider found for channelName "${channelName}"`,
-        ErrorCode.BadRequest,
-        400,
-      ),
-    };
-  }
-
-  if (nearestSlot) {
-    if (nearestSlot.transport) {
-      // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-      return {
-        transport: nearestSlot.transport as unknown as ClientTransport<TEvent, TMessage>,
-      };
-    }
-    // Nearest provider exists but construction failed.
-    return {
-      transport: SKIPPED_TRANSPORT as unknown as ClientTransport<TEvent, TMessage>,
-      transportError: nearestSlot.error,
-    };
-  }
-
-  return {
-    transport: SKIPPED_TRANSPORT as unknown as ClientTransport<TEvent, TMessage>,
-    transportError: new Ably.ErrorInfo(
-      'unable to use transport; no TransportProvider found in the tree',
-      ErrorCode.BadRequest,
-      400,
-    ),
-  };
-};