@vercel/queue - npm Package Compare versions

Comparing version 0.3.1 to 0.4.0

dist/index.d.mts

@@ -125,2 +125,30 @@ /**
 /**
+ * Minimal structural stand-ins for the `@opentelemetry/api` types referenced by
+ * this SDK's public surface. They are defined locally rather than imported so
+ * the optional `@opentelemetry/api` peer never appears in the published
+ * `.d.ts` — otherwise consumers who don't install it fail to compile under the
+ * TypeScript default `skipLibCheck: false`. A real `@opentelemetry/api`
+ * `Tracer` / `AttributeValue` is structurally assignable to these.
+ */
+/** Subset of `@opentelemetry/api`'s `AttributeValue`. */
+type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+/** Subset of `@opentelemetry/api`'s `Span` produced when starting a span. */
+interface OtelSpan {
+    setAttribute(key: string, value: AttributeValue): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(): void;
+}
+/** Subset of `@opentelemetry/api`'s `Tracer` used by this SDK. */
+interface Tracer {
+    startSpan(name: string, options?: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+        links?: unknown[];
+    }, context?: unknown): OtelSpan;
+}
+
+/**
  * Vercel region code. The 20 known codes match
@@ -151,2 +179,52 @@ * {@link https://dcs.vercel-infra.com/ | dcs.vercel-infra.com}.
 type BaseUrlResolver = (region: string) => URL;
+/**
+ * Client-level OpenTelemetry configuration.
+ *
+ * Controls the optional trace correlation built into the client: the
+ * PRODUCER `vqs.send` span and W3C trace-context injection on `send()`,
+ * and trace-context extraction around callback handlers.
+ *
+ * The `VERCEL_QUEUE_TRACE_PROPAGATION=off` environment variable always takes
+ * precedence and disables tracing regardless of these options.
+ */
+interface TelemetryOptions {
+    /**
+     * Whether tracing (send spans, trace-context injection, and callback
+     * context extraction) is enabled for this client.
+     * Can be overridden per send via {@link SendTelemetryOptions.isEnabled}.
+     * @default true
+     */
+    isEnabled?: boolean;
+    /**
+     * Custom OpenTelemetry `Tracer` used to start `vqs.send` spans.
+     * @default trace.getTracer("@vercel/queue") from the global tracer provider
+     */
+    tracer?: Tracer;
+    /**
+     * Static attributes stamped on every `vqs.send` span. Keys are prefixed
+     * with `vqs.metadata.` to avoid colliding with semantic-convention
+     * attributes. Merged with per-send metadata; per-send values win on
+     * key conflicts.
+     */
+    metadata?: Record<string, AttributeValue>;
+}
+/**
+ * Per-send OpenTelemetry configuration overrides.
+ * See {@link TelemetryOptions} for the client-level configuration.
+ */
+interface SendTelemetryOptions {
+    /**
+     * Overrides the client-level `isEnabled` for this send only.
+     * The `VERCEL_QUEUE_TRACE_PROPAGATION=off` environment variable still
+     * takes precedence.
+     * @default the client-level setting (which defaults to true)
+     */
+    isEnabled?: boolean;
+    /**
+     * Attributes stamped on this send's `vqs.send` span, prefixed with
+     * `vqs.metadata.`. Merged over client-level metadata; values here win
+     * on key conflicts.
+     */
+    metadata?: Record<string, AttributeValue>;
+}
 interface QueueClientOptions {
@@ -229,2 +307,22 @@ /**
     dispatcher?: unknown;
+    /**
+     * OpenTelemetry configuration for this client.
+     *
+     * Applies to sends (the `vqs.send` span and trace-context injection) and
+     * to callback handlers created from this client (trace-context extraction).
+     * Tracing is enabled by default; requires `@opentelemetry/api` and a
+     * registered OTEL SDK to have any effect.
+     *
+     * @example
+     * ```ts
+     * new QueueClient({
+     *   telemetry: {
+     *     isEnabled: true,
+     *     tracer: myTracer,
+     *     metadata: { service: "billing" },
+     *   },
+     * });
+     * ```
+     */
+    telemetry?: TelemetryOptions;
 }
@@ -282,2 +380,8 @@ /**
     headers?: Record<string, string>;
+    /**
+     * OpenTelemetry overrides for this send only.
+     * `isEnabled` overrides the client-level setting; `metadata` is merged
+     * over client-level metadata (this send wins on key conflicts).
+     */
+    telemetry?: SendTelemetryOptions;
 }
