Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

upon-arrival

Package Overview
Dependencies
Maintainers
1
Versions
3
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

upon-arrival

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

  • 0.0.3
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
120
decreased by-25%
Maintainers
1
Weekly downloads
 
Created
Source

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

  • What Color is Your Function by Bob Nystrom
  • Promises/A+ Spec

Keywords

FAQs

Package last updated on 29 Apr 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc