import { Env } from '../boundary/components/env/types.js'; import { Cache } from '../cache/index.js'; import { SseConfig } from '../boundary/components/sse/types.js'; import { Actions, Model, Props } from '../types/index.js'; import { AppHandle, AppContextHandle } from './types.js'; import { Tap } from '../boundary/components/tap/types.js'; export type { AppArgs, AppContextHandle, AppFetcher, AppResource, } from './types.js'; export type { AppHandle } from './types.js'; /** * Creates an `App` — the entrypoint for a typed Env shape `E`, * inferred from `config.env`. `App` exposes `Boundary`, hooks, and * a `Resource` factory all wired against the same shape. * * Each `` instance owns its own Env, so different `App`s * can coexist in the same tree with completely independent shapes. * * Pass `tap` to subscribe to every action handler's dispatch / settle / * error inside the boundary — useful for analytics, audit logging, * Sentry breadcrumbs. See `recipes/tap.md`. Pass `cache` to persist * every `app.Resource(fetcher)` declaration through a single * {@link Cache} — each resource is namespaced inside the cache by * its declaration order, so reloads seed from storage automatically and * resources do not collide on shared params keys. Omit `cache` to keep * each resource's payloads in an isolated in-memory slot. * * `env`, `tap`, and `cache` are all fixed at `App()` time; * `` does not accept overrides. Mutate the live Env * through `context.actions.produce(({ env }) => …)`, and declare a * separate `App` when a test or storybook needs a different initial * value. * * @example * ```tsx * import { App, Cache, type Taps } from "march-hare"; * * type Session = { accessToken: string }; * * function tap(event: Taps) { * if (event.type === "error") { * Sentry.captureException(event.error, { tags: { action: event.action } }); * } * } * * export const app = App({ * env: { * session: null as Session | null, * operating: "idle" as "idle" | "signing-out", * }, * tap, * cache: Cache({ * get: (key) => localStorage.getItem(key), * set: (key, value) => localStorage.setItem(key, value), * remove: (key) => localStorage.removeItem(key), * keys: () => Object.keys(localStorage), * }), * }); * * // Root render. * * * ; * * // In resources.ts — persisted via the App's cache. * export const user = app.Resource((context) => * ky * .get("/api/user", { * headers: context.env.session * ? { Authorization: `Bearer ${context.env.session.accessToken}` } * : {}, * signal: context.controller.signal, * }) * .json(), * ); * ``` */ export declare function App(config?: { env?: E; tap?: Tap; cache?: Cache; sse?: SseConfig; }): AppHandle; /** * Standalone counterpart to `app.useContext`, exported as * `shared.useContext` — same call shape, but takes the **Env * shape `E` as a mandatory first generic** so the caller can be a * reusable component that isn't tied to a single `App` import. * * `E` is the Env type your component expects to see — usually * a union of every App's Env shape it might run under. Inside the * handler, `context.env` is typed as `E`; reach for `in` / `typeof` * narrowing for keys present on only a subset. * * Pass `app` directly if you only need to talk to one App — * `app.useContext()` is shorter and infers the * Env from the value. Reach for the standalone form only when a * component must support more than one App. * * @template E The Env shape (or union) the component supports. * @template M The model type, or `void`. * @template AC The Actions class, or `void`. * @template D The reactive data type returned from the `useActions` * data callback. * * @example * ```tsx * import { Action, shared } from "march-hare"; * * type WebEnv = { session: Session | null; locale: string }; * type MobileEnv = { session: Session | null; platform: "ios" | "android" }; * type Envs = WebEnv | MobileEnv; * * type Model = { name: string | null }; * const model: Model = { name: null }; * * class Actions { * static Sign = Action("Sign"); * } * * function useProfileActions() { * const context = shared.useContext(); * const actions = context.useActions(model); * * actions.useAction(Actions.Sign, (context, name) => * context.actions.produce(({ model }) => void (model.name = name)), * ); * * return actions; * } * ``` */ export declare function useContext(): AppContextHandle; /** * Standalone counterpart to `app.useEnv`, exported as `shared.useEnv` * — reads the nearest ``'s Env, typed against the * Env shape `E` supplied at the call site. For reusable components * that need an Env read outside any action handler (e.g. to hand a * closure to an external library at module bridge time). * * @template E The Env shape (or union) the component supports. * * @example * ```tsx * import { shared } from "march-hare"; * * type WebEnv = { session: Session | null }; * type MobileEnv = { session: Session | null }; * * function SessionBadge() { * const env = shared.useEnv(); * return {env.session ? env.session.user.name : "Signed out"}; * } * ``` */ export declare function useEnv(): Readonly;