N4JS Tutorial

direct instance

export abstract class Task {  (1)
  public id: string?;
  public label: string?;
}
/** An appointment. */ (1)
export class Appointment extends Task {   (2)
  public time: Date;     (3)
  public place: string;   (3)
}

export class Todo extends Task {  
  public dueDate: Date?;   
  public done = false;   (4)
}  
export class Todo extends Task {
  public dueDate: Date?;
  public priority = Priority.NORMAL;
  public done = false;
}

@StringBased (1)
export enum Priority {
  LOW, NORMAL, HIGH
}
import { Task } from "model"

export public interface Storage {

  size(): int
  clear()

  getTasks(): Array<Task>
  storeTask(task: Task): string

  isEmpty(): boolean {
    return (this.size()) === 0;
  }
}
import { Storage } from "Storage"
import { Task } from "model"

export class StorageInMemory implements Storage { (2)

  private lowestUnusedId = 1;
  @Final
  private tasks = new Map<string,Task>();  (1)

  @Override
  public size(): int {
  return this.tasks.size;
  }

  @Override
  public storeTask(task: Task): string {
    let id = 'id' + this.lowestUnusedId++;
    this.tasks.set(id, task);
    task.id = id;
    return id;
  }

  @Override
  public clear() {
    this.lowestUnusedId = 1;
    this.tasks.clear();
  }

  @Override
  public getTasks(): Array<Task> {
    return Array.from(this.tasks.values());
  }
}
ProjectId: n4js.example.tasks
ProjectType: library
ProjectVersion: 0.0.1
VendorId: eu.mycompany
VendorName: "MyCompany AG"
Output: "src-gen"
Sources {
  source {
    "src"
  }
}
RequiredRuntimeLibraries {
  n4js-runtime-es2015
}
import { StorageInMemory } from "StorageInMemory"
import { Todo } from "model"

let sim = new StorageInMemory();
let todo = new Todo();
todo.done = false;
todo.dueDate = new Date();
todo.label = "Test TODO";
sim.storeTask(todo);

console.log(sim.getTasks());
export abstract class Task {
  // ...

  constructor(@Spec spec: ~i~this=undefined) {  
  // code for initialization will be generated due to @Spec annotation  
  }  
}  
...
constructor(spec: ~i~this=undefined) {
  this.id = spec.id;
  this.label = spec.label;
}
let todo = new Todo({dueDate: new Date(), label: "Test TODO"});
sim.storeTask(todo);
import { Task } from "model"

export public interface Storage {

  async size(): int  (1)
  async clear()

  async getTasks(): Array<Task>
  async storeTask(task: Task): string

  async isEmpty(): boolean {
    return (await this.size()) === 0;
  }
}
Promise { <pending> }
import { Todo } from "model"
import { Task } from "model"
import { Storage } from "Storage"
import { StorageInMemory } from "StorageInMemory"

export public class TaskManager {

  private storage: Storage = new StorageInMemory();

  public async getTasks(): Array<Task> {
    return await this.storage.getTasks();
  }

  public async createTodo(label: string): string {
    let newTodo = new Todo({label: label});
    let newId = await this.storage.storeTask(newTodo);
    return newId;
  }
}
…
TestedProjects {
  n4js.example.tasks
}
Output: "src-gen"
Sources {
  test {
    "src"
  }
}
ProjectDependencies {
  org.eclipse.n4js.mangelhaft,
  org.eclipse.n4js.mangelhaft.assert
}
import { TaskManager } from "TaskManager"
import { Assert } from "n4/mangel/assert/Assert"

export public class TaskManagerTest {

  mgr: TaskManager = new TaskManager();

  @Test
  async testCreateTodo() {
    await this.mgr.createTodo("test todo");
    Assert.equal("test todo", (await this.mgr.getTasks())[0].label);
  }
}
mongod --dbpath /db
ProjectDependencies {
  mongodb
}
import * as mongodb+ from "mongodb"

mongodb.MongoClient.connect('mongodb://localhost:27017/tasks', function (err: any+, db: any+) {
  if (!err) {
    // ... use data base ...
    db.close();
  }
});
import { Storage } from "Storage";
import { Task, Appointment, Todo } from "model";
import { Collection, Db, MongoClient, ObjectID } from "mongodb";

/**
* Persistence for task lists using a mongodb instance.
*/
export class StorageMongoDB implements Storage {
  cachedDb: Db = null;

  private async getTasksCollection(): Collection {
    if (!this.cachedDb) {
      this.cachedDb = await MongoClient.connect('mongodb://localhost:27017/tasks');
    }
  return this.cachedDb.collection('tasks');
  }

  public async shutdown() {
    this.cachedDb.close(true);
    this.cachedDb = null;
  }
}
export class StorageMongoDB implements Storage {

// ...

  @Override
  public async size(): int {
    let coll = await this.getTasksCollection();
    return await coll.count({});
  }

  @Override
  public async clear() {
    let coll = await this.getTasksCollection();
    await coll.deleteMany({});
  }

  @Override
  public async getTasks(): Array<Task> {
    let coll = await this.getTasksCollection();
    let resultRaw = await coll.find({}).toArray();
    let result = resultRaw.map((data): Task => fromData(data));  (1)
    return result;
  }

