@beignet/core 0.0.48 → 0.0.50

package/src/openapi/index.ts

@@ -11,6 +11,8 @@ import {
   getContractHeaderSchemas,
   methodSupportsRequestBody,
   parsePathTemplate,
+  type QueryFieldTransport,
+  queryTransportSchema,
   resolveContract,
   STANDARD_ERROR_RESPONSE_SCHEMA,
 } from "../contracts/index.js";
@@ -20,7 +22,9 @@ import {
 } from "../contracts/lifecycle.js";
 import {
   comparePathParamsToTemplate,
+  compareQueryTransportFields,
   formatPathParamsMismatch,
+  formatQueryTransportMismatch,
 } from "../contracts/schema-shape.js";
 import {
   createZodIntrospector,
@@ -157,6 +161,21 @@ export interface ParameterObject {
    * Parameter schema.
    */
   schema?: SchemaObject | ReferenceObject;
+  /**
+   * OpenAPI parameter serialization style.
+   */
+  style?:
+    | "form"
+    | "simple"
+    | "matrix"
+    | "label"
+    | "spaceDelimited"
+    | "pipeDelimited"
+    | "deepObject";
+  /**
+   * Whether arrays and objects are expanded into separate parameter values.
+   */
+  explode?: boolean;
   /**
    * Parameter description.
    */
@@ -627,12 +646,36 @@ function addQueryParams(
   state: GeneratorState,
 ): void {
   if (!contract.query) return;
+  const transport = contract.queryTransport;
+  if (!transport) {
+    throw new Error(
+      `Contract "${contract.name}" declares a query schema without a query transport.`,
+    );
+  }
 
   const shape = state.introspector.getShape(contract.query);
-  if (!shape) return;
+  if (!shape) {
+    throw new Error(
+      `Unable to inspect query schema for contract "${contract.name}". Pass a schemaIntrospector that can read its fields so OpenAPI requiredness and constraints remain aligned with the declared query transport.`,
+    );
+  }
 
-  for (const key of Object.keys(shape)) {
+  const schemaKeys = Object.keys(shape);
+  const transportKeys = Object.keys(transport.fields);
+  if (!compareQueryTransportFields({ schemaKeys, transportKeys })) {
+    throw new Error(
+      formatQueryTransportMismatch({
+        contractName: contract.name,
+        schemaKeys,
+        transportKeys,
+      }),
+    );
+  }
+
+  for (const key of Object.keys(transport.fields)) {
     const originalField = shape[key];
+    const fieldTransport = transport.fields[key];
+    if (!originalField || !fieldTransport) continue;
     const optional = state.introspector.isOptional(originalField);
 
     const field = originalField;
@@ -644,6 +687,7 @@ function addQueryParams(
       state,
       "input",
     );
+    applyQueryTransportSchema(paramSchemaRef, fieldTransport, state);
 
     const param: ParameterObject = {
       name: key,
@@ -651,12 +695,92 @@ function addQueryParams(
       required: !optional,
       schema: paramSchemaRef,
       description,
+      style: fieldTransport.kind === "deep-object" ? "deepObject" : "form",
+      explode: true,
     };
 
     addParameter(operation, param);
   }
 }
 
+function applyQueryTransportSchema(
+  schema: SchemaObject | ReferenceObject,
+  transport: QueryFieldTransport,
+  state: GeneratorState,
+): void {
+  if (!("$ref" in schema) || typeof schema.$ref !== "string") return;
+  const prefix = "#/components/schemas/";
+  if (!schema.$ref.startsWith(prefix)) return;
+  const name = schema.$ref.slice(prefix.length);
+  const converted = state.components.schemas?.[name];
+  if (!converted || !state.components.schemas) return;
+  state.components.schemas[name] = mergeQueryTransportSchema(
+    converted,
+    transport,
+  );
+}
+
+function mergeQueryTransportSchema(
+  converted: SchemaObject,
+  transport: QueryFieldTransport,
+): SchemaObject {
+  const declared = queryTransportSchema(transport);
+  const merged: SchemaObject = {
+    ...converted,
+    type: declared.type,
+  };
+  if (declared.format) merged.format = declared.format;
+  if (transport.kind === "integer") {
+    merged.minimum = Math.max(
+      typeof converted.minimum === "number"
+        ? converted.minimum
+        : Number.MIN_SAFE_INTEGER,
+      Number.MIN_SAFE_INTEGER,
+    );
+    merged.maximum = Math.min(
+      typeof converted.maximum === "number"
+        ? converted.maximum
+        : Number.MAX_SAFE_INTEGER,
+      Number.MAX_SAFE_INTEGER,
+    );
+  }
+  if (declared["x-beignet-empty-query"]) {
+    merged["x-beignet-empty-query"] = declared["x-beignet-empty-query"];
+  }
+
+  if (transport.kind === "array") {
+    const convertedItems =
+      typeof converted.items === "object" && converted.items !== null
+        ? (converted.items as SchemaObject)
+        : {};
+    merged.items = mergeQueryTransportSchema(convertedItems, transport.item);
+  }
+
+  if (transport.kind === "deep-object") {
+    const convertedProperties =
+      typeof converted.properties === "object" && converted.properties !== null
+        ? (converted.properties as Record<string, unknown>)
+        : {};
+    merged.properties = Object.fromEntries(
+      Object.entries(transport.fields).map(([key, field]) => {
+        const convertedProperty = convertedProperties[key];
+        return [
+          key,
+          mergeQueryTransportSchema(
+            typeof convertedProperty === "object" && convertedProperty !== null
+              ? (convertedProperty as SchemaObject)
+              : {},
+            field,
+          ),
+        ];
+      }),
+    );
+    merged.additionalProperties = false;
+  }
+
+  return merged;
+}
+
 /**
  * Add header parameters from contract to operation.
  */

package/src/outbox/index.ts

@@ -555,7 +555,8 @@ export interface DrainOutboxOptions {
    */
   registry: OutboxRegistry;
   /**
-   * Event bus used for event messages.
+   * Event bus used for event messages. Required when the registry contains
+   * events.
    */
   eventBus?: {
     publish<E extends EventPayloadDef>(
@@ -565,7 +566,8 @@ export interface DrainOutboxOptions {
     ): MaybePromise<void>;
   };
   /**
-   * Job dispatcher used for job messages.
+   * Job dispatcher used for job messages. Required when the registry contains
+   * jobs.
    */
   jobs?: JobDispatcherPort;
   /**
@@ -1476,15 +1478,17 @@ async function deliverOutboxMessage(
  * Claim and deliver one batch of outbox messages.
  *
  * This does not loop forever; production workers should call it on their own
- * polling cadence. Event and job messages require matching registry entries.
- * Failed messages are retried with backoff until `maxAttempts`, then
- * dead-lettered.
+ * polling cadence. Event and job messages require matching registry entries
+ * and delivery transports. Required transports are validated before a batch
+ * is claimed. Failed messages are retried with backoff until `maxAttempts`,
+ * then dead-lettered.
  */
 export async function drainOutbox(
   options: DrainOutboxOptions,
 ): Promise<DrainOutboxResult> {
   const batchSize = options.batchSize ?? 100;
   assertPositiveInteger("batchSize", batchSize);
+  assertOutboxDeliveryCapabilities(options);
   const instrumentation = createProviderInstrumentation(
     options.instrumentation,
     {
@@ -1659,6 +1663,23 @@ export async function drainOutbox(
   return result;
 }
 
+function assertOutboxDeliveryCapabilities(options: DrainOutboxOptions): void {
+  const missing: string[] = [];
+
+  if (options.registry.events.size > 0 && !options.eventBus) {
+    missing.push("events require an event bus");
+  }
+  if (options.registry.jobs.size > 0 && !options.jobs) {
+    missing.push("jobs require a job dispatcher");
+  }
+
+  if (missing.length > 0) {
+    throw new OutboxRegistryError(
+      `Cannot drain this outbox registry: ${missing.join("; ")}.`,
+    );
+  }
+}
+
 /**
  * Domain event recorder port re-exported for outbox integrations.
  */

package/src/ports/best-effort-work.ts

@@ -0,0 +1,21 @@
+/**
+ * Non-durable work scheduled outside the originating application operation.
+ */
+export type BestEffortWork = () => Promise<void> | void;
+
+/**
+ * Non-durable, best-effort follow-up work.
+ *
+ * Use this for follow-up work that may be lost without changing the outcome
+ * of the originating operation. Required or retryable work belongs in a job
+ * or durable outbox instead.
+ */
+export interface BestEffortWorkPort {
+  /**
+   * Schedule work without waiting for it in the originating operation.
+   *
+   * Adapters should isolate scheduling and callback failures from the caller
+   * and report them through their configured error observer.
+   */
+  defer(work: BestEffortWork): void;
+}

package/src/ports/cache.ts

@@ -3,11 +3,35 @@
  */
 export interface CacheSetOptions {
   /**
-   * Time-to-live in seconds. Omit this for a value that does not expire.
+   * Time-to-live in seconds. Values must be positive safe integers. Omit this
+   * for a value that does not expire.
    */
   ttlSeconds?: number;
 }
 
+/**
+ * Resolve and validate the optional TTL shared by cache adapters.
+ *
+ * @param options - Cache write options.
+ * @returns The positive TTL, or `undefined` for a persistent value.
+ */
+export function resolveCacheTtlSeconds(
+  options?: CacheSetOptions,
+): number | undefined {
+  const ttlSeconds = options?.ttlSeconds;
+  if (ttlSeconds === undefined) {
+    return undefined;
+  }
+
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds <= 0) {
+    throw new RangeError(
+      "Cache ttlSeconds must be a positive safe integer when provided.",
+    );
+  }
+
+  return ttlSeconds;
+}
+
 /**
  * App-facing string cache port.
  *
@@ -54,15 +78,12 @@ type MemoryCacheEntry = {
 };
 
 function resolveExpiresAt(options: CacheSetOptions | undefined): number | null {
-  if (options?.ttlSeconds == null) {
+  const ttlSeconds = resolveCacheTtlSeconds(options);
+  if (ttlSeconds === undefined) {
     return null;
   }
 
-  if (options.ttlSeconds <= 0) {
-    return Date.now();
-  }
-
-  return Date.now() + options.ttlSeconds * 1000;
+  return Math.min(Number.MAX_SAFE_INTEGER, Date.now() + ttlSeconds * 1000);
 }
 
 function isExpired(entry: MemoryCacheEntry): boolean {
@@ -120,6 +141,7 @@ export function createMemoryCache(
       return (await getFreshEntry(key)) != null;
     },
     async remember(key, factory, options) {
+      resolveCacheTtlSeconds(options);
       const cached = await cache.get(key);
       if (cached != null) {
         return cached;

package/src/ports/events.ts

@@ -1,9 +1,13 @@
 import type {
   EventPayloadDef,
   EventPublishOptions,
+  EventSubscription,
   InferEventPayload as InferContractEventPayload,
   StandardSchema,
 } from "../events/index.js";
+
+export type { EventSubscription } from "../events/index.js";
+
 import type {
   JobDef as ContractJobDef,
   InferJobPayload as InferContractJobPayload,
@@ -58,15 +62,16 @@ export type InferJobPayload<J extends JobDef> = InferContractJobPayload<J>;
  * const eventBus = createMemoryEventBus();
  *
  * // Subscribe to an event
- * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+ * const subscription = eventBus.subscribe(UserRegistered, (payload) => {
  *   console.log(`User registered: ${payload.email}`);
  * });
+ * await subscription.ready;
  *
  * // Publish an event
  * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
  *
  * // Unsubscribe when done
- * unsubscribe();
+ * await subscription.unsubscribe();
  * ```
  */
 export interface EventBusPort {
@@ -80,7 +85,7 @@ export interface EventBusPort {
   ): Promise<void> | void;
 
   /**
-   * Subscribe to a domain event. Returns an unsubscribe function.
+   * Subscribe to a domain event. Returns initial readiness and cleanup.
    */
   subscribe<E extends DomainEventDef>(
     event: E,
@@ -88,7 +93,7 @@ export interface EventBusPort {
       payload: InferEventPayload<E>,
       options?: EventPublishOptions,
     ) => Promise<void> | void,
-  ): () => void;
+  ): EventSubscription;
 }
 
 /**

package/src/ports/index.ts

@@ -8,6 +8,7 @@
  * - `definePorts` – helper to define a typed ports object
  * - `PortsContext` – a generic type that describes ctx objects that carry ports
  * - `EventBusPort` – interface for event bus implementations
+ * - `BestEffortWorkPort` – interface for non-durable follow-up work
  * - `JobDispatcherPort` – interface for job dispatch implementations
  * - `UnitOfWorkPort` – interface for app-owned transaction boundaries
  * - `OutboxPort` – interface for durable event/job delivery storage
@@ -468,6 +469,13 @@ export {
   requireUserId,
   TenantRequiredError,
 } from "./auth.js";
+/**
+ * Best-effort work port exports.
+ */
+export type {
+  BestEffortWork,
+  BestEffortWorkPort,
+} from "./best-effort-work.js";
 /**
  * Ports builder exports.
  */
@@ -483,7 +491,7 @@ export type { CachePort, CacheSetOptions } from "./cache.js";
 /**
  * Cache helper exports.
  */
-export { createMemoryCache } from "./cache.js";
+export { createMemoryCache, resolveCacheTtlSeconds } from "./cache.js";
 /**
  * Clock port exports.
  */
@@ -498,6 +506,7 @@ export { createFrozenClock, createSystemClock } from "./clock.js";
 export type {
   DomainEventDef,
   EventBusPort,
+  EventSubscription,
   InferEventPayload,
   InferJobPayload,
   JobDef,

package/src/ports/testing.ts

@@ -38,6 +38,7 @@ import {
   createTenant,
   createUserActor,
 } from "./audit.js";
+import type { BestEffortWork, BestEffortWorkPort } from "./best-effort-work.js";
 import type { EventBusPort, JobDef, JobDispatcherPort } from "./events.js";
 import {
   type CreateGateOptions,
@@ -114,6 +115,50 @@ export function createRecordingEventBus(): {
   return { bus, events };
 }
 
+/**
+ * Recording best-effort-work adapter for deterministic tests.
+ *
+ * Calls to `defer(...)` append work without running it. `flush()` runs the
+ * currently pending batch in FIFO order, then rejects with the callback error
+ * or an `AggregateError` after every callback in that batch has been attempted.
+ * Work deferred by a running callback remains pending for the next flush so
+ * one flush stays bounded.
+ */
+export function createRecordingBestEffortWork(): {
+  bestEffortWork: BestEffortWorkPort;
+  pending: BestEffortWork[];
+  flush(): Promise<void>;
+} {
+  const pending: BestEffortWork[] = [];
+
+  return {
+    bestEffortWork: {
+      defer(work) {
+        pending.push(work);
+      },
+    },
+    pending,
+    async flush() {
+      const batch = pending.splice(0);
+      const errors: unknown[] = [];
+      for (const work of batch) {
+        try {
+          await work();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+
+      if (errors.length === 1) {
+        throw errors[0];
+      }
+      if (errors.length > 1) {
+        throw new AggregateError(errors, "Best-effort work batch failed.");
+      }
+    },
+  };
+}
+
 /**
  * A job dispatch captured by `createRecordingJobDispatcher(...)`.
  */

package/src/providers/provider.ts

@@ -55,9 +55,11 @@ export type MaybePromise<T> = T | Promise<T>;
 /**
  * Late-bound service context factory exposed to providers.
  *
- * Calling it before all providers have started throws, so providers should
- * only invoke it from runtime entrypoints such as job dispatch, listeners, or
- * scheduled work.
+ * Calling it during provider setup or after provider shutdown throws. Start
+ * and stop hooks may invoke it after every provider has contributed ports and
+ * the server has verified that no deferred port remains unbound. Runtime
+ * entrypoints such as job dispatch, listeners, or scheduled work can close
+ * over it for later use.
  *
  * App-local providers can type the factory by declaring `Context` and
  * `ServiceInput` through the curried `createProvider<Requires, Context,
@@ -222,8 +224,9 @@ export interface ServiceProvider<
    * @param ctx.ports - Ports contributed by previous providers
    * @param ctx.config - Validated config (if config was defined), or undefined
    * @param ctx.createServiceContext - Late-bound service context factory.
-   * Throws until all providers have started, so call it lazily from runtime
-   * entrypoints such as job dispatchers and event listeners.
+   * Throws during setup. Start and stop hooks may invoke it after all provider
+   * ports have been contributed and validated; runtime entrypoints such as job
+   * dispatchers and event listeners may call it lazily afterward.
    */
   setup(ctx: {
     ports: Readonly<Ports>;

package/src/server/hooks/cors.ts

@@ -2,7 +2,11 @@
  * CORS hook utilities for @beignet/core/server
  */
 
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 
 /**
  * CORS configuration for `createCorsHooks(...)`.
@@ -55,10 +59,12 @@ function resolveCorsConfig(config: CorsConfig): Required<CorsConfig> {
   return resolved;
 }
 
-function appendVaryOrigin(headers: Record<string, string>): void {
+function appendVaryOrigin(headers: HttpResponseHeaders): void {
   const varyKey =
     Object.keys(headers).find((key) => key.toLowerCase() === "vary") ?? "Vary";
-  const current = headers[varyKey];
+  const currentValue = headers[varyKey];
+  const current =
+    typeof currentValue === "string" ? currentValue : currentValue?.join(", ");
   const values = current?.split(",").map((value) => value.trim().toLowerCase());
   if (values?.includes("origin")) return;
 
@@ -72,7 +78,7 @@ function appendVaryOrigin(headers: Record<string, string>): void {
  * when cookies or authorization headers are allowed cross-origin.
  */
 export function applyCorsHeaders(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   req: HttpRequestLike,
   corsConfig: CorsConfig,
 ): void {
@@ -121,7 +127,7 @@ export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
       ) {
         return undefined;
       }
-      const headers: Record<string, string> = {};
+      const headers: HttpResponseHeaders = {};
       applyCorsHeaders(headers, req, corsConfig);
       return {
         status: 204,

package/src/server/hooks/logging.ts

@@ -7,7 +7,11 @@ import {
   resolveTrustedRequest,
   type TrustedRequestInfo,
 } from "../trusted-proxy.js";
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 import { getRequestIdFromContext } from "./utils.js";
 
 /**
@@ -60,7 +64,7 @@ export interface LoggingConfig<Ctx> {
     ctx?: Ctx;
     req: HttpRequestLike;
     requestInfo: TrustedRequestInfo;
-    res: { status: number; headers: Record<string, string> };
+    res: { status: number; headers: HttpResponseHeaders };
     durationMs: number;
     contract?: HttpContractConfig;
     error?: unknown;