Index

N4JS Design Specification

2019-08-08 13:15:33 CEST
version 0.9

Table of Contents

1. Introduction
- 1.1. Notation
- 1.2. IDE Components
  - 1.2.1. Naming Conventions
2. Eclipse Setup
- 2.1. System Requirements
- 2.2. Contribute
  - 2.2.1. Eclipse Installer
    - 2.2.1.1. Changing the Setup Script
  - 2.2.2. Manual IDE Configuration
3. Release Engineering
- 3.1. Nightly build on Eclipse infrastructure
- 3.2. Build the N4JS IDE from command line
- 3.3. Updating frameworks and dependencies
  - 3.3.1. Update of Eclipse, EMF, Xtext, etc.
  - 3.3.2. Update of the embedded JRE
4. Tips and Tricks
- 4.1. Naming
- 4.2. Logging
- 4.3. Cancellation Handling
- 4.4. Caching
- 4.5. Dependency Injection
- 4.6. Miscellaneous
5. Parser
- 5.1. Overview
- 5.2. N4JS Parser
- 5.3. Parser Generation Post-Processing
- 5.4. Modifiers
- 5.5. Conflict Resolutions
  - 5.5.1. Reserved Keywords vs. Identifier Names
  - 5.5.2. Operators and Generics
- 5.6. Content-Assist Parser
6. Type System
- 6.1. Type Model and Grammar
- 6.2. Type System Implementation
- 6.3. Type Inference of AST
- 6.4. Structural Typing
7. Type Index
- 7.1. Design Rationale
  - 7.1.1. Getting the Xtext Index (IResourceDescriptions) Content
- 7.2. Design Overview
- 7.3. N4JS Resource Load States
- 7.4. Types Builder
- 7.5. Incremental Builder (Overview)
- 7.6. Dirty state handling
  - 7.6.1. Use case: Restoring types from user data
  - 7.6.2. Use case: Updating the Xtext index
8. Project Model
- 8.1. Package.json File
- 8.2. Accessing Project Information
- 8.3. Caching
  - 8.3.1. Caching of ExternalLibraryWorkspace
  - 8.3.2. Caching of N4JSProjectsStateHelper
- 8.4. WildcardPathFilter
- 8.5. ProjectUtils
9. Binding
- 9.1. Design Rationale
- 9.2. Binding to Members
- 9.3. Getter / Setter Binding
- 9.4. Static Member Binding
- 9.5. Enumeration Literals Binding
- 9.6. Accessibility of types and members
- 9.7. Member Scope Example
- 9.8. Scoping for Members of Composed Type (Union/Intersection) Example
- 9.9. Structurally References Types
- 9.10. Building
- 9.11. Proxies and Proxy Resolution (Overview)
10. Validation
- 10.1. Validation overview
- 10.2. Validation control flow
- 10.3. Issue IDs and Messages
- 10.4. Usage Pattern
- 10.5. Links
11. References
- 11.1. Use cases
- 11.2. Calculation algorithm
  - 11.2.1. Xtext default implementation
  - 11.2.2. N4JS implementation
- 11.3. Performance Of Dependency Calculation
- 11.4. Kinds of references
  - 11.4.1. Cross References to be ignored
  - 11.4.2. Cross References to be handled
- 11.5. Transitive dependencies
- 11.6. Find references
  - 11.6.1. Background
  - 11.6.2. How Find References Work
12. Compilation
- 12.1. Introduction
- 12.2. Generators
- 12.3. Transpilers
- 12.4. N4JS-to-EcmaScript Transpiler
- 12.5. n4jsc Headless Compiler Interface
  - 12.5.1. building the headless compiler
13. Execution
- 13.1. N4JS Project Execution And Linking Model
  - 13.1.1. N4JS Execution With NodeJS
- 13.2. N4JS Execution And Linking File
  - 13.2.1. NodeJS Specific ELF
- 13.3. Runners
- 13.4. Legacy Execution Engine
- 13.5. Design
  - 13.5.1. Usage Outside N4JSIDE
    - 13.5.1.1. Use Node with Maven
  - 13.5.2. Usage Inside N4JSIDE
- 13.6. Runtime Injection
14. Tests
- 14.1. Performance Tests
  - 14.1.1. Synthetic Performance Tests
- 14.2. ECMA Tests
  - 14.2.1. Grammar Tests
    - 14.2.1.1. Negative Tests
    - 14.2.1.2. Test Exclusion
- 14.3. Integration Tests
- 14.4. Test Helpers
  - 14.4.1. Parameterized N4JS tests
