Merge remote-tracking branch 'origin/trunk' into lukim/spice.js

Author: lukekim

.editorconfig

@@ -1,2 +1,3 @@
 [*]
-quote_type = single
+quote_type = single
+trailing_comma = all

.github/actions/setup-vercel-endpoint/action.yml

@@ -44,8 +44,8 @@ runs:
           echo "Detected tag/release: ${BRANCH_NAME}, using production endpoint"
         else
           # For branches, construct the git branch preview URL
-          # Remove periods, replace / with - and convert to lowercase for Vercel format
-          BRANCH_SLUG=$(echo "$BRANCH_NAME" | sed 's/\.//g' | sed 's/\//-/g' | tr '[:upper:]' '[:lower:]')
+          # Remove periods, replace first / with -, remove remaining /, convert to lowercase for Vercel format
+          BRANCH_SLUG=$(echo "$BRANCH_NAME" | sed 's/\.//g' | sed 's/\//-/' | sed 's/\///g' | tr '[:upper:]' '[:lower:]')
           VERCEL_ENDPOINT="https://spice-js-git-${BRANCH_SLUG}-spice.vercel.app"
           echo "Detected branch: ${BRANCH_NAME}, using preview endpoint"
         fi

.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "semi": true,
+  "arrowParens": "always"
+}

README.md

@@ -33,6 +33,7 @@ Querying data is done through a `SpiceClient` object that initializes the connec
 - `apiKey` (string, optional): API key to authenticate with the endpoint.
 - `flightUrl` (string, optional): URL of the Flight endpoint to use (default: `localhost:50051`)
 - `httpUrl` (string, optional): URL of the HTTP endpoint to use (default: `http://localhost:8090`)
