@beignet/core 0.0.2 → 0.0.4

package/src/openapi/index.ts

@@ -4,7 +4,6 @@
  * OpenAPI 3.1 generation from Beignet contracts
  */
 
-import { type ZodTypeAny, z } from "zod";
 import {
   type AnyContract,
   type ContractLike,
@@ -13,17 +12,26 @@ import {
   parsePathTemplate,
   resolveContract,
   STANDARD_ERROR_RESPONSE_SCHEMA,
-} from "../contracts";
+} from "../contracts/index.js";
+import {
+  comparePathParamsToTemplate,
+  formatPathParamsMismatch,
+} from "../contracts/schema-shape.js";
 import {
   createZodIntrospector,
+  createZodSchemaConverter,
+  type SchemaConverter,
   type SchemaIntrospector,
-} from "./schema-introspector";
+  type SchemaIO,
+} from "./schema-introspector.js";
 
 // Re-export the introspector types for consumers who want custom implementations
 export {
   createZodIntrospector,
+  createZodSchemaConverter,
+  type SchemaConverter,
   type SchemaIntrospector,
-} from "./schema-introspector";
+} from "./schema-introspector.js";
 
 /**
  * OpenAPI 3.1 info object.
@@ -338,6 +346,11 @@ export interface OpenAPIGeneratorOptions {
    * to support other schema libraries.
    */
   schemaIntrospector?: SchemaIntrospector;
+  /**
+   * Schema converters used to turn contract schemas into OpenAPI schemas.
+   * Custom converters run before Beignet's default Zod converter.
+   */
+  schemaConverters?: readonly SchemaConverter[];
 }
 
 /**
@@ -347,10 +360,9 @@ type GeneratorState = {
   components: ComponentsObject;
   jsonMediaType: string;
   introspector: SchemaIntrospector;
+  schemaConverters: readonly SchemaConverter[];
 };
 
-type SchemaIO = "input" | "output";
-
 /**
  * Contract input accepted by the OpenAPI generator.
  */
