@angular-wave/angular.ts 0.9.2 → 0.9.4

package/{src/filters → docs/content/docs/filter}/filter.md

@@ -9,19 +9,23 @@
 -
 - @param {Array} array The source array.
 - <div class="alert alert-info">
-- **Note**: If the array contains objects that reference themselves, filtering is not possible.
+- **Note**: If the array contains objects that reference themselves, filtering
+  is not possible.
 - </div>
-- @param {string|Object|function()} expression The predicate to be used for selecting items from
+- @param {string|Object|function()} expression The predicate to be used for
+  selecting items from
 - `array`.
 -
 - Can be one of:
 -
-- - `string`: The string is used for matching against the contents of the `array`. All strings or
+- - `string`: The string is used for matching against the contents of the
+    `array`. All strings or
 -     objects with string properties in `array` that match this string will be returned. This also
 -     applies to nested object properties.
 -     The predicate can be negated by prefixing the string with `!`.
 -
-- - `Object`: A pattern object can be used to filter specific properties on objects contained
+- - `Object`: A pattern object can be used to filter specific properties on
+    objects contained
 -     by `array`. For example `{name:"M", phone:"1"}` predicate will return an array of items
 -     which have property `name` containing "M" and property `phone` containing "1". A special
 -     property name (`$` by default) can be used (e.g. as in `{$: "text"}`) to accept a match
@@ -37,13 +41,15 @@
 -     `{name: {first: 'John', last: 'Doe'}}` will **not** be matched by `{name: 'John'}`, but
 -     **will** be matched by `{$: 'John'}`.
 -
-- - `function(value, index, array)`: A predicate function can be used to write arbitrary filters.
+- - `function(value, index, array)`: A predicate function can be used to write
+    arbitrary filters.
 -     The function is called for each element of the array, with the element, its index, and
 -     the entire array itself as arguments.
 -
 -     The final result is an array of those elements that the predicate returned true for.
 -
-- @param {function(actual, expected)|true|false} [comparator] Comparator which is used in
+- @param {function(actual, expected)|true|false} [comparator] Comparator which
+  is used in
 -     determining if values retrieved using `expression` (when it is not a function) should be
 -     considered a match based on the expected value (from the filter expression) and actual
 -     value (from the object in the array).
@@ -54,16 +60,19 @@
 -     The function will be given the object value and the predicate value to compare and
 -     should return true if both values should be considered equal.
 -
-- - `true`: A shorthand for `function(actual, expected) { return angular.equals(actual, expected)}`.
+- - `true`: A shorthand for
+    `function(actual, expected) { return angular.equals(actual, expected)}`.
 -     This is essentially strict comparison of expected and actual.
 -
-- - `false`: A short hand for a function which will look for a substring match in a case
+- - `false`: A short hand for a function which will look for a substring match
+    in a case
 -     insensitive way. Primitive values are converted to strings. Objects are not compared against
 -     primitives, unless they have a custom `toString` method (e.g. `Date` objects).
 -
 -
 - Defaults to `false`.
 -
-- @param {string} [anyPropertyKey] The special property name that matches against any property.
+- @param {string} [anyPropertyKey] The special property name that matches
+  against any property.
 -     By default `$`.
 - \*/

package/{src/filters → docs/content/docs/filter}/json.md

@@ -4,12 +4,15 @@
 
 Allows you to convert a JavaScript object into a JSON string.
 
-This filter is mostly useful for debugging. When using the double curly `{{value}}` notation, the binding is automatically converted to JSON.
+This filter is mostly useful for debugging. When using the double curly
+`{{value}}` notation, the binding is automatically converted to JSON.
 
 ## Parameters
 
-- **object** `{*}`: Any JavaScript object (including arrays and primitive types) to filter.
-- **spacing** `{number=}`: The number of spaces to use per indentation, defaults to 2.
+- **object** `{*}`: Any JavaScript object (including arrays and primitive types)
+  to filter.
+- **spacing** `{number=}`: The number of spaces to use per indentation, defaults
+  to 2.
 
 ## Returns
 

package/docs/content/docs/filter/limit-to.md

