@effectionx/watch 0.3.1 → 0.4.0

package/test/helpers.ts

@@ -0,0 +1,144 @@
+import type { Process } from "@effectionx/process";
+import { emptyDir, ensureDir } from "@effectionx/fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Operation, Result, Stream } from "effection";
+import { each, Ok, resource, sleep, spawn, until } from "effection";
+import { cp, readFile, writeFile } from "node:fs/promises";
+import assert from "node:assert";
+
+import type { Start } from "../watch.ts";
+
+export interface Fixture {
+  path: string;
+  getPath(filename: "src/file.txt" | "dist/artifact.txt"): string;
+  read(name: "src/file.txt"): Operation<string>;
+  write(
+    filename: "src/file.txt" | "dist/artifact.txt",
+    content: string,
+  ): Operation<void>;
+}
+
+export function* useFixture(): Operation<Fixture> {
+  let tmpDir = fileURLToPath(new URL("./temp", import.meta.url));
+  let fixtureDir = fileURLToPath(new URL("./fixtures", import.meta.url));
+  // let path = join(tmpDir, "fixtures");
+  let path = tmpDir;
+  try {
+    yield* emptyDir(tmpDir);
+  } catch (e) {
+    console.log(`Encountered error clearing ${tmpDir}`);
+    console.error(e);
+  }
+
+  try {
+    yield* until(
+      cp(fixtureDir, tmpDir, {
+        recursive: true,
+        preserveTimestamps: true,
+        force: true,
+      }),
+    );
+  } catch (e) {
+    console.log(`Encountered error copying from ${fixtureDir} to ${tmpDir}`);
+    console.error(e);
+  }
+
+  return {
+    path,
+    getPath(filename): string {
+      return join(path, filename);
+    },
+    *write(filename: string, content: string) {
+      const dest = join(path, filename);
+      yield* ensureDir(dirname(dest));
+      yield* until(writeFile(join(path, filename), content));
+    },
+    *read(name) {
+      return String(yield* until(readFile(join(path, name))));
+    },
+  };
+}
+
+type SuccessfulStart = {
+  stdout: string;
+  stderr: string;
+  process: Process;
+};
+
+type ProcessStart = Result<SuccessfulStart>;
+
+interface Inspector {
+  starts: ProcessStart[];
+  expectNext(): Operation<SuccessfulStart>;
+  expectNoRestart(): Operation<void>;
+}
+
+export function inspector(stream: Stream<Start, never>): Operation<Inspector> {
+  return resource(function* (provide) {
+    let starts: ProcessStart[] = [];
+
+    let expected = 0;
+
+    yield* spawn(function* () {
+      for (let { result } of yield* each(stream)) {
+        if (result.ok) {
+          let process = result.value;
+          let start = {
+            stdout: "",
+            stderr: "",
+            process: result.value,
+          };
+          starts.push(Ok(start));
+          yield* spawn(function* () {
+            for (let chunk of yield* each(process.stdout)) {
+              start.stdout += String(chunk);
+              yield* each.next();
+            }
+          });
+          yield* spawn(function* () {
+            for (let chunk of yield* each(process.stderr)) {
+              start.stderr += String(chunk);
+              yield* each.next();
+            }
+          });
+        } else {
+          starts.push(result);
+        }
+
+        yield* each.next();
+      }
+    });
+
+    yield* provide({
+      starts,
+      *expectNext() {
+        let initial = expected;
+        for (let i = 0; i < 500; i++) {
+          if (initial < starts.length) {
+            yield* sleep(10);
+            expected = starts.length;
+            let result = starts[starts.length - 1];
+            if (result.ok) {
+              return result.value;
+            }
+            throw new Error(
+              `expected successful start, but failed: ${result.error}`,
+            );
+          }
+          yield* sleep(10);
+        }
+        throw new Error("expecting a sucessful start but it never appeared.");
+      },
+      *expectNoRestart() {
+        let prexisting = starts.length;
+        yield* sleep(200);
+        let restarts = starts.length - prexisting;
+        assert(
+          restarts === 0,
+          `expected no process restarts to have happened, but instead there were: ${restarts}`,
+        );
+      },
+    });
+  });
+}

