@molecule/app-svelte

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.

Svelte framework bindings for molecule.dev.

Provides Svelte stores and context utilities for all molecule core interfaces: call setMoleculeContext(config) once in the root layout, then consume services anywhere below via store factories (createAuthStores, createThemeStores, createI18nStores, …).

Quick Start

<!-- +layout.svelte — wire providers ONCE, during component init -->
<script lang="ts">
  import { setMoleculeContext } from '@molecule/app-svelte'
  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'

  setMoleculeContext({
    state: stateProvider,
    auth: createJWTAuthClient({ baseURL: '/api' }),
    theme: themeProvider,
  })
</script>

<slot />

<!-- Component.svelte — consume via stores -->
<script lang="ts">
  import { createAuthStores, createThemeStores } from '@molecule/app-svelte'

  const { user, isAuthenticated, logout } = createAuthStores<{ name?: string }>()
  const { theme, toggleTheme, mode } = createThemeStores()
</script>

{#if $isAuthenticated}
  <div style:background={$theme.colors.background}>
    <h1>Welcome, {$user?.name}!</h1>
    <button on:click={toggleTheme}>Toggle ({$mode})</button>
    <button on:click={() => logout()}>Logout</button>
  </div>
{/if}

Type

framework

Installation

npm install @molecule/app-svelte @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 svelte

API

Interfaces

AsyncStateStore

Async state store.

interface AsyncStateStore<T> extends Writable<T> {
  setState: (value: T | ((prev: T) => T) | Promise<T | ((prev: T) => T)>) => void
  extendState: (
    partial:
      Partial<T> | ((prev: T) => Partial<T>) | Promise<Partial<T> | ((prev: T) => Partial<T>)>,
  ) => void
}

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
}

HttpState

State for async HTTP operations.

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

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
}

Logger

Logger instance with leveled logging methods, child logger creation, and transport management.

interface Logger {
  /**
   * Logs a trace message.
   */
  trace(message: string, ...args: unknown[]): void
  /**
   * Logs a debug message.
   */
  debug(message: string, ...args: unknown[]): void
  /**
   * Logs an info message.
   */
  info(message: string, ...args: unknown[]): void
  /**
   * Logs a warning message.
   */
  warn(message: string, ...args: unknown[]): void
  /**
   * Logs an error message.
   */
  error(message: string | Error, ...args: unknown[]): void
  /**
   * Sets the log level.
   */
  setLevel(level: LogLevel): void
  /**
   * Gets the current log level.
   */
  getLevel(): LogLevel
  /**
   * Creates a child logger with a namespace.
   */
  child(name: string, context?: Record<string, unknown>): Logger
  /**
   * Adds additional context to the logger.
   */
  withContext(context: Record<string, unknown>): Logger
  /**
   * Adds a transport.
   */
  addTransport(transport: LogTransport): () => void
  /**
   * Removes a transport.
   */
  removeTransport(transport: LogTransport): 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
}

MoleculeConfig

Configuration for molecule Svelte context.

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

MoleculeStore

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
}

OAuthHelpers

OAuth helpers returned by {@link createOAuthHelpers}.

interface OAuthHelpers {
  /** Readable store of available OAuth provider names. */
  providers: Readable<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 when
   * {@link createOAuthHelpers} is called in a browser; exposed for manual
   * invocation (e.g. tests or custom callback screens).
   */
  handleCallback: () => Promise<void>
}

OAuthOptions

OAuth configuration options.

interface OAuthOptions {
  /** 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 client in Svelte context (only resolvable when
   * called during component initialization) — pass one explicitly for
   * callers/tests outside a component/context.
   */
  authClient?: AuthClient<unknown>
}

PasswordResetStores

Password reset stores.

interface PasswordResetStores {
  request: Readable<PromiseState<void>> & {
    call: (data: PasswordResetRequest) => Promise<void>
    cancel: (message?: string) => void
    reset: () => void
  }
  confirm: Readable<PromiseState<void>> & {
    call: (data: PasswordResetConfirm) => Promise<void>
    cancel: (message?: string) => void
    reset: () => void
  }
  resetAll: () => void
}

