fix #70: Improve documentation for Transform decorator on properties

README.md

@@ -383,6 +383,45 @@ InstanceType.transforms = {
 };
 ```
 
+#### Transform Gotchas
+It is important to note that property transforms are lazily evaluated on field access, rather than when the document is retrieved from the database.
+This is done for performance reasons, but has the side effect that complex objects which are the targets of property transforms must be re-assigned to the field
+if you wish to trigger the `toDB` transform function.
+
+Let's take the following model definition for our example, here we have a GeoJSON representation of a location but we want our application to use the data
+in a `{lat,lng}` style object. In this case we can use a transform which translates from one form to another to accomplish our task.
+
+```typescript
+import {inspect} from "util";
+
+export class InstanceType extends Iridium.Instance<any, InstanceType> {
+    // Converts a GeoJSON object into a simple {lat, lng} object and back.
+    @Iridium.Transform(
+        data => { lat: data.coordinates[1], lng: data.coordinates[0] },
+        data => { type: "Point", coordinates: [data.lng, data.lat] }
+    )
+    position: {
+        lat: number;
+        lng: number;
+    };
+}
+
+db.Model.findOne().then(instance => {
+    console.log(util.inspect(instance.position)); // { lat: 1, lng: 2 }
+    console.log(util.inspect(instance.document.position)); // { type: "Point", coordinates: [2, 1] }
+
+    let pos = instance.pos;
+    pos.lat = 3;
+    console.log(util.inspect(pos)); // { lat: 3, lng: 2 }
+    console.log(util.inspect(instance.position)); // { lat: 1, lng: 2 }
+    console.log(util.inspect(instance.document.position)); // { type: "Point", coordinates: [2, 1] }
+
+    instance.position = pos
+    console.log(util.inspect(instance.position)); // { lat: 3, lng: 2 }
+    console.log(util.inspect(instance.document.position)); // { type: "Point", coordinates: [2, 3] }
+});
+```
+
 #### 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.

lib/Decorators.ts

@@ -106,6 +106,10 @@ export function Property(...args: any[]): (target: Instance<any, any> | Instance
  * @param {function} fromDB The function used to convert values from the database for the application.
  * @param {function} toDB The function used to convert values from the application to the form used in the database.
  *
+ * Property transforms are lazily evaluated when their fields are accessed for performance reasons.
+ * Modifying the values of an array or object will *not* trigger its transform function unless the
+ * document level property is re-assigned.
+ * 
  * This decorator can either compliment or replace the static transforms property on your instance
  * class, however only one transform can be applied to any property at a time.
  * If your transpiler does not support decorators then you are free to make use of the