Merge pull request #1180 from streamich/fsa-observable

Reactivity improvements

Author: streamich

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

src/core/Link.ts

@@ -1,14 +1,22 @@
-import { EventEmitter } from 'events';
 import { constants, PATH } from '../constants';
+import { FanOut } from 'thingies/lib/fanout';
 import type { Node } from './Node';
 import type { Superblock } from './Superblock';
 
+export type LinkEventChildAdd = [type: 'child:add', link: Link, parent: Link];
+
+export type LinkEventChildDelete = [type: 'child:del', link: Link, parent: Link];
+
+export type LinkEvent = LinkEventChildAdd | LinkEventChildDelete;
+
 const { S_IFREG } = constants;
 
 /**
  * Represents a hard link that points to an i-node `node`.
  */
-export class Link extends EventEmitter {
+export class Link {
+  public readonly changes = new FanOut<LinkEvent>();
+
   vol: Superblock;
 
   parent: Link | undefined;
@@ -45,7 +53,6 @@ export class Link extends EventEmitter {
   }
 
   constructor(vol: Superblock, parent: Link | undefined, name: string) {
-    super();
     this.vol = vol;
     this.parent = parent;
     this.name = name;
@@ -87,7 +94,7 @@ export class Link extends EventEmitter {
     }
 
     this.getNode().mtime = new Date();
-    this.emit('child:add', link, this);
+    this.changes.emit(['child:add', link, this]);
 
     return link;
   }
@@ -102,7 +109,7 @@ export class Link extends EventEmitter {
     this.length--;
 
     this.getNode().mtime = new Date();
-    this.emit('child:delete', link, this);
+    this.changes.emit(['child:del', link, this]);
   }
 
   getChild(name: string): Link | undefined {

src/core/Node.ts

@@ -1,7 +1,13 @@
+import { FanOut } from 'thingies/lib/fanout';
 import process from '../process';
 import { Buffer, bufferAllocUnsafe, bufferFrom } from '../internal/buffer';
 import { constants, S } from '../constants';
-import { EventEmitter } from 'events';
+
+export type NodeEventModify = [type: 'modify'];
+
+export type NodeEventDelete = [type: 'delete'];
+
+export type NodeEvent = NodeEventModify | NodeEventDelete;
 
 const { S_IFMT, S_IFDIR, S_IFREG, S_IFLNK, S_IFCHR } = constants;
 const getuid = (): number => process.getuid?.() ?? 0;
@@ -10,7 +16,9 @@ const getgid = (): number => process.getgid?.() ?? 0;
 /**
  * Node in a file system (like i-node, v-node).
  */
-export class Node extends EventEmitter {
+export class Node {
+  public readonly changes = new FanOut<NodeEvent>();
+
   // i-node number.
   ino: number;
 
@@ -35,7 +43,6 @@ export class Node extends EventEmitter {
   symlink: string;
 
   constructor(ino: number, mode: number = 0o666) {
-    super();
     this.mode = mode;
     this.ino = ino;
   }
@@ -221,7 +228,7 @@ export class Node extends EventEmitter {
 
   touch() {
     this.mtime = new Date();
-    this.emit('change', this);
+    this.changes.emit(['modify']);
   }
 
   canRead(uid: number = getuid(), gid: number = getgid()): boolean {
@@ -285,7 +292,7 @@ export class Node extends EventEmitter {
   }
 
   del() {
-    this.emit('delete', this);
+    this.changes.emit(['delete']);
   }
 
   toJSON() {

src/fsa/CoreFileSystemFileHandle.ts

@@ -9,7 +9,6 @@ import type {
   IFileSystemSyncAccessHandle,
 } from './types';
 import type { Superblock } from '../core/Superblock';
-import { Buffer } from '../internal/buffer';
 import { ERROR_CODE } from '../core/constants';
 
 export class CoreFileSystemFileHandle extends CoreFileSystemHandle implements IFileSystemFileHandle {

src/fsa/CoreFileSystemObserver.ts

@@ -0,0 +1,28 @@
+import type {
+  IFileSystemChangeRecord,
+  IFileSystemDirectoryHandle,
+  IFileSystemFileHandle,
+  IFileSystemObserver,
+  IFileSystemObserverObserveOptions,
+  IFileSystemSyncAccessHandle,
+} from './types';
+import type { Superblock } from '../core';
+
+export class CoreFileSystemObserver implements IFileSystemObserver {
+  constructor(
+    protected readonly _core: Superblock,
+    protected readonly callback: (records: IFileSystemChangeRecord[], observer: IFileSystemObserver) => void,
+  ) {}
+
+  public async observe(
+    handle: IFileSystemFileHandle | IFileSystemDirectoryHandle | IFileSystemSyncAccessHandle,
+    options?: IFileSystemObserverObserveOptions,
+  ): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+
+  /** Disconnect and stop all observations. */
+  public disconnect(): void {
+    throw new Error('Method not implemented.');
+  }
+}

src/fsa/__tests__/CoreFileSystemHandle.test.ts

@@ -1,6 +1,5 @@
 import { Superblock } from '../../core/Superblock';
 import { CoreFileSystemDirectoryHandle } from '../CoreFileSystemDirectoryHandle';
-import { CoreFileSystemFileHandle } from '../CoreFileSystemFileHandle';
 import { onlyOnNode20 } from '../../__tests__/util';
 import { DirectoryJSON } from '../../core/json';
 

src/fsa/__tests__/CoreFileSystemObserver.test.ts

@@ -0,0 +1,25 @@
+import { fsa, IFileSystemChangeRecord } from '..';
+import { onlyOnNode20 } from '../../__tests__/util';
+
+onlyOnNode20('CoreFileSystemObserver', () => {
+  test.skip('can listen to file writes', async () => {
+    const { dir, FileSystemObserver } = fsa({ mode: 'readwrite' });
+    const changes: IFileSystemChangeRecord[] = [];
+    const observer = new FileSystemObserver(records => {
+      changes.push(...records);
+    });
+    const file = await dir.getFileHandle('file.txt', { create: true });
+    await observer.observe(file);
+    expect(changes).toEqual([]);
+    const writable = await file.createWritable();
+    await writable.write('Hello, world!');
+    await writable.close();
+    expect(changes.length).toBe(1);
+    expect(changes).toMatchObject([
+      {
+        type: 'modified',
+      },
+    ]);
+    observer.disconnect();
+  });
+});

src/fsa/__tests__/scenarios.test.ts

@@ -1,8 +1,16 @@
 import { Superblock } from '../../core/Superblock';
-import { coreToFsa, fsa } from '../index';
+import { CoreFsaContext, fsa } from '../index';
 import { CoreFileSystemDirectoryHandle } from '../CoreFileSystemDirectoryHandle';
 import { onlyOnNode20 } from '../../__tests__/util';
-import { fileURLToPath } from 'url';
+
+const coreToFsa = (
+  core: Superblock,
+  dirPath: string = '/',
+  ctx?: Partial<CoreFsaContext>,
+): CoreFileSystemDirectoryHandle => {
+  const { dir } = fsa(ctx, core, dirPath);
+  return dir;
+};
 
 onlyOnNode20('coreToFsa scenarios', () => {
   test('can create FSA from empty Superblock', () => {

src/fsa/index.ts

@@ -1,37 +1,44 @@
 import { CoreFileSystemDirectoryHandle } from './CoreFileSystemDirectoryHandle';
-import { CoreFsaContext } from './types';
+import {
+  CoreFsaContext,
+  IFileSystemChangeRecord,
+  IFileSystemObserver,
+  IFileSystemObserverConstructable,
+} from './types';
 import { Superblock } from '../core/Superblock';
+import { CoreFileSystemObserver } from './CoreFileSystemObserver';
 
 export * from './types';
 export * from './CoreFileSystemHandle';
 export * from './CoreFileSystemDirectoryHandle';
 export * from './CoreFileSystemFileHandle';
 export * from './CoreFileSystemSyncAccessHandle';
 export * from './CoreFileSystemWritableFileStream';
+export * from './CoreFileSystemObserver';
 export * from './CorePermissionStatus';
 
-/**
- * Creates a File System Access API implementation on top of a Superblock.
- */
-export const coreToFsa = (
-  core: Superblock,
-  dirPath: string = '/',
-  ctx?: Partial<CoreFsaContext>,
-): CoreFileSystemDirectoryHandle => {
-  return new CoreFileSystemDirectoryHandle(core, dirPath, ctx);
-};
-
 /**
  * Create a new instance of an in-memory File System Access API
  * implementation rooted at the root directory of the filesystem.
  *
  * @param ctx Optional context for the File System Access API.
+ * @param core Optional low-level file system implementation to
+ *     back the File System Access API. If not provided, a new empty
+ *     Superblock instance will be created.
+ * @param dirPath Optional path within the filesystem to use as the root
+ *     directory of the File System Access API. Defaults to `/`.
  * @returns A File System Access API implementation `dir` rooted at
- *     the root directory of the filesystem, as well as the `core`
- *     file system itself.
+ *     the root directory of the filesystem, as well as the `core`,
+ *     a low-level file system implementation itself. Also, returns
+ *     `FileSystemObserver`, a class that can be used to create
+ *     observers that watch for changes to files and directories.
  */
-export const fsa = (ctx?: Partial<CoreFsaContext>) => {
-  const core = new Superblock();
-  const dir = new CoreFileSystemDirectoryHandle(core, '/', ctx);
-  return { dir, core };
+export const fsa = (ctx?: Partial<CoreFsaContext>, core = new Superblock(), dirPath: string = '/') => {
+  const dir = new CoreFileSystemDirectoryHandle(core, dirPath, ctx);
+  const FileSystemObserver: IFileSystemObserverConstructable = class FileSystemObserver extends CoreFileSystemObserver {
+    constructor(callback: (records: IFileSystemChangeRecord[], observer: IFileSystemObserver) => void) {
+      super(core, callback);
+    }
+  };
+  return { core, dir, FileSystemObserver };
 };

src/fsa/types.ts

@@ -1,5 +1,3 @@
-import type { Superblock } from '../core/Superblock';
-
 export interface IPermissionStatus {
   name: string;
   state: 'granted' | 'denied' | 'prompt';
@@ -126,3 +124,105 @@ export type Data =
   | DataView
   | Blob
   | string;
+
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord
+ */
+export interface IFileSystemChangeRecord {
+  /**
+   * A reference to the file system handle that the change was observed on. This
+   * property will be null for records with a "disappeared", "errored", or
+   * "unknown" type.
+   */
+  changedHandle: IFileSystemHandle | IFileSystemSyncAccessHandle | IFileSystemDirectoryHandle | null;
+
+  /**
+   * An array containing the path components that make up the relative file path
+   * from the `root` to the `changedHandle`, including the `changedHandle`
+   * filename.
+   */
+  relativePathComponents: string[];
+
+  /**
+   * An array containing the path components that make up the relative file path
+   * from the `root` to the `changedHandle`'s former location, in the case of
+   * observations with a `"moved"` type. If the type is not `"moved"`, this
+   * property will be `null`.
+   */
+  relativePathMovedFrom: string[] | null;
+
+  /**
+   * A reference to the root file system handle, that is, the one passed to the
+   * `observe()` call that started the observation.
+   */
+  root: IFileSystemHandle | IFileSystemSyncAccessHandle | IFileSystemDirectoryHandle;
+
+  /**
+   * The type of change that occurred.
+   */
+  type: /** The file or directory was created or moved into the `root` file structure. */
+  | 'appeared'
+
+    /**
+     * The file or directory was deleted or moved out of the root file structure.
+     * To find out which file or directory `disappeared`, you can query the
+     * `relativePathComponents` property.
+     */
+    | 'disappeared'
+
+    /** An error state occurred in the observed directory. */
+    | 'errored'
+
+    /** The file or directory was modified. */
+    | 'modified'
+
+    /**
+     * The file or directory was moved within the root file structure.
+     *
+     * Chrome note: On Windows, "moved" observations aren't supported between
+     * directories. They are reported as a "disappeared" observation in the
+     * source directory and an "appeared" observation in the destination directory.
+     */
+    | 'moved'
+
+    /**
+     * Indicates that some observations were missed. If you wish to find out
+     * information on what changed in the missed observations, you could fall
+     * back to polling the observed directory.
+     */
+    | 'unknown';
+}
+
+export interface IFileSystemObserverObserveOptions {
+  /** Whether to observe changes recursively in subdirectories. */
+  recursive?: boolean;
+}
+
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/FileSystemObserver
+ */
+export interface IFileSystemObserver {
+  /**
+   * Start observing changes to a given file or directory.
+   *
+   * @param handle The file or directory handle to observe.
+   * @param options Optional settings for the observation.
+   */
+  observe(
+    handle: IFileSystemFileHandle | IFileSystemDirectoryHandle | IFileSystemSyncAccessHandle,
+    options?: IFileSystemObserverObserveOptions,
+  ): Promise<void>;
+
+  /** Disconnect and stop all observations. */
+  disconnect(): void;
+}
+
+export interface IFileSystemObserverConstructable {
+  /**
+   * Constructor for creating a FileSystemObserver.
+   *
+   * @param callback Function called with file system change records and the
+   *     observer instance
+   */
+  new (callback: (records: IFileSystemChangeRecord[], observer: IFileSystemObserver) => void): IFileSystemObserver;
+}