@beignet/core 0.0.50 → 0.0.52

package/src/events/payload-state.ts

@@ -0,0 +1,223 @@
+import type { EventPublishOptions } from "./index.js";
+import type { EventTransportValue } from "./transport.js";
+
+const PARSED_EVENT_PAYLOAD = Symbol.for("beignet.eventPayload.parsed");
+const TRANSPORT_STABLE_EVENT_PAYLOAD = Symbol.for(
+  "beignet.eventPayload.transportStable",
+);
+
+type ParsedEventPublishOptions = EventPublishOptions & {
+  [PARSED_EVENT_PAYLOAD]?: object;
+  [TRANSPORT_STABLE_EVENT_PAYLOAD]?: object;
+};
+
+interface ParsedPayloadState {
+  readonly eventName: string;
+  readonly payloadSchema: object;
+  readonly validate: unknown;
+  readonly payload: unknown;
+}
+
+type PayloadSnapshot =
+  | { readonly kind: "primitive"; readonly value: unknown }
+  | {
+      readonly kind: "array";
+      readonly value: object;
+      readonly prototype: object | null;
+      readonly items: readonly PayloadSnapshot[];
+    }
+  | {
+      readonly kind: "object";
+      readonly value: object;
+      readonly prototype: object | null;
+      readonly entries: readonly (readonly [string, PayloadSnapshot])[];
+    };
+
+interface TransportStablePayloadState {
+  readonly eventName: string;
+  readonly payloadSchema: object;
+  readonly validate: unknown;
+  readonly payload: PayloadSnapshot;
+  readonly fingerprint: string;
+}
+
+interface EventPayloadIdentity {
+  readonly name: string;
+  readonly payload: {
+    readonly "~standard": {
+      readonly validate: unknown;
+    };
+  };
+}
+
+const transportStablePayloadStates = new WeakMap<
+  object,
+  TransportStablePayloadState
+>();
+const parsedPayloadStates = new WeakMap<object, ParsedPayloadState>();
+
+function transportFingerprint(value: EventTransportValue): string {
+  return JSON.stringify(value);
+}
+
+function capturePayloadSnapshot(value: unknown): PayloadSnapshot {
+  if (value === null || typeof value !== "object") {
+    return { kind: "primitive", value };
+  }
+  if (Array.isArray(value)) {
+    const items: PayloadSnapshot[] = [];
+    for (let index = 0; index < value.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor || !("value" in descriptor)) {
+        throw new TypeError(
+          "Transport-stable array state must contain data properties.",
+        );
+      }
+      items.push(capturePayloadSnapshot(descriptor.value));
+    }
+    return {
+      kind: "array",
+      value,
+      prototype: Object.getPrototypeOf(value),
+      items,
+    };
+  }
+  return {
+    kind: "object",
+    value,
+    prototype: Object.getPrototypeOf(value),
+    entries: Reflect.ownKeys(value).map((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (typeof key !== "string" || !descriptor || !("value" in descriptor)) {
+        throw new TypeError(
+          "Transport-stable payload state must contain data properties.",
+        );
+      }
+      return [key, capturePayloadSnapshot(descriptor.value)] as const;
+    }),
+  };
+}
+
+function matchesPayloadSnapshot(
+  snapshot: PayloadSnapshot,
+  value: unknown,
+): boolean {
+  if (snapshot.kind === "primitive") return Object.is(snapshot.value, value);
+  if (snapshot.value !== value || value === null || typeof value !== "object") {
+    return false;
+  }
+  if (Object.getPrototypeOf(value) !== snapshot.prototype) return false;
+  if (snapshot.kind === "array") {
+    return (
+      Array.isArray(value) &&
+      value.length === snapshot.items.length &&
+      snapshot.items.every((item, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          value,
+          String(index),
+        );
+        return (
+          descriptor !== undefined &&
+          "value" in descriptor &&
+          matchesPayloadSnapshot(item, descriptor.value)
+        );
+      })
+    );
+  }
+  if (Array.isArray(value)) return false;
+  const keys = Reflect.ownKeys(value);
+  return (
+    keys.length === snapshot.entries.length &&
+    snapshot.entries.every(([key, item], index) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return (
+        keys[index] === key &&
+        descriptor !== undefined &&
+        "value" in descriptor &&
+        matchesPayloadSnapshot(item, descriptor.value)
+      );
+    })
+  );
+}
+
+export function markEventPayloadParsed(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  options?: EventPublishOptions,
+): EventPublishOptions {
+  const token = {};
+  parsedPayloadStates.set(token, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload,
+  });
+  return {
+    ...options,
+    [PARSED_EVENT_PAYLOAD]: token,
+  } as ParsedEventPublishOptions;
+}
+
+export function isEventPayloadParsed(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  options?: EventPublishOptions,
+): boolean {
+  const token = (options as ParsedEventPublishOptions | undefined)?.[
+    PARSED_EVENT_PAYLOAD
+  ];
+  const state = token ? parsedPayloadStates.get(token) : undefined;
+  return (
+    state?.eventName === event.name &&
+    state.payloadSchema === event.payload &&
+    state.validate === event.payload["~standard"].validate &&
+    Object.is(state.payload, payload)
+  );
+}
+
+export function markEventPayloadTransportStable(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  transportValue: EventTransportValue,
+  options?: EventPublishOptions,
+): EventPublishOptions {
+  const parsedToken = {};
+  parsedPayloadStates.set(parsedToken, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload,
+  });
+  const stableToken = {};
+  transportStablePayloadStates.set(stableToken, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload: capturePayloadSnapshot(payload),
+    fingerprint: transportFingerprint(transportValue),
+  });
+  return {
+    ...options,
+    [PARSED_EVENT_PAYLOAD]: parsedToken,
+    [TRANSPORT_STABLE_EVENT_PAYLOAD]: stableToken,
+  } as ParsedEventPublishOptions;
+}
+
+export function isEventPayloadTransportStable(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  transportValue: EventTransportValue,
+  options?: EventPublishOptions,
+): boolean {
+  const token = (options as ParsedEventPublishOptions | undefined)?.[
+    TRANSPORT_STABLE_EVENT_PAYLOAD
+  ];
+  const state = token ? transportStablePayloadStates.get(token) : undefined;
+  return (
+    state?.eventName === event.name &&
+    state.payloadSchema === event.payload &&
+    state.validate === event.payload["~standard"].validate &&
+    matchesPayloadSnapshot(state.payload, payload) &&
+    state.fingerprint === transportFingerprint(transportValue)
+  );
+}

