svelte-reflector 1.3.11 → 2.1.0

package/README.md

@@ -1,395 +1,477 @@
-# Svelte Reflector
-
-**Turn your OpenAPI into a first-class Svelte 5 DX.**
-
-Svelte Reflector is a **developer-experience-first code generator** that converts OpenAPI specs into fully typed, reactive Svelte 5 modules — ready for production, forms included.
-
-[![npm version](https://img.shields.io/npm/v/svelte-reflector.svg)](https://www.npmjs.com/package/svelte-reflector)
-[![npm downloads](https://img.shields.io/npm/dm/svelte-reflector.svg)](https://www.npmjs.com/package/svelte-reflector)
-[![npm total downloads](https://img.shields.io/npm/dt/svelte-reflector.svg)](https://www.npmjs.com/package/svelte-reflector)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
-[![Svelte](https://img.shields.io/badge/Svelte-5+-orange.svg)](https://svelte.dev/)
-
-## Features
-
-- **Automatic Type Generation** - Generates TypeScript interfaces and classes from OpenAPI schemas
-- **Svelte 5 Runes Integration** - Uses `$state` and `$derived` for reactive state management
-- **Abstract Modules** - Generated modules are abstract classes, ready to be extended with custom logic
-- **Per-Module Schemas** - Each module gets its own schema file with only the types it needs (tree-shaking friendly)
-- **Form Handling** - Auto-generates form schemas with `BuildedInput<T>` wrappers and validation support
-- **Type-Safe API Calls** - Full TypeScript support for all API operations
-- **Query Parameter Sync** - `QueryBuilder` and `EnumQueryBuilder` keep state synced with URL searchParams
-- **Enum Support** - Auto-generates enum types and array enum query builders
-- **OpenAPI/Swagger Compatible** - Works with any backend that exposes OpenAPI specs
-- **Development Mode** - Smart regeneration based on environment
-- **Validation Ready** - Built-in support for custom field validators
-- **Vite Plugin** - Can be used as a Vite plugin for automatic generation on build
-
-## Installation
-
-```bash
-npm install svelte-reflector
-# or
-yarn add svelte-reflector
-# or
-pnpm add svelte-reflector
-```
-
-> **Note:** `prettier` >= 3.0.0 is a required peer dependency. Make sure it's installed in your project.
-
-## Quick Start
-
-### 1. Configure Environment Variables
-
-Create a `.env` file in your project root:
-
-```env
-# Required - Your backend URL
-BACKEND_URL=https://api.example.com/
-# or
-PUBLIC_BACKEND=https://api.example.com/
-
-# Optional - Environment (defaults to PROD)
-ENVIRONMENT=DEV
-# or
-VITE_ENVIRONMENT=DEV
-```
-
-### 2. Create Reflector Config (Optional)
-
-Create a `src/reflector.config.ts` to define custom validators:
-
-```typescript
-export const validators = [
-  {
-    fields: ["email", "userEmail"],
-    validator: "validateEmail",
-  },
-  {
-    fields: ["phone", "mobile"],
-    validator: "validatePhone",
-  },
-];
-```
-
-Validators are resolved from `$lib/sanitizers/validateFormats` — you need to implement and export them in your project.
-
-### 3. Configure API Import Path (Optional)
-
-Create a `reflector.json` in your project root to customize the API import path:
-
-```json
-{
-  "api": "$lib/api"
-}
-```
-
-Defaults to `$lib/api` if not specified. This is the module that generated modules will import for making HTTP requests.
-
-### 4. Run the Generator
-
-```bash
-# Manual generation
-npx reflect
-
-# Or programmatically as a Vite plugin
-import { reflector } from "svelte-reflector";
-await reflector(true); // true = force generation
-```
-
-### 5. Use Generated Modules
-
-Generated modules are **abstract classes**. Extend them to add custom logic or simply to instantiate:
-
-```typescript
-import { UserModule } from "$reflector/controllers/user/user.module.svelte";
-import type { User } from "$reflector/controllers/user/user.schema.svelte";
-
-// Extend the abstract module
-class UserService extends UserModule {}
-
-const userService = new UserService();
-
-// Access reactive state
-console.log(userService.loading); // $state<boolean>
-console.log(userService.list);    // $state<User[]>
-
-// Call API methods
-await userService.listAll({
-  behavior: {
-    onSuccess: (response) => console.log(response),
-    onError: (error) => console.error(error),
-  },
-});
-
-// Work with forms
-const userForm = userService.forms.createUser;
-userForm.name.value = "John Doe";
-userForm.email.value = "john@example.com";
-
-// Submit form
-await userService.createUser();
-```
-
-## Generated Structure
-
-```
-src/reflector/
-├── controllers/
-│   └── user/
-│       ├── user.module.svelte.ts      # Abstract API module with methods
-│       └── user.schema.svelte.ts      # Schemas & types used by this module
-├── reflector.svelte.ts                # Core utilities (build, isFormValid, QueryBuilder, etc.)
-├── fields.ts                          # Field name constants
-├── enums.ts                           # Enum type definitions
-├── mocked-params.svelte.ts            # Mocked path parameters ($state)
-└── backup.json                        # Cached OpenAPI spec
-```
-
-Each module gets its own schema file (`*.schema.svelte.ts`) containing only the schemas it uses, with transitive dependencies automatically resolved.
-
-## Generated Module API
-
-Each generated module is an **abstract class** that provides:
-
-### State Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `loading` | `$state<boolean>` | Request loading state |
-| `list` | `$state<T[]>` | List results (for list endpoints) |
-| `forms` | `$state<Record<string, T>>` | Form instances |
-| `querys` | `Querys` | Query parameter state (QueryBuilder instances) |
-| `headers` | `Headers` | Header state |
-| `paths` | `Paths` | Path parameter state |
-
-### Methods
-
-```typescript
-// List all items (GET with page parameter)
-async listAll(params?: { behavior?: Behavior }): Promise<T[]>
-
-// Get single entity (GET without page parameter)
-async get(params?: { behavior?: Behavior }): Promise<T>
-
-// Create/Update (POST/PUT/PATCH)
-async create(params?: { behavior?: Behavior }): Promise<T>
-async update(params?: { behavior?: Behavior }): Promise<T>
-
-// Delete (DELETE)
-async delete(params?: { behavior?: Behavior }): Promise<void>
-
-// Reset all state (protected)
-protected reset(): void
-
-// Clear forms (protected)
-protected clearForms(): void
-```
-
-> `reset()` and `clearForms()` are `protected` — override them in your subclass if you need custom reset behavior.
-
-### QueryBuilder
-
-Query parameters are wrapped in `QueryBuilder` instances that sync with URL searchParams:
-
-```typescript
-// Single value query parameter
-const querys = module.querys;
-querys.status.update("active"); // Updates URL searchParam and internal state
-
-// Array enum query parameter
-const enumQuery = module.querys.roles; // EnumQueryBuilder<RoleType>
-enumQuery.selected = "admin";
-enumQuery.add();      // Adds to URL searchParams
-enumQuery.remove(0);  // Removes from URL searchParams
-enumQuery.values;     // $derived from URL - always in sync
-```
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `BACKEND_URL` | Yes* | Backend API URL |
-| `PUBLIC_BACKEND` | Yes* | Alternative to BACKEND_URL |
-| `ENVIRONMENT` | No | DEV/PROD (defaults to PROD) |
-| `VITE_ENVIRONMENT` | No | Vite-specific env var |
-| `NODE_ENV` | No | Node environment |
-
-\* At least one of `BACKEND_URL` or `PUBLIC_BACKEND` is required.
-
-### Behavior Pattern
-
-All API methods accept a `Behavior` object for callbacks:
-
-```typescript
-class Behavior<TSuccess, TError> {
-  onSuccess?: (value: TSuccess) => Promise<void> | void;
-  onError?: (error: TError) => Promise<void> | void;
-}
-
-// Usage
-await userService.createUser({
-  behavior: {
-    onSuccess: (user) => console.log("Created:", user),
-    onError: (err) => console.error("Failed:", err),
-  },
-});
-```
-
-### Form Validation
-
-Forms use `BuildedInput` class with validation:
-
-```typescript
-class BuildedInput<T> {
-  value: T;           // Current value ($state)
-  display: T;         // Display value ($state)
-  required: boolean;  // Is field required
-  placeholder: T;     // Placeholder/example value
-  readonly kind: 'builded';
-  validator?: (v: T) => string | null; // Validation function
-  validate(): string | null; // Run validation
-}
-
-// Check if all form fields are valid
-import { isFormValid } from "$reflector/reflector.svelte";
-
-if (isFormValid(userService.forms.createUser)) {
-  await userService.createUser();
-}
-```
-
-## TypeScript Configuration
-
-Add path aliases to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "paths": {
-      "$reflector/*": ["./src/reflector/*"],
-      "$lib/*": ["./src/lib/*"]
-    }
-  }
-}
-```
-
-For Vite projects, also update `vite.config.ts`:
-
-```typescript
-export default defineConfig({
-  resolve: {
-    alias: {
-      $reflector: path.resolve("./src/reflector"),
-      $lib: path.resolve("./src/lib"),
-    },
-  },
-});
-```
-
-## Workflow
-
-### Development Mode
-
-In `ENVIRONMENT=DEV`:
-- Schemas are **NOT** auto-regenerated on build
-- Use `npx reflect` to manually regenerate
-- Faster builds, manual control
-
-### Production Mode
-
-In `ENVIRONMENT=PROD`:
-- Schemas are auto-regenerated on each build
-- Fresh types from latest OpenAPI spec
-- Fallback to `backup.json` if backend is unavailable
-
-## Advanced Usage
-
-### Extending Abstract Modules
-
-Since modules are abstract, you can add custom logic:
-
-```typescript
-import { UserModule } from "$reflector/controllers/user/user.module.svelte";
-
-class UserService extends UserModule {
-  // Add custom computed state
-  get activeUsers() {
-    return this.list.filter(u => u.active);
-  }
-
-  // Override protected methods for custom behavior
-  protected override clearForms() {
-    super.clearForms();
-    // custom cleanup logic
-  }
-
-  // Add custom methods
-  async fetchAndFilter(status: string) {
-    this.querys.status.update(status);
-    await this.listAll();
-  }
-}
-```
-
-### Manual Schema Access
-
-```typescript
-import { User } from "$reflector/controllers/user/user.schema.svelte";
-
-// Create instance
-const user = new User({ name: "John", email: "john@example.com" });
-
-// Get data bundle
-const data = user.bundle(); // { name: "John", email: "john@example.com" }
-```
-
-### Batch Query Updates
-
-```typescript
-import { setQueryGroup } from "$reflector/reflector.svelte";
-
-// Update multiple query params at once
-setQueryGroup([
-  { key: "page", value: 1 },
-  { key: "status", value: "active" },
-  { key: "roles", value: ["admin", "editor"] }, // Array params supported
-]);
-```
-
-## Troubleshooting
-
-### "BACKEND_URL vazio" Error
-
-Ensure you have set `BACKEND_URL` or `PUBLIC_BACKEND` in your `.env` file.
-
-### Schemas Not Updating
-
-In DEV mode, run `npx reflect` manually. Check that your backend's OpenAPI spec is accessible at `{BACKEND_URL}openapi.json`.
-
-### Type Errors After Generation
-
-1. Restart your TypeScript language server
-2. Check path aliases in `tsconfig.json`
-3. Ensure `$reflector/*` alias is configured
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details.
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## Links
-
-- [npm](https://www.npmjs.com/package/svelte-reflector)
-- [GitHub](https://github.com/aleleppy/reflector)
-- [Svelte](https://svelte.dev/)
-- [OpenAPI Specification](https://swagger.io/specification/)
-
----
-
-Built with by the Pinaculo Digital team.
+# Svelte Reflector
+
+**Turn your OpenAPI into a first-class Svelte 5 DX.**
+
+Svelte Reflector is a **developer-experience-first code generator** that converts OpenAPI specs into fully typed, reactive Svelte 5 modules — ready for production, forms included.
+
+[![npm version](https://img.shields.io/npm/v/svelte-reflector.svg)](https://www.npmjs.com/package/svelte-reflector)
+[![npm downloads](https://img.shields.io/npm/dm/svelte-reflector.svg)](https://www.npmjs.com/package/svelte-reflector)
+[![npm total downloads](https://img.shields.io/npm/dt/svelte-reflector.svg)](https://www.npmjs.com/package/svelte-reflector)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![Svelte](https://img.shields.io/badge/Svelte-5+-orange.svg)](https://svelte.dev/)
+
+## Features
+
+- **Automatic Type Generation** - Generates TypeScript interfaces and classes from OpenAPI schemas
+- **Svelte 5 Runes Integration** - Uses `$state` and `$derived` for reactive state management
+- **Abstract Modules** - Generated modules are abstract classes, ready to be extended with custom logic
+- **Per-Module Schemas** - Each module gets its own schema file with only the types it needs (tree-shaking friendly)
+- **Form Handling** - Auto-generates form schemas with `BuildedInput<T>` wrappers and validation support
+- **Type-Safe API Calls** - Full TypeScript support for all API operations
+- **Query Parameter Sync** - `QueryBuilder` and `EnumQueryBuilder` keep state synced with URL searchParams
+- **Enum Support** - Auto-generates enum types and array enum query builders
+- **OpenAPI/Swagger Compatible** - Works with any backend that exposes OpenAPI specs
+- **Development Mode** - Smart regeneration based on environment
+- **Validation Ready** - Built-in support for custom field validators
+- **Vite Plugin** - Can be used as a Vite plugin for automatic generation on build
+
+## Installation
+
+```bash
+npm install svelte-reflector
+# or
+yarn add svelte-reflector
+# or
+pnpm add svelte-reflector
+```
+
+> **Note:** `prettier` >= 3.0.0 is a required peer dependency. Make sure it's installed in your project.
+
+## Quick Start
+
+### 1. Configure Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+# Required - Your backend URL
+BACKEND_URL=https://api.example.com/
+# or
+PUBLIC_BACKEND=https://api.example.com/
+
+# Optional - Environment (defaults to PROD)
+ENVIRONMENT=DEV
+# or
+VITE_ENVIRONMENT=DEV
+```
+
+### 2. Create Reflector Config (Optional)
+
+Create a `src/reflector.config.ts` to define custom validators:
+
+```typescript
+export const validators = [
+  {
+    fields: ["email", "userEmail"],
+    validator: "validateEmail",
+  },
+  {
+    fields: ["phone", "mobile"],
+    validator: "validatePhone",
+  },
+];
+```
+
+Validators are resolved from `$lib/sanitizers/validateFormats` — you need to implement and export them in your project.
+
+### 3. Configure API Import Path (Optional)
+
+Create a `reflector.json` in your project root to customize the API import path:
+
+```json
+{
+  "api": "$lib/api"
+}
+```
+
+Defaults to `$lib/api` if not specified. This is the module that generated modules will import for making HTTP requests.
+
+### 4. Run the Generator
+
+```bash
+# Manual generation
+npx reflect
+
+# Or programmatically as a Vite plugin
+import { reflector } from "svelte-reflector";
+await reflector(true); // true = force generation
+```
+
+### 5. Use Generated Modules
+
+Generated modules are **abstract classes**. Extend them to add custom logic or simply to instantiate:
+
+```typescript
+import { UserModule } from "$reflector/controllers/user/user.module.svelte";
+import type { User } from "$reflector/controllers/user/user.schema.svelte";
+
+// Extend the abstract module
+class UserService extends UserModule {}
+
+const userService = new UserService();
+
+// Access reactive state
+console.log(userService.loading); // $state<boolean>
+console.log(userService.list);    // $state<User[]>
+
+// Call API methods
+await userService.listAll({
+  behavior: {
+    onSuccess: (response) => console.log(response),
+    onError: (error) => console.error(error),
+  },
+});
+
+// Work with forms
+const userForm = userService.forms.createUser;
+userForm.name.value = "John Doe";
+userForm.email.value = "john@example.com";
+
+// Submit form
+await userService.createUser();
+```
+
+## Generated Structure
+
+```
+src/reflector/
+├── controllers/
+│   └── user/
+│       ├── user.module.svelte.ts      # Abstract API module with methods
+│       └── user.schema.svelte.ts      # Schemas & types used by this module
+├── reflector.svelte.ts                # Core utilities (build, isFormValid, QueryBuilder, etc.)
+├── fields.ts                          # Field name constants
+├── enums.ts                           # Enum type definitions
+├── mocked-params.svelte.ts            # Mocked path parameters ($state)
+└── backup.json                        # Cached OpenAPI spec
+```
+
+Each module gets its own schema file (`*.schema.svelte.ts`) containing only the schemas it uses, with transitive dependencies automatically resolved.
+
+## Generated Module API
+
+Each generated module is an **abstract class** that provides:
+
+### State Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `loading` | `$state<boolean>` | Request loading state |
+| `list` | `$state<T[]>` | List results (for list endpoints) |
+| `forms` | `$state<Record<string, T>>` | Form instances |
+| `querys` | `Querys` | Query parameter state (QueryBuilder instances) |
+| `headers` | `Headers` | Header state |
+| `paths` | `Paths` | Path parameter state |
+
+### Methods
+
+```typescript
+// List all items (GET with page parameter)
+async listAll(params?: { behavior?: Behavior }): Promise<T[]>
+
+// Get single entity (GET without page parameter)
+async get(params?: { behavior?: Behavior }): Promise<T>
+
+// Create/Update (POST/PUT/PATCH)
+async create(params?: { behavior?: Behavior }): Promise<T>
+async update(params?: { behavior?: Behavior }): Promise<T>
+
+// Delete (DELETE)
+async delete(params?: { behavior?: Behavior }): Promise<void>
+
+// Reset all state (protected)
+protected reset(): void
+
+// Clear forms (protected)
+protected clearForms(): void
+```
+
+> `reset()` and `clearForms()` are `protected` — override them in your subclass if you need custom reset behavior.
+
+### QueryBuilder
+
+Query parameters are wrapped in `QueryBuilder` / `EnumQueryBuilder` instances
+that read directly from `page.url.searchParams`. There is no local cached
+state — every read goes through the URL, so multiple instances with the same
+key are always coherent.
+
+```typescript
+// Single value query parameter
+const querys = module.querys;
+
+querys.status.value;          // string | null — read-only getter, always
+                              // reflects the current URL
+querys.status.update("active"); // pushes ?status=active via goto()
+
+// Array enum query parameter
+const enumQuery = module.querys.roles; // EnumQueryBuilder<RoleType>
+enumQuery.selected = "admin";
+enumQuery.add();      // appends to URL searchParams
+enumQuery.remove(0);  // removes from URL searchParams
+enumQuery.values;     // $derived — always in sync with URL
+```
+
+#### Defaults
+
+`default` declared in the OpenAPI schema is propagated to the builder
+constructor automatically:
+
+```yaml
+parameters:
+  - name: limit
+    in: query
+    schema: { type: integer, default: 10 }
+  - name: tags
+    in: query
+    schema:
+      type: array
+      items: { type: string, enum: [hot, new, sale] }
+      default: [hot]
+```
+
+generates:
+
+```typescript
+class Querys {
+  readonly limit = new QueryBuilder({ key: 'limit', defaultValue: 10 });
+  readonly tags = new EnumQueryBuilder<'hot' | 'new' | 'sale'>({
+    key: 'tags',
+    defaultValues: ['hot'],
+  });
+}
+```
+
+When the URL has the param, the URL value wins. When the URL has no param,
+the default is returned. The URL stays clean until the user interacts.
+
+#### Migrating from 1.x
+
+`value` is no longer a setter. Two replacements:
+
+```typescript
+// 1.x
+querys.page.value = "1";
+querys.page.value ??= "1"; // seed default
+
+// 2.x — declarative default (preferred, set at codegen via OpenAPI)
+new QueryBuilder({ key: "page", defaultValue: "1" });
+
+// 2.x — imperative update (push to URL)
+querys.page.update("1");
+```
+
+The auto-injected `setQueryGroup([...])` constructor on the generated
+`Querys` class was removed — defaults now live on the builder. Import
+`setQueryGroup` manually from `$reflector/reflector.svelte` if you still
+need batch URL writes.
+
+#### Ephemeral pagination (sidebar / widget)
+
+Sometimes a list lives outside the canonical route — a global sidebar, a
+widget, a paginated combobox in a modal — and should NOT mutate the
+current URL. For those cases, every generated `call()` with query params
+accepts an optional `queryOverride`:
+
+```typescript
+const sidebar = new UserService();
+
+// Current URL stays put. Request goes out with ?page=2&limit=10.
+await sidebar.listAll({
+  queryOverride: { page: "2", limit: "10" },
+});
+```
+
+When `queryOverride` is passed, the method skips `this.querys.bundle()`
+entirely and uses the override as `queryData`. Without it, the method
+reads from `QueryBuilder.value` (the URL) as usual — so you can mix and
+match on a per-call basis. Omit a key to drop it from the request; pass
+`null` to send a literal `null`.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BACKEND_URL` | Yes* | Backend API URL |
+| `PUBLIC_BACKEND` | Yes* | Alternative to BACKEND_URL |
+| `ENVIRONMENT` | No | DEV/PROD (defaults to PROD) |
+| `VITE_ENVIRONMENT` | No | Vite-specific env var |
+| `NODE_ENV` | No | Node environment |
+
+\* At least one of `BACKEND_URL` or `PUBLIC_BACKEND` is required.
+
+### Behavior Pattern
+
+All API methods accept a `Behavior` object for callbacks:
+
+```typescript
+class Behavior<TSuccess, TError> {
+  onSuccess?: (value: TSuccess) => Promise<void> | void;
+  onError?: (error: TError) => Promise<void> | void;
+}
+
+// Usage
+await userService.createUser({
+  behavior: {
+    onSuccess: (user) => console.log("Created:", user),
+    onError: (err) => console.error("Failed:", err),
+  },
+});
+```
+
+### Form Validation
+
+Forms use `BuildedInput` class with validation:
+
+```typescript
+class BuildedInput<T> {
+  value: T;           // Current value ($state)
+  display: T;         // Display value ($state)
+  required: boolean;  // Is field required
+  placeholder: T;     // Placeholder/example value
+  readonly kind: 'builded';
+  validator?: (v: T) => string | null; // Validation function
+  validate(): string | null; // Run validation
+}
+
+// Check if all form fields are valid
+import { isFormValid } from "$reflector/reflector.svelte";
+
+if (isFormValid(userService.forms.createUser)) {
+  await userService.createUser();
+}
+```
+
+## TypeScript Configuration
+
+Add path aliases to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "$reflector/*": ["./src/reflector/*"],
+      "$lib/*": ["./src/lib/*"]
+    }
+  }
+}
+```
+
+For Vite projects, also update `vite.config.ts`:
+
+```typescript
+export default defineConfig({
+  resolve: {
+    alias: {
+      $reflector: path.resolve("./src/reflector"),
+      $lib: path.resolve("./src/lib"),
+    },
+  },
+});
+```
+
+## Workflow
+
+### Development Mode
+
+In `ENVIRONMENT=DEV`:
+- Schemas are **NOT** auto-regenerated on build
+- Use `npx reflect` to manually regenerate
+- Faster builds, manual control
+
+### Production Mode
+
+In `ENVIRONMENT=PROD`:
+- Schemas are auto-regenerated on each build
+- Fresh types from latest OpenAPI spec
+- Fallback to `backup.json` if backend is unavailable
+
+## Advanced Usage
+
+### Extending Abstract Modules
+
+Since modules are abstract, you can add custom logic:
+
+```typescript
+import { UserModule } from "$reflector/controllers/user/user.module.svelte";
+
+class UserService extends UserModule {
+  // Add custom computed state
+  get activeUsers() {
+    return this.list.filter(u => u.active);
+  }
+
+  // Override protected methods for custom behavior
+  protected override clearForms() {
+    super.clearForms();
+    // custom cleanup logic
+  }
+
+  // Add custom methods
+  async fetchAndFilter(status: string) {
+    this.querys.status.update(status);
+    await this.listAll();
+  }
+}
+```
+
+### Manual Schema Access
+
+```typescript
+import { User } from "$reflector/controllers/user/user.schema.svelte";
+
+// Create instance
+const user = new User({ name: "John", email: "john@example.com" });
+
+// Get data bundle
+const data = user.bundle(); // { name: "John", email: "john@example.com" }
+```
+
+### Batch Query Updates
+
+```typescript
+import { setQueryGroup } from "$reflector/reflector.svelte";
+
+// Update multiple query params at once
+setQueryGroup([
+  { key: "page", value: 1 },
+  { key: "status", value: "active" },
+  { key: "roles", value: ["admin", "editor"] }, // Array params supported
+]);
+```
+
+## Troubleshooting
+
+### "BACKEND_URL vazio" Error
+
+Ensure you have set `BACKEND_URL` or `PUBLIC_BACKEND` in your `.env` file.
+
+### Schemas Not Updating
+
+In DEV mode, run `npx reflect` manually. Check that your backend's OpenAPI spec is accessible at `{BACKEND_URL}openapi.json`.
+
+### Type Errors After Generation
+
+1. Restart your TypeScript language server
+2. Check path aliases in `tsconfig.json`
+3. Ensure `$reflector/*` alias is configured
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- [npm](https://www.npmjs.com/package/svelte-reflector)
+- [GitHub](https://github.com/aleleppy/reflector)
+- [Svelte](https://svelte.dev/)
+- [OpenAPI Specification](https://swagger.io/specification/)
+
+---
+
+Built with by the Pinaculo Digital team.

package/dist/core/generators/CallMethodGenerator.js

@@ -44,7 +44,7 @@ export class CallMethodGenerator {
         const { querys, paths, cookies } = method.analyzers.props;
         const lines = [];
         if (querys.length > 0) {
-            lines.push(`const { ${this.joinNames(querys)} } = this.querys.bundle()`);
+            lines.push(`const { ${this.joinNames(querys)} } = params?.queryOverride ?? this.querys.bundle()`);
         }
         if (paths.length > 0) {
             lines.push(`const { ${this.joinNames(paths)} } = params?.paths ?? this.paths`);

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

@@ -6,4 +6,6 @@ export declare class ModuleCallStrategy implements CallStrategy {
     formStateAccess(method: CallMethodInput): string;
     private buildParamsType;
     private buildPathsBlock;
+    private buildQueryOverrideBlock;
+    private queryOverrideType;
 }

package/dist/core/generators/ModuleCallStrategy.js

@@ -17,27 +17,43 @@ export class ModuleCallStrategy {
     buildParamsType(method) {
         const behaviorType = `Behavior<${method.responseTypeInterface}, ApiErrorResponse>`;
         const pathsBlock = this.buildPathsBlock(method);
-        if (pathsBlock) {
-            return `{
-        behavior?: ${behaviorType};${pathsBlock}
-      }`;
-        }
+        const queryBlock = this.buildQueryOverrideBlock(method);
+        const blocks = [`behavior?: ${behaviorType};`, pathsBlock, queryBlock]
+            .filter((b) => !!b)
+            .join("\n");
         return `{
-      behavior?: ${behaviorType};
+      ${blocks}
     }`;
     }
     buildPathsBlock(method) {
         const paths = method.analyzers.props.paths;
         if (paths.length === 0)
             return undefined;
-        return `
-    paths?: {
+        return `paths?: {
       ${paths
             .map((p) => {
             const type = p.rawType ?? p.type;
             return `${p.name}: ${type}`;
         })
             .join("\n")}
-    }`;
+    };`;
+    }
+    buildQueryOverrideBlock(method) {
+        const querys = method.analyzers.props.querys;
+        if (querys.length === 0)
+            return undefined;
+        const fields = querys
+            .map((q) => `${q.name}?: ${this.queryOverrideType(q)}`)
+            .join("\n");
+        return `queryOverride?: {
+      ${fields}
+    };`;
+    }
+    queryOverrideType(q) {
+        if ("isEnum" in q && q.isEnum)
+            return `${q.type}[]`;
+        if (!("rawType" in q) && !("enumName" in q))
+            return "string[]";
+        return "string | null";
     }
 }

package/dist/core/module/ModuleClassBuilder.js

@@ -26,8 +26,6 @@ export class ModuleClassBuilder {
       `;
         }
         else if (name === "Querys") {
-            this.imports.addSetQueryGroupImport();
-            const queryGroupValues = [];
             props.forEach((prop) => {
                 if ("rawType" in prop) {
                     attributes.push(prop.queryBuild());
@@ -35,13 +33,9 @@ export class ModuleClassBuilder {
                         this.imports.addReflectorImport("EnumQueryBuilder");
                         this.imports.addEnumImport(String(prop.type));
                         bundle.push(`${prop.name}: this.${prop.name}?.values`);
-                        // Array de enum usa valor padrão []
-                        queryGroupValues.push(`{ key: '${prop.name}', value: ${prop.queryDefaultValue()} }`);
                     }
                     else {
                         bundle.push(prop.bundleBuild());
-                        // PrimitiveProp usa seu valor padrão
-                        queryGroupValues.push(`{ key: '${prop.name}', value: ${prop.queryDefaultValue()} }`);
                     }
                 }
                 else if ("enumName" in prop) {
@@ -49,7 +43,6 @@ export class ModuleClassBuilder {
                     this.imports.addEnumImport(prop.enumName);
                     attributes.push(prop.queryBuild());
                     bundle.push(prop.bundleBuild());
-                    queryGroupValues.push(`{ key: '${prop.name}', value: ${prop.queryDefaultValue()} }`);
                 }
                 else {
                     // ArrayProp (não-enum)
@@ -57,16 +50,8 @@ export class ModuleClassBuilder {
                     this.imports.addEnumImport(prop.type);
                     bundle.push(prop.queryBundleBuild());
                     this.imports.addReflectorImport("EnumQueryBuilder");
-                    queryGroupValues.push(`{ key: '${prop.name}', value: ${prop.queryDefaultValue()} }`);
                 }
             });
-            const constructorBuild = `
-        constructor() {
-          setQueryGroup([
-            ${queryGroupValues.join(",\n            ")}
-          ]);
-        }
-      `;
             if (bundle.length > 0) {
                 this.imports.addReflectorImport("bundleStrict");
             }
@@ -74,8 +59,6 @@ export class ModuleClassBuilder {
         class ${outputName} {
           ${attributes.join(";")}
 
-          ${constructorBuild}
-
           ${bundle.length > 0 ? `
           bundle() {
             return bundleStrict({

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

@@ -9,7 +9,6 @@ export declare class ModuleImports {
     addImport(importStr: string): void;
     addMockedImport(importStr: string): void;
     addReflectorImport(importStr: string): void;
-    addSetQueryGroupImport(): void;
     addEnumImport(enumName: string): void;
     addPageStateImport(): void;
     getImportsArray(): string[];

package/dist/core/module/ModuleImports.js

@@ -25,9 +25,6 @@ export class ModuleImports {
     addReflectorImport(importStr) {
         this.reflectorImports.add(importStr);
     }
-    addSetQueryGroupImport() {
-        this.reflectorImports.add("setQueryGroup");
-    }
     addEnumImport(enumName) {
         this.enumImports.add(enumName);
     }
@@ -55,16 +52,12 @@ export class ModuleImports {
     typeOnlyImports = new Set(["ApiCallParams"]);
     buildReflectorImportsLine() {
         const imports = this.getReflectorImportsArray();
-        const regularImports = imports.filter(i => i !== "setQueryGroup" && !this.typeOnlyImports.has(i));
-        const typeImports = imports.filter(i => this.typeOnlyImports.has(i));
-        const hasSetQueryGroup = imports.includes("setQueryGroup");
+        const regularImports = imports.filter((i) => !this.typeOnlyImports.has(i));
+        const typeImports = imports.filter((i) => this.typeOnlyImports.has(i));
         let result = `import { ${regularImports.join(", ")}, type ApiErrorResponse`;
         for (const t of typeImports) {
             result += `, type ${t}`;
         }
-        if (hasSetQueryGroup) {
-            result += `, setQueryGroup`;
-        }
         result += ` } from "${this.config.reflectorAlias}/reflector.svelte";`;
         return result;
     }

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

@@ -8,6 +8,7 @@ export declare class ArrayProp {
     private _isPrimitiveType;
     private readonly isNullable;
     private readonly context;
+    private readonly defaultValues;
     get isSchemaRef(): boolean;
     readonly isEnum: boolean;
     constructor(params: {
@@ -28,5 +29,4 @@ export declare class ArrayProp {
     queryBundleBuild(): string;
     queryBuild(): string;
     staticBuild(): string;
-    queryDefaultValue(): string;
 }

package/dist/props/array.property.js

@@ -9,6 +9,7 @@ export class ArrayProp {
     _isPrimitiveType = false;
     isNullable;
     context;
+    defaultValues;
     get isSchemaRef() {
         return !this._isPrimitiveType && !this.isEnum;
     }
@@ -22,6 +23,7 @@ export class ArrayProp {
         this.type = this.getType({ schemaObject, schemaName });
         this.isRequired = required;
         this.isParam = !!isParam;
+        this.defaultValues = Array.isArray(schemaObject.default) ? schemaObject.default : [];
     }
     getType(params) {
         const { schemaObject, schemaName } = params;
@@ -82,10 +84,15 @@ export class ArrayProp {
     }
     queryBuild() {
         if (this.isEnum) {
-            return `readonly ${this.name} = $derived(new EnumQueryBuilder<${this.type}>({ key: '${this.name}' }))`;
+            if (this.defaultValues.length === 0) {
+                return `readonly ${this.name} = new EnumQueryBuilder<${this.type}>({ key: '${this.name}' })`;
+            }
+            const literal = `[${this.defaultValues
+                .map((v) => (typeof v === "string" ? `'${v}'` : String(v)))
+                .join(", ")}]`;
+            return `readonly ${this.name} = new EnumQueryBuilder<${this.type}>({ key: '${this.name}', defaultValues: ${literal} })`;
         }
-        // Para arrays normais (não enum), usamos QueryBuilder padrão
-        return `readonly ${this.name} = $derived(new QueryBuilder({ key: '${this.name}' }))`;
+        return `readonly ${this.name} = new QueryBuilder({ key: '${this.name}' })`;
     }
     staticBuild() {
         const result = this._isPrimitiveType ? "obj" : `new ${this.type}({ data: obj })`;
@@ -96,7 +103,4 @@ export class ArrayProp {
       }
     `;
     }
-    queryDefaultValue() {
-        return "[]";
-    }
 }

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

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

package/dist/props/enum.property.js

@@ -34,12 +34,9 @@ export class EnumProp {
         return `${this.name}${req}: ${this.enumName}`;
     }
     queryBuild() {
-        return `readonly ${this.name} = $derived(new QueryBuilder({ key: '${this.name}' }))`;
+        return `readonly ${this.name} = new QueryBuilder({ key: '${this.name}' })`;
     }
     bundleBuild() {
         return `${this.name}: this.${this.name}?.value`;
     }
-    queryDefaultValue() {
-        return `'${this.example}'`;
-    }
 }

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

@@ -1,7 +1,6 @@
 import type { SchemaObject } from "../types/open-api-spec.interface.js";
 import type { ReflectorParamType } from "../types/types.js";
 type AbstractType = string | boolean | number | undefined;
-type Example = string | boolean | number;
 export declare class PrimitiveProp {
     name: string;
     type: AbstractType;
@@ -14,6 +13,7 @@ export declare class PrimitiveProp {
     private readonly buildedConst;
     private readonly example;
     private readonly fallbackExample;
+    private readonly defaultValue;
     private get effectiveType();
     /** Non-required fields become nullable (| null) instead of optional (?) */
     private get isEffectivelyNullable();
@@ -37,6 +37,5 @@ export declare class PrimitiveProp {
     queryBuild(): string;
     updateQueryBuild(): string;
     bundleBuild(): string;
-    queryDefaultValue(): Example;
 }
 export {};

package/dist/props/primitive.property.js

@@ -12,6 +12,7 @@ export class PrimitiveProp {
     buildedConst;
     example;
     fallbackExample;
+    defaultValue;
     get effectiveType() {
         return this.customType ?? this.rawType;
     }
@@ -28,6 +29,7 @@ export class PrimitiveProp {
         const { emptyExample, example } = this.getExampleAndFallback({ schemaObject, type, name });
         this.example = example;
         this.fallbackExample = emptyExample;
+        this.defaultValue = schemaObject.default;
         const buildedType = customType ?? type;
         const treated = treatPropertyName(name);
         this.name = treated.name;
@@ -132,7 +134,13 @@ export class PrimitiveProp {
         return `readonly ${this.name} = $derived.by(() => '${this.name}' in page.params ? page.params.${this.name} : mockedParams.${this.name}) as string | null;`;
     }
     queryBuild() {
-        return `readonly ${this.name} = $derived(new QueryBuilder({ key: '${this.name}' }))`;
+        if (this.defaultValue === undefined || this.defaultValue === null) {
+            return `readonly ${this.name} = new QueryBuilder({ key: '${this.name}' })`;
+        }
+        const literal = typeof this.defaultValue === "string"
+            ? `'${this.defaultValue}'`
+            : String(this.defaultValue);
+        return `readonly ${this.name} = new QueryBuilder({ key: '${this.name}', defaultValue: ${literal} })`;
     }
     updateQueryBuild() {
         return `${this.name}: (event: SvelteEvent) => changeParam({ key: '${this.name}', event })`;
@@ -140,7 +148,4 @@ export class PrimitiveProp {
     bundleBuild() {
         return `${this.name}: ${this.thisDot()}${this.name}?.value`;
     }
-    queryDefaultValue() {
-        return this.fallbackExample;
-    }
 }

package/dist/runtime/reflector.svelte.ts

@@ -9,9 +9,10 @@ type ValidatorResult = string | null;
 type ValidatorFn<T> = (v: T) => ValidatorResult;
 type BundleResult<T> = T extends { bundle: () => infer R } ? R : T;
 
-export type ApiCallParams<TResponse, TPaths = void> = TPaths extends void
-  ? { behavior?: Behavior<TResponse, ApiErrorResponse> }
-  : { behavior?: Behavior<TResponse, ApiErrorResponse>; paths?: TPaths };
+export type ApiCallParams<TResponse, TPaths = void, TQuery = void> = {
+  behavior?: Behavior<TResponse, ApiErrorResponse>;
+} & (TPaths extends void ? object : { paths?: TPaths }) &
+  (TQuery extends void ? object : { queryOverride?: TQuery });
 
 type PartialBuildedInput<T> = {
   [K in Exclude<keyof T, "bundle">]?: BuildedInput<T[K]>;
@@ -79,13 +80,18 @@ export class BuildedInput<T> {
 
 export class EnumQueryBuilder<T> {
   readonly key: string = "";
-  values = $derived(page.url.searchParams.getAll(this.key)) as T[];
-  selected = $state<T | null>(null);
+  private readonly defaultValues: T[] = [];
 
-  constructor(params: { key: string }) {
-    const { key } = params;
+  values = $derived(
+    page.url.searchParams.has(this.key)
+      ? (page.url.searchParams.getAll(this.key) as T[])
+      : this.defaultValues,
+  );
+  selected = $state<T | null>(null);
 
-    this.key = key;
+  constructor(params: { key: string; defaultValues?: T[] }) {
+    this.key = params.key;
+    this.defaultValues = params.defaultValues ?? [];
   }
 
   add = () => {
@@ -167,22 +173,26 @@ type QueryWithArrayType = {
 };
 
 export class QueryBuilder {
-  readonly key: string = "";
-  value = $state<string | null>(null);
+  readonly key: string;
   readonly kind = "query";
+  private readonly defaultValue: string | null;
+
+  constructor(params: { key: string; defaultValue?: string | number | null }) {
+    this.key = params.key;
+    this.defaultValue =
+      params.defaultValue === undefined || params.defaultValue === null
+        ? null
+        : String(params.defaultValue);
+  }
 
-  constructor(params: { key: string }) {
-    const { key } = params;
-    this.key = key;
-
-    const urlValue = page.url.searchParams.get(key);
-    this.value = urlValue !== null ? urlValue : null;
+  get value(): string | null {
+    const fromUrl = page.url.searchParams.get(this.key);
+    return fromUrl !== null ? fromUrl : this.defaultValue;
   }
 
   update(event: string | number | null) {
     if (event === null || event === undefined) return;
-    this.value = String(event);
-    return changeParam({ key: this.key, event: this.value });
+    return changeParam({ key: this.key, event: String(event) });
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-reflector",
-  "version": "1.3.11",
+  "version": "2.1.0",
   "description": "Reflects zod types from openAPI schemas",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,8 @@
     "build": "tsc && tsc -p tsconfig.runtime.json && node scripts/copy-runtime.mjs",
     "typecheck:runtime": "tsc -p tsconfig.runtime.json",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "patch": "npm run build && npm version patch && npm publish"
   },
   "dependencies": {
     "axios": "^1.12.2",