@symbiote-native/file-system 0.1.0

package/src/next/node-path.ts

@@ -0,0 +1,362 @@
+// Ported verbatim from expo-file-system's own vendored copy of Node's posix `path` module
+// (Copyright Joyent, Inc. and other Node contributors, MIT licensed) — a self-contained,
+// mechanical algorithm with zero native dependency, so a straight port carries low risk.
+
+function isPathSeparator(code: string) {
+  return code === '/';
+}
+
+// Resolves . and .. elements in a path with directory names
+function normalizeString(
+  path: string,
+  allowAboveRoot: boolean,
+  separator: string,
+) {
+  let res = '';
+  let lastSegmentLength = 0;
+  let lastSlash = -1;
+  let dots = 0;
+  let code = '';
+  for (let i = 0; i <= path.length; ++i) {
+    if (i < path.length) code = path.charAt(i);
+    else if (isPathSeparator(code)) break;
+    else code = '/';
+
+    if (isPathSeparator(code)) {
+      if (lastSlash === i - 1 || dots === 1) {
+        // NOOP
+      } else if (dots === 2) {
+        if (
+          res.length < 2 ||
+          lastSegmentLength !== 2 ||
+          res.charAt(res.length - 1) !== '.' ||
+          res.charAt(res.length - 2) !== '.'
+        ) {
+          if (res.length > 2) {
+            const lastSlashIndex = res.lastIndexOf(separator);
+            if (lastSlashIndex === -1) {
+              res = '';
+              lastSegmentLength = 0;
+            } else {
+              res = res.slice(0, lastSlashIndex);
+              lastSegmentLength = res.length - 1 - res.lastIndexOf(separator);
+            }
+            lastSlash = i;
+            dots = 0;
+            continue;
+          } else if (res.length !== 0) {
+            res = '';
+            lastSegmentLength = 0;
+            lastSlash = i;
+            dots = 0;
+            continue;
+          }
+        }
+        if (allowAboveRoot) {
+          res += res.length > 0 ? `${separator}..` : '..';
+          lastSegmentLength = 2;
+        }
+      } else {
+        if (res.length > 0)
+          res += `${separator}${path.slice(lastSlash + 1, i)}`;
+        else res = path.slice(lastSlash + 1, i);
+        lastSegmentLength = i - lastSlash - 1;
+      }
+      lastSlash = i;
+      dots = 0;
+    } else if (code === '.' && dots !== -1) {
+      ++dots;
+    } else {
+      dots = -1;
+    }
+  }
+  return res;
+}
+
+export function resolve(...args: string[]) {
+  let resolvedPath = '';
+  let resolvedAbsolute = false;
+
+  for (let i = args.length - 1; i >= -1 && !resolvedAbsolute; i--) {
+    const path = i >= 0 ? args[i] : '';
+
+    if (!path || path.length === 0) {
+      continue;
+    }
+
+    resolvedPath = `${path}/${resolvedPath}`;
+    resolvedAbsolute = !!(path && path.charAt(0) === '/');
+  }
+
+  resolvedPath = normalizeString(resolvedPath, !resolvedAbsolute, '/');
+
+  if (resolvedAbsolute) {
+    return `/${resolvedPath}`;
+  }
+  return resolvedPath.length > 0 ? resolvedPath : '.';
+}
+
+export function normalize(path: string) {
+  if (path.length === 0) return '.';
+
+  const isAbsolute = path.charAt(0) === '/';
+  const trailingSeparator = path.charAt(path.length - 1) === '/';
+
+  path = normalizeString(path, !isAbsolute, '/');
+
+  if (path.length === 0) {
+    if (isAbsolute) return '/';
+    return trailingSeparator ? './' : '.';
+  }
+  if (trailingSeparator) path += '/';
+
+  return isAbsolute ? `/${path}` : path;
+}
+
+export function isAbsolute(path: string) {
+  return path.length > 0 && path.charAt(0) === '/';
+}
+
+export function join(...args: string[]) {
+  if (args.length === 0) return '.';
+
+  const path: string[] = [];
+  for (let i = 0; i < args.length; ++i) {
+    const arg = args[i];
+    if (arg && arg.length > 0) {
+      path.push(arg);
+    }
+  }
+
+  if (path.length === 0) return '.';
+
+  return normalize(path.join('/'));
+}
+
+export function relative(from: string, to: string) {
+  if (from === to) return '';
+
+  from = resolve(from);
+  to = resolve(to);
+
+  if (from === to) return '';
+
+  const fromStart = 1;
+  const fromEnd = from.length;
+  const fromLen = fromEnd - fromStart;
+  const toStart = 1;
+  const toLen = to.length - toStart;
+
+  const length = fromLen < toLen ? fromLen : toLen;
+  let lastCommonSep = -1;
+  let i = 0;
+  for (; i < length; i++) {
+    const fromChar = from.charAt(fromStart + i);
+    if (fromChar !== to.charAt(toStart + i)) break;
+    else if (fromChar === '/') lastCommonSep = i;
+  }
+  if (i === length) {
+    if (toLen > length) {
+      if (to.charAt(toStart + i) === '/') {
+        return to.slice(toStart + i + 1);
+      }
+      if (i === 0) {
+        return to.slice(toStart + i);
+      }
+    } else if (fromLen > length) {
+      if (from.charAt(fromStart + i) === '/') {
+        lastCommonSep = i;
+      } else if (i === 0) {
+        lastCommonSep = 0;
+      }
+    }
+  }
+
+  let out = '';
+  for (i = fromStart + lastCommonSep + 1; i <= fromEnd; ++i) {
+    if (i === fromEnd || from.charAt(i) === '/') {
+      out += out.length === 0 ? '..' : '/..';
+    }
+  }
+
+  return `${out}${to.slice(toStart + lastCommonSep)}`;
+}
+
+export function dirname(path: string) {
+  if (path.length === 0) return '.';
+  const hasRoot = path.charAt(0) === '/';
+  let end = -1;
+  let matchedSlash = true;
+  for (let i = path.length - 1; i >= 1; --i) {
+    if (path.charAt(i) === '/') {
+      if (!matchedSlash) {
+        end = i;
+        break;
+      }
+    } else {
+      matchedSlash = false;
+    }
+  }
+
+  if (end === -1) return hasRoot ? '/' : '.';
+  if (hasRoot && end === 1) return '//';
+  return path.slice(0, end);
+}
+
+export function basename(path: string, suffix?: string) {
+  let start = 0;
+  let end = -1;
+  let matchedSlash = true;
+
+  if (
+    suffix !== undefined &&
+    suffix.length > 0 &&
+    suffix.length <= path.length
+  ) {
+    if (suffix === path) return '';
+    let extIdx = suffix.length - 1;
+    let firstNonSlashEnd = -1;
+    for (let i = path.length - 1; i >= 0; --i) {
+      const code = path.charAt(i);
+      if (code === '/') {
+        if (!matchedSlash) {
+          start = i + 1;
+          break;
+        }
+      } else {
+        if (firstNonSlashEnd === -1) {
+          matchedSlash = false;
+          firstNonSlashEnd = i + 1;
+        }
+        if (extIdx >= 0) {
+          if (code === suffix.charAt(extIdx)) {
+            if (--extIdx === -1) {
+              end = i;
+            }
+          } else {
+            extIdx = -1;
+            end = firstNonSlashEnd;
+          }
+        }
+      }
+    }
+
+    if (start === end) end = firstNonSlashEnd;
+    else if (end === -1) end = path.length;
+    return path.slice(start, end);
+  }
+  for (let i = path.length - 1; i >= 0; --i) {
+    if (path.charAt(i) === '/') {
+      if (!matchedSlash) {
+        start = i + 1;
+        break;
+      }
+    } else if (end === -1) {
+      matchedSlash = false;
+      end = i + 1;
+    }
+  }
+
+  if (end === -1) return '';
+  return path.slice(start, end);
+}
+
+export function extname(path: string) {
+  let startDot = -1;
+  let startPart = 0;
+  let end = -1;
+  let matchedSlash = true;
+  let preDotState = 0;
+  for (let i = path.length - 1; i >= 0; --i) {
+    const code = path.charAt(i);
+    if (code === '/') {
+      if (!matchedSlash) {
+        startPart = i + 1;
+        break;
+      }
+      continue;
+    }
+    if (end === -1) {
+      matchedSlash = false;
+      end = i + 1;
+    }
+    if (code === '.') {
+      if (startDot === -1) startDot = i;
+      else if (preDotState !== 1) preDotState = 1;
+    } else if (startDot !== -1) {
+      preDotState = -1;
+    }
+  }
+
+  if (
+    startDot === -1 ||
+    end === -1 ||
+    preDotState === 0 ||
+    (preDotState === 1 && startDot === end - 1 && startDot === startPart + 1)
+  ) {
+    return '';
+  }
+  return path.slice(startDot, end);
+}
+
+export function parse(path: string) {
+  const ret = { root: '', dir: '', base: '', ext: '', name: '' };
+  if (path.length === 0) return ret;
+  const isAbsolutePath = path.charAt(0) === '/';
+  let start;
+  if (isAbsolutePath) {
+    ret.root = '/';
+    start = 1;
+  } else {
+    start = 0;
+  }
+  let startDot = -1;
+  let startPart = 0;
+  let end = -1;
+  let matchedSlash = true;
+  let i = path.length - 1;
+  let preDotState = 0;
+
+  for (; i >= start; --i) {
+    const code = path.charAt(i);
+    if (code === '/') {
+      if (!matchedSlash) {
+        startPart = i + 1;
+        break;
+      }
+      continue;
+    }
+    if (end === -1) {
+      matchedSlash = false;
+      end = i + 1;
+    }
+    if (code === '.') {
+      if (startDot === -1) startDot = i;
+      else if (preDotState !== 1) preDotState = 1;
+    } else if (startDot !== -1) {
+      preDotState = -1;
+    }
+  }
+
+  if (end !== -1) {
+    const nameStart = startPart === 0 && isAbsolutePath ? 1 : startPart;
+    if (
+      startDot === -1 ||
+      preDotState === 0 ||
+      (preDotState === 1 && startDot === end - 1 && startDot === startPart + 1)
+    ) {
+      ret.base = ret.name = path.slice(nameStart, end);
+    } else {
+      ret.name = path.slice(nameStart, startDot);
+      ret.base = path.slice(nameStart, end);
+      ret.ext = path.slice(startDot, end);
+    }
+  }
+
+  if (startPart > 0) ret.dir = path.slice(0, startPart - 1);
+  else if (isAbsolutePath) ret.dir = '/';
+
+  return ret;
+}
+
+export const sep = '/';

