@molecule/app-vue

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Vue framework bindings for molecule.dev.

Provides Vue composables and an app plugin for all molecule core interfaces: install moleculePlugin with your providers, then consume them in components via useAuth, useTheme, useTranslation, useStore, and the other composables.

Quick Start

import { createApp, defineComponent, h } from 'vue'
import { moleculePlugin, useAuth, useTheme } from '@molecule/app-vue'
import { provider as stateProvider } from '@molecule/app-state-zustand'
import { provider as themeProvider } from '@molecule/app-theme-css-variables'
import { createJWTAuthClient } from '@molecule/app-auth'

const Dashboard = defineComponent({
  setup() {
    // Composables are inject()-based: call them here in setup(), nowhere else.
    const { user, isAuthenticated, logout } = useAuth<{ name?: string }>()
    const { theme, toggleTheme } = useTheme()
    return () =>
      isAuthenticated.value
        ? h('div', { style: { background: theme.value.colors.background } }, [
            h('h1', `Welcome, ${user.value?.name ?? ''}!`),
            h('button', { onClick: toggleTheme }, 'Toggle theme'),
            h('button', { onClick: () => logout() }, 'Log out'),
          ])
        : h('a', { href: '/login' }, 'Log in')
  },
})

const app = createApp(Dashboard)
app.use(moleculePlugin, {
  state: stateProvider,
  auth: createJWTAuthClient({ baseURL: '/api' }),
  theme: themeProvider,
})
app.mount('#app')

Type

framework

Installation

npm install @molecule/app-vue @molecule/app-auth @molecule/app-device @molecule/app-forms @molecule/app-http @molecule/app-i18n @molecule/app-logger @molecule/app-platform @molecule/app-push @molecule/app-routing @molecule/app-state @molecule/app-storage @molecule/app-theme @molecule/app-ui @molecule/app-utilities @molecule/app-version vue

API

Interfaces

AuthClient

Auth client interface that all auth bond packages must implement. Provides login/logout/register flows, token management, profile updates, and auth state subscription.

interface AuthClient<T = UserProfile> {
  /**
   * Returns the current authentication state snapshot.
   */
  getState(): AuthState<T>
  /**
   * Returns whether the user is currently authenticated.
   */
  isAuthenticated(): boolean
  /**
   * Gets the current user.
   */
  getUser(): T | null
  /**
   * Updates the cached user object (state + persistent storage) without
   * hitting the network. Intended for local refreshes after a per-app
   * mutation (e.g., the user just PATCHed their own profile and the
   * server returned the canonical row). Does NOT change tokens.
   */
  setUser(user: T | null): void
  /**
   * Gets the current access token.
   */
  getAccessToken(): string | null
  /**
   * Stores the access token in the configured token storage adapter (in-memory
   * by default). Use this to seed the token after an out-of-band exchange (e.g.
   * the OAuth code→token redirect) instead of writing to `localStorage` directly,
   * which would violate the in-memory-default storage contract and make the bearer
   * token JS-readable (XSS-exfiltratable). Pass `null` to clear it.
   */
  setAccessToken(token: string | null): void
  /**
   * Gets the refresh token.
   */
  getRefreshToken(): string | null
  /**
   * Logs in with credentials.
   */
  login(credentials: LoginCredentials): Promise<AuthResult<T>>
  /**
   * Logs out the current user.
   */
  logout(): Promise<void>
  /**
   * Registers a new user.
   */
  register(data: RegisterData): Promise<AuthResult<T>>
  /**
   * Refreshes the access token.
   */
  refresh(): Promise<AuthResult<T>>
  /**
   * Requests a password reset.
   */
  requestPasswordReset(data: PasswordResetRequest): Promise<void>
  /**
   * Confirms a password reset.
   */
  confirmPasswordReset(data: PasswordResetConfirm): Promise<void>
  /**
   * Updates the current user's profile.
   */
  updateProfile(data: Partial<T>): Promise<T>
  /**
   * Changes the current user's password.
   */
  changePassword(oldPassword: string, newPassword: string): Promise<void>
  /**
   * Initializes auth state (e.g., from stored tokens).
   */
  initialize(): Promise<void>
  /**
   * Subscribes to auth state changes.
   */
  subscribe(callback: (state: AuthState<T>) => void): () => void
  /**
   * Subscribes to auth state changes (alias for subscribe).
   */
  onAuthChange(callback: (state: AuthState<T>) => void): () => void
  /**
   * Gets the current access token (alias for getAccessToken).
   */
  getToken?(): string | null
  /**
   * Adds an auth event listener.
   */
  addEventListener(listener: AuthEventListener): () => void
  /**
   * Destroys the auth client.
   */
  destroy(): void
}

AuthState

Reactive authentication state snapshot (initialized, authenticated, user, loading, and error).

interface AuthState<T = UserProfile> {
  /**
   * Whether auth state has been initialized.
   */
  initialized: boolean
  /**
   * Whether the user is authenticated.
   */
  authenticated: boolean
  /**
   * Current user (if authenticated).
   */
  user: T | null
  /**
   * Whether an auth operation is in progress.
   */
  loading: boolean
  /**
   * Last auth error (if any).
   */
  error: string | null
}

FormController

Form controller interface.

All form providers must implement this interface.