package/test/watch-graceful.ts

@@ -0,0 +1,11 @@
+import { main, sleep } from "effection";
+
+console.log("started");
+
+await main(function* () {
+  try {
+    yield* sleep(100_000_000);
+  } finally {
+    console.log("done");
+  }
+});

package/test/watch.test.ts

@@ -0,0 +1,121 @@
+import { describe, it } from "@effectionx/bdd";
+import { createArraySignal, is } from "@effectionx/signals";
+import { forEach } from "@effectionx/stream-helpers";
+import { expect } from "expect";
+
+import process from "node:process";
+import { spawn } from "effection";
+import { watch } from "../watch.ts";
+import { inspector, useFixture } from "./helpers.ts";
+
+describe("watch", () => {
+  it("restarts the specified process when files change.", function* () {
+    let fixture = yield* useFixture();
+    let processes = yield* inspector(
+      watch({
+        path: fixture.path,
+        cmd: "node --experimental-strip-types cat.ts",
+        event: "change",
+        execOptions: {
+          cwd: import.meta.dirname,
+          env: {
+            PATH: process.env.PATH ?? "",
+          },
+          arguments: [fixture.getPath("src/file.txt")],
+        },
+      }),
+    );
+
+    let start = yield* processes.expectNext();
+
+    yield* start.process.expect();
+
+    expect(start).toMatchObject({
+      stderr: "",
+      stdout: "this is a source file",
+    });
+
+    yield* fixture.write("src/file.txt", "this source file is changed");
+
+    let next = yield* processes.expectNext();
+
+    yield* next.process.expect();
+
+    expect(next).toMatchObject({
+      stderr: "",
+      stdout: "this source file is changed",
+    });
+  });
+
+  it("ignores files in .gitignore", function* () {
+    expect.assertions(1);
+    let fixture = yield* useFixture();
+
+    let processes = yield* inspector(
+      watch({
+        path: fixture.path,
+        cmd: "echo hello",
+        event: "change",
+      }),
+    );
+
+    //it starts the first time
+    yield* processes.expectNext();
+
+    yield* fixture.write("dist/artifact.txt", "this file was built again");
+
+    yield* processes.expectNoRestart();
+
+    expect(processes.starts).toHaveLength(1);
+  });
+
+  it.skip("ignores files in a .gitignore that is in a parent directory", function* () {
+    // start an example in a nested directory than the git ignore
+    // touch a change in an ignored file within the directory
+    // enuser that there was no restart;
+  });
+
+  it("waits until stdout is closed before restarting", function* () {
+    let fixture = yield* useFixture();
+    let processes = yield* inspector(
+      watch({
+        path: fixture.path,
+        cmd: "node --experimental-strip-types watch-graceful.ts",
+        execOptions: {
+          cwd: import.meta.dirname,
+          env: {
+            PATH: process.env.PATH ?? "",
+          },
+        },
+      }),
+    );
+
+    const output = yield* createArraySignal<string>([]);
+
+    let first = yield* processes.expectNext();
+
+    yield* spawn(function* () {
+      yield* forEach(function* (line) {
+        output.push(`${line}`.trim());
+      }, first.process.stdout);
+    });
+
+    yield* is(output, (array) => array.includes("started"));
+
+    yield* fixture.write("src/file.txt", "hello planet");
+
+    yield* is(output, (array) => array.includes("done"));
+
+    yield* processes.expectNext();
+
+    expect(output.valueOf()).toEqual(["started", "done"]);
+  });
+
+  // start an example that prints "done" to the console upon SIGINT);
+
+  it.skip("allows for a hard kill ", function* () {
+    // start an example that will suspend asked to exit and so will
+    // never exit.
+    // send the command to exit the watch and the main returns
+  });
+});

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": ".",
+    "resolveJsonModule": true
+  },
+  "include": ["**/*.ts", "package.json"],
+  "exclude": ["**/*.test.ts", "test/**", "dist"],
+  "references": [
+    {
+      "path": "../bdd"
+    },
+    {
+      "path": "../fs"
+    },
+    {
+      "path": "../process"
+    },
+    {
+      "path": "../signals"
+    },
+    {
+      "path": "../stream-helpers"
+    }
+  ]
+}

