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

package/src/stats.ts

@@ -0,0 +1,196 @@
+/**
+ * `Stats` and `Dirent`, built over the plain objects the native module returns.
+ *
+ * The module crosses the bridge with numbers rather than methods — a generated
+ * TurboModule result cannot carry predicates — so the classes live here and
+ * reproduce the shape Node's callers test for. The `kind` field is the coarse
+ * classification the native side can make without a platform syscall; `mode` is
+ * there for the finer predicates, and is zero on Windows where there are no
+ * Unix mode bits at all.
+ */
+
+import { constants } from './constants';
+
+/** The native `FileKind` numbers; must match `module::kind` in Rust. */
+export const FILE_KIND = {
+  file: 0,
+  directory: 1,
+  symlink: 2,
+  other: 3,
+} as const;
+
+/** The shape `stat`, `lstat` and `fstat` return across the bridge. */
+export interface StatResult {
+  size: number;
+  mode: number;
+  kind: number;
+  atimeMs: number;
+  mtimeMs: number;
+  ctimeMs: number;
+  birthtimeMs: number;
+  dev: number;
+  ino: number;
+  nlink: number;
+  uid: number;
+  gid: number;
+}
+
+/** The shape `readdir` returns across the bridge. */
+export interface DirEntryResult {
+  name: string;
+  kind: number;
+  parentPath: string;
+}
+
+/** The type bits of a mode, or 0 when the platform does not report them. */
+function fileTypeBits(mode: number): number {
+  return mode & constants.S_IFMT;
+}
+
+/**
+ * Node's `fs.Stats`.
+ *
+ * The fields are plain properties rather than getters: they are copied once from
+ * the native result, and a caller destructuring the object sees the same values
+ * Node's does.
+ */
+export class Stats {
+  readonly dev: number;
+  readonly ino: number;
+  readonly mode: number;
+  readonly nlink: number;
+  readonly uid: number;
+  readonly gid: number;
+  readonly rdev: number;
+  readonly size: number;
+  readonly blksize: number;
+  readonly blocks: number;
+
+  readonly atimeMs: number;
+  readonly mtimeMs: number;
+  readonly ctimeMs: number;
+  readonly birthtimeMs: number;
+
+  readonly atime: Date;
+  readonly mtime: Date;
+  readonly ctime: Date;
+  readonly birthtime: Date;
+
+  /** The native classification, kept because it answers predicates the mode
+   * cannot on platforms that report no type bits. */
+  private readonly kind: number;
+
+  constructor(result: StatResult) {
+    this.dev = result.dev;
+    this.ino = result.ino;
+    this.mode = result.mode;
+    this.nlink = result.nlink;
+    this.uid = result.uid;
+    this.gid = result.gid;
+    // The native result has no `rdev`, block size or block count; Node reports
+    // zero for them where the platform cannot say, so zero is the honest value.
+    this.rdev = 0;
+    this.size = result.size;
+    this.blksize = 0;
+    this.blocks = 0;
+
+    this.atimeMs = result.atimeMs;
+    this.mtimeMs = result.mtimeMs;
+    this.ctimeMs = result.ctimeMs;
+    this.birthtimeMs = result.birthtimeMs;
+
+    this.atime = new Date(result.atimeMs);
+    this.mtime = new Date(result.mtimeMs);
+    this.ctime = new Date(result.ctimeMs);
+    this.birthtime = new Date(result.birthtimeMs);
+
+    this.kind = result.kind;
+  }
+
+  isFile(): boolean {
+    const bits = fileTypeBits(this.mode);
+    return bits === 0
+      ? this.kind === FILE_KIND.file
+      : bits === constants.S_IFREG;
+  }
+
+  isDirectory(): boolean {
+    const bits = fileTypeBits(this.mode);
+    return bits === 0
+      ? this.kind === FILE_KIND.directory
+      : bits === constants.S_IFDIR;
+  }
+
+  isSymbolicLink(): boolean {
+    const bits = fileTypeBits(this.mode);
+    return bits === 0
+      ? this.kind === FILE_KIND.symlink
+      : bits === constants.S_IFLNK;
+  }
+
+  isBlockDevice(): boolean {
+    return fileTypeBits(this.mode) === constants.S_IFBLK;
+  }
+
+  isCharacterDevice(): boolean {
+    return fileTypeBits(this.mode) === constants.S_IFCHR;
+  }
+
+  isFIFO(): boolean {
+    return fileTypeBits(this.mode) === constants.S_IFIFO;
+  }
+
+  isSocket(): boolean {
+    return fileTypeBits(this.mode) === constants.S_IFSOCK;
+  }
+}
+
+/**
+ * Node's `fs.Dirent`.
+ *
+ * `parentPath` is `''` when the caller already held the parent, matching what
+ * `readdir` with `{withFileTypes: true}` produces there.
+ */
+export class Dirent {
+  readonly name: string;
+  readonly parentPath: string;
+  readonly path: string;
+
+  private readonly kind: number;
+
+  constructor(result: DirEntryResult) {
+    this.name = result.name;
+    this.parentPath = result.parentPath;
+    // `path` is the older name for the same field, and libraries still read it.
+    this.path = result.parentPath;
+    this.kind = result.kind;
+  }
+
+  isFile(): boolean {
+    return this.kind === FILE_KIND.file;
+  }
+
+  isDirectory(): boolean {
+    return this.kind === FILE_KIND.directory;
+  }
+
+  isSymbolicLink(): boolean {
+    return this.kind === FILE_KIND.symlink;
+  }
+
+  isBlockDevice(): boolean {
+    return false;
+  }
+
+  isCharacterDevice(): boolean {
+    return false;
+  }
+
+  isFIFO(): boolean {
+    return false;
+  }
+
+  isSocket(): boolean {
+    return false;
+  }
+}