+- `logging` (boolean, optional): Enable or disable logging output (default: `true`). Set to `false` to silence all library console output.
 
 Read more about the Spice.ai Apache Arrow Flight API at [docs.spice.ai](https://docs.spice.ai/api/sql-query-api/apache-arrow-flight-api).
 

src/client-common.ts

@@ -24,6 +24,7 @@ import {
   normalizeSchema,
   serializeArrowField,
 } from './arrow-utils';
+import { Logger } from './logger';
 
 // Retry will be imported by the platform-specific entry point
 export interface RetryModule {
@@ -428,6 +429,7 @@ export class SpiceClient {
   private _retry: RetryModule;
   private _isSpiceCloud: boolean = false;
   private _flightOnly: boolean = false;
+  private _logger: Logger;
 
   // Default Spice Cloud endpoints
   private static readonly DEFAULT_CLOUD_HTTP = 'https://data.spiceai.io';
@@ -450,6 +452,7 @@ export class SpiceClient {
       this._flightUrl = SpiceClient.DEFAULT_CLOUD_FLIGHT;
       this._userAgent = platform.getUserAgent();
       this._flightOnly = false;
+      this._logger = new Logger(true); // Default: logging enabled
     } else {
       const {
         apiKey,
@@ -459,8 +462,12 @@ export class SpiceClient {
         userAgent,
         customHeaders,
         flightOnly,
+        logging,
       } = params;
 
+      // Initialize logger (default: enabled)
+      this._logger = new Logger(logging !== false);
+
       this._apiKey = apiKey;
       this._flightOnly = flightOnly || false;
 
@@ -509,6 +516,7 @@ export class SpiceClient {
         this._flightUrl,
         this._userAgent,
         this._flightTlsEnabled,
+        this._logger,
       );
     }
 
@@ -575,7 +583,7 @@ export class SpiceClient {
       );
     }
 
-    console.debug(configLines.join('\n'));
+    this._logger.debug(configLines.join('\n'));
   }
 
   /**
@@ -803,7 +811,9 @@ export class SpiceClient {
           }
         }
       } catch (parseError) {
-        console.warn(`[spice.js] Failed to parse JSON line: ${parseError}`);
+        this._logger.warn(
+          `[spice.js] Failed to parse JSON line: ${parseError}`,
+        );
       }
     }
 

src/grpc/client.node.ts

@@ -10,6 +10,7 @@ import * as protobuf from 'protobufjs';
 import { EventEmitter } from 'stream';
 import { FlightClient, FlightInfo, DescriptorType, Ticket } from '../flight';
 import { platform } from '../platform/node';
+import { Logger } from '../logger';
 // Note: Flight SQL prepared statements are not currently supported by the Spice server.
 // The server uses a custom protocol. For parameterized queries, we use client-side substitution.
 // This is secure for the supported use cases and matches the HTTP API behavior.
@@ -36,9 +37,9 @@ let grpcAvailable = false;
 /**
  * Downloads the Flight.proto file from the remote URL and keeps it in memory
  */
-async function downloadProtoFile(): Promise<string> {
+async function downloadProtoFile(logger?: Logger): Promise<string> {
   try {
-    console.log('[spice.js] Downloading Flight.proto from remote source...');
+    logger?.info('[spice.js] Downloading Flight.proto from remote source...');
     const response = await platform.fetch(PROTO_DOWNLOAD_URL, {
       method: 'GET',
       headers: {},
@@ -51,11 +52,11 @@ async function downloadProtoFile(): Promise<string> {
     }
 
     const content = await response.text();
-    console.log('[spice.js] Flight.proto downloaded successfully');
+    logger?.info('[spice.js] Flight.proto downloaded successfully');
 
     return content;
   } catch (error: any) {
-    console.warn(`[spice.js] Failed to download proto file: ${error.message}`);
+    logger?.warn(`[spice.js] Failed to download proto file: ${error.message}`);
     throw error;
   }
 }
@@ -64,15 +65,15 @@ async function downloadProtoFile(): Promise<string> {
  * Loads proto content from local file or downloads it
  * Returns the proto content as a string
  */
-async function loadProtoContent(): Promise<string | null> {
+async function loadProtoContent(logger?: Logger): Promise<string | null> {
   // Try local file first
   if (fs.existsSync(fullProtoPath)) {
     return fs.readFileSync(fullProtoPath, 'utf-8');
   }
 
   // Try to download
   try {
-    return await downloadProtoFile();
+    return await downloadProtoFile(logger);
   } catch (error) {
     return null;
   }
@@ -81,7 +82,7 @@ async function loadProtoContent(): Promise<string | null> {
 /**
  * Loads proto definition from content in memory using protobufjs
  */
-function loadProtoFromContent(content: string): any {
+function loadProtoFromContent(content: string, logger?: Logger): any {
   try {
     // Parse the proto content directly in memory using protobufjs
     const root = protobuf.parse(content, { keepCase: false }).root;
@@ -101,7 +102,7 @@ function loadProtoFromContent(content: string): any {
     const arrow = grpc.loadPackageDefinition(packageDefinition).arrow as any;
     return arrow.flight.protocol;
   } catch (error: any) {
-    console.warn(
+    logger?.info(
       '[spice.js] Failed to load proto from content:',
       error.message,
     );
@@ -137,17 +138,20 @@ export class GrpcFlightClient {
   private flightTlsEnabled: boolean;
   private initPromise: Promise<void>;
   private useGrpc: boolean = grpcAvailable;
+  private logger: Logger;
 
   constructor(
     apiKey: string | undefined,
     flightUrl: string,
     userAgent: string,
     flightTlsEnabled: boolean,
+    logger?: Logger,
   ) {
     this.apiKey = apiKey;
     this.flightUrl = flightUrl;
     this.userAgent = userAgent;
     this.flightTlsEnabled = flightTlsEnabled;
+    this.logger = logger || new Logger(true);
     this.initPromise = this.initialize();
   }
 
@@ -163,7 +167,7 @@ export class GrpcFlightClient {
     try {
       // Check if we already have proto content in memory
       if (!protoContent) {
-        protoContent = await loadProtoContent();
+        protoContent = await loadProtoContent(this.logger);
       }
 
       if (!protoContent) {
@@ -172,7 +176,7 @@ export class GrpcFlightClient {
       }
 
       // Load the proto from content
-      const proto = loadProtoFromContent(protoContent);
+      const proto = loadProtoFromContent(protoContent, this.logger);
 
       if (!proto?.FlightService) {
         throw new Error('Invalid proto file structure');
@@ -182,7 +186,7 @@ export class GrpcFlightClient {
       grpcAvailable = true;
       this.useGrpc = true;
     } catch (error: any) {
-      console.warn(
+      this.logger.warn(
         `[spice.js] gRPC initialization failed: ${error.message}. Using HTTP endpoint.`,
       );
       this.useGrpc = false;

src/interfaces.ts

@@ -11,6 +11,12 @@ export interface SpiceClientConfig {
    * @default false
    */
   flightOnly?: boolean;
+  /**
+   * Enable or disable logging output from the library.
+   * When false, all console output is suppressed.
+   * @default true
+   */
+  logging?: boolean;
 }
 
 export interface SchemaField {

src/logger.ts

@@ -0,0 +1,73 @@
+/**
+ * Simple logger with enable/disable support for spice.js
+ *
+ * When disabled, all logging methods are no-ops.
+ * When enabled, logs are forwarded to the appropriate console methods.
+ */
+export class Logger {
+  private readonly enabled: boolean;
+
+  constructor(enabled: boolean = true) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Log debug messages (uses console.debug)
+   */
+  debug(...args: unknown[]): void {
+    if (this.enabled) {
+      console.debug(...args);
+    }
+  }
+
+  /**
+   * Log informational messages (uses console.log)
+   */
+  info(...args: unknown[]): void {
+    if (this.enabled) {
+      console.log(...args);
+    }
+  }
+
+  /**
+   * Log warning messages (uses console.warn)
+   */
+  warn(...args: unknown[]): void {
+    if (this.enabled) {
+      console.warn(...args);
+    }
+  }
+
+  /**
+   * Log error messages (uses console.error)
+   */
+  error(...args: unknown[]): void {
+    if (this.enabled) {
+      console.error(...args);
+    }
+  }
+
+  /**
+   * Log messages (alias for info, uses console.log)
+   */
+  log(...args: unknown[]): void {
+    if (this.enabled) {
+      console.log(...args);
+    }
+  }
+
+  /**
+   * Check if logging is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+}
+
+/**
+ * Create a new logger instance
+ * @param enabled - Whether logging is enabled (default: true)
+ */
+export function createLogger(enabled: boolean = true): Logger {
+  return new Logger(enabled);
+}