One JS API, honest platform behavior

Part 10 · Further improvements

One JS API, honest platform behavior

Prerequisites: 05-expo-module-contract, 08-builds-and-ota

The public API can be shared; platform lifecycle and capability checks remain separate. Nodes: JS contract, Android path, iOS path, Shared tests, Device checks. — The public API can be shared; platform lifecycle and capability checks remain separate. [S07] [S08] [S09]

Mental model verified

An API can present the same JS method name on both platforms while Android Activity lifecycle and iOS app lifecycle hooks differ. A good abstraction states common behavior and surfaces capability differences explicitly.

[S07]

Worked example synthesis

For a secure-document scan wrapper, define a discriminated result for success, user cancellation, denied permission and unsupported capability. Implement dismissal/cleanup separately for Android and iOS, then test each path on devices.

[S07]

Engineering choice synthesis

Keep the TS facade stable; make platform-specific native tests and contract tests for returned shapes. Version the binary and JS API together when native behavior changes.

[S07] [S09]

Pitfall and next step synthesis

A simulator success can hide hardware permission and lifecycle problems. Add device checks for background/foreground, rotation or activity recreation where relevant, and app termination.

[S07] [S08]

Keep this: Share the public contract, then test platform-specific permission, lifecycle, threading and error behavior independently.

Check yourself: Does the same method name guarantee identical Android and iOS semantics?

No. Native capabilities and lifecycles differ; the wrapper should document differences and normalize only what can be normalized honestly.