@@ -910,2 +1014,2 @@ /**
 
-export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, TooManyRequestsError, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, type SendTelemetryOptions, StreamTransport, type TelemetryOptions, TooManyRequestsError, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };

dist/index.d.ts

@@ -125,2 +125,30 @@ /**
 /**
+ * Minimal structural stand-ins for the `@opentelemetry/api` types referenced by
+ * this SDK's public surface. They are defined locally rather than imported so
+ * the optional `@opentelemetry/api` peer never appears in the published
+ * `.d.ts` — otherwise consumers who don't install it fail to compile under the
+ * TypeScript default `skipLibCheck: false`. A real `@opentelemetry/api`
+ * `Tracer` / `AttributeValue` is structurally assignable to these.
+ */
+/** Subset of `@opentelemetry/api`'s `AttributeValue`. */
+type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+/** Subset of `@opentelemetry/api`'s `Span` produced when starting a span. */
+interface OtelSpan {
+    setAttribute(key: string, value: AttributeValue): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(): void;
+}
+/** Subset of `@opentelemetry/api`'s `Tracer` used by this SDK. */
+interface Tracer {
+    startSpan(name: string, options?: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+        links?: unknown[];
+    }, context?: unknown): OtelSpan;
+}
+
+/**
  * Vercel region code. The 20 known codes match
@@ -151,2 +179,52 @@ * {@link https://dcs.vercel-infra.com/ | dcs.vercel-infra.com}.
 type BaseUrlResolver = (region: string) => URL;
+/**
+ * Client-level OpenTelemetry configuration.
+ *
+ * Controls the optional trace correlation built into the client: the
+ * PRODUCER `vqs.send` span and W3C trace-context injection on `send()`,
+ * and trace-context extraction around callback handlers.
+ *
+ * The `VERCEL_QUEUE_TRACE_PROPAGATION=off` environment variable always takes
+ * precedence and disables tracing regardless of these options.
+ */
+interface TelemetryOptions {
+    /**
+     * Whether tracing (send spans, trace-context injection, and callback
+     * context extraction) is enabled for this client.
+     * Can be overridden per send via {@link SendTelemetryOptions.isEnabled}.
+     * @default true
+     */
+    isEnabled?: boolean;
+    /**
+     * Custom OpenTelemetry `Tracer` used to start `vqs.send` spans.
+     * @default trace.getTracer("@vercel/queue") from the global tracer provider
+     */
+    tracer?: Tracer;
+    /**
+     * Static attributes stamped on every `vqs.send` span. Keys are prefixed
+     * with `vqs.metadata.` to avoid colliding with semantic-convention
+     * attributes. Merged with per-send metadata; per-send values win on
+     * key conflicts.
+     */
+    metadata?: Record<string, AttributeValue>;
+}
+/**
+ * Per-send OpenTelemetry configuration overrides.
+ * See {@link TelemetryOptions} for the client-level configuration.
+ */
+interface SendTelemetryOptions {
+    /**
+     * Overrides the client-level `isEnabled` for this send only.
+     * The `VERCEL_QUEUE_TRACE_PROPAGATION=off` environment variable still
+     * takes precedence.
+     * @default the client-level setting (which defaults to true)
+     */
+    isEnabled?: boolean;
+    /**
+     * Attributes stamped on this send's `vqs.send` span, prefixed with
+     * `vqs.metadata.`. Merged over client-level metadata; values here win
+     * on key conflicts.
+     */
+    metadata?: Record<string, AttributeValue>;
+}
 interface QueueClientOptions {
@@ -229,2 +307,22 @@ /**
     dispatcher?: unknown;
+    /**
+     * OpenTelemetry configuration for this client.
+     *
+     * Applies to sends (the `vqs.send` span and trace-context injection) and
+     * to callback handlers created from this client (trace-context extraction).
+     * Tracing is enabled by default; requires `@opentelemetry/api` and a
+     * registered OTEL SDK to have any effect.
+     *
+     * @example
+     * ```ts
+     * new QueueClient({
+     *   telemetry: {
+     *     isEnabled: true,
+     *     tracer: myTracer,
+     *     metadata: { service: "billing" },
+     *   },
+     * });
+     * ```
+     */
+    telemetry?: TelemetryOptions;
 }
@@ -282,2 +380,8 @@ /**
     headers?: Record<string, string>;
+    /**
+     * OpenTelemetry overrides for this send only.
+     * `isEnabled` overrides the client-level setting; `metadata` is merged
+     * over client-level metadata (this send wins on key conflicts).
+     */
+    telemetry?: SendTelemetryOptions;
 }
@@ -910,2 +1014,2 @@ /**
 
-export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, StreamTransport, TooManyRequestsError, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };
+export { BadRequestError, type BaseUrlResolver, BufferTransport, CLOUD_EVENT_TYPE_V1BETA, CLOUD_EVENT_TYPE_V2BETA, ConsumerDiscoveryError, ConsumerRegistryNotConfiguredError, DuplicateMessageError, ForbiddenError, InternalServerError, InvalidLimitError, JsonTransport, type Message, MessageAlreadyProcessedError, MessageCorruptedError, type MessageHandler, MessageLockedError, type MessageMetadata, MessageNotAvailableError, MessageNotFoundError, type ParsedCallbackRequest, type ParsedCallbackV1, type ParsedCallbackV2, PollingQueueClient, type PollingQueueClientOptions, QueueClient, type QueueClientOptions, QueueEmptyError, type ReceiveBatchOptions, type ReceiveByIdOptions, type ReceiveOptions, type ReceiveResult, type RegisterDevConsumerOptions, type RetryDirective, type RetryHandler, type SendOptions, type SendResult, type SendTelemetryOptions, StreamTransport, type TelemetryOptions, TooManyRequestsError, type Transport, UnauthorizedError, type VercelRegion, handleCallback, parseCallback, parseRawCallback, registerDevConsumer, send };

package.json

 {
   "name": "@vercel/queue",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "publishConfig": {
@@ -44,4 +44,15 @@ "access": "public"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.52.8",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.0.0",
+    "@opentelemetry/core": "^2.0.0",
     "@types/minimatch": "^6.0.0",
@@ -48,0 +59,0 @@ "@types/node": "^22.15.24",

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

704789

10.45%

Lines of code

6298

9.21%

Worsened metrics

Dependency count

5

25%

Dev dependency count

11

37.5%

Number of low supply chain risk alerts

26

18.18%

No dependency changes