  @Override
  public async storeTask(task: Task): string {
    let coll = await this.getTasksCollection();
    let result = await coll.insertOne(toData(task));
    if (result.insertedCount === 1) {
      task.id = result.insertedId.toHexString();
      return task.id;
    }
    throw new Error("insert document failed");
  }
}
function toData(task: Task): ~~Task {
  let metaClass = N4Type.of(task),
  data: any+ = {};
  // note: would have to set data._id, here, if we
  // wanted support for updating existing tasks
  data._type = metaClass.name;
  let taskAsObject: Object = task; // up-cast to object to allow index access
  for (let field of metaClass.dataFields(true,true)) {
    data[field.name] = taskAsObject[field.name];
  }
  return data;
}
function fromData(data: any+): Task {
  let ctor = typeToCtor.get(data._type as string);
  if (!ctor) {
    throw new Error('Unsupported type of data model entity: ' + data._type);
  }
  let task = new ctor(data);
  task.id = (data._id as ObjectID).toHexString();
  return task;
}

const typeToCtor = new Map<string,constructor{Task}>([
  ['Todo', Todo] as Iterable2<string, constructor{Task}>,
  ['Appointment', Appointment] as Iterable2<string, constructor{Task}>
]);
export public class TaskManager {

  @Inject
  private storage: Storage;

  // ...
}
@Binder
@Bind(Storage,StorageInMemory)
class InMemoryBinder {}
@GenerateInjector @UseBinder(InMemoryBinder)
export public class TaskManagerTest {
  …
}
…
export public class TaskManagerTest {
  @Inject
  mgr: TaskManager;
}
ProjectDependencies {
  mongodb,
  express,
  n4js.lang
}
//Creating a simple Web User Interface in HTML

import { TaskManager } from "TaskManager"
import {Application, Response } from "express";
import express from "express";
import { Todo } from "model"

export class WebUI {

  private app: Application;

  @Inject
  private manager: TaskManager;

  public start() {

    this.app = express();

    this.app.get('/', async (req, res) => {
      let page = await this.renderHomePage();
      res.send(page);
    });
  }
}
public start() {

// ... code shown above ...

  this.app.get("/create", async (req, res) => {
    let values = req.query as ~Object with {type: string, label: string};
    if (values && values.type === 'Todo' && values.label && values.label.length > 0) {
      await this.manager.createTodo(values.label);
    }
    redirect(res, '/');
  });
}
public start() {

// ... code shown above ...

  this.app.listen(4000, '0.0.0.0', 511, function() {
    console.log("HTTP server listening on http://localhost:4000/");
  });
}
export class WebUI {

  // ... methods shown above ...

  protected async renderHomePage(): string {
    let tasks = await this.manager.getTasks();
    let todos = tasks.filter((task) => task instanceof Todo);
    return `
      <html>
      <body>
        Your to-do's:
        <ul>
          ${
            todos.length === 0 ? '<li><em>none</em></li>\n'
            : todos.map((todo) =>
            '<li>'+todo.label+' <small>(id: '+ todo.id +')</small></li>'
            ).join('\n')
          }
        </ul>
        <hr/>
        <form action="/create" method="get">
          <input type="hidden" name="type" value="Todo">
          Label: <input type="text" name="label"><br>
          <input type="submit" value="Create Todo">
        </form>
        <hr/>
        <a href="/clear">[Clear All]</a>
      </body>
      </html>
      `;
  }
}

function redirect(res: Response, url: string) {
  res.header('Cache-Control', 'no-cache');
  res.redirect(301, url);
}
import { Storage } from "Storage";
import { StorageMongoDB } from "StorageMongoDB";
import { WebUI } from "WebUI";
import { N4Injector } from "n4js/lang/N4Injector";

@Binder
@Bind(Storage, StorageMongoDB)
class Binding { }

@GenerateInjector
@UseBinder(Binding)
class Root { }

N4Injector.of(Root).create(WebUI).start();
$ npm install -g n4js.example.tasks
$ node -r n4js.example.tasks/launch
HTTP server listening on http://localhost:4000/
$ export NODE_PATH=`pwd`
$ pushd n4js.example.tasks; npm install; popd
n4js.example.tasks@0.0.1 /Users/me/prj/n4js.example.tasks
├─┬ express@4.13.4
...
$ node n4js.example.tasks/launch.js
HTML server listening on http://localhost:4000/
$ export NODE_PATH=`pwd`
$ cd n4js.example.tasks; npm install
n4js.example.tasks@0.0.1 /Users/me/prj/n4js.example.tasks
├─┬ express@4.13.4
...
$ ./node_modules/.bin/n4js n4js.example.tasks/launch
HTTP server listening on http://localhost:4000/

1	Appointment is prefaced with a JSDoc annotation (a comment beginning with /** and closed with */ which documents that it is a single Appointment task. JSDoc comments are used to provide markup annotation of your code. The content of these comments is displayed when you hover over a reference to that element.
2	The class Appointment is a subclass of Task. This is achieved by using the keyword extends and demonstrates inheritance. N4JS supports single class inheritance similar to ECMAScript 2015 or Java. The subclass Appointment will inherit the members id and label with types from Task.
3	We add the members time and place with type annotations. The type annotations of the members in Appointment are more strict than before, since the optional modifier (denoted by the question mark) is missing. We will see the effects of these different modifiers later on.
4	Class Todo has a data field without type annotation but with an initializer. The N4JS type checker can infer the type of the initializer, in this case a boolean literal, and implicitly sets the type of the field to boolean.

N4JS Tutorial

Using N4JS to Implement a Node.js Application

Creating a new N4JS Project

The Domain Model

Creating new classes and modules

Implement the entity classes

Add an Enumeration

The Storage Layer

Defining an Interface

Implement the Interface

Edit the Manifest

Running a Module

Extend Entities with Spec-Constructor

Creating a Task Manager

Make the Storage Asynchronous

Testing

Storage using MongoDB

Dependency Injection

Web UI module

Export as npm

Run from command line with Node.js

Bibliography

Quick Links