svelte-reflector 2.5.0 → 2.5.2

package/dist/core/schema/DiscriminatedInterfaceRenderer.d.ts

@@ -0,0 +1,35 @@
+import type { ArrayProp } from "../../props/array.property.js";
+import type { EnumProp } from "../../props/enum.property.js";
+import type { ObjectProp } from "../../props/object.property.js";
+import type { PrimitiveProp } from "../../props/primitive.property.js";
+import type { UnionProp } from "../../props/union.property.js";
+/**
+ * Renders a schema's `Interface` as a *discriminated union* type alias when one
+ * of its properties is a `oneOf` carrying a `discriminator` whose `propertyName`
+ * points at a sibling enum property (e.g. `NotificationData.actionMeta` keyed by
+ * `action`). Each `discriminator.mapping` entry (action value → variant schema)
+ * becomes a union member that pins `action` to its literal(s) and `actionMeta`
+ * to the matching variant `Interface`:
+ *
+ * ```ts
+ * export type NotificationDataInterface =
+ *   | { ...commons; action: "STOCK_LOW" | "STOCK_OUT"; actionMeta: ProductStockMetaInterface }
+ *   | { ...commons; action: "ANNOUNCEMENT"; actionMeta: UrlMetaInterface };
+ * ```
+ *
+ * This is what makes `if (n.action === "STOCK_LOW") n.actionMeta.productId`
+ * narrow on plain `Interface`-typed values (raw response data, `.bundle()`,
+ * `.discriminated()`). It never narrows on the live `$state` class instance —
+ * TS can't correlate two independent mutable fields.
+ */
+export declare class DiscriminatedInterfaceRenderer {
+    static render(params: {
+        name: string;
+        union: UnionProp;
+        primitiveProps: PrimitiveProp[];
+        arrayProps: ArrayProp[];
+        objectProps: ObjectProp[];
+        enumProps: EnumProp[];
+        otherUnionProps: UnionProp[];
+    }): string;
+}

package/dist/core/schema/DiscriminatedInterfaceRenderer.js

@@ -0,0 +1,70 @@
+/**
+ * Renders a schema's `Interface` as a *discriminated union* type alias when one
+ * of its properties is a `oneOf` carrying a `discriminator` whose `propertyName`
+ * points at a sibling enum property (e.g. `NotificationData.actionMeta` keyed by
+ * `action`). Each `discriminator.mapping` entry (action value → variant schema)
+ * becomes a union member that pins `action` to its literal(s) and `actionMeta`
+ * to the matching variant `Interface`:
+ *
+ * ```ts
+ * export type NotificationDataInterface =
+ *   | { ...commons; action: "STOCK_LOW" | "STOCK_OUT"; actionMeta: ProductStockMetaInterface }
+ *   | { ...commons; action: "ANNOUNCEMENT"; actionMeta: UrlMetaInterface };
+ * ```
+ *
+ * This is what makes `if (n.action === "STOCK_LOW") n.actionMeta.productId`
+ * narrow on plain `Interface`-typed values (raw response data, `.bundle()`,
+ * `.discriminated()`). It never narrows on the live `$state` class instance —
+ * TS can't correlate two independent mutable fields.
+ */
+export class DiscriminatedInterfaceRenderer {
+    static render(params) {
+        const { name, union, primitiveProps, arrayProps, objectProps, enumProps, otherUnionProps } = params;
+        const discProp = union.discriminator.propertyName;
+        const mapping = union.discriminator.mapping ?? {};
+        // Commons = every property except the discriminant and the discriminated union itself.
+        const allProps = [
+            ...primitiveProps,
+            ...arrayProps,
+            ...objectProps,
+            ...enumProps,
+            ...otherUnionProps,
+        ];
+        const commons = allProps
+            .filter((p) => p.name !== discProp && p.name !== union.name)
+            .map((p) => p.interfaceBuild());
+        // Invert the mapping: variant schema name → the action literals that select it,
+        // preserving first-seen order so output stays deterministic.
+        const byVariant = new Map();
+        for (const [actionValue, ref] of Object.entries(mapping)) {
+            const variant = ref.split("/").at(-1) ?? "";
+            if (!variant)
+                continue;
+            const list = byVariant.get(variant) ?? [];
+            list.push(actionValue);
+            byVariant.set(variant, list);
+        }
+        // The discriminated part: only the discriminant + the union field vary per variant.
+        // Commons are factored into a single object type and intersected with the union —
+        // narrowing on `action` still works through the intersection.
+        const members = [...byVariant.entries()].map(([variant, actions]) => {
+            const literals = actions.map((a) => `"${a}"`).join(" | ");
+            return `{ ${discProp}: ${literals}; ${union.name}: ${variant}Interface }`;
+        });
+        const variantUnion = members.map((m) => `| ${m}`).join("\n");
+        // No commons → emit the bare union (avoid a pointless `{} & (...)`).
+        if (commons.length === 0) {
+            return `
+      export type ${name}Interface =
+        ${variantUnion};
+    `;
+        }
+        return `
+      export type ${name}Interface = {
+        ${commons.join(";\n")}
+      } & (
+        ${variantUnion}
+      );
+    `;
+    }
+}

