@rocicorp/zero 0.25.0-canary.1 → 0.25.0-canary.11

package/out/zero-client/src/client/active-clients-manager.js

@@ -0,0 +1,199 @@
+import { resolver } from "@rocicorp/resolver";
+import { BroadcastChannel as bc } from "../../../shared/src/broadcast-channel.js";
+import { getBrowserGlobal } from "../../../shared/src/browser-env.js";
+const keyPrefix = "zero-active";
+function toLockName(clientGroupID, clientID) {
+  return `${keyPrefix}/${clientGroupID}/${clientID}`;
+}
+function toBroadcastChannelName(clientGroupID) {
+  return `${keyPrefix}/${clientGroupID}`;
+}
+function fromLockName(lockKey) {
+  if (!lockKey || !lockKey.startsWith(keyPrefix)) {
+    return void 0;
+  }
+  const parts = lockKey.slice(keyPrefix.length).split("/");
+  if (parts.length !== 3) {
+    return void 0;
+  }
+  return {
+    clientGroupID: parts[1],
+    clientID: parts[2]
+  };
+}
+function ignoreAbortError(e) {
+  if (e instanceof Error && e.name === "AbortError") {
+    return;
+  }
+  throw e;
+}
+class ActiveClientsManager {
+  clientGroupID;
+  clientID;
+  #resolver = resolver();
+  #lockManager;
+  #activeClients = /* @__PURE__ */ new Set();
+  /**
+   * A callback that is called when a client is added to the client group.
+   * It receives the client ID of the added client.
+   */
+  onAdd;
+  /**
+   * A callback that is called when a client is deleted from the client group.
+   * It receives the client ID of the deleted client.
+   */
+  onDelete;
+  /**
+   * Creates an instance of `ActiveClientsManager` for the specified client
+   * group and client ID. It will return a promise that resolves when the
+   * instance is ready to use, which means that it has successfully acquired the
+   * exclusive lock for the client and has retrieved the list of active clients.
+   */
+  static async create(clientGroupID, clientID, signal) {
+    const instance = new ActiveClientsManager(clientGroupID, clientID, signal);
+    await instance.#init(signal);
+    return instance;
+  }
+  constructor(clientGroupID, clientID, signal) {
+    this.clientGroupID = clientGroupID;
+    this.clientID = clientID;
+    this.#lockManager = getClientLockManager(signal);
+    this.#activeClients.add(clientID);
+  }
+  async #init(signal) {
+    const { clientGroupID, clientID } = this;
+    const name = toLockName(clientGroupID, clientID);
+    const channel = new bc(toBroadcastChannelName(clientGroupID));
+    channel.addEventListener(
+      "message",
+      (e) => {
+        const client = fromLockName(e.data);
+        if (client?.clientGroupID === this.clientGroupID) {
+          this.#addClient(client.clientID);
+        }
+      },
+      { signal }
+    );
+    this.#lockManager.request(name, "exclusive", () => this.#resolver.promise).catch(ignoreAbortError);
+    signal.addEventListener(
+      "abort",
+      () => {
+        this.#lockManager.release(name, () => this.#resolver.resolve());
+        channel.close();
+      },
+      { once: true }
+    );
+    for (const clientID2 of await this.#getActiveClients()) {
+      if (clientID2 !== this.clientID) {
+        this.#addClient(clientID2);
+      }
+    }
+    if (!signal.aborted) {
+      channel.postMessage(name);
+    }
+  }
+  get activeClients() {
+    return this.#activeClients;
+  }
+  async #getActiveClients() {
+    const activeClients = /* @__PURE__ */ new Set();
+    for await (const lockName of this.#lockManager.queryExclusive()) {
+      const client = fromLockName(lockName);
+      if (client?.clientGroupID === this.clientGroupID) {
+        activeClients.add(client.clientID);
+      }
+    }
+    return activeClients;
+  }
+  /**
+   * This gets called when a new client is added to the client group.
+   *
+   * It will request a shared lock for the client, and when the exclusive lock
+   * is released, it will notify that the client has been deactivated.
+   */
+  #addSharedLockForOtherClient(clientID) {
+    const name = toLockName(this.clientGroupID, clientID);
+    this.#lockManager.request(name, "shared", () => this.#removeClient(clientID)).catch(ignoreAbortError);
+  }
+  #addClient(clientID) {
+    if (!this.#activeClients.has(clientID)) {
+      this.#activeClients.add(clientID);
+      this.#addSharedLockForOtherClient(clientID);
+      this.onAdd?.(clientID);
+    }
+  }
+  #removeClient(clientID) {
+    if (this.#activeClients.delete(clientID)) {
+      this.onDelete?.(clientID, this.clientGroupID);
+    }
+  }
+}
+function getClientLockManager(signal) {
+  const locks = getBrowserGlobal("navigator")?.locks;
+  if (locks) {
+    return new NativeClientLockManager(locks, signal);
+  }
+  return new MockClientLockManager();
+}
+class NativeClientLockManager {
+  #locks;
+  #signal;
+  constructor(locks, signal) {
+    this.#locks = locks;
+    this.#signal = signal;
+  }
+  async request(name, mode, fn) {
+    await this.#locks.request(name, { mode, signal: this.#signal }, fn);
+  }
+  release(_name, fn) {
+    fn();
+  }
+  async *queryExclusive() {
+    const snapshot = await this.#locks.query();
+    for (const lock of [
+      ...snapshot.held ?? [],
+      ...snapshot.pending ?? []
+    ]) {
+      if (lock.mode === "exclusive" && lock.name) {
+        yield lock.name;
+      }
+    }
+  }
+}
+const mockLockNames = /* @__PURE__ */ new Set();
+const mockListeners = /* @__PURE__ */ new Set();
+class MockClientLockManager {
+  #listeners = /* @__PURE__ */ new Set();
+  request(name, mode, fn) {
+    if (mode === "exclusive") {
+      mockLockNames.add(name);
+    } else {
+      const listener = (removed) => {
+        if (removed === name) {
+          mockListeners.delete(listener);
+          return fn();
+        }
+      };
+      mockListeners.add(listener);
+      this.#listeners.add(listener);
+    }
+    return Promise.resolve();
+  }
+  release(name, fn) {
+    mockLockNames.delete(name);
+    for (const listener of mockListeners) {
+      listener(name);
+    }
+    for (const listener of this.#listeners) {
+      mockListeners.delete(listener);
+    }
+    fn();
+  }
+  async *queryExclusive() {
+    yield* mockLockNames;
+  }
+}
+export {
+  ActiveClientsManager
+};
+//# sourceMappingURL=active-clients-manager.js.map

