future-proxy

Welcome to future-proxy 👋

A proxy which wraps a potential "future" object, that does not exist Yet!

Quick Practical Example:

  // Let's say we have to require an es6 module such as 
  // node-fetch (Latest version)

  const proxy = require('future-proxy');
  const fetch = proxy.Import('node-fetch');
  // Now, fetch can be used immediately. Once it is resolved, it will work automatically // (See documentation below!)

  // The above is a shorthand for:
  const fetch = proxy.trap(new proxy.Future(proxy.Function, import('node-fetch').then(_ => _.default)))  // Documentation below!

🏠 Homepage

Install

npm install future-proxy

A JS Proxy wraps an object where we can intercept (and do whatever we wish with the object!). But what if the object does not exist yet? One example being a mock http request (I am working on this ;)). So, here it goes. Here are a few examples that will illustrate the usage:

Warning: Only limitation is: By default, 'get' trap outputs a function. If you wish anything else, you will have to provide in interceptors!

Minimal Setup:

  const proxy = require('future-proxy');

  const t = new proxy.Future(); // Create a reference to some future object.
  const x = proxy.trap(t);

  // Do whatever you would do through x, as if the object 't' actually exists
  x.something(); // Where something is a method on future 't' object.

  // Later after sometime...
  t.resolve(futureObject); // Now, all the calls (get, set, etc.) to 'futureObject' will be made.

If you wish to trap a function, instead of new proxy.Future, call:

  new proxy.Future(proxy.Function);

The documentation is a progress to include the other (advanced) features. Meanwhile, files inside test/ can be referenced.

API

trap(target, interceptors) ⇒ Proxy

This function outputs the Proxy. The actual methods are called when the target is set to proper value by calling target.resolve(value);

Kind: function
Returns: Proxy - This records all the calls and calls them later when the target is resolved!

Param	Type	Description
target	Future	o : Must be an instance of Future.
interceptors	*	: An interceptor object (Optional). See below:

Interceptors param can be either of the following:

• function(trapKey, arguments) Here, trapKey is any of the proxy handler key i.e. get, set, etc. arguments is the arguments to the handler trap.
• { ... same key value pairs as Proxy Handler. See [https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy] }

Interceptor return values and actions:

• If no value returned, same call will be made when the target is resolved.
• If any value other than the below, are returned, same call will be made when the target is resolved.
  <... More and advanced usage documentation in progress ... >

Future

Kind: class

new Future([future], [promise])

Holds a potential future object which is unavailable yet!

Returns: Future Object

Param	Type	Description
[future]	proxy.Function	Optional: Can be proxy.Function if the 'future' object is expected to be a function
[promise]	Promise	Optional: If present, the future will be auto resolved once the promise is resolved

future.await(promise) ⇒

Awaits for the promise and resolves once the promise resolves.

Kind: instance method of Future
Returns: this

Param	Type
promise	Promise

Run tests

npm run test

Author

👤 Praveen Ranjan Keshri

• Github: @prkeshri
• LinkedIn: @prkeshri

Show your support

Give a ⭐️ if this project helped you!

This README was generated with ❤️ by readme-md-generator