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:

1. 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.
2. { ... same key value pairs as Proxy Handler. See [https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy] }

Interceptor return values and actions:

1. If no value returned, same call will be made when the target is resolved.
2. 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