autotel-message-contract 0.1.0

package/dist/serializer.js

@@ -0,0 +1,44 @@
+//#region src/serializer.ts
+/**
+* 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) {
+	if (Array.isArray(value)) return value.map((element) => sortKeysDeep(element));
+	if (value !== null && typeof value === "object" && isPlainObject(value)) {
+		const sorted = {};
+		for (const key of Object.keys(value).toSorted()) sorted[key] = sortKeysDeep(value[key]);
+		return sorted;
+	}
+	return value;
+}
+function isPlainObject(value) {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* 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…).
+*/
+function jsonSerializer(options = {}) {
+	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, void 0, indent);
+		},
+		deserialize(serialized) {
+			return JSON.parse(serialized);
+		}
+	};
+}
+/** The serializer used when a contract does not specify one. */
+const defaultSerializer = jsonSerializer();
+
+//#endregion
+export { defaultSerializer, jsonSerializer };
+//# sourceMappingURL=serializer.js.map

package/dist/serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.js","names":[],"sources":["../src/serializer.ts"],"sourcesContent":["/**\n * Message serializers.\n *\n * A contract pins the bytes a message becomes *once serialized* — the exact\n * shape a consumer, a queue, or a stored event reads. The only way that\n * snapshot is meaningful is if it is produced by the **same serializer your\n * application ships with**. Pin a shape your consumers never see and you have\n * pinned nothing.\n *\n * So a {@link MessageSerializer} is a tiny, explicit seam: `serialize` /\n * `deserialize`. The default is JSON with deterministic key ordering (so a\n * snapshot does not churn when object construction order changes), but you are\n * encouraged to pass your app's real serializer — `superjson`, `devalue`, a\n * snake_case Jackson-equivalent, a protobuf codec — so the snapshot records the\n * exact bytes you put on the wire.\n */\n\n/** A reversible mapping between an in-memory value and its serialized form. */\nexport interface MessageSerializer<Serialized = string> {\n  /** Human-facing name, surfaced in snapshot headers and failure messages. */\n  readonly name: string;\n  /** Turn a value into its serialized form (the bytes you ship). */\n  serialize(value: unknown): Serialized;\n  /** Turn a serialized form back into a value. */\n  deserialize(serialized: Serialized): unknown;\n}\n\n/**\n * Recursively sort object keys so two values with the same fields serialize\n * identically regardless of insertion order. Arrays keep their order (it is\n * semantically meaningful); plain objects are reordered; class instances,\n * Maps, Sets, Dates, etc. are left untouched so the serializer can decide.\n */\nfunction sortKeysDeep(value: unknown): unknown {\n  if (Array.isArray(value)) {\n    return value.map((element) => sortKeysDeep(element));\n  }\n  if (value !== null && typeof value === 'object' && isPlainObject(value)) {\n    const sorted: Record<string, unknown> = {};\n    for (const key of Object.keys(value).toSorted()) {\n      sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);\n    }\n    return sorted;\n  }\n  return value;\n}\n\nfunction isPlainObject(value: object): boolean {\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\nexport interface JsonSerializerOptions {\n  /**\n   * Pretty-print with this indent. Defaults to `2` so the approved file reads\n   * cleanly in a diff. Set to `0` to pin the compact bytes you actually ship.\n   */\n  indent?: number;\n  /**\n   * Sort object keys deterministically before serializing. Defaults to `true`\n   * so a snapshot reflects *fields*, not construction order. Turn it off when\n   * key order is itself part of the contract.\n   */\n  sortKeys?: boolean;\n}\n\n/**\n * The default serializer: `JSON.stringify` with deterministic key ordering.\n * Good enough to pin most events and commands; swap it for your own when the\n * bytes you ship differ (custom date formats, snake_case, omitted nulls…).\n */\nexport function jsonSerializer(\n  options: JsonSerializerOptions = {},\n): MessageSerializer<string> {\n  const { indent = 2, sortKeys = true } = options;\n  return {\n    name: sortKeys ? 'json' : 'json (key-order preserved)',\n    serialize(value) {\n      const prepared = sortKeys ? sortKeysDeep(value) : value;\n      return JSON.stringify(prepared, undefined, indent);\n    },\n    deserialize(serialized) {\n      return JSON.parse(serialized) as unknown;\n    },\n  };\n}\n\n/** The serializer used when a contract does not specify one. */\nexport const defaultSerializer: MessageSerializer<string> = jsonSerializer();\n"],"mappings":";;;;;;;AAiCA,SAAS,aAAa,OAAyB;CAC7C,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,YAAY,aAAa,OAAO,CAAC;CAErD,IAAI,UAAU,QAAQ,OAAO,UAAU,YAAY,cAAc,KAAK,GAAG;EACvE,MAAM,SAAkC,CAAC;EACzC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,GAC5C,OAAO,OAAO,aAAc,MAAkC,IAAI;EAEpE,OAAO;CACT;CACA,OAAO;AACT;AAEA,SAAS,cAAc,OAAwB;CAC7C,MAAM,QAAQ,OAAO,eAAe,KAAK;CACzC,OAAO,UAAU,OAAO,aAAa,UAAU;AACjD;;;;;;AAqBA,SAAgB,eACd,UAAiC,CAAC,GACP;CAC3B,MAAM,EAAE,SAAS,GAAG,WAAW,SAAS;CACxC,OAAO;EACL,MAAM,WAAW,SAAS;EAC1B,UAAU,OAAO;GACf,MAAM,WAAW,WAAW,aAAa,KAAK,IAAI;GAClD,OAAO,KAAK,UAAU,UAAU,QAAW,MAAM;EACnD;EACA,YAAY,YAAY;GACtB,OAAO,KAAK,MAAM,UAAU;EAC9B;CACF;AACF;;AAGA,MAAa,oBAA+C,eAAe"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "autotel-message-contract",
+  "version": "0.1.0",
+  "description": "Brokerless message contract testing for autotel — pin the serialized shape of your events/commands/messages and prove old and new versions stay compatible, as ordinary unit tests.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./serializer": {
+      "types": "./dist/serializer.d.ts",
+      "import": "./dist/serializer.js",
+      "require": "./dist/serializer.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist"
+  },
+  "keywords": [
+    "autotel",
+    "contract-testing",
+    "serialization",
+    "snapshot",
+    "approval-testing",
+    "backward-compatibility",
+    "forward-compatibility",
+    "event-sourcing",
+    "schema-evolution",
+    "messages"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
+  "license": "MIT",
+  "peerDependencies": {
+    "autotel": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "autotel": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/autotel",
+    "directory": "packages/autotel-message-contract"
+  },
+  "bugs": {
+    "url": "https://github.com/jagreehal/autotel/issues"
+  },
+  "homepage": "https://github.com/jagreehal/autotel/tree/main/packages/autotel-message-contract#readme"
+}

package/src/contract.test.ts

@@ -0,0 +1,279 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  approvedSnapshot,
+  ContractViolationError,
+  messageContract,
+} from './contract.js';
+import { jsonSerializer } from './serializer.js';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'autotel-contract-'));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('snapshot contract', () => {
+  const order = { orderId: 'ord-1', customer: 'Alice', total: 99.5 };
+
+  it('writes the approved file and passes on first run', () => {
+    expect(() =>
+      messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+        .given(order)
+        .whenSerialized()
+        .thenContractIsUnchanged(),
+    ).not.toThrow();
+  });
+
+  it('passes when the serialized shape is unchanged', () => {
+    const run = () =>
+      messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+        .given(order)
+        .whenSerialized()
+        .thenContractIsUnchanged();
+    run(); // record
+    expect(run).not.toThrow(); // compare
+  });
+
+  it('fails with a diff when a field is renamed', () => {
+    messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+      .given(order)
+      .whenSerialized()
+      .thenContractIsUnchanged();
+
+    const drifted = { orderId: 'ord-1', customerName: 'Alice', total: 99.5 };
+    expect(() =>
+      messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+        .given(drifted)
+        .whenSerialized()
+        .thenContractIsUnchanged(),
+    ).toThrowError(ContractViolationError);
+  });
+
+  it('is insensitive to object construction order by default', () => {
+    messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+      .given({ orderId: 'ord-1', customer: 'Alice', total: 99.5 })
+      .whenSerialized()
+      .thenContractIsUnchanged();
+
+    expect(() =>
+      messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+        .given({ total: 99.5, customer: 'Alice', orderId: 'ord-1' })
+        .whenSerialized()
+        .thenContractIsUnchanged(),
+    ).not.toThrow();
+  });
+
+  it('rewrites the approved file in update mode without failing', () => {
+    messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+      .given(order)
+      .whenSerialized()
+      .thenContractIsUnchanged();
+
+    const changed = { orderId: 'ord-1', customer: 'Bob', total: 1 };
+    expect(() =>
+      messageContract({ snapshot: { dir, name: 'OrderPlaced' }, update: true })
+        .given(changed)
+        .whenSerialized()
+        .thenContractIsUnchanged(),
+    ).not.toThrow();
+
+    // Subsequent non-update run now compares against the rewritten file.
+    expect(() =>
+      messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+        .given(changed)
+        .whenSerialized()
+        .thenContractIsUnchanged(),
+    ).not.toThrow();
+  });
+
+  it('pins the bytes the app actually ships when given its serializer', () => {
+    const snakeCase = jsonSerializer({ indent: 0 });
+    const step = messageContract({
+      serializer: {
+        name: 'snake',
+        serialize: (v) =>
+          snakeCase.serialize(v).replaceAll('orderId', 'order_id'),
+        deserialize: snakeCase.deserialize,
+      },
+      snapshot: { dir, name: 'OrderPlaced_snake' },
+    })
+      .given(order)
+      .whenSerialized();
+    expect(step.output).toContain('order_id');
+    expect(() => step.thenContractIsUnchanged()).not.toThrow();
+  });
+
+  it('requires a snapshot name', () => {
+    expect(() =>
+      messageContract()
+        .given(order)
+        .whenSerialized()
+        .thenContractIsUnchanged(),
+    ).toThrowError(/snapshot name is required/);
+  });
+
+  it('rejects trying to serialize an approved snapshot source', () => {
+    expect(() =>
+      messageContract({ snapshot: { dir, name: 'OrderPlaced' } })
+        .given(approvedSnapshot())
+        .whenSerialized(),
+    ).toThrowError(/Cannot serialize an approved snapshot source/);
+  });
+});
+
+describe('compatibility checks', () => {
+  // A reader is a plain parse function here; a Zod/Valibot schema works identically.
+  const orderV2Reader = (value: unknown) => {
+    const v = value as Record<string, unknown>;
+    if (typeof v.orderId !== 'string') throw new Error('orderId must be a string');
+    if (typeof v.customer !== 'string') throw new Error('customer must be a string');
+    return {
+      orderId: v.orderId,
+      customer: v.customer,
+      coupon: typeof v.coupon === 'string' ? v.coupon : undefined,
+    };
+  };
+
+  it('passes backward compatibility when a newer reader reads older bytes', async () => {
+    const v1 = { orderId: 'ord-1', customer: 'Alice' };
+    await expect(
+      messageContract()
+        .given(v1)
+        .whenDeserializedAs(orderV2Reader)
+        .thenBackwardCompatible((v2) => {
+          expect(v2.coupon).toBeUndefined();
+        }),
+    ).resolves.toMatchObject({ orderId: 'ord-1' });
+  });
+
+  it('fails backward compatibility when a required field was renamed away', async () => {
+    const broken = { orderId: 'ord-1', customerName: 'Alice' };
+    await expect(
+      messageContract()
+        .given(broken)
+        .whenDeserializedAs(orderV2Reader)
+        .thenBackwardCompatible(),
+    ).rejects.toThrowError(/Not backward-compatible/);
+  });
+
+  it('passes forward compatibility when the newer writer only adds fields', async () => {
+    const v2 = { orderId: 'ord-1', customer: 'Alice', coupon: 'SAVE10' };
+    const orderV1Reader = (value: unknown) => {
+      const v = value as Record<string, unknown>;
+      if (typeof v.orderId !== 'string') throw new Error('orderId must be a string');
+      if (typeof v.customer !== 'string') throw new Error('customer must be a string');
+      return {
+        orderId: v.orderId,
+        customer: v.customer,
+      };
+    };
+
+    await expect(
+      messageContract()
+        .given(v2)
+        .whenDeserializedAs(orderV1Reader)
+        .thenForwardCompatible(),
+    ).resolves.toMatchObject({ orderId: 'ord-1', customer: 'Alice' });
+  });
+
+  it('fails compatibility when the reader silently renames a shared field', async () => {
+    const driftedReader = (value: unknown) => {
+      const v = value as Record<string, unknown>;
+      return {
+        orderId: v.orderId,
+        customerName: v.customer,
+      };
+    };
+
+    await expect(
+      messageContract()
+        .given({ orderId: 'ord-1', customer: 'Alice' })
+        .whenDeserializedAs(driftedReader)
+        .thenBackwardCompatible(),
+    ).rejects.toThrowError(/structural incompatibility/);
+  });
+
+  it('fails compatibility when the reader changes a shared field value', async () => {
+    const lossyReader = (value: unknown) => {
+      const v = value as Record<string, unknown>;
+      return {
+        orderId: v.orderId,
+        customer: typeof v.customer === 'string' ? v.customer.toUpperCase() : v.customer,
+      };
+    };
+
+    await expect(
+      messageContract()
+        .given({ orderId: 'ord-1', customer: 'Alice' })
+        .whenDeserializedAs(lossyReader)
+        .thenBackwardCompatible(),
+    ).rejects.toThrowError(/\$\.customer: value differs/);
+  });
+
+  it('can replay an approved snapshot as the compatibility source', async () => {
+    messageContract({ snapshot: { dir, name: 'OrderPlaced_v1' } })
+      .given({ orderId: 'ord-1', customer: 'Alice' })
+      .whenSerialized()
+      .thenContractIsUnchanged();
+
+    await expect(
+      messageContract()
+        .given(approvedSnapshot({ dir, name: 'OrderPlaced_v1' }))
+        .whenDeserializedAs(orderV2Reader)
+        .thenBackwardCompatible((v2) => {
+          expect(v2.coupon).toBeUndefined();
+        }),
+    ).resolves.toMatchObject({ orderId: 'ord-1', customer: 'Alice' });
+  });
+
+  it('can use the configured snapshot location as the compatibility source', async () => {
+    messageContract({ snapshot: { dir, name: 'OrderPlaced_v1' } })
+      .given({ orderId: 'ord-1', customer: 'Alice' })
+      .whenSerialized()
+      .thenContractIsUnchanged();
+
+    await expect(
+      messageContract({ snapshot: { dir, name: 'OrderPlaced_v1' } })
+        .given(approvedSnapshot())
+        .whenDeserializedAs(orderV2Reader)
+        .thenBackwardCompatible(),
+    ).resolves.toMatchObject({ orderId: 'ord-1', customer: 'Alice' });
+  });
+
+  it('fails clearly when the approved snapshot source is missing', async () => {
+    await expect(
+      messageContract({ snapshot: { dir, name: 'missing' } })
+        .given(approvedSnapshot())
+        .whenDeserializedAs(orderV2Reader)
+        .thenBackwardCompatible(),
+    ).rejects.toThrowError(/Cannot read approved snapshot/);
+  });
+
+  it('supports a Standard Schema reader', async () => {
+    const schema = {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'test',
+        validate: (value: unknown) => {
+          const v = value as Record<string, unknown>;
+          if (typeof v.orderId === 'string') return { value: v };
+          return { issues: [{ message: 'orderId required', path: ['orderId'] }] };
+        },
+      },
+    };
+    await expect(
+      messageContract().given({ orderId: 'ord-1' }).whenDeserializedAs(schema).thenForwardCompatible(),
+    ).resolves.toBeDefined();
+
+    await expect(
+      messageContract().given({ nope: true }).whenDeserializedAs(schema).thenForwardCompatible(),
+    ).rejects.toThrowError(/orderId required/);
+  });
+});