@helfy/helfy 0.0.8 → 0.0.9

package/README.md

@@ -21,16 +21,20 @@ Components are defined as classes with the `@View` decorator, state is managed v
   - [@for](#for)
   - [@empty](#empty)
 - [State Management](#state-management)
-  - [Creating a Store](#creating-a-store)
-  - [Subscribing with @observe](#subscribing-with-observe)
-  - [Store context](#store-context)
+  - [Architecture layers (Store, Service, UseCase)](#state-management)
+  - [Creating a Store](#creating-a-store-store)
+  - [Infrastructure services](#infrastructure-services-service)
+  - [Business use cases](#business-use-cases-usecase)
+  - [Accessing Store and UseCase from components](#accessing-store-and-usecase-from-components)
+  - [Store context (optional)](#store-context-optional)
 - [Logging (@logger)](#logging-logger)
 - [Context & DI](#context--di)
-  - [Provider (@Context, @provide)](#provider-context-provide)
-  - [Consumer (@ctx)](#consumer-ctx)
+  - [Provider (@Context)](#provider-context)
+  - [Consumer (@useCtx)](#consumer-usectx)
   - [Reactive fields](#reactive-fields)
   - [Optional injection](#optional-injection)
-  - [DI Container](#di-container-constructor-injection)
+  - [DI: props vs dependencies](#di-props-vs-dependencies)
+  - [Global services (@inject)](#global-services-inject)
 - [JSX](#jsx)
   - [Attributes](#attributes)
   - [Events](#events)
@@ -78,7 +82,7 @@ Or in `package.json`:
 
 ### Build setup
 
-The Babel plugin runs the DI scanner before transformation (no pre-scripts in `package.json` needed). The scanner generates `.helfy/di-tokens.ts` and `.helfy/di-registry.ts`. Add `.helfy` to `.gitignore`.
+The Babel plugin runs the DI scanner and context scanner before transformation (no pre-scripts in `package.json` needed). The scanners generate `.helfy/di-tokens.ts`, `.helfy/di-registry.ts`, and `.helfy/ctx-tokens.ts`. Add `.helfy` to `.gitignore`.
 
 ### Babel
 
@@ -90,9 +94,9 @@ A single preset in `.babelrc` is enough:
 }
 ```
 
-The preset includes: JSX runtime, TypeScript, legacy decorators, class properties, babel-plugin-transform-typescript-metadata, **helfy-di** (compile-time DI for `@Injectable<IX>()`, auto-registration at `createApp`, `@logger()` → `@logger("<ClassName>")` transformation).
+The preset includes: JSX runtime, TypeScript, legacy decorators, class properties, babel-plugin-transform-typescript-metadata, **helfy-di** (compile-time DI for `@Injectable<IX>()`, `@Service<IX>()`, `@UseCase<IX>()`, `@Store`, `@inject<IX>()`, `@useCtx<IX>()`, auto-registration at `createApp`, `@logger()` → `@logger("<ClassName>")` transformation).
 
-### Webpack
+### Webpack / Rspack
 
 To process directives (`@if`, `@for`, `@ref`, `@bind`, `@field`) in `.tsx` files, add the loader:
 
@@ -106,6 +110,8 @@ To process directives (`@if`, `@for`, `@ref`, `@bind`, `@field`) in `.tsx` files
 }
 ```
 
+The same configuration works with both Webpack and Rspack. Rspack is a faster, Rust-based bundler with webpack-compatible API.
+
 ### TypeScript
 
 In `tsconfig.json` set:
@@ -152,7 +158,7 @@ The `@View` decorator automatically:
 - wraps `this.props` in a reactive Proxy (each prop is a signal)
 - configures fine-grained effects: when a signal changes, only the specific DOM node that reads it is updated, not the entire component
 
-> **Important:** When inheriting from `@View`, apply the decorator on the child class as well. Otherwise `@ctx`, `scheduleUpdate`, and DOM updates will not work.
+> **Important:** When inheriting from `@View`, apply the decorator on the child class as well. Otherwise `@useCtx`, `scheduleUpdate`, and DOM updates will not work.
 
 ### Props
 
@@ -450,7 +456,7 @@ export class LoginForm {
 }
 ```
 
-Wrapper components (TextField, CheckboxField, etc.) accept `field` as a prop: `<TextField field={this.form.email} label="Email" />` and use `<input @field(this.props.field) />` internally.
+Wrapper components (TextField, CheckboxField, etc.) accept `$field` as a writable prop: `<TextField $field={this.form.email} label="Email" />` and use `<input @field(this.props.$field) />` internally. The `$` prefix marks a writable prop — mutable objects like FieldState bypass the default signal-based (readonly) props so form inputs work correctly.
 
 **JSX directive `@field(expr)`** — one directive replaces `@bind` + `onblur` + error `class` + `aria-invalid`. The compiler generates:
 
@@ -555,105 +561,212 @@ The `@empty` block after `@for` renders when the array is empty:
 
 ## State Management
 
-### Creating a Store
+Helfy uses a three-layer architecture: **@Store** (pure state), **@Service** (infrastructure), **@UseCase** (business logic).
+
+### Dependency flow
+
+```
+@UseCase  ──→  @Store  ←──  @Service
+   │                 ↑
+   └─────────────────┘
+```
+
+- **@Store** — pure reactive state; no dependencies, no side effects. Store does not know about anyone.
+- **@Service** — infrastructure (HTTP, validation, storage); can inject Store and other Services.
+- **@UseCase** — orchestrates business scenarios; injects Store + Services.
 
-A Store is a global reactive store. Create a class with the `@Store` decorator; reactive fields use `@observable`:
+### Creating a Store (@Store)
+
+A Store is a global reactive state container. **Requirements:**
+- Empty constructor (no parameters)
+- Only `@state` on fields and `@computed` on getters
+- Mutation methods that only change own state (synchronous; no `await` — async work belongs in @Service)
+- **Forbidden:** `@inject`, `@useCtx`, `@effect`, direct access to HTTP/storage/timers
 
 ```typescript
-import { Store, observable } from "@helfy/helfy";
+import { Store, state, computed } from "@helfy/helfy";
 
 @Store
-class UserStore {
-    @observable name = "Guest";
-    @observable isLoggedIn = false;
-
-    login(name: string) {
-        this.name = name;
-        this.isLoggedIn = true; // subscribers of name and isLoggedIn are notified
+class TodoStore {
+  @state todos: Todo[] = [];
+  @state filter: "all" | "active" | "completed" = "all";
+
+  @computed get filteredTodos() {
+    switch (this.filter) {
+      case "active": return this.todos.filter(t => !t.completed);
+      case "completed": return this.todos.filter(t => t.completed);
+      default: return this.todos;
     }
+  }
 
-    logout() {
-        this.name = "Guest";
-        this.isLoggedIn = false;
-    }
-}
+  add(title: string) {
+    this.todos = [...this.todos, { id: crypto.randomUUID(), title, completed: false }];
+  }
 
-export default UserStore;
+  toggle(id: string) {
+    this.todos = this.todos.map(t =>
+      t.id === id ? { ...t, completed: !t.completed } : t
+    );
+  }
+
+  setFilter(f: typeof this.filter) {
+    this.filter = f;
+  }
+}
 ```
 
-The `@Store` decorator adds:
-- `subscribe(field, callback)` — subscribe to field changes, returns unsubscribe function
-- `unsubscribe(field, callback)` — unsubscribe
+Fields use `@state` or `@observable` — both create signals.
 
-The `@observable` decorator turns a field into a reactive property with getter/setter. On write, all subscribers are notified.
+### Infrastructure services (@Service)
 
-### Subscribing with @observe
+Use `@Service` for infrastructure: HTTP clients, validators, repositories. **Requirements:**
+- Constructor with DI dependencies (other Services, Store)
+- Provides atomic technical capabilities
+- Can directly mutate Store (e.g. after fetching data)
+- **Forbidden:** `@state`, `@computed`, `@effect` on fields
 
-The `@observe` decorator binds a component field to a store field. When the store value changes, the component re-renders:
+```typescript
+import { Service } from "@helfy/helfy";
 
-```tsx
-import { View, observe } from "@helfy/helfy";
-import Stores from "./StoreContext";
-import UserStore from "./UserStore";
+export interface ITodoValidateService {
+  validateTitle(title: string): ValidationResult;
+}
 
-@View
-class Header {
-    @observe(Stores.userStore, 'name')
-    private userName: UserStore['name'];
+@Service<ITodoValidateService>()
+export class TodoValidateService implements ITodoValidateService {
+  validateTitle(title: string) {
+    // ...
+  }
+}
+```
 
-    @observe(Stores.userStore, 'isLoggedIn')
-    private isLoggedIn: UserStore['isLoggedIn'];
+### Business use cases (@UseCase)
 
-    render() {
-        return (
-            <header>
-                @if (this.isLoggedIn) {
-                    <span>Hello, {this.userName}!</span>
-                } @else {
-                    <span>Sign in</span>
-                }
-            </header>
-        );
-    }
+Use `@UseCase` to orchestrate business scenarios. **Requirements:**
+- Constructor with DI (Store, Services)
+- Main public method: `execute`, `perform`, or `handle`
+- Typical flow: validation → call services → update Store → side effects (notifications, analytics)
+- **Forbidden:** `@state`, `@computed`, `@effect` on fields
+
+```typescript
+import { UseCase } from "@helfy/helfy";
+
+@UseCase<ICreateTodoUseCase>()
+export class CreateTodoUseCase implements ICreateTodoUseCase {
+  constructor(
+    private store: TodoStore,
+    private validateService: ITodoValidateService
+  ) {}
+
+  async execute(dto: CreateTodoDto): Promise<Result<Todo, AppError>> {
+    const validation = this.validateService.validateTitle(dto.title);
+    if (!validation.valid) return Err(validation.error);
+
+    const todo = { id: crypto.randomUUID(), ...dto, completed: false };
+    this.store.add(todo);
+    return Ok(todo);
+  }
 }
 ```
 
-The field type is inferred from the store via lookup type (`UserStore['name']`), giving full type safety.
+### HttpClient and ApiClient
 
-### Store context
+Helfy provides an HTTP client and a Query/Mutation layer (similar to TanStack Query) for API data fetching.
+
+**Configure HttpClient** in `createApp`:
+
+```typescript
+createApp({ root: document.getElementById("root")! })
+  .http({
+    baseUrl: "/api",
+    timeout: 10000,
+    headers: { "X-App-Version": "1.0" },
+    queryCacheMaxSize: 100,
+  })
+  .router({ routes })
+  .mount(App);
+```
 
-Create a single context for all stores:
+**Define API interface and implementation** with `@ApiClient` and `@queryConfig`:
 
 ```typescript
-import UserStore from "./UserStore";
-import AppStore from "./AppStore";
+import { ApiClient, queryConfig, QueryBuilder, type Query, type HttpClient } from "@helfy/helfy";
+
+export interface TodoApi {
+  todos(): Query<Todo[]>;
+}
+
+@ApiClient<TodoApi>()
+export class TodoApiImpl implements TodoApi {
+  constructor(private readonly http: HttpClient) {}
+
+  @queryConfig("todos")
+  todos() {
+    return new QueryBuilder<Todo[]>(["todo"])
+      .fn(() => this.http.get<Todo[]>("/todos"))
+      .staleTime(5 * 60 * 1000)
+      .refetchOnWindowFocus(true);
+  }
+}
+```
 
-class Stores {
-    static readonly userStore = new UserStore();
-    static readonly appStore = new AppStore();
+**Use `@useQuery` in View** for automatic fetch on mount:
+
+```tsx
+@View
+class TodoList {
+  @useQuery<TodoApi>("todos") private todosQuery!: Query<Todo[]>;
+
+  render() {
+    const q = this.todosQuery;
+    if (q.isLoading) return <Spinner />;
+    if (q.isError) return <ErrorMessage error={q.error} />;
+    return <ul>{q.data?.map((t) => <li>{t.text}</li>)}</ul>;
+  }
 }
+```
+
+**Use `@useMutation`** for imperative mutations:
+
+```tsx
+import type { Mutation } from "@helfy/helfy";
+
+@useMutation<TodoApi>("create") private createTodo!: Mutation<TodoItem, AddTodoDto>;
 
-export default Stores;
+async handleSubmit() {
+  await this.createTodo.mutateAsync({ title: this.title });
+}
 ```
 
-Usage in components:
+### Accessing Store and UseCase from components
+
+Inject Store and UseCase via `@inject` in View/Context. Prefer UseCase for mutations, Store for reads:
 
 ```tsx
-import Stores from "./StoreContext";
+import { View, inject } from "@helfy/helfy";
 
-// subscribe via decorator
-@observe(Stores.userStore, 'name')
-private userName: string;
+@View
+class TodoList {
+  @inject<ITodoStore>() private store!: ITodoStore;
+  @inject<ICreateTodoUseCase>() private createTodo!: ICreateTodoUseCase;
 
-// direct store method call
-Stores.userStore.login("Alice");
+  render() {
+    return (
+      <ul>
+        @for (todo of this.store.filteredTodos; track todo.id) {
+          <li>{todo.title}</li>
+        }
+      </ul>
+    );
+  }
+}
 ```
 
 ---
 
 ## Logging (@logger)
 
-The `@logger` decorator injects a logger into View, Context, Store, and Injectable classes. The class name is set at compile time (Babel plugin), keeping readable names even after minification.
+The `@logger` decorator injects a logger into View, Context, Store, Service, and UseCase classes. The class name is set at compile time (Babel plugin), keeping readable names even after minification.
 
 ### Usage
 
@@ -681,7 +794,8 @@ class TodoInput {
 | Type | Format | Color |
 |------|--------|-------|
 | View (components) | `<TodoInput>` | skyblue |
-| Injectable (services) | `TodoValidateService()` | pink |
+| Service / Injectable | `TodoValidateService()` | pink |
+| UseCase | `CreateTodoUseCase()` | pink |
 | Context | `{TodoContext}` | khaki |
 | Form | `[LoginFormContext]` | bright blue |
 | Store | `TodoStore[]` | lime green |
@@ -720,23 +834,24 @@ Without a registered logger in the container, a fallback that logs to `console`
 
 ## Context & DI
 
-Helfy supports hierarchical Context and Dependency Injection: a provider wraps a subtree in JSX, and child components receive values via `@ctx`. Useful for theme, forms, routing, and other shared dependencies.
+Helfy supports hierarchical Context and Dependency Injection: a provider wraps a subtree in JSX, and child components receive values via `@useCtx`. Useful for theme, forms, routing, and other shared dependencies.
+
+### Provider (@Context)
 
-### Provider (@Context, @provide)
+A class with the `@Context` decorator is a non-rendering provider: it has no `render()` and only renders its children. Use `@state` for reactive fields, `@computed` for derived values; public methods are exposed automatically.
 
-A class with the `@Context` decorator is a non-rendering provider: it has no `render()` and only renders its children. Fields with `@provide` are available to consumers down the tree.
+**Constructor:** receives only props from JSX. Define your own props interface (same as View). Use `@inject` for container dependencies.
 
 ```tsx
-import { Context, provide } from "@helfy/helfy";
+import { Context, state } from "@helfy/helfy";
 
 export type TThemeMode = "light" | "dark";
 
 @Context
 export class ThemeContext {
-  @provide({ reactive: true })
+  @state
   mode: TThemeMode = "dark";
 
-  @provide()
   toggle = () => {
     this.mode = this.mode === "dark" ? "light" : "dark";
   };
@@ -754,17 +869,31 @@ Usage in JSX — wrap a subtree:
 
 The framework only renders the children of `ThemeContext`; the provider itself does not create DOM nodes.
 
-### Consumer (@ctx)
+**Context with typed props** — define an interface and use it in the constructor (same pattern as View):
+
+```tsx
+interface ApiContextProps {
+  baseUrl: string;
+}
+
+@Context
+export class ApiContext {
+  constructor(readonly props: ApiContextProps) {}
+  // ...
+}
+```
+
+### Consumer (@useCtx)
 
-A component with `@View` can receive context values via `@ctx`:
+A component with `@View` can receive context values via `@useCtx`:
 
 ```tsx
-import { View, ctx } from "@helfy/helfy";
+import { View, useCtx } from "@helfy/helfy";
 import { ThemeContext } from "./ThemeContext";
 
 @View
 class ThemeToggle {
-  @ctx(ThemeContext)
+  @useCtx(ThemeContext)
   private theme!: ThemeContext;
 
   render() {
@@ -782,7 +911,7 @@ You can inject only a context field:
 ```tsx
 @View
 class ModeDisplay {
-  @ctx(ThemeContext, "mode")
+  @useCtx(ThemeContext, "mode")
   private mode!: TThemeMode;
 
   render() {
@@ -791,16 +920,26 @@ class ModeDisplay {
 }
 ```
 
+**Interface-based injection** — for contexts with `@Context<IX>()`, use `@useCtx<ITodoContext>()`:
+
+```tsx
+@useCtx<ITodoContext>()
+private ctx!: ITodoContext;
+
+@useCtx<ITodoContext>("filteredTodos")
+private filteredTodos!: ITodoContext["filteredTodos"];
+```
+
 Provider lookup goes up the tree (`_parentView`); the nearest provider with the matching key is used.
 
 ### Reactive fields
 
-`@provide({ reactive: true })` makes a field reactive: when it changes, all consumers re-render. For methods, `@provide()` without `reactive` is enough.
+`@state` makes a field reactive: when it changes, all consumers re-render. Public methods are exposed automatically.
 
-**Computed fields** — getters with `@provide({ computed: true, deps: ["field1", "field2"] })` recompute when dependencies change and trigger consumer re-renders:
+**Computed fields** — getters with `@computed` recompute when dependencies change and trigger consumer re-renders:
 
 ```tsx
-@provide({ computed: true, deps: ["todos", "filter"] })
+@computed
 get filteredTodos(): Todo[] {
   return this.filter === "active"
     ? this.todos.filter(t => !t.completed)
@@ -810,50 +949,60 @@ get filteredTodos(): Todo[] {
 
 ### Optional injection
 
-The third argument of `@ctx` — options `{ optional?, defaultValue? }`:
+The third argument of `@useCtx` — options `{ optional?, defaultValue? }`:
 
 ```tsx
-@ctx(ThemeContext, { optional: true })
+@useCtx(ThemeContext, { optional: true })
 private theme?: ThemeContext;
 
-@ctx(ThemeContext, "mode", { defaultValue: "light" })
+@useCtx(ThemeContext, "mode", { defaultValue: "light" })
 private mode = "light";
 ```
 
 With no provider in the tree, `optional: true` yields `undefined`; `defaultValue` is used when the provider is absent.
 
-### DI Container (constructor injection)
+### DI: props vs dependencies
+
+**View and Context:** constructor receives only props from JSX. Dependencies are injected via field decorators:
+- `@inject<IX>()` — from global container (Store, Service, UseCase)
+- `@useCtx<IX>()` — from tree @Context / @Form providers
 
-Helfy supports a DI container for global services with **compile-time** magic: services are marked with `@Injectable<IX>()`, consumers only specify the type in the constructor — no `@inject` or explicit tokens.
+**@Service and @UseCase:** constructor DI via `@diParams` (added by Babel plugin) for injected dependencies.
 
-**Convention:** the last constructor parameter is props from the parent; preceding parameters are resolved from the container or from @Context up the tree.
+### Global services (@inject)
 
-**Service** — must use `@Injectable<IX>()` (interface in generic):
+Use `@inject<IX>()` in View/Context to access Store, Service, and UseCase from the container:
 
 ```typescript
+// Define interface and implement with @Service
 export interface ITodoValidateService {
   validate(title: string): ValidationResult;
 }
 
-@Injectable<ITodoValidateService>()
+@Service<ITodoValidateService>()
 export class TodoValidateService implements ITodoValidateService {
   validate(title: string) { ... }
 }
 ```
 
-**Consumer** — only the type in the constructor (plugin injects the token):
+**Consumer (View)** — inject Store or UseCase:
 
 ```tsx
 @View
 class TodoInput {
-  constructor(
-    private readonly validateService: ITodoValidateService,
-    readonly props: Props
-  ) {}
+  @inject<ITodoValidateService>() private validateService!: ITodoValidateService;
+  @inject<ICreateTodoUseCase>() private createTodo!: ICreateTodoUseCase;
+
+  constructor(readonly props: Props) {}
+
+  render() {
+    // Call UseCase for mutations, Service for validation
+    return <form onsubmit={() => this.createTodo.execute(this.form.getPayload())}>...</form>;
+  }
 }
 ```
 
-**Bootstrap** — DI registration is attached automatically at `createApp` (plugin injects `.useDI(registerAllServices)` in the chain):
+**Bootstrap** — DI registration is automatic at `createApp` (plugin injects `.useDI(registerAllServices)`):
 
 ```typescript
 createApp({ root: document.getElementById("root")! })
@@ -861,9 +1010,9 @@ createApp({ root: document.getElementById("root")! })
   .mount(App);
 ```
 
-The scanner is run by the Babel plugin before transformation, finds all `@Injectable<IX>()`, and generates `.helfy/di-tokens.ts` and `.helfy/di-registry.ts`.
+The DI scanner finds `@Store`, `@Service<IX>()`, `@UseCase<IX>()` and generates `.helfy/di-tokens.ts`, `.helfy/di-registry.ts`.
 
-**Fallback** — for manual setup: `.configureContainer()`, `@inject(token)`, `@Injectable(token)`:
+**Fallback** — for manual setup: `.configureContainer()`, `@Injectable(token)`:
 
 ```typescript
 createApp({ root })
@@ -949,19 +1098,25 @@ import styles from './App.module.css';
 |-----------|-------|-------------|
 | `@View` | Class | Turns a class into a component with `render()`, `view`, `update()` |
 | `@state` | Field | Component local state on signals (write updates only this component) |
-| `@Store` | Class | Adds `subscribe`/`unsubscribe` and `@observable` field reactivity |
-| `@observable` | Field | Makes a store field reactive — write notifies subscribers |
-| `@observe(store, field)` | Field | Binds a component field to a store field |
+| `@Store` | Class | Global reactive state. Empty constructor; only `@state`/`@computed`. No `@inject`, `@useCtx`, `@effect`, or external I/O |
+| `@observable` | Field | Alias for `@state` in Store; makes field reactive |
+| `@Service<IX>()` | Class | Infrastructure (HTTP, validation, repos). Constructor DI. No `@state`/`@computed`. Can mutate Store |
+| `@UseCase<IX>()` | Class | Business scenarios. Injects Store + Service. Main method: `execute`/`perform`/`handle`. No `@state`/`@computed` |
 | `@Context` | Class | Non-rendering context provider; renders only children |
-| `@provide()` / `@provide({ reactive: true })` / `@provide({ computed: true, deps })` | Field | Marks a field as available to `@ctx`. `reactive` — consumers re-render on change; `computed` + `deps` — for getters |
-| `@ctx(ContextClass)` / `@ctx(ContextClass, field)` | Field | Injects context or a context field from the nearest provider up the tree |
-| `@Injectable<IX>()` / `@Injectable<IX>('singleton' \| 'transient' \| 'scoped')` / `@Injectable(token)` | Class | Marks a class as injectable. Scope in (): `'singleton'` (default), `'transient'`, `'scoped'`. Fallback: `@Injectable(token)` with Symbol/string |
-| `@inject(token)` | Constructor param | Sets the token for the parameter (fallback; with `@Injectable<IX>()` the plugin injects it automatically) |
+| `@state` / `@computed` | Context field | In `@Context`: `@state` for reactive fields, `@computed` for derived getters. Public methods exposed automatically |
+| `@inject<IX>()` | Field | Injects Store, Service, or UseCase from container. Use in View/Context |
+| `@useCtx(ContextClass)` / `@useCtx<IX>()` / `@useCtx(ContextClass, field)` | Field | Injects context or a context field from the nearest provider up the tree |
+| `@Injectable<IX>()` | Class | Generic injectable. Prefer `@Service` for infrastructure, `@UseCase` for business logic |
 | `@logger()` / `@logger("tag")` | Field | Injects ILogger. No arg — compile-time class name and color by type (View/Context/Store/Injectable). With arg — custom tag (gray) |
 | `@ref` | Field | Marks a field to receive a DOM or component reference (use with `@ref(this.fieldName)` in JSX) |
 | `@expose` | Method | Makes a method available to the parent when using `@ref` on a component (without `@expose` the parent gets the full instance) |
 | `@binded(name)` | Field | Binds a field to `@bind:name` from the parent (for custom components) |
 | `@bind(expr)` / `@bind:name(expr)` | JSX | Two-way binding with `@state` field (value/checked + oninput/onchange). For components: `@bind:value(expr)` |
+| `@ApiClient<IX>()` | Class | API client with `@queryConfig` / `@mutationConfig` methods. Registers as Service by interface |
+| `@queryConfig(keyTemplate)` | Method | Marks method as Query; returns QueryBuilder chain, decorator calls `.build()` |
+| `@mutationConfig(options?)` | Method | Marks method as Mutation; merges invalidateQueries, optimisticFn into Mutation |
+| `@useQuery<ApiInterface>(keyOrGetter)` | Field | Injects Query from ApiClient, refetch on mount, reactive data/isLoading/isError |
+| `@useMutation<ApiInterface>(methodName)` | Field | Injects Mutation from ApiClient by method name |
 | `@Form` | Class | Form context with `@field` fields |
 | `@field(options)` | FormContext field | Creates FieldState for a form field (value, isTouched, error, isDirty) |
 | `@useForm(FormContext)` | Field | Injects the form into a component with subscription to field changes |

package/babel-preset.js

@@ -15,7 +15,8 @@ module.exports = (api, opts = {}) => ({
     "@babel/preset-typescript",
   ],
   plugins: [
-    [diPlugin, opts.di || {}],
+    // Plugins run before Presets — di-plugin must run before TS strips constructor param types
+    [diPlugin, opts.di || opts || {}],
     "babel-plugin-transform-typescript-metadata",
     ["@babel/plugin-proposal-decorators", { legacy: true }],
     ["@babel/plugin-proposal-class-properties", { loose: true }],

package/dist/Helfy/Render/DOM.d.ts

@@ -41,6 +41,8 @@ export default class DOM {
     /**
      * Mount a reactive @if / @ifelse. Uses createEffect to reactively
      * evaluate the condition and mount/unmount the body.
+     * Only destroys/remounts when the condition actually changes (prevents
+     * form state loss on blur/input when effect re-runs spuriously).
      */
     private static mountReactiveIf;
     /**

package/dist/app/createApp.d.ts

@@ -1,5 +1,5 @@
 import { Container } from "../di/Container";
-import type { RouterOptions } from "./types";
+import type { HttpConfig, RouterOptions } from "./types";
 import type { ViewInstance } from "../decorators/View.decorator";
 export interface CreateAppOptions {
     root: Element;
@@ -14,6 +14,8 @@ export interface AppBuilder {
     configureContainer(fn: (container: Container) => void): AppBuilder;
     /** Register services. Optional — plugin injects .useDI(registerAllServices) on createApp chains. */
     useDI(registerAllServices?: RegisterServicesFn): AppBuilder;
+    /** Configure HTTP client (baseUrl, headers, timeout, etc.) and register HttpClient in DI. */
+    http(config: HttpConfig): AppBuilder;
     router(options: RouterOptions): AppBuilder;
     mount(app: new (props?: any) => any): ViewInstance;
 }

package/dist/app/index.d.ts

@@ -1,4 +1,4 @@
 export { createApp } from "./createApp";
 export { HelfyApp } from "./HelfyApp";
 export type { AppBuilder, CreateAppOptions, RegisterServicesFn } from "./createApp";
-export type { AppConfig, RouterOptions } from "./types";
+export type { AppConfig, HttpConfig, RouterOptions } from "./types";

package/dist/app/types.d.ts

@@ -1,4 +1,5 @@
 import type { RouteConfig } from "../router/types";
+import type { HttpClient } from "../http/HttpClient.types";
 export interface AppConfig {
     root: Element;
     routes: RouteConfig[];
@@ -7,3 +8,12 @@ export interface AppConfig {
 export interface RouterOptions {
     routes: RouteConfig[];
 }
+export interface HttpConfig {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    /** Custom HttpClient implementation (otherwise FetchHttpClient) */
+    client?: new (config: HttpConfig) => HttpClient;
+    /** QueryCache max entries for LRU eviction. Default 100 */
+    queryCacheMaxSize?: number;
+}