@databricks/appkit 0.1.4 → 0.2.0

package/dist/stream/stream-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-manager.js","names":["streamOperation: StreamOperation","streamEntry: StreamEntry"],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { IAppResponse, StreamConfig } from \"shared\";\nimport { EventRingBuffer } from \"./buffers\";\nimport { streamDefaults } from \"./defaults\";\nimport { SSEWriter } from \"./sse-writer\";\nimport { StreamRegistry } from \"./stream-registry\";\nimport { SSEErrorCode, type StreamEntry, type StreamOperation } from \"./types\";\nimport { StreamValidator } from \"./validator\";\n\n// main entry point for Server-Sent events streaming\nexport class StreamManager {\n  private activeOperations: Set<StreamOperation>;\n  private streamRegistry: StreamRegistry;\n  private sseWriter: SSEWriter;\n  private maxEventSize: number;\n  private bufferTTL: number;\n\n  constructor(options?: StreamConfig) {\n    this.streamRegistry = new StreamRegistry(\n      options?.maxActiveStreams ?? streamDefaults.maxActiveStreams,\n    );\n    this.sseWriter = new SSEWriter();\n    this.maxEventSize = options?.maxEventSize ?? streamDefaults.maxEventSize;\n    this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;\n    this.activeOperations = new Set();\n  }\n\n  // main streaming method - handles new connection and reconnection\n  stream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const { streamId } = options || {};\n\n    // setup SSE headers\n    this.sseWriter.setupHeaders(res);\n\n    // handle reconnection\n    if (streamId && StreamValidator.validateStreamId(streamId)) {\n      const existingStream = this.streamRegistry.get(streamId);\n      // if stream exists, attach to it\n      if (existingStream) {\n        return this._attachToExistingStream(res, existingStream, options);\n      }\n    }\n\n    // if stream does not exist, create a new one\n    return this._createNewStream(res, handler, options);\n  }\n\n  // abort all active operations\n  abortAll(): void {\n    this.activeOperations.forEach((operation) => {\n      if (operation.heartbeat) clearInterval(operation.heartbeat);\n      operation.controller.abort(\"Server shutdown\");\n    });\n    this.activeOperations.clear();\n    this.streamRegistry.clear();\n  }\n\n  // get the number of active operations\n  getActiveCount(): number {\n    return this.activeOperations.size;\n  }\n\n  // attach to existing stream\n  private async _attachToExistingStream(\n    res: IAppResponse,\n    streamEntry: StreamEntry,\n    options?: StreamConfig,\n  ): Promise<void> {\n    // handle reconnection - replay missed events\n    const lastEventId = res.req?.headers[\"last-event-id\"];\n\n    if (StreamValidator.validateEventId(lastEventId)) {\n      // cast to string after validation\n      const validEventId = lastEventId as string;\n      if (streamEntry.eventBuffer.has(validEventId)) {\n        const missedEvents =\n          streamEntry.eventBuffer.getEventsSince(validEventId);\n        // broadcast missed events to client\n        for (const event of missedEvents) {\n          if (options?.userSignal?.aborted) break;\n          this.sseWriter.writeBufferedEvent(res, event);\n        }\n      } else {\n        // buffer overflow - send warning\n        this.sseWriter.writeBufferOverflowWarning(res, validEventId);\n      }\n    }\n\n    // add client to stream entry\n    streamEntry.clients.add(res);\n    streamEntry.lastAccess = Date.now();\n\n    // start heartbeat\n    const combinedSignal = this._combineSignals(\n      streamEntry.abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: streamEntry.abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      streamEntry.clients.delete(res);\n      this.activeOperations.delete(streamOperation);\n\n      // cleanup if stream is completed and no clients are connected\n      if (streamEntry.isCompleted && streamEntry.clients.size === 0) {\n        setTimeout(() => {\n          if (streamEntry.clients.size === 0) {\n            this.streamRegistry.remove(streamEntry.streamId);\n          }\n        }, this.bufferTTL);\n      }\n    });\n\n    // if stream is completed, close connection\n    if (streamEntry.isCompleted) {\n      res.end();\n      // cleanup operation\n      this.activeOperations.delete(streamOperation);\n      clearInterval(heartbeat);\n    }\n  }\n  private async _createNewStream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const streamId = options?.streamId ?? randomUUID();\n    const abortController = new AbortController();\n\n    // create event buffer\n    const eventBuffer = new EventRingBuffer(\n      options?.bufferSize ?? streamDefaults.bufferSize,\n    );\n\n    // setup signals and heartbeat\n    const combinedSignal = this._combineSignals(\n      abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // create stream entry\n    const streamEntry: StreamEntry = {\n      streamId,\n      generator: handler(combinedSignal),\n      eventBuffer,\n      clients: new Set([res]),\n      isCompleted: false,\n      lastAccess: Date.now(),\n      abortController,\n    };\n    this.streamRegistry.add(streamEntry);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      this.activeOperations.delete(streamOperation);\n      streamEntry.clients.delete(res);\n    });\n\n    await this._processGeneratorInBackground(streamEntry);\n\n    // cleanup\n    clearInterval(heartbeat);\n    this.activeOperations.delete(streamOperation);\n  }\n\n  private async _processGeneratorInBackground(\n    streamEntry: StreamEntry,\n  ): Promise<void> {\n    try {\n      // retrieve all events from generator\n      for await (const event of streamEntry.generator) {\n        if (streamEntry.abortController.signal.aborted) break;\n        const eventId = randomUUID();\n        const eventData = JSON.stringify(event);\n\n        // validate event size\n        if (eventData.length > this.maxEventSize) {\n          const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;\n          const errorCode = SSEErrorCode.INVALID_REQUEST;\n          // broadcast error to all connected clients\n          this._broadcastErrorToClients(\n            streamEntry,\n            eventId,\n            errorMsg,\n            errorCode,\n          );\n          continue;\n        }\n\n        // buffer event for reconnection\n        streamEntry.eventBuffer.add({\n          id: eventId,\n          type: event.type,\n          data: eventData,\n          timestamp: Date.now(),\n        });\n\n        // broadcast to all connected clients\n        this._broadcastEventsToClients(streamEntry, eventId, event);\n        streamEntry.lastAccess = Date.now();\n      }\n\n      streamEntry.isCompleted = true;\n\n      // close all clients\n      this._closeAllClients(streamEntry);\n\n      // cleanup if no clients are connected\n      this._cleanupStream(streamEntry);\n    } catch (error) {\n      const errorMsg =\n        error instanceof Error ? error.message : \"Internal server error\";\n      const errorEventId = randomUUID();\n      const errorCode = this._categorizeError(error);\n\n      // buffer error event\n      streamEntry.eventBuffer.add({\n        id: errorEventId,\n        type: \"error\",\n        data: JSON.stringify({ error: errorMsg, code: errorCode }),\n        timestamp: Date.now(),\n      });\n\n      // send error event to all connected clients\n      this._broadcastErrorToClients(\n        streamEntry,\n        errorEventId,\n        errorMsg,\n        errorCode,\n        true,\n      );\n      streamEntry.isCompleted = true;\n    }\n  }\n\n  private _combineSignals(\n    internalSignal?: AbortSignal,\n    userSignal?: AbortSignal,\n  ): AbortSignal {\n    if (!userSignal) return internalSignal || new AbortController().signal;\n\n    const signals = [internalSignal, userSignal].filter(\n      Boolean,\n    ) as AbortSignal[];\n    const controller = new AbortController();\n\n    signals.forEach((signal) => {\n      if (signal?.aborted) {\n        controller.abort(signal.reason);\n        return;\n      }\n\n      signal?.addEventListener(\n        \"abort\",\n        () => {\n          controller.abort(signal.reason);\n        },\n        { once: true },\n      );\n    });\n    return controller.signal;\n  }\n\n  // broadcast events to all connected clients\n  private _broadcastEventsToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    event: any,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeEvent(client, eventId, event);\n      }\n    }\n  }\n\n  // broadcast error to all connected clients\n  private _broadcastErrorToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    errorMessage: string,\n    errorCode: SSEErrorCode,\n    closeClients: boolean = false,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeError(client, eventId, errorMessage, errorCode);\n        if (closeClients) {\n          client.end();\n        }\n      }\n    }\n  }\n\n  // close all connected clients\n  private _closeAllClients(streamEntry: StreamEntry): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        client.end();\n      }\n    }\n  }\n\n  // cleanup stream if no clients are connected\n  private _cleanupStream(streamEntry: StreamEntry): void {\n    if (streamEntry.clients.size === 0) {\n      setTimeout(() => {\n        if (streamEntry.clients.size === 0) {\n          this.streamRegistry.remove(streamEntry.streamId);\n        }\n      }, this.bufferTTL);\n    }\n  }\n\n  private _categorizeError(error: unknown): SSEErrorCode {\n    if (error instanceof Error) {\n      const message = error.message.toLowerCase();\n      if (message.includes(\"timeout\") || message.includes(\"timed out\")) {\n        return SSEErrorCode.TIMEOUT;\n      }\n\n      if (message.includes(\"unavailable\") || message.includes(\"econnrefused\")) {\n        return SSEErrorCode.TEMPORARY_UNAVAILABLE;\n      }\n\n      if (error.name === \"AbortError\") {\n        return SSEErrorCode.STREAM_ABORTED;\n      }\n    }\n\n    return SSEErrorCode.INTERNAL_ERROR;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"stream-manager.js","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { context } from \"@opentelemetry/api\";\nimport type { IAppResponse, StreamConfig } from \"shared\";\nimport { EventRingBuffer } from \"./buffers\";\nimport { streamDefaults } from \"./defaults\";\nimport { SSEWriter } from \"./sse-writer\";\nimport { StreamRegistry } from \"./stream-registry\";\nimport { SSEErrorCode, type StreamEntry, type StreamOperation } from \"./types\";\nimport { StreamValidator } from \"./validator\";\n\n// main entry point for Server-Sent events streaming\nexport class StreamManager {\n  private activeOperations: Set<StreamOperation>;\n  private streamRegistry: StreamRegistry;\n  private sseWriter: SSEWriter;\n  private maxEventSize: number;\n  private bufferTTL: number;\n\n  constructor(options?: StreamConfig) {\n    this.streamRegistry = new StreamRegistry(\n      options?.maxActiveStreams ?? streamDefaults.maxActiveStreams,\n    );\n    this.sseWriter = new SSEWriter();\n    this.maxEventSize = options?.maxEventSize ?? streamDefaults.maxEventSize;\n    this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;\n    this.activeOperations = new Set();\n  }\n\n  // main streaming method - handles new connection and reconnection\n  async stream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const { streamId } = options || {};\n\n    // check if response is already closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    // setup SSE headers\n    this.sseWriter.setupHeaders(res);\n\n    // handle reconnection\n    if (streamId && StreamValidator.validateStreamId(streamId)) {\n      const existingStream = this.streamRegistry.get(streamId);\n      // if stream exists, attach to it\n      if (existingStream) {\n        return this._attachToExistingStream(res, existingStream, options);\n      }\n    }\n\n    // if stream does not exist, create a new one\n    return this._createNewStream(res, handler, options);\n  }\n\n  // abort all active operations\n  abortAll(): void {\n    this.activeOperations.forEach((operation) => {\n      if (operation.heartbeat) clearInterval(operation.heartbeat);\n      operation.controller.abort(\"Server shutdown\");\n    });\n    this.activeOperations.clear();\n    this.streamRegistry.clear();\n  }\n\n  // get the number of active operations\n  getActiveCount(): number {\n    return this.activeOperations.size;\n  }\n\n  // attach to existing stream\n  private async _attachToExistingStream(\n    res: IAppResponse,\n    streamEntry: StreamEntry,\n    options?: StreamConfig,\n  ): Promise<void> {\n    // handle reconnection - replay missed events\n    const lastEventId = res.req?.headers[\"last-event-id\"];\n\n    if (StreamValidator.validateEventId(lastEventId)) {\n      // cast to string after validation\n      const validEventId = lastEventId as string;\n      if (streamEntry.eventBuffer.has(validEventId)) {\n        const missedEvents =\n          streamEntry.eventBuffer.getEventsSince(validEventId);\n        // broadcast missed events to client\n        for (const event of missedEvents) {\n          if (options?.userSignal?.aborted) break;\n          this.sseWriter.writeBufferedEvent(res, event);\n        }\n      } else {\n        // buffer overflow - send warning\n        this.sseWriter.writeBufferOverflowWarning(res, validEventId);\n      }\n    }\n\n    // add client to stream entry\n    streamEntry.clients.add(res);\n    streamEntry.lastAccess = Date.now();\n\n    // start heartbeat\n    const combinedSignal = this._combineSignals(\n      streamEntry.abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: streamEntry.abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      streamEntry.clients.delete(res);\n      this.activeOperations.delete(streamOperation);\n\n      // cleanup if stream is completed and no clients are connected\n      if (streamEntry.isCompleted && streamEntry.clients.size === 0) {\n        setTimeout(() => {\n          if (streamEntry.clients.size === 0) {\n            this.streamRegistry.remove(streamEntry.streamId);\n          }\n        }, this.bufferTTL);\n      }\n    });\n\n    // if stream is completed, close connection\n    if (streamEntry.isCompleted) {\n      res.end();\n      // cleanup operation\n      this.activeOperations.delete(streamOperation);\n      clearInterval(heartbeat);\n    }\n  }\n  private async _createNewStream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const streamId = options?.streamId ?? randomUUID();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    const abortController = new AbortController();\n\n    // create event buffer\n    const eventBuffer = new EventRingBuffer(\n      options?.bufferSize ?? streamDefaults.bufferSize,\n    );\n\n    // setup signals and heartbeat\n    const combinedSignal = this._combineSignals(\n      abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // capture the current trace context at stream creation time\n    const traceContext = context.active();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      clearInterval(heartbeat);\n      return;\n    }\n\n    // create stream entry\n    const streamEntry: StreamEntry = {\n      streamId,\n      generator: handler(combinedSignal),\n      eventBuffer,\n      clients: new Set([res]),\n      isCompleted: false,\n      lastAccess: Date.now(),\n      abortController,\n      traceContext,\n    };\n    this.streamRegistry.add(streamEntry);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      this.activeOperations.delete(streamOperation);\n      streamEntry.clients.delete(res);\n    });\n\n    await this._processGeneratorInBackground(streamEntry);\n\n    // cleanup\n    clearInterval(heartbeat);\n    this.activeOperations.delete(streamOperation);\n  }\n\n  private async _processGeneratorInBackground(\n    streamEntry: StreamEntry,\n  ): Promise<void> {\n    // run the entire generator processing within the captured trace context\n    return context.with(streamEntry.traceContext, async () => {\n      try {\n        // retrieve all events from generator\n        for await (const event of streamEntry.generator) {\n          if (streamEntry.abortController.signal.aborted) break;\n          const eventId = randomUUID();\n          const eventData = JSON.stringify(event);\n\n          // validate event size\n          if (eventData.length > this.maxEventSize) {\n            const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;\n            const errorCode = SSEErrorCode.INVALID_REQUEST;\n            // broadcast error to all connected clients\n            this._broadcastErrorToClients(\n              streamEntry,\n              eventId,\n              errorMsg,\n              errorCode,\n            );\n            continue;\n          }\n\n          // buffer event for reconnection\n          streamEntry.eventBuffer.add({\n            id: eventId,\n            type: event.type,\n            data: eventData,\n            timestamp: Date.now(),\n          });\n\n          // broadcast to all connected clients\n          this._broadcastEventsToClients(streamEntry, eventId, event);\n          streamEntry.lastAccess = Date.now();\n        }\n\n        streamEntry.isCompleted = true;\n\n        // close all clients\n        this._closeAllClients(streamEntry);\n\n        // cleanup if no clients are connected\n        this._cleanupStream(streamEntry);\n      } catch (error) {\n        const errorMsg =\n          error instanceof Error ? error.message : \"Internal server error\";\n        const errorEventId = randomUUID();\n        const errorCode = this._categorizeError(error);\n\n        // buffer error event\n        streamEntry.eventBuffer.add({\n          id: errorEventId,\n          type: \"error\",\n          data: JSON.stringify({ error: errorMsg, code: errorCode }),\n          timestamp: Date.now(),\n        });\n\n        // send error event to all connected clients\n        this._broadcastErrorToClients(\n          streamEntry,\n          errorEventId,\n          errorMsg,\n          errorCode,\n          true,\n        );\n        streamEntry.isCompleted = true;\n      }\n    });\n  }\n\n  private _combineSignals(\n    internalSignal?: AbortSignal,\n    userSignal?: AbortSignal,\n  ): AbortSignal {\n    if (!userSignal) return internalSignal || new AbortController().signal;\n\n    const signals = [internalSignal, userSignal].filter(\n      Boolean,\n    ) as AbortSignal[];\n    const controller = new AbortController();\n\n    signals.forEach((signal) => {\n      if (signal?.aborted) {\n        controller.abort(signal.reason);\n        return;\n      }\n\n      signal?.addEventListener(\n        \"abort\",\n        () => {\n          controller.abort(signal.reason);\n        },\n        { once: true },\n      );\n    });\n    return controller.signal;\n  }\n\n  // broadcast events to all connected clients\n  private _broadcastEventsToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    event: any,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeEvent(client, eventId, event);\n      }\n    }\n  }\n\n  // broadcast error to all connected clients\n  private _broadcastErrorToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    errorMessage: string,\n    errorCode: SSEErrorCode,\n    closeClients: boolean = false,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeError(client, eventId, errorMessage, errorCode);\n        if (closeClients) {\n          client.end();\n        }\n      }\n    }\n  }\n\n  // close all connected clients\n  private _closeAllClients(streamEntry: StreamEntry): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        client.end();\n      }\n    }\n  }\n\n  // cleanup stream if no clients are connected\n  private _cleanupStream(streamEntry: StreamEntry): void {\n    if (streamEntry.clients.size === 0) {\n      setTimeout(() => {\n        if (streamEntry.clients.size === 0) {\n          this.streamRegistry.remove(streamEntry.streamId);\n        }\n      }, this.bufferTTL);\n    }\n  }\n\n  private _categorizeError(error: unknown): SSEErrorCode {\n    if (error instanceof Error) {\n      const message = error.message.toLowerCase();\n      if (message.includes(\"timeout\") || message.includes(\"timed out\")) {\n        return SSEErrorCode.TIMEOUT;\n      }\n\n      if (message.includes(\"unavailable\") || message.includes(\"econnrefused\")) {\n        return SSEErrorCode.TEMPORARY_UNAVAILABLE;\n      }\n\n      if (error.name === \"AbortError\") {\n        return SSEErrorCode.STREAM_ABORTED;\n      }\n    }\n\n    return SSEErrorCode.INTERNAL_ERROR;\n  }\n}\n"],"mappings":"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"}