interface FormController<T extends Record<string, unknown> = Record<string, unknown>> {
  /**
   * Gets the current form state.
   */
  getState(): FormState<T>
  /**
   * Gets the value of a specific field.
   */
  getValue(name: string): unknown
  getValue<K extends keyof T>(name: K): T[K]
  /**
   * Gets all form values.
   */
  getValues(): T
  /**
   * Sets the value of a specific field.
   */
  setValue(
    name: string,
    value: unknown,
    options?: {
      shouldValidate?: boolean
      shouldDirty?: boolean
      shouldTouch?: boolean
    },
  ): void
  /**
   * Sets multiple values at once.
   */
  setValues(
    values: Partial<T>,
    options?: {
      shouldValidate?: boolean
    },
  ): void
  /**
   * Gets the error for a specific field.
   */
  getError(name: string): string | undefined
  /**
   * Sets the error for a specific field.
   */
  setError(name: string, error: string | undefined): void
  /**
   * Clears the error for a specific field.
   */
  clearError<K extends keyof T>(name: K): void
  /**
   * Clears all errors.
   */
  clearErrors(): void
  /**
   * Gets the field state for a specific field.
   */
  getFieldState<K extends keyof T>(name: K): FieldState<T[K]>
  /**
   * Registers a field for form management.
   */
  register(nameOrOptions: string | RegisterOptions, options?: RegisterOptions): FieldRegistration
  /**
   * Unregisters a field.
   */
  unregister(name: string): void
  /**
   * Validates a specific field.
   */
  validateField<K extends keyof T>(name: K): Promise<boolean>
  /**
   * Validates all fields.
   */
  validate(): Promise<boolean>
  /**
   * Resets the form to initial values.
   */
  reset(values?: Partial<T>): void
  /**
   * Handles form submission.
   */
  handleSubmit(
    onSubmit: (values: T) => void | Promise<void>,
    onError?: (errors: Partial<Record<keyof T, string>>) => void,
  ): (event?: { preventDefault?: () => void }) => Promise<void>
  /**
   * Sets focus to a field.
   */
  setFocus(name: keyof T): void
  /**
   * Subscribes to form state changes.
   */
  subscribe(callback: (state: FormState<T>) => void): () => void
  /**
   * Destroys the form controller.
   */
  destroy(): void
}

FormOptions

Form creation options.

interface FormOptions<T extends Record<string, unknown>> {
  /**
   * Default values.
   */
  defaultValues?: Partial<T>
  /**
   * Validation mode.
   */
  mode?: 'onSubmit' | 'onChange' | 'onBlur' | 'all'
  /**
   * Revalidation mode.
   */
  reValidateMode?: 'onChange' | 'onBlur' | 'onSubmit'
  /**
   * Whether to focus the first error field on submit.
   */
  shouldFocusError?: boolean
  /**
   * Form-level validation function.
   */
  validate?: (
    values: T,
  ) => Partial<Record<keyof T, string>> | Promise<Partial<Record<keyof T, string>>>
}

HttpClient

HTTP client interface.

All HTTP providers must implement this interface.

