@beignet/core 0.0.2 → 0.0.4

package/src/application/index.ts

@@ -1,4 +1,12 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  type ProviderInstrumentationEventInput,
+  resolveProviderInstrumentationPort,
+} from "../providers/instrumentation.js";
+import {
+  createChildTraceContext,
+  type TraceContextInput,
+} from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -315,6 +323,21 @@ function createUseCaseEventHelpers<Emits extends readonly DomainEventLike[]>(
  */
 export type UseCaseKind = "command" | "query";
 
+/**
+ * Symbol key for the trusted run path attached to finalized use cases.
+ *
+ * The server route binder calls this method instead of `run` when the route's
+ * input was already validated by the exact same schema object at the HTTP
+ * boundary. It behaves like `run` but skips the input parse; output
+ * validation, instrumentation, events, and `onRun` are unchanged.
+ *
+ * The key uses `Symbol.for(...)` so the binder and the application builder
+ * agree on the key even across separately bundled copies of the package.
+ */
+export const USE_CASE_TRUSTED_RUN: unique symbol = Symbol.for(
+  "beignet.useCase.trustedRun",
+);
+
 /**
  * Finalized use case definition.
  *
@@ -390,10 +413,24 @@ export interface UseCaseRunEvent<Ctx> {
  */
 export interface CreateUseCaseOptions<Ctx> {
   /**
-   * Optional instrumentation hook called on use case start, end, and error.
+   * Optional app-owned observer called on use case start, end, and error.
+   *
+   * Observers run in addition to the built-in instrumentation.
    */
   onRun?: (event: UseCaseRunEvent<Ctx>) => void;
 
+  /**
+   * Built-in use-case instrumentation.
+   *
+   * By default every run records `usecase` lifecycle events (plus `error`
+   * events for failed runs) into the provider instrumentation port resolved
+   * from `ctx.ports` (`ports.instrumentation`, then `ports.devtools`). When no
+   * port is installed, runs stay silent. Pass `false` to opt out.
+   *
+   * @default true
+   */
+  instrumentation?: boolean;
+
   /**
    * Enable or disable schema validation for use case boundaries.
    *
@@ -423,6 +460,120 @@ function normalizeValidationOptions(
   return { input: true, output: true };
 }
 
+type UseCaseRunInstrumentation = {
+  end(durationMs: number): void;
+  error(durationMs: number, error: unknown): void;
+};
+
+function getInstrumentationRequestId(ctx: unknown): string | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const requestId = (ctx as { requestId?: unknown }).requestId;
+  return typeof requestId === "string" ? requestId : undefined;
+}
+
+function getInstrumentationTrace(ctx: unknown): TraceContextInput | undefined {
+  if (!ctx || typeof ctx !== "object") return undefined;
+  const context = ctx as TraceContextInput;
+  if (!context.traceId && !context.spanId && !context.traceparent) {
+    return undefined;
+  }
+  return {
+    traceId: context.traceId,
+    spanId: context.spanId,
+    parentSpanId: context.parentSpanId,
+    traceparent: context.traceparent,
+  };
+}
+
+function getRunErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  return "Unknown error";
+}
+
+/**
+ * Start built-in instrumentation for one use-case run.
+ *
+ * The instrumentation port is resolved from `ctx.ports` per run so use cases
+ * stay decoupled from any specific sink. Runs without a resolved port stay
+ * silent.
+ */
+function startUseCaseRunInstrumentation(args: {
+  ctx: unknown;
+  name: string;
+  kind: UseCaseKind;
+}): UseCaseRunInstrumentation | undefined {
+  const ports =
+    args.ctx && typeof args.ctx === "object"
+      ? (args.ctx as { ports?: unknown }).ports
+      : undefined;
+  const port = resolveProviderInstrumentationPort(
+    ports as Parameters<typeof resolveProviderInstrumentationPort>[0],
+  );
+  if (!port) return undefined;
+
+  const useCasesEnabled = port.isWatcherEnabled?.("useCases") ?? true;
+  const errorsEnabled = port.isWatcherEnabled?.("errors") ?? true;
+  if (!useCasesEnabled && !errorsEnabled) return undefined;
+
+  const requestId = getInstrumentationRequestId(args.ctx);
+  const trace = createChildTraceContext(
+    getInstrumentationTrace(args.ctx) ?? {},
+  );
+
+  const record = (event: ProviderInstrumentationEventInput) => {
+    try {
+      port.record(event);
+    } catch {
+      // Instrumentation sinks must never affect use-case behavior.
+    }
+  };
+
+  const recordPhase = (
+    phase: "start" | "end" | "error",
+    durationMs?: number,
+    error?: unknown,
+  ) => {
+    if (useCasesEnabled) {
+      record({
+        type: "usecase",
+        requestId,
+        traceId: trace.traceId,
+        spanId: trace.spanId,
+        parentSpanId: trace.parentSpanId,
+        traceparent: trace.traceparent,
+        name: args.name,
+        kind: args.kind,
+        phase,
+        durationMs,
+        error: phase === "error" ? getRunErrorMessage(error) : undefined,
+      });
+    }
+
+    if (phase === "error" && errorsEnabled) {
+      record({
+        type: "error",
+        requestId,
+        traceId: trace.traceId,
+        spanId: trace.spanId,
+        parentSpanId: trace.parentSpanId,
+        traceparent: trace.traceparent,
+        message: getRunErrorMessage(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        useCaseName: args.name,
+        owner: "route",
+      });
+    }
+  };
+
+  recordPhase("start");
+
+  return {
+    end: (durationMs) => recordPhase("end", durationMs),
+    error: (durationMs, error) => recordPhase("error", durationMs, error),
+  };
+}
+
 /**
  * Internal configuration for the use case builder
  */
@@ -464,6 +615,7 @@ class UseCaseBuilder<
       input: true,
       output: true,
     },
+    private readonly instrumented: boolean = true,
   ) {}
 
   /**
@@ -479,6 +631,7 @@ class UseCaseBuilder<
       },
       this.onRun,
       this.validation,
+      this.instrumented,
     );
   }
 
@@ -495,6 +648,7 @@ class UseCaseBuilder<
       },
       this.onRun,
       this.validation,
+      this.instrumented,
     );
   }
 
@@ -511,6 +665,7 @@ class UseCaseBuilder<
       },
       this.onRun,
       this.validation,
+      this.instrumented,
     );
   }
 
@@ -544,6 +699,7 @@ class UseCaseBuilder<
     const useCaseName = this.config.name;
     const useCaseKind = this.config.kind;
     const onRun = this.onRun;
+    const instrumented = this.instrumented;
     const inputSchema = this.config.input as Extract<
       InputSchema,
       StandardSchemaV1
@@ -558,7 +714,7 @@ class UseCaseBuilder<
       this.config.emits,
     );
 
-    const runFn = async (
+    const execute = async (
       args: InputSchema extends StandardSchemaV1
         ? OutputSchema extends StandardSchemaV1
           ? {
@@ -567,8 +723,16 @@ class UseCaseBuilder<
             }
           : never
         : never,
+      parseInput: boolean,
     ) => {
       const startedAt = Date.now();
+      const instrumentation = instrumented
+        ? startUseCaseRunInstrumentation({
+            ctx: args.ctx,
+            name: useCaseName,
+            kind: useCaseKind,
+          })
+        : undefined;
       onRun?.({
         name: useCaseName,
         kind: useCaseKind,
@@ -577,9 +741,10 @@ class UseCaseBuilder<
       });
 
       try {
-        const parsedInput = validation.input
-          ? await parseSchema(inputSchema, args.input, useCaseName, "input")
-          : (args.input as SchemaOutput<InputSchema>);
+        const parsedInput =
+          parseInput && validation.input
+            ? await parseSchema(inputSchema, args.input, useCaseName, "input")
+            : (args.input as SchemaOutput<InputSchema>);
 
         const rawResult = await fn({
           ctx: args.ctx,
@@ -591,21 +756,25 @@ class UseCaseBuilder<
           ? await parseSchema(outputSchema, rawResult, useCaseName, "output")
           : (rawResult as SchemaOutput<OutputSchema>);
 
+        const durationMs = Date.now() - startedAt;
+        instrumentation?.end(durationMs);
         onRun?.({
           name: useCaseName,
           kind: useCaseKind,
           phase: "end",
-          durationMs: Date.now() - startedAt,
+          durationMs,
           ctx: args.ctx,
         });
 
         return result;
       } catch (err) {
+        const durationMs = Date.now() - startedAt;
+        instrumentation?.error(durationMs, err);
         onRun?.({
           name: useCaseName,
           kind: useCaseKind,
           phase: "error",
-          durationMs: Date.now() - startedAt,
+          durationMs,
           error: err,
           ctx: args.ctx,
         });
@@ -613,18 +782,29 @@ class UseCaseBuilder<
       }
     };
 
+    type RunArgs = Parameters<typeof execute>[0];
+
     // Type assertion required to satisfy the conditional return type.
     // The runtime checks above ensure input/output schemas are set.
     // The conditional types ensure type safety at compile time - run() returns
     // UseCaseDef only when both InputSchema and OutputSchema are StandardSchemaV1.
-    return {
+    const def = {
       name: this.config.name,
       kind: this.config.kind,
       inputSchema: this.config.input,
       outputSchema: this.config.output,
       emits: this.config.emits,
-      run: runFn,
-    } as unknown as InputSchema extends StandardSchemaV1
+      run: (args: RunArgs) => execute(args, true),
+    };
+
+    // The trusted run path skips only the input parse. It is non-enumerable so
+    // serialization and object spreads keep treating use cases as plain data.
+    Object.defineProperty(def, USE_CASE_TRUSTED_RUN, {
+      value: (args: RunArgs) => execute(args, false),
+      enumerable: false,
+    });
+
+    return def as unknown as InputSchema extends StandardSchemaV1
       ? OutputSchema extends StandardSchemaV1
         ? UseCaseDef<Ctx, Name, Kind, InputSchema, OutputSchema, Emits>
         : never
@@ -769,6 +949,7 @@ export function createUseCase<Ctx>(
 ): UseCaseBuilderRoot<Ctx> {
   const onRun = options?.onRun;
   const validation = normalizeValidationOptions(options?.validate);
+  const instrumented = options?.instrumentation !== false;
   return {
     command<Name extends string>(name: Name) {
       return new UseCaseBuilder<
@@ -786,6 +967,7 @@ export function createUseCase<Ctx>(
         },
         onRun,
         validation,
+        instrumented,
       );
     },
     query<Name extends string>(name: Name) {
@@ -804,6 +986,7 @@ export function createUseCase<Ctx>(
         },
         onRun,
         validation,
+        instrumented,
       );
     },
   };