effect-app 4.0.0-beta.33 → 4.0.0-beta.331

package/test/schema.test.ts

@@ -1,6 +1,10 @@
 // import { generateFromArbitrary } from "@effect-app/infra/test"
-import { Array, S } from "effect-app"
-import { expect, expectTypeOf, test } from "vitest"
+import * as Array from "effect-app/Array"
+import * as S from "effect-app/Schema"
+import { specialJsonSchemaDocument } from "effect-app/Schema/SpecialJsonSchema"
+import * as Effect from "effect/Effect"
+import * as Struct from "effect/Struct"
+import { describe, expect, expectTypeOf, test } from "vitest"
 
 const A = S.Struct({ a: S.NonEmptyString255, email: S.NullOr(S.Email) })
 test("works", () => {
@@ -14,22 +18,170 @@ test("works", () => {
 })
 
 test("literal default works", () => {
-  const l = S.Literal("a", "b")
+  const l = S.Literals(["a", "b"])
   expect(l.Default).toBe("a")
-  const s = S.Struct({ l: l.withDefault })
-  expect(s.makeUnsafe({}).l).toBe("a")
+  expectTypeOf(l.Default).toEqualTypeOf<"a">()
+  const s = S.Struct({ l: l.withConstructorDefault })
+  expect(s.make({}).l).toBe("a")
 
   const l2 = l.changeDefault("b")
-  const s2 = S.Struct({ l: l2.withDefault })
-  expect(s2.makeUnsafe({}).l).toBe("b")
+  const s2 = S.Struct({ l: l2.withConstructorDefault })
+  expect(s2.make({}).l).toBe("b")
+})
+
+// Toy schema for `dropConstructorDefault`: a field with a constructor
+// default that should NOT auto-populate when deriving a partial-update
+// schema from a "create" schema.
+const Person = S.Struct({
+  name: S.String,
+  notes: S.NullOr(S.String).pipe(S.optionalKey, S.withConstructorDefault(Effect.succeed(null)))
+})
+
+test("plain Struct.omit leaks the inherited constructor default (the bug)", () => {
+  const UpdatePersonBuggy = S.Struct(Struct.omit(Person.fields, [] as const))
+  expect(UpdatePersonBuggy.make({ name: "Mario" })).toEqual({ name: "Mario", notes: null })
+})
+
+test("Struct.map(S.dropConstructorDefault) strips the inherited constructor default (the fix)", () => {
+  const UpdatePersonFixed = S.Struct(Struct.map(Struct.omit(Person.fields, [] as const), S.dropConstructorDefault))
+  expect(UpdatePersonFixed.make({ name: "Mario" })).toEqual({ name: "Mario" })
+})
+
+test("Struct.map(S.dropConstructorDefault) still omits the requested keys, like Struct.omit", () => {
+  const NameOnly = S.Struct(Struct.map(Struct.omit(Person.fields, ["notes"] as const), S.dropConstructorDefault))
+  expect(NameOnly.make({ name: "Mario" })).toEqual({ name: "Mario" })
+  expectTypeOf<typeof NameOnly.Type>().toEqualTypeOf<{ readonly name: string }>()
+})
+
+test("makeExactOptional drops the inherited constructor default too", () => {
+  const UpdatePerson = S.Struct(S.makeExactOptional(Person.fields))
+  expect(UpdatePerson.make({ name: "Mario" })).toEqual({ name: "Mario" })
+})
+
+test("dropConstructorDefault stays 'no-default' after annotate/annotateKey (Rebuild fix)", () => {
+  const notesDropped = S.dropConstructorDefault(Person.fields.notes)
+  expectTypeOf<(typeof notesDropped)["~type.constructor.default"]>().toEqualTypeOf<"no-default">()
+
+  const notesAnnotated = notesDropped.annotate({ description: "no longer defaulted" })
+  expectTypeOf<(typeof notesAnnotated)["~type.constructor.default"]>().toEqualTypeOf<"no-default">()
+
+  const notesKeyAnnotated = notesDropped.annotateKey({ description: "no longer defaulted (key)" })
+  expectTypeOf<(typeof notesKeyAnnotated)["~type.constructor.default"]>().toEqualTypeOf<"no-default">()
+
+  const UpdatePerson = S.Struct({ name: Person.fields.name, notes: notesAnnotated })
+  expect(UpdatePerson.make({ name: "Mario" })).toEqual({ name: "Mario" })
+})
+
+test("NonEmptyString255.Type uses the named brand alias", () => {
+  type A = typeof S.NonEmptyString255.Type
+  type B = string & S.NonEmptyString255Brand
+  expectTypeOf<A>().toEqualTypeOf<B>()
+})
+
+test("Opaque accepts an explicit Encoded type", () => {
+  interface User {
+    readonly id: string
+    readonly _tag: "User"
+  }
+
+  interface UserEncoded {
+    readonly id: string
+  }
+
+  const baseSchema = S.Struct({ id: S.String, name: S.String })
+  const _UserSchema = S.Opaque<User, UserEncoded>()(baseSchema)
+
+  expectTypeOf<S.Codec.Encoded<typeof _UserSchema>>().toEqualTypeOf<UserEncoded>()
+  expectTypeOf<S.Schema.Type<typeof _UserSchema>>().toEqualTypeOf<User>()
+  expectTypeOf<S.Codec.Encoded<typeof _UserSchema>>().not.toEqualTypeOf<S.Codec.Encoded<typeof baseSchema>>()
+})
+
+test("Opaque with one generic keeps the base encoded shape", () => {
+  interface User {
+    readonly id: string
+  }
+
+  const baseSchema = S.Struct({ id: S.String })
+  const _UserSchema = S.Opaque<User>()(baseSchema)
+
+  expectTypeOf<S.Codec.Encoded<typeof _UserSchema>>().toEqualTypeOf<{ readonly id: string }>()
+  expectTypeOf<S.Schema.Type<typeof _UserSchema>>().toEqualTypeOf<User>()
+})
+
+test("Opaque preserves optional Struct.make input", () => {
+  interface User {
+    readonly a?: string | undefined
+    readonly b?: number | undefined
+  }
+
+  const schema = S.Opaque<User>()(S.Struct({
+    a: S.optional(S.String),
+    b: S.optional(S.Number)
+  }))
+
+  const made = schema.make()
+  expect(made).toEqual({})
+  expectTypeOf(made).toEqualTypeOf<User>()
+})
+
+test("Opaque preserves optional TaggedStruct.make input", () => {
+  interface OnlyTag {
+    readonly _tag: "OnlyTag"
+  }
+
+  const schema = S.Opaque<OnlyTag>()(S.TaggedStruct("OnlyTag", {}))
+
+  const made = schema.make()
+  expect(made).toEqual({ _tag: "OnlyTag" })
+  expectTypeOf(made).toEqualTypeOf<OnlyTag>()
+})
+
+test("S.Literals([\"A\", \"B\"]).Default is typed as \"A\"", () => {
+  const l = S.Literals(["A", "B"])
+  expect(l.Default).toBe("A")
+  expectTypeOf(l.Default).toEqualTypeOf<"A">()
+})
+
+test("Struct.make accepts void when all fields are optional", () => {
+  const schema = S.Struct({
+    a: S.optional(S.String),
+    b: S.optional(S.Number)
+  })
+
+  const made = schema.make()
+  expect(made).toEqual({})
+  expectTypeOf(made).toEqualTypeOf<{ readonly a?: string | undefined; readonly b?: number | undefined }>()
+})
+
+test("StructNestedEncoded resolves Struct and from.Encoded", () => {
+  const plain = S.Struct({ a: S.String, b: S.NullOr(S.String) })
+  const encodedKeys = plain.pipe(S.encodeKeys({ b: "b_encoded" }))
+
+  expectTypeOf<S.StructNestedEncoded<typeof plain>>().toEqualTypeOf<{
+    readonly a: string
+    readonly b: string | null
+  }>()
+
+  expectTypeOf<S.StructNestedEncoded<typeof encodedKeys>>().toEqualTypeOf<{
+    readonly a: string
+    readonly b_encoded: string | null
+  }>()
+})
+
+test("TaggedStruct.make accepts void when only constructor-default fields exist", () => {
+  const schema = S.TaggedStruct("OnlyTag", {})
+
+  const made = schema.make()
+  expect(made).toEqual({ _tag: "OnlyTag" })
+  expectTypeOf(made).toEqualTypeOf<{ readonly _tag: "OnlyTag" }>()
 })
 
 test("tagged union derives tag map and tags from v4 literal ast", () => {
-  const schema = S.TaggedUnion(
+  const schema = S.TaggedUnion([
     S.TaggedStruct("A", { a: S.String }),
     S.TaggedStruct("B", { b: S.Finite }),
     S.TaggedStruct("C", { c: S.Boolean })
-  )
+  ])
   const caseA = schema.cases["A"]
   const caseB = schema.cases["B"]
   const caseC = schema.cases["C"]
@@ -56,21 +208,21 @@ test("tagged union derives tag map and tags from v4 literal ast", () => {
 })
 
 test("TaggedUnion tags returns a Literals schema with correct literal values", () => {
-  const schema = S.TaggedUnion(
+  const schema = S.TaggedUnion([
     S.TaggedStruct("X", { x: S.String }),
     S.TaggedStruct("Y", { y: S.Finite })
-  )
+  ])
 
   expect(schema.tags.literals).toEqual(["X", "Y"])
   expectTypeOf(schema.tags.literals).toMatchTypeOf<readonly ["X", "Y"]>()
 })
 
 test("TaggedUnion tags.pick returns a subset of the tag literals", () => {
-  const schema = S.TaggedUnion(
+  const schema = S.TaggedUnion([
     S.TaggedStruct("A", { a: S.String }),
     S.TaggedStruct("B", { b: S.Finite }),
     S.TaggedStruct("C", { c: S.Boolean })
-  )
+  ])
 
   const subset = schema.tags.pick(["A", "C"])
   expect(subset.literals).toEqual(["A", "C"])
@@ -109,24 +261,23 @@ test("ExtendTaggedUnion adds tags to an existing Union", () => {
 })
 
 test("TaggedUnion match dispatches on _tag", () => {
-  const schema = S.TaggedUnion(
+  const schema = S.TaggedUnion([
     S.TaggedStruct("A", { a: S.String }),
     S.TaggedStruct("B", { b: S.Finite })
-  )
-  type T = S.Schema.Type<typeof schema>
+  ])
 
   const matcher = schema.match({
     A: (v) => `got A: ${v.a}`,
     B: (v) => `got B: ${v.b}`
   })
-  expect(matcher({ _tag: "A", a: "hello" } as T)).toBe("got A: hello")
-  expect(matcher({ _tag: "B", b: 42 } as T)).toBe("got B: 42")
+  expect(matcher({ _tag: "A", a: "hello" })).toBe("got A: hello")
+  expect(matcher({ _tag: "B", b: 42 })).toBe("got B: 42")
 })
 
 test("TaggedUnion with single member", () => {
-  const schema = S.TaggedUnion(
+  const schema = S.TaggedUnion([
     S.TaggedStruct("Only", { val: S.String })
-  )
+  ])
 
   expect(schema.tags.literals).toEqual(["Only"])
   expect(S.decodeSync(schema.tags)("Only")).toBe("Only")
@@ -135,11 +286,11 @@ test("TaggedUnion with single member", () => {
 })
 
 test("TaggedUnion tags type is narrowed to the exact tag literals", () => {
-  const schema = S.TaggedUnion(
+  const schema = S.TaggedUnion([
     S.TaggedStruct("Alpha", { a: S.String }),
     S.TaggedStruct("Beta", { b: S.Finite }),
     S.TaggedStruct("Gamma", { c: S.Boolean })
-  )
+  ])
 
   type Tags = S.Schema.Type<typeof schema.tags>
   expectTypeOf<Tags>().toEqualTypeOf<"Alpha" | "Beta" | "Gamma">()
@@ -153,7 +304,7 @@ test("TaggedUnion with encodeKeys renaming a non-tag key", () => {
     S.encodeKeys({ lastName: "last_name" })
   )
 
-  const schema = S.TaggedUnion(MemberA, MemberB)
+  const schema = S.TaggedUnion([MemberA, MemberB])
 
   expect(schema.tags.literals).toEqual(["A", "B"])
   expect(S.decodeSync(schema.tags)("A")).toBe("A")
@@ -167,8 +318,7 @@ test("TaggedUnion with encodeKeys renaming a non-tag key", () => {
   expect(decoded2).toEqual({ _tag: "B", lastName: 42 })
 
   // encode back to snake_case
-  type T = S.Schema.Type<typeof schema>
-  const encoded = S.encodeSync(schema)({ _tag: "A", firstName: "Alice" } as T)
+  const encoded = S.encodeSync(schema)({ _tag: "A", firstName: "Alice" })
   expect(encoded).toEqual({ _tag: "A", first_name: "Alice" })
 
   // guards work on decoded values
@@ -181,7 +331,7 @@ test("TaggedUnion with TaggedClass members", () => {
   class Foo extends S.TaggedClass<Foo>()("Foo", { name: S.String }) {}
   class Bar extends S.TaggedClass<Bar>()("Bar", { count: S.Finite }) {}
 
-  const schema = S.TaggedUnion(Foo, Bar)
+  const schema = S.TaggedUnion([Foo, Bar])
 
   expect(schema.tags.literals).toEqual(["Foo", "Bar"])
   expect(S.decodeSync(schema.tags)("Foo")).toBe("Foo")
@@ -200,3 +350,332 @@ test("TaggedUnion with TaggedClass members", () => {
   expect(schema.guards.Foo(new Bar({ count: 3 }))).toBe(false)
   expect(schema.guards.Bar(new Bar({ count: 3 }))).toBe(true)
 })
+
+describe("ReadonlySetFromArray", () => {
+  test("decodes an array of strings to a Set", () => {
+    const schema = S.ReadonlySetFromArray(S.String)
+    const decoded = S.decodeUnknownSync(schema)(["a", "b", "c"])
+    expect(decoded).toEqual(new Set(["a", "b", "c"]))
+  })
+
+  test("encodes a Set back to an array", () => {
+    const schema = S.ReadonlySetFromArray(S.String)
+    const encoded = S.encodeSync(schema)(new Set(["a", "b"]))
+    expect(encoded).toEqual(["a", "b"])
+  })
+
+  test("decodes with NumberFromString as value", () => {
+    const schema = S.ReadonlySetFromArray(S.NumberFromString)
+    const decoded = S.decodeUnknownSync(schema)(["1", "2", "3"])
+    expect(decoded).toEqual(new Set([1, 2, 3]))
+    expectTypeOf(decoded).toEqualTypeOf<ReadonlySet<number>>()
+  })
+
+  test("encodes with NumberFromString as value", () => {
+    const schema = S.ReadonlySetFromArray(S.NumberFromString)
+    const encoded = S.encodeSync(schema)(new Set([1, 2, 3]))
+    expect(encoded).toEqual(["1", "2", "3"])
+  })
+
+  test("rejects invalid input", () => {
+    const schema = S.ReadonlySetFromArray(S.NumberFromString)
+    expect(() => S.decodeUnknownSync(schema)([1, 2])).toThrow()
+  })
+})
+
+describe("ReadonlyMapFromArray", () => {
+  test("decodes an array of tuples to a Map", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.String, value: S.Finite })
+    const decoded = S.decodeUnknownSync(schema)([["a", 1], ["b", 2]])
+    expect(decoded).toEqual(new Map([["a", 1], ["b", 2]]))
+  })
+
+  test("encodes a Map back to an array of tuples", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.String, value: S.Finite })
+    const encoded = S.encodeSync(schema)(new Map([["a", 1], ["b", 2]]))
+    expect(encoded).toEqual([["a", 1], ["b", 2]])
+  })
+
+  test("decodes with NumberFromString as key", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.NumberFromString, value: S.String })
+    const decoded = S.decodeUnknownSync(schema)([["1", "one"], ["2", "two"]])
+    expect(decoded).toEqual(new Map([[1, "one"], [2, "two"]]))
+    expectTypeOf(decoded).toEqualTypeOf<ReadonlyMap<number, string>>()
+  })
+
+  test("encodes with NumberFromString as key", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.NumberFromString, value: S.String })
+    const encoded = S.encodeSync(schema)(new Map([[1, "one"], [2, "two"]]))
+    expect(encoded).toEqual([["1", "one"], ["2", "two"]])
+  })
+
+  test("decodes with NumberFromString as value", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.String, value: S.NumberFromString })
+    const decoded = S.decodeUnknownSync(schema)([["a", "10"], ["b", "20"]])
+    expect(decoded).toEqual(new Map([["a", 10], ["b", 20]]))
+    expectTypeOf(decoded).toEqualTypeOf<ReadonlyMap<string, number>>()
+  })
+
+  test("encodes with NumberFromString as value", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.String, value: S.NumberFromString })
+    const encoded = S.encodeSync(schema)(new Map([["a", 10], ["b", 20]]))
+    expect(encoded).toEqual([["a", "10"], ["b", "20"]])
+  })
+
+  test("decodes with NumberFromString as both key and value", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.NumberFromString, value: S.NumberFromString })
+    const decoded = S.decodeUnknownSync(schema)([["1", "10"], ["2", "20"]])
+    expect(decoded).toEqual(new Map([[1, 10], [2, 20]]))
+    expectTypeOf(decoded).toEqualTypeOf<ReadonlyMap<number, number>>()
+  })
+
+  test("rejects invalid input", () => {
+    const schema = S.ReadonlyMapFromArray({ key: S.NumberFromString, value: S.String })
+    expect(() => S.decodeUnknownSync(schema)([[1, "val"]])).toThrow()
+  })
+})
+
+describe("ReadonlySet (with withConstructorDefault)", () => {
+  test("make provides withConstructorDefault", () => {
+    const schema = S.ReadonlySet(S.NumberFromString)
+    const struct = S.Struct({ items: schema.withConstructorDefault })
+    const made = struct.make({})
+    expect(made.items).toEqual(new Set())
+  })
+
+  test("decodes a Set with NumberFromString values", () => {
+    const schema = S.ReadonlySet(S.NumberFromString)
+    const decoded = S.decodeUnknownSync(schema)(new Set(["1", "2"]))
+    expect(decoded).toEqual(new Set([1, 2]))
+  })
+
+  test("Encoded is a Set, not an array", () => {
+    const schema = S.ReadonlySet(S.String)
+    const encoded = S.encodeSync(schema)(new Set(["a"]))
+    expect(encoded).toEqual(new Set(["a"]))
+    expectTypeOf(encoded).toEqualTypeOf<ReadonlySet<string>>()
+  })
+})
+
+describe("ReadonlyMap (with withConstructorDefault)", () => {
+  test("make provides withConstructorDefault", () => {
+    const schema = S.ReadonlyMap({ key: S.NumberFromString, value: S.String })
+    const struct = S.Struct({ items: schema.withConstructorDefault })
+    const made = struct.make({})
+    expect(made.items).toEqual(new Map())
+  })
+
+  test("decodes a Map with NumberFromString keys", () => {
+    const schema = S.ReadonlyMap({ key: S.NumberFromString, value: S.String })
+    const decoded = S.decodeUnknownSync(schema)(new Map([["1", "one"]]))
+    expect(decoded).toEqual(new Map([[1, "one"]]))
+  })
+
+  test("Encoded is a Map, not an array of tuples", () => {
+    const schema = S.ReadonlyMap({ key: S.String, value: S.Finite })
+    const encoded = S.encodeSync(schema)(new Map([["a", 1]]))
+    expect(encoded).toEqual(new Map([["a", 1]]))
+    expectTypeOf(encoded).toEqualTypeOf<ReadonlyMap<string, number>>()
+  })
+})
+
+describe("JSON Schema", () => {
+  test("Email has format, minLength, maxLength", () => {
+    const doc = S.toJsonSchemaDocument(S.Email)
+    expect(doc).toStrictEqual({
+      dialect: "draft-2020-12",
+      schema: { "$ref": "#/$defs/Email" },
+      definitions: {
+        Email: {
+          type: "string",
+          title: "Email",
+          description: "an email according to RFC 5322",
+          format: "email",
+          minLength: 3,
+          maxLength: 998
+        }
+      }
+    })
+  })
+
+  test("Email specialJsonSchemaDocument flattens allOf", () => {
+    const doc = specialJsonSchemaDocument(S.Email)
+    expect(doc).toStrictEqual({
+      dialect: "draft-2020-12",
+      schema: { "$ref": "#/$defs/Email" },
+      definitions: {
+        Email: {
+          type: "string",
+          title: "Email",
+          description: "an email according to RFC 5322",
+          format: "email",
+          minLength: 3,
+          maxLength: 998
+        }
+      }
+    })
+  })
+
+  test("Date Encoded is Date; JSON codec encodes ISO strings", () => {
+    const d = new Date("2024-01-01T00:00:00.000Z")
+    expect(S.decodeUnknownSync(S.Date)(d)).toBe(d)
+    expect(S.encodeSync(S.Date)(d)).toBe(d)
+    expect(S.encodeSync(S.toCodecJson(S.Date))(d)).toBe("2024-01-01T00:00:00.000Z")
+    const doc = S.toJsonSchemaDocument(S.Date)
+    expect(doc.dialect).toBe("draft-2020-12")
+    expect(doc.schema).toEqual({ type: "string" })
+  })
+
+  test("DateFromString keeps string Encoded", () => {
+    const doc = S.toJsonSchemaDocument(S.DateFromString)
+    expect(doc).toStrictEqual({
+      dialect: "draft-2020-12",
+      schema: { "$ref": "#/$defs/DateOrInvalid" },
+      definitions: {
+        DateOrInvalid: {
+          type: "string",
+          description: "an ISO 8601 date string that will be decoded as a Date (may be invalid)",
+          format: "date-time"
+        }
+      }
+    })
+  })
+
+  test("PhoneNumber has format phone", () => {
+    const doc = specialJsonSchemaDocument(S.PhoneNumber)
+    expect(doc).toStrictEqual({
+      dialect: "draft-2020-12",
+      schema: { "$ref": "#/$defs/PhoneNumber" },
+      definitions: {
+        PhoneNumber: {
+          type: "string",
+          title: "PhoneNumber",
+          description: "a phone number with at least 7 digits",
+          format: "phone"
+        }
+      }
+    })
+  })
+
+  test("Url has format uri", () => {
+    const doc = specialJsonSchemaDocument(S.Url)
+    expect(doc).toStrictEqual({
+      dialect: "draft-2020-12",
+      schema: { "$ref": "#/$defs/Url" },
+      definitions: {
+        Url: {
+          type: "string",
+          title: "Url",
+          format: "uri"
+        }
+      }
+    })
+  })
+})
+
+describe("generateGuards", () => {
+  const StateSchema = S.TaggedUnion([
+    S.TaggedStruct("Active", { since: S.String }),
+    S.TaggedStruct("Inactive", { reason: S.String }),
+    S.TaggedStruct("Pending", { eta: S.Finite })
+  ])
+
+  type State = S.Schema.Type<typeof StateSchema>
+  type Entity = { readonly state: State; readonly name: string }
+
+  const { isActive, isAnyOf, isInactive, isPending } = StateSchema.generateGuards("state")
+
+  test("isActive narrows to Active member", () => {
+    const entity: Entity = { state: { _tag: "Active", since: "2024-01-01" }, name: "foo" }
+    expect(isActive(entity)).toBe(true)
+    if (isActive(entity)) {
+      expectTypeOf(entity.state).toEqualTypeOf<{ readonly _tag: "Active"; readonly since: string }>()
+    }
+  })
+
+  test("isActive returns false for non-Active", () => {
+    const entity: Entity = { state: { _tag: "Inactive", reason: "expired" }, name: "foo" }
+    expect(isActive(entity)).toBe(false)
+  })
+
+  test("isInactive narrows to Inactive member", () => {
+    const entity: Entity = { state: { _tag: "Inactive", reason: "expired" }, name: "foo" }
+    expect(isInactive(entity)).toBe(true)
+  })
+
+  test("isPending narrows to Pending member", () => {
+    const entity: Entity = { state: { _tag: "Pending", eta: 42 }, name: "foo" }
+    expect(isPending(entity)).toBe(true)
+  })
+
+  test("isAnyOf narrows to union of specified members", () => {
+    const isActiveOrPending = isAnyOf(["Active", "Pending"])
+    const active: Entity = { state: { _tag: "Active", since: "2024-01-01" }, name: "foo" }
+    const pending: Entity = { state: { _tag: "Pending", eta: 5 }, name: "bar" }
+    const inactive: Entity = { state: { _tag: "Inactive", reason: "expired" }, name: "baz" }
+
+    expect(isActiveOrPending(active)).toBe(true)
+    expect(isActiveOrPending(pending)).toBe(true)
+    expect(isActiveOrPending(inactive)).toBe(false)
+
+    if (isActiveOrPending(active)) {
+      expectTypeOf(active.state).toEqualTypeOf<
+        { readonly _tag: "Active"; readonly since: string } | { readonly _tag: "Pending"; readonly eta: number }
+      >()
+    }
+  })
+
+  test("guards use schema-based validation (built-in guards)", () => {
+    expect(StateSchema.guards.Active({ _tag: "Active" })).toBe(false)
+    expect(StateSchema.guards.Active({ _tag: "Active", since: "2024-01-01" })).toBe(true)
+  })
+})
+
+describe("generateGuardsFor", () => {
+  const StateSchema = S.TaggedUnion([
+    S.TaggedStruct("Active", { since: S.String }),
+    S.TaggedStruct("Inactive", { reason: S.String }),
+    S.TaggedStruct("Pending", { eta: S.Finite })
+  ])
+
+  type State = S.Schema.Type<typeof StateSchema>
+  type Entity = { readonly state: State; readonly name: string }
+
+  const { isActive, isAnyOf } = StateSchema.generateGuardsFor<Entity>()("state")
+
+  test("isActive narrows to Active member", () => {
+    const entity: Entity = { state: { _tag: "Active", since: "2024-01-01" }, name: "foo" }
+    expect(isActive(entity)).toBe(true)
+    if (isActive(entity)) {
+      expectTypeOf(entity.state).toEqualTypeOf<{ readonly _tag: "Active"; readonly since: string }>()
+    }
+  })
+
+  test("isActive returns false for non-Active", () => {
+    const entity: Entity = { state: { _tag: "Inactive", reason: "expired" }, name: "foo" }
+    expect(isActive(entity)).toBe(false)
+  })
+
+  test("isAnyOf narrows to union of specified members", () => {
+    const isActiveOrPending = isAnyOf(["Active", "Pending"])
+    const active: Entity = { state: { _tag: "Active", since: "2024-01-01" }, name: "foo" }
+    const inactive: Entity = { state: { _tag: "Inactive", reason: "expired" }, name: "baz" }
+
+    expect(isActiveOrPending(active)).toBe(true)
+    expect(isActiveOrPending(inactive)).toBe(false)
+  })
+
+  test("ExtendTaggedUnion also exposes generateGuardsFor", () => {
+    const union = S.Union([
+      S.TaggedStruct("X", { x: S.String }),
+      S.TaggedStruct("Y", { y: S.Finite })
+    ])
+    const extended = S.ExtendTaggedUnion(union)
+    type Obj = { readonly field: S.Schema.Type<typeof extended> }
+    const { isX, isY } = extended.generateGuardsFor<Obj>()("field")
+
+    expect(isX({ field: { _tag: "X", x: "hi" } })).toBe(true)
+    expect(isX({ field: { _tag: "Y", y: 1 } })).toBe(false)
+    expect(isY({ field: { _tag: "Y", y: 1 } })).toBe(true)
+  })
+})