@@ -392,6 +404,10 @@ export function contractsToOpenAPI(
     components,
     jsonMediaType: options.jsonMediaType ?? "application/json",
     introspector: options.schemaIntrospector ?? createZodIntrospector(),
+    schemaConverters: [
+      ...(options.schemaConverters ?? []),
+      createZodSchemaConverter(),
+    ],
   };
 
   for (const contract of contracts) {
@@ -456,6 +472,7 @@ function addContractToPaths(
   addHeaderParams(contract, operation, state);
   addRequestBody(contract, operation, state);
   addResponses(contract, operation, state);
+  applyOpenAPIOverrides(operation, meta);
 
   // Clean up empty parameters array
   if (operation.parameters?.length === 0) {
@@ -474,6 +491,25 @@ function addContractToPaths(
   pathItem[methodKey] = operation;
 }
 
+function applyOpenAPIOverrides(
+  operation: OperationObject,
+  meta: AnyContract["metadata"]["openapi"] | undefined,
+): void {
+  if (!meta) return;
+
+  for (const parameter of meta.parameters ?? []) {
+    addParameter(operation, parameter);
+  }
+
+  if (meta.requestBody) {
+    operation.requestBody = meta.requestBody;
+  }
+
+  for (const [status, response] of Object.entries(meta.responses ?? {})) {
+    operation.responses[status] = response;
+  }
+}
+
 function addParameter(
   operation: OperationObject,
   parameter: ParameterObject,
@@ -525,20 +561,12 @@ function addPathParams(
     return;
   }
 
-  const shapeKeys = Object.keys(shape);
-  const missingKeys = pathKeys.filter((key) => !shapeKeys.includes(key));
-  const extraKeys = shapeKeys.filter((key) => !pathKeys.includes(key));
+  const { missingKeys, extraKeys } = comparePathParamsToTemplate({
+    pathKeys,
+    shapeKeys: Object.keys(shape),
+  });
   if (missingKeys.length > 0 || extraKeys.length > 0) {
-    const details = [
-      missingKeys.length > 0
-        ? `missing pathParams keys: ${missingKeys.join(", ")}`
-        : undefined,
-      extraKeys.length > 0
-        ? `extra pathParams keys: ${extraKeys.join(", ")}`
-        : undefined,
-    ]
-      .filter(Boolean)
-      .join("; ");
+    const details = formatPathParamsMismatch({ missingKeys, extraKeys });
     throw new Error(
       `Path parameters for contract "${contract.name}" must match "${contract.path}" (${details}).`,
     );
@@ -546,8 +574,8 @@ function addPathParams(
 
   for (const key of pathKeys) {
     const field = shape[key];
-    const paramSchemaRef = zodToSchemaRef(
-      field as ZodTypeAny,
+    const paramSchemaRef = schemaToConvertedSchemaRef(
+      field,
       `${contract.name}_path_${key}`,
       state,
       "input",
@@ -593,8 +621,8 @@ function addQueryParams(
       description = state.introspector.getDescription(field);
     }
 
-    const paramSchemaRef = zodToSchemaRef(
-      field as ZodTypeAny,
+    const paramSchemaRef = schemaToConvertedSchemaRef(
+      field,
       `${contract.name}_query_${key}`,
       state,
       "input",
@@ -630,8 +658,8 @@ function addHeaderParams(
       const optional = state.introspector.isOptional(originalField);
       const description = state.introspector.getDescription(originalField);
 
-      const paramSchemaRef = zodToSchemaRef(
-        originalField as ZodTypeAny,
+      const paramSchemaRef = schemaToConvertedSchemaRef(
+        originalField,
         `${contract.name}_header_${key}`,
         state,
         "input",
@@ -663,8 +691,8 @@ function addRequestBody(
     );
   }
 
-  const schemaRef = zodToSchemaRef(
-    contract.body as ZodTypeAny,
+  const schemaRef = schemaToConvertedSchemaRef(
+    contract.body,
     `${contract.name}_body`,
     state,
     "input",
@@ -889,10 +917,10 @@ function normalizeExampleKey(key: string): string {
 }
 
 /**
- * Convert a Zod schema to a JSON Schema reference, registering it in components
+ * Convert a validation schema to a JSON Schema reference, registering it in components.
  */
-function zodToSchemaRef(
-  schema: ZodTypeAny,
+function schemaToConvertedSchemaRef(
+  schema: unknown,
   nameHint: string,
   state: GeneratorState,
   io: SchemaIO,
@@ -905,14 +933,21 @@ function zodToSchemaRef(
   const schemaName = normalizeSchemaName(nameHint, state);
 
   if (!state.components.schemas[schemaName]) {
-    const jsonSchema = z.toJSONSchema(schema, {
-      target: "draft-2020-12",
-      unrepresentable: "any",
-      io,
-    }) as SchemaObject;
+    const converter = state.schemaConverters.find((candidate) =>
+      candidate.canConvert(schema),
+    );
+
+    if (!converter) {
+      throw new Error(
+        `Unable to convert schema "${nameHint}" to OpenAPI. ` +
+          "Pass a schemaConverters entry to contractsToOpenAPI for this schema library.",
+      );
+    }
 
-    // Remove $schema as it's not needed in OpenAPI
-    delete jsonSchema.$schema;
+    const jsonSchema = converter.toJSONSchema(schema, {
+      nameHint,
+      io,
+    });
 
     state.components.schemas[schemaName] = jsonSchema;
   }
@@ -930,7 +965,7 @@ function schemaToSchemaRef(
     return standardErrorResponseSchemaRef(nameHint, state);
   }
 
-  return zodToSchemaRef(schema as ZodTypeAny, nameHint, state, io);
+  return schemaToConvertedSchemaRef(schema, nameHint, state, io);
 }
 
 function standardErrorResponseSchemaRef(

package/src/openapi/schema-introspector.ts

@@ -1,3 +1,45 @@
+import { type ZodTypeAny, z } from "zod";
+import { getObjectSchemaShape } from "../contracts/schema-shape.js";
+
+export type SchemaIO = "input" | "output";
+
+type ConvertedSchemaObject = Record<string, unknown>;
+
+/**
+ * Context passed to an OpenAPI schema converter.
+ */
+export type SchemaConverterContext = {
+  /**
+   * Whether the schema is documenting request input or response output.
+   */
+  io: SchemaIO;
+  /**
+   * Component name hint Beignet will use when registering the converted schema.
+   */
+  nameHint: string;
+};
+
+/**
+ * Converts a validation schema into an OpenAPI-compatible JSON Schema object.
+ */
+export interface SchemaConverter {
+  /**
+   * Human-readable converter name used in diagnostics.
+   */
+  name: string;
+  /**
+   * Return true when this converter owns the schema value.
+   */
+  canConvert(schema: unknown): boolean;
+  /**
+   * Convert the schema into an OpenAPI-compatible JSON Schema object.
+   */
+  toJSONSchema(
+    schema: unknown,
+    context: SchemaConverterContext,
+  ): ConvertedSchemaObject;
+}
+
 /**
  * Schema introspection adapter.
  *
@@ -31,6 +73,31 @@ export interface SchemaIntrospector {
   unwrapOptional(schema: unknown): unknown;
 }
 
+/**
+ * Create the default schema converter for Zod schemas.
+ */
+export function createZodSchemaConverter(): SchemaConverter {
+  return {
+    name: "zod",
+    canConvert(schema: unknown): boolean {
+      return schema instanceof z.ZodType;
+    },
+    toJSONSchema(
+      schema: unknown,
+      context: SchemaConverterContext,
+    ): ConvertedSchemaObject {
+      const jsonSchema = z.toJSONSchema(schema as ZodTypeAny, {
+        target: "draft-2020-12",
+        unrepresentable: "any",
+        io: context.io,
+      }) as ConvertedSchemaObject;
+
+      delete jsonSchema.$schema;
+      return jsonSchema;
+    },
+  };
+}
+
 /**
  * Create a schema introspector for Zod schemas.
  *
@@ -41,23 +108,7 @@ export interface SchemaIntrospector {
 export function createZodIntrospector(): SchemaIntrospector {
   return {
     getShape(schema: unknown): Record<string, unknown> | undefined {
-      if (!schema || typeof schema !== "object") return undefined;
-
-      const schemaDef = (schema as Record<string, unknown>)?._def;
-      if (!schemaDef || typeof schemaDef !== "object") return undefined;
-
-      if (!("shape" in schemaDef)) return undefined;
-
-      let shape: unknown;
-      if (typeof schemaDef.shape === "function") {
-        shape = schemaDef.shape();
-      } else if (typeof schemaDef.shape === "object") {
-        shape = schemaDef.shape;
-      }
-
-      if (!shape || typeof shape !== "object") return undefined;
-
-      return shape as Record<string, unknown>;
+      return getObjectSchemaShape(schema);
     },
 
     getDescription(schema: unknown): string | undefined {

package/src/outbox/index.ts

@@ -9,13 +9,25 @@ import {
   type EventPayloadDef,
   type InferEventPayload,
   parseEventPayload,
-} from "../events";
-import { type InferJobPayload, type JobDef, parseJobPayload } from "../jobs";
-import type { JobDispatcherPort } from "../ports/events";
+} from "../events/index.js";
+import {
+  getJobRetryDelayMs,
+  getJobRetryMaxAttempts,
+  type InferJobPayload,
+  type JobDef,
+  parseJobPayload,
+  shouldRetryJob,
+} from "../jobs/index.js";
+import type { JobDispatcherPort } from "../ports/events.js";
 import type {
   BufferedDomainEventRecorder,
   DomainEventRecorderPort,
-} from "../ports/unit-of-work";
+} from "../ports/unit-of-work.js";
+import {
+  type BaseProviderInstrumentationEvent,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "../providers/index.js";
 
 /**
  * Value or promise of that value.
@@ -354,6 +366,14 @@ export interface DefineOutboxRegistryInput {
   jobs?: readonly JobDef[];
 }
 
+/**
+ * Correlation fields attached to outbox instrumentation events.
+ */
+export type OutboxInstrumentationContext = Pick<
+  BaseProviderInstrumentationEvent,
+  "requestId" | "traceId" | "spanId" | "parentSpanId" | "traceparent"
+>;
+
 /**
  * Options for draining one outbox batch.
  */
@@ -401,6 +421,15 @@ export interface DrainOutboxOptions {
         error: unknown;
         now: Date;
       }) => number);
+  /**
+   * Optional instrumentation target for delivery, retry, and dead-letter
+   * visibility.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+  /**
+   * Optional correlation fields attached to outbox instrumentation events.
+   */
+  instrumentationContext?: OutboxInstrumentationContext;
   /**
    * Observer called when delivery fails. Observer failures are ignored so the
    * original delivery failure still controls retry/dead-letter behavior.
@@ -852,7 +881,7 @@ export async function enqueueJob<J extends JobDef>(
     name: job.name,
     payload: toOutboxJsonValue(parsed),
     availableAt: options.availableAt,
-    maxAttempts: options.maxAttempts,
+    maxAttempts: options.maxAttempts ?? getJobRetryMaxAttempts(job.retry),
   });
 }
 
@@ -906,9 +935,52 @@ function resolveRetryDelayMs(
     return options.retryDelayMs;
   }
 
+  if (message.kind === "job") {
+    const job = options.registry.jobs.get(message.name);
+    if (job?.retry) {
+      return getJobRetryDelayMs(job.retry, {
+        attempt: message.attempts,
+        error,
+        jobName: message.name,
+      });
+    }
+  }
+
   return Math.min(60_000, 1000 * 2 ** Math.max(0, message.attempts - 1));
 }
 
+function shouldRetryOutboxMessage(
+  options: DrainOutboxOptions,
+  message: ClaimedOutboxMessage,
+  error: unknown,
+): boolean {
+  if (message.kind !== "job") {
+    return message.attempts < message.maxAttempts;
+  }
+
+  const job = options.registry.jobs.get(message.name);
+  return shouldRetryJob(job?.retry, {
+    attempt: message.attempts,
+    error,
+    jobName: message.name,
+    maxAttempts: message.maxAttempts,
+  });
+}
+
+function outboxInstrumentationDetails(
+  message: ClaimedOutboxMessage,
+  details?: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    attempt: message.attempts,
+    maxAttempts: message.maxAttempts,
+    messageId: message.id,
+    messageKind: message.kind,
+    messageName: message.name,
+    ...details,
+  };
+}
+
 async function deliverOutboxMessage(
   options: DrainOutboxOptions,
   message: ClaimedOutboxMessage,
@@ -962,6 +1034,20 @@ export async function drainOutbox(
 ): Promise<DrainOutboxResult> {
   const batchSize = options.batchSize ?? 100;
   assertPositiveInteger("batchSize", batchSize);
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "outbox",
+      watcher: "outbox",
+    },
+  );
+  const jobInstrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "outbox",
+      watcher: "jobs",
+    },
+  );
 
   const now = options.now ?? new Date();
   const messages = await options.outbox.claimBatch({
@@ -984,6 +1070,15 @@ export async function drainOutbox(
         claimToken: message.claimToken,
         now,
       });
+      instrumentation.record({
+        type: "outbox",
+        ...options.instrumentationContext,
+        messageId: message.id,
+        messageKind: message.kind,
+        messageName: message.name,
+        status: "delivered",
+        details: outboxInstrumentationDetails(message),
+      });
       result.delivered += 1;
     } catch (error) {
       try {
@@ -992,7 +1087,8 @@ export async function drainOutbox(
         // Preserve the delivery failure path so the message is retried or
         // dead-lettered even if the observer fails.
       }
-      const deadLetter = message.attempts >= message.maxAttempts;
+      const shouldRetry = shouldRetryOutboxMessage(options, message, error);
+      const deadLetter = !shouldRetry;
       const retryDelayMs = deadLetter
         ? 0
         : resolveRetryDelayMs(options, message, error, now);
@@ -1008,8 +1104,57 @@ export async function drainOutbox(
       });
 
       if (deadLetter) {
+        instrumentation.record({
+          type: "outbox",
+          ...options.instrumentationContext,
+          messageId: message.id,
+          messageKind: message.kind,
+          messageName: message.name,
+          status: "deadLettered",
+          details: outboxInstrumentationDetails(message, {
+            error: serializeOutboxError(error),
+          }),
+        });
+        if (message.kind === "job") {
+          jobInstrumentation.record({
+            type: "job",
+            ...options.instrumentationContext,
+            jobName: message.name,
+            status: "deadLettered",
+            details: outboxInstrumentationDetails(message, {
+              error: serializeOutboxError(error),
+            }),
+          });
+        }
         result.deadLettered += 1;
       } else {
+        const retryAt = new Date(now.getTime() + retryDelayMs).toISOString();
+        instrumentation.record({
+          type: "outbox",
+          ...options.instrumentationContext,
+          messageId: message.id,
+          messageKind: message.kind,
+          messageName: message.name,
+          status: "retryScheduled",
+          details: outboxInstrumentationDetails(message, {
+            retryDelayMs,
+            retryAt,
+            error: serializeOutboxError(error),
+          }),
+        });
+        if (message.kind === "job") {
+          jobInstrumentation.record({
+            type: "job",
+            ...options.instrumentationContext,
+            jobName: message.name,
+            status: "retryScheduled",
+            details: outboxInstrumentationDetails(message, {
+              retryDelayMs,
+              retryAt,
+              error: serializeOutboxError(error),
+            }),
+          });
+        }
         result.retried += 1;
       }
     }