ng-current - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

demo/directives.js

@@ -68,2 +68,8 @@ 'use strict'
 
+            // NOTE - you don't have to call User.byId
+            // here, `next` already represents the desired
+            // User object. I am using User.byId to simply
+            // show how you can acquire the state of
+            // **any** context-based entity, not just the
+            // user's "selected".
             User.byId(next.id).then(function(user) {
@@ -70,0 +76,0 @@ Contexts.select('user', user)

demo/services/Auth.js

@@ -20,3 +20,3 @@ 'use strict'
   this.current = function() {
-    return self.token('[e-mail]', 'pass123').then(function(auth) {
+    return self.token('[e-mail]', 'pass123').then(function(auth) {
       return Contexts.currentOr('auth', auth)
@@ -23,0 +23,0 @@ })

demo/services/Quote.js

@@ -22,3 +22,3 @@ 'use strict'
     return Site.current().then(function(site) {
-      return Contexts.currentOr('quote', { none: site.quotes[0] }) // provide first by default (TODO - something fancier)
+      return Contexts.currentOr('quote', site.quotes[0]) // provide first by default (TODO - something fancier, such as with $http)
     })
@@ -25,0 +25,0 @@ }

demo/services/Site.js

@@ -31,3 +31,3 @@ 'use strict'
     return User.current().then(function(user) {
-      return Contexts.currentOr('site', user.sites[0]) // provide first by default (TODO - something fancier)
+      return Contexts.currentOr('site', user.sites[0]) // provide first by default (TODO - something fancier, such as with $http)
     })
@@ -34,0 +34,0 @@ }

package.json

 {
   "name": "ng-current",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Relational context manager for Angular",
@@ -9,5 +9,2 @@ "main": "ng-current.js",
   },
-  "browser": {
-    "angular": "./node_modules/angular/angular.js"
-  },
   "repository": {
@@ -31,5 +28,3 @@ "type": "git",
   "devDependencies": {
-    "bower": "^1.7.7",
-    "json-loader": "^0.5.4",
-    "ng-annotate-loader": "^0.1.0"
+    "bower": "^1.7.7"
   },
@@ -36,0 +31,0 @@ "dependencies": {

README.md

@@ -5,14 +5,22 @@ # :radio_button: ng-current
 
+## tl;dr
+
+ * :sparkles: Transparently manage the context-based states of your interdependent `Services` and their related components
+ * :art: Non-invasive - choose how to integrate and when to use
+ * :rocket: Fast and efficient - based on PubSub, minimizing the complexity and size of the `$digest` cycle
+
 ## Problem
 
 Have you ever encountered challenges or annoyances with managing
-your Angular 1.X application's context of related **currently selected `Service` entities**?
+your Angular 1.X application's context of related **currently selected `Service` entities**?:
 
  * Dangling references to stale data in directives and views
-    - Example: The quote of another user still displaying after you logged out
+    - Example: The data of the last user still displaying after you re-authenticated as a new user
  * Needing to use `$watch` to ensure new defaults are selected properly
     - Example: A user has quotes, and if you switch users but are still viewing quotes, you may need to select a new "current" quote
  * Functions getting called excessively on the `$digest` cycle in order to help guarantee the "latest and greatest"
- * Tracking current entities in vanilla `Services`, which by design, doesn't integrate with the `$digest` cycle, often resulting in one or more of the aforementioned issues
+ * Needing to "drag along" related user selections across `Services` and other components in order to support state-dependent features that become relevant at a later point
+ * Tracking current entities in vanilla `Services`, which by design, do not integrate with the `$digest` cycle and often result in one or more of the aforementioned issues
 
+
 Managing this current context is trivial when you're only working
@@ -31,3 +39,3 @@ with a single disjoint entity (say for instance, an extremely basic `User`),
 For example, a `User` of say a construction management portal may be able
-to generate multiple `Sites`, each  which may have multiple `Quotes`. It is often
+to generate multiple construction `Sites`, each  which may have multiple `Quotes`. It is often
 the case that one entity of each type may be currently selected in the
@@ -53,2 +61,6 @@ application at a time (like when viewing a specific `Quote`, the others
 
+Deriving the other entities in this way can become difficult. For instance, a user can technically visit the page from any other page, and thus the proper state of the new page must be accessible and/or determinable from the state of any page preceding it (assuming all data is loaded asynchronously, satisfying SPA)
+
+Tools such as `angular-ui-router` have some success with alleviating this, but in my experience force the user to be overly verbose with redundant generator methods, and worse of all needing to jump through several hoops in order to make the correct data/state accessible to deeply nested components. This stems from the fact that state (and thus isolated scope-bound instances of Services) is exclusively controlled by the current `URL`, and this often makes supporting contextual features that don't quite fit into the URL scheme difficult and complex.
+
 ### Multiple "Current"s
@@ -64,10 +76,9 @@
 
-These can be tolerated for a while, but pretty much all of these will require the
-use of `$watch` throughout the app in order to guarantee that your data shows
-only the data that is relevant to the user's current selections (at least without forcing a page refresh,
-which in my opinion damages the user experience and the quality of your application).
+These can be tolerated for a while, but pretty much all of these will require either the
+use of `$watch` or monolthic controllers throughout the app in order to guarantee that your components show only the data that is relevant to the user's current selections (at least without forcing a page refresh,
+which breaks SPA and in my opinion damages the user experience and quality of your application).
 
 ---
 
-More examples on the challenges involved with SPA applications can be
+More examples on the challenges involved with SPAs can be
 found in [Gooey's README](https://github.com/slurmulon/gooey). Gooey is a small JS library
@@ -83,5 +94,5 @@ that takes a hierarchical, bi-directional PubSub approach for generic data synchronization
 By establishing the following properties:
- * `this.name` (required) a unique name to identify the service (often lowercase version of service)
+ * `this.name` (**required**) a unique name to identify the service (often lowercase version of service)
  * `this.model` (optional) pseudo-constructor function that's refreshed on updates to your Service entities
- * `this.rels` (optional) set of related child entities
+ * `this.rels` (optional) collection of immediate child entities, order independent
 
@@ -93,2 +104,3 @@ and then registering the service at the end of your definition:
 
+// inject `Contexts` service which serves as a transparent state orchestrator for our `Service`(s)
 mod.service('User', function(Contexts) {
@@ -101,3 +113,8 @@ var self = this
   this.model = function(user) {
-    // ... logic for a Service entity
+    // ... model logic for a single `User` entity
+
+    user.firstName = function() {
+      return user.givenName + ' ' + user.familyName
+    }
+
     return user
@@ -107,3 +124,6 @@ }
   // arbitrary user defined generator method -
-  // typically something using `$http` or `$resource` with cache
+  // typically something using `$http` or `$resource` with cache.
+  // multiple users are considered because
+  // more than one user may use the application
+  // in a single window session (asynchronous re-authentication)
   this.all = function() {
@@ -119,3 +139,3 @@ return [
   // because I'm lazy, this example simply
-  // returns the first in the array (`none` property)
+  // returns the first in the array
   this.current = function() {
@@ -127,3 +147,3 @@ return this.all().then(function(users) {
 
-  // required as the final definition of your Service.
+  // required as the final statement of your `Service`.
   // registers your Service with the global pool
@@ -148,7 +168,13 @@ Contexts.register(this)
 
-**ES5**: `var Current = require('ng-current')`
+**ES5**
+```javascript
+var Current = require('ng-current')
+```
 
-**ES6**: `import Current from 'ng-current'`
+**ES6**:
+```javascript
+import Current from 'ng-current'
+```
 
-but be sure to require `angular` first so that it's accessible to `ng-current`:
+but **be sure to require `angular` first** so that it's accessible to `ng-current`:
 
@@ -155,0 +181,0 @@ `import angular`

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24035

increased by8.11%

Dev dependency count

1

decreased by-66.67%

Number of lines in readme file

174

increased by17.57%

Worsened metrics

Lines of code

463

decreased by-1.28%

No dependency changes