blob: f2ef13a1f2c4e204962459430e917a694d845db0 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<meta name="author" content="2019-08-08 13:15:33 CEST">
<title>N4JS Language Specification</title>
<link rel="stylesheet" href="styles/spec.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
<!-- ************* docinfo ******************************************************************* -->
<!-- ************* Favicon ************-->
<link rel="icon" href="images/favicon.ico" />
<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
<link href="styles/prism.min.css" rel="stylesheet" />
<script type="text/javascript" async
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>
<!-- ************* Styles ************* -->
<link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css">
<!-- ****************** NavBar ****************** -->
<div id="menubar">
<div class="banner">
<a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a>
</div>
<ul>
<li><a href="index.html">Index</a></li>
</ul>
</div>
<!-- ************* docinfo ******************************************************************* -->
<style>
.admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42}
</style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>N4JS Language Specification</h1>
<div class="details">
<span id="author" class="author">2019-08-08 13:15:33 CEST</span><br>
<span id="revnumber">version 0.9</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="introduction.html#_introduction">1. Introduction</a>
<ul class="sectlevel2">
<li><a href="introduction.html#_notation">1.1. Notation</a>
<ul class="sectlevel3">
<li><a href="introduction.html#_grammar-notation">1.1.1. Grammar Notation</a></li>
<li><a href="introduction.html#_type-judgments-and-rules-and-constraints-notation">1.1.2. Type Judgments and Rules and Constraints Notation</a>
<ul class="sectlevel4">
<li><a href="introduction.html#_typing-rules-and-judgments">1.1.2.1. Typing Rules and Judgments</a></li>
<li><a href="introduction.html#_types-of-an-element">1.1.2.2. Types of an Element</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="introduction.html#_auxiliary-functions">1.2. Auxiliary Functions</a>
<ul class="sectlevel3">
<li><a href="introduction.html#_binding">1.2.1. Binding</a></li>
<li><a href="introduction.html#_merging-types">1.2.2. Merging Types</a>
<ul class="sectlevel4">
<li><a href="introduction.html#_logic-formulas">1.2.2.1. Logic Formulas</a></li>
</ul>
</li>
<li><a href="introduction.html#_symbols-and-font-convention">1.2.3. Symbols and Font Convention</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="grammar.html#_grammar">2. Grammar</a>
<ul class="sectlevel2">
<li><a href="grammar.html#_lexical-conventions">2.1. Lexical Conventions</a>
<ul class="sectlevel3">
<li><a href="grammar.html#_identifier-names-and-identifiers">2.1.1. Identifier Names and Identifiers</a></li>
<li><a href="grammar.html#_this-keyword">2.1.2. This Keyword</a></li>
<li><a href="grammar.html#_regular-expression-literals">2.1.3. Regular Expression Literals</a></li>
<li><a href="grammar.html#_automatic-semicolon-insertion">2.1.4. Automatic Semicolon Insertion</a></li>
<li><a href="grammar.html#_jsdoc">2.1.5. JSDoc</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="names.html#_names">3. Names</a>
<ul class="sectlevel2">
<li><a href="names.html#_access-control">3.1. Access Control</a></li>
<li><a href="names.html#_accessibility-of-types-top-level-variables-and-function-declarations">3.2. Accessibility of Types, Top-Level Variables and Function Declarations</a>
<ul class="sectlevel3">
<li><a href="names.html#_accessibility-of-members">3.2.1. Accessibility of Members</a></li>
<li><a href="names.html#_valid-names">3.2.2. Valid Names</a></li>
<li><a href="names.html#_qualified-names">3.2.3. Qualified Names</a></li>
<li><a href="names.html#_name-duplicates">3.2.4. Name Duplicates</a>
<ul class="sectlevel4">
<li><a href="names.html#_lexical-environment">3.2.4.1. Lexical Environment</a></li>
<li><a href="names.html#_duplicates-and-shadowing">3.2.4.2. Duplicates and Shadowing</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_types">4. Types</a>
<ul class="sectlevel2">
<li><a href="types.html#_overview">4.1. Overview</a></li>
<li><a href="types.html#_type-expressions">4.2. Type Expressions</a>
<ul class="sectlevel3">
<li><a href="types.html#_syntax">4.2.1. Syntax</a></li>
<li><a href="types.html#_properties">4.2.2. Properties</a></li>
<li><a href="types.html#_semantics">4.2.3. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_type-inference">4.3. Type Inference</a></li>
<li><a href="types.html#_generic-and-parameterized-types">4.4. Generic and Parameterized Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_generic-types">4.4.1. Generic Types</a></li>
<li><a href="types.html#_type-variables">4.4.2. Type Variables</a></li>
<li><a href="types.html#_parameterized-types">4.4.3. Parameterized Types</a></li>
</ul>
</li>
<li><a href="types.html#_primitive-ecmascript-types">4.5. Primitive ECMAScript Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_undefined-type">4.5.1. Undefined Type</a></li>
<li><a href="types.html#_null-type">4.5.2. Null Type</a></li>
<li><a href="types.html#_primitive-boolean-type">4.5.3. Primitive Boolean Type</a></li>
<li><a href="types.html#_primitive-string-type">4.5.4. Primitive String Type</a></li>
<li><a href="types.html#_primitive-number-type">4.5.5. Primitive Number Type</a></li>
<li><a href="types.html#_primitive-type-int">4.5.6. Primitive Type int</a></li>
<li><a href="types.html#_primitive-symbol-type">4.5.7. Primitive Symbol Type</a></li>
</ul>
</li>
<li><a href="types.html#_primitive-n4js-types">4.6. Primitive N4JS Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_any-type">4.6.1. Any Type</a>
<ul class="sectlevel4">
<li><a href="types.html#any-type-semantics">4.6.1.1. Semantics</a></li>
<li><a href="types.html#any-type-type-inference">4.6.1.2. Type Inference</a>
<ul class="sectlevel5">
<li><a href="types.html#_default-type-of-variables">4.6.1.2.1. Default Type of Variables</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_void-type">4.6.2. Void Type</a>
<ul class="sectlevel4">
<li><a href="types.html#void-type-semantics">4.6.2.1. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_unknown-type">4.6.3. Unknown Type</a></li>
<li><a href="types.html#_primitive-pathselector-and-i18nkey">4.6.4. Primitive Pathselector and I18nKey</a>
<ul class="sectlevel4">
<li><a href="types.html#pathselector-semantics">4.6.4.1. Semantics</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_built-in-ecmascript-object-types">4.7. Built-in ECMAScript Object Types</a>
<ul class="sectlevel3">
<li><a href="types.html#ECMAScript-objects-semantics">4.7.1. Semantics</a></li>
<li><a href="types.html#_object-type">4.7.2. Object Type</a></li>
<li><a href="types.html#_function-object-type">4.7.3. Function-Object-Type</a></li>
<li><a href="types.html#_array-object-type">4.7.4. Array Object Type</a></li>
<li><a href="types.html#_string-object-type">4.7.5. String Object Type</a></li>
<li><a href="types.html#_boolean-object-type">4.7.6. Boolean Object Type</a></li>
<li><a href="types.html#_number-object-type">4.7.7. Number Object Type</a></li>
<li><a href="types.html#_global-object-type">4.7.8. Global Object Type</a></li>
<li><a href="types.html#_symbol">4.7.9. Symbol</a></li>
<li><a href="types.html#_promise">4.7.10. Promise</a></li>
<li><a href="types.html#_iterator-interface">4.7.11. Iterator Interface</a></li>
<li><a href="types.html#_iterable-interface">4.7.12. Iterable Interface</a></li>
</ul>
</li>
<li><a href="types.html#_built-in-n4js-types">4.8. Built-In N4JS Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_n4object">4.8.1. N4Object</a>
<ul class="sectlevel4">
<li><a href="types.html#N4Object-semantics">4.8.1.1. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_n4class">4.8.2. N4Class</a></li>
<li><a href="types.html#IterableN">4.8.3. IterableN</a></li>
</ul>
</li>
<li><a href="types.html#_type-modifiers">4.9. Type Modifiers</a>
<ul class="sectlevel3">
<li><a href="types.html#Type_Modifiers_Dynamic">4.9.1. Dynamic</a></li>
<li><a href="types.html#_optional-return-types">4.9.2. Optional Return Types</a></li>
</ul>
</li>
<li><a href="types.html#_union-and-intersection-type-composed-types">4.10. Union and Intersection Type (Composed Types)</a>
<ul class="sectlevel3">
<li><a href="types.html#_union-type">4.10.1. Union Type</a>
<ul class="sectlevel4">
<li><a href="types.html#union-type-syntax">4.10.1.1. Syntax</a></li>
<li><a href="types.html#union-type-semantics">4.10.1.2. Semantics</a></li>
<li><a href="types.html#_warnings">4.10.1.3. Warnings</a></li>
</ul>
</li>
<li><a href="types.html#_intersection-type">4.10.2. Intersection Type</a>
<ul class="sectlevel4">
<li><a href="types.html#intersection-type-syntax">4.10.2.1. Syntax</a></li>
<li><a href="types.html#intersection-type-semantics">4.10.2.2. Semantics</a></li>
<li><a href="types.html#_warnings-2">4.10.2.3. Warnings</a></li>
</ul>
</li>
<li><a href="types.html#_composed-types-in-wildcards">4.10.3. Composed Types in Wildcards</a></li>
<li><a href="types.html#_property-access-for-composed-types">4.10.4. Property Access for Composed Types</a>
<ul class="sectlevel4">
<li><a href="types.html#_properties-of-union-type">4.10.4.1. Properties of Union Type</a>
<ul class="sectlevel5">
<li><a href="types.html#_remarks-on-union-type-s-members">4.10.4.1.1. Remarks on union type’s members:</a></li>
</ul>
</li>
<li><a href="types.html#_properties-of-intersection-type">4.10.4.2. Properties of Intersection Type</a>
<ul class="sectlevel5">
<li><a href="types.html#_remarks-on-intersection-type-s-methods">4.10.4.2.1. Remarks on intersection type’s methods:</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_constructor-and-classifier-type">4.11. Constructor and Classifier Type</a>
<ul class="sectlevel3">
<li><a href="types.html#_syntax-3">4.11.1. Syntax</a></li>
<li><a href="types.html#_semantics-2">4.11.2. Semantics</a></li>
<li><a href="types.html#_constructors-and-prototypes-in-ecmascript-2015">4.11.3. Constructors and Prototypes in ECMAScript 2015</a></li>
</ul>
</li>
<li><a href="types.html#_this-type">4.12. This Type</a>
<ul class="sectlevel3">
<li><a href="types.html#this-type-syntax">4.12.1. Syntax</a></li>
<li><a href="types.html#this-keyword-semantics">4.12.2. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_enums">4.13. Enums</a>
<ul class="sectlevel3">
<li><a href="types.html#_enums-n4js">4.13.1. Enums (N4JS)</a>
<ul class="sectlevel4">
<li><a href="types.html#enums-syntax">4.13.1.1. Syntax</a></li>
<li><a href="types.html#enums-semantics">4.13.1.2. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_string-based-enums">4.13.2. String-Based Enums</a></li>
</ul>
</li>
<li><a href="types.html#_short-hand-syntax">4.14. Short-Hand Syntax</a>
<ul class="sectlevel3">
<li><a href="types.html#_array-short-hand-syntax">4.14.1. Array Short-Hand Syntax</a></li>
<li><a href="types.html#_iterablen-short-hand-syntax">4.14.2. IterableN Short-Hand Syntax</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_classifiers">5. Classifiers</a>
<ul class="sectlevel2">
<li><a href="classifiers.html#_n4js-specific-classifiers">5.1. N4JS Specific Classifiers</a>
<ul class="sectlevel3">
<li><a href="classifiers.html#_properties-2">5.1.1. Properties</a></li>
<li><a href="classifiers.html#_common-semantics-of-classifiers">5.1.2. Common Semantics of Classifiers</a></li>
<li><a href="classifiers.html#_classes">5.1.3. Classes</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_definition-of-classes">5.1.3.1. Definition of Classes</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#class-syntax">5.1.3.1.1. Syntax</a></li>
<li><a href="classifiers.html#class-properties">5.1.3.1.2. Properties</a></li>
<li><a href="classifiers.html#class-type-inference">5.1.3.1.3. Type Inference</a></li>
</ul>
</li>
<li><a href="classifiers.html#class-semantics">5.1.3.2. Semantics</a></li>
<li><a href="classifiers.html#_final-modifier">5.1.3.3. Final Modifier</a></li>
<li><a href="classifiers.html#_abstract-classes">5.1.3.4. Abstract Classes</a></li>
<li><a href="classifiers.html#_non-instantiable-classes">5.1.3.5. Non-Instantiable Classes</a></li>
<li><a href="classifiers.html#_superclass">5.1.3.6. Superclass</a></li>
</ul>
</li>
<li><a href="classifiers.html#_interfaces">5.1.4. Interfaces</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_definition-of-interfaces">5.1.4.1. Definition of Interfaces</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#interfaces-syntax">5.1.4.1.1. Syntax</a></li>
<li><a href="classifiers.html#interfaces-properties">5.1.4.1.2. Properties</a></li>
<li><a href="classifiers.html#interfaces-type-inference">5.1.4.1.3. Type Inference</a></li>
<li><a href="classifiers.html#interfaces-semantics">5.1.4.1.4. Semantics</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_generic-classifiers">5.1.5. Generic Classifiers</a></li>
<li><a href="classifiers.html#sec:definition-site-variance">5.1.6. Definition-Site Variance</a></li>
</ul>
</li>
<li><a href="classifiers.html#_members">5.2. Members</a>
<ul class="sectlevel3">
<li><a href="classifiers.html#_syntax-4">5.2.1. Syntax</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_properties-3">5.2.1.1. Properties</a></li>
</ul>
</li>
<li><a href="classifiers.html#_semantics-3">5.2.2. Semantics</a></li>
<li><a href="classifiers.html#_methods">5.2.3. Methods</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_syntax-5">5.2.3.1. Syntax</a></li>
<li><a href="classifiers.html#_properties-4">5.2.3.2. Properties</a></li>
<li><a href="classifiers.html#_semantics-4">5.2.3.3. Semantics</a></li>
<li><a href="classifiers.html#_final-methods">5.2.3.4. Final Methods</a></li>
<li><a href="classifiers.html#_abstract-methods">5.2.3.5. Abstract Methods</a></li>
<li><a href="classifiers.html#_generic-methods">5.2.3.6. Generic Methods</a></li>
</ul>
</li>
<li><a href="classifiers.html#_default-methods-in-interfaces">5.2.4. Default Methods in Interfaces</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_asynchronous-methods">5.2.4.1. Asynchronous Methods</a></li>
</ul>
</li>
<li><a href="classifiers.html#_constructors">5.2.5. Constructors</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_structural-this-type-in-constructor">5.2.5.1. Structural This Type in Constructor</a></li>
<li><a href="classifiers.html#spec-constructor">5.2.5.2. @Spec Constructor</a></li>
<li><a href="classifiers.html#_callable-constructors">5.2.5.3. Callable Constructors</a></li>
<li><a href="classifiers.html#_covariant-constructors">5.2.5.4. Covariant Constructors</a></li>
</ul>
</li>
<li><a href="classifiers.html#_data-fields">5.2.6. Data Fields</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#data-fields-syntax">5.2.6.1. Syntax</a></li>
<li><a href="classifiers.html#data-fields-properties">5.2.6.2. Properties</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#data-fields-semantics">5.2.6.2.1. Semantics</a></li>
<li><a href="classifiers.html#data-fields-type-inference">5.2.6.2.2. Type Inference</a></li>
</ul>
</li>
<li><a href="classifiers.html#_assignment-modifiers">5.2.6.3. Assignment Modifiers</a></li>
<li><a href="classifiers.html#_field-accessors-getter-setter">5.2.6.4. Field Accessors (Getter/Setter)</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#field-acessors-syntax">5.2.6.4.1. Syntax</a></li>
<li><a href="classifiers.html#field-acessors-properties">5.2.6.4.2. Properties</a></li>
<li><a href="classifiers.html#field-accessors-semantics">5.2.6.4.3. Semantics</a></li>
</ul>
</li>
<li><a href="classifiers.html#optional-fields">5.2.6.5. Optional Fields</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#_syntax-6">5.2.6.5.1. Syntax</a></li>
<li><a href="classifiers.html#_semantics-5">5.2.6.5.2. Semantics</a></li>
<li><a href="classifiers.html#_background">5.2.6.5.3. Background</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_static-members">5.2.7. Static Members</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_access-from-and-to-static-members">5.2.7.1. Access From and To Static Members</a></li>
<li><a href="classifiers.html#_generic-static-methods">5.2.7.2. Generic static methods</a></li>
<li><a href="classifiers.html#_static-members-of-interfaces">5.2.7.3. Static Members of Interfaces</a></li>
</ul>
</li>
<li><a href="classifiers.html#_redefinition-of-members">5.2.8. Redefinition of Members</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_overriding-of-members">5.2.8.1. Overriding of Members</a></li>
<li><a href="classifiers.html#_implementation-of-members">5.2.8.2. Implementation of Members</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#_member-consumption">5.2.8.2.1. Member Consumption</a></li>
<li><a href="classifiers.html#_member-implementation">5.2.8.2.2. Member Implementation</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_structural-typing">5.3. Structural Typing</a>
<ul class="sectlevel3">
<li><a href="classifiers.html#_syntax-7">5.3.1. Syntax</a></li>
<li><a href="classifiers.html#_definition-site-structural-typing">5.3.2. Definition Site Structural Typing</a></li>
<li><a href="classifiers.html#_use-site-structural-typing">5.3.3. Use-Site Structural Typing</a></li>
<li><a href="classifiers.html#structural-readWriteInit-field-typing">5.3.4. Structural Read-only, Write-only and Initializer Field Typing</a></li>
<li><a href="classifiers.html#_public-setter-annotated-with-code-providesinitializer-code">5.3.5. Public Setter Annotated With <code>ProvidesInitializer</code></a></li>
<li><a href="classifiers.html#_structural-types-with-optional-fields">5.3.6. Structural Types With Optional Fields</a></li>
<li><a href="classifiers.html#_structural-types-with-access-modifier">5.3.7. Structural Types With Access Modifier</a></li>
<li><a href="classifiers.html#_structural-types-with-additional-members">5.3.8. Structural Types With Additional Members</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_syntax-8">5.3.8.1. Syntax</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#_semantics-6">5.3.8.1.1. Semantics</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_functions">6. Functions</a>
<ul class="sectlevel2">
<li><a href="functions.html#_function-type">6.1. Function Type</a>
<ul class="sectlevel3">
<li><a href="functions.html#_properties-5">6.1.1. Properties</a></li>
<li><a href="functions.html#function-type-inference">6.1.2. Type Inference</a></li>
<li><a href="functions.html#_autoboxing-of-function-type">6.1.3. Autoboxing of Function Type</a></li>
<li><a href="functions.html#_arguments-object">6.1.4. Arguments Object</a></li>
</ul>
</li>
<li><a href="functions.html#_ecmascript-5-function-definition">6.2. ECMAScript 5 Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_function-declaration">6.2.1. Function Declaration</a>
<ul class="sectlevel4">
<li><a href="functions.html#_syntax-9">6.2.1.1. Syntax</a></li>
<li><a href="functions.html#_semantics-8">6.2.1.2. Semantics</a></li>
</ul>
</li>
<li><a href="functions.html#_function-expression">6.2.2. Function Expression</a>
<ul class="sectlevel4">
<li><a href="functions.html#function-expression-syntax">6.2.2.1. Syntax</a></li>
<li><a href="functions.html#_semantics-and-type-inference">6.2.2.2. Semantics and Type Inference</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_ecmascript-2015-function-definition">6.3. ECMAScript 2015 Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_formal-parameters">6.3.1. Formal Parameters</a>
<ul class="sectlevel4">
<li><a href="functions.html#Type_Modifiers_Optional">6.3.1.1. Optional Parameters</a></li>
<li><a href="functions.html#Type_Modifiers_Default">6.3.1.2. Default Parameters</a></li>
<li><a href="functions.html#Type_Modifiers_Variadic">6.3.1.3. Variadic</a></li>
</ul>
</li>
<li><a href="functions.html#_generator-functions">6.3.2. Generator Functions</a>
<ul class="sectlevel4">
<li><a href="functions.html#generator-functions-syntax">6.3.2.1. Syntax</a></li>
<li><a href="functions.html#generator-functions-semantics">6.3.2.2. Semantics</a></li>
<li><a href="functions.html#_generator-arrow-functions">6.3.2.3. Generator Arrow Functions</a></li>
</ul>
</li>
<li><a href="functions.html#_arrow-function-expression">6.3.3. Arrow Function Expression</a>
<ul class="sectlevel4">
<li><a href="functions.html#arrow-function-expression-syntax">6.3.3.1. Syntax</a></li>
<li><a href="functions.html#arrow-function-expression-semantics-and-type-inference">6.3.3.2. Semantics and Type Inference</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_ecmascript-proposals-function-definition">6.4. ECMAScript Proposals Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_asynchronous-functions">6.4.1. Asynchronous Functions</a>
<ul class="sectlevel4">
<li><a href="functions.html#asynchronous-functions-syntax">6.4.1.1. Syntax</a></li>
<li><a href="functions.html#asynchronous-functions-semantics">6.4.1.2. Semantics</a></li>
<li><a href="functions.html#_asynchronous-arrow-functions">6.4.1.3. Asynchronous Arrow Functions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_n4js-extended-function-definition">6.5. N4JS Extended Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_generic-functions">6.5.1. Generic Functions</a></li>
<li><a href="functions.html#_promisifiable-functions">6.5.2. Promisifiable Functions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_conversions-and-reflection">7. Conversions and Reflection</a>
<ul class="sectlevel2">
<li><a href="conversions_and_reflection.html#_autoboxing-and-coercing">7.1. Autoboxing and Coercing</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_coercing">7.1.1. Coercing</a></li>
<li><a href="conversions_and_reflection.html#_autoboxing-of-primitives">7.1.2. Autoboxing of Primitives</a></li>
<li><a href="conversions_and_reflection.html#_autoboxing-of-function-expressions-and-declarations">7.1.3. Autoboxing of Function Expressions and Declarations</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_auto-conversion-of-objects">7.2. Auto-Conversion of Objects</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_auto-conversion-of-class-instances">7.2.1. Auto-Conversion of Class Instances</a>
<ul class="sectlevel4">
<li><a href="conversions_and_reflection.html#_auto-conversion-of-interface-instances">7.2.1.1. Auto-Conversion of Interface Instances</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_auto-conversion-of-enum-literals">7.2.2. Auto-Conversion of Enum Literals</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_type-cast-and-type-check">7.3. Type Cast and Type Check</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_type-cast">7.3.1. Type Cast</a></li>
<li><a href="conversions_and_reflection.html#_type-check">7.3.2. Type Check</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_reflection-meta-information">7.4. Reflection meta-information</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_reflection-for-classes">7.4.1. Reflection for Classes</a></li>
<li><a href="conversions_and_reflection.html#_reflection-for-interfaces">7.4.2. Reflection for Interfaces</a></li>
<li><a href="conversions_and_reflection.html#_reflection-for-enumerations">7.4.3. Reflection for Enumerations</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_conversion-of-primitive-types">7.5. Conversion of primitive types</a></li>
</ul>
</li>
<li><a href="expressions.html#_expressions">8. Expressions</a>
<ul class="sectlevel2">
<li><a href="expressions.html#_ecmascript-5-expressions">8.1. ECMAScript 5 Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_the-this-literal">8.1.1. The this Literal</a></li>
<li><a href="expressions.html#_identifier">8.1.2. Identifier</a></li>
<li><a href="expressions.html#_literals">8.1.3. Literals</a>
<ul class="sectlevel4">
<li><a href="expressions.html#_integer-literals">8.1.3.1. Integer Literals</a></li>
</ul>
</li>
<li><a href="expressions.html#_array-literal">8.1.4. Array Literal</a></li>
<li><a href="expressions.html#_object-literal">8.1.5. Object Literal</a>
<ul class="sectlevel4">
<li><a href="expressions.html#_properties-6">8.1.5.1. Properties</a></li>
<li><a href="expressions.html#_scoping-and-linking">8.1.5.2. Scoping and linking</a></li>
</ul>
</li>
<li><a href="expressions.html#_parenthesized-expression-and-grouping-operator">8.1.6. Parenthesized Expression and Grouping Operator</a></li>
<li><a href="expressions.html#_property-accessors">8.1.7. Property Accessors</a>
<ul class="sectlevel4">
<li><a href="expressions.html#properties-1">8.1.7.1. Properties</a></li>
</ul>
</li>
<li><a href="expressions.html#_new-expression">8.1.8. New Expression</a></li>
<li><a href="expressions.html#_function-expression-2">8.1.9. Function Expression</a></li>
<li><a href="expressions.html#_function-calls">8.1.10. Function Calls</a></li>
<li><a href="expressions.html#_postfix-expression">8.1.11. Postfix Expression</a></li>
<li><a href="expressions.html#_unary-expression">8.1.12. Unary Expression</a></li>
<li><a href="expressions.html#_multiplicative-expression">8.1.13. Multiplicative Expression</a></li>
<li><a href="expressions.html#_additive-expression">8.1.14. Additive Expression</a>
<ul class="sectlevel4">
<li><a href="expressions.html#type-inference-10">8.1.14.1. Type Inference</a></li>
</ul>
</li>
<li><a href="expressions.html#_bitwise-shift-expression">8.1.15. Bitwise Shift Expression</a></li>
<li><a href="expressions.html#_relational-expression">8.1.16. Relational Expression</a></li>
<li><a href="expressions.html#_equality-expression">8.1.17. Equality Expression</a></li>
<li><a href="expressions.html#_binary-bitwise-expression">8.1.18. Binary Bitwise Expression</a></li>
<li><a href="expressions.html#_binary-logical-expression">8.1.19. Binary Logical Expression</a></li>
<li><a href="expressions.html#_conditional-expression">8.1.20. Conditional Expression</a></li>
<li><a href="expressions.html#_assignment-expression">8.1.21. Assignment Expression</a></li>
<li><a href="expressions.html#_comma-expression">8.1.22. Comma Expression</a></li>
</ul>
</li>
<li><a href="expressions.html#_ecmascript-6-expressions">8.2. ECMAScript 6 Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_the-super-keyword">8.2.1. The super Keyword</a></li>
</ul>
</li>
<li><a href="expressions.html#_ecmascript-7-expressions">8.3. ECMAScript 7 Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_await-expression">8.3.1. Await Expression</a></li>
</ul>
</li>
<li><a href="expressions.html#_n4js-specific-expressions">8.4. N4JS Specific Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_class-expression">8.4.1. Class Expression</a></li>
<li><a href="expressions.html#_cast-as-expression">8.4.2. Cast (As) Expression</a>
<ul class="sectlevel4">
<li><a href="expressions.html#cast-as-expression-semantics-type-inference">8.4.2.1. Semantics and Type Inference</a></li>
</ul>
</li>
<li><a href="expressions.html#Import_Calls">8.4.3. Import Calls</a></li>
</ul>
</li>
<li><a href="expressions.html#compile-time-expressions">8.5. Compile-Time Expressions</a></li>
</ul>
</li>
<li><a href="statements.html#_statements">9. Statements</a>
<ul class="sectlevel2">
<li><a href="statements.html#_ecmascript-5-statements">9.1. ECMAScript 5 Statements</a>
<ul class="sectlevel3">
<li><a href="statements.html#_function-or-field-accessor-bodies">9.1.1. Function or Field Accessor Bodies</a></li>
<li><a href="statements.html#_variable-statement">9.1.2. Variable Statement</a></li>
<li><a href="statements.html#_if-statement">9.1.3. If Statement</a></li>
<li><a href="statements.html#_iteration-statements">9.1.4. Iteration Statements</a></li>
<li><a href="statements.html#_return-statement">9.1.5. Return Statement</a></li>
<li><a href="statements.html#_with-statement">9.1.6. With Statement</a></li>
<li><a href="statements.html#_switch-statement">9.1.7. Switch Statement</a></li>
<li><a href="statements.html#_throw-try-and-catch-statements">9.1.8. Throw, Try, and Catch Statements</a></li>
<li><a href="statements.html#_debugger-statement">9.1.9. Debugger Statement</a></li>
</ul>
</li>
<li><a href="statements.html#_ecmascript-6-statements">9.2. ECMAScript 6 Statements</a>
<ul class="sectlevel3">
<li><a href="statements.html#_let">9.2.1. Let</a></li>
<li><a href="statements.html#_const">9.2.2. Const</a></li>
<li><a href="statements.html#_for-of-statement">9.2.3. <code>for &#8230;&#8203; of</code> statement</a></li>
<li><a href="statements.html#_import-statement">9.2.4. Import Statement</a>
<ul class="sectlevel4">
<li><a href="statements.html#Dynamic_Imports">9.2.4.1. Dynamic Imports</a></li>
<li><a href="statements.html#_immutabilaty-of-imports">9.2.4.2. Immutabilaty of Imports</a></li>
</ul>
</li>
<li><a href="statements.html#_export-statement">9.2.5. Export Statement</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="annotations.html#_annotations">10. Annotations</a>
<ul class="sectlevel2">
<li><a href="annotations.html#_introduction-2">10.1. Introduction</a>
<ul class="sectlevel3">
<li><a href="annotations.html#_syntax-13">10.1.1. Syntax</a></li>
<li><a href="annotations.html#_properties-7">10.1.2. Properties</a></li>
<li><a href="annotations.html#_element-specific-annotations">10.1.3. Element-Specific Annotations</a></li>
<li><a href="annotations.html#_general-annotations">10.1.4. General Annotations</a>
<ul class="sectlevel4">
<li><a href="annotations.html#_idebug">10.1.4.1. IDEBUG</a></li>
</ul>
</li>
<li><a href="annotations.html#idebug-syntax">10.1.5. Syntax</a>
<ul class="sectlevel4">
<li><a href="annotations.html#_semantics-11">10.1.5.1. Semantics</a></li>
<li><a href="annotations.html#_suppress-warnings">10.1.5.2. Suppress Warnings</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="annotations.html#_declaration-of-annotations">10.2. Declaration of Annotations</a></li>
</ul>
</li>
<li><a href="#_extended-fetaures">11. Extended Fetaures</a>
<ul class="sectlevel2">
<li><a href="#_array-and-object-destructuring">11.1. Array and Object Destructuring</a>
<ul class="sectlevel3">
<li><a href="#_syntax-14">11.1.1. Syntax</a></li>
<li><a href="#_semantics-12">11.1.2. Semantics</a></li>
</ul>
</li>
<li><a href="#_dependency-injection">11.2. Dependency Injection</a>
<ul class="sectlevel3">
<li><a href="#_di-components-and-injectors">11.2.1. DI Components and Injectors</a>
<ul class="sectlevel4">
<li><a href="#_dicomponent-relations">11.2.1.1. DIComponent Relations</a></li>
</ul>
</li>
<li><a href="#_binders-and-bindings">11.2.2. Binders and Bindings</a></li>
<li><a href="#_injection-points">11.2.3. Injection Points</a>
<ul class="sectlevel4">
<li><a href="#_field-injection">11.2.3.1. Field Injection</a></li>
<li><a href="#_constructor-injection">11.2.3.2. Constructor Injection</a></li>
<li><a href="#_method-injection">11.2.3.3. Method Injection</a>
<ul class="sectlevel5">
<li><a href="#_provider">11.2.3.3.1. Provider</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_n4js-di-life-cycle-and-scopes">11.2.4. N4JS DI Life Cycle and Scopes</a>
<ul class="sectlevel4">
<li><a href="#_injection-cylces">11.2.4.1. Injection Cylces</a></li>
<li><a href="#_default-scope">11.2.4.2. Default Scope</a></li>
<li><a href="#_singleton-scope">11.2.4.3. Singleton Scope</a></li>
<li><a href="#_per-injection-chain-singleton">11.2.4.4. Per Injection Chain Singleton</a></li>
</ul>
</li>
<li><a href="#_validation-of-callsites-targeting-n4injector-methods">11.2.5. Validation of callsites targeting N4Injector methods</a></li>
<li><a href="#_n4js-di-annotations">11.2.6. N4JS DI Annotations</a>
<ul class="sectlevel4">
<li><a href="#_n4js-di-generateinjector">11.2.6.1. N4JS DI @GenerateInjector</a></li>
<li><a href="#_n4js-di-withparentinjector">11.2.6.2. N4JS DI @WithParentInjector</a></li>
<li><a href="#_n4js-di-usebinder">11.2.6.3. N4JS DI @UseBinder</a></li>
<li><a href="#_n4js-di-binder">11.2.6.4. N4JS DI @Binder</a></li>
<li><a href="#_n4js-di-bind">11.2.6.5. N4JS DI @Bind</a></li>
<li><a href="#_n4js-di-provides">11.2.6.6. N4JS DI @Provides</a></li>
<li><a href="#_n4js-di-inject">11.2.6.7. N4JS DI @Inject</a></li>
<li><a href="#_n4js-di-singleton">11.2.6.8. N4JS DI @Singleton</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_test-support">11.3. Test Support</a></li>
<li><a href="#_polyfill-definitions">11.4. Polyfill Definitions</a>
<ul class="sectlevel3">
<li><a href="#_runtime-polyfill-definitions">11.4.1. Runtime Polyfill Definitions</a></li>
<li><a href="#_static-polyfill-definitions">11.4.2. Static Polyfill Definitions</a></li>
<li><a href="#_transpiling-static-polyfilled-classes">11.4.3. Transpiling static polyfilled classes</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="components.html#_components">12. Components</a>
<ul class="sectlevel2">
<li><a href="components.html#_overview-2">12.1. Overview</a></li>
<li><a href="components.html#Component_Types">12.2. Component Types</a>
<ul class="sectlevel3">
<li><a href="components.html#_libraries">12.2.1. Libraries</a></li>
<li><a href="components.html#_runtime-environment-and-runtime-libraries">12.2.2. Runtime Environment and Runtime Libraries</a></li>
<li><a href="components.html#_tests">12.2.3. Tests</a></li>
<li><a href="components.html#_type-definitions">12.2.4. Type Definitions</a></li>
</ul>
</li>
<li><a href="components.html#package-json">12.3. Package.json File</a>
<ul class="sectlevel3">
<li><a href="components.html#_basic-properties">12.3.1. Basic Properties</a></li>
<li><a href="components.html#_n4js-properties">12.3.2. N4JS Properties</a></li>
<li><a href="components.html#_constraints">12.3.3. Constraints</a></li>
</ul>
</li>
<li><a href="components.html#_support-for-npm-scopes">12.4. Support for NPM Scopes</a></li>
<li><a href="components.html#sec:N4JS-Type-Definitions">12.5. N4JS Type Definitions</a>
<ul class="sectlevel3">
<li><a href="components.html#_specify-type-definition">12.5.1. Specify Type Definition</a></li>
<li><a href="components.html#_name-conventions">12.5.2. Name Conventions</a></li>
<li><a href="components.html#_version-conventions">12.5.3. Version Conventions</a>
<ul class="sectlevel4">
<li><a href="components.html#_define-a-new-type-definition-package">12.5.3.1. Define a New Type Definition Package</a></li>
<li><a href="components.html#_using-a-type-definition-package">12.5.3.2. Using a Type Definition Package</a></li>
<li><a href="components.html#_rational">12.5.3.3. Rational</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="components.html#_modules">12.6. Modules</a></li>
<li><a href="components.html#_api-and-implementation-component">12.7. API and Implementation Component</a>
<ul class="sectlevel3">
<li><a href="components.html#_execution-of-api-and-implementation-components">12.7.1. Execution of API and Implementation Components</a></li>
<li><a href="components.html#_api-and-implementation-with-di">12.7.2. API and Implementation With DI</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="plainjs.html#_plainjs">13. PlainJS</a>
<ul class="sectlevel2">
<li><a href="plainjs.html#_type-inference-and-validation-for-plain-js">13.1. Type Inference and Validation for Plain JS</a></li>
<li><a href="plainjs.html#_external-declarations">13.2. External Declarations</a>
<ul class="sectlevel3">
<li><a href="plainjs.html#_declaring-externals">13.2.1. Declaring externals</a></li>
<li><a href="plainjs.html#_instantiating-external-classes">13.2.2. Instantiating external classes</a></li>
<li><a href="plainjs.html#_implementation-of-external-declarations">13.2.3. Implementation of External Declarations</a></li>
<li><a href="plainjs.html#_example">13.2.4. Example</a></li>
</ul>
</li>
<li><a href="plainjs.html#_global-definitions">13.3. Global Definitions</a></li>
<li><a href="plainjs.html#_runtime-definitions">13.4. Runtime Definitions</a></li>
<li><a href="plainjs.html#_applying-polyfills">13.5. Applying Polyfills</a></li>
</ul>
</li>
<li><a href="jsdoc.html#_jsdoc-2">14. JSDoc</a>
<ul class="sectlevel2">
<li><a href="jsdoc.html#_general-n4jsdoc-features">14.1. General N4JSDoc Features</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_provided-inline-tags">14.1.1. Provided Inline Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#jsdoc_tag__code">14.1.1.1. @code</a></li>
<li><a href="jsdoc.html#jsdoc_tag__link">14.1.1.2. @link</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_n4jsdoc-for-user-projects">14.2. N4JSdoc for User Projects</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_standard-tags">14.2.1. Standard Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#_-author">14.2.1.1. @author</a></li>
<li><a href="jsdoc.html#jsdoc_tag_param">14.2.1.2. @param</a></li>
<li><a href="jsdoc.html#jsdoc_tag_return">14.2.1.3. @return</a></li>
</ul>
</li>
<li><a href="jsdoc.html#_test-related-tags">14.2.2. Test Related Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#jsdoc_tag__testee">14.2.2.1. @testee</a></li>
<li><a href="jsdoc.html#jsdoc_tag__testeeFromType">14.2.2.2. @testeeFromType</a></li>
<li><a href="jsdoc.html#_testeeType_and__testeeMember">14.2.2.3. @testeeType and @testeeMember</a></li>
<li><a href="jsdoc.html#jsdoc_tag_reqid_in_Tests">14.2.2.4. @reqid in Tests</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_n4jsdoc-for-api-and-implementation-projects">14.3. N4JSDoc for API and Implementation Projects</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#jsdoc_tag__apiNote">14.3.1. @apiNote</a></li>
<li><a href="jsdoc.html#API_Project_Tags">14.3.2. API Project Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#jsdoc_tag_apiState">14.3.2.1. @apiState</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="jsx.html#_jsx">15. JSX</a>
<ul class="sectlevel2">
<li><a href="jsx.html#_jsx-support">15.1. JSX Support</a></li>
<li><a href="jsx.html#_jsx-backend">15.2. JSX Backend</a></li>
</ul>
</li>
<li><a href="grammars.html#_grammars">16. Grammars</a>
<ul class="sectlevel2">
<li><a href="grammars.html#_type-expressions-grammar">16.1. Type Expressions Grammar</a></li>
<li><a href="grammars.html#_n4js-language-grammar">16.2. N4JS Language Grammar</a></li>
</ul>
</li>
<li><a href="jsobjects.html#_jsobjects">17. JSObjects</a>
<ul class="sectlevel2">
<li><a href="jsobjects.html#_object">17.1. Object</a></li>
<li><a href="jsobjects.html#_string">17.2. String</a></li>
<li><a href="jsobjects.html#_boolean">17.3. Boolean</a></li>
<li><a href="jsobjects.html#_number">17.4. Number</a>
<ul class="sectlevel3">
<li><a href="jsobjects.html#_static-attributes">17.4.1. Static Attributes</a></li>
</ul>
</li>
<li><a href="jsobjects.html#function">17.5. Function</a></li>
<li><a href="jsobjects.html#_error">17.6. Error</a></li>
<li><a href="jsobjects.html#_array">17.7. Array</a></li>
<li><a href="jsobjects.html#_date">17.8. Date</a></li>
<li><a href="jsobjects.html#_math">17.9. Math</a>
<ul class="sectlevel3">
<li><a href="jsobjects.html#static-attributes-1">17.9.1. Static Attributes</a></li>
</ul>
</li>
<li><a href="jsobjects.html#_regexp">17.10. RegExp</a></li>
<li><a href="jsobjects.html#_json">17.11. JSON</a></li>
</ul>
</li>
<li><a href="n4js_objects.html#_n4js-objects">18. N4JS Objects</a>
<ul class="sectlevel2">
<li><a href="n4js_objects.html#_reflection-model">18.1. Reflection Model</a></li>
<li><a href="n4js_objects.html#_error-types">18.2. Error Types</a>
<ul class="sectlevel3">
<li><a href="n4js_objects.html#_n4apinotimplemented">18.2.1. N4ApiNotImplemented</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_acronyms.html#_acronyms">Appendix A: Acronyms</a></li>
<li><a href="appendix_b_license.html#sec:License">Appendix B: License</a></li>
<li><a href="appendix_c_bibliography.html#_bibliography">Appendix C: Bibliography</a></li>
</ul>
</div>
</div>
<div id="content"><div class="sect1">
<h2 id="_extended-fetaures"><a class="anchor" href="#_extended-fetaures"></a><a class="link" href="#_extended-fetaures">11. Extended Fetaures</a></h2>
<div class="sectionbody">
<div class="sect2 language-n4js">
<h3 id="_array-and-object-destructuring"><a class="anchor" href="#_array-and-object-destructuring"></a><a class="link" href="#_array-and-object-destructuring">11.1. Array and Object Destructuring</a></h3>
<div class="paragraph">
<p>N4JS supports array and object destructuring as provided in ES6.
This is used to conveniently assign selected elements of an array or object to a number of newly-declared or pre-existing variables or to further destructure them by using nested
destructuring patterns <sup class="footnote">[<a id="_footnoteref_55" class="footnote" href="appendix_c_bibliography.html#_footnote_55" title="View footnote.">55</a>]</sup>.</p>
</div>
<div class="sect3">
<h4 id="_syntax-14"><a class="anchor" href="#_syntax-14"></a><a class="link" href="#_syntax-14">11.1.1. Syntax</a></h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ebnf" data-lang="ebnf">BindingPattern &lt;Yield&gt;:
ObjectBindingPattern&lt;Yield&gt;
| ArrayBindingPattern&lt;Yield&gt;
;
ObjectBindingPattern &lt;Yield&gt; returns BindingPattern:
{BindingPattern}
'{' (properties+=BindingProperty&lt;Yield,AllowType=false&gt; (',' properties+=BindingProperty&lt;Yield,AllowType=false&gt;)*)? '}'
;
ArrayBindingPattern &lt;Yield&gt; returns BindingPattern:
{BindingPattern}
'['
elements+=Elision* (
elements+=BindingRestElement&lt;Yield&gt;
(',' elements+=Elision* elements+=BindingRestElement&lt;Yield&gt;)*
(',' elements+=Elision*)?
)?
']'
;
BindingProperty &lt;Yield, AllowType&gt;:
=&gt;(LiteralBindingPropertyName&lt;Yield&gt; ':') value=BindingElement&lt;Yield&gt;
| value=SingleNameBinding&lt;Yield,AllowType&gt;
;
fragment LiteralBindingPropertyName &lt;Yield&gt;*:
declaredName=IdentifierName | declaredName=STRING | declaredName=NumericLiteralAsString
// this is added here due to special treatment for a known set of expressions
| '[' (declaredName=SymbolLiteralComputedName&lt;Yield&gt; | declaredName=STRING) ']'
;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_semantics-12"><a class="anchor" href="#_semantics-12"></a><a class="link" href="#_semantics-12">11.1.2. Semantics</a></h4>
<div class="paragraph">
<p>The following example declares four variables <code>a</code>, <code>b</code>, <code>x</code>, and <code>prop2</code>. Variables <code>a</code> and <code>x</code> will have the value <code>hello</code>, whereas <code>b</code> and <code>prop2</code> will have value 42.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var [a,b] = ["hello", 42];
var {prop1:x, prop2} = {prop1:"hello", prop2:42};</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the case of <code>prop2</code>, we do not provide a property name and variable name separately; this is useful in cases where the property name also makes for a
suitable variable name (called <code>single name binding</code>).</p>
</div>
<div class="paragraph">
<p>One of the most useful use cases of destructuring is in a <code>for..of</code> loop.
Take this example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var arr1 = [ ["hello",1,2,3], ["goodbye",4,5,6] ];
for(var [head,...tail] of arr1) {
console.log(head,'/',tail);
}
// will print:
// hello / [ 1, 2, 3 ]
// goodbye / [ 4, 5, 6 ]
var arr2 = [ {key:"hello", value:42}, {key:"goodbye", value:43} ];
for(var {key,value} of arr2) {
console.log(key,'/',value);
}
// will print:
// hello / 42
// goodbye / 43</code></pre>
</div>
</div>
<div class="paragraph">
<p>Array and object destructuring pattern can appear in many different places:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>In a variable declaration (not just in variable statements but also in other places where variable declarations are allowed, e.g. plain for loops; called <em>destructuring binding</em>; see <a href="statements.html#_variable-statement">Variable Statement</a>).</p>
</li>
<li>
<p>On the left-hand side of an assignment expression (the assignment expression is then called <em>destructuring assignment</em>; see <a href="expressions.html#_assignment-expression">Assignment Expression</a>).</p>
</li>
<li>
<p>In a <code>for..in</code> or <code>for..of</code> loop on the left side of the <code>in</code>/<code>of</code> (see <a href="statements.html#_for-of-statement"><code>for &#8230;&#8203; of</code> statement</a>).</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title=""></i>
</td>
<td class="content">
It can also be used in plain statements, but then we actually have one of the above two use cases.
</td>
</tr>
</table>
</div>
</li>
<li>
<p>With lists of formal parameters or function arguments (not supported yet).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For further details on array and object destructuring please refer to the ECMAScript 6 specification - [<a href="appendix_c_bibliography.html#ECMA15a">ECMA15a</a>].</p>
</div>
<div class="paragraph">
<p>Type annotations can only be added when a new variable name is introduced since the short version would be ambiguous with the long one.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var {x: someTypeOrNewVar} = ol</code></pre>
</div>
</div>
<div class="paragraph">
<p>could either mean that a new variable <code>someTypeOrNewVar</code> is declared and <code>ol.x</code> is assigned to it, or that a new variable <code>x</code> is declared with type <code>someTypeOrNewVar</code>.
The longer form would look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var {x: x: someType} = ol</code></pre>
</div>
</div>
<div class="paragraph">
<p>We can make this more readable:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var {propOfOl: newVar: typeOfNewVar} = ol</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="_dependency-injection"><a class="anchor" href="#_dependency-injection"></a><a class="link" href="#_dependency-injection">11.2. Dependency Injection</a></h3>
<div class="paragraph">
<p>This chapter describes <a href="appendix_a_acronyms.html#_acronyms">DI</a> mechanisms for N4JS.
This includes compiler, validation and language extensions that allow to achieve DI mechanisms built in into the N4JS language and IDE.</p>
</div>
<div class="paragraph">
<p>N4JS <a href="appendix_a_acronyms.html#_acronyms">DI</a> support specifies a means for obtaining objects in such a way as to maximize reusability, testability and maintainability,
especially compared to traditional approaches such as constructors, factories and service locators.
While this can be achieved manually (without tooling support) it is difficult for nontrivial applications.
The solutions that DI provides should empower N4JS users to achieve the above goals without the burden of maintaining so-called ’boilerplate’ code.</p>
</div>
<div id="fig-di-terms" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/diBasicTerms.png" alt="diBasicTerms">
</div>
<div class="title">Figure 8. DI Basic Terms</div>
</div>
<div class="paragraph">
<p><em>key: pass the dependency instead of letting the client create or find it</em></p>
</div>
<div class="paragraph">
<p>Core terms</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Service</strong> - A set of APIs describing the functionality of the service.</p>
</li>
<li>
<p><strong>Service Implementation</strong>s - One or more implementations of given service API.</p>
</li>
<li>
<p><strong>Client</strong> - Consumer of a given functionality, uses the given <strong>Service Implementation</strong>.</p>
</li>
<li>
<p><strong>Injector</strong> - Object providing <strong>Service Implementation</strong> of a specific <strong>Service</strong>, according to configuration.</p>
</li>
<li>
<p><strong>Binding</strong> - Part of configuration describing which interface implementing a subtype will be injected, when a given interface is requested.</p>
</li>
<li>
<p><strong>Provider</strong> - Factory used to create instances of a given <strong>Service Implementation</strong> or its sub-components, can be a method.</p>
</li>
<li>
<p><strong>Injection Point</strong> - Part of the user’s code that will have the given dependency injected. This is usually fields, method parameters, constructor parameters etc.</p>
</li>
<li>
<p><strong>DI configuration</strong> - This describes which elements of the user’s code are used in mechanisms and how they are wired.
It is derived from user code elements being marked with appropriate annotations, bindings and providers.</p>
</li>
<li>
<p><strong>di wiring</strong> - The code responsible for creating user objects.
These are injectors, type factories/providers, fields initiators etc.</p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="_di-components-and-injectors"><a class="anchor" href="#_di-components-and-injectors"></a><a class="link" href="#_di-components-and-injectors">11.2.1. DI Components and Injectors</a></h4>
<div class="paragraph">
<p>N4JS’ <a href="#_dependency-injection">Dependency Injection</a> systems is based on the notion of <a href="appendix_a_acronyms.html#_acronyms">DIC</a>.</p>
</div>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="di_component"></a><strong>Definition:</strong> <a href="#di_component">DI Component</a></p>
</div>
<div class="paragraph">
<p>A <a href="appendix_a_acronyms.html#_acronyms">DIC</a> is a N4Class annotated with <code>@GenerateInjector</code>.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>This annotation causes an <em>injector</em> to be created for (and associated to) the <a href="appendix_a_acronyms.html#_acronyms">DI</a>.
DIC can be composed; meaning that when requested to inject an instance of a type, a DIC’s injector can delegate this request to the injector of the containing DIC.
An injector always prioritizes its own configuration before delegating to the container’s injector.
For validation purposes, a child DI can be annotated with <code>@WithParent</code> to ensure that it is always used with a proper parent.</p>
</div>
<div class="paragraph">
<p><em>Injector</em> is the main object of DI mechanisms responsible for creating object graphs of the application.
At runtime, injectors are instances of <code>N4Injector</code>.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-138"></a><strong>Req. IDE-138:</strong> <a href="#Req-IDE-138">DI Component and Injector</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>The following constraints must hold for a class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> marked as DIC:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>A subclass <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> of <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> is a DIC as well and it must be marked with <code>GenerateInjector</code>.</p>
</li>
<li>
<p>If a parent <a href="#_dicomponent-relations">DIC</a> <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> is specified via <code>WithParent</code>, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> must be a DIC as well.</p>
</li>
<li>
<p>The injector associated to a DIC is of type <code>N4Injector</code>. It can be retrieved via <code>N4Injector.of(DIC)</code> in which <code>DIC</code> is the <code>DIC</code>.</p>
</li>
<li>
<p>Injectors associated to DIC a are DI-singletons (cf. <a href="#_singleton-scope">Singleton Scope</a>).
Two calls to <code>N4Injector.of(DIC)</code> are different (as different DIC are assumed).</p>
</li>
</ol>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-139"></a><strong>Req. IDE-139:</strong> <a href="#Req-IDE-139">Injection Phase</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>We call the (transitive) creation and setting of values by an injector <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>I</mi></math> caused by the creation of an root object <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>R</mi></math> the <em>injection phase</em>.
If an instance <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> is newly created by the injector <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>I</mi></math> (regardless of the injection point being used), the injection is transitively applied on <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math>.
The following constraints have to hold:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Root objects are created by one of the following mechanisms:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Any class or interface can be created as root objects via an injector associated to a DIC:<br>
<code>var x: X = N4Injector.of(DIC).create(X);</code><br>
in which <code>DIC</code> is a DIC.</p>
<div class="paragraph">
<p>Of course, an appropriate binding must exist. <sup class="footnote">[<a id="_footnoteref_56" class="footnote" href="appendix_c_bibliography.html#_footnote_56" title="View footnote.">56</a>]</sup></p>
</div>
</li>
<li>
<p>If a type has the injector being injected, e.g. via field injection <code>@Inject injector: N4Injector;</code>, then this injector can be used anytime in the control flow to create
a new root object similar as above (using <code>create</code> method).</p>
</li>
<li>
<p>If a provider has been injected (i.e. an instance of <code>{N4Provider}</code>), then its <code>get()</code> method can be used to create a root object causing a new injection phase to take place.</p>
</li>
</ol>
</div>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> is marked as injection point, all its arguments are set by the injector.
This is also true for an inherited constructor marked as an injection point.
See <a href="#Req-IDE-143">[Req-IDE-143]</a> . For all arguments the injection phase constraints have to hold as well.</p>
</li>
<li>
<p>All fields of <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math>, including <em>inherited</em> once, marked as injection points are set by the injector.
For all fields the injection phase constraints have to hold as well.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The injector may use a provider method (of a binder) to create nested instances.</p>
</div>
<div class="paragraph">
<p>The injector is configured with <em>Binders</em> and it tracks <em>Bindings</em> between types (<a href="#_binders-and-bindings">Binders and Bindings</a>).
An N4JS developer normally would not interact with this object directly except when defining an entry-point to his application.
<em>Injector</em>s are configured with <em>Binder</em>s which contain explicit <em>Binding</em>s defined by an N4JS developer.
A set of these combined with <em>implicit bindings</em> creates the <em>di configuration</em> used by a given injector.
To configure given <em>Injector</em>s with given <em>Binder</em>(s) use <code>@UseBinder</code> annotation.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_dicomponent-relations"><a class="anchor" href="#_dicomponent-relations"></a><a class="link" href="#_dicomponent-relations">11.2.1.1. DIComponent Relations</a></h5>
<div class="paragraph">
<p>A Parent-Child relation can be established between two DIComponents.
Child DIComponents use the parent bindings but can also be configured with their own bindings or <em>change</em> targets used by a parent.
The final circumstance is local to the child and is referred to as <em>rebinding</em>.
For more information about bindings see <a href="#_binders-and-bindings">Binders and Bindings</a>.
A Child-Parent relation is expressed by the <code>@WithParentInjector</code> annotation attached to a given DIComponent.
When this relation is defined between DIComponents, the user needs to take care to preserve the proper relation between injectors.
In other words, the user must provide an instance of the parent injector (the injector of the DIComponent passes as a parameter to <code>@WithParentInjector</code>) when creating the child injector
(injector of the DIComponent annotated with <code>@WithParentInjector</code>).</p>
</div>
<div class="exampleblock">
<div class="title">Example 99. Simple DIComponents Relation</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@GenerateInjector
class ParentDIComponent{}
@GenerateInjector
@WithParentInjector(ParentDIComponent)
class ChildDIComponent{}
var parentInejctor = N4Inejctor.of(ParentDiCompoennt);
var childInjector = N4Inejctor.of(ChildDIComponent, parentInjector);</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>With complex DIComponent structures, injector instances can be created with a directly-declared parent and also with any of its children.
This is due to the fact that any child can rebind types, add new bindings, but not remove them.
Any child is, therefore, <em>compatible</em> with its parents.</p>
</div>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="compatible_dicomponent"></a><strong>Definition:</strong> <a href="#compatible_dicomponent">Compatible DIComponent</a></p>
</div>
<div class="paragraph">
<p>A given DIComponent is compatible with another DIComponent if it has bindings for all keys in other component bindings.</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mo></mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>1</mn><mo>,</mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>2</mn><mi>:</mi><mi>D</mi><mi>I</mi><mi>C</mi><mn>1.</mn><mover accent="true"><mrow><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mi>i</mi><mi>n</mi><mi>g</mi></mrow><mo>¯</mo></mover><mo>.</mo><mover accent="true"><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mo>¯</mo></mover><mo></mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>2.</mn><mover accent="true"><mrow><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mi>i</mi><mi>n</mi><mi>g</mi></mrow><mo>¯</mo></mover><mo>.</mo><mover accent="true"><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mo>¯</mo></mover><mo></mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>2</mn><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>D</mi><mi>I</mi><mi>C</mi><mn>1</mn></math>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title=""></i>
</td>
<td class="content">
Although subtype notation <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/></math> is used here it does <strong>not</strong> imply actual subtype relations.
It was used in this instance for of lack of formal notations for DI concepts and because this is similar to the Liskov Substitution principle.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>A complex Child-Parent relation between components is depicted in <a href="#fig-complex-dicomponents-relations">Complex DIComponents Relations</a> and <a href="#ex:complex-dicomponents-relations">Complex DIComponents Relations</a> below.</p>
</div>
<div id="fig-complex-dicomponents-relations" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/diagDICParentChild.svg" alt="diagDICParentChild">
</div>
<div class="title">Figure 9. Complex DIComponents Relations</div>
</div>
</div>
</div>
<div id="ex:complex-dicomponents-relations" class="exampleblock">
<div class="title">Example 100. Complex DIComponents Relations</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@GenerateInjector class A {}
@GenerateInjector @WithParentInjector(A) class B {}
@GenerateInjector @WithParentInjector(B) class C {}
@GenerateInjector @WithParentInjector(C) class D {}
@GenerateInjector @WithParentInjector(A) class B2 {}
@GenerateInjector @WithParentInjector(B2) class C2 {}
@GenerateInjector @WithParentInjector(C2) class D2 {}
@GenerateInjector @WithParentInjector(A) class X {}
@GenerateInjector @WithParentInjector(C) class Y {}
// creating injectors
var injectorA = N4Injector.of(A);
//following throws DIConfigurationError, expected parent is not provided
//var injectorB = N4Injector.of(B);
//correct declarations
var injectorB = N4Injector.of(B, injectorA);
var injectorC = N4Injector.of(C, injectorB);
var injectorD = N4Injector.of(D, injectorC);
var injectorB2 = N4Injector.of(B2, injectorA);
var injectorC2 = N4Injector.of(C2, injectorB2);
var injectorD2 = N4Injector.of(D2, injectorC2);
//Any injector of {A,B,C,D,b2,C2,D2} s valid parent for injector of X, e.g. D or D2
N4Injector.of(X, injectorD);//is ok as compatible parent is provided
N4Injector.of(X, injectorD2);//is ok as compatible parent is provided
N4Injector.of(Y, injectorC);//is ok as direct parent is provided
N4Injector.of(Y, injectorD);//is ok as compatible parent is provided
N4Injector.of(Y, injectorB2);//throws DIConfigurationError, incompatible parent is provided
N4Injector.of(Y, injectorC2);//throws DIConfigurationError, incompatible parent is provided
N4Injector.of(Y, injectorD2);//throws DIConfigurationError, incompatible parent is provided</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_binders-and-bindings"><a class="anchor" href="#_binders-and-bindings"></a><a class="link" href="#_binders-and-bindings">11.2.2. Binders and Bindings</a></h4>
<div class="paragraph">
<p><em>Binder</em> allows an N4JS developer to (explicitly) define a set of <em>Binding</em>s that will be used by an <em>Injector</em> configured with a given <em>Binder</em>.
There are two ways for <em>Binder</em> to define <em>Binding</em>s: <code>@Bind</code> (<a href="#_n4js-di-bind">N4JS DI @Bind</a>) annotations and a method annotated with <code>@Provides</code>.</p>
</div>
<div class="paragraph">
<p><em>Binder</em> is declared by annotating a class with the <code>@Binder</code> annotation.</p>
</div>
<div class="paragraph">
<p>A <em>Binding</em> is part of a configuration that defines which instance of
what type should be injected into an <em>injection point</em> (<a href="#_injection-points">Injection Points</a>) with an expected type.</p>
</div>
<div class="paragraph">
<p><em>Provider Method</em> is essentially a <em>factory method</em> that is used to create an instance of a type.
N4JS allows a developer to declare those methods (see <a href="#_n4js-di-provides">N4JS DI @Provides</a>) which gives them a hook in instance creation process.
Those methods will be used when creating instances by the <em>Injector</em> configured with the corresponding <em>Binder</em>.
A provider method is a special kind of binding (<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math>) in which the return type of the method is the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math>.
The <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> type is unknown at compile time (although it may be inferred by examining the return statements of the provide method).</p>
</div>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="binding"></a><strong>Definition:</strong> <a href="#binding">Binding</a></p>
</div>
<div class="paragraph">
<p>A <em>binding</em> is a pair <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></mrow></mfenced></math>.
It defines that for a dependency with a given key which usually is the expected type at the injection point.
An instance of type <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> is injected.</p>
</div>
<div class="paragraph">
<p>A <em>binding</em> is called <em>explicit</em> if it is declared in the code, i.e. via <code>@Bind</code>
annotation or <code>@Provides</code> annotation).</p>
</div>
<div class="paragraph">
<p>A <em>binding</em> is called <em>implicit</em> if it is not declared.
An implicit binding can only be used if the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> is a class and derived from the type at the injection point, i.e. the type of the field or parameter to be injected.
In that case, the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> equals the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math>.</p>
</div>
<div class="paragraph">
<p>A provider method <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi></math> (in the binder) defines a binding</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mfenced close=")" open="("><mrow><mi>M</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi></mrow><mi>X</mi></mfenced></math>
</div>
</div>
<div class="paragraph">
<p>(in which <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>X</mi></math> is an existential type with <math xmlns="http://www.w3.org/1998/Math/MathML"><mo></mo><mi>X</mi><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi></math>).</p>
</div>
<div class="paragraph">
<p>For simplification, we define:</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mi>k</mi><mi>e</mi><mi>y</mi><mo>*</mo><mo>=</mo><mfenced close="" open="{"><mtable><mtr><mtd><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>if target is provider method</mtext></mstyle></mtd></mtr><mtr><mtd><mi>k</mi><mi>e</mi><mi>y</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>otherwise (key is a type reference)</mtext></mstyle></mtd></mtr></mtable></mfenced></mtd></mtr></mtable></math>
</div>
</div>
<div class="paragraph">
<p>and</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>*</mo><mo>=</mo><mfenced close="" open="{"><mtable><mtr><mtd><mi>X</mi><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>if target is provider method</mtext></mstyle></mtd></mtr><mtr><mtd><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>otherwise (target is a type reference)</mtext></mstyle></mtd></mtr></mtable></mfenced></mtd></mtr></mtable></math>
</div>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-140"></a><strong>Req. IDE-140:</strong> <a href="#Req-IDE-140">Bindings</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>For a given binding <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></mrow></mfenced></math>, the following constraints must hold: <sup class="footnote">[<a id="_footnoteref_57" class="footnote" href="appendix_c_bibliography.html#_footnote_57" title="View footnote.">57</a>]</sup></p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> must be either a class or an interface.</p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> must either be a class or a provider method.</p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi></math> is implicit, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> must be a class.
If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> references a type <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>T</mi></math>, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>=</mo><mi>T</mi></math> – even if <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> is a use-site structural type.</p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> and <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>*</mo></math> can be nominal, structural or field-structural types, either definition-site or use-site.
The injector and binder needs to take the different structural reference into account at runtime!</p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>*</mo><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>k</mi><mi>e</mi><mi>y</mi></math> must hold</p>
</li>
<li>
<p>If during injection phase no binding for a given key is found, an <code>DIUnsatisfiedBindingError</code> is thrown.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-141"></a><strong>Req. IDE-141:</strong> <a href="#Req-IDE-141">Transitive Bindings</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>If an injector contains two given bindings <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>b</mi><mn>1</mn></msub><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>1</mn></msub></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><msub><mi>t</mi><mn>1</mn></msub></mrow></mfenced></math> and
<math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>b</mi><mn>2</mn></msub><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>2</mn></msub></mrow><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>1</mn></msub></mrow></mfenced></math>, an effective binding
<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>2</mn></msub></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><msub><mi>t</mi><mn>1</mn></msub></mrow></mfenced></math> is derived (replacing
<math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>b</mi><mn>1</mn></msub></math>).</p>
</div>
<div class="paragraph">
<p>N4JS <a href="appendix_a_acronyms.html#_acronyms">DI</a> mechanisms don’t allow for injection of primitives or built-in types.
Only user-defined N4Types can be used. In cases where a user needs to inject a primitive or a built-in type, the developer must wrap it into its own
class <sup class="footnote">[<a id="_footnoteref_58" class="footnote" href="appendix_c_bibliography.html#_footnote_58" title="View footnote.">58</a>]</sup>.
This is to say that none of the following metatypes can be bound: primitive types, enumerations, functions, object types, union- or intersection types. It is possible to (implicitly) bind to built-in classes.</p>
</div>
<div class="paragraph">
<p>While direct binding overriding or rebinding is not allowed, <em>Injector</em> can be configured in a way where one type can be separately bound to different types with implicit binding,
<em>explicit binding</em> and in bindings of the child injectors.
<em>Binding precedence</em> is a mechanism of <em>Injector</em> selecting a binding use for a type.
It operates in the following order:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Try to use explicit binding, if this is not available:</p>
</li>
<li>
<p>Try to delegate to parent injectors (order of lookup is not guaranteed, first found is selected). If this is not available then:</p>
</li>
<li>
<p>Try to use use implicit binding, which is simply to attempt to create the instance.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>If no binding for a requested type is available an error will be thrown.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_injection-points"><a class="anchor" href="#_injection-points"></a><a class="link" href="#_injection-points">11.2.3. Injection Points</a></h4>
<div class="paragraph">
<p>By <em>injection point</em> we mean a place in the source code which, at runtime, will be expected to hold a reference to a particular type instance.</p>
</div>
<div class="sect4">
<h5 id="_field-injection"><a class="anchor" href="#_field-injection"></a><a class="link" href="#_field-injection">11.2.3.1. Field Injection</a></h5>
<div class="paragraph">
<p>In its simplest form, this is a class field annotated with <code>@Inject</code> annotation.
At runtime, an instance of the containing class will be expected to hold reference to an instance of the field declared type.
Usually that case
is called <em>Field Injection</em>.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-142"></a><strong>Req. IDE-142:</strong> <a href="#Req-IDE-142">Field Injection</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>The injector will inject the
following fields:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>All directly contained fields annotated with <code>@Inject</code>.</p>
</li>
<li>
<p>All inherited fields annotated with <code>@Inject</code>.</p>
</li>
<li>
<p>The injected fields will be created by the injector and their fields will be injected as well.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 101. Simple Field Injection</div>
<div class="content">
<div class="paragraph">
<p><a href="#ex:field-injection">Simple Field Injection</a> demonstrates simple field injection using default bindings.
Note that all inherited fields (i.e. <code>A.xInA</code>) are injected and also fields in injected fields (i.e. <code>x.y</code>)</p>
</div>
<div id="ex:field-injection" class="listingblock">
<div class="title">Simple Field Injection</div>
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class X {
@Inject y: Y;
}
class Y {}
class A {
@Inject xInA: X;
}
class B extends A {
@Inject xInB: X;
}
@GenerateInjector
export public class DIC {
@Inject a: B;
}
var dic = N4Injector.of(DIC).create(DIC);
console.log(dic); // --&gt; DIC
console.log(dic.a); // --&gt; B
console.log(dic.a.xInA); // --&gt; X
console.log(dic.a.xInA.y); // --&gt; Y
console.log(dic.a.xInB); // --&gt; X
console.log(dic.a.xInB.y); // --&gt; Y</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_constructor-injection"><a class="anchor" href="#_constructor-injection"></a><a class="link" href="#_constructor-injection">11.2.3.2. Constructor Injection</a></h5>
<div class="paragraph">
<p>Parameters of the constructor can also be injected, in which case this is usually referred to as <em>Constructor Inejction</em>.
This is similar to <em>Method Injection</em> and while constructor injection is supported in N4JS, method injection is not (see remarks below).</p>
</div>
<div class="paragraph">
<p>When a constructor is annotated with <code>@Inject</code> annotation, all user-defined, non-generic types given as the parameters will be injected into the instance’s constructor created by the dependency injection framework.
Currently, optional constructor parameters are always initialized and created by the framework, therefore, they are ensured to be available at the constructor invocation time.
Unlike optional parameters, variadic parameters cannot be injected into a type’s constructor.
In case of annotating a constructor with <code>@Inject</code> that has variadic parameters, a validation error will be reported.
When a class’s constructor is annotated with <code>@Inject</code> annotation, it is highly recommended to annotate all explicitly-defined constructors at the subclass level.
If this is not done, the injection chain can break and runtime errors might occur due to undefined constructor parameters.
In the case of a possible broken injection chain due to missing <code>@Inject</code> annotations for any subclasses, a validation warning will
be reported.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-143"></a><strong>Req. IDE-143:</strong> <a href="#Req-IDE-143">Constructor Injection</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>If a class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> has a constructor marked as injection point, the
following applies:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> is subclassed by <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math>, and if <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> has no explicit constructor, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> inherits the constructor from <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> and it will be an injection point handled by the injector during injection phase.</p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> provides its own injector, <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> is no longer recognized by the injector during the injection phase.
There will be a warning generated in <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> to mark it as injection point as well in order to prevent inconsistent injection behavior.
Still, <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> must be called in <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> similarly to other overridden constructors.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_method-injection"><a class="anchor" href="#_method-injection"></a><a class="link" href="#_method-injection">11.2.3.3. Method Injection</a></h5>
<div class="paragraph">
<p>Other kinds of injector points are method parameters where (usually) all method parameters are injected when the method is called.
In a way, constructor injection is a special case of the method itself.</p>
</div>
<div class="sect5">
<h6 id="_provider"><a class="anchor" href="#_provider"></a><a class="link" href="#_provider">11.2.3.3.1. Provider</a></h6>
<div class="paragraph">
<p><em>Provider</em> is essentially a <em>factory</em> for a given type.
By injecting an <code>N4Provider</code> into any injection point, one can acquire new instances of a given type provided by the injected provider.
The providers prove useful when one has to solve re-injection issues since the depended type can be wired and injected via the provider rather than the dependency itself and can therefore obtain
new instances from it if required.
Provider can be also used as a means of delaying the instantiation time of a given type.</p>
</div>
<div class="paragraph">
<p><code>N4Provider</code> is a public generic built-in interface that is used to support the re-injection.
The generic type represents the dependent type that has to be obtained.
The <code>N4Provider</code> interface has one single public method: <code>public T get()</code> which should be invoked from the client code when a new instance of the dependent type is required.
Unlike any other unbound interfaces, the <code>N4Provider</code> can be injected without any explicit binding.</p>
</div>
<div class="paragraph">
<p>The following snippet demonstrates the usage of <code>N4Provider</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class SomeService { }
@Singleton
class SomeSingletonService { }
class SomeClass {
@Inject serviceProvider: N4Provider&lt;SomeService&gt;;
@Inject singletonServiceProvider: N4Provider&lt;SomeSingletonService&gt;;
void foo() {
console.log(serviceProvider.get() ===
serviceProvider.get()); //false
console.log(singletonServiceProvider.get() ===
singletonServiceProvider.get()); //true
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>It is important to note that the <code>N4Provider</code> interface can be extended by any user-defined interfaces and/or can be implemented by any user-defined classes.
For those user-defined providers, consider all binding-related rules; the extended interface, for example, must be explicitly bound via a binder to be injected.
The binding can be omitted only for the built-in <code>N4Provider</code>s.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_n4js-di-life-cycle-and-scopes"><a class="anchor" href="#_n4js-di-life-cycle-and-scopes"></a><a class="link" href="#_n4js-di-life-cycle-and-scopes">11.2.4. N4JS DI Life Cycle and Scopes</a></h4>
<div class="paragraph">
<p><a href="appendix_a_acronyms.html#_acronyms">DI</a> Life Cycle defines when a new instance is created by the injector as its destruction is handled by JavaScript.
The creation depends on the scope of the type.
Aside from the scopes, note that it is also possible to implement custom scopes and life cycle management via <code>N4JSProvider</code> and <code>Binder@Provides</code> methods.</p>
</div>
<div class="sect4">
<h5 id="_injection-cylces"><a class="anchor" href="#_injection-cylces"></a><a class="link" href="#_injection-cylces">11.2.4.1. Injection Cylces</a></h5>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="injection_cycle"></a><strong>Definition:</strong> <a href="#injection_cycle">Injection Cycle</a></p>
</div>
<div class="paragraph">
<p>We define an injection graph <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>G</mi><mfenced close=")" open="("><mi>V</mi><mi>E</mi></mfenced></math> as a directed graph as follows: <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>V</mi></math> (the vertices) is the set types of which instances are created during the injection phase and which use .
<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>E</mi></math> (the edges) is a set of directed and labeled edges <math xmlns="http://www.w3.org/1998/Math/MathML"><mfenced close=")" open="("><msub><mi>v</mi><mn>1</mn></msub><msub><mi>v</mi><mn>2</mn></msub><mrow><mi>l</mi><mi>a</mi><mi>b</mi><mi>e</mi><mi>l</mi></mrow></mfenced></math>, where label indicates the injection point:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mfenced close=")" open="("><msub><mi>T</mi><mi>o</mi></msub><msub><mi>T</mi><mi>f</mi></msub><mrow><mi>"</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>l</mi><mi>d</mi><mi>"</mi></mrow></mfenced></math>, if <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>f</mi></msub></math> is the actualy type of an an injected field of an instance of type <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>o</mi></msub></math></p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mfenced close=")" open="("><msub><mi>T</mi><mi>c</mi></msub><msub><mi>T</mi><mi>p</mi></msub><mrow><mi>"</mi><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi><mi>"</mi></mrow></mfenced></math>, if <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>p</mi></msub></math> is the type of a parameter used in a constructor injection of type <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>c</mi></msub></math></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>One cycle in this graph is an injection cycle.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>When injecting instances into an object, cycles have to be detected and handled independently from the scope.
If this is not done, the following examples would result in an infinite loop causing the entire script to freeze until the engine reports an error:</p>
</div>
<table class="tableblock frame-none grid-rows spread">
<colgroup>
<col style="width: 57.1428%;">
<col style="width: 42.8572%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-bottom"><div><div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class A { @Inject b: B; }
class B { @Inject a: A; }</code></pre>
</div>
</div></div></td>
<td class="tableblock halign-center valign-top"><div><div id="fig-field-cycle" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/injectionGraph_cycleField.svg" alt="injectionGraph cycleField">
</div>
<div class="title">Figure 10. Field Cycle</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-bottom"><div><div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class C { @Inject constructor(d: D) {} }
class D { @Inject c: C; }</code></pre>
</div>
</div></div></td>
<td class="tableblock halign-center valign-top"><div><div id="fig-ctor-field" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/injectionGraph_cycleCtorField.svg" alt="injectionGraph cycleCtorField">
</div>
<div class="title">Figure 10. Ctor Field Cycle</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-bottom"><div><div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class E { @Inject constructor(f: F) {} }
class F { @Inject constructor(e: E) {} }</code></pre>
</div>
</div></div></td>
<td class="tableblock halign-center valign-top"><div><div id="fig-ctor-cycle" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/injectionGraph_cycleCtor.svg" alt="injectionGraph cycleCtor">
</div>
<div class="title">Figure 10. Ctor Cycle</div>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The injector needs to detect these cycles and resolve them.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-144"></a><strong>Req. IDE-144:</strong> <a href="#Req-IDE-144">Resolution of Injection Cycles</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>A cycle <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>c</mi><mo></mo><mi>G</mi></math>, with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>G</mi></math> being an injection graph, is resolved as follows:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>c</mi></math> contains no edge with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>l</mi><mi>a</mi><mi>b</mi><mi>e</mi><mi>l</mi><mo>=</mo><mi>"</mi><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi><mi>"</mi></math>, the cycle is resolved using the algorithm described below.</p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>c</mi></math> contains at least one edge with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>l</mi><mi>a</mi><mi>b</mi><mi>e</mi><mi>l</mi><mo>=</mo><mi>"</mi><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi><mi>"</mi></math>, a runtime exception is thrown.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="paragraph">
<p>Cycles stemming from field injection are resolved by halting the creation of new instances of types which have been already created by a containing instance.
The previously-created instance is then reused.
This makes injecting the instance of a (transitive) container less complicated and without the need to pass the container instance down the entire chain.
The following pseudo code describes the algorithm to create new instances which are injected into a newly created object:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">function injectDependencies(object) {
doInjectionWithCylceAwareness(object, {(typeof object -&gt; object)})
}
function doInjectionWithCylceAwareness(object, createdInstancesPerType) {
forall v $\in$ injectedVars of object {
var type = retrieveBoundType(v)
var instance = createdInstancesPerType.get(type)
if (not exists instance) {
instance = createInstance(type, createdInstancesPerType)
doInjectionWithCylceAwareness(instance,
createdInstancesPerType $\cap$ {(type-&gt;instance)})
}
v.value = instance;
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The actual instance is created in line 10 via <code>createInstance</code>.
This function then takes scopes into account.
The <code>createdInstancesPerType</code> map is passed to that function in order to enable cycle detection for constructor injection.
The following scopes are supported by the N4JS DI, other scopes, cf. <a href="https://jersey.java.net/documentation/latest/ioc.html">Jersey custom scopes</a> and <a href="https://github.com/google/guice/wiki/CustomScopes">Guice custom scopes</a>, may be added in the future.</p>
</div>
<div class="paragraph">
<p>This algorithm is not working for constructor injection because it is possible to already access all fields of the arguments passed to the constructor.
In the algorithm, however, the instances may not be completely initialized.</p>
</div>
</div>
<div class="sect4">
<h5 id="_default-scope"><a class="anchor" href="#_default-scope"></a><a class="link" href="#_default-scope">11.2.4.2. Default Scope</a></h5>
<div class="paragraph">
<p>The default scope always creates a new instance.</p>
</div>
</div>
<div class="sect4">
<h5 id="_singleton-scope"><a class="anchor" href="#_singleton-scope"></a><a class="link" href="#_singleton-scope">11.2.4.3. Singleton Scope</a></h5>
<div class="paragraph">
<p>The singleton scope (per injector) creates one instance (of the type with <code>@Singleton</code> scope) per injector, which is then shared between clients.</p>
</div>
<div class="paragraph">
<p>The injector will preserve a single instance of the type of <code>S</code> and will provide it to all injection points where type of <code>S</code> is used.
Assuming nested injectors without any declared binding where the second parameter is <code>S</code>, the same preserved singleton instance will be available for all nested injectors at all injection points as well.</p>
</div>
<div class="paragraph">
<p>The singleton preservation behavior changes when explicit bindings are declared for type <code>S</code> on the nested injector level.
Let&#8217;s assume that the type <code>S</code> exists and the type is annotated with <code>@Singleton</code>.
Furthermore, there is a declared binding where the binding&#8217;s second argument is <code>S</code>.
In that case, unlike in other dependency injection frameworks, nested injectors may preserve a singleton for itself and all descendant injectors with <code>@Bind</code> annotation.
In this case, the preserved singleton at the child injector level will be a different instance than the one at the parent injectors.</p>
</div>
<div class="paragraph">
<p>The tables below depict the expected runtime behavior of singletons used at different injector levels.
Assume the following are injectors: <code>C</code>, <code>D</code>, <code>E</code>, <code>F</code> and <code>G</code>. Injector <code>C</code> is the top most injector and its nesting injector <code>D</code>, hence injector <code>C</code> is the parent of the injector <code>D</code>.
Injector <code>D</code> is nesting <code>E</code> and so on.
The most nested injector is <code>G</code>. Let&#8217;s assume <code>J</code> is an interface, class <code>U</code> implements interface <code>J</code> and class <code>V</code> extends class <code>U</code>.
Finally assume both <code>U</code> and <code>V</code> are annotated with <code>@Singleton</code> at definition-site.</p>
</div>
<div class="paragraph">
<p><a href="#tab:diNoBindings">DI No Bindings</a> depicts the singleton preservation for nested injectors without any bindings.
All injectors use the same instance from a type.
Type <code>J</code> is not available at all since it is not bound to any concrete implementation:</p>
</div>
<table id="tab:diNoBindings" class="tableblock frame-all grid-all spread">
<caption class="title">Table 12. DI No Bindings</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Binding</p></th>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (<math xmlns="http://www.w3.org/1998/Math/MathML"><mo>&gt;</mo></math>)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><a href="#tab:diTransitiveBindings">DI Transitive Bindings</a> is configured by explicit bindings. At the root injector level, type <code>J</code> is bound to type <code>U</code>.
Since the second argument of the binding is declared as a singleton at the definition-site,
this explicit binding implicitly ensures that the injector and all of its descendants preserve a singleton of the bound type <code>U</code>.
At injector level <code>C</code>, <code>D</code> and <code>E</code>, the same instance is used for type <code>J</code> which is type <code>U</code> at runtime.
At injector level <code>E</code> there is an additional binding from type <code>U</code> to type <code>V</code> that overrules the binding declared at the root injector level.
With this binding, each places where <code>J</code> is declared, type <code>U</code> is used at runtime.</p>
</div>
<div class="paragraph">
<p>Furthermore, since <code>V</code> is declared as a singleton, both injector <code>F</code> and <code>G</code> are using a shared singleton instance of type <code>V</code>.
Finally, for type <code>V</code>, injector <code>C</code>, <code>D</code> and <code>E</code> should use a separate instance of <code>V</code> other than injector level <code>F</code> and <code>G</code> because <code>V</code> is preserved at injector level <code>F</code> with the <code>U</code> <math xmlns="http://www.w3.org/1998/Math/MathML"><mo></mo></math> <code>V</code> binding.</p>
</div>
<table id="tab:diTransitiveBindings" class="tableblock frame-all grid-all spread">
<caption class="title">Table 13. DI Transitive Bindings</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Binding</th>
<th class="tableblock halign-center valign-top">J &#8594; U</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">U &#8594; V</th>
<th class="tableblock halign-center valign-top"></th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (&gt;)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><a href="#tab:diReBinding">DI Re - Binding</a> depicts the singleton behaviour but unlike the above
table, the bindings are declared for the interface <code>J</code>.</p>
</div>
<table id="tab:diReBinding" class="tableblock frame-all grid-all spread">
<caption class="title">Table 14. DI Re - Binding</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Binding</th>
<th class="tableblock halign-center valign-top">J &#8594; U</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">J &#8594; V</th>
<th class="tableblock halign-center valign-top"></th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (<math xmlns="http://www.w3.org/1998/Math/MathML"><mo>&gt;</mo></math>)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><a href="#tab:diChildBinding">DI Child Binding</a> describes the singleton behavior when both bindings are configured at child injector levels but not the root injector level.</p>
</div>
<table id="tab:diChildBinding" class="tableblock frame-all grid-all spread">
<caption class="title">Table 15. DI Child Binding</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Binding</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">U <math xmlns="http://www.w3.org/1998/Math/MathML"><mo></mo></math> V</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">J <math xmlns="http://www.w3.org/1998/Math/MathML"><mo></mo></math> U</th>
<th class="tableblock halign-center valign-top"></th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (<math xmlns="http://www.w3.org/1998/Math/MathML"><mo>&gt;</mo></math>)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="_per-injection-chain-singleton"><a class="anchor" href="#_per-injection-chain-singleton"></a><a class="link" href="#_per-injection-chain-singleton">11.2.4.4. Per Injection Chain Singleton</a></h5>
<div class="paragraph">
<p>The per injection chain singleton is ’between’ the default and singleton scope.
It can be used in order to explicitly describe the situation which happens when a simple cycle is resolved automatically.
It has more effects that lead to a more deterministic behavior.</p>
</div>
<div class="paragraph">
<p>Assume a provider declared as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var pb: Provider&lt;B&gt;;</code></pre>
</div>
</div>
<div class="paragraph">
<p>to be available:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@PerInjectionSingleton
class A { }
class B { @Inject a: A; @Inject a1: A;}
b1=pb.get();
b2=pb.get();
b1.a != b2.a
b1.a == b1.a1
b2.a == b2.a1</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@Singleton
class A { }
class B { @Inject a: A; @Inject a1: A;}
b1=pb.get();
b2=pb.get();
b1.a == b2.a
b1.a == b1.a1
b2.a == b2.a1</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">// no annotation
class A { }
class B { @Inject a A; @Inject a1: A;}
b1=pb.get();
b2=pb.get();
b1.a != b2.a
b1.a != b1.a1
b2.a != b2.a1</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_validation-of-callsites-targeting-n4injector-methods"><a class="anchor" href="#_validation-of-callsites-targeting-n4injector-methods"></a><a class="link" href="#_validation-of-callsites-targeting-n4injector-methods">11.2.5. Validation of callsites targeting N4Injector methods</a></h4>
<div class="paragraph">
<p>Terminology for this section:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>a value is <strong>injectable</strong> if it</p>
<div class="ulist">
<ul>
<li>
<p>either conforms to a user-defined class or interface (a non-parameterized one, that is),</p>
</li>
<li>
<p>or conforms to Provider-of-T where T is injectable itself.</p>
</li>
</ul>
</div>
</li>
<li>
<p>a classifier declaring injected members is said to <strong>require injection</strong></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To better understand the validations in effect for callsites targeting</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">N4Injector.of(ctorOfDIC: constructor{N4Object}, parentDIC: N4Injector?, ...providedBinders: N4Object)</code></pre>
</div>
</div>
<div class="paragraph">
<p>we can recap that at runtime:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The first argument denotes a DIC constructor.</p>
</li>
<li>
<p>The second (optional) argument is an injector.</p>
</li>
<li>
<p>Lastly, the purpose of <code>providedBinders</code> is as follows:</p>
<div class="ulist">
<ul>
<li>
<p>The DIC above is marked with one or more <code>@UseBinder</code>.</p>
</li>
<li>
<p>Some of those binders may require injection.</p>
</li>
<li>
<p>Some of those binders may have constructor(s) taking parameters.</p>
</li>
<li>
<p>The set of binders described above should match the providedBinders.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>Validations in effect for <code>N4Injector.create(type{T} ctor)</code> callsites:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>type{T}</code> should be injectable (in particular, it may be an <code>N4Provider</code>).</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_n4js-di-annotations"><a class="anchor" href="#_n4js-di-annotations"></a><a class="link" href="#_n4js-di-annotations">11.2.6. N4JS DI Annotations</a></h4>
<div class="paragraph">
<p>Following annotations describe API used to configure N4JSDI.</p>
</div>
<div class="sect4">
<h5 id="_n4js-di-generateinjector"><a class="anchor" href="#_n4js-di-generateinjector"></a><a class="link" href="#_n4js-di-generateinjector">11.2.6.1. N4JS DI @GenerateInjector</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@GenerateInjector</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Class</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@GenerateInjector</code> marks a given class as DIComponent of the graph.
The generated injector will be responsible for creating an instance of that class and all of its dependencies.</p>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-withparentinjector"><a class="anchor" href="#_n4js-di-withparentinjector"></a><a class="link" href="#_n4js-di-withparentinjector">11.2.6.2. N4JS DI @WithParentInjector</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@WithParentInjector</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Class</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>TypeRef</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@WithParentInjector</code> marks given <em>injector</em> as depended on other <em>injector</em>.
The depended <em>injector</em> may use provided <em>injector</em> to create instances of objects required in its object graph.</p>
</div>
<div class="paragraph">
<p>Additional <em>WithParentInjector</em> constraints:</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-145"></a><strong>Req. IDE-145:</strong> <a href="#Req-IDE-145">DI WithParentInjector</a> (ver. 1)</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Allowed only on <code>N4ClassDeclarations</code> annotated with <code>@GenerateInjector</code>.</p>
</li>
<li>
<p>Its parameter can only be <code>N4ClassDeclarations</code> annotated with .</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-usebinder"><a class="anchor" href="#_n4js-di-usebinder"></a><a class="link" href="#_n4js-di-usebinder">11.2.6.3. N4JS DI @UseBinder</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>