WAT?
Crave gives you the ability to structure your application's files any way you like without the burden of manually requiring each file's location. Take these file structures for example:
Left: A common node application file structure where each folder is required dynamically. This works great, but restricts where your files must be located.
Right: Crave allows you to move files where ever you like and will require them dynamically. This grouping by feature makes related code easier to find and transfer between projects.
Getting Started
Install Crave using npm and save it as a dependency in your package.json.
npm install crave --save
You can require Crave just like every other node.js module.
var crave = ;
Controllers, modules, and other files you wish to require before starting your server should be structured like this:
// This is the Crave type, it tells crave when and// if to load this file. You can use any text you want.// ~> Controller // Export a function whose parameters are global values// needed in the controller's logic.module { // Place your controller logic inside this method. // An example route that sends "Hello" app;};
Use Crave's directory method to require your files dynamically. They will be required in the order you specify and will recieve the parameters you pass.
var crave = express = ; // Create an express application object.var app = ; // Create a method to start the server.var { iferr return console; // A list of files that were required by crave, or where attempted to be // required by crave are listed in the filesRequired parameter. console; // A list of returned values, or errors, from each file required are located in the // returnValues parameter. console; var server = app;} // Define the directory where Crave will search for files in.// Crave will do a recursive search, looking in children folders.var directoryToLoad = '/path/to/my/app/files'; // Define an ordered list of file types for Crave to load.// This is the Crave type we just talked about in the// earlier example: " // ~> Controller "var types = "controller" ; // Crave will now load the files in the given directory with the specified types.// Each file will recieve the application and configuration objects as parameters.// You can pass any number of parameters into the files being loaded by continuing// to overload the crave.driectory method. Once Crave has loaded all the files// the callback method will be called, aka startServerMethod.crave;
Errors
There are two types of errors passive
and blocking
. A blocking error is typically non-recoverable or requires the server to respond in some way. Where a passive error can be ignored, allowing the server to operate as normal or close to normal.
All errors are logged to the console by default and can be toggle off using the error
flag in the Crave configuration object.
Blocking Errors
If a blocking error occurs while requiring files crave will return the error instantly to the callback method provided. Your server can then determine the best course of action.
// ...var { iferr return console;}// ...crave;
Passive Errors
If, for example, a file contains an error and as a result Crave fails to require the file, then a passive error would be generated. Passive errors are passed to the callback method in the 3rd parameter, known as returnValues
. Where returnValues
is a list of values returned from each required file in the same order as the list of filesRequired
.
// ...var { iferr return console; console;}// ...crave;
Instead of undefined
or the expected return value you will instead see something like the following:
Config
You can configure Crave using the setConfig(myConfigObject)
method. Pass along an object with any of the properties you wish to override. For example:
var crave = ;var express = ; var app = ; crave crave
The available properties are:
Property | Type | Default | Description |
---|---|---|---|
cache | Object | An object containing configuration properties related to file path caching. | |
cache.enable | Boolean | false |
when true, the file path cache is used. |
cache.path | String | /data/cache.json |
An absolute path to where the file path cache is stored or will be stored. |
debug | Boolean | false |
When true, Crave will display log messages. |
error | Boolean | true |
When true, Crave will display error log messages. |
identification | Object | An object containing configuration properties related to how files are recognized and grouped. | |
identification.type | String | string |
Describes the method on each file to find an identifier. Available options are string or filename , where either the file is searched or a filename is searched looking for the identifier specified, respectively. |
identification.identifier | String | ~> |
A unique string used to indicate the following string indicates the grouping name for a file. |
trace | Boolean | false |
When true, Crave will display trace log messages. |
File Identification
You may have noticed that you can change how Crave identifies a file as a model
, controller
, or etc. There are two ways to identify a file, either using a string
of text in the file or by filename
.
String
When using the string
option, crave will search all the text in every file looking for the unique identifier you specify. Once an identifier is found the following string will be evaluated as a possible type (e.g. controller
).
String identification is the default for Crave and an example can be found in the Getting Started section.
Filename
When using the filename
option, crave will search each filename for the unique identifier you specified. Once an identifier is found the following characters will be evaluated as a possible type (e.g. controller
).
Crave can be configured to use filenames using the configuration object. Here is an example:
var crave = ;var express = ; var app = ; crave crave
Using the configuration described above the following file structure:
Crave would generate a list of files to require that looks like this:
~/myproject/app/device/device_model.js
~/myproject/app/user/user_model.js
~/myproject/app/device/device_controller.js
~/myproject/app/user/user_controller.js
Cache
Searching for files or inside files can take some time. In a development environment this time is negligible, however in a production environment we should avoid it. So when in production you should enable the cache.
crave.setConfig({
cache: {
enable: true
}
});
Once the cache is enabled and crave.directory()
is called, then crave will save the ordered list of files to a file. After that each time crave.directory()
is called the same list of files will be required until it is cleared, even if the server is restarted or new files are added.
Clear Cache
Crave can of course delete the cache using the clearCache()
method. Once the cache is deleted, a new list will be generated and saved the next time crave.directory()
is called. Lets look at an example:
// Keeps track of how many time we have restarted the server.var restartCounter = 0; // Create a method to start the server.var { iferr return console; var server = app;} // Enable the cache for crave.crave; // Trigger crave to search for all the files to require. Once found this ordered// list will be saved to a file. Once this file is created, it will never change// until you tell crave to remove it.crave;
Cache Path
The cache file is stored by default in the crave module folder at /data/cache.json
. You can change this location by specifying an absolute path in the path
property of the configuration object.
crave.setConfig({
cache: {
enable: true,
path: "/Absolute/Path/To/Custom/Cache/File.json"
}
})
Debug
Debugging crave can be done using the debug
, trace
, and error
flags that can be toggled on/off using the config. When enabling these flags additional logging will be enabled allowing you to find issues within Crave easier.
Documentation
Further documentation can be found in the wiki.