autotel-message-contract 0.1.0

package/src/serializer.ts

@@ -0,0 +1,89 @@
+/**
+ * Message serializers.
+ *
+ * A contract pins the bytes a message becomes *once serialized* — the exact
+ * shape a consumer, a queue, or a stored event reads. The only way that
+ * snapshot is meaningful is if it is produced by the **same serializer your
+ * application ships with**. Pin a shape your consumers never see and you have
+ * pinned nothing.
+ *
+ * So a {@link MessageSerializer} is a tiny, explicit seam: `serialize` /
+ * `deserialize`. The default is JSON with deterministic key ordering (so a
+ * snapshot does not churn when object construction order changes), but you are
+ * encouraged to pass your app's real serializer — `superjson`, `devalue`, a
+ * snake_case Jackson-equivalent, a protobuf codec — so the snapshot records the
+ * exact bytes you put on the wire.
+ */
+
+/** A reversible mapping between an in-memory value and its serialized form. */
+export interface MessageSerializer<Serialized = string> {
+  /** Human-facing name, surfaced in snapshot headers and failure messages. */
+  readonly name: string;
+  /** Turn a value into its serialized form (the bytes you ship). */
+  serialize(value: unknown): Serialized;
+  /** Turn a serialized form back into a value. */
+  deserialize(serialized: Serialized): unknown;
+}
+
+/**
+ * Recursively sort object keys so two values with the same fields serialize
+ * identically regardless of insertion order. Arrays keep their order (it is
+ * semantically meaningful); plain objects are reordered; class instances,
+ * Maps, Sets, Dates, etc. are left untouched so the serializer can decide.
+ */
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((element) => sortKeysDeep(element));
+  }
+  if (value !== null && typeof value === 'object' && isPlainObject(value)) {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+export interface JsonSerializerOptions {
+  /**
+   * Pretty-print with this indent. Defaults to `2` so the approved file reads
+   * cleanly in a diff. Set to `0` to pin the compact bytes you actually ship.
+   */
+  indent?: number;
+  /**
+   * Sort object keys deterministically before serializing. Defaults to `true`
+   * so a snapshot reflects *fields*, not construction order. Turn it off when
+   * key order is itself part of the contract.
+   */
+  sortKeys?: boolean;
+}
+
+/**
+ * The default serializer: `JSON.stringify` with deterministic key ordering.
+ * Good enough to pin most events and commands; swap it for your own when the
+ * bytes you ship differ (custom date formats, snake_case, omitted nulls…).
+ */
+export function jsonSerializer(
+  options: JsonSerializerOptions = {},
+): MessageSerializer<string> {
+  const { indent = 2, sortKeys = true } = options;
+  return {
+    name: sortKeys ? 'json' : 'json (key-order preserved)',
+    serialize(value) {
+      const prepared = sortKeys ? sortKeysDeep(value) : value;
+      return JSON.stringify(prepared, undefined, indent);
+    },
+    deserialize(serialized) {
+      return JSON.parse(serialized) as unknown;
+    },
+  };
+}
+
+/** The serializer used when a contract does not specify one. */
+export const defaultSerializer: MessageSerializer<string> = jsonSerializer();

package/src/snapshot-storage.ts

@@ -0,0 +1,113 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Snapshot storage.
+ *
+ * A snapshot is just a file you commit: the serialized shape of a message,
+ * reviewed once and from then on compared on every run. There is no broker, no
+ * registry, no service to start — a format change shows up in a normal diff,
+ * reviewed like any other code. This mirrors the "approved file" convention
+ * (`<name>.approved.txt`) familiar from approval testing.
+ *
+ * By default the file lives in a `__contracts__` directory beside the test that
+ * created it, resolved from the call stack so you do not have to thread paths
+ * around. Override `dir` / `path` when you keep snapshots elsewhere.
+ */
+
+/** Set any of these (e.g. `AUTOTEL_CONTRACT_UPDATE=1`) to (re)write approved files. */
+const UPDATE_ENV_VARS = [
+  'AUTOTEL_CONTRACT_UPDATE',
+  'UPDATE_CONTRACTS',
+  'UPDATE_SNAPSHOTS',
+] as const;
+
+export function isUpdateMode(env: NodeJS.ProcessEnv = process.env): boolean {
+  return UPDATE_ENV_VARS.some((name) => {
+    const value = env[name];
+    return value === '1' || value === 'true';
+  });
+}
+
+export interface SnapshotLocation {
+  /** Directory holding the approved file. */
+  dir?: string;
+  /** Logical name; the file becomes `<name>.approved.txt`. */
+  name: string;
+  /** Fully-qualified path; when set, `dir`/`name` are ignored for placement. */
+  path?: string;
+}
+
+const DEFAULT_DIR_NAME = '__contracts__';
+const APPROVED_SUFFIX = '.approved.txt';
+
+/** Resolve the absolute file path for a snapshot. */
+export function resolveSnapshotPath(location: SnapshotLocation): string {
+  if (location.path) {
+    return path.isAbsolute(location.path)
+      ? location.path
+      : path.resolve(process.cwd(), location.path);
+  }
+  const dir = location.dir ?? defaultSnapshotDir();
+  return path.join(dir, `${sanitize(location.name)}${APPROVED_SUFFIX}`);
+}
+
+function sanitize(name: string): string {
+  // Keep it filesystem-safe while preserving readable type names.
+  return name.replaceAll(/[^\w.@-]+/g, '_');
+}
+
+export interface ReadSnapshotResult {
+  exists: boolean;
+  content?: string;
+  path: string;
+}
+
+export function readSnapshot(location: SnapshotLocation): ReadSnapshotResult {
+  const filePath = resolveSnapshotPath(location);
+  if (!existsSync(filePath)) return { exists: false, path: filePath };
+  return { exists: true, content: readFileSync(filePath, 'utf8'), path: filePath };
+}
+
+export function writeSnapshot(
+  location: SnapshotLocation,
+  content: string,
+): string {
+  const filePath = resolveSnapshotPath(location);
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content, 'utf8');
+  return filePath;
+}
+
+/**
+ * Best-effort `__contracts__` directory beside the calling test file, found by
+ * walking the stack past this module and the contract internals. Falls back to
+ * `<cwd>/__contracts__` when the caller cannot be determined (e.g. bundled).
+ */
+function defaultSnapshotDir(): string {
+  const callerFile = callerOutsidePackage();
+  const base = callerFile ? path.dirname(callerFile) : process.cwd();
+  return path.join(base, DEFAULT_DIR_NAME);
+}
+
+function callerOutsidePackage(): string | undefined {
+  const stack = new Error('stack probe').stack;
+  if (!stack) return undefined;
+  const lines = stack.split('\n').slice(1);
+  for (const line of lines) {
+    const match = line.match(/\((.*?):\d+:\d+\)/) ?? line.match(/at (.*?):\d+:\d+/);
+    const file = match?.[1];
+    if (!file) continue;
+    if (file.includes('node:')) continue;
+    // Skip frames inside this package's own source/dist.
+    if (file.includes(`${path.join('autotel-message-contract', 'src')}`)) continue;
+    if (file.includes(`${path.join('autotel-message-contract', 'dist')}`)) continue;
+    if (file.includes('node_modules')) continue;
+    return file.startsWith('file://') ? fileUrlToPath(file) : file;
+  }
+  return undefined;
+}
+
+function fileUrlToPath(url: string): string {
+  return decodeURIComponent(url.replace(/^file:\/\//, ''));
+}