|
1 | 1 | import * as Effect from "effect/Effect"; |
2 | 2 | import * as Option from "effect/Option"; |
3 | 3 | import * as Schema from "effect/Schema"; |
| 4 | +import * as SchemaGetter from "effect/SchemaGetter"; |
4 | 5 | import * as SchemaTransformation from "effect/SchemaTransformation"; |
5 | 6 |
|
6 | 7 | export const TrimmedString = Schema.String.pipe( |
@@ -35,14 +36,6 @@ export type DpopFailureReason = typeof DpopFailureReason.Type; |
35 | 36 | export const IsoDateTime = Schema.String; |
36 | 37 | export type IsoDateTime = typeof IsoDateTime.Type; |
37 | 38 |
|
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 | | - */ |
46 | 39 | /** |
47 | 40 | * Same idea for one optional value whose literal set grows over time: a |
48 | 41 | * 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) => { |
107 | 100 | ); |
108 | 101 | }; |
109 | 102 |
|
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( |
113 | 173 | 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 | + >({ |
116 | 246 | 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"] |
119 | 249 | >, |
120 | 250 | encode: (values) => values, |
121 | 251 | }), |
122 | 252 | ), |
123 | 253 | ); |
| 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; |
124 | 272 | }; |
125 | 273 |
|
126 | 274 | /** |
|
0 commit comments