@symbiote-native/file-system 0.1.0

package/src/next/types.ts

@@ -0,0 +1,194 @@
+import type { File } from './file';
+import type { Directory } from './directory';
+
+export type IFileCreateOptions = {
+  intermediates?: boolean;
+  overwrite?: boolean;
+};
+
+export type IRelocationOptions = {
+  overwrite?: boolean;
+};
+
+export enum FileSystemEncodingType {
+  UTF8 = 'utf8',
+  Base64 = 'base64',
+}
+
+export type IFileWriteOptions = {
+  encoding?: FileSystemEncodingType | 'utf8' | 'base64';
+  append?: boolean;
+};
+
+export enum FileMode {
+  ReadWrite = 'rw',
+  ReadOnly = 'r',
+  WriteOnly = 'w',
+  Append = 'wa',
+  Truncate = 'wt',
+}
+
+export type IFileSystemHandle = {
+  close(): void;
+  readBytes(length: number): Uint8Array<ArrayBuffer>;
+  writeBytes(bytes: Uint8Array): void;
+  offset: number | null;
+  size: number | null;
+};
+
+export type IFileInfo = {
+  exists: boolean;
+  uri?: string;
+  size?: number;
+  modificationTime?: number;
+  creationTime?: number;
+  md5?: string;
+};
+
+export type IFileSystemInfoOptions = {
+  md5?: boolean;
+};
+
+export type IPickFileGeneralOptions = {
+  initialUri?: string;
+  mimeTypes?: string | string[];
+  multipleFiles?: boolean;
+};
+
+export type IPickSingleFileOptions = IPickFileGeneralOptions & {
+  multipleFiles?: false;
+};
+
+export type IPickMultipleFilesOptions = IPickFileGeneralOptions & {
+  multipleFiles: true;
+};
+
+export type IPickFileOptions =
+  IPickSingleFileOptions | IPickMultipleFilesOptions;
+
+export type IPickSingleFileSuccessResult = {
+  result: File;
+  canceled: false;
+};
+
+export type IPickMultipleFilesSuccessResult = {
+  result: File[];
+  canceled: false;
+};
+
+export type IPickFileCanceledResult = {
+  result: null;
+  canceled: true;
+};
+
+export type IPickSingleFileResult =
+  IPickSingleFileSuccessResult | IPickFileCanceledResult;
+export type IPickMultipleFilesResult =
+  IPickMultipleFilesSuccessResult | IPickFileCanceledResult;
+
+export type IDirectoryCreateOptions = {
+  intermediates?: boolean;
+  overwrite?: boolean;
+  idempotent?: boolean;
+};
+
+export type IDirectoryInfo = {
+  exists: boolean;
+  uri?: string;
+  size?: number;
+  modificationTime?: number;
+  creationTime?: number;
+  files?: string[];
+};
+
+export type IPathInfo = {
+  exists: boolean;
+  isDirectory: boolean | null;
+};
+
+export type IFileSystemDownloadProgress = {
+  bytesWritten: number;
+  totalBytes: number;
+};
+
+export type IFileSystemDownloadOptions = {
+  headers?: Record<string, string>;
+  idempotent?: boolean;
+  onProgress?: (data: IFileSystemDownloadProgress) => void;
+  signal?: AbortSignal;
+};
+
+export enum FileSystemUploadType {
+  BINARY_CONTENT = 0,
+  MULTIPART = 1,
+}
+
+export type IFileSystemUploadProgress = {
+  bytesSent: number;
+  totalBytes: number;
+};
+
+export type IFileSystemUploadResult = {
+  body: string;
+  status: number;
+  headers: Record<string, string>;
+};
+
+export type IFileSystemNetworkTaskSessionType = 'background' | 'foreground';
+
+export type IFileSystemUploadOptions = {
+  httpMethod?: 'POST' | 'PUT' | 'PATCH';
+  uploadType?: FileSystemUploadType;
+  headers?: Record<string, string>;
+  fieldName?: string;
+  mimeType?: string;
+  parameters?: Record<string, string>;
+  onProgress?: (data: IFileSystemUploadProgress) => void;
+  sessionType?: IFileSystemNetworkTaskSessionType;
+  signal?: AbortSignal;
+};
+
+export type IFileSystemDownloadTaskOptions = {
+  headers?: Record<string, string>;
+  sessionType?: IFileSystemNetworkTaskSessionType;
+  onProgress?: (data: IFileSystemDownloadProgress) => void;
+  signal?: AbortSignal;
+};
+
+export type IFileSystemDownloadPauseState = {
+  url: string;
+  fileUri: string;
+  isDirectory: boolean;
+  headers?: Record<string, string>;
+  resumeData?: string;
+};
+
+type IFileSystemTaskState =
+  'idle' | 'active' | 'paused' | 'completed' | 'cancelled' | 'error';
+
+export type IFileSystemUploadTaskState = Exclude<
+  IFileSystemTaskState,
+  'paused'
+>;
+export type IFileSystemDownloadTaskState = IFileSystemTaskState;
+
+export const DEFAULT_WATCH_DEBOUNCE_MS = 100;
+
+export type IFileSystemWatchEventType =
+  'created' | 'modified' | 'deleted' | 'renamed';
+
+export type IFileSystemWatchEvent<T extends File | Directory> = {
+  type: IFileSystemWatchEventType;
+  target: T;
+  nativeEventFlags?: number;
+  newTarget?: T;
+};
+
+export type IFileSystemWatchOptions = {
+  debounce?: number;
+  events?: IFileSystemWatchEventType[];
+};
+
+export type IFileSystemWatchSubscription = {
+  remove(): void;
+};

