fix: enhance documentation comments

Author: Gioee

src/drivers/connection-ws.ts

@@ -143,16 +143,24 @@ export class SQLiteCloudWebsocketConnection extends SQLiteCloudConnection {
   }
 }
 
-/** Builds the gateway hostname from a core hostname by replacing the last two labels with
- *  the given `gatewayurl` suffix (default `gateway.sqlite.cloud`). Returns host unchanged
- *  when it already ends with the suffix (idempotent) or is too short to have a tenant prefix. */
+/** Default gateway domain suffix used when `gatewayurl` is not provided. */
+const DEFAULT_GATEWAY_DOMAIN = 'gateway.sqlite.cloud'
+
+/** Builds the gateway hostname from a core hostname, swapping its last two labels (the
+ *  TLD) with the given `gatewayurl` suffix.
+ *
+ *  Example: buildGatewayHost('crvheg7dhk.g4.sqlite.cloud')
+ *    → 'crvheg7dhk.g4.gateway.sqlite.cloud'
+ *
+ *  Returns `host` unchanged when it already ends with the suffix (idempotent) or when
+ *  it's too short to extract a tenant prefix (eg 'localhost'). */
 function buildGatewayHost(host: string, gatewayurl?: string): string {
   if (!host) return host
-  const suffix = gatewayurl || 'gateway.sqlite.cloud'
+  const suffix = gatewayurl || DEFAULT_GATEWAY_DOMAIN
   if (host === suffix || host.endsWith('.' + suffix)) return host
-  const labels = host.split('.')
-  if (labels.length < 3) return host
-  return labels.slice(0, -2).join('.') + '.' + suffix
+  const parts = host.split('.')
+  if (parts.length < 3) return host
+  return parts.slice(0, -2).join('.') + '.' + suffix
 }
 
 export default SQLiteCloudWebsocketConnection

src/drivers/types.ts

@@ -92,9 +92,14 @@ export interface SQLiteCloudConfig {
 
   /** True if we should force use of SQLite Cloud Gateway and websocket connections, default: true in browsers, false in node.js */
   usewebsocket?: boolean
-  /** Domain suffix that identifies the gateway environment. Appended to the tenant prefix
-   *  (eg `crvheg7dhk.g4`) to form the gateway hostname the driver connects to. Default:
-   *  `gateway.sqlite.cloud`. */
+  /** Domain suffix used to build the gateway hostname the driver connects to.
+   *  Default: `gateway.sqlite.cloud`.
+   *
+   *  Example: with `host: 'crvheg7dhk.g4.sqlite.cloud'` and the default `gatewayurl`,
+   *  the driver opens `wss://crvheg7dhk.g4.gateway.sqlite.cloud:443`. For local
+   *  development, pass a value containing `localhost` (eg `'ws://localhost:4000'`)
+   *  and the driver will route TCP to that target while forwarding `host` as the
+   *  gateway Host header. */
   gatewayurl?: string
 
   /** Optional identifier used for verbose logging */