@uploadista/observability 0.0.3

package/dist/core/testing.js

@@ -0,0 +1,93 @@
+import { Effect, Layer, Metric } from "effect";
+import { FlowObservability, StorageObservability, UploadObservability, } from "./layers.js";
+import { createStorageMetrics } from "./metrics.js";
+// ============================================================================
+// Test Observability Layers
+// ============================================================================
+/**
+ * Mock storage observability for testing
+ */
+export const makeTestStorageObservability = (storageType) => {
+    const metrics = createStorageMetrics(storageType);
+    const service = {
+        serviceName: `test-${storageType}-store`,
+        storageType,
+        metrics,
+        enabled: true,
+    };
+    return Layer.succeed(StorageObservability, service);
+};
+/**
+ * Mock upload observability for testing
+ */
+export const makeTestUploadObservability = () => {
+    const service = {
+        serviceName: "test-upload-server",
+        enabled: true,
+        metrics: {
+            uploadCreated: Effect.void,
+            uploadCompleted: Effect.void,
+            uploadFailed: Effect.void,
+            chunkUploaded: Effect.void,
+        },
+    };
+    return Layer.succeed(UploadObservability, service);
+};
+/**
+ * Mock flow observability for testing
+ */
+export const makeTestFlowObservability = () => {
+    const service = {
+        serviceName: "test-flow-engine",
+        enabled: true,
+        metrics: {
+            flowStarted: Effect.void,
+            flowCompleted: Effect.void,
+            flowFailed: Effect.void,
+            nodeExecuted: Effect.void,
+        },
+    };
+    return Layer.succeed(FlowObservability, service);
+};
+// ============================================================================
+// Test Utilities
+// ============================================================================
+/**
+ * Capture metrics snapshot from an effect for testing
+ * Note: Metric snapshots are simplified - for full metric testing,
+ * use Effect's built-in metric testing utilities
+ */
+export const captureMetrics = (effect) => Effect.gen(function* () {
+    const result = yield* effect;
+    // Metrics are automatically captured by Effect runtime
+    yield* Metric.snapshot;
+    return result;
+});
+/**
+ * Test helper to capture metrics around effect execution
+ * This is a simplified version - for production testing,
+ * use Effect's metric testing utilities
+ */
+export const withMetricTracking = (effect) => Effect.gen(function* () {
+    // Track metric before execution
+    yield* Metric.snapshot;
+    const result = yield* effect;
+    // Track metric after execution
+    yield* Metric.snapshot;
+    return result;
+});
+/**
+ * Create a complete test fixture with all observability layers
+ */
+export const createTestFixture = (storageType = "test-storage") => ({
+    storageObservability: makeTestStorageObservability(storageType),
+    uploadObservability: makeTestUploadObservability(),
+    flowObservability: makeTestFlowObservability(),
+});
+/**
+ * Run an effect with test observability layers
+ */
+export const runWithTestObservability = (effect, storageType = "test-storage") => {
+    const fixture = createTestFixture(storageType);
+    return effect.pipe(Effect.provide(fixture.storageObservability), Effect.provide(fixture.uploadObservability), Effect.provide(fixture.flowObservability));
+};

package/dist/core/tracing.d.ts

