• Stars
    star
    373
  • Rank 110,648 (Top 3 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 9 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Wrapper library for directory and file watching.

watchpack

Wrapper library for directory and file watching.

Build Status Build status Test coverage codecov downloads Github contributors

Concept

watchpack high level API doesn't map directly to watchers. Instead a three level architecture ensures that for each directory only a single watcher exists.

  • The high level API requests DirectoryWatchers from a WatcherManager, which ensures that only a single DirectoryWatcher per directory is created.
  • A user-faced Watcher can be obtained from a DirectoryWatcher and provides a filtered view on the DirectoryWatcher.
  • Reference-counting is used on the DirectoryWatcher and Watcher to decide when to close them.
  • The real watchers are created by the DirectoryWatcher.
  • Files are never watched directly. This should keep the watcher count low.
  • Watching can be started in the past. This way watching can start after file reading.
  • Symlinks are not followed, instead the symlink is watched.

API

var Watchpack = require("watchpack");

var wp = new Watchpack({
	// options:
	aggregateTimeout: 1000,
	// fire "aggregated" event when after a change for 1000ms no additional change occurred
	// aggregated defaults to undefined, which doesn't fire an "aggregated" event

	poll: true,
	// poll: true - use polling with the default interval
	// poll: 10000 - use polling with an interval of 10s
	// poll defaults to undefined, which prefer native watching methods
	// Note: enable polling when watching on a network path
	// When WATCHPACK_POLLING environment variable is set it will override this option

	followSymlinks: true,
	// true: follows symlinks and watches symlinks and real files
	//   (This makes sense when symlinks has not been resolved yet, comes with a performance hit)
	// false (default): watches only specified item they may be real files or symlinks
	//   (This makes sense when symlinks has already been resolved)

	ignored: "**/.git"
	// ignored: "string" - a glob pattern for files or folders that should not be watched
	// ignored: ["string", "string"] - multiple glob patterns that should be ignored
	// ignored: /regexp/ - a regular expression for files or folders that should not be watched
	// ignored: (entry) => boolean - an arbitrary function which must return truthy to ignore an entry
	// For all cases expect the arbitrary function the path will have path separator normalized to '/'.
	// All subdirectories are ignored too
});

// Watchpack.prototype.watch({
//   files: Iterable<string>,
//   directories: Iterable<string>,
//   missing: Iterable<string>,
//   startTime?: number
// })
wp.watch({
	files: listOfFiles,
	directories: listOfDirectories,
	missing: listOfNotExistingItems,
	startTime: Date.now() - 10000
});
// starts watching these files and directories
// calling this again will override the files and directories
// files: can be files or directories, for files: content and existence changes are tracked
//        for directories: only existence and timestamp changes are tracked
// directories: only directories, directory content (and content of children, ...) and
//              existence changes are tracked.
//              assumed to exist, when directory is not found without further information a remove event is emitted
// missing: can be files or directorees,
//          only existence changes are tracked
//          expected to not exist, no remove event is emitted when not found initially
// files and directories are assumed to exist, when they are not found without further information a remove event is emitted
// missing is assumed to not exist and no remove event is emitted

wp.on("change", function(filePath, mtime, explanation) {
	// filePath: the changed file
	// mtime: last modified time for the changed file
	// explanation: textual information how this change was detected
});

wp.on("remove", function(filePath, explanation) {
	// filePath: the removed file or directory
	// explanation: textual information how this change was detected
});

wp.on("aggregated", function(changes, removals) {
	// changes: a Set of all changed files
	// removals: a Set of all removed files
	// watchpack gives up ownership on these Sets.
});

// Watchpack.prototype.pause()
wp.pause();
// stops emitting events, but keeps watchers open
// next "watch" call can reuse the watchers
// The watcher will keep aggregating events
// which can be received with getAggregated()

// Watchpack.prototype.close()
wp.close();
// stops emitting events and closes all watchers

// Watchpack.prototype.getAggregated(): { changes: Set<string>, removals: Set<string> }
const { changes, removals } = wp.getAggregated();
// returns the current aggregated info and removes that from the watcher
// The next aggregated event won't include that info and will only emitted
// when futher changes happen
// Can also be used when paused.

// Watchpack.prototype.collectTimeInfoEntries(fileInfoEntries: Map<string, Entry>, directoryInfoEntries: Map<string, Entry>)
wp.collectTimeInfoEntries(fileInfoEntries, directoryInfoEntries);
// collects time info objects for all known files and directories
// this include info from files not directly watched
// key: absolute path, value: object with { safeTime, timestamp }
// safeTime: a point in time at which it is safe to say all changes happened before that
// timestamp: only for files, the mtime timestamp of the file

// Watchpack.prototype.getTimeInfoEntries()
var fileTimes = wp.getTimeInfoEntries();
// returns a Map with all known time info objects for files and directories
// similar to collectTimeInfoEntries but returns a single map with all entries

// (deprecated)
// Watchpack.prototype.getTimes()
var fileTimes = wp.getTimes();
// returns an object with all known change times for files
// this include timestamps from files not directly watched
// key: absolute path, value: timestamp as number

More Repositories

1

webpack

A bundler for javascript and friends. Packs many modules into a few bundled assets. Code Splitting allows for loading parts of the application on demand. Through "loaders", modules can be CommonJs, AMD, ES6 modules, CSS, Images, JSON, Coffeescript, LESS, ... and your custom stuff.
JavaScript
64,061
star
2

webpack-dev-server

Serves a webpack app. Updates the browser on changes. Documentation https://webpack.js.org/configuration/dev-server/.
JavaScript
7,728
star
3

tapable

Just a little module for plugins.
JavaScript
3,668
star
4

webpack-cli

Webpack's Command Line Interface
JavaScript
2,538
star
5

webpack-dev-middleware

A development middleware for webpack
JavaScript
2,468
star
6

react-starter

[OUTDATED] Starter template for React with webpack. Doesn't focus on simplicity! NOT FOR BEGINNERS!
JavaScript
2,215
star
7

webpack.js.org

Repository for webpack documentation and more!
MDX
2,197
star
8

docs

[OLD] documentation for webpack
JavaScript
1,456
star
9

enhanced-resolve

Offers an async require.resolve function. It's highly configurable.
JavaScript
897
star
10

memory-fs

[DEPRECATED use memfs instead] A simple in-memory filesystem. Holds data in a javascript object.
JavaScript
882
star
11

analyse

analyse web app for webpack stats
JavaScript
873
star
12

webpack-pwa

Example for a super simple PWA with webpack.
JavaScript
809
star
13

loader-utils

utils for webpack loaders
JavaScript
764
star
14

react-webpack-server-side-example

Example of an react application with webpack including server-side rendering.
JavaScript
460
star
15

node-libs-browser

[DEPRECATED] The node core libs for in browser usage.
JavaScript
445
star
16

webpack-with-common-libs

webpack with some common libraries
JavaScript
340
star
17

loader-runner

Runs (webpack) loaders
JavaScript
291
star
18

webpack-sources

Source code handling classes for webpack
JavaScript
254
star
19

changelog-v5

Temporary repo for the changelog for webpack 5
252
star
20

schema-utils

Options Validation
JavaScript
234
star
21

meeting-notes

Webpack core team meeting notes.
188
star
22

concord

[WIP] concord modules specification
156
star
23

example-app

[OUTDATED] example web app for webpack
JavaScript
139
star
24

fastparse

A very simple and stupid parser, based on a statemachine and regular expressions.
JavaScript
65
star
25

enhanced-require

[CURRENTLY UNMAINTAINED] Enhance the require function in node.js with support for loaders which preprocess files. This is a standalone polyfill for features of webpack.
JavaScript
64
star
26

playground

In-browser playground for webpack
JavaScript
59
star
27

analyse-tool

A tool to analyse your webpack build result. It allows to browse the compilation and points out options to optimize the build.
JavaScript
55
star
28

hot-node-example

Example for HMR in a node.js process
JavaScript
54
star
29

source-list-map

Fast line to line SourceMap generator.
JavaScript
39
star
30

benchmark

Run benchmarks for webpack.
JavaScript
37
star
31

core

[OBSOLETE in webpack 2] The core of webpack and enhanced-require...
JavaScript
26
star
32

media

23
star
33

voting-app

An application for casting votes on new webpack features and fixes.
JavaScript
22
star
34

tooling

A collection of reusable tooling for webpack repos.
JavaScript
20
star
35

graph

[DEPRECATED] Converts JSON stats from webpack to a nice SVG-Image.
JavaScript
13
star
36

template

[DEPRECATED] Create a new web app from a template.
JavaScript
10
star
37

webpack.github.com

webpack.github.com
JavaScript
10
star
38

management

Mission, Goals, projects and budget for webpack
6
star
39

github-org-overview

Scans all repos of a github organization and check if published
JavaScript
5
star
40

the-big-test

[OUTDATED] the big webpack/enhanced-require test
JavaScript
5
star
41

meetup-2018-05-08

QA for the webpack meetup in Munich
4
star
42

v4.webpack.js.org

Hosting for old version of webpack documentation
3
star
43

jquery-wpt-module

[DEPRECATED] webpack-template-module for jquery
JavaScript
2
star
44

bootstrap-wpt-module

[DEPRECATED] webpack-template-module for twitter's bootstrap
JavaScript
2
star
45

github-wiki

The server-side code (heruko) for serving the wiki as gh-pages.
JavaScript
2
star
46

enhanced-resolve-completion-demo

[OUTDATED] demo for the request completion of enhanced-resolve
JavaScript
2
star
47

webpack-tests-example

DEPRECATED (use mocha-loader now): A simple example for doing tests with webpack and mocha.
JavaScript
2
star