Merge pull request #1262 from streamich/fs-core-events

feat: 🎸 add event emission to fs-core

Author: streamich

.gitignore

@@ -26,3 +26,5 @@ out.bin
 .claude/
 
 .yarn/install-state.gz
+
+.docs/

packages/fs-core/src/Superblock.ts

@@ -21,6 +21,7 @@ import type { PathLike } from '@jsonjoy.com/fs-node-utils/lib/types/misc';
 import { ERROR_CODE } from './constants';
 import { TFileId, StatError } from './types';
 import { Err, Ok, Result } from './result';
+import { FsEvent, FsEventType } from './watch/FsEvent';
 
 const pathSep = posix ? posix.sep : sep;
 const pathRelative = posix ? posix.relative : relative;
@@ -101,6 +102,12 @@ export class Superblock {
     this.root = root;
   }
 
+  public onchange?: (event: FsEvent) => void;
+
+  protected emit(change: FsEvent) {
+    if (this.onchange) this.onchange(change);
+  }
+
   createLink(): Link;
   createLink(parent: Link, name: string, isDirectory?: boolean, mode?: number): Link;
   createLink(parent?: Link, name?: string, isDirectory: boolean = false, mode?: number): Link {
@@ -132,6 +139,17 @@ export class Superblock {
     return false;
   }
 
+  private _emitDeleteRecursive(link: Link) {
+    if (link.getNode().isDirectory()) {
+      for (const [name, child] of link.children.entries()) {
+        if (child && name !== '.' && name !== '..') {
+          this._emitDeleteRecursive(child);
+        }
+      }
+    }
+    this.emit(new FsEvent(FsEventType.DELETE, link.steps, link.getNode()));
+  }
+
   private newInoNumber(): number {
     const releasedFd = this.releasedInos.pop();
 
@@ -489,7 +507,10 @@ export class Superblock {
     this.fds[file.fd] = file;
     this.openFiles++;
 
-    if (flagsNum & O_TRUNC) file.truncate();
+    if (flagsNum & O_TRUNC) {
+      file.truncate();
+      this.emit(new FsEvent(FsEventType.MODIFY, file.link.steps, file.node));
+    }
 
     return file;
   }
@@ -527,6 +548,7 @@ export class Superblock {
         modeNum ??= 0o666;
 
         link = this.createLink(dirLink, steps[steps.length - 1], false, modeNum);
+        this.emit(new FsEvent(FsEventType.CREATE, link.steps, link.getNode()));
       } else throw err;
     }
 
@@ -622,13 +644,15 @@ export class Superblock {
     if (dir2.getChild(name)) throw createError(ERROR_CODE.EEXIST, 'link', filename1, filename2);
     const node = link1.getNode();
     node.nlink++;
-    dir2.createChild(name, node);
+    const newLink = dir2.createChild(name, node);
+    this.emit(new FsEvent(FsEventType.CREATE, newLink.steps, node));
   };
 
   public readonly unlink = (filename: string) => {
     const link: Link = this.getLinkOrThrow(filename, 'unlink');
     // TODO: Check if it is file, dir, other...
     if (link.length) throw Error('Dir not empty...');
+    this._emitDeleteRecursive(link);
     this.deleteLink(link);
     const node = link.getNode();
     node.nlink--;
@@ -661,6 +685,7 @@ export class Superblock {
     // Create symlink.
     const symlink: Link = dirLink.createChild(name);
     symlink.getNode().makeSymlink(targetFilename);
+    this.emit(new FsEvent(FsEventType.CREATE, symlink.steps, symlink.getNode()));
     return symlink;
   };
 
@@ -709,9 +734,11 @@ export class Superblock {
 
     // Rename should overwrite the new path, if that exists.
     const name = basename(newPathFilename);
+    const oldSteps = link.steps;
     link.name = name;
     link.steps = [...newPathDirLink.steps, name];
     newPathDirLink.setChild(link.getName(), link);
+    this.emit(new FsEvent(FsEventType.MOVE, link.steps, link.getNode(), oldSteps));
   };
 
   public readonly mkdir = (filename: string, modeNum: number): void => {
@@ -724,7 +751,8 @@ export class Superblock {
     if (dir.getChild(name)) throw createError(ERROR_CODE.EEXIST, 'mkdir', filename);
     const node = dir.getNode();
     if (!node.canWrite() || !node.canExecute()) throw createError(ERROR_CODE.EACCES, 'mkdir', filename);
-    dir.createChild(name, this.createNode(constants.S_IFDIR | modeNum));
+    const child = dir.createChild(name, this.createNode(constants.S_IFDIR | modeNum));
+    this.emit(new FsEvent(FsEventType.CREATE, child.steps, child.getNode()));
   };
 
   /**
@@ -759,13 +787,15 @@ export class Superblock {
       }
       created = true;
       curr = curr.createChild(steps[i], this.createNode(constants.S_IFDIR | modeNum));
+      this.emit(new FsEvent(FsEventType.CREATE, curr.steps, curr.getNode()));
     }
     return created ? filename : undefined;
   };
 
   public readonly rmdir = (filename: string, recursive: boolean = false) => {
     const link = this.getLinkAsDirOrThrow(filename, 'rmdir');
     if (link.length && !recursive) throw createError(ERROR_CODE.ENOTEMPTY, 'rmdir', filename);
+    this._emitDeleteRecursive(link);
     this.deleteLink(link);
   };
 
@@ -781,6 +811,7 @@ export class Superblock {
     }
     if (link.getNode().isDirectory() && !recursive) throw createError(ERROR_CODE.ERR_FS_EISDIR, 'rm', filename);
     if (!link.parent?.getNode().canWrite()) throw createError(ERROR_CODE.EACCES, 'rm', filename);
+    this._emitDeleteRecursive(link);
     this.deleteLink(link);
   };
 
@@ -802,6 +833,73 @@ export class Superblock {
     if (file.node.isSymlink()) {
       throw createError(ERROR_CODE.EBADF, 'write', file.link.getPath());
     }
-    return file.write(buf, offset, length, position === -1 || typeof position !== 'number' ? undefined : position);
+    const bytes = file.write(
+      buf,
+      offset,
+      length,
+      position === -1 || typeof position !== 'number' ? undefined : position,
+    );
+    if (bytes > 0) this.emit(new FsEvent(FsEventType.MODIFY, file.link.steps, file.node));
+    return bytes;
   }
+
+  public readonly ftruncate = (fd: number, len?: number): void => {
+    const file = this.getFileByFdOrThrow(fd, 'ftruncate');
+    file.truncate(len);
+    this.emit(new FsEvent(FsEventType.MODIFY, file.link.steps, file.node));
+  };
+
+  public readonly fchmod = (fd: number, modeNum: number): void => {
+    const file = this.getFileByFdOrThrow(fd, 'fchmod');
+    file.chmod(modeNum);
+    this.emit(new FsEvent(FsEventType.MODIFY, file.link.steps, file.node));
+  };
+
+  public readonly chmod = (filename: string, modeNum: number): void => {
+    const link = this.getResolvedLinkOrThrow(filename, 'chmod');
+    link.getNode().chmod(modeNum);
+    this.emit(new FsEvent(FsEventType.MODIFY, link.steps, link.getNode()));
+  };
+
+  public readonly lchmod = (filename: string, modeNum: number): void => {
+    const link = this.getLinkOrThrow(filename, 'lchmod');
+    link.getNode().chmod(modeNum);
+    this.emit(new FsEvent(FsEventType.MODIFY, link.steps, link.getNode()));
+  };
+
+  public readonly fchown = (fd: number, uid: number, gid: number): void => {
+    const file = this.getFileByFdOrThrow(fd, 'fchown');
+    file.chown(uid, gid);
+    this.emit(new FsEvent(FsEventType.MODIFY, file.link.steps, file.node));
+  };
+
+  public readonly chown = (filename: string, uid: number, gid: number): void => {
+    const link = this.getResolvedLinkOrThrow(filename, 'chown');
+    link.getNode().chown(uid, gid);
+    this.emit(new FsEvent(FsEventType.MODIFY, link.steps, link.getNode()));
+  };
+
+  public readonly lchown = (filename: string, uid: number, gid: number): void => {
+    const link = this.getLinkOrThrow(filename, 'lchown');
+    link.getNode().chown(uid, gid);
+    this.emit(new FsEvent(FsEventType.MODIFY, link.steps, link.getNode()));
+  };
+
+  public readonly futimes = (fd: number, atime: number, mtime: number): void => {
+    const file = this.getFileByFdOrThrow(fd, 'futimes');
+    const node = file.node;
+    node.atime = new Date(atime * 1000);
+    node.mtime = new Date(mtime * 1000);
+    this.emit(new FsEvent(FsEventType.MODIFY, file.link.steps, file.node));
+  };
+
+  public readonly utimes = (filename: string, atime: number, mtime: number, followSymlinks: boolean = true): void => {
+    const link = followSymlinks
+      ? this.getResolvedLinkOrThrow(filename, 'utimes')
+      : this.getLinkOrThrow(filename, 'lutimes');
+    const node = link.getNode();
+    node.atime = new Date(atime * 1000);
+    node.mtime = new Date(mtime * 1000);
+    this.emit(new FsEvent(FsEventType.MODIFY, link.steps, node));
+  };
 }

packages/fs-core/src/__tests__/Superblock.events.test.ts

@@ -0,0 +1,133 @@
+import { Superblock } from '../Superblock';
+import { FsEvent, FsEventType } from '../watch/FsEvent';
+import { FLAGS } from '@jsonjoy.com/fs-node-utils';
+import { Buffer } from '@jsonjoy.com/fs-node-builtins/lib/internal/buffer';
+
+const setup = () => {
+  const sb = new Superblock();
+  const events: FsEvent[] = [];
+  sb.onchange = e => events.push(e);
+  return { sb, events };
+};
+
+describe('Superblock events', () => {
+  it('emits CREATE on mkdir', () => {
+    const { sb, events } = setup();
+    sb.mkdir('/test', 0o777);
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe(FsEventType.CREATE);
+    expect(events[0].steps).toEqual(['', 'test']);
+  });
+
+  it('emits CREATE on file open with O_CREAT', () => {
+    const { sb, events } = setup();
+    sb.open('/test.txt', FLAGS.a, 0o666);
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe(FsEventType.CREATE);
+    expect(events[0].steps).toEqual(['', 'test.txt']);
+  });
+
+  it('emits MODIFY on write', () => {
+    const { sb, events } = setup();
+    const fd = sb.open('/test.txt', FLAGS.w, 0o666);
+    sb.write(fd, Buffer.from('hi'), 0, 2, 0);
+    expect(events.length).toBe(3);
+    expect(events[2].type).toBe(FsEventType.MODIFY);
+    expect(events[2].steps).toEqual(['', 'test.txt']);
+  });
+
+  it('does not emit MODIFY on zero-byte write', () => {
+    const { sb, events } = setup();
+    const fd = sb.open('/test.txt', FLAGS.w, 0o666);
+    const numEvents = events.length;
+    sb.write(fd, Buffer.from(''), 0, 0, 0);
+    expect(events.length).toBe(numEvents);
+  });
+
+  it('emits MODIFY on truncate', () => {
+    const sb = new Superblock();
+    const fd = sb.open('/test.txt', FLAGS.w, 0o666);
+    const events: FsEvent[] = [];
+    sb.onchange = e => events.push(e);
+    sb.ftruncate(fd, 10);
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe(FsEventType.MODIFY);
+    expect(events[0].steps).toEqual(['', 'test.txt']);
+  });
+
+  it('emits MODIFY on chmod and chown', () => {
+    const { sb, events } = setup();
+    sb.open('/test.txt', FLAGS.w, 0o666);
+    events.length = 0;
+    sb.chmod('/test.txt', 0o600);
+    sb.chown('/test.txt', 1, 1);
+    expect(events.length).toBe(2);
+    expect(events[0].type).toBe(FsEventType.MODIFY);
+    expect(events[0].steps).toEqual(['', 'test.txt']);
+    expect(events[1].type).toBe(FsEventType.MODIFY);
+  });
+
+  it('emits MODIFY on utimes and futimes', () => {
+    const { sb, events } = setup();
+    const fd = sb.open('/test.txt', FLAGS.w, 0o666);
+    events.length = 0;
+    sb.utimes('/test.txt', 1, 1);
+    sb.futimes(fd, 2, 2);
+    expect(events.length).toBe(2);
+    expect(events[0].type).toBe(FsEventType.MODIFY);
+    expect(events[0].steps).toEqual(['', 'test.txt']);
+    expect(events[1].type).toBe(FsEventType.MODIFY);
+    expect(events[1].steps).toEqual(['', 'test.txt']);
+  });
+
+  it('emits MODIFY on lutimes of a symlink', () => {
+    const { sb, events } = setup();
+    sb.open('/test.txt', FLAGS.w, 0o666);
+    sb.symlink('/test.txt', '/link');
+    events.length = 0;
+    sb.utimes('/link', 1, 1, false);
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe(FsEventType.MODIFY);
+    expect(events[0].steps).toEqual(['', 'link']);
+  });
+
+  it('emits MOVE on rename', () => {
+    const sb = new Superblock();
+    sb.open('/test.txt', FLAGS.w, 0o666);
+    const events: FsEvent[] = [];
+    sb.onchange = e => events.push(e);
+    sb.rename('/test.txt', '/test2.txt');
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe(FsEventType.MOVE);
+    expect(events[0].steps).toEqual(['', 'test2.txt']);
+    expect(events[0].oldSteps).toEqual(['', 'test.txt']);
+  });
+
+  it('emits DELETE on unlink', () => {
+    const sb = new Superblock();
+    sb.open('/test.txt', FLAGS.w, 0o666);
+    const events: FsEvent[] = [];
+    sb.onchange = e => events.push(e);
+    sb.unlink('/test.txt');
+    expect(events.length).toBe(1);
+    expect(events[0].type).toBe(FsEventType.DELETE);
+    expect(events[0].steps).toEqual(['', 'test.txt']);
+  });
+
+  it('emits multiple DELETEs recursively for rmdir/rm', () => {
+    const sb = new Superblock();
+    sb.mkdir('/dir', 0o777);
+    sb.mkdir('/dir/sub', 0o777);
+    sb.open('/dir/sub/file.txt', FLAGS.w, 0o666);
+    const events: FsEvent[] = [];
+    sb.onchange = e => events.push(e);
+    sb.rm('/dir', false, true);
+    expect(events.length).toBe(3);
+    expect(events[0].type).toBe(FsEventType.DELETE);
+    expect(events[0].steps).toEqual(['', 'dir', 'sub', 'file.txt']);
+    expect(events[1].type).toBe(FsEventType.DELETE);
+    expect(events[1].steps).toEqual(['', 'dir', 'sub']);
+    expect(events[2].type).toBe(FsEventType.DELETE);
+    expect(events[2].steps).toEqual(['', 'dir']);
+  });
+});

packages/fs-core/src/index.ts

@@ -6,6 +6,7 @@ export { Node, type NodeEvent } from './Node';
 export { Link, type LinkEvent } from './Link';
 export { File } from './File';
 export { Superblock } from './Superblock';
+export * from './watch/FsEvent';
 export type { IProcess } from './process';
 export {
   dataToBuffer,

packages/fs-core/src/watch/FsEvent.ts

@@ -0,0 +1,17 @@
+import type { Node } from '../Node';
+
+export const enum FsEventType {
+  CREATE,
+  DELETE,
+  MODIFY,
+  MOVE,
+}
+
+export class FsEvent {
+  constructor(
+    public readonly type: FsEventType,
+    public readonly steps: string[],
+    public readonly node: Node,
+    public readonly oldSteps: string[] | undefined = void 0,
+  ) {}
+}

packages/fs-fsa/src/CoreFileSystemSyncAccessHandle.ts

@@ -96,9 +96,8 @@ export class CoreFileSystemSyncAccessHandle implements IFileSystemSyncAccessHand
     }
 
     try {
-      const link = this._core.getResolvedLinkOrThrow(this._path);
-      const node = link.getNode();
-      node.truncate(newSize);
+      const fd = this._ensureOpen();
+      this._core.ftruncate(fd, newSize);
     } catch (error) {
       if (error && typeof error === 'object' && error.code === ERROR_CODE.EACCES) {
         throw newNotAllowedError();

packages/fs-fsa/src/CoreFileSystemWritableFileStream.ts

@@ -84,9 +84,10 @@ export class CoreFileSystemWritableFileStream extends WS implements IFileSystemW
       throw new DOMException('The stream is closed.', 'InvalidStateError');
     }
     try {
-      const link = this._core.getResolvedLinkOrThrow(this._path);
-      const node = link.getNode();
-      node.truncate(size);
+      if (this._fd === undefined) {
+        throw new DOMException('The stream is not ready.', 'InvalidStateError');
+      }
+      this._core.ftruncate(this._fd, size);
     } catch (error) {
       if (error && typeof error === 'object' && error.code === ERROR_CODE.EACCES) {
         throw newNotAllowedError();