package/src/next/path-utilities.ts

@@ -0,0 +1,144 @@
+import type { File } from './file';
+import type { Directory } from './directory';
+import * as nodePath from './node-path';
+import { asUrl, isUrl, encodeURLChars } from './url-utilities';
+
+function uriObjectToString(path: string | File | Directory): string {
+  return typeof path === 'string' ? path : path.uri;
+}
+
+// React Native's own ambient `URL` type (react-native/src/types/globals.d.ts) declares every
+// property but `search` as readonly, so a new pathname is applied by reconstructing the URL
+// rather than assigning `.pathname` in place — matching what a real setter would do internally.
+// Built from `.protocol`/`.host` rather than `.origin`, because `file://` URLs report `.origin`
+// as the literal string `"null"` per spec.
+function withPathname(url: URL, pathname: string): URL {
+  return new URL(
+    `${url.protocol}//${url.host}${pathname}${url.search}${url.hash}`,
+  );
+}
+
+export class PathUtilities {
+  /**
+   * Joins path segments into a single path.
+   */
+  static join(...paths: (string | File | Directory)[]): string {
+    const [firstSegment = '', ...rest] = paths.map(uriObjectToString);
+    const pathAsUrl = asUrl(firstSegment);
+    if (pathAsUrl) {
+      const joined = nodePath.join(
+        pathAsUrl.pathname,
+        ...rest.map(encodeURLChars),
+      );
+      return withPathname(pathAsUrl, joined).toString();
+    }
+    return nodePath.join(firstSegment, ...rest.map(encodeURLChars));
+  }
+
+  /**
+   * Resolves a relative path to an absolute path.
+   */
+  static relative(
+    from: string | File | Directory,
+    to: string | File | Directory,
+  ): string {
+    let fromPath: string | File | Directory = from;
+    let toPath: string | File | Directory = to;
+    const fromString = uriObjectToString(from);
+    const toString = uriObjectToString(to);
+
+    if (isUrl(fromString)) {
+      fromPath = asUrl(fromString)!.pathname;
+    }
+    if (isUrl(toString)) {
+      toPath = asUrl(toString)!.pathname;
+    }
+    return nodePath.relative(
+      uriObjectToString(fromPath),
+      uriObjectToString(toPath),
+    );
+  }
+
+  /**
+   * Checks if a path is absolute.
+   */
+  static isAbsolute(path: string | File | Directory): boolean {
+    const pathString = uriObjectToString(path);
+    if (isUrl(pathString)) {
+      return true;
+    }
+    return nodePath.isAbsolute(pathString);
+  }
+
+  /**
+   * Normalizes a path.
+   */
+  static normalize(path: string | File | Directory): string {
+    const pathString = uriObjectToString(path);
+    const pathURL = asUrl(encodeURLChars(pathString));
+    if (pathURL) {
+      const normalized = encodeURLChars(
+        nodePath.normalize(decodeURIComponent(pathURL.pathname)),
+      );
+      return withPathname(pathURL, normalized).toString();
+    }
+    return nodePath.normalize(pathString);
+  }
+
+  /**
+   * Returns the directory name of a path.
+   */
+  static dirname(path: string | File | Directory): string {
+    const pathString = uriObjectToString(path);
+    const pathURL = asUrl(pathString);
+    if (pathURL) {
+      const dirnamePath = encodeURLChars(
+        nodePath.dirname(decodeURIComponent(pathURL.pathname)),
+      );
+      return withPathname(pathURL, dirnamePath).toString();
+    }
+    return nodePath.dirname(pathString);
+  }
+
+  /**
+   * Returns the base name of a path.
+   */
+  static basename(path: string | File | Directory, ext?: string): string {
+    const pathString = uriObjectToString(path);
+    const pathURL = asUrl(pathString);
+    if (pathURL) {
+      return nodePath.basename(decodeURIComponent(pathURL.pathname));
+    }
+    return nodePath.basename(pathString, ext);
+  }
+
+  /**
+   * Returns the extension of a path.
+   */
+  static extname(path: string | File | Directory): string {
+    const pathString = uriObjectToString(path);
+    const pathURL = asUrl(pathString);
+    if (pathURL) {
+      return nodePath.extname(decodeURIComponent(pathURL.pathname));
+    }
+    return nodePath.extname(pathString);
+  }
+
+  /**
+   * Parses a path into its components.
+   */
+  static parse(path: string | File | Directory): {
+    root: string;
+    dir: string;
+    base: string;
+    ext: string;
+    name: string;
+  } {
+    const pathString = uriObjectToString(path);
+    const pathURL = asUrl(pathString);
+    if (pathURL) {
+      return nodePath.parse(decodeURIComponent(pathURL.pathname));
+    }
+    return nodePath.parse(pathString);
+  }
+}

