@symbiote-native/file-system 0.1.0

package/src/core/native-module.ts

@@ -0,0 +1,99 @@
+import {
+  requireOptionalNativeModule,
+  type EventSubscription,
+} from 'expo-modules-core';
+
+import type {
+  IFileSystemDeletingOptions,
+  IFileSystemDownloadOptions,
+  IFileSystemDownloadResult,
+  IFileSystemFileInfo,
+  IFileSystemInfoOptions,
+  IFileSystemMakeDirectoryOptions,
+  IFileSystemRelocatingOptions,
+  IFileSystemRequestDirectoryPermissionsResult,
+  IFileSystemUploadOptions,
+  IFileSystemUploadResult,
+  IFileSystemWritingOptions,
+} from './types';
+
+export type INativeFileSystemModule = {
+  documentDirectory: string | null;
+  cacheDirectory: string | null;
+  bundleDirectory: string | null;
+
+  getInfoAsync?: (
+    fileUri: string,
+    options: IFileSystemInfoOptions,
+  ) => Promise<IFileSystemFileInfo>;
+  readAsStringAsync?: (
+    fileUri: string,
+    options: Record<string, unknown>,
+  ) => Promise<string>;
+  getContentUriAsync?: (fileUri: string) => Promise<string>;
+  writeAsStringAsync?: (
+    fileUri: string,
+    contents: string,
+    options: IFileSystemWritingOptions,
+  ) => Promise<void>;
+  deleteAsync?: (
+    fileUri: string,
+    options: IFileSystemDeletingOptions,
+  ) => Promise<void>;
+  moveAsync?: (options: IFileSystemRelocatingOptions) => Promise<void>;
+  copyAsync?: (options: IFileSystemRelocatingOptions) => Promise<void>;
+  makeDirectoryAsync?: (
+    fileUri: string,
+    options: IFileSystemMakeDirectoryOptions,
+  ) => Promise<void>;
+  readDirectoryAsync?: (fileUri: string) => Promise<string[]>;
+  getFreeDiskStorageAsync?: () => Promise<number>;
+  getTotalDiskCapacityAsync?: () => Promise<number>;
+  downloadAsync?: (
+    uri: string,
+    fileUri: string,
+    options: IFileSystemDownloadOptions,
+  ) => Promise<IFileSystemDownloadResult>;
+  uploadAsync?: (
+    url: string,
+    fileUri: string,
+    options: IFileSystemUploadOptions,
+  ) => Promise<IFileSystemUploadResult>;
+  networkTaskCancelAsync?: (uuid: string) => Promise<void>;
+  addListener?: (
+    eventName: string,
+    callback: (event: unknown) => void,
+  ) => EventSubscription;
+  uploadTaskStartAsync?: (
+    url: string,
+    fileUri: string,
+    uuid: string,
+    options: IFileSystemUploadOptions,
+  ) => Promise<IFileSystemUploadResult | undefined | null>;
+  downloadResumableStartAsync?: (
+    url: string,
+    fileUri: string,
+    uuid: string,
+    options: IFileSystemDownloadOptions,
+    resumeData?: string,
+  ) => Promise<IFileSystemDownloadResult | undefined>;
+  downloadResumablePauseAsync?: (
+    uuid: string,
+  ) => Promise<{ resumeData?: string } | undefined>;
+  requestDirectoryPermissionsAsync?: (
+    initialFileUrl: string | null,
+  ) => Promise<IFileSystemRequestDirectoryPermissionsResult>;
+  readSAFDirectoryAsync?: (dirUri: string) => Promise<string[]>;
+  makeSAFDirectoryAsync?: (
+    parentUri: string,
+    dirName: string,
+  ) => Promise<string>;
+  createSAFFileAsync?: (
+    parentUri: string,
+    fileName: string,
+    mimeType: string,
+  ) => Promise<string>;
+};
+
+export const expoFileSystem =
+  requireOptionalNativeModule<INativeFileSystemModule>('ExponentFileSystem');

package/src/core/types.ts

