@beignet/core 0.0.48 → 0.0.50

package/src/contracts/schema-shape.ts

@@ -73,3 +73,27 @@ export function formatPathParamsMismatch(args: {
     .filter(Boolean)
     .join("; ");
 }
+
+/** Compare an introspected query schema's fields with its transport fields. */
+export function compareQueryTransportFields(args: {
+  schemaKeys: readonly string[];
+  transportKeys: readonly string[];
+}): boolean {
+  const schemaKeys = [...args.schemaKeys].sort();
+  const transportKeys = [...args.transportKeys].sort();
+  return (
+    schemaKeys.length === transportKeys.length &&
+    schemaKeys.every((key, index) => key === transportKeys[index])
+  );
+}
+
+/** Format a query schema/transport mismatch consistently across consumers. */
+export function formatQueryTransportMismatch(args: {
+  contractName: string;
+  schemaKeys: readonly string[];
+  transportKeys: readonly string[];
+}): string {
+  const schemaKeys = [...args.schemaKeys].sort();
+  const transportKeys = [...args.transportKeys].sort();
+  return `Query transport fields for contract "${args.contractName}" must match its query schema fields (schema: ${schemaKeys.join(", ") || "none"}; transport: ${transportKeys.join(", ") || "none"}).`;
+}

package/src/contracts/types.ts

@@ -2,6 +2,7 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { IdempotencyMeta } from "../idempotency/index.js";
 import type { ContractDeprecationMeta } from "./lifecycle.js";
 import type { OpenAPIOperationMeta } from "./openapi-meta.js";
+import type { QueryTransport } from "./query-transport.js";
 import type { RateLimitMeta } from "./rate-limit.js";
 
 /**
@@ -343,6 +344,10 @@ export type HttpContractConfig<
    * Query parameter schema.
    */
   query: TQuery;
+  /**
+   * Deterministic HTTP encoding for the query schema.
+   */
+  queryTransport: QueryTransport | null;
   /**
    * Request header schema or schemas.
    */

package/src/events/index.ts

@@ -16,6 +16,9 @@ export type StandardSchema = StandardSchemaV1<unknown, unknown>;
  */
 export type MaybePromise<T> = T | Promise<T>;
 
+const DEFAULT_LISTENER_READY_TIMEOUT_MS = 10_000;
+const MAX_TIMER_MS = 2_147_483_647;
+
 /**
  * Infer the parsed output type from a Standard Schema.
  */
@@ -68,6 +71,74 @@ export interface EventPublishOptions {
   trace?: TraceCarrier;
 }
 
+/**
+ * Lifecycle handle for one event subscription or a composed listener
+ * registration.
+ *
+ * `ready` proves initial transport readiness. It does not represent ongoing
+ * connectivity, durability, replay, or handler success after startup.
+ */
+export interface EventSubscription {
+  /** Resolves when the subscription can receive events. */
+  readonly ready: Promise<void>;
+  /** Stop local delivery and await transport cleanup. Idempotent. */
+  unsubscribe(): Promise<void>;
+}
+
+/** Error used when a subscription closes before initial readiness. */
+export class EventSubscriptionClosedError extends Error {
+  constructor(message = "Event subscription closed before it became ready.") {
+    super(message);
+    this.name = "EventSubscriptionClosedError";
+  }
+}
+
+/** Error thrown when a listener registry misses its readiness deadline. */
+export class ListenerRegistrationTimeoutError extends Error {
+  /** Configured readiness deadline in milliseconds. */
+  readonly timeoutMs: number;
+  /** Listener names that were part of the registration. */
+  readonly listenerNames: readonly string[];
+
+  constructor(args: {
+    timeoutMs: number;
+    listenerNames: readonly string[];
+  }) {
+    const suffix = args.listenerNames.length
+      ? `: ${args.listenerNames.join(", ")}`
+      : "";
+    super(
+      `Listeners did not become ready within ${args.timeoutMs}ms${suffix}.`,
+    );
+    this.name = "ListenerRegistrationTimeoutError";
+    this.timeoutMs = args.timeoutMs;
+    this.listenerNames = [...args.listenerNames];
+  }
+}
+
+/** Error thrown when listener rollback misses the registration deadline. */
+export class ListenerRegistrationCleanupTimeoutError extends Error {
+  /** Configured registration deadline in milliseconds. */
+  readonly timeoutMs: number;
+  /** Listener names that were part of the registration. */
+  readonly listenerNames: readonly string[];
+
+  constructor(args: {
+    timeoutMs: number;
+    listenerNames: readonly string[];
+  }) {
+    const suffix = args.listenerNames.length
+      ? `: ${args.listenerNames.join(", ")}`
+      : "";
+    super(
+      `Listener cleanup did not finish before the ${args.timeoutMs}ms registration deadline${suffix}.`,
+    );
+    this.name = "ListenerRegistrationCleanupTimeoutError";
+    this.timeoutMs = args.timeoutMs;
+    this.listenerNames = [...args.listenerNames];
+  }
+}
+
 /**
  * Options for `defineEvent(...)`.
  */
@@ -153,7 +224,7 @@ export interface EventBusLike {
     options?: EventPublishOptions,
   ): MaybePromise<void>;
   /**
-   * Subscribe to an event and return an unsubscribe function.
+   * Subscribe to an event and return its readiness and cleanup handle.
    */
   subscribe<E extends EventPayloadDef>(
     event: E,
@@ -161,7 +232,7 @@ export interface EventBusLike {
       payload: InferEventPayload<E>,
       options?: EventPublishOptions,
     ) => MaybePromise<void>,
-  ): () => void;
+  ): EventSubscription;
 }
 
 /**
@@ -182,6 +253,12 @@ export interface RegisterListenersOptions<Ctx> {
    * the event bus subscription callback.
    */
   onError?: (error: unknown, listener: ListenerDef<EventDef, Ctx>) => void;
