clean-architecture-frontend-template/tests/unit/realtime/event-codec.test.ts

import { describe, expect, it } from "vitest";

import {
  compareRealtimeSequences,
  isCanonicalRealtimeSequence,
  isRealtimeResumeCursor,
  isStrictRealtimeTimestamp,
  nextRealtimeSequence,
  REALTIME_MAX_SEQUENCE,
} from "../../../src/contracts/realtime-events.ts";
import {
  isValidatedRealtimeEventDto,
} from "../../../src/adapters/realtime/event-codec.ts";
import {
  TEST_LIMITS,
  createTestRealtimeCodec,
  createTestRealtimeRegistry,
  realtimeEventJson,
  realtimeEventValue,
} from "./fixture.ts";

describe("REALTIME_EVENT_V1 codec", () => {
  it("accepts an exact registered envelope and snapshots schema output", () => {
    const codec = createTestRealtimeCodec();
    const result = codec.decode(realtimeEventJson());

    expect(result).toMatchObject({
      ok: true,
      value: {
        envelope: {
          protocol: "REALTIME_EVENT_V1",
          sequence: "1",
          recoveryMode: "CURSOR",
          resumeCursor: "cursor-00000001",
          payload: { value: "changed" },
        },
      },
    });
    if (!result.ok) return;
    expect(isValidatedRealtimeEventDto(result.value)).toBe(true);
    expect(Object.isFrozen(result.value)).toBe(true);
    expect(Object.isFrozen(result.value.envelope)).toBe(true);
    expect(Object.isFrozen(result.value.envelope.payload)).toBe(true);
    expect(result.value.wireBytes).toBeGreaterThan(0);
    expect(result.value.fingerprintBytes).toBeGreaterThan(0);
  });

  it("rejects extra keys, unknown registrations and schema failures", () => {
    const codec = createTestRealtimeCodec();

    expect(
      codec.decode(
        JSON.stringify({
          ...realtimeEventValue(),
          arbitrary: "override",
        }),
      ),
    ).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT", operation: "DECODE" },
    });
    expect(
      codec.decode(
        realtimeEventJson({ streamId: "UNKNOWN_STREAM" }),
      ),
    ).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT" },
    });
    expect(
      codec.decode(
        realtimeEventJson({ eventType: "UNKNOWN_EVENT" }),
      ),
    ).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT" },
    });
    expect(
      codec.decode(realtimeEventJson({ payload: { value: 42 } })),
    ).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT" },
    });

    const duplicateEnvelopeMember =
      `{"eventId":"shadowed",${JSON.stringify(
        realtimeEventValue(),
      ).slice(1)}`;
    expect(codec.decode(duplicateEnvelopeMember)).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT", operation: "DECODE" },
    });
    const duplicatePayloadMember = realtimeEventJson().replace(
      '"payload":{"value":"changed"}',
      '"payload":{"value":"first","\\u0076alue":"changed"}',
    );
    expect(codec.decode(duplicatePayloadMember)).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT", operation: "DECODE" },
    });
  });

  it("fails closed on version, sequence, timestamp, scope and cursor syntax", () => {
    const codec = createTestRealtimeCodec();

    expect(
      codec.decode(realtimeEventJson({ protocol: "REALTIME_EVENT_V2" })),
    ).toMatchObject({
      ok: false,
      error: { kind: "PROTOCOL_MISMATCH" },
    });
    for (const overrides of [
      { sequence: "01" },
      { sequence: "18446744073709551616" },
      { occurredAt: "2026-02-30T01:02:03Z" },
      { occurredAt: "2026-07-28 01:02:03Z" },
      { scopeBinding: "scope\r\ninjected" },
      { resumeCursor: "" },
      { resumeCursor: "cursor\ninjected" },
      { recoveryMode: "SNAPSHOT_ONLY", resumeCursor: null },
    ]) {
      expect(codec.decode(realtimeEventJson(overrides))).toMatchObject({
        ok: false,
        error: { kind: "MALFORMED_EVENT" },
      });
    }
  });

  it("enforces global, per-stream and payload structure ceilings", () => {
    const strictCodec = createTestRealtimeCodec(
      createTestRealtimeRegistry({
        limits: {
          ...TEST_LIMITS,
          maxEventBytes: 512,
          maxPayloadNodes: 1,
        },
      }),
    );
    expect(
      strictCodec.decode(realtimeEventJson()),
    ).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT" },
    });

    const byteBoundCodec = createTestRealtimeCodec(
      createTestRealtimeRegistry({
        limits: {
          ...TEST_LIMITS,
          maxEventBytes: 512,
        },
      }),
    );
    expect(
      byteBoundCodec.decode(
        realtimeEventJson({ payload: { value: "x".repeat(600) } }),
      ),
    ).toMatchObject({
      ok: false,
      error: { kind: "EVENT_TOO_LARGE" },
    });

    expect(
      createTestRealtimeCodec().decode(
        "x".repeat(64 * 1024 + 1),
      ),
    ).toMatchObject({
      ok: false,
      error: { kind: "EVENT_TOO_LARGE" },
    });
  });

  it("supports the exact null-cursor SESSION_REBUILD discriminant", () => {
    const registry = createTestRealtimeRegistry({
      recovery: {
        mode: "SESSION_REBUILD",
        rebuildInputId: "referenceRealtimeRebuild",
      },
      delivery: "EPHEMERAL",
      stateBearing: false,
    });
    const codec = createTestRealtimeCodec(registry);

    expect(
      codec.decode(
        realtimeEventJson({
          recoveryMode: "SESSION_REBUILD",
          resumeCursor: null,
        }),
      ),
    ).toMatchObject({
      ok: true,
      value: {
        envelope: {
          recoveryMode: "SESSION_REBUILD",
          resumeCursor: null,
        },
      },
    });
    expect(
      codec.decode(
        realtimeEventJson({
          recoveryMode: "SESSION_REBUILD",
          resumeCursor: "synthetic",
        }),
      ),
    ).toMatchObject({
      ok: false,
      error: { kind: "MALFORMED_EVENT" },
    });
  });

  it("normalizes semantic identity independently of JSON key order", () => {
    const codec = createTestRealtimeCodec();
    const value = realtimeEventValue();
    const reversed = Object.fromEntries(
      Object.entries(value).reverse(),
    );
    const first = codec.decode(JSON.stringify(value));
    const second = codec.decode(JSON.stringify(reversed));

    expect(first.ok).toBe(true);
    expect(second.ok).toBe(true);
    if (!first.ok || !second.ok) return;
    expect(first.value.semanticFingerprint).toBe(
      second.value.semanticFingerprint,
    );
  });

  it("uses bounded uint64 sequence and header-safe cursor helpers", () => {
    expect(isCanonicalRealtimeSequence("0")).toBe(true);
    expect(isCanonicalRealtimeSequence(REALTIME_MAX_SEQUENCE)).toBe(true);
    expect(isCanonicalRealtimeSequence("00")).toBe(false);
    expect(isCanonicalRealtimeSequence("18446744073709551616")).toBe(false);
    expect(compareRealtimeSequences("9", "10")).toBe(-1);
    expect(nextRealtimeSequence("9")).toBe("10");
    expect(nextRealtimeSequence(REALTIME_MAX_SEQUENCE)).toBeNull();
    expect(isRealtimeResumeCursor("cursor:/+=._~-")).toBe(true);
    expect(isRealtimeResumeCursor("cursor\nunsafe")).toBe(false);
    expect(isStrictRealtimeTimestamp("2024-02-29T23:59:59Z")).toBe(true);
    expect(isStrictRealtimeTimestamp("2023-02-29T23:59:59Z")).toBe(false);
  });
});