interface HttpClient {
  /**
   * Base URL for all requests.
   */
  baseURL: string
  /**
   * Default headers for all requests.
   */
  defaultHeaders: Record<string, string>
  /**
   * Makes a generic HTTP request.
   */
  request<T = unknown>(config: FullRequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a GET request.
   */
  get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a POST request.
   */
  post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a PUT request.
   */
  put<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a PATCH request.
   */
  patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Makes a DELETE request.
   */
  delete<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
  /**
   * Adds a request interceptor.
   * Returns a function to remove the interceptor.
   */
  addRequestInterceptor(interceptor: RequestInterceptor): () => void
  /**
   * Adds a response interceptor.
   * Returns a function to remove the interceptor.
   */
  addResponseInterceptor(interceptor: ResponseInterceptor): () => void
  /**
   * Adds an error interceptor.
   * Returns a function to remove the interceptor.
   */
  addErrorInterceptor(interceptor: ErrorInterceptor): () => void
  /**
   * Sets the authorization token.
   */
  setAuthToken(token: string | null): void
  /**
   * Returns the current authorization token, or `null` if not set.
   */
  getAuthToken(): string | null
  /**
   * Registers a handler for authentication errors (401).
   *
   * @returns An unsubscribe function.
   */
  onAuthError(handler: () => void): () => void
}

I18nProvider

i18n provider interface.

All i18n providers must implement this interface.

interface I18nProvider {
  /**
   * Gets the current locale.
   */
  getLocale(): string
  /**
   * Sets the current locale.
   *
   * **Fleet contract:** every conformant provider (the core simple provider,
   * `@molecule/api-i18n-simple`, `@molecule/app-i18n-i18next`, and
   * `@molecule/app-i18n-react-i18next`) MUST throw `Error('Locale "<code>"
   * not found')` when `locale` is not registered — via the constructor's
   * `initialLocales`/`locales` config, `addLocale()`, or `addTranslations()`
   * (all three register a locale). It must NOT silently degrade to
   * fallback-locale text while `getLocale()` reports the unregistered code —
   * that divergence makes a misconfigured locale switch indistinguishable
   * from a working one until a user notices the wrong language on screen.
   */
  setLocale(locale: string): Promise<void>
  /**
   * Gets all available locales.
   */
  getLocales(): LocaleConfig[]
  /**
   * Adds a locale.
   */
  addLocale(config: LocaleConfig): void
  /**
   * Removes a locale by code, notifying subscribers so language pickers
   * built on `onLocaleChange` re-render their list. If the removed locale
   * is currently active, the caller is responsible for switching to a
   * fallback (e.g. `'en'`) BEFORE calling this — the provider will not
   * auto-fall-back on its own.
   *
   * Returns `true` if the locale was registered and removed, `false`
   * otherwise.
   */
  removeLocale(code: string): boolean
  /**
   * Adds translations to a locale. Auto-creates the locale if it doesn't exist.
   *
   * **Fleet contract:** merges are DEEP, not a shallow spread — registering
   * two calls (e.g. two modules) that share a top-level namespace key merges
   * their subtrees instead of the second call clobbering the first's nested
   * translations wholesale. `@molecule/api-i18n-simple` implements the same
   * contract on the API side.
   */
  addTranslations(locale: string, translations: Translations, namespace?: string): void
  /**
   * Translates a key with optional interpolation values and pluralization.
   *
   * **Fleet plural contract (matches i18next's own key resolution order):**
   * when `options.count` is provided, the plural-suffixed key
   * (`` `${key}_${pluralForm}` ``, e.g. `item_one`/`item_few`/…, falling back
   * to `` `${key}_other` ``) is looked up FIRST and wins over the base `key`
   * if BOTH are registered. Only when no plural-suffixed key exists at all
   * does resolution fall back to the base key. A catalog that ships both
   * `item` and `item_one`/`item_other` therefore pluralizes identically
   * whichever provider is bonded.
   *
   * @returns The translated string, or the default value / key if not found.
   */
  t(
    key: string,
    values?: InterpolationValues,
    options?: {
      defaultValue?: string
      count?: number
    },
  ): string
  /**
   * Checks if a translation key exists.
   *
   * **Fleet contract:** follows the SAME locale-resolution chain as `t()` —
   * the active locale, then the English fallback — so `exists(key) === true`
   * whenever `t(key)` would render real translated text (not the raw key or
   * an inline `defaultValue`). Do not narrow this to "only the active
   * locale's own catalog"; that made `exists()` return `false` for keys `t()`
   * happily rendered via the English fallback, and the answer differed by
   * provider.
   *
   * @returns `true` if the key has a translation.
   */
  exists(key: string): boolean
  /**
   * Formats a number according to the current locale.
   *
   * @returns The locale-formatted number string.
   */
  formatNumber(value: number, options?: NumberFormatOptions): string
  /**
   * Formats a date according to the current locale.
   *
   * @returns The locale-formatted date string.
   */
  formatDate(value: Date | number | string, options?: DateFormatOptions): string
  /**
   * Formats a relative time (e.g. "2 hours ago").
   *
   * @returns The locale-formatted relative time string.
   */
  formatRelativeTime(
    value: Date | number,
    options?: {
      unit?: Intl.RelativeTimeFormatUnit
    },
  ): string
  /**
   * Formats a list (e.g. "A, B, and C").
   *
   * @returns The locale-formatted list string.
   */
  formatList(
    values: string[],
    options?: {
      type?: 'conjunction' | 'disjunction' | 'unit'
    },
  ): string
  /**
   * Subscribes to locale changes.
   *
   * @returns An unsubscribe function.
   */
  onLocaleChange(listener: (locale: string) => void): () => void
  /**
   * Gets the text direction for the current locale.
   *
   * @returns `'ltr'` or `'rtl'`.
   */
  getDirection(): 'ltr' | 'rtl'
  /**
   * Checks if a translation key exists (alias for exists).
   */
  hasKey?(key: string): boolean
  /**
   * Checks if the provider is ready.
   */
  isReady?(): boolean
  /**
   * Registers a callback for when the provider is ready.
   */
  onReady?(callback: () => void): () => void
  /**
   * Registers a lazily-loaded content module for automatic reload on locale changes.
   * All registered content is reloaded during `setLocale()` before listeners fire,
   * ensuring content is available on the first re-render with no flash.
   *
   * Idempotent: registering the same module name twice is a no-op.
   */
  registerContent?(module: string, loader: (locale: string) => Promise<void>): void
}

LoggerProvider

Logger provider interface that all logger bond packages must implement. Creates and manages logger instances and global log configuration.

interface LoggerProvider {
  /**
   * Gets a logger by name, or the root logger if no name given.
   */
  getLogger(name?: string): Logger
  /**
   * Creates a named logger.
   */
  createLogger(nameOrConfig: string | LoggerConfig, config?: LoggerConfig): Logger
  /**
   * Sets the global log level.
   */
  setLevel(level: LogLevel): void
  /**
   * Gets the global log level.
   */
  getLevel(): LogLevel
  /**
   * Adds a global transport.
   */
  addTransport(transport: LogTransport): () => void
  /**
   * Enables logging.
   */
  enable(): void
  /**
   * Disables logging.
   */
  disable(): void
  /**
   * Checks if logging is enabled.
   *
   * @returns `true` if logging is currently enabled.
   */
  isEnabled(): boolean
}

MoleculePluginOptions

Options for the molecule Vue plugin.

interface MoleculePluginOptions {
  state?: StateProvider
  auth?: AuthClient<unknown>
  theme?: ThemeProvider
  router?: Router
  i18n?: I18nProvider
  http?: HttpClient
  storage?: StorageProvider
  logger?: LoggerProvider
}

Router

Client-side router providing navigation, guards, route matching, and history control.

All routing providers must implement this interface.

interface Router {
  /**
   * Returns the current route location (pathname, search, hash, state).
   */
  getLocation(): RouteLocation
  /**
   * Gets the current route params.
   */
  getParams<T extends RouteParams = RouteParams>(): T
  /**
   * Gets the current query params.
   */
  getQuery(): QueryParams
  /**
   * Gets a specific query parameter.
   */
  getQueryParam(key: string): string | undefined
  /**
   * Gets the current hash.
   */
  getHash(): string
  /**
   * Navigates to a path.
   */
  navigate(path: string, options?: NavigateOptions): void
  /**
   * Navigates to a named route.
   */
  navigateTo(
    name: string,
    params?: RouteParams,
    query?: QueryParams,
    options?: NavigateOptions,
  ): void
  /**
   * Goes back in history.
   */
  back(): void
  /**
   * Goes forward in history.
   */
  forward(): void
  /**
   * Goes to a specific point in history.
   */
  go(delta: number): void
  /**
   * Updates the current query params.
   */
  setQuery(params: QueryParams, options?: NavigateOptions): void
  /**
   * Updates a specific query parameter.
   */
  setQueryParam(key: string, value: string | undefined, options?: NavigateOptions): void
  /**
   * Updates the current hash.
   */
  setHash(hash: string, options?: NavigateOptions): void
  /**
   * Checks if a path matches the current location.
   *
   * @returns `true` if the path matches the current route.
   */
  isActive(path: string, exact?: boolean): boolean
  /**
   * Matches a path pattern against a pathname.
   */
  matchPath<Params extends RouteParams = RouteParams>(
    pattern: string,
    pathname: string,
  ): RouteMatch<Params> | null
  /**
   * Generates a URL from a named route.
   */
  generatePath(name: string, params?: RouteParams, query?: QueryParams): string
  /**
   * Subscribes to route changes.
   */
  subscribe(listener: RouteChangeListener): () => void
  /**
   * Adds a navigation guard.
   */
  addGuard(guard: NavigationGuard): () => void
  /**
   * Registers route definitions.
   */
  registerRoutes(routes: RouteDefinition[]): void
  /**
   * Gets all registered routes.
   */
  getRoutes(): RouteDefinition[]
  /**
   * Destroys the router.
   */
  destroy(): void
}

RouterConfig

Configuration options for creating a router instance.

interface RouterConfig {
  /**
   * Router mode.
   */
  mode?: 'history' | 'hash' | 'memory'
  /**
   * Base path.
   */
  basePath?: string
  /**
   * Initial routes.
   */
  routes?: RouteDefinition[]
}

StateProvider

State provider interface that all state management bond packages must implement. Provides the store creation factory.

interface StateProvider {
  /**
   * Creates a new store.
   */
  createStore<T>(config: StoreConfig<T>): Store<T>
}

StorageProvider

Storage provider interface.

All storage providers must implement this interface.

interface StorageProvider {
  /**
   * Gets a value from storage.
   */
  get<T = unknown>(key: string): Promise<T | null>
  /**
   * Sets a value in storage.
   */
  set<T = unknown>(key: string, value: T): Promise<void>
  /**
   * Removes a value from storage.
   */
  remove(key: string): Promise<void>
  /**
   * Clears all values from storage.
   */
  clear(): Promise<void>
  /**
   * Gets all keys in storage.
   */
  keys(): Promise<string[]>
  /**
   * Gets multiple values from storage.
   */
  getMany?<T = unknown>(keys: string[]): Promise<Map<string, T | null>>
  /**
   * Sets multiple values in storage.
   */
  setMany?<T = unknown>(entries: Array<[string, T]>): Promise<void>
  /**
   * Removes multiple values from storage.
   */
  removeMany?(keys: string[]): Promise<void>
}

Store

Reactive state container with getState, setState, subscribe, and destroy.

All state management providers must implement this interface.

interface Store<T> {
  /**
   * Gets the current state.
   */
  getState(): T
  /**
   * Sets the state (partial or via updater function).
   */
  setState(partial: Partial<T> | ((state: T) => Partial<T>)): void
  /**
   * Subscribes to state changes.
   * Returns an unsubscribe function.
   */
  subscribe(listener: StateListener<T>): () => void
  /**
   * Destroys the store and cleans up subscriptions.
   */
  destroy(): void
}

StoreConfig

Configuration for creating a store (initial state, optional name, and middleware chain).

interface StoreConfig<T> {
  /**
   * Initial state value.
   */
  initialState: T
  /**
   * Optional name for debugging.
   */
  name?: string
  /**
   * Optional middleware functions.
   */
  middleware?: StoreMiddleware<T>[]
}

Theme

Complete theme definition.

interface Theme {
  name: string
  mode: 'light' | 'dark'
  colors: ThemeColors
  breakpoints: ThemeBreakpoints
  spacing: ThemeSpacing
  typography: ThemeTypography
  borderRadius: ThemeBorderRadius
  shadows: ThemeShadows
  transitions: ThemeTransitions
  zIndex: ThemeZIndex
}

ThemeProvider

Manages theme state including the active theme, mode toggling, and change subscriptions.

interface ThemeProvider {
  /**
   * Returns the currently active theme.
   */
  getTheme(): Theme
  /**
   * Sets the active theme by reference or by name.
   *
   * @param theme - A `Theme` object or a theme name string to activate.
   */
  setTheme(theme: Theme | string): void
  /**
   * Toggles between light and dark mode for the active theme.
   */
  toggleMode(): void
  /**
   * Subscribes to theme changes. The callback fires whenever
   * `setTheme()` or `toggleMode()` is called.
   *
   * @param callback - Invoked with the new theme after each change.
   * @returns An unsubscribe function.
   */
  subscribe(callback: (theme: Theme) => void): () => void
  /**
   * Returns all registered themes. Optional — not all providers
   * support multiple themes.
   */
  getThemes?(): Theme[]
}

UseAsyncStateReturn

Return type for the {@link useAsyncState} composable.

interface UseAsyncStateReturn<T> {
  /** The reactive state value. */
  state: Ref<T>
  /** Set the state to a new value, function updater, or promise. */
  setState: (value: T | ((prev: T) => T) | Promise<T | ((prev: T) => T)>) => void
  /** Merge a partial value into the state (object states only). */
  extendState: (
    partial:
      Partial<T> | ((prev: T) => Partial<T>) | Promise<Partial<T> | ((prev: T) => Partial<T>)>,
  ) => void
}

UseAuthReturn

Return type for useAuth composable.

interface UseAuthReturn<T = unknown> {
  state: ComputedRef<AuthState<T>>
  user: ComputedRef<T | null>
  isAuthenticated: ComputedRef<boolean>
  isLoading: ComputedRef<boolean>
  login: AuthClient<T>['login']
  logout: AuthClient<T>['logout']
  register: AuthClient<T>['register']
  refresh: AuthClient<T>['refresh']
}

UseCapacitorAppReturn

Return type for the useCapacitorApp composable.

interface UseCapacitorAppReturn {
  ready: ComputedRef<boolean>
  deviceReady: ComputedRef<boolean>
  pushReady: ComputedRef<boolean>
  error: ComputedRef<Error | null>
  initialize: () => Promise<void>
}

UseChangePasswordReturn

Return type for the {@link useChangePassword} composable.

interface UseChangePasswordReturn {
  status: ComputedRef<PromiseStatus>
  error: ComputedRef<Error | null>
  changePassword: (oldPassword: string, newPassword: string) => Promise<void>
  reset: () => void
}

UseDeviceReturn

Return type for the useDevice composable.

interface UseDeviceReturn {
  deviceInfo: DeviceInfo
  screenInfo: ScreenInfo
  hardwareInfo: HardwareInfo
  featureSupport: FeatureSupport
  supports: (feature: keyof FeatureSupport) => boolean
  isOnline: () => boolean
  isStandalone: () => boolean
  language: string
  languages: string[]
}

UseFormOptions

Options for useForm composable.

interface UseFormOptions<T extends Record<string, unknown>> extends FormOptions<T> {
  /**
   * Form provider's createForm function.
   */
  createForm: (options: FormOptions<T>) => FormController<T>
}

UseFormReturn

Return type for useForm composable.

interface UseFormReturn<T extends Record<string, unknown>> {
  // State
  formState: ComputedRef<FormState<T>>
  isValid: ComputedRef<boolean>
  isDirty: ComputedRef<boolean>
  isSubmitting: ComputedRef<boolean>

