File Watcher

A minimal, type-safe file watcher for JavaScript/TypeScript. You can use it to watch directories or files for changes and perform actions when changes are detected. It is a thin wrapper around chokidar with a type-safe, minimal API and improved logging.

Features:

• Written in TypeScript
• Builds to both modern ES modules and CommonJS formats
• Provides TypeScript type definitions
• ESLint for code linting
• Prettier for code formatting
• Vitest for testing
• Tsup for building
• Minimal dependencies

Installation

npm install @coursebook/file-watcher

Usage

A minimal, type-safe file watcher for JavaScript/TypeScript. Use it to watch directories or files for changes and perform actions when changes are detected.

Basic Example

import { FileWatcherImpl, type FileWatcher } from "@coursebook/file-watcher";

const fileWatcher: FileWatcher = new FileWatcherImpl({
  source: "./source-folder",
  // Exclude any file that includes "tmp" in the name
  exclude: ["**/*tmp*"],
});

fileWatcher.setLogLevel("info"); // set to "trace" to see more detailed logs

fileWatcher.watch(async (path) => {
  // Do something with the file
  console.log(`File changed: ${path}`);
});

• Run your script, then create/update/delete files in the ./source-folder directory to see the output.
• Stop the script with ctrl+c.

Configuration Options

interface WatchOptions {
  /** Source directory to watch */
  source: string | string[];
  /** Patterns to ignore, relative to source directory */
  exclude?: string | string[];
  /** Whether to use polling instead of native watchers */
  usePolling?: boolean;
}

FileWatcher Interface

interface FileWatcher {
  /**
   * Start watching files/directories
   * @param onChange - The function to call when a file changes
   */
  watch(onChange: (path: string) => Promise<void>): void;

  /**
   * Set the log level for the file watcher
   * @param level - The log level to set ("trace" | "info")
   */
  setLogLevel(level: LogLevel): void;
}

Error Handling

The component uses custom error types for better error handling:

enum FileWatcherErrorType {
  WATCH_ERROR = "WATCH_ERROR",
  CONFIG_ERROR = "CONFIG_ERROR",
}

class FileWatcherError extends Error {
  constructor(
    public type: FileWatcherErrorType,
    message: string,
    public cause?: Error,
  ) {
    super(message);
    this.name = "FileWatcherError";
  }
}

Logging

The file watcher uses the LogManager for detailed operation logging:

• trace: Detailed operation steps
• info: Operation summaries

Set the log level using setLogLevel("trace" | "info").

Cloning the Repository

To make your workflow more organized, it’s a good idea to clone this repository into a directory named file-watcher-workspace. This helps differentiate the workspace from the file-watcher located in the packages directory.

git clone https://github.com/proj-coursebook/file-watcher file-watcher-workspace

cd file-watcher-workspace

Repository Structure

• packages — Contains the primary package(s) for this repository (e.g., file-watcher). Each package is self-contained and can be copied out and used independently.
• examples — Contains examples of how to use the packages. Each example is a minimal, standalone project.
• playgrounds — Contains demos of the dependencies of the primary package(s). Each playground is a minimal, standalone project.
• docs — Contains various documentation for users and developers.
• .github — Contains GitHub-specific files, such as workflows and issue templates.

How to Use This Repo

• To work on a package, go to packages/<package-name> and follow its README.
• To try an example, go to examples/<example-name> and follow its README.
• To run the playground, go to playground/<package-name> and follow its README.
• For documentation, see the docs folder.

Using a VSCode Multi-root Workspace

With Visual Studio Code, you can enhance your development experience by using a multi-root workspace to access packages, examples, and playgrounds simultaneously. This approach is more efficient than opening the root directory, or each package or example separately.

To set up a multi-root workspace:

1. Open Visual Studio Code.
2. Navigate to File > Open Workspace from File....
3. Select the file-watcher.code-workspace file located at the root of the repository. This action will open all specified folders in one workspace.

The file-watcher.code-workspace file can be customized to include different folders or settings. Here’s a typical configuration:

{
  "folders": [
    {
      "path": "packages/file-watcher"
    },
    {
      "path": "examples/simple"
    },
    {
      "path": "playgrounds/chokidar"
    }
  ],
  "settings": {
    // Add any workspace-specific settings here, for example:
    "git.openRepositoryInParentFolders": "always"
  }
}

Developing the Package

Change to the package directory and install dependencies:

cd packages/file-watcher
npm install

• Read the Project Roadmap for project goals, status, evolution, and development guidelines.
• Read the Development Guide for detailed information on the package architecture, build configuration, and implementation patterns.
• Follow the Contributing Guide for contribution guidelines, coding standards, and best practices.

Package Management

When you are ready to publish your package:

npm run release

This single command will:

• Validate your code with the full validation pipeline
• Analyze commits to determine version bump
• Update package.json version and changelog
• Build the package
• Create and push git tag
• Create GitHub release
• Publish to NPM

[!TIP] For detailed information about package publishing, versioning, and local development workflows, see the NPM Package Management Guide.