package/src/events/transport.ts

@@ -0,0 +1,242 @@
+/** Canonical JSON value that can cross an event transport boundary. */
+export type EventTransportValue =
+  | null
+  | string
+  | number
+  | boolean
+  | readonly EventTransportValue[]
+  | { readonly [key: string]: EventTransportValue };
+
+/** Why an event payload cannot safely cross a serialized transport. */
+export type EventTransportErrorReason = "not-json-safe" | "not-stable";
+
+/** Error thrown when an event payload cannot survive canonical JSON transport. */
+export class EventTransportError extends Error {
+  /** Stable event name. */
+  readonly eventName: string;
+  /** Whether the value is not JSON-safe or changes under repeated parsing. */
+  readonly reason: EventTransportErrorReason;
+  /** Payload path associated with a JSON-safety failure. */
+  readonly path?: string;
+
+  constructor(args: {
+    eventName: string;
+    reason: EventTransportErrorReason;
+    message: string;
+    path?: string;
+    cause?: unknown;
+  }) {
+    super(`Event "${args.eventName}" payload ${args.message}`, {
+      cause: args.cause,
+    });
+    this.name = "EventTransportError";
+    this.eventName = args.eventName;
+    this.reason = args.reason;
+    this.path = args.path;
+  }
+}
+
+function childTransportPath(path: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+    ? `${path}.${key}`
+    : `${path}[${JSON.stringify(key)}]`;
+}
+
+function throwJsonSafetyError(args: {
+  eventName: string;
+  path: string;
+  message: string;
+}): never {
+  throw new EventTransportError({
+    eventName: args.eventName,
+    reason: "not-json-safe",
+    path: args.path,
+    message: `is not transport-safe at ${args.path}: ${args.message}`,
+  });
+}
+
+export function toEventTransportValue(
+  eventName: string,
+  value: unknown,
+  path = "payload",
+  seen: WeakSet<object> = new WeakSet(),
+): EventTransportValue {
+  if (value === null) return null;
+
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "numbers must be finite.",
+      });
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+
+  if (typeof value !== "object") {
+    return throwJsonSafetyError({
+      eventName,
+      path,
+      message: `received ${typeof value}; use null, strings, finite numbers, booleans, arrays, or plain objects.`,
+    });
+  }
+
+  try {
+    if (value instanceof Date) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "Date values are not supported; use an ISO string or number.",
+      });
+    }
+
+    if (seen.has(value)) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "circular references are not supported.",
+      });
+    }
+
+    seen.add(value);
+    if (Array.isArray(value)) {
+      const output: EventTransportValue[] = [];
+      const ownKeys = Reflect.ownKeys(value);
+      const hasUnsupportedKey = ownKeys.some((key) => {
+        if (key === "length") return false;
+        if (typeof key !== "string") return true;
+        const index = Number(key);
+        return (
+          !Number.isInteger(index) ||
+          index < 0 ||
+          index >= value.length ||
+          String(index) !== key
+        );
+      });
+      if (hasUnsupportedKey) {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "arrays cannot contain symbol or custom properties.",
+        });
+      }
+      if (ownKeys.length !== value.length + 1) {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "sparse arrays are not supported.",
+        });
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        const key = String(index);
+        const itemPath = `${path}[${index}]`;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor) {
+          return throwJsonSafetyError({
+            eventName,
+            path: itemPath,
+            message: "sparse arrays are not supported.",
+          });
+        }
+        if (!("value" in descriptor) || !descriptor.enumerable) {
+          return throwJsonSafetyError({
+            eventName,
+            path: itemPath,
+            message: "array items must be enumerable data properties.",
+          });
+        }
+        output.push(
+          toEventTransportValue(eventName, descriptor.value, itemPath, seen),
+        );
+      }
+      return output;
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "objects must be plain objects.",
+      });
+    }
+
+    const output = {} as Record<string, EventTransportValue>;
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== "string") {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "symbol properties are not supported.",
+        });
+      }
+      const propertyPath = childTransportPath(path, key);
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+        return throwJsonSafetyError({
+          eventName,
+          path: propertyPath,
+          message: "properties must be enumerable data properties.",
+        });
+      }
+      Object.defineProperty(output, key, {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: toEventTransportValue(
+          eventName,
+          descriptor.value,
+          propertyPath,
+          seen,
+        ),
+      });
+    }
+    return output;
+  } catch (error) {
+    if (error instanceof EventTransportError) throw error;
+    throw new EventTransportError({
+      eventName,
+      reason: "not-json-safe",
+      path,
+      message: `could not be inspected as transport data at ${path}.`,
+      cause: error,
+    });
+  } finally {
+    seen.delete(value);
+  }
+}
+
+export function eventTransportValuesEqual(
+  left: EventTransportValue,
+  right: EventTransportValue,
+): boolean {
+  if (left === right) return true;
+  if (left === null || right === null || typeof left !== typeof right) {
+    return false;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right)) return false;
+    return (
+      left.length === right.length &&
+      left.every((value, index) =>
+        eventTransportValuesEqual(value, right[index]),
+      )
+    );
+  }
+  if (typeof left !== "object" || typeof right !== "object") return false;
+
+  const leftRecord = left as Readonly<Record<string, EventTransportValue>>;
+  const rightRecord = right as Readonly<Record<string, EventTransportValue>>;
+  const leftKeys = Object.keys(leftRecord).sort();
+  const rightKeys = Object.keys(rightRecord).sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key, index) =>
+        key === rightKeys[index] &&
+        eventTransportValuesEqual(leftRecord[key], rightRecord[key]),
+    )
+  );
+}

