@fitzzero/quickdraw-core 5.1.1 → 5.1.3

package/dist/chunk-NX2V6SIL.js

@@ -0,0 +1,202 @@
+import {
+  isTimeLimit,
+  mayConnect,
+  notifyEach,
+  retryAfterOf
+} from "./chunk-STH5DLQP.js";
+import {
+  CLIENT_EVENTS,
+  reservedRoomPrefix,
+  socketIdShaped
+} from "./chunk-X4ZU4QH5.js";
+import {
+  QuickdrawError,
+  fromWire
+} from "./chunk-Q4OGQM5I.js";
+import {
+  isRecord
+} from "./chunk-QSU47XEX.js";
+
+// src/client/call.ts
+var UNSENT_TIMEOUT = "operation has timed out";
+function isNotModified(result) {
+  return result.nm === true;
+}
+function cancelledError() {
+  return new QuickdrawError("CANCELLED", "The call was cancelled");
+}
+function internalError(message) {
+  return new QuickdrawError("INTERNAL", message);
+}
+var lostInFlight = /* @__PURE__ */ new WeakSet();
+function isUnknownOutcome(error) {
+  return error instanceof QuickdrawError && (error.code === "TIMEOUT" || lostInFlight.has(error));
+}
+function lostError() {
+  const error = internalError("No answer: the connection to the server is down");
+  lostInFlight.add(error);
+  return error;
+}
+function refusedBeforeSending(connection, kind, signal) {
+  if (signal?.aborted === true) {
+    return cancelledError();
+  }
+  if (!connection.socket.connected && !mayConnect(connection)) {
+    return internalError("Not connected to the server");
+  }
+  const remaining = connection.backoffRemaining(kind);
+  if (remaining > 0) {
+    return new QuickdrawError(
+      "RATE_LIMITED",
+      `Waiting before more ${kind} calls: the server answered RATE_LIMITED`,
+      { retryAfterMs: Math.ceil(remaining) }
+    );
+  }
+  return void 0;
+}
+function envelopeOf(id, request) {
+  return {
+    id,
+    s: request.service,
+    m: request.method,
+    ...request.input === void 0 ? {} : { i: request.input },
+    ...request.v === void 0 ? {} : { v: request.v }
+  };
+}
+function readReply(connection, kind, reply) {
+  if (isRecord(reply) && reply.ok === true) {
+    const versioned = typeof reply.v === "string" || typeof reply.v === "number";
+    if (reply.nm === true && !versioned) {
+      return internalError("The server answered not modified without a version");
+    }
+    return reply;
+  }
+  if (isRecord(reply) && reply.ok === false) {
+    const error = fromWire(reply.e);
+    if (error.code === "RATE_LIMITED") {
+      connection.reportRateLimited(kind, retryAfterOf(error));
+    }
+    return error;
+  }
+  return internalError("The server's reply is not a call reply");
+}
+function isQueuedCall(data, id) {
+  return Array.isArray(data) && data[0] === CLIENT_EVENTS.call && isRecord(data[1]) && data[1].id === id;
+}
+function cancelCall(socket, id) {
+  const queued = socket.sendBuffer.findIndex((packet) => isQueuedCall(packet.data, id));
+  if (queued >= 0) {
+    socket.sendBuffer.splice(queued, 1);
+  } else if (socket.connected) {
+    socket.emit(CLIENT_EVENTS.cancel, { id });
+  }
+}
+function call(connection, request) {
+  const kind = request.kind ?? "query";
+  const { signal } = request;
+  const refused = refusedBeforeSending(connection, kind, signal);
+  if (refused !== void 0) {
+    return Promise.reject(refused);
+  }
+  const { socket } = connection;
+  const timeoutMs = request.timeoutMs ?? connection.timeoutMs;
+  if (!isTimeLimit(timeoutMs)) {
+    return Promise.reject(
+      new TypeError(
+        "call: timeoutMs must be a number of milliseconds, above 0 and at most 2^31 - 1"
+      )
+    );
+  }
+  const id = connection.nextCallId();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (outcome) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      if (outcome instanceof QuickdrawError) {
+        reject(outcome);
+      } else {
+        notifyEach([request.onReply], (onReply) => {
+          onReply?.(outcome);
+        });
+        resolve(outcome);
+      }
+    };
+    function onAbort() {
+      cancelCall(socket, id);
+      settle(cancelledError());
+    }
+    socket.timeout(timeoutMs).emit(CLIENT_EVENTS.call, envelopeOf(id, request), (error, reply) => {
+      if (error === null) {
+        settle(readReply(connection, kind, reply));
+      } else if (error instanceof QuickdrawError) {
+        settle(error);
+      } else if (socket.connected) {
+        settle(new QuickdrawError("TIMEOUT", `No answer within ${timeoutMs} ms`));
+      } else if (error.message === UNSENT_TIMEOUT) {
+        settle(internalError("No answer: the connection to the server is down"));
+      } else {
+        settle(lostError());
+      }
+    });
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function callData(connection, request) {
+  const result = await call(connection, request);
+  if (isNotModified(result)) {
+    throw internalError("The server answered not modified to a call that sent no version");
+  }
+  return result.d;
+}
+function shouldRetry(failureCount, error) {
+  return failureCount < 1 && (!(error instanceof QuickdrawError) || error.code === "INTERNAL");
+}
+
+// src/client/host/rooms.ts
+function appRoom(value) {
+  return typeof value === "string" && value !== "" && reservedRoomPrefix(value) === void 0 && !socketIdShaped(value) ? value : void 0;
+}
+function computed(room, value) {
+  try {
+    return appRoom(room(value));
+  } catch {
+    return void 0;
+  }
+}
+function channelRoomOf(def, payload, rooms) {
+  const room = def.requires?.room;
+  if (typeof room === "string") {
+    return room;
+  }
+  if (typeof room === "function") {
+    return computed(room, payload);
+  }
+  if (typeof room === "object") {
+    for (const known of rooms) {
+      if (known.startsWith(room.prefix)) {
+        return known;
+      }
+    }
+  }
+  return void 0;
+}
+function streamRoomOf(def, scope) {
+  const access = typeof def.access === "object" ? def.access : void 0;
+  const room = access?.room;
+  return typeof room === "function" ? computed(room, scope) : void 0;
+}
+
+export {
+  isNotModified,
+  isUnknownOutcome,
+  call,
+  callData,
+  shouldRetry,
+  channelRoomOf,
+  streamRoomOf
+};
+//# sourceMappingURL=chunk-NX2V6SIL.js.map

