API reference#

Exports of @sigx/lynx-file-system v0.35.0.

Everything ships under a single FileSystem namespace object, plus the FileInfo type. All exports are available on both iOS and Android.

import { FileSystem } from '@sigx/lynx-file-system';
import type { FileInfo } from '@sigx/lynx-file-system';

Namespace#

FileSystem#

The object bundling all file system operations, backed by the native FileSystem module. Scoped to the app sandbox — no broad storage permissions are required.

const FileSystem: {
  readFile(path: string): Promise<string>;
  readFileBase64(path: string): Promise<string>;
  readFileAsArrayBuffer(path: string): Promise<ArrayBuffer>;
  writeFile(path: string, content: string): Promise<void>;
  deleteFile(path: string): Promise<void>;
  getInfo(path: string): Promise<FileInfo>;
  getDocumentDirectory(): string;
  getCacheDirectory(): string;
  isAvailable(): boolean;
};

Platform: iOS and Android.

Across both platforms, plain relative paths resolve against the document directory, absolute paths are used as-is, and file:// URIs (such as those returned by pickers) are accepted.

Functions#

FileSystem.readFile#

Reads a file as UTF-8 text.

readFile(path: string): Promise<string>

• path — file path. Relative paths resolve against the document directory.
• Returns — a Promise resolving to the file's text content.

Rejects with a SigxError (code: 'native_error') if the file does not exist or can't be read.

Platform: iOS and Android.

FileSystem.readFileBase64#

Reads the raw bytes of a file, returned base64-encoded.

readFileBase64(path: string): Promise<string>

• path — file path. Accepts plain paths, file:// URIs, and (Android only) content:// URIs, which are read via the ContentResolver.
• Returns — a Promise resolving to the base64-encoded file contents.

Throws a SigxError (code: 'native_error') prefixed [@sigx/lynx-file-system] on read failure, and also when native returns anything other than a base64 string. The whole file is materialized in memory and base64 is roughly 33% larger crossing the bridge — use for small and medium files only.

Platform: iOS and Android.

FileSystem.readFileAsArrayBuffer#

Reads a file and decodes its bytes into an ArrayBuffer.

readFileAsArrayBuffer(path: string): Promise<ArrayBuffer>

• path — file path (same resolution rules as readFileBase64).
• Returns — a Promise resolving to an ArrayBuffer of the file's bytes.

A JS-side helper that calls readFileBase64 and decodes the result. Same in-memory and size caveats apply.

Platform: iOS and Android.

FileSystem.writeFile#

Writes UTF-8 text to a file, creating parent directories as needed (atomically on iOS).

writeFile(path: string, content: string): Promise<void>

• path — destination file path.
• content — UTF-8 text to write.
• Returns — a Promise that resolves when the write completes. Rejects when the write fails — an unwritable path or a full volume.

Text-only — there is no binary write API.

Platform: iOS and Android.

FileSystem.deleteFile#

Deletes a file.

deleteFile(path: string): Promise<void>

• path — file path to delete.
• Returns — a Promise that resolves when the delete completes.

Deleting a path that doesn't exist is a no-op on both platforms. A real failure — a read-only path, or a non-empty directory on Android (iOS removes those recursively) — rejects. A picker's content:// URI is not a path the app owns, so deleting one rejects on Android rather than reporting a success that deleted nothing; file:// URIs are unaffected.

Platform: iOS and Android.

FileSystem.getInfo#

Returns metadata for a path.

getInfo(path: string): Promise<FileInfo>

• path — file or directory path.
• Returns — a Promise resolving to a FileInfo with all five fields populated on both platforms. A missing path resolves exists: false with size, modifiedAt zeroed and isDirectory: false — check exists for presence.

A path that exists but can't be stat'd — a protected-data file on a locked iOS device, a permission-denied path — rejects rather than resolving something that would read as an empty file.

Platform: iOS and Android.

FileSystem.getDocumentDirectory#

Returns the app's persistent document directory path. Synchronous.

getDocumentDirectory(): string

• Returns — the absolute path to the document directory.

Data here survives app updates and is included in iCloud / Android backup. iOS: NSDocumentDirectory; Android: context.filesDir.

Platform: iOS and Android.

FileSystem.getCacheDirectory#

Returns the app's cache directory path. Synchronous.

getCacheDirectory(): string

• Returns — the absolute path to the cache directory.

Disposable storage the OS may purge under disk pressure — use the document directory for data that must persist. iOS: NSCachesDirectory; Android: context.cacheDir.

Platform: iOS and Android.

FileSystem.isAvailable#

Reports whether the native FileSystem module is registered in the current build.

isAvailable(): boolean

• Returns — true if the native module is available, otherwise false.

Platform: iOS and Android.

Types#

FileInfo#

Metadata returned by getInfo.

interface FileInfo {
  uri: string;
  size: number;
  exists: boolean;
  isDirectory: boolean;
  modifiedAt: number; // epoch milliseconds
}

Platform: iOS and Android.