System APIs Overview
The perry/system module provides access to platform-native system features:
preferences, secure storage, notifications, dark-mode detection, audio
capture, and app introspection. Every snippet below is excerpted from
docs/examples/system/snippets.ts — CI
links the file on every PR.
// import {
// openURL, isDarkMode,
// preferencesGet, preferencesSet,
// keychainSave, keychainGet, keychainDelete,
// notificationSend,
// audioStart, audioStop, audioGetLevel, audioGetPeak, audioGetWaveform,
// } from "perry/system"
Available APIs
| Function | Description | Platforms |
|---|---|---|
openURL(url) | Open URL in default browser/app | All |
isDarkMode() | Check system dark mode | All |
getDeviceIdiom() | "phone", "pad", "mac", "tv", … | All |
getDeviceModel() | Device model identifier (e.g. "iPhone13,4") | All |
preferencesSet(key, value) | Store a preference (string or number) | All |
preferencesGet(key) | Read a preference (returns `string | number |
keychainSave(key, value) | Secure storage write | All |
keychainGet(key) | Secure storage read | All |
keychainDelete(key) | Secure storage remove | All |
notificationSend(title, body) | Local notification | All |
notificationCancel(id) | Cancel a scheduled notification | Apple |
notificationOnTap(cb) | Handle banner taps | Apple |
notificationRegisterRemote(cb) / notificationOnReceive(cb) | Push (APNs) | iOS, macOS |
audioStart() / audioStop() | Microphone capture | All |
audioGetLevel() / audioGetPeak() | RMS / peak amplitude (0..1) | All |
audioGetWaveform(n) | Recent waveform samples for visualization | All |
audioSetOutputFilename(p) / audioStartRecording() / audioStopRecording() | Capture mic to a WAV file | All native |
geolocationGetCurrent(ok, err) | One-shot device position | iOS, Android, macOS |
geolocationWatch(cb) / geolocationStopWatch(id) | Subscribe to position updates | iOS, Android, macOS |
geolocationRequestPermission(cb) | Request location permission | iOS, Android, macOS |
imagePickerPick(max, multi, cb) | Native photo-library picker | iOS, Android, macOS |
registerTask(id, fn) / schedule(id, …) / cancel(id) | Deferred / periodic background work — see perry/background | iOS, Android, tvOS, visionOS, watchOS, macOS |
Clipboard lives in
perry/ui(notperry/system): importclipboardReadandclipboardWritefrom there.
Quick Example
if (isDarkMode()) {
console.log("Dark mode is active")
}
// Strings and numbers round-trip natively — no manual stringification needed.
preferencesSet("theme", "dark")
preferencesSet("font-size", 14)
const theme = preferencesGet("theme") // string | number | undefined
const fontSize = preferencesGet("font-size") // → 14 (number)
if (typeof theme === "string") {
console.log(`saved theme: ${theme}`)
}
if (typeof fontSize === "number") {
console.log(`saved font-size: ${fontSize}`)
}
openURL("https://example.com")