package/src/upload.ts

@@ -0,0 +1,97 @@
+/**
+ * `upload`: a file, or a range of one, streamed as an HTTP request body.
+ *
+ * The native side reads the file in small blocks while the connection takes
+ * them, so nothing larger than a block is ever held in memory.
+ */
+
+import NativeFs from './NativeFs';
+import { nodeError, toPath, withContext, type NodeError } from './shared';
+
+export interface UploadOptions {
+  /** `PUT` unless set. */
+  method?: string;
+  headers?: Record<string, string>;
+  /** Where in the file the body starts. Zero unless set. */
+  offset?: number;
+  /** How many bytes to send. Everything from `offset` unless set. */
+  length?: number;
+  /** Called while the body is sent. */
+  onProgress?: (sent: number, total: number) => void;
+  /** Aborting rejects with an `AbortError`. */
+  signal?: AbortSignal;
+}
+
+export interface UploadResult {
+  status: number;
+  /** Response headers, lower-cased; repeated headers are joined with `, `. */
+  headers: Record<string, string>;
+  /** The first part of the response body. */
+  body: string;
+}
+
+let nextId = 1;
+
+function abortError(): NodeError {
+  const error = nodeError('ABORT_ERR', 'The upload was aborted');
+  error.name = 'AbortError';
+  return error;
+}
+
+function toRecord(list: Array<{ name: string; value: string }>) {
+  const record: Record<string, string> = {};
+  for (const { name, value } of list) {
+    record[name] = value;
+  }
+  return record;
+}
+
+export async function upload(
+  url: string,
+  path: string,
+  options: UploadOptions = {},
+): Promise<UploadResult> {
+  const { signal, onProgress } = options;
+  if (signal?.aborted) {
+    throw abortError();
+  }
+  const source = toPath(path);
+  const id = nextId++;
+  const subscription = onProgress
+    ? NativeFs.onUploadProgress(event => {
+        if (event.id === id) {
+          onProgress(event.sent, event.total);
+        }
+      })
+    : null;
+  const onAbort = () => {
+    NativeFs.cancelUpload(id);
+  };
+  signal?.addEventListener('abort', onAbort);
+
+  try {
+    const result = await NativeFs.upload(url, source, {
+      id,
+      method: options.method ?? 'PUT',
+      headers: Object.entries(options.headers ?? {}).map(([name, value]) => ({
+        name,
+        value,
+      })),
+      offset: options.offset ?? 0,
+      length: options.length ?? -1,
+    });
+    return {
+      status: result.status,
+      headers: toRecord(result.headers),
+      body: result.body,
+    };
+  } catch (error) {
+    if (signal?.aborted || (error as NodeError)?.code === 'ABORT_ERR') {
+      throw abortError();
+    }
+    throw withContext(error, 'upload', source);
+  } finally {
+    signal?.removeEventListener('abort', onAbort);
+    subscription?.remove();
+  }
+}

package/src/watch.ts