package/watch.ts

@@ -0,0 +1,198 @@
+import { access } from "node:fs/promises";
+import { join, relative } from "node:path";
+import chokidar, { type EmitArgsWithName } from "chokidar";
+import {
+  call,
+  createChannel,
+  createSignal,
+  Err,
+  Ok,
+  type Operation,
+  resource,
+  type Result,
+  spawn,
+  type Stream,
+  until,
+  withResolvers,
+} from "effection";
+import { default as createIgnore } from "ignore";
+import { pipe } from "remeda";
+import { readFile } from "node:fs/promises";
+import { exec, type ExecOptions, type Process } from "@effectionx/process";
+
+import { debounce } from "./stream-helpers.ts";
+
+// Extended FSWatcher interface that includes EventEmitter methods
+interface FSWatcherWithEvents {
+  on(event: string, listener: (...args: EmitArgsWithName) => void): this;
+  close(): Promise<void>;
+}
+
+/**
+ * Represents a single start of the specified command
+ */
+export interface Start {
+  /**
+   * A result containing the {Process} on a successful start, or
+   * an error otherwise.
+   */
+  result: Result<Process>;
+  /**
+   * An operation that resolves when the current start begins its
+   * shutdown.
+   */
+  restarting: Operation<void>;
+}
+
+/**
+ * A watch is a strema of process starts that happen in reaction
+ * to some source file changing on the file system.
+ */
+export interface Watch extends Stream<Result<Process>, never> {}
+
+/**
+ * Options available to configure what is watched
+ */
+export interface WatchOptions {
+  /**
+   * The directory to watch
+   */
+  path: string;
+  /**
+   * The command to run (and re-run every time a change is detected)
+   */
+  cmd: string;
+
+  /**
+   * @ignore
+   */
+  event?: "all" | "change";
+
+  /**
+   * Options passed to process exec
+   */
+  execOptions?: ExecOptions;
+}
+
+/**
+ * Create a watch configuration that observes file system changes and executes a command
+ * when changes are detected. The watch can be consumed as a stream of process starts.
+ *
+ * @example
+ * ```ts
+ * const watcher = yield* watch({
+ *  path: './src',
+ *  cmd: 'npm test'
+ * });
+ * ```
+ *
+ * @param options - Configuration options for the watch
+ * @param options.path - The directory path to watch for changes
+ * @param options.cmd - The command to execute when changes are detected
+ * @param options.event - The type of event to watch for ('all' or 'change', defaults to 'all')
+ *
+ * @returns A Stream that emits `Result<Process>` for each command execution
+ *
+ * @remarks
+ * - Uses chokidar for file system watching
+ * - Respects .gitignore patterns if present
+ * - Implements debouncing to prevent rapid successive executions
+ * - Filters out stale events using the fresh() function
+ *
+ * @throws Will throw an error if the process execution fails
+ *
+ * @see {@link WatchOptions} for configuration options
+ * @see {@link Process} for process execution details
+ */
+export function watch(options: WatchOptions): Stream<Start, never> {
+  return resource(function* (provide) {
+    let starts = createChannel<Start, never>();
+    let input = createSignal<EmitArgsWithName, never>();
+
+    let gitignored = yield* findIgnores(options.path);
+
+    // Cast to extended interface that includes EventEmitter methods
+    let watcher = chokidar.watch(options.path, {
+      ignored: (path) => {
+        let relpath = relative(options.path, path);
+        let isGit = relpath === ".git" || relpath.startsWith(".git");
+        return isGit || gitignored(path);
+      },
+      ignoreInitial: true,
+    }) as unknown as FSWatcherWithEvents;
+
+    let { event = "all" } = options;
+    watcher.on(event, (...args: EmitArgsWithName) => {
+      if (event !== "all") {
+        args.unshift(event);
+      }
+      let [, path] = args;
+      if (fresh(500)(args) && !gitignored(path)) {
+        input.send(args);
+      }
+    });
+
+    let changes = yield* pipe(input, debounce(100));
+    let subscription = yield* starts;
+
+    yield* spawn(function* () {
+      while (true) {
+        let task = yield* spawn(function* () {
+          let restarting = withResolvers<void>();
+          try {
+            let process = yield* exec(options.cmd, options.execOptions);
+            yield* starts.send({
+              result: Ok(process),
+              restarting: restarting.operation,
+            });
+          } catch (error) {
+            yield* starts.send({
+              result: Err(error as Error),
+              restarting: restarting.operation,
+            });
+          }
+          yield* changes.next();
+          restarting.resolve();
+        });
+        yield* task;
+      }
+    });
+
+    try {
+      yield* provide(subscription);
+    } finally {
+      yield* until(watcher.close());
+    }
+  });
+}
+
+/**
+ * locate a `.gitignore` file if it exists and use it to filter
+ * out any change events against paths that are matched by it
+ */
+function* findIgnores(path: string): Operation<(path: string) => boolean> {
+  let gitignore = join(path, ".gitignore");
+  if (
+    yield* call(() =>
+      access(gitignore).then(
+        () => true,
+        () => false,
+      ),
+    )
+  ) {
+    let ignores = createIgnore();
+    let buffer = yield* call(() => readFile(gitignore));
+    ignores.add(buffer.toString());
+    return (pathname) => {
+      let relativePathname = relative(path, pathname).trim();
+      return relativePathname !== "" && ignores.ignores(relativePathname);
+    };
+  }
+  return () => false;
+}
+
+function fresh(staletime: number): (args: EmitArgsWithName) => boolean {
+  return ([, , stats]) => {
+    return !stats || Date.now() - stats.mtimeMs < staletime;
+  };
+}