@@ -0,0 +1,135 @@
+export enum FileSystemSessionType {
+  BACKGROUND = 0,
+  FOREGROUND = 1,
+}
+
+export enum FileSystemUploadType {
+  BINARY_CONTENT = 0,
+  MULTIPART = 1,
+}
+
+export type IFileSystemDownloadOptions = {
+  md5?: boolean;
+  cache?: boolean;
+  headers?: Record<string, string>;
+  sessionType?: FileSystemSessionType;
+};
+
+export type IFileSystemHttpResult = {
+  headers: Record<string, string>;
+  status: number;
+  mimeType: string | null;
+};
+
+export type IFileSystemDownloadResult = IFileSystemHttpResult & {
+  uri: string;
+  md5?: string;
+};
+
+export type IFileSystemAcceptedUploadHttpMethod = 'POST' | 'PUT' | 'PATCH';
+
+export type IFileSystemUploadOptionsBinary = {
+  uploadType?: FileSystemUploadType;
+};
+
+export type IFileSystemUploadOptionsMultipart = {
+  uploadType: FileSystemUploadType;
+  fieldName?: string;
+  mimeType?: string;
+  parameters?: Record<string, string>;
+};
+
+export type IFileSystemUploadOptions = (
+  IFileSystemUploadOptionsBinary | IFileSystemUploadOptionsMultipart
+) & {
+  headers?: Record<string, string>;
+  httpMethod?: IFileSystemAcceptedUploadHttpMethod;
+  sessionType?: FileSystemSessionType;
+};
+
+export type IFileSystemUploadResult = IFileSystemHttpResult & {
+  body: string;
+};
+
+export type IFileSystemNetworkTaskProgressCallback<
+  T extends IFileSystemDownloadProgressData | IFileSystemUploadProgressData,
+> = (data: T) => void;
+
+export type IFileSystemDownloadProgressData = {
+  totalBytesWritten: number;
+  totalBytesExpectedToWrite: number;
+};
+
+export type IFileSystemUploadProgressData = {
+  totalBytesSent: number;
+  totalBytesExpectedToSend: number;
+};
+
+export type IFileSystemDownloadPauseState = {
+  url: string;
+  fileUri: string;
+  options: IFileSystemDownloadOptions;
+  resumeData?: string;
+};
+
+export type IFileSystemFileInfo =
+  | {
+      exists: true;
+      uri: string;
+      size: number;
+      isDirectory: boolean;
+      modificationTime: number;
+      md5?: string;
+    }
+  | {
+      exists: false;
+      uri: string;
+      isDirectory: false;
+    };
+
+export enum FileSystemEncodingType {
+  UTF8 = 'utf8',
+  Base64 = 'base64',
+}
+
+export type IFileSystemReadingOptions = {
+  encoding?: FileSystemEncodingType | 'utf8' | 'base64';
+  position?: number;
+  length?: number;
+};
+
+export type IFileSystemWritingOptions = {
+  encoding?: FileSystemEncodingType | 'utf8' | 'base64';
+  append?: boolean;
+};
+
+export type IFileSystemDeletingOptions = {
+  idempotent?: boolean;
+};
+
+export type IFileSystemInfoOptions = {
+  md5?: boolean;
+};
+
+export type IFileSystemRelocatingOptions = {
+  from: string;
+  to: string;
+};
+
+export type IFileSystemMakeDirectoryOptions = {
+  intermediates?: boolean;
+};
+
+export type IFileSystemProgressEvent<T> = {
+  uuid: string;
+  data: T;
+};
+
+export type IFileSystemRequestDirectoryPermissionsResult =
+  | {
+      granted: false;
+    }
+  | {
+      granted: true;
+      directoryUri: string;
+    };

package/src/next/directory.ts