package/dist/core/schema/ReflectorInterface.d.ts

@@ -2,6 +2,7 @@ import type { ArrayProp } from "../../props/array.property.js";
 import type { EnumProp } from "../../props/enum.property.js";
 import type { ObjectProp } from "../../props/object.property.js";
 import type { PrimitiveProp } from "../../props/primitive.property.js";
+import type { UnionProp } from "../../props/union.property.js";
 export declare class ReflectorInterface {
     builded: string;
     constructor(params: {
@@ -10,5 +11,6 @@ export declare class ReflectorInterface {
         name: string;
         objectProps: ObjectProp[];
         enumProps: EnumProp[];
+        unionProps: UnionProp[];
     });
 }

package/dist/core/schema/ReflectorInterface.js

@@ -1,7 +1,7 @@
 export class ReflectorInterface {
     builded;
     constructor(params) {
-        const { name, arrayProps, primitiveProps, objectProps, enumProps } = params;
+        const { name, arrayProps, primitiveProps, objectProps, enumProps, unionProps } = params;
         const buildedProps = [];
         primitiveProps.forEach((prop) => {
             buildedProps.push(prop.interfaceBuild());
@@ -15,6 +15,9 @@ export class ReflectorInterface {
         enumProps.forEach((prop) => {
             buildedProps.push(prop.interfaceBuild());
         });
+        unionProps.forEach((prop) => {
+            buildedProps.push(prop.interfaceBuild());
+        });
         this.builded = `
       export interface ${name}Interface {
         ${buildedProps}

package/dist/core/schema/Schema.d.ts

@@ -2,6 +2,7 @@ import { ArrayProp } from "../../props/array.property.js";
 import { EnumProp } from "../../props/enum.property.js";
 import { ObjectProp } from "../../props/object.property.js";
 import { PrimitiveProp } from "../../props/primitive.property.js";
+import { UnionProp } from "../../props/union.property.js";
 import type { SchemaObject, ReferenceObject } from "../../types/open-api-spec.interface.js";
 import type { FieldConfigs } from "../../types/types.js";
 import type { CodegenContext } from "../CodegenContext.js";
@@ -11,6 +12,7 @@ export declare class Schema {
     arrayProps: ArrayProp[];
     objectProps: ObjectProp[];
     enumProps: EnumProp[];
+    unionProps: UnionProp[];
     /** Other schema class names this schema depends on (via ObjectProp/$ref arrays) */
     readonly schemaDeps: string[];
     /** Enum type names used by this schema */

package/dist/core/schema/Schema.js

@@ -2,6 +2,7 @@ import { ArrayProp } from "../../props/array.property.js";
 import { EnumProp } from "../../props/enum.property.js";
 import { ObjectProp } from "../../props/object.property.js";
 import { PrimitiveProp } from "../../props/primitive.property.js";
+import { UnionProp } from "../../props/union.property.js";
 import { isReferenceObject } from "../../helpers/helpers.js";
 import { SchemaPropertyClassifier } from "./SchemaPropertyClassifier.js";
 import { SchemaDependencyCollector } from "./SchemaDependencyCollector.js";
@@ -13,6 +14,7 @@ export class Schema {
     arrayProps = [];
     objectProps = [];
     enumProps = [];
+    unionProps = [];
     /** Other schema class names this schema depends on (via ObjectProp/$ref arrays) */
     schemaDeps;
     /** Enum type names used by this schema */
@@ -45,6 +47,7 @@ export class Schema {
         schema.arrayProps = [];
         schema.objectProps = [];
         schema.enumProps = [];
+        schema.unionProps = [];
         schema.schemaDeps = element.kind === "ref" ? [element.type] : [];
         schema.enumDeps = element.kind === "enum" ? [element.type] : [];
         schema.customTypeDeps = [];
@@ -110,12 +113,15 @@ export class Schema {
                 this.objectProps.push(prop);
             else if (prop instanceof EnumProp)
                 this.enumProps.push(prop);
+            else if (prop instanceof UnionProp)
+                this.unionProps.push(prop);
         }
         const deps = SchemaDependencyCollector.collect({
             primitiveProps: this.primitiveProps,
             arrayProps: this.arrayProps,
             objectProps: this.objectProps,
             enumProps: this.enumProps,
+            unionProps: this.unionProps,
         });
         this.schemaDeps = deps.schemaDeps;
         this.enumDeps = deps.enumDeps;
@@ -127,6 +133,7 @@ export class Schema {
             arrayProps: this.arrayProps,
             objectProps: this.objectProps,
             enumProps: this.enumProps,
+            unionProps: this.unionProps,
         });
         this.interface = rendered.interface;
         this.schema = rendered.schema;
@@ -148,6 +155,7 @@ export class Schema {
             arrayProps: this.arrayProps,
             objectProps: this.objectProps,
             enumProps: this.enumProps,
+            unionProps: this.unionProps,
             mode: "request",
         });
         this.schema = rendered.schema;

package/dist/core/schema/SchemaClassRenderer.d.ts

@@ -2,6 +2,7 @@ import type { ArrayProp } from "../../props/array.property.js";
 import type { EnumProp } from "../../props/enum.property.js";
 import type { ObjectProp } from "../../props/object.property.js";
 import type { PrimitiveProp } from "../../props/primitive.property.js";
+import type { UnionProp } from "../../props/union.property.js";
 export declare class SchemaClassRenderer {
     static render(params: {
         name: string;
@@ -9,6 +10,7 @@ export declare class SchemaClassRenderer {
         arrayProps: ArrayProp[];
         objectProps: ObjectProp[];
         enumProps: EnumProp[];
+        unionProps: UnionProp[];
         mode?: "request" | "response";
     }): {
         interface: string;

package/dist/core/schema/SchemaClassRenderer.js

@@ -1,19 +1,36 @@
+import { DiscriminatedInterfaceRenderer } from "./DiscriminatedInterfaceRenderer.js";
 import { ReflectorInterface } from "./ReflectorInterface.js";
 export class SchemaClassRenderer {
     static render(params) {
-        const { name, primitiveProps, arrayProps, objectProps, enumProps } = params;
+        const { name, primitiveProps, arrayProps, objectProps, enumProps, unionProps } = params;
         const mode = params.mode ?? "response";
-        const reflectorInterface = new ReflectorInterface({
-            name,
-            arrayProps,
-            primitiveProps,
-            objectProps,
-            enumProps,
-        });
+        // A `oneOf` with a usable discriminator turns the Interface into a discriminated
+        // union type alias; the matching `discriminated()` accessor is emitted below.
+        const discriminatedUnion = unionProps.find((u) => u.hasDiscriminator);
+        const interfaceStr = discriminatedUnion
+            ? DiscriminatedInterfaceRenderer.render({
+                name,
+                union: discriminatedUnion,
+                primitiveProps,
+                arrayProps,
+                objectProps,
+                enumProps,
+                otherUnionProps: unionProps.filter((u) => u !== discriminatedUnion),
+            })
+            : new ReflectorInterface({ name, arrayProps, primitiveProps, objectProps, enumProps, unionProps }).builded;
         const constructorThis = [];
         const keys = [];
         const bundleParams = [];
         let staticMethod = "";
+        // Optional, always-instantiated sub-DTOs (`nome? = $state<T>(new T)`): the
+        // runtime gate reads this set to skip an empty optional block instead of
+        // flagging its inner `required` fields. Emitted only when non-empty.
+        const optionalDtoNames = objectProps
+            .map((prop) => prop.optionalGateName())
+            .filter((name) => name !== null);
+        const optionalDtosDecl = optionalDtoNames.length
+            ? `readonly _optionalDtos = new Set<string>([${optionalDtoNames.map((name) => `"${name}"`).join(", ")}])`
+            : "";
         primitiveProps.forEach((prop) => {
             constructorThis.push(prop.constructorBuild());
             bundleParams.push(prop.bundleBuild());
@@ -35,6 +52,11 @@ export class SchemaClassRenderer {
             keys.push(prop.classBuild());
             bundleParams.push(prop.bundleBuild());
         });
+        unionProps.forEach((prop) => {
+            constructorThis.push(prop.constructorBuild());
+            keys.push(prop.classBuild());
+            bundleParams.push(prop.bundleBuild());
+        });
         const constructorCode = `constructor(params?: { data?: ${name}Interface | undefined, empty?: boolean }) {
         ${constructorThis.join(";\n")}
       }`;
@@ -43,6 +65,7 @@ export class SchemaClassRenderer {
         arrayProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
         objectProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
         enumProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
+        unionProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
         const hydrateCode = `
       hydrate(data: Partial<${name}Interface>): void {
         ${hydrateLines.join(";\n")}
@@ -52,18 +75,34 @@ export class SchemaClassRenderer {
         this.hydrate(new ${name}({ empty: true }).bundle() as Partial<${name}Interface>);
       }
     `;
+        // Live class instances can't narrow `actionMeta` by `action` (independent
+        // `$state` fields), so expose a plain discriminated snapshot for consumers
+        // that want the narrowing. `bundle()` already returns the discriminated type
+        // (see below), so this is just an ergonomic, cast-free alias.
+        const discriminatedAccessor = discriminatedUnion
+            ? `discriminated(): ${name}Interface { return this.bundle(); }`
+            : "";
         // Request DTO serializa a partir das instâncias `BuildedInput` (carregam os flags
         // required/nullable), não do `.value` pré-extraído — bundleInputs faz a coerção
         // nullable ''→null e cobre array/aninhado. Response fica em bundleStrict (inalterado).
+        //
+        // Para um schema com união discriminada, `bundleStrict` infere a forma plana (action
+        // = enum inteiro), que NÃO é atribuível a nenhum membro da união — o array-root wrapper
+        // (`item.bundle()` tipado como `Interface[]` discriminada) quebraria. O único `as` do
+        // feature mora aqui, fazendo `bundle()` devolver a própria união; `discriminated()` e
+        // `reset()` ficam cast-free por consequência.
         const bundleHelper = mode === "request" ? "inputs" : "strict";
+        const responseBundle = discriminatedUnion
+            ? `return bundleStrict({ ${bundleParams.join(",")} }) as ${name}Interface`
+            : `return bundleStrict({ ${bundleParams.join(",")} })`;
         const bundleBody = mode === "request"
-            ? `return bundleInputs({ ${[...primitiveProps, ...arrayProps, ...objectProps, ...enumProps]
+            ? `return bundleInputs({ ${[...primitiveProps, ...arrayProps, ...objectProps, ...enumProps, ...unionProps]
                 .map((p) => `${p.name}: this.${p.name}`)
                 .join(",")} })`
-            : `return bundleStrict({ ${bundleParams.join(",")} })`;
+            : responseBundle;
         const schema = `
     export class ${name} {
-      ${keys.join(";")}
+      ${[...keys, optionalDtosDecl].filter(Boolean).join(";\n      ")}
 
       ${constructorCode}
 
@@ -74,7 +113,9 @@ export class SchemaClassRenderer {
       bundle(){
         ${bundleBody}
       }
+
+      ${discriminatedAccessor}
     };`;
-        return { interface: reflectorInterface.builded, schema, bundleHelper };
+        return { interface: interfaceStr, schema, bundleHelper };
     }
 }

package/dist/core/schema/SchemaDependencyCollector.d.ts

@@ -2,6 +2,7 @@ import type { ArrayProp } from "../../props/array.property.js";
 import type { EnumProp } from "../../props/enum.property.js";
 import type { ObjectProp } from "../../props/object.property.js";
 import type { PrimitiveProp } from "../../props/primitive.property.js";
+import type { UnionProp } from "../../props/union.property.js";
 export interface SchemaDependencies {
     schemaDeps: string[];
     enumDeps: string[];
@@ -14,5 +15,6 @@ export declare class SchemaDependencyCollector {
         arrayProps: ArrayProp[];
         objectProps: ObjectProp[];
         enumProps: EnumProp[];
+        unionProps: UnionProp[];
     }): SchemaDependencies;
 }

package/dist/core/schema/SchemaDependencyCollector.js

@@ -1,6 +1,6 @@
 export class SchemaDependencyCollector {
     static collect(props) {
-        const { primitiveProps, arrayProps, objectProps, enumProps } = props;
+        const { primitiveProps, arrayProps, objectProps, enumProps, unionProps } = props;
         const schemaDepsSet = new Set();
         for (const prop of objectProps) {
             schemaDepsSet.add(prop.type);
@@ -10,6 +10,11 @@ export class SchemaDependencyCollector {
                 schemaDepsSet.add(prop.type);
             }
         }
+        for (const prop of unionProps) {
+            for (const variant of prop.variantTypes) {
+                schemaDepsSet.add(variant);
+            }
+        }
         const enumDepsSet = new Set();
         for (const prop of enumProps) {
             if (prop.enumName)

package/dist/core/schema/SchemaPropertyClassifier.d.ts

@@ -2,10 +2,11 @@ import { ArrayProp } from "../../props/array.property.js";
 import { EnumProp } from "../../props/enum.property.js";
 import { ObjectProp } from "../../props/object.property.js";
 import { PrimitiveProp } from "../../props/primitive.property.js";
+import { UnionProp } from "../../props/union.property.js";
 import type { SchemaObject, ReferenceObject } from "../../types/open-api-spec.interface.js";
 import type { FieldConfigs } from "../../types/types.js";
 import type { CodegenContext } from "../CodegenContext.js";
-export type ClassifiedProp = PrimitiveProp | ArrayProp | ObjectProp | EnumProp;
+export type ClassifiedProp = PrimitiveProp | ArrayProp | ObjectProp | EnumProp | UnionProp;
 export declare class SchemaPropertyClassifier {
     static classify(params: {
         key: string;

package/dist/core/schema/SchemaPropertyClassifier.js

@@ -2,11 +2,21 @@ import { ArrayProp } from "../../props/array.property.js";
 import { EnumProp } from "../../props/enum.property.js";
 import { ObjectProp } from "../../props/object.property.js";
 import { PrimitiveProp } from "../../props/primitive.property.js";
+import { UnionProp } from "../../props/union.property.js";
 import { isReferenceObject, isPrimitiveEnumValues } from "../../helpers/helpers.js";
 export class SchemaPropertyClassifier {
     static classify(params) {
         const { key, value, requireds, fieldConfigs, schemaName, context } = params;
         if (isReferenceObject(value) || !value?.type) {
+            if (!isReferenceObject(value) && value.oneOf) {
+                return new UnionProp({
+                    name: key,
+                    oneOf: value.oneOf,
+                    discriminator: value.discriminator,
+                    isRequired: requireds.includes(key),
+                    isNullable: value.nullable,
+                });
+            }
             if (!isReferenceObject(value) && value.additionalProperties) {
                 const fakeStringSchema = { ...value, type: "string" };
                 const config = fieldConfigs.get(key);
@@ -21,7 +31,7 @@ export class SchemaPropertyClassifier {
                     isNullable: value.nullable,
                 });
             }
-            return SchemaPropertyClassifier.classifyObject({ key, value });
+            return SchemaPropertyClassifier.classifyObject({ key, value, requireds });
         }
         const required = requireds.includes(key);
         const items = value.items;
@@ -97,10 +107,10 @@ export class SchemaPropertyClassifier {
         });
     }
     static classifyObject(params) {
-        const { value, key } = params;
+        const { value, key, requireds } = params;
         if ("allOf" in value) {
             const ref = value.allOf?.[0];
-            const isRequired = !!value.nullable;
+            const isRequired = requireds.includes(key);
             const nullable = !!value.nullable;
             if (ref && isReferenceObject(ref)) {
                 return new ObjectProp({ name: key, referenceObject: ref, isRequired, isNullable: nullable });
@@ -108,7 +118,7 @@ export class SchemaPropertyClassifier {
             return null;
         }
         if (isReferenceObject(value)) {
-            return new ObjectProp({ name: key, referenceObject: value });
+            return new ObjectProp({ name: key, referenceObject: value, isRequired: requireds.includes(key) });
         }
         return null;
     }

package/dist/props/object.property.d.ts

@@ -14,5 +14,14 @@ export declare class ObjectProp {
     classBuild(): string;
     interfaceBuild(): string;
     bundleBuild(): string;
+    /**
+     * Field name when this sub-DTO is emitted as optional AND always-instantiated
+     * (`nome? = $state<T>(new T)` — `!required && !nullable`), so the client-side
+     * gate (`validateForm`) must skip it when empty instead of validating its inner
+     * `required` fields as mandatory. `null` for required or nullable sub-DTOs (the
+     * latter defaults to `null` and is already skipped at runtime). Mirrors the `?`
+     * modifier `classBuild` emits, keeping the runtime gate consistent with the type.
+     */
+    optionalGateName(): string | null;
     hydrateBuild(): string;
 }

package/dist/props/object.property.js

@@ -7,7 +7,7 @@ export class ObjectProp {
         const { referenceObject, name, isRequired, isNullable } = params;
         this.name = name;
         this.type = referenceObject.$ref.split("/").at(-1) ?? "";
-        this.required = isRequired ?? true; // tem que ver isso daí
+        this.required = isRequired ?? false;
         this.isNullable = !!isNullable;
     }
     constructorBuild() {
@@ -31,6 +31,17 @@ export class ObjectProp {
         const nullable = this.isNullable ? "?? null" : "";
         return `${this.name}: this.${this.name}?.bundle() ${nullable}`;
     }
+    /**
+     * Field name when this sub-DTO is emitted as optional AND always-instantiated
+     * (`nome? = $state<T>(new T)` — `!required && !nullable`), so the client-side
+     * gate (`validateForm`) must skip it when empty instead of validating its inner
+     * `required` fields as mandatory. `null` for required or nullable sub-DTOs (the
+     * latter defaults to `null` and is already skipped at runtime). Mirrors the `?`
+     * modifier `classBuild` emits, keeping the runtime gate consistent with the type.
+     */
+    optionalGateName() {
+        return !this.required && !this.isNullable ? this.name : null;
+    }
     hydrateBuild() {
         if (this.isNullable) {
             return `if (data.${this.name} !== undefined) {

package/dist/props/union.property.d.ts

@@ -0,0 +1,37 @@
+import type { DiscriminatorObject, ReferenceObject, SchemaObject } from "../types/open-api-spec.interface.js";
+/**
+ * Property whose OpenAPI schema is a `oneOf` — a union of `$ref`ed component
+ * schemas, optionally carrying a `discriminator`. Only `$ref` variants are
+ * supported (inline `oneOf` members aren't promoted today).
+ *
+ * Runtime model is intentionally flat/passthrough: the class field stores the
+ * raw incoming object typed as the union of the variants' `Interface`s — there
+ * is no `new` (you can't instantiate a union) and no `.bundle()` on it
+ * (`bundleStrict`/`bundleInputs` pass plain objects through unchanged). The
+ * elegant discriminated narrowing lives in the schema's `Interface` type alias
+ * (see `DiscriminatedInterfaceRenderer`), not on the live class instance.
+ */
+export declare class UnionProp {
+    name: string;
+    /** Variant component names extracted from each `oneOf` `$ref` (deduped, order-preserving). */
+    readonly variantTypes: string[];
+    readonly discriminator: DiscriminatorObject | undefined;
+    private readonly required;
+    private readonly isNullable;
+    constructor(params: {
+        name: string;
+        oneOf: (SchemaObject | ReferenceObject)[];
+        discriminator?: DiscriminatorObject | undefined;
+        isRequired?: boolean;
+        isNullable?: boolean | undefined;
+    });
+    /** `AInterface | BInterface | ...` — the flat union used for the class field type. */
+    flatUnion(): string;
+    /** True when this union can render as a discriminated `Interface` (needs a mapping). */
+    get hasDiscriminator(): boolean;
+    classBuild(): string;
+    constructorBuild(): string;
+    bundleBuild(): string;
+    interfaceBuild(): string;
+    hydrateBuild(): string;
+}

package/dist/props/union.property.js

@@ -0,0 +1,62 @@
+import { isReferenceObject } from "../helpers/helpers.js";
+/**
+ * Property whose OpenAPI schema is a `oneOf` — a union of `$ref`ed component
+ * schemas, optionally carrying a `discriminator`. Only `$ref` variants are
+ * supported (inline `oneOf` members aren't promoted today).
+ *
+ * Runtime model is intentionally flat/passthrough: the class field stores the
+ * raw incoming object typed as the union of the variants' `Interface`s — there
+ * is no `new` (you can't instantiate a union) and no `.bundle()` on it
+ * (`bundleStrict`/`bundleInputs` pass plain objects through unchanged). The
+ * elegant discriminated narrowing lives in the schema's `Interface` type alias
+ * (see `DiscriminatedInterfaceRenderer`), not on the live class instance.
+ */
+export class UnionProp {
+    name;
+    /** Variant component names extracted from each `oneOf` `$ref` (deduped, order-preserving). */
+    variantTypes;
+    discriminator;
+    required;
+    isNullable;
+    constructor(params) {
+        const { name, oneOf, discriminator, isRequired, isNullable } = params;
+        this.name = name;
+        this.discriminator = discriminator;
+        this.required = isRequired ?? true;
+        this.isNullable = !!isNullable;
+        const refs = oneOf
+            .filter(isReferenceObject)
+            .map((ref) => ref.$ref.split("/").at(-1) ?? "")
+            .filter(Boolean);
+        this.variantTypes = [...new Set(refs)];
+    }
+    /** `AInterface | BInterface | ...` — the flat union used for the class field type. */
+    flatUnion() {
+        return this.variantTypes.map((t) => `${t}Interface`).join(" | ");
+    }
+    /** True when this union can render as a discriminated `Interface` (needs a mapping). */
+    get hasDiscriminator() {
+        return !!this.discriminator?.mapping && Object.keys(this.discriminator.mapping).length > 0;
+    }
+    classBuild() {
+        const req = this.required ? "" : "?";
+        const nullable = this.isNullable ? " | null" : "";
+        // No `new` for a union — `$state<T>()` (no arg) yields `T | undefined`,
+        // populated by the constructor from the incoming data.
+        return `${this.name}${req} = $state<${this.flatUnion()}${nullable}>()`;
+    }
+    constructorBuild() {
+        return `this.${this.name} = params?.data?.${this.name}`;
+    }
+    bundleBuild() {
+        return `${this.name}: this.${this.name}`;
+    }
+    interfaceBuild() {
+        const req = this.required ? "" : "?";
+        const nullable = this.isNullable ? " | null" : "";
+        return `${this.name}${req}: ${this.flatUnion()}${nullable}`;
+    }
+    hydrateBuild() {
+        return `if (data.${this.name} !== undefined) this.${this.name} = data.${this.name}`;
+    }
+}

package/dist/runtime/reflector.svelte.ts

@@ -74,6 +74,7 @@ export class BuildedInput<T> {
   private _value = $state<T>(null as any);
   private serverErrorMessage = $state<string | null>(null);
   private serverErrorValue = $state.raw<T | null>(null);
+  showError = $state(false);
   sanitizer?: Sanitizer;
   required: boolean;
   nullable: boolean;
@@ -180,6 +181,14 @@ export class BuildedInput<T> {
     return this.validator(this.value);
   }
 
+  touch(): void {
+    this.showError = true;
+  }
+
+  untouch(): void {
+    this.showError = false;
+  }
+
   setServerError(message: string) {
     this.serverErrorMessage = message;
     this.serverErrorValue = this.value;
@@ -241,6 +250,11 @@ export function build<T>(params: {
   return new BuildedInput(params);
 }
 
+/**
+ * @deprecated Use `validateForm` — `isFormValid` faz `throw` no primeiro campo
+ * inválido (nunca retorna `false`), ignora o flag `required` e muta o schema
+ * (`delete schema.bundle`). Remoção real fica para o próximo major.
+ */
 export function isFormValid<T>(schema: PartialBuildedInput<T>): boolean {
   delete (schema as { bundle?: unknown }).bundle;
 
@@ -266,6 +280,93 @@ export function isFormValid<T>(schema: PartialBuildedInput<T>): boolean {
   return isValid;
 }
 
+function isNestedDto(v: unknown): v is Record<string, unknown> {
+  return v != null && typeof v === "object" && typeof (v as { bundle?: unknown }).bundle === "function";
+}
+
+function isInputEmpty(input: BuildedInput<unknown>): boolean {
+  return input.value === "" || input.value === null || input.value === undefined;
+}
+
+/**
+ * Visita os `BuildedInput` do schema, recursando em DTO aninhado (campo com
+ * `.bundle()`) e em array de DTOs — simétrico ao `bundleInputs`/`bundle`, que
+ * também recursam. Sem short-circuit: aplica `fn` em cada campo.
+ *
+ * `skipOptionalEmpty`: pula um sub-DTO listado no `_optionalDtos` do pai cujos
+ * campos estão TODOS vazios. O codegen marca os sub-DTOs **opcionais
+ * always-instantiated** (`nome? = $state<T>(new T)`); sem isso o gate validaria
+ * o `required` interno de um bloco opcional em branco e bloquearia o submit.
+ */
+function forEachBuildedInput(
+  schema: Record<string, unknown>,
+  fn: (input: BuildedInput<unknown>) => void,
+  skipOptionalEmpty: boolean,
+): void {
+  const optional = skipOptionalEmpty
+    ? (schema as { _optionalDtos?: Set<string> })._optionalDtos
+    : undefined;
+  for (const [key, v] of Object.entries(schema)) {
+    if (isBuildedInput(v)) {
+      fn(v);
+    } else if (Array.isArray(v)) {
+      for (const item of v) {
+        if (isBuildedInput(item)) fn(item);
+        else if (isNestedDto(item)) forEachBuildedInput(item, fn, skipOptionalEmpty);
+      }
+    } else if (isNestedDto(v)) {
+      if (optional?.has(key) && isEmptyDto(v)) continue;
+      forEachBuildedInput(v, fn, skipOptionalEmpty);
+    }
+  }
+}
+
+function isEmptyDto(dto: Record<string, unknown>): boolean {
+  let empty = true;
+  forEachBuildedInput(
+    dto,
+    (input) => {
+      if (!isInputEmpty(input)) empty = false;
+    },
+    false,
+  );
+  return empty;
+}
+
+/**
+ * Gate de validação client-side honesto: percorre os campos `BuildedInput` do
+ * schema (recursando em DTO aninhado e array de DTOs), chama `touch()` em cada um
+ * (acende o erro por-campo no submit) e retorna `true` só se todos forem válidos.
+ * Campo vazio é inválido quando `required`; caso contrário consulta o `validator`.
+ * Sub-DTO opcional inteiramente vazio é pulado (não bloqueia bloco em branco).
+ * Sem `throw`, sem `toast`, sem mutar o schema. Tocar todos é de propósito (não
+ * `.every`, que short-circuita e deixaria campos sem acender).
+ */
+export function validateForm(schema: Record<string, unknown>): boolean {
+  let valid = true;
+  forEachBuildedInput(
+    schema,
+    (input) => {
+      input.touch();
+      const fieldValid = isInputEmpty(input) ? !input.required : input.validate() === null;
+      if (!fieldValid) valid = false;
+    },
+    true,
+  );
+  return valid;
+}
+
+/**
+ * Simétrico do `validateForm`: apaga `showError` de todos os campos do schema
+ * (incl. aninhados, sem pular opcional). Usar no `onClose`/reset de modal que
+ * reusa a instância do form. (Quando o endpoint faz `reset()` → `new Dto()`,
+ * `showError` já volta `false` de graça; o untouch só é necessário pra instância
+ * reutilizada.)
+ */
+export function untouchForm(schema: Record<string, unknown>): void {
+  forEachBuildedInput(schema, (input) => input.untouch(), false);
+}
+
 export function genericArrayBundler(data: string[]): string[];
 export function genericArrayBundler<T extends { bundle: () => BundleResult<T> }>(
   data: T[],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-reflector",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "Reflects types from openAPI schemas",
   "type": "module",
   "main": "./dist/index.js",