expressa 2.0.18 → 2.0.20

package/doc/listeners.md

@@ -1,103 +1,103 @@
-## When to use listeners
-
-* decorate endpoint responses with relational data
-* fine grained role-permissions: hide certain properties based on role
-* save bandwidth: hide certain properties like file/image-data 
-* do additional actions like sending emails when content is created or changed
-* add fields whose values are computed from others
-* custom validation like ensuring a user doesn't create too many documents of a collection type.
-
-> TIP: to prevent having listenercode all over the place, use [expressa-folder](https://npmjs.org/package/expressa-folder) to automatically map listeners to files.
-
-## Modifying behavior using listeners
-Use `expressa.addListener(eventTypes, priority, callback)`
-
-`eventTypes` is a string or array of the event types listed below e.g. 'get' or ['put', 'post']
-
-`priority` is a number which determines the order of callback execution. Listeners with lower priority are executed first. If you don't care about order just use 0.
-
-`callback` is a function like the following: 
-
-`function(req, collection, doc)`  where
-
-> `req` is the request  
-> `collection` is a string of the name of the collection acted upon  
-> `doc` is the relevant document.
-
-### Before Event Types
-
-Using these listeners you can control whether an action is allowed. Return `true` to allow the action. Return `false`  (or an object with a custom message, as shown in the example below) to deny the action. Don't return anything or `undefined` to let other listeners decide. If all listeners return undefined the action is allowed. Order is significant because it's the first defined return value that controls whether the action is allowed.
-
-A promise can be returned so that asynchronous logic can be perfomed. In this case, it will wait for the promise to fulfill and use the resolved value.
-
-* `get` - called once for each document being retrieved. Returning false in a request involving multiple documents (e.g. all or find) will simply remove that document from the list.
-* `post` - called before creating a new document
-* `put` - called before changing a document
-* `delete` - called before deleting a document. Note: only the _id of the document is available in the callback. If the full document is needed you will need to load it yourself.
-
-For example to prevent modifying old posts you could add the following listener:
-
-    expressa.addListener('put', 10, function(req, collection, doc) {
-      if (collection == 'listing') {
-        if (Date.now() - new Date(doc.meta.created) > (1000*60*60*24)) { //older than a day
-          return {
-            code: 403,
-            message: 'You cannot modify posts older than a day'
-          }
-        }
-      }
-    })
-
-### After Event Types
-
-With these, the value returned from the listener is ignored.
-
-* `changed` - called after a put or post has succeeded
-* `deleted` - called after a successful deletion
-
-## Debugging 
-
-Run `DEBUG=expressa node --use-strict app.js` or `DEBUG=* --use-strict node app.js` to see what's going on in your app
-
-## Async wrapper example 
-
-    var request = require('request');
-    expressa.addListener('put', -10, function(req, collection, doc) {
-      if (collection == 'users') {
-        var key = your google maps api key;
-        var loc = doc.address;
-        return new Promise(function(resolve, reject) {
-          request('https://maps.googleapis.com/maps/api/geocode/json?address=' + loc + '&key=' + key, function(err, response, body) {
-            if (err) {
-              console.error('failed to geolocate address');
-              return reject();
-            }
-            var data = JSON.parse(body);
-            if (!data.results[0]) {
-              console.error('Geolocation of user address had empty response.');
-              return reject();
-            }
-            doc.coordinates = data.results[0].geometry.location;
-            resolve();
-          });
-        });
-      }
-
-## Manual wrappers
-
-Sometimes you may need to wrap an expressa endpoint so you have full control before and after (like recovering from expressa errors, or other middleware). In those cases we can wrap an expressa-point like so:
-
-    app.post('/api/myendpoint', require('./lib/listener/myendpoint/post.js')(expressa) ) 
-    app.use('/api', expressa )
-
-> NOTE: put it above the expressa init
-
-And `lib/listener/myendpoint/post.js` like so:
-
-		module.exports = function(expressa) {
-			return function(req, res, next) {
-				          // do stuff before expressa handler 
-        next()    // run expressa handler
-									// do stuff after expressa handler
-     }
-   }
+## When to use listeners
+
+* decorate endpoint responses with relational data
+* fine grained role-permissions: hide certain properties based on role
+* save bandwidth: hide certain properties like file/image-data 
+* do additional actions like sending emails when content is created or changed
+* add fields whose values are computed from others
+* custom validation like ensuring a user doesn't create too many documents of a collection type.
+
+> TIP: to prevent having listenercode all over the place, use [expressa-folder](https://npmjs.org/package/expressa-folder) to automatically map listeners to files.
+
+## Modifying behavior using listeners
+Use `expressa.addListener(eventTypes, priority, callback)`
+
+`eventTypes` is a string or array of the event types listed below e.g. 'get' or ['put', 'post']
+
+`priority` is a number which determines the order of callback execution. Listeners with lower priority are executed first. If you don't care about order just use 0.
+
+`callback` is a function like the following: 
+
+`function(req, collection, doc)`  where
+
+> `req` is the request  
+> `collection` is a string of the name of the collection acted upon  
+> `doc` is the relevant document.
+
+### Before Event Types
+
+Using these listeners you can control whether an action is allowed. Return `true` to allow the action. Return `false`  (or an object with a custom message, as shown in the example below) to deny the action. Don't return anything or `undefined` to let other listeners decide. If all listeners return undefined the action is allowed. Order is significant because it's the first defined return value that controls whether the action is allowed.
+
+A promise can be returned so that asynchronous logic can be perfomed. In this case, it will wait for the promise to fulfill and use the resolved value.
+
+* `get` - called once for each document being retrieved. Returning false in a request involving multiple documents (e.g. all or find) will simply remove that document from the list.
+* `post` - called before creating a new document
+* `put` - called before changing a document
+* `delete` - called before deleting a document. Note: only the _id of the document is available in the callback. If the full document is needed you will need to load it yourself.
+
+For example to prevent modifying old posts you could add the following listener:
+
+    expressa.addListener('put', 10, function(req, collection, doc) {
+      if (collection == 'listing') {
+        if (Date.now() - new Date(doc.meta.created) > (1000*60*60*24)) { //older than a day
+          return {
+            code: 403,
+            message: 'You cannot modify posts older than a day'
+          }
+        }
+      }
+    })
+
+### After Event Types
+
+With these, the value returned from the listener is ignored.
+
+* `changed` - called after a put or post has succeeded
+* `deleted` - called after a successful deletion
+
+## Debugging 
+
+Run `DEBUG=expressa node --use-strict app.js` or `DEBUG=* --use-strict node app.js` to see what's going on in your app
+
+## Async wrapper example 
+
+    var request = require('request');
+    expressa.addListener('put', -10, function(req, collection, doc) {
+      if (collection == 'users') {
+        var key = your google maps api key;
+        var loc = doc.address;
+        return new Promise(function(resolve, reject) {
+          request('https://maps.googleapis.com/maps/api/geocode/json?address=' + loc + '&key=' + key, function(err, response, body) {
+            if (err) {
+              console.error('failed to geolocate address');
+              return reject();
+            }
+            var data = JSON.parse(body);
+            if (!data.results[0]) {
+              console.error('Geolocation of user address had empty response.');
+              return reject();
+            }
+            doc.coordinates = data.results[0].geometry.location;
+            resolve();
+          });
+        });
+      }
+
+## Manual wrappers
+
+Sometimes you may need to wrap an expressa endpoint so you have full control before and after (like recovering from expressa errors, or other middleware). In those cases we can wrap an expressa-point like so:
+
+    app.post('/api/myendpoint', require('./lib/listener/myendpoint/post.js')(expressa) ) 
+    app.use('/api', expressa )
+
+> NOTE: put it above the expressa init
+
+And `lib/listener/myendpoint/post.js` like so:
+
+		module.exports = function(expressa) {
+			return function(req, res, next) {
+				          // do stuff before expressa handler 
+        next()    // run expressa handler
+									// do stuff after expressa handler
+     }
+   }

package/doc/modules.md

@@ -1,9 +1,9 @@
-Modules are defined in modules/<module name>/<module name>.js and can export the following fields:
-
-| Field Name     | Type     | Purpose                                                   |
-|----------------|----------|-----------------------------------------------------------|
-| settingsSchema | object   | Properties to be added to the settings JSON schema object |
-| collections    | object[] | List of collections to be added on install                |
-| install        | function | Function to be called once, on install                    |
-| permissions    | string[] | List of permissions                                       |
+Modules are defined in modules/<module name>/<module name>.js and can export the following fields:
+
+| Field Name     | Type     | Purpose                                                   |
+|----------------|----------|-----------------------------------------------------------|
+| settingsSchema | object   | Properties to be added to the settings JSON schema object |
+| collections    | object[] | List of collections to be added on install                |
+| install        | function | Function to be called once, on install                    |
+| permissions    | string[] | List of permissions                                       |
 | init           | function | Function to be called on application startup              |

package/doc/permissions.md

@@ -1,15 +1,15 @@
-## Permissions
-
-Expressa lets you easily manage CRUD permissions for each type of action on collections using admin interface. Users can have one or more roles and each role is given ability to create, read, update, delete, etc.
-
-By default you start with the following roles (but you can add your own):
-
- * **Admin**: this is the "super user" role that lets you manage all data.
- * **Authenticated**: any signed-in user
- * **Anonymous**: permissions given to all requests that come from non-signed in users
-
-You can declare collections as having documents that are owned. This lets you manage permissions for editing, reading, and deleting a user's own documents.
-
-Here's a screenshot example of the admin UI for managing permissions on a "post" collection.
-
+## Permissions
+
+Expressa lets you easily manage CRUD permissions for each type of action on collections using admin interface. Users can have one or more roles and each role is given ability to create, read, update, delete, etc.
+
+By default you start with the following roles (but you can add your own):
+
+ * **Admin**: this is the "super user" role that lets you manage all data.
+ * **Authenticated**: any signed-in user
+ * **Anonymous**: permissions given to all requests that come from non-signed in users
+
+You can declare collections as having documents that are owned. This lets you manage permissions for editing, reading, and deleting a user's own documents.
+
+Here's a screenshot example of the admin UI for managing permissions on a "post" collection.
+
 ![post permissions](https://cloud.githubusercontent.com/assets/406149/15307975/8c609530-1b95-11e6-9888-36a76a9a8248.png)

package/doc/relationships.md

@@ -1,65 +1,65 @@
-## Relationships & References 
-
-Let's suppose we want to extend our `/data/collection/users.json`-collection, by specifying which user belongs to another user:
-
-    { 
-      "properties":{
-        "other_user":{            
-          "title": "Has relationship with",
-          "type": "string",·     
-          "links": [             
-              {                  
-                "rel": "» show profile",        
-                "href": "/admin/#/edit/users/{{self}}", 
-                "class": "comment-link open-in-modal primary-text"
-              }
-          ]
-        }
-
-        ...        
-
-      } 
-    }
-
-Done, now expressa-admin will show a textfield in which we can write the userid:
-
-![](https://gist.githubusercontent.com/coderofsalvation/1ea3f6fad8a880b45b1a23917f9975b5/raw/d828acb18ff1cb5c6e3b9319b813e996cfbfda8f/reference_2.png)
-
-
-## Dynamically generated Relationships
-
-To make things extra convenient, lets generate a dropdown of all users:
-
-      expressa.addListener('get', -101, function(req,collection,doc){
-        if( req.url.match(/\/users\/schema$/) != null ) {
-          // add user reference to schema      
-          var schema = {             
-            "enumSource": [{         
-                // A watched field source       
-                source: [],          
-                title: "{{item.title}}",        
-                value: "{{item.id}}" 
-            }]
-          }
-          return new Promise( function(resolve, reject ){
-            expressa.db.users.find() 
-            .then( function(users){  
-              users.map( function(u){·
-                schema.enumSource[0].source.push({title: u.firstname+" "+u.lastname+", "+u.email,id:u._id})·
-              })
-              doc.properties.id_parent.enumSource = schema.enumSource
-              return resolve({"code":200, "message":doc})
-            })
-            .catch(reject)                                                                                                                                                                                                                                                                                                           
-          })  
-        }  
-      }
-
-Done, now we'll have a nice dropdown to select our relationship:
-
-
-![](https://gist.githubusercontent.com/coderofsalvation/1ea3f6fad8a880b45b1a23917f9975b5/raw/d828acb18ff1cb5c6e3b9319b813e996cfbfda8f/reference_1.png)
-
-> For more info on enumSource see the [json-editor docs](https://github.com/jdorn/json-editor)
-
-> TIP: use [expressa-folder](https://npmjs.org/package/expressa-folder) to automatically map listeners to files.
+## Relationships & References 
+
+Let's suppose we want to extend our `/data/collection/users.json`-collection, by specifying which user belongs to another user:
+
+    { 
+      "properties":{
+        "other_user":{            
+          "title": "Has relationship with",
+          "type": "string",·     
+          "links": [             
+              {                  
+                "rel": "» show profile",        
+                "href": "/admin/#/edit/users/{{self}}", 
+                "class": "comment-link open-in-modal primary-text"
+              }
+          ]
+        }
+
+        ...        
+
+      } 
+    }
+
+Done, now expressa-admin will show a textfield in which we can write the userid:
+
+![](https://gist.githubusercontent.com/coderofsalvation/1ea3f6fad8a880b45b1a23917f9975b5/raw/d828acb18ff1cb5c6e3b9319b813e996cfbfda8f/reference_2.png)
+
+
+## Dynamically generated Relationships
+
+To make things extra convenient, lets generate a dropdown of all users:
+
+      expressa.addListener('get', -101, function(req,collection,doc){
+        if( req.url.match(/\/users\/schema$/) != null ) {
+          // add user reference to schema      
+          var schema = {             
+            "enumSource": [{         
+                // A watched field source       
+                source: [],          
+                title: "{{item.title}}",        
+                value: "{{item.id}}" 
+            }]
+          }
+          return new Promise( function(resolve, reject ){
+            expressa.db.users.find() 
+            .then( function(users){  
+              users.map( function(u){·
+                schema.enumSource[0].source.push({title: u.firstname+" "+u.lastname+", "+u.email,id:u._id})·
+              })
+              doc.properties.id_parent.enumSource = schema.enumSource
+              return resolve({"code":200, "message":doc})
+            })
+            .catch(reject)                                                                                                                                                                                                                                                                                                           
+          })  
+        }  
+      }
+
+Done, now we'll have a nice dropdown to select our relationship:
+
+
+![](https://gist.githubusercontent.com/coderofsalvation/1ea3f6fad8a880b45b1a23917f9975b5/raw/d828acb18ff1cb5c6e3b9319b813e996cfbfda8f/reference_1.png)
+
+> For more info on enumSource see the [json-editor docs](https://github.com/jdorn/json-editor)
+
+> TIP: use [expressa-folder](https://npmjs.org/package/expressa-folder) to automatically map listeners to files.

package/doc/testing.md

@@ -1,47 +1,47 @@
-## Testing your express(a) app
-
-Testing can be done in many ways, with or without a test framework.
-Here's just an easy testframework-agnostic, linux way to test your app.
-
-## package.json
-
-Add the 'test' command in the `script`-section of your package.json:
-
-    "scripts":{
-      "test": "for i in test/*; do [ -x $i  ] && [ ! -d $i  ] && { printf '\n<▶ '$i'\n\n' && ./$i || exit 1;  }; done;"
-    }
-
-## app.js 
-
-In your expressa main-file (`app.js` e.g.), search for `app.listen()`, and modify it like this:
-
-    module.exports = { 
-      expressa:expressa, 
-      express:express, 
-      app:app, 
-      server: app.listen(port, function(){
-        console.log("listening on "+host)
-        if( module.exports.onServerReady ) setTimeout(module.exports.onServerReady, 500 )  // fire tests if any
-      })
-    }
-
-## test/tests/mytest.js
-
-    #!/usr/bin/env node                                                                                                                                                                                                                
-    var app      = require('./../../app.js')     
-    var expressa = app.expressa
-
-    var run = function(done){
-      // do mocha stuff here etc and call done()  
-    }
-
-    app.onServerReady = run.bind(this, function(){
-      app.server.close()
-      process.exit(0)
-    }) 
-
-Dont forget to `chmod 755 test/tests/mytest.js` in the console 
-
-## That's it!
-
-Now just run `npm test` or `./test/tests/mytest.js` and your test(s) will run
+## Testing your express(a) app
+
+Testing can be done in many ways, with or without a test framework.
+Here's just an easy testframework-agnostic, linux way to test your app.
+
+## package.json
+
+Add the 'test' command in the `script`-section of your package.json:
+
+    "scripts":{
+      "test": "for i in test/*; do [ -x $i  ] && [ ! -d $i  ] && { printf '\n<▶ '$i'\n\n' && ./$i || exit 1;  }; done;"
+    }
+
+## app.js 
+
+In your expressa main-file (`app.js` e.g.), search for `app.listen()`, and modify it like this:
+
+    module.exports = { 
+      expressa:expressa, 
+      express:express, 
+      app:app, 
+      server: app.listen(port, function(){
+        console.log("listening on "+host)
+        if( module.exports.onServerReady ) setTimeout(module.exports.onServerReady, 500 )  // fire tests if any
+      })
+    }
+
+## test/tests/mytest.js
+
+    #!/usr/bin/env node                                                                                                                                                                                                                
+    var app      = require('./../../app.js')     
+    var expressa = app.expressa
+
+    var run = function(done){
+      // do mocha stuff here etc and call done()  
+    }
+
+    app.onServerReady = run.bind(this, function(){
+      app.server.close()
+      process.exit(0)
+    }) 
+
+Dont forget to `chmod 755 test/tests/mytest.js` in the console 
+
+## That's it!
+
+Now just run `npm test` or `./test/tests/mytest.js` and your test(s) will run

package/doc/uploading-files.md

@@ -1,53 +1,53 @@
-## Uploading files
-
-Lets say you want your blog posts to contain images.
-Here's how you add an image file-upload in `data/collection/post.json`:
-
-    "properties":{
-
-      ...
-
-      "picture": {
-          "title": "Picture",
-          "type": "string",
-          "media": {
-              "binaryEncoding": "base64",
-              "type": "image/png"
-          }
-      }
-
-> NOTE: you probably want to create an expressa listener which hides the 'picture'-property to save bandwidth. On top of that, you probably want automatic thumbnails using something like [this expressa middleware](https://gist.github.com/coderofsalvation/d3c67fbdf4639dfae4d292a37434097c)
-
-![](https://gist.githubusercontent.com/coderofsalvation/f9af1791560bdcde2e536ba6ee85fd66/raw/86bfd8821d4c426a8404ff10ea1164b4f171ea8c/file-upload.png)
-
-    "properties":{
-
-      ...
-
-      "file": {
-        "type": "string",
-        "format": "file",
-        "title": "File"
-        "links": [
-          {
-            "rel": "Download File",
-            "href": "/custom_endpoint/{{self}}",
-            // Can also set `download` to a string as per the HTML5 spec
-            "download": true
-          }
-        ]
-      }
-
-> NOTE: the links probably will need a custom endpoint which serves the file with the proper media type 
-
-    expressa.get('/files/:file',function(req,res,next){
-        var file = .... // get file
-        res.writeHeader(200, {
-          "Content-Type":"image/png"
-        })
-        res.send(file)
-    })
-
-For more info on the "links"- of "media"-property see [json-editor](https://github.com/jdorn/json-editor)
-
-> TODO: more examples (like listeners proxying the base64 string to S3 Bucket or a local folder)
+## Uploading files
+
+Lets say you want your blog posts to contain images.
+Here's how you add an image file-upload in `data/collection/post.json`:
+
+    "properties":{
+
+      ...
+
+      "picture": {
+          "title": "Picture",
+          "type": "string",
+          "media": {
+              "binaryEncoding": "base64",
+              "type": "image/png"
+          }
+      }
+
+> NOTE: you probably want to create an expressa listener which hides the 'picture'-property to save bandwidth. On top of that, you probably want automatic thumbnails using something like [this expressa middleware](https://gist.github.com/coderofsalvation/d3c67fbdf4639dfae4d292a37434097c)
+
+![](https://gist.githubusercontent.com/coderofsalvation/f9af1791560bdcde2e536ba6ee85fd66/raw/86bfd8821d4c426a8404ff10ea1164b4f171ea8c/file-upload.png)
+
+    "properties":{
+
+      ...
+
+      "file": {
+        "type": "string",
+        "format": "file",
+        "title": "File"
+        "links": [
+          {
+            "rel": "Download File",
+            "href": "/custom_endpoint/{{self}}",
+            // Can also set `download` to a string as per the HTML5 spec
+            "download": true
+          }
+        ]
+      }
+
+> NOTE: the links probably will need a custom endpoint which serves the file with the proper media type 
+
+    expressa.get('/files/:file',function(req,res,next){
+        var file = .... // get file
+        res.writeHeader(200, {
+          "Content-Type":"image/png"
+        })
+        res.send(file)
+    })
+
+For more info on the "links"- of "media"-property see [json-editor](https://github.com/jdorn/json-editor)
+
+> TODO: more examples (like listeners proxying the base64 string to S3 Bucket or a local folder)