@molecule/app-battery

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.

Battery status interface for molecule.dev.

Provides a unified API for battery monitoring across platforms: level, charging state, low-battery callbacks, and capability discovery, plus formatting helpers (toPercentage, getLevelText, formatRemainingTime) and a createBatteryAwareExecutor for deferring heavy work on low charge.

Quick Start

import type { BatteryProvider } from '@molecule/app-battery'
import { setProvider, getStatus, onLow, toPercentage } from '@molecule/app-battery'

// No prebuilt provider bond ships yet — supply your platform implementation
// (web: navigator.getBattery, Chromium-only; native: the platform battery API).
const myBatteryProvider = {} as BatteryProvider // stand-in for your implementation
setProvider(myBatteryProvider)

const status = await getStatus()
console.log(`Battery at ${toPercentage(status.level)}%`)

const stop = onLow((level) => {
  console.warn(`Low battery: ${toPercentage(level)}%`)
}, 0.15)
stop()

Type

native

Installation

npm install @molecule/app-battery @molecule/app-bond @molecule/app-i18n

API

Interfaces

BatteryCapabilities

Battery capabilities

interface BatteryCapabilities {
  /** Whether battery monitoring is supported */
  supported: boolean
  /** Whether charging time estimation is available */
  hasChargingTime: boolean
  /** Whether discharging time estimation is available */
  hasDischargingTime: boolean
  /** Whether low power mode detection is available */
  hasLowPowerMode: boolean
  /** Whether charging state detail is available */
  hasChargingState: boolean
}

BatteryChangeEvent

Battery change event

interface BatteryChangeEvent {
  /** Previous status */
  previous: BatteryStatus
  /** Current status */
  current: BatteryStatus
  /** Whether level changed */
  levelChanged: boolean
  /** Whether charging state changed */
  chargingChanged: boolean
}

BatteryProvider

Battery provider interface

interface BatteryProvider {
  /**
   * Get current battery status
   * @returns The current battery status including level, charging state, and time estimates.
   */
  getStatus(): Promise<BatteryStatus>

  /**
   * Get current battery level
   * @returns Level (0-1)
   */
  getLevel(): Promise<number>

  /**
   * Check if device is charging
   * @returns Whether the device is currently charging.
   */
  isCharging(): Promise<boolean>

  /**
   * Check if low power mode is enabled
   * @returns Whether low power mode is currently active.
   */
  isLowPowerMode(): Promise<boolean>

  /**
   * Listen for battery status changes
   * @param callback - Called when battery status changes
   * @returns Unsubscribe function
   */
  onChange(callback: (event: BatteryChangeEvent) => void): () => void

  /**
   * Listen for charging state changes
   * @param callback - Called when charging state changes
   * @returns Unsubscribe function
   */
  onChargingChange(callback: (isCharging: boolean) => void): () => void

  /**
   * Listen for low battery
   * @param callback - Called when battery goes low
   * @param threshold - Threshold (default: 0.2)
   * @returns Unsubscribe function
   */
  onLow(callback: (level: number) => void, threshold?: number): () => void

  /**
   * Listen for critical battery
   * @param callback - Called when battery goes critical
   * @param threshold - Threshold (default: 0.05)
   * @returns Unsubscribe function
   */
  onCritical(callback: (level: number) => void, threshold?: number): () => void

  /**
   * Get battery capabilities
   * @returns The battery capabilities indicating supported monitoring features.
   */
  getCapabilities(): Promise<BatteryCapabilities>
}

BatteryStatus

Device battery status: level (0–1), charging state, time estimates, and low/critical flags.

interface BatteryStatus {
  /** Battery level (0-1) */
  level: number
  /** Whether device is charging */
  isCharging: boolean
  /** Detailed charging state */
  chargingState: ChargingState
  /** Estimated time to full charge (seconds, if charging) */
  chargingTime?: number
  /** Estimated time to discharge (seconds, if discharging) */
  dischargingTime?: number
  /** Whether battery is in low power mode */
  isLowPowerMode?: boolean
  /** Whether battery level is low (< 20%) */
  isLow: boolean
  /** Whether battery level is critical (< 5%) */
  isCritical: boolean
}

BatteryThresholds

Battery level thresholds

interface BatteryThresholds {
  /** Low battery threshold (default: 0.2) */
  low: number
  /** Critical battery threshold (default: 0.05) */
  critical: number
}

Types

ChargingState

Battery charging state

type ChargingState =
  | 'charging' // Currently charging
  | 'discharging' // Running on battery
  | 'full' // Fully charged
  | 'not-charging' // Not charging (plugged in but not charging)
  | 'unknown'

Functions

createBatteryAwareExecutor(minimumLevel)

Create a battery-aware task executor

function createBatteryAwareExecutor(minimumLevel?: number): {
  execute<T>(task: () => T | Promise<T>, fallback?: () => T | Promise<T>): Promise<T | undefined>
  canExecute(): Promise<boolean>
}

• minimumLevel — Minimum battery level to execute (0-1)