package/src/next/url-utilities.ts

@@ -0,0 +1,70 @@
+// Ported verbatim from expo-file-system's own vendored copy (Copyright Joyent, Inc. and other
+// Node contributors, MIT licensed) — url-encoding helpers used when a path is a `file://`/URL
+// rather than a bare posix path.
+
+import { resolve, sep } from './node-path';
+
+const percentRegEx = /%/g;
+const backslashRegEx = /\\/g;
+const newlineRegEx = /\n/g;
+const carriageReturnRegEx = /\r/g;
+const tabRegEx = /\t/g;
+const questionRegex = /\?/g;
+const hashRegex = /#/g;
+const spaceRegEx = / /g;
+
+function encodePathChars(filepath: string) {
+  if (filepath.indexOf('%') !== -1)
+    filepath = filepath.replace(percentRegEx, '%25');
+  if (filepath.indexOf('\\') !== -1)
+    filepath = filepath.replace(backslashRegEx, '%5C');
+  if (filepath.indexOf('\n') !== -1)
+    filepath = filepath.replace(newlineRegEx, '%0A');
+  if (filepath.indexOf('\r') !== -1)
+    filepath = filepath.replace(carriageReturnRegEx, '%0D');
+  if (filepath.indexOf('\t') !== -1)
+    filepath = filepath.replace(tabRegEx, '%09');
+  if (filepath.indexOf(' ') !== -1)
+    filepath = filepath.replace(spaceRegEx, '%20');
+  return filepath;
+}
+
+export function encodeURLChars(path: string) {
+  let resolved = resolve(path);
+  const filePathLast = path.charAt(path.length - 1);
+  if (filePathLast === '/' && resolved[resolved.length - 1] !== sep)
+    resolved += '/';
+
+  resolved = encodePathChars(resolved);
+
+  if (resolved.indexOf('?') !== -1)
+    resolved = resolved.replace(questionRegex, '%3F');
+  if (resolved.indexOf('#') !== -1)
+    resolved = resolved.replace(hashRegex, '%23');
+  return resolved;
+}
+
+export function isUrl(url: string) {
+  try {
+    return !!new URL(url);
+  } catch {
+    return false;
+  }
+}
+
+export function asUrl(url: string | URL) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.hash === '') {
+      return parsed;
+    }
+    // Strip the hash by reconstructing rather than assigning `.hash = ''` — this project's
+    // resolved `URL` type declares its setters read-only (see path-utilities.ts's own note).
+    const hashIndex = parsed.href.indexOf('#');
+    return new URL(
+      hashIndex === -1 ? parsed.href : parsed.href.slice(0, hashIndex),
+    );
+  } catch {
+    return null;
+  }
+}