@@ -0,0 +1,83 @@
+import { File } from './file';
+import { expoFileSystemNext } from './native-module';
+import { Paths } from './paths';
+import { FileSystemWatcher } from './watcher';
+import type {
+  IFileSystemWatchEvent,
+  IFileSystemWatchOptions,
+  IFileSystemWatchSubscription,
+} from './types';
+
+/**
+ * Represents a directory on the filesystem.
+ *
+ * A `Directory` instance can be created for any path, and does not need to exist on the
+ * filesystem during creation.
+ */
+export class Directory extends expoFileSystemNext.FileSystemDirectory {
+  static pickDirectoryAsync: (initialUri?: string) => Promise<Directory>;
+
+  /**
+   * Creates an instance of a directory. It can be created for any path, and does not need to
+   * exist on the filesystem during creation.
+   */
+  constructor(...uris: (string | File | Directory)[]) {
+    super(Paths.join(...uris));
+    this.validatePath();
+  }
+
+  /** Directory containing this directory. */
+  get parentDirectory() {
+    return new Directory(Paths.join(this.uri, '..'));
+  }
+
+  /**
+   * Lists the contents of a directory. Calling this method if the parent directory does not
+   * exist will throw an error.
+   */
+  override list(): (Directory | File)[] {
+    return super
+      .listAsRecords()
+      .map(({ isDirectory, uri }) =>
+        isDirectory ? new Directory(uri) : new File(uri),
+      );
+  }
+
+  /** Directory name. */
+  get name() {
+    return Paths.basename(this.uri);
+  }
+
+  override createFile(name: string, mimeType: string | null): File {
+    return new File(super.createFile(name, mimeType).uri);
+  }
+
+  override createDirectory(name: string): Directory {
+    return new Directory(super.createDirectory(name).uri);
+  }
+
+  /**
+   * Watches this directory for changes to its contents or the directory itself. On iOS,
+   * child changes are surfaced as a coarse-grained `modified` event on the directory itself, so
+   * filtering for child-level `created`, `deleted`, or `renamed` events is not reliable. The
+   * watcher automatically stops when the directory is deleted or renamed. To stop watching
+   * manually, call `remove()` on the returned subscription.
+   */
+  watch(
+    callback: (event: IFileSystemWatchEvent<File | Directory>) => void,
+    options?: IFileSystemWatchOptions,
+  ): IFileSystemWatchSubscription {
+    return new FileSystemWatcher<File | Directory>(
+      this.uri,
+      callback,
+      options,
+      (uri, isDirectory) => (isDirectory ? new Directory(uri) : new File(uri)),
+    );
+  }
+}
+
+Directory.pickDirectoryAsync = async function (initialUri?: string) {
+  const directory = (await expoFileSystemNext.pickDirectoryAsync(initialUri))
+    .uri;
+  return new Directory(directory);
+};

package/src/next/file.ts

