@spfn/core 0.3.0-beta.17 → 0.3.0-beta.19

package/dist/contract/index.d.ts

@@ -1,10 +1,11 @@
+import { E as EventRouterDef } from '../router-CysBmgv3.js';
 import { R as Router } from '../router-BqyEARoY.js';
-import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-ClQVomgV.js';
-export { d as CompatibilityPolicy, e as ContractRequest, f as ContractViolationKind, J as JsonSchema } from '../types-ClQVomgV.js';
+import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-B4DuGCyM.js';
+export { d as CompatibilityPolicy, e as ContractEvent, f as ContractEvents, g as ContractRequest, h as ContractViolationKind, J as JsonSchema } from '../types-B4DuGCyM.js';
+import '@sinclair/typebox';
 import '../define-middleware-CVKgqo8S.js';
 import 'hono';
 import '../route-builder-2ani2jEI.js';
-import '@sinclair/typebox';
 import 'hono/utils/http-status';
 import '../route/types.js';
 
@@ -12,7 +13,8 @@ import '../route/types.js';
  * Contract Collection
  *
  * Walks a loaded router and turns every route carrying `.contract()` into a
- * contract operation.
+ * contract operation, and every event of an event router carrying
+ * `.contract()` into a contract event.
  *
  * The router is loaded and walked rather than parsed from source. Real routes
  * build their schemas from imported values — `EmailSchema`, `FileSchema()`,
@@ -26,11 +28,14 @@ declare class ContractCollectionError extends Error {
     constructor(message: string);
 }
 /**
- * Build the contract document from a loaded router.
+ * Build the contract document from a loaded router and, optionally, the app's
+ * event router.
  *
- * Routes without `.contract()` are skipped — they are not part of the promise.
+ * Routes and events without `.contract()` are skipped — they are not part of
+ * the promise. A document with no contracted event carries no `events` key, so
+ * it is byte-identical to one collected without an event router.
  */