package/dist/chunk-NX2V6SIL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/call.ts","../src/client/host/rooms.ts"],"sourcesContent":["// One method call over a client connection (RFC 0003 sections 8.2, 9 and\n// 11.2): a `qd:call` envelope with a fresh id, answered through Socket.IO's\n// acknowledgement. 4.1 sent one event per method and resolved the\n// `{ success, data }` reply (4.1 `src/client/useServiceQuery.ts:94-121`).\n//\n// - A failed call rejects with the `QuickdrawError` the reply carries.\n//   `RATE_LIMITED` also starts the connection's backoff for the call's kind,\n//   and while it lasts a call of that kind fails at once, without being\n//   sent, so a client that is being limited stops spending the budget.\n// - Aborting the signal rejects with `CANCELLED` and sends `qd:cancel`; a\n//   call still waiting in Socket.IO's send buffer is dropped instead, so it\n//   never reaches the server.\n// - No answer within the time limit rejects with `TIMEOUT`. It is never\n//   retried here: the server may still be running the call.\n// - A connection that drops before the answer, or is not open at all,\n//   rejects with `INTERNAL`. A call made while the socket reconnects, or\n//   while the connection waits to connect again after the server could not\n//   authenticate it (`mayConnect`), waits in Socket.IO's send buffer, within\n//   its time limit; new credentials meanwhile fail it with `CANCELLED`\n//   instead of sending it as them (`connection.ts`).\n// - A `TIMEOUT`, and the `INTERNAL` of a call whose connection dropped after\n//   it was sent, leave its outcome unknown: the server may have run it, and\n//   may still be running it. `isUnknownOutcome` tells them from refusals, so\n//   an optimistic addition waits for its scope's next load instead of being\n//   refused (`optimisticCall.ts`).\n// - A reply `{ ok: true, nm: true, v }` resolves as it is: the version the\n//   caller sent is current, and the caller keeps its copy.\n//\n// React-free: the hooks call through here, and so can any other client.\n\nimport type { MethodKind } from \"../contract/methods\";\nimport { CLIENT_EVENTS } from \"../contract/names\";\nimport type {\n  CallEnvelope,\n  CallId,\n  CallNotModified,\n  CallSuccess,\n  Version,\n} from \"../protocol/envelope\";\nimport { QuickdrawError, fromWire } from \"../protocol/errors\";\nimport { isRecord } from \"../protocol/guards\";\nimport { retryAfterOf } from \"./backoff\";\nimport {\n  isTimeLimit,\n  mayConnect,\n  type QuickdrawConnection,\n  type QuickdrawSocket,\n} from \"./connection\";\nimport { notifyEach } from \"./watch\";\n\n/**\n * What Socket.IO's client fails an acknowledgement with when its time limit\n * passes; with the socket down, the packet was still in its send buffer,\n * which drops it. Any other failure while the socket is down (it says \"socket\n * has been disconnected\") came after the packet was sent.\n */\nconst UNSENT_TIMEOUT = \"operation has timed out\";\n\n/** One call, as {@link call} takes it. */\nexport interface CallRequest {\n  /** The service's name on the wire: the contract's `name`. */\n  readonly service: string;\n  readonly method: string;\n  /** The input; left out of the envelope when `undefined`. */\n  readonly input?: unknown;\n  /** The method's kind, which picks the backoff a `RATE_LIMITED` answer starts. Default `\"query\"`. */\n  readonly kind?: MethodKind;\n  /** Aborting it cancels the call. */\n  readonly signal?: AbortSignal;\n  /** How long to wait for the answer. Default: the connection's `timeoutMs`. */\n  readonly timeoutMs?: number;\n  /** The version of the result the caller holds; the server answers \"not modified\" while it is current. */\n  readonly v?: Version;\n  /**\n   * Called with the result the moment the reply arrives, before any frame\n   * the server sent after it is handled; the returned promise settles only\n   * after more microtasks, and a client on Node can handle several frames in\n   * between. What must follow reply order goes here: an optimistic layer\n   * ends at the first newer frame after its call's reply.\n   */\n  readonly onReply?: (result: CallResult) => void;\n}\n\n/** What a call resolves with: the data, or \"not modified\" when the `v` it sent is current. */\nexport type CallResult<Output = unknown> = CallSuccess<Output> | CallNotModified;\n\n/** True when the server answered that the caller's version is current. */\nexport function isNotModified(result: CallResult): result is CallNotModified {\n  return result.nm === true;\n}\n\n/** The error a cancelled call rejects with. */\nfunction cancelledError(): QuickdrawError {\n  return new QuickdrawError(\"CANCELLED\", \"The call was cancelled\");\n}\n\nfunction internalError(message: string): QuickdrawError {\n  return new QuickdrawError(\"INTERNAL\", message);\n}\n\n/** The errors of calls whose connection dropped after they were sent: their outcome is unknown. */\nconst lostInFlight = new WeakSet<QuickdrawError>();\n\n/**\n * True when `error` leaves a call's outcome unknown: a `TIMEOUT` (the\n * server may still be running it, or ran it and the answer was lost), or the\n * `INTERNAL` of a call whose connection dropped after it was sent. The write\n * may have been made: before sending it again, make sure the call is\n * idempotent (a create that carries an id the client made, which the server\n * keeps, fails `CONFLICT` the second time instead of writing a second row).\n * False for a refusal, and for a call that was never sent.\n *\n * @example\n * onError: (error) => setStatus(isUnknownOutcome(error) ? \"checking\" : \"failed\")\n */\nexport function isUnknownOutcome(error: unknown): boolean {\n  return error instanceof QuickdrawError && (error.code === \"TIMEOUT\" || lostInFlight.has(error));\n}\n\n/** The error of a call whose connection dropped after it was sent. */\nfunction lostError(): QuickdrawError {\n  const error = internalError(\"No answer: the connection to the server is down\");\n  lostInFlight.add(error);\n  return error;\n}\n\n/** Why a call fails before it is sent, if it does. */\nfunction refusedBeforeSending(\n  connection: QuickdrawConnection,\n  kind: MethodKind,\n  signal: AbortSignal | undefined,\n): QuickdrawError | undefined {\n  if (signal?.aborted === true) {\n    return cancelledError();\n  }\n  if (!connection.socket.connected && !mayConnect(connection)) {\n    return internalError(\"Not connected to the server\");\n  }\n  const remaining = connection.backoffRemaining(kind);\n  if (remaining > 0) {\n    return new QuickdrawError(\n      \"RATE_LIMITED\",\n      `Waiting before more ${kind} calls: the server answered RATE_LIMITED`,\n      { retryAfterMs: Math.ceil(remaining) },\n    );\n  }\n  return undefined;\n}\n\nfunction envelopeOf(id: CallId, request: CallRequest): CallEnvelope {\n  return {\n    id,\n    s: request.service,\n    m: request.method,\n    ...(request.input === undefined ? {} : { i: request.input }),\n    ...(request.v === undefined ? {} : { v: request.v }),\n  };\n}\n\n/** The result or error a reply stands for; `RATE_LIMITED` starts the kind's backoff. */\nfunction readReply(\n  connection: QuickdrawConnection,\n  kind: MethodKind,\n  reply: unknown,\n): CallResult | QuickdrawError {\n  if (isRecord(reply) && reply.ok === true) {\n    const versioned = typeof reply.v === \"string\" || typeof reply.v === \"number\";\n    if (reply.nm === true && !versioned) {\n      return internalError(\"The server answered not modified without a version\");\n    }\n    return reply as unknown as CallResult;\n  }\n  if (isRecord(reply) && reply.ok === false) {\n    const error = fromWire(reply.e);\n    if (error.code === \"RATE_LIMITED\") {\n      connection.reportRateLimited(kind, retryAfterOf(error));\n    }\n    return error;\n  }\n  return internalError(\"The server's reply is not a call reply\");\n}\n\n/** True when a send-buffer packet is the `qd:call` frame of call `id`. */\nfunction isQueuedCall(data: unknown, id: CallId): boolean {\n  return (\n    Array.isArray(data) && data[0] === CLIENT_EVENTS.call && isRecord(data[1]) && data[1].id === id\n  );\n}\n\n/** Drops the call from Socket.IO's send buffer, or else asks the server to cancel it. */\nfunction cancelCall(socket: QuickdrawSocket, id: CallId): void {\n  const queued = socket.sendBuffer.findIndex((packet) => isQueuedCall(packet.data, id));\n  if (queued >= 0) {\n    socket.sendBuffer.splice(queued, 1);\n  } else if (socket.connected) {\n    socket.emit(CLIENT_EVENTS.cancel, { id });\n  }\n}\n\n/**\n * Calls `request.method` of `request.service` over `connection`. Resolves\n * with `{ ok: true, d, v? }`, or `{ ok: true, nm: true, v }` when the `v` it\n * sent is current; rejects with a `QuickdrawError` (see the top of this file\n * for which code when).\n *\n * @example\n * const reply = await call(connection, { service: \"taskService\", method: \"get\", input: { id } });\n * const task = isNotModified(reply) ? cached : reply.d;\n */\nexport function call<Output = unknown>(\n  connection: QuickdrawConnection,\n  request: CallRequest,\n): Promise<CallResult<Output>> {\n  const kind = request.kind ?? \"query\";\n  const { signal } = request;\n  const refused = refusedBeforeSending(connection, kind, signal);\n  if (refused !== undefined) {\n    return Promise.reject(refused);\n  }\n  const { socket } = connection;\n  const timeoutMs = request.timeoutMs ?? connection.timeoutMs;\n  if (!isTimeLimit(timeoutMs)) {\n    return Promise.reject(\n      new TypeError(\n        \"call: timeoutMs must be a number of milliseconds, above 0 and at most 2^31 - 1\",\n      ),\n    );\n  }\n  const id = connection.nextCallId();\n  return new Promise<CallResult<Output>>((resolve, reject) => {\n    let settled = false;\n    const settle = (outcome: CallResult | QuickdrawError): void => {\n      if (settled) {\n        return;\n      }\n      settled = true;\n      signal?.removeEventListener(\"abort\", onAbort);\n      if (outcome instanceof QuickdrawError) {\n        reject(outcome);\n      } else {\n        notifyEach([request.onReply], (onReply) => {\n          onReply?.(outcome);\n        });\n        resolve(outcome as CallResult<Output>);\n      }\n    };\n    function onAbort(): void {\n      cancelCall(socket, id);\n      settle(cancelledError());\n    }\n    socket\n      .timeout(timeoutMs)\n      .emit(CLIENT_EVENTS.call, envelopeOf(id, request), (error: Error | null, reply: unknown) => {\n        if (error === null) {\n          settle(readReply(connection, kind, reply));\n        } else if (error instanceof QuickdrawError) {\n          // Failed by the connection before it was sent (new credentials).\n          settle(error);\n        } else if (socket.connected) {\n          settle(new QuickdrawError(\"TIMEOUT\", `No answer within ${timeoutMs} ms`));\n        } else if (error.message === UNSENT_TIMEOUT) {\n          // Still in the send buffer when its time ran out: Socket.IO drops it unsent.\n          settle(internalError(\"No answer: the connection to the server is down\"));\n        } else {\n          // Sent, then the connection dropped: Socket.IO fails the acknowledgements it waits for.\n          settle(lostError());\n        }\n      });\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n  });\n}\n\n/**\n * Calls a method and resolves with its data. For a caller that sends no\n * version, which is never answered \"not modified\".\n */\nexport async function callData<Output = unknown>(\n  connection: QuickdrawConnection,\n  request: Omit<CallRequest, \"v\">,\n): Promise<Output> {\n  const result = await call<Output>(connection, request);\n  if (isNotModified(result)) {\n    throw internalError(\"The server answered not modified to a call that sent no version\");\n  }\n  return result.d;\n}\n\n/**\n * The default `retry` of query hooks: one more attempt after an `INTERNAL`\n * error, which includes a dropped connection, or an error that is not a\n * `QuickdrawError`; none for any other code. A `TIMEOUT` is not retried,\n * because the server may still be running the call, and `RATE_LIMITED`\n * waits for the backoff instead.\n */\nexport function shouldRetry(failureCount: number, error: unknown): boolean {\n  return failureCount < 1 && (!(error instanceof QuickdrawError) || error.code === \"INTERNAL\");\n}\n","// The app room a host-served member names (host mode, RFC 0003 section\n// 12.5), read from the contract as the server reads it: a channel's\n// `requires: { room }` (a name, a function of the payload, or `{ prefix }`)\n// and a stream's `access: { room: (scope) => room }`. A computed name that\n// is not a string, is empty, is the framework's (`qd:`, `user:`) or has the\n// shape of a socket id names no room. The peer side asks which host to send\n// to; the host side checks that a message or a subscribe is for its room.\n//\n// React-free.\n\nimport { reservedRoomPrefix, socketIdShaped } from \"../../contract/names\";\nimport type { ChannelDef, StreamDef } from \"../../contract/realtime\";\n\n/** `value`, when it can name an app room. */\nfunction appRoom(value: unknown): string | undefined {\n  return typeof value === \"string\" &&\n    value !== \"\" &&\n    reservedRoomPrefix(value) === undefined &&\n    !socketIdShaped(value)\n    ? value\n    : undefined;\n}\n\n/** Calls a room function of the contract; one that throws names no room. */\nfunction computed(room: unknown, value: unknown): string | undefined {\n  try {\n    return appRoom((room as (input: unknown) => unknown)(value));\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The room a host-served channel's message is for: its requirement's name,\n * the one it computes from `payload`, or for `{ prefix }` the first of\n * `rooms` (the rooms whose host is known) that starts with it.\n */\nexport function channelRoomOf(\n  def: ChannelDef,\n  payload: unknown,\n  rooms: Iterable<string>,\n): string | undefined {\n  const room = def.requires?.room;\n  if (typeof room === \"string\") {\n    return room;\n  }\n  if (typeof room === \"function\") {\n    return computed(room, payload);\n  }\n  if (typeof room === \"object\") {\n    for (const known of rooms) {\n      if (known.startsWith(room.prefix)) {\n        return known;\n      }\n    }\n  }\n  return undefined;\n}\n\n/** The room whose host serves a host-served stream's feed of `scope`. */\nexport function streamRoomOf(def: StreamDef, scope: string): string | undefined {\n  const access = typeof def.access === \"object\" ? def.access : undefined;\n  const room = access?.room;\n  return typeof room === \"function\" ? computed(room, scope) : undefined;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-ZIVPHYRG.js → chunk-NZHA4TZD.js}

