typescene-async v1.0.29

Typescene Async Library

Library for strongly typed asynchronous programming, part of the Typescene toolkit.

Typescene Async Library - API Reference

Introduction

Project Status

The Typescene project is mostly centered around the UI toolkit it provides. While still very new, this toolkit provides a solid foundation for anyone writing a browser-based front end application (not a website, not a blog... but a real application that resembles a desktop UI more than an HTML page). See further documentation on the typescene-ui GitHub page.

What is mostly lacking at this stage, is a solid framework of unit tests. For the Async library, only the Promise implementation can be tested fully automatically (using the Promises/A+ tests). Therefore, the top priority for this project is not expanding the library but writing tests and fixing bugs, if any.

Documentation

Rudimentary documentation for this project is available here. A single page with definitions and descriptions for all classes and methods is generated automatically from source code comments. It is mostly lacking clear examples, so anyone looking into this library should use the typescene-ui project as a reference.

Purpose

This library provides a toolkit for asynchronous programming, primarily in the browser (or other browser-based front end such as Electron), mostly developed to provide a foundation for asynchronous UI toolkit development.

Prerequisites

This library assumes the use of TypeScript (although technically not required), compiled to a minimum target of "ES5" to make property decorators work.

Overview

The included functions and classes build on one another, in the following order:

• defer function: provides a basic queueing mechanism to schedule code asynchronously.
• Signals: defined using defineSignal, which creates a Signal class, of which instances can be emitted along with a single value. Like events, but different.
• Promises: the Promise class provides a Promises/A+ compliant promise implementation, along with some additional convenience methods.
• Observable values: objects wrapped around a single value (in the .value property of an ObservableValue object), which can be subscribed to for capturing changes to this value. In addition, observables can be defined using a getter function, which may use other observable values in turn (making changes cascade down a dependency tree when subscribed to; this can be employed to implement composite UIs efficiently).
• Observable arrays: arrays of observable values, hiding the ObservableValue instances in getters and setters for all array indices of an ObservableArray object.
• Observable objects: loosely defined objects for which some or all of the properties are made observable (using getters and setters) as properties of an ObservableObject, which also defines a PropertyChange signal to listen for changes without subscribing directly to observable values.

Additionally, this library exports a static HTTP class with methods that employ XMLHTTPRequest to send and receive JSON or text (or HTML) data, each returning a Promise instance.

Usage

Scheduling deferred execution of a piece of code:

// outputs first line after second line
Async.defer(() => { console.log("Hello, future.") });
console.log("Wait for it...");

Creating a signal and subscribing to it:

var MySignal = Async.defineSignal<string>();

// subscribe to this signal
MySignal.connect(text => {
    console.log("Received: " + text);
    return text.toUpperCase();
});

// simple:
MySignal.emit("text");

// advanced, capture return values:
new MySignal("text").emit().then(results => {
    console.log("Response: ", results.join(", "));
});

Creating a promise and waiting for it to be resolved:

var p = new Async.Promise((resolve, reject) => {
    setTimeout(() => resolve("abc"), 1000);
});
p.then(v => { console.log("Value: ", v) });

// ... which is the same as:
var p2 = new Async.Promise(() =>
    Async.sleep(1000).then(() => "abc"));
p2.then(v => { /* ... */ });

// ... or even:
Async.sleep(1000, "abc").then(v => { /* ... */ });

Creating a class with observable properties (there are many ways to do this, but here is an elegant solution using decorators):

// Example class with observable properties:
class MyClass extends Async.ObservableObject {
    // Observable string
    @Async.observable
    public text: string;

    // Observable string, never "undefined"
    @Async.observable_string
    public get stringified() { return this.text }

    // Observable array (automatically converts plain arrays)
    @Async.observable
    public list: string[] = [];
}

var c = new MyClass();
console.log(c.text);  // => "undefined"
console.log(c.stringified);  // => ""

// listen for changes:
Async.observe(() => c.stringified + " " + c.list.join(", "))
    .subscribe(v => console.log("Now: " + v));
    // => "Now:  "

// also track changed properties without subscribing:
c.PropertyChange.connect(p => {
    console.log("Updated: " + p)
});

// modify properties (does not output anything yet)
c.text = "Hi!";
c.list.push("a", "b", "c");

// asynchronously outputs: ...
// "Updated: text"
// "Hi! a, b, c"
// "Updated: stringified"