-declare function collectContractDocument(router: Router<any>): ContractDocument;
+declare function collectContractDocument(router: Router<any>, eventRouter?: EventRouterDef<any>): ContractDocument;
 
 /**
  * Backward-compatibility comparison
@@ -52,6 +57,10 @@ declare function collectContractDocument(router: Router<any>): ContractDocument;
  * | required → optional     | pass    | refuse   |
  * | optional → required     | refuse  | pass     |
  * | type changed            | refuse  | refuse   |
+ *
+ * An event payload flows server → client like a response, so it is compared
+ * under the response rules by the same walk, and only the violation kinds are
+ * renamed.
  */
 
 interface DocumentComparison {
@@ -63,14 +72,19 @@ interface DocumentComparison {
      * whether any released app still calls it, which is a separate check.
      */
     removedOperations: string[];
+    /**
+     * Events present in the baseline and gone from the current contract —
+     * decided against usage files exactly as a removed operation is.
+     */
+    removedEvents: string[];
 }
 /** Compare one operation that exists on both sides. */
 declare function compareOperation(before: ContractOperation, after: ContractOperation): ContractViolation[];
 /**
  * Compare a released contract against the one this build produced.
  *
- * Operations that are new in `after` need no check — nothing has been promised
- * about them yet.
+ * Operations and events that are new in `after` need no check — nothing has
+ * been promised about them yet.
  */
 declare function compareDocuments(before: ContractDocument, after: ContractDocument): DocumentComparison;
 
@@ -79,7 +93,7 @@ declare function compareDocuments(before: ContractDocument, after: ContractDocum
  *
  * Puts the pieces together: read the newest released snapshot, compare this
  * build's contract against it, and decide removals against what released
- * clients still call.
+ * clients still call or subscribe to.
  *
  * Nothing released yet is a pass — with a warning. "This is the first contract"
  * and "the release that should have written a snapshot didn't" produce the same
@@ -181,12 +195,12 @@ declare function readCurrentDocument(contractsDir: string): ContractDocument;
 declare function writeCurrentDocument(contractsDir: string, document: ContractDocument): boolean;
 
 /**
- * Usage files — who still calls an operation
+ * Usage files — who still calls an operation or subscribes to an event
  *
  * A released app is compiled and shipped; the server cannot ask it what it
- * calls. So each released client writes down the operations it uses, and those
- * files are what a removal is judged against:
- * `contracts/usage/<platform>-<appVersion>.json`.
+ * calls. So each released client writes down the operations it uses and the
+ * events it subscribes to, and those files are what a removal is judged
+ * against: `contracts/usage/<platform>-<appVersion>.json`.
  *
  * The one rule this file exists to hold: **an unreadable file and "nobody calls
  * it" are not the same answer.** An empty scan result reading as a pass is how
@@ -198,6 +212,12 @@ interface UsageRecord {
     platform: string;
     appVersion: string;
     operations: string[];
+    /**
+     * Contracted events the client subscribes to. Always set when read from a
+     * file — a file without the key subscribes to none — and optional only so a
+     * record built by hand before events were contracted still type-checks.
+     */
+    events?: string[];
     /** File this came from, for messages. */
     file: string;
 }
@@ -217,5 +237,7 @@ type UsageReadResult = {
 declare function readUsageRecords(usageDir: string): UsageReadResult;
 /** Which released clients still call `operation`. */
 declare function callersOf(operation: string, records: UsageRecord[]): UsageRecord[];
+/** Which released clients still subscribe to `event`. */
+declare function subscribersOf(event: string, records: UsageRecord[]): UsageRecord[];
 
-export { CURRENT_FILENAME, type ContractCheckResult, ContractCollectionError, ContractDocument, ContractOperation, ContractSnapshot, ContractSnapshotError, ContractViolation, type DocumentComparison, RELEASED_DIRNAME, type SnapshotFile, USAGE_DIRNAME, type UsageReadResult, type UsageRecord, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, usageDir, writeCurrentDocument, writeSnapshot };
+export { CURRENT_FILENAME, type ContractCheckResult, ContractCollectionError, ContractDocument, ContractOperation, ContractSnapshot, ContractSnapshotError, ContractViolation, type DocumentComparison, RELEASED_DIRNAME, type SnapshotFile, USAGE_DIRNAME, type UsageReadResult, type UsageRecord, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, subscribersOf, usageDir, writeCurrentDocument, writeSnapshot };

package/dist/contract/index.js

@@ -2,6 +2,12 @@ import { createHash } from 'crypto';
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, statSync } from 'fs';
 import { join } from 'path';
 
+// src/event/sse/paths.ts
+var DEFAULT_SSE_STREAM_PATH = "/events/stream";
+function sseTokenPath(streamPath) {
+  return streamPath.replace(/\/[^/]+$/, "/token");
+}
+
 // src/contract/collect.ts
 var ContractCollectionError = class extends Error {
   constructor(message) {
@@ -104,15 +110,65 @@ function addOperation(name, routeDef, trail, found) {
     }
   });
 }