@@ -0,0 +1,19 @@
+import { Context, Effect, Layer } from "effect";
+export declare const TracingService: Context.Tag<{
+    serviceName: string;
+}, {
+    serviceName: string;
+}>;
+export declare const createTracingLayer: (options?: {
+    serviceName?: string;
+}) => Layer.Layer<{
+    serviceName: string;
+}, never, never>;
+export declare const createStorageTracingLayer: (storageType: string) => Layer.Layer<{
+    serviceName: string;
+}, never, never>;
+export declare const withStorageSpan: <A, E, R>(operation: string, storageType: string, attributes?: Record<string, unknown>) => (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, import("effect/Tracer").ParentSpan>>;
+export declare const WebSdkLive: Layer.Layer<import("@effect/opentelemetry/Resource").Resource, never, never>;
+export declare const NodeSdkLive: Layer.Layer<import("@effect/opentelemetry/Resource").Resource, never, never>;
+export declare const WorkersSdkLive: Layer.Layer<import("@effect/opentelemetry/Resource").Resource, never, never>;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/core/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/core/tracing.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAOhD,eAAO,MAAM,cAAc;iBAAqC,MAAM;;iBAAN,MAAM;EAErE,CAAC;AAGF,eAAO,MAAM,kBAAkB,GAAI,UAAU;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;iBALL,MAAM;gBAUrE,CAAC;AAGF,eAAO,MAAM,yBAAyB,GAAI,aAAa,MAAM;iBAbG,MAAM;gBAgBlE,CAAC;AAGL,eAAO,MAAM,eAAe,GACzB,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,WAAW,MAAM,EACjB,aAAa,MAAM,EACnB,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAErC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,wEAS5B,CAAC;AAGN,eAAO,MAAM,UAAU,8EAIpB,CAAC;AAEJ,eAAO,MAAM,WAAW,8EAIrB,CAAC;AAGJ,eAAO,MAAM,cAAc,8EAIxB,CAAC"}

package/dist/core/tracing.js

@@ -0,0 +1,43 @@
+import { NodeSdk, WebSdk } from "@effect/opentelemetry";
+import { BatchSpanProcessor, ConsoleSpanExporter, } from "@opentelemetry/sdk-trace-base";
+import { Context, Effect, Layer } from "effect";
+// ============================================================================
+// Universal Tracing (Environment-agnostic)
+// ============================================================================
+// Generic service tag for tracing context
+export const TracingService = Context.GenericTag("TracingService");
+// Create a tracing layer using Effect's native tracing (works in all environments)
+export const createTracingLayer = (options) => {
+    const serviceName = options?.serviceName ?? "uploadista-storage";
+    // Return a layer that provides tracing service context
+    return Layer.succeed(TracingService, { serviceName });
+};
+// Storage-specific tracing layers
+export const createStorageTracingLayer = (storageType) => createTracingLayer({
+    serviceName: `uploadista-${storageType}-store`,
+});
+// Utility to add storage context to spans
+export const withStorageSpan = (operation, storageType, attributes) => (effect) => effect.pipe(Effect.withSpan(`${storageType}-${operation}`, {
+    attributes: {
+        "storage.type": storageType,
+        operation: operation,
+        ...attributes,
+    },
+}));
+// Set up tracing with the OpenTelemetry SDK
+export const WebSdkLive = WebSdk.layer(() => ({
+    resource: { serviceName: "uploadista-storage" },
+    // Export span data to the console
+    spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter()),
+}));
+export const NodeSdkLive = NodeSdk.layer(() => ({
+    resource: { serviceName: "uploadista-storage" },
+    // Export span data to the console
+    spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter()),
+}));
+// Cloudflare Workers SDK (uses WebSdk as base)
+export const WorkersSdkLive = WebSdk.layer(() => ({
+    resource: { serviceName: "uploadista-storage-workers" },
+    // Export span data to the console in Workers environment
+    spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter()),
+}));

package/dist/core/utilities.d.ts

