Assert styleguide

Author: tolyo

@types/shared/utils.d.ts

@@ -437,6 +437,7 @@ export function assert(argument: boolean, errorMsg?: string): void;
 /**
  * Validate a value using a predicate function.
  * Throws if the predicate returns false.
+ * IMPORTANT: use this function only for developper errors and not for user/data errors
  *
  * @param {ng.Validator} fn - Predicate validator function.
  * @param {*} arg - The value to validate.
@@ -459,6 +460,13 @@ export function validateRequired(arg: any, name: string): any;
  * @throws {TypeError} If the value does not satisfy the validator.
  */
 export function validateArray(arg: any, name: string): any;
+/**
+ * @param {*} arg - The value to validate.
+ * @param {string} name - Parameter name (included in error message).
+ * @returns {*} The validated value.
+ * @throws {TypeError} If the value does not satisfy the validator.
+ */
+export function validateIsString(arg: any, name: string): any;
 /**
  * Throw error if the argument is falsy.
  */

DEVELOPERS.md

@@ -342,158 +342,3 @@ yarn grunt build
 
 To view the docs, see [Running a Local Development Web Server](#local-server).
 
-### Writing jsdoc
-
-The ngdoc utility has basic support for many of the standard jsdoc directives. But in particular it
-is interested in the following block tags:
-
-- `@name name` - the name of the ngdoc document
-- `@param {type} name description` - describes a parameter of a function
-- `@returns {type} description` - describes what a function returns
-- `@requires` - normally indicates that a JavaScript module is required; in an Angular service it is
-  used to describe what other services this service relies on
-- `@property` - describes a property of an object
-- `@description` - used to provide a description of a component in markdown
-- `@link` - specifies a link to a URL or a type in the API reference.
-  Links to the API have the following structure:
-  - the module namespace, followed by `.` (optional, default `ng`)
-  - the `@ngdoc` type (see below), followed by `:` (optional, automatically inferred)
-  - the name
-  - the method, property, or anchor (optional)
-  - the display name
-
-  For example: `{@link ng.type:$rootScope.Scope#$new Scope.$new()}`.
-
-- `@example` - specifies an example. This can be a simple code block, or a
-  [runnable example](#the-example-tag).
-- `@deprecated` - specifies that the following code is deprecated and should not be used.
-  In The AngularTS docs, there are two specific patterns which can be used to further describe
-  the deprecation: `sinceVersion="<version>"` and `removeVersion="<version>"`
-
-The `type` in `@param` and `@returns` must be wrapped in `{}` curly braces, e.g. `{Object|Array}`.
-Parameters can be made optional by _either_ appending a `=` to the type, e.g. `{Object=}`, _or_ by
-putting the `[name]` in square brackets.
-Default values are only possible with the second syntax by appending `=<value>` to the parameter
-name, e.g. `@param {boolean} [ownPropsOnly=false]`.
-
-Descriptions can contain markdown formatting.
-
-#### AngularTS-specific jsdoc directives
-
-In addition to the standard jsdoc tags, there are a number that are specific to the Angular
-code-base:
-
-- `@ngdoc` - specifies the type of thing being documented. See below for more detail.
-- `@eventType emit|broadcast` - specifies whether the event is emitted or broadcast
-- `@usage` - shows how to use a `function` or `directive`. Is usually automatically generated.
-- `@knownIssue` - adds info about known quirks, problems, or limitations with the API, and possibly,
-  workarounds. This section is not for bugs.
-
-The following are specific to directives:
-
-- `@animations` - specifies the animations a directive supports
-- `@multiElement` - specifies if a directive can span over multiple elements
-- `@priority` - specifies a directive's priority
-- `@restrict` - is extracted to show the usage of a directive. For example, for [E]lement,
-  [A]ttribute, and [C]lass, use `@restrict ECA`
-- `@scope` - specifies that a directive will create a new scope
-
-### The `@ngdoc` Directive
-
-This directive helps to specify the template used to render the item being documented. For instance,
-a directive would have different properties to a filter and so would be documented differently. The
-commonly used types are:
-
-- `overview` - a general page (guide, api index)
-- `provider` - AngularTS provider, such as `$compileProvider` or `$httpProvider`.
-- `service` - injectable AngularTS service, such as `$compile` or `$http`.
-- `object` - well defined object (often exposed as a service)
-- `function` - function that will be available to other methods (such as a helper function within
-  the ng module)
-- `method` - method on an object/service/controller
-- `property` - property on an object/service/controller
-- `event` - AngularTS event that will propagate through the `$scope` tree.
-- `directive` - AngularTS directive
-- `filter` - AngularTS filter
-- `error` - minErr error description
-
-### General documentation with Markdown
-
-Any text in tags can contain markdown syntax for formatting. Generally, you can use any markdown
-feature.
-
-#### Headings
-
-Only use _h2_ headings and lower, as the page title is set in _h1_. Also make sure you follow the
-heading hierarchy. This ensures correct table of contents are created.
-
-#### Code blocks
-
-In line code can be specified by enclosing the code in back-ticks (\`).
-A block of multi-line code can be enclosed in triple back-ticks (\`\`\`) but it is formatted better
-if it is enclosed in &lt;pre&gt;...&lt;/pre&gt; tags and the code lines themselves are indented.
-
-### Writing runnable (live) examples and e2e tests
-
-It is possible to embed examples in the documentation along with appropriate e2e tests. These
-examples and scenarios will be converted to runnable code within the documentation. So it is
-important that they work correctly. To ensure this, all these e2e scenarios are run as part of the
-continuous integration tests.
-
-If you are adding an example with an e2e test, you should [run the test locally](#e2e-tests) first
-to ensure it passes. You can change `it(...)` to `it(...)` to run only your test,
-but make sure you change it back to `it(...)` before committing.
-
-#### The `<example>` tag
-
-This tag identifies a block of HTML that will define a runnable example. It can take the following
-attributes:
-
-- `animations` - if set to `true` then this example uses ngAnimate.
-- `deps` - Semicolon-separated list of additional angular module files to be loaded,
-  e.g. `angular-animate.js`
-- `name` - every example should have a name. It should start with the component, e.g directive name,
-  and not contain whitespace
-- `module` - the name of the app module as defined in the example's JavaScript
-
-Within this tag we provide `<file>` tags that specify what files contain the example code.
-
-```
-<example
-  module="angularAppModule"
-  name="exampleName"
-  deps="angular-animate.js;angular-route.js"
-  animations="true">
-  ...
-  <file name="index.html">...</file>
-  <file name="script.js">...</file>
-  <file name="animations.css">...</file>
-  <file name="protractor.js">...</file>
-  ...
-</example>
-```
-
-You can see an example of a well-defined example [in the `ngRepeat` documentation][code.ngRepeat-example].
-
-[closing-issues]: https://help.github.com/articles/closing-issues-via-commit-messages/
-[Closure guide to i18n changes]: https://github.com/google/closure-library/wiki/Internationalization-%28i18n%29-changes-in-Closure-Library
-[code.badrestrict]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/ng/compile.js#L1107-L1110
-[code.debugInfoEnabled]: https://github.com/angular/angular.js/blob/32fbb2e78f53d765fbb170f7cf99e42e072d363b/src/ng/compile.js#L1378-L1413
-[code.html5Mode]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/ng/location.js#L752-L797
-[code.minErr]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/minErr.js#L53-L113
-[code.ngRepeat-example]: https://github.com/angular/angular.js/blob/0822d34b10ea0371c260c80a1486a4d508ea5a91/src/ng/directive/ngRepeat.js#L249-L340
-[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
-[Common Locale Data Repository (CLDR)]: http://cldr.unicode.org
-[corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html
-[dgeni]: https://github.com/angular/dgeni
-[docs.badrestrict]: docs/content/error/$compile/badrestrict.ngdoc
-[docs.provider]: https://code.angularjs.org/snapshot/docs/api/auto/service/$provide#provider
-[git-revert]: https://git-scm.com/docs/git-revert
-[git-setup]: https://help.github.com/articles/set-up-git
-[github-issues]: https://github.com/angular/angular.js/issues
-[github]: https://github.com/angular/angular.js
-[js-style-guide]: https://google.github.io/styleguide/javascriptguide.xml
-[karma-browserstack]: https://github.com/karma-runner/karma-browserstack-launcher
-[karma-saucelabs]: https://github.com/karma-runner/karma-sauce-launcher
-[unit-testing]: https://docs.angularjs.org/guide/unit-testing
-[yarn-install]: https://yarnpkg.com/en/docs/install

STYLEGUIDE.md

@@ -0,0 +1,58 @@
+# AngularTS Internal style guide
+
+## 🔒 Assert Validation
+
+Asserts enforce **framework correctness**, not **application behavior**.
+
+Asserts exist to **detect developer errors**, enforce **internal
+invariants**, and make framework misuse fail fast during development.\
+They are *not* a general-purpose validation mechanism for runtime or
+user-controlled data.
+
+Any assert must:
+-   fail early and loudly with developer-only "sanity" checks
+-   maintain and support **public** API contracts and types
+-   must itself be part of the API via `@throw` tag
+
+#### ✅ When to Use Asserts
+
+Use asserts **only** when the error indicates a **fatal error**
+or **misuse of an internal API** such that a framework cannot function.
+
+Asserts SHOULD be used when:
+
+-   An internal invariant is violated.
+-   An API contract is not respected by developers.
+-   A value should *never* be invalid if the code using the API assumes it 
+    to be correct.
+-   The input originates from the framework itself, not from end-users or
+    dynamic data.
+-   The failure shoudl notify the developer to immediately stop what they are
+    doing and refactor their code.
+
+#### ❌ When *Not* to Use Asserts
+
+Do **not** use asserts for anything that may fail due to **external
+conditions**, **user-controlled input** or performance-critical code.
+
+Asserts SHOULD NOT be used for:
+
+-   End-user data.
+-   JSON data, environment config, or network responses.
+-   Errors that are part of expected runtime behavior.
+-   Validation of business rules.
+
+Assert SHOULD NOT be used in "hot code paths" or any place where
+its use can degrade the performance of the application over a period of time.
+
+These should be handled either by the developer, before it reaches the framework API, 
+or by a unified error sink at the framework level, such as `$exceptionHandler`;
+
+###### Examples
+
+-   User-provided data fails validation.
+-   Server returns malformed JSON.
+-   Missing runtime config.
+-   Event payloads have unexpected types.
+-   Anything that can be corrected by the user instead of the developer.
+

src/services/cookie/cookie.js

@@ -1,15 +1,14 @@
 import { $injectTokens } from "../../injection-tokens.js";
 import {
   BADARG,
-  BADARGKEY,
   BADARGVALUE,
   assert,
   isDefined,
-  isFunction,
   isNullOrUndefined,
   isNumber,
-  isObject,
   isString,
+  validateIsString,
+  validateRequired,
 } from "../../shared/utils.js";
 
 /**
@@ -42,8 +41,6 @@ export class CookieService {
    * @param {ng.ExceptionHandlerService} $exceptionHandler
    */
   constructor(defaults, $exceptionHandler) {
-    assert(isObject(defaults), BADARG);
-    assert(isFunction($exceptionHandler), BADARG);
     /** @type {ng.CookieOptions} */
     this.defaults = Object.freeze({ ...defaults });
     this.$exceptionHandler = $exceptionHandler;
@@ -57,7 +54,7 @@ export class CookieService {
    * @throws {URIError} – If decodeURIComponent fails.
    */
   get(key) {
-    assert(isString(key), BADARG);
+    validateIsString(key, "key");
 
     try {
       const all = parseCookies();
@@ -77,7 +74,8 @@ export class CookieService {
    * @throws {SyntaxError} if cookie JSON is invalid
    */
   getObject(key) {
-    assert(isString(key), BADARG);
+    validateIsString(key, "key");
+
     const raw = this.get(key);
 
     if (!raw) return null;
@@ -113,8 +111,8 @@ export class CookieService {
    * @param {ng.CookieOptions} [options]
    */
   put(key, value, options = {}) {
-    assert(isString(key), BADARGKEY);
-    assert(isString(value), BADARGVALUE);
+    validateIsString(key, "key");
+    validateIsString(value, "value");
     const encodedKey = encodeURIComponent(key);
 
     const encodedVal = encodeURIComponent(value);
@@ -138,7 +136,8 @@ export class CookieService {
    * @throws {TypeError} if Object cannot be converted to JSON
    */
   putObject(key, value, options) {
-    assert(isString(key), BADARGKEY);
+    validateIsString(key, "key");
+    validateRequired(value, "value");
     assert(!isNullOrUndefined(value), BADARGVALUE);
 
     try {
@@ -159,7 +158,7 @@ export class CookieService {
    * @param {ng.CookieOptions} [options]
    */
   remove(key, options = {}) {
-    assert(isString(key), BADARG);
+    validateIsString(key, "key");
     this.put(key, "", {
       ...this.defaults,
       ...options,

src/shared/utils.js

@@ -961,7 +961,7 @@ export function assert(argument, errorMsg = "Assertion failed") {
 
 /** @type {Map<ng.Validator, string>} */
 const reasons = new Map([
-  [isNullOrUndefined, "required"],
+  [notNullOrUndefined, "required"],
   [Array.isArray, "notarray"],
   [isInjectable, "notinjectable"],
   [isDefined, "required"],
@@ -980,6 +980,7 @@ function getReason(val) {
 /**
  * Validate a value using a predicate function.
  * Throws if the predicate returns false.
+ * IMPORTANT: use this function only for developper errors and not for user/data errors
  *
  * @param {ng.Validator} fn - Predicate validator function.
  * @param {*} arg - The value to validate.
@@ -1021,6 +1022,16 @@ export function validateArray(arg, name) {
   return validate(Array.isArray, arg, name);
 }
 
+/**
+ * @param {*} arg - The value to validate.
+ * @param {string} name - Parameter name (included in error message).
+ * @returns {*} The validated value.
+ * @throws {TypeError} If the value does not satisfy the validator.
+ */
+export function validateIsString(arg, name) {
+  return validate(isString, arg, name);
+}
+
 /**
  * Throw error if the argument is falsy.
  */