effect-app 4.0.0-beta.5 → 4.0.0-beta.52

package/src/ConfigProvider.ts

@@ -0,0 +1,48 @@
+import { type ConfigProvider, make, type Path } from "effect/ConfigProvider"
+import { dual } from "effect/Function"
+
+/**
+ * Scopes a provider so that all lookups are prefixed with the given path
+ * segments.
+ *
+ * When to use:
+ * - Namespacing config under a prefix like `"app"` or `"database"`.
+ * - Reusing the same provider shape for multiple sub-configs.
+ *
+ * Accepts a single string or a full `Path` array. The prefix is prepended
+ * *after* any `mapInput` transformation runs, so ordering matters when
+ * composing with {@link mapInput} or {@link constantCase}.
+ *
+ * Supports both data-last and data-first calling conventions.
+ *
+ * **Example** (Nesting under a prefix)
+ *
+ * ```ts
+ * import { ConfigProvider } from "effect"
+ *
+ * const provider = ConfigProvider.fromEnv({
+ *   env: { APP_HOST: "localhost", APP_PORT: "3000" }
+ * })
+ *
+ * // Lookups for ["HOST"] now resolve to ["APP", "HOST"]
+ * const scoped = ConfigProvider.nested(provider, "APP")
+ * ```
+ *
+ * @see {@link mapInput} – for arbitrary path transformations
+ *
+ * @category Combinators
+ * @since 4.0.0
+ */
+export const nested: {
+  (prefix: string | Path): (self: ConfigProvider) => ConfigProvider
+  (self: ConfigProvider, prefix: string | Path): ConfigProvider
+} = dual(
+  2,
+  (self: ConfigProvider, prefix: string | Path): ConfigProvider => {
+    let path: Path = typeof prefix === "string" ? [prefix] : prefix
+    if (self.mapInput) path = self.mapInput(path)
+    return make(self.get, self.mapInput, self.prefix ? [...self.prefix, ...path] : path)
+  }
+)
+
+export * from "effect/ConfigProvider"

package/src/Effect.ts