@@ -0,0 +1,11 @@
+import { Effect, Metric } from "effect";
+import type { StorageMetrics } from "./metrics.js";
+export declare const withUploadMetrics: <A, E, R>(metrics: StorageMetrics, uploadId: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const withApiMetrics: <A, E, R>(metrics: StorageMetrics, operation: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const withTimingMetrics: <A, E, R>(metric: Metric.Metric.Histogram<number>, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const trackFileSize: <A, E, R>(metrics: StorageMetrics, fileSize: number, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const trackPartSize: <A, E, R>(metrics: StorageMetrics, partSize: number, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const withActiveUploadTracking: <A, E, R>(metrics: StorageMetrics, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const withThroughputTracking: <A, E, R>(metrics: StorageMetrics, bytes: number, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const withStorageOperationMetrics: <A, E, R>(metrics: StorageMetrics, operation: string, uploadId: string, effect: Effect.Effect<A, E, R>, fileSize?: number) => Effect.Effect<A, E, R>;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/core/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../../src/core/utilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAOnD,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACvC,SAAS,cAAc,EACvB,UAAU,MAAM,EAChB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAiBrB,CAAC;AAGJ,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACpC,SAAS,cAAc,EACvB,WAAW,MAAM,EACjB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAOrB,CAAC;AAGJ,eAAO,MAAM,iBAAiB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACvC,QAAQ,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EACvC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAUpB,CAAC;AAGL,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACnC,SAAS,cAAc,EACvB,UAAU,MAAM,EAChB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAGrB,CAAC;AAGJ,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACnC,SAAS,cAAc,EACvB,UAAU,MAAM,EAChB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAGrB,CAAC;AAGJ,eAAO,MAAM,wBAAwB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAC9C,SAAS,cAAc,EACvB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAIrB,CAAC;AAGJ,eAAO,MAAM,sBAAsB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAC5C,SAAS,cAAc,EACvB,OAAO,MAAM,EACb,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAWpB,CAAC;AAGL,eAAO,MAAM,2BAA2B,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACjD,SAAS,cAAc,EACvB,WAAW,MAAM,EACjB,UAAU,MAAM,EAChB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,WAAW,MAAM,KAChB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAgBvB,CAAC"}

package/dist/core/utilities.js

@@ -0,0 +1,41 @@
+import { Effect, Metric } from "effect";
+// ============================================================================
+// Storage Observability Utility Functions
+// ============================================================================
+// Generic upload metrics wrapper
+export const withUploadMetrics = (metrics, uploadId, effect) => effect.pipe(Effect.tap(() => metrics.uploadRequestsTotal.pipe(Metric.tagged("upload_id", uploadId))(Effect.succeed(1))), Effect.tapError(() => metrics.uploadErrorsTotal.pipe(Metric.tagged("upload_id", uploadId))(Effect.succeed(1))), Effect.tap(() => metrics.uploadSuccessTotal.pipe(Metric.tagged("upload_id", uploadId))(Effect.succeed(1))));
+// Generic API call metrics wrapper
+export const withApiMetrics = (metrics, operation, effect) => effect.pipe(Effect.tap(() => metrics.apiCallsTotal.pipe(Metric.tagged("operation", operation))(Effect.succeed(1))));
+// Generic timing metrics wrapper
+export const withTimingMetrics = (metric, effect) => Effect.gen(function* () {
+    const startTime = yield* Effect.sync(() => Date.now());
+    const result = yield* effect;
+    const endTime = yield* Effect.sync(() => Date.now());
+    const duration = (endTime - startTime) / 1000; // Convert to seconds
+    yield* metric(Effect.succeed(duration));
+    return result;
+});
+// File size tracking
+export const trackFileSize = (metrics, fileSize, effect) => effect.pipe(Effect.tap(() => metrics.fileSizeHistogram(Effect.succeed(fileSize))));
+// Part size tracking
+export const trackPartSize = (metrics, partSize, effect) => effect.pipe(Effect.tap(() => metrics.partSizeHistogram(Effect.succeed(partSize))));
+// Active uploads tracking
+export const withActiveUploadTracking = (metrics, effect) => effect.pipe(Effect.tap(() => metrics.activeUploadsGauge(Effect.succeed(1))), Effect.ensuring(metrics.activeUploadsGauge(Effect.succeed(-1))));
+// Throughput calculation and tracking
+export const withThroughputTracking = (metrics, bytes, effect) => Effect.gen(function* () {
+    const startTime = yield* Effect.sync(() => Date.now());
+    const result = yield* effect;
+    const endTime = yield* Effect.sync(() => Date.now());
+    const durationSeconds = (endTime - startTime) / 1000;
+    const throughputBps = durationSeconds > 0 ? bytes / durationSeconds : 0;
+    yield* metrics.uploadThroughputGauge(Effect.succeed(throughputBps));
+    return result;
+});
+// Combined metrics wrapper for common upload operations
+export const withStorageOperationMetrics = (metrics, operation, uploadId, effect, fileSize) => {
+    let wrappedEffect = effect.pipe((eff) => withApiMetrics(metrics, operation, eff), (eff) => withUploadMetrics(metrics, uploadId, eff), (eff) => withTimingMetrics(metrics.uploadDurationHistogram, eff), (eff) => withActiveUploadTracking(metrics, eff));
+    if (fileSize !== undefined) {
+        wrappedEffect = wrappedEffect.pipe((eff) => trackFileSize(metrics, fileSize, eff), (eff) => withThroughputTracking(metrics, fileSize, eff));
+    }
+    return wrappedEffect;
+};

package/dist/flow/errors.d.ts

@@ -0,0 +1,15 @@
+import { Effect } from "effect";
+export type FlowErrorCategory = "flow_validation_error" | "node_execution_error" | "node_not_found_error" | "flow_timeout_error" | "flow_cancelled_error" | "unknown_flow_error";
+/**
+ * Classify flow execution errors
+ */
+export declare const classifyFlowError: (error: unknown) => FlowErrorCategory;
+/**
+ * Track flow errors with classification
+ */
+export declare const trackFlowError: <E>(error: E) => Effect.Effect<void, never, never>;
+/**
+ * Track node errors with classification
+ */
+export declare const trackNodeError: <E>(nodeId: string, nodeType: string, error: E) => Effect.Effect<void, never, never>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/flow/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/flow/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AAOxC,MAAM,MAAM,iBAAiB,GACzB,uBAAuB,GACvB,sBAAsB,GACtB,sBAAsB,GACtB,oBAAoB,GACpB,sBAAsB,GACtB,oBAAoB,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,iBA0BlD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,OAAO,CAAC,KACP,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAgBlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,QAAQ,MAAM,EACd,UAAU,MAAM,EAChB,OAAO,CAAC,KACP,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAkBlC,CAAC"}

package/dist/flow/errors.js

@@ -0,0 +1,66 @@
+import { Effect, Metric } from "effect";
+import { createFlowMetrics } from "./metrics.js";
+/**
+ * Classify flow execution errors
+ */
+export const classifyFlowError = (error) => {
+    if (!error || typeof error !== "object")
+        return "unknown_flow_error";
+    const errorCode = "code" in error ? error.code : undefined;
+    if (!errorCode)
+        return "unknown_flow_error";
+    // Flow-specific error codes
+    switch (errorCode) {
+        case "FLOW_VALIDATION_ERROR":
+        case "FLOW_INVALID_INPUT":
+        case "FLOW_INVALID_OUTPUT":
+            return "flow_validation_error";
+        case "FLOW_NODE_NOT_FOUND":
+        case "FLOW_EDGE_INVALID":
+            return "node_not_found_error";
+        case "FLOW_NODE_EXECUTION_FAILED":
+        case "FLOW_NODE_ERROR":
+            return "node_execution_error";
+        case "FLOW_TIMEOUT":
+            return "flow_timeout_error";
+        case "FLOW_CANCELLED":
+        case "ABORTED":
+            return "flow_cancelled_error";
+        default:
+            return "unknown_flow_error";
+    }
+};
+/**
+ * Track flow errors with classification
+ */
+export const trackFlowError = (error) => {
+    const metrics = createFlowMetrics();
+    const category = classifyFlowError(error);
+    return Effect.gen(function* () {
+        // Increment total failed flows
+        yield* Metric.increment(metrics.flowFailedTotal);
+        // Log error with classification
+        yield* Effect.logError("Flow execution failed").pipe(Effect.annotateLogs({
+            "error.category": category,
+            "error.message": String(error),
+        }));
+    });
+};
+/**
+ * Track node errors with classification
+ */
+export const trackNodeError = (nodeId, nodeType, error) => {
+    const metrics = createFlowMetrics();
+    const category = classifyFlowError(error);
+    return Effect.gen(function* () {
+        // Increment node failed counter
+        yield* Metric.increment(metrics.nodeFailedTotal);
+        // Log error with node context
+        yield* Effect.logError("Node execution failed").pipe(Effect.annotateLogs({
+            "node.id": nodeId,
+            "node.type": nodeType,
+            "error.category": category,
+            "error.message": String(error),
+        }));
+    });
+};

package/dist/flow/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./metrics.js";
+export * from "./tracing.js";
+export { makeFlowObservabilityLive, FlowObservabilityLive, getFlowMetrics, withFlowDuration, withNodeDuration, trackActiveFlow, trackActiveNode, } from "./layers.js";
+export * from "./errors.js";
+export { makeTestFlowObservability as makeTestFlowObservabilityUtil, runWithTestFlowObservability, } from "./testing.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/flow/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,yBAAyB,IAAI,6BAA6B,EAC1D,4BAA4B,GAC7B,MAAM,cAAc,CAAC"}

package/dist/flow/index.js

@@ -0,0 +1,6 @@
+// Flow observability exports
+export * from "./metrics.js";
+export * from "./tracing.js";
+export { makeFlowObservabilityLive, FlowObservabilityLive, getFlowMetrics, withFlowDuration, withNodeDuration, trackActiveFlow, trackActiveNode, } from "./layers.js";
+export * from "./errors.js";
+export { makeTestFlowObservability as makeTestFlowObservabilityUtil, runWithTestFlowObservability, } from "./testing.js";

package/dist/flow/layers.d.ts

@@ -0,0 +1,40 @@
+import { Effect, Layer } from "effect";
+import { FlowObservability } from "../core/layers.js";
+/**
+ * Create a live flow observability layer with full metrics
+ */
+export declare const makeFlowObservabilityLive: (serviceName?: string) => Layer.Layer<FlowObservability>;
+/**
+ * Default live flow observability layer
+ */
+export declare const FlowObservabilityLive: Layer.Layer<FlowObservability, never, never>;
+/**
+ * No-op flow observability layer (for testing or disabled observability)
+ */
+export declare const FlowObservabilityDisabled: Layer.Layer<FlowObservability, never, never>;
+/**
+ * Helper to get flow metrics from context
+ */
+export declare const getFlowMetrics: Effect.Effect<{
+    flowStarted: Effect.Effect<void>;
+    flowCompleted: Effect.Effect<void>;
+    flowFailed: Effect.Effect<void>;
+    nodeExecuted: Effect.Effect<void>;
+}, never, FlowObservability>;
+/**
+ * Helper to track flow duration
+ */
+export declare const withFlowDuration: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Helper to track node duration
+ */
+export declare const withNodeDuration: <A, E, R>(nodeId: string, nodeType: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Helper to track active flows
+ */
+export declare const trackActiveFlow: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Helper to track active nodes
+ */
+export declare const trackActiveNode: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+//# sourceMappingURL=layers.d.ts.map

package/dist/flow/layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../src/flow/layers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAU,MAAM,QAAQ,CAAC;AAC/C,OAAO,EACL,iBAAiB,EAElB,MAAM,mBAAmB,CAAC;AAO3B;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACpC,oBAAsC,KACrC,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAa/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,8CAA8B,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,yBAAyB,8CAAoC,CAAC;AAE3E;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;4BAGzB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACtC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAUvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACtC,QAAQ,MAAM,EACd,UAAU,MAAM,EAChB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAiBvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACrC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAavB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACrC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAavB,CAAC"}

package/dist/flow/layers.js

@@ -0,0 +1,94 @@
+import { Effect, Layer, Metric } from "effect";
+import { FlowObservability, makeFlowObservabilityLayer, } from "../core/layers.js";
+import { createFlowMetrics } from "./metrics.js";
+// ============================================================================
+// Flow Observability Layer Implementation
+// ============================================================================
+/**
+ * Create a live flow observability layer with full metrics
+ */
+export const makeFlowObservabilityLive = (serviceName = "uploadista-flow-engine") => {
+    const metrics = createFlowMetrics();
+    return Layer.succeed(FlowObservability, {
+        serviceName,
+        enabled: true,
+        metrics: {
+            flowStarted: Metric.increment(metrics.flowStartedTotal),
+            flowCompleted: Metric.increment(metrics.flowCompletedTotal),
+            flowFailed: Metric.increment(metrics.flowFailedTotal),
+            nodeExecuted: Metric.increment(metrics.nodeExecutedTotal),
+        },
+    });
+};
+/**
+ * Default live flow observability layer
+ */
+export const FlowObservabilityLive = makeFlowObservabilityLive();
+/**
+ * No-op flow observability layer (for testing or disabled observability)
+ */
+export const FlowObservabilityDisabled = makeFlowObservabilityLayer(false);
+/**
+ * Helper to get flow metrics from context
+ */
+export const getFlowMetrics = Effect.gen(function* () {
+    const obs = yield* FlowObservability;
+    return obs.metrics;
+});
+/**
+ * Helper to track flow duration
+ */
+export const withFlowDuration = (effect) => {
+    const metrics = createFlowMetrics();
+    return Effect.gen(function* () {
+        const startTime = Date.now();
+        const result = yield* effect;
+        const duration = (Date.now() - startTime) / 1000; // Convert to seconds
+        yield* Metric.update(metrics.flowDurationHistogram, duration);
+        yield* Metric.update(metrics.flowLatencySummary, duration);
+        return result;
+    }).pipe(Effect.withSpan("flow-execution"));
+};
+/**
+ * Helper to track node duration
+ */
+export const withNodeDuration = (nodeId, nodeType, effect) => {
+    const metrics = createFlowMetrics();
+    return Effect.gen(function* () {
+        const startTime = Date.now();
+        const result = yield* effect;
+        const duration = (Date.now() - startTime) / 1000; // Convert to seconds
+        yield* Metric.update(metrics.nodeDurationHistogram, duration);
+        yield* Metric.update(metrics.nodeLatencySummary, duration);
+        return result;
+    }).pipe(Effect.withSpan(`node-${nodeType}`, {
+        attributes: {
+            "node.id": nodeId,
+            "node.type": nodeType,
+        },
+    }));
+};
+/**
+ * Helper to track active flows
+ */
+export const trackActiveFlow = (effect) => {
+    const metrics = createFlowMetrics();
+    return Effect.gen(function* () {
+        // Increment active flows
+        yield* Metric.increment(metrics.activeFlowsGauge);
+        // Use acquireUseRelease for proper cleanup
+        return yield* Effect.acquireUseRelease(Effect.void, () => effect, () => Metric.set(metrics.activeFlowsGauge, -1));
+    });
+};
+/**
+ * Helper to track active nodes
+ */
+export const trackActiveNode = (effect) => {
+    const metrics = createFlowMetrics();
+    return Effect.gen(function* () {
+        // Increment active nodes
+        yield* Metric.increment(metrics.activeNodesGauge);
+        // Use acquireUseRelease for proper cleanup
+        return yield* Effect.acquireUseRelease(Effect.void, () => effect, () => Metric.set(metrics.activeNodesGauge, -1));
+    });
+};

package/dist/flow/metrics.d.ts

@@ -0,0 +1,52 @@
+import { Metric } from "effect";
+/**
+ * Flow engine metrics for tracking flow execution operations
+ */
+export declare const createFlowMetrics: () => {
+    flowStartedTotal: Metric.Metric.Counter<number>;
+    flowCompletedTotal: Metric.Metric.Counter<number>;
+    flowFailedTotal: Metric.Metric.Counter<number>;
+    flowPausedTotal: Metric.Metric.Counter<number>;
+    flowResumedTotal: Metric.Metric.Counter<number>;
+    nodeExecutedTotal: Metric.Metric.Counter<number>;
+    nodeSuccessTotal: Metric.Metric.Counter<number>;
+    nodeFailedTotal: Metric.Metric.Counter<number>;
+    nodeSkippedTotal: Metric.Metric.Counter<number>;
+    flowDurationHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    nodeDurationHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    flowNodeCountHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    parallelNodesHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    activeFlowsGauge: Metric.Metric.Gauge<number>;
+    activeNodesGauge: Metric.Metric.Gauge<number>;
+    pausedFlowsGauge: Metric.Metric.Gauge<number>;
+    flowLatencySummary: Metric.Metric.Summary<number>;
+    nodeLatencySummary: Metric.Metric.Summary<number>;
+};
+/**
+ * Type for flow metrics
+ */
+export type FlowMetrics = ReturnType<typeof createFlowMetrics>;
+/**
+ * Default flow metrics instance
+ */
+export declare const flowMetrics: {
+    flowStartedTotal: Metric.Metric.Counter<number>;
+    flowCompletedTotal: Metric.Metric.Counter<number>;
+    flowFailedTotal: Metric.Metric.Counter<number>;
+    flowPausedTotal: Metric.Metric.Counter<number>;
+    flowResumedTotal: Metric.Metric.Counter<number>;
+    nodeExecutedTotal: Metric.Metric.Counter<number>;
+    nodeSuccessTotal: Metric.Metric.Counter<number>;
+    nodeFailedTotal: Metric.Metric.Counter<number>;
+    nodeSkippedTotal: Metric.Metric.Counter<number>;
+    flowDurationHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    nodeDurationHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    flowNodeCountHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    parallelNodesHistogram: Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    activeFlowsGauge: Metric.Metric.Gauge<number>;
+    activeNodesGauge: Metric.Metric.Gauge<number>;
+    pausedFlowsGauge: Metric.Metric.Gauge<number>;
+    flowLatencySummary: Metric.Metric.Summary<number>;
+    nodeLatencySummary: Metric.Metric.Summary<number>;
+};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/flow/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/flow/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,QAAQ,CAAC;AAMlD;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;CA8G5B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;CAAsB,CAAC"}

package/dist/flow/metrics.js

@@ -0,0 +1,89 @@
+import { Metric, MetricBoundaries } from "effect";
+// ============================================================================
+// Flow Engine Metrics
+// ============================================================================
+/**
+ * Flow engine metrics for tracking flow execution operations
+ */
+export const createFlowMetrics = () => ({
+    // Counter metrics
+    flowStartedTotal: Metric.counter("flow_started_total", {
+        description: "Total number of flows started",
+    }),
+    flowCompletedTotal: Metric.counter("flow_completed_total", {
+        description: "Total number of flows completed successfully",
+    }),
+    flowFailedTotal: Metric.counter("flow_failed_total", {
+        description: "Total number of flows that failed",
+    }),
+    flowPausedTotal: Metric.counter("flow_paused_total", {
+        description: "Total number of flows that were paused",
+    }),
+    flowResumedTotal: Metric.counter("flow_resumed_total", {
+        description: "Total number of flows that were resumed",
+    }),
+    nodeExecutedTotal: Metric.counter("node_executed_total", {
+        description: "Total number of nodes executed",
+    }),
+    nodeSuccessTotal: Metric.counter("node_success_total", {
+        description: "Total number of nodes executed successfully",
+    }),
+    nodeFailedTotal: Metric.counter("node_failed_total", {
+        description: "Total number of nodes that failed",
+    }),
+    nodeSkippedTotal: Metric.counter("node_skipped_total", {
+        description: "Total number of nodes skipped (conditional)",
+    }),
+    // Histogram metrics
+    flowDurationHistogram: Metric.histogram("flow_duration_seconds", MetricBoundaries.exponential({
+        start: 0.1, // 100ms
+        factor: 2,
+        count: 20, // Up to ~100 seconds
+    }), "Duration of complete flow execution in seconds"),
+    nodeDurationHistogram: Metric.histogram("node_duration_seconds", MetricBoundaries.exponential({
+        start: 0.01, // 10ms
+        factor: 2,
+        count: 18, // Up to ~26 seconds
+    }), "Duration of individual node execution in seconds"),
+    flowNodeCountHistogram: Metric.histogram("flow_node_count", MetricBoundaries.linear({
+        start: 1,
+        width: 5,
+        count: 20, // Up to 100 nodes
+    }), "Number of nodes in a flow"),
+    parallelNodesHistogram: Metric.histogram("parallel_nodes_count", MetricBoundaries.linear({
+        start: 1,
+        width: 2,
+        count: 15, // Up to 30 parallel nodes
+    }), "Number of nodes executed in parallel"),
+    // Gauge metrics
+    activeFlowsGauge: Metric.gauge("active_flows", {
+        description: "Number of currently active flows",
+    }),
+    activeNodesGauge: Metric.gauge("active_nodes", {
+        description: "Number of currently executing nodes",
+    }),
+    pausedFlowsGauge: Metric.gauge("paused_flows", {
+        description: "Number of currently paused flows",
+    }),
+    // Summary metrics for latency percentiles
+    flowLatencySummary: Metric.summary({
+        name: "flow_latency_seconds",
+        maxAge: "10 minutes",
+        maxSize: 1000,
+        error: 0.01,
+        quantiles: [0.5, 0.9, 0.95, 0.99],
+        description: "Flow execution latency percentiles",
+    }),
+    nodeLatencySummary: Metric.summary({
+        name: "node_latency_seconds",
+        maxAge: "10 minutes",
+        maxSize: 1000,
+        error: 0.01,
+        quantiles: [0.5, 0.9, 0.95, 0.99],
+        description: "Node execution latency percentiles",
+    }),
+});
+/**
+ * Default flow metrics instance
+ */
+export const flowMetrics = createFlowMetrics();

package/dist/flow/testing.d.ts

@@ -0,0 +1,11 @@
+import { Effect, Layer } from "effect";
+import { FlowObservability } from "../core/layers.js";
+/**
+ * Mock flow observability for testing
+ */
+export declare const makeTestFlowObservability: () => Layer.Layer<FlowObservability>;
+/**
+ * Run an effect with test flow observability
+ */
+export declare const runWithTestFlowObservability: <A, E>(effect: Effect.Effect<A, E, FlowObservability>) => Effect.Effect<A, E>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/flow/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/flow/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAOtD;;GAEG;AACH,eAAO,MAAM,yBAAyB,QAAO,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAYzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,EAAE,CAAC,EAC/C,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,iBAAiB,CAAC,KAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAEpB,CAAC"}