package/src/locks/index.ts

@@ -285,10 +285,6 @@ export function createMemoryLocksProvider(
 
   return createProvider({
     name,
-    metadata: {
-      ports: ["locks"],
-      watchers: ["locks"],
-    },
     setup({ ports }) {
       const instrumentation = createProviderInstrumentation(ports, {
         providerName: name,

package/src/openapi/index.ts

@@ -436,20 +436,58 @@ export function contractsToOpenAPI(
     ],
   };
   const operationIds = new Map<string, string>();
+  const operations = new Map<
+    string,
+    { readonly contractName: string; readonly route: string }
+  >();
+  const pathShapes = new Map<
+    string,
+    {
+      readonly contractName: string;
+      readonly pathKey: string;
+      readonly route: string;
+    }
+  >();
 
   for (const contract of contracts) {
     const config = resolveContract(contract);
     assertValidContractLifecycle(config);
+    const pathTemplate = parsePathTemplate(config.path);
+    const pathKey = pathTemplate.openApiPath;
+    const route = `${config.method.toUpperCase()} ${config.path}`;
+    const operationRoute = `${config.method.toUpperCase()} ${pathKey}`;
+    const conflictingOperation = operations.get(operationRoute);
+    if (conflictingOperation) {
+      throw new Error(
+        `Duplicate OpenAPI operation: ${operationRoute} is produced by both contract "${conflictingOperation.contractName}" (${conflictingOperation.route}) and contract "${config.name}" (${route}). Each method + normalized path combination must be unique within an OpenAPI document.`,
+      );
+    }
+    const conflictingPathShape = pathShapes.get(pathTemplate.shapeKey);
+    if (conflictingPathShape && conflictingPathShape.pathKey !== pathKey) {
+      throw new Error(
+        `Ambiguous OpenAPI path: ${pathKey} from contract "${config.name}" (${route}) conflicts with ${conflictingPathShape.pathKey} from contract "${conflictingPathShape.contractName}" (${conflictingPathShape.route}). Templated paths with the same hierarchy must use the same parameter names within an OpenAPI document.`,
+      );
+    }
     const operationId = getContractOperationId(config);
-    const route = `${config.method} ${config.path}`;
     const conflictingRoute = operationIds.get(operationId);
     if (conflictingRoute) {
       throw new Error(
         `Duplicate OpenAPI operationId: "${operationId}" is used by both ${conflictingRoute} and ${route}. Operation IDs must be unique within an OpenAPI document.`,
       );
     }
+    operations.set(operationRoute, {
+      contractName: config.name,
+      route,
+    });
+    if (!conflictingPathShape) {
+      pathShapes.set(pathTemplate.shapeKey, {
+        contractName: config.name,
+        pathKey,
+        route,
+      });
+    }
     operationIds.set(operationId, route);
-    addContractToPaths(config, paths, state);
+    addContractToPaths(config, pathKey, paths, state);
   }
 
   const openapi: OpenAPIObject = {
@@ -481,10 +519,10 @@ export function contractsToOpenAPI(
  */
 function addContractToPaths(
   contract: AnyContract,
+  pathKey: string,
   paths: PathsObject,
   state: GeneratorState,
 ): void {
-  const pathKey = parsePathTemplate(contract.path).openApiPath;
   if (!paths[pathKey]) {
     paths[pathKey] = {};
   }