feat: 🎸 add scaffold for CoreFileSystemObserver implementation and restructure fsa() helper

Author: streamich

.vscode/settings.json

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

src/fsa/CoreFileSystemObserver.ts

@@ -0,0 +1,18 @@
+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__/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,39 @@
 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';
@@ -213,14 +211,6 @@ export interface IFileSystemObserverObserveOptions {
  * @see https://developer.mozilla.org/en-US/docs/Web/API/FileSystemObserver
  */
 export interface IFileSystemObserver {
-  /**
-   * 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;
-
   /**
    * Start observing changes to a given file or directory.
    *
@@ -232,3 +222,13 @@ export interface IFileSystemObserver {
   /** 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;
+}