okmodel 0.7.0 → 0.9.0

package/dist/tooling/shared/kbqnrs1x.js

@@ -0,0 +1,1425 @@
+import {
+  createClient
+} from "./jr2nmr81.js";
+import {
+  OkmError,
+  isConnectionSqlstate,
+  isConnectionErrno
+} from "./hfq3n3bd.js";
+
+// src/runtime/topology.ts
+var CIRCUIT_AT = 2;
+var BACKOFF_CAP_MS = 30000;
+var DEFAULT_PROBE_MS = 1000;
+var CAPABILITY_SQL = "select case when to_regprocedure('pg_last_wal_replay_lsn()') is null then false when to_regprocedure('pg_current_wal_insert_lsn()') is null then false else has_function_privilege(to_regprocedure('pg_last_wal_replay_lsn()'), 'execute') and has_function_privilege(to_regprocedure('pg_current_wal_insert_lsn()'), 'execute') end";
+var HEALTH_SQL = "select 1, pg_last_wal_replay_lsn()::text";
+var HEALTH_TIME_SQL = "select 1, pg_last_wal_replay_lsn()::text, pg_last_xact_replay_timestamp()::text";
+var INSERT_LSN_SQL = "select pg_current_wal_insert_lsn()::text";
+var PING_SQL = "select 1";
+var SELECT_NAMES = ["weighted", "roundRobin", "leastConnections", "latencyAware"];
+var LATENCY_ALPHA = 0.2;
+var ROUTING_KEYS = "probe, select, fallback, consistency, maxLag";
+var handles = new WeakMap;
+async function connectTopology(target, options, open) {
+  if (Object.prototype.hasOwnProperty.call(options.schema.model, "using")) {
+    throw new OkmError("OKM1120", 'Table "using" collides with client.using(). Rename the table.');
+  }
+  refuseRouting(options.routing);
+  const consistency = readConsistency(options.routing?.consistency);
+  const maxLag = readMaxLag(options.routing?.maxLag);
+  const select = readSelect(options.routing?.select);
+  const primaryUrl = readPrimary(target);
+  const replicas = readReplicas(target);
+  const probeMs = readProbe(options.routing?.probe);
+  const defaults = driverFields(options);
+  const opened = [];
+  try {
+    opened.push(await openEndpoint(open, primaryUrl, defaults.max, defaults, "primary", "primary", 1, probeMs));
+    for (let index = 0;index < replicas.length; index += 1) {
+      const replica = replicas[index];
+      if (replica === undefined)
+        continue;
+      const name = replica.name ?? `replica-${String(index + 1)}`;
+      opened.push(await openEndpoint(open, replica.url, replica.max ?? defaults.max, defaults, name, "replica", replica.weight, probeMs));
+    }
+    assertNames(opened);
+    await Promise.all(opened.map((endpoint) => detectPosition(endpoint)));
+    const replicaEndpoints = opened.filter((endpoint) => endpoint.role === "replica");
+    const handle = {
+      closed: false,
+      probeMs,
+      consistency,
+      maxLag,
+      hasReplicas: replicaEndpoints.length > 0,
+      watermark: undefined,
+      positionUnknown: false,
+      unknownEpoch: 0,
+      primaryLsn: undefined,
+      fallback: readFallback(options.routing?.fallback),
+      select,
+      rrLast: undefined,
+      scratch: [],
+      onRoute: options.onRoute,
+      replicaState: options.replicaState,
+      endpoints: opened,
+      closing: undefined
+    };
+    await Promise.all([
+      ...replicaEndpoints.map((endpoint) => sample(handle, endpoint)),
+      samplePrimary(handle)
+    ]);
+    for (const endpoint of replicaEndpoints) {
+      endpoint.nextDelayMs = delayFor(probeMs, endpoint);
+      schedule(handle, endpoint);
+    }
+    schedulePrimary(handle);
+    const primary = opened[0];
+    if (primary === undefined) {
+      throw new OkmError("OKM1120", "A topology needs one primary URL.");
+    }
+    const shared = {
+      http: options.errors?.http,
+      includeValues: options.errors?.includeValues,
+      logger: options.logger,
+      signal: options.signal,
+      timeout: options.timeout,
+      timeouts: options.timeouts,
+      hookm: options.hookm,
+      catalog: options.catalog,
+      catalogDir: options.catalogDir,
+      requireMeta: options.requireMeta,
+      generators: options.generators
+    };
+    const router = routePool(handle);
+    const client = createClient(options.schema, router, { ownsPool: true, ...shared });
+    const routed = client;
+    routed.using = (route) => derive(options.schema, handle, router, shared, route);
+    return instrument(routed, handle);
+  } catch (error) {
+    for (const endpoint of opened) {
+      if (endpoint.timer !== undefined)
+        clearTimeout(endpoint.timer);
+      endpoint.timer = undefined;
+    }
+    await Promise.all(opened.map((endpoint) => endpoint.pool.close()));
+    throw error;
+  }
+}
+function instrument(client, handle, forced) {
+  const proxy = new Proxy(client, {
+    get(target, key, receiver) {
+      if (key === "using")
+        return Reflect.get(target, key, receiver);
+      const value = Reflect.get(target, key, receiver);
+      if (typeof value !== "function")
+        return retarget(value, handle, forced);
+      if (key === "tx") {
+        return (...args) => {
+          const index = typeof args[0] === "function" ? 0 : 1;
+          const fn = args[index];
+          if (typeof fn === "function") {
+            args[index] = (inner, ...rest) => fn(typeof inner === "object" && inner !== null ? instrument(inner, handle, "primary") : inner, ...rest);
+          }
+          return value.apply(target, args);
+        };
+      }
+      return (...args) => retarget(value.apply(target, args), handle, forced);
+    }
+  });
+  handles.set(proxy, handle);
+  return proxy;
+}
+function wrapTable(table, handle, forced) {
+  return new Proxy(table, {
+    get(target, key, receiver) {
+      const value = Reflect.get(target, key, receiver);
+      if (typeof value !== "function")
+        return value;
+      return (...args) => {
+        const route = forced ?? readCallRoute(args[0]);
+        return retarget(value.apply(target, args), handle, route);
+      };
+    }
+  });
+}
+function retarget(value, handle, route) {
+  if (typeof value !== "object" || value === null)
+    return value;
+  if (typeof Reflect.get(value, "inspect") === "function" && typeof Reflect.get(value, "then") === "function") {
+    return showReason(value, handle, route);
+  }
+  if (typeof Reflect.get(value, "find") === "function")
+    return wrapTable(value, handle, route);
+  if (typeof Reflect.get(value, "table") === "function")
+    return instrument(value, handle, route);
+  return value;
+}
+function showReason(query, handle, route) {
+  return new Proxy(query, {
+    get(target, key, receiver) {
+      const value = Reflect.get(target, key, receiver);
+      if (key === "inspect" && typeof value === "function") {
+        const inspect = value;
+        return () => Promise.resolve(inspect.call(target)).then(async (view) => {
+          if (typeof view !== "object" || view === null)
+            return view;
+          const sql = Reflect.get(view, "sql");
+          const text = typeof sql === "object" && sql !== null && typeof Reflect.get(sql, "text") === "string" ? Reflect.get(sql, "text") : "";
+          const choice = await preview(handle, text, route);
+          return {
+            ...view,
+            routing: {
+              endpoint: choice.endpoint.name,
+              role: choice.endpoint.role,
+              reason: choice.reason
+            }
+          };
+        });
+      }
+      if ((key === "all" || key === "required") && typeof value === "function") {
+        const method = value;
+        return (...args) => retarget(method.apply(target, args), handle, route);
+      }
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+function readCallRoute(value) {
+  if (typeof value !== "object" || value === null)
+    return;
+  const route = Reflect.get(value, "route");
+  return route === "primary" || route === "replica" ? route : undefined;
+}
+async function preview(handle, text, route) {
+  const currents = handle.endpoints.map((endpoint) => endpoint.current);
+  const rrLast = handle.rrLast;
+  try {
+    return await choose(handle, text, route);
+  } finally {
+    for (let index = 0;index < handle.endpoints.length; index += 1) {
+      const endpoint = handle.endpoints[index];
+      if (endpoint !== undefined)
+        endpoint.current = currents[index] ?? 0;
+    }
+    handle.rrLast = rrLast;
+  }
+}
+function refuseRouting(routing) {
+  if (routing === undefined)
+    return;
+  if (typeof routing !== "object" || routing === null || Array.isArray(routing)) {
+    throw new OkmError("OKM1120", `routing must be an object. Accepted keys: ${ROUTING_KEYS}.`);
+  }
+  for (const key of Object.keys(routing)) {
+    if (key === "probe" || key === "fallback" || key === "select" || key === "consistency" || key === "maxLag") {
+      continue;
+    }
+    throw new OkmError("OKM1120", `routing.${key} is not a routing option. Accepted keys: ${ROUTING_KEYS}.`);
+  }
+}
+function readSelect(value) {
+  if (value === undefined)
+    return "weighted";
+  if (typeof value === "function")
+    return value;
+  if (typeof value === "string" && isSelectName(value))
+    return value;
+  throw new OkmError("OKM1120", `routing.select must be "${SELECT_NAMES.join('", "')}", or a function.`);
+}
+function isSelectName(value) {
+  return SELECT_NAMES.includes(value);
+}
+function readConsistency(value) {
+  if (value === undefined || value === "session")
+    return "session";
+  if (value === "eventual")
+    return "eventual";
+  throw new OkmError("OKM1120", `routing.consistency must be "session" or "eventual". ${shown(value)} is not one of those.`);
+}
+function readMaxLag(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string") {
+    throw new OkmError("OKM1120", maxLagMessage(shown(value)));
+  }
+  const text = value.trim();
+  const time = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(text);
+  if (time !== null) {
+    const amount = Number(time[1]);
+    const unit = time[2];
+    if (!Number.isFinite(amount) || amount < 0 || unit === undefined) {
+      throw new OkmError("OKM1120", maxLagMessage(value));
+    }
+    const ms = unit === "ms" ? amount : unit === "s" ? amount * 1000 : amount * 60000;
+    return { kind: "time", ms };
+  }
+  const size = /^(\d+(?:\.\d+)?)(B|KB|MB|GB)$/.exec(text);
+  if (size !== null) {
+    const amount = Number(size[1]);
+    const unit = size[2];
+    if (!Number.isFinite(amount) || amount < 0 || unit === undefined) {
+      throw new OkmError("OKM1120", maxLagMessage(value));
+    }
+    return { kind: "bytes", bytes: scaleBytes(amount, unit) };
+  }
+  throw new OkmError("OKM1120", maxLagMessage(value));
+}
+function maxLagMessage(value) {
+  return `routing.maxLag must be a duration ("5s", "500ms", "2m") or a size ("16MB", "512KB", "1GB", "4096B"). ${value} is not one of those forms.`;
+}
+function scaleBytes(amount, unit) {
+  const scale = unit === "B" ? 1n : unit === "KB" ? 1024n : unit === "MB" ? 1048576n : 1073741824n;
+  if (Number.isInteger(amount))
+    return BigInt(amount) * scale;
+  return BigInt(Math.trunc(amount * Number(scale)));
+}
+function readPrimary(target) {
+  const value = fields(target);
+  for (const key of Object.keys(value)) {
+    if (key !== "primary" && key !== "replicas") {
+      throw new OkmError("OKM1120", `Topology key ${key} is not accepted. Accepted keys: primary, replicas.`);
+    }
+  }
+  const primary = value.primary;
+  if (typeof primary !== "string" || primary.length === 0) {
+    throw new OkmError("OKM1120", "A topology needs one primary URL. Accepted shape: { primary, replicas }.");
+  }
+  return primary;
+}
+function readReplicas(target) {
+  const value = fields(target).replicas;
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    throw new OkmError("OKM1120", "replicas must be an array of URLs or { url, weight, name, pool }.");
+  }
+  return value.map((entry, index) => readReplica(entry, index));
+}
+function readReplica(entry, index) {
+  if (typeof entry === "string") {
+    if (entry.length === 0) {
+      throw new OkmError("OKM1120", `replicas[${String(index)}] is an empty URL.`);
+    }
+    return { url: entry, weight: 1, name: undefined, max: undefined };
+  }
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new OkmError("OKM1120", `replicas[${String(index)}] must be a URL or { url, weight, name, pool }.`);
+  }
+  const value = fields(entry);
+  for (const key of Object.keys(value)) {
+    if (key !== "url" && key !== "weight" && key !== "name" && key !== "pool") {
+      throw new OkmError("OKM1120", `replicas[${String(index)}].${key} is not accepted. Accepted keys: url, weight, name, pool.`);
+    }
+  }
+  const url = value.url;
+  if (typeof url !== "string" || url.length === 0) {
+    throw new OkmError("OKM1120", `replicas[${String(index)}] needs a url.`);
+  }
+  return {
+    url,
+    weight: readWeight(value.weight, index),
+    name: readName(value.name, index),
+    max: readPoolMax(value.pool, index)
+  };
+}
+function readWeight(value, index) {
+  if (value === undefined)
+    return 1;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new OkmError("OKM1120", `replicas[${String(index)}].weight must be a positive number.`);
+  }
+  return value;
+}
+function readName(value, index) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new OkmError("OKM1120", `replicas[${String(index)}].name must be a non-empty string.`);
+  }
+  return value;
+}
+function readPoolMax(value, index) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new OkmError("OKM1120", `replicas[${String(index)}].pool must be { max }.`);
+  }
+  const pool = fields(value);
+  for (const key of Object.keys(pool)) {
+    if (key !== "max") {
+      throw new OkmError("OKM1120", `replicas[${String(index)}].pool.${key} is not accepted. Accepted key: max.`);
+    }
+  }
+  const max = pool.max;
+  if (typeof max !== "number" || !Number.isInteger(max) || max < 1) {
+    throw new OkmError("OKM1120", `replicas[${String(index)}].pool.max must be a positive integer.`);
+  }
+  return max;
+}
+function readProbe(value) {
+  if (value === undefined)
+    return DEFAULT_PROBE_MS;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new OkmError("OKM1120", "routing.probe must be a positive number of milliseconds.");
+    }
+    return value;
+  }
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(value.trim());
+  const amount = match?.[1];
+  const unit = match?.[2];
+  if (amount === undefined || unit === undefined) {
+    throw new OkmError("OKM1120", 'routing.probe must be a number of milliseconds, or "1s", "500ms", or "1m".');
+  }
+  const parsed = Number(amount);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new OkmError("OKM1120", "routing.probe must be positive.");
+  }
+  if (unit === "ms")
+    return parsed;
+  if (unit === "s")
+    return parsed * 1000;
+  return parsed * 60000;
+}
+function assertNames(endpoints) {
+  const seen = new Set;
+  for (const endpoint of endpoints) {
+    if (seen.has(endpoint.name)) {
+      throw new OkmError("OKM1120", `Endpoint name ${endpoint.name} is used twice.`);
+    }
+    seen.add(endpoint.name);
+  }
+}
+function driverFields(options) {
+  const value = fields(options);
+  const prepared = value.prepared;
+  return {
+    max: typeof value.max === "number" ? value.max : undefined,
+    timeouts: typeof value.timeouts === "object" && value.timeouts !== null ? value.timeouts : undefined,
+    prepared: prepared === "named" || prepared === "unnamed" ? prepared : undefined,
+    searchPath: typeof value.searchPath === "string" ? value.searchPath : undefined,
+    ssl: value.ssl
+  };
+}
+async function openEndpoint(open, url, max, defaults, name, role, weight, probeMs) {
+  const pool = await open({
+    url,
+    dataDir: url,
+    ...max !== undefined ? { max } : {},
+    ...defaults.timeouts !== undefined ? { timeouts: defaults.timeouts } : {},
+    ...defaults.prepared !== undefined ? { prepared: defaults.prepared } : {},
+    ...defaults.searchPath !== undefined ? { searchPath: defaults.searchPath } : {},
+    ...defaults.ssl !== undefined ? { ssl: defaults.ssl } : {}
+  });
+  return {
+    name,
+    role,
+    weight,
+    max,
+    pool,
+    position: false,
+    circuit: "closed",
+    failures: 0,
+    replayLsn: null,
+    replayPos: undefined,
+    replayAt: null,
+    nextDelayMs: role === "replica" ? probeMs : 0,
+    timer: undefined,
+    current: 0,
+    inflight: 0,
+    latencyMs: null,
+    generation: 0
+  };
+}
+async function detectPosition(endpoint) {
+  try {
+    const result = await endpoint.pool.execute(CAPABILITY_SQL);
+    endpoint.position = truth(result.rows[0]?.[0]);
+  } catch {
+    endpoint.position = false;
+  }
+}
+async function sample(handle, endpoint) {
+  try {
+    const sampled = await readPosition(handle, endpoint);
+    const reopened = endpoint.circuit === "open";
+    endpoint.failures = 0;
+    endpoint.circuit = "closed";
+    if (reopened)
+      endpoint.generation += 1;
+    applySample(endpoint, sampled);
+  } catch {
+    endpoint.failures += 1;
+    if (endpoint.failures >= CIRCUIT_AT)
+      endpoint.circuit = "open";
+  }
+}
+async function readPosition(handle, endpoint) {
+  const state = handle.replicaState;
+  const started = performance.now();
+  if (state === undefined) {
+    const sql = handle.maxLag?.kind === "time" ? HEALTH_TIME_SQL : HEALTH_SQL;
+    const result = await endpoint.pool.execute(sql);
+    observe(endpoint, performance.now() - started);
+    const row = result.rows[0];
+    return { lsn: row?.[1] ?? null, time: row?.[2] ?? null };
+  }
+  await endpoint.pool.execute(PING_SQL);
+  observe(endpoint, performance.now() - started);
+  const lsn = await state.replayLsn({ name: endpoint.name });
+  if (typeof lsn !== "string" && lsn !== null) {
+    throw new OkmError("OKM1120", "ReplicaState.replayLsn must return a WAL position or null.");
+  }
+  return { lsn, time: await seamTime(handle, endpoint, state) };
+}
+async function seamTime(handle, endpoint, state) {
+  if (handle.maxLag?.kind !== "time" || state.replayTime === undefined)
+    return null;
+  const value = await state.replayTime({ name: endpoint.name });
+  if (value instanceof Date)
+    return value.toISOString();
+  if (typeof value === "string" || value === null)
+    return value;
+  throw new OkmError("OKM1120", "ReplicaState.replayTime must return a timestamp or null.");
+}
+function applySample(endpoint, sampled) {
+  if (sampled.lsn !== null)
+    noteReplay(endpoint, sampled.lsn);
+  if (sampled.time !== null)
+    noteTime(endpoint, sampled.time);
+}
+function noteReplay(endpoint, text) {
+  const pos = parseLsn(text);
+  if (pos === undefined)
+    return;
+  if (endpoint.replayPos !== undefined && pos < endpoint.replayPos)
+    return;
+  endpoint.replayPos = pos;
+  endpoint.replayLsn = text.trim();
+}
+function noteTime(endpoint, text) {
+  const parsed = parseTime(text);
+  if (parsed === undefined)
+    return;
+  endpoint.replayAt = parsed;
+}
+function observe(endpoint, sampleMs) {
+  const previous = endpoint.latencyMs;
+  endpoint.latencyMs = previous === null ? sampleMs : LATENCY_ALPHA * sampleMs + (1 - LATENCY_ALPHA) * previous;
+}
+function delayFor(probeMs, endpoint) {
+  if (endpoint.circuit === "closed")
+    return probeMs;
+  const steps = Math.min(Math.max(endpoint.failures - 1, 1), 8);
+  const delay = probeMs * 2 ** steps;
+  return delay > BACKOFF_CAP_MS ? BACKOFF_CAP_MS : delay;
+}
+function schedule(handle, endpoint) {
+  if (handle.closed || endpoint.role !== "replica")
+    return;
+  const timer = setTimeout(() => {
+    endpoint.timer = undefined;
+    runProbe(handle, endpoint);
+  }, endpoint.nextDelayMs);
+  timer.unref();
+  endpoint.timer = timer;
+}
+function schedulePrimary(handle) {
+  const primary = handle.endpoints[0];
+  if (handle.closed || primary === undefined || !probesPrimary(handle))
+    return;
+  const timer = setTimeout(() => {
+    primary.timer = undefined;
+    runPrimary(handle);
+  }, handle.probeMs);
+  timer.unref();
+  primary.timer = timer;
+}
+async function runPrimary(handle) {
+  if (handle.closed)
+    return;
+  await samplePrimary(handle);
+  if (handle.closed)
+    return;
+  schedulePrimary(handle);
+}
+async function samplePrimary(handle) {
+  if (!probesPrimary(handle))
+    return;
+  const primary = handle.endpoints[0];
+  if (primary === undefined)
+    return;
+  const epoch = handle.unknownEpoch;
+  const wasUnknown = handle.positionUnknown;
+  try {
+    const lsn = await readInsertLsn(primary.pool);
+    if (lsn === undefined)
+      return;
+    if (wasUnknown && handle.unknownEpoch === epoch && handle.positionUnknown) {
+      raiseWatermark(handle, lsn);
+      return;
+    }
+    notePrimary(handle, lsn);
+  } catch {}
+}
+function probesPrimary(handle) {
+  if (!handle.hasReplicas)
+    return false;
+  const primary = handle.endpoints[0];
+  if (primary === undefined || !primary.position)
+    return false;
+  return handle.consistency === "session" || handle.maxLag !== undefined;
+}
+async function runProbe(handle, endpoint) {
+  if (handle.closed)
+    return;
+  await sample(handle, endpoint);
+  if (handle.closed)
+    return;
+  endpoint.nextDelayMs = delayFor(handle.probeMs, endpoint);
+  schedule(handle, endpoint);
+}
+function closeHandle(handle) {
+  handle.closing ??= shutdown(handle);
+  return handle.closing;
+}
+async function shutdown(handle) {
+  handle.closed = true;
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.timer !== undefined)
+      clearTimeout(endpoint.timer);
+    endpoint.timer = undefined;
+  }
+  await Promise.all(handle.endpoints.map((endpoint) => endpoint.pool.close()));
+}
+function routePool(handle) {
+  const primary = handle.endpoints[0];
+  if (primary === undefined) {
+    throw new OkmError("OKM1120", "A topology needs one primary URL.");
+  }
+  const pool = {
+    capabilities: primary.pool.capabilities,
+    execute: async (text, params, options) => {
+      if (handle.closed)
+        closed();
+      const choice = await resolve(handle, text, options);
+      const result = await attempt(handle, choice, (endpoint) => endpoint.pool.execute(text, params, strip(options)));
+      if (choice.op === "write")
+        await noteWrite(handle, primary.pool);
+      return result;
+    },
+    batch: async (statements, options) => {
+      if (handle.closed)
+        closed();
+      if (options?.route === "replica")
+        replicaRefused();
+      const reason = options?.route === "primary" ? "constraint:primary" : "primary-required";
+      tell(handle, { op: "write", endpoint: primary.name, reason });
+      await callGuard(primary);
+      const result = await primary.pool.batch(statements, strip(options));
+      await noteWrite(handle, primary.pool);
+      return result;
+    },
+    stats: () => primary.pool.stats(),
+    close: () => closeHandle(handle)
+  };
+  if (primary.pool.reserve !== undefined) {
+    pool.reserve = async () => {
+      if (handle.closed)
+        closed();
+      tell(handle, { op: "tx", endpoint: primary.name, reason: "primary-required" });
+      return wrap(handle, await primary.pool.reserve());
+    };
+  }
+  if (primary.pool.describe !== undefined) {
+    pool.describe = async (text, params) => {
+      const choice = await choose(handle, text, undefined);
+      tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+      if (choice.endpoint.pool.describe !== undefined) {
+        return choice.endpoint.pool.describe(text, params);
+      }
+      return primary.pool.describe(text, params);
+    };
+  }
+  if (primary.pool.stream !== undefined) {
+    pool.stream = (text, params) => readStream(handle, text, undefined, params, primary.pool);
+  }
+  if (primary.pool.listen !== undefined) {
+    pool.listen = (channel, onNotify) => {
+      tell(handle, { op: "read", endpoint: primary.name, reason: "primary-required" });
+      return primary.pool.listen(channel, onNotify);
+    };
+  }
+  if (primary.pool.cancel !== undefined) {
+    pool.cancel = () => {
+      for (const endpoint of handle.endpoints)
+        endpoint.pool.cancel?.();
+    };
+  }
+  const routed = pool;
+  routed.okmReadOnlyUnit = (text, params, prelude, options) => readOnlyUnit(handle, text, params, prelude, options);
+  routed.okmReadOnlyStream = (text, params, prelude, options) => readOnlyStream(handle, text, params, prelude, options);
+  routed.okmEndpoints = () => handle.endpoints.map((endpoint) => ({
+    name: endpoint.name,
+    generation: endpoint.generation,
+    pool: endpoint.pool
+  }));
+  return pool;
+}
+function derive(schema, handle, router, shared, route) {
+  const name = readRoute(route);
+  const client = createClient(schema, force(handle, router, name), { ...shared, ownsPool: false });
+  delete client.close;
+  return instrument(client, handle, name);
+}
+function force(handle, router, route) {
+  const pool = {
+    forcedRoute: route,
+    capabilities: router.capabilities,
+    execute: (text, params, options) => router.execute(text, params, { ...options, route }),
+    batch: (statements, options) => router.batch(statements, { ...options, route }),
+    stats: () => router.stats(),
+    close: () => Promise.resolve()
+  };
+  if (router.reserve !== undefined) {
+    pool.reserve = () => {
+      if (route === "replica")
+        replicaRefused();
+      return router.reserve();
+    };
+  }
+  if (router.describe !== undefined) {
+    pool.describe = async (text, params) => {
+      const choice = await choose(handle, text, route);
+      tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+      if (choice.endpoint.pool.describe !== undefined) {
+        return choice.endpoint.pool.describe(text, params);
+      }
+      return router.describe(text, params);
+    };
+  }
+  if (router.stream !== undefined) {
+    pool.stream = (text, params) => readStream(handle, text, route, params, router);
+  }
+  if (router.listen !== undefined) {
+    pool.listen = (channel, onNotify) => {
+      if (route === "replica")
+        replicaRefused();
+      return router.listen(channel, onNotify);
+    };
+  }
+  if (router.cancel !== undefined)
+    pool.cancel = () => router.cancel();
+  const unit = router.okmReadOnlyUnit;
+  const stream = router.okmReadOnlyStream;
+  const forced = pool;
+  if (unit !== undefined) {
+    forced.okmReadOnlyUnit = (text, params, prelude, options) => unit(text, params, prelude, { ...options, route });
+  }
+  if (stream !== undefined) {
+    forced.okmReadOnlyStream = (text, params, prelude, options) => stream(text, params, prelude, { ...options, route });
+  }
+  return pool;
+}
+async function readOnlyUnit(handle, text, params, prelude, options) {
+  if (handle.closed)
+    closed();
+  const choice = await resolve(handle, text, options);
+  return attempt(handle, choice, async (endpoint) => {
+    if (endpoint.pool.reserve === undefined)
+      replicaReserve();
+    const conn = await endpoint.pool.reserve();
+    try {
+      await conn.execute("begin read only");
+      try {
+        await conn.execute(prelude.text, prelude.params);
+        const result = await conn.execute(text, params, strip(options));
+        await conn.execute("commit");
+        return result;
+      } catch (error) {
+        await conn.execute("rollback").catch(() => {
+          return;
+        });
+        throw error;
+      }
+    } finally {
+      await conn.release();
+    }
+  });
+}
+function readOnlyStream(handle, text, params, prelude, options) {
+  return async function* () {
+    if (handle.closed)
+      closed();
+    const choice = await choose(handle, text, options?.route);
+    tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+    await callGuard(choice.endpoint);
+    if (choice.endpoint.pool.reserve === undefined)
+      replicaReserve();
+    const conn = await choice.endpoint.pool.reserve();
+    try {
+      await conn.execute("begin read only");
+      try {
+        await conn.execute(prelude.text, prelude.params);
+        await conn.execute(`declare okm_rls no scroll cursor for ${text}`, params);
+        for (;; ) {
+          const chunk = await conn.execute("fetch 64 from okm_rls");
+          if (chunk.rows.length === 0)
+            break;
+          yield chunk.rows;
+        }
+        await conn.execute("close okm_rls");
+        await conn.execute("commit");
+      } catch (error) {
+        await conn.execute("rollback").catch(() => {
+          return;
+        });
+        throw error;
+      }
+    } finally {
+      await conn.release();
+    }
+  }();
+}
+function replicaReserve() {
+  throw new OkmError("OKM1111", "Row-level security needs a driver that can reserve a connection.", {
+    fix: { summary: "Use a Postgres driver that supports interactive transactions." }
+  });
+}
+function classOf(text) {
+  const head = text.trimStart().toLowerCase().replace(/\s+/g, " ");
+  if (/^(begin|start transaction|commit|rollback|savepoint|release|set|reset)\b/.test(head)) {
+    return "tx";
+  }
+  if (head.includes("pg_advisory"))
+    return "lock";
+  if (/\sfor (no key update|key share|update|share)\b/.test(head))
+    return "lock";
+  if (/^(insert|update|delete|refresh|with|create|alter|drop|truncate|grant|revoke|comment|vacuum|analyze|reindex|copy)\b/.test(head)) {
+    return "write";
+  }
+  return "read";
+}
+async function choose(handle, text, route) {
+  if (route !== undefined && route !== "primary" && route !== "replica") {
+    throw new OkmError("OKM1120", 'route must be "primary" or "replica".');
+  }
+  const op = classOf(text);
+  const primary = handle.endpoints[0];
+  if (primary === undefined)
+    throw new OkmError("OKM1120", "A topology needs one primary URL.");
+  if (text.trimStart().toLowerCase().startsWith("select current_setting")) {
+    return { endpoint: primary, op: "read", reason: "primary-required", skipGuard: true };
+  }
+  if (route === "replica" && op !== "read")
+    replicaRefused();
+  if (op !== "read") {
+    return {
+      endpoint: primary,
+      op,
+      reason: route === "primary" ? "constraint:primary" : "primary-required"
+    };
+  }
+  if (route === "primary")
+    return { endpoint: primary, op, reason: "constraint:primary" };
+  if (handle.positionUnknown && handle.consistency === "session" && handle.hasReplicas) {
+    if (route === "replica")
+      noReplica();
+    if (handle.fallback === "error")
+      fallbackRefused("position-unknown");
+    return { endpoint: primary, op, reason: "fallback:position-unknown" };
+  }
+  const explicit = route === "replica";
+  const gated = await gate(handle, undefined, !explicit);
+  const replica = pick(handle, gated.ready, !explicit);
+  if (replica !== undefined) {
+    return {
+      endpoint: replica,
+      op,
+      reason: explicit ? "constraint:replica" : `auto:${replica.name}`
+    };
+  }
+  if (explicit)
+    noReplica();
+  if (handle.fallback === "error")
+    fallbackRefused(gated.miss);
+  return { endpoint: primary, op, reason: `fallback:${gated.miss}` };
+}
+async function* readStream(handle, text, route, params, fallback) {
+  const choice = await choose(handle, text, route);
+  tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+  const pool = choice.endpoint.pool.stream !== undefined ? choice.endpoint.pool : fallback;
+  if (pool.stream === undefined)
+    return;
+  yield* pool.stream(text, params);
+}
+async function attempt(handle, choice, run) {
+  tell(handle, { op: choice.op, endpoint: choice.endpoint.name, reason: choice.reason });
+  try {
+    if (choice.skipGuard !== true)
+      await callGuard(choice.endpoint);
+    return await tracked(choice.endpoint, choice.op === "read", () => run(choice.endpoint));
+  } catch (error) {
+    if (choice.pinned === true || choice.op !== "read" || !isUnreachable(error))
+      throw error;
+    choice.endpoint.generation += 1;
+    const next = await retryOf(handle, choice);
+    if (next === undefined)
+      throw error;
+    tell(handle, { op: "read", endpoint: next.endpoint.name, reason: next.reason });
+    if (choice.skipGuard !== true)
+      await callGuard(next.endpoint);
+    return tracked(next.endpoint, true, () => run(next.endpoint));
+  }
+}
+function callGuard(endpoint) {
+  const guard = endpoint.pool.okmGuard;
+  if (guard === undefined)
+    return Promise.resolve();
+  return guard({
+    name: endpoint.name,
+    generation: endpoint.generation,
+    pool: endpoint.pool
+  });
+}
+var CHAIN_DEPTH = 8;
+function isUnreachable(error) {
+  const seen = new Set;
+  const visit = (value, depth) => {
+    if (typeof value !== "object" || value === null || depth > CHAIN_DEPTH)
+      return false;
+    if (seen.has(value))
+      return false;
+    seen.add(value);
+    if (unreachableNode(value))
+      return true;
+    if (visit(Reflect.get(value, "cause"), depth + 1))
+      return true;
+    const errors = Reflect.get(value, "errors");
+    return Array.isArray(errors) && errors.some((item) => visit(item, depth + 1));
+  };
+  return visit(error, 0);
+}
+function unreachableNode(node) {
+  for (const key of ["sqlstate", "code", "errno"]) {
+    const code = Reflect.get(node, key);
+    if (typeof code !== "string" || code.length === 0)
+      continue;
+    if (isConnectionSqlstate(code) || isConnectionErrno(code))
+      return true;
+    if (code.startsWith("ERR_POSTGRES_CONNECTION_"))
+      return true;
+    if (code === "ERR_POSTGRES_IDLE_TIMEOUT" || code === "ERR_POSTGRES_LIFETIME_TIMEOUT") {
+      return true;
+    }
+  }
+  return false;
+}
+async function tracked(endpoint, time, run) {
+  const replica = endpoint.role === "replica";
+  if (replica)
+    endpoint.inflight += 1;
+  const started = replica && time ? performance.now() : 0;
+  try {
+    const result = await run();
+    if (replica && time)
+      observe(endpoint, performance.now() - started);
+    return result;
+  } finally {
+    if (replica)
+      endpoint.inflight -= 1;
+  }
+}
+async function retryOf(handle, choice) {
+  if (choice.endpoint.role === "replica")
+    noteFailure(choice.endpoint);
+  const explicit = choice.reason.startsWith("constraint:");
+  const gated = await gate(handle, choice.endpoint, !explicit);
+  const replica = pick(handle, gated.ready, !explicit);
+  if (replica !== undefined) {
+    return {
+      endpoint: replica,
+      op: "read",
+      reason: explicit ? "constraint:replica" : `auto:${replica.name}`
+    };
+  }
+  if (explicit)
+    return;
+  if (handle.fallback === "error")
+    fallbackRefused(gated.miss);
+  const primary = handle.endpoints[0];
+  if (primary === undefined)
+    return;
+  return { endpoint: primary, op: "read", reason: `fallback:${gated.miss}` };
+}
+async function gate(handle, except, capacity) {
+  const healthy = takeHealthy(handle, except);
+  if (healthy.length === 0)
+    return { ready: healthy, miss: emptyReason(handle, capacity) };
+  const lagged = await consistent(handle, healthy);
+  if (lagged.length === 0)
+    return { ready: lagged, miss: "behind" };
+  if (!capacity)
+    return { ready: lagged, miss: "behind" };
+  const room = [];
+  for (const endpoint of lagged) {
+    if (!saturated(endpoint))
+      room.push(endpoint);
+  }
+  if (room.length === 0)
+    return { ready: room, miss: "saturated" };
+  return { ready: room, miss: "behind" };
+}
+function takeHealthy(handle, except) {
+  const scratch = handle.scratch;
+  scratch.length = 0;
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.role !== "replica" || endpoint === except || endpoint.circuit !== "closed") {
+      continue;
+    }
+    scratch.push(endpoint);
+  }
+  const copy = scratch.slice();
+  scratch.length = 0;
+  return copy;
+}
+async function consistent(handle, healthy) {
+  if (!filters(handle))
+    return healthy;
+  const kept = [];
+  for (const endpoint of healthy) {
+    if (freshEnough(handle, endpoint)) {
+      kept.push(endpoint);
+      continue;
+    }
+    if (!endpoint.position)
+      continue;
+    try {
+      applySample(endpoint, await readPosition(handle, endpoint));
+    } catch (error) {
+      if (error instanceof OkmError)
+        throw error;
+      noteFailure(endpoint);
+      continue;
+    }
+    if (freshEnough(handle, endpoint))
+      kept.push(endpoint);
+  }
+  return kept;
+}
+function filters(handle) {
+  if (handle.maxLag !== undefined)
+    return true;
+  return handle.consistency === "session" && handle.watermark !== undefined;
+}
+function freshEnough(handle, endpoint) {
+  return coversWatermark(handle, endpoint) && coversLag(handle, endpoint);
+}
+function coversWatermark(handle, endpoint) {
+  if (handle.consistency !== "session" || handle.watermark === undefined)
+    return true;
+  if (!endpoint.position)
+    return false;
+  const replay = endpoint.replayPos;
+  if (replay === undefined)
+    return false;
+  return replay >= handle.watermark;
+}
+function coversLag(handle, endpoint) {
+  const lag = handle.maxLag;
+  if (lag === undefined)
+    return true;
+  if (!endpoint.position)
+    return false;
+  if (lag.kind === "bytes") {
+    const diff = byteLag(handle, endpoint);
+    return diff !== null && diff <= lag.bytes;
+  }
+  const ms = timeLag(handle, endpoint);
+  return ms !== null && ms <= lag.ms;
+}
+function saturated(endpoint) {
+  const max = endpoint.max;
+  if (max === undefined)
+    return false;
+  const stats = endpoint.pool.stats();
+  return stats.idle === 0 && stats.waiting > 0 && stats.size >= max;
+}
+function emptyReason(handle, capacity) {
+  let replicas = 0;
+  let healthy = 0;
+  let room = 0;
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.role !== "replica")
+      continue;
+    replicas += 1;
+    if (endpoint.circuit !== "closed")
+      continue;
+    healthy += 1;
+    if (!capacity || !saturated(endpoint))
+      room += 1;
+  }
+  if (replicas === 0)
+    return "no-replicas";
+  if (healthy === 0)
+    return "unhealthy";
+  if (capacity && room === 0)
+    return "saturated";
+  return "unhealthy";
+}
+function pick(handle, candidates, automatic) {
+  if (candidates.length === 0)
+    return;
+  const select = handle.select;
+  if (typeof select === "function") {
+    if (!automatic || candidates.length < 2)
+      return candidates[0];
+    return fromSelect(handle, select, candidates);
+  }
+  if (select === "roundRobin")
+    return roundRobin(handle, candidates);
+  if (select === "leastConnections")
+    return leastConnections(candidates);
+  if (select === "latencyAware")
+    return latencyAware(candidates);
+  return weighted(handle, candidates);
+}
+function weighted(handle, candidates) {
+  const live = new Set(candidates);
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.role === "replica" && !live.has(endpoint))
+      endpoint.current = 0;
+  }
+  const first = candidates[0];
+  if (first === undefined)
+    throw new Error("selection saw no candidate");
+  let best = first;
+  let total = 0;
+  for (const endpoint of candidates) {
+    endpoint.current += endpoint.weight;
+    total += endpoint.weight;
+    if (endpoint.current > best.current)
+      best = endpoint;
+  }
+  best.current -= total;
+  return best;
+}
+function roundRobin(handle, candidates) {
+  const next = after(handle, handle.rrLast, candidates);
+  handle.rrLast = next;
+  return next;
+}
+function after(handle, last, candidates) {
+  const first = candidates[0];
+  if (first === undefined)
+    throw new Error("selection saw no candidate");
+  if (last === undefined)
+    return first;
+  const start = handle.endpoints.indexOf(last);
+  if (start === -1)
+    return first;
+  for (let step = 1;step <= handle.endpoints.length; step += 1) {
+    const endpoint = handle.endpoints[(start + step) % handle.endpoints.length];
+    if (endpoint !== undefined && candidates.includes(endpoint))
+      return endpoint;
+  }
+  return first;
+}
+function leastConnections(candidates) {
+  let best = candidates[0];
+  if (best === undefined)
+    throw new Error("selection saw no candidate");
+  for (let index = 1;index < candidates.length; index += 1) {
+    const endpoint = candidates[index];
+    if (endpoint !== undefined && endpoint.inflight < best.inflight)
+      best = endpoint;
+  }
+  return best;
+}
+function latencyAware(candidates) {
+  let best = candidates[0];
+  if (best === undefined)
+    throw new Error("selection saw no candidate");
+  for (let index = 1;index < candidates.length; index += 1) {
+    const endpoint = candidates[index];
+    if (endpoint !== undefined && lowerLatency(endpoint, best))
+      best = endpoint;
+  }
+  return best;
+}
+function lowerLatency(endpoint, best) {
+  if (endpoint.latencyMs === null)
+    return false;
+  if (best.latencyMs === null)
+    return true;
+  return endpoint.latencyMs < best.latencyMs;
+}
+function fromSelect(handle, select, candidates) {
+  const endpoints = candidates.slice();
+  const offered = [];
+  for (const endpoint of endpoints) {
+    offered.push({
+      name: endpoint.name,
+      weight: endpoint.weight,
+      inflight: endpoint.inflight,
+      latencyMs: endpoint.latencyMs,
+      lag: byteLagNumber(handle, endpoint)
+    });
+  }
+  const returned = select(offered, { op: "read" });
+  if (typeof returned === "string") {
+    const endpoint = endpoints.find((item) => item.name === returned);
+    if (endpoint !== undefined)
+      return endpoint;
+  } else if (offered.includes(returned)) {
+    const index = offered.indexOf(returned);
+    const endpoint = endpoints[index];
+    if (endpoint !== undefined)
+      return endpoint;
+  }
+  throw new OkmError("OKM1120", `routing.select returned ${shown(returned)}. It must return a candidate or its name.`);
+}
+function shown(value) {
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (value === null)
+    return "null";
+  if (value === undefined)
+    return "undefined";
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    const name = Reflect.get(value, "name");
+    if (typeof name === "string")
+      return `an object named ${JSON.stringify(name)}`;
+    return "an object";
+  }
+  return typeof value;
+}
+function noteFailure(endpoint) {
+  endpoint.failures += 1;
+  if (endpoint.failures >= CIRCUIT_AT)
+    endpoint.circuit = "open";
+}
+function strip(options) {
+  if (options === undefined)
+    return;
+  if (!("route" in options) && !("pin" in options))
+    return options;
+  const bag = options;
+  const { route: _route, pin: _pin, ...rest } = bag;
+  if (rest.signal === undefined && rest.timeout === undefined)
+    return;
+  return rest;
+}
+async function resolve(handle, text, options) {
+  const pin = taken(options);
+  if (pin?.name !== undefined)
+    return held(handle, pin.name);
+  const choice = await choose(handle, text, options?.route);
+  if (pin !== undefined && choice.op === "read") {
+    pin.name = choice.endpoint.name;
+    return { ...choice, pinned: true };
+  }
+  return choice;
+}
+function taken(options) {
+  if (options === undefined || !("pin" in options))
+    return;
+  const pin = options.pin;
+  if (typeof pin !== "object" || pin === null)
+    return;
+  return pin;
+}
+function held(handle, name) {
+  for (const endpoint of handle.endpoints) {
+    if (endpoint.name !== name)
+      continue;
+    return { endpoint, op: "read", reason: `stream:${name}`, pinned: true };
+  }
+  throw new OkmError("OKM1120", `stream() stays on ${name}. That target is not in this topology.`, {
+    fix: { summary: "The first batch chose this target. Later batches do not move." }
+  });
+}
+async function noteWrite(handle, runner) {
+  if (!tracks(handle))
+    return;
+  const primary = handle.endpoints[0];
+  if (primary === undefined || !primary.position) {
+    markUnknown(handle);
+    return;
+  }
+  try {
+    const lsn = await readInsertLsn(runner);
+    if (lsn === undefined) {
+      markUnknown(handle);
+      return;
+    }
+    raiseWatermark(handle, lsn);
+  } catch {
+    markUnknown(handle);
+  }
+}
+function markUnknown(handle) {
+  handle.positionUnknown = true;
+  handle.unknownEpoch += 1;
+}
+function tracks(handle) {
+  return handle.hasReplicas && handle.consistency === "session";
+}
+async function readInsertLsn(runner) {
+  const result = await runner.execute(INSERT_LSN_SQL);
+  const text = result.rows[0]?.[0];
+  if (text === null || text === undefined)
+    return;
+  return parseLsn(text);
+}
+function notePrimary(handle, lsn) {
+  if (handle.primaryLsn === undefined || lsn > handle.primaryLsn)
+    handle.primaryLsn = lsn;
+}
+function raiseWatermark(handle, lsn) {
+  notePrimary(handle, lsn);
+  if (handle.watermark === undefined || lsn > handle.watermark)
+    handle.watermark = lsn;
+  handle.positionUnknown = false;
+}
+function byteLag(handle, endpoint) {
+  const primary = handle.primaryLsn;
+  const replay = endpoint.replayPos;
+  if (primary === undefined || replay === undefined)
+    return null;
+  if (replay >= primary)
+    return 0n;
+  return primary - replay;
+}
+function byteLagNumber(handle, endpoint) {
+  const diff = byteLag(handle, endpoint);
+  if (diff === null)
+    return null;
+  if (diff > BigInt(Number.MAX_SAFE_INTEGER))
+    return Number.MAX_SAFE_INTEGER;
+  return Number(diff);
+}
+function timeLag(handle, endpoint) {
+  const primary = handle.primaryLsn;
+  const replay = endpoint.replayPos;
+  if (primary === undefined || replay === undefined)
+    return null;
+  if (replay >= primary)
+    return 0;
+  if (endpoint.replayAt === null)
+    return null;
+  const lag = Date.now() - endpoint.replayAt;
+  return lag < 0 ? 0 : lag;
+}
+function parseLsn(text) {
+  const match = /^([0-9A-Fa-f]+)\/([0-9A-Fa-f]+)$/.exec(text.trim());
+  const high = match?.[1];
+  const low = match?.[2];
+  if (high === undefined || low === undefined)
+    return;
+  return (BigInt(`0x${high}`) << 32n) + BigInt(`0x${low}`);
+}
+function parseTime(text) {
+  const direct = Date.parse(text);
+  if (!Number.isNaN(direct))
+    return direct;
+  const iso = Date.parse(text.replace(" ", "T"));
+  if (!Number.isNaN(iso))
+    return iso;
+  return;
+}
+function controlKind(text) {
+  const head = text.trimStart().toLowerCase().replace(/\s+/g, " ");
+  if (/^commit\b/.test(head))
+    return "commit";
+  if (/^rollback\b/.test(head) && !/^rollback\s+to\b/.test(head))
+    return "rollback";
+  return "other";
+}
+function wrap(handle, conn) {
+  let pending = false;
+  return {
+    execute: async (text, params, options) => {
+      if (options?.route === "replica")
+        replicaRefused();
+      const result = await conn.execute(text, params, strip(options));
+      const kind = controlKind(text);
+      if (kind === "commit") {
+        if (pending) {
+          pending = false;
+          await noteWrite(handle, conn);
+        }
+      } else if (kind === "rollback") {
+        pending = false;
+      } else if (classOf(text) === "write") {
+        pending = true;
+      }
+      return result;
+    },
+    batch: async (statements, options) => {
+      if (options?.route === "replica")
+        replicaRefused();
+      const result = await conn.batch(statements, strip(options));
+      pending = true;
+      return result;
+    },
+    release: () => conn.release(),
+    ...conn.cancel !== undefined ? { cancel: () => conn.cancel() } : {}
+  };
+}
+function tell(handle, event) {
+  if (handle.onRoute === undefined)
+    return;
+  try {
+    handle.onRoute(event);
+  } catch {}
+}
+function readRoute(route) {
+  if (route === "primary" || route === "replica")
+    return route;
+  throw new OkmError("OKM1120", 'using takes "primary" or "replica".');
+}
+function readFallback(value) {
+  if (value === undefined || value === "primary")
+    return "primary";
+  if (value === "error")
+    return "error";
+  throw new OkmError("OKM1120", 'routing.fallback must be "primary" or "error".');
+}
+function closed() {
+  throw new OkmError("OKM1120", "The client is closed.");
+}
+function replicaRefused() {
+  throw new OkmError("OKM1840", "This operation needs the primary.", {
+    fix: {
+      summary: "Run the operation on the primary. Writes, batch, locks, and tx() never go to a replica."
+    }
+  });
+}
+function noReplica() {
+  throw new OkmError("OKM1843", "No replica is eligible. This call does not read the primary.", {
+    fix: {
+      summary: "Configure a replica or drop the route. This call does not read the primary."
+    }
+  });
+}
+function fallbackRefused(why) {
+  throw new OkmError("OKM1844", `No replica is eligible (${why}) and fallback is error.`, {
+    fix: {
+      summary: "Restore a replica, or set fallback to primary if the primary should absorb the read."
+    }
+  });
+}
+function truth(value) {
+  return value === "t" || value === "true" || value === "1";
+}
+function fields(value) {
+  return value;
+}
+var topology_default = connectTopology;
+export {
+  topology_default as default
+};