@@ -0,0 +1,30 @@
+# limitTo Filter
+
+## Description
+
+Creates a new array or string containing only a specified number of elements.
+The elements are taken from either the beginning or the end of the source array,
+string, or number, as specified by the value and sign (positive or negative) of
+`limit`. Other array-like objects are also supported (e.g., array subclasses,
+NodeLists, JQLite/jQuery collections, etc.). If a number is used as input, it is
+converted to a string.
+
+## Parameters
+
+- **input** `{Array|ArrayLike|string|number}`: Array/array-like, string, or
+  number to be limited.
+- **limit** `{string|number}`: The length of the returned array or string.
+  - If the `limit` number is positive, `limit` number of items from the
+    beginning of the source array/string are copied.
+  - If the number is negative, `limit` number of items from the end of the
+    source array/string are copied.
+  - The `limit` will be trimmed if it exceeds `array.length`.
+  - If `limit` is undefined, the input will be returned unchanged.
+- **begin** `{(string|number)=}`: Index at which to begin limitation. As a
+  negative index, `begin` indicates an offset from the end of `input`. Defaults
+  to `0`.
+
+## Returns
+
+- `{Array|string}`: A new sub-array or substring of length `limit` or less if
+  the input had less than `limit` elements.

package/docs/content/docs/filter/order-by.md

@@ -0,0 +1,123 @@
+# OrderBy Filter
+
+## Description
+
+Returns an array containing the items from the specified `collection`, ordered
+by a `comparator` function based on the values computed using the `expression`
+predicate.
+
+For example, `[{id: 'foo'}, {id: 'bar'}] | orderBy:'id'` would result in
+`[{id: 'bar'}, {id: 'foo'}]`.
+
+The `collection` can be an Array or array-like object (e.g., NodeList, jQuery
+object, TypedArray, String, etc).
+
+The `expression` can be a single predicate or a list of predicates, each serving
+as a tie-breaker for the preceding one. The `expression` is evaluated against
+each item and the output is used for comparing with other items.
+
+You can change the sorting order by setting `reverse` to `true`. By default,
+items are sorted in ascending order.
+
+The comparison is done using the `comparator` function. If none is specified, a
+default, built-in comparator is used (see below for details - in a nutshell, it
+compares numbers numerically and strings alphabetically).
+
+### Under the Hood
+
+Ordering the specified `collection` happens in two phases:
+
+1. All items are passed through the predicate (or predicates), and the returned
+   values are saved along with their type (`string`, `number`, etc). For
+   example, an item `{label: 'foo'}`, passed through a predicate that extracts
+   the value of the `label` property, would be transformed to:
+   ```javascript
+   {
+     value: 'foo',
+     type: 'string',
+     index: ...
+   }
+   ```
+
+Note: null values use 'null' as their type. 2. The comparator function is used
+to sort the items, based on the derived values, types, and indices.
+
+If you use a custom comparator, it will be called with pairs of objects of the
+form {value: ..., type: '...', index: ...} and is expected to return 0 if the
+objects are equal (as far as the comparator is concerned), -1 if the 1st one
+should be ranked higher than the second, or 1 otherwise.
+
+To ensure that the sorting will be deterministic across platforms, if none of
+the specified predicates can distinguish between two items, orderBy will
+automatically introduce a dummy predicate that returns the item's index as
+value. (If you are using a custom comparator, make sure it can handle this
+predicate as well.)
+
+If a custom comparator still can't distinguish between two items, then they will
+be sorted based on their index using the built-in comparator.
+
+Finally, in an attempt to simplify things, if a predicate returns an object as
+the extracted value for an item, orderBy will try to convert that object to a
+primitive value before passing it to the comparator. The following rules govern
+the conversion:
+
+If the object has a valueOf() method that returns a primitive, its return value
+will be used instead. (If the object has a valueOf() method that returns another
+object, then the returned object will be used in subsequent steps.) If the
+object has a custom toString() method (i.e., not the one inherited from Object)
+that returns a primitive, its return value will be used instead. (If the object
+has a toString() method that returns another object, then the returned object
+will be used in subsequent steps.) No conversion; the object itself is used. The
+Default Comparator The default, built-in comparator should be sufficient for
+most use cases. In short, it compares numbers numerically, strings
+alphabetically (and case-insensitively), for objects falls back to using their
+index in the original collection, sorts values of different types by type, and
+puts undefined and null values at the end of the sorted list.
+
+More specifically, it follows these steps to determine the relative order of
+items:
+
+If the compared values are of different types: If one of the values is
+undefined, consider it "greater than" the other. Else if one of the values is
+null, consider it "greater than" the other. Else compare the types themselves
+alphabetically. If both values are of type string, compare them alphabetically
+in a case- and locale-insensitive way. If both values are objects, compare their
+indices instead. Otherwise, return: 0, if the values are equal (by strict
+equality comparison, i.e., using ===). -1, if the 1st value is "less than" the
+2nd value (compared using the < operator). 1, otherwise. Note: If you notice
+numbers not being sorted as expected, make sure they are actually being saved as
+numbers and not strings. Note: For the purpose of sorting, null and undefined
+are considered "greater than" any other value (with undefined "greater than"
+null). This effectively means that null and undefined values end up at the end
+of a list sorted in ascending order. Note: null values use 'null' as their type
+to be able to distinguish them from objects.
+
+Parameters collection {Array|ArrayLike}: The collection (array or array-like
+object) to sort.
+
+expression {(Function|string|Array.<Function|string>)=}: A predicate (or list of
+predicates) to be used by the comparator to determine the order of elements.
+
+Can be one of:
+
+Function: A getter function. This function will be called with each item as an
+argument and the return value will be used for sorting. string: An AngularTS
+expression. This expression will be evaluated against each item and the result
+will be used for sorting. For example, use 'label' to sort by a property called
+label or 'label.substring(0, 3)' to sort by the first 3 characters of the label
+property. (The result of a constant expression is interpreted as a property name
+to be used for comparison. For example, use '"special name"' (note the extra
+pair of quotes) to sort by a property called special name.) An expression can be
+optionally prefixed with + or - to control the sorting direction, ascending or
+descending. For example, '+label' or '-label'. If no property is provided,
+(e.g., '+' or '-'), the collection element itself is used in comparisons. Array:
+An array of function and/or string predicates. If a predicate cannot determine
+the relative order of two items, the next predicate is used as a tie-breaker.
+Note: If the predicate is missing or empty, then it defaults to '+'.
+
+reverse {boolean=}: If true, reverse the sorting order.
+
+comparator {(Function)=}: The comparator function used to determine the relative
+order of value pairs. If omitted, the built-in comparator will be used.
+
+Returns {Array}: The sorted array.

