This package has been deprecated

Author message:

This package has been deprecated in favor of several '@esfx/*' packages that replace it. Please see the README for more information

prex
TypeScript icon, indicating that this package has built-in type declarations

0.4.9 • Public • Published

Promise Extensions for JavaScript (prex)

Asynchronous coordination for JavaScript and TypeScript.

DEPRECATED: This package has been deprecated in favor of the following packages that replace it:]

This library contains a number of coordination primitives to assist in asynchronous application development in JavaScript and TypeScript. This includes useful additions for building complex asynchronous logic including:

Installing

For the latest version:

npm install prex

Documentation

Samples

Cancellation

API Reference: Cancellation

The CancellationTokenSource and CancellationToken primitives allow you to create asynchronous operations that can be canceled externally. The following is an example of a function used to download a file asynchronously that can be canceled:

import * as http from "http";
import * as fs from "fs";
import { CancellationTokenSource, CancellationToken } from "prex";

function downloadFile(from: string, to: string, token = CancellationToken.none) {
    return new Promise<void>((resolve, reject) => {
        const request = http.get(from);

        // abort the request if canceled.
        const registration = token.register(() => {
            request.abort();
            reject(new Error("Operation canceled."));
        });

        request.on("error", err => {
            registration.unregister();
            reject(err);
        });

        request.on("response", (response: http.IncomingMessage) => {
            response
                .pipe(fs.createWriteStream(to))
                .on("error", err => {
                    registration.unregister();
                    reject(err);
                })
                .on("end", () => {
                    registration.unregister();
                    resolve();
                });
        });
    });
}

async function main() {
    const source = new CancellationTokenSource();

    // cancel the source if the file takes more than one second to download
    setTimeout(() => source.cancel(), 1000);

    await downloadFile("http://tempuri.org/some/file", "file", source.token);
}

Coordination

API Reference: Coordination

A Semaphore can be used to protect access to a critical section of your code when you must limit access across multiple async operations. The following is an example of two functions which both need exclusive access to a single resource but could possibly be preempted when suspended while awaiting an asynchronous operation:

import { Semaphore } from "prex";

const criticalResource = new Semaphore(1);

async function updateCriticalLocalResource() {
    // Acquire a lock on the critical resource
    await criticalResource.wait();

    // Make local changes...

    // await a network resources
    await postUpdateToNetworkResource(changes);

    // release the lock
    criticalResource.release();
}

async function deleteCriticalLocalResource() {
    // Acquire a lock on the critical resource
    await criticalResource.wait();

    // Make local changes...

    // await a network resources
    await postUpdateToNetworkResource(changes);

    // release the lock
    criticalResource.release();
}

declare function postUpdateToNetworkResource(changes): Promise<void>;

A Barrier can be used to coordinate complex async operations:

import { Barrier } from "prex";

const barrier = new Barrier(/*participantCount*/ 3);

async function processNpcAI() {
    while (true) {
        // process AI activities...
        await barrier.signalAndWait();
    }
}

async function processGameRules() {
    while (true) {
        // process game rules
        await barrier.signalAndWait();
    }
}

async function processGameInput() {
    while (true) {
        // process user input
        await barrier.signalAndWait();
    }
}

Scheduling

API Reference: Scheduling

An AsyncQueue is a useful primitive for scheduling asynchronous work:

import { AsyncQueue } from "prex";

const workItems = new AsyncQueue();

function queueUserWorkItem(action: () => void) {
    workItems.put(action);
}

async function processWorkItems() {
    while (true) {
        const action = await workItems.get();
        try {
            action();
        }
        catch (e) {
            console.error(e);
        }
    }
}

License

Copyright (c) Microsoft Corporation. Licensed under the Apache License, Version 2.0.

See LICENSE file in the project root for details.

Package Sidebar

Install

npm i prex

Weekly Downloads

3,700

Version

0.4.9

License

Apache-2.0

Unpacked Size

183 kB

Total Files

45

Last publish

Collaborators

  • rbuckton