on-zero 0.7.10 → 0.8.0

package/src/helpers/recoverZeroClient.ts

@@ -1,7 +1,6 @@
-import type { Emitter } from '@take-out/helpers'
-import type { ZeroEvent } from '../types'
-import type { UpdateNeededReason } from '@rocicorp/zero'
+import type { ZeroEventsEmitter, ZeroRecoveryReasonKey } from '../types'
 import type { Context, LogLevel, LogSink } from '@rocicorp/logger'
+import type { UpdateNeededReason } from '@rocicorp/zero'
 
 // per-reason guard window: the SAME reason re-failing right after its reload is
 // surfaced as fatal instead of reload-storming on something the reload can't fix.
@@ -24,22 +23,21 @@ const STORE_CLOSED = 'Store is closed'
 const STORE_CLOSED_REPEAT_MIN_MS = 2_000
 const STORE_CLOSED_REPEAT_MAX_MS = 60_000
 
-export type ZeroRecoveryLogReason =
-  | 'indexeddb-not-found'
-  | 'sqlite-statement-finalized'
-  | 'store-closed-repeat'
-  | 'mutation-desync'
-  | 'connection-cookie-invalid'
-  | 'client-not-found'
-  | 'connection-userid-mismatch'
-
 export type ZeroRecoveryLogClassification = {
-  reason: ZeroRecoveryLogReason
-  reasonKey: string
+  reasonKey: Exclude<
+    ZeroRecoveryReasonKey,
+    | 'NewClientGroup'
+    | 'VersionNotSupported'
+    | 'SchemaVersionNotSupported'
+    | 'client-state-not-found'
+    | 'server-ack-timeout'
+  >
   message: string
   dropLocalState: boolean
 }
 
+export type ZeroLogPattern = string | RegExp
+
 // a minimal synchronous key/value store the cross-reload guard persists into.
 // web defaults to sessionStorage; native (Hermes) has none, so a consumer can
 // inject an MMKV/sqlite-backed store to get cross-reload loop protection — the