Returns: An executor object with execute and canExecute methods gated by battery level.

formatRemainingTime(seconds, t)

Format remaining time

function formatRemainingTime(
  seconds: number,
  t?: (
    key: string,
    values?: Record<string, unknown>,
    options?: { defaultValue?: string },
  ) => string,
): string

• seconds — Remaining time in seconds
• t — Optional translation function for localized formatting

Returns: A human-readable time string (e.g., "2h 15m" or "30m"), or "Unknown" if the value is not finite.

getBatteryIcon(status)

Get battery icon name based on level and charging state

function getBatteryIcon(status: BatteryStatus): string

• status — Battery status

Returns: The icon name corresponding to the battery level and charging state.

getCapabilities()

Get the platform's battery monitoring capabilities.

function getCapabilities(): Promise<BatteryCapabilities>

Returns: The battery capabilities indicating which monitoring features are available.

getChargingStateText(state, t)

Get charging state description

function getChargingStateText(
  state: ChargingState,
  t?: (
    key: string,
    values?: Record<string, unknown>,
    options?: { defaultValue?: string },
  ) => string,
): string

• state — Charging state
• t — Optional translation function for localized descriptions

Returns: A human-readable label for the charging state (e.g., "Charging", "On Battery").

getLevel()

Get current battery level

function getLevel(): Promise<number>

Returns: The battery level as a decimal between 0 and 1.

getLevelText(level)

Get battery level as text

function getLevelText(level: number): string

• level — Battery level (0-1)

Returns: The battery level formatted as a percentage string (e.g., "85%").

getProvider()

Get the current battery provider

function getProvider(): BatteryProvider

Returns: The active battery provider instance.

getStatus()

Get current battery status

function getStatus(): Promise<BatteryStatus>

Returns: The current battery status including level, charging state, and time estimates.

hasProvider()

Check if a battery provider is set

function hasProvider(): boolean

Returns: Whether a battery provider has been registered.

isAboveThreshold(level, threshold)

Check if battery level is above threshold

function isAboveThreshold(level: number, threshold: number): boolean

• level — Battery level (0-1)
• threshold — Threshold (0-1)

Returns: Whether the battery level exceeds the given threshold.

isCharging()

Check if the device is currently charging.

function isCharging(): Promise<boolean>

Returns: Whether the device is charging.

isLowPowerMode()

Check if the device has low power mode enabled.

function isLowPowerMode(): Promise<boolean>

Returns: Whether low power mode is active.

onChange(callback)

Listen for battery status changes.

function onChange(callback: (event: BatteryChangeEvent) => void): () => void

• callback — Called with a BatteryChangeEvent when level or charging state changes.

Returns: A function that unsubscribes the listener when called.

onChargingChange(callback)

Listen for charging state changes.

function onChargingChange(callback: (isCharging: boolean) => void): () => void

• callback — Called with a boolean indicating whether the device started or stopped charging.

Returns: A function that unsubscribes the listener when called.

onCritical(callback, threshold)

Listen for critical battery events. Fires when level drops below the critical threshold.

function onCritical(callback: (level: number) => void, threshold?: number): () => void

• callback — Called with the current battery level (0-1) when it drops below threshold.
• threshold — Battery level threshold (default: 0.05).

Returns: A function that unsubscribes the listener when called.

onLow(callback, threshold)

Listen for low battery events. Fires when level drops below the threshold.

function onLow(callback: (level: number) => void, threshold?: number): () => void

• callback — Called with the current battery level (0-1) when it drops below threshold.
• threshold — Battery level threshold (default: 0.2).

Returns: A function that unsubscribes the listener when called.

setProvider(provider)

Set the battery provider

function setProvider(provider: BatteryProvider): void

• provider — BatteryProvider implementation

toPercentage(level)

Convert battery level to percentage

function toPercentage(level: number): number

• level — Battery level (0-1)

Returns: The battery level as a rounded integer percentage (0-100).

waitForLevel(targetLevel, options)

Wait for battery to reach a level

function waitForLevel(
  targetLevel: number,
  options?: { timeout?: number; checkInterval?: number },
): Promise<boolean>

• targetLevel — Target level (0-1)
• options — Polling and timeout options
• options.timeout — Maximum time to wait in milliseconds (0 for no timeout)
• options.checkInterval — Interval between level checks in milliseconds

Returns: Whether the target level was reached before timeout.

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-i18n ^1.0.1

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• Wire with setProvider() or bond('battery', provider) — this core delegates to the shared @molecule/app-bond registry, so both write the same slot; the core's own setProvider() is always correct.

• No prebuilt provider bond exists for this interface yet — implement BatteryProvider yourself. Ignore any runtime error text suggesting a -capacitor package; none ships.

• Web support is narrow: navigator.getBattery() exists only in Chromium browsers. Gate the feature on getCapabilities()/hasProvider() and design for absence.

• level is 0-1, not 0-100 — use toPercentage()/getLevelText() for display.

Translations

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