expressa 2.0.18 → 2.0.19

package/doc/custom-endpoints.md

@@ -1,20 +1,20 @@
-## Custom Endpoints
-
-Since Expressa exports a middleware you can include it in express apps that have other endpoints. These other endpoints
-do not have access to the current user and other expressa objects attached to the request object. If you need these see
-the section below.
-
-## Add endpoints within expressa
-
-The api middleware exposes a "custom" which is an express router you can attach additional endpoints to. These endpoints
-are called after internal expressa middleware, but before any expressa endpoints.
-
-Note: you can use req.hasPermission('users: edit') to check if the user has a specific permission.
-
-Example:
-```javascript
-const api = expressa.api();
-api.custom.get('/test', function (req, res) {
-    res.send(req.user)
-})
-```
+## Custom Endpoints
+
+Since Expressa exports a middleware you can include it in express apps that have other endpoints. These other endpoints
+do not have access to the current user and other expressa objects attached to the request object. If you need these see
+the section below.
+
+## Add endpoints within expressa
+
+The api middleware exposes a "custom" which is an express router you can attach additional endpoints to. These endpoints
+are called after internal expressa middleware, but before any expressa endpoints.
+
+Note: you can use req.hasPermission('users: edit') to check if the user has a specific permission.
+
+Example:
+```javascript
+const api = expressa.api();
+api.custom.get('/test', function (req, res) {
+    res.send(req.user)
+})
+```

package/doc/database.md

@@ -1,23 +1,23 @@
-### Generic JSON Database API
-
-You can access a collection's database using `expressa.db[collectionName].action where action is one of the following:
-
-* all - returns all documents
-* find - returns array of documents matching the mongo query
-* get - retrieve a document by id
-* create - create a new document
-* update - modify an existing document
-* delete - delete a document by id
-* init - called once during startup, useful to create/ensure collection exists
-
-### Implemented JSON databases
-* MongoDB
-* PostgreSQL (using [jsonb](http://www.postgresql.org/docs/9.4/static/datatype-json.html) and [mongo-query-to-postgres-jsonb](https://github.com/thomas4019/mongo-query-to-postgres-jsonb))
-* Text files (using [json-file-store](https://github.com/flosse/json-file-store) and [mongo-query](https://github.com/Automattic/mongo-query))
-* In-memory (useful for small/medium ephemeral datasets like logs)
-
-Other JSON capable databases can be added easily (pull requests welcome!) by writing a wrapper that supports each of the above methods.
-
-### Smart database objects
-
-[expressa-folder](https://npmjs.org/package/expressa-folder) will automatically add functions to objects returned by `all`,`find` and `get`
+### Generic JSON Database API
+
+You can access a collection's database using `expressa.db[collectionName].action where action is one of the following:
+
+* all - returns all documents
+* find - returns array of documents matching the mongo query
+* get - retrieve a document by id
+* create - create a new document
+* update - modify an existing document
+* delete - delete a document by id
+* init - called once during startup, useful to create/ensure collection exists
+
+### Implemented JSON databases
+* MongoDB
+* PostgreSQL (using [jsonb](http://www.postgresql.org/docs/9.4/static/datatype-json.html) and [mongo-query-to-postgres-jsonb](https://github.com/thomas4019/mongo-query-to-postgres-jsonb))
+* Text files (using [json-file-store](https://github.com/flosse/json-file-store) and [mongo-query](https://github.com/Automattic/mongo-query))
+* In-memory (useful for small/medium ephemeral datasets like logs)
+
+Other JSON capable databases can be added easily (pull requests welcome!) by writing a wrapper that supports each of the above methods.
+
+### Smart database objects
+
+[expressa-folder](https://npmjs.org/package/expressa-folder) will automatically add functions to objects returned by `all`,`find` and `get`

package/doc/development.md

@@ -1,34 +1,34 @@
-## Setup for developing expressa
-1. git clone git@github.com:thomas4019/expressa.git
-1. cd expressa
-1. npm install
-1. npm link
-1. cd modules/admin
-1. npm install
-1. npm run build
-
-In another folder, create a project using app.js from the readme.
-1. npm link expressa
-1. node app.js
-
-## Developing admin UI locally
-* npm run testserver
-* (cd modules/admin && npm run dev)
-* npm run cypress (to manually run specific tests)
-
-## Before committing/releasing
-* npm run test
-* npm run testdbs (if changing Postgres or Mongo code)
-* npm run testcypress (if changing admin UI or related)
-* npm run fixlint
-* (cd modules/admin && npm run lint) (if changing admin UI)
-
-## To release
-* Update version in package.json
-* (cd modules/admin && npm run build)
-* ls -la modules/admin/dist/static/js
-* npm publish
-* Create release on GitHub
-
-## More info
+## Setup for developing expressa
+1. git clone git@github.com:thomas4019/expressa.git
+1. cd expressa
+1. npm install
+1. npm link
+1. cd modules/admin
+1. npm install
+1. npm run build
+
+In another folder, create a project using app.js from the readme.
+1. npm link expressa
+1. node app.js
+
+## Developing admin UI locally
+* npm run testserver
+* (cd modules/admin && npm run dev)
+* npm run cypress (to manually run specific tests)
+
+## Before committing/releasing
+* npm run test
+* npm run testdbs (if changing Postgres or Mongo code)
+* npm run testcypress (if changing admin UI or related)
+* npm run fixlint
+* (cd modules/admin && npm run lint) (if changing admin UI)
+
+## To release
+* Update version in package.json
+* (cd modules/admin && npm run build)
+* ls -la modules/admin/dist/static/js
+* npm publish
+* Create release on GitHub
+
+## More info
 [Modules](doc/modules.md)

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