ng-next
Ng-next is a simple and elegant way to use Angular 1.x with ES6 / ES7. It provides an expressive syntax to maintain the simplicity and readability of your code.
- Decorators for angular & ui-router
- Async / Await (zone.js) integration to make it compatible with angular's $digest cycle
- Monkey patch for
$scope.$watchCollectionto work with ES6 iterables (Set / Map / Symbol.iterator)
Requirements
- Angular 1.x
Note: In order to use Angular UI-Router specific decorators, you need to install Angular UI-Router first.
Installation
NPM
Ng-next is available on npm
npm install --save ng-next
Configuration
Ng-next will initialize itself the first time you call
import "ng-next"You may perform some configuration through the following object, altough there isn't much to configure because ng-next aims to provide the simplest solution you can get!
import {config} from "ng-next"
// If ng-next fails to auto-detect your module
config.MODULE = angular.module("my-app");
// Enable or disable zone.js for $digest support
config.ZONE_JS = true / false;Babel & Decorators
For the full list of ECMAScript 2015 features, please refer to the Babel Documentation.
If you want to use decorators please install Babel support for decoratos
Async / Await
Making asynchronous http requests was until now a bit of a hassle. Ng-next provides therefore an elegant and convenient way to achieve the same result.
Ng-next makes use of the ES6 async / await functions.
//Http call
async function doGet(url)
{
let response = await $http.get(url);
return response.data;
}
//API call
async getUsers()
{
this.users = await this.UserService.get();
}You don't have to manually call the $rootScope.$digest() after every asynchronous http requests you make.
This is achieved by bootstrapping your angular application inside its own "angular zone", which will trigger $rootScope.$digest(), if not already done, every time your code leaves the zone.
Note: With this technique you're also no longer relying on
$timeout,$intervaland so on...
Use nativesetTimeout,setInterval,addEventListener... and your app will still always be up to date. Magic!
Note:
NgZoneis available via the window object or as injectable service
NgZone.runOutsideAngular
Sometimes you want to execute something outside of angular, without executing $digest after the task has completed, this is often the case for frequent tasks like requestAnimationFrame that would totally destroy your CPU.
To achieve this, you may call your function outside of Angular
import {Inject, Service, Init} from "ng-next"
@Service
class RenderService
{
@Inject NgZone;
@Init render()
{
//Care, will trigger $digest every frame
//requestAnimationFrame(() => this.render());
//Will run without triggering anything
this.NgZone.runOutsideAngular(() => requestAnimationFrame(() => this.render()));
}
}For further information see zone.js Documentation
$scope.$watchCollection
Ng-next monkey patches $scope.$watchCollection of every scope to make it compatible with any iterable object.
With this technique you can use ng-repeat and similiar directives with a Set or any object that has a [Symbol.iterator] method.
import {Controller} from "ng-next"
@Controller
export class ListController
{
list = new Set(["1", "2", "3", "4", "5"])
[Symbol.iterator]()
{
return this.list[Symbol.iterator]();
}
}
//Html
<div ng-controller="ListController as listCtrl">
<h1>Iterate over Set</h1>
<h2 ng-repeat="item in listCtrl.list">{{ item }}</h2>
<h1>Iterate over controller</h1>
<h2 ng-repeat="item in listCtrl">{{ item }}</h2>
</div>Decorators
Angular configuration decorators
@Controller@Service@Component@Directive@Filter@Config / @Run
Utility decorators
@Inject@Init@Destroy@On@Watch@WatchCollection@Debounce
Other decorators
@State@Alias@View@Bind
Angular configuration decorators
@Controller
import {Controller} from "ng-next"
@Controller
export class FooController
{
@Inject $http;
}
@Controller("BarController") //Minify safe
export class BarController
{
@Inject $rootScope;
}
@Service
import {Service} from "ng-next"
@Service
export class FooService { }
@Service("BarService") //Minify safe
export class BarService { }
@Component
@Component is placed directly on top of its controller!
import {Component, View, Alias, Bind} from "ng-next"
/**
* Component with decorators
*/
@Component("bar") //<bar></bar> Same as @Component({ name : "bar" })
@Alias("barCtrl")
@View("<h1>{{ barCtrl.foo }}</h1>")
export class BarComponent
{
@Bind("=") foo;
constructor() {
console.log(this.foo);
}
}
/**
* More old-scool component.
* The object given into the decorator is used as directive configuration
* You may use every property a directive can have
*/
@Component("foo", {
template : "<h1>{{ fooCtrl.bar }}</h1>"
bindings : {
bar : "="
},
as : "fooCtrl"
}) //<foo> </foo>
export class FooComponent
{
constructor() {
console.log(this.bar);
}
}
@Directive
import {Directive} from "ng-next"
@Directive("foo") //<div foo> </div>
export class FooDirective
{
restrict = "AE"
scope = {
bar : "="
}
link(...){}
}
@Filter
import {Filter} from "ng-next"
export class Filters
{
/**
* @ngInject
*/
@Filter //uses method name as filter name
upper($http){
return (string) => string.toUpperCase()
}
/**
* @ngInject
*/
@Filter("lower")
lower($rootScope){
return (string) => string.toLowerCase()
}
}
}
@Config / @Run
import {Config, Run} from "ng-next"
export class Configuration
{
/**
* @ngInject
*/
@Run
runSomething($rootScope){
return (string) => string.toUpperCase()
}
/**
* @ngInject
*/
@Config
configureSomething($httpProvider){
//Config method
}
}Utility decorators
Those decorators should only be used on controllers and services. For services ng-next will use the $rootScope as the scope for @On, @Watch etc.
import {Inject, Controller, Init, Destroy, On, Watch, WatchCollection, Debounce}
@Controller
export class MainController
{
/**
* Directly inject the angular http service
*/
@Inject $http;
/**
* Directly inject the controller $scope
*/
@Inject $scope;
/**
* Inject the $rootScope under an alias
*/
@Inject("$rootScope") baseScope;
/**
* A random property
*/
property = "Hello World";
/**
* A random array
*/
array = ["1", "hello", "red"];
@Init //You cannot use await in constructors, so @Init is perfect for that
async init()
{
let response = await this.$http.get("....");
//Do init stuff
}
@Destroy
cleanUp()
{
//Cleanup when the controller / its scope gets destroyed
}
/**
* With @On you can listen to any event you can with $scope.$on
*/
@On("$stateChangeSuccess")
stateChanged(event)
{
console.log("state changed", event)
}
/**
* With @Watch you can listen to any property as you would with $scope.$watch, but
* its evaluateed on the controller instead of the scope
*/
@Watch("property")
stateChanged(newValue, oldValue)
{
console.log(`Property changed from ${oldValue} to ${newValue}`)
}
/**
* With @WatchCollection you can listen to any property as you would with $scope.$watchCollection, but
* its evaluateed on the controller instead of the scope
*/
@WatchCollection("array")
stateChanged(newValue, oldValue)
{
console.log(`Array changed from ${oldValue} to ${newValue}`)
}
/**
* @Debounce will debounce the method for the given amount of millis
*/
@Debounce(100)
oftenCalledMethod()
{
//I get executed after i wasn't called for 100 milliseconds
}
}Other decorators
@State
The @State decorator defines a state for the common ui-router plugin and sets the class
its on top of as controller.
You can combine it with @View / @Alias or configure the state as you're used to.
import {State, Alias, View}
@State({
name : "user",
url : "/user",
default : true // Default state
})
@View("/views/user.html")
@Alias("userCtrl")
export class UserController
{
//State controller
}
@Alias
Sets the controllerAs property of an @Component or @State
import {Alias, State, Component}
@State(...)
@Alias("userCtrl")
export class UserController{ ... }
@Component("user")
@Alias("userCtrl")
export class UserComponent{ ... }
@View
Sets the template / templateUrl property of an @Component or @State, if the string contains a "<" it will be
treated as the HTML template, otherwise it will be considered as the path to the HTML template.
import {View, State, Component}
@State(...)
@View("/views/user.html")
export class UserController{ ... }
@Component("user")
@View("<h1>Hello</h1>")
export class UserComponent{ ... }
@Bind
Defines a property / attribute which should be bound with the related component.
In this case the user component.
import {Bind, Component, View}
@Component("user")
@View("<h1>{{ $ctrl.name }}</h1>")
export class UserComponent
{
/**
* If the html is <user name="Dude"></user> then
* this property is "Dude"
*/
@Bind("@") name;
}
Info
This little library is pretty new and under active development. Please report bugs and improvements :)
License
The ng-next library is open-sourced software licensed under the MIT License.