@@ -10,23 +10,18 @@ import {
   createBinding,
   createInvalidationCoordinator,
   createMutationTrace,
-  createQuickdrawConnection,
   entityScopes,
   entryQuery,
   feedKey,
   invalidateWith,
-  isTimeLimit,
   isWatchedQuery,
   liveDataOf,
   loopGuardOf,
   newItem,
-  notifyEach,
   overlaysOf,
   reconnectJitter,
   refetchOnAccessChanges,
   registerQuery,
-  reloadOncePerSession,
-  retryAfterOf,
   searchCall,
   searchTargetOf,
   serverStateOf,
@@ -43,167 +38,45 @@ import {
   useQuickdrawContext,
   userOf,
   viewPredicate
-} from "./chunk-OECZPRPW.js";
+} from "./chunk-64I6MYBC.js";
 import {
-  CLIENT_EVENTS,
-  SERVICE_TOPIC,
-  collectionTopic
-} from "./chunk-VSQBHPWH.js";
+  call,
+  callData,
+  channelRoomOf,
+  isNotModified,
+  isUnknownOutcome,
+  shouldRetry,
+  streamRoomOf
+} from "./chunk-NX2V6SIL.js";
 import {
-  isScopedStream
-} from "./chunk-RT6OILOI.js";
+  createQuickdrawConnection,
+  hostLinksOf,
+  hostsOf,
+  mayConnect,
+  reloadOncePerSession
+} from "./chunk-STH5DLQP.js";
 import {
   buildCaller,
   collectionKey,
   entityKey,
   methodKey,
   methodKeyPrefix
-} from "./chunk-X5CWPX7H.js";
+} from "./chunk-IIQ3WMJK.js";
+import {
+  CLIENT_EVENTS,
+  SERVICE_TOPIC,
+  collectionTopic
+} from "./chunk-X4ZU4QH5.js";
+import {
+  isHostServed,
+  isScopedStream
+} from "./chunk-GYLWEJHW.js";
+import {
+  QuickdrawError
+} from "./chunk-Q4OGQM5I.js";
 import {
-  QuickdrawError,
-  fromWire,
   isRecord
-} from "./chunk-4YO5H5ON.js";
-
-// src/client/call.ts
-var UNSENT_TIMEOUT = "operation has timed out";
-function isNotModified(result) {
-  return result.nm === true;
-}
-function cancelledError() {
-  return new QuickdrawError("CANCELLED", "The call was cancelled");
-}
-function internalError(message) {
-  return new QuickdrawError("INTERNAL", message);
-}
-var lostInFlight = /* @__PURE__ */ new WeakSet();
-function isUnknownOutcome(error) {
-  return error instanceof QuickdrawError && (error.code === "TIMEOUT" || lostInFlight.has(error));
-}
-function lostError() {
-  const error = internalError("No answer: the connection to the server is down");
-  lostInFlight.add(error);
-  return error;
-}
-function refusedBeforeSending(connection, kind, signal) {
-  if (signal?.aborted === true) {
-    return cancelledError();
-  }
-  const { socket } = connection;
-  if (!socket.connected && !socket.active) {
-    return internalError("Not connected to the server");
-  }
-  const remaining = connection.backoffRemaining(kind);
-  if (remaining > 0) {
-    return new QuickdrawError(
-      "RATE_LIMITED",
-      `Waiting before more ${kind} calls: the server answered RATE_LIMITED`,
-      { retryAfterMs: Math.ceil(remaining) }
-    );
-  }
-  return void 0;
-}
-function envelopeOf(id, request) {
-  return {
-    id,
-    s: request.service,
-    m: request.method,
-    ...request.input === void 0 ? {} : { i: request.input },
-    ...request.v === void 0 ? {} : { v: request.v }
-  };
-}
-function readReply(connection, kind, reply) {
-  if (isRecord(reply) && reply.ok === true) {
-    const versioned = typeof reply.v === "string" || typeof reply.v === "number";
-    if (reply.nm === true && !versioned) {
-      return internalError("The server answered not modified without a version");
-    }
-    return reply;
-  }
-  if (isRecord(reply) && reply.ok === false) {
-    const error = fromWire(reply.e);
-    if (error.code === "RATE_LIMITED") {
-      connection.reportRateLimited(kind, retryAfterOf(error));
-    }
-    return error;
-  }
-  return internalError("The server's reply is not a call reply");
-}
-function isQueuedCall(data, id) {
-  return Array.isArray(data) && data[0] === CLIENT_EVENTS.call && isRecord(data[1]) && data[1].id === id;
-}
-function cancelCall(socket, id) {
-  const queued = socket.sendBuffer.findIndex((packet) => isQueuedCall(packet.data, id));
-  if (queued >= 0) {
-    socket.sendBuffer.splice(queued, 1);
-  } else if (socket.connected) {
-    socket.emit(CLIENT_EVENTS.cancel, { id });
-  }
-}
-function call(connection, request) {
-  const kind = request.kind ?? "query";
-  const { signal } = request;
-  const refused = refusedBeforeSending(connection, kind, signal);
-  if (refused !== void 0) {
-    return Promise.reject(refused);
-  }
-  const { socket } = connection;
-  const timeoutMs = request.timeoutMs ?? connection.timeoutMs;
-  if (!isTimeLimit(timeoutMs)) {
-    return Promise.reject(
-      new TypeError(
-        "call: timeoutMs must be a number of milliseconds, above 0 and at most 2^31 - 1"
-      )
-    );
-  }
-  const id = connection.nextCallId();
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const settle = (outcome) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      signal?.removeEventListener("abort", onAbort);
-      if (outcome instanceof QuickdrawError) {
-        reject(outcome);
-      } else {
-        notifyEach([request.onReply], (onReply) => {
-          onReply?.(outcome);
-        });
-        resolve(outcome);
-      }
-    };
-    function onAbort() {
-      cancelCall(socket, id);
-      settle(cancelledError());
-    }
-    socket.timeout(timeoutMs).emit(CLIENT_EVENTS.call, envelopeOf(id, request), (error, reply) => {
-      if (error === null) {
-        settle(readReply(connection, kind, reply));
-      } else if (error instanceof QuickdrawError) {
-        settle(error);
-      } else if (socket.connected) {
-        settle(new QuickdrawError("TIMEOUT", `No answer within ${timeoutMs} ms`));
-      } else if (error.message === UNSENT_TIMEOUT) {
-        settle(internalError("No answer: the connection to the server is down"));
-      } else {
-        settle(lostError());
-      }
-    });
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-async function callData(connection, request) {
-  const result = await call(connection, request);
-  if (isNotModified(result)) {
-    throw internalError("The server answered not modified to a call that sent no version");
-  }
-  return result.d;
-}
-function shouldRetry(failureCount, error) {
-  return failureCount < 1 && (!(error instanceof QuickdrawError) || error.code === "INTERNAL");
-}
+} from "./chunk-QSU47XEX.js";
 
 // src/client/live/useSearch.ts
 import { useQuery as useQuery2 } from "@tanstack/react-query";