  // Field methods
  register: (name: keyof T, options?: RegisterOptions) => FieldRegistration
  getValue: <K extends keyof T>(name: K) => T[K]
  setValue: <K extends keyof T>(name: K, value: T[K]) => void
  getError: (name: keyof T) => string | undefined
  setError: (name: keyof T, error: string | undefined) => void
  clearErrors: () => void

  // Form methods
  handleSubmit: (
    onSubmit: (values: T) => void | Promise<void>,
    onError?: (errors: Partial<Record<keyof T, string>>) => void,
  ) => (event?: { preventDefault?: () => void }) => Promise<void>
  reset: (values?: Partial<T>) => void
  validate: () => Promise<boolean>

  // Form controller (for use with useWatch/useFieldState)
  form: FormController<T>
}

UseHttpOptions

Options for useHttp composable.

interface UseHttpOptions {
  immediate?: boolean
  onSuccess?: <T>(data: T) => void
  onError?: (error: Error) => void
}

UseHttpReturn

Return type for useHttp composable.

interface UseHttpReturn<T> extends UseHttpState<T> {
  execute: () => Promise<T | null>
  reset: () => void
}

UseHttpState

State for async HTTP operations.

interface UseHttpState<T> {
  data: Ref<T | null>
  loading: Ref<boolean>
  error: Ref<Error | null>
}

UseLoginReturn

Return type for the {@link useLogin} composable.

interface UseLoginReturn<T = unknown> {
  status: ComputedRef<PromiseStatus>
  value: ComputedRef<AuthResult<T> | null>
  error: ComputedRef<Error | null>
  login: (credentials: LoginCredentials) => Promise<AuthResult<T>>
  reset: () => void
}

UseOAuthOptions

OAuth configuration options.

interface UseOAuthOptions {
  /** Base URL for the API server (e.g. `https://api.example.com`). */
  baseURL?: string
  /** List of supported OAuth provider names (e.g. `['google', 'github']`). */
  oauthProviders?: string[]
  /** Path prefix for OAuth initiation routes. Defaults to `/oauth`. */
  oauthEndpoint?: string
  /** Path for the OAuth login POST endpoint. Defaults to `/users/log-in/oauth`. */
  loginEndpoint?: string
  /** Callback fired after a successful OAuth login. */
  onSuccess?: () => void
  /** Callback fired with an error message when the OAuth login fails. */
  onError?: (error: string) => void
  /**
   * Explicit auth client used to establish the session after the callback
   * exchange. Defaults to the injected client ({@link AuthKey}) when the
   * composable runs during component setup — pass one explicitly for
   * callers/tests outside an auth provider.
   */
  authClient?: AuthClient<unknown>
}

UseOAuthReturn

Return type for the {@link useOAuth} composable.

interface UseOAuthReturn {
  /** Available OAuth provider names. */
  providers: ComputedRef<string[]>
  /** Builds the OAuth initiation URL for a provider. */
  getOAuthUrl: (provider: string) => string
  /** Full-page redirect to the provider's OAuth initiation endpoint. */
  redirect: (provider: string) => void
  /**
   * Handles an OAuth callback: when the current URL carries a `code` param and
   * a provider was stashed by {@link redirect}, exchanges the code for a
   * session. A guarded no-op otherwise. Runs automatically on mount when the
   * composable is used inside a component; exposed for manual invocation
   * outside components (e.g. tests or custom callback screens).
   */
  handleCallback: () => Promise<void>
}

UsePasswordResetReturn

Return type for usePasswordReset composable.

interface UsePasswordResetReturn {
  requestStatus: ComputedRef<PromiseStatus>
  requestError: ComputedRef<Error | null>
  confirmStatus: ComputedRef<PromiseStatus>
  confirmError: ComputedRef<Error | null>
  requestReset: (data: PasswordResetRequest) => Promise<void>
  confirmReset: (data: PasswordResetConfirm) => Promise<void>
  reset: () => void
}

UsePlatformReturn

Return type for the usePlatform composable.

interface UsePlatformReturn {
  platform: Platform
  isNative: boolean
  isMobile: boolean
  isDesktop: boolean
  isWeb: boolean
  isDevelopment: boolean
  isProduction: boolean
  isPlatform: (...platforms: Platform[]) => boolean
}

UsePromiseReturn

Return type for usePromise composable.

interface UsePromiseReturn<T> {
  /** Current status of the async operation. */
  status: ComputedRef<PromiseStatus>
  /** Resolved value, or null if not yet resolved. */
  value: ComputedRef<T | null>
  /** Rejection error, or null if not rejected. */
  error: ComputedRef<Error | null>
  /** Invoke the async function. Returns a promise that resolves with the result. */
  call: (...args: any[]) => Promise<T>
  /** Cancel the current in-flight call. */
  cancel: (message?: string) => void
  /** Reset state to idle with null value and error. */
  reset: () => void
}

UsePushReturn

Return type for the usePush composable.

interface UsePushReturn {
  permission: ShallowRef<PermissionStatus | null>
  token: ShallowRef<PushToken | null>
  checkPermission: () => Promise<PermissionStatus>
  requestPermission: () => Promise<PermissionStatus>
  register: (options?: PushRegisterOptions) => Promise<PushToken>
  unregister: () => Promise<void>
  onNotificationReceived: (listener: NotificationReceivedListener) => () => void
  onNotificationAction: (listener: NotificationActionListener) => () => void
  onTokenChange: (listener: TokenChangeListener) => () => void
  setBadge: (count: number) => Promise<void>
  clearBadge: () => Promise<void>
}

UseRouterReturn

Return type for useRouter composable.

interface UseRouterReturn {
  location: ComputedRef<ReturnType<Router['getLocation']>>
  params: ComputedRef<RouteParams>
  query: ComputedRef<QueryParams>
  navigate: Router['navigate']
  navigateTo: Router['navigateTo']
  back: Router['back']
  forward: Router['forward']
  isActive: Router['isActive']
}

UseSignupReturn

Return type for useSignup composable.

interface UseSignupReturn<T = unknown> {
  status: ComputedRef<PromiseStatus>
  value: ComputedRef<AuthResult<T> | null>
  error: ComputedRef<Error | null>
  signup: (data: RegisterData) => Promise<AuthResult<T>>
  reset: () => void
}

UseStorageValueOptions

Options for useStorageValue composable.

interface UseStorageValueOptions<T> {
  defaultValue?: T
}

UseStorageValueReturn

Return type for useStorageValue composable.

interface UseStorageValueReturn<T> {
  value: Ref<T | undefined>
  loading: Ref<boolean>
  error: Ref<Error | null>
  setValue: (value: T) => Promise<void>
  removeValue: () => Promise<void>
}

UseStoreOptions

Options for useStore composable.

interface UseStoreOptions<T, S> {
  selector?: (state: T) => S
}

UseThemeReturn

Return type for useTheme composable.

interface UseThemeReturn {
  theme: ComputedRef<Theme>
  themeName: ComputedRef<string>
  mode: ComputedRef<'light' | 'dark'>
  setTheme: (name: string) => void
  toggleTheme: () => void
}

UseTranslationReturn

Return type for useTranslation composable.

interface UseTranslationReturn {
  t: I18nProvider['t']
  locale: ComputedRef<string>
  direction: ComputedRef<'ltr' | 'rtl'>
  locales: ComputedRef<ReturnType<I18nProvider['getLocales']>>
  setLocale: I18nProvider['setLocale']
  formatNumber: I18nProvider['formatNumber']
  formatDate: I18nProvider['formatDate']
}

UseVersionReturn

Return type for the useVersion composable.

interface UseVersionReturn {
  state: ComputedRef<VersionState>
  isUpdateAvailable: ComputedRef<boolean>
  isChecking: ComputedRef<boolean>
  isServiceWorkerWaiting: ComputedRef<boolean>
  newVersion: ComputedRef<string | undefined>
  checkForUpdates: () => Promise<boolean>
  applyUpdate: (options?: { force?: boolean }) => void
  dismissUpdate: () => void
  startPeriodicChecks: (options?: UpdateCheckOptions) => void
  stopPeriodicChecks: () => void
}

Functions

createAuthPlugin(client)

Creates a Vue plugin that provides an auth service via dependency injection.

function createAuthPlugin(client: AuthClient<T>): Plugin

• client — The auth client to inject into the Vue application.

Returns: A Vue plugin that provides the auth client to all descendant components.

createHttpPlugin(client)

Creates a Vue plugin that provides an HTTP service via dependency injection.

function createHttpPlugin(client: HttpClient): Plugin

• client — The HTTP client to inject into the Vue application.

Returns: A Vue plugin that provides the HTTP client to all descendant components.

createI18nPlugin(provider)

Creates a Vue plugin that provides an i18n service via dependency injection.

function createI18nPlugin(provider: I18nProvider): Plugin

• provider — The i18n provider to inject into the Vue application.

Returns: A Vue plugin that provides the i18n service to all descendant components.

createLoggerPlugin(provider)

Creates a Vue plugin that provides a logger service via dependency injection.

function createLoggerPlugin(provider: LoggerProvider): Plugin

• provider — The logger provider to inject into the Vue application.

Returns: A Vue plugin that provides the logger service to all descendant components.

createRouterPlugin(router)

Creates a Vue plugin that provides a router service via dependency injection.

function createRouterPlugin(router: Router): Plugin

• router — The router instance to inject into the Vue application.

Returns: A Vue plugin that provides the router to all descendant components.

createStatePlugin(provider)

Creates a Vue plugin that provides a state service via dependency injection.

function createStatePlugin(provider: StateProvider): Plugin

• provider — The state provider to inject into the Vue application.

Returns: A Vue plugin that provides the state service to all descendant components.

createStoragePlugin(provider)

Creates a Vue plugin that provides a storage service via dependency injection.

function createStoragePlugin(provider: StorageProvider): Plugin

• provider — The storage provider to inject into the Vue application.

Returns: A Vue plugin that provides the storage service to all descendant components.

createThemePlugin(provider)

Creates a Vue plugin that provides a theme service via dependency injection.

function createThemePlugin(provider: ThemeProvider): Plugin

• provider — The theme provider to inject into the Vue application.

Returns: A Vue plugin that provides the theme service to all descendant components.

useAsyncState(initialValue)

Vue composable for async-capable state management.

Provides a reactive state ref with setState and extendState methods that accept synchronous values, updater functions, or promises.

function useAsyncState(initialValue: T): UseAsyncStateReturn<T>

• initialValue — The initial state value

Returns: Reactive state and setter methods

useAuth()

Composable for authentication state and actions.

function useAuth(): UseAuthReturn<T>

Returns: Auth state and action methods

useAuthClient()

Composable to access the auth client from injection.

function useAuthClient(): AuthClient<T>

Returns: The auth client

useCapacitorApp(options)

Composable for Capacitor app initialization.

Wraps createCapacitorApp from @molecule/app-platform with Vue reactivity. Auto-initializes on mount (inside a component) or eagerly (inside an effect scope). Cleans up on scope dispose.

function useCapacitorApp(options?: CapacitorAppOptions): UseCapacitorAppReturn

• options — Capacitor app configuration options

Returns: Reactive Capacitor app state including readiness flags, error, and an initialize method.

useChangePassword()

Composable for changing password with async state tracking.

function useChangePassword(): UseChangePasswordReturn

Returns: Reactive status, error, a changePassword action, and a reset method.

useChildLogger(parentName, context)

Composable to create a child logger with additional context.

function useChildLogger(parentName: string, context: Record<string, unknown>): Logger

• parentName — Parent logger name
• context — Additional context

Returns: Child logger instance

useCurrentTheme()

Composable to get just the current theme.

function useCurrentTheme(): ComputedRef<Theme>

Returns: Computed theme reference

useDelete(url, config, options)

Composable for DELETE requests.

function useDelete(url: string, config?: RequestConfig, options?: UseHttpOptions): UseHttpReturn<T>

• url — The request URL of the resource to delete.
• config — Optional HTTP request configuration (headers, params, etc.).
• options — Optional composable behavior options (immediate execution, callbacks).

Returns: Reactive request state (data, loading, error) and execute/reset methods.

useDevice()

Composable for device information.

Uses module-level getProvider() from @molecule/app-device (singleton). Static — no reactivity needed. Just calls provider methods and returns plain values.

function useDevice(): UseDeviceReturn

Returns: Device information and utility methods

useDirection()

Composable to get the text direction.

function useDirection(): ComputedRef<'ltr' | 'rtl'>

Returns: Computed direction reference

useFieldState(form, name)

Composable to get field-level state.

function useFieldState(form: FormController<T>, name: keyof T): ComputedRef<FieldState<T[keyof T]>>

• form — Form controller (from useForm().form)
• name — Field name

Returns: Computed field state (value, error, touched, dirty, valid, validating)

useForm(options)

Composable for form state management.

function useForm(options: UseFormOptions<T>): UseFormReturn<T>

• options — Form options including createForm from a forms provider

Returns: Form state, computed properties, and methods

useGet(url, config, options)

Composable for GET requests.

function useGet(url: string, config?: RequestConfig, options?: UseHttpOptions): UseHttpReturn<T>

• url — The request URL to fetch from.
• config — Optional HTTP request configuration (headers, params, etc.).
• options — Optional composable behavior options (immediate execution, callbacks).

Returns: Reactive request state (data, loading, error) and execute/reset methods.

useHttp(method, url, config, options)

Composable for making HTTP requests with state management.

function useHttp(
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
  url: string,
  config?: RequestConfig,
  options?: UseHttpOptions,
): UseHttpReturn<T>

• method — HTTP method
• url — Request URL
• config — Request configuration
• options — Composable options

Returns: Request state and execute function

useHttpClient()

Composable to access the HTTP client from injection.

function useHttpClient(): HttpClient

Returns: The HTTP client

useI18nProvider()

Composable to access the i18n provider from injection.

function useI18nProvider(): I18nProvider

Returns: The i18n provider

useIsActive(path, exact)

Composable to check if a path is currently active.

function useIsActive(path: string, exact?: boolean): ComputedRef<boolean>

• path — The path to check
• exact — Whether to match exactly (default: false)

Returns: Computed boolean indicating if the path is active

useIsAuthenticated()

Composable to check if user is authenticated.

function useIsAuthenticated(): ComputedRef<boolean>

Returns: Computed authentication status

useLocale()

Composable to get the current locale.

function useLocale(): ComputedRef<string>

Returns: Computed locale reference

useLocation()

Composable to get the current location.

function useLocation(): ComputedRef<RouteLocation>

Returns: Computed location reference

useLogger(name, config)

Composable to get a logger instance.

function useLogger(name: string, config?: Partial<LoggerConfig>): Logger

• name — Logger name (usually component name)
• config — Optional logger configuration

Returns: Logger instance

useLoggerProvider()

Composable to access the logger provider from injection.

function useLoggerProvider(): LoggerProvider

Returns: The logger provider

useLogin()

Composable for login with async state tracking.

function useLogin(): UseLoginReturn<T>

Returns: Reactive status, auth result value, error, a login action, and a reset method.

useNavigate()

Composable to get the navigate function.

function useNavigate(): (path: string, options?: NavigateOptions) => void

Returns: A function that navigates to the given path with optional navigation options.

useOAuth(options)

Composable for OAuth authentication.

Reads OAuth configuration from the provided options and provides helpers to build OAuth URLs and start a login. When used inside a component, it automatically handles OAuth callbacks on mount by detecting code and state URL parameters and exchanging them for a session.

Session establishment: the exchange result is applied to the resolved auth client (an explicit options.authClient, else the injected {@link AuthKey} client when running during component setup). When NO client is available, the server has already established the httpOnly-cookie session via the exchange, so a user-carrying response still counts as success — options.onSuccess fires; a response with no user fires options.onError.

function useOAuth(options?: UseOAuthOptions): UseOAuthReturn

• options — OAuth configuration (base URL, providers, endpoint paths, callbacks, auth client).

Returns: Available providers, a URL builder, a redirect method, and a callback handler.

useParams()

Composable to get route parameters.

function useParams(): ComputedRef<T>

Returns: Computed params reference

usePasswordReset()

Composable for password reset flow with async state tracking.

function usePasswordReset(): UsePasswordResetReturn

Returns: Password reset state and actions

usePatch(url, config, options)

Composable for PATCH requests.

function usePatch(url: string, config?: RequestConfig, options?: UseHttpOptions): UseHttpReturn<T>

• url — The request URL to send a partial update to.
• config — Optional HTTP request configuration (headers, body data, etc.).
• options — Optional composable behavior options (immediate execution, callbacks).

Returns: Reactive request state (data, loading, error) and execute/reset methods.

usePlatform()

Composable for platform detection.

Uses module-level platform() and isPlatform() from @molecule/app-platform (singleton). Static — no reactivity needed.

function usePlatform(): UsePlatformReturn

Returns: Platform information and utility methods

usePost(url, config, options)

Composable for POST requests.

function usePost(url: string, config?: RequestConfig, options?: UseHttpOptions): UseHttpReturn<T>

• url — The request URL to send data to.
• config — Optional HTTP request configuration (headers, body data, etc.).
• options — Optional composable behavior options (immediate execution, callbacks).

Returns: Reactive request state (data, loading, error) and execute/reset methods.

usePromise(fn)

Vue composable for tracking async function state.

Wraps an async function and provides reactive state tracking for its pending/resolved/rejected status, along with cancellation and reset support.

function usePromise(fn: (...args: any[]) => Promise<T>): UsePromiseReturn<T>

• fn — The async function to track

Returns: Reactive state and control methods

usePush()

Composable for push notifications.

Uses module-level getProvider() from @molecule/app-push (singleton). Wraps async methods to update reactive refs for permission and token.

function usePush(): UsePushReturn

Returns: Push notification state and action methods

usePut(url, config, options)

Composable for PUT requests.

function usePut(url: string, config?: RequestConfig, options?: UseHttpOptions): UseHttpReturn<T>

• url — The request URL to send a full replacement to.
• config — Optional HTTP request configuration (headers, body data, etc.).
• options — Optional composable behavior options (immediate execution, callbacks).

Returns: Reactive request state (data, loading, error) and execute/reset methods.

useQuery()

Composable to get query parameters.

function useQuery(): ComputedRef<T>

Returns: A computed ref containing the current URL query parameters.

useRootLogger()

Composable to get the root logger.

function useRootLogger(): Logger

Returns: Root logger instance

useRouter()

Composable for routing state and actions.

function useRouter(): UseRouterReturn

Returns: Router state and navigation methods

useRouterInstance()

Composable to access the router from injection.

function useRouterInstance(): Router

Returns: The router

useSetStore(store)

Composable to get store's setState function.

function useSetStore(store: Store<T>): (partial: Partial<T> | ((state: T) => Partial<T>)) => void

• store — The store

Returns: The setState function

useSignup()

Composable for user registration with async state tracking.

function useSignup(): UseSignupReturn<T>

Returns: Signup state and action

useStateProvider()

Composable to access the state provider from injection.

function useStateProvider(): StateProvider

Returns: The state provider

useStorage()

Composable for direct storage operations.

function useStorage(): {
  get: <T>(key: string) => Promise<T | null>
  set: <T>(key: string, value: T) => Promise<void>
  remove: (key: string) => Promise<void>
  clear: () => Promise<void>
  keys: () => Promise<string[]>
}

Returns: Storage operation methods

useStorageProvider()

Composable to access the storage provider from injection.

function useStorageProvider(): StorageProvider

Returns: The storage provider

useStorageValue(key, options)

Composable to manage a single storage value with Vue reactivity.

function useStorageValue(key: string, options?: UseStorageValueOptions<T>): UseStorageValueReturn<T>

• key — Storage key
• options — Composable options

Returns: Value, setter, and loading state

useStore(store, options)

Composable to subscribe to a store with optional selector.

function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): Ref<S, S>

