@react-native-gpui/fs 0.0.0-stage → 0.0.1-alpha.0

package/src/index.ts

@@ -0,0 +1,769 @@
+/**
+ * `@react-native-gpui/fs`: a Node-shaped file API for the desktop app.
+ *
+ * The native module underneath is one TurboModule on its own thread with
+ * `ArrayBuffer` arguments and plain-object results. Everything Node adds on top
+ * of that — encodings, `Stats` and `Dirent` instances, callback forms, the
+ * `fs/promises` object — lives in this package's JS layer, so the bridge stays a
+ * byte mover and the API stays recognisably Node's.
+ *
+ * The default export is the `node:fs` object; `dialog`, `paths` and `watch` are
+ * named exports because they have no `fs` counterpart to hang off.
+ */
+
+import { constants } from './constants';
+import NativeFs from './NativeFs';
+import {
+  Dirent,
+  FileHandle,
+  Stats,
+  promises,
+  readFileImpl,
+  type MkdirOptions,
+  type OpenOptions,
+  type RmOptions,
+  type WriteOptions,
+} from './promises';
+import {
+  decodeString,
+  flagFrom,
+  missingPath,
+  modeFrom,
+  normalizeEncoding,
+  relativeEntryName,
+  toArrayBuffer,
+  toPath,
+  withContext,
+  type BinaryData,
+  type Encoding,
+  type NodeError,
+} from './shared';
+import { watch } from './watch';
+
+export type {
+  CpOptions,
+  MkdirOptions,
+  OpenOptions,
+  ReaddirOptions,
+  RmOptions,
+  TimeLike,
+  WriteOptions,
+} from './promises';
+export type { BinaryData, Encoding, NodeError } from './shared';
+export type {
+  FSWatcher,
+  WatchEventType,
+  WatchListener,
+  WatchOptions,
+} from './watch';
+export { Dirent, Stats, FileHandle, promises, constants, watch };
+
+/* -------------------------------------------------------------------------- */
+/* Dialogs                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface DialogFilter {
+  name: string;
+  extensions: Array<string>;
+}
+
+export interface OpenDialogOptions {
+  title?: string;
+  defaultPath?: string;
+  multiple?: boolean;
+  directory?: boolean;
+  filters?: Array<DialogFilter>;
+}
+
+export interface SaveDialogOptions {
+  title?: string;
+  defaultPath?: string;
+  defaultName?: string;
+  filters?: Array<DialogFilter>;
+}
+
+/**
+ * The native pickers.
+ *
+ * Cancelling is not an error: `open` resolves with `[]` and `save` with `null`,
+ * which is what the design specifies and what libraries pairing the two expect.
+ */
+export const dialog = {
+  async open(options: OpenDialogOptions = {}): Promise<string[]> {
+    return NativeFs.showOpenDialog({
+      title: options.title,
+      defaultPath:
+        options.defaultPath === undefined
+          ? undefined
+          : toPath(options.defaultPath),
+      multiple: options.multiple ?? false,
+      directory: options.directory ?? false,
+      filters: options.filters ?? [],
+    });
+  },
+
+  async save(options: SaveDialogOptions = {}): Promise<string | null> {
+    return NativeFs.showSaveDialog({
+      title: options.title,
+      defaultPath:
+        options.defaultPath === undefined
+          ? undefined
+          : toPath(options.defaultPath),
+      defaultName: options.defaultName,
+      filters: options.filters ?? [],
+    });
+  },
+};
+
+/* -------------------------------------------------------------------------- */
+/* Known paths                                                                */
+/* -------------------------------------------------------------------------- */
+
+/** The well-known directories, as the native side reports them. */
+export interface KnownPaths {
+  home: string;
+  documents: string;
+  downloads: string;
+  desktop: string;
+  temp: string;
+  appData: string;
+  appCache: string;
+  appLogs: string;
+}
+
+const KNOWN_PATH_NAMES = [
+  'home',
+  'documents',
+  'downloads',
+  'desktop',
+  'temp',
+  'appData',
+  'appCache',
+  'appLogs',
+] as const;
+
+let cachedPaths: KnownPaths | null = null;
+
+/**
+ * Reads the known paths once and remembers them.
+ *
+ * Lazy rather than at import time so that importing this package cannot fail: the
+ * native module is only asked when an app actually names a directory, and the
+ * native side creates the per-app folders on that first read.
+ */
+function knownPaths(): KnownPaths {
+  if (cachedPaths === null) {
+    cachedPaths = NativeFs.getPaths();
+  }
+  return cachedPaths;
+}
+
+/**
+ * `paths.home`, `paths.documents` and the rest.
+ *
+ * Each property is a getter over one cached native read, so destructuring works
+ * and the object can be exported before the module has been asked anything.
+ */
+export const paths: KnownPaths = Object.defineProperties(
+  {},
+  Object.fromEntries(
+    KNOWN_PATH_NAMES.map(name => [
+      name,
+      { enumerable: true, get: () => knownPaths()[name] },
+    ]),
+  ),
+) as KnownPaths;
+
+/* -------------------------------------------------------------------------- */
+/* Sync forms                                                                 */
+/* -------------------------------------------------------------------------- */
+
+function readFileSync(path: string): Uint8Array;
+function readFileSync(
+  path: string,
+  options: Encoding | { encoding: Encoding },
+): string;
+function readFileSync(
+  path: string,
+  options?: Encoding | { encoding?: Encoding | null } | null,
+): Uint8Array | string {
+  const target = toPath(path);
+  const encoding =
+    typeof options === 'string' ? options : (options?.encoding ?? null);
+  try {
+    if (encoding === null) {
+      return new Uint8Array(NativeFs.readFileSync(target));
+    }
+    const normalized = normalizeEncoding(encoding) ?? 'utf8';
+    if (normalized === 'utf8') {
+      // The dedicated text method decodes in Rust instead of handing JS bytes
+      // to decode a second time.
+      return NativeFs.readTextFileSync(target);
+    }
+    return decodeString(
+      new Uint8Array(NativeFs.readFileSync(target)),
+      normalized,
+    );
+  } catch (error) {
+    throw withContext(error, 'open', target);
+  }
+}
+
+function writeFileSync(
+  path: string,
+  data: BinaryData,
+  options?: WriteOptions | Encoding,
+): void {
+  const target = toPath(path);
+  const opts: WriteOptions =
+    typeof options === 'string' ? { encoding: options } : (options ?? {});
+  const flag = flagFrom(
+    opts.flag,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC,
+  );
+  const mode = modeFrom(opts.mode);
+  try {
+    if (typeof data === 'string') {
+      const encoding = normalizeEncoding(opts.encoding ?? 'utf8') ?? 'utf8';
+      if (encoding === 'utf8') {
+        NativeFs.writeTextFileSync(target, data, flag, mode);
+        return;
+      }
+      NativeFs.writeFileSync(target, toArrayBuffer(data, encoding), flag, mode);
+      return;
+    }
+    NativeFs.writeFileSync(target, toArrayBuffer(data), flag, mode);
+  } catch (error) {
+    throw withContext(error, 'open', target);
+  }
+}
+
+function appendFileSync(
+  path: string,
+  data: BinaryData,
+  options?: WriteOptions | Encoding,
+): void {
+  const opts: WriteOptions =
+    typeof options === 'string' ? { encoding: options } : (options ?? {});
+  writeFileSync(path, data, {
+    ...opts,
+    flag:
+      opts.flag ?? constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND,
+  });
+}
+
+function existsSync(path: string): boolean {
+  try {
+    return NativeFs.existsSync(toPath(path));
+  } catch {
+    // `existsSync` answers a question rather than reporting a failure, so every
+    // error — a permission problem as much as a missing path — is a `false`.
+    return false;
+  }
+}
+
+function statSync(path: string): Stats {
+  const target = toPath(path);
+  try {
+    const result = NativeFs.statSync(target, true);
+    if (result === null) {
+      throw missingPath(target, 'stat');
+    }
+    return new Stats(result);
+  } catch (error) {
+    throw withContext(error, 'stat', target);
+  }
+}
+
+function lstatSync(path: string): Stats {
+  const target = toPath(path);
+  try {
+    const result = NativeFs.statSync(target, false);
+    if (result === null) {
+      throw missingPath(target, 'lstat');
+    }
+    return new Stats(result);
+  } catch (error) {
+    throw withContext(error, 'lstat', target);
+  }
+}
+
+function readdirSync(
+  path: string,
+  options?: { withFileTypes?: false; recursive?: boolean } | null,
+): string[];
+function readdirSync(
+  path: string,
+  options: { withFileTypes: true; recursive?: boolean },
+): Dirent[];
+function readdirSync(
+  path: string,
+  options?: { withFileTypes?: boolean; recursive?: boolean } | null,
+): string[] | Dirent[] {
+  const target = toPath(path);
+  try {
+    const recursive = options?.recursive ?? false;
+    const entries = NativeFs.readdirSync(target, recursive);
+    return options?.withFileTypes
+      ? entries.map(entry => new Dirent(entry))
+      : entries.map(entry =>
+          recursive
+            ? relativeEntryName(target, entry.parentPath, entry.name)
+            : entry.name,
+        );
+  } catch (error) {
+    throw withContext(error, 'scandir', target);
+  }
+}
+
+function mkdirSync(path: string, options?: MkdirOptions | number): void {
+  const target = toPath(path);
+  const opts: MkdirOptions =
+    typeof options === 'number' ? { mode: options } : (options ?? {});
+  try {
+    NativeFs.mkdirSync(
+      target,
+      opts.recursive ?? false,
+      modeFrom(opts.mode, 0o777),
+    );
+  } catch (error) {
+    throw withContext(error, 'mkdir', target);
+  }
+}
+
+function rmSync(path: string, options?: RmOptions): void {
+  const target = toPath(path);
+  try {
+    NativeFs.rmSync(
+      target,
+      options?.recursive ?? false,
+      options?.force ?? false,
+    );
+  } catch (error) {
+    throw withContext(error, 'rm', target);
+  }
+}
+
+function renameSync(from: string, to: string): void {
+  const source = toPath(from);
+  const destination = toPath(to);
+  try {
+    NativeFs.renameSync(source, destination);
+  } catch (error) {
+    const wrapped = withContext(error, 'rename', source);
+    // Node's rename error names both ends; the second is `dest`, not `path`.
+    if (wrapped.dest === undefined) {
+      wrapped.dest = destination;
+    }
+    throw wrapped;
+  }
+}
+
+function copyFileSync(from: string, to: string): void {
+  const source = toPath(from);
+  const destination = toPath(to);
+  try {
+    NativeFs.copyFileSync(source, destination);
+  } catch (error) {
+    const wrapped = withContext(error, 'copyfile', source);
+    if (wrapped.dest === undefined) {
+      wrapped.dest = destination;
+    }
+    throw wrapped;
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Callback forms                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The callback forms are wrappers over the promise implementations, as the
+ * design says, so there is one implementation of each operation.
+ *
+ * The trailing argument is the callback in every form; the optional argument
+ * before it is an options object (or an encoding, or a mode) when it is not a
+ * function. That is the whole of Node's overloading convention here.
+ */
+
+type NodeCallback<T> = (error: NodeError | null, value?: T) => void;
+
+function callbackOf<T>(args: unknown[]): NodeCallback<T> {
+  const callback = args[args.length - 1];
+  if (typeof callback !== 'function') {
+    throw new TypeError('A callback function is required');
+  }
+  return callback as NodeCallback<T>;
+}
+
+/** The options argument, if the caller supplied one rather than the callback. */
+function before<T>(args: unknown[], index: number, fallback: T): T {
+  const value = args[index];
+  return value === undefined || typeof value === 'function'
+    ? fallback
+    : (value as T);
+}
+
+/**
+ * Reports a settled promise the Node way.
+ *
+ * A rejection that has a callback is delivered to it; nothing is thrown, because
+ * a throw from here would escape the caller's stack rather than the callback.
+ */
+function settle<T>(promise: Promise<T>, callback: NodeCallback<T>): void {
+  promise.then(
+    value => callback(null, value),
+    (error: NodeError) => callback(error),
+  );
+}
+
+function readFile(
+  path: string,
+  callback: NodeCallback<Uint8Array | string>,
+): void;
+function readFile(
+  path: string,
+  options: Encoding | { encoding?: Encoding | null } | null,
+  callback: NodeCallback<Uint8Array | string>,
+): void;
+function readFile(path: string, ...args: unknown[]): void {
+  // The promise overloads keep the result precise; the callback form goes
+  // through the coarse alias because at that point the encoding is a runtime
+  // value and either shape is possible.
+  const options = before(args, 0, undefined) as
+    Encoding | { encoding?: Encoding | null } | null | undefined;
+  settle(readFileImpl(path, options), callbackOf(args));
+}
+
+function writeFile(
+  path: string,
+  data: BinaryData,
+  callback: NodeCallback<void>,
+): void;
+function writeFile(
+  path: string,
+  data: BinaryData,
+  options: WriteOptions | Encoding | null,
+  callback: NodeCallback<void>,
+): void;
+function writeFile(path: string, data: BinaryData, ...args: unknown[]): void {
+  settle(
+    promises.writeFile(
+      path,
+      data,
+      before(args, 0, undefined) as WriteOptions | Encoding | undefined,
+    ),
+    callbackOf(args),
+  );
+}
+
+function appendFile(
+  path: string,
+  data: BinaryData,
+  callback: NodeCallback<void>,
+): void;
+function appendFile(
+  path: string,
+  data: BinaryData,
+  options: WriteOptions | Encoding | null,
+  callback: NodeCallback<void>,
+): void;
+function appendFile(path: string, data: BinaryData, ...args: unknown[]): void {
+  settle(
+    promises.appendFile(
+      path,
+      data,
+      before(args, 0, undefined) as WriteOptions | Encoding | undefined,
+    ),
+    callbackOf(args),
+  );
+}
+
+function readdir(
+  path: string,
+  callback: NodeCallback<string[] | Dirent[]>,
+): void;
+function readdir(
+  path: string,
+  options: { withFileTypes?: boolean; recursive?: boolean } | null,
+  callback: NodeCallback<string[] | Dirent[]>,
+): void;
+function readdir(path: string, ...args: unknown[]): void {
+  const options = before(args, 0, null) as {
+    withFileTypes?: boolean;
+    recursive?: boolean;
+  } | null;
+  const pending: Promise<string[] | Dirent[]> = options?.withFileTypes
+    ? promises.readdir(path, { ...options, withFileTypes: true })
+    : promises.readdir(path, {
+        recursive: options?.recursive,
+        withFileTypes: false,
+      });
+  settle(pending, callbackOf(args));
+}
+
+function stat(path: string, callback: NodeCallback<Stats>): void;
+function stat(path: string, ...args: unknown[]): void {
+  settle(promises.stat(path), callbackOf([...args]));
+}
+
+function lstat(path: string, callback: NodeCallback<Stats>): void;
+function lstat(path: string, ...args: unknown[]): void {
+  settle(promises.lstat(path), callbackOf([...args]));
+}
+
+function mkdir(path: string, callback: NodeCallback<string | undefined>): void;
+function mkdir(
+  path: string,
+  options: MkdirOptions | number | null,
+  callback: NodeCallback<string | undefined>,
+): void;
+function mkdir(path: string, ...args: unknown[]): void {
+  settle(
+    promises.mkdir(
+      path,
+      before(args, 0, undefined) as MkdirOptions | number | undefined,
+    ),
+    callbackOf(args),
+  );
+}
+
+function rm(path: string, callback: NodeCallback<void>): void;
+function rm(
+  path: string,
+  options: RmOptions | null,
+  callback: NodeCallback<void>,
+): void;
+function rm(path: string, ...args: unknown[]): void {
+  settle(
+    promises.rm(path, before(args, 0, undefined) as RmOptions | undefined),
+    callbackOf(args),
+  );
+}
+
+function rename(from: string, to: string, callback: NodeCallback<void>): void;
+function rename(from: string, to: string, ...args: unknown[]): void {
+  settle(promises.rename(from, to), callbackOf([...args]));
+}
+
+function copyFile(from: string, to: string, callback: NodeCallback<void>): void;
+function copyFile(
+  from: string,
+  to: string,
+  mode: number,
+  callback: NodeCallback<void>,
+): void;
+function copyFile(from: string, to: string, ...args: unknown[]): void {
+  settle(
+    promises.copyFile(
+      from,
+      to,
+      before(args, 0, undefined) as number | undefined,
+    ),
+    callbackOf(args),
+  );
+}
+
+function cp(from: string, to: string, callback: NodeCallback<void>): void;
+function cp(
+  from: string,
+  to: string,
+  options: { recursive?: boolean } | null,
+  callback: NodeCallback<void>,
+): void;
+function cp(from: string, to: string, ...args: unknown[]): void {
+  settle(
+    promises.cp(
+      from,
+      to,
+      before(args, 0, undefined) as { recursive?: boolean } | undefined,
+    ),
+    callbackOf(args),
+  );
+}
+
+function access(path: string, callback: NodeCallback<void>): void;
+function access(path: string, mode: number, callback: NodeCallback<void>): void;
+function access(path: string, ...args: unknown[]): void {
+  settle(
+    promises.access(path, before(args, 0, undefined) as number | undefined),
+    callbackOf(args),
+  );
+}
+
+function realpath(path: string, callback: NodeCallback<string>): void;
+function realpath(path: string, ...args: unknown[]): void {
+  settle(promises.realpath(path), callbackOf([...args]));
+}
+
+function readlink(path: string, callback: NodeCallback<string>): void;
+function readlink(path: string, ...args: unknown[]): void {
+  settle(promises.readlink(path), callbackOf([...args]));
+}
+
+function symlink(
+  target: string,
+  path: string,
+  callback: NodeCallback<void>,
+): void;
+function symlink(
+  target: string,
+  path: string,
+  type: string,
+  callback: NodeCallback<void>,
+): void;
+function symlink(target: string, path: string, ...args: unknown[]): void {
+  settle(
+    promises.symlink(
+      target,
+      path,
+      before(args, 0, undefined) as 'file' | 'dir' | 'junction' | undefined,
+    ),
+    callbackOf(args),
+  );
+}
+
+function truncate(path: string, callback: NodeCallback<void>): void;
+function truncate(
+  path: string,
+  length: number,
+  callback: NodeCallback<void>,
+): void;
+function truncate(path: string, ...args: unknown[]): void {
+  settle(
+    promises.truncate(path, before(args, 0, undefined) as number | undefined),
+    callbackOf(args),
+  );
+}
+
+function utimes(
+  path: string,
+  atime: Date | number | string,
+  mtime: Date | number | string,
+  callback: NodeCallback<void>,
+): void;
+function utimes(
+  path: string,
+  atime: Date | number | string,
+  mtime: Date | number | string,
+  ...args: unknown[]
+): void {
+  settle(promises.utimes(path, atime, mtime), callbackOf([...args]));
+}
+
+function chmod(
+  path: string,
+  mode: number | string,
+  callback: NodeCallback<void>,
+): void;
+function chmod(path: string, mode: number | string, ...args: unknown[]): void {
+  settle(promises.chmod(path, mode), callbackOf([...args]));
+}
+
+function mkdtemp(prefix: string, callback: NodeCallback<string>): void;
+function mkdtemp(
+  prefix: string,
+  options: Encoding | { encoding?: Encoding },
+  callback: NodeCallback<string>,
+): void;
+function mkdtemp(prefix: string, ...args: unknown[]): void {
+  settle(
+    promises.mkdtemp(
+      prefix,
+      before(args, 0, undefined) as
+        Encoding | { encoding?: Encoding } | undefined,
+    ),
+    callbackOf(args),
+  );
+}
+
+function open(path: string, callback: NodeCallback<FileHandle>): void;
+function open(
+  path: string,
+  flags: string | number | OpenOptions,
+  callback: NodeCallback<FileHandle>,
+): void;
+function open(
+  path: string,
+  flags: string | number | OpenOptions,
+  mode: number | string,
+  callback: NodeCallback<FileHandle>,
+): void;
+function open(path: string, ...args: unknown[]): void {
+  const flags = before(args, 0, undefined) as
+    string | number | OpenOptions | undefined;
+  const mode = before(args, 1, undefined) as number | string | undefined;
+  settle(
+    mode === undefined
+      ? promises.open(path, flags)
+      : promises.open(path, flags, mode),
+    callbackOf(args),
+  );
+}
+
+function reveal(path: string, callback: NodeCallback<void>): void;
+function reveal(path: string, ...args: unknown[]): void {
+  settle(promises.reveal(path), callbackOf([...args]));
+}
+
+function openExternal(path: string, callback: NodeCallback<void>): void;
+function openExternal(path: string, ...args: unknown[]): void {
+  settle(promises.openExternal(path), callbackOf([...args]));
+}
+
+/* -------------------------------------------------------------------------- */
+/* The `fs` object                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Node's `fs`, as far as this platform implements it.
+ *
+ * The callback forms wrap the promise implementations; the sync forms call the
+ * bridge's JS-thread methods directly; `promises` is the same object shape Node
+ * exposes as `fs.promises`.
+ */
+const fs = {
+  constants,
+  promises,
+
+  readFile,
+  writeFile,
+  appendFile,
+  readdir,
+  stat,
+  lstat,
+  mkdir,
+  rm,
+  rename,
+  copyFile,
+  cp,
+  access,
+  realpath,
+  readlink,
+  symlink,
+  truncate,
+  utimes,
+  chmod,
+  mkdtemp,
+  open,
+  reveal,
+  openExternal,
+
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+  existsSync,
+  statSync,
+  lstatSync,
+  readdirSync,
+  mkdirSync,
+  rmSync,
+  renameSync,
+  copyFileSync,
+
+  Stats,
+  Dirent,
+  FileHandle,
+};
+
+export default fs;