API reference#

Exports of @sigx/lynx-core v0.20.0.

The package has a single public entry point. Everything below is imported from @sigx/lynx-core. All exports work on both iOS and Android.

import {
  getModule,
  callSync,
  callAsync,
  isModuleAvailable,
  guardModule,
  base64ToArrayBuffer,
  arrayBufferToBase64,
  Platform,
  OS,
  select,
  DeviceInfo,
} from '@sigx/lynx-core';
import type {
  PermissionStatus,
  PermissionResponse,
  PlatformOS,
  PlatformSelectSpec,
  DeviceInfoResult,
  IosDeviceInfo,
  AndroidDeviceInfo,
} from '@sigx/lynx-core';

Everything here is also re-exported from the @sigx/lynx barrel, so app code can import Platform, DeviceInfo and friends straight from @sigx/lynx.

The bridge helpers read from a global NativeModules object that the Lynx runtime injects — a Record whose properties are the registered native modules. It is not itself an export; it is the surface getModule and isModuleAvailable inspect.

Functions#

getModule#

export function getModule(name: string): Record<string, (...args: any[]) => any>

Returns the native module proxy injected by the Lynx runtime as NativeModules[name]. Throws a descriptive, actionable error if the module is unavailable — the message names the package to install (mapping known module names through an internal table, e.g. Haptics to @sigx/lynx-haptics) and points at sigx prebuild.

• name — the registered native module name (for example 'Haptics', 'Camera').
• Returns — the module proxy, an object whose properties are its native methods. Never returns undefined; it throws when the module is missing.
• Platform — iOS and Android.

callSync#

export function callSync<T = void>(module: string, method: string, ...args: any[]): T

Invokes a synchronous bridge method on the named module and returns its result directly, cast to T.

• module — the native module name.
• method — the method to invoke on that module.
• ...args — arguments forwarded to the native method.
• Returns — the native method's return value, typed as T (defaults to void).
• Platform — iOS and Android.

callAsync#

export function callAsync<T = any>(module: string, method: string, ...args: any[]): Promise<T>

Invokes an async bridge method that takes a result callback as its last argument, wrapping it in a Promise that resolves with the callback's value.

The native method is expected to call a node-style callback that receives only a success value, not (err, res). There is no native-side error channel in this signature, so the returned Promise only rejects if the synchronous invocation itself throws.

• module — the native module name.
• method — the async method to invoke.
• ...args — arguments forwarded to the native method (the result callback is appended automatically).
• Returns — a Promise<T> that resolves with the callback's value.
• Platform — iOS and Android.

isModuleAvailable#

export function isModuleAvailable(name: string): boolean

Feature-detects whether a native module is registered in the current runtime, without throwing. Use this when you want to degrade gracefully rather than fail.

• name — the native module name.
• Returns — true if the module is registered, otherwise false.
• Platform — iOS and Android.

guardModule#

export function guardModule(name: string): void

Throws the descriptive "module not available" error if the module is not linked; meant for early failure at module-package entry points. Call it at the top of each public wrapper function so missing native linkage fails loudly and early.

• name — the native module name to assert.
• Returns — nothing. Throws if the module is missing.
• Platform — iOS and Android.

base64ToArrayBuffer#

export function base64ToArrayBuffer(b64: string): ArrayBuffer

Decodes a base64 string into an ArrayBuffer. Uses atob when available, otherwise a pure-JS fallback decoder that tolerates whitespace and newlines, strips trailing padding, and sizes the output exactly (no trailing zero padding).

• b64 — the base64-encoded string.
• Returns — the decoded bytes as an ArrayBuffer.
• Platform — iOS and Android.

arrayBufferToBase64#

export function arrayBufferToBase64(buf: ArrayBuffer | ArrayBufferView): string

Encodes an ArrayBuffer or typed-array view to base64 for native transport. Honors a view's byteOffset/byteLength — it encodes only the view's window, not the whole backing buffer — and chunks the encode (at 0x8000 bytes) to avoid call-stack limits on large payloads. Falls back to a pure-JS encoder that produces output identical to the native path when btoa is unavailable.

• buf — an ArrayBuffer, Uint8Array, or any ArrayBufferView.
• Returns — the base64-encoded string.
• Platform — iOS and Android.

Platform#

Synchronous platform information and a select() helper, read once from the Lynx SystemInfo global at module load. Use it for runtime branching between iOS and Android (which share one native bundle) and for reading display metrics.

Platform#

const Platform: {
  /** `'ios' | 'android' | 'web'`. */
  OS: PlatformOS;
  /** OS version string, e.g. '17.4' / '14'. Empty when unknown. */
  Version: string;
  /** Best-effort iPad detection (iOS + logical min edge ≥ 600dp). */
  isPad: boolean;
  /** Device pixel ratio (physical px per dp). `1` when unknown. */
  pixelRatio: number;
  /** Physical screen width in px. `0` when unknown. */
  pixelWidth: number;
  /** Physical screen height in px. `0` when unknown. */
  pixelHeight: number;
  /** Lynx engine version string. Empty when unknown. */
  engineVersion: string;
  /** JS runtime, e.g. 'v8' | 'jsc' | 'quickjs'. Empty when unknown. */
  runtimeType: string;
  select: typeof select;
};

Fields fall back to neutral defaults under tests, SSR, and non-Lynx hosts. On the web bundle, OS is 'web'; on native it is 'ios' or 'android', discriminated from SystemInfo.