@@ -0,0 +1,318 @@
+import { uuid, type EventSubscription } from 'expo-modules-core';
+
+import { Directory } from './directory';
+import { expoFileSystemNext } from './native-module';
+import { DownloadTask, UploadTask } from './network-tasks';
+import { Paths } from './paths';
+import {
+  FileSystemReadableStreamSource,
+  FileSystemWritableSink,
+} from './streams';
+import { FileSystemWatcher } from './watcher';
+import {
+  FileMode,
+  type IFileSystemDownloadOptions,
+  type IFileSystemDownloadProgress,
+  type IFileSystemDownloadTaskOptions,
+  type IFileSystemUploadOptions,
+  type IFileSystemUploadResult,
+  type IFileSystemWatchEvent,
+  type IFileSystemWatchOptions,
+  type IFileSystemWatchSubscription,
+  type IPickFileOptions,
+  type IPickMultipleFilesOptions,
+  type IPickMultipleFilesResult,
+  type IPickSingleFileOptions,
+  type IPickSingleFileResult,
+} from './types';
+
+function createAbortError(reason?: unknown): Error {
+  const message =
+    typeof reason === 'string' ? reason : 'The operation was aborted.';
+  const error = new Error(message);
+  error.name = 'AbortError';
+  return error;
+}
+
+function parsePickFileOptions(
+  initialUriOrOptions?: string | IPickFileOptions,
+  mimeType?: string,
+): { options: IPickFileOptions; usingOldAPI: boolean } {
+  if (typeof initialUriOrOptions === 'object') {
+    return { options: initialUriOrOptions, usingOldAPI: false };
+  }
+  return {
+    options: {
+      initialUri: initialUriOrOptions,
+      mimeTypes: mimeType,
+      multipleFiles: false,
+    },
+    usingOldAPI:
+      mimeType !== undefined || typeof initialUriOrOptions === 'string',
+  };
+}
+
+/**
+ * Represents a file on the filesystem.
+ *
+ * A `File` instance can be created for any path, and does not need to exist on the filesystem
+ * during creation. The constructor accepts an array of strings that are joined to create the
+ * file URI. The first argument can also be a `Directory` instance (like `Paths.cache`) or a
+ * `File` instance (which creates a new reference to the same file).
+ */
+export class File extends expoFileSystemNext.FileSystemFile {
+  /**
+   * Downloads a file from the network.
+   *
+   * On Android, the response body streams directly into the target file. If the download fails
+   * after it starts, a partially written file may remain at the destination. On iOS, the
+   * download first completes in a temporary location and the file is moved into place only
+   * after success, so no file is left behind when the request fails.
+   */
+  static downloadFileAsync: (
+    url: string,
+    destination: Directory | File,
+    options?: IFileSystemDownloadOptions,
+  ) => Promise<File>;
+
+  /**
+   * Opens the system file picker for selecting a single file.
+   */
+  static pickFileAsync(
+    options?: IPickSingleFileOptions,
+  ): Promise<IPickSingleFileResult>;
+  /**
+   * Opens the system file picker for selecting multiple files.
+   */
+  static pickFileAsync(
+    options?: IPickMultipleFilesOptions,
+  ): Promise<IPickMultipleFilesResult>;
+  /**
+   * @deprecated Use `pickFileAsync({initialUri, mimeTypes: mimeType})` instead.
+   */
+  static pickFileAsync(
+    initialUri?: string,
+    mimeType?: string,
+  ): Promise<File | File[]>;
+  static async pickFileAsync(
+    initialUriOrOptions?: string | IPickFileOptions,
+    mimeType?: string,
+  ): Promise<File | File[] | IPickSingleFileResult | IPickMultipleFilesResult> {
+    const { options, usingOldAPI } = parsePickFileOptions(
+      initialUriOrOptions,
+      mimeType,
+    );
+    try {
+      if (options.multipleFiles) {
+        const files = await expoFileSystemNext.pickFileAsync(options);
+        return {
+          result: files.map(file => new File(file.uri)),
+          canceled: false,
+        };
+      }
+      const file = await expoFileSystemNext.pickFileAsync(options);
+      if (usingOldAPI) {
+        return new File(file.uri);
+      }
+      return {
+        result: new File(file.uri),
+        canceled: false,
+      };
+    } catch (error) {
+      if (usingOldAPI) {
+        throw error;
+      }
+      return {
+        result: null,
+        canceled: true,
+      };
+    }
+  }
+
+  /**
+   * Creates an instance of a file. It can be created for any path, and does not need to exist on
+   * the filesystem during creation.
+   */
+  constructor(...uris: (string | File | Directory)[]) {
+    super(Paths.join(...uris));
+    this.validatePath();
+  }
+
+  /** Directory containing the file. */
+  get parentDirectory() {
+    return new Directory(Paths.dirname(this.uri));
+  }
+
+  /** File extension, e.g. `.png`. */
+  get extension() {
+    return Paths.extname(this.uri);
+  }
+
+  /** File name. Includes the extension. */
+  get name() {
+    return Paths.basename(this.uri);
+  }
+
+  readableStream() {
+    return new ReadableStream(
+      new FileSystemReadableStreamSource(super.open(FileMode.ReadOnly)),
+    );
+  }
+
+  writableStream() {
+    return new WritableStream<Uint8Array>(
+      new FileSystemWritableSink(super.open(FileMode.WriteOnly)),
+    );
+  }
+
+  async arrayBuffer(): Promise<ArrayBuffer> {
+    const bytes = await this.bytes();
+    return bytes.buffer;
+  }
+
+  async json(): Promise<unknown> {
+    return JSON.parse(await this.text());
+  }
+
+  async formData(): ReturnType<Response['formData']> {
+    return new Response(await this.arrayBuffer(), {
+      headers: this.type ? { 'Content-Type': this.type } : undefined,
+    }).formData();
+  }
+
+  stream(): ReadableStream<Uint8Array<ArrayBuffer>> {
+    return this.readableStream();
+  }
+
+  slice(start?: number, end?: number, contentType?: string): Blob {
+    // React Native's own ambient `Blob` declaration (react-native/src/types/globals.d.ts) is
+    // narrower than its runtime: `blobParts` is typed as `(Blob | string)[]` only (the real
+    // native implementation accepts raw bytes), and `BlobOptions` requires both `type` and
+    // `lastModified` even though `lastModified` is a `File`-only concept the Web `Blob` spec
+    // doesn't have at all. Cast at this one call — RN's declared contract, not our logic, is
+    // what's incomplete; `lastModified` is supplied only to satisfy the type and is not read by
+    // any real `Blob` implementation.
+    const bytes = this.bytesSync().slice(start, end) as unknown as string;
+    return new Blob([bytes], {
+      type: contentType ?? '',
+      lastModified: Date.now(),
+    });
+  }
+
+  /**
+   * Uploads this file to a server and starts the request immediately.
+   */
+  upload(
+    url: string,
+    options?: IFileSystemUploadOptions,
+  ): Promise<IFileSystemUploadResult> {
+    return new UploadTask(this, url, options).uploadAsync();
+  }
+
+  /**
+   * Creates an upload task for this file without starting it.
+   */
+  createUploadTask(
+    url: string,
+    options?: IFileSystemUploadOptions,
+  ): UploadTask {
+    return new UploadTask(this, url, options);
+  }
+
+  /**
+   * Creates a download task without starting it.
+   */
+  static createDownloadTask(
+    url: string,
+    destination: File | Directory,
+    options?: IFileSystemDownloadTaskOptions,
+  ): DownloadTask {
+    return new DownloadTask(url, destination, options);
+  }
+
+  /**
+   * Watches this file for changes on the filesystem. The watcher automatically stops when the
+   * file is deleted or renamed. To stop watching manually, call `remove()` on the returned
+   * subscription.
+   */
+  watch(
+    callback: (event: IFileSystemWatchEvent<File>) => void,
+    options?: IFileSystemWatchOptions,
+  ): IFileSystemWatchSubscription {
+    return new FileSystemWatcher<File>(
+      this.uri,
+      callback,
+      options,
+      uri => new File(uri),
+    );
+  }
+}
+
+// Cannot use `static` keyword in class declaration because of a runtime error (matches upstream's
+// own comment — assigning after the class body avoids whatever native interop issue upstream ran
+// into with `SharedObject`-extending classes).
+File.downloadFileAsync = async function downloadFileAsync(
+  url: string,
+  to: File | Directory,
+  options?: IFileSystemDownloadOptions,
+) {
+  const needsUuid = options?.onProgress || options?.signal;
+  const downloadUuid = needsUuid ? uuid.v4() : undefined;
+
+  let subscription: EventSubscription | undefined;
+  let abortHandler: (() => void) | undefined;
+  let lastProgress: IFileSystemDownloadProgress | undefined;
+
+  try {
+    if (options?.signal?.aborted) {
+      throw createAbortError(options.signal.reason);
+    }
+
+    if (downloadUuid && options?.onProgress) {
+      subscription = expoFileSystemNext.addListener(
+        'downloadProgress',
+        event => {
+          if (event.uuid === downloadUuid) {
+            lastProgress = event.data;
+            options.onProgress!(lastProgress);
+          }
+        },
+      );
+    }
+
+    if (downloadUuid && options?.signal) {
+      abortHandler = () => {
+        expoFileSystemNext.cancelDownloadAsync(downloadUuid);
+      };
+      options.signal.addEventListener('abort', abortHandler, { once: true });
+    }
+
+    const outputURI = await expoFileSystemNext.downloadFileAsync(
+      url,
+      to,
+      options,
+      downloadUuid,
+    );
+    const file = new File(outputURI);
+    const fileSize = file.size ?? 0;
+    if (
+      options?.onProgress &&
+      fileSize > 0 &&
+      (lastProgress?.bytesWritten !== fileSize ||
+        lastProgress?.totalBytes !== fileSize)
+    ) {
+      options.onProgress({ bytesWritten: fileSize, totalBytes: fileSize });
+    }
+    return file;
+  } catch (error) {
+    if (options?.signal?.aborted) {
+      throw createAbortError(options.signal.reason);
+    }
+    throw error;
+  } finally {
+    subscription?.remove();
+    if (abortHandler && options?.signal) {
+      options.signal.removeEventListener('abort', abortHandler);
+    }
+  }
+};

package/src/next/index.ts

@@ -0,0 +1,5 @@
+export { File } from './file';
+export { Directory } from './directory';
+export { Paths } from './paths';
+export { UploadTask, DownloadTask } from './network-tasks';
+export * from './types';