Skip to content

Commit 5349dc9

Browse files
feat(contracts): shared forward-compatible unions, and arrays that keep transformations
ForwardCompatibleArray checked each element with its own schema but passed the raw value through, so an element with a transformation (a DateTimeUtc, a decoding default) was dropped or threw. It now decodes each element through its schema and drops only the ones that fail. ForwardCompatibleUnion adds a catch-all for a tagged union's members a newer server may add: an unknown tag decodes to UnknownUnionMember for the caller to handle, while a known member that does not decode still fails. ForwardCompatibleUnionArray drops unknown members from an array. Turn items now use these shared helpers instead of a local copy. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent ec6e47b commit 5349dc9

3 files changed

Lines changed: 305 additions & 69 deletions

File tree

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
import { describe, expect, it } from "@effect/vitest";
2+
import * as DateTime from "effect/DateTime";
3+
import * as Effect from "effect/Effect";
4+
import * as Schema from "effect/Schema";
5+
6+
import {
7+
ForwardCompatibleArray,
8+
ForwardCompatibleUnion,
9+
ForwardCompatibleUnionArray,
10+
isUnknownUnionMember,
11+
} from "./baseSchemas.ts";
12+
13+
const at = "2026-10-05T00:00:00.000Z";
14+
const Shape = Schema.Union([
15+
Schema.Struct({ kind: Schema.Literal("circle"), radius: Schema.Number, at: Schema.DateTimeUtc }),
16+
Schema.Struct({ kind: Schema.Literal("square"), side: Schema.Number }),
17+
]);
18+
const members = Shape.members;
19+
/** How clients decode: the JSON wire codec over the runtime schema. */
20+
const fromWire = <S extends Schema.Top>(schema: S) =>
21+
Schema.decodeUnknownSync(Schema.toCodecJson(schema) as never) as (value: unknown) => S["Type"];
22+
23+
describe("ForwardCompatibleArray", () => {
24+
it("decodes elements through their own codec and drops ones it cannot read", () => {
25+
const decoded = fromWire(ForwardCompatibleArray(Shape))([
26+
{ kind: "circle", radius: 1, at },
27+
{ kind: "triangle" },
28+
{ kind: "square", side: "wide" },
29+
]);
30+
expect(decoded).toHaveLength(1);
31+
expect(DateTime.isDateTime((decoded[0] as { at: unknown }).at)).toBe(true);
32+
});
33+
34+
it("applies decoding defaults instead of failing", () => {
35+
const WithDefault = Schema.Struct({
36+
name: Schema.String,
37+
count: Schema.optionalKey(Schema.Number).pipe(
38+
Schema.withDecodingDefaultKey(Effect.succeed(7)),
39+
),
40+
});
41+
expect(Schema.decodeUnknownSync(ForwardCompatibleArray(WithDefault))([{ name: "a" }])).toEqual([
42+
{ name: "a", count: 7 },
43+
]);
44+
});
45+
});
46+
47+
describe("ForwardCompatibleUnion", () => {
48+
const decode = fromWire(ForwardCompatibleUnion(members, "kind"));
49+
50+
it("decodes a member from a newer server as unknown", () => {
51+
const decoded = decode({ kind: "triangle", corners: 3 });
52+
expect(isUnknownUnionMember(decoded)).toBe(true);
53+
expect(decoded).toEqual({ _unknown: true, tag: "kind", value: "triangle" });
54+
});
55+
56+
it("decodes known members in full, transformations included", () => {
57+
const decoded = decode({ kind: "circle", radius: 1, at });
58+
expect(isUnknownUnionMember(decoded)).toBe(false);
59+
expect(DateTime.isDateTime((decoded as { at: unknown }).at)).toBe(true);
60+
});
61+
62+
it("still fails a known member whose payload is broken", () => {
63+
expect(() => decode({ kind: "square", side: "wide" })).toThrow();
64+
});
65+
66+
it("refuses to encode an unknown member", () => {
67+
const encode = Schema.encodeSync(ForwardCompatibleUnion(members, "kind") as never);
68+
expect(() => encode({ _unknown: true, tag: "kind", value: "triangle" } as never)).toThrow();
69+
});
70+
});
71+
72+
describe("ForwardCompatibleUnionArray", () => {
73+
const decode = fromWire(ForwardCompatibleUnionArray(members, "kind"));
74+
75+
it("drops members a newer server added and keeps the rest", () => {
76+
const decoded = decode([
77+
{ kind: "triangle" },
78+
{ kind: "circle", radius: 1, at },
79+
{ kind: "square", side: 2 },
80+
]);
81+
expect(decoded.map((shape) => shape.kind)).toEqual(["circle", "square"]);
82+
});
83+
84+
it("fails when a known member is broken, so real bugs stay visible", () => {
85+
expect(() => decode([{ kind: "square", side: "wide" }])).toThrow();
86+
});
87+
88+
it("encodes as a plain array", () => {
89+
const encode = Schema.encodeSync(
90+
Schema.toCodecJson(ForwardCompatibleUnionArray(members, "kind")),
91+
);
92+
const square = { kind: "square" as const, side: 2 };
93+
expect(encode([square])).toEqual([square]);
94+
});
95+
});

