@jsenv/filesystem

Jsenv filesystem

Collection of functions to interact with filesystem in Node.js.

Presentation

@jsenv/filesystem provides functions needed to work with files. It has no external dependency.

Examples

The whole list of functions exported by @jsenv/filesystem are documented in ./docs/API.md. This section demonstrates how @jsenv/filesystem can be used in common use cases.

Get a relative url

import { urlToRelativeUrl } from "@jsenv/filesystem"

const projectDirectoryUrl = "file:///project/"
const jsFileUrl = "file:///project/src/file.js"
const relativeUrl = urlToRelativeUrl(jsFileUrl, projectDirectoryUrl) // "src/file.js"

Collect files using pattern matching

import { collectFiles } from "@jsenv/filesystem"

const jsAndSourceMapFiles = await collectFiles({
  directoryUrl: "file:///project/directory/",
  structuredMetaMap: {
    isJsFile: {
      "./**/*.js": true,
    },
    isSourceMapFile: {
      "./**/*.js.map": true,
    },
  },
  predicate: ({ isJsFile, isSourceMapFile }) => isJsFile || isSourceMapFile,
})
console.log(jsAndSourceMapFiles.length)

Watch a specific file change

import { readFileSync } from "node:fs"
import { registerFileLifecycle } from "@jsenv/filesystem"

const packageJSONFileUrl = new URL("./package.json", import.meta.url)
let packageJSON = null
const unregister = registerFileLifecycle(packageJSONFileUrl, {
  added: () => {
    packageJSON = JSON.parse(String(readFileSync(filePath)))
  },
  updated: () => {
    packageJSON = JSON.parse(String(readFileSync(filePath)))
  },
  removed: () => {
    packageJSON = null
  },
  notifyExistent: true,
})
unregister() // stop watching the file changes

Watch many file change

import { registerDirectoryLifecycle } from "@jsenv/filesystem"

const contentMap = {}
const unregister = registerDirectoryLifecycle("file:///directory/", {
  watchDescription: {
    "./**/*": true,
    "./node_modules/": false,
  },
  added: ({ relativeUrl, type }) => {
    contentMap[relativeUrl] = type
  },
  removed: ({ relativeUrl }) => {
    delete contentMap[relativeUrl]
  },
})
unregister() // stop watching the directory changes

Installation

npm install @jsenv/filesystem

Development

If you are part or want to be part of the developpers of this package, check docs/development.md

Changelog

31.0.0

• Major update on dependencies
• Update how to start dev server in https
• More validation on public function params (type errors thrown on unexpected params)
• "errored" execution status becomes "failed"