@@ -153,8 +153,9 @@ export function allLower<T extends Record<string, ServiceMap.Service<any, any> |
 ) {
   return Effect.all(
     typedKeysOf(services).reduce((prev, cur) => {
-      const svc = services[cur]
-      prev[((cur as string)[0]!.toLowerCase() + (cur as string).slice(1)) as unknown as LowerFirst<typeof cur>] = svc // "_id" in svc && svc._id === TagTypeId ? svc : svc
+      const svc = services[cur]!
+      prev[((cur as string)[0]!.toLowerCase() + (cur as string).slice(1)) as unknown as LowerFirst<typeof cur>] =
+        "asEffect" in svc ? svc.asEffect() : svc
       return prev
     }, {} as any),
     { concurrency: "inherit" }

package/src/Pure.ts

@@ -117,11 +117,11 @@ export interface PureEnvEnv<W, S, S2> extends ServiceTagged<typeof PureEnvEnv> {
 }
 
 export function get<S>(): Pure<never, S, S, never, never, S> {
-  return (castTag<never, S, S>() as any).use((_: any) => _.env.state)
+  return (castTag<never, S, S>()).useSync((_) => _.env.state)
 }
 
 export function set<S>(s: S): Pure<never, S, S, never, never, void> {
-  return (castTag<never, S, S>() as any).use((_: any) => {
+  return (castTag<never, S, S>()).useSync((_) => {
     _.env.state = s
   })
 }
@@ -129,13 +129,13 @@ export function set<S>(s: S): Pure<never, S, S, never, never, void> {
 export type PureLogT<W> = Pure<W, unknown, never, never, never, void>
 
 export function log<W>(w: W): PureLogT<W> {
-  return (castTag<W, unknown, never>() as any).use((_: any) => {
+  return (castTag<W, unknown, never>()).useSync((_) => {
     _.env.log = Chunk.append(_.env.log, w)
   })
 }
 
 export function logMany<W>(w: Iterable<W>): PureLogT<W> {
-  return (castTag<W, unknown, never>() as any).use((_: any) => {
+  return (castTag<W, unknown, never>()).useSync((_) => {
     _.env.log = Chunk.appendAll(_.env.log, Chunk.fromIterable(w))
   })
 }
@@ -150,17 +150,16 @@ export function runAll<R, E, A, W3, S1, S3, S4 extends S1>(
 > {
   const a = Effect
     .flatMap(self, (x) =>
-      (castTag<W3, S1, S3>() as any)
-        .use(
-          ({ env: _ }: any) => Effect.sync(() => ({ log: _.log, state: _.state }))
+      (castTag<W3, S1, S3>())
+        .useSync(
+          ({ env: _ }) => ({ log: _.log, state: _.state })
         )
         .pipe(
-          Effect.flatMap((_: any) => Effect.succeed(_)),
           Effect.map(
-            ({ log, state }: any) => tuple(log, Result.succeed(tuple(state, x)))
+            ({ log, state }) => tuple(log, Result.succeed(tuple(state, x)))
           )
         ))
-    .pipe(Effect.catch((err: any) => (tagg as any).use((env: any) => tuple(env.env.log, Result.fail(err)))))
+    .pipe(Effect.catch((err: any) => tagg.useSync((env) => tuple(env.env.log, Result.fail(err)))))
   return Effect.provide(a, Layer.succeed(tagg, { env: makePureEnv<W3, S3, S4>(s) as any }) as any) as any
 }
 
@@ -198,7 +197,7 @@ export function runA<R, E, A, W3, S1, S3, S4 extends S1>(
 export function modify<S2, A, S3>(
   mod: (s: S2) => readonly [S3, A]
 ): Effect.Effect<A, never, { env: PureEnv<never, S2, S3> }> {
-  return (castTag<never, S3, S2>() as any).use((_: any) => {
+  return (castTag<never, S3, S2>()).useSync((_) => {
     const [s, a] = mod(_.env.state)
     _.env.state = s as any
     return a
@@ -210,10 +209,10 @@ export function modifyM<W, R, E, A, S2, S3>(
 ): Effect.Effect<A, E, FixEnv<R, W, S2, S3>> {
   // return serviceWithEffect(_ => Ref.modifyM_(_.state, mod))
   return Effect.flatMap(
-    (castTag<W, S3, S2>() as any).use((_: any) => _),
+    (castTag<W, S3, S2>()).useSync((_) => _),
     (_: any) =>
       Effect.map(mod(_.env.state), ([s, a]: any) => {
-        _.env.state = s as any
+        _.env.state = s
         return a
       })
   ) as any

package/src/Schema/Class.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { pipe, Struct as Struct2 } from "effect"
+import { Effect, Option, pipe, Schema, SchemaAST, SchemaIssue, Struct as Struct2 } from "effect"
 import type { Struct } from "effect/Schema"
 import * as S from "effect/Schema"
 
@@ -13,9 +13,6 @@ 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>
 }
@@ -26,6 +23,57 @@ type HasFields<Fields extends Struct.Fields> = {
   readonly from: HasFields<Fields>
 }
 
+export type Class<Self, S extends S.Top & { readonly fields: Struct.Fields }, Inherited> = S.Class<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 structSchema = Schema.Struct(fields)
+  const isStructValue = Schema.is(structSchema)
+  return new SchemaAST.Declaration(
+    ast.typeParameters,
+    () => (input: unknown, self: SchemaAST.Declaration) => {
+      if (input instanceof cls || isStructValue(input)) {
+        return Effect.succeed(input)
+      }
+      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>(identifier: string) => <Fields extends S.Struct.Fields>(
   fieldsOr: Fields | HasFields<Fields>,
   annotations?: ClassAnnotations<Self>
@@ -35,38 +83,84 @@ export const Class: <Self = never>(identifier: string) => <Fields extends S.Stru
     S.Struct<Fields>,
     {}
   > = (identifier) => (fields, annotations) => {
-    const cls = S.Class as any
-    return class extends cls(identifier)(fields, annotations) {
-      constructor(a: any, b = true) {
-        super(a, b)
+    // Build the original Schema.Class
+    const Base = (S.Class as any)(identifier)(fields, 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>()
+
+    return class extends Base {
+      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 = makeRelaxedDeclaration(originalAst, Base.fields, this)
+        astCache.set(this, cached)
+        return cached
       }
-      // 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>(
+  identifier?: string
+) => <Tag extends string, Fields extends S.Struct.Fields>(
   tag: Tag,
   fieldsOr: Fields | HasFields<Fields>,
   annotations?: ClassAnnotations<Self>
-) => [Self] extends [never] ? MissingSelfGeneric<"Class">
+) => [Self] extends [never] ? MissingSelfGeneric<"TaggedClass">
   : EnhancedClass<
     Self,
     S.Struct<{ readonly _tag: S.tag<Tag> } & Fields>,
     {}
   > = (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)
+    const Base = (S.TaggedClass as any)(identifier)(tag, fields, annotations)
+    const originalAstDescriptor = Object.getOwnPropertyDescriptor(Base, "ast")!
+    const astCache = new WeakMap<any, SchemaAST.Declaration>()
+
+    return class extends Base {
+      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 = makeRelaxedDeclaration(originalAst, Base.fields, this)
+        astCache.set(this, cached)
+        return cached
       }
-      // 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
   }
 
+// ---------------------------------------------------------------------------
+// ExtendedClass — like Class but with extra type parameter for hierarchies
+// ---------------------------------------------------------------------------
+
 export const ExtendedClass: <Self, _SelfFrom>(identifier: string) => <Fields extends S.Struct.Fields>(
   fieldsOr: Fields | HasFields<Fields>,
   annotations?: ClassAnnotations<Self>
@@ -76,6 +170,10 @@ export const ExtendedClass: <Self, _SelfFrom>(identifier: string) => <Fields ext
   {}
 > = Class as any
 
+// ---------------------------------------------------------------------------
+// ExtendedTaggedClass — like TaggedClass but with extra type parameter for hierarchies
+// ---------------------------------------------------------------------------
+
 export interface EnhancedTaggedClass<Self, Tag extends string, Fields extends Struct.Fields, SelfFrom>
   extends
     EnhancedClass<

package/src/Schema/SpecialJsonSchema.ts

@@ -0,0 +1,216 @@
+/**
+ * SpecialJsonSchema — A variant of Schema.toJsonSchemaDocument that deduplicates
+ * references sharing the same identifier when they produce identical
+ * representations (based on a string fingerprint).
+ *
+ * Without this, two different AST nodes that have the same identifier and
+ * resolve to the same JSON Schema representation can end up as separate $defs
+ * entries (e.g. "X" and "X1"). This converter collapses them into one.
+ */
+import { Formatter, type JsonSchema, type Schema, SchemaRepresentation } from "effect"
+
+/**
+ * Converts a schema to a JSON Schema Document (draft-2020-12), with an
+ * extra deduplication pass that collapses references sharing the same
+ * base identifier when their representations are identical.
+ *
+ * @example
+ * ```ts
+ * import { Schema, SchemaGetter, Option, Predicate } from "effect"
+ * import { specialJsonSchemaDocument } from "./SpecialJsonSchema.js"
+ *
+ * const X = Schema.String.annotate({ title: "X", identifier: "X" })
+ *
+ * const s = Schema.Struct({
+ *   a: Schema.NullOr(X).pipe(
+ *     Schema.encodeTo(Schema.optionalKey(X), {
+ *       decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)),
+ *       encode: SchemaGetter.transformOptional(Option.filter(Predicate.isNotNull))
+ *     })
+ *   ),
+ *   b: Schema.NullOr(X),
+ *   c: X
+ * })
+ *
+ * // Without dedup: $defs would contain both "X" and "X1" (identical).
+ * // With specialJsonSchemaDocument: only "X" is emitted.
+ * const doc = specialJsonSchemaDocument(s)
+ * ```
+ */
+export function specialJsonSchemaDocument(
+  schema: Schema.Top,
+  options?: Schema.ToJsonSchemaOptions
+): JsonSchema.Document<"draft-2020-12"> {
+  const doc = SchemaRepresentation.fromAST(schema.ast)
+  const deduped = deduplicateReferences(doc)
+  const jd = SchemaRepresentation.toJsonSchemaDocument(deduped, options)
+  return {
+    dialect: "draft-2020-12",
+    schema: jd.schema,
+    definitions: jd.definitions
+  }
+}
+
+/**
+ * Deduplicates references in a Document: when multiple $ref keys share
+ * the same base identifier (e.g. "X" and "X1") and their representations
+ * are identical (by string fingerprint), the duplicates are collapsed into
+ * the first entry found for that identifier.
+ */
+function deduplicateReferences(
+  doc: SchemaRepresentation.Document
+): SchemaRepresentation.Document {
+  const refs = doc.references
+  const refKeys = Object.keys(refs)
+  if (refKeys.length === 0) return doc
+
+  // Group references by base identifier (strip trailing digits added by gen())
+  const identifierGroups = new Map<string, Array<{ key: string; fingerprint: string }>>()
+  for (const key of refKeys) {
+    const base = getBaseIdentifier(key)
+    const fingerprint = Formatter.format(refs[key])
+    const group = identifierGroups.get(base)
+    if (group === undefined) {
+      identifierGroups.set(base, [{ key, fingerprint }])
+    } else {
+      group.push({ key, fingerprint })
+    }
+  }
+
+  // Build a mapping from duplicate keys to their canonical key
+  const remapping = new Map<string, string>()
+  for (const [, group] of identifierGroups) {
+    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 doc
+
+  // Build new references, excluding duplicates
+  const newRefs: Record<string, SchemaRepresentation.Representation> = {}
+  for (const key of refKeys) {
+    if (!remapping.has(key)) {
+      newRefs[key] = refs[key]!
+    }
+  }
+
+  // Rewrite $ref pointers throughout the document
+  const newRepresentation = rewriteRefs(doc.representation, remapping)
+  const rewrittenRefs: Record<string, SchemaRepresentation.Representation> = {}
+  for (const [key, rep] of Object.entries(newRefs)) {
+    rewrittenRefs[key] = rewriteRefs(rep, remapping)
+  }
+
+  return { representation: newRepresentation, references: rewrittenRefs }
+}
+
+/**
+ * Extracts the base identifier from a reference key by stripping trailing
+ * digits appended by the gen() function during fromASTs.
+ * 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 pointers in a Representation tree.
+ */
+function rewriteRefs(
+  rep: SchemaRepresentation.Representation,
+  remapping: Map<string, string>
+): SchemaRepresentation.Representation {
+  switch (rep._tag) {
+    case "Reference": {
+      const target = remapping.get(rep.$ref)
+      return target !== undefined ? { ...rep, $ref: target } : rep
+    }
+    case "Declaration":
+      return {
+        ...rep,
+        typeParameters: rep.typeParameters.map((tp) => rewriteRefs(tp, remapping)),
+        encodedSchema: rewriteRefs(rep.encodedSchema, remapping)
+      }
+    case "Suspend":
+      return {
+        ...rep,
+        thunk: rewriteRefs(rep.thunk, remapping)
+      }
+    case "Arrays":
+      return {
+        ...rep,
+        elements: rep.elements.map((e) => ({ ...e, type: rewriteRefs(e.type, remapping) })),
+        rest: rep.rest.map((r) => rewriteRefs(r, remapping))
+      }
+    case "Objects":
+      return {
+        ...rep,
+        propertySignatures: rep.propertySignatures.map((ps) => ({
+          ...ps,
+          type: rewriteRefs(ps.type, remapping)
+        })),
+        indexSignatures: rep.indexSignatures.map((is) => ({
+          ...is,
+          parameter: rewriteRefs(is.parameter, remapping),
+          type: rewriteRefs(is.type, remapping)
+        })),
+        checks: rewriteChecks(rep.checks, remapping)
+      }
+    case "Union":
+      return {
+        ...rep,
+        types: rep.types.map((t) => rewriteRefs(t, remapping))
+      }
+    case "TemplateLiteral":
+      return {
+        ...rep,
+        parts: rep.parts.map((p) => rewriteRefs(p, remapping))
+      }
+    case "String": {
+      if (rep.contentSchema !== undefined) {
+        return {
+          ...rep,
+          contentSchema: rewriteRefs(rep.contentSchema, remapping)
+        }
+      }
+      return rep
+    }
+    default:
+      // Leaf nodes: Null, Undefined, Void, Never, Unknown, Any, Boolean,
+      // Symbol, Number, BigInt, Literal, UniqueSymbol, ObjectKeyword, Enum
+      return rep
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function rewriteChecks<M>(
+  checks: ReadonlyArray<SchemaRepresentation.Check<M>>,
+  remapping: Map<string, string>
+): ReadonlyArray<SchemaRepresentation.Check<M>> {
+  return checks.map((c) => {
+    switch (c._tag) {
+      case "Filter": {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const meta = c.meta as any
+        if (meta && meta._tag === "isPropertyNames" && meta.propertyNames) {
+          return {
+            ...c,
+            meta: { ...meta, propertyNames: rewriteRefs(meta.propertyNames, remapping) }
+          }
+        }
+        return c
+      }
+      case "FilterGroup":
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return { ...c, checks: rewriteChecks(c.checks, remapping) as any }
+    }
+  })
+}

package/src/Schema/SpecialOpenApi.ts

@@ -0,0 +1,126 @@
+/**
+ * SpecialOpenApi — Deduplicates `components/schemas` entries in an OpenAPI spec.
+ *
+ * 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 and rewrites all `$ref` pointers accordingly.
+ *
+ * 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 })))
+ * ```
+ */
+
+/**
+ * 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 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 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)
+  }
+}