Closes #124.

Stable Version 1.0.0-beta.1

Author: jmdobry

CHANGELOG.md

@@ -1,4 +1,4 @@
-##### 1.0.0-beta.1 - xx August 2014
+##### 1.0.0-beta.1 - 23 August 2014
 
 ###### Backwards compatible API changes
 - #40 - Support for nested resource endpoints

README.md

@@ -11,10 +11,9 @@ Supporting relations, computed properties, model lifecycle control and a slew of
 __Latest Release:__ [0.10.5](http://angular-data.pseudobry.com/)
 __master:__ [1.0.0-beta.1](http://angular-data-next.pseudobry.com/)
 
-Angular-data is approaching 1.0.0 Beta. The API is stabilizing and angular-data is well tested.
-
-Although angular-data is being used in production, it's not 1.0.0. If you want to use Angular-data, keep an eye on the changelog. 1.0.0 will introduce strict semver (until then, minor number is bumped for breaking changes).
+Angular-data is in a 1.0.0 Beta. The API is rather stable and angular-data is well tested.
 
+Although angular-data is being used in production, it's not fully 1.0.0. If you want to use Angular-data, keep an eye on the changelog. 1.0.0 will introduce strict semver (until then, minor number is bumped for breaking changes).
 
 ## Documentation
 [http://angular-data.pseudobry.com](http://angular-data.pseudobry.com)

bower.json

@@ -26,11 +26,11 @@
     "karma.start.js"
   ],
   "devDependencies": {
-    "angular": "~1.2.16",
-    "angular-mocks": "~1.2.16",
+    "angular": "~1.2.22",
+    "angular-mocks": "~1.2.22",
     "angular-cache": "~3.1.0",
     "observe-js": "0.3.4",
-    "angular-data-mocks": "~0.5.3",
+    "angular-data-mocks": "~0.5.5",
     "bootstrap": "~3.2.0"
   }
 }

guide/angular-data/asynchronous.md

@@ -3,18 +3,18 @@
 @name Asynchronous Methods
 @description
 
-Angular-data ships with a number of asynchronous methods that facilitate communication between the data store and the
-persistence layer. These methods cover the basic CRUD operations.
+Angular-data ships with a number of asynchronous methods that facilitate communication between the data store and a
+persistence layer. These methods cover CRUD operations.
 
 The asynchronous methods return Promises produced by Angular's `$q` service.
 
 Example:
 
 ```js
-// synchronous
+// synchronous, looks only at the cache
 DS.get('document', 45); // undefined
 
-// asynchronous
+// asynchronous, works through an adapter
 DS.find('document', 45).then(function (document) {
   document; // { title: 'How to Cook', id: 45 }
 

guide/angular-data/how.md

@@ -3,8 +3,8 @@
 @name How do I?
 @description
 
-#### How do I serialize data before it's saved?
-Before the data store sends date to an adapter, you may need to transform it to a custom request object of yours.
+## How do I serialize data before it's saved?
+Before the data store sends data to an adapter, you may need to transform it into a custom request object of yours.
 
 Define a global serialization method:
 ```js
@@ -28,8 +28,8 @@ DS.defineResource({
 });
 ```
 
-#### How do I deserialize data?
-When an adapter returns data to the data store from the server, for example, you may need to extract data from a custom response object of yours.
+## How do I deserialize data?
+When an adapter returns data to the data store from a persistence layer, you may need to extract data from a custom response object of yours.
 
 Define a global deserialization method:
 ```js
@@ -48,3 +48,74 @@ DS.defineResource({
   }
 });
 ```
+
+## How do I use angular-cache with angular-data?
+
+First, make sure you have angular-data.js and angular-cache.js loaded and your app has `angular-data.DS` and `angular-data.DSCacheFactory` as dependencies.
+
+Each resource you define will have its own cache instance, so you can pass different options to each resource.
+
+```js
+var Document = DS.defineResource({
+  name: 'document',
+  maxAge: 900000,
+  deleteOnExpire: 'aggressive'
+});
+
+var User = DS.defineResource({
+  name: 'user',
+  maxAge: 36000000,
+  deleteOnExpire: 'aggressive',
+  onExpire: function (id, user) {...}
+});
+```
+
+## How do I add my own static methods to resources?
+
+```js
+app.factory('User', function (DS, $q) {
+
+  var loggedInUser;
+  
+  var User = DS.defineUser({
+    name: 'user',
+    methods: {
+      // Instance method
+      fullName: function () {
+        return this.first + ' ' + this.last;
+      }
+    }
+  });
+  
+  // Static method
+  User.getLoggedInUser = function () {
+    var deferred = $q.defer();
+    
+    if (loggedInUser) {
+      deferred.resolve(loggedInUser);
+    } else {
+      DS.find('loggedInUser', { cacheResponse: false })
+        .then(function (user) {
+          loggedInUser = user;
+          deferred.resolve(loggedInUser);
+        }, deferred.reject);
+    }
+      
+    return deferred.promise;
+  };
+  
+  return User;
+});
+```
+
+```js
+app.controller('ProfileCtrl', function (User) {
+
+  // use the static method
+  User.getLoggedInUser().then(function (user) {
+    
+    // instance methods would be used here
+    user.fullName(); // "John Anderson"
+  });
+});
+```

guide/angular-data/resource/resource.md

@@ -12,7 +12,7 @@
 @name Overview
 @description
 
-A _resource_ is the data and meta data associated with a particular RESTful endpoint.
+An angular-data _resource_ is the data and meta data associated with a particular RESTful resource.
 
 You define _resources_ and register them with the data store. A _resource definition_ tells angular-data
 about a particular _resource_, like what its root endpoint is and which attribute refers to the primary key of the
@@ -48,6 +48,10 @@ With this definition the data store assumes the following:
 - The RESTful endpoint for this resource is `DSProvider.defaults.baseUrl + "/document"`
 - The primary key is specified by the `"id"` property (or whatever is specified by `DSProvider.defaults.idAttribute`)
 - This resource has no custom lifecycle hooks (unless `DSProvider.defaults` has some lifecycle hooks defined)
+- No computed properties
+- No instance methods
+- No extra configuration for angular-cache (if you have it loaded)
+- No relations
 
 @doc overview
 @id advanced
@@ -62,16 +66,26 @@ var Document = DS.defineResource({
   idAttribute: '_id',
   endpoint: 'documents',
   baseUrl: 'https://example.com/api',
+  
+  // hook for the validate step in the model lifecycle
   validate: function (attrs, cb) {
     if (!angular.isObject(attrs) {
       cb('Must be an object!');
     } else if (!angular.isString(attrs.title)) {
       cb('title must be a string!');
     }
   },
+  
   // the "meta" property is reserved for developer use
   // it will never be used by the API
-  meta: {}
+  meta: {},
+  
+  // instance methods
+  methods: {
+    filename: function () {
+      return this.title + '.' + this.extension;
+    }
+  }
 });
 ```
 