- 14.5. Issue Suppression
- 14.6. Xpect Tests
- 14.7. Xpect Proposal Tests
- 14.8. Apply Proposal And Execute Tests
- 14.9. Organize Imports Test
  - 14.9.1. organizeImports
- 14.10. Access Control Test
- 14.11. Smoke Tests
  - 14.11.1. How to handle smoke test errors?
  - 14.11.2. SmokeTester and ExceptionAnalyzer
- 14.12. UI Tests with SWTBot
  - 14.12.1. Writing SWTBot Tests
  - 14.12.2. Running SWTBot Tests
- 14.13. Debugging UI Tests
  - 14.13.1. Connecting to the X-server on the build-node
  - 14.13.2. Tools to investigate the java-stack
15. UI Concepts
- 15.1. User Interface Concepts
  - 15.1.1. Eclipse UI Concepts
  - 15.1.2. Non-Eclipse UI Concepts
- 15.2. User Interface Resources
  - 15.2.1. Icons
16. Formatting
- 16.1. Objective
  - 16.1.1. Formatting Comments
- 16.2. Architecture
  - 16.2.1. Implementation example
- 16.3. Formatter Implementation Guidelines
- 16.4. Configuration
- 16.5. UI Integration
- 16.6. Unit Testing with Xpect
17. External Libraries
- 17.1. Major Components
- 17.2. Headless External Library Support
  - 17.2.1. Custom npm settings
- 17.3. Future Work
  - 17.3.1. Multiple Dependency Scope
  - 17.3.2. Run Tests from TestLibrary
18. JSON Support
- 18.1. JSON Parser
- 18.2. JSON Language Extensions
  - 18.2.1. JSON Validator Extensions
    - 18.2.1.1. File-Specific Validator Extensions
    - 18.2.1.2. Declarative JSON Validator Extensions
  - 18.2.2. JSON Resource Description Strategy
19. JSDoc
- 19.1. Design Rationale
  - 19.1.1. General Design
  - 19.1.2. Type Expressions
20. DocExporter
- 20.1. Specification Exporter
21. Rename Refactoring
- 21.1. Rename Refactoring UI interaction
- 21.2. RenameElementProcessor interaction
22. Flow Graphs
- 22.1. Flow graphs overview
- 22.2. Dataflow
  - 22.2.1. Dataflow graph
  - 22.2.2. Dataflow analyses
    - 22.2.2.1. Def→Def / Def→Nothing analysis
    - 22.2.2.2. Def|Use←Decl analysis
23. Publish npms
- 23.1. Publish n4js-libs to during maven build
Appendix A: Hints
- A.1. Xtext Injection
  - A.1.1. Multiple Injectors and Singletons
    - A.1.1.1. Avoiding duplicate singletons
      - A.1.1.1.1. Defining binding in the shared injector
      - A.1.1.1.2. Defining binding in the custom injector
  - A.1.2. Dependency Injection Hints
- A.2. Eclipse
  - A.2.1. Show the current Xtext index
  - A.2.2. Plug-in spy
- A.3. Maven
  - A.3.1. How to check for Maven MOJO updates
Appendix B: Module Loading
- B.1. Dependency Management
- B.2. ECMAScript Modules
  - B.2.1. ES5 Modules Systems
  - B.2.2. ES6 Modules
- B.3. ECMAScript Module Loaders
  - B.3.1. ES6 Module Loaders
  - B.3.2. Polyfills for ES6 Module Loaders
- B.4. Case Study : TypeScript
  - B.4.1. ES6 Modules Support
  - B.4.2. TypeScript and Module Loading
- B.5. Cyclic Dependencies
- B.6. System.register as transpilation target
- B.7. CommonJS as transpilation target
Appendix C: License
Appendix D: Acronyms
Appendix E: Bibliography and Footnotes

Last Updated: 2019-08-08

Authors:
Jens von Pilgrim, Jakub Siberski, Mark-Oliver Reiser, Torsten Krämer, Ákos Kitta, Sebastian Zarnekow, Lorenzo Bettini, Jörg Reichert, Kristian Duske, Marcus Mews, Minh Quang Tran, Luca Beurer-Kellner

This document contains the N4JS Design and Implementation documentation.

Introduction
Eclipse Setup
Release Engineering
Tips and Tricks
Parser
Type System
Type Index
Project Model
Binding
Validation
References
Compilation
Execution
Tests
UI Concepts
Formatting
External Libraries
JSON Support
JSDoc
DocExporter
Rename Refactoring
Flow Graphs
Publish npms
Appendix
1. Hints
2. Module Loading
3. License
4. Acronyms
5. Bibliography and Footnotes

N4JS Design Specification

Quick Links