Merge branch 'master' into release

SierraSoftworks · Dec 15, 2015 · b8be5ec · b8be5ec
2 parents c0bf6e5 + d426f7f
commit b8be5ec
Show file tree

Hide file tree

Showing 37 changed files with 468 additions and 97 deletions.
diff --git a/.npmignore b/.npmignore
@@ -18,4 +18,5 @@ Gruntfile.js
 .gitattributes
 .gitignore
 typings/DefinitelyTyped
-doc/
+doc/
+*.dat
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,31 @@
 
+## [Working Changes](https://github.com/sierrasoftworks/iridium)
+- [3ecbcfa](https://github.com/sierrasoftworks/iridium/commit/3ecbcfa) Version 6.5.1
+- [2a6b079](https://github.com/sierrasoftworks/iridium/commit/2a6b079) (origin/master) fix [#25](https://github.com/sierrasoftworks/iridium/issues/25): Address issues when cloning values of type MongoDB.ObjectID and MongoDB.Binary
+- [95a5dff](https://github.com/sierrasoftworks/iridium/commit/95a5dff) doc: Updated docs
+- [defa9cb](https://github.com/sierrasoftworks/iridium/commit/defa9cb) Updated CHANGELOG
+
+## [v6.5.0](https://github.com/sierrasoftworks/iridium/tree/v6.5.0)
+- [dcfd08b](https://github.com/sierrasoftworks/iridium/commit/dcfd08b) Version 6.5.0
+- [a4a5caa](https://github.com/sierrasoftworks/iridium/commit/a4a5caa) doc: Added README content for the validation and transform layers
+- [f83905b](https://github.com/sierrasoftworks/iridium/commit/f83905b) doc: Added documentation explaining how to use @Transform on a class
+- [89f52ab](https://github.com/sierrasoftworks/iridium/commit/89f52ab) feat: Allow @Transform to be applied to a document
+- [a18a706](https://github.com/sierrasoftworks/iridium/commit/a18a706) build: Compile new JS files
+- [15bb03d](https://github.com/sierrasoftworks/iridium/commit/15bb03d) test: Add tests to ensure that $document transforms work as expected
+- [47ac927](https://github.com/sierrasoftworks/iridium/commit/47ac927) fix: Correctly apply $document.toDB to saved instances
+- [eeb6650](https://github.com/sierrasoftworks/iridium/commit/eeb6650) fix: Correctly convert new documents for the database
+- [011d48c](https://github.com/sierrasoftworks/iridium/commit/011d48c) refactor: Switch to using an options object for transform calls
+- [29a630a](https://github.com/sierrasoftworks/iridium/commit/29a630a) revert: Switch back to type-less Transforms as it would otherwise be a breaking change
+- [67872f2](https://github.com/sierrasoftworks/iridium/commit/67872f2) feat: Add BSON interfaces to help enhance type safety of low level code
+- [399babc](https://github.com/sierrasoftworks/iridium/commit/399babc) test: Fix a badly written test fixture
+- [b3b7eaf](https://github.com/sierrasoftworks/iridium/commit/b3b7eaf) fix: Improve validation errors for ObjectID validator
+- [8db6a98](https://github.com/sierrasoftworks/iridium/commit/8db6a98) feat: Add $document special transform
+- [0c3cb73](https://github.com/sierrasoftworks/iridium/commit/0c3cb73) style: Remove promise binding which is not needed with lambda functions
+- [8270e79](https://github.com/sierrasoftworks/iridium/commit/8270e79) feat: Expose property name and model for transform functions
+- [8dc9a32](https://github.com/sierrasoftworks/iridium/commit/8dc9a32) test: Fix various unhandled rejections when the database server is unavailable for testing
+- [ea7d614](https://github.com/sierrasoftworks/iridium/commit/ea7d614) Updated documentation
+- [cf6e586](https://github.com/sierrasoftworks/iridium/commit/cf6e586) Updated CHANGELOG
+
 ## [v6.4.1](https://github.com/sierrasoftworks/iridium/tree/v6.4.1)
 - [238db28](https://github.com/sierrasoftworks/iridium/commit/238db28) Version 6.4.1
 - [5bdb845](https://github.com/sierrasoftworks/iridium/commit/5bdb845) build: Compile code with latest changes
@@ -7,7 +34,7 @@
 - [3ced29a](https://github.com/sierrasoftworks/iridium/commit/3ced29a) tweak: Adjust error message to be more explicit about what can pass
 - [7b12722](https://github.com/sierrasoftworks/iridium/commit/7b12722) tweak: Improved error messages when a binary object fails validation
 - [a10dbd4](https://github.com/sierrasoftworks/iridium/commit/a10dbd4) test: Added a number of additional tests for the new binary type
-- [ec0890a](https://github.com/sierrasoftworks/iridium/commit/ec0890a) (origin/master, origin/HEAD) Updated documentation
+- [ec0890a](https://github.com/sierrasoftworks/iridium/commit/ec0890a) Updated documentation
 - [a76f656](https://github.com/sierrasoftworks/iridium/commit/a76f656) Updated CHANGELOG
 
 ## [v6.4.0](https://github.com/sierrasoftworks/iridium/tree/v6.4.0)
@@ -23,7 +50,7 @@
 - [50713c7](https://github.com/sierrasoftworks/iridium/commit/50713c7) Version 6.3.0
 - [f09fa1b](https://github.com/sierrasoftworks/iridium/commit/f09fa1b) Merge branch 'feat/async-hooks'
 - [fcddc72](https://github.com/sierrasoftworks/iridium/commit/fcddc72) Merge branch 'pr/20'
-- [1fe25e2](https://github.com/sierrasoftworks/iridium/commit/1fe25e2) (origin/feat/async-hooks, feat/async-hooks) refactor: Remove duplicate `wrapped` definition
+- [1fe25e2](https://github.com/sierrasoftworks/iridium/commit/1fe25e2) (origin/feat/async-hooks) refactor: Remove duplicate `wrapped` definition
 - [c697682](https://github.com/sierrasoftworks/iridium/commit/c697682) docs: Added some comments regarding promise performance under async conditions
 - [d24448e](https://github.com/sierrasoftworks/iridium/commit/d24448e) build: Update js maps following support for Promise.Thenable on external APIs
 - [9e56ec9](https://github.com/sierrasoftworks/iridium/commit/9e56ec9) refactor: Support libraries other than Bluebird for external promise sources
@@ -35,7 +62,7 @@
 - [2dabf54](https://github.com/sierrasoftworks/iridium/commit/2dabf54) Promises support in hooks
 - [0a8ee18](https://github.com/sierrasoftworks/iridium/commit/0a8ee18) feat: Add ability to specify a cursor's read preference using readFrom()
 - [ea3eb8f](https://github.com/sierrasoftworks/iridium/commit/ea3eb8f) feat: Add ability to use cursor to retrieve a single document
-- [bd0858e](https://github.com/sierrasoftworks/iridium/commit/bd0858e) (pr/20) Test case for promises in hooks
+- [bd0858e](https://github.com/sierrasoftworks/iridium/commit/bd0858e) Test case for promises in hooks
 - [0db5f34](https://github.com/sierrasoftworks/iridium/commit/0db5f34) Promises support in hooks
 - [1354dc0](https://github.com/sierrasoftworks/iridium/commit/1354dc0) Merge branch 'master' into release
 - [be5e698](https://github.com/sierrasoftworks/iridium/commit/be5e698) Updated documentation
@@ -102,7 +129,7 @@
 
 ## [v5.11.0](https://github.com/sierrasoftworks/iridium/tree/v5.11.0)
 - [bd475da](https://github.com/sierrasoftworks/iridium/commit/bd475da) Version 5.11.0
-- [ea2a7c8](https://github.com/sierrasoftworks/iridium/commit/ea2a7c8) Listed docs in README (Closes [#9](https://github.com/sierrasoftworks/iridium/issues/9))
+- [ea2a7c8](https://github.com/sierrasoftworks/iridium/commit/ea2a7c8) Listed docs in README (Closes #9)
 - [d806e89](https://github.com/sierrasoftworks/iridium/commit/d806e89) Updated documentation
 - [971a2b8](https://github.com/sierrasoftworks/iridium/commit/971a2b8) Added implementation and tests for core level connection hooks
 - [42940bb](https://github.com/sierrasoftworks/iridium/commit/42940bb) Merge branch 'master' into release
@@ -112,7 +139,7 @@
 ## [v5.10.1](https://github.com/sierrasoftworks/iridium/tree/v5.10.1)
 - [ad98906](https://github.com/sierrasoftworks/iridium/commit/ad98906) Version 5.10.1
 - [b18beb5](https://github.com/sierrasoftworks/iridium/commit/b18beb5) Merge pull request #17 from SierraSoftworks/feature/nicedocs
-- [9ece18a](https://github.com/sierrasoftworks/iridium/commit/9ece18a) Updated docs
+- [9ece18a](https://github.com/sierrasoftworks/iridium/commit/9ece18a) (feature/nicedocs) Updated docs
 - [39524f7](https://github.com/sierrasoftworks/iridium/commit/39524f7) Fixed a number of broken test fixtures
 - [89725a4](https://github.com/sierrasoftworks/iridium/commit/89725a4) Fix a little issue with CI tests
 - [7b29f33](https://github.com/sierrasoftworks/iridium/commit/7b29f33) Changed the submodule URL for docs
@@ -149,7 +176,7 @@
 - [b9c13fb](https://github.com/sierrasoftworks/iridium/commit/b9c13fb) Updated changelog generation
 - [f656174](https://github.com/sierrasoftworks/iridium/commit/f656174) Revert "Switch to Travis-CI container infrastucture"
 - [5261ea0](https://github.com/sierrasoftworks/iridium/commit/5261ea0) Revert "Updated travis config to use MongoDB precise (3.x)"
-- [cefc0f4](https://github.com/sierrasoftworks/iridium/commit/cefc0f4) (infrastructure/travisci-containers) Updated travis config to use MongoDB precise (3.x)
+- [cefc0f4](https://github.com/sierrasoftworks/iridium/commit/cefc0f4) Updated travis config to use MongoDB precise (3.x)
 - [d11c8f3](https://github.com/sierrasoftworks/iridium/commit/d11c8f3) Switch to Travis-CI container infrastucture
 - [3565d59](https://github.com/sierrasoftworks/iridium/commit/3565d59) Merge branch 'master' into release
 - [5a2dc37](https://github.com/sierrasoftworks/iridium/commit/5a2dc37) Updated CHANGELOG
@@ -461,7 +488,7 @@
 - [40fab25](https://github.com/sierrasoftworks/iridium/commit/40fab25) Log all the things for Travis
 - [50523ce](https://github.com/sierrasoftworks/iridium/commit/50523ce) Come on Travis, we believe in you
 - [858b766](https://github.com/sierrasoftworks/iridium/commit/858b766) Return nModified from update() on MongoDB 2.4
-- [caf864a](https://github.com/sierrasoftworks/iridium/commit/caf864a) (sierrasoftworks/master) Make some test failures output more useful informatio
+- [caf864a](https://github.com/sierrasoftworks/iridium/commit/caf864a) Make some test failures output more useful informatio
 - [86b494f](https://github.com/sierrasoftworks/iridium/commit/86b494f) Travis is still broken, more logging and possible fixes
 - [2448a4f](https://github.com/sierrasoftworks/iridium/commit/2448a4f) Support MongoDB 2.4 responses in update()
 - [81144a2](https://github.com/sierrasoftworks/iridium/commit/81144a2) Added some logging to find out why Travis is failing tes
@@ -481,7 +508,7 @@
 - [0147aea](https://github.com/sierrasoftworks/iridium/commit/0147aea) Updated project file
 - [f9e57cb](https://github.com/sierrasoftworks/iridium/commit/f9e57cb) Show badges for the master branch
 - [fdb0746](https://github.com/sierrasoftworks/iridium/commit/fdb0746) Merge pull request #7 from SierraSoftworks/typescript
-- [cab9a81](https://github.com/sierrasoftworks/iridium/commit/cab9a81) Renamed Promise to Bluebird to avoid confusion and possible conflicts
+- [cab9a81](https://github.com/sierrasoftworks/iridium/commit/cab9a81) (sierrasoftworks/typescript) Renamed Promise to Bluebird to avoid confusion and possible conflicts
 - [a029c1e](https://github.com/sierrasoftworks/iridium/commit/a029c1e) Removed unused variable in Omnom
 - [b4fb151](https://github.com/sierrasoftworks/iridium/commit/b4fb151) Removed unnecessary semicolons in module index
 - [45ec39d](https://github.com/sierrasoftworks/iridium/commit/45ec39d) Updated .jshintrc file
@@ -491,7 +518,7 @@
 - [aad75e8](https://github.com/sierrasoftworks/iridium/commit/aad75e8) Separated Model into a number of smaller files to make it more manageable
 - [fb6f69a](https://github.com/sierrasoftworks/iridium/commit/fb6f69a) Added some fringe case tests for Omnom
 - [2e48949](https://github.com/sierrasoftworks/iridium/commit/2e48949) Fixed Travis code climate configuration
-- [c91116d](https://github.com/sierrasoftworks/iridium/commit/c91116d) (sierrasoftworks/typescript) Added more badges to the README
+- [c91116d](https://github.com/sierrasoftworks/iridium/commit/c91116d) Added more badges to the README
 - [65ffea9](https://github.com/sierrasoftworks/iridium/commit/65ffea9) Updated code coverage submissions for CodeClimate
 - [8949641](https://github.com/sierrasoftworks/iridium/commit/8949641) Added coveralls coverage badge to README
 - [5e229b9](https://github.com/sierrasoftworks/iridium/commit/5e229b9) Updated the project file

diff --git a/README.md b/README.md
@@ -206,7 +206,8 @@ Iridium uses [Skmatc](https://github.com/SierraSoftworks/Skmatc) for schema vali
 we'll give a quick rundown of the way you make use of it here.
 
 The model's schema is defined using an object in which keys represent their document property counterparts while the values represent a validation
-rule.
+rule. You can also make use of the [`@Property`](http://sierrasoftworks.github.io/Iridium/globals.html#property) decorator to automatically build
+up your schema object.
 
 **TypeScript**
 ```typescript
@@ -221,6 +222,16 @@ class InstanceType {
 }
 ```
 
+```typescript
+class InstanceType extends Iridium.Instance<any, InstanceType> {
+    @Iridium.ObjectID
+    _id: string;
+
+    @Iridium.Property(String)
+    email: string;
+}
+```
+
 **JavaScript**
 ```javascript
 function InstanceType() {}
@@ -266,5 +277,142 @@ If you've used the `Iridium.Instance` constructor then you'll have a couple of u
 You'll also find `first()` and `select()` which allow you to select the first, or all, entr(y|ies) in a collection which match a predicate - ensuring that `this`
 maps to the instance itself within the predicate - helping to make comparisons somewhat easier within JavaScript ES5.
 
-### Custom Instances
-If you decide to implement your own instance constructor then this is the part you'll be interested in.
+## Best Practices
+There are a number of best practices which you should keep in mind when working with Iridium to help get the best possible experience. For starters, Iridium is
+built up of a number of smaller components - namely the [validation](https://github.com/sierrasoftworks/skmatc), transform and caching layers.
+
+### Validation Layer
+The validation layer allows you to plug in your own custom validators, or simply make use of the built in ones, to quickly validate your documents against a
+strongly defined schema. It is designed to enable you to quickly generate meaningful and human readable validation messages, minimizing the need for error
+translation within your application.
+
+Custom validators can be added either using the [`validators`](http://sierrasoftworks.github.io/Iridium/interfaces/instanceimplementation.html#validators) property
+or by using the [`@Validate`](http://sierrasoftworks.github.io/Iridium/globals.html#validate) decorator on your instance class.
+
+```typescript
+@Iridium.Validate('myValidator', x => x === 42)
+export class InstanceType extends Iridium.Instance<any, InstanceType> {
+    @Iridium.Property('myValidator')
+    myProperty: number;
+}
+```
+
+```javascript
+var skmatc = require('skmatc');
+
+function InstanceType() {
+    Iridium.Instance.apply(this, arguments);
+}
+
+require('util').inherits(InstanceType, Iridium.Instance);
+
+InstanceType.validators = [
+    skmatc.create(function(schema) {
+        return schema === 'myValidator';
+    }, function(data, schema, path) {
+        return data === 42;
+    })
+];
+
+InstanceType.schema = {
+    myProperty: 'myValidator'
+};
+```
+
+Iridium expects validators to operate in a read-only mode, modifying documents within your validators (while possible) is strongly discouraged as it can lead
+to some strange side effects and isn't guaranteed to behave the same way between releases. If you need to make changes to documents, take a look at the Transform
+Layer. 
+
+### Transform Layer
+The transform layer is designed to make changes to the documents you store within MongoDB as well as the data presented to your application. A good example is the
+way in which ObjectIDs are treated, within your application they appear as plain strings - allowing you to quickly and easily perform many different operations with
+them. However, when you attempt to save an ObjectID field to the database, it is automatically converted into the correct ObjectID object before being persisted.
+
+The transform layer allows you to register your own transforms both on a per-model and per-property basis. In the case of a model, the transform is given the whole
+document and is expected to return the transformed document. Property transforms work the same, except that they are presented with, and expected to return, the value
+of a single top-level property.
+
+The easiest way to add a transform is using the [`@Transform`](http://sierrasoftworks.github.io/Iridium/globals.html#transform) decorator, however if you are working
+in a language which doesn't yet support decorators then you can easily use the
+[`transforms`](http://sierrasoftworks.github.io/Iridium/interfaces/instanceimplementation.html#transforms) property on your instance class.
+
+```typescript
+@Iridium.Transform(document => {
+    document.lastFetched = new Date();
+}, document => {
+    document.lastFetched && delete document.lastFetched;
+    return document;
+})
+export class InstanceType extends Iridium.Instance<any, InstanceType> {
+    @Iridium.Transform(data => data.toUpperCase(), data => data.toLowerCase())
+    email: string;
+}
+```
+
+```javascript
+function InstanceType() {
+    Iridium.Instance.apply(this, arguments);
+}
+
+require('util').inherits(InstanceType, Iridium.Instance);
+
+InstanceType.transforms = {
+    $document: {
+        fromDB: document => {
+            document.lastFetched = new Date();
+        },
+        toDB: document => {
+            document.lastFetched && delete document.lastFetched;
+            return document;
+        }
+    },
+    email: {
+        fromDB: value => value.toUpperCase(),
+        toDB: value => value.toLowerCase()
+    }
+};
+```
+
+#### Useful Transform Tricks
+There are a couple of clever tricks you can do using transforms to enable additional functionality within Iridium. An example would be cleaning your documents of properties
+not defined within your schemas whenever they are saved to the database.
+
+##### Strict Schemas
+Let's say you want to only insert values which appear in your schemas - an example would be if you accept documents from a REST API and don't wish to manually cherry-pick
+the properties you are going to insert. It could also simply be a way of lazily cleaning up old properties from documents as your schema evolves over time, helping to avoid
+complications if someone forgets to clean up the database after making changes to the schema.
+This can be easily achieved using the `$document` transform.
+
+```typescript
+@Iridium.Transform(document => document, (document, property, model) => {
+    Object.keys(document).forEach(key => {
+        if(!model.schema.hasOwnProperty(key)) delete document[key];
+    });
+
+    return document;
+})
+export class InstanceType extends Iridium.Instance<any, InstanceType> {
+
+}
+```
+
+```javascript
+function InstanceType() {
+    Iridium.Instance.apply(this, arguments);
+}
+
+require('util').inherits(InstanceType, Iridium.Instance);
+
+InstanceType.transforms = {
+    $document: {
+        fromDB: document => document,
+        toDB: (document, property, model) => {
+            Object.keys(document).forEach(key => {
+                if(!model.schema.hasOwnProperty(key)) delete document[key];
+            });
+
+            return document;
+        }
+    }
+};
+```
diff --git a/dist/lib/Bson.js b/dist/lib/Bson.js