@jsenv/file-watcher v1.0.0

jsenv file watcher

Watch file changes on your filesystem.

Table of contents

• Presentation
• Code example
• registerDirectoryLifecycle
• registerFileLifecycle
• Installation

Presentation

This repository allows you to watch a given file or directory and be notified when a file is added, updated or removed.

It exists because fs.watch documentation says you should not use it directly due to several limitations specific to the filesystem.

chokidar exists but does it does more then what jsenv needs.

registerDirectoryLifecycle

registerDirectoryLifecycle is a function watching a path and calling added, updated, removed according to what is happening to the directory at that path .

Implemented in src/registerDirectoryLifecycle.js and could be used as shown below.

import { registerFolderLifecycle } from "@dmail/filesystem-watch"

const folderContentMap = {}
registerFolderLifecycle("/Users/you/folder", {
  added: ({ relativePath, type ) => {
    folderContentMap[relativePath] = type
  },
  removed: ({ relativePath }) => {
    delete folderContentMap[relativePath]
  },
})

Usually, filesystem takes less than 100ms to notify something has changed.

added

added is a function called after file is added in the directory.

This parameters is optional with a default value of:

undefined

updated

updated is a function called after file is updated in the directory.

This parameters is optional with a default value of:

undefined

removed

removed is a function called after file is removed in the directory.

This parameters is optional with a default value of:

undefined

watchDescription

watchDescription in an object used to know what should be watched inside the directory.

This parameter is optional with a default value of:

{
  "/**/*": true,
}

The default watchDescription watch everything but you should prefer to pass your own like this one for instance:

{
  // exclude everything
  "/**/*": false,
  // include only js files
  "/**/*.js": true,
  // exclude js files inside node_modules
  "/**/node_modules/": false,
}

The pattern matching behaviour is documented here: https://github.com/jsenv/jsenv-url-meta#pattern-matching-behaviour

notifyExistent

notifyExistent is a boolean controlling if added is called immediatly for every file already existing inside the directory.

This parameters is optional with a default value of:

false

keepProcessAlive

keepProcessAlive is a boolean controlling if watching directory keeps node process alive or not.

This parameters is optional with a default value of:

true

unregisterDirectoryLifecycle

unregisterDirectoryLifecycle is a function you can call to stop watching.

It is returned by registerDirectoryLifecycle, see below an example:

import { registerDirectoryLifecycle } from "@jsenv/file-watcher"

const unregisterDirectoryLifecycle = registerDirectoryLifecycle("/Users/whatever/", {
  updated: () => {
    console.log("updated")
  },
})
unregisterDirectoryLifecycle()

First call to this function cleans up things required to watch file. Subsequent calls to this function are ignored.

registerFileLifecycle

registerFileLifecycle is a function watching a path and calling added, updated, removed according to what is happening to the file at that path .

Implemented in src/registerFileLifecycle.js and could be used as shown below.

import { readFileSync } from "fs"
import { registerFileLifecycle } from "@jsenv/file-watcher"

const path = "/Users/whatever/file.json"
let currentConfig = null
registerFileLifecycle(path, {
  added: () => {
    currentConfig = JSON.parse(String(readFileSync(path)))
  },
  updated: () => {
    currentConfig = JSON.parse(String(readFileSync(path)))
  },
  removed: () => {
    currentConfig = null
  },
})

Usually, filesystem takes less than 100ms to notify something has changed.

added

added is a function called after file is added on your filesystem.

This parameters is optional with a default value of:

undefined

updated

updated is a function called after file content or attributes like modification date has changed on your filesystem.

This parameters is optional with a default value of:

undefined

removed

removed is a function called after file is removed from your filesystem.

This parameters is optional with a default value of:

undefined

notifyExistent

notifyExistent is a boolean controlling if added is called immediatly when file already exists.

This parameters is optional with a default value of:

false

keepProcessAlive

keepProcessAlive is a boolean controlling if watching file keeps node process alive or not.

This parameters is optional with a default value of:

true

unregisterFileLifecycle

unregisterFileLifecycle is a function you can call to stop watching.

It is returned by registerFileLifecycle, see below an example:

import { registerFileLifecycle } from "@jsenv/file-watcher"

const unregisterFileLifecycle = registerFileLifecycle("/Users/whatever/file.json", {
  updated: () => {
    console.log("updated")
  },
})

unregisterFileLifecycle()

First call to this function cleans up things required to watch file. Subsequent calls to this function are ignored.

Installation

If you have never installed a jsenv package, read Installing a jsenv package before going further.

This documentation is up-to-date with a specific version so prefer any of the following commands

npm install --save-dev @jsenv/file-watcher@1.0.0

yarn add --dev @jsenv/file-watcher@1.0.0