@nmtjs/client 0.15.0-beta.9 → 0.15.1

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './core.ts'
 export * from './events.ts'
+export * from './plugins/index.ts'
 export * from './transformers.ts'
 export * from './transport.ts'
 export * from './types.ts'

package/src/plugins/browser.ts

@@ -0,0 +1,61 @@
+import type { ClientPlugin } from './types.ts'
+
+export const browserConnectivityPlugin = (): ClientPlugin => {
+  return (client) => {
+    const cleanup: Array<() => void> = []
+
+    const maybeConnect = () => {
+      if (client.state === 'disconnected' && !client.isDisposed()) {
+        client.connect().catch(() => void 0)
+      }
+    }
+
+    return {
+      name: 'browser-connectivity',
+      onInit: () => {
+        if (globalThis.window) {
+          const onPageShow = () => maybeConnect()
+          globalThis.window.addEventListener('pageshow', onPageShow)
+          cleanup.push(() =>
+            globalThis.window?.removeEventListener('pageshow', onPageShow),
+          )
+
+          const onOnline = () => maybeConnect()
+          globalThis.window.addEventListener('online', onOnline)
+          cleanup.push(() =>
+            globalThis.window?.removeEventListener('online', onOnline),
+          )
+
+          const onFocus = () => maybeConnect()
+          globalThis.window.addEventListener('focus', onFocus)
+          cleanup.push(() =>
+            globalThis.window?.removeEventListener('focus', onFocus),
+          )
+        }
+
+        if (globalThis.document) {
+          const onVisibilityChange = () => {
+            if (globalThis.document?.visibilityState === 'visible') {
+              maybeConnect()
+            }
+          }
+
+          globalThis.document.addEventListener(
+            'visibilitychange',
+            onVisibilityChange,
+          )
+          cleanup.push(() =>
+            globalThis.document?.removeEventListener(
+              'visibilitychange',
+              onVisibilityChange,
+            ),
+          )
+        }
+      },
+      dispose: () => {
+        for (const stop of cleanup) stop()
+        cleanup.length = 0
+      },
+    }
+  }
+}

package/src/plugins/heartbeat.ts