+  /**
+   * Maximum time for the complete listener registry to become ready. The same
+   * registration deadline bounds automatic rollback after startup failure.
+   * Defaults to 10 seconds.
+   */
+  readyTimeoutMs?: number;
 }
 
 /**
@@ -319,54 +396,202 @@ export async function publishEvent<E extends EventPayloadDef>(
   await eventBus.publish(event, payload, options);
 }
 
+function assertReadyTimeoutMs(value: number): void {
+  if (Number.isInteger(value) && value >= 1 && value <= MAX_TIMER_MS) return;
+  throw new RangeError(
+    `readyTimeoutMs must be an integer between 1 and ${MAX_TIMER_MS} milliseconds.`,
+  );
+}
+
+function errorsFromCleanup(error: unknown): unknown[] {
+  return error instanceof AggregateError ? [...error.errors] : [error];
+}
+
+function unsubscribeAllSettled(
+  subscriptions: readonly EventSubscription[],
+): Promise<PromiseSettledResult<void>[]> {
+  const attempts: Promise<void>[] = [];
+  for (const subscription of [...subscriptions].reverse()) {
+    try {
+      attempts.push(Promise.resolve(subscription.unsubscribe()));
+    } catch (error) {
+      attempts.push(Promise.reject(error));
+    }
+  }
+
+  return Promise.allSettled(attempts);
+}
+
+function throwSubscriptionCleanupErrors(
+  results: readonly PromiseSettledResult<void>[],
+): void {
+  const errors = results.flatMap((result) =>
+    result.status === "rejected" ? errorsFromCleanup(result.reason) : [],
+  );
+  if (errors.length > 0) {
+    throw new AggregateError(errors, "Event subscription cleanup failed");
+  }
+}
+
+function withListenerDeadline<T>(
+  operation: Promise<T>,
+  args: {
+    deadlineAt: number;
+    timeoutError: Error;
+  },
+): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<T>((_, reject) => {
+    timeout = setTimeout(
+      () => {
+        reject(args.timeoutError);
+      },
+      Math.max(0, args.deadlineAt - performance.now()),
+    );
+  });
+
+  return Promise.race([operation, timedOut]).finally(() => {
+    if (timeout !== undefined) clearTimeout(timeout);
+  });
+}
+
 /**
- * Register listeners against an event bus and return an unsubscribe function.
+ * Register listeners against an event bus and return a composite lifecycle
+ * handle.
  *
  * Payloads are validated before listener handlers run. Listener context is
- * resolved per delivery when `options.ctx` is a factory.
+ * resolved per delivery when `options.ctx` is a factory. Initial registration
+ * starts every child cleanup after a synchronous subscribe failure, rejected
+ * readiness promise, or readiness timeout. Cleanup that cannot finish inside
+ * the registration deadline is reported without extending startup forever.
  */
 export function registerListeners<Ctx>(
   eventBus: EventBusLike,
   listeners: readonly ListenerDef<EventDef, Ctx>[],
   options: RegisterListenersOptions<Ctx> = {},
-): () => void {
-  const unsubscribes = listeners.map((listener) =>
-    eventBus.subscribe(listener.event, async (rawPayload, publishOptions) => {
-      try {
-        const payload = await parseEventPayload(listener.event, rawPayload);
-        const traceAttributes = {
-          "beignet.listener.name": listener.name,
-          "beignet.event.name": listener.event.name,
-        } as const;
-        await runWithResolvedTracingContext({
-          tracing: options.tracing,
-          ctx: options.ctx as Ctx | (() => MaybePromise<Ctx>),
-          operation: {
-            name: `beignet.listener ${listener.name}`,
-            type: "listener",
-            kind: "consumer",
-            parent: parseTraceCarrier(publishOptions?.trace),
-            attributes: traceAttributes,
-            metricAttributes: traceAttributes,
+): EventSubscription {
+  const readyTimeoutMs =
+    options.readyTimeoutMs ?? DEFAULT_LISTENER_READY_TIMEOUT_MS;
+  assertReadyTimeoutMs(readyTimeoutMs);
+  const registrationDeadlineAt = performance.now() + readyTimeoutMs;
+  const listenerNames = listeners.map(({ name }) => name);
+
+  const subscriptions: EventSubscription[] = [];
+  let registrationError: unknown;
+
+  for (const listener of listeners) {
+    try {
+      subscriptions.push(
+        eventBus.subscribe(
+          listener.event,
+          async (rawPayload, publishOptions) => {
+            try {
+              const payload = await parseEventPayload(
+                listener.event,
+                rawPayload,
+              );
+              const traceAttributes = {
+                "beignet.listener.name": listener.name,
+                "beignet.event.name": listener.event.name,
+              } as const;
+              await runWithResolvedTracingContext({
+                tracing: options.tracing,
+                ctx: options.ctx as Ctx | (() => MaybePromise<Ctx>),
+                operation: {
+                  name: `beignet.listener ${listener.name}`,
+                  type: "listener",
+                  kind: "consumer",
+                  parent: parseTraceCarrier(publishOptions?.trace),
+                  attributes: traceAttributes,
+                  metricAttributes: traceAttributes,
+                },
+                run: (ctx) =>
+                  listener.handle({
+                    event: listener.event,
+                    payload,
+                    ctx,
+                  }),
+              });
+            } catch (error) {
+              options.onError?.(error, listener);
+              if (!options.onError) throw error;
+            }
           },
-          run: (ctx) =>
-            listener.handle({
-              event: listener.event,
-              payload,
-              ctx,
+        ),
+      );
+    } catch (error) {
+      registrationError = error;
+      break;
+    }
+  }
+
+  let rejectClosed!: (error: unknown) => void;
+  const closedBeforeReady = new Promise<void>((_, reject) => {
+    rejectClosed = reject;
+  });
+  // A consumer may only await cleanup. Keep an explicit observer on the
+  // cancellation signal so that use does not create an unhandled rejection.
+  void closedBeforeReady.catch(() => undefined);
+
+  let cleanupPromise: Promise<void> | undefined;
+  const cleanup = (deadlineAt?: number): Promise<void> => {
+    if (cleanupPromise) return cleanupPromise;
+    const operation = unsubscribeAllSettled(subscriptions);
+    cleanupPromise =
+      deadlineAt === undefined
+        ? operation.then(throwSubscriptionCleanupErrors)
+        : withListenerDeadline(operation, {
+            deadlineAt,
+            timeoutError: new ListenerRegistrationCleanupTimeoutError({
+              timeoutMs: readyTimeoutMs,
+              listenerNames,
             }),
-        });
-      } catch (error) {
-        options.onError?.(error, listener);
-        if (!options.onError) throw error;
+          }).then(throwSubscriptionCleanupErrors);
+    return cleanupPromise;
+  };
+
+  const initialReadiness = registrationError
+    ? Promise.reject(registrationError)
+    : Promise.all(subscriptions.map(({ ready }) => ready)).then(
+        () => undefined,
+      );
+  let readySettled = false;
+  const ready = withListenerDeadline(
+    Promise.race([initialReadiness, closedBeforeReady]),
+    {
+      deadlineAt: registrationDeadlineAt,
+      timeoutError: new ListenerRegistrationTimeoutError({
+        timeoutMs: readyTimeoutMs,
+        listenerNames,
+      }),
+    },
+  )
+    .catch(async (primaryError: unknown) => {
+      try {
+        await cleanup(registrationDeadlineAt);
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [primaryError, ...errorsFromCleanup(cleanupError)],
+          "Listener registration failed and cleanup failed",
+        );
       }
-    }),
-  );
+      throw primaryError;
+    })
+    .finally(() => {
+      readySettled = true;
+    });
+  // EventSubscription allows callers that only own cleanup. Preserve the
+  // rejection for awaiters while preventing process-level unhandled noise.
+  void ready.catch(() => undefined);
 
-  return () => {
-    for (const unsubscribe of [...unsubscribes].reverse()) {
-      unsubscribe();
-    }
+  return {
+    ready,
+    unsubscribe() {
+      if (!readySettled) {
+        rejectClosed(new EventSubscriptionClosedError());
+      }
+      return cleanup(readySettled ? undefined : registrationDeadlineAt);
+    },
   };
 }
 

package/src/idempotency/index.ts

@@ -451,6 +451,17 @@ type CanonicalValue =
   | readonly CanonicalValue[]
   | { readonly [key: string]: CanonicalValue };
 
+const CANONICAL_TYPE_KEY = "$beignet:idempotency-type";
+
+function canonicalType(
+  type: "bigint" | "date" | "negative-zero" | "omitted",
+  value?: string,
+): CanonicalValue {
+  return {
+    [CANONICAL_TYPE_KEY]: value === undefined ? [type] : [type, value],
+  };
+}
+
 type MemoryRecord = MemoryIdempotencyEntry & {
   replayTtlSec?: number;
 };
@@ -875,11 +886,15 @@ function canonicalize(
     return undefined;
   }
 
-  if (
-    value === null ||
-    typeof value === "string" ||
-    typeof value === "boolean"
-  ) {
+  if (value === null) {
+    return null;
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (typeof value === "boolean") {
     return value;
   }
 
@@ -889,25 +904,54 @@ function canonicalize(
         "Cannot fingerprint non-finite numeric values.",
       );
     }
-    return value;
+    return Object.is(value, -0) ? canonicalType("negative-zero") : value;
   }
 
   if (typeof value === "bigint") {
-    return value.toString();
+    return canonicalType("bigint", value.toString());
   }
 
   if (value instanceof Date) {
-    return value.toISOString();
+    if (!Number.isFinite(value.getTime())) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint an invalid Date value.",
+      );
+    }
+    return canonicalType("date", value.toISOString());
   }
 
   if (Array.isArray(value)) {
-    return value.map(
-      (item, index) =>
-        canonicalize(item, options, [...path, String(index)], seen) ?? null,
-    );
+    if (seen.has(value)) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint circular values.",
+      );
+    }
+    seen.add(value);
+    const result: CanonicalValue = Array.from(value, (item, index) => {
+      const nestedValue = canonicalize(
+        item,
+        options,
+        [...path, String(index)],
+        seen,
+      );
+      return nestedValue === undefined ? canonicalType("omitted") : nestedValue;
+    });
+    seen.delete(value);
+    return result;
   }
 
   if (typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint unsupported object values. Use plain objects, arrays, Dates, and JSON primitives.",
+      );
+    }
+    if (Object.hasOwn(value, CANONICAL_TYPE_KEY)) {
+      throw new IdempotencyFingerprintError(
+        `Cannot fingerprint an object containing the reserved key "${CANONICAL_TYPE_KEY}".`,
+      );
+    }
     if (seen.has(value)) {
       throw new IdempotencyFingerprintError(
         "Cannot fingerprint circular values.",
@@ -915,7 +959,7 @@ function canonicalize(
     }
     seen.add(value);
 
-    const result: Record<string, CanonicalValue> = {};
+    const result: Record<string, CanonicalValue> = Object.create(null);
     for (const key of Object.keys(value as Record<string, unknown>).sort()) {
       const nestedValue = canonicalize(
         (value as Record<string, unknown>)[key],
@@ -946,9 +990,13 @@ function bytesToHex(bytes: ArrayBuffer): string {
 /**
  * Create a SHA-256 fingerprint from a canonicalized value.
  *
- * Object keys are sorted, `undefined` and functions are omitted, `Date` values
- * become ISO strings, BigInts become strings, and circular or non-finite values
- * throw. Exact omit paths may be supplied as dotted strings or string arrays.
+ * Object keys are sorted, while non-JSON values carry reserved type tags so
+ * BigInts and Dates cannot collide with same-looking strings. Ordinary JSON
+ * inputs retain their existing canonical representation. `undefined` values
+ * and functions are omitted from objects and represented as omitted array
+ * positions. Circular or unsupported object values, reserved tag keys,
+ * invalid dates, and non-finite numbers throw. Exact omit paths may be supplied
+ * as dotted strings or string arrays.
  */
 export async function createIdempotencyFingerprint(
   value: unknown,
@@ -961,7 +1009,7 @@ export async function createIdempotencyFingerprint(
   }
 
   const canonical = canonicalize(value, options, [], new WeakSet());
-  const json = JSON.stringify(canonical ?? null);
+  const json = JSON.stringify(canonical ?? canonicalType("omitted"));
   const digest = await globalThis.crypto.subtle.digest(
     "SHA-256",
     new TextEncoder().encode(json),

package/src/mail/index.ts

@@ -403,13 +403,17 @@ export function createMemoryMailerProvider(
           onSend,
         },
         (delivery, durationMs) => {
+          const recipientCount =
+            delivery.message.to.length +
+            (delivery.message.cc?.length ?? 0) +
+            (delivery.message.bcc?.length ?? 0);
           instrumentation.custom({
             name: "mail.sent",
             label: "Mail sent",
-            summary: delivery.message.subject,
+            summary: "Mail sent",
             details: {
-              to: delivery.message.to,
-              subject: delivery.message.subject,
+              provider: "memory",
+              recipientCount,
               id: delivery.id,
               durationMs,
             },