PromiseStore

Promise store with action methods.

interface PromiseStore<T> extends Readable<PromiseState<T>> {
  call: (...args: any[]) => Promise<T>
  cancel: (message?: string) => void
  reset: () => void
}

Readable

Readable interface for subscribing.

interface Readable<T> {
  /**
   * Subscribe on value changes.
   * @param run subscription callback
   * @param invalidate cleanup callback
   */
  subscribe(this: void, run: Subscriber<T>, invalidate?: () => void): Unsubscriber
}

RouteLocation

Current URL decomposed into pathname, search string, hash, navigation state, and unique key.

interface RouteLocation {
  /**
   * Current pathname.
   */
  pathname: string
  /**
   * Query string (including leading ?).
   */
  search: string
  /**
   * Hash (including leading #).
   */
  hash: string
  /**
   * State data passed with navigation.
   */
  state?: unknown
  /**
   * Unique key for this location.
   */
  key?: string
}

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
}

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>
}

StorageValueState

State for async storage values.

interface StorageValueState<T> {
  value: T | undefined
  loading: boolean
  error: Error | null
}

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[]
}

Writable

Writable interface for both updating and subscribing.

interface Writable<T> extends Readable<T> {
  /**
   * Set value and inform subscribers.
   * @param value to set
   */
  set(this: void, value: T): void

  /**
   * Update value using callback and inform subscribers.
   * @param updater callback
   */
  update(this: void, updater: Updater<T>): void
}

Types

CapacitorAppStore

Return type for the Capacitor app store.

type CapacitorAppStore = Readable<CapacitorAppState> & {
  initialize: () => Promise<void>
}

ChangePasswordStore

Change password store type.

type ChangePasswordStore = PromiseStore<void>

LoginStore

Login store type.

type LoginStore<T = unknown> = PromiseStore<AuthResult<T>>

QueryParams

URL query string parameter map (single values or arrays for repeated keys).

type QueryParams = Record<string, string | string[] | undefined>

RouteParams

URL path parameter key-value map extracted from dynamic route segments (e.g. { id: '123' }).

type RouteParams = Record<string, string>

SignupStore

Signup store type.

type SignupStore<T = unknown> = PromiseStore<AuthResult<T>>

Functions

createAsyncState(initialValue)

Creates a writable store with async-capable setState and extendState.

function createAsyncState(initialValue: T): AsyncStateStore<T>

• initialValue — The initial state value

Returns: The created instance.

createAuthStores()

Create auth stores from the auth client in context.

function createAuthStores(): AuthStores<T> & { error: Readable<string | null> }

Returns: Auth stores and actions

createAuthStoresFromClient(client)

Create auth stores from a specific auth client.

Use this when you don't want to use context.

function createAuthStoresFromClient(client: AuthClient<T>): AuthStores<T>

• client — Auth client

Returns: Auth stores and actions

createCapacitorAppStore(options)

Create a Svelte store wrapping the Capacitor app coordinator.

Creates a CapacitorApp instance, subscribes to state changes, and auto-initializes. The returned store is readable and also exposes an initialize method for manual re-initialization.

function createCapacitorAppStore(options?: CapacitorAppOptions): CapacitorAppStore

• options — Capacitor app options

Returns: A readable store of CapacitorAppState with an initialize method

createChangePasswordStore()

Creates a change password store with async state tracking.

function createChangePasswordStore(): ChangePasswordStore

Returns: Change password promise store

createDeleteStore(url, config)

Creates a DELETE request store.

function createDeleteStore(url: string, config?: RequestConfig): HttpStore<T>

• url — The request endpoint URL.
• config — Optional request configuration such as headers or params.

Returns: A subscribable HTTP store for the DELETE request with execute and reset methods.

createDeviceStores()

