effect-app 4.0.0-beta.18 → 4.0.0-beta.180

package/src/Schema/Class.ts

@@ -1,101 +1,318 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { pipe, Struct as Struct2 } from "effect"
-import type { Struct } from "effect/Schema"
+import { type Cause, Effect, Option, Schema, SchemaAST, SchemaIssue } from "effect"
 import * as S from "effect/Schema"
+import { copyOrigin } from "../utils.js"
+import { concurrencyUnbounded } from "./ext.js"
+import * as SchemaParser from "./SchemaParser.js"
 
 type ClassAnnotations<Self> = S.Annotations.Declaration<Self, readonly [any]>
 
-export interface EnhancedClass<Self, SchemaS extends S.Top & { readonly fields: Struct.Fields }, Inherited>
-  extends S.Class<Self, SchemaS, Inherited>, /* Reason for enhancement */ PropsExtensions<SchemaS["fields"]>
+export interface EnhancedClass<Self, SchemaS extends S.Top & { readonly fields: S.Struct.Fields }, Inherited>
+  extends S.Class<Self, SchemaS, Inherited>
 {
+  /**
+   * See `copyOrigin` docs in `utils.ts` for return-type design details.
+   */
+  readonly copy: ReturnType<typeof copyOrigin<new(_: any) => Self>>
 }
 type MissingSelfGeneric<Usage extends string, Params extends string = ""> =
   `Missing \`Self\` generic - use \`class Self extends ${Usage}<Self>()(${Params}{ ... })\``
 