package/docs/content/docs/provider/sceProvider.md

@@ -0,0 +1,194 @@
+---
+title: $sceProvider
+description: >
+  Strict Contextual Escaping service
+---
+
+# `$sceProvider` and `$sce` Documentation
+
+## `$sceProvider`
+
+The `$sceProvider` provider allows developers to configure the [`$sce`](#sce)
+service.
+
+- Enable/disable Strict Contextual Escaping (SCE) in a module
+- Override the default implementation with a custom delegate
+
+Read more about [Strict Contextual Escaping (SCE)](#strict-contextual-escaping).
+
+---
+
+## `$sce`
+
+`$sce` is a service that provides **Strict Contextual Escaping (SCE)** services
+to AngularTS.
+
+---
+
+## Strict Contextual Escaping
+
+### Overview
+
+Strict Contextual Escaping (SCE) is a mode in which AngularTS constrains
+bindings to only render trusted values. Its goal is to:
+
+- Help you write **secure-by-default** code.
+- Simplify **auditing for vulnerabilities** such as XSS and clickjacking.
+
+By default, AngularTS treats **all values as untrusted** in HTML or sensitive
+URL bindings. When binding untrusted values, AngularTS will:
+
+- Sanitize or validate them based on context.
+- Or throw an error if it cannot guarantee safety.
+
+Example — `ng-bind-html` renders its value directly as HTML (its “context”). If
+the input is untrusted, AngularTS will sanitize or reject it.
+
+To bypass sanitization, you must mark a value as trusted before binding it.
+
+> **Note:** Since version 1.2, AngularTS ships with SCE **enabled by default**.
+
+---
+
+### Example: Binding in a Privileged Context
+
+```html
+<input ng-model="userHtml" aria-label="User input" />
+<div ng-bind-html="userHtml"></div>
+```
+
+If SCE is disabled, this allows arbitrary HTML injection — a serious XSS risk.
+
+To safely render user content, you should sanitize the HTML (on the server or
+client) **before** binding it.
+
+SCE ensures that only trusted, validated, or sanitized values are rendered.
+
+You can mark trusted values explicitly using:
+
+```js
+$sce.trustAs(context, value);
+```
+
+or shorthand methods such as:
+
+```js
+$sce.trustAsHtml(value);
+$sce.trustAsUrl(value);
+$sce.trustAsResourceUrl(value);
+```
+
+---
+
+### How It Works
+
+Directives and Angular internals bind trusted values using:
+
+```js
+$sce.getTrusted(context, value);
+```
+
+Example: the `ngBindHtml` directive uses `$sce.parseAsHtml` internally:
+
+```js
+let ngBindHtmlDirective = [
+  '$sce',
+  function ($sce) {
+    return function (scope, element, attr) {
+      scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function (value) {
+        element.html(value || '');
+      });
+    };
+  },
+];
+```
+
+---
+
+### Impact on Loading Templates
+
+SCE affects both:
+
+- The [`ng-include`](https://docs.angularjs.org/api/ng/directive/ngInclude)
+  directive
+- The `templateUrl` property in directives
+
+By default, AngularTS loads templates **only** from the same domain and protocol
+as the main document.  
+It uses:
+
+```js
+$sce.getTrustedResourceUrl(url);
+```
+
+To allow templates from other domains, use:
+
+- `$sceDelegateProvider.trustedResourceUrlList`
+- Or `$sce.trustAsResourceUrl(url)`
+
+> **Note:** Browser CORS and Same-Origin policies still apply.
+
+---
+
+### Is This Too Much Overhead?
+
+SCE applies only to **interpolation expressions**.
+
+Constant literals are automatically trusted, e.g.:
+
+```html
+<div ng-bind-html="'<b>implicitly trusted</b>'"></div>
+```
+
+If the `ngSanitize` module is included, `$sceDelegate` will use `$sanitize` to
+clean untrusted HTML automatically.
+
+AngularTS’ default `$sceDelegate` allows loading from your app’s domain,
+blocking others unless explicitly whitelisted.
+
+This small overhead provides major security benefits and simplifies auditing.
+
+---
+
+### Supported Trusted Contexts
+
+| Context             | Description                                                |
+| ------------------- | ---------------------------------------------------------- |
+| `$sce.HTML`         | Safe HTML (used by `ng-bind-html`).                        |
+| `$sce.CSS`          | Safe CSS. Currently unused.                                |
+| `$sce.MEDIA_URL`    | Safe media URLs (auto-sanitized).                          |
+| `$sce.URL`          | Safe navigable URLs.                                       |
+| `$sce.RESOURCE_URL` | Safe resource URLs (used in `ng-include`, `iframe`, etc.). |
+| `$sce.JS`           | Safe JavaScript for execution.                             |
+
+> ⚠️ Before AngularTS 1.7.0, `a[href]` and `img[src]` sanitized directly.  
+> As of 1.7.0, these now use `$sce.URL` and `$sce.MEDIA_URL` respectively.
+
+---
+
+### Resource URL List Patterns
+
+Trusted and banned resource URL lists accept:
+
+- `'self'` → matches same domain & protocol
+- Strings with wildcards:
+  - `*` → matches within a single path segment
+  - `**` → matches across path segments (use carefully)
+- Regular expressions (`RegExp`)
+
+> **Caution:** Regex patterns are powerful but harder to maintain — use only
+> when necessary.
+
+---
+
+### Disabling SCE (Not Recommended)
+
+You can disable SCE globally — though this is strongly discouraged.
+
+```js
+angular.module('myAppWithSceDisabled', []).config(function ($sceProvider) {
+  // Completely disable SCE. For demonstration purposes only!
+  // Do not use in new projects or libraries.
+  $sceProvider.enabled(false);
+});
+```

package/docs/content/docs/provider/templateRequestProvider.md

@@ -0,0 +1,5 @@
+---
+title: $templateRequestProvider
+description: >
+  Template request service
+---

package/docs/content/docs/service/compile.md

@@ -0,0 +1,5 @@
+---
+title: $compile
+description: >
+  Template compilation service
+---

package/docs/content/docs/service/controller.md

@@ -0,0 +1,5 @@
+---
+title: $controller
+description: >
+  Controller service
+---

package/docs/content/docs/service/http.md

@@ -0,0 +1,161 @@
+---
+title: $http
+description: >
+  HTTP service
+---
+
+# `$http` Service (AngularTS)
+
+The `$http` service is a core AngularTS service that facilitates communication
+with remote HTTP servers via the browser's
+[XMLHttpRequest](https://developer.mozilla.org/en/xmlhttprequest) object or via
+[JSONP](http://en.wikipedia.org/wiki/JSONP).
+
+For unit testing applications that use the `$http` service, see
+[`$httpBackend` mock](https://docs.angularjs.org/api/ngMock/service/$httpBackend).
+
+For a higher-level abstraction, see the
+[`$resource`](https://docs.angularjs.org/api/ngResource/service/$resource)
+service.
+
+The `$http` API is based on the
+[`$q` deferred/promise APIs](https://docs.angularjs.org/api/ng/service/$q).
+Familiarity with these APIs is important for advanced usage.
+
+---
+
+## General Usage
+
+The `$http` service is a function that takes a single argument — a
+**configuration object** — used to generate an HTTP request. It returns a
+**promise** that resolves on success or rejects on failure with a **response
+object**.
+
+```js
+$http({
+  method: 'GET',
+  url: '/someUrl'
+}).then(function successCallback(response) {
+  // Called asynchronously when the response is available
+}, function errorCallback(response) {
+  // Called asynchronously if an error occurs or the server returns an error
+});
+
+Shortcut Methods
+
+Shortcut methods are available for all common HTTP methods. All require a URL; POST/PUT requests require data. An optional config object can be passed as the last argument.
+
+$http.get('/someUrl', config).then(successCallback, errorCallback);
+$http.post('/someUrl', data, config).then(successCallback, errorCallback);
+
+
+Shortcut methods list:
+
+$http.get
+$http.head
+$http.post
+$http.put
+$http.delete
+$http.patch
+
+$http.get(...);
+
+Setting HTTP Headers
+
+The $http service automatically adds certain HTTP headers to all requests. These defaults can be configured using $httpProvider.defaults.headers.
+
+Default headers:
+
+Common headers: Accept: application/json, text/plain, */*
+
+POST headers: Content-Type: application/json
+
+PUT headers: Content-Type: application/json
+
+You can modify defaults:
+
+$httpProvider.defaults.headers.get = { 'My-Header': 'value' };
+
+
+Or modify headers globally at runtime:
+
+module.run(function($http) {
+  $http.defaults.headers.common.Authorization = 'Basic YmVlcDpib29w';
+});
+
+
+Per-request overrides:
+
+let req = {
+  method: 'POST',
+  url: 'http://example.com',
+  headers: {
+    'Content-Type': undefined
+  },
+  data: { test: 'test' }
+};
+
+$http(req).then(success, error);
+
+Transforming Requests and Responses
+
+Requests and responses can be transformed using transformRequest and transformResponse. Each can be a single function or an array of functions. Functions take (data, headersGetter[, status]) and return the transformed value.
+
+Note: AngularTS does not make a copy of data before passing it to transformRequest. Avoid side effects.
+
+Default transformations:
+
+Requests: objects are serialized to JSON
+
+Responses: XSRF prefix removed; JSON responses are parsed
+
+Per-request override example:
+
+function appendTransform(defaults, transform) {
+  defaults = angular.isArray(defaults) ? defaults : [defaults];
+  return defaults.concat(transform);
+}
+
+$http({
+  url: '...',
+  method: 'GET',
+  transformResponse: appendTransform($http.defaults.transformResponse, function(value) {
+    return doTransform(value);
+  })
+});
+
+Caching
+
+By default, $http responses are not cached. Enable caching with:
+
+config.cache = true or a cache object
+
+Global default cache: $http.defaults.cache = true
+
+Only GET and JSONP requests are cached.
+
+Interceptors
+
+Interceptors allow modification of requests/responses globally. Add factories to $httpProvider.interceptors.
+
+Interceptor types:
+
+request(config)
+
+requestError(rejection)
+
+response(response)
+
+responseError(rejection)
+
+Example:
+
+$provide.factory('myHttpInterceptor', function($q) {
+  return {
+    request: function(config) { return config; },
+    responseError: function(rejection) { return $q.reject(rejection); }
+  };
+});
+
+$httpProvider.interceptors.push('myHttpInterceptor');
+```

package/docs/content/docs/service/interpolation.md

@@ -0,0 +1,5 @@
+---
+title: $interpolate
+description: >
+  HTTP service
+---

package/docs/content/docs/service/log.md

@@ -1,7 +1,7 @@
 ---
 title: $log
 description: >
-  A simple service for logging
+  Logging service
 ---
 
 ### Using `$log`

package/docs/content/docs/service/parse.md

@@ -0,0 +1,5 @@
+---
+title: $parse
+description: >
+  URL normalization for HTML5/hashbang modes
+---

package/docs/content/docs/service/rootElement.md

@@ -0,0 +1,5 @@
+---
+title: $rootElement
+description: >
+  URL normalization for HTML5/hashbang modes
+---

package/docs/content/docs/service/rootScope.md

@@ -0,0 +1,5 @@
+---
+title: $rootScope
+description: >
+  Root scope service
+---