Create device stores from the module-level device provider.

Device information is static (no reactive subscription needed), so this returns plain values rather than Svelte stores.

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

Returns: Device information and utility functions

createFieldStore(controller, name)

Create a readable store that tracks a single field's state.

function createFieldStore(controller: FormController<T>, name: K): Readable<FieldState<T[K]>>

• controller — Form controller
• name — Field name to track

Returns: Readable store of the field state

createFormStores(provider, options)

Create form stores from a form provider and options.

function createFormStores(provider: FormProvider, options: FormOptions<T>): FormStores<T>

• provider — Form provider instance
• options — Form creation options

Returns: Form stores and actions

createGetStore(url, config)

Creates a GET request store.

function createGetStore(url: string, config?: RequestConfig): HttpStore<T>

• url — The request endpoint URL.
• config — Optional request configuration such as headers or params.

Returns: A subscribable HTTP store for the GET request with execute and reset methods.

createHttpStore(method, url, config)

Create an HTTP request store.

function createHttpStore(
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
  url: string,
  config?: RequestConfig,
): HttpStore<T>

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

Returns: Store with state and actions

createHttpStoresFromClient(client)

Creates HTTP store factory methods bound to a specific client instance.

function createHttpStoresFromClient(client: HttpClient): HttpStoreFactory

• client — The HTTP client to use for all created stores.

Returns: An object with get, post, put, patch, and delete factory methods.

createI18nStores()

Create i18n stores from the i18n provider in context.

function createI18nStores(): I18nStores

Returns: I18n stores and actions

createI18nStoresFromProvider(provider)

Create i18n stores from a specific provider.

function createI18nStoresFromProvider(provider: I18nProvider): I18nStores

• provider — I18n provider

Returns: I18n stores and actions

createIsActiveStore(location, router, path, exact)

Create a derived store that checks if a path is active.

function createIsActiveStore(
  location: Readable<RouteLocation>,
  router: Router,
  path: string,
  exact?: boolean,
): Readable<boolean>

• location — A readable location store (from createRouterStores or createRouterStoresFromRouter)
• router — Router instance (for isActive check)
• path — Path to check
• exact — Whether to require exact match (default: false)

Returns: Readable store of whether the path is active

createLogger(config)

Create a logger with custom configuration.

function createLogger(config: LoggerConfig): Logger

• config — Logger configuration

Returns: Logger instance

createLoggerHelpers()

Create logger helpers from context.

function createLoggerHelpers(): LoggerHelpers

Returns: Logger helper functions

createLoggerHelpersFromProvider(provider)

Create logger helpers from a specific provider.

function createLoggerHelpersFromProvider(provider: LoggerProvider): LoggerHelpers

• provider — Logger provider

Returns: Logger helper functions

createLoginStore()

Creates a login store with async state tracking.

function createLoginStore(): LoginStore<T>

Returns: Login promise store

createOAuthHelpers(options)

Creates OAuth helpers for provider-based authentication flows.

When created in a browser, automatically handles OAuth callbacks by detecting code and state URL parameters and exchanging them for a session (a guarded no-op when there is no callback code in the URL).

Session establishment: the exchange result is applied to the resolved auth client (an explicit options.authClient, else the Svelte-context client when created during component initialization). 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 createOAuthHelpers(options?: OAuthOptions): OAuthHelpers

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

Returns: An object containing a readable providers store, URL builder, redirect function, and callback handler.

createPasswordResetStores()

Creates password reset stores with async state tracking.

function createPasswordResetStores(): PasswordResetStores

Returns: Password reset stores for request and confirm steps

createPatchStore(url, config)

Creates a PATCH request store.

function createPatchStore(url: string, config?: RequestConfig): HttpStore<T>

• url — The request endpoint URL.
• config — Optional request configuration such as headers or body data.

Returns: A subscribable HTTP store for the PATCH request with execute and reset methods.

createPlatformStores()

Create platform stores from the module-level platform info.