-export interface PropsExtensions<Fields> {
-  // include: <NewProps extends S.Struct.Fields>(
-  //   fnc: (fields: Fields) => NewProps
-  // ) => NewProps
-  pick: <P extends keyof Fields>(...keys: readonly P[]) => Pick<Fields, P>
-  omit: <P extends keyof Fields>(...keys: readonly P[]) => Omit<Fields, P>
-}
-
-type HasFields<Fields extends Struct.Fields> = {
+type HasFields<Fields extends S.Struct.Fields> = {
   readonly fields: Fields
 } | {
   readonly from: HasFields<Fields>
 }
 
-export const Class: <Self = never>(identifier: string) => <Fields extends S.Struct.Fields>(
+type ClassOptions = {
+  readonly strict?: boolean
+}
+
+declare const ExtendedSchemaNoEncoded: unique symbol
+
+type ExtendedSchemaNoEncoded = typeof ExtendedSchemaNoEncoded
+
+type WithEncoded<SchemaS extends S.Top, Encoded> = Omit<SchemaS, "Encoded"> & { readonly Encoded: Encoded }
+
+type ExtendedSchema<SchemaS extends S.Top, Encoded> = [Encoded] extends [ExtendedSchemaNoEncoded] ? SchemaS
+  : WithEncoded<SchemaS, Encoded>
+
+type OptionalMakeSurface<SchemaS extends S.Top> = {} extends SchemaS["~type.make.in"] ? {
+    make(input?: SchemaS["~type.make.in"], options?: S.MakeOptions): SchemaS["Type"]
+    makeOption(input?: SchemaS["~type.make.in"], options?: S.MakeOptions): Option.Option<SchemaS["Type"]>
+    makeEffect(
+      input?: SchemaS["~type.make.in"],
+      options?: S.MakeOptions
+    ): Effect.Effect<SchemaS["Type"], S.SchemaError>
+  }
+  : {}
+
+export type Class<Self, S extends S.Top & { readonly fields: S.Struct.Fields }, Inherited> = EnhancedClass<
+  Self,
+  S,
+  Inherited
+>
+
+/**
+ * Build a modified Declaration that accepts struct-matching values during
+ * encoding, given the original Declaration and the class's fields.
+ */
+function makeRelaxedDeclaration(
+  ast: SchemaAST.Declaration,
+  fields: Schema.Struct.Fields,
+  cls: any
+): SchemaAST.Declaration {
+  const parseOptions = ast.annotations?.["parseOptions"] as SchemaAST.ParseOptions | undefined
+  const structSchema = Schema.Struct(fields)
+  const annotatedStruct = parseOptions ? S.toType(structSchema).annotate({ parseOptions }) : S.toType(structSchema)
+  const decodeStruct = SchemaParser.decodeUnknownEffect(annotatedStruct)
+
+  return new SchemaAST.Declaration(
+    ast.typeParameters,
+    () => (input: unknown, self: SchemaAST.Declaration, options: SchemaAST.ParseOptions) => {
+      if (input instanceof cls) {
+        return Effect.succeed(input)
+      }
+      if (input !== null && typeof input === "object") {
+        return decodeStruct(input, options)
+      }
+      return Effect.fail(new SchemaIssue.InvalidType(self, Option.some(input)))
+    },
+    ast.annotations,
+    ast.checks,
+    ast.encoding,
+    ast.context
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Class — like Schema.Class but with relaxed encoding
+// ---------------------------------------------------------------------------
+
+/**
+ * Like `Schema.Class`, but the resulting class accepts plain objects matching
+ * the struct schema during encoding — not only `instanceof` or type-id
+ * checks.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Class } from "./Class.js"
+ *
+ * class A extends Class<A>("A")({ a: Schema.String }) {}
+ *
+ * // Construction works as normal:
+ * new A({ a: "hello" })
+ *
+ * // Encoding accepts plain objects:
+ * Schema.encodeUnknownSync(A)({ a: "hello" }) // { a: "hello" }
+ * ```
+ */
+export const Class: <Self = never, Encoded = ExtendedSchemaNoEncoded>(
+  identifier: string
+) => <Fields extends S.Struct.Fields>(
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
 ) => [Self] extends [never] ? MissingSelfGeneric<"Class">
   : EnhancedClass<
     Self,
-    S.Struct<Fields>,
+    ExtendedSchema<S.Struct<Fields>, Encoded>,
     {}
-  > = (identifier) => (fields, annotations) => {
-    const cls = S.Class as any
-    return class extends cls(identifier)(fields, annotations) {
-      constructor(a: any, b = true) {
-        super(a, b)
+  > = (identifier) => (fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    // Build the original Schema.Class
+    const Base = (S.Class as any)(identifier)(fields, { ...concurrencyUnbounded, ...annotations })
+    // Get the original ast getter from the base class
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+
+    // Cache per-class to avoid recomputing
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        // Call the original getter with `this` bound to the actual user class,
+        // so getClassSchema(this) creates a schema that uses `new this(...)`.
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
       }
-      // static readonly include = include(fields)
-      static readonly pick = (...selection: any[]) => pipe(this["fields"], Struct2.pick(selection))
-      static readonly omit = (...selection: any[]) => pipe(this["fields"], Struct2.omit(selection))
     } as any
   }
 
-export const TaggedClass: <Self = never>(identifier?: string) => <Tag extends string, Fields extends S.Struct.Fields>(
+// ---------------------------------------------------------------------------
+// TaggedClass — like Schema.TaggedClass but with relaxed encoding
+// ---------------------------------------------------------------------------
+
+/**
+ * Like `Schema.TaggedClass`, but the resulting class accepts plain objects
+ * matching the struct schema during encoding.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { TaggedClass } from "./Class.js"
+ *
+ * class Circle extends TaggedClass<Circle>()("Circle", {
+ *   radius: Schema.Number
+ * }) {}
+ *
+ * Schema.encodeUnknownSync(Circle)({ _tag: "Circle", radius: 5 })
+ * ```
+ */
+export const TaggedClass: <Self = never, Encoded = ExtendedSchemaNoEncoded>(
+  identifier?: string
+) => <Tag extends string, Fields extends S.Struct.Fields>(
   tag: Tag,
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
-) => [Self] extends [never] ? MissingSelfGeneric<"Class">
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
+) => [Self] extends [never] ? MissingSelfGeneric<"TaggedClass">
   : EnhancedClass<
     Self,
-    S.Struct<{ readonly _tag: S.tag<Tag> } & Fields>,
+    ExtendedSchema<S.Struct<{ readonly _tag: S.tag<Tag> } & Fields>, Encoded>,
     {}
-  > = (identifier) => (tag, fields, annotations) => {
-    const cls = S.TaggedClass as any
-    return class extends cls(identifier)(tag, fields, annotations) {
-      constructor(a: any, b = true) {
-        super(a, b)
+  > = (identifier) => (tag, fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    const Base = (S.TaggedClass as any)(identifier)(tag, fields, { ...concurrencyUnbounded, ...annotations })
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
       }
-      // static readonly include = include(fields)
-      static readonly pick = (...selection: any[]) => pipe(this["fields"], Struct2.pick(selection))
-      static readonly omit = (...selection: any[]) => pipe(this["fields"], Struct2.omit(selection))
     } as any
   }
 
-export const ExtendedClass: <Self, _SelfFrom>(identifier: string) => <Fields extends S.Struct.Fields>(
+// ---------------------------------------------------------------------------
+// ErrorClass — like Schema.ErrorClass but with relaxed encoding
+// ---------------------------------------------------------------------------
+
+export const ErrorClass: <Self = never, Encoded = ExtendedSchemaNoEncoded, Brand = {}>(
+  identifier: string
+) => <Fields extends S.Struct.Fields>(
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
-) => EnhancedClass<
-  Self,
-  S.Struct<Fields>,
-  {}
-> = Class as any
-
-export interface EnhancedTaggedClass<Self, Tag extends string, Fields extends Struct.Fields, SelfFrom>
-  extends
-    EnhancedClass<
-      Self,
-      S.Struct<Fields> & { readonly Encoded: SelfFrom },
-      {}
-    >
-{
-  readonly _tag: Tag
-}
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
+) => [Self] extends [never] ? MissingSelfGeneric<"ErrorClass">
+  : EnhancedClass<
+    Self,
+    ExtendedSchema<S.Struct<Fields>, Encoded>,
+    Cause.YieldableError & Brand
+  > = (identifier) => (fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    const Base = (S.ErrorClass as any)(identifier)(fields, { ...concurrencyUnbounded, ...annotations })
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
+      }
+    } as any
+  }
+
+// ---------------------------------------------------------------------------
+// TaggedErrorClass — like Schema.TaggedErrorClass but with relaxed encoding
+// ---------------------------------------------------------------------------
 
-export const ExtendedTaggedClass: <Self, SelfFrom>(
+export const TaggedErrorClass: <Self = never, Encoded = ExtendedSchemaNoEncoded, Brand = {}>(
   identifier?: string
 ) => <Tag extends string, Fields extends S.Struct.Fields>(
   tag: Tag,
   fieldsOr: Fields | HasFields<Fields>,
-  annotations?: ClassAnnotations<Self>
-) => EnhancedTaggedClass<
-  Self,
-  Tag,
-  { readonly _tag: S.tag<Tag> } & Fields,
-  SelfFrom
-> = TaggedClass as any
+  annotations?: ClassAnnotations<Self>,
+  options?: ClassOptions
+) => [Self] extends [never] ? MissingSelfGeneric<"TaggedErrorClass">
+  : EnhancedClass<
+    Self,
+    ExtendedSchema<S.Struct<{ readonly _tag: S.tag<Tag> } & Fields>, Encoded>,
+    Cause.YieldableError & Brand
+  > = (identifier) => (tag, fields, annotations, options) => {
+    const relaxed = options?.strict === false
+    const Base = (S.TaggedErrorClass as any)(identifier)(tag, fields, { ...concurrencyUnbounded, ...annotations })
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+    const copyCache = new WeakMap<any, ReturnType<typeof copyOrigin>>()
+
+    return class extends Base {
+      static get copy() {
+        let cached = copyCache.get(this)
+        if (cached === undefined) {
+          cached = copyOrigin(this)
+          copyCache.set(this, cached)
+        }
+        return cached
+      }
+      static get ast(): SchemaAST.Declaration {
+        let cached = astCache.get(this)
+        if (cached !== undefined) return cached
+        const originalAst = originalAstDescriptor.get!.call(this) as SchemaAST.Declaration
+        cached = relaxed ? makeRelaxedDeclaration(originalAst, Base.fields, this) : originalAst
+        astCache.set(this, cached)
+        return cached
+      }
+      static mapFields(f: any, options?: any) {
+        return Base.mapFields(f, options).annotate(concurrencyUnbounded)
+      }
+    } as any
+  }
+
+const ExtendedOpaque: <Self, Encoded = ExtendedSchemaNoEncoded, Brand = {}>() => <SchemaS extends S.Top>(
+  schema: SchemaS
+) =>
+  & S.Opaque<Self, ExtendedSchema<SchemaS, Encoded>, Brand>
+  & Omit<SchemaS, keyof S.Top>
+  & OptionalMakeSurface<S.Opaque<Self, ExtendedSchema<SchemaS, Encoded>, Brand>> = S.Opaque as any
+
+export const Opaque = ExtendedOpaque

package/src/Schema/SchemaParser.ts

@@ -0,0 +1,12 @@
+import * as SchemaParser from "effect/SchemaParser"
+import { withDefaultParseOptions } from "./ext.js"
+
+export * from "effect/SchemaParser"
+
+export const decodeEffectConcurrently: typeof SchemaParser.decodeEffect = withDefaultParseOptions(
+  SchemaParser.decodeEffect
+)
+
+export const decodeUnknownEffectConcurrently: typeof SchemaParser.decodeUnknownEffect = withDefaultParseOptions(
+  SchemaParser.decodeUnknownEffect
+)

package/src/Schema/SpecialJsonSchema.ts

@@ -0,0 +1,137 @@
+/**
+ * SpecialJsonSchema — A variant of Schema.toJsonSchemaDocument that
+ * post-processes the output (e.g. flattens simple allOf).
+ */
+import { type JsonSchema, type Schema, SchemaRepresentation } from "effect"
+
+/**
+ * Converts a schema to a JSON Schema Document (draft-2020-12), with
+ * post-processing that flattens simple allOf entries.
+ */
+export function specialJsonSchemaDocument(
+  schema: Schema.Top,
+  options?: Schema.ToJsonSchemaOptions
+): JsonSchema.Document<"draft-2020-12"> {
+  const doc = SchemaRepresentation.fromAST(schema.ast)
+  const jd = SchemaRepresentation.toJsonSchemaDocument(doc, options)
+  const processedDefs: JsonSchema.Definitions = {}
+  for (const [key, def] of Object.entries(jd.definitions)) {
+    processedDefs[key] = postProcessJsonSchema(def)
+  }
+  return {
+    dialect: "draft-2020-12",
+    schema: postProcessJsonSchema(jd.schema),
+    definitions: processedDefs
+  }
+}
+
+/**
+ * Flattens `allOf` entries into the parent when the parent already has a
+ * `type` and every `allOf` entry is a plain constraint object (no `$ref`,
+ * no `type`). Merged properties from `allOf` entries win on conflict.
+ */
+export function flattenSimpleAllOf(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj
+
+  if (globalThis.Array.isArray(obj)) {
+    return obj.map(flattenSimpleAllOf)
+  }
+
+  const record = obj as Record<string, unknown>
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = flattenSimpleAllOf(value)
+  }
+
+  if (result["type"] && globalThis.Array.isArray(result["allOf"])) {
+    const allOf = result["allOf"] as Array<Record<string, unknown>>
+    const canFlatten = allOf.every((entry) =>
+      typeof entry === "object" && entry !== null && !("$ref" in entry) && !("type" in entry)
+    )
+    if (canFlatten) {
+      const { allOf: _, ...rest } = result
+      const merged: Record<string, unknown> = { ...rest }
+      for (const entry of allOf) {
+        Object.assign(merged, entry)
+      }
+      return merged
+    }
+  }
+
+  return result
+}
+
+/**
+ * Recursively removes `additionalProperties: false` from JSON Schema objects.
+ * Only removes when the value is exactly `false` -- other values are left intact.
+ */
+export function removeAdditionalPropertiesFalse(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj
+
+  if (globalThis.Array.isArray(obj)) {
+    return obj.map(removeAdditionalPropertiesFalse)
+  }
+
+  const record = obj as Record<string, unknown>
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "additionalProperties" && value === false) continue
+    result[key] = removeAdditionalPropertiesFalse(value)
+  }
+
+  return result
+}
+
+/**
+ * Flattens nested `anyOf` entries: if an anyOf entry is itself just `{ anyOf: [...] }`
+ * with no other keys, its children are inlined. If only one item remains, the anyOf
+ * wrapper is removed entirely.
+ */
+export function flattenNestedAnyOf(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj
+  if (globalThis.Array.isArray(obj)) return obj.map(flattenNestedAnyOf)
+
+  const record = obj as Record<string, unknown>
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = flattenNestedAnyOf(value)
+  }
+
+  if (globalThis.Array.isArray(result["anyOf"])) {
+    const anyOf = result["anyOf"] as Array<unknown>
+    const flattened: Array<unknown> = []
+    for (const entry of anyOf) {
+      if (
+        typeof entry === "object"
+        && entry !== null
+        && !globalThis.Array.isArray(entry)
+        && "anyOf" in entry
+        && Object.keys(entry).length === 1
+        && globalThis.Array.isArray((entry as Record<string, unknown>)["anyOf"])
+      ) {
+        flattened.push(...(entry as Record<string, unknown>)["anyOf"] as Array<unknown>)
+      } else {
+        flattened.push(entry)
+      }
+    }
+    if (flattened.length === 1) {
+      const { anyOf: _, ...rest } = result
+      const single = flattened[0]
+      if (typeof single === "object" && single !== null && !globalThis.Array.isArray(single)) {
+        return { ...rest, ...single }
+      }
+      return single
+    }
+    result["anyOf"] = flattened
+  }
+
+  return result
+}
+
+/**
+ * Applies JSON Schema post-processing: flattens simple allOf,
+ * flattens nested anyOf, then strips additionalProperties: false.
+ */
+export function postProcessJsonSchema(obj: JsonSchema.JsonSchema): JsonSchema.JsonSchema {
+  return removeAdditionalPropertiesFalse(flattenNestedAnyOf(flattenSimpleAllOf(obj))) as JsonSchema.JsonSchema
+}