package/src/next/paths.ts

@@ -0,0 +1,52 @@
+import { Directory } from './directory';
+import { expoFileSystemNext } from './native-module';
+import { PathUtilities } from './path-utilities';
+import type { IPathInfo } from './types';
+
+export class Paths extends PathUtilities {
+  /**
+   * A place to store files that can be deleted by the system when the device runs low on
+   * storage.
+   */
+  static get cache() {
+    return new Directory(expoFileSystemNext.cacheDirectory);
+  }
+
+  /** The directory where assets bundled with the application are stored. */
+  static get bundle() {
+    return new Directory(expoFileSystemNext.bundleDirectory);
+  }
+
+  /** A place to store files that are safe from being deleted by the system. */
+  static get document() {
+    return new Directory(expoFileSystemNext.documentDirectory);
+  }
+
+  /** @platform ios */
+  static get appleSharedContainers() {
+    const containers: Record<string, string> =
+      expoFileSystemNext.appleSharedContainers ?? {};
+    const result: Record<string, Directory> = {};
+    for (const appGroupId in containers) {
+      if (containers[appGroupId]) {
+        result[appGroupId] = new Directory(containers[appGroupId]);
+      }
+    }
+    return result;
+  }
+
+  /** The total space on the device's internal storage, in bytes. */
+  static get totalDiskSpace() {
+    return expoFileSystemNext.totalDiskSpace;
+  }
+
+  /** The available space on the device's internal storage, in bytes. */
+  static get availableDiskSpace() {
+    return expoFileSystemNext.availableDiskSpace;
+  }
+
+  /** Returns an object that indicates if the specified path represents a directory. */
+  static info(...uris: string[]): IPathInfo {
+    return expoFileSystemNext.info(uris.join('/'));
+  }
+}