Platform information is static (no reactive subscription needed), so this returns plain values rather than Svelte stores.

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

Returns: Platform information and utility functions

createPostStore(url, config)

Creates a POST request store.

function createPostStore(url: string, config?: RequestConfig): HttpStore<T>

• url — The request endpoint URL.
• config — Optional request configuration such as headers or body data.

Returns: A subscribable HTTP store for the POST request with execute and reset methods.

createPromiseStore(asyncFn)

Creates a store that tracks async function state.

function createPromiseStore(asyncFn: T): PromiseStore<Awaited<ReturnType<T>>>

• asyncFn — The async function to track

Returns: Promise store with subscribe, call, cancel, and reset

createPushStores()

Create push notification stores from the module-level push provider.

function createPushStores(): {
  permission: Readable<PermissionStatus | null>
  token: Readable<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>
}

Returns: Push notification stores and actions

createPutStore(url, config)

Creates a PUT request store.

function createPutStore(url: string, config?: RequestConfig): HttpStore<T>

• url — The request endpoint URL.
• config — Optional request configuration such as headers or body data.

Returns: A subscribable HTTP store for the PUT request with execute and reset methods.

createRouterStores()

Create router stores from the router in context.

function createRouterStores(): RouterStores

Returns: Router stores and actions

createRouterStoresFromRouter(router)

Create router stores from a specific router.

function createRouterStoresFromRouter(router: Router): RouterStores

• router — Router instance

Returns: Router stores and actions

createSignupStore()

Creates a signup store with async state tracking.

function createSignupStore(): SignupStore<T>

Returns: Signup promise store

createStorageHelpers()

Create storage helper functions from context.

function createStorageHelpers(): StorageHelpers

Returns: Storage functions

createStorageStore(key, defaultValue)

Create a storage value store.

function createStorageStore(key: string, defaultValue?: T): StorageStore<T>

• key — Storage key
• defaultValue — Default value if not found

Returns: Store with value and actions

createStorageStoreFromProvider(storage, key, defaultValue)

Create storage store from a specific provider.

function createStorageStoreFromProvider(
  storage: StorageProvider,
  key: string,
  defaultValue?: T,
): StorageStore<T>

• storage — Storage provider
• key — Storage key
• defaultValue — Default value

Returns: Store with value and actions

createStoreAction(store, action)

Create a bound action for a store.

function createStoreAction(
  store: MoleculeStore<T>,
  action: (
    setState: MoleculeStore<T>['setState'],
    getState: MoleculeStore<T>['getState'],
  ) => (...args: Args) => R,
): (...args: Args) => R

• store — The store
• action — Action creator function

Returns: Bound action

createStoreReadable(store)

Create a readable Svelte store from a molecule store.

function createStoreReadable(store: MoleculeStore<T>): Readable<T>

• store — The molecule store

Returns: Readable Svelte store

createStoreSelector(store, selector)

Create a derived Svelte store with a selector.

function createStoreSelector(store: MoleculeStore<T>, selector: (state: T) => S): Readable<S>

• store — The molecule store
• selector — Selector function

Returns: Derived Svelte store

createThemeColorsStore(theme)

Create a derived store that returns just the theme colors.

function createThemeColorsStore(theme: Readable<Theme>): Readable<ThemeColors>

• theme — A readable theme store (from createThemeStores or createThemeStoresFromProvider)

Returns: Readable store of theme colors

createThemeStores()

Create theme stores from the theme provider in context.

function createThemeStores(): ThemeStores & { colors: Readable<Theme['colors']> }

Returns: Theme stores and actions

createThemeStoresFromProvider(provider)

Create theme stores from a specific theme provider.

function createThemeStoresFromProvider(provider: ThemeProvider): ThemeStores

• provider — Theme provider

Returns: Theme stores and actions

createVersionStores()

Create version stores from the module-level version provider.

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

Returns: Version stores and actions

createWatchStore(controller, name)

Create a readable store that tracks a single field's value.