package/out/zero-client/src/client/active-clients-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-clients-manager.js","sources":["../../../../../zero-client/src/client/active-clients-manager.ts"],"sourcesContent":["import {resolver} from '@rocicorp/resolver';\nimport type {\n  ClientGroupID,\n  ClientID,\n} from '../../../replicache/src/sync/ids.ts';\nimport {BroadcastChannel} from '../../../shared/src/broadcast-channel.ts';\nimport {getBrowserGlobal} from '../../../shared/src/browser-env.ts';\nimport type {MaybePromise} from '../../../shared/src/types.ts';\n\n/**\n * The prefix for the keys used for the locks and the broadcast channels.\n */\nconst keyPrefix = 'zero-active';\n\nfunction toLockName(clientGroupID: string, clientID: string): string {\n  return `${keyPrefix}/${clientGroupID}/${clientID}`;\n}\n\nfunction toBroadcastChannelName(clientGroupID: string): string {\n  return `${keyPrefix}/${clientGroupID}`;\n}\n\nfunction fromLockName(\n  lockKey: string | undefined,\n): {clientGroupID: string; clientID: string} | undefined {\n  if (!lockKey || !lockKey.startsWith(keyPrefix)) {\n    return undefined;\n  }\n  const parts = lockKey.slice(keyPrefix.length).split('/');\n  if (parts.length !== 3) {\n    return undefined;\n  }\n  return {\n    clientGroupID: parts[1],\n    clientID: parts[2],\n  };\n}\n\nfunction ignoreAbortError(e: unknown) {\n  if (e instanceof Error && e.name === 'AbortError') {\n    // Ignore the AbortError, it is expected when the signal is aborted.\n    return;\n  }\n  throw e;\n}\n\n/**\n * A class that lists the active clients in a client group. It uses the\n * `navigator.locks` API to manage locks for each client. The class is designed\n * to be used in a browser environment where the `navigator.locks` API is\n * available.\n *\n * When navigator.locks is not available, it will return a set only containing\n * the clients in the current scripting context (window, worker, etc).\n *\n * It uses one exclusive lock per client, identified by a combination of\n * `clientGroupID` and `clientID`. Then the `query` method is used to get the\n * list of all clients that hold or are waiting for locks in the same client\n * group.\n *\n * It also tries to get a shared lock for each client in the group, so that it\n * can be notified when the exclusive lock is released. This allows the class to\n * keep track of the active clients in the group and notify when an existing\n * client is removed.\n *\n * The class also uses a `BroadcastChannel` to notify other clients in the\n * same client group when a new client is added. This allows the class to keep\n * track of the active clients in the group and notify when a new client is\n * added.\n */\nexport class ActiveClientsManager {\n  readonly clientGroupID: string;\n  readonly clientID: string;\n  readonly #resolver = resolver<void>();\n  readonly #lockManager: ClientLockManager;\n  readonly #activeClients: Set<string> = new Set();\n\n  /**\n   * A callback that is called when a client is added to the client group.\n   * It receives the client ID of the added client.\n   */\n  onAdd: ((clientID: string) => void) | undefined;\n\n  /**\n   * A callback that is called when a client is deleted from the client group.\n   * It receives the client ID of the deleted client.\n   */\n  onDelete:\n    | ((clientID: ClientID, clientGroupID: ClientGroupID) => void)\n    | undefined;\n\n  /**\n   * Creates an instance of `ActiveClientsManager` for the specified client\n   * group and client ID. It will return a promise that resolves when the\n   * instance is ready to use, which means that it has successfully acquired the\n   * exclusive lock for the client and has retrieved the list of active clients.\n   */\n  static async create(\n    clientGroupID: string,\n    clientID: string,\n    signal: AbortSignal,\n  ): Promise<ActiveClientsManager> {\n    const instance = new ActiveClientsManager(clientGroupID, clientID, signal);\n    await instance.#init(signal);\n    return instance;\n  }\n\n  private constructor(\n    clientGroupID: string,\n    clientID: string,\n    signal: AbortSignal,\n  ) {\n    this.clientGroupID = clientGroupID;\n    this.clientID = clientID;\n    this.#lockManager = getClientLockManager(signal);\n    this.#activeClients.add(clientID);\n  }\n\n  async #init(signal: AbortSignal): Promise<void> {\n    const {clientGroupID, clientID} = this;\n    const name = toLockName(clientGroupID, clientID);\n\n    // The BroadcastChannel is used to notify other clients in the same client\n    // group when a new client is added. It listens for messages that contain\n    // the lock name, which is used to identify the client. When a message is\n    // received, it checks if the client belongs to the same client group and\n    // adds it to the list of active clients. It also adds a shared lock for\n    // the client, so that it can be notified when the exclusive lock is\n    // released.\n    const channel = new BroadcastChannel(toBroadcastChannelName(clientGroupID));\n    channel.addEventListener(\n      'message',\n      e => {\n        const client = fromLockName(e.data);\n        if (client?.clientGroupID === this.clientGroupID) {\n          this.#addClient(client.clientID);\n        }\n      },\n      {signal},\n    );\n\n    this.#lockManager\n      .request(name, 'exclusive', () => this.#resolver.promise)\n      .catch(ignoreAbortError);\n\n    signal.addEventListener(\n      'abort',\n      () => {\n        this.#lockManager.release(name, () => this.#resolver.resolve());\n        channel.close();\n      },\n      {once: true},\n    );\n\n    for (const clientID of await this.#getActiveClients()) {\n      if (clientID !== this.clientID) {\n        this.#addClient(clientID);\n      }\n    }\n\n    if (!signal.aborted) {\n      channel.postMessage(name);\n    }\n  }\n\n  get activeClients(): ReadonlySet<string> {\n    return this.#activeClients;\n  }\n\n  async #getActiveClients(): Promise<Set<string>> {\n    const activeClients: Set<string> = new Set();\n\n    for await (const lockName of this.#lockManager.queryExclusive()) {\n      const client = fromLockName(lockName);\n      if (client?.clientGroupID === this.clientGroupID) {\n        activeClients.add(client.clientID);\n      }\n    }\n\n    return activeClients;\n  }\n\n  /**\n   * This gets called when a new client is added to the client group.\n   *\n   * It will request a shared lock for the client, and when the exclusive lock\n   * is released, it will notify that the client has been deactivated.\n   */\n  #addSharedLockForOtherClient(clientID: string): void {\n    const name = toLockName(this.clientGroupID, clientID);\n    this.#lockManager\n      .request(name, 'shared', () => this.#removeClient(clientID))\n      .catch(ignoreAbortError);\n  }\n\n  #addClient(clientID: string): void {\n    if (!this.#activeClients.has(clientID)) {\n      this.#activeClients.add(clientID);\n      this.#addSharedLockForOtherClient(clientID);\n      this.onAdd?.(clientID);\n    }\n  }\n\n  #removeClient(clientID: string): void {\n    if (this.#activeClients.delete(clientID)) {\n      this.onDelete?.(clientID, this.clientGroupID);\n    }\n  }\n}\n\nfunction getClientLockManager(signal: AbortSignal): ClientLockManager {\n  const locks = getBrowserGlobal('navigator')?.locks;\n  if (locks) {\n    return new NativeClientLockManager(locks, signal);\n  }\n  return new MockClientLockManager();\n}\n\ninterface ClientLockManager {\n  request(\n    name: string,\n    mode: 'exclusive' | 'shared',\n    fn: () => MaybePromise<void>,\n  ): Promise<void>;\n  release(name: string, fn: () => void): void;\n  queryExclusive(): AsyncIterable<string>;\n}\n\nclass NativeClientLockManager implements ClientLockManager {\n  readonly #locks: LockManager;\n  readonly #signal: AbortSignal;\n\n  constructor(locks: LockManager, signal: AbortSignal) {\n    this.#locks = locks;\n    this.#signal = signal;\n  }\n\n  async request(\n    name: string,\n    mode: 'exclusive' | 'shared',\n    fn: () => Promise<void>,\n  ): Promise<void> {\n    await this.#locks.request(name, {mode, signal: this.#signal}, fn);\n  }\n\n  release(_name: string, fn: () => void): void {\n    fn();\n  }\n\n  async *queryExclusive(): AsyncIterable<string> {\n    const snapshot = await this.#locks.query();\n    for (const lock of [\n      ...(snapshot.held ?? []),\n      ...(snapshot.pending ?? []),\n    ]) {\n      if (lock.mode === 'exclusive' && lock.name) {\n        yield lock.name;\n      }\n    }\n  }\n}\n\nconst mockLockNames = new Set<string>();\n\nconst mockListeners: Set<(name: string) => void> = new Set();\n\nclass MockClientLockManager implements ClientLockManager {\n  readonly #listeners: Set<(name: string) => void> = new Set();\n\n  request(\n    name: string,\n    mode: 'exclusive' | 'shared',\n    fn: () => void | Promise<void>,\n  ): Promise<void> {\n    if (mode === 'exclusive') {\n      mockLockNames.add(name);\n    } else {\n      mode satisfies 'shared';\n\n      // For the mock locks we will add a listener that will notify us when the\n      // lock is deleted from the `allMockLocks` set.\n      const listener = (removed: string) => {\n        if (removed === name) {\n          mockListeners.delete(listener);\n          return fn();\n        }\n      };\n      mockListeners.add(listener);\n      this.#listeners.add(listener);\n    }\n    return Promise.resolve();\n  }\n\n  release(name: string, fn: () => void): void {\n    mockLockNames.delete(name);\n    for (const listener of mockListeners) {\n      listener(name);\n    }\n    for (const listener of this.#listeners) {\n      mockListeners.delete(listener);\n    }\n    fn();\n  }\n\n  async *queryExclusive(): AsyncIterable<string> {\n    yield* mockLockNames;\n  }\n}\n"],"names":["BroadcastChannel","clientID"],"mappings":"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"}

package/out/zero-client/src/client/bindings.d.ts

@@ -0,0 +1,43 @@
+import type { Schema } from '../../../zero-types/src/schema.ts';
+import type { Format, ViewFactory } from '../../../zql/src/ivm/view.ts';
+import type { AnyMutatorRegistry } from '../../../zql/src/mutate/mutator-registry.ts';
+import type { QueryDelegate } from '../../../zql/src/query/query-delegate.ts';
+import type { HumanReadable, MaterializeOptions, Query } from '../../../zql/src/query/query.ts';
+import type { TypedView } from '../../../zql/src/query/typed-view.ts';
+import type { CustomMutatorDefs } from './custom.ts';
+import type { Zero } from './zero.ts';
+export declare function registerZeroDelegate<TSchema extends Schema, MD extends AnyMutatorRegistry | CustomMutatorDefs | undefined, TContext>(zero: Zero<TSchema, MD, TContext>, delegate: QueryDelegate): void;
+/**
+ * Bindings interface for Zero instances, providing methods to materialize queries
+ * and extract query metadata.
+ *
+ * @internal This API is for bindings only, not end users.
+ */
+export interface BindingsForZero<TSchema extends Schema> {
+    /**
+     * Materialize a query into a reactive view without a custom factory.
+     * Returns a TypedView that automatically updates when underlying data changes.
+     */
+    materialize<TTable extends keyof TSchema['tables'] & string, TReturn>(query: Query<TTable, TSchema, TReturn>, factory?: undefined, options?: MaterializeOptions): TypedView<HumanReadable<TReturn>>;
+    /**
+     * Materialize a query into a reactive view using a custom factory.
+     * The factory can transform the view into a framework-specific reactive object.
+     */
+    materialize<TTable extends keyof TSchema['tables'] & string, TReturn, T>(query: Query<TTable, TSchema, TReturn>, factory: ViewFactory<TTable, TSchema, TReturn, T>, options?: MaterializeOptions): T;
+    /**
+     * Compute the hash of a query for caching and deduplication purposes.
+     */
+    hash<TTable extends keyof TSchema['tables'] & string, TReturn>(query: Query<TTable, TSchema, TReturn>): string;
+    /**
+     * Get the format/schema of a query's result set.
+     */
+    format<TTable extends keyof TSchema['tables'] & string, TReturn>(query: Query<TTable, TSchema, TReturn>): Format;
+}
+/**
+ * Create a bindings object for a Zero instance.
+ * This provides low-level access to query materialization and metadata extraction.
+ *
+ * @internal This API is for bindings only, not end users.
+ */
+export declare function bindingsForZero<TSchema extends Schema, MD extends AnyMutatorRegistry | CustomMutatorDefs | undefined, TContext>(zero: Zero<TSchema, MD, TContext>): BindingsForZero<TSchema>;
+//# sourceMappingURL=bindings.d.ts.map

package/out/zero-client/src/client/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../../../../zero-client/src/client/bindings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mCAAmC,CAAC;AAC9D,OAAO,KAAK,EAAC,MAAM,EAAE,WAAW,EAAC,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,6CAA6C,CAAC;AACpF,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,0CAA0C,CAAC;AAE5E,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,KAAK,EACN,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,sCAAsC,CAAC;AACpE,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAapC,wBAAgB,oBAAoB,CAClC,OAAO,SAAS,MAAM,EACtB,EAAE,SAAS,kBAAkB,GAAG,iBAAiB,GAAG,SAAS,EAC7D,QAAQ,EACR,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAElE;AAcD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,MAAM;IACrD;;;OAGG;IACH,WAAW,CAAC,MAAM,SAAS,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAClE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EACtC,OAAO,CAAC,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAErC;;;OAGG;IACH,WAAW,CAAC,MAAM,SAAS,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,EACrE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EACtC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,EACjD,OAAO,CAAC,EAAE,kBAAkB,GAC3B,CAAC,CAAC;IAEL;;OAEG;IACH,IAAI,CAAC,MAAM,SAAS,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAC3D,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,GACrC,MAAM,CAAC;IAEV;;OAEG;IACH,MAAM,CAAC,MAAM,SAAS,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,OAAO,EAC7D,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,GACrC,MAAM,CAAC;CACX;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,SAAS,MAAM,EACtB,EAAE,SAAS,kBAAkB,GAAG,iBAAiB,GAAG,SAAS,EAC7D,QAAQ,EACR,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,CA0B7D"}

package/out/zero-client/src/client/bindings.js

@@ -0,0 +1,33 @@
+import { asQueryInternals } from "../../../zql/src/query/query-internals.js";
+const zeroDelegates = /* @__PURE__ */ new WeakMap();
+function registerZeroDelegate(zero, delegate) {
+  zeroDelegates.set(zero, delegate);
+}
+function mustGetDelegate(zero) {
+  const delegate = zeroDelegates.get(zero);
+  if (!delegate) {
+    throw new Error("Zero instance not registered with bindings");
+  }
+  return delegate;
+}
+function bindingsForZero(zero) {
+  const delegate = mustGetDelegate(zero);
+  return {
+    materialize(query, factory, options) {
+      return delegate.materialize(query, factory, options);
+    },
+    hash(query) {
+      const queryInternals = asQueryInternals(query);
+      return queryInternals.hash();
+    },
+    format(query) {
+      const queryInternals = asQueryInternals(query);
+      return queryInternals.format;
+    }
+  };
+}
+export {
+  bindingsForZero,
+  registerZeroDelegate
+};
+//# sourceMappingURL=bindings.js.map

package/out/zero-client/src/client/bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.js","sources":["../../../../../zero-client/src/client/bindings.ts"],"sourcesContent":["import type {Schema} from '../../../zero-types/src/schema.ts';\nimport type {Format, ViewFactory} from '../../../zql/src/ivm/view.ts';\nimport type {AnyMutatorRegistry} from '../../../zql/src/mutate/mutator-registry.ts';\nimport type {QueryDelegate} from '../../../zql/src/query/query-delegate.ts';\nimport {asQueryInternals} from '../../../zql/src/query/query-internals.ts';\nimport type {\n  HumanReadable,\n  MaterializeOptions,\n  Query,\n} from '../../../zql/src/query/query.ts';\nimport type {TypedView} from '../../../zql/src/query/typed-view.ts';\nimport type {CustomMutatorDefs} from './custom.ts';\nimport type {Zero} from './zero.ts';\n\n/**\n * Internal WeakMap to store QueryDelegate for each Zero instance.\n * This is populated by Zero's constructor and allows bindings to access\n * the delegate without exposing it as a public API.\n */\nconst zeroDelegates = new WeakMap<\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  Zero<any, any, any>,\n  QueryDelegate\n>();\n\nexport function registerZeroDelegate<\n  TSchema extends Schema,\n  MD extends AnyMutatorRegistry | CustomMutatorDefs | undefined,\n  TContext,\n>(zero: Zero<TSchema, MD, TContext>, delegate: QueryDelegate): void {\n  zeroDelegates.set(zero, delegate);\n}\n\nfunction mustGetDelegate<\n  TSchema extends Schema,\n  MD extends AnyMutatorRegistry | CustomMutatorDefs | undefined,\n  TContext,\n>(zero: Zero<TSchema, MD, TContext>): QueryDelegate {\n  const delegate = zeroDelegates.get(zero);\n  if (!delegate) {\n    throw new Error('Zero instance not registered with bindings');\n  }\n  return delegate;\n}\n\n/**\n * Bindings interface for Zero instances, providing methods to materialize queries\n * and extract query metadata.\n *\n * @internal This API is for bindings only, not end users.\n */\nexport interface BindingsForZero<TSchema extends Schema> {\n  /**\n   * Materialize a query into a reactive view without a custom factory.\n   * Returns a TypedView that automatically updates when underlying data changes.\n   */\n  materialize<TTable extends keyof TSchema['tables'] & string, TReturn>(\n    query: Query<TTable, TSchema, TReturn>,\n    factory?: undefined,\n    options?: MaterializeOptions,\n  ): TypedView<HumanReadable<TReturn>>;\n\n  /**\n   * Materialize a query into a reactive view using a custom factory.\n   * The factory can transform the view into a framework-specific reactive object.\n   */\n  materialize<TTable extends keyof TSchema['tables'] & string, TReturn, T>(\n    query: Query<TTable, TSchema, TReturn>,\n    factory: ViewFactory<TTable, TSchema, TReturn, T>,\n    options?: MaterializeOptions,\n  ): T;\n\n  /**\n   * Compute the hash of a query for caching and deduplication purposes.\n   */\n  hash<TTable extends keyof TSchema['tables'] & string, TReturn>(\n    query: Query<TTable, TSchema, TReturn>,\n  ): string;\n\n  /**\n   * Get the format/schema of a query's result set.\n   */\n  format<TTable extends keyof TSchema['tables'] & string, TReturn>(\n    query: Query<TTable, TSchema, TReturn>,\n  ): Format;\n}\n\n/**\n * Create a bindings object for a Zero instance.\n * This provides low-level access to query materialization and metadata extraction.\n *\n * @internal This API is for bindings only, not end users.\n */\nexport function bindingsForZero<\n  TSchema extends Schema,\n  MD extends AnyMutatorRegistry | CustomMutatorDefs | undefined,\n  TContext,\n>(zero: Zero<TSchema, MD, TContext>): BindingsForZero<TSchema> {\n  const delegate = mustGetDelegate(zero);\n\n  return {\n    materialize<TTable extends keyof TSchema['tables'] & string, TReturn, T>(\n      query: Query<TTable, TSchema, TReturn>,\n      factory?: ViewFactory<TTable, TSchema, TReturn, T>,\n      options?: MaterializeOptions,\n    ) {\n      return delegate.materialize(query, factory, options);\n    },\n\n    hash<TTable extends keyof TSchema['tables'] & string, TReturn>(\n      query: Query<TTable, TSchema, TReturn>,\n    ): string {\n      const queryInternals = asQueryInternals(query);\n      return queryInternals.hash();\n    },\n\n    format<TTable extends keyof TSchema['tables'] & string, TReturn>(\n      query: Query<TTable, TSchema, TReturn>,\n    ): Format {\n      const queryInternals = asQueryInternals(query);\n      return queryInternals.format;\n    },\n  };\n}\n"],"names":[],"mappings":";AAmBA,MAAM,oCAAoB,QAAA;AAMnB,SAAS,qBAId,MAAmC,UAA+B;AAClE,gBAAc,IAAI,MAAM,QAAQ;AAClC;AAEA,SAAS,gBAIP,MAAkD;AAClD,QAAM,WAAW,cAAc,IAAI,IAAI;AACvC,MAAI,CAAC,UAAU;AACb,UAAM,IAAI,MAAM,4CAA4C;AAAA,EAC9D;AACA,SAAO;AACT;AAkDO,SAAS,gBAId,MAA6D;AAC7D,QAAM,WAAW,gBAAgB,IAAI;AAErC,SAAO;AAAA,IACL,YACE,OACA,SACA,SACA;AACA,aAAO,SAAS,YAAY,OAAO,SAAS,OAAO;AAAA,IACrD;AAAA,IAEA,KACE,OACQ;AACR,YAAM,iBAAiB,iBAAiB,KAAK;AAC7C,aAAO,eAAe,KAAA;AAAA,IACxB;AAAA,IAEA,OACE,OACQ;AACR,YAAM,iBAAiB,iBAAiB,KAAK;AAC7C,aAAO,eAAe;AAAA,IACxB;AAAA,EAAA;AAEJ;"}

package/out/zero-client/src/client/client-error-kind-enum.d.ts

@@ -2,26 +2,26 @@ export declare const AbruptClose = "AbruptClose";
 export declare const CleanClose = "CleanClose";
 export declare const ClientClosed = "ClientClosed";
 export declare const ConnectTimeout = "ConnectTimeout";
-export declare const DisconnectTimeout = "DisconnectTimeout";
-export declare const UnexpectedBaseCookie = "UnexpectedBaseCookie";
-export declare const PingTimeout = "PingTimeout";
-export declare const PullTimeout = "PullTimeout";
 export declare const Hidden = "Hidden";
-export declare const NoSocketOrigin = "NoSocketOrigin";
+export declare const Internal = "Internal";
 export declare const InvalidMessage = "InvalidMessage";
+export declare const NoSocketOrigin = "NoSocketOrigin";
+export declare const Offline = "Offline";
+export declare const PingTimeout = "PingTimeout";
+export declare const PullTimeout = "PullTimeout";
+export declare const UnexpectedBaseCookie = "UnexpectedBaseCookie";
 export declare const UserDisconnect = "UserDisconnect";
-export declare const Internal = "Internal";
 export type AbruptClose = typeof AbruptClose;
 export type CleanClose = typeof CleanClose;
 export type ClientClosed = typeof ClientClosed;
 export type ConnectTimeout = typeof ConnectTimeout;
-export type DisconnectTimeout = typeof DisconnectTimeout;
-export type UnexpectedBaseCookie = typeof UnexpectedBaseCookie;
-export type PingTimeout = typeof PingTimeout;
-export type PullTimeout = typeof PullTimeout;
 export type Hidden = typeof Hidden;
-export type NoSocketOrigin = typeof NoSocketOrigin;
+export type Internal = typeof Internal;
 export type InvalidMessage = typeof InvalidMessage;
+export type NoSocketOrigin = typeof NoSocketOrigin;
+export type Offline = typeof Offline;
+export type PingTimeout = typeof PingTimeout;
+export type PullTimeout = typeof PullTimeout;
+export type UnexpectedBaseCookie = typeof UnexpectedBaseCookie;
 export type UserDisconnect = typeof UserDisconnect;
-export type Internal = typeof Internal;
 //# sourceMappingURL=client-error-kind-enum.d.ts.map

package/out/zero-client/src/client/client-error-kind-enum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-error-kind-enum.d.ts","sourceRoot":"","sources":["../../../../../zero-client/src/client/client-error-kind-enum.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,QAAQ,aAAa,CAAC;AAEnC,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAC7C,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC;AAC3C,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAC/C,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC;AACzD,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC;AAC/D,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAC7C,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC;AACnC,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC"}
+{"version":3,"file":"client-error-kind-enum.d.ts","sourceRoot":"","sources":["../../../../../zero-client/src/client/client-error-kind-enum.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,QAAQ,aAAa,CAAC;AACnC,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,OAAO,YAAY,CAAC;AACjC,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAC7C,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC;AAC3C,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAC/C,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC;AACnC,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC;AACvC,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AACnD,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC;AACrC,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAC7C,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC;AAC/D,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC"}

package/out/zero-client/src/client/client-error-kind-enum.js

@@ -0,0 +1,29 @@
+const AbruptClose = "AbruptClose";
+const CleanClose = "CleanClose";
+const ClientClosed = "ClientClosed";
+const ConnectTimeout = "ConnectTimeout";
+const Hidden = "Hidden";
+const Internal = "Internal";
+const InvalidMessage = "InvalidMessage";
+const NoSocketOrigin = "NoSocketOrigin";
+const Offline = "Offline";
+const PingTimeout = "PingTimeout";
+const PullTimeout = "PullTimeout";
+const UnexpectedBaseCookie = "UnexpectedBaseCookie";
+const UserDisconnect = "UserDisconnect";
+export {
+  AbruptClose,
+  CleanClose,
+  ClientClosed,
+  ConnectTimeout,
+  Hidden,
+  Internal,
+  InvalidMessage,
+  NoSocketOrigin,
+  Offline,
+  PingTimeout,
+  PullTimeout,
+  UnexpectedBaseCookie,
+  UserDisconnect
+};
+//# sourceMappingURL=client-error-kind-enum.js.map

package/out/zero-client/src/client/client-error-kind-enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-error-kind-enum.js","sources":["../../../../../zero-client/src/client/client-error-kind-enum.ts"],"sourcesContent":["export const AbruptClose = 'AbruptClose';\nexport const CleanClose = 'CleanClose';\nexport const ClientClosed = 'ClientClosed';\nexport const ConnectTimeout = 'ConnectTimeout';\nexport const Hidden = 'Hidden';\nexport const Internal = 'Internal';\nexport const InvalidMessage = 'InvalidMessage';\nexport const NoSocketOrigin = 'NoSocketOrigin';\nexport const Offline = 'Offline';\nexport const PingTimeout = 'PingTimeout';\nexport const PullTimeout = 'PullTimeout';\nexport const UnexpectedBaseCookie = 'UnexpectedBaseCookie';\nexport const UserDisconnect = 'UserDisconnect';\n\nexport type AbruptClose = typeof AbruptClose;\nexport type CleanClose = typeof CleanClose;\nexport type ClientClosed = typeof ClientClosed;\nexport type ConnectTimeout = typeof ConnectTimeout;\nexport type Hidden = typeof Hidden;\nexport type Internal = typeof Internal;\nexport type InvalidMessage = typeof InvalidMessage;\nexport type NoSocketOrigin = typeof NoSocketOrigin;\nexport type Offline = typeof Offline;\nexport type PingTimeout = typeof PingTimeout;\nexport type PullTimeout = typeof PullTimeout;\nexport type UnexpectedBaseCookie = typeof UnexpectedBaseCookie;\nexport type UserDisconnect = typeof UserDisconnect;\n"],"names":[],"mappings":"AAAO,MAAM,cAAc;AACpB,MAAM,aAAa;AACnB,MAAM,eAAe;AACrB,MAAM,iBAAiB;AACvB,MAAM,SAAS;AACf,MAAM,WAAW;AACjB,MAAM,iBAAiB;AACvB,MAAM,iBAAiB;AACvB,MAAM,UAAU;AAChB,MAAM,cAAc;AACpB,MAAM,cAAc;AACpB,MAAM,uBAAuB;AAC7B,MAAM,iBAAiB;"}

package/out/zero-client/src/client/connection-manager.d.ts

@@ -1,25 +1,9 @@
 import { Subscribable } from '../../../shared/src/subscribable.ts';
 import { ConnectionStatus } from './connection-status.ts';
-import { type ZeroError } from './error.ts';
-/**
- * The current connection state of the Zero instance. It can be one of the following states:
- *
- * - `connecting`: The client is actively trying to connect every 5 seconds.
- *   - `attempt` counts the number of retries within the current retry window,
- *   - `disconnectAt` is the epoch timestamp when the client will transition to `disconnected` state
- *   - `reason` is the optional error associated with the connection attempt.
- * - `disconnected`: The client is now in an "offline" state. It will continue
- *   to try to connect every 5 seconds.
- * - `connected`: The client has opened a successful connection to the server.
- * - `error`: A fatal error occurred. No connection retries will be made until the host
- *   application calls `connect()` again.
- *   - `reason` is the `ZeroError` associated with the error state.
- * - `closed`: The client was shut down (for example via `zero.close()`). This is
- *   a terminal state, and a new Zero instance must be created to reconnect.
- */
-export type ConnectionState = {
+import { type AuthError, type ClosedError, type OfflineError, type ZeroError } from './error.ts';
+export type ConnectionManagerState = {
     name: ConnectionStatus.Disconnected;
-    reason: ZeroError;
+    reason: OfflineError;
 } | {
     name: ConnectionStatus.Connecting;
     attempt: number;
@@ -27,34 +11,37 @@ export type ConnectionState = {
     reason?: ZeroError | undefined;
 } | {
     name: ConnectionStatus.Connected;
+} | {
+    name: ConnectionStatus.NeedsAuth;
+    reason: AuthError;
 } | {
     name: ConnectionStatus.Error;
     reason: ZeroError;
 } | {
     name: ConnectionStatus.Closed;
-    reason: ZeroError;
+    reason: ClosedError;
 };
 export type ConnectionManagerOptions = {
     /**
-     * The amount of time we allow for continuous connecting attempts before
+     * The amount of milliseconds we allow for continuous connecting attempts before
      * transitioning to disconnected state.
      */
-    disconnectTimeoutMs: number;
+    disconnectTimeout: number;
     /**
      * How frequently we check whether the connecting timeout has elapsed.
      * Defaults to 1 second.
      */
     timeoutCheckIntervalMs?: number | undefined;
 };
-declare const TERMINAL_STATES: ["error"];
+declare const TERMINAL_STATES: ["needs-auth", "error"];
 type TerminalConnectionStatus = (typeof TERMINAL_STATES)[number];
-type TerminalConnectionState = Extract<ConnectionState, {
+type TerminalConnectionManagerState = Extract<ConnectionManagerState, {
     name: TerminalConnectionStatus;
 }>;
-export declare class ConnectionManager extends Subscribable<ConnectionState> {
+export declare class ConnectionManager extends Subscribable<ConnectionManagerState> {
     #private;
     constructor(options: ConnectionManagerOptions);
-    get state(): ConnectionState;
+    get state(): ConnectionManagerState;
     /**
      * Returns true if the current state is equal to the given status.
      */
@@ -68,28 +55,28 @@ export declare class ConnectionManager extends Subscribable<ConnectionState> {
      * Returns true if the given status is a terminal state
      * that can be recovered from by calling connect().
      */
-    static isTerminalState(state: ConnectionState): state is TerminalConnectionState;
+    static isTerminalState(state: ConnectionManagerState): state is TerminalConnectionManagerState;
     /**
      * Returns true if the run loop should continue.
-     * The run loop continues in disconnected, connecting, connected, and error states.
-     * It stops in closed state.
+     * The run loop continues in all states except closed.
+     * In needs-auth and error states, the run loop pauses and waits for connect() to be called.
      */
     shouldContinueRunLoop(): boolean;
     /**
      * Waits for the next state change.
      * @returns A promise that resolves when the next state change occurs.
      */
-    waitForStateChange(): Promise<ConnectionState>;
+    waitForStateChange(): Promise<ConnectionManagerState>;
     /**
      * Transition to connecting state.
      *
-     * This starts the 5-minute timeout timer, but if we've entered disconnected state,
+     * This starts the timeout timer, but if we've entered disconnected state,
      * we stay there and continue retrying.
      *
      * @returns An object containing a promise that resolves on the next state change.
      */
     connecting(reason?: ZeroError): {
-        nextStatePromise: Promise<ConnectionState>;
+        nextStatePromise: Promise<ConnectionManagerState>;
     };
     /**
      * Transition to connected state.
@@ -98,28 +85,37 @@ export declare class ConnectionManager extends Subscribable<ConnectionState> {
      * @returns An object containing a promise that resolves on the next state change.
      */
     connected(): {
-        nextStatePromise: Promise<ConnectionState>;
+        nextStatePromise: Promise<ConnectionManagerState>;
     };
     /**
      * Transition to disconnected state.
-     * This is called when the 5-minute timeout expires, or when we're intentionally
-     * disconnecting due to an error (this will eventually be a separate state, error).
+     * This is called when the timeout expires.
      * The run loop will continue trying to reconnect.
      *
      * @returns An object containing a promise that resolves on the next state change.
      */
-    disconnected(reason: ZeroError): {
-        nextStatePromise: Promise<ConnectionState>;
+    disconnected(reason: OfflineError): {
+        nextStatePromise: Promise<ConnectionManagerState>;
+    };
+    /**
+     * Transition to needs-auth state.
+     * This pauses the run loop until connect() is called with new credentials.
+     * Resets the retry window and attempt counter.
+     *
+     * @returns An object containing a promise that resolves on the next state change.
+     */
+    needsAuth(reason: AuthError): {
+        nextStatePromise: Promise<ConnectionManagerState>;
     };
     /**
      * Transition to error state.
      * This pauses the run loop until connect() is called.
-     * Resets the 5-minute retry window and attempt counter.
+     * Resets the retry window and attempt counter.
      *
      * @returns An object containing a promise that resolves on the next state change.
      */
     error(reason: ZeroError): {
-        nextStatePromise: Promise<ConnectionState>;
+        nextStatePromise: Promise<ConnectionManagerState>;
     };
     /**
      * Transition to closed state.
@@ -133,6 +129,6 @@ export declare class ConnectionManager extends Subscribable<ConnectionState> {
  *
  * @param state - The current connection state.
  */
-export declare const throwIfConnectionError: (state: ConnectionState) => void;
+export declare const throwIfConnectionError: (state: ConnectionManagerState) => void;
 export {};
 //# sourceMappingURL=connection-manager.d.ts.map

package/out/zero-client/src/client/connection-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-manager.d.ts","sourceRoot":"","sources":["../../../../../zero-client/src/client/connection-manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,YAAY,EAAC,MAAM,qCAAqC,CAAC;AACjE,OAAO,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAA6B,KAAK,SAAS,EAAC,MAAM,YAAY,CAAC;AAKtE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,GACvB;IACE,IAAI,EAAE,gBAAgB,CAAC,YAAY,CAAC;IACpC,MAAM,EAAE,SAAS,CAAC;CACnB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,UAAU,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC;CAClC,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC;IAC7B,MAAM,EAAE,SAAS,CAAC;CACnB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC;IAC9B,MAAM,EAAE,SAAS,CAAC;CACnB,CAAC;AAEN,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C,CAAC;AAEF,QAAA,MAAM,eAAe,WAEkB,CAAC;AAExC,KAAK,wBAAwB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,KAAK,uBAAuB,GAAG,OAAO,CACpC,eAAe,EACf;IAAC,IAAI,EAAE,wBAAwB,CAAA;CAAC,CACjC,CAAC;AAEF,qBAAa,iBAAkB,SAAQ,YAAY,CAAC,eAAe,CAAC;;gBAgCtD,OAAO,EAAE,wBAAwB;IAiB7C,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED;;OAEG;IACH,EAAE,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;IAIrC;;;OAGG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;;OAGG;IACH,MAAM,CAAC,eAAe,CACpB,KAAK,EAAE,eAAe,GACrB,KAAK,IAAI,uBAAuB;IAMnC;;;;OAIG;IACH,qBAAqB,IAAI,OAAO;IAIhC;;;OAGG;IACH,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAI9C;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG;QAC9B,gBAAgB,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;KAC5C;IA+CD;;;;;OAKG;IACH,SAAS,IAAI;QAAC,gBAAgB,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;KAAC;IAsBzD;;;;;;;OAOG;IACH,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG;QAC/B,gBAAgB,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;KAC5C;IA6BD;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG;QAAC,gBAAgB,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;KAAC;IAuBtE;;;OAGG;IACH,MAAM;IAqBG,OAAO,QAAO,IAAI,CAGzB;CA4DH;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,eAAe,SAkB5D,CAAC"}
+{"version":3,"file":"connection-manager.d.ts","sourceRoot":"","sources":["../../../../../zero-client/src/client/connection-manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,YAAY,EAAC,MAAM,qCAAqC,CAAC;AAEjE,OAAO,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,sBAAsB,GAC9B;IACE,IAAI,EAAE,gBAAgB,CAAC,YAAY,CAAC;IACpC,MAAM,EAAE,YAAY,CAAC;CACtB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,UAAU,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC;CAClC,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC;IACjC,MAAM,EAAE,SAAS,CAAC;CACnB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC;IAC7B,MAAM,EAAE,SAAS,CAAC;CACnB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC;IAC9B,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC;AAEN,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C,CAAC;AAEF,QAAA,MAAM,eAAe,yBAGkB,CAAC;AAExC,KAAK,wBAAwB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,KAAK,8BAA8B,GAAG,OAAO,CAC3C,sBAAsB,EACtB;IAAC,IAAI,EAAE,wBAAwB,CAAA;CAAC,CACjC,CAAC;AAEF,qBAAa,iBAAkB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAgC7D,OAAO,EAAE,wBAAwB;IAiB7C,IAAI,KAAK,IAAI,sBAAsB,CAElC;IAED;;OAEG;IACH,EAAE,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;IAIrC;;;OAGG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;;OAGG;IACH,MAAM,CAAC,eAAe,CACpB,KAAK,EAAE,sBAAsB,GAC5B,KAAK,IAAI,8BAA8B;IAM1C;;;;OAIG;IACH,qBAAqB,IAAI,OAAO;IAIhC;;;OAGG;IACH,kBAAkB,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAIrD;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG;QAC9B,gBAAgB,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;KACnD;IA+CD;;;;;OAKG;IACH,SAAS,IAAI;QAAC,gBAAgB,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;KAAC;IAsBhE;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG;QAClC,gBAAgB,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;KACnD;IA6BD;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG;QAC5B,gBAAgB,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;KACnD;IAuBD;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,SAAS,GAAG;QACxB,gBAAgB,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;KACnD;IAuBD;;;OAGG;IACH,MAAM;IAqBG,OAAO,QAAO,IAAI,CAGzB;CA4DH;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,sBAAsB,SAkBnE,CAAC"}