@@ -310,7 +183,7 @@ async function fetchVersioned(connection, queryClient, query, signal) {
   return fetchFresh(connection, query, signal);
 }
 async function helloKnown(connection, signal) {
-  const ready = () => connection.getState().hello !== null || !connection.socket.active || signal?.aborted === true;
+  const ready = () => connection.getState().hello !== null || !mayConnect(connection) || signal?.aborted === true;
   if (ready()) {
     return;
   }
@@ -356,7 +229,9 @@ async function fetchMethodQuery(connection, queryClient, query, signal) {
 }
 
 // src/client/queryHooks.ts
-import { hashKey } from "@tanstack/react-query";
+import {
+  hashKey
+} from "@tanstack/react-query";
 import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 function watchedModelsOf(target) {
   const { watch } = target;
@@ -465,6 +340,19 @@ function useOverlaySelect(queryClient, target, select) {
     };
   }, [shape, view, select]);
 }
+function placeholderFromCache(queryClient, placeholderData) {
+  if (typeof placeholderData !== "function") {
+    return placeholderData;
+  }
+  const asked = placeholderData;
+  const fromCache = (previousData, previousQuery) => previousQuery === void 0 || queryClient.getQueryCache().get(previousQuery.queryHash) === previousQuery ? asked(previousData, previousQuery) : void 0;
+  return fromCache;
+}
+function placeholderOption(queryClient, queryKey, options) {
+  const keyDefaults = queryClient.getQueryDefaults(queryKey);
+  const given = "placeholderData" in options ? options.placeholderData : Object.hasOwn(keyDefaults, "placeholderData") ? keyDefaults.placeholderData : queryClient.getDefaultOptions().queries?.placeholderData;
+  return placeholderFromCache(queryClient, given);
+}
 function hiddenResult(result) {
   return {
     ...result,
@@ -725,6 +613,7 @@ function useMethodQuery(target, input, options = {}) {
     enabled: live ? enabled ?? true : false,
     retry: retry ?? shouldRetry,
     structuralSharing: shareKeepingVersion(structuralSharing),
+    placeholderData: placeholderOption(queryClient, queryKey, options),
     ...shown2 === void 0 ? {} : { select: shown2 }
   });
   return awaiting ? hiddenResult(result) : result;
@@ -939,17 +828,25 @@ function clientAdminNamespace(contract, methods) {
 
 // src/client/live/useChannel.ts
 import { useCallback, useMemo as useMemo4 } from "react";
-function useChannel(service, channel) {
+function useChannel(service, channel, def) {
   const { connection } = useQuickdrawContext(`${service}.${channel}.useChannel`);
   const state = useConnectionState(connection);
   const send = useCallback(
     (payload) => {
       const { socket } = connection;
-      if (socket.connected) {
-        socket.volatile.emit(CLIENT_EVENTS.channel, [service, channel, payload]);
+      if (!socket.connected) {
+        return;
+      }
+      if (def !== void 0 && isHostServed(def)) {
+        const room = channelRoomOf(def, payload, hostsOf(connection).rooms.keys());
+        if (room !== void 0) {
+          hostLinksOf(connection).send(room, service, channel, payload);
+        }
+        return;
       }
+      socket.volatile.emit(CLIENT_EVENTS.channel, [service, channel, payload]);
     },
-    [connection, service, channel]
+    [connection, service, channel, def]
   );
   const isReady = state.status === "connected" && state.hello !== null;
   return useMemo4(() => ({ send, isReady }), [send, isReady]);
@@ -1016,13 +913,16 @@ function streamMember(target) {
 }
 function realtimeMembers(contract) {
   const service = contract.name;
-  const streams = Object.entries(contract.streams).map(([stream, def]) => [
-    stream,
-    streamMember(Object.freeze({ service, stream, scoped: isScopedStream(def) }))
-  ]);
-  const channels = Object.keys(contract.channels).map((channel) => [
+  const streams = Object.entries(contract.streams).map(([stream, def]) => {
+    const host = isHostServed(def) ? { host: (scope) => streamRoomOf(def, scope) } : {};
+    return [
+      stream,
+      streamMember(Object.freeze({ service, stream, scoped: isScopedStream(def), ...host }))
+    ];
+  });
+  const channels = Object.entries(contract.channels).map(([channel, def]) => [
     channel,
-    Object.freeze({ useChannel: () => useChannel(service, channel) })
+    Object.freeze({ useChannel: () => useChannel(service, channel, def) })
   ]);
   const events = Object.keys(contract.events).map((event) => [
     event,
@@ -1244,9 +1144,11 @@ function searchMember(target, definition, contract) {
 var RESERVED_KEYS = ["invalidate"];
 function queryMember(binding, target, extra) {
   const key = (input) => methodKey(target.service, target.method, input);
+  const defaults = target.queryDefaults;
   const member = Object.freeze({
     ...extra,
-    useQuery: (input, options) => useMethodQuery(target, input, options),
+    // The caller's options over the method's defaults (the admin kit's reads of rows: `staleTime: 0`).
+    useQuery: (input, options) => useMethodQuery(target, input, defaults === void 0 ? options : { ...defaults, ...options }),
     call: async (input, options) => await callData(connectionOf(binding, target, "call"), {
       ...target,
       input,
@@ -1399,15 +1301,10 @@ function useQuickdraw() {
 }
 
 export {
-  isNotModified,
-  isUnknownOutcome,
-  call,
-  callData,
-  shouldRetry,
   useLiveData,
   SEARCH_DEBOUNCE_MS,
   createQuickdrawClient,
   QuickdrawProvider,
   useQuickdraw
 };
-//# sourceMappingURL=chunk-ZIVPHYRG.js.map
+//# sourceMappingURL=chunk-NZHA4TZD.js.map