@workglow/util 0.0.115 → 0.0.116

package/dist/telemetry/ConsoleTelemetryProvider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ISpan, ITelemetryProvider, SpanOptions } from "./ITelemetryProvider";
+/**
+ * Lightweight telemetry provider that prints span summaries to console.
+ * Useful for local development without requiring a full OpenTelemetry stack.
+ */
+export declare class ConsoleTelemetryProvider implements ITelemetryProvider {
+    readonly isEnabled = true;
+    startSpan(name: string, options?: SpanOptions): ISpan;
+}
+//# sourceMappingURL=ConsoleTelemetryProvider.d.ts.map

package/dist/telemetry/ConsoleTelemetryProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleTelemetryProvider.d.ts","sourceRoot":"","sources":["../../src/telemetry/ConsoleTelemetryProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAkB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAwEnG;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,kBAAkB;IACjE,QAAQ,CAAC,SAAS,QAAQ;IAE1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK;CAGtD"}

package/dist/telemetry/ITelemetryProvider.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Attributes that can be attached to a span.
+ * Values follow OpenTelemetry attribute value conventions.
+ */
+export type SpanAttributes = Record<string, string | number | boolean | undefined>;
+/**
+ * Status codes for a span, matching OpenTelemetry conventions.
+ */
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+export type SpanStatusCode = (typeof SpanStatusCode)[keyof typeof SpanStatusCode];
+/**
+ * A handle to an active span. Call `end()` when the operation completes.
+ */
+export interface ISpan {
+    /** Record key-value attributes on the span. */
+    setAttributes(attributes: SpanAttributes): void;
+    /** Record a timestamped event (log) on the span. */
+    addEvent(name: string, attributes?: SpanAttributes): void;
+    /** Mark the span with a status code and optional message. */
+    setStatus(code: SpanStatusCode, message?: string): void;
+    /** End the span. Must be called exactly once. */
+    end(): void;
+}
+/**
+ * Options for starting a new span.
+ */
+export interface SpanOptions {
+    /** Attributes to set on the span at creation. */
+    attributes?: SpanAttributes;
+}
+/**
+ * Provider interface for telemetry instrumentation.
+ * Implementations bridge to OpenTelemetry, Datadog, or any APM backend.
+ *
+ * Register a provider via {@link setTelemetryProvider} to enable tracing
+ * across task-graph, job-queue, and ai-provider packages.
+ */
+export interface ITelemetryProvider {
+    /**
+     * Start a new span for the given operation.
+     *
+     * @param name - Dot-separated operation name, e.g. `"workglow.task.run"`
+     * @param options - Optional span configuration
+     * @returns A handle to the active span
+     */
+    startSpan(name: string, options?: SpanOptions): ISpan;
+    /**
+     * Whether the provider is actively collecting traces.
+     * When false, callers may skip expensive attribute computation.
+     */
+    readonly isEnabled: boolean;
+}
+//# sourceMappingURL=ITelemetryProvider.d.ts.map

package/dist/telemetry/ITelemetryProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITelemetryProvider.d.ts","sourceRoot":"","sources":["../../src/telemetry/ITelemetryProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;AAEnF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,+CAA+C;IAC/C,aAAa,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC;IAChD,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1D,6DAA6D;IAC7D,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,iDAAiD;IACjD,GAAG,IAAI,IAAI,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEtD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B"}

package/dist/telemetry/NoopTelemetryProvider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ISpan, ITelemetryProvider, SpanOptions } from "./ITelemetryProvider";
+/**
+ * Default no-op telemetry provider. All methods are zero-cost stubs.
+ * This is the default provider when no telemetry backend is configured.
+ */
+export declare class NoopTelemetryProvider implements ITelemetryProvider {
+    readonly isEnabled = false;
+    startSpan(_name: string, _options?: SpanOptions): ISpan;
+}
+//# sourceMappingURL=NoopTelemetryProvider.d.ts.map

