npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

upon-arrival

v0.0.3

Published

Call void functions and set values on promises, to be executed when the promise is resolved

Downloads

1,650

Readme

upon-arrival

upon-arrival is a library that allows promised objects to be treated as if they were available synchronously for the purposes of calling their methods. This is very useful for libraries which may be lazy loaded, and have some side-effect that can occur sometime in the future, such as metrics gathering libraries noting that an event occurred.

The object returned by uponArrival, the default export of this library, is an ES6 proxy. While the promise is not yet resolved, calls to functions on the target object are placed in a queue, which are then resolved in order when the target promise resolves. After the promise has resolved, calls to functions on the target object will be synchronous.

A simple example

import uponArrival from 'upon-arrival';

const myCallableObject = {
   foo() {
      return 'bar';
   }

   doBar() {
      // ...
   }
};

async function getCallable() {
   await new Promise(resolve => setTimeout(resolve, 1000));
   return myCallableObject;
}

const arrival = uponArrival(getCallable());

// I can call arrival.doBar(), even though the promise isn't resolved yet
arrival.doBar();

// I can call foo(), but it won't necessarily return anything, so typescript will
// complain if I try to use that value
// @ts-expect-error
const foo: string = arrival.foo();

// When the promise resolves, all of the called methods will execute in order

Errors

upon-arrival exposes a promise that rejects when an error occurs. The type of the error is always ArrivalError. Any causative error will appear in the cause property of the error. If an error occurs as the promise is resolving, an error will be printed to the console with a stack trace.

An example with an error

import uponArrival, {PROMISE} from 'upon-arrival';

const arrival = uponArrival(myPromise);
const promise = arrival[PROMISE];

promise.catch(err => console.error(err.message));

// I can cause an error by calling a method that throws
arrival.methodThatThrows();

// I can also cause an error by calling a method that doesn't exist, but
// Typescript will prevent this if it knows the method doesn't exist
// @ts-expect-error
arrival.methodThatDoesNotExist();

// when the promise resolves, both of these errors will be returned in the
// `errors` property of a single `ArrivalError`

API

  • function uponArrival<T>(promise: Promise<T>): Arrival<T> (default export): Create an Arrival object from a promise. An arrival object has all the same methods as the object returned by the promise, but they are all void, since they cannot return anything if the promise hasn't been resolved yet. TODO: actually no reason to not return a promise that resolves with the value, once the inner promise is resolved.
  • PROMISE: A symbol that can be used to access the promise for error-handling.
  • ArrivalError: a subclass of Error that is thrown when an error occurs while resolving the promise. It may have a cause or errors property which reference the cause of the error.

Further reading