package/esm/_dnt.polyfills.d.ts

@@ -1,8 +0,0 @@
-declare global {
-    interface ArrayConstructor {
-        fromAsync<T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | Promise<T>> | ArrayLike<T | Promise<T>>): Promise<T[]>;
-        fromAsync<T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>) => U, thisArg?: any): Promise<Awaited<U>[]>;
-    }
-}
-export {};
-//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/esm/_dnt.polyfills.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AACA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,gBAAgB;QACxB,SAAS,CAAC,CAAC,EACP,mBAAmB,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAC7F,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;QAEhB,SAAS,CAAC,CAAC,EAAE,CAAC,EACV,mBAAmB,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EAClE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAC/B,OAAO,CAAC,EAAE,GAAG,GACd,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;KAC1B;CACF;AAoID,OAAO,EAAE,CAAC"}

package/esm/_dnt.polyfills.js

@@ -1,110 +0,0 @@
-// From https://github.com/es-shims/array-from-async/blob/4a5ff83947b861f35b380d5d4f20da2f07698638/index.mjs
-// Tried to have dnt depend on the package instead, but it distributes as an
-// ES module, so doesn't work with CommonJS.
-//
-// Code below:
-//
-// Copyright 2021 J. S. Choi
-//
-// Redistribution and use in source and binary forms, with or without
-// modification, are permitted provided that the following conditions
-// are met:
-//
-// 1. Redistributions of source code must retain the above copyright
-//    notice, this list of conditions and the following disclaimer.
-//
-// 2. Redistributions in binary form must reproduce the above copyright
-//    notice, this list of conditions and the following disclaimer in the
-//    documentation and/or other materials provided with the distribution.
-//
-// 3. Neither the name of the copyright holder nor the names of its
-//    contributors may be used to endorse or promote products derived from
-//    this software without specific prior written permission.
-//
-// **This software is provided by the copyright holders and contributors
-// "as is" and any express or implied warranties, including, but not
-// limited to, the implied warranties of merchantability and fitness for a
-// particular purpose are disclaimed. In no event shall the copyright
-// holder or contributors be liable for any direct, indirect, incidental,
-// special, exemplary, or consequential damages (including, but not limited
-// to, procurement of substitute goods or services; loss of use, data, or
-// profits; or business interruption) however caused and on any theory of
-// liability, whether in contract, strict liability, or tort (including
-// negligence or otherwise) arising in any way out of the use of this
-// software, even if advised of the possibility of such damage.**
-const { MAX_SAFE_INTEGER } = Number;
-const iteratorSymbol = Symbol.iterator;
-const asyncIteratorSymbol = Symbol.asyncIterator;
-const IntrinsicArray = Array;
-const tooLongErrorMessage = 'Input is too long and exceeded Number.MAX_SAFE_INTEGER times.';
-function isConstructor(obj) {
-    if (obj != null) {
-        const prox = new Proxy(obj, {
-            construct() {
-                return prox;
-            },
-        });
-        try {
-            new prox;
-            return true;
-        }
-        catch (err) {
-            return false;
-        }
-    }
-    else {
-        return false;
-    }
-}
-async function fromAsync(items, mapfn, thisArg) {
-    const itemsAreIterable = (asyncIteratorSymbol in items ||
-        iteratorSymbol in items);
-    if (itemsAreIterable) {
-        const result = isConstructor(this)
-            ? new this
-            : IntrinsicArray(0);
-        let i = 0;
-        for await (const v of items) {
-            if (i > MAX_SAFE_INTEGER) {
-                throw TypeError(tooLongErrorMessage);
-            }
-            else if (mapfn) {
-                result[i] = await mapfn.call(thisArg, v, i);
-            }
-            else {
-                result[i] = v;
-            }
-            i++;
-        }
-        result.length = i;
-        return result;
-    }
-    else {
-        // In this case, the items are assumed to be an arraylike object with
-        // a length property and integer properties for each element.
-        const { length } = items;
-        const result = isConstructor(this)
-            ? new this(length)
-            : IntrinsicArray(length);
-        let i = 0;
-        while (i < length) {
-            if (i > MAX_SAFE_INTEGER) {
-                throw TypeError(tooLongErrorMessage);
-            }
-            const v = await items[i];
-            if (mapfn) {
-                result[i] = await mapfn.call(thisArg, v, i);
-            }
-            else {
-                result[i] = v;
-            }
-            i++;
-        }
-        result.length = i;
-        return result;
-    }
-}
-if (!Array.fromAsync) {
-    Array.fromAsync = fromAsync;
-}
-export {};

