effect-app 4.0.0-beta.27 → 4.0.0-beta.272

package/test/dist/rpc.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc.test.d.ts","sourceRoot":"","sources":["../rpc.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACrF,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;;;;;;;;;;;;;;;;;;;;;;;;AAE7C,qBAAa,iBAAkB,SAAQ,sBAIrC;CAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAIL,qBAAa,KAAM,SAAQ,UAQzB;CAAG"}
+{"version":3,"file":"rpc.test.d.ts","sourceRoot":"","sources":["../rpc.test.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAErF,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;;;;;;;;;;;;;;;;;;;;;;;;AAE7C,qBAAa,iBAAkB,SAAQ,sBAIrC;CAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAI0B,KAAK;;;;AAKpC,qBAAa,KAAM,SAAQ,UAQzB;CAAG"}

package/test/dist/secretURL.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secretURL.test.d.ts","sourceRoot":"","sources":["../secretURL.test.ts"],"names":[],"mappings":""}

package/test/dist/special.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"special.test.d.ts","sourceRoot":"","sources":["../special.test.ts"],"names":[],"mappings":""}

package/test/moreStrings.test.ts

@@ -1,4 +1,4 @@
-import { S } from "effect-app"
+import * as S from "effect-app/Schema"
 import * as fc from "fast-check"
 import { urlAlphabet } from "nanoid"
 import { test } from "vitest"

package/test/rpc.test.ts

@@ -1,4 +1,8 @@
+import type * as Effect from "effect/Effect"
+import type * as Option from "effect/Option"
+import { expect, test } from "vitest"
 import { makeRpcClient, NotLoggedInError, UnauthorizedError } from "../src/client.js"
+import { ForceVoid } from "../src/client/makeClient.js"
 import { S } from "../src/index.js"
 import { RpcContextMap } from "../src/rpc.js"
 
@@ -8,16 +12,52 @@ export class RequestContextMap extends RpcContextMap.makeMap({
   test: RpcContextMap.make()(S.Never)
 }) {}
 
-const { TaggedRequest } = makeRpcClient(RequestContextMap)
+const stubMiddleware = {
+  requestContextMap: RequestContextMap.config,
+  requestContext: undefined as never
+}
+const { TaggedRequestFor } = makeRpcClient(stubMiddleware)
+const TaggedRequest = TaggedRequestFor("Test").Query
 
 export class Stats extends TaggedRequest<Stats>()("Stats", {}, {
   allowedRoles: ["manager"],
   success: {
-    usersActive24Hours: S.Number,
-    usersActiveLastWeek: S.Number,
-    newUsersLast24Hours: S.Number,
-    newUsersLastWeek: S.Number
+    usersActive24Hours: S.Finite,
+    usersActiveLastWeek: S.Finite,
+    newUsersLast24Hours: S.Finite,
+    newUsersLastWeek: S.Finite
   }
 }) {}
 
-declare const _stats: typeof Stats.success.Type
+declare const _stats: typeof Stats.Type
+declare const _statsSuccess: typeof Stats.success.Type
+declare const _statsError: typeof Stats.error.Type
+declare const _statsRequestType: typeof Stats.type
+
+test("ForceVoid decodes and encodes as void", () => {
+  const statsFromMake = Stats.make({})
+  const statsFromMakeOption = Stats.makeOption({})
+  const statsFromMakeEffect = Stats.makeEffect({})
+
+  expect(S.decodeUnknownSync(ForceVoid)(undefined)).toBe(undefined)
+  expect(S.is(ForceVoid)(undefined)).toBe(true)
+  expect(S.decodeUnknownSync(ForceVoid)("test")).toBe(undefined)
+  expect(S.is(ForceVoid)("test")).toBe(true)
+  expect(S.encodeUnknownSync(ForceVoid)("test")).toBe(undefined)
+  expect(S.encodeUnknownSync(S.toCodecJson(ForceVoid))("test")).toBe(null)
+  expectTypeOf<typeof _stats>().toEqualTypeOf<Stats>()
+  expectTypeOf<typeof _statsSuccess>().toEqualTypeOf<{
+    readonly usersActive24Hours: number
+    readonly usersActiveLastWeek: number
+    readonly newUsersLast24Hours: number
+    readonly newUsersLastWeek: number
+  }>()
+  // Resource error carries only `config.error` (and optional `generalErrors`); rcm-derived
+  // middleware errors no longer leak into `resource.error` — they reach the wire via the
+  // middleware tag attached to the rpc group (`rpc.middlewares[*].error` failure-union).
+  expectTypeOf<typeof _statsError>().toEqualTypeOf<never>()
+  expectTypeOf<typeof _statsRequestType>().toEqualTypeOf<"query">()
+  expectTypeOf(statsFromMake).toEqualTypeOf<Stats>()
+  expectTypeOf(statsFromMakeOption).toEqualTypeOf<Option.Option<Stats>>()
+  expectTypeOf(statsFromMakeEffect).toEqualTypeOf<Effect.Effect<Stats, S.SchemaError>>()
+})

