onnxAsset.ts

Purpose

This module handles the full lifecycle of ONNX model assets in an Expo React Native environment: locating bundled model files, copying them to the device cache directory on first use, and creating reusable InferenceSession instances.

Its responsibilities include:

• Accepting a typed OnnxSpec descriptor for each model
• Checking the Expo file system cache for an already-extracted model file
• Downloading and copying the Expo asset to the cache directory on first use
• Creating an InferenceSession from the cached file URI
• Maintaining an in-memory session cache keyed by OnnxSpec.key
• Providing utility helpers for extracting outputs from session results
• Handling iOS file:// URI requirements with a two-attempt fallback strategy

Invariants

Cache Directory Availability

FileSystem.cacheDirectory must be non-null before any asset operation is attempted.

A missing cache directory throws an Error immediately.

One Session Per Key

At most one InferenceSession is held per OnnxSpec.key within the process lifetime.

Subsequent calls with the same key return the cached session without disk access or session recreation.

Asset Download on First Use

If the model file does not exist on disk, the module:

1. Resolves the Expo asset via Asset.fromModule(assetModule)
2. Calls asset.downloadAsync() to make the localUri available
3. Copies the asset from localUri to the cache destination

A missing localUri after download throws an Error with the filename.

URI Normalization

The returned model path is always prefixed with file:// for compatibility with ORT on iOS.

If session creation fails with the file:// URI, one retry is attempted with the prefix stripped.

Variants

Scalar Output Shape

readScalar accepts any ORT output tensor whose .data field is either:

• a typed array (reads index [0])
• a bare number

Non-numeric or NaN values throw a descriptive Error.

Output Key Selection

pickOutputKey prefers session.outputNames[0] when available.

If outputNames is absent or empty, it falls back to the first key of the outputs object.

Exports

OnnxSpec

type OnnxSpec = {
	key: string;
	assetModule: number;
	filename: string;
};

Descriptor for a single ONNX model asset:

getOnnxSession(...)

async function getOnnxSession(spec: OnnxSpec): Promise<InferenceSession>

Returns a cached or newly created InferenceSession for the given model spec.

Parameters

Returns

A Promise<InferenceSession> ready to run inference.

Throws

Throws when:

• the cache directory is unavailable
• the Expo asset download fails or yields no localUri
• file copy to cache fails
• both file:// and bare-path session creation attempts fail

pickOutputKey(...)

function pickOutputKey(
	session: InferenceSession,
	outputs: Record<string, any>,
): string

Returns the preferred output tensor key from a session run result.

readScalar(...)

function readScalar(outputTensor: any): number

Extracts a single numeric scalar from an ORT output tensor.

Throws

Throws when the extracted value is not a finite number or is NaN.