effect-app 4.0.0-beta.99 → 4.0.0

package/test/special.test.ts

@@ -1,145 +1,595 @@
-import { Option, Predicate, Schema, SchemaGetter } from "effect"
 import { InvalidStateError, LoginError, NotFoundError, NotLoggedInError, OptimisticConcurrencyException, ServiceUnavailableError, UnauthorizedError, ValidationError } from "effect-app/client/errors"
+import { RequestContext } from "effect-app/RequestContext"
 import * as AppSchema from "effect-app/Schema"
-import { Class, TaggedClass } from "effect-app/Schema/Class"
-import { flattenSimpleAllOf, specialJsonSchemaDocument } from "effect-app/Schema/SpecialJsonSchema"
+import { Class } from "effect-app/Schema/Class"
+import { flattenNestedAnyOf, flattenSimpleAllOf, specialJsonSchemaDocument } from "effect-app/Schema/SpecialJsonSchema"
 import { deduplicateOpenApiSchemas } from "effect-app/Schema/SpecialOpenApi"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
 import * as S from "effect/Schema"
+import * as SchemaGetter from "effect/SchemaGetter"
 import { describe, expect, it } from "vitest"
 
+class _FacadeModel extends AppSchema.Class<_FacadeModel>("FacadeModel")({ value: S.String }) {
+  get upperValue() {
+    return this.value.toUpperCase()
+  }
+
+  static describe(self: { readonly value: string }) {
+    return `value:${self.value}`
+  }
+}
+
+interface FacadeModelEncoded {
+  readonly value: string
+}
+
+interface FacadeModelMake {
+  readonly value: string
+}
+
+class FacadeModel extends AppSchema.OpaqueFacade<
+  FacadeModel,
+  FacadeModelEncoded,
+  FacadeModelMake,
+  never,
+  never
+>()(_FacadeModel) {
+  declare readonly value: string
+  declare readonly upperValue: string
+
+  get decoratedValue() {
+    return `facade:${this.value}`
+  }
+
+  label() {
+    return this.decoratedValue
+  }
+}
+
+class _RenamedFacadeModel extends AppSchema.Class<_RenamedFacadeModel>("RenamedFacadeModel")({
+  internalName: S.String
+}) {
+  get upperName() {
+    return this.internalName.toUpperCase()
+  }
+}
+
+interface RenamedFacadeModelEncoded {
+  readonly external_name: string
+}
+
+interface RenamedFacadeModelMake {
+  readonly internalName: string
+}
+
+class RenamedFacadeModel extends AppSchema.OpaqueFacade<
+  RenamedFacadeModel,
+  RenamedFacadeModelEncoded,
+  RenamedFacadeModelMake,
+  never,
+  never
+>()(_RenamedFacadeModel.pipe(S.encodeKeys({ internalName: "external_name" }))) {
+  declare readonly internalName: string
+  declare readonly upperName: string
+
+  get decoratedName() {
+    return `facade:${this.internalName}`
+  }
+}
+
+const _StructFacadeModel = AppSchema.Struct({ value: S.String })
+
+interface StructFacadeModelEncoded {
+  readonly value: string
+}
+
+interface StructFacadeModelMake {
+  readonly value: string
+}
+
+class StructFacadeModel extends AppSchema.OpaqueFacade<
+  StructFacadeModel,
+  StructFacadeModelEncoded,
+  StructFacadeModelMake,
+  never,
+  never
+>()(_StructFacadeModel) {
+  declare readonly value: string
+}
+
+const _RenamedStructFacadeModel = AppSchema.Struct({ internalName: S.String }).pipe(
+  S.encodeKeys({ internalName: "external_name" })
+)
+
+interface RenamedStructFacadeModelEncoded {
+  readonly external_name: string
+}
+
+interface RenamedStructFacadeModelMake {
+  readonly internalName: string
+}
+
+class RenamedStructFacadeModel extends AppSchema.OpaqueFacade<
+  RenamedStructFacadeModel,
+  RenamedStructFacadeModelEncoded,
+  RenamedStructFacadeModelMake,
+  never,
+  never
+>()(_RenamedStructFacadeModel) {
+  declare readonly internalName: string
+}
+
+const _RenamedOpaqueStructFacadeModel = AppSchema
+  .Opaque<
+    { readonly internalName: string },
+    RenamedStructFacadeModelEncoded
+  >()(AppSchema.Struct({ internalName: S.String }))
+  .pipe(S.encodeKeys({ internalName: "external_name" }))
+
+class RenamedOpaqueStructFacadeModel extends AppSchema.OpaqueFacade<
+  RenamedOpaqueStructFacadeModel,
+  RenamedStructFacadeModelEncoded,
+  RenamedStructFacadeModelMake,
+  never,
+  never
+>()(_RenamedOpaqueStructFacadeModel) {
+  declare readonly internalName: string
+}
+
 describe("Class", () => {
-  it("encoding accepts plain objects matching the struct (Fields argument)", () => {
-    class A extends Class<A>("A")({ a: S.String }) {}
+  describe("strict", () => {
+    it("encoding doesnt accepts plain objects matching the struct (Fields argument)", () => {
+      class A extends Class<A>("A")({ a: S.String }) {}
 
-    // Encoding a class instance still works
-    expect(S.encodeUnknownSync(A)(new A({ a: "hello" }))).toStrictEqual({ a: "hello" })
+      expect(S.encodeUnknownSync(A)(new A({ a: "hello" }))).toStrictEqual({ a: "hello" })
+      expect(() => S.encodeUnknownSync(A)({ a: "world" })).toThrow()
+      expect(() => S.encodeUnknownSync(A)(null)).toThrow()
+    })
 
-    // Encoding a plain object matching the struct now succeeds
-    expect(S.encodeUnknownSync(A)({ a: "world" })).toStrictEqual({ a: "world" })
+    it("encoding rejects plain objects matching the struct (Struct argument)", () => {
+      class A extends Class<A>("A")(S.Struct({ a: S.String })) {}
 
-    // Encoding null still fails
-    expect(() => S.encodeUnknownSync(A)(null)).toThrow()
-  })
+      expect(S.encodeUnknownSync(A)(new A({ a: "hello" }))).toStrictEqual({ a: "hello" })
+      expect(() => S.encodeUnknownSync(A)({ a: "world" })).toThrow()
+      expect(() => S.encodeUnknownSync(A)(null)).toThrow()
+    })
 
-  it("encoding accepts plain objects matching the struct (Struct argument)", () => {
-    class A extends Class<A>("A")(S.Struct({ a: S.String })) {}
+    it("decoding still works normally", () => {
+      class A extends Class<A>("A")({ a: S.String }) {}
 
-    expect(S.encodeUnknownSync(A)(new A({ a: "hello" }))).toStrictEqual({ a: "hello" })
-    expect(S.encodeUnknownSync(A)({ a: "world" })).toStrictEqual({ a: "world" })
-    expect(() => S.encodeUnknownSync(A)(null)).toThrow()
-  })
+      const decoded = S.decodeUnknownSync(A)({ a: "hello" })
+      expect(decoded).toBeInstanceOf(A)
+      expect(decoded.a).toBe("hello")
 
-  it("decoding still works normally", () => {
-    class A extends Class<A>("A")({ a: S.String }) {}
+      expect(() => S.decodeUnknownSync(A)(null)).toThrow()
+      expect(() => S.decodeUnknownSync(A)({ a: 1 })).toThrow()
+    })
 
-    const decoded = S.decodeUnknownSync(A)({ a: "hello" })
-    expect(decoded).toBeInstanceOf(A)
-    expect((decoded as A).a).toBe("hello")
+    it("S.is accepts class instances and not matching plain objects", () => {
+      class A extends Class<A>("A")({ a: S.String }) {}
 
-    expect(() => S.decodeUnknownSync(A)(null)).toThrow()
-    expect(() => S.decodeUnknownSync(A)({ a: 1 })).toThrow()
-  })
+      expect(S.is(A)(new A({ a: "hello" }))).toBe(true)
+      expect(S.is(A)({ a: "world" })).toBe(false)
+      expect(S.is(A)({ a: 1 })).toBe(false)
+      expect(S.is(A)(null)).toBe(false)
+    })
 
-  it("rejects values that don't match the struct", () => {
-    class A extends Class<A>("A")({ a: S.String }) {}
+    it("rejects values that don't match the struct", () => {
+      class A extends Class<A>("A")({ a: S.String }) {}
 
-    expect(() => S.encodeUnknownSync(A)({ a: 123 })).toThrow()
-    expect(() => S.encodeUnknownSync(A)("not an object")).toThrow()
-  })
+      expect(() => S.encodeUnknownSync(A)({ a: 123 })).toThrow()
+      expect(() => S.encodeUnknownSync(A)("not an object")).toThrow()
+    })
 
-  it("returns a class constructor — new and instanceof work", () => {
-    class A extends Class<A>("A")({ a: S.String }) {}
+    it("returns a class constructor — new and instanceof work", () => {
+      class A extends Class<A>("A")({ a: S.String }) {}
 
-    const instance = new A({ a: "hello" })
-    expect(instance).toBeInstanceOf(A)
-    expect(instance.a).toBe("hello")
-  })
+      const instance = new A({ a: "hello" })
+      expect(instance).toBeInstanceOf(A)
+      expect(instance.a).toBe("hello")
+    })
 
-  it("preserves fields and identifier", () => {
-    class A extends Class<A>("A")({ a: S.String, b: S.Number }) {}
+    it("preserves fields and identifier", () => {
+      class A extends Class<A>("A")({ a: S.String, b: S.Number }) {}
 
-    expect(A.identifier).toBe("A")
-    expect(Object.keys(A.fields)).toStrictEqual(["a", "b"])
+      expect(A.identifier).toBe("A")
+      expect(Object.keys(A.fields)).toStrictEqual(["a", "b"])
+    })
   })
-})
 
-describe("Class constructor", () => {
-  it("works as a base class — new, instanceof, encoding plain objects", () => {
-    class A extends Class<A>("A")({ a: S.String }) {}
+  describe("non strict", () => {
+    it("encoding accepts plain objects matching the struct (Fields argument)", () => {
+      class A extends Class<A>("A")({ a: S.String }, undefined, { strict: false }) {}
+
+      expect(S.encodeUnknownSync(A)(new A({ a: "hello" }))).toStrictEqual({ a: "hello" })
+      expect(S.encodeUnknownSync(A)({ a: "world" })).toStrictEqual({ a: "world" })
+      expect(() => S.encodeUnknownSync(A)(null)).toThrow()
+    })
 
-    // Construction
-    const instance = new A({ a: "hello" })
-    expect(instance).toBeInstanceOf(A)
-    expect(instance.a).toBe("hello")
+    it("encoding accepts plain objects matching the struct (Struct argument)", () => {
+      class A extends Class<A>("A")(S.Struct({ a: S.String }), undefined, { strict: false }) {}
 
-    // Encoding a class instance
-    expect(S.encodeUnknownSync(A)(instance)).toStrictEqual({ a: "hello" })
+      expect(S.encodeUnknownSync(A)(new A({ a: "hello" }))).toStrictEqual({ a: "hello" })
+      expect(S.encodeUnknownSync(A)({ a: "world" })).toStrictEqual({ a: "world" })
+      expect(() => S.encodeUnknownSync(A)(null)).toThrow()
+    })
 
-    // Encoding a plain object
-    expect(S.encodeUnknownSync(A)({ a: "world" })).toStrictEqual({ a: "world" })
+    it("S.is accepts class instances and matching plain objects", () => {
+      class A extends Class<A>("A")({ a: S.String }, undefined, { strict: false }) {}
 
-    // Encoding invalid input fails
-    expect(() => S.encodeUnknownSync(A)(null)).toThrow()
-    expect(() => S.encodeUnknownSync(A)({ a: 123 })).toThrow()
+      expect(S.is(A)(new A({ a: "hello" }))).toBe(true)
+      expect(S.is(A)({ a: "world" })).toBe(true)
+      expect(S.is(A)({ a: 1 })).toBe(false)
+      expect(S.is(A)(null)).toBe(false)
+    })
   })
+})
 
-  it("decoding works normally", () => {
-    class A extends Class<A>("A")({ a: S.String }) {}
+describe("Class constructor", () => {
+  describe("strict", () => {
+    it("works as a base class — new, instanceof, encoding plain objects", () => {
+      class A extends Class<A>("A")({ a: S.String }) {}
+
+      const instance = new A({ a: "hello" })
+      expect(instance).toBeInstanceOf(A)
+      expect(instance.a).toBe("hello")
+
+      expect(S.encodeUnknownSync(A)(instance)).toStrictEqual({ a: "hello" })
+      expect(() => S.encodeUnknownSync(A)({ a: "world" })).toThrow()
+      expect(() => S.encodeUnknownSync(A)(null)).toThrow()
+      expect(() => S.encodeUnknownSync(A)({ a: 123 })).toThrow()
+    })
 
-    const decoded = S.decodeUnknownSync(A)({ a: "hello" })
-    expect(decoded).toBeInstanceOf(A)
-    expect((decoded as A).a).toBe("hello")
+    it("decoding works normally", () => {
+      class A extends Class<A>("A")({ a: S.String }) {}
 
-    expect(() => S.decodeUnknownSync(A)({ a: 1 })).toThrow()
+      const decoded = S.decodeUnknownSync(A)({ a: "hello" })
+      expect(decoded).toBeInstanceOf(A)
+      expect(decoded.a).toBe("hello")
+
+      expect(() => S.decodeUnknownSync(A)({ a: 1 })).toThrow()
+    })
+
+    it("exposes fields, identifier", () => {
+      class A extends Class<A>("A")({ a: S.String, b: S.Number }) {}
+
+      expect(A.identifier).toBe("A")
+      expect(Object.keys(A.fields)).toStrictEqual(["a", "b"])
+    })
   })
 
-  it("exposes fields, identifier", () => {
-    class A extends Class<A>("A")({ a: S.String, b: S.Number }) {}
+  describe("non strict", () => {
+    it("works as a base class — new, instanceof, encoding plain objects", () => {
+      class A extends Class<A>("A")({ a: S.String }, undefined, { strict: false }) {}
 
-    expect(A.identifier).toBe("A")
-    expect(Object.keys(A.fields)).toStrictEqual(["a", "b"])
+      const instance = new A({ a: "hello" })
+      expect(instance).toBeInstanceOf(A)
+      expect(instance.a).toBe("hello")
+
+      expect(S.encodeUnknownSync(A)(instance)).toStrictEqual({ a: "hello" })
+      expect(S.encodeUnknownSync(A)({ a: "world" })).toStrictEqual({ a: "world" })
+      expect(() => S.encodeUnknownSync(A)(null)).toThrow()
+      expect(() => S.encodeUnknownSync(A)({ a: 123 })).toThrow()
+    })
   })
 })
 
-describe("TaggedClass constructor", () => {
-  it("works as a base class with _tag — new, instanceof, encoding plain objects", () => {
-    class Circle extends TaggedClass<Circle>()("Circle", { radius: S.Number }) {}
+describe("TaggedStruct constructor", () => {
+  it("works with _tag, make, and encoding plain objects", () => {
+    const Circle = AppSchema.TaggedStruct("Circle", { radius: S.Number })
 
-    // Construction
-    const instance = new Circle({ radius: 5 })
-    expect(instance).toBeInstanceOf(Circle)
-    expect(instance._tag).toBe("Circle")
-    expect(instance.radius).toBe(5)
+    const instance = Circle.make({ radius: 5 })
+    expect(instance).toEqual({ _tag: "Circle", radius: 5 })
 
-    // Encoding a class instance
     expect(S.encodeUnknownSync(Circle)(instance)).toStrictEqual({ _tag: "Circle", radius: 5 })
-
-    // Encoding a plain object
     expect(S.encodeUnknownSync(Circle)({ _tag: "Circle", radius: 10 })).toStrictEqual({ _tag: "Circle", radius: 10 })
 
-    // Encoding invalid input fails
     expect(() => S.encodeUnknownSync(Circle)(null)).toThrow()
     expect(() => S.encodeUnknownSync(Circle)({ _tag: "Circle", radius: "nope" })).toThrow()
   })
 
   it("decoding works normally", () => {
-    class Circle extends TaggedClass<Circle>()("Circle", { radius: S.Number }) {}
+    const Circle = AppSchema.TaggedStruct("Circle", { radius: S.Number })
 
     const decoded = S.decodeUnknownSync(Circle)({ _tag: "Circle", radius: 5 })
-    expect(decoded).toBeInstanceOf(Circle)
-    expect((decoded as Circle).radius).toBe(5)
-    expect((decoded as Circle)._tag).toBe("Circle")
+    expect(decoded).toEqual({ _tag: "Circle", radius: 5 })
+  })
+
+  it("S.decodeSync(S.toType(X)) should report n length schema error", () => {
+    class X extends S.Opaque<X>()(S.TaggedStruct("X", { n: S.String.pipe(S.check(S.isMinLength(3))) })) {}
+
+    try {
+      S.decodeSync(S.toType(X))({ _tag: "X", n: "a" /* not length 3 */ })
+      expect.fail("expected decode to fail with a SchemaError")
+    } catch (error) {
+      expect(S.isSchemaError(error)).toBe(true)
+      if (S.isSchemaError(error)) {
+        expect(error.message).toContain("n")
+        expect(error.message.toLowerCase()).toContain("length")
+      }
+    }
   })
 
-  it("exposes fields, identifier", () => {
-    class Circle extends TaggedClass<Circle>()("Circle", { radius: S.Number }) {}
+  it("exposes fields", () => {
+    const Circle = AppSchema.TaggedStruct("Circle", { radius: S.Number })
 
-    expect(Circle.identifier).toBe("Circle")
     expect(Object.keys(Circle.fields)).toContain("_tag")
     expect(Object.keys(Circle.fields)).toContain("radius")
   })
 })
 
+describe("strict declaration option", () => {
+  it("Class strict: true keeps class-level expected errors", () => {
+    class X extends Class<X>("X")({ n: S.String.pipe(S.check(S.isMinLength(3))) }, undefined, { strict: true }) {}
+
+    expect(() => S.decodeSync(S.toType(X))({ n: "a" })).toThrow("Expected X")
+  })
+
+  it("TaggedStruct preserves field-level expected errors", () => {
+    class X extends S.Opaque<X>()(AppSchema.TaggedStruct("X", { n: S.String.pipe(S.check(S.isMinLength(3))) })) {}
+
+    expect(() => S.decodeSync(S.toType(X))({ _tag: "X", n: "a" })).toThrow()
+  })
+
+  it("Class with encoded override strict: true keeps class-level expected errors", () => {
+    class X extends Class<X, never>("X")({ n: S.String.pipe(S.check(S.isMinLength(3))) }, undefined, {
+      strict: true
+    }) {}
+
+    expect(() => S.decodeSync(S.toType(X))({ n: "a" })).toThrow("Expected X")
+  })
+
+  it("TaggedStruct with opaque wrapper decodes tagged input", () => {
+    class X extends S.Opaque<X>()(AppSchema.TaggedStruct("X", { n: S.String.pipe(S.check(S.isMinLength(3))) })) {}
+
+    expect(() => S.decodeSync(S.toType(X))({ _tag: "X", n: "a" })).toThrow()
+  })
+})
+
+describe("Class.copy", () => {
+  it("creates a new instance with updated fields", () => {
+    class A extends Class<A>("A")({ a: S.String, b: S.Number }) {}
+
+    const instance = new A({ a: "hello", b: 1 })
+    const copied: A = A.copy(instance, { b: 2 })
+    expect(copied).toBeInstanceOf(A)
+    expect(copied.a).toBe("hello")
+    expect(copied.b).toBe(2)
+  })
+
+  it("accepts a function for updates", () => {
+    class A extends Class<A>("A")({ a: S.String, b: S.Number }) {}
+
+    const instance = new A({ a: "hello", b: 1 })
+    const copied: A = A.copy(instance, (a) => ({ b: a.b + 1 }))
+    expect(copied).toBeInstanceOf(A)
+    expect(copied.b).toBe(2)
+  })
+
+  it("is pipeable", () => {
+    class A extends Class<A>("A")({ a: S.String, b: S.Number }) {}
+
+    const instance = new A({ a: "hello", b: 1 })
+    const copied: A = A.copy({ b: 2 })(instance)
+    expect(copied).toBeInstanceOf(A)
+    expect(copied.b).toBe(2)
+  })
+})
+
+describe("TaggedStruct (opaque).copy", () => {
+  it("creates a new instance with updated fields", () => {
+    const Circle = AppSchema.TaggedStruct("Circle", { radius: S.Number })
+
+    const instance = Circle.make({ radius: 5 })
+    const copied = Circle.copy(instance, { radius: 10 })
+    expect(copied).toEqual({ _tag: "Circle", radius: 10 })
+  })
+
+  it("accepts a function for updates", () => {
+    const Circle = AppSchema.TaggedStruct("Circle", { radius: S.Number })
+
+    const instance = Circle.make({ radius: 5 })
+    const copied = Circle.copy(instance, (c) => ({ radius: c.radius * 2 }))
+    expect(copied).toEqual({ _tag: "Circle", radius: 10 })
+  })
+})
+
+describe("OpaqueFacade", () => {
+  it("keeps OpaqueFacade usable with struct schemas", () => {
+    const decoded = S.decodeSync(StructFacadeModel)({ value: "hello" })
+
+    expect(decoded).toStrictEqual({ value: "hello" })
+    expect(S.encodeSync(StructFacadeModel)(decoded)).toStrictEqual({ value: "hello" })
+    expect(S.is(StructFacadeModel)(decoded)).toBe(true)
+    expect(S.is(StructFacadeModel)({ value: 1 })).toBe(false)
+  })
+
+  it("keeps encoded-key struct facades on the struct path", () => {
+    const decoded = S.decodeSync(RenamedStructFacadeModel)({ external_name: "fran" })
+
+    expect(decoded).toStrictEqual({ internalName: "fran" })
+    expect(decoded).not.toBeInstanceOf(RenamedStructFacadeModel)
+    expect(S.encodeSync(RenamedStructFacadeModel)(decoded)).toStrictEqual({ external_name: "fran" })
+    expect(S.is(RenamedStructFacadeModel)(decoded)).toBe(true)
+    expect(S.is(RenamedStructFacadeModel)({ external_name: "fran" })).toBe(false)
+  })
+
+  it("keeps encoded-key opaque struct facades on the struct path", () => {
+    const decoded = S.decodeSync(RenamedOpaqueStructFacadeModel)({ external_name: "fran" })
+
+    expect(decoded).toStrictEqual({ internalName: "fran" })
+    expect(decoded).not.toBeInstanceOf(RenamedOpaqueStructFacadeModel)
+    expect(S.encodeSync(RenamedOpaqueStructFacadeModel)(decoded)).toStrictEqual({ external_name: "fran" })
+    expect(S.is(RenamedOpaqueStructFacadeModel)(decoded)).toBe(true)
+    expect(S.is(RenamedOpaqueStructFacadeModel)({ external_name: "fran" })).toBe(false)
+  })
+
+  it("decodes through the public facade class", () => {
+    const decoded = S.decodeSync(FacadeModel)({ value: "hello" })
+    const decodedEffect = Effect.runSync(S.decodeUnknownEffect(FacadeModel)({ value: "effect" }))
+
+    expect(decoded).toBeInstanceOf(FacadeModel)
+    expect(decodedEffect).toBeInstanceOf(FacadeModel)
+    expect(decoded).toBeInstanceOf(_FacadeModel)
+    expect(decoded.value).toBe("hello")
+    expect(decoded.upperValue).toBe("HELLO")
+    expect(decoded.decoratedValue).toBe("facade:hello")
+    expect(decoded.label()).toBe("facade:hello")
+    expect(FacadeModel.describe(decoded)).toBe("value:hello")
+  })
+
+  it("validates facade instances with S.is", () => {
+    const instance = new FacadeModel({ value: "hello" })
+
+    expect(instance).toBeInstanceOf(FacadeModel)
+    expect(instance.upperValue).toBe("HELLO")
+    expect(instance.label()).toBe("facade:hello")
+    expect(S.is(FacadeModel)(instance)).toBe(true)
+    expect(S.is(FacadeModel)(S.decodeSync(FacadeModel)({ value: "world" }))).toBe(true)
+    expect(S.is(FacadeModel)({ value: "plain" })).toBe(false)
+    expect(S.is(FacadeModel)({ value: 1 })).toBe(false)
+  })
+
+  it("decodes renamed keys through the public facade class", () => {
+    const decoded = S.decodeSync(RenamedFacadeModel)({ external_name: "fran" })
+
+    expect(decoded).toBeInstanceOf(RenamedFacadeModel)
+    expect(decoded).toBeInstanceOf(_RenamedFacadeModel)
+    expect(Object.getPrototypeOf(decoded)).toBe(RenamedFacadeModel.prototype)
+    expect(decoded.internalName).toBe("fran")
+    expect(decoded.upperName).toBe("FRAN")
+    expect(decoded.decoratedName).toBe("facade:fran")
+    expect(S.encodeSync(RenamedFacadeModel)(decoded)).toStrictEqual({ external_name: "fran" })
+    expect(S.is(RenamedFacadeModel)(decoded)).toBe(true)
+    expect(S.is(RenamedFacadeModel)({ internalName: "plain" })).toBe(false)
+    expect(S.is(RenamedFacadeModel)({ external_name: "plain" })).toBe(false)
+  })
+
+  it("keeps generated struct facades decodable with public statics", () => {
+    const input: typeof RequestContext.Encoded = {
+      span: { traceId: "trace", spanId: "span", sampled: true },
+      name: "operation",
+      locale: "en",
+      namespace: "tenant"
+    }
+
+    const decoded = S.decodeSync(RequestContext)(input)
+
+    expect(decoded).not.toBeInstanceOf(RequestContext)
+    expect(S.is(RequestContext)(decoded)).toBe(true)
+    expect(RequestContext.toMonitoring(decoded)).toStrictEqual({ operationName: "operation", locale: "en" })
+  })
+
+  it("keeps error facades class-only", () => {
+    const makeStructErrorFacade = () =>
+      AppSchema.OpaqueErrorFacadeClass<
+        { readonly value: string },
+        { readonly value: string },
+        { readonly value: string },
+        never,
+        never
+      >()(
+        // Runtime guard: only class schemas are accepted (struct schemas throw).
+        AppSchema.Struct({ value: S.String }) as never
+      )
+
+    expect(makeStructErrorFacade).toThrow("OpaqueErrorFacadeClass requires a class schema")
+  })
+})
+
+describe("Struct.copy", () => {
+  it("creates a new value with updated fields", () => {
+    const A = AppSchema.Struct({ a: S.String, b: S.Number })
+
+    const instance = A.make({ a: "hello", b: 1 })
+    const copied = A.copy(instance, { b: 2 })
+
+    expect(copied).toEqual({ a: "hello", b: 2 })
+    expect(copied).not.toBe(instance)
+  })
+
+  it("accepts a function for updates", () => {
+    const A = AppSchema.Struct({ a: S.String, b: S.Number })
+
+    const instance = A.make({ a: "hello", b: 1 })
+    const copied = A.copy(instance, (a) => ({ b: a.b + 1 }))
+
+    expect(copied).toEqual({ a: "hello", b: 2 })
+  })
+
+  it("allows widening updates against the full struct type", () => {
+    const A = AppSchema.Struct({
+      name: S.String,
+      state: S.Union([
+        S.Struct({ _tag: S.tag("a"), a: S.String }),
+        S.Struct({ _tag: S.tag("b"), b: S.Number })
+      ])
+    })
+
+    const instance = A.make({ name: "x", state: { _tag: "a", a: "a" } })
+    const copied = A.copy(instance, { state: { _tag: "b", b: 1 } })
+
+    expect(copied).toEqual({ name: "x", state: { _tag: "b", b: 1 } })
+  })
+
+  it("copy function is preserved when using .annotate()", () => {
+    const A = AppSchema.Struct({ a: S.String, b: S.Number }).annotate({ title: "A" })
+
+    const instance = A.make({ a: "hello", b: 1 })
+    const copied = A.copy(instance, { b: 2 })
+
+    expect(copied).toEqual({ a: "hello", b: 2 })
+    expect(copied).not.toBe(instance)
+  })
+
+  it("copy function is preserved when using .annotateKey()", () => {
+    const A = AppSchema.Struct({ a: S.String, b: S.Number }).annotateKey({ title: "A" })
+
+    const instance = A.make({ a: "hello", b: 1 })
+    const copied = A.copy(instance, { b: 2 })
+
+    expect(copied).toEqual({ a: "hello", b: 2 })
+    expect(copied).not.toBe(instance)
+  })
+
+  it("copy function is preserved when using .mapFields()", () => {
+    const A = AppSchema.Struct({ a: S.String, b: S.Number }).mapFields((f) => ({ ...f }))
+
+    const instance = A.make({ a: "hello", b: 1 })
+    const copied = A.copy(instance, { b: 2 })
+
+    expect(copied).toEqual({ a: "hello", b: 2 })
+    expect(copied).not.toBe(instance)
+  })
+
+  it("copy function is preserved through chained calls", () => {
+    const A = AppSchema
+      .Struct({ a: S.String, b: S.Number })
+      .annotate({ title: "A" })
+      .annotateKey({ description: "test" })
+
+    const instance = A.make({ a: "hello", b: 1 })
+    const copied = A.copy(instance, { b: 2 })
+
+    expect(copied).toEqual({ a: "hello", b: 2 })
+    expect(copied).not.toBe(instance)
+  })
+})
+
+describe("TaggedStruct.copy", () => {
+  it("creates a new tagged value with updated fields", () => {
+    const Circle = AppSchema.TaggedStruct("Circle", { radius: S.Number })
+
+    const instance = Circle.make({ radius: 5 })
+    const copied = Circle.copy(instance, { radius: 10 })
+
+    expect(copied).toEqual({ _tag: "Circle", radius: 10 })
+    expect(copied).not.toBe(instance)
+  })
+})
+
 describe("TaggedError", () => {
   it("InvalidStateError toString includes the message", () => {
     const error = new InvalidStateError("something went wrong")
@@ -191,36 +641,36 @@ describe("TaggedError", () => {
 
 describe("SpecialJsonSchema", () => {
   it("nullable to optional — from NullOr", () => {
-    const nullableDecodedUndefinedEncoded = (schema: Schema.Top) => {
+    const nullableDecodedUndefinedEncoded = (schema: S.Top) => {
       const isNullableSchema = "members" in schema
         && globalThis.Array.isArray((schema as any).members)
         && (schema as any).members.length === 2
         && (schema as any).members.some((member: any) => member.ast._tag === "Null")
 
-      const nullableMembers = isNullableSchema ? (schema as any).members as ReadonlyArray<Schema.Top> : undefined
+      const nullableMembers = isNullableSchema ? (schema as any).members as ReadonlyArray<S.Top> : undefined
       const innerSchema = nullableMembers
         ? nullableMembers.find((member: any) => member.ast._tag !== "Null")!
         : schema
 
-      const nullableSchema = isNullableSchema ? schema : Schema.NullOr(schema)
+      const nullableSchema = isNullableSchema ? schema : S.NullOr(schema)
 
       return nullableSchema.pipe(
-        Schema.encodeTo(Schema.optionalKey(innerSchema), {
+        S.encodeTo(S.optionalKey(innerSchema), {
           decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)),
           encode: SchemaGetter.transformOptional(Option.filter(Predicate.isNotNull))
         })
       )
     }
 
-    const fromNullOr = nullableDecodedUndefinedEncoded(Schema.NullOr(Schema.String))
-    const structFromNullOr = Schema.Struct({ status: fromNullOr })
+    const fromNullOr = nullableDecodedUndefinedEncoded(S.NullOr(S.String))
+    const structFromNullOr = S.Struct({ status: fromNullOr })
 
-    const encode = Schema.encodeUnknownSync(structFromNullOr as any)
-    const encodedNull = encode({ status: null }) as any
+    const encode = S.encodeUnknownSync(structFromNullOr as any)
+    const encodedNull = encode({ status: null })
     expect("status" in encodedNull).toBe(false)
     expect(encode({ status: "test" })).toStrictEqual({ status: "test" })
 
-    const decode = Schema.decodeUnknownSync(structFromNullOr as any)
+    const decode = S.decodeUnknownSync(structFromNullOr as any)
     expect(decode({})).toStrictEqual({ status: null })
     expect(decode({ status: "test" })).toStrictEqual({ status: "test" })
 
@@ -229,34 +679,34 @@ describe("SpecialJsonSchema", () => {
       dialect: "draft-2020-12",
       schema: {
         "type": "object",
+        "additionalProperties": true,
         "properties": {
           "status": { "type": "string" }
-        },
-        "additionalProperties": false
+        }
       },
       definitions: {}
     })
   })
 
   it("identifies X universally — deduplicates same-fingerprint references", () => {
-    const X = Schema.String.annotate({ title: "X", identifier: "X" })
+    const X = S.String.annotate({ title: "X", identifier: "X" })
 
-    const s = Schema.Struct({
-      a: Schema.NullOr(X).pipe(
-        Schema.encodeTo(Schema.optionalKey(X), {
+    const s = S.Struct({
+      a: S.NullOr(X).pipe(
+        S.encodeTo(S.optionalKey(X), {
           decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)),
           encode: SchemaGetter.transformOptional(Option.filter(Predicate.isNotNull))
         })
       ),
-      b: Schema.NullOr(X).pipe(
-        Schema.encodeTo(Schema.optionalKey(X), {
+      b: S.NullOr(X).pipe(
+        S.encodeTo(S.optionalKey(X), {
           decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)),
           encode: SchemaGetter.transformOptional(Option.filter(Predicate.isNotNull))
         })
       ),
-      c: Schema.NullOr(X),
+      c: S.NullOr(X),
       d: X,
-      e: X.pipe(Schema.optionalKey)
+      e: X.pipe(S.optionalKey)
     })
 
     const doc = specialJsonSchemaDocument(s)
@@ -264,6 +714,7 @@ describe("SpecialJsonSchema", () => {
       dialect: "draft-2020-12",
       schema: {
         "type": "object",
+        "additionalProperties": true,
         "properties": {
           "a": { "$ref": "#/$defs/X" },
           "b": { "$ref": "#/$defs/X" },
@@ -276,8 +727,7 @@ describe("SpecialJsonSchema", () => {
           "d": { "$ref": "#/$defs/X" },
           "e": { "$ref": "#/$defs/X" }
         },
-        "required": ["c", "d"],
-        "additionalProperties": false
+        "required": ["c", "d"]
       },
       definitions: {
         X: {
@@ -289,16 +739,16 @@ describe("SpecialJsonSchema", () => {
   })
 
   it("shared annotated schema via helper — deduplicates", () => {
-    const X = Schema.String.annotate({ title: "X", identifier: "X" })
+    const X = S.String.annotate({ title: "X", identifier: "X" })
 
     const cache = new WeakMap()
-    const nullableDecodedUndefinedEncoded = (schema: Schema.Top) => {
+    const nullableDecodedUndefinedEncoded = (schema: S.Top) => {
       const isNullableSchema = "members" in schema
         && globalThis.Array.isArray((schema as any).members)
         && (schema as any).members.length === 2
         && (schema as any).members.some((member: any) => member.ast._tag === "Null")
 
-      const nullableMembers = isNullableSchema ? (schema as any).members as ReadonlyArray<Schema.Top> : undefined
+      const nullableMembers = isNullableSchema ? (schema as any).members as ReadonlyArray<S.Top> : undefined
       const innerSchema = nullableMembers
         ? nullableMembers.find((member: any) => member.ast._tag !== "Null")!
         : schema
@@ -306,9 +756,9 @@ describe("SpecialJsonSchema", () => {
       const cached = cache.get(innerSchema.ast)
       if (cached !== undefined) return cached
 
-      const nullableSchema = isNullableSchema ? schema : Schema.NullOr(schema)
+      const nullableSchema = isNullableSchema ? schema : S.NullOr(schema)
       const out = nullableSchema.pipe(
-        Schema.encodeTo(Schema.optionalKey(innerSchema), {
+        S.encodeTo(S.optionalKey(innerSchema), {
           decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)),
           encode: SchemaGetter.transformOptional(Option.filter(Predicate.isNotNull))
         })
@@ -318,12 +768,12 @@ describe("SpecialJsonSchema", () => {
       return out
     }
 
-    const structWithShared = Schema.Struct({
+    const structWithShared = S.Struct({
       a: nullableDecodedUndefinedEncoded(X),
-      b: nullableDecodedUndefinedEncoded(Schema.NullOr(X)),
-      c: Schema.NullOr(X),
+      b: nullableDecodedUndefinedEncoded(S.NullOr(X)),
+      c: S.NullOr(X),
       d: X,
-      e: X.pipe(Schema.optionalKey)
+      e: X.pipe(S.optionalKey)
     })
 
     const doc = specialJsonSchemaDocument(structWithShared)
@@ -331,6 +781,7 @@ describe("SpecialJsonSchema", () => {
       dialect: "draft-2020-12",
       schema: {
         "type": "object",
+        "additionalProperties": true,
         "properties": {
           "a": { "$ref": "#/$defs/X" },
           "b": { "$ref": "#/$defs/X" },
@@ -343,8 +794,7 @@ describe("SpecialJsonSchema", () => {
           "d": { "$ref": "#/$defs/X" },
           "e": { "$ref": "#/$defs/X" }
         },
-        "required": ["c", "d"],
-        "additionalProperties": false
+        "required": ["c", "d"]
       },
       definitions: {
         X: {
@@ -658,8 +1108,7 @@ describe("Post-processing integration — real Effect Schema types", () => {
     const doc = specialJsonSchemaDocument(AppSchema.PositiveInt)
     expect(doc.definitions["PositiveInt"]).toStrictEqual({
       type: "integer",
-      exclusiveMinimum: 0,
-      title: "PositiveInt"
+      exclusiveMinimum: 0
     })
   })
 
@@ -668,8 +1117,7 @@ describe("Post-processing integration — real Effect Schema types", () => {
     expect(doc.definitions["NonEmptyString255"]).toStrictEqual({
       type: "string",
       minLength: 1,
-      maxLength: 255,
-      title: "NonEmptyString255"
+      maxLength: 255
     })
   })
 
@@ -680,6 +1128,7 @@ describe("Post-processing integration — real Effect Schema types", () => {
     // null variant preserved (correct JSON Schema for NullOr)
     expect(doc.schema).toStrictEqual({
       type: "object",
+      additionalProperties: true,
       properties: {
         note: {
           anyOf: [
@@ -688,16 +1137,14 @@ describe("Post-processing integration — real Effect Schema types", () => {
           ]
         }
       },
-      required: ["note"],
-      additionalProperties: false
+      required: ["note"]
     })
 
     // allOf flattened in the referenced definition
     expect(doc.definitions["NonEmptyString64k"]).toStrictEqual({
       type: "string",
       minLength: 1,
-      maxLength: 65536,
-      title: "NonEmptyString64k"
+      maxLength: 65536
     })
   })
 
@@ -705,14 +1152,13 @@ describe("Post-processing integration — real Effect Schema types", () => {
     const doc = specialJsonSchemaDocument(AppSchema.NonNegativeInt)
     expect(doc.definitions["NonNegativeInt"]).toStrictEqual({
       type: "integer",
-      minimum: 0,
-      title: "NonNegativeInt"
+      minimum: 0
     })
   })
 
-  it("NullOr union preserves null and non-null members in anyOf", () => {
-    const A = S.String.annotate({ identifier: "A", title: "A" })
-    const B = S.Boolean.annotate({ identifier: "B", title: "B" })
+  it("NullOr union flattens nested anyOf members", () => {
+    const A = S.String.annotate({ identifier: "A" })
+    const B = S.Boolean.annotate({ identifier: "B" })
     const schema = S.Struct({
       value: S.NullOr(S.Union([A, B]))
     })
@@ -721,9 +1167,95 @@ describe("Post-processing integration — real Effect Schema types", () => {
 
     expect(valueProp).toStrictEqual({
       anyOf: [
-        { anyOf: [{ $ref: "#/$defs/A" }, { $ref: "#/$defs/B" }] },
+        { $ref: "#/$defs/A" },
+        { $ref: "#/$defs/B" },
         { type: "null" }
       ]
     })
   })
 })
+
+describe("flattenNestedAnyOf", () => {
+  it("flattens nested anyOf with no sibling keys", () => {
+    const input = {
+      anyOf: [
+        { anyOf: [{ type: "string" }, { type: "number" }] },
+        { type: "null" }
+      ]
+    }
+    expect(flattenNestedAnyOf(input)).toStrictEqual({
+      anyOf: [
+        { type: "string" },
+        { type: "number" },
+        { type: "null" }
+      ]
+    })
+  })
+
+  it("does not flatten anyOf entry with sibling keys", () => {
+    const input = {
+      anyOf: [
+        { anyOf: [{ type: "string" }], title: "X" },
+        { type: "null" }
+      ]
+    }
+    // The inner anyOf is not flattened into the outer (sibling "title" prevents it),
+    // but the single-element inner anyOf is unwrapped within the entry itself
+    expect(flattenNestedAnyOf(input)).toStrictEqual({
+      anyOf: [
+        { type: "string", title: "X" },
+        { type: "null" }
+      ]
+    })
+  })
+
+  it("unwraps anyOf with single item after flattening", () => {
+    const input = {
+      anyOf: [
+        { anyOf: [{ type: "string" }] }
+      ]
+    }
+    expect(flattenNestedAnyOf(input)).toStrictEqual({ type: "string" })
+  })
+
+  it("unwraps anyOf with single item, merging sibling properties", () => {
+    const input = {
+      title: "MyField",
+      anyOf: [{ type: "string" }]
+    }
+    expect(flattenNestedAnyOf(input)).toStrictEqual({
+      title: "MyField",
+      type: "string"
+    })
+  })
+
+  it("recurses into nested objects", () => {
+    const input = {
+      properties: {
+        field: {
+          anyOf: [
+            { anyOf: [{ $ref: "#/defs/A" }, { $ref: "#/defs/B" }] },
+            { type: "null" }
+          ]
+        }
+      }
+    }
+    expect(flattenNestedAnyOf(input)).toStrictEqual({
+      properties: {
+        field: {
+          anyOf: [
+            { $ref: "#/defs/A" },
+            { $ref: "#/defs/B" },
+            { type: "null" }
+          ]
+        }
+      }
+    })
+  })
+
+  it("passes through non-objects unchanged", () => {
+    expect(flattenNestedAnyOf(null)).toBe(null)
+    expect(flattenNestedAnyOf(42)).toBe(42)
+    expect(flattenNestedAnyOf("hello")).toBe("hello")
+  })
+})