package/test/schema.test.ts

@@ -1,6 +1,8 @@
 // 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 { describe, expect, expectTypeOf, test } from "vitest"
 
 const A = S.Struct({ a: S.NonEmptyString255, email: S.NullOr(S.Email) })
 test("works", () => {
@@ -14,22 +16,127 @@ 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")
+})
+
+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.Number }),
+    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 +163,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.Number })
-  )
+    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.Number }),
+    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"])
@@ -82,7 +189,7 @@ test("TaggedUnion tags.pick returns a subset of the tag literals", () => {
 test("tags standalone function extracts tags from member schemas", () => {
   const members = [
     S.TaggedStruct("Foo", { foo: S.String }),
-    S.TaggedStruct("Bar", { bar: S.Number })
+    S.TaggedStruct("Bar", { bar: S.Finite })
   ] as const
 
   const tagSchema = S.tags(members)
@@ -95,7 +202,7 @@ test("tags standalone function extracts tags from member schemas", () => {
 test("ExtendTaggedUnion adds tags to an existing Union", () => {
   const union = S.Union([
     S.TaggedStruct("P", { p: S.String }),
-    S.TaggedStruct("Q", { q: S.Number })
+    S.TaggedStruct("Q", { q: S.Finite })
   ])
   const extended = S.ExtendTaggedUnion(union)
 
@@ -109,10 +216,10 @@ 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.Number })
-  )
+    S.TaggedStruct("B", { b: S.Finite })
+  ])
   type T = S.Schema.Type<typeof schema>
 
   const matcher = schema.match({
@@ -124,9 +231,9 @@ test("TaggedUnion match dispatches on _tag", () => {
 })
 
 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 +242,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.Number }),
+    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">()
@@ -149,11 +256,11 @@ test("TaggedUnion with encodeKeys renaming a non-tag key", () => {
   const MemberA = S.TaggedStruct("A", { firstName: S.String }).pipe(
     S.encodeKeys({ firstName: "first_name" })
   )
-  const MemberB = S.TaggedStruct("B", { lastName: S.Number }).pipe(
+  const MemberB = S.TaggedStruct("B", { lastName: S.Finite }).pipe(
     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")
@@ -179,9 +286,9 @@ test("TaggedUnion with encodeKeys renaming a non-tag key", () => {
 
 test("TaggedUnion with TaggedClass members", () => {
   class Foo extends S.TaggedClass<Foo>()("Foo", { name: S.String }) {}
-  class Bar extends S.TaggedClass<Bar>()("Bar", { count: S.Number }) {}
+  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 +307,325 @@ 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.ReadonlyMap({ 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 array with NumberFromString values", () => {
+    const schema = S.ReadonlySet(S.NumberFromString)
+    const decoded = S.decodeUnknownSync(schema)(["1", "2"])
+    expect(decoded).toEqual(new Set([1, 2]))
+  })
+})
+
+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 array of tuples with NumberFromString keys", () => {
+    const schema = S.ReadonlyMap({ key: S.NumberFromString, value: S.String })
+    const decoded = S.decodeUnknownSync(schema)([["1", "one"]])
+    expect(decoded).toEqual(new Map([[1, "one"]]))
+  })
+})
+
+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",
+          allOf: [
+            { 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 has identifier DateOrInvalid and ISO 8601 description", () => {
+    const doc = S.toJsonSchemaDocument(S.Date)
+    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("DateValid has identifier Date and ISO 8601 description", () => {
+    const doc = S.toJsonSchemaDocument(S.DateValid)
+    expect(doc).toStrictEqual({
+      dialect: "draft-2020-12",
+      schema: { "$ref": "#/$defs/Date" },
+      definitions: {
+        Date: {
+          type: "string",
+          description: "a valid ISO 8601 date string that will be decoded as a Date",
+          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)
+  })
+})