@@ -0,0 +1,141 @@
+/**
+ * `watch`: the JS half of the typed watcher event.
+ *
+ * The native module returns a watcher id; every event it produces carries that
+ * id, so one shared emitter serves every open watcher and each listener keeps
+ * only its own. The subscription is taken through the generated typed emitter on
+ * the module (`NativeFs.onWatchEvent`), which is the same mechanism the fixture's
+ * `onProgress` uses in `RustTurboModuleFixture.tsx`, rather than through
+ * `NativeEventEmitter`: the spec declares `onWatchEvent` as a typed
+ * `CodegenTypes.EventEmitter`, and the bridge installs a listener for exactly
+ * that; `NativeEventEmitter` would subscribe on the global device-emitter channel
+ * that only `sendEvent` writes to, so it would never fire.
+ */
+
+import NativeFs, { type WatchEvent } from './NativeFs';
+import { toPath, withContext, type NodeError } from './shared';
+
+/** The event names Node uses for the two things a watcher reports. */
+export type WatchEventType = 'rename' | 'change';
+
+export interface WatchOptions {
+  recursive?: boolean;
+  encoding?: string;
+}
+
+export interface FSWatcher {
+  close(): Promise<void>;
+}
+
+export type WatchListener = (
+  eventType: WatchEventType,
+  filename: string | null,
+) => void;
+
+/**
+ * Which of Node's two event types a native kind is.
+ *
+ * Node folds everything it sees into `rename` (the entry appeared, vanished or
+ * moved) and `change` (its contents or metadata changed). The caller's callback
+ * signature is Node's, so the mapping happens here while the native kind stays
+ * available to anyone who subscribes to the module directly.
+ */
+function eventTypeOf(kind: string): WatchEventType {
+  return kind === 'modify' ? 'change' : 'rename';
+}
+
+/** The file a path names, relative to the watched root where it is below it. */
+/**
+ * The filename a listener is given.
+ *
+ * The native side already reported it relative to the watch root, and its own
+ * name for a single-file watch: it canonicalises the root, which is where macOS
+ * decides between `/var` and `/private/var`, and it strips whichever spelling the
+ * event actually carries. Stripping a prefix here as well would be a second,
+ * weaker guess at the same question — a relative root never matches, and Windows
+ * separates with `\` — so the event path is passed through unchanged.
+ */
+function fileNameOf(eventPath: string): string {
+  return eventPath;
+}
+
+/**
+ * Starts a watcher.
+ *
+ * The id arrives asynchronously, but the caller expects a handle it can close
+ * immediately, so the handle is created first and closing it before the id is
+ * known sets a flag the resolution honours. That is the one ordering hazard in
+ * this API, and it is invisible from the outside.
+ *
+ * Node reports a failure to start through an `error` event on the watcher. This
+ * handle has no event surface, so the failure is held and rejected from
+ * `close()` instead: it can then never become an unhandled rejection, and a
+ * caller that closes what it opened is guaranteed to see it.
+ */
+export function watch(path: string, listener: WatchListener): FSWatcher;
+export function watch(
+  path: string,
+  options: WatchOptions | null,
+  listener: WatchListener,
+): FSWatcher;
+export function watch(
+  path: string,
+  optionsOrListener: WatchOptions | null | WatchListener,
+  maybeListener?: WatchListener,
+): FSWatcher {
+  const options =
+    typeof optionsOrListener === 'function' ? {} : (optionsOrListener ?? {});
+  const listener =
+    typeof optionsOrListener === 'function' ? optionsOrListener : maybeListener;
+  if (typeof listener !== 'function') {
+    throw new TypeError('watch requires a listener function');
+  }
+
+  const target = toPath(path);
+  let id: number | null = null;
+  let closed = false;
+  let failure: NodeError | null = null;
+  let subscription: { remove(): void } | null = null;
+
+  const ready = NativeFs.watch(target, options.recursive ?? false)
+    .then(watcherId => {
+      id = watcherId;
+      if (closed) {
+        // `close()` ran while the id was in flight; stop the native watcher now
+        // that there is something to stop.
+        NativeFs.unwatch(watcherId);
+        return;
+      }
+      subscription = NativeFs.onWatchEvent((event: WatchEvent) => {
+        if (event.id !== id) {
+          return;
+        }
+        // The encoding option only affects how a non-ASCII name is decoded, and
+        // every name already arrives as a JS string.
+        listener(eventTypeOf(event.kind), fileNameOf(event.path));
+      });
+    })
+    .catch((error: unknown) => {
+      failure = withContext(error, 'watch', target);
+    });
+
+  return {
+    async close(): Promise<void> {
+      closed = true;
+      subscription?.remove();
+      subscription = null;
+      if (id !== null) {
+        NativeFs.unwatch(id);
+        id = null;
+      }
+      // Awaiting the start makes `close()` immediately after `watch()` still stop
+      // the native watcher rather than racing it.
+      await ready;
+      if (failure !== null) {
+        const error = failure;
+        failure = null;
+        throw error;
+      }
+    },
+  };
+}