package/dist/telemetry/NoopTelemetryProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoopTelemetryProvider.d.ts","sourceRoot":"","sources":["../../src/telemetry/NoopTelemetryProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAkB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAanG;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IAC9D,QAAQ,CAAC,SAAS,SAAS;IAE3B,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,KAAK;CAGxD"}

package/dist/telemetry/OTelTelemetryProvider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ISpan, ITelemetryProvider, SpanOptions } from "./ITelemetryProvider";
+/**
+ * Minimal subset of the OpenTelemetry `Tracer` interface that we depend on.
+ * This avoids a hard dependency on `@opentelemetry/api` while still being
+ * fully compatible with `trace.getTracer()`.
+ */
+export interface OTelTracer {
+    startSpan(name: string, options?: any, context?: any): OTelSpan;
+}
+/**
+ * Minimal subset of the OpenTelemetry `Span` interface.
+ */
+export interface OTelSpan {
+    setAttribute(key: string, value: string | number | boolean): any;
+    addEvent(name: string, attributes?: Record<string, any>): any;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): any;
+    end(): void;
+}
+/**
+ * Telemetry provider backed by a real OpenTelemetry tracer.
+ *
+ * @example
+ * ```ts
+ * import { trace } from "@opentelemetry/api";
+ * import { OTelTelemetryProvider, setTelemetryProvider } from "@workglow/util";
+ *
+ * const tracer = trace.getTracer("my-app", "1.0.0");
+ * setTelemetryProvider(new OTelTelemetryProvider(tracer));
+ * ```
+ */
+export declare class OTelTelemetryProvider implements ITelemetryProvider {
+    private readonly tracer;
+    readonly isEnabled = true;
+    constructor(tracer: OTelTracer);
+    startSpan(name: string, options?: SpanOptions): ISpan;
+}
+//# sourceMappingURL=OTelTelemetryProvider.d.ts.map

package/dist/telemetry/OTelTelemetryProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OTelTelemetryProvider.d.ts","sourceRoot":"","sources":["../../src/telemetry/OTelTelemetryProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAkB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnG;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,QAAQ,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,GAAG,CAAC;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;IAC9D,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,GAAG,CAAC;IAC3D,GAAG,IAAI,IAAI,CAAC;CACb;AAuCD;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IAGlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,SAAS,QAAQ;gBAEG,MAAM,EAAE,UAAU;IAE/C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK;CAUtD"}

package/dist/telemetry/TelemetryRegistry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITelemetryProvider } from "./ITelemetryProvider";
+/**
+ * Service token for the global telemetry provider instance.
+ */
+export declare const TELEMETRY_PROVIDER: import("../di").ServiceToken<ITelemetryProvider>;
+/**
+ * Returns the current global telemetry provider.
+ */
+export declare function getTelemetryProvider(): ITelemetryProvider;
+/**
+ * Replaces the global telemetry provider instance.
+ *
+ * @example
+ * ```ts
+ * import { OTelTelemetryProvider } from "@workglow/util";
+ * import { trace } from "@opentelemetry/api";
+ *
+ * setTelemetryProvider(new OTelTelemetryProvider(trace.getTracer("my-app")));
+ * ```
+ */
+export declare function setTelemetryProvider(provider: ITelemetryProvider): void;
+//# sourceMappingURL=TelemetryRegistry.d.ts.map

package/dist/telemetry/TelemetryRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelemetryRegistry.d.ts","sourceRoot":"","sources":["../../src/telemetry/TelemetryRegistry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D;;GAEG;AACH,eAAO,MAAM,kBAAkB,kDAAsD,CAAC;AA4BtF;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAEvE"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./ConsoleTelemetryProvider";
+export * from "./ITelemetryProvider";
+export * from "./NoopTelemetryProvider";
+export * from "./OTelTelemetryProvider";
+export * from "./TelemetryRegistry";
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@workglow/util",
   "type": "module",
-  "version": "0.0.115",
+  "version": "0.0.116",
   "description": "Utility functions and shared types for Workglow, providing common functionality across all packages.",
   "scripts": {
     "watch": "concurrently -c 'auto' 'bun:watch-*'",