@@ -0,0 +1,111 @@
+import { ConnectionType } from '@nmtjs/protocol'
+
+import type { ClientPlugin } from './types.ts'
+
+const DEFAULT_HEARTBEAT_INTERVAL = 15000
+const DEFAULT_HEARTBEAT_TIMEOUT = 5000
+
+const sleep = (ms: number, signal?: AbortSignal) => {
+  return new Promise<void>((resolve) => {
+    if (signal?.aborted) return resolve()
+    const timer = setTimeout(resolve, ms)
+    if (signal) {
+      signal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        { once: true },
+      )
+    }
+  })
+}
+
+const isPaused = () => {
+  if (globalThis.window && 'navigator' in globalThis.window) {
+    if (globalThis.window.navigator?.onLine === false) return true
+  }
+  if (globalThis.document) {
+    if (globalThis.document.visibilityState === 'hidden') return true
+  }
+  return false
+}
+
+export interface HeartbeatPluginOptions {
+  interval?: number
+  timeout?: number
+}
+
+export const heartbeatPlugin = (
+  options: HeartbeatPluginOptions = {},
+): ClientPlugin => {
+  return (client) => {
+    const interval = options.interval ?? DEFAULT_HEARTBEAT_INTERVAL
+    const timeout = options.timeout ?? DEFAULT_HEARTBEAT_TIMEOUT
+
+    let heartbeatAbortController: AbortController | null = null
+    let heartbeatTask: Promise<void> | null = null
+
+    const stopHeartbeat = () => {
+      heartbeatAbortController?.abort()
+      heartbeatAbortController = null
+      heartbeatTask = null
+    }
+
+    const startHeartbeat = () => {
+      if (heartbeatTask) return
+      if (client.transportType !== ConnectionType.Bidirectional) return
+
+      heartbeatAbortController = new AbortController()
+      const signal = heartbeatAbortController.signal
+
+      heartbeatTask = (async () => {
+        while (
+          !signal.aborted &&
+          !client.isDisposed() &&
+          client.state === 'connected'
+        ) {
+          if (isPaused()) {
+            await sleep(1000, signal)
+            continue
+          }
+
+          await sleep(interval, signal)
+
+          if (
+            signal.aborted ||
+            client.isDisposed() ||
+            client.state !== 'connected'
+          ) {
+            continue
+          }
+
+          try {
+            await client.ping(timeout, signal)
+          } catch {
+            if (
+              !signal.aborted &&
+              !client.isDisposed() &&
+              client.state === 'connected'
+            ) {
+              await client
+                .requestReconnect('heartbeat_timeout')
+                .catch(() => void 0)
+            }
+          }
+        }
+      })().finally(() => {
+        heartbeatTask = null
+        heartbeatAbortController = null
+      })
+    }
+
+    return {
+      name: 'heartbeat',
+      onConnect: startHeartbeat,
+      onDisconnect: () => stopHeartbeat(),
+      dispose: stopHeartbeat,
+    }
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,5 @@
+export * from './browser.ts'
+export * from './heartbeat.ts'
+export * from './logging.ts'
+export * from './reconnect.ts'
+export * from './types.ts'

package/src/plugins/logging.ts

@@ -0,0 +1,42 @@
+import type { ClientPlugin, ClientPluginEvent } from './types.ts'
+
+export type ClientLogEvent = ClientPluginEvent
+
+export interface LoggingPluginOptions {
+  includeBodies?: boolean
+  onEvent(event: ClientLogEvent): void | Promise<void>
+  mapEvent?(event: ClientLogEvent): ClientLogEvent | null
+  onSinkError?(error: unknown, event: ClientLogEvent): void
+}
+
+const stripEventBody = (event: ClientLogEvent): ClientLogEvent => {
+  if (!('body' in event)) return event
+
+  const { body: _body, ...rest } = event
+  return rest as ClientLogEvent
+}
+
+export const loggingPlugin = (options: LoggingPluginOptions): ClientPlugin => {
+  const includeBodies = options.includeBodies ?? false
+
+  return () => ({
+    name: 'logging',
+    onClientEvent: (event) => {
+      const eventToMap = includeBodies ? event : stripEventBody(event)
+      const mappedEvent = options.mapEvent
+        ? options.mapEvent(eventToMap)
+        : eventToMap
+
+      if (!mappedEvent) return
+
+      try {
+        const sinkResult = options.onEvent(mappedEvent)
+        Promise.resolve(sinkResult).catch((error) => {
+          options.onSinkError?.(error, mappedEvent)
+        })
+      } catch (error) {
+        options.onSinkError?.(error, mappedEvent)
+      }
+    },
+  })
+}

package/src/plugins/reconnect.ts

@@ -0,0 +1,130 @@
+import { ConnectionType } from '@nmtjs/protocol'
+
+import type { ClientDisconnectReason, ClientPlugin } from './types.ts'
+
+const DEFAULT_RECONNECT_TIMEOUT = 1000
+const DEFAULT_MAX_RECONNECT_TIMEOUT = 60000
+
+const sleep = (ms: number, signal?: AbortSignal) => {
+  return new Promise<void>((resolve) => {
+    if (signal?.aborted) return resolve()
+    const timer = setTimeout(resolve, ms)
+    if (signal) {
+      signal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        { once: true },
+      )
+    }
+  })
+}
+
+const computeReconnectDelay = (ms: number) => {
+  if (globalThis.window) {
+    const jitter = Math.floor(ms * 0.2 * Math.random())
+    return ms + jitter
+  }
+  return ms
+}
+
+const isReconnectPaused = () => {
+  if (globalThis.window && 'navigator' in globalThis.window) {
+    if (globalThis.window.navigator?.onLine === false) return true
+  }
+  if (globalThis.document) {
+    if (globalThis.document.visibilityState === 'hidden') return true
+  }
+  return false
+}
+
+export interface ReconnectPluginOptions {
+  initialTimeout?: number
+  maxTimeout?: number
+}
+
+export const reconnectPlugin = (
+  options: ReconnectPluginOptions = {},
+): ClientPlugin => {
+  return (client) => {
+    let reconnecting: Promise<void> | null = null
+    let reconnectAbortController: AbortController | null = null
+    let reconnectTimeout = options.initialTimeout ?? DEFAULT_RECONNECT_TIMEOUT
+
+    const cancelReconnect = () => {
+      reconnectAbortController?.abort()
+      reconnectAbortController = null
+      reconnecting = null
+    }
+
+    const ensureReconnectLoop = () => {
+      if (reconnecting) return
+
+      reconnectAbortController = new AbortController()
+      const signal = reconnectAbortController.signal
+
+      reconnecting = (async () => {
+        while (
+          !signal.aborted &&
+          !client.isDisposed() &&
+          client.state === 'disconnected' &&
+          client.lastDisconnectReason !== 'client'
+        ) {
+          if (isReconnectPaused()) {
+            await sleep(1000, signal)
+            continue
+          }
+
+          const delay = computeReconnectDelay(reconnectTimeout)
+          await sleep(delay, signal)
+
+          if (
+            signal.aborted ||
+            client.isDisposed() ||
+            client.state !== 'disconnected' ||
+            client.lastDisconnectReason === 'client'
+          ) {
+            break
+          }
+
+          const previousTimeout = reconnectTimeout
+          await client.connect().catch(() => void 0)
+
+          if (client.state === 'disconnected') {
+            reconnectTimeout = Math.min(
+              previousTimeout * 2,
+              options.maxTimeout ?? DEFAULT_MAX_RECONNECT_TIMEOUT,
+            )
+          }
+        }
+      })().finally(() => {
+        reconnecting = null
+        reconnectAbortController = null
+      })
+    }
+
+    const onDisconnect = (reason: ClientDisconnectReason) => {
+      if (
+        client.transportType !== ConnectionType.Bidirectional ||
+        reason === 'client' ||
+        client.isDisposed()
+      ) {
+        cancelReconnect()
+        return
+      }
+      ensureReconnectLoop()
+    }
+
+    return {
+      name: 'reconnect',
+      onConnect: () => {
+        reconnectTimeout = options.initialTimeout ?? DEFAULT_RECONNECT_TIMEOUT
+        cancelReconnect()
+      },
+      onDisconnect,
+      dispose: cancelReconnect,
+    }
+  }
+}

package/src/plugins/types.ts

@@ -0,0 +1,72 @@
+import type { BaseClient } from '../core.ts'
+
+export type ClientDisconnectReason = 'client' | 'server' | (string & {})
+
+export type ClientPluginEvent =
+  | {
+      kind: 'connected'
+      timestamp: number
+      transportType: 'bidirectional' | 'unidirectional'
+    }
+  | { kind: 'disconnected'; timestamp: number; reason: ClientDisconnectReason }
+  | {
+      kind: 'server_message'
+      timestamp: number
+      messageType: number | string
+      rawByteLength: number
+      body?: unknown
+    }
+  | {
+      kind: 'rpc_request'
+      timestamp: number
+      callId: number
+      procedure: string
+      body?: unknown
+    }
+  | {
+      kind: 'rpc_response'
+      timestamp: number
+      callId: number
+      procedure: string
+      body?: unknown
+      stream?: boolean
+    }
+  | {
+      kind: 'rpc_error'
+      timestamp: number
+      callId: number
+      procedure: string
+      error: unknown
+    }
+  | {
+      kind: 'stream_event'
+      timestamp: number
+      direction: 'incoming' | 'outgoing'
+      streamType: 'rpc' | 'client_blob' | 'server_blob'
+      action: 'response' | 'pull' | 'push' | 'end' | 'abort'
+      callId?: number
+      streamId?: number
+      byteLength?: number
+      reason?: string
+    }
+
+/**
+ * Client plugin lifecycle contract.
+ *
+ * Ordering guarantees:
+ * - `onInit`, `onConnect`, `onServerMessage`, `onClientEvent`: registration order
+ * - `onDisconnect`, `dispose`: reverse registration order
+ */
+export interface ClientPluginInstance {
+  name?: string
+  onInit?(): void
+  onConnect?(): void | Promise<void>
+  onDisconnect?(reason: ClientDisconnectReason): void | Promise<void>
+  onServerMessage?(message: unknown, raw: ArrayBufferView): void
+  onClientEvent?(event: ClientPluginEvent): void | Promise<void>
+  dispose?(): void
+}
+
+export type ClientPlugin = (
+  client: BaseClient<any, any, any, any, any>,
+) => ClientPluginInstance

package/src/streams.ts

@@ -29,7 +29,7 @@ export class ClientStreams {
     this.#collection.delete(streamId)
   }
 
-  async abort(streamId: number, reason?: string) {
+  async abort(streamId: number, reason?: any) {
     const stream = this.#collection.get(streamId)
     if (!stream) return // Stream already cleaned up
     await stream.abort(reason)
@@ -46,7 +46,7 @@ export class ClientStreams {
     this.remove(streamId)
   }
 
-  async clear(reason?: string) {
+  async clear(reason?: any) {
     if (reason) {
       const abortPromises = [...this.#collection.values()].map((stream) =>
         stream.abort(reason),
@@ -118,7 +118,7 @@ export class ServerStreams<
     this.remove(streamId)
   }
 
-  async clear(reason?: string) {
+  async clear(reason?: any) {
     if (reason) {
       const abortPromises = [...this.#writers.values()].map((writer) =>
         writer.abort(reason).finally(() => writer.releaseLock()),

package/src/types.ts

@@ -4,7 +4,6 @@ import type { ProtocolBlobInterface } from '@nmtjs/protocol'
 import type {
   ProtocolError,
   ProtocolServerBlobStream,
-  ProtocolServerStreamInterface,
 } from '@nmtjs/protocol/client'
 import type { BaseTypeAny, PlainType, t } from '@nmtjs/type'
 
@@ -60,9 +59,7 @@ export type AnyResolvedContractProcedure = {
 
 export type AnyResolvedContractRouter = {
   [ResolvedType]: 'router'
-  [key: string]:
-    | AnyResolvedContractProcedure
-    | { [ResolvedType]: 'router'; [key: string]: AnyResolvedContractProcedure }
+  [key: string]: AnyResolvedContractProcedure | AnyResolvedContractRouter
 }
 
 export type ResolveAPIRouterRoutes<
@@ -114,19 +111,6 @@ type OmitType<T extends object, E> = {
   [K in keyof T as T[K] extends E ? never : K]: T[K]
 }
 
-// export type FilterResolvedContractRouter<
-//   Resolved extends AnyResolvedContractRouter,
-//   Stream extends boolean,
-// > = {
-//   [K in keyof Resolved]: Resolved[K] extends AnyResolvedContractProcedure
-//     ? Resolved[K]['stream'] extends Stream
-//       ? Resolved[K]
-//       : never
-//     : Resolved[K] extends AnyResolvedContractRouter
-//       ? FilterResolvedContractRouter<Resolved[K], Stream>
-//       : never
-// }
-
 export type ClientCallers<
   Resolved extends AnyResolvedContractRouter,
   SafeCall extends boolean,