• store — The store to subscribe to
• options — Composable options (selector)

Returns: Reactive state reference

useStoreComputed(store, selector)

Composable to create a computed store value.

function useStoreComputed(store: Store<T>, selector: (state: T) => S): ComputedRef<S>

• store — The store
• selector — Selector function

Returns: Computed reference

useT()

Composable to get just the translation function.

function useT(): (key: string, values?: InterpolationValues) => string

Returns: Translation function

useTheme()

Composable for theme state and actions.

function useTheme(): UseThemeReturn

Returns: Theme state and actions

useThemeColors()

Composable to get the current theme colors.

function useThemeColors(): ComputedRef<ThemeColors>

Returns: Computed colors reference

useThemeMode()

Composable to get just the theme mode.

function useThemeMode(): ComputedRef<'light' | 'dark'>

Returns: Computed mode reference

useThemeProvider()

Composable to access the theme provider from injection.

function useThemeProvider(): ThemeProvider

Returns: The theme provider

useTranslation()

Composable for internationalization.

function useTranslation(): UseTranslationReturn

Returns: Translation function and locale management

useUser()

Composable to get just the authenticated user.

function useUser(): ComputedRef<T | null>

Returns: Computed user reference

useVersion()

Composable for version and update management.

Uses module-level getProvider() from @molecule/app-version (singleton).