@@ -80,7 +94,8 @@ With this definition the data store understands the following:
 - Resource will be referred to as `"document"`
 - The RESTful endpoint for this resource is `"https://example.com/api/documents"`
 - The primary key is specified by the `"_id"` property
-- Before create/save operations, the provided `validate` function is executed (and any lifecycle hooks defined in `DSProvider.defaults`)
+- Before create/update operations, the provided `validate` function is executed (and any lifecycle hooks defined in `DSProvider.defaults`)
+- documents will have one instance method
 
 See [DS.defineResource](/documentation/api/api/DS.sync_methods:defineResource) for the full resource definition specification.
 
@@ -100,7 +115,7 @@ The following asynchronous operations support a model lifecycle:
 - `create` - Implementation provided by adapter
 - `afterCreate` - Default: `noop`
 
-### DS.save()
+### DS.save() & DS.update()
 
 - `beforeValidate` - Default: `noop`
 - `validate` - Default: `noop`

guide/angular-data/resources.md

@@ -9,12 +9,16 @@ Angular-data keeps track of _resource definitions_ to know what kind of data sho
 myApp.run(function (DS) {
 
   // This is a basic resource definition
-  DS.defineResource({
+  var Document = DS.defineResource({
     name: 'document'
   });
 
   // angular-data now knows it can perform
   // operations related to the "document" resource
+  
+  // These are the same
+  Document.find(5).then(function (document) {...});
+  DS.find('document', 5).then(function (document) {...});
 });
 ```
 

guide/angular-data/synchronous.md

@@ -13,7 +13,7 @@ Example:
 DS.get('document', 45); // { title: 'How to Cook', id: 45 }
 ```
 
-`get(resourceName, id)` will return the data if it is in the store, otherwise `undefined`. This method is useful inside
+`get(resourceName, id[ options])` will return the data if it is in the store, otherwise `undefined`. This method is useful inside
 of a `$watch` callback function, for example:
 
 ```js
@@ -33,6 +33,7 @@ To make things simpler, angular-data has some bind methods to help with this:
 
 ```js
 DS.bindOne($scope, 'myDoc', 'document', 45');
+Document.bindOne($scope, 'myDoc', 45');
 ```
 
 The above example shows how to bind an item in the data store to the $scope. Whenever that item changes it will be updated

guide/index.html

@@ -6,10 +6,8 @@
 <head>
     <meta charset="utf-8">
     <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
-    <meta name="Description"
-        content="An in-browser data store for Angular.js.">
-    <meta name="Keywords"
-        content="model, schema, angular, angular.js, data, datastore, adapter, store">
+    <meta name="Description" content="Data store and caching for Angular.js.">
+    <meta name="Keywords" content="model, schema, angular, angular.js, data, datastore, adapter, store">
     <meta name="fragment" content="!">
     <meta name="google-site-verification" content="k4PBv7ljh_CWjOj3OwgNdB3dlnD1DFUiLZjoovga2so" />
     <title ng-bind-template="angular-data: {{mainpage.partialTitle}}">angular-data</title>