# typescene-async

> Library for strongly typed asynchronous programming

Latest version **1.0.29** (published 2016-12-16) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install typescene-async
pnpm add typescene-async
yarn add typescene-async
bun add typescene-async
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.0.29 |
| Published | 2016-12-16 |
| First published | 2016-08-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jelmer Cormont |
| Maintainers | typescene |

## Links

- npm: https://www.npmjs.com/package/typescene-async
- Repository: https://github.com/typescene/typescene-async
- Homepage: https://github.com/typescene/typescene-async#readme
- Issues: https://github.com/typescene/typescene-async/issues
- npm.io page: https://npm.io/package/typescene-async

## Recent versions

- 1.0.29 (latest) — 2016-12-16
- 1.1.7 (next) — 2017-02-11
- 1.1.6 — 2017-02-11
- 1.1.5 — 2017-02-11
- 1.1.4 — 2017-02-10
- 1.1.3 — 2017-01-11
- 1.1.2 — 2017-01-10
- 1.1.1 — 2017-01-10
- 1.1.0 — 2017-01-09
- 1.0.31 — 2016-12-22
- 1.0.30 — 2016-12-22
- 1.0.28 — 2016-12-06
- 1.0.27 — 2016-12-05
- 1.0.26 — 2016-11-02
- 1.0.25 — 2016-10-26
- … 25 more at https://npm.io/package/typescene-async/versions

## README

# Typescene Async Library
Library for strongly typed asynchronous programming, part of the [Typescene toolkit](https://github.com/typescene/typescene/).

[Typescene Async Library - API Reference](http://typescene.github.io/typescene-async)

## 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](https://github.com/typescene/typescene-ui).

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](http://typescene.github.io/typescene-async). 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](http://www.typescriptlang.org/) (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+](http://promisesaplus.com) 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:

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

Creating a signal and subscribing to it:

```typescript
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:

```typescript
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):

```typescript
// 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"
```

---
_Source: https://npm.io/package/typescene-async · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._