package/dist/stream/stream-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-registry.js","names":["oldestStream: StreamEntry | null"],"sources":["../../src/stream/stream-registry.ts"],"sourcesContent":["import { RingBuffer } from \"./buffers\";\nimport { SSEErrorCode, type StreamEntry } from \"./types\";\n\nexport class StreamRegistry {\n  private streams: RingBuffer<StreamEntry>;\n\n  constructor(maxActiveStreams: number) {\n    this.streams = new RingBuffer<StreamEntry>(\n      maxActiveStreams,\n      (entry) => entry.streamId,\n    );\n  }\n\n  // add a stream to the registry\n  add(entry: StreamEntry): void {\n    // enforce hard cap\n    if (this.streams.getSize() >= this.streams.capacity) {\n      this._evictOldestStream(entry.streamId);\n    }\n\n    this.streams.add(entry);\n  }\n\n  // get a stream from the registry\n  get(streamId: string): StreamEntry | null {\n    return this.streams.get(streamId);\n  }\n\n  // check if a stream exists in the registry\n  has(streamId: string): boolean {\n    return this.streams.has(streamId);\n  }\n\n  // remove a stream from the registry\n  remove(streamId: string): void {\n    this.streams.remove(streamId);\n  }\n\n  // get the number of streams in the registry\n  size(): number {\n    return this.streams.getSize();\n  }\n\n  clear(): void {\n    const allStreams = this.streams.getAll();\n\n    for (const stream of allStreams) {\n      stream.abortController.abort(\"Server shutdown\");\n    }\n\n    this.streams.clear();\n  }\n\n  // evict the oldest stream from the registry\n  private _evictOldestStream(excludeStreamId: string): void {\n    const allStreams = this.streams.getAll();\n    let oldestStream: StreamEntry | null = null;\n    let oldestAccess = Infinity;\n\n    // find the least recently accessed stream\n    for (const stream of allStreams) {\n      if (\n        stream.streamId !== excludeStreamId &&\n        stream.lastAccess < oldestAccess\n      ) {\n        oldestStream = stream;\n        oldestAccess = stream.lastAccess;\n      }\n    }\n\n    // abort the oldest stream\n    if (oldestStream) {\n      // broadcast stream eviction error to all clients\n      for (const client of oldestStream.clients) {\n        if (!client.writableEnded) {\n          try {\n            client.write(`event: error\\n`);\n            client.write(\n              `data: ${JSON.stringify({ error: \"Stream evicted\", code: SSEErrorCode.STREAM_EVICTED })}\\n\\n`,\n            );\n          } catch (_error) {\n            // ignore\n          }\n        }\n      }\n      oldestStream.abortController.abort(\"Stream evicted\");\n      this.streams.remove(oldestStream.streamId);\n    }\n  }\n}\n"],"mappings":";;;;AAGA,IAAa,iBAAb,MAA4B;CAG1B,YAAY,kBAA0B;AACpC,OAAK,UAAU,IAAI,WACjB,mBACC,UAAU,MAAM,SAClB;;CAIH,IAAI,OAA0B;AAE5B,MAAI,KAAK,QAAQ,SAAS,IAAI,KAAK,QAAQ,SACzC,MAAK,mBAAmB,MAAM,SAAS;AAGzC,OAAK,QAAQ,IAAI,MAAM;;CAIzB,IAAI,UAAsC;AACxC,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAInC,IAAI,UAA2B;AAC7B,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAInC,OAAO,UAAwB;AAC7B,OAAK,QAAQ,OAAO,SAAS;;CAI/B,OAAe;AACb,SAAO,KAAK,QAAQ,SAAS;;CAG/B,QAAc;EACZ,MAAM,aAAa,KAAK,QAAQ,QAAQ;AAExC,OAAK,MAAM,UAAU,WACnB,QAAO,gBAAgB,MAAM,kBAAkB;AAGjD,OAAK,QAAQ,OAAO;;CAItB,AAAQ,mBAAmB,iBAA+B;EACxD,MAAM,aAAa,KAAK,QAAQ,QAAQ;EACxC,IAAIA,eAAmC;EACvC,IAAI,eAAe;AAGnB,OAAK,MAAM,UAAU,WACnB,KACE,OAAO,aAAa,mBACpB,OAAO,aAAa,cACpB;AACA,kBAAe;AACf,kBAAe,OAAO;;AAK1B,MAAI,cAAc;AAEhB,QAAK,MAAM,UAAU,aAAa,QAChC,KAAI,CAAC,OAAO,cACV,KAAI;AACF,WAAO,MAAM,iBAAiB;AAC9B,WAAO,MACL,SAAS,KAAK,UAAU;KAAE,OAAO;KAAkB,MAAM,aAAa;KAAgB,CAAC,CAAC,MACzF;YACM,QAAQ;AAKrB,gBAAa,gBAAgB,MAAM,iBAAiB;AACpD,QAAK,QAAQ,OAAO,aAAa,SAAS"}
+{"version":3,"file":"stream-registry.js","names":[],"sources":["../../src/stream/stream-registry.ts"],"sourcesContent":["import { RingBuffer } from \"./buffers\";\nimport { SSEErrorCode, type StreamEntry } from \"./types\";\n\nexport class StreamRegistry {\n  private streams: RingBuffer<StreamEntry>;\n\n  constructor(maxActiveStreams: number) {\n    this.streams = new RingBuffer<StreamEntry>(\n      maxActiveStreams,\n      (entry) => entry.streamId,\n    );\n  }\n\n  // add a stream to the registry\n  add(entry: StreamEntry): void {\n    // enforce hard cap\n    if (this.streams.getSize() >= this.streams.capacity) {\n      this._evictOldestStream(entry.streamId);\n    }\n\n    this.streams.add(entry);\n  }\n\n  // get a stream from the registry\n  get(streamId: string): StreamEntry | null {\n    return this.streams.get(streamId);\n  }\n\n  // check if a stream exists in the registry\n  has(streamId: string): boolean {\n    return this.streams.has(streamId);\n  }\n\n  // remove a stream from the registry\n  remove(streamId: string): void {\n    this.streams.remove(streamId);\n  }\n\n  // get the number of streams in the registry\n  size(): number {\n    return this.streams.getSize();\n  }\n\n  clear(): void {\n    const allStreams = this.streams.getAll();\n\n    for (const stream of allStreams) {\n      stream.abortController.abort(\"Server shutdown\");\n    }\n\n    this.streams.clear();\n  }\n\n  // evict the oldest stream from the registry\n  private _evictOldestStream(excludeStreamId: string): void {\n    const allStreams = this.streams.getAll();\n    let oldestStream: StreamEntry | null = null;\n    let oldestAccess = Infinity;\n\n    // find the least recently accessed stream\n    for (const stream of allStreams) {\n      if (\n        stream.streamId !== excludeStreamId &&\n        stream.lastAccess < oldestAccess\n      ) {\n        oldestStream = stream;\n        oldestAccess = stream.lastAccess;\n      }\n    }\n\n    // abort the oldest stream\n    if (oldestStream) {\n      // broadcast stream eviction error to all clients\n      for (const client of oldestStream.clients) {\n        if (!client.writableEnded) {\n          try {\n            client.write(`event: error\\n`);\n            client.write(\n              `data: ${JSON.stringify({ error: \"Stream evicted\", code: SSEErrorCode.STREAM_EVICTED })}\\n\\n`,\n            );\n          } catch (_error) {\n            // ignore\n          }\n        }\n      }\n      oldestStream.abortController.abort(\"Stream evicted\");\n      this.streams.remove(oldestStream.streamId);\n    }\n  }\n}\n"],"mappings":";;;;AAGA,IAAa,iBAAb,MAA4B;CAG1B,YAAY,kBAA0B;AACpC,OAAK,UAAU,IAAI,WACjB,mBACC,UAAU,MAAM,SAClB;;CAIH,IAAI,OAA0B;AAE5B,MAAI,KAAK,QAAQ,SAAS,IAAI,KAAK,QAAQ,SACzC,MAAK,mBAAmB,MAAM,SAAS;AAGzC,OAAK,QAAQ,IAAI,MAAM;;CAIzB,IAAI,UAAsC;AACxC,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAInC,IAAI,UAA2B;AAC7B,SAAO,KAAK,QAAQ,IAAI,SAAS;;CAInC,OAAO,UAAwB;AAC7B,OAAK,QAAQ,OAAO,SAAS;;CAI/B,OAAe;AACb,SAAO,KAAK,QAAQ,SAAS;;CAG/B,QAAc;EACZ,MAAM,aAAa,KAAK,QAAQ,QAAQ;AAExC,OAAK,MAAM,UAAU,WACnB,QAAO,gBAAgB,MAAM,kBAAkB;AAGjD,OAAK,QAAQ,OAAO;;CAItB,AAAQ,mBAAmB,iBAA+B;EACxD,MAAM,aAAa,KAAK,QAAQ,QAAQ;EACxC,IAAI,eAAmC;EACvC,IAAI,eAAe;AAGnB,OAAK,MAAM,UAAU,WACnB,KACE,OAAO,aAAa,mBACpB,OAAO,aAAa,cACpB;AACA,kBAAe;AACf,kBAAe,OAAO;;AAK1B,MAAI,cAAc;AAEhB,QAAK,MAAM,UAAU,aAAa,QAChC,KAAI,CAAC,OAAO,cACV,KAAI;AACF,WAAO,MAAM,iBAAiB;AAC9B,WAAO,MACL,SAAS,KAAK,UAAU;KAAE,OAAO;KAAkB,MAAM,aAAa;KAAgB,CAAC,CAAC,MACzF;YACM,QAAQ;AAKrB,gBAAa,gBAAgB,MAAM,iBAAiB;AACpD,QAAK,QAAQ,OAAO,aAAa,SAAS"}