package/src/next/watcher.ts

@@ -0,0 +1,106 @@
+import type { EventSubscription } from 'expo-modules-core';
+
+import type { Directory } from './directory';
+import type { File } from './file';
+import {
+  expoFileSystemNext,
+  type INativeFileSystemWatcherEvent,
+} from './native-module';
+import { DEFAULT_WATCH_DEBOUNCE_MS } from './types';
+import type {
+  IFileSystemWatchEvent,
+  IFileSystemWatchOptions,
+  IFileSystemWatchSubscription,
+} from './types';
+
+type ITargetFactory<T> = (uri: string, isDirectory: boolean) => T;
+
+function normalizePath(path: string): string {
+  return path.replace(/\/+$/, '');
+}
+
+/**
+ * @hidden
+ * Internal implementation of file system watching. Use `File.watch()` or `Directory.watch()` instead.
+ */
+export class FileSystemWatcher<
+  T extends File | Directory,
+> implements IFileSystemWatchSubscription {
+  private nativeWatcher: InstanceType<
+    typeof expoFileSystemNext.FileSystemWatcher
+  > | null;
+  private subscription: EventSubscription | null = null;
+  private removed = false;
+  private readonly normalizedWatchedPath: string;
+
+  constructor(
+    path: string,
+    callback: (event: IFileSystemWatchEvent<T>) => void,
+    options: IFileSystemWatchOptions = {},
+    private readonly targetFactory: ITargetFactory<T>,
+  ) {
+    this.normalizedWatchedPath = normalizePath(path);
+    this.nativeWatcher = new expoFileSystemNext.FileSystemWatcher(path, {
+      debounce: options.debounce ?? DEFAULT_WATCH_DEBOUNCE_MS,
+      events: options.events,
+    });
+
+    this.subscription = this.nativeWatcher.addListener(
+      'change',
+      (raw: INativeFileSystemWatcherEvent) => {
+        const event = this.mapEvent(raw);
+        const isWatchedTarget =
+          normalizePath(raw.path) === this.normalizedWatchedPath;
+
+        if (!options.events || options.events.includes(event.type)) {
+          callback(event);
+        }
+
+        if (
+          (event.type === 'deleted' || event.type === 'renamed') &&
+          isWatchedTarget
+        ) {
+          this.remove();
+        }
+      },
+    );
+
+    try {
+      this.nativeWatcher.start();
+    } catch (error) {
+      this.subscription.remove();
+      this.subscription = null;
+      this.nativeWatcher = null;
+      throw error;
+    }
+  }
+
+  private mapEvent(
+    raw: INativeFileSystemWatcherEvent,
+  ): IFileSystemWatchEvent<T> {
+    return {
+      type: raw.type,
+      target: this.targetFactory(raw.path, raw.isDirectory),
+      newTarget: raw.newPath
+        ? this.targetFactory(
+            raw.newPath,
+            raw.newPathIsDirectory ?? raw.isDirectory,
+          )
+        : undefined,
+      nativeEventFlags: raw.nativeEventFlags,
+    };
+  }
+
+  remove(): void {
+    if (this.removed) {
+      return;
+    }
+    this.removed = true;
+
+    this.subscription?.remove();
+    this.subscription = null;
+
+    this.nativeWatcher?.stop();
+    this.nativeWatcher = null;
+  }
+}