package/esm/_dnt.shims.d.ts

@@ -1,2 +0,0 @@
-export declare const dntGlobalThis: Omit<typeof globalThis, never>;
-//# sourceMappingURL=_dnt.shims.d.ts.map

package/esm/_dnt.shims.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_dnt.shims.d.ts","sourceRoot":"","sources":["../src/_dnt.shims.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,gCAA2C,CAAC"}

package/esm/_dnt.shims.js

@@ -1,57 +0,0 @@
-const dntGlobals = {};
-export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
-function createMergeProxy(baseObj, extObj) {
-    return new Proxy(baseObj, {
-        get(_target, prop, _receiver) {
-            if (prop in extObj) {
-                return extObj[prop];
-            }
-            else {
-                return baseObj[prop];
-            }
-        },
-        set(_target, prop, value) {
-            if (prop in extObj) {
-                delete extObj[prop];
-            }
-            baseObj[prop] = value;
-            return true;
-        },
-        deleteProperty(_target, prop) {
-            let success = false;
-            if (prop in extObj) {
-                delete extObj[prop];
-                success = true;
-            }
-            if (prop in baseObj) {
-                delete baseObj[prop];
-                success = true;
-            }
-            return success;
-        },
-        ownKeys(_target) {
-            const baseKeys = Reflect.ownKeys(baseObj);
-            const extKeys = Reflect.ownKeys(extObj);
-            const extKeysSet = new Set(extKeys);
-            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
-        },
-        defineProperty(_target, prop, desc) {
-            if (prop in extObj) {
-                delete extObj[prop];
-            }
-            Reflect.defineProperty(baseObj, prop, desc);
-            return true;
-        },
-        getOwnPropertyDescriptor(_target, prop) {
-            if (prop in extObj) {
-                return Reflect.getOwnPropertyDescriptor(extObj, prop);
-            }
-            else {
-                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
-            }
-        },
-        has(_target, prop) {
-            return prop in extObj || prop in baseObj;
-        },
-    });
-}