-function collectContractDocument(router) {
+var RESERVED_EVENT_NAMES = /* @__PURE__ */ new Set(["connected", "ping"]);
+function byName(a, b) {
+  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+function toContractEvent(name, eventDef) {
+  const contract = eventDef._contract;
+  if (RESERVED_EVENT_NAMES.has(name)) {
+    throw new ContractCollectionError(
+      `Contracted event "${name}" uses a reserved frame name. The stream itself sends "connected" and "ping" frames, so a client could not tell this event from them. Register the event under another key.`
+    );
+  }
+  if (!contract.since) {
+    throw new ContractCollectionError(
+      `Contracted event "${name}" has no "since" version. The version an event first appeared in is part of the promise.`
+    );
+  }
+  if (!eventDef.schema) {
+    throw new ContractCollectionError(
+      `Contracted event "${name}" declares no payload schema. Its frame carries no data, so there is nothing for the contract to describe. Declare Type.Object({}) and emit {} instead.`
+    );
+  }
+  return {
+    name,
+    since: contract.since,
+    ...contract.deprecatedIn ? { deprecatedIn: contract.deprecatedIn } : {},
+    ...contract.removedIn ? { removedIn: contract.removedIn } : {},
+    payload: toJsonSchema(eventDef.schema)
+  };
+}
+function collectEvents(eventRouter) {
+  const contracted = Object.entries(eventRouter?.events ?? {}).filter(([, eventDef]) => eventDef._contract);
+  if (contracted.length === 0) {
+    return void 0;
+  }
+  const routerContract = eventRouter._contract;
+  if (!routerContract) {
+    throw new ContractCollectionError(
+      `Event router defineEventRouter({ ${eventRouter.eventNames.join(", ")} }) contracts events but declares no .contract() of its own. Without it the contract cannot say whether a client must exchange a token before opening the stream. Add .contract({ auth: 'none' }) or .contract({ auth: 'tokenExchange' }) to the router.`
+    );
+  }
+  const streamPath = routerContract.streamPath ?? DEFAULT_SSE_STREAM_PATH;
+  return {
+    streamPath,
+    tokenPath: sseTokenPath(streamPath),
+    auth: routerContract.auth,
+    items: contracted.map(([name, eventDef]) => toContractEvent(name, eventDef)).sort(byName)
+  };
+}
+function collectContractDocument(router, eventRouter) {
   const found = /* @__PURE__ */ new Map();
   visitRouter(router, ["router"], found);
-  const operations = [...found.values()].map((entry) => entry.operation).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  const operations = [...found.values()].map((entry) => entry.operation).sort(byName);
+  const events = collectEvents(eventRouter);
   return {
     documentVersion: 1,
     ...router._contractVersion ? { contractVersion: router._contractVersion } : {},
     compatibilityPolicy: "perOperation",
-    operations
+    operations,
+    ...events ? { events } : {}
   };
 }
 function canonicalize(value) {
@@ -279,6 +335,52 @@ function compareOperation(before, after) {
   );
   return violations;
 }
+var PAYLOAD_KINDS = {
+  "response.field-removed": "event.payload.field-removed",
+  "response.field-became-optional": "event.payload.field-became-optional",
+  "response.type-changed": "event.payload.type-changed"
+};
+function compareEvent(before, after) {
+  const found = [];
+  compareSchema(before.payload, after.payload, "payload", { operation: before.name, side: "response", violations: found });
+  return found.map(({ kind, operation, ...rest }) => ({ ...rest, kind: PAYLOAD_KINDS[kind] ?? kind, event: operation }));
+}
+function compareStream(before, after) {
+  const violations = [];
+  if (before.streamPath !== after.streamPath) {
+    violations.push({
+      kind: "events.stream-path-changed",
+      detail: `stream path moved ${before.streamPath} \u2192 ${after.streamPath}; released clients open the old one`
+    });
+  }
+  if (before.auth !== after.auth) {
+    violations.push({
+      kind: "events.auth-changed",
+      detail: `stream auth changed ${before.auth} \u2192 ${after.auth}; released clients connect the old way`
+    });
+  }
+  return violations;
+}
+function compareEvents(before, after) {
+  if (!before) {
+    return { violations: [], removedEvents: [] };
+  }
+  if (!after) {
+    return { violations: [], removedEvents: before.items.map((item) => item.name) };
+  }
+  const current = new Map(after.items.map((item) => [item.name, item]));
+  const violations = compareStream(before, after);
+  const removedEvents = [];
+  for (const item of before.items) {
+    const now = current.get(item.name);
+    if (!now) {
+      removedEvents.push(item.name);
+      continue;
+    }
+    violations.push(...compareEvent(item, now));
+  }
+  return { violations, removedEvents };
+}
 function compareDocuments(before, after) {
   const current = new Map(after.operations.map((operation) => [operation.name, operation]));
   const violations = [];
@@ -291,7 +393,12 @@ function compareDocuments(before, after) {
     }
     violations.push(...compareOperation(operation, now));
   }
-  return { violations, removedOperations };
+  const events = compareEvents(before.events, after.events);
+  return {
+    violations: [...violations, ...events.violations],
+    removedOperations,
+    removedEvents: events.removedEvents
+  };
 }
 var ContractSnapshotError = class extends Error {
   constructor(message) {
@@ -454,10 +561,15 @@ function parseRecord(file, raw) {
   if (!Array.isArray(parsed.operations) || parsed.operations.some((name) => typeof name !== "string")) {
     throw new Error('"operations" must be an array of operation names');
   }
+  const events = parsed.events ?? [];
+  if (!Array.isArray(events) || events.some((name) => typeof name !== "string")) {
+    throw new Error('"events" must be an array of event names');
+  }
   return {
     platform: parsed.platform,
     appVersion: parsed.appVersion,
     operations: parsed.operations,
+    events,
     file
   };
 }
@@ -489,6 +601,9 @@ function readUsageRecords(usageDir2) {
 function callersOf(operation, records) {
   return records.filter((record) => record.operations.includes(operation));
 }
+function subscribersOf(event, records) {
+  return records.filter((record) => (record.events ?? []).includes(event));
+}
 
 // src/contract/check.ts
 function checkContract(contractsDir, current) {
@@ -514,45 +629,54 @@ function checkContract(contractsDir, current) {
       }]
     };
   }
-  const { violations, removedOperations } = compareDocuments(previous, current);
+  const { violations, removedOperations, removedEvents } = compareDocuments(previous, current);
   return {
     baselineVersion: baseline.version,
     warnings: [],
-    violations: [...violations, ...judgeRemovals(contractsDir, removedOperations)]
+    violations: [...violations, ...judgeRemovals(contractsDir, removedOperations, removedEvents)]
   };
 }
-function judgeRemovals(contractsDir, removedOperations) {
-  if (removedOperations.length === 0) {
+function judgeRemovals(contractsDir, removedOperations, removedEvents) {
+  const removed = [...removedOperations, ...removedEvents];
+  if (removed.length === 0) {
     return [];
   }
   const usage = readUsageRecords(usageDir(contractsDir));
   if (!usage.decidable) {
     return [{
       kind: "usage.undecidable",
-      detail: `${removedOperations.join(", ")} would be removed, but no released client's call list could be read (${usage.reason}). Not knowing who calls an operation is not the same as knowing nobody does.`
+      detail: `${removed.join(", ")} would be removed, but no released client's usage list could be read (${usage.reason}). Not knowing who uses it is not the same as knowing nobody does.`
     }];
   }
-  const violations = [];
-  for (const operation of removedOperations) {
-    const callers = callersOf(operation, usage.records);
-    if (callers.length === 0) {
-      continue;
-    }
-    violations.push({
-      kind: "usage.still-called",
-      operation,
-      detail: "still called by " + callers.map((caller) => `${caller.platform} ${caller.appVersion}`).join(", ")
-    });
+  return [
+    ...removedOperations.flatMap((operation) => stillUsed(
+      { kind: "usage.still-called", operation },
+      "still called by",
+      callersOf(operation, usage.records)
+    )),
+    ...removedEvents.flatMap((event) => stillUsed(
+      { kind: "usage.still-subscribed", event },
+      "still subscribed to by",
+      subscribersOf(event, usage.records)
+    ))
+  ];
+}
+function stillUsed(subject, verb, users) {
+  if (users.length === 0) {
+    return [];
   }
-  return violations;
+  return [{
+    ...subject,
+    detail: `${verb} ${users.map((user) => `${user.platform} ${user.appVersion}`).join(", ")}`
+  }];
 }
 function formatViolations(violations) {
   return violations.map((violation) => {
-    const where = [violation.operation, violation.location].filter(Boolean).join(" ");
+    const where = [violation.operation ?? violation.event, violation.location].filter(Boolean).join(" ");
     return `  - [${violation.kind}]${where ? ` ${where}` : ""}: ${violation.detail}`;
   }).join("\n");
 }
 
-export { CURRENT_FILENAME, ContractCollectionError, ContractSnapshotError, RELEASED_DIRNAME, USAGE_DIRNAME, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, usageDir, writeCurrentDocument, writeSnapshot };
+export { CURRENT_FILENAME, ContractCollectionError, ContractSnapshotError, RELEASED_DIRNAME, USAGE_DIRNAME, callersOf, canonicalize, checkContract, collectContractDocument, compareDocuments, compareOperation, compareVersions, currentPath, formatViolations, listSnapshots, newestSnapshot, readCurrentDocument, readSnapshot, readUsageRecords, releasedDir, stableDigest, stableStringify, stableStringifyPretty, subscribersOf, usageDir, writeCurrentDocument, writeSnapshot };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map