package/dist/stream/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n}\n\nexport interface BufferEntry {\n  buffer: EventRingBuffer;\n  lastAccess: number;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAGA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CACjB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n}\n\nexport interface BufferEntry {\n  buffer: EventRingBuffer;\n  lastAccess: number;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CACjB"}

package/dist/telemetry/index.d.ts

@@ -1,4 +1,4 @@
 import { ITelemetry, InstrumentConfig, TelemetryConfig } from "./types.js";
 import { Counter, Histogram, Span as Span$1, SpanStatusCode } from "@opentelemetry/api";
-import { SeverityNumber } from "@opentelemetry/api-logs";
-export { type Counter, type Histogram, SeverityNumber, type Span$1 as Span, SpanStatusCode };
+import { SeverityNumber as SeverityNumber$1 } from "@opentelemetry/api-logs";
+export { type Counter, type Histogram, SeverityNumber$1 as SeverityNumber, type Span$1 as Span, SpanStatusCode };

package/dist/telemetry/index.js

@@ -3,6 +3,6 @@ import { instrumentations } from "./instrumentations.js";
 import { TelemetryProvider } from "./telemetry-provider.js";
 import { TelemetryManager } from "./telemetry-manager.js";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
-import { SeverityNumber } from "@opentelemetry/api-logs";
+import { SeverityNumber as SeverityNumber$1 } from "@opentelemetry/api-logs";
 
-export { SeverityNumber, SpanKind, SpanStatusCode };
+export { SeverityNumber$1 as SeverityNumber, SpanKind, SpanStatusCode };

package/dist/telemetry/instrumentations.js

@@ -1,3 +1,4 @@
+import { shouldIgnoreRequest } from "../utils/path-exclusions.js";
 import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
 import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
 
@@ -10,17 +11,20 @@ import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
 * the recommended approach is to register them once in a corresponding plugin constructor.
 */
 const instrumentations = {
-	http: new HttpInstrumentation({ applyCustomAttributesOnSpan(span, request) {
-		let spanName = null;
-		if (request.route) {
-			const fullPath = (request.baseUrl || "") + (request.url?.split("?")[0] || "");
-			if (fullPath) spanName = `${request.method} ${fullPath}`;
-		} else if (request.url) {
-			const path = request.url.split("?")[0];
-			spanName = `${request.method} ${path}`;
+	http: new HttpInstrumentation({
+		ignoreIncomingRequestHook: shouldIgnoreRequest,
+		applyCustomAttributesOnSpan(span, request) {
+			let spanName = null;
+			if (request.route) {
+				const fullPath = (request.baseUrl || "") + (request.url?.split("?")[0] || "");
+				if (fullPath) spanName = `${request.method} ${fullPath}`;
+			} else if (request.url) {
+				const path = request.url.split("?")[0];
+				spanName = `${request.method} ${path}`;
+			}
+			if (spanName) span.updateName(spanName);
 		}
-		if (spanName) span.updateName(spanName);
-	} }),
+	}),
 	express: new ExpressInstrumentation({ requestHook: (span, info) => {
 		const req = info.request;
 		if (info.layerType === "request_handler" && req.route) {

package/dist/telemetry/instrumentations.js.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentations.js","names":["instrumentations: Record<string, Instrumentation>","spanName: string | null"],"sources":["../../src/telemetry/instrumentations.ts"],"sourcesContent":["import { ExpressInstrumentation } from \"@opentelemetry/instrumentation-express\";\nimport { HttpInstrumentation } from \"@opentelemetry/instrumentation-http\";\nimport type { Instrumentation } from \"@opentelemetry/instrumentation\";\n\n/**\n * Registry of pre-configured instrumentations for common use cases.\n * These can be selectively registered by plugins that need them.\n *\n * While instrumentations are generally safe to re-register,\n * the recommended approach is to register them once in a corresponding plugin constructor.\n */\nexport const instrumentations: Record<string, Instrumentation> = {\n  http: new HttpInstrumentation({\n    applyCustomAttributesOnSpan(span: any, request: any) {\n      let spanName: string | null = null;\n\n      if (request.route) {\n        const baseUrl = request.baseUrl || \"\";\n        const url = request.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          spanName = `${request.method} ${fullPath}`;\n        }\n      } else if (request.url) {\n        // No Express route (e.g., static assets) - use the raw URL path\n        // Remove query string for cleaner trace names\n        const path = request.url.split(\"?\")[0];\n        spanName = `${request.method} ${path}`;\n      }\n\n      if (spanName) {\n        span.updateName(spanName);\n      }\n    },\n  }),\n  express: new ExpressInstrumentation({\n    requestHook: (span: any, info: any) => {\n      const req = info.request;\n\n      // Only update span name for route handlers (layerType: request_handler)\n      // This ensures we're not renaming middleware spans\n      if (info.layerType === \"request_handler\" && req.route) {\n        // Combine baseUrl with url to get full path with actual parameter values\n        // e.g., baseUrl=\"/api/analytics\" + url=\"/query/spend_data\" = \"/api/analytics/query/spend_data\"\n        const baseUrl = req.baseUrl || \"\";\n        const url = req.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          const spanName = `${req.method} ${fullPath}`;\n          span.updateName(spanName);\n        }\n      }\n    },\n  }),\n};\n"],"mappings":";;;;;;;;;;;AAWA,MAAaA,mBAAoD;CAC/D,MAAM,IAAI,oBAAoB,EAC5B,4BAA4B,MAAW,SAAc;EACnD,IAAIC,WAA0B;AAE9B,MAAI,QAAQ,OAAO;GAGjB,MAAM,YAFU,QAAQ,WAAW,OACvB,QAAQ,KAAK,MAAM,IAAI,CAAC,MAAM;AAE1C,OAAI,SACF,YAAW,GAAG,QAAQ,OAAO,GAAG;aAEzB,QAAQ,KAAK;GAGtB,MAAM,OAAO,QAAQ,IAAI,MAAM,IAAI,CAAC;AACpC,cAAW,GAAG,QAAQ,OAAO,GAAG;;AAGlC,MAAI,SACF,MAAK,WAAW,SAAS;IAG9B,CAAC;CACF,SAAS,IAAI,uBAAuB,EAClC,cAAc,MAAW,SAAc;EACrC,MAAM,MAAM,KAAK;AAIjB,MAAI,KAAK,cAAc,qBAAqB,IAAI,OAAO;GAKrD,MAAM,YAFU,IAAI,WAAW,OACnB,IAAI,KAAK,MAAM,IAAI,CAAC,MAAM;AAEtC,OAAI,UAAU;IACZ,MAAM,WAAW,GAAG,IAAI,OAAO,GAAG;AAClC,SAAK,WAAW,SAAS;;;IAIhC,CAAC;CACH"}
+{"version":3,"file":"instrumentations.js","names":[],"sources":["../../src/telemetry/instrumentations.ts"],"sourcesContent":["import type { Instrumentation } from \"@opentelemetry/instrumentation\";\nimport { ExpressInstrumentation } from \"@opentelemetry/instrumentation-express\";\nimport { HttpInstrumentation } from \"@opentelemetry/instrumentation-http\";\nimport { shouldIgnoreRequest } from \"../utils/path-exclusions\";\n\n/**\n * Registry of pre-configured instrumentations for common use cases.\n * These can be selectively registered by plugins that need them.\n *\n * While instrumentations are generally safe to re-register,\n * the recommended approach is to register them once in a corresponding plugin constructor.\n */\nexport const instrumentations: Record<string, Instrumentation> = {\n  http: new HttpInstrumentation({\n    // Filter out requests before creating spans - this is the most efficient approach\n    ignoreIncomingRequestHook: shouldIgnoreRequest,\n\n    applyCustomAttributesOnSpan(span: any, request: any) {\n      let spanName: string | null = null;\n\n      if (request.route) {\n        const baseUrl = request.baseUrl || \"\";\n        const url = request.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          spanName = `${request.method} ${fullPath}`;\n        }\n      } else if (request.url) {\n        // No Express route (e.g., static assets) - use the raw URL path\n        // Remove query string for cleaner trace names\n        const path = request.url.split(\"?\")[0];\n        spanName = `${request.method} ${path}`;\n      }\n\n      if (spanName) {\n        span.updateName(spanName);\n      }\n    },\n  }),\n  express: new ExpressInstrumentation({\n    requestHook: (span: any, info: any) => {\n      const req = info.request;\n\n      // Only update span name for route handlers (layerType: request_handler)\n      // This ensures we're not renaming middleware spans\n      if (info.layerType === \"request_handler\" && req.route) {\n        // Combine baseUrl with url to get full path with actual parameter values\n        // e.g., baseUrl=\"/api/analytics\" + url=\"/query/spend_data\" = \"/api/analytics/query/spend_data\"\n        const baseUrl = req.baseUrl || \"\";\n        const url = req.url?.split(\"?\")[0] || \"\";\n        const fullPath = baseUrl + url;\n        if (fullPath) {\n          const spanName = `${req.method} ${fullPath}`;\n          span.updateName(spanName);\n        }\n      }\n    },\n  }),\n};\n"],"mappings":";;;;;;;;;;;;AAYA,MAAa,mBAAoD;CAC/D,MAAM,IAAI,oBAAoB;EAE5B,2BAA2B;EAE3B,4BAA4B,MAAW,SAAc;GACnD,IAAI,WAA0B;AAE9B,OAAI,QAAQ,OAAO;IAGjB,MAAM,YAFU,QAAQ,WAAW,OACvB,QAAQ,KAAK,MAAM,IAAI,CAAC,MAAM;AAE1C,QAAI,SACF,YAAW,GAAG,QAAQ,OAAO,GAAG;cAEzB,QAAQ,KAAK;IAGtB,MAAM,OAAO,QAAQ,IAAI,MAAM,IAAI,CAAC;AACpC,eAAW,GAAG,QAAQ,OAAO,GAAG;;AAGlC,OAAI,SACF,MAAK,WAAW,SAAS;;EAG9B,CAAC;CACF,SAAS,IAAI,uBAAuB,EAClC,cAAc,MAAW,SAAc;EACrC,MAAM,MAAM,KAAK;AAIjB,MAAI,KAAK,cAAc,qBAAqB,IAAI,OAAO;GAKrD,MAAM,YAFU,IAAI,WAAW,OACnB,IAAI,KAAK,MAAM,IAAI,CAAC,MAAM;AAEtC,OAAI,UAAU;IACZ,MAAM,WAAW,GAAG,IAAI,OAAO,GAAG;AAClC,SAAK,WAAW,SAAS;;;IAIhC,CAAC;CACH"}

package/dist/telemetry/telemetry-manager.js

@@ -1,4 +1,6 @@
+import { createLogger } from "../logging/logger.js";
 import { TelemetryProvider } from "./telemetry-provider.js";
+import { AppKitSampler } from "./trace-sampler.js";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
@@ -7,11 +9,11 @@ import { registerInstrumentations } from "@opentelemetry/instrumentation";
 import { detectResources, envDetector, hostDetector, processDetector, resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { AlwaysOnSampler } from "@opentelemetry/sdk-trace-base";
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 
 //#region src/telemetry/telemetry-manager.ts
+const logger = createLogger("telemetry");
 var TelemetryManager = class TelemetryManager {
 	static {
 		this.DEFAULT_EXPORT_INTERVAL_MS = 1e4;
@@ -44,7 +46,7 @@ var TelemetryManager = class TelemetryManager {
 			this.sdk = new NodeSDK({
 				resource: this.createResource(config),
 				autoDetectResources: false,
-				sampler: new AlwaysOnSampler(),
+				sampler: new AppKitSampler(),
 				traceExporter: new OTLPTraceExporter({ headers: config.headers }),
 				metricReaders: [new PeriodicExportingMetricReader({
 					exporter: new OTLPMetricExporter({ headers: config.headers }),
@@ -55,9 +57,9 @@ var TelemetryManager = class TelemetryManager {
 			});
 			this.sdk.start();
 			this.registerShutdown();
-			console.log("[Telemetry] Initialized successfully");
+			logger.debug("Initialized successfully");
 		} catch (error) {
-			console.error("[Telemetry] Failed to initialize:", error);
+			logger.error("Failed to initialize: %O", error);
 		}
 	}
 	/**
@@ -103,7 +105,7 @@ var TelemetryManager = class TelemetryManager {
 			await this.sdk.shutdown();
 			this.sdk = void 0;
 		} catch (error) {
-			console.error("[Telemetry] Error shutting down:", error);
+			logger.error("Error shutting down: %O", error);
 		}
 	}
 };

package/dist/telemetry/telemetry-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-manager.js","names":[],"sources":["../../src/telemetry/telemetry-manager.ts"],"sourcesContent":["import type { TelemetryOptions } from \"shared\";\nimport { getNodeAutoInstrumentations } from \"@opentelemetry/auto-instrumentations-node\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-proto\";\nimport { OTLPMetricExporter } from \"@opentelemetry/exporter-metrics-otlp-proto\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-proto\";\nimport {\n  type Instrumentation,\n  registerInstrumentations as otelRegisterInstrumentations,\n} from \"@opentelemetry/instrumentation\";\nimport {\n  detectResources,\n  envDetector,\n  hostDetector,\n  processDetector,\n  type Resource,\n  resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { BatchLogRecordProcessor } from \"@opentelemetry/sdk-logs\";\nimport { PeriodicExportingMetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { AlwaysOnSampler } from \"@opentelemetry/sdk-trace-base\";\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from \"@opentelemetry/semantic-conventions\";\nimport { TelemetryProvider } from \"./telemetry-provider\";\nimport type { TelemetryConfig } from \"./types\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\n\nexport class TelemetryManager {\n  private static readonly DEFAULT_EXPORT_INTERVAL_MS = 10000;\n  private static readonly DEFAULT_FALLBACK_APP_NAME = \"databricks-app\";\n\n  private static instance?: TelemetryManager;\n  private sdk?: NodeSDK;\n\n  /**\n   * Create a scoped telemetry provider for a specific plugin.\n   * The plugin's name will be used as the default tracer/meter name.\n   * @param pluginName - The name of the plugin to create scoped telemetry for\n   * @param telemetryConfig - The telemetry configuration for the plugin\n   * @returns A scoped telemetry instance for the plugin\n   */\n  static getProvider(\n    pluginName: string,\n    telemetryConfig?: TelemetryOptions,\n  ): TelemetryProvider {\n    const globalManager = TelemetryManager.getInstance();\n    return new TelemetryProvider(pluginName, globalManager, telemetryConfig);\n  }\n\n  private constructor() {}\n\n  static getInstance(): TelemetryManager {\n    if (!TelemetryManager.instance) {\n      TelemetryManager.instance = new TelemetryManager();\n    }\n    return TelemetryManager.instance;\n  }\n\n  static initialize(config: Partial<TelemetryConfig> = {}): void {\n    const instance = TelemetryManager.getInstance();\n    instance._initialize(config);\n  }\n\n  private _initialize(config: Partial<TelemetryConfig>): void {\n    if (this.sdk) return;\n\n    if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {\n      return;\n    }\n\n    try {\n      this.sdk = new NodeSDK({\n        resource: this.createResource(config),\n        autoDetectResources: false,\n        sampler: new AlwaysOnSampler(),\n        traceExporter: new OTLPTraceExporter({ headers: config.headers }),\n        metricReaders: [\n          new PeriodicExportingMetricReader({\n            exporter: new OTLPMetricExporter({ headers: config.headers }),\n            exportIntervalMillis:\n              config.exportIntervalMs ||\n              TelemetryManager.DEFAULT_EXPORT_INTERVAL_MS,\n          }),\n        ],\n        logRecordProcessors: [\n          new BatchLogRecordProcessor(\n            new OTLPLogExporter({ headers: config.headers }),\n          ),\n        ],\n        instrumentations: this.getDefaultInstrumentations(),\n      });\n\n      this.sdk.start();\n      this.registerShutdown();\n      console.log(\"[Telemetry] Initialized successfully\");\n    } catch (error) {\n      console.error(\"[Telemetry] Failed to initialize:\", error);\n    }\n  }\n\n  /**\n   * Register OpenTelemetry instrumentations.\n   * Can be called at any time, but recommended to call in plugin constructor.\n   * @param instrumentations - Array of OpenTelemetry instrumentations to register\n   */\n  registerInstrumentations(instrumentations: Instrumentation[]): void {\n    otelRegisterInstrumentations({\n      //  global providers set by NodeSDK.start()\n      instrumentations,\n    });\n  }\n\n  private createResource(config: Partial<TelemetryConfig>): Resource {\n    const serviceName =\n      config.serviceName ||\n      process.env.OTEL_SERVICE_NAME ||\n      process.env.DATABRICKS_APP_NAME ||\n      TelemetryManager.DEFAULT_FALLBACK_APP_NAME;\n    const initialResource = resourceFromAttributes({\n      [ATTR_SERVICE_NAME]: serviceName,\n      [ATTR_SERVICE_VERSION]: config.serviceVersion ?? undefined,\n    });\n    const detectedResource = detectResources({\n      detectors: [envDetector, hostDetector, processDetector],\n    });\n    return initialResource.merge(detectedResource);\n  }\n\n  private getDefaultInstrumentations(): Instrumentation[] {\n    return [\n      ...getNodeAutoInstrumentations({\n        //\n        // enabled as a part of the server plugin\n        //\n        \"@opentelemetry/instrumentation-http\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-express\": {\n          enabled: false,\n        },\n        //\n        // reduce noise\n        //\n        \"@opentelemetry/instrumentation-fs\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-dns\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-net\": {\n          enabled: false,\n        },\n      }),\n    ];\n  }\n\n  private registerShutdown() {\n    const shutdownFn = async () => {\n      await TelemetryManager.getInstance().shutdown();\n    };\n    process.once(\"SIGTERM\", shutdownFn);\n    process.once(\"SIGINT\", shutdownFn);\n  }\n\n  private async shutdown(): Promise<void> {\n    if (!this.sdk) {\n      return;\n    }\n\n    try {\n      await this.sdk.shutdown();\n      this.sdk = undefined;\n    } catch (error) {\n      console.error(\"[Telemetry] Error shutting down:\", error);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AA4BA,IAAa,mBAAb,MAAa,iBAAiB;;oCACyB;;;mCACD;;;;;;;;;CAYpD,OAAO,YACL,YACA,iBACmB;AAEnB,SAAO,IAAI,kBAAkB,YADP,iBAAiB,aAAa,EACI,gBAAgB;;CAG1E,AAAQ,cAAc;CAEtB,OAAO,cAAgC;AACrC,MAAI,CAAC,iBAAiB,SACpB,kBAAiB,WAAW,IAAI,kBAAkB;AAEpD,SAAO,iBAAiB;;CAG1B,OAAO,WAAW,SAAmC,EAAE,EAAQ;AAE7D,EADiB,iBAAiB,aAAa,CACtC,YAAY,OAAO;;CAG9B,AAAQ,YAAY,QAAwC;AAC1D,MAAI,KAAK,IAAK;AAEd,MAAI,CAAC,QAAQ,IAAI,4BACf;AAGF,MAAI;AACF,QAAK,MAAM,IAAI,QAAQ;IACrB,UAAU,KAAK,eAAe,OAAO;IACrC,qBAAqB;IACrB,SAAS,IAAI,iBAAiB;IAC9B,eAAe,IAAI,kBAAkB,EAAE,SAAS,OAAO,SAAS,CAAC;IACjE,eAAe,CACb,IAAI,8BAA8B;KAChC,UAAU,IAAI,mBAAmB,EAAE,SAAS,OAAO,SAAS,CAAC;KAC7D,sBACE,OAAO,oBACP,iBAAiB;KACpB,CAAC,CACH;IACD,qBAAqB,CACnB,IAAI,wBACF,IAAI,gBAAgB,EAAE,SAAS,OAAO,SAAS,CAAC,CACjD,CACF;IACD,kBAAkB,KAAK,4BAA4B;IACpD,CAAC;AAEF,QAAK,IAAI,OAAO;AAChB,QAAK,kBAAkB;AACvB,WAAQ,IAAI,uCAAuC;WAC5C,OAAO;AACd,WAAQ,MAAM,qCAAqC,MAAM;;;;;;;;CAS7D,yBAAyB,kBAA2C;AAClE,2BAA6B,EAE3B,kBACD,CAAC;;CAGJ,AAAQ,eAAe,QAA4C;EACjE,MAAM,cACJ,OAAO,eACP,QAAQ,IAAI,qBACZ,QAAQ,IAAI,uBACZ,iBAAiB;EACnB,MAAM,kBAAkB,uBAAuB;IAC5C,oBAAoB;IACpB,uBAAuB,OAAO,kBAAkB;GAClD,CAAC;EACF,MAAM,mBAAmB,gBAAgB,EACvC,WAAW;GAAC;GAAa;GAAc;GAAgB,EACxD,CAAC;AACF,SAAO,gBAAgB,MAAM,iBAAiB;;CAGhD,AAAQ,6BAAgD;AACtD,SAAO,CACL,GAAG,4BAA4B;GAI7B,uCAAuC,EACrC,SAAS,OACV;GACD,0CAA0C,EACxC,SAAS,OACV;GAID,qCAAqC,EACnC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACF,CAAC,CACH;;CAGH,AAAQ,mBAAmB;EACzB,MAAM,aAAa,YAAY;AAC7B,SAAM,iBAAiB,aAAa,CAAC,UAAU;;AAEjD,UAAQ,KAAK,WAAW,WAAW;AACnC,UAAQ,KAAK,UAAU,WAAW;;CAGpC,MAAc,WAA0B;AACtC,MAAI,CAAC,KAAK,IACR;AAGF,MAAI;AACF,SAAM,KAAK,IAAI,UAAU;AACzB,QAAK,MAAM;WACJ,OAAO;AACd,WAAQ,MAAM,oCAAoC,MAAM"}
+{"version":3,"file":"telemetry-manager.js","names":[],"sources":["../../src/telemetry/telemetry-manager.ts"],"sourcesContent":["import { getNodeAutoInstrumentations } from \"@opentelemetry/auto-instrumentations-node\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-proto\";\nimport { OTLPMetricExporter } from \"@opentelemetry/exporter-metrics-otlp-proto\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-proto\";\nimport {\n  type Instrumentation,\n  registerInstrumentations as otelRegisterInstrumentations,\n} from \"@opentelemetry/instrumentation\";\nimport {\n  detectResources,\n  envDetector,\n  hostDetector,\n  processDetector,\n  type Resource,\n  resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { BatchLogRecordProcessor } from \"@opentelemetry/sdk-logs\";\nimport { PeriodicExportingMetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\nimport {\n  ATTR_SERVICE_NAME,\n  ATTR_SERVICE_VERSION,\n} from \"@opentelemetry/semantic-conventions\";\nimport type { TelemetryOptions } from \"shared\";\nimport { createLogger } from \"../logging/logger\";\nimport { TelemetryProvider } from \"./telemetry-provider\";\nimport { AppKitSampler } from \"./trace-sampler\";\nimport type { TelemetryConfig } from \"./types\";\n\nconst logger = createLogger(\"telemetry\");\n\nexport class TelemetryManager {\n  private static readonly DEFAULT_EXPORT_INTERVAL_MS = 10000;\n  private static readonly DEFAULT_FALLBACK_APP_NAME = \"databricks-app\";\n\n  private static instance?: TelemetryManager;\n  private sdk?: NodeSDK;\n\n  /**\n   * Create a scoped telemetry provider for a specific plugin.\n   * The plugin's name will be used as the default tracer/meter name.\n   * @param pluginName - The name of the plugin to create scoped telemetry for\n   * @param telemetryConfig - The telemetry configuration for the plugin\n   * @returns A scoped telemetry instance for the plugin\n   */\n  static getProvider(\n    pluginName: string,\n    telemetryConfig?: TelemetryOptions,\n  ): TelemetryProvider {\n    const globalManager = TelemetryManager.getInstance();\n    return new TelemetryProvider(pluginName, globalManager, telemetryConfig);\n  }\n\n  private constructor() {}\n\n  static getInstance(): TelemetryManager {\n    if (!TelemetryManager.instance) {\n      TelemetryManager.instance = new TelemetryManager();\n    }\n    return TelemetryManager.instance;\n  }\n\n  static initialize(config: Partial<TelemetryConfig> = {}): void {\n    const instance = TelemetryManager.getInstance();\n    instance._initialize(config);\n  }\n\n  private _initialize(config: Partial<TelemetryConfig>): void {\n    if (this.sdk) return;\n\n    if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {\n      return;\n    }\n\n    try {\n      this.sdk = new NodeSDK({\n        resource: this.createResource(config),\n        autoDetectResources: false,\n        sampler: new AppKitSampler(),\n        traceExporter: new OTLPTraceExporter({ headers: config.headers }),\n        metricReaders: [\n          new PeriodicExportingMetricReader({\n            exporter: new OTLPMetricExporter({ headers: config.headers }),\n            exportIntervalMillis:\n              config.exportIntervalMs ||\n              TelemetryManager.DEFAULT_EXPORT_INTERVAL_MS,\n          }),\n        ],\n        logRecordProcessors: [\n          new BatchLogRecordProcessor(\n            new OTLPLogExporter({ headers: config.headers }),\n          ),\n        ],\n        instrumentations: this.getDefaultInstrumentations(),\n      });\n\n      this.sdk.start();\n      this.registerShutdown();\n      logger.debug(\"Initialized successfully\");\n    } catch (error) {\n      logger.error(\"Failed to initialize: %O\", error);\n    }\n  }\n\n  /**\n   * Register OpenTelemetry instrumentations.\n   * Can be called at any time, but recommended to call in plugin constructor.\n   * @param instrumentations - Array of OpenTelemetry instrumentations to register\n   */\n  registerInstrumentations(instrumentations: Instrumentation[]): void {\n    otelRegisterInstrumentations({\n      //  global providers set by NodeSDK.start()\n      instrumentations,\n    });\n  }\n\n  private createResource(config: Partial<TelemetryConfig>): Resource {\n    const serviceName =\n      config.serviceName ||\n      process.env.OTEL_SERVICE_NAME ||\n      process.env.DATABRICKS_APP_NAME ||\n      TelemetryManager.DEFAULT_FALLBACK_APP_NAME;\n    const initialResource = resourceFromAttributes({\n      [ATTR_SERVICE_NAME]: serviceName,\n      [ATTR_SERVICE_VERSION]: config.serviceVersion ?? undefined,\n    });\n    const detectedResource = detectResources({\n      detectors: [envDetector, hostDetector, processDetector],\n    });\n    return initialResource.merge(detectedResource);\n  }\n\n  private getDefaultInstrumentations(): Instrumentation[] {\n    return [\n      ...getNodeAutoInstrumentations({\n        //\n        // enabled as a part of the server plugin\n        //\n        \"@opentelemetry/instrumentation-http\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-express\": {\n          enabled: false,\n        },\n        //\n        // reduce noise\n        //\n        \"@opentelemetry/instrumentation-fs\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-dns\": {\n          enabled: false,\n        },\n        \"@opentelemetry/instrumentation-net\": {\n          enabled: false,\n        },\n      }),\n    ];\n  }\n\n  private registerShutdown() {\n    const shutdownFn = async () => {\n      await TelemetryManager.getInstance().shutdown();\n    };\n    process.once(\"SIGTERM\", shutdownFn);\n    process.once(\"SIGINT\", shutdownFn);\n  }\n\n  private async shutdown(): Promise<void> {\n    if (!this.sdk) {\n      return;\n    }\n\n    try {\n      await this.sdk.shutdown();\n      this.sdk = undefined;\n    } catch (error) {\n      logger.error(\"Error shutting down: %O\", error);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AA6BA,MAAM,SAAS,aAAa,YAAY;AAExC,IAAa,mBAAb,MAAa,iBAAiB;;oCACyB;;;mCACD;;;;;;;;;CAYpD,OAAO,YACL,YACA,iBACmB;AAEnB,SAAO,IAAI,kBAAkB,YADP,iBAAiB,aAAa,EACI,gBAAgB;;CAG1E,AAAQ,cAAc;CAEtB,OAAO,cAAgC;AACrC,MAAI,CAAC,iBAAiB,SACpB,kBAAiB,WAAW,IAAI,kBAAkB;AAEpD,SAAO,iBAAiB;;CAG1B,OAAO,WAAW,SAAmC,EAAE,EAAQ;AAE7D,EADiB,iBAAiB,aAAa,CACtC,YAAY,OAAO;;CAG9B,AAAQ,YAAY,QAAwC;AAC1D,MAAI,KAAK,IAAK;AAEd,MAAI,CAAC,QAAQ,IAAI,4BACf;AAGF,MAAI;AACF,QAAK,MAAM,IAAI,QAAQ;IACrB,UAAU,KAAK,eAAe,OAAO;IACrC,qBAAqB;IACrB,SAAS,IAAI,eAAe;IAC5B,eAAe,IAAI,kBAAkB,EAAE,SAAS,OAAO,SAAS,CAAC;IACjE,eAAe,CACb,IAAI,8BAA8B;KAChC,UAAU,IAAI,mBAAmB,EAAE,SAAS,OAAO,SAAS,CAAC;KAC7D,sBACE,OAAO,oBACP,iBAAiB;KACpB,CAAC,CACH;IACD,qBAAqB,CACnB,IAAI,wBACF,IAAI,gBAAgB,EAAE,SAAS,OAAO,SAAS,CAAC,CACjD,CACF;IACD,kBAAkB,KAAK,4BAA4B;IACpD,CAAC;AAEF,QAAK,IAAI,OAAO;AAChB,QAAK,kBAAkB;AACvB,UAAO,MAAM,2BAA2B;WACjC,OAAO;AACd,UAAO,MAAM,4BAA4B,MAAM;;;;;;;;CASnD,yBAAyB,kBAA2C;AAClE,2BAA6B,EAE3B,kBACD,CAAC;;CAGJ,AAAQ,eAAe,QAA4C;EACjE,MAAM,cACJ,OAAO,eACP,QAAQ,IAAI,qBACZ,QAAQ,IAAI,uBACZ,iBAAiB;EACnB,MAAM,kBAAkB,uBAAuB;IAC5C,oBAAoB;IACpB,uBAAuB,OAAO,kBAAkB;GAClD,CAAC;EACF,MAAM,mBAAmB,gBAAgB,EACvC,WAAW;GAAC;GAAa;GAAc;GAAgB,EACxD,CAAC;AACF,SAAO,gBAAgB,MAAM,iBAAiB;;CAGhD,AAAQ,6BAAgD;AACtD,SAAO,CACL,GAAG,4BAA4B;GAI7B,uCAAuC,EACrC,SAAS,OACV;GACD,0CAA0C,EACxC,SAAS,OACV;GAID,qCAAqC,EACnC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACD,sCAAsC,EACpC,SAAS,OACV;GACF,CAAC,CACH;;CAGH,AAAQ,mBAAmB;EACzB,MAAM,aAAa,YAAY;AAC7B,SAAM,iBAAiB,aAAa,CAAC,UAAU;;AAEjD,UAAQ,KAAK,WAAW,WAAW;AACnC,UAAQ,KAAK,UAAU,WAAW;;CAGpC,MAAc,WAA0B;AACtC,MAAI,CAAC,KAAK,IACR;AAGF,MAAI;AACF,SAAM,KAAK,IAAI,UAAU;AACzB,QAAK,MAAM;WACJ,OAAO;AACd,UAAO,MAAM,2BAA2B,MAAM"}

package/dist/telemetry/trace-sampler.js

@@ -0,0 +1,33 @@
+import { shouldExcludePath } from "../utils/path-exclusions.js";
+import { SamplingDecision } from "@opentelemetry/sdk-trace-base";
+
+//#region src/telemetry/trace-sampler.ts
+/**
+* Custom sampler that filters out asset requests and other noise.
+*
+* This acts as a secondary filter after HttpInstrumentation.ignoreIncomingRequestHook.
+* It catches any spans that slip through the primary filter.
+*/
+var AppKitSampler = class {
+	shouldSample(_context, _traceId, spanName, _spanKind, attributes, _links) {
+		const httpTarget = attributes["http.target"];
+		const httpRoute = attributes["http.route"];
+		const httpUrl = attributes["http.url"];
+		let path = httpTarget || httpRoute;
+		if (!path && httpUrl) try {
+			path = new URL(httpUrl).pathname;
+		} catch {
+			path = httpUrl;
+		}
+		if (!path) path = spanName;
+		if (shouldExcludePath(path)) return { decision: SamplingDecision.NOT_RECORD };
+		return { decision: SamplingDecision.RECORD_AND_SAMPLED };
+	}
+	toString() {
+		return "AppKitSampler";
+	}
+};
+
+//#endregion
+export { AppKitSampler };
+//# sourceMappingURL=trace-sampler.js.map

package/dist/telemetry/trace-sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-sampler.js","names":[],"sources":["../../src/telemetry/trace-sampler.ts"],"sourcesContent":["import type { Attributes, Context, Link } from \"@opentelemetry/api\";\nimport type { Sampler, SamplingResult } from \"@opentelemetry/sdk-trace-base\";\nimport { SamplingDecision } from \"@opentelemetry/sdk-trace-base\";\nimport { shouldExcludePath } from \"../utils/path-exclusions\";\n\n/**\n * Custom sampler that filters out asset requests and other noise.\n *\n * This acts as a secondary filter after HttpInstrumentation.ignoreIncomingRequestHook.\n * It catches any spans that slip through the primary filter.\n */\nexport class AppKitSampler implements Sampler {\n  shouldSample(\n    _context: Context,\n    _traceId: string,\n    spanName: string,\n    _spanKind: number,\n    attributes: Attributes,\n    _links: Link[],\n  ): SamplingResult {\n    // Check if this is an HTTP request span\n    const httpTarget = attributes[\"http.target\"] as string | undefined;\n    const httpRoute = attributes[\"http.route\"] as string | undefined;\n    const httpUrl = attributes[\"http.url\"] as string | undefined;\n\n    // Try to extract path from various attributes\n    let path = httpTarget || httpRoute;\n    if (!path && httpUrl) {\n      try {\n        path = new URL(httpUrl).pathname;\n      } catch {\n        // Not a valid URL, use as-is\n        path = httpUrl;\n      }\n    }\n    if (!path) {\n      path = spanName;\n    }\n\n    // Check if path should be excluded\n    if (shouldExcludePath(path)) {\n      return {\n        decision: SamplingDecision.NOT_RECORD,\n      };\n    }\n\n    // For all other requests, record and sample\n    return {\n      decision: SamplingDecision.RECORD_AND_SAMPLED,\n    };\n  }\n\n  toString(): string {\n    return \"AppKitSampler\";\n  }\n}\n"],"mappings":";;;;;;;;;;AAWA,IAAa,gBAAb,MAA8C;CAC5C,aACE,UACA,UACA,UACA,WACA,YACA,QACgB;EAEhB,MAAM,aAAa,WAAW;EAC9B,MAAM,YAAY,WAAW;EAC7B,MAAM,UAAU,WAAW;EAG3B,IAAI,OAAO,cAAc;AACzB,MAAI,CAAC,QAAQ,QACX,KAAI;AACF,UAAO,IAAI,IAAI,QAAQ,CAAC;UAClB;AAEN,UAAO;;AAGX,MAAI,CAAC,KACH,QAAO;AAIT,MAAI,kBAAkB,KAAK,CACzB,QAAO,EACL,UAAU,iBAAiB,YAC5B;AAIH,SAAO,EACL,UAAU,iBAAiB,oBAC5B;;CAGH,WAAmB;AACjB,SAAO"}

package/dist/type-generator/index.js

@@ -1,9 +1,11 @@
+import { createLogger } from "../logging/logger.js";
 import { generateQueriesFromDescribe } from "./query-registry.js";
 import fs from "node:fs";
 import dotenv from "dotenv";
 
 //#region src/type-generator/index.ts
 dotenv.config();
+const logger = createLogger("type-generator");
 /**
 * Generate type declarations for QueryRegistry
 * Create the d.ts file from the plugin routes and query schemas
@@ -33,12 +35,12 @@ declare module "@databricks/appkit-ui/react" {
 */
 async function generateFromEntryPoint(options) {
 	const { outFile, queryFolder, warehouseId, noCache } = options;
-	console.log("\n[AppKit] Starting type generation...\n");
+	logger.debug("Starting type generation...");
 	let queryRegistry = [];
 	if (queryFolder) queryRegistry = await generateQueriesFromDescribe(queryFolder, warehouseId, { noCache });
 	const typeDeclarations = generateTypeDeclarations(queryRegistry);
 	fs.writeFileSync(outFile, typeDeclarations, "utf-8");
-	console.log("\n[AppKit] Type generation complete!\n");
+	logger.debug("Type generation complete!");
 }
 
 //#endregion

package/dist/type-generator/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["queryRegistry: QuerySchema[]"],"sources":["../../src/type-generator/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport dotenv from \"dotenv\";\nimport { generateQueriesFromDescribe } from \"./query-registry\";\nimport type { QuerySchema } from \"./types\";\n\ndotenv.config();\n\n/**\n * Generate type declarations for QueryRegistry\n * Create the d.ts file from the plugin routes and query schemas\n * @param querySchemas - the list of query schemas\n * @returns - the type declarations as a string\n */\nfunction generateTypeDeclarations(querySchemas: QuerySchema[] = []): string {\n  const queryEntries = querySchemas\n    .map(({ name, type }) => {\n      const indentedType = type\n        .split(\"\\n\")\n        .map((line, i) => (i === 0 ? line : `    ${line}`))\n        .join(\"\\n\");\n      return `    ${name}: ${indentedType}`;\n    })\n    .join(\";\\n\");\n\n  const querySection = queryEntries ? `\\n${queryEntries};\\n  ` : \"\";\n\n  return `// Auto-generated by AppKit - DO NOT EDIT\n// Generated by 'npx appkit-generate-types' or Vite plugin during build\nimport \"@databricks/appkit-ui/react\";\nimport type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from \"@databricks/appkit-ui/js\";\n\ndeclare module \"@databricks/appkit-ui/react\" {\n  interface QueryRegistry {${querySection}}\n}\n`;\n}\n\n/**\n * Entry point for generating type declarations from all imported files\n * @param options - the options for the generation\n * @param options.entryPoint - the entry point file\n * @param options.outFile - the output file\n * @param options.querySchemaFile - optional path to query schema file (e.g. config/queries/schema.ts)\n */\nexport async function generateFromEntryPoint(options: {\n  outFile: string;\n  queryFolder?: string;\n  warehouseId: string;\n  noCache?: boolean;\n}) {\n  const { outFile, queryFolder, warehouseId, noCache } = options;\n\n  console.log(\"\\n[AppKit] Starting type generation...\\n\");\n\n  let queryRegistry: QuerySchema[] = [];\n  if (queryFolder)\n    queryRegistry = await generateQueriesFromDescribe(\n      queryFolder,\n      warehouseId,\n      {\n        noCache,\n      },\n    );\n\n  const typeDeclarations = generateTypeDeclarations(queryRegistry);\n\n  fs.writeFileSync(outFile, typeDeclarations, \"utf-8\");\n\n  console.log(\"\\n[AppKit] Type generation complete!\\n\");\n}\n"],"mappings":";;;;;AAKA,OAAO,QAAQ;;;;;;;AAQf,SAAS,yBAAyB,eAA8B,EAAE,EAAU;CAC1E,MAAM,eAAe,aAClB,KAAK,EAAE,MAAM,WAAW;AAKvB,SAAO,OAAO,KAAK,IAJE,KAClB,MAAM,KAAK,CACX,KAAK,MAAM,MAAO,MAAM,IAAI,OAAO,OAAO,OAAQ,CAClD,KAAK,KAAK;GAEb,CACD,KAAK,MAAM;AAId,QAAO;;;;;;6BAFc,eAAe,KAAK,aAAa,SAAS,GAQvB;;;;;;;;;;;AAY1C,eAAsB,uBAAuB,SAK1C;CACD,MAAM,EAAE,SAAS,aAAa,aAAa,YAAY;AAEvD,SAAQ,IAAI,2CAA2C;CAEvD,IAAIA,gBAA+B,EAAE;AACrC,KAAI,YACF,iBAAgB,MAAM,4BACpB,aACA,aACA,EACE,SACD,CACF;CAEH,MAAM,mBAAmB,yBAAyB,cAAc;AAEhE,IAAG,cAAc,SAAS,kBAAkB,QAAQ;AAEpD,SAAQ,IAAI,yCAAyC"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/type-generator/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport dotenv from \"dotenv\";\nimport { createLogger } from \"../logging/logger\";\nimport { generateQueriesFromDescribe } from \"./query-registry\";\nimport type { QuerySchema } from \"./types\";\n\ndotenv.config();\n\nconst logger = createLogger(\"type-generator\");\n\n/**\n * Generate type declarations for QueryRegistry\n * Create the d.ts file from the plugin routes and query schemas\n * @param querySchemas - the list of query schemas\n * @returns - the type declarations as a string\n */\nfunction generateTypeDeclarations(querySchemas: QuerySchema[] = []): string {\n  const queryEntries = querySchemas\n    .map(({ name, type }) => {\n      const indentedType = type\n        .split(\"\\n\")\n        .map((line, i) => (i === 0 ? line : `    ${line}`))\n        .join(\"\\n\");\n      return `    ${name}: ${indentedType}`;\n    })\n    .join(\";\\n\");\n\n  const querySection = queryEntries ? `\\n${queryEntries};\\n  ` : \"\";\n\n  return `// Auto-generated by AppKit - DO NOT EDIT\n// Generated by 'npx appkit-generate-types' or Vite plugin during build\nimport \"@databricks/appkit-ui/react\";\nimport type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from \"@databricks/appkit-ui/js\";\n\ndeclare module \"@databricks/appkit-ui/react\" {\n  interface QueryRegistry {${querySection}}\n}\n`;\n}\n\n/**\n * Entry point for generating type declarations from all imported files\n * @param options - the options for the generation\n * @param options.entryPoint - the entry point file\n * @param options.outFile - the output file\n * @param options.querySchemaFile - optional path to query schema file (e.g. config/queries/schema.ts)\n */\nexport async function generateFromEntryPoint(options: {\n  outFile: string;\n  queryFolder?: string;\n  warehouseId: string;\n  noCache?: boolean;\n}) {\n  const { outFile, queryFolder, warehouseId, noCache } = options;\n\n  logger.debug(\"Starting type generation...\");\n\n  let queryRegistry: QuerySchema[] = [];\n  if (queryFolder)\n    queryRegistry = await generateQueriesFromDescribe(\n      queryFolder,\n      warehouseId,\n      {\n        noCache,\n      },\n    );\n\n  const typeDeclarations = generateTypeDeclarations(queryRegistry);\n\n  fs.writeFileSync(outFile, typeDeclarations, \"utf-8\");\n\n  logger.debug(\"Type generation complete!\");\n}\n"],"mappings":";;;;;;AAMA,OAAO,QAAQ;AAEf,MAAM,SAAS,aAAa,iBAAiB;;;;;;;AAQ7C,SAAS,yBAAyB,eAA8B,EAAE,EAAU;CAC1E,MAAM,eAAe,aAClB,KAAK,EAAE,MAAM,WAAW;AAKvB,SAAO,OAAO,KAAK,IAJE,KAClB,MAAM,KAAK,CACX,KAAK,MAAM,MAAO,MAAM,IAAI,OAAO,OAAO,OAAQ,CAClD,KAAK,KAAK;GAEb,CACD,KAAK,MAAM;AAId,QAAO;;;;;;6BAFc,eAAe,KAAK,aAAa,SAAS,GAQvB;;;;;;;;;;;AAY1C,eAAsB,uBAAuB,SAK1C;CACD,MAAM,EAAE,SAAS,aAAa,aAAa,YAAY;AAEvD,QAAO,MAAM,8BAA8B;CAE3C,IAAI,gBAA+B,EAAE;AACrC,KAAI,YACF,iBAAgB,MAAM,4BACpB,aACA,aACA,EACE,SACD,CACF;CAEH,MAAM,mBAAmB,yBAAyB,cAAc;AAEhE,IAAG,cAAc,SAAS,kBAAkB,QAAQ;AAEpD,QAAO,MAAM,4BAA4B"}

package/dist/type-generator/query-registry.js

@@ -1,3 +1,4 @@
+import { createLogger } from "../logging/logger.js";
 import { CACHE_VERSION, hashSQL, loadCache, saveCache } from "./cache.js";
 import { Spinner } from "./spinner.js";
 import { sqlTypeToHelper, sqlTypeToMarker } from "./types.js";
@@ -6,6 +7,7 @@ import path from "node:path";
 import fs from "node:fs";
 
 //#region src/type-generator/query-registry.ts
+const logger = createLogger("type-generator:query-registry");
 /**
 * Extract parameters from a SQL query
 * @param sql - the SQL query to extract parameters from
@@ -64,7 +66,7 @@ function extractParameterTypes(sql) {
 async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {}) {
 	const { noCache = false } = options;
 	const queryFiles = fs.readdirSync(queryFolder).filter((file) => file.endsWith(".sql"));
-	console.log(`  Found ${queryFiles.length} SQL queries\n`);
+	logger.debug("Found %d SQL queries", queryFiles.length);
 	const cache = noCache ? {
 		version: CACHE_VERSION,
 		queries: {}
@@ -123,7 +125,7 @@ async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {
 		}
 	}
 	saveCache(cache);
-	if (failedQueries.length > 0) console.warn(`  Warning: ${failedQueries.length} queries failed\n`);
+	if (failedQueries.length > 0) logger.debug("Warning: %d queries failed", failedQueries.length);
 	return querySchemas;
 }
 /**

package/dist/type-generator/query-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-registry.js","names":["paramTypes: Record<string, string>","querySchemas: QuerySchema[]","failedQueries: { name: string; error: string }[]","typeMap: Record<string, string>"],"sources":["../../src/type-generator/query-registry.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport { CACHE_VERSION, hashSQL, loadCache, saveCache } from \"./cache\";\nimport { Spinner } from \"./spinner\";\nimport {\n  type DatabricksStatementExecutionResponse,\n  type QuerySchema,\n  sqlTypeToHelper,\n  sqlTypeToMarker,\n} from \"./types\";\n\n/**\n * Extract parameters from a SQL query\n * @param sql - the SQL query to extract parameters from\n * @returns an array of parameter names\n */\nexport function extractParameters(sql: string): string[] {\n  const matches = sql.matchAll(/:([a-zA-Z_]\\w*)/g);\n  const params = new Set<string>();\n  for (const match of matches) {\n    params.add(match[1]);\n  }\n  return Array.from(params);\n}\n\n// parameters that are injected by the server\nexport const SERVER_INJECTED_PARAMS = [\"workspaceId\"];\n\nexport function convertToQueryType(\n  result: DatabricksStatementExecutionResponse,\n  sql: string,\n  queryName: string,\n): string {\n  const dataRows = result.result?.data_array || [];\n  const columns = dataRows.map((row) => ({\n    name: row[0] || \"\",\n    type_name: row[1]?.toUpperCase() || \"STRING\",\n    comment: row[2] || undefined,\n  }));\n\n  const params = extractParameters(sql).filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p),\n  );\n\n  const paramTypes = extractParameterTypes(sql);\n\n  // generate parameters types with JSDoc hints\n  const paramsType =\n    params.length > 0\n      ? `{\\n      ${params\n          .map((p) => {\n            const sqlType = paramTypes[p];\n            // if no type annotation, use SQLTypeMarker (union type)\n            const markerType = sqlType\n              ? sqlTypeToMarker[sqlType]\n              : \"SQLTypeMarker\";\n            const helper = sqlType ? sqlTypeToHelper[sqlType] : \"sql.*()\";\n            return `/** ${sqlType || \"any\"} - use ${helper} */\\n      ${p}: ${markerType}`;\n          })\n          .join(\";\\n      \")};\\n    }`\n      : \"Record<string, never>\";\n\n  // generate result fields with JSDoc\n  const resultFields = columns.map((column) => {\n    const normalizedType = normalizeTypeName(column.type_name);\n    const mappedType = typeMap[normalizedType] || \"unknown\";\n    // validate column name is a valid identifier\n    const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name)\n      ? column.name\n      : `\"${column.name}\"`;\n\n    // generate comment for column\n    const comment = column.comment\n      ? `/** ${column.comment} */\\n      `\n      : `/** @sqlType ${column.type_name} */\\n      `;\n\n    return `${comment}${name}: ${mappedType}`;\n  });\n\n  return `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: Array<{\n      ${resultFields.join(\";\\n      \")};\n    }>;\n  }`;\n}\n\nexport function extractParameterTypes(sql: string): Record<string, string> {\n  const paramTypes: Record<string, string> = {};\n  const regex =\n    /--\\s*@param\\s+(\\w+)\\s+(STRING|NUMERIC|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi;\n  const matches = sql.matchAll(regex);\n  for (const match of matches) {\n    const [, paramName, paramType] = match;\n    paramTypes[paramName] = paramType.toUpperCase();\n  }\n\n  return paramTypes;\n}\n\n/**\n * Generate query schemas from a folder of SQL files\n * It uses DESCRIBE QUERY to get the schema without executing the query\n * @param queryFolder - the folder containing the SQL files\n * @param warehouseId - the warehouse id to use for schema analysis\n * @param options - options for the query generation\n * @param options.noCache - if true, skip the cache and regenerate all types\n * @returns an array of query schemas\n */\nexport async function generateQueriesFromDescribe(\n  queryFolder: string,\n  warehouseId: string,\n  options: { noCache?: boolean } = {},\n): Promise<QuerySchema[]> {\n  const { noCache = false } = options;\n\n  // read all query files in the folder\n  const queryFiles = fs\n    .readdirSync(queryFolder)\n    .filter((file) => file.endsWith(\".sql\"));\n\n  console.log(`  Found ${queryFiles.length} SQL queries\\n`);\n\n  // load cache\n  const cache = noCache ? { version: CACHE_VERSION, queries: {} } : loadCache();\n\n  const client = new WorkspaceClient({});\n  const querySchemas: QuerySchema[] = [];\n  const failedQueries: { name: string; error: string }[] = [];\n  const spinner = new Spinner();\n\n  // process each query file\n  for (let i = 0; i < queryFiles.length; i++) {\n    const file = queryFiles[i];\n    const queryName = path.basename(file, \".sql\");\n\n    // read query file content\n    const sql = fs.readFileSync(path.join(queryFolder, file), \"utf8\");\n    const sqlHash = hashSQL(sql);\n\n    // check cache\n    const cached = cache.queries[queryName];\n    if (cached && cached.hash === sqlHash) {\n      querySchemas.push({ name: queryName, type: cached.type });\n      spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);\n      spinner.stop(`✓ ${queryName} (cached)`);\n      continue;\n    }\n\n    spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);\n\n    const sqlWithDefaults = sql.replace(/:([a-zA-Z_]\\w*)/g, \"''\");\n\n    // strip trailing semicolon for DESCRIBE QUERY\n    const cleanedSql = sqlWithDefaults.trim().replace(/;\\s*$/, \"\");\n\n    // execute DESCRIBE QUERY to get schema without running the actual query\n    try {\n      const result = (await client.statementExecution.executeStatement({\n        statement: `DESCRIBE QUERY ${cleanedSql}`,\n        warehouse_id: warehouseId,\n      })) as DatabricksStatementExecutionResponse;\n\n      if (result.status.state === \"FAILED\") {\n        spinner.stop(`✗ ${queryName} - failed`);\n        failedQueries.push({\n          name: queryName,\n          error: \"Query execution failed\",\n        });\n        continue;\n      }\n\n      // convert result to query schema\n      const type = convertToQueryType(result, sql, queryName);\n      querySchemas.push({ name: queryName, type });\n\n      // update cache\n      cache.queries[queryName] = { hash: sqlHash, type };\n\n      spinner.stop(`✓ ${queryName}`);\n    } catch (error) {\n      const errorMessage =\n        error instanceof Error ? error.message : \"Unknown error\";\n      spinner.stop(`✗ ${queryName} - ${errorMessage}`);\n      failedQueries.push({ name: queryName, error: errorMessage });\n    }\n  }\n\n  // save cache\n  saveCache(cache);\n\n  // log warning if there are failed queries\n  if (failedQueries.length > 0) {\n    console.warn(`  Warning: ${failedQueries.length} queries failed\\n`);\n  }\n\n  return querySchemas;\n}\n\n/**\n * Normalize SQL type name by removing parameters/generics\n * Examples:\n *   DECIMAL(38,6) -> DECIMAL\n *   ARRAY<STRING> -> ARRAY\n *   MAP<STRING,INT> -> MAP\n *   STRUCT<name:STRING> -> STRUCT\n *   INTERVAL DAY TO SECOND -> INTERVAL\n *   GEOGRAPHY(4326) -> GEOGRAPHY\n */\nexport function normalizeTypeName(typeName: string): string {\n  return typeName\n    .replace(/\\(.*\\)$/, \"\") // remove (p, s) eg: DECIMAL(38,6) -> DECIMAL\n    .replace(/<.*>$/, \"\") // remove <T> eg: ARRAY<STRING> -> ARRAY\n    .split(\" \")[0]; // take first word eg: INTERVAL DAY TO SECOND -> INTERVAL\n}\n\n/** Type Map for Databricks data types to JavaScript types */\nconst typeMap: Record<string, string> = {\n  // string types\n  STRING: \"string\",\n  BINARY: \"string\",\n  // boolean\n  BOOLEAN: \"boolean\",\n  // numeric types\n  TINYINT: \"number\",\n  SMALLINT: \"number\",\n  INT: \"number\",\n  BIGINT: \"number\",\n  FLOAT: \"number\",\n  DOUBLE: \"number\",\n  DECIMAL: \"number\",\n  // date/time types\n  DATE: \"string\",\n  TIMESTAMP: \"string\",\n  TIMESTAMP_NTZ: \"string\",\n  INTERVAL: \"string\",\n  // complex types\n  ARRAY: \"unknown[]\",\n  MAP: \"Record<string, unknown>\",\n  STRUCT: \"Record<string, unknown>\",\n  OBJECT: \"Record<string, unknown>\",\n  VARIANT: \"unknown\",\n  // spatial types\n  GEOGRAPHY: \"unknown\",\n  GEOMETRY: \"unknown\",\n  // null type\n  VOID: \"null\",\n};\n"],"mappings":"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"}
+{"version":3,"file":"query-registry.js","names":[],"sources":["../../src/type-generator/query-registry.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport { createLogger } from \"../logging/logger\";\nimport { CACHE_VERSION, hashSQL, loadCache, saveCache } from \"./cache\";\nimport { Spinner } from \"./spinner\";\nimport {\n  type DatabricksStatementExecutionResponse,\n  type QuerySchema,\n  sqlTypeToHelper,\n  sqlTypeToMarker,\n} from \"./types\";\n\nconst logger = createLogger(\"type-generator:query-registry\");\n\n/**\n * Extract parameters from a SQL query\n * @param sql - the SQL query to extract parameters from\n * @returns an array of parameter names\n */\nexport function extractParameters(sql: string): string[] {\n  const matches = sql.matchAll(/:([a-zA-Z_]\\w*)/g);\n  const params = new Set<string>();\n  for (const match of matches) {\n    params.add(match[1]);\n  }\n  return Array.from(params);\n}\n\n// parameters that are injected by the server\nexport const SERVER_INJECTED_PARAMS = [\"workspaceId\"];\n\nexport function convertToQueryType(\n  result: DatabricksStatementExecutionResponse,\n  sql: string,\n  queryName: string,\n): string {\n  const dataRows = result.result?.data_array || [];\n  const columns = dataRows.map((row) => ({\n    name: row[0] || \"\",\n    type_name: row[1]?.toUpperCase() || \"STRING\",\n    comment: row[2] || undefined,\n  }));\n\n  const params = extractParameters(sql).filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p),\n  );\n\n  const paramTypes = extractParameterTypes(sql);\n\n  // generate parameters types with JSDoc hints\n  const paramsType =\n    params.length > 0\n      ? `{\\n      ${params\n          .map((p) => {\n            const sqlType = paramTypes[p];\n            // if no type annotation, use SQLTypeMarker (union type)\n            const markerType = sqlType\n              ? sqlTypeToMarker[sqlType]\n              : \"SQLTypeMarker\";\n            const helper = sqlType ? sqlTypeToHelper[sqlType] : \"sql.*()\";\n            return `/** ${sqlType || \"any\"} - use ${helper} */\\n      ${p}: ${markerType}`;\n          })\n          .join(\";\\n      \")};\\n    }`\n      : \"Record<string, never>\";\n\n  // generate result fields with JSDoc\n  const resultFields = columns.map((column) => {\n    const normalizedType = normalizeTypeName(column.type_name);\n    const mappedType = typeMap[normalizedType] || \"unknown\";\n    // validate column name is a valid identifier\n    const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name)\n      ? column.name\n      : `\"${column.name}\"`;\n\n    // generate comment for column\n    const comment = column.comment\n      ? `/** ${column.comment} */\\n      `\n      : `/** @sqlType ${column.type_name} */\\n      `;\n\n    return `${comment}${name}: ${mappedType}`;\n  });\n\n  return `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: Array<{\n      ${resultFields.join(\";\\n      \")};\n    }>;\n  }`;\n}\n\nexport function extractParameterTypes(sql: string): Record<string, string> {\n  const paramTypes: Record<string, string> = {};\n  const regex =\n    /--\\s*@param\\s+(\\w+)\\s+(STRING|NUMERIC|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi;\n  const matches = sql.matchAll(regex);\n  for (const match of matches) {\n    const [, paramName, paramType] = match;\n    paramTypes[paramName] = paramType.toUpperCase();\n  }\n\n  return paramTypes;\n}\n\n/**\n * Generate query schemas from a folder of SQL files\n * It uses DESCRIBE QUERY to get the schema without executing the query\n * @param queryFolder - the folder containing the SQL files\n * @param warehouseId - the warehouse id to use for schema analysis\n * @param options - options for the query generation\n * @param options.noCache - if true, skip the cache and regenerate all types\n * @returns an array of query schemas\n */\nexport async function generateQueriesFromDescribe(\n  queryFolder: string,\n  warehouseId: string,\n  options: { noCache?: boolean } = {},\n): Promise<QuerySchema[]> {\n  const { noCache = false } = options;\n\n  // read all query files in the folder\n  const queryFiles = fs\n    .readdirSync(queryFolder)\n    .filter((file) => file.endsWith(\".sql\"));\n\n  logger.debug(\"Found %d SQL queries\", queryFiles.length);\n\n  // load cache\n  const cache = noCache ? { version: CACHE_VERSION, queries: {} } : loadCache();\n\n  const client = new WorkspaceClient({});\n  const querySchemas: QuerySchema[] = [];\n  const failedQueries: { name: string; error: string }[] = [];\n  const spinner = new Spinner();\n\n  // process each query file\n  for (let i = 0; i < queryFiles.length; i++) {\n    const file = queryFiles[i];\n    const queryName = path.basename(file, \".sql\");\n\n    // read query file content\n    const sql = fs.readFileSync(path.join(queryFolder, file), \"utf8\");\n    const sqlHash = hashSQL(sql);\n\n    // check cache\n    const cached = cache.queries[queryName];\n    if (cached && cached.hash === sqlHash) {\n      querySchemas.push({ name: queryName, type: cached.type });\n      spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);\n      spinner.stop(`✓ ${queryName} (cached)`);\n      continue;\n    }\n\n    spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);\n\n    const sqlWithDefaults = sql.replace(/:([a-zA-Z_]\\w*)/g, \"''\");\n\n    // strip trailing semicolon for DESCRIBE QUERY\n    const cleanedSql = sqlWithDefaults.trim().replace(/;\\s*$/, \"\");\n\n    // execute DESCRIBE QUERY to get schema without running the actual query\n    try {\n      const result = (await client.statementExecution.executeStatement({\n        statement: `DESCRIBE QUERY ${cleanedSql}`,\n        warehouse_id: warehouseId,\n      })) as DatabricksStatementExecutionResponse;\n\n      if (result.status.state === \"FAILED\") {\n        spinner.stop(`✗ ${queryName} - failed`);\n        failedQueries.push({\n          name: queryName,\n          error: \"Query execution failed\",\n        });\n        continue;\n      }\n\n      // convert result to query schema\n      const type = convertToQueryType(result, sql, queryName);\n      querySchemas.push({ name: queryName, type });\n\n      // update cache\n      cache.queries[queryName] = { hash: sqlHash, type };\n\n      spinner.stop(`✓ ${queryName}`);\n    } catch (error) {\n      const errorMessage =\n        error instanceof Error ? error.message : \"Unknown error\";\n      spinner.stop(`✗ ${queryName} - ${errorMessage}`);\n      failedQueries.push({ name: queryName, error: errorMessage });\n    }\n  }\n\n  // save cache\n  saveCache(cache);\n\n  // log warning if there are failed queries\n  if (failedQueries.length > 0) {\n    logger.debug(\"Warning: %d queries failed\", failedQueries.length);\n  }\n\n  return querySchemas;\n}\n\n/**\n * Normalize SQL type name by removing parameters/generics\n * Examples:\n *   DECIMAL(38,6) -> DECIMAL\n *   ARRAY<STRING> -> ARRAY\n *   MAP<STRING,INT> -> MAP\n *   STRUCT<name:STRING> -> STRUCT\n *   INTERVAL DAY TO SECOND -> INTERVAL\n *   GEOGRAPHY(4326) -> GEOGRAPHY\n */\nexport function normalizeTypeName(typeName: string): string {\n  return typeName\n    .replace(/\\(.*\\)$/, \"\") // remove (p, s) eg: DECIMAL(38,6) -> DECIMAL\n    .replace(/<.*>$/, \"\") // remove <T> eg: ARRAY<STRING> -> ARRAY\n    .split(\" \")[0]; // take first word eg: INTERVAL DAY TO SECOND -> INTERVAL\n}\n\n/** Type Map for Databricks data types to JavaScript types */\nconst typeMap: Record<string, string> = {\n  // string types\n  STRING: \"string\",\n  BINARY: \"string\",\n  // boolean\n  BOOLEAN: \"boolean\",\n  // numeric types\n  TINYINT: \"number\",\n  SMALLINT: \"number\",\n  INT: \"number\",\n  BIGINT: \"number\",\n  FLOAT: \"number\",\n  DOUBLE: \"number\",\n  DECIMAL: \"number\",\n  // date/time types\n  DATE: \"string\",\n  TIMESTAMP: \"string\",\n  TIMESTAMP_NTZ: \"string\",\n  INTERVAL: \"string\",\n  // complex types\n  ARRAY: \"unknown[]\",\n  MAP: \"Record<string, unknown>\",\n  STRUCT: \"Record<string, unknown>\",\n  OBJECT: \"Record<string, unknown>\",\n  VARIANT: \"unknown\",\n  // spatial types\n  GEOGRAPHY: \"unknown\",\n  GEOMETRY: \"unknown\",\n  // null type\n  VOID: \"null\",\n};\n"],"mappings":"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"}

package/dist/type-generator/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["sqlTypeToMarker: Record<string, string>","sqlTypeToHelper: Record<string, string>"],"sources":["../../src/type-generator/types.ts"],"sourcesContent":["/**\n * Databricks statement execution response interface for DESCRIBE QUERY\n * @property statement_id - the id of the statement\n * @property status - the status of the statement\n * @property result - the result containing column schema as rows [col_name, data_type, comment]\n */\nexport interface DatabricksStatementExecutionResponse {\n  statement_id: string;\n  status: { state: string };\n  result?: {\n    data_array?: (string | null)[][];\n  };\n}\n\n/**\n * Map of SQL types to their corresponding marker types\n * Used to convert SQL types to their corresponding marker types\n */\nexport const sqlTypeToMarker: Record<string, string> = {\n  // string\n  STRING: \"SQLStringMarker\",\n  BINARY: \"SQLBinaryMarker\",\n  // boolean\n  BOOLEAN: \"SQLBooleanMarker\",\n  // numeric\n  NUMERIC: \"SQLNumberMarker\",\n  INT: \"SQLNumberMarker\",\n  BIGINT: \"SQLNumberMarker\",\n  TINYINT: \"SQLNumberMarker\",\n  SMALLINT: \"SQLNumberMarker\",\n  FLOAT: \"SQLNumberMarker\",\n  DOUBLE: \"SQLNumberMarker\",\n  DECIMAL: \"SQLNumberMarker\",\n  // date/time\n  DATE: \"SQLDateMarker\",\n  TIMESTAMP: \"SQLTimestampMarker\",\n  TIMESTAMP_NTZ: \"SQLTimestampMarker\",\n};\n\n/**\n * Map of SQL types to their corresponding helper function names\n * Used to generate JSDoc hints for parameters\n */\nexport const sqlTypeToHelper: Record<string, string> = {\n  // string\n  STRING: \"sql.string()\",\n  BINARY: \"sql.binary()\",\n  // boolean\n  BOOLEAN: \"sql.boolean()\",\n  // numeric\n  NUMERIC: \"sql.number()\",\n  INT: \"sql.number()\",\n  BIGINT: \"sql.number()\",\n  TINYINT: \"sql.number()\",\n  SMALLINT: \"sql.number()\",\n  FLOAT: \"sql.number()\",\n  DOUBLE: \"sql.number()\",\n  DECIMAL: \"sql.number()\",\n  // date/time\n  DATE: \"sql.date()\",\n  TIMESTAMP: \"sql.timestamp()\",\n  TIMESTAMP_NTZ: \"sql.timestamp()\",\n};\n\n/**\n * Query schema interface\n * @property name - the name of the query\n * @property type - the type of the query (string, number, boolean, object, array, etc.)\n */\nexport interface QuerySchema {\n  name: string;\n  type: string;\n}\n"],"mappings":";;;;;AAkBA,MAAaA,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB;;;;;AAMD,MAAaC,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/type-generator/types.ts"],"sourcesContent":["/**\n * Databricks statement execution response interface for DESCRIBE QUERY\n * @property statement_id - the id of the statement\n * @property status - the status of the statement\n * @property result - the result containing column schema as rows [col_name, data_type, comment]\n */\nexport interface DatabricksStatementExecutionResponse {\n  statement_id: string;\n  status: { state: string };\n  result?: {\n    data_array?: (string | null)[][];\n  };\n}\n\n/**\n * Map of SQL types to their corresponding marker types\n * Used to convert SQL types to their corresponding marker types\n */\nexport const sqlTypeToMarker: Record<string, string> = {\n  // string\n  STRING: \"SQLStringMarker\",\n  BINARY: \"SQLBinaryMarker\",\n  // boolean\n  BOOLEAN: \"SQLBooleanMarker\",\n  // numeric\n  NUMERIC: \"SQLNumberMarker\",\n  INT: \"SQLNumberMarker\",\n  BIGINT: \"SQLNumberMarker\",\n  TINYINT: \"SQLNumberMarker\",\n  SMALLINT: \"SQLNumberMarker\",\n  FLOAT: \"SQLNumberMarker\",\n  DOUBLE: \"SQLNumberMarker\",\n  DECIMAL: \"SQLNumberMarker\",\n  // date/time\n  DATE: \"SQLDateMarker\",\n  TIMESTAMP: \"SQLTimestampMarker\",\n  TIMESTAMP_NTZ: \"SQLTimestampMarker\",\n};\n\n/**\n * Map of SQL types to their corresponding helper function names\n * Used to generate JSDoc hints for parameters\n */\nexport const sqlTypeToHelper: Record<string, string> = {\n  // string\n  STRING: \"sql.string()\",\n  BINARY: \"sql.binary()\",\n  // boolean\n  BOOLEAN: \"sql.boolean()\",\n  // numeric\n  NUMERIC: \"sql.number()\",\n  INT: \"sql.number()\",\n  BIGINT: \"sql.number()\",\n  TINYINT: \"sql.number()\",\n  SMALLINT: \"sql.number()\",\n  FLOAT: \"sql.number()\",\n  DOUBLE: \"sql.number()\",\n  DECIMAL: \"sql.number()\",\n  // date/time\n  DATE: \"sql.date()\",\n  TIMESTAMP: \"sql.timestamp()\",\n  TIMESTAMP_NTZ: \"sql.timestamp()\",\n};\n\n/**\n * Query schema interface\n * @property name - the name of the query\n * @property type - the type of the query (string, number, boolean, object, array, etc.)\n */\nexport interface QuerySchema {\n  name: string;\n  type: string;\n}\n"],"mappings":";;;;;AAkBA,MAAa,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB;;;;;AAMD,MAAa,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB"}

package/dist/type-generator/vite-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.d.ts","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":[],"mappings":";;;;;;AACmC;AAoBnC,UAbU,wBAAA,CAauB;EAAA,OAAA,CAAA,EAAA,MAAA;;cAAsC,CAAA,EAAA,MAAA,EAAA;;;;;;;;iBAAvD,iBAAA,WAA4B,2BAA2B"}
+{"version":3,"file":"vite-plugin.d.ts","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":[],"mappings":";;;;;;AAEmC;AAsBnC,UAbU,wBAAA,CAauB;EAAA,OAAA,CAAA,EAAA,MAAA;;cAAsC,CAAA,EAAA,MAAA,EAAA;;;;;;;;iBAAvD,iBAAA,WAA4B,2BAA2B"}

package/dist/type-generator/vite-plugin.js

@@ -1,8 +1,10 @@
+import { createLogger } from "../logging/logger.js";
 import { generateFromEntryPoint } from "./index.js";
 import path from "node:path";
 import fs from "node:fs";
 
 //#region src/type-generator/vite-plugin.ts
+const logger = createLogger("type-generator:vite-plugin");
 /**
 * Vite plugin to generate types for AppKit queries.
 * Calls generateFromEntryPoint under the hood.
@@ -17,7 +19,7 @@ function appKitTypesPlugin(options) {
 		try {
 			const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || "";
 			if (!warehouseId) {
-				console.warn("[AppKit] Warehouse ID not found. Skipping type generation.");
+				logger.debug("Warehouse ID not found. Skipping type generation.");
 				return;
 			}
 			await generateFromEntryPoint({
@@ -28,14 +30,14 @@ function appKitTypesPlugin(options) {
 			});
 		} catch (error) {
 			if (process.env.NODE_ENV === "production") throw error;
-			console.error("[AppKit] Error generating types:", error);
+			logger.error("Error generating types: %O", error);
 		}
 	}
 	return {
 		name: "appkit-types",
 		apply() {
 			if (!(process.env.DATABRICKS_WAREHOUSE_ID || "")) {
-				console.warn("[AppKit] Warehouse ID not found. Skipping type generation.");
+				logger.debug("Warehouse ID not found. Skipping type generation.");
 				return false;
 			}
 			if (!fs.existsSync(path.join(process.cwd(), "config", "queries"))) return false;

package/dist/type-generator/vite-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.js","names":["root: string","outFile: string","watchFolders: string[]"],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport fs from \"node:fs\";\nimport { generateFromEntryPoint } from \"./index\";\n\n/**\n * Options for the AppKit types plugin.\n */\ninterface AppKitTypesPluginOptions {\n  /* Path to the output d.ts file (relative to client folder). */\n  outFile?: string;\n  /** Folders to watch for changes. */\n  watchFolders?: string[];\n}\n\n/**\n * Vite plugin to generate types for AppKit queries.\n * Calls generateFromEntryPoint under the hood.\n * @param options - Options to override default values.\n * @returns Vite plugin to generate types for AppKit queries.\n */\nexport function appKitTypesPlugin(options?: AppKitTypesPluginOptions): Plugin {\n  let root: string;\n  let outFile: string;\n  let watchFolders: string[];\n\n  async function generate() {\n    try {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        console.warn(\n          \"[AppKit] Warehouse ID not found. Skipping type generation.\",\n        );\n        return;\n      }\n\n      await generateFromEntryPoint({\n        outFile,\n        queryFolder: watchFolders[0],\n        warehouseId,\n        noCache: false,\n      });\n    } catch (error) {\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        throw error;\n      }\n      console.error(\"[AppKit] Error generating types:\", error);\n    }\n  }\n\n  return {\n    name: \"appkit-types\",\n\n    apply() {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        console.warn(\n          \"[AppKit] Warehouse ID not found. Skipping type generation.\",\n        );\n        return false;\n      }\n\n      if (!fs.existsSync(path.join(process.cwd(), \"config\", \"queries\"))) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      root = config.root;\n      outFile = path.resolve(root, options?.outFile ?? \"src/appKitTypes.d.ts\");\n      watchFolders = options?.watchFolders ?? [\n        path.join(process.cwd(), \"config\", \"queries\"),\n      ];\n    },\n\n    buildStart() {\n      generate();\n    },\n\n    configureServer(server) {\n      server.watcher.add(watchFolders);\n\n      server.watcher.on(\"change\", (changedFile) => {\n        const isWatchedFile = watchFolders.some((folder) =>\n          changedFile.startsWith(folder),\n        );\n\n        if (isWatchedFile && changedFile.endsWith(\".sql\")) {\n          generate();\n        }\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;AAqBA,SAAgB,kBAAkB,SAA4C;CAC5E,IAAIA;CACJ,IAAIC;CACJ,IAAIC;CAEJ,eAAe,WAAW;AACxB,MAAI;GACF,MAAM,cAAc,QAAQ,IAAI,2BAA2B;AAE3D,OAAI,CAAC,aAAa;AAChB,YAAQ,KACN,6DACD;AACD;;AAGF,SAAM,uBAAuB;IAC3B;IACA,aAAa,aAAa;IAC1B;IACA,SAAS;IACV,CAAC;WACK,OAAO;AAEd,OAAI,QAAQ,IAAI,aAAa,aAC3B,OAAM;AAER,WAAQ,MAAM,oCAAoC,MAAM;;;AAI5D,QAAO;EACL,MAAM;EAEN,QAAQ;AAGN,OAAI,EAFgB,QAAQ,IAAI,2BAA2B,KAEzC;AAChB,YAAQ,KACN,6DACD;AACD,WAAO;;AAGT,OAAI,CAAC,GAAG,WAAW,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAAC,CAC/D,QAAO;AAGT,UAAO;;EAGT,eAAe,QAAQ;AACrB,UAAO,OAAO;AACd,aAAU,KAAK,QAAQ,MAAM,SAAS,WAAW,uBAAuB;AACxE,kBAAe,SAAS,gBAAgB,CACtC,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAC9C;;EAGH,aAAa;AACX,aAAU;;EAGZ,gBAAgB,QAAQ;AACtB,UAAO,QAAQ,IAAI,aAAa;AAEhC,UAAO,QAAQ,GAAG,WAAW,gBAAgB;AAK3C,QAJsB,aAAa,MAAM,WACvC,YAAY,WAAW,OAAO,CAC/B,IAEoB,YAAY,SAAS,OAAO,CAC/C,WAAU;KAEZ;;EAEL"}
+{"version":3,"file":"vite-plugin.js","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport { createLogger } from \"../logging/logger\";\nimport { generateFromEntryPoint } from \"./index\";\n\nconst logger = createLogger(\"type-generator:vite-plugin\");\n\n/**\n * Options for the AppKit types plugin.\n */\ninterface AppKitTypesPluginOptions {\n  /* Path to the output d.ts file (relative to client folder). */\n  outFile?: string;\n  /** Folders to watch for changes. */\n  watchFolders?: string[];\n}\n\n/**\n * Vite plugin to generate types for AppKit queries.\n * Calls generateFromEntryPoint under the hood.\n * @param options - Options to override default values.\n * @returns Vite plugin to generate types for AppKit queries.\n */\nexport function appKitTypesPlugin(options?: AppKitTypesPluginOptions): Plugin {\n  let root: string;\n  let outFile: string;\n  let watchFolders: string[];\n\n  async function generate() {\n    try {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return;\n      }\n\n      await generateFromEntryPoint({\n        outFile,\n        queryFolder: watchFolders[0],\n        warehouseId,\n        noCache: false,\n      });\n    } catch (error) {\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        throw error;\n      }\n      logger.error(\"Error generating types: %O\", error);\n    }\n  }\n\n  return {\n    name: \"appkit-types\",\n\n    apply() {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return false;\n      }\n\n      if (!fs.existsSync(path.join(process.cwd(), \"config\", \"queries\"))) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      root = config.root;\n      outFile = path.resolve(root, options?.outFile ?? \"src/appKitTypes.d.ts\");\n      watchFolders = options?.watchFolders ?? [\n        path.join(process.cwd(), \"config\", \"queries\"),\n      ];\n    },\n\n    buildStart() {\n      generate();\n    },\n\n    configureServer(server) {\n      server.watcher.add(watchFolders);\n\n      server.watcher.on(\"change\", (changedFile) => {\n        const isWatchedFile = watchFolders.some((folder) =>\n          changedFile.startsWith(folder),\n        );\n\n        if (isWatchedFile && changedFile.endsWith(\".sql\")) {\n          generate();\n        }\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;AAMA,MAAM,SAAS,aAAa,6BAA6B;;;;;;;AAkBzD,SAAgB,kBAAkB,SAA4C;CAC5E,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,eAAe,WAAW;AACxB,MAAI;GACF,MAAM,cAAc,QAAQ,IAAI,2BAA2B;AAE3D,OAAI,CAAC,aAAa;AAChB,WAAO,MAAM,oDAAoD;AACjE;;AAGF,SAAM,uBAAuB;IAC3B;IACA,aAAa,aAAa;IAC1B;IACA,SAAS;IACV,CAAC;WACK,OAAO;AAEd,OAAI,QAAQ,IAAI,aAAa,aAC3B,OAAM;AAER,UAAO,MAAM,8BAA8B,MAAM;;;AAIrD,QAAO;EACL,MAAM;EAEN,QAAQ;AAGN,OAAI,EAFgB,QAAQ,IAAI,2BAA2B,KAEzC;AAChB,WAAO,MAAM,oDAAoD;AACjE,WAAO;;AAGT,OAAI,CAAC,GAAG,WAAW,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAAC,CAC/D,QAAO;AAGT,UAAO;;EAGT,eAAe,QAAQ;AACrB,UAAO,OAAO;AACd,aAAU,KAAK,QAAQ,MAAM,SAAS,WAAW,uBAAuB;AACxE,kBAAe,SAAS,gBAAgB,CACtC,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAC9C;;EAGH,aAAa;AACX,aAAU;;EAGZ,gBAAgB,QAAQ;AACtB,UAAO,QAAQ,IAAI,aAAa;AAEhC,UAAO,QAAQ,GAAG,WAAW,gBAAgB;AAK3C,QAJsB,aAAa,MAAM,WACvC,YAAY,WAAW,OAAO,CAC/B,IAEoB,YAAY,SAAS,OAAO,CAC/C,WAAU;KAEZ;;EAEL"}

package/dist/utils/env-validator.js

@@ -1,14 +1,14 @@
-import { __esmMin } from "../_virtual/rolldown_runtime.js";
+import { ValidationError } from "../errors/validation.js";
+import { init_errors } from "../errors/index.js";
 
 //#region src/utils/env-validator.ts
+init_errors();
 function validateEnv(envVars) {
 	const missingVars = [];
 	for (const envVar of envVars) if (!process.env[envVar]) missingVars.push(envVar);
-	if (missingVars.length > 0) throw new Error(`Missing required environment variables: ${missingVars.join(", ")}`);
+	if (missingVars.length > 0) throw ValidationError.missingEnvVars(missingVars);
 }
-var init_env_validator = __esmMin((() => {}));
 
 //#endregion
-init_env_validator();
-export { init_env_validator, validateEnv };
+export { validateEnv };
 //# sourceMappingURL=env-validator.js.map

package/dist/utils/env-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-validator.js","names":[],"sources":["../../src/utils/env-validator.ts"],"sourcesContent":["export function validateEnv(envVars: string[]) {\n  const missingVars = [];\n\n  for (const envVar of envVars) {\n    if (!process.env[envVar]) {\n      missingVars.push(envVar);\n    }\n  }\n\n  if (missingVars.length > 0) {\n    throw new Error(\n      `Missing required environment variables: ${missingVars.join(\", \")}`,\n    );\n  }\n}\n"],"mappings":";;;AAAA,SAAgB,YAAY,SAAmB;CAC7C,MAAM,cAAc,EAAE;AAEtB,MAAK,MAAM,UAAU,QACnB,KAAI,CAAC,QAAQ,IAAI,QACf,aAAY,KAAK,OAAO;AAI5B,KAAI,YAAY,SAAS,EACvB,OAAM,IAAI,MACR,2CAA2C,YAAY,KAAK,KAAK,GAClE"}
+{"version":3,"file":"env-validator.js","names":[],"sources":["../../src/utils/env-validator.ts"],"sourcesContent":["import { ValidationError } from \"../errors\";\n\nexport function validateEnv(envVars: string[]) {\n  const missingVars = [];\n\n  for (const envVar of envVars) {\n    if (!process.env[envVar]) {\n      missingVars.push(envVar);\n    }\n  }\n\n  if (missingVars.length > 0) {\n    throw ValidationError.missingEnvVars(missingVars);\n  }\n}\n"],"mappings":";;;;aAA4C;AAE5C,SAAgB,YAAY,SAAmB;CAC7C,MAAM,cAAc,EAAE;AAEtB,MAAK,MAAM,UAAU,QACnB,KAAI,CAAC,QAAQ,IAAI,QACf,aAAY,KAAK,OAAO;AAI5B,KAAI,YAAY,SAAS,EACvB,OAAM,gBAAgB,eAAe,YAAY"}

package/dist/utils/merge.js

@@ -1,5 +1,3 @@
-import { __esmMin } from "../_virtual/rolldown_runtime.js";
-
 //#region src/utils/merge.ts
 function deepMerge(target, ...sources) {
 	if (!sources.length) return target;
@@ -17,9 +15,7 @@ function deepMerge(target, ...sources) {
 function isObject(item) {
 	return typeof item === "object" && item !== null && !Array.isArray(item);
 }
-var init_merge = __esmMin((() => {}));
 
 //#endregion
-init_merge();
-export { deepMerge, init_merge };
+export { deepMerge };
 //# sourceMappingURL=merge.js.map

package/dist/utils/merge.js.map

@@ -1 +1 @@
-{"version":3,"file":"merge.js","names":[],"sources":["../../src/utils/merge.ts"],"sourcesContent":["export function deepMerge<T extends Record<string, unknown>>(\n  target: T,\n  ...sources: Array<Partial<T> | undefined>\n): T {\n  if (!sources.length) return target;\n\n  const source = sources.shift();\n  if (!source) return deepMerge(target, ...sources);\n\n  const result = { ...target };\n\n  for (const key in source) {\n    const sourceValue = source[key];\n    const targetValue = result[key];\n\n    if (sourceValue !== undefined) {\n      if (isObject(sourceValue) && isObject(targetValue)) {\n        result[key] = deepMerge(\n          targetValue as Record<string, unknown>,\n          sourceValue as Record<string, unknown>,\n        ) as T[Extract<keyof T, string>];\n      } else {\n        result[key] = sourceValue as T[Extract<keyof T, string>];\n      }\n    }\n  }\n\n  return sources.length ? deepMerge(result, ...sources) : result;\n}\n\nfunction isObject(item: unknown): item is Record<string, unknown> {\n  return typeof item === \"object\" && item !== null && !Array.isArray(item);\n}\n"],"mappings":";;;AAAA,SAAgB,UACd,QACA,GAAG,SACA;AACH,KAAI,CAAC,QAAQ,OAAQ,QAAO;CAE5B,MAAM,SAAS,QAAQ,OAAO;AAC9B,KAAI,CAAC,OAAQ,QAAO,UAAU,QAAQ,GAAG,QAAQ;CAEjD,MAAM,SAAS,EAAE,GAAG,QAAQ;AAE5B,MAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,cAAc,OAAO;EAC3B,MAAM,cAAc,OAAO;AAE3B,MAAI,gBAAgB,OAClB,KAAI,SAAS,YAAY,IAAI,SAAS,YAAY,CAChD,QAAO,OAAO,UACZ,aACA,YACD;MAED,QAAO,OAAO;;AAKpB,QAAO,QAAQ,SAAS,UAAU,QAAQ,GAAG,QAAQ,GAAG;;AAG1D,SAAS,SAAS,MAAgD;AAChE,QAAO,OAAO,SAAS,YAAY,SAAS,QAAQ,CAAC,MAAM,QAAQ,KAAK"}
+{"version":3,"file":"merge.js","names":[],"sources":["../../src/utils/merge.ts"],"sourcesContent":["export function deepMerge<T extends Record<string, unknown>>(\n  target: T,\n  ...sources: Array<Partial<T> | undefined>\n): T {\n  if (!sources.length) return target;\n\n  const source = sources.shift();\n  if (!source) return deepMerge(target, ...sources);\n\n  const result = { ...target };\n\n  for (const key in source) {\n    const sourceValue = source[key];\n    const targetValue = result[key];\n\n    if (sourceValue !== undefined) {\n      if (isObject(sourceValue) && isObject(targetValue)) {\n        result[key] = deepMerge(\n          targetValue as Record<string, unknown>,\n          sourceValue as Record<string, unknown>,\n        ) as T[Extract<keyof T, string>];\n      } else {\n        result[key] = sourceValue as T[Extract<keyof T, string>];\n      }\n    }\n  }\n\n  return sources.length ? deepMerge(result, ...sources) : result;\n}\n\nfunction isObject(item: unknown): item is Record<string, unknown> {\n  return typeof item === \"object\" && item !== null && !Array.isArray(item);\n}\n"],"mappings":";AAAA,SAAgB,UACd,QACA,GAAG,SACA;AACH,KAAI,CAAC,QAAQ,OAAQ,QAAO;CAE5B,MAAM,SAAS,QAAQ,OAAO;AAC9B,KAAI,CAAC,OAAQ,QAAO,UAAU,QAAQ,GAAG,QAAQ;CAEjD,MAAM,SAAS,EAAE,GAAG,QAAQ;AAE5B,MAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,cAAc,OAAO;EAC3B,MAAM,cAAc,OAAO;AAE3B,MAAI,gBAAgB,OAClB,KAAI,SAAS,YAAY,IAAI,SAAS,YAAY,CAChD,QAAO,OAAO,UACZ,aACA,YACD;MAED,QAAO,OAAO;;AAKpB,QAAO,QAAQ,SAAS,UAAU,QAAQ,GAAG,QAAQ,GAAG;;AAG1D,SAAS,SAAS,MAAgD;AAChE,QAAO,OAAO,SAAS,YAAY,SAAS,QAAQ,CAAC,MAAM,QAAQ,KAAK"}