function useVersion(): UseVersionReturn

Returns: The result.

useWatch(form, name)

Composable to watch a specific field value.

function useWatch(form: FormController<T>, name: K): ComputedRef<T[K]>

• form — Form controller (from useForm().form)
• name — Field name to watch

Returns: Computed reference to the field value

Constants

AuthKey

Injection key for auth client.

const AuthKey: InjectionKey<AuthClient<unknown>>

HttpKey

Injection key for HTTP client.

const HttpKey: InjectionKey<HttpClient>

I18nKey

Injection key for i18n provider.

const I18nKey: InjectionKey<I18nProvider>

LoggerKey

Injection key for logger provider.

const LoggerKey: InjectionKey<LoggerProvider>

moleculePlugin

Vue plugin that provides all molecule services.

const moleculePlugin: Plugin<MoleculePluginOptions>

RouterKey

Injection key for router.

const RouterKey: InjectionKey<Router>

StateKey

Injection key for state provider.

const StateKey: InjectionKey<StateProvider>

StorageKey

Injection key for storage provider.

const StorageKey: InjectionKey<StorageProvider>

ThemeKey

Injection key for theme provider.

const ThemeKey: InjectionKey<ThemeProvider>

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-auth ^1.0.1
• @molecule/app-device ^1.0.1
• @molecule/app-forms ^1.0.1
• @molecule/app-http ^1.0.1
• @molecule/app-i18n ^1.0.1
• @molecule/app-logger ^1.0.1
• @molecule/app-platform ^1.0.1
• @molecule/app-push ^1.0.1
• @molecule/app-routing ^1.0.1
• @molecule/app-state ^1.0.1
• @molecule/app-storage ^1.0.1
• @molecule/app-theme ^1.0.1
• @molecule/app-ui ^1.0.1
• @molecule/app-utilities ^1.0.1
• @molecule/app-version ^1.0.1
• vue ^3.4.0

Runtime Dependencies

• @molecule/app-auth

• @molecule/app-device

• @molecule/app-forms

• @molecule/app-http

• @molecule/app-i18n

• @molecule/app-logger

• @molecule/app-platform

• @molecule/app-push

• @molecule/app-routing

• @molecule/app-state

• @molecule/app-storage

• @molecule/app-theme

• @molecule/app-ui

• @molecule/app-utilities

• @molecule/app-version

• vue

• Composables work only inside setup() / <script setup> (they use inject()), and each one throws when moleculePlugin was not installed with that service — the plugin provides ONLY the options you pass. Fix the app.use(moleculePlugin, …) options; don't catch the error.

• Returned state is Vue refs/computed — templates auto-unwrap ({{ user?.name }}), but script code needs .value (isAuthenticated.value). useStore returns a Ref of the selected state.

• For locale-reactive text use useTranslation()'s t in components — the raw t() import from @molecule/app-i18n does not trigger re-render on locale change.

Translations

Translation strings are provided by @molecule/app-locales-vue.