package/src/Schema/SpecialOpenApi.ts

@@ -0,0 +1,130 @@
+/**
+ * SpecialOpenApi — Deduplicates `components/schemas` entries in an OpenAPI spec
+ * and applies JSON Schema post-processing (null removal, allOf flattening).
+ *
+ * When `OpenApi.fromApi` generates the spec, different AST nodes sharing the
+ * same identifier can produce duplicate entries (e.g. "X" and "X1") in
+ * `components.schemas`. This module provides a transform function that
+ * collapses those duplicates, rewrites all `$ref` pointers accordingly,
+ * and post-processes schemas for better codegen compatibility.
+ *
+ * Usage with the OpenApi `Transform` annotation:
+ *
+ * ```ts
+ * import { OpenApi } from "effect/unstable"
+ * import { deduplicateOpenApiSchemas } from "./SpecialOpenApi.js"
+ *
+ * const api = HttpApi.make("myApi")
+ *   .pipe(HttpApi.annotateContext(OpenApi.annotations({ transform: deduplicateOpenApiSchemas })))
+ * ```
+ */
+
+import { postProcessJsonSchema } from "./SpecialJsonSchema.js"
+
+/**
+ * Deduplicates `components.schemas` entries in an OpenAPI spec.
+ *
+ * Entries sharing the same base identifier (e.g. "X" and "X1") whose JSON
+ * representations are identical are collapsed into a single canonical entry,
+ * and all `$ref` pointers throughout the spec are rewritten to point to
+ * the canonical key.
+ *
+ * Designed to be used as the `transform` option in `OpenApi.annotations`.
+ */
+export function deduplicateOpenApiSchemas(
+  spec: Record<string, any>
+): Record<string, any> {
+  const components = spec["components"] as Record<string, any> | undefined
+  if (!components) return spec
+  const schemas = components["schemas"] as Record<string, any> | undefined
+  if (!schemas) return spec
+
+  const keys = Object.keys(schemas)
+  if (keys.length === 0) return spec
+
+  // Group keys by base identifier (strip trailing digits)
+  const groups = new Map<string, Array<{ key: string; fingerprint: string }>>()
+  for (const key of keys) {
+    const base = getBaseIdentifier(key)
+    const fingerprint = JSON.stringify(schemas[key])
+    const group = groups.get(base)
+    if (group === undefined) {
+      groups.set(base, [{ key, fingerprint }])
+    } else {
+      group.push({ key, fingerprint })
+    }
+  }
+
+  // Build remapping from duplicate keys to canonical keys
+  const remapping = new Map<string, string>()
+  for (const [, group] of groups) {
+    if (group.length <= 1) continue
+    const seen = new Map<string, string>() // fingerprint -> canonical key
+    for (const entry of group) {
+      const canonical = seen.get(entry.fingerprint)
+      if (canonical !== undefined) {
+        remapping.set(entry.key, canonical)
+      } else {
+        seen.set(entry.fingerprint, entry.key)
+      }
+    }
+  }
+
+  if (remapping.size === 0) return postProcessJsonSchema(spec)
+
+  // Build new schemas object without duplicates
+  const newSchemas: Record<string, any> = {}
+  for (const key of keys) {
+    if (!remapping.has(key)) {
+      newSchemas[key] = schemas[key]
+    }
+  }
+
+  // Deep clone the spec, replace schemas, and rewrite all $ref pointers
+  const newSpec = structuredClone(spec)
+  newSpec["components"]["schemas"] = newSchemas
+  rewriteRefs(newSpec, remapping)
+
+  return postProcessJsonSchema(newSpec)
+}
+
+/**
+ * Extracts the base identifier from a schema key by stripping trailing
+ * digits appended by the gen() function.
+ * E.g. "X1" -> "X", "X" -> "X", "MyType2" -> "MyType"
+ */
+function getBaseIdentifier(key: string): string {
+  const match = key.match(/^(.+?)(\d+)$/)
+  return match ? match[1]! : key
+}
+
+/**
+ * Recursively rewrites `$ref` values in a JSON object tree.
+ * Mutates the object in-place (caller should pass a deep clone).
+ */
+function rewriteRefs(obj: any, remapping: Map<string, string>): void {
+  if (obj === null || typeof obj !== "object") return
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      rewriteRefs(item, remapping)
+    }
+    return
+  }
+
+  if (typeof obj.$ref === "string") {
+    // OpenAPI refs look like "#/components/schemas/X1"
+    const prefix = "#/components/schemas/"
+    if (obj.$ref.startsWith(prefix)) {
+      const refKey = obj.$ref.slice(prefix.length)
+      const canonical = remapping.get(refKey)
+      if (canonical !== undefined) {
+        obj.$ref = prefix + canonical
+      }
+    }
+  }
+
+  for (const value of Object.values(obj)) {
+    rewriteRefs(value, remapping)
+  }
+}

package/src/Schema/brand.ts

@@ -35,11 +35,19 @@ type BrandAnnotations<C extends B.Brand<any>> =
       : {}
   )
 
+type BrandedSchema<Self extends S.Top, C extends B.Brand<any>> =
+  & Omit<S.brand<Self["Rebuild"], B.Brand.Keys<C>>, "Type" | "Iso" | "~type.make">
+  & {
+    readonly Type: C
+    readonly Iso: C
+    readonly "~type.make": C
+  }
+
 export const fromBrand = <C extends B.Brand<any>>(
   constructor: Constructor<C>,
   options?: BrandAnnotations<C>
 ) =>
-<Self extends S.Top>(self: Self): S.brand<Self["~rebuild.out"], B.Brand.Keys<C>> => {
+<Self extends S.Top>(self: Self): BrandedSchema<Self, C> => {
   const branded = S.fromBrand(options?.identifier ?? "Brand", constructor as any)(self as any)
   return options ? (branded as any).pipe(S.annotate(options)) : branded as any
 }