@yesiree/basin
v0.3.4
Published
An asynchronous, event-emitting, file watching, process channeling, static-site generating, build tool.
Downloads
30
Readme
Basin
A generic file processor. You could use this for bundling, static site generation, etc.
Many site generation and task running tools take a linear approach. Basin uses an event emitting approach, which allows you to process files using whatever workflow you like. You can specify a map of source names and globs, separating files into different channels. Any changes (creation, modification, deletion) are emitted to those channels. Files can be processed and any artifacts can be re-emitted on any relevant channels for further processing or writing to a file, etc. You can emit whatever data you like to whichever channels you like whenever you like. You can even emit the same data to multiple channels. This provides a lot of flexibility and allows Basin to work for very simple and very complex workflows.
Install
npm i @yesiree/basin
Example
const Basin = require('@yesiree/basin')
const basin = new Basin({
root: 'src',
sources: {
markdown: '**/*.md'
}
})
basin.on('markdown', /*async*/ function (file) {
if (file.event === 'DEL') return
// /*await*/ convert file.content to html...
this.emit('write', file)
})
basin.on('write', async function (file) {
await this.write(file.path, file.content)
})
A couple of things to note about this example:
- Sources, which are a type of channel on which events can be emitted, are setup when instantiating the Basin instance
- Sources have a glob associated with them and whenever a file change (creation, modification, deletion) occurs, an event is emitted on that source's channel.
- Channels can be subscribed to using the Basin instance method
on
. The first parameter is the channel name, which in the case of source channels, is the name of the source specificed in the configuration object passed to the Basin constructor method. - Non-source channels don't need to be configured. You can simply emit data to a new channel by specifying a new name as the first parameter to the Basin instance's
emit
method, followed by whatever data you want to send to that channel (this is the case for thewrite
channel in the example above).
API — Basin
Static Properties
Basin.Ready
A JavaScript symbol that is used to register listeners on a special Basin.Ready
channel. This channel is emitted to only once, after the initial glob search has completed and all asynchronous listeners called as part of that initial search have resolved.
Basin.All
A JavaScript symbol that is used to register listeners on a special Basin.All
channel. This channel receives all events emitted on the basin instance, regardless of the channel name. This can be useful for logging and debugging.
Basin.Default
A JavaScript symbol that is used to register listeners on a special Basin.Default
channel. This channel is the default channel if no channels are specified in the source
parameter to the basin constructor.
Static Methods
Basin.constructor
Creates a new Basin
object.
Parameters
root
— The root path to read files from. This path will be further refined by thesources
parameter. (Defaults to/
.)sources
— A map of source names and globs (globs can be either strings or array of strings). These globs will be prefixed with theroot
parameter. The source names will be the names of Basin channels, and the globs will be used to find files to push to these chanels. (Defaults to{ [Basin.Default]: '**/*'}
.)ignore
— a glob pattern to ignore when searching for files. (Defaults toundefined
.)emitFileData
— If true, a file object withpath
andcontent
properties will be emitted on the channel, otherwise, only thepath
will be emitted.watch
— If true, Basin will watch for changes on the file system and emit those files to the appropriate channels.
Return Value
An instance of Basin
.
Basin.read(path)
Reads the contents of a file specified by path
from disk.
Parameters
path
— The path of the file to read from.root
— A root directory to prefix the path with (optional).
Return Value
The contents of the file (as a buffer).
Basin.write(path, data, root)
Writes data
out to a file specified by path
.
Parameters
path
— The path of the file to write to.data
— The data to be written to the file.root
— A root directory to prefix the path with (optional).
Return Value
A promise that resolves when the file has been written.
Basin.rimraf(glob)
Deletes files matching glob
.
Parameters
glob
— A glob pattern to match files to be deleted.
Return Value
A promise that resolves when the files have been deleted.
Instance Properties
basin.ready
A boolean property that indicates whether or not the Basin.Ready
event has been fired or not.
Instance Methods
basin.on(channel, listener)
Adds a listener to channel
. Whenever something is emitted on that channel, the listener will be called.
Parameters
channel
— The channel to which the listener should be added. If no channel is specified, theBasin.Default
channel will be used.listener
— A listener function to be called when something is emitted on the channel.
Return Value
The basin instance. This allows chaining multiple calls to basin.on
.
basin.off(channel, listener)
Removes a listener from channel
.
Parameters
channel
— The channel from which to remove the listener. If no channel is specified, theBasin.Default
channel will be used.listener
— A reference to the listener function to be removed.
Return Value
The basin instance.
basin.once(channel, listener)
Adds a listener to channel
. If no channel is specified, the Basin.Default
channel will be used. The listener will be removed after the first time it is called.
Parameters
channel
— The channel to which the listener should be added.listener
— A listener function to be called when something is emitted on the channel.
Return Value
The basin instance. This allows chaining multiple calls to basin.once
.
basin.emit(channel, ...args)
Emits a series of arguments on channel
.
Parameters
channel
— The channel on which to emit the arguments....args
— A series of arguments to be emitted on the channel.
Return Value
A promise that resolves when all asynchronous listeners have resolved.
basin.emitWhenReady(channel, ...args)
Emits a series of arguments on channel
only after the Basin.Ready
event has been fired. The ready
event occurs after the initial glob search is complete and all pending emits from that initial search settle.
Parameters
channel
— The channel on which to emit the arguments...args
— A series of arguments to be emitted on the channel.
Return Value
A promise that resolves when all asynchronous listeners have resolved.
basin.run()
Start the process of searching for files and loading them into channels.
Return Value
An instance of Basin
.
basin.cache(store, key, object)
Stores an object
in a cache store
using key
Parameters
store
— The cache namespace in which to store the object.key
— The key used to store the object.object
— The object to be stored
Return Value
The object being stored in the cache.
basin.get(store, key)
Returns an object from the cache.
Parameters
store
— The cache namespace from which to retrieve the object.key
— The key of the object to be retrieved.
Return Value
The object being retrieved from the cache.
basin.purge(store, key)
Purges an object from the cache.
Parameters
store
— The cache namespace from which to purge the object.key
— The key of the object to be purged.
Return Value
The object being purged from the cache.
basin.read(path)
Reads the contents of a file specified by path
from disk.
Parameters
path
— The path of the file to read from.root
— A root directory to prefix the path with (optional).
Return Value
The contents of the file (as a buffer).
basin.write(path, data, root)
Writes data
out to a file specified by path
.
Parameters
path
— The path of the file to write to.data
— The data to be written to the file.root
— A root directory to prefix the path with (optional).
Return Value
A promise that resolves when the file has been written.
basin.rimraf(glob)
Deletes files matching glob
.
Parameters
glob
— A glob pattern to match files to be deleted.
Return Value
A promise that resolves when the files have been deleted.
Listener Function
async listener = ({ type, path, absolutePath, data? }) => Promise
Parameters
type
— The type of event that was emitted. This will be one of the following:'ADD'
— A file was created.'MOD'
— A file was modified.'DEL'
— A file was deleted.path
— The path of the file that was created, modified, or deleted.absolutePath
— The absolute path of the file that was created, modified, or deleted.data
— The contents of the file that was created, modified, or deleted. This will only be present if theemitFileData
option is passed to theBasin
constructor.
Return Value
A promise that resolves when the listener has finished processing the event.
Utility Methods
getCacheBustingPath(path, content)
Parameters
path
— The path of the file to be cache busted.content
— The contents of the file to be cache busted.
Return Value
A path with a hash of the file contents inserted into the filename.
replaceWithCacheBustingPath(path, content)
Replaces instances of path
in content
with a cache-busting path.
Parameters
path
— The path of the file to be cache busted.content
— The contents of a file in which to replacepath
with a cache-busting path.cacheBustingPath
— The cache-busting path to replacepath
with.openingTag
— The opening tag to use when replacingpath
withcacheBustingPath
.closingTag
— The closing tag to use when replacingpath
withcacheBustingPath
.
Return Value
The value of content
with instances of path
replaced with cacheBustingPath
.