Reactively extract all available data from files in a directory to one javascript object
Contexter reactively builds a context object from the data and metadata available in files in a directory for easy manipulation. It mirrors the directory structure and selectively extracts data depending on file type. Watches for any change in directory to keep the javascript object continuously updated
It's functionality could be extended by plugins
(You may prefer to start a contexter
test drive with contexter-cli sample application)
Sample dir structure:
dir/
|-- assets/
| |-- photo.jpg
| |-- style.css
| `-- posts.yml <--- contains foo:"bar"
|
|-- index.html
|-- README.md
`-- notes.txt
In your code:
var Contexter = require('contexter');
var ctxr = new Contexter();
ctxr.watcher('./dir')
.on('ready', function (context) {
console.log( context.dir.assets['posts.yml'].data.foo );
});
output:
> "bar" // value `foo:"bar"` from inside `posts.yml`
> "BAZ" // ... value after editing to `foo:"BAZ"` in `posts.yml`
> ... // reactively display any update to files in `./dir`
The result is a reactive context
variable equivalent to:
var context = {
dir: {
assets: {
"posts.yml": {
data: {foo: "bar", ...}, ...
}}
},
datafiles: [
{...} // posts.yml
],
unknowns: [
] // empty
}
dir
with all data files, it's data and metadata directly availabledatafiles
unknowns
There are two file types. Files with extensions .json
, .yml
and .ymal
are datafile
type and those that can not be processed are unknown
type
Each datafile appears twice in context
object
dir
in the corresponding nested level according with the directory structuredatafiles
or unknowns
In the context
object, a file
is represented by a property named after the filename including the extension. For example: file posts.yml
is the property "posts.yml"
of the object assets
The file
value is an object that contains a property (among others) named data
with the data values of the parsed content of the file.
This file
object also has other properties representing metadata about the file, properties like path
and stats
file
properties samples:
.path.full
: Full path file.path.relative
: file path relative to directory provided.path.processRelative
: file path relative to process.cwd()
path
properties from upath.parse()
function from the npm upathstats
properties from fs.statSync()
from the npm fs-extraContexter(config)
.watcher(path, options)
config
: Object for Contexter(config)
configuration
config.reportInterval
: Number representing the interval milliseconds to report the remaining files to context
be ready. Commonly used to keep the user informed that files are been processed. Affects contexting
and all
events. Default to 0
(zero) meaning that reporting is disabled.config.isWatchAll
: Boolean to set file watch mode. There are two mode: true
for "dir path" and false
for "glob optimized". The first one, watch for ALL files in the directory specified, the later one, optimize a glob
to watch ONLY for files with their extensions stated in the plugins. Default to false, meaning: "glob optimized" to ONLY watch for a "narrow" set of filesconfig.pluginConfig
: Object with global plugin
configuration (see API below)options
: Object for .watcher(path, options)
chokidar.watch()
The context
object format and content can be custom redefined
Custom file types could be extended beyond the datafile
default type, example: image
, stylesheet
,... (see Advanced Methods below)
Custom file processes could be used beyond data file JSON
and yaml
parse, example: other parsers and renders (see Advanced Methods below)
Install with npm:
$ npm install contexter --save
Then require
and use it in your code:
const Contexter= require('contexter')
const ctxr = new Contexter()
// Example of a typical implementation structure:
// Initialize watcher.
var sentinel = ctxr.watcher('path-to-dir', {
ignored: /(^|[\/\\])\../ // ignore dot files (filename beginning with a dot)
});
// Something to use when events are received.
var log = console.log.bind(console);
// Add event listeners.
sentinel
.on('ready', context => log(`context is ready with ${context.datafiles.length} datafiles`))
// More possible events.
sentinel
.on('started', context => log(`Just started with context empty ${context['/']}`))
.on('adding', file => log(`File ${file.path.relative} has been added`))
.on('updating', file => log(`File ${file.path.relative} has been updated`))
.on('deleting', file => log(`File ${file.path.relative} has been deleted`))
.on('contexting', files => log(`Processing : ${files.length} files`))
(You may prefer to start a contexter
test drive with contexter-cli sample application)
Contexter([config])
reportInterval
: Time in milliseconds between "remaining files" report (0 to disable reporting)isWatchAll
: Flag to watch all files. Default to not watch all (false
means, optimize)pluginConfig
: Object with global plugin's configuration
pluginConfig.targetDir
: Full directory path where file should be render or writtenexample:
var Contexter = require('contexter');
var ctxr = new Contexter({
reportInterval: 2000 // Report remaining files every 2 sec. until all are contexted
});
ctxr.watcher('./dir')
.on('ready', function (context) {
console.log( context.dir.assets['posts.yml'].data.foo );
});
ctxr.watcher(path, [options])
path
(string). Path to dir to be watched recursivelyoptions
(object)
ctxr.watcher()
produces an instance of event-emitter
:
.on(event, callback)
: Listen for an FS event.
Available events:
strarting
event signature: .on('strarting', callback(context))
contexting
event signature: .on('contexting', callback(files))
ready
event signature: .on('ready', callback(context))
adding
event signature: .on('adding', callback(file))
updating
event signature: .on('updating', callback(file))
deleting
event signature: .on('deleting', callback(file))
Additionally all
event is available which gets emitted with the underlying event name for every event except starting
. It acts as single event triggered by all other events
all
event signature: .on('all', callback(ctx, eventName, payload))
payload
is an array of files
for contexting
payload
is null
for ready
payload
is a single file
for adding
, updating
and deleting
The default file
class has 3 types of methods
file
objectsfiletype
object to "extend" file
capabilities like the content and format of the context
object to suit datafile
or custom file types like image
, stylesheet
, etc.plugin
object to "use" different file
process like different parsers or to custom render results from the parsed files.extend(filetypeName, filetype)
: Extends the File class to have other file types beyond datafiles
or even modify the context
object structure and format
filetype
object inside pluginsfile
class methods. Used to define de context
format.use(plugin)
: Extend the File class to have other file process beyond data file JSON
and yaml
parse. Custom processes like parse()
and render()
plugin
: Object with methods that replace some of the original file
class methodsFor more on advanced methods, see overview and detailed information
The MIT License (MIT)
Copyright (c) 2017 Eduardo Martinez
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.