svelte-reflector 2.1.8 → 2.5.0

package/dist/core/Reflector.js

@@ -33,7 +33,8 @@ export class Reflector {
             context: this.context,
             config: this.config,
         });
-        this.registry = new SchemaRegistry({ components, fieldConfigs, context: this.context });
+        const requestBodyNames = new Set(this.modules.flatMap((m) => m.requestBodyNames));
+        this.registry = new SchemaRegistry({ components, fieldConfigs, context: this.context, requestBodyNames });
         this.schemas = this.registry.schemas;
         this.propertiesNames = this.registry.propertiesNames;
     }

package/dist/core/api/ApiClassBuilder.js

@@ -53,17 +53,17 @@ export class ApiClassBuilder {
             this.imports.addReflectorImport("genericArrayBundler");
         }
         const className = capitalizeFirstLetter(method.name);
-        const classCode = `
-      export class ${className} {
-        ${stateProps.join(";")}
-        ${processedParams.paramAttributes.map((a) => `${a};`).join("\n        ")}
-
-        ${callMethod}
-
-        reset() {
-          ${resetLines.join(";")}
-        }
-      }
+        const classCode = `
+      export class ${className} {
+        ${stateProps.join(";")}
+        ${processedParams.paramAttributes.map((a) => `${a};`).join("\n        ")}
+
+        ${callMethod}
+
+        reset() {
+          ${resetLines.join(";")}
+        }
+      }
     `;
         const paramCode = processedParams.paramClasses.join("\n");
         return { paramCode, classCode, schemaEntries };
@@ -91,7 +91,7 @@ export class ApiClassBuilder {
         const { attributeType, bodyType } = method.request;
         const lines = [];
         if (attributeType === "form" && bodyType) {
-            lines.push(`this.form = new ${bodyType}()`);
+            lines.push(`this.form.reset()`);
         }
         else if (attributeType === "list") {
             lines.push("this.data = []");

package/dist/core/config/ReflectorConfig.d.ts

@@ -6,8 +6,10 @@
 export interface ReflectorConfig {
     /** Alias that resolves to the generated reflector folder (e.g. `$reflector`). */
     reflectorAlias: string;
-    /** Full import path to the validators/sanitizers module. */
+    /** Full import path to the validators module (exports `validateInputs`). */
     validatorsImport: string;
+    /** Full import path to the sanitizers module (input masks; exports `sanitizers`). */
+    sanitizersImport: string;
     /** Module path for the environment flag (e.g. `$env/static/public`). */
     environmentImport: string;
     /** Name of the exported environment flag — values other than `DEV` are treated as prod. */

package/dist/core/config/ReflectorConfig.js

@@ -1,6 +1,7 @@
 export const DEFAULT_REFLECTOR_CONFIG = {
     reflectorAlias: "$reflector",
     validatorsImport: "$lib/sanitizers/validateFormats",
+    sanitizersImport: "$lib/sanitizers/input-sanitizers",
     environmentImport: "$env/static/public",
     environmentFlag: "PUBLIC_ENVIRONMENT",
     toastImport: "$lib/utils/toast.svelte",

package/dist/core/generators/ApiCallStrategy.d.ts

@@ -2,6 +2,7 @@ import type { CallMethodInput, CallStrategy } from "./CallStrategy.js";
 export declare class ApiCallStrategy implements CallStrategy {
     listStateAccess(_method: CallMethodInput): string;
     buildSignature(method: CallMethodInput): string;
+    buildLegacyWrapper(method: CallMethodInput): string;
     entityStateAccess(_method: CallMethodInput): string;
     formStateAccess(_method: CallMethodInput): string;
     private buildParamsType;

package/dist/core/generators/ApiCallStrategy.js

@@ -5,7 +5,16 @@ export class ApiCallStrategy {
     }
     buildSignature(method) {
         const paramsType = this.buildParamsType(method);
-        return `async call(params?: ${paramsType})`;
+        return `async run(params?: ${paramsType})`;
+    }
+    buildLegacyWrapper(method) {
+        const paramsType = this.buildParamsType(method);
+        return `
+      /** @deprecated use \`run()\` — returns a discriminated ApiResult */
+      async call(params?: ${paramsType}) {
+        const res = await this.run(params);
+        return res.ok ? res.data : undefined;
+      }`;
     }
     entityStateAccess(_method) {
         return "this.data";

package/dist/core/generators/CallMethodGenerator.js

@@ -8,6 +8,7 @@ export class CallMethodGenerator {
         const { inside, outside } = this.buildApiCall(method, strategy);
         const methodReturn = this.buildMethodReturn(method, strategy);
         const signature = strategy.buildSignature(method);
+        const legacyWrapper = strategy.buildLegacyWrapper(method);
         return `
       ${description}
       ${signature} {
@@ -25,7 +26,7 @@ export class CallMethodGenerator {
           ${inside}
           await onSuccess?.(response);
 
-          return ${methodReturn};
+          return { ok: true, data: ${methodReturn} };
         } catch (e) {
           let parsedError: ApiErrorResponse;
           try {
@@ -33,11 +34,14 @@ export class CallMethodGenerator {
           } catch {
             parsedError = { error: 'unknown', message: (e as Error).message ?? String(e) };
           }
-          return await onError?.(parsedError);
+          await onError?.(parsedError);
+          return { ok: false, error: parsedError };
         } finally {
           this.loading = false;
         }
       }
+
+      ${legacyWrapper}
     `;
     }
     buildProps(method) {

package/dist/core/generators/CallStrategy.d.ts

@@ -17,8 +17,13 @@ export interface CallMethodInput {
  * (per-endpoint Api class vs Module `_methodName` protected method).
  */
 export interface CallStrategy {
-    /** Full method signature incl. params — e.g. `async call(params?: ...)` or `protected async _foo(params?: ...)` */
+    /** Full signature of the discriminated `run` method incl. params —
+     *  e.g. `async run(params?: ...)` (api) or `protected async _fooRun(params?: ...)` (module). */
     buildSignature(method: CallMethodInput): string;
+    /** Full `@deprecated` legacy method that delegates to the `run` variant and
+     *  reproduces the old `Res | null | undefined` return shape. Emitted verbatim
+     *  after the run method. Api → `call()`; module → `_foo()`. */
+    buildLegacyWrapper(method: CallMethodInput): string;
     /** State field holding list results — e.g. `this.list` / `this.listControllers` (module) or `this.data` (api).
      *  Takes `method` so the module strategy can suffix the field when two list
      *  operations collide in the same controller. */

package/dist/core/generators/ModuleCallStrategy.d.ts

@@ -2,6 +2,7 @@ import type { CallMethodInput, CallStrategy } from "./CallStrategy.js";
 export declare class ModuleCallStrategy implements CallStrategy {
     listStateAccess(method: CallMethodInput): string;
     buildSignature(method: CallMethodInput): string;
+    buildLegacyWrapper(method: CallMethodInput): string;
     entityStateAccess(method: CallMethodInput): string;
     formStateAccess(method: CallMethodInput): string;
     private buildParamsType;

package/dist/core/generators/ModuleCallStrategy.js

@@ -6,7 +6,16 @@ export class ModuleCallStrategy {
     }
     buildSignature(method) {
         const paramsType = this.buildParamsType(method);
-        return `protected async _${method.name}(params?: ${paramsType})`;
+        return `protected async _${method.name}Run(params?: ${paramsType})`;
+    }
+    buildLegacyWrapper(method) {
+        const paramsType = this.buildParamsType(method);
+        return `
+      /** @deprecated use \`_${method.name}Run()\` — returns a discriminated ApiResult */
+      protected async _${method.name}(params?: ${paramsType}) {
+        const res = await this._${method.name}Run(params);
+        return res.ok ? res.data : undefined;
+      }`;
     }
     entityStateAccess(method) {
         const rType = method.analyzers.request.responseType ?? "";

package/dist/core/module/Module.d.ts

@@ -12,6 +12,8 @@ export declare class Module {
     readonly methods: Method[];
     /** Schema class names directly used by this module (for per-module schema generation) */
     readonly schemaClassNames: string[];
+    /** Nomes-raiz dos request body DTOs deste módulo (para serialização schema-aware) */
+    readonly requestBodyNames: string[];
     private readonly imports;
     private readonly methodProcessor;
     private readonly classBuilder;

package/dist/core/module/Module.js

@@ -14,6 +14,8 @@ export class Module {
     methods;
     /** Schema class names directly used by this module (for per-module schema generation) */
     schemaClassNames;
+    /** Nomes-raiz dos request body DTOs deste módulo (para serialização schema-aware) */
+    requestBodyNames;
     imports;
     methodProcessor;
     classBuilder;
@@ -55,6 +57,7 @@ export class Module {
         // Extract schema class names for per-module schema generation
         this.schemaClassNames = Array.from(processedMethods.entries)
             .filter((e) => e !== "type any" && !e.startsWith("type "));
+        this.requestBodyNames = Array.from(processedMethods.requestBodyNames);
         // Monta o resultado final
         const allBuilded = this.buildModuleData(processedMethods, processedParams);
         const moduleConstructor = this.constructorBuilder.build(allBuilded.form);
@@ -97,7 +100,7 @@ export class Module {
       `);
             moduleInit.add("this.clearForms()");
             moduleClear.add(`
-        protected clearForms() { this.forms = this.buildForms(true) }
+        protected clearForms() { ${form.map((f) => `this.forms.${f.name}.reset()`).join("; ")} }
       `);
         }
         return {

package/dist/core/module/ModuleMethodProcessor.d.ts

@@ -6,6 +6,8 @@ import type { Form } from "./ModuleConstructorBuilder.js";
 export interface ProcessedMethods {
     buildedMethods: string[];
     entries: Set<string>;
+    /** Nomes-raiz dos request body DTOs (para serialização schema-aware via bundleInputs) */
+    requestBodyNames: Set<string>;
     form: Form[];
     formSet: Set<string>;
     methodsAttributes: string[];

package/dist/core/module/ModuleMethodProcessor.js

@@ -13,6 +13,7 @@ export class ModuleMethodProcessor {
         const form = [];
         const formSet = new Set();
         const entries = new Set();
+        const requestBodyNames = new Set();
         const buildedMethods = [];
         const queryMap = new Map();
         const headerMap = new Map();
@@ -54,6 +55,7 @@ export class ModuleMethodProcessor {
             }
             if (bodyType) {
                 entries.add(bodyType);
+                requestBodyNames.add(bodyType);
             }
             if (responseType && responseType !== "response" && !isPrimitiveResponse) {
                 entries.add(`type ${responseType}Interface`);
@@ -64,6 +66,7 @@ export class ModuleMethodProcessor {
             form,
             formSet,
             entries,
+            requestBodyNames,
             buildedMethods,
             methodsAttributes: Array.from(methodsAttributes),
             methodsInit: Array.from(methodsInit),

package/dist/core/module/ModuleSchemaFileBuilder.js

@@ -16,11 +16,25 @@ export class ModuleSchemaFileBuilder {
                 customTypeDeps.add(t);
             }
         }
+        // só presença importa (o import é o objeto `sanitizers` inteiro), não os refs
+        const usesSanitizers = schemas.some((s) => s.sanitizerDeps.length > 0);
         const treatedSchemas = schemas.map((s) => `${s.interface};\n${s.schema};`);
+        // import preciso: response usa bundleStrict, request usa bundleInputs, array-root
+        // não usa nenhum. Evita import morto (svelte-check/eslint do consumer reclama).
+        const needsStrict = schemas.some((s) => s.bundleHelper === "strict");
+        const needsInputs = schemas.some((s) => s.bundleHelper === "inputs");
+        const reflectorImports = ["build", "BuildedInput"];
+        if (needsStrict)
+            reflectorImports.push("bundleStrict");
+        if (needsInputs)
+            reflectorImports.push("bundleInputs");
         const imports = [
-            `import { build, BuildedInput, bundleStrict } from "${config.reflectorAlias}/reflector.svelte";`,
+            `import { ${reflectorImports.join(", ")} } from "${config.reflectorAlias}/reflector.svelte";`,
             `import { validateInputs } from "${config.validatorsImport}";`,
         ];
+        if (usesSanitizers) {
+            imports.push(`import { sanitizers } from "${config.sanitizersImport}";`);
+        }
         if (enumDeps.size > 0) {
             imports.push(`import type { ${[...enumDeps].join(", ")} } from "${config.reflectorAlias}/enums"`);
         }

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

@@ -17,8 +17,16 @@ export declare class Schema {
     readonly enumDeps: string[];
     /** Custom type names used by this schema (from fieldConfigs) */
     readonly customTypeDeps: string[];
+    /** Sanitizer refs used by this schema (from fieldConfigs) — gates the `sanitizers` import */
+    readonly sanitizerDeps: string[];
     schema: string;
     interface: string;
+    /**
+     * Qual helper de runtime o `bundle()` renderizado referencia — controla os imports
+     * do schema file. `'strict'` = response (bundleStrict), `'inputs'` = request
+     * (bundleInputs), `null` = array-root (mapeia `item.bundle()`, não usa nenhum).
+     */
+    bundleHelper: "strict" | "inputs" | null;
     /**
      * Builds a Schema for an array-root component (top-level `type: array`), e.g.
      * a promoted `data: array` response envelope. Renders a wrapper class whose
@@ -48,4 +56,12 @@ export declare class Schema {
         fieldConfigs: FieldConfigs;
         context: CodegenContext;
     });
+    /**
+     * Re-renderiza este schema como request DTO: `bundle()` passa a serializar a partir
+     * das instâncias `BuildedInput` via `bundleInputs` (em vez de `bundleStrict` sobre os
+     * `.value` extraídos). Idempotente. Schemas array-root não têm props → no-op
+     * (continuam mapeando `item.bundle()`). Chamado pelo `SchemaRegistry` para o fecho
+     * transitivo dos request bodies.
+     */
+    setRequestMode(): void;
 }

package/dist/core/schema/Schema.js

@@ -19,8 +19,16 @@ export class Schema {
     enumDeps;
     /** Custom type names used by this schema (from fieldConfigs) */
     customTypeDeps;
+    /** Sanitizer refs used by this schema (from fieldConfigs) — gates the `sanitizers` import */
+    sanitizerDeps;
     schema;
     interface;
+    /**
+     * Qual helper de runtime o `bundle()` renderizado referencia — controla os imports
+     * do schema file. `'strict'` = response (bundleStrict), `'inputs'` = request
+     * (bundleInputs), `null` = array-root (mapeia `item.bundle()`, não usa nenhum).
+     */
+    bundleHelper;
     /**
      * Builds a Schema for an array-root component (top-level `type: array`), e.g.
      * a promoted `data: array` response envelope. Renders a wrapper class whose
@@ -40,6 +48,7 @@ export class Schema {
         schema.schemaDeps = element.kind === "ref" ? [element.type] : [];
         schema.enumDeps = element.kind === "enum" ? [element.type] : [];
         schema.customTypeDeps = [];
+        schema.sanitizerDeps = [];
         const rendered = ArraySchemaRenderer.render({
             name,
             elementType: element.type,
@@ -47,6 +56,7 @@ export class Schema {
         });
         schema.interface = rendered.interface;
         schema.schema = rendered.schema;
+        schema.bundleHelper = null;
         return schema;
     }
     /**
@@ -110,6 +120,7 @@ export class Schema {
         this.schemaDeps = deps.schemaDeps;
         this.enumDeps = deps.enumDeps;
         this.customTypeDeps = deps.customTypeDeps;
+        this.sanitizerDeps = deps.sanitizerDeps;
         const rendered = SchemaClassRenderer.render({
             name: this.name,
             primitiveProps: this.primitiveProps,
@@ -119,5 +130,27 @@ export class Schema {
         });
         this.interface = rendered.interface;
         this.schema = rendered.schema;
+        this.bundleHelper = rendered.bundleHelper;
+    }
+    /**
+     * Re-renderiza este schema como request DTO: `bundle()` passa a serializar a partir
+     * das instâncias `BuildedInput` via `bundleInputs` (em vez de `bundleStrict` sobre os
+     * `.value` extraídos). Idempotente. Schemas array-root não têm props → no-op
+     * (continuam mapeando `item.bundle()`). Chamado pelo `SchemaRegistry` para o fecho
+     * transitivo dos request bodies.
+     */
+    setRequestMode() {
+        if (this.bundleHelper !== "strict")
+            return;
+        const rendered = SchemaClassRenderer.render({
+            name: this.name,
+            primitiveProps: this.primitiveProps,
+            arrayProps: this.arrayProps,
+            objectProps: this.objectProps,
+            enumProps: this.enumProps,
+            mode: "request",
+        });
+        this.schema = rendered.schema;
+        this.bundleHelper = rendered.bundleHelper;
     }
 }

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

@@ -9,8 +9,10 @@ export declare class SchemaClassRenderer {
         arrayProps: ArrayProp[];
         objectProps: ObjectProp[];
         enumProps: EnumProp[];
+        mode?: "request" | "response";
     }): {
         interface: string;
         schema: string;
+        bundleHelper: "strict" | "inputs";
     };
 }

package/dist/core/schema/SchemaClassRenderer.js

@@ -2,6 +2,7 @@ import { ReflectorInterface } from "./ReflectorInterface.js";
 export class SchemaClassRenderer {
     static render(params) {
         const { name, primitiveProps, arrayProps, objectProps, enumProps } = params;
+        const mode = params.mode ?? "response";
         const reflectorInterface = new ReflectorInterface({
             name,
             arrayProps,
@@ -34,9 +35,32 @@ export class SchemaClassRenderer {
             keys.push(prop.classBuild());
             bundleParams.push(prop.bundleBuild());
         });
-        const constructorCode = `constructor(params?: { data?: ${name}Interface | undefined, empty?: boolean }) { 
+        const constructorCode = `constructor(params?: { data?: ${name}Interface | undefined, empty?: boolean }) {
         ${constructorThis.join(";\n")}
       }`;
+        const hydrateLines = [];
+        primitiveProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
+        arrayProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
+        objectProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
+        enumProps.forEach((p) => hydrateLines.push(p.hydrateBuild()));
+        const hydrateCode = `
+      hydrate(data: Partial<${name}Interface>): void {
+        ${hydrateLines.join(";\n")}
+      }
+
+      reset(): void {
+        this.hydrate(new ${name}({ empty: true }).bundle() as Partial<${name}Interface>);
+      }
+    `;
+        // 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).
+        const bundleHelper = mode === "request" ? "inputs" : "strict";
+        const bundleBody = mode === "request"
+            ? `return bundleInputs({ ${[...primitiveProps, ...arrayProps, ...objectProps, ...enumProps]
+                .map((p) => `${p.name}: this.${p.name}`)
+                .join(",")} })`
+            : `return bundleStrict({ ${bundleParams.join(",")} })`;
         const schema = `
     export class ${name} {
       ${keys.join(";")}
@@ -45,10 +69,12 @@ export class SchemaClassRenderer {
 
       ${staticMethod}
 
+      ${hydrateCode}
+
       bundle(){
-        return bundleStrict({ ${bundleParams.join(",")} })
+        ${bundleBody}
       }
     };`;
-        return { interface: reflectorInterface.builded, schema };
+        return { interface: reflectorInterface.builded, schema, bundleHelper };
     }
 }

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

@@ -6,6 +6,7 @@ export interface SchemaDependencies {
     schemaDeps: string[];
     enumDeps: string[];
     customTypeDeps: string[];
+    sanitizerDeps: string[];
 }
 export declare class SchemaDependencyCollector {
     static collect(props: {

package/dist/core/schema/SchemaDependencyCollector.js

@@ -20,14 +20,18 @@ export class SchemaDependencyCollector {
                 enumDepsSet.add(prop.type);
         }
         const customTypeDepsSet = new Set();
+        const sanitizerDepsSet = new Set();
         for (const prop of primitiveProps) {
             if (prop.customType)
                 customTypeDepsSet.add(prop.customType);
+            if (prop.sanitizer)
+                sanitizerDepsSet.add(prop.sanitizer);
         }
         return {
             schemaDeps: [...schemaDepsSet],
             enumDeps: [...enumDepsSet],
             customTypeDeps: [...customTypeDepsSet],
+            sanitizerDeps: [...sanitizerDepsSet],
         };
     }
 }

package/dist/core/schema/SchemaPropertyClassifier.js

@@ -15,6 +15,7 @@ export class SchemaPropertyClassifier {
                     schemaObject: fakeStringSchema,
                     required: requireds.includes(key),
                     validator: config?.validator,
+                    sanitizer: config?.sanitizer,
                     customType: config?.type,
                     isParam: undefined,
                     isNullable: value.nullable,
@@ -53,6 +54,7 @@ export class SchemaPropertyClassifier {
         }
         const config = fieldConfigs.get(key);
         const validator = config?.validator;
+        const sanitizer = config?.sanitizer;
         const customType = config?.type;
         const type = value.type;
         if (type === "object") {
@@ -63,6 +65,7 @@ export class SchemaPropertyClassifier {
                     schemaObject: fakeStringSchema,
                     required,
                     validator,
+                    sanitizer,
                     customType,
                     isParam: undefined,
                     isNullable: value.nullable,
@@ -87,6 +90,7 @@ export class SchemaPropertyClassifier {
             schemaObject: value,
             required,
             validator,
+            sanitizer,
             customType,
             isParam: undefined,
             isNullable: value.nullable,

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

@@ -10,6 +10,8 @@ export declare class SchemaRegistry {
         components: ComponentsObject;
         fieldConfigs: FieldConfigs;
         context: CodegenContext;
+        /** Nomes-raiz dos request body DTOs — eles e seu fecho transitivo serializam via bundleInputs */
+        requestBodyNames?: Set<string>;
     });
     /** Resolve transitive schema dependencies from a list of schema class names */
     resolveTransitiveDeps(names: string[]): Schema[];

package/dist/core/schema/SchemaRegistry.js

@@ -5,7 +5,7 @@ export class SchemaRegistry {
     propertiesNames = new Set();
     schemaMap = new Map();
     constructor(params) {
-        const { components, fieldConfigs, context } = params;
+        const { components, fieldConfigs, context, requestBodyNames } = params;
         const componentSchemas = components.schemas;
         if (!componentSchemas)
             return;
@@ -32,6 +32,15 @@ export class SchemaRegistry {
         for (const schema of this.schemas) {
             this.schemaMap.set(schema.name, schema);
         }
+        // Request body DTOs (e seu fecho transitivo de deps) serializam via bundleInputs:
+        // o bundle() lê os flags do BuildedInput em vez de só o .value extraído. Transitivo
+        // porque um DTO aninhado (ex.: createBody.role → UserRole) também é serializado no
+        // request — marcar só a raiz deixaria o nested em bundleStrict (bug nested).
+        if (requestBodyNames && requestBodyNames.size > 0) {
+            for (const schema of this.resolveTransitiveDeps([...requestBodyNames])) {
+                schema.setRequestMode();
+            }
+        }
         console.log(`${this.schemas.length} schemas generated successfully.`);
     }
     /** Resolve transitive schema dependencies from a list of schema class names */

package/dist/helpers/generate-doc.helper.d.ts

@@ -1,6 +1,7 @@
 interface LooseFieldConfig {
     fields: string[];
     validator?: string;
+    sanitizer?: string;
     type?: string;
 }
 export declare function parseFieldConfigsFromConfig(code: string): LooseFieldConfig[];

package/dist/helpers/generate-doc.helper.js

@@ -96,12 +96,17 @@ export function parseFieldConfigsFromConfig(code) {
         // extrai validator (referência sem aspas, ex: validateInputs.email)
         const validatorMatch = block.match(/validator\s*:\s*([A-Za-z0-9_$.]+)/);
         const validator = validatorMatch?.[1]?.trim();
+        // extrai sanitizer (referência sem aspas, ex: sanitizers.phone)
+        const sanitizerMatch = block.match(/sanitizer\s*:\s*([A-Za-z0-9_$.]+)/);
+        const sanitizer = sanitizerMatch?.[1]?.trim();
         // extrai type (string literal com aspas, ex: 'IconName')
         const typeMatch = block.match(/type\s*:\s*['"`]([^'"`]+)['"`]/);
         const type = typeMatch?.[1]?.trim();
         const config = { fields };
         if (validator)
             config.validator = validator;
+        if (sanitizer)
+            config.sanitizer = sanitizer;
         if (type)
             config.type = type;
         results.push(config);

package/dist/loaders/ConfigLoader.js

@@ -22,6 +22,8 @@ export class ConfigLoader {
                 const config = {};
                 if (rel.validator)
                     config.validator = rel.validator;
+                if (rel.sanitizer)
+                    config.sanitizer = rel.sanitizer;
                 if (rel.type)
                     config.type = rel.type;
                 fieldConfigs.set(field, config);

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

@@ -28,5 +28,6 @@ export declare class ArrayProp {
     bundleBuild(): string;
     queryBundleBuild(): string;
     queryBuild(): string;
+    hydrateBuild(): string;
     staticBuild(): string;
 }

package/dist/props/array.property.js

@@ -96,6 +96,12 @@ export class ArrayProp {
             .join(", ")}]`;
         return `readonly ${this.name} = new EnumQueryBuilder<${this.type}>({ key: '${this.name}', defaultValues: ${literal} })`;
     }
+    hydrateBuild() {
+        if (this.isSchemaRef) {
+            return `if (data.${this.name} !== undefined) this.${this.name} = (data.${this.name} ?? []).map((i) => new ${this.type}({ data: i as never }))`;
+        }
+        return `if (data.${this.name} !== undefined) this.${this.name} = data.${this.name} ?? []`;
+    }
     staticBuild() {
         const result = this._isPrimitiveType ? "obj" : `new ${this.type}({ data: obj })`;
         const aType = this._isPrimitiveType ? this.type : `${this.type}Interface`;

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

@@ -19,4 +19,5 @@ export declare class EnumProp {
     interfaceBuild(): string;
     queryBuild(): string;
     bundleBuild(): string;
+    hydrateBuild(): string;
 }

package/dist/props/enum.property.js

@@ -39,4 +39,8 @@ export class EnumProp {
     bundleBuild() {
         return `${this.name}: this.${this.name}?.value`;
     }
+    hydrateBuild() {
+        const opt = this.isRequired ? "" : "?";
+        return `if (data.${this.name} !== undefined) this.${this.name}${opt}.hydrate(data.${this.name} as never)`;
+    }
 }

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

@@ -14,4 +14,5 @@ export declare class ObjectProp {
     classBuild(): string;
     interfaceBuild(): string;
     bundleBuild(): string;
+    hydrateBuild(): string;
 }

package/dist/props/object.property.js

@@ -31,4 +31,17 @@ export class ObjectProp {
         const nullable = this.isNullable ? "?? null" : "";
         return `${this.name}: this.${this.name}?.bundle() ${nullable}`;
     }
+    hydrateBuild() {
+        if (this.isNullable) {
+            return `if (data.${this.name} !== undefined) {
+        if (data.${this.name} === null) this.${this.name} = null;
+        else if (this.${this.name}) this.${this.name}.hydrate(data.${this.name} as never);
+        else this.${this.name} = new ${this.type}({ data: data.${this.name} as never });
+      }`;
+        }
+        return `if (data.${this.name} !== undefined) {
+      if (this.${this.name}) this.${this.name}.hydrate(data.${this.name} as never);
+      else this.${this.name} = new ${this.type}({ data: data.${this.name} as never });
+    }`;
+    }
 }

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

@@ -10,6 +10,7 @@ export declare class PrimitiveProp {
     private readonly isNullable;
     readonly rawType: ReflectorParamType;
     readonly customType: string | undefined;
+    readonly sanitizer: string | undefined;
     private readonly buildedConst;
     private readonly example;
     private readonly fallbackExample;
@@ -23,6 +24,7 @@ export declare class PrimitiveProp {
         schemaObject: SchemaObject;
         required: boolean;
         validator: string | undefined;
+        sanitizer?: string | undefined;
         customType?: string | undefined;
         isParam: boolean | undefined;
         isNullable?: boolean | undefined;
@@ -38,5 +40,6 @@ export declare class PrimitiveProp {
     queryBuild(): string;
     updateQueryBuild(): string;
     bundleBuild(): string;
+    hydrateBuild(): string;
 }
 export {};

package/dist/props/primitive.property.js

@@ -9,6 +9,7 @@ export class PrimitiveProp {
     isNullable;
     rawType;
     customType;
+    sanitizer;
     buildedConst;
     example;
     fallbackExample;
@@ -22,7 +23,7 @@ export class PrimitiveProp {
         return this.isNullable || !this.required;
     }
     constructor(params) {
-        const { name, schemaObject, required, validator, customType, isParam, isNullable } = params;
+        const { name, schemaObject, required, validator, sanitizer, customType, isParam, isNullable } = params;
         const { type: rawType } = schemaObject;
         this.isNullable = !!isNullable;
         const normalizedRawType = rawType === "integer" ? "number" : rawType;
@@ -38,10 +39,13 @@ export class PrimitiveProp {
         this.isSpecial = treated.isSpecial;
         this.rawType = type ?? "any";
         this.customType = customType;
+        // sanitizer só vale para campo string — gate aqui garante que emissão e
+        // rastreio de dependência (import) concordam.
+        this.sanitizer = type === "string" ? sanitizer : undefined;
         this.type = `BuildedInput<${buildedType}>`;
         this.required = required;
         this.isParam = !!isParam;
-        this.buildedConst = this.buildConst({ example, name: this.name, required, type, validator, emptyExample: this.example });
+        this.buildedConst = this.buildConst({ example, name: this.name, required, type, validator, sanitizer: this.sanitizer, emptyExample: this.example });
     }
     getEmptyExample(params) {
         const { schemaObject, type, name } = params;
@@ -83,7 +87,7 @@ export class PrimitiveProp {
         };
     }
     buildConst(params) {
-        const { name, required, type, validator } = params;
+        const { name, required, type, validator, sanitizer } = params;
         const getValidator = (type) => {
             if (type === "string") {
                 return "emptyString";
@@ -114,10 +118,22 @@ export class PrimitiveProp {
         else if (this.customType) {
             typeParam = `<${this.effectiveType}>`;
         }
-        const nullableParam = this.isNullable ? "nullable: true, " : "";
-        const maxParam = this.max !== undefined ? `max: ${this.max}, ` : "";
+        // Monta as props num array e junta com vírgula: com dois opcionais
+        // (validator + sanitizer) o controle manual de vírgula quebrava.
+        const props = [
+            `key: ${keyExpr}`,
+            `placeholder: ${this.example}`,
+            `example: ${buildedExample}`,
+            `required: ${required}`,
+            this.isNullable ? "nullable: true" : "",
+            this.max !== undefined ? `max: ${this.max}` : "",
+            buildedValidator(),
+            sanitizer ? `sanitizer: ${sanitizer}` : "",
+        ]
+            .filter(Boolean)
+            .join(", ");
         return `
-      build${typeParam}({ key: ${keyExpr}, placeholder: ${this.example}, example: ${buildedExample}, required: ${required}, ${nullableParam}${maxParam}${buildedValidator()}})
+      build${typeParam}({ ${props} })
     `;
     }
     thisDot() {
@@ -154,4 +170,7 @@ export class PrimitiveProp {
     bundleBuild() {
         return `${this.name}: ${this.thisDot()}${this.name}?.value`;
     }
+    hydrateBuild() {
+        return `if (data.${this.name} !== undefined) ${this.thisDot()}${this.name}.hydrate(data.${this.name} as never)`;
+    }
 }

package/dist/runtime/reflector.svelte.ts

@@ -3,12 +3,18 @@ import toast from "$lib/utils/toast.svelte";
 import { goto } from "$app/navigation";
 import { page } from "$app/state";
 import { browser } from "$app/environment";
+import { untrack } from "svelte";
 import { SvelteURL } from "svelte/reactivity";
 
 type ValidatorResult = string | null;
 type ValidatorFn<T> = (v: T) => ValidatorResult;
 type BundleResult<T> = T extends { bundle: () => infer R } ? R : T;
 
+export type Sanitizer = {
+  parse: (display: string) => string; // texto exibido -> valor canônico
+  format: (value: string) => string; // valor canônico -> texto exibido (máscara)
+};
+
 export type ApiCallParams<TResponse, TPaths = void, TQuery = void> = {
   behavior?: Behavior<TResponse, ApiErrorResponse>;
 } & (TPaths extends void ? object : { paths?: TPaths }) &
@@ -30,9 +36,18 @@ export type SvelteEvent = {
   currentTarget: EventTarget & SeiLa;
 };
 
+export interface ValidationErrorItem {
+  field: string;
+  code: string;
+  message: string;
+  received?: string;
+}
+
 export interface ApiErrorResponse {
   error: string;
   message: string;
+  statusCode?: number;
+  errors?: ValidationErrorItem[];
 }
 
 export class Behavior<TSuccess = unknown, TError = unknown> {
@@ -40,9 +55,26 @@ export class Behavior<TSuccess = unknown, TError = unknown> {
   onSuccess?: (v: TSuccess) => Promise<void> | void;
 }
 
+/**
+ * Discriminated result of a generated `run()` call. `ok` is the single
+ * discriminator — never branch on `data` being nullish to detect success.
+ * `data` is the raw response class instance (with `.bundle()`) for endpoints
+ * with a body, and `null` for void endpoints.
+ */
+export type ApiResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: ApiErrorResponse };
+
 export class BuildedInput<T> {
-  value = $state<T>(null as any);
   display = $state<T>(null as any);
+  // Backing store for `value` — only used WITHOUT a sanitizer, where `value`
+  // and `display` are two independent states (legacy behavior). With a
+  // sanitizer, `display` is the single writable source and `value` derives
+  // from it via the getter, so `_value` is left untouched.
+  private _value = $state<T>(null as any);
+  private serverErrorMessage = $state<string | null>(null);
+  private serverErrorValue = $state.raw<T | null>(null);
+  sanitizer?: Sanitizer;
   required: boolean;
   nullable: boolean;
   placeholder: T;
@@ -58,13 +90,10 @@ export class BuildedInput<T> {
     placeholder: T;
     max?: number;
     validator?: ValidatorFn<T>;
+    sanitizer?: Sanitizer;
   }) {
-    const { example, required, nullable, key, validator, placeholder, max } = params;
+    const { example, required, nullable, key, validator, placeholder, max, sanitizer } = params;
 
-    const initial = key === undefined ? example : key;
-
-    this.value = initial;
-    this.display = initial;
     this.required = required;
     this.nullable = nullable ?? false;
     this.placeholder = placeholder;
@@ -76,12 +105,95 @@ export class BuildedInput<T> {
     if (validator) {
       this.validator = validator;
     }
+
+    if (sanitizer) {
+      this.sanitizer = sanitizer;
+    }
+
+    const initial = key === undefined ? example : key;
+
+    if (this.sanitizer) {
+      this.value = initial as T; // setter formata display a partir do valor canônico
+    } else {
+      this._value = initial; // comportamento atual: dois states independentes
+      this.display = initial;
+    }
+  }
+
+  get value(): T {
+    if (!this.sanitizer) return this._value;
+    const parsed = this.sanitizer.parse((this.display ?? "") as unknown as string);
+    if (this.nullable && parsed === "") return null as unknown as T;
+    return parsed as unknown as T;
+  }
+
+  set value(v: T) {
+    if (!this.sanitizer) {
+      // Antes só escrevia `_value`, deixando `display` stale → input de texto
+      // (`bind:value={data.display}`) renderizava vazio quando o consumidor setava
+      // `.value` e esquecia `.display`. Agora mantém os dois em sincronia. `_value`
+      // segue sendo a fonte de leitura do getter, então não quebra quem mantém
+      // value≠display via sanitizer ou mask manual (que seta `display` DEPOIS).
+      this._value = v;
+      this.display = v;
+      return;
+    }
+    if (v === null || v === undefined) {
+      this.display = "" as unknown as T;
+      return;
+    }
+    this.display = this.sanitizer.format(String(v)) as unknown as T;
+  }
+
+  /**
+   * Reaplica a máscara: parse(display) -> format. Usado na hidratação / oninput
+   * pelo componente. No-op sem sanitizer. Reassina `display`, então o caret vai
+   * pro fim — isso é responsabilidade do componente, não do reflector.
+   */
+  reformat(): void {
+    if (!this.sanitizer) return;
+    const parsed = this.sanitizer.parse((this.display ?? "") as unknown as string);
+    this.display = this.sanitizer.format(parsed) as unknown as T;
+  }
+
+  /**
+   * Hidrata in-place: seta valor canônico + display formatado, sanitizer-aware,
+   * e limpa server error. Envolto em `untrack` pra poder ser chamado de dentro
+   * de um `$effect` que lê `data` sem criar loop (a leitura de
+   * `display`/`sanitizer` não vira dependência). Substitui o
+   * `hydrateForm`/`clearFormInPlace` que os consumidores escreviam na mão.
+   */
+  hydrate(v: T): void {
+    untrack(() => {
+      if (this.sanitizer) {
+        this.value = v; // setter já formata display a partir do canônico
+      } else {
+        this._value = v;
+        this.display = v;
+      }
+      this.clearServerError();
+    });
   }
 
   validate(): ValidatorResult {
     if (!this.validator) return null;
     return this.validator(this.value);
   }
+
+  setServerError(message: string) {
+    this.serverErrorMessage = message;
+    this.serverErrorValue = this.value;
+  }
+
+  clearServerError() {
+    this.serverErrorMessage = null;
+    this.serverErrorValue = null;
+  }
+
+  get serverError(): string | null {
+    if (this.serverErrorMessage === null) return null;
+    return this.value === this.serverErrorValue ? this.serverErrorMessage : null;
+  }
 }
 
 export class EnumQueryBuilder<T> {
@@ -89,8 +201,8 @@ export class EnumQueryBuilder<T> {
   private readonly defaultValues: T[] = [];
 
   values = $derived(
-    page.url.searchParams.has(this.key)
-      ? (page.url.searchParams.getAll(this.key) as T[])
+    (pendingUrl ?? page.url).searchParams.has(this.key)
+      ? ((pendingUrl ?? page.url).searchParams.getAll(this.key) as T[])
       : this.defaultValues,
   );
   selected = $state<T | null>(null);
@@ -124,6 +236,7 @@ export function build<T>(params: {
   nullable?: boolean;
   max?: number;
   validator?: ValidatorFn<T>;
+  sanitizer?: Sanitizer;
 }): BuildedInput<T> {
   return new BuildedInput(params);
 }
@@ -165,19 +278,45 @@ export function genericArrayBundler<T extends { bundle: () => BundleResult<T> }>
   return (data as T[]).map((item) => item.bundle());
 }
 
+/**
+ * Acumulador de mutações de query param. N chamadas no mesmo tick mutam a MESMA
+ * `SvelteURL` pendente e coalescem num único `goto` agendado por microtask —
+ * evita clobber (cada `goto` partir da URL antiga) e faz read-after-write
+ * honesto (os getters leem de `pendingUrl ?? page.url`). `$state.raw`: a troca
+ * de referência null↔URL dá a reatividade grossa; a `SvelteURL` já é reativa
+ * nos próprios `searchParams`, então um `$state` profundo proxiaria um objeto
+ * que já é reativo.
+ */
+let pendingUrl = $state.raw<SvelteURL | null>(null);
+
+function stageParamMutation(mutate: (params: URLSearchParams) => void) {
+  if (!browser) return;
+  if (!pendingUrl) {
+    pendingUrl = new SvelteURL(page.url);
+    queueMicrotask(flushPendingUrl);
+  }
+  mutate(pendingUrl.searchParams);
+}
+
+function flushPendingUrl() {
+  const url = pendingUrl;
+  pendingUrl = null;
+  if (url) goto(url, { replaceState: true, keepFocus: true });
+}
+
 /**
  * Atualiza um query param na URL.
  * - `""` (string vazia) → remove o param.
  * - qualquer outro valor → `searchParams.set(key, String(event))`.
  */
 export function changeParam({ event, key }: QueryContract) {
-  const url = new SvelteURL(page.url);
-  if (event === "") {
-    url.searchParams.delete(key);
-  } else {
-    url.searchParams.set(key, String(event));
-  }
-  goto(url, { replaceState: true, keepFocus: true });
+  stageParamMutation((params) => {
+    if (event === "") {
+      params.delete(key);
+    } else {
+      params.set(key, String(event));
+    }
+  });
 }
 
 type StringOrNumber = string | number;
@@ -200,11 +339,21 @@ export class QueryBuilder {
         : String(params.defaultValue);
   }
 
-  get value(): string | null {
-    const fromUrl = page.url.searchParams.get(this.key);
+  /** Snapshot read-only do query param (a URL é a fonte). Escrita só via `.update()`. */
+  get current(): string | null {
+    const fromUrl = (pendingUrl ?? page.url).searchParams.get(this.key);
     return fromUrl !== null ? fromUrl : this.defaultValue;
   }
 
+  /**
+   * @deprecated Use `.current`. `.value` colide de nome com `BuildedInput.value`
+   * (que é gravável) — semântica oposta, fonte de confusão. Será removido num major
+   * futuro; até lá delega pra `.current`.
+   */
+  get value(): string | null {
+    return this.current;
+  }
+
   /**
    * Aplica o valor recebido ao query param.
    * - `null` / `undefined` → no-op (não chama `goto`).
@@ -224,35 +373,31 @@ export class QueryBuilder {
  * - outros valores → `set(key, String(value))`.
  */
 export function setQueryGroup(group: QueryWithArrayType[]) {
-  if (!browser) return;
-
-  const url = new SvelteURL(page.url);
-
-  for (const p of group) {
-    const { key, value } = p;
-
-    if (Array.isArray(value)) {
-      url.searchParams.delete(key);
-      value.forEach((v) => url.searchParams.append(key, String(v)));
-      continue;
+  stageParamMutation((params) => {
+    for (const p of group) {
+      const { key, value } = p;
+
+      if (Array.isArray(value)) {
+        params.delete(key);
+        value.forEach((v) => params.append(key, String(v)));
+        continue;
+      }
+
+      if (value === "") {
+        params.delete(key);
+        continue;
+      }
+
+      params.set(key, String(value));
     }
-
-    if (value === "") {
-      url.searchParams.delete(key);
-      continue;
-    }
-
-    url.searchParams.set(key, String(value));
-  }
-
-  goto(url, { replaceState: true, keepFocus: false });
+  });
 }
 
 export function changeArrayParam({ values, key }: { values: string[]; key: string }) {
-  const url = new SvelteURL(page.url);
-  url.searchParams.delete(key);
-  values.forEach((value) => url.searchParams.append(key, value));
-  goto(url, { replaceState: true, keepFocus: true });
+  stageParamMutation((params) => {
+    params.delete(key);
+    values.forEach((value) => params.append(key, value));
+  });
 }
 
 export function bundleStrict<T extends Record<string, unknown>>(
@@ -261,3 +406,71 @@ export function bundleStrict<T extends Record<string, unknown>>(
 export function bundleStrict(payload: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(Object.entries(payload).filter(([, v]) => v !== undefined));
 }
+
+function isBuildedInput(v: unknown): v is BuildedInput<unknown> {
+  return v != null && typeof v === "object" && (v as { kind?: unknown }).kind === "builded";
+}
+
+/**
+ * Serialização schema-aware de request: recebe as instâncias `BuildedInput` (não o
+ * `.value` já extraído), então enxerga os flags (`required`/`nullable`) que vivem na
+ * instância. Corrige o 400 silencioso do `bundleStrict` cego: campo `nullable` apagado
+ * pra `''` virava `""` no payload (estourava parse de ISO date no back). Aqui `nullable`
+ * com `''` vira `null` de propósito.
+ *
+ * Não faz gate client-side de `required` — consistente com o padrão do projeto
+ * (`bundle()` só serializa; validação é do backend, surface via toast). Quem quiser
+ * gate síncrono usa `isFormValid` antes do `bundle`.
+ *
+ * Trata cada entry: `undefined` → omite; `BuildedInput` → value (com coerção nullable);
+ * array → `genericArrayBundler`; DTO aninhado (`.bundle()`) → recursa; plain → passthrough.
+ *
+ * O overload tipado espelha o `bundleStrict`: strip do wrapper `BuildedInput<V> → V`,
+ * array → `BundleResult`, DTO aninhado → retorno do seu `bundle`, e dropa as keys
+ * puramente `undefined`. Sem ele o request `bundle()` regredia pra `Record<string,unknown>`
+ * e estourava svelte-check em todo consumidor que lê campo tipado do payload.
+ */
+type BundledValue<V> =
+  V extends BuildedInput<infer U>
+    ? U
+    : V extends readonly (infer E)[]
+      ? BundleResult<E>[]
+      : V extends { bundle: () => infer R }
+        ? R
+        : V;
+
+export function bundleInputs<T extends Record<string, unknown>>(
+  inputs: T,
+): {
+  [K in keyof T as Exclude<BundledValue<T[K]>, undefined> extends never
+    ? never
+    : K]: Exclude<BundledValue<T[K]>, undefined>;
+};
+export function bundleInputs(inputs: Record<string, unknown>): Record<string, unknown>;
+export function bundleInputs(inputs: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(inputs)) {
+    if (v === undefined) continue; // opcional nunca construído → omite
+
+    if (isBuildedInput(v)) {
+      let val = v.value as unknown;
+      if (v.nullable && val === "") val = null; // mata o ''→"" que estoura ISO no back
+      if (val === undefined) continue; // omite undefined; NÃO omite null (nullable manda null de propósito)
+      out[key] = val;
+      continue;
+    }
+
+    if (Array.isArray(v)) {
+      out[key] = genericArrayBundler(v);
+      continue;
+    }
+
+    if (v && typeof (v as { bundle?: unknown }).bundle === "function") {
+      out[key] = (v as { bundle: () => unknown }).bundle(); // DTO aninhado → recursa
+      continue;
+    }
+
+    out[key] = v; // plain (v !== undefined já garantido)
+  }
+  return out;
+}

package/dist/types/types.d.ts

@@ -17,6 +17,7 @@ export type Info = {
 export type Example = string | boolean | number;
 export interface FieldConfig {
     validator?: string;
+    sanitizer?: string;
     type?: string;
 }
 export type FieldConfigs = Map<string, FieldConfig>;

package/package.json

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