package/src/next/streams-ambient.d.ts

@@ -0,0 +1,34 @@
+// React Native ships its own ambient global types (react-native/src/types/globals.d.ts) that
+// this project's tsconfig picks up ahead of any DOM lib, and that file declares `Blob`, `File`,
+// `Response`, `AbortSignal`, `URL` (all readonly except `search` — see path-utilities.ts's own
+// note), but NOT `ReadableStream`/`WritableStream` at all, and its `AbortSignal` class predates
+// the spec's `reason` property. RN's own Streams runtime (react-native/flow/streams.js.flow) has
+// no TypeScript counterpart. These are minimal structural declarations for the shapes this
+// package's `/next` surface actually constructs and reads — not a full spec-complete polyfill.
+
+declare global {
+  class ReadableStream<R = unknown> {
+    constructor(underlyingSource?: unknown, strategy?: unknown);
+    readonly locked: boolean;
+    cancel(reason?: unknown): Promise<void>;
+    getReader(): unknown;
+    pipeThrough(transform: unknown, options?: unknown): ReadableStream;
+    pipeTo(destination: unknown, options?: unknown): Promise<void>;
+    tee(): [ReadableStream<R>, ReadableStream<R>];
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  class WritableStream<W = unknown> {
+    constructor(underlyingSink?: unknown, strategy?: unknown);
+    readonly locked: boolean;
+    abort(reason?: unknown): Promise<void>;
+    close(): Promise<void>;
+    getWriter(): unknown;
+  }
+
+  interface AbortSignal {
+    readonly reason?: unknown;
+  }
+}
+
+export {};

package/src/next/streams.ts

@@ -0,0 +1,81 @@
+import type { IFileSystemHandle } from './types';
+
+// This project's tsconfig carries no DOM lib (RN ships its own Streams polyfill, typed only in
+// Flow upstream — react-native/flow/streams.js.flow — with no TypeScript ambient declaration
+// reachable here), so the WHATWG `UnderlyingByteSource`/`UnderlyingSink`/
+// `ReadableByteStreamController` names aren't in scope. These local structural types match the
+// spec shape `new ReadableStream(source)`/`new WritableStream(sink)` expect at the call site.
+type IReadableByteStreamController = {
+  readonly byobRequest: {
+    view: ArrayBufferView | null;
+    respond(bytesWritten: number): void;
+  } | null;
+  close(): void;
+  enqueue(chunk: Uint8Array): void;
+};
+
+export class FileSystemReadableStreamSource {
+  handle: IFileSystemHandle;
+  size: number = 1024;
+  type = 'bytes' as const;
+
+  constructor(handle: IFileSystemHandle) {
+    this.handle = handle;
+  }
+
+  cancel() {
+    this.handle.close();
+  }
+
+  pull(controller: IReadableByteStreamController) {
+    const theView = controller.byobRequest?.view;
+    if (!theView) {
+      const bytes = this.handle.readBytes(this.size);
+      if (bytes.length === 0) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(bytes);
+      return;
+    }
+
+    // TODO: Optimize by adding a native method that can write into a TypedArray at a given offset.
+    const bytes = this.handle.readBytes(
+      theView.byteLength - theView.byteOffset,
+    );
+    if (bytes.length === 0) {
+      controller.close();
+      controller.byobRequest.respond(0);
+      return;
+    }
+    if (theView instanceof Uint8Array) {
+      theView.set(bytes, theView.byteOffset);
+    } else {
+      const array = new Uint8Array(theView.buffer);
+      for (let i = 0; i < bytes.length; i++) {
+        array[i + (theView.byteOffset ?? 0)] = bytes[i]!;
+      }
+    }
+    controller.byobRequest.respond(bytes.length);
+  }
+}
+
+export class FileSystemWritableSink {
+  handle: IFileSystemHandle;
+
+  constructor(handle: IFileSystemHandle) {
+    this.handle = handle;
+  }
+
+  abort() {
+    this.close();
+  }
+
+  close() {
+    this.handle.close();
+  }
+
+  write(chunk: Uint8Array) {
+    this.handle.writeBytes(chunk);
+  }
+}