@@ -54,7 +52,7 @@ export type RecoveryGuardStorage = {
 // expo-updates reload) while still driving the SAME deletes-then-reload work.
 export type ScheduleReloadContext = {
   reason: string
-  reasonKey: string
+  reasonKey: ZeroRecoveryReasonKey
   dropLocalState: boolean
   // deletes every affected instance's local store, awaits beforeReload, then
   // reloads. idempotent — safe to call once the consumer decides to proceed.
@@ -67,7 +65,7 @@ export type ZeroRecoveryDeps = {
   // EVERY underlying store; the latch below keeps it to one reload.
   deleteLocalState: () => Promise<unknown>
   // recovery lifecycle for consumers (preview postMessage, toast, …).
-  zeroEvents: Emitter<ZeroEvent | null>
+  zeroEvents: ZeroEventsEmitter
   // awaited before the reload — e.g. wait for the dev origin to come back so the
   // reload doesn't land on a restarting server. optional.
   beforeReload?: () => Promise<void>
@@ -78,9 +76,11 @@ export type ZeroRecoveryDeps = {
   // cross-reload guard backing store (defaults to sessionStorage on web). inject
   // a native KV so Hermes gets real cross-reload loop protection.
   guardStorage?: RecoveryGuardStorage
-  // called with the joined log text for a classified recovery signature; return
-  // true to treat it as benign and NOT recover (soot's cf cold-boot timeout).
-  benignLogFilter?: (message: string) => boolean
+  // classified transport/app messages that are expected and must not recover.
+  benignLogPatterns?: readonly ZeroLogPattern[]
+  // internal lifecycle fence. recovery invalidates queued and in-flight work
+  // before the consumer can defer the reload.
+  onRecovery?: (reasonKey: ZeroRecoveryReasonKey) => void
   // injectable for tests; defaults to a real page reload.
   reload?: () => void
 }
@@ -117,8 +117,8 @@ function defaultGuardStorage(): RecoveryGuardStorage | undefined {
 // survives the reload, so a reason that reloaded then immediately re-fires is
 // caught as a genuine fatal instead of reload-storming across loads.
 function recoveryGuardOpen(
-  reasonKey: string,
-  guardStorage: RecoveryGuardStorage | undefined,
+  reasonKey: ZeroRecoveryReasonKey,
+  guardStorage: RecoveryGuardStorage | undefined
 ): boolean {
   const key = `on-zero-recover-${reasonKey}`
   const now = Date.now()
@@ -207,11 +207,12 @@ function performReload(deps: ZeroRecoveryDeps): Promise<void> {
 
 function recover(
   deps: ZeroRecoveryDeps,
-  reasonKey: string,
+  reasonKey: ZeroRecoveryReasonKey,
   message: string,
-  dropLocalState: boolean,
+  dropLocalState: boolean
 ): void {
   if (typeof window === 'undefined') return
+  deps.onRecovery?.(reasonKey)
   // each affected instance drops its OWN stale store, even when a reload is
   // already queued — otherwise a sibling's store survives the reload and
   // fatal-loops on the next boot. the single scheduled reload awaits these.
@@ -222,13 +223,13 @@ function recover(
   if (reloadScheduled) return
   if (!recoveryGuardOpen(reasonKey, deps.guardStorage)) {
     console.error(`[on-zero] ${message} — already recovered once, not reloading`)
-    deps.zeroEvents.emit({ type: 'fatal', reason: message })
+    deps.zeroEvents.emit({ type: 'fatal', reasonKey, reason: message })
     return
   }
   reloadScheduled = true
   armReloadLatchTimeout()
   console.warn(`[on-zero] ${message} — recovering`)
-  deps.zeroEvents.emit({ type: 'recovering', reason: message })
+  deps.zeroEvents.emit({ type: 'recovering', reasonKey, reason: message })
 
   const runReload = () => performReload(deps)
   if (deps.scheduleReload) {
@@ -261,7 +262,7 @@ export function makeZeroRecovery(deps: ZeroRecoveryDeps) {
         deps,
         reason.type,
         `update needed (${reason.message || reason.type})`,
-        dropLocalState,
+        dropLocalState
       )
     },
     onClientStateNotFound() {
@@ -269,6 +270,18 @@ export function makeZeroRecovery(deps: ZeroRecoveryDeps) {
       // drop it and reload into a fresh client.
       recover(deps, 'client-state-not-found', 'client state not found', true)
     },
+    onServerAckTimeout(input: {
+      label: string
+      timeoutMs: number
+      consecutiveTimeouts: number
+    }) {
+      recover(
+        deps,
+        'server-ack-timeout',
+        `${input.label} server acknowledgement timed out ${input.consecutiveTimeouts} consecutive times (${input.timeoutMs}ms each)`,
+        true
+      )
+    },
   }
 }
 
@@ -311,16 +324,14 @@ function isBenignStoreClosedLog(text: string): boolean {
 // the mutation/connection desync class: the local client group is out of sync
 // with the server's last-mutation-id / cookie / client record, so the store is
 // unusable and must be dropped + recovered. these surface only through the error
-// log, never the structured onClientStateNotFound callback. genuinely app-infra
-// signatures (a consumer's synthesized ack-timeout marker, a cold-boot connect
-// timeout) are NOT here — a consumer keeps those with benignLogFilter / its own
-// handling.
+// log, never the structured onClientStateNotFound callback. server acknowledgement
+// timeouts enter through the mutation lifecycle instead of string classification;
+// expected transport startup messages are declared through benignLogPatterns.
 function classifyMutationDesync(
-  text: string,
-): { reason: ZeroRecoveryLogReason; reasonKey: string; message: string } | undefined {
+  text: string
+): Pick<ZeroRecoveryLogClassification, 'reasonKey' | 'message'> | undefined {
   if (text.includes('sent mutation ID') && text.includes('but expected')) {
     return {
-      reason: 'mutation-desync',
       reasonKey: 'mutation-desync',
       message: 'mutation id desync',
     }
@@ -330,42 +341,36 @@ function classifyMutationDesync(
     text.includes('Server reported an out-of-order mutation')
   ) {
     return {
-      reason: 'mutation-desync',
       reasonKey: 'mutation-desync',
       message: 'out-of-order mutation',
     }
   }
   if (text.includes('already processed')) {
     return {
-      reason: 'mutation-desync',
       reasonKey: 'mutation-desync',
       message: 'mutation already processed',
     }
   }
   if (text.includes('InvalidConnectionRequestLastMutationID')) {
     return {
-      reason: 'mutation-desync',
       reasonKey: 'mutation-desync',
       message: 'invalid connection last mutation id',
     }
   }
   if (text.includes('InvalidConnectionRequestBaseCookie')) {
     return {
-      reason: 'connection-cookie-invalid',
       reasonKey: 'connection-cookie-invalid',
       message: 'invalid connection base cookie',
     }
   }
   if (text.includes('ClientNotFound') || text.includes('Client not found')) {
     return {
-      reason: 'client-not-found',
       reasonKey: 'client-not-found',
       message: 'client not found',
     }
   }
   if (text.includes('connection userID mismatch')) {
     return {
-      reason: 'connection-userid-mismatch',
       reasonKey: 'connection-userid-mismatch',
       message: 'connection user id mismatch',
     }
@@ -376,21 +381,19 @@ function classifyMutationDesync(
 export function classifyZeroRecoveryLog(
   level: LogLevel | string,
   args: readonly unknown[],
-  nowMs = Date.now(),
+  nowMs = Date.now()
 ): ZeroRecoveryLogClassification | undefined {
   if (level !== 'error') return undefined
   const text = args.map(logArgText).join(' ')
   if (text.includes(LOCAL_STORE_LOST)) {
     return {
-      reason: 'indexeddb-not-found',
-      reasonKey: 'local-store',
+      reasonKey: 'indexeddb-not-found',
       message: 'local store lost',
       dropLocalState: true,
     }
   }
   if (text.includes(SQLITE_ERROR_NAME) && text.includes(SQLITE_STATEMENT_FINALIZED)) {
     return {
-      reason: 'sqlite-statement-finalized',
       reasonKey: 'sqlite-statement-finalized',
       message: 'sqlite statement finalized',
       dropLocalState: true,
@@ -409,7 +412,6 @@ export function classifyZeroRecoveryLog(
       nowMs - prevMs <= STORE_CLOSED_REPEAT_MAX_MS
     ) {
       return {
-        reason: 'store-closed-repeat',
         reasonKey: 'store-closed-repeat',
         message: 'local store closed repeatedly',
         dropLocalState: true,
@@ -426,7 +428,7 @@ export function classifyZeroRecoveryLog(
 // consumer that owns log-based recovery isn't double-fired.
 export function composeRecoveryLogSink(
   deps: ZeroRecoveryDeps,
-  consumerLogSink?: LogSink,
+  consumerLogSink?: LogSink
 ): LogSink {
   const consumerFlush = consumerLogSink?.flush
   return {
@@ -435,10 +437,9 @@ export function composeRecoveryLogSink(
       else logToConsole(level, context, ...args)
       const recovery = classifyZeroRecoveryLog(level, args)
       if (!recovery) return
-      if (deps.benignLogFilter) {
-        const text = args.map(logArgText).join(' ')
-        if (deps.benignLogFilter(text)) return
-      }
+      const text = args.map(logArgText).join(' ')
+      if (deps.benignLogPatterns?.some((pattern) => matchesLogPattern(text, pattern)))
+        return
       recover(deps, recovery.reasonKey, recovery.message, recovery.dropLocalState)
     },
     // call through the consumer sink so a class-based sink keeps its `this`,
@@ -447,6 +448,12 @@ export function composeRecoveryLogSink(
   }
 }
 
+function matchesLogPattern(message: string, pattern: ZeroLogPattern): boolean {
+  if (typeof pattern === 'string') return message.includes(pattern)
+  pattern.lastIndex = 0
+  return pattern.test(message)
+}
+
 // generic Zero stale-poke / stale-cookie signatures: the client's view is behind
 // the server's snapshot cookie, which a plain reconnect resolves — this is not a
 // fatal store-loss, so ConnectionMonitor reconnects instead of recovering.

package/src/helpers/sleep.ts

@@ -0,0 +1,8 @@
+import { AbortError } from './errors'
+
+export const sleep = async (ms: number, signal?: AbortSignal): Promise<void> => {
+  await new Promise((res) => setTimeout(res, ms))
+  if (signal?.aborted) {
+    throw new AbortError()
+  }
+}

package/src/helpers/time.ts

@@ -0,0 +1,51 @@
+interface MsFunction {
+  (n: number): number
+  seconds: (n: number) => number
+  minutes: (n: number) => number
+  hours: (n: number) => number
+  days: (n: number) => number
+  weeks: (n: number) => number
+}
+
+interface SecondFunction {
+  (n: number): number
+  minutes: (n: number) => number
+  hours: (n: number) => number
+  days: (n: number) => number
+  weeks: (n: number) => number
+}
+
+interface MinuteFunction {
+  (n: number): number
+  hours: (n: number) => number
+  days: (n: number) => number
+  weeks: (n: number) => number
+}
+
+const ms = ((n: number) => n) as MsFunction
+ms.seconds = (n: number) => n * 1000
+ms.minutes = (n: number) => ms.seconds(n * 60)
+ms.hours = (n: number) => ms.minutes(n * 60)
+ms.days = (n: number) => ms.hours(n * 24)
+ms.weeks = (n: number) => ms.days(n * 7)
+
+const second = ((n: number) => n) as SecondFunction
+second.minutes = (n: number) => n * 60
+second.hours = (n: number) => second.minutes(n * 60)
+second.days = (n: number) => second.hours(n * 24)
+second.weeks = (n: number) => second.days(n * 7)
+
+const minute = ((n: number) => n * 60) as MinuteFunction
+minute.hours = (n: number) => minute(n * 60)
+minute.days = (n: number) => minute.hours(n * 24)
+minute.weeks = (n: number) => minute.days(n * 7)
+
+export const time: {
+  ms: MsFunction
+  second: SecondFunction
+  minute: MinuteFunction
+} = {
+  ms,
+  second,
+  minute,
+}

package/src/helpers/tuple.ts

@@ -0,0 +1 @@
+export type TupleToUnion<T extends any[]> = T[number]

package/src/helpers/useMutation.tsx

@@ -53,7 +53,7 @@ function emitMutationError(error: MutationError): void {
 
 function toMutationError(
   scope: 'client' | 'server',
-  details: unknown,
+  details: unknown
 ): MutationError | null {
   if (!details || typeof details !== 'object') return null
   const d = details as {
@@ -90,7 +90,7 @@ function rejectionToError(scope: 'client' | 'server', e: unknown): MutationError
  */
 export function observeMutation(
   result: MutatorResultLike,
-  onError?: (error: MutationError) => void,
+  onError?: (error: MutationError) => void
 ): Promise<void> {
   let reportedGlobal = false
   const report = (err: MutationError | null) => {
@@ -128,7 +128,7 @@ export function observeMutation(
  * transaction, not N calls — that keeps it atomic and a single state.
  */
 export function useMutation<Fn extends (...args: any[]) => MutatorResultLike>(
-  mutator: Fn,
+  mutator: Fn
 ): [Fn, MutationState] {
   const [pending, setPending] = useState(false)
   const [error, setError] = useState<MutationError | null>(null)

package/src/helpers/useZeroDebug.ts

@@ -1,6 +1,6 @@
-import { getCurrentComponentStack } from '@take-out/helpers'
 import { useEffect, useId } from 'react'
 
+import { getCurrentComponentStack } from './getCurrentComponentStack'
 import { prettyFormatZeroQuery } from './prettyFormatZeroQuery'
 
 import type { Query } from '@rocicorp/zero'
@@ -42,7 +42,7 @@ export const useZeroDebug = (query: Query<any, any, any>, options: any, results:
     if (shouldLog) {
       if (COLLAPSED) {
         console.groupCollapsed(
-          `${isPermissionQuery ? `👮‍♂️` : `✨`}${prettyFormatZeroQuery(query, 'minimal')}`,
+          `${isPermissionQuery ? `👮‍♂️` : `✨`}${prettyFormatZeroQuery(query, 'minimal')}`
         )
         console.info(id, prettyFormatZeroQuery(query, 'full'))
         console.info('cached result', results)
@@ -80,7 +80,7 @@ export const useZeroDebug = (query: Query<any, any, any>, options: any, results:
             table,
             changeCount: history.changeCount,
             recentAsts: history.asts,
-          },
+          }
         )
       }
     }

package/src/index.ts

@@ -24,6 +24,7 @@ export * from './mutations'
 export * from './where'
 export * from './serverWhere'
 export * from './zql'
+export { defineConfig, type DataConfig, type DataInstanceConfig } from './config'
 export { defineQuery, defineQueries } from '@rocicorp/zero'
 
 // drizzle-zero re-exports moved to 'on-zero/drizzle' to avoid pulling
@@ -48,8 +49,19 @@ export {
   composeRecoveryLogSink,
   isRecoverableZeroStalePokeMessage,
   type ZeroRecoveryLogClassification,
-  type ZeroRecoveryLogReason,
   type ZeroRecoveryDeps,
   type ScheduleReloadContext,
   type RecoveryGuardStorage,
+  type ZeroLogPattern,
 } from './helpers/recoverZeroClient'
+
+export {
+  isStaleGenerationError,
+  mutationErrorMessage,
+  MutationResultError,
+  MutationTimeoutError,
+  StaleGenerationError,
+  type BackgroundMutationOptions,
+  type MutationLike,
+  type MutationPhase,
+} from './helpers/mutationLifecycle'

package/src/instanceRegistry.ts

@@ -7,8 +7,9 @@
 // stored via globalValue so dual-loaded module copies (cjs/esm) share one map,
 // matching the package's other cross-module registries.
 
-import { globalValue } from '@take-out/helpers'
+import { globalValue } from './helpers/globalValue'
 import { getQueryName } from './queryRegistry'
+
 import type { ZeroRunner } from './zeroRunner'
 import type { AnyQueryRegistry } from '@rocicorp/zero'
 
@@ -23,15 +24,27 @@ export type ZeroClientInstance = {
 const getInstancesByNamespace = () =>
   globalValue<Map<string, ZeroClientInstance>>(
     'on-zero:instances-by-namespace',
-    () => new Map(),
+    () => new Map()
   )
 
 const getInstancesByQueryName = () =>
   globalValue<Map<string, ZeroClientInstance>>(
     'on-zero:instances-by-query-name',
-    () => new Map(),
+    () => new Map()
   )
 
+export function releaseClientInstances(names: readonly string[]): void {
+  const releasing = new Set(names)
+  const instancesByNamespace = getInstancesByNamespace()
+  const instancesByQueryName = getInstancesByQueryName()
+  for (const [namespace, owner] of instancesByNamespace) {
+    if (releasing.has(owner.name)) instancesByNamespace.delete(namespace)
+  }
+  for (const [queryName, owner] of instancesByQueryName) {
+    if (releasing.has(owner.name)) instancesByQueryName.delete(queryName)
+  }
+}
+
 export function registerClientInstance({
   name,
   namespaces,
@@ -65,7 +78,7 @@ export function registerClientInstance({
     if (existing) {
       throw new Error(
         `[on-zero] namespace '${namespace}' is already claimed by zero client instance '${existing.name}' ` +
-          `(while creating instance '${name}'). Each query/mutator namespace must belong to exactly one createZeroClient instance.`,
+          `(while creating instance '${name}'). Each query/mutator namespace must belong to exactly one createZeroClient instance.`
       )
     }
     instancesByNamespace.set(namespace, instance)
@@ -76,7 +89,7 @@ export function registerClientInstance({
     if (existing) {
       throw new Error(
         `[on-zero] query '${queryName}' is already claimed by zero client instance '${existing.name}' ` +
-          `(while creating instance '${name}'). Each query function must belong to exactly one createZeroClient instance.`,
+          `(while creating instance '${name}'). Each query function must belong to exactly one createZeroClient instance.`
       )
     }
     instancesByQueryName.set(queryName, instance)
@@ -86,7 +99,7 @@ export function registerClientInstance({
 }
 
 export function getInstanceForNamespace(
-  namespace: string,
+  namespace: string
 ): ZeroClientInstance | undefined {
   return getInstancesByNamespace().get(namespace)
 }

package/src/multi.ts

@@ -1,9 +1,11 @@
+import { combineZeroClients } from './combineZeroClients'
+import { createUseQueryDirect } from './createUseQueryDirect'
 import {
   createZeroClientInternal,
   type DirectQueryAdapter,
   type CreateZeroClientOptions,
 } from './createZeroClient'
-import { createUseQueryDirect } from './createUseQueryDirect'
+import { releaseClientInstances } from './instanceRegistry'
 
 import type { GenericModels } from './types'
 import type { Schema as ZeroSchema } from '@rocicorp/zero'
@@ -14,7 +16,7 @@ export function createZeroClientWithDirectQueries<
   Schema extends ZeroSchema,
   Models extends GenericModels,
 >(
-  options: CreateZeroClientOptions<Schema, Models>,
+  options: CreateZeroClientOptions<Schema, Models>
 ): ReturnType<typeof createZeroClientInternal<Schema, Models>> {
   const createDirectUseQuery: DirectQueryAdapter<Schema> = createUseQueryDirect
   return createZeroClientInternal<Schema, Models>({
@@ -23,35 +25,77 @@ export function createZeroClientWithDirectQueries<
   })
 }
 
-// fail loud when a generated namespace drifts out of a multi-instance partition.
-// multi-instance consumers (control + project, control + server, …) hand-split
-// the generated query/model namespaces across instances; a namespace that ends
-// up in NEITHER partition silently un-registers its queries (its useQuery throws
-// "query not registered" at runtime, error-boundarying a whole screen — the soot
-// `planGrant` regression). run this at module-eval over each partitioned group so
-// the drift is a build/boot throw instead. also catches a namespace listed in
-// MORE than one partition (an ambiguous owner), which the hand-rolled loops did
-// not. `partitions` maps a label (e.g. 'control'/'project') to that instance's
-// namespace table; every key in `entries` must appear in exactly one.
-export function assertZeroInstancePartition(
-  kind: string,
-  entries: Record<string, unknown>,
-  partitions: Record<string, Record<string, unknown>>,
-): void {
-  const labels = Object.keys(partitions)
-  for (const name of Object.keys(entries)) {
-    const owners = labels.filter((label) => name in partitions[label])
-    if (owners.length === 0) {
-      throw new Error(
-        `[on-zero] generated ${kind} "${name}" is missing from the instance partition ` +
-          `(${labels.join(' / ')}) — add it to exactly one partition table.`,
-      )
-    }
-    if (owners.length > 1) {
-      throw new Error(
-        `[on-zero] generated ${kind} "${name}" is claimed by more than one instance partition ` +
-          `(${owners.join(', ')}) — it must belong to exactly one.`,
-      )
+export type ZeroInstanceManifestEntry<
+  Schema extends ZeroSchema = ZeroSchema,
+  Models extends GenericModels = GenericModels,
+> = {
+  schema: Schema
+  queries: CreateZeroClientOptions<Schema, Models>['groupedQueries']
+  models: Models
+  tables: readonly string[]
+  syncTables: readonly string[]
+  supportTables: readonly string[]
+  scope: string | null
+  defaultVisibility: ((value: string) => { column: string; value: string }) | null
+}
+
+type ClientFor<Entry> =
+  Entry extends ZeroInstanceManifestEntry<infer Schema, infer Models>
+    ? ReturnType<typeof createZeroClientInternal<Schema, Models>>
+    : never
+
+type ClientMap<Instances extends Record<string, ZeroInstanceManifestEntry>> = {
+  [Name in keyof Instances]: ClientFor<Instances[Name]>
+}
+
+type ClientUnion<Instances extends Record<string, ZeroInstanceManifestEntry>> =
+  ClientMap<Instances>[keyof Instances]
+
+export function createZeroClients<
+  const Instances extends Record<string, ZeroInstanceManifestEntry>,
+>(instances: Instances) {
+  const names = Object.keys(instances)
+  if (names.length === 0) {
+    throw new Error('[on-zero] createZeroClients requires at least one instance')
+  }
+  if (names.includes('default')) {
+    names.splice(names.indexOf('default'), 1)
+    names.unshift('default')
+  }
+
+  const innerName = names[names.length - 1]!
+  const clients: Record<string, ReturnType<typeof createZeroClientInternal>> = {}
+
+  // release the complete old partition atomically before any new instance
+  // claims namespaces that may have moved during hot reload.
+  releaseClientInstances(names)
+  for (const name of [...names].reverse()) {
+    const instance = instances[name]!
+    const options = {
+      schema: instance.schema,
+      models: instance.models,
+      groupedQueries: instance.queries,
+      instanceName: name,
     }
+    clients[name] =
+      name === innerName
+        ? createZeroClientInternal(options)
+        : createZeroClientWithDirectQueries(options)
+  }
+
+  const typedClients = clients as ClientMap<Instances>
+  // names is checked non-empty above. retain the union of the concrete client
+  // types so combineZeroClients can intersect every instance surface.
+  const orderedClients = names.map(
+    (name) => typedClients[name as keyof Instances]
+  ) as unknown as [ClientUnion<Instances>, ...ClientUnion<Instances>[]]
+  const providers = Object.fromEntries(
+    names.map((name) => [name, clients[name]!.ProvideZero])
+  ) as { [Name in keyof Instances]: ClientMap<Instances>[Name]['ProvideZero'] }
+
+  return {
+    clients: typedClients,
+    providers,
+    combined: combineZeroClients(...orderedClients),
   }
 }