‎packages/contracts/src/baseSchemas.ts‎

Lines changed: 163 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import * as Effect from "effect/Effect";
22
import * as Option from "effect/Option";
33
import * as Schema from "effect/Schema";
4+
import * as SchemaGetter from "effect/SchemaGetter";
45
import * as SchemaTransformation from "effect/SchemaTransformation";
56

67
export const TrimmedString = Schema.String.pipe(
@@ -35,14 +36,6 @@ export type DpopFailureReason = typeof DpopFailureReason.Type;
3536
export const IsoDateTime = Schema.String;
3637
export type IsoDateTime = typeof IsoDateTime.Type;
3738

38-
/**
39-
* Wire codec for server→client arrays whose element unions grow over time
40-
* (new literal members, new struct variants). Decoding drops elements the
41-
* current build cannot decode instead of failing the whole payload — a client
42-
* has to keep decoding configs sent by servers newer than itself, and
43-
* rejecting the payload would take down the connection over data the client
44-
* couldn't act on anyway. Encoding is the plain array encoding.
45-
*/
4639
/**
4740
* Same idea for one optional value whose literal set grows over time: a
4841
* member this build does not know decodes as absent rather than failing the
@@ -107,20 +100,175 @@ export const OmittedWhenNull = <Value extends Schema.Top>(value: Value) => {
107100
);
108101
};
109102

110-
export const ForwardCompatibleArray = <Element extends Schema.Top>(element: Element) => {
111-
const decodeElement = Schema.decodeUnknownOption(element as never);
112-
return Schema.Array(Schema.Unknown).pipe(
103+
/**
104+
* Wire codec for a server→client value whose shape grows over time: a union
105+
* a newer server may add members to, or an array of such values. Clients keep
106+
* decoding payloads from servers newer than themselves instead of failing the
107+
* connection over data they could not act on anyway.
108+
*
109+
* Decoding runs each value through its own schema, so transformations (dates,
110+
* trimming, decoding defaults) apply as usual. Only values that schema
111+
* rejects are dropped; encoding is the plain encoding.
112+
*
113+
* For a tagged union, prefer {@link ForwardCompatibleUnion}: it drops only
114+
* values whose tag this build does not know, so a known member with a broken
115+
* payload still fails loudly.
116+
*/
117+
export const ForwardCompatibleArray = <Element extends Schema.Top>(element: Element) =>
118+
Schema.Array(
119+
Schema.UndefinedOr(element).pipe(
120+
// An element this build cannot read becomes a hole, filtered out below.
121+
Schema.catchDecoding(() => Effect.succeedSome(undefined)),
122+
),
123+
).pipe(
124+
Schema.decodeTo(
125+
Schema.Array(Schema.toType(element)),
126+
SchemaTransformation.transform<
127+
ReadonlyArray<Element["Type"]>,
128+
ReadonlyArray<Element["Type"] | undefined>
129+
>({
130+
decode: (values) => values.filter((value) => value !== undefined),
131+
encode: (values) => values,
132+
}),
133+
),
134+
) as unknown as ForwardCompatibleArray<Element>;
135+
export type ForwardCompatibleArray<Element extends Schema.Top> = Schema.Codec<
136+
ReadonlyArray<Element["Type"]>,
137+
ReadonlyArray<Element["Encoded"]>,
138+
Element["DecodingServices"],
139+
Element["EncodingServices"]
140+
>;
141+
142+
/** A member of a {@link ForwardCompatibleUnion} whose tag this build does not know. */
143+
export interface UnknownUnionMember<Tag extends string> {
144+
readonly _unknown: true;
145+
readonly tag: Tag;
146+
readonly value: string;
147+
}
148+
149+
/**
150+
* Wire codec for a server→client tagged union a newer server may add members
151+
* to. A value whose `tag` field holds a value this build does not know decodes
152+
* to {@link UnknownUnionMember} instead of failing; a known member decodes
153+
* through its own schema, so a broken known payload still fails. Callers
154+
* decide what an unknown member means: skip it, or show a fallback.
155+
*
156+
* Unknown members are decode-only; encoding one fails.
157+
*/
158+
export const ForwardCompatibleUnion = <
159+
const Members extends ReadonlyArray<Schema.Top & { readonly fields: object }>,
160+
const Tag extends string,
161+
>(
162+
members: Members,
163+
tag: Tag,
164+
) => {
165+
const known = knownTags(members, tag);
166+
const unknownMember = Schema.Struct({
167+
[tag]: Schema.String.check(
168+
Schema.makeFilter(
169+
(value: string) => !known.has(value) || `A known ${tag} must decode in full.`,
170+
),
171+
),
172+
} as Record<Tag, Schema.String>).pipe(
113173
Schema.decodeTo(
114-
Schema.Array(element),
115-
SchemaTransformation.transform<ReadonlyArray<Element["Encoded"]>, ReadonlyArray<unknown>>({
174+
Schema.Struct({
175+
_unknown: Schema.Literal(true),
176+
tag: Schema.Literal(tag),
177+
value: Schema.String,
178+
}),
179+
{
180+
decode: SchemaGetter.transform((raw: Record<string, string>) => ({
181+
_unknown: true as const,
182+
tag,
183+
value: raw[tag]!,
184+
})),
185+
encode: SchemaGetter.forbidden(() => `Unknown ${tag} values are never sent.`),
186+
},
187+
),
188+
);
189+
return Schema.Union([...members, unknownMember]) as unknown as ForwardCompatibleUnion<
190+
Members,
191+
Tag
192+
>;
193+
};
194+
export type ForwardCompatibleUnion<
195+
Members extends ReadonlyArray<Schema.Top>,
196+
Tag extends string,
197+
> = Schema.Codec<
198+
Members[number]["Type"] | UnknownUnionMember<Tag>,
199+
Members[number]["Encoded"],
200+
Members[number]["DecodingServices"],
201+
Members[number]["EncodingServices"]
202+
>;
203+
204+
/**
205+
* Whether a raw, undecoded value carries a `tag` this build does not know
206+
* among `members`. For checks outside a {@link ForwardCompatibleUnion}, such
207+
* as an envelope that must skip a payload of an unknown kind.
208+
*/
209+
export const hasUnknownUnionTag = (
210+
members: ReadonlyArray<Schema.Top & { readonly fields: object }>,
211+
tag: string,
212+
): ((value: unknown) => boolean) => {
213+
const known = knownTags(members, tag);
214+
return (value) =>
215+
typeof value === "object" &&
216+
value !== null &&
217+
tag in value &&
218+
!known.has((value as Record<string, unknown>)[tag] as string);
219+
};
220+
221+
/** Whether a decoded {@link ForwardCompatibleUnion} value is a member this build does not know. */
222+
export const isUnknownUnionMember = <A>(
223+
value: A,
224+
): value is Extract<A, UnknownUnionMember<string>> =>
225+
typeof value === "object" && value !== null && "_unknown" in value && value._unknown === true;
226+
227+
/**
228+
* An array of a growing tagged union that drops members this build does not
229+
* know. Known members decode through their own schema and still fail when
230+
* broken. Encoding is the plain array encoding.
231+
*/
232+
export const ForwardCompatibleUnionArray = <
233+
const Members extends ReadonlyArray<Schema.Top & { readonly fields: object }>,
234+
const Tag extends string,
235+
>(
236+
members: Members,
237+
tag: Tag,
238+
) =>
239+
Schema.Array(ForwardCompatibleUnion(members, tag)).pipe(
240+
Schema.decodeTo(
241+
Schema.Array(Schema.toType(Schema.Union(members))),
242+
SchemaTransformation.transform<
243+
ReadonlyArray<Members[number]["Type"]>,
244+
ReadonlyArray<Members[number]["Type"] | UnknownUnionMember<Tag>>
245+
>({
116246
decode: (values) =>
117-
values.filter((value) => Option.isSome(decodeElement(value))) as ReadonlyArray<
118-
Element["Encoded"]
247+
values.filter((value) => !isUnknownUnionMember(value)) as ReadonlyArray<
248+
Members[number]["Type"]
119249
>,
120250
encode: (values) => values,
121251
}),
122252
),
123253
);
254+
255+
const knownTags = (
256+
members: ReadonlyArray<Schema.Top & { readonly fields: object }>,
257+
tag: string,
258+
): ReadonlySet<string> => {
259+
const tags = new Set<string>();
260+
for (const member of members) {
261+
const field = (member.fields as Record<string, unknown>)[tag] as
262+
| { readonly literal?: unknown; readonly literals?: ReadonlyArray<unknown> }
263+
| undefined;
264+
for (const literal of field?.literals ?? [field?.literal]) {
265+
if (typeof literal !== "string") {
266+
throw new Error(`Every ForwardCompatibleUnion member needs a string literal ${tag}.`);
267+
}
268+
tags.add(literal);
269+
}
270+
}
271+
return tags;
124272
};
125273

126274
/**

0 commit comments

Comments
 (0)