• Platform — iOS, Android and web.

Platform.select#

export function select<T>(spec: PlatformSelectSpec<T> & { default: T }): T;
export function select<T>(spec: PlatformSelectSpec<T>): T | undefined;

Picks a value for the current platform. Precedence: the exact OS key (ios / android / web) → native (matches ios/android only) → default. Presence-based, not truthiness — an explicit undefined for the matching key is honored. Providing default makes the return type non-optional T; omitting it makes it T | undefined.

const padding = Platform.select({ ios: 12, android: 8, default: 10 }); // number
const transport = Platform.select({ web: webTransport, native: nativeTransport });

• Platform — iOS, Android and web.

OS#

export const OS: PlatformOS; // 'ios' | 'android' | 'web'

The bare current-platform constant, also exposed as Platform.OS. Note that Platform.OS === 'web' is a runtime check and does not tree-shake — for build-time, tree-shakeable web↔native splitting, branch on the __WEB__ / __NATIVE__ defines (see the platform-specific code guide).

• Platform — iOS, Android and web.

Device info#

Async, native-backed device metadata served by core's own SigxCore native module. Complements the synchronous Platform surface.

DeviceInfo#

const DeviceInfo: {
  getInfo(): Promise<DeviceInfoResult>;
  isAvailable(): boolean;
};

• Platform — iOS and Android.

DeviceInfo.getInfo#

Resolves a single snapshot of the device's hardware, OS, screen and app metadata as a platform-discriminated DeviceInfoResult. It calls the native SigxCore module's getDeviceInfo method. Values are a point-in-time snapshot and are not reactive — call it again to refresh.

getInfo(): Promise<DeviceInfoResult>

• Returns — a Promise resolving to a DeviceInfoResult. Switch on its platform field to read the per-platform extras type-safely.
• Platform — iOS and Android.

DeviceInfo.isAvailable#

isAvailable(): boolean

Returns whether the native SigxCore module is registered in the current build (delegates to isModuleAvailable). Use it to guard getInfo() where the module may not be linked.

• Platform — iOS and Android.

Types#

PermissionStatus#

export type PermissionStatus = 'granted' | 'denied' | 'undetermined' | 'blocked'

Permission status string union returned by permission-using native modules. Type-only export.

• Platform — iOS and Android.

PermissionResponse#

export interface PermissionResponse {
  /** Current permission status. */
  status: PermissionStatus;
  /**
   * Whether the app can show the OS permission dialog again.
   * `false` when the user selected "Don't ask again" (Android) or
   * after the first denial (iOS — user must go to Settings).
   */
  canAskAgain: boolean;
}

The shape returned by requestPermission() / getPermissionStatus() across permission-using modules. Combines a status with whether the OS dialog can be shown again. Type-only export.

• status — the current PermissionStatus.
• canAskAgain — false once the user picked "Don't ask again" on Android, or after the first denial on iOS.
• Platform — iOS and Android.

PlatformOS#

export type PlatformOS = 'ios' | 'android' | 'web'

The current platform string — the type of Platform.OS and OS. Type-only export.

PlatformSelectSpec#

export interface PlatformSelectSpec<T> {
  ios?: T;
  android?: T;
  web?: T;
  /** Matches any native platform (ios/android), after the exact-OS key. */
  native?: T;
  /** Fallback when no platform key matches. */
  default?: T;
}

The spec object accepted by Platform.select. Type-only export.

DeviceInfoResult#

The platform-discriminated shape resolved by DeviceInfo.getInfo — a guaranteed common core plus per-platform extras, discriminated by platform.

export type DeviceInfoResult = IosDeviceInfo | AndroidDeviceInfo;

interface DeviceInfoCommon {
  platform: 'ios' | 'android'; // discriminant
  manufacturer: string;
  model: string;               // Android: friendly name ('Pixel 9'); iOS: generic ('iPhone')
  brand: string;
  systemName: string;
  systemVersion: string;
  appVersion: string;
  deviceId: string;            // iOS: stable per-vendor UUID; Android: Build.ID (a build id)
  screenWidth: number;         // density-independent points (dp/pt) on BOTH platforms
  screenHeight: number;        // density-independent points (dp/pt) on BOTH platforms
  screenScale: number;         // dp→px multiplier (physical px ≈ screenWidth * screenScale)
}

export interface IosDeviceInfo extends DeviceInfoCommon {
  platform: 'ios';
  modelName: string;           // hardware identifier, e.g. 'iPhone16,2'
  appBuildNumber: string;      // CFBundleVersion
  bundleId: string;
}

export interface AndroidDeviceInfo extends DeviceInfoCommon {
  platform: 'android';
  sdkVersion: number;          // Build.VERSION.SDK_INT
  appPackage: string;
}

Field semantics worth noting:

• screenWidth / screenHeight are density-independent points (dp/pt) on both platforms; screenScale is the dp→px multiplier, so physical pixels ≈ screenWidth * screenScale.
• model is a friendly name on Android but generic ('iPhone') on iOS — the iOS hardware identifier lives in the iOS-only modelName.
• deviceId is a per-vendor stable UUID on iOS but Build.ID (a build id, not a stable device id) on Android.

Type-only export. Platform — iOS and Android.

See also#

• Usage — practical patterns for wrapping native modules.
• Overview — what the package is and where it fits.