function createWatchStore(controller: FormController<T>, name: K): Readable<T[K]>

• controller — Form controller
• name — Field name to watch

Returns: Readable store of the field value

getAuthClient()

Gets the auth client from Svelte context.

function getAuthClient(): AuthClient<T>

Returns: The auth client instance.

getChildLogger(name, context)

Create a child logger with additional context.

function getChildLogger(name: string, context: Record<string, unknown>): Logger

• name — Parent logger name
• context — Additional context

Returns: Child logger instance

getHttpClient()

Gets the HTTP client from Svelte context.

function getHttpClient(): HttpClient

Returns: The HTTP client instance.

getI18nProvider()

Gets the i18n provider from Svelte context.

function getI18nProvider(): I18nProvider

Returns: The i18n provider instance.

getLogger(name)

Get a logger instance.

function getLogger(name?: string): Logger

• name — Logger name

Returns: Logger instance

getLoggerProvider()

Gets the logger provider from Svelte context.

function getLoggerProvider(): LoggerProvider

Returns: The logger provider instance.

getRootLogger()

Get the root logger.

function getRootLogger(): Logger

Returns: Root logger instance

getRouter()

Gets the router from Svelte context.

function getRouter(): Router

Returns: The router instance.

getSetStore(store)

Get the setState function from a molecule store.

function getSetStore(
  store: MoleculeStore<T>,
): (partial: Partial<T> | ((state: T) => Partial<T>)) => void

• store — The molecule store

Returns: setState function

getStateProvider()

Gets the state provider from Svelte context.

function getStateProvider(): StateProvider

Returns: The state provider instance.

getStorageProvider()

Gets the storage provider from Svelte context.

function getStorageProvider(): StorageProvider

Returns: The storage provider instance.

getThemeProvider()

Gets the theme provider from Svelte context.

function getThemeProvider(): ThemeProvider

Returns: The theme provider instance.

setAuthContext(client)

Sets the auth context.

function setAuthContext(client: AuthClient<T>): void

• client — The auth client to store in Svelte context.

setHttpContext(client)

Sets the HTTP context.

function setHttpContext(client: HttpClient): void

• client — The HTTP client to store in Svelte context.

setI18nContext(provider)

Sets the i18n context.

function setI18nContext(provider: I18nProvider): void

• provider — The i18n provider to store in Svelte context.

setLoggerContext(provider)

Sets the logger context.

function setLoggerContext(provider: LoggerProvider): void

• provider — The logger provider to store in Svelte context.

setMoleculeContext(config)

Set all molecule providers in Svelte context.

Call this in your root layout/component.

function setMoleculeContext(config: MoleculeConfig): void

• config — Provider instances to register (state, auth, theme, router, i18n, http, storage, logger).

setRouterContext(router)

Sets the router context.

function setRouterContext(router: Router): void

• router — The router instance to store in Svelte context.

setStateContext(provider)

Sets the state context.

function setStateContext(provider: StateProvider): void

• provider — The state provider to store in Svelte context.

setStorageContext(provider)

Sets the storage context.

function setStorageContext(provider: StorageProvider): void

• provider — The storage provider to store in Svelte context.

setThemeContext(provider)

Sets the theme context.

function setThemeContext(provider: ThemeProvider): void

• provider — The theme provider to store in Svelte context.

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
• svelte ^4.0.0 || ^5.0.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

• svelte

• setMoleculeContext and every create*Stores factory use Svelte context — they are only legal during component initialization (the top level of a component <script>), never in module scope, after onMount, in event handlers, or in async callbacks. Wire the context in the ROOT layout so every route inherits it.

• Factories throw per missing service: the context carries ONLY the services you passed — createAuthStores() under a context without auth throws. Fix the setMoleculeContext config; don't wrap in try/catch.

• Results are Svelte stores — read them with the $ prefix ($isAuthenticated, $theme); actions (logout, toggleTheme, setTheme) are plain functions.

Translations

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