Convert

The Convert class contains static methods that provide convenient and flexible mechanisms for transforming non-Promise methods into Promise-generating methods.

Interfaces / Definitions

IAsynchronousMethodWrapper

function(fulfillmentMethod, rejectionMethod, ...normalArguments)

A wrapper method that encapsulates an asynchronous operation, translating it to a common signature for conversion to a Promise. Implementators of this interface encapsulate non-Promise, asynchronous methods in such a way that each execution of the implementor executes the wrapped method in a Promises/A+-compliant manner and represents the result as a Promise. Implementations must meet the following requirements / design guidelines:

  • The implementation must call the provided fulfillmentMethod if / when the wrapped method completes successfully, optionally supplying a fulfillment value.
  • The implementation must call the provided rejectionMethod if / when the wrapped method encounters an error or does not complete successfully, optionally supplying a reason.
  • Implementors must ensure that the method it encapsulates is executed under the context under which the implementor is invoked - that is, that execution context is properly propagated as necessary.
  • If the invocation of the wrapped method immediately throws an exception, that exception should be allowed to propagate to the caller; all other exceptions should cause the returned Promise to be rejected.

Parameters

fulfillmentMethod
A function passed to the wrapper method that it can call to indicate that the wrapped asynchronous operation has completed (i.e. been fulfilled), optionally providing a resulting value.
rejectionMethod
A function passed to the wrapper method that it can call to indicate that the wrapped asynchronous operation has failed (i.e. been rejected), optionally providing a reason for the failure.
...normalArguments
Any arguments normally passed to the inner / wrapped method.

Return Value

None

IPromiseFactory

function(...arguments)

A method that generates a new Promise upon each invocation. Implementators of this interface encapsulate non-Promise methods in such a way that each execution of the implementor executes the wrapped method in a Promises/A+-compliant manner and represents the result as a Promise.

Parameters

...arguments
Any arguments to be passed to the encapsulated method upon invocation.

Return Value

A Promise that represents the result of the current invocation of the method given the provided arguments.

Static Methods

fromAsyncMethod(wrapperMethod, context)

Creates a Promise-generating version of an asynchronous method (i.e. an IPromiseFactory) from a standardized wrapper around that method. This method is intended to provide a flexible mechanism for wrapping existing asynchronous or deferred operations within a Promise.

Parameters

wrapperMethod
An IAsynchronousMethodWrapper method that wraps / maps an asynchronous method such that, in addition to the normal arguments of the wrapped method, wrapperMethod" accepts two additional prepended parameters that are invoked to indicate that the asynchronous operation has been fulfilled or rejected. wrapperMethod" must properly ensure that the provided methods for fulfillment or rejection are invoked properly. wrapperMethod" has a signature of the form “(filfill, reject, normalArgument1, normalARgument2, normalArgumentN)”.
context (optional)
The context (i.e."this" value) applied to each execution of the wrapperMethod. If not specified (i.e. undefined), the "this" value under which the returned IPromiseFactory executes is used. This latter option is useful for encapsulating prototype-defined methods. Also note that a value of null is allowed and different from a value of undefined.

Return Value

An IPromiseFactory" function that wraps wrapperMethod" and, upon each invocation, is supplied appropriate methods to indicate fulfillment or rejection of the operation in addition to the (normal) invocation parameters and executed under the appropriate context, representing its fulfillment or rejection with a Promise. Upon each execution of the IPromiseFactory", wrapperMethod" is executed and its return value (if any) is provided as the fulfillment value when it completes. If wrapperMethod" throws an exception when it is invoked, the exception is immediately propagated; any later exception generated by the wrapped method should cause the returned Promise to be rejected with the exception provided as the reason.

fromNodeAsyncMethod(nodeMethod, context)

Creates a Promise-generating, asynchronous method (i.e. IPromiseFactory) from an asynchronous method having a Node.js-style signature.

Parameters

nodeMethod
An asynchronous Node.js-style function to encapsulate. This specifically means that the method ends with a "(error, ...results)" or similar callback.
context (optional)
The context (i.e."this" value) applied to each execution of the nodeMethod. If not specified (i.e. undefined), the "this" value under which the returned IPromiseFactory executes is used. This latter option is useful for encapsulating prototype-defined methods. Also note that a value of null is allowed and different from a value of undefined.

Return Value

A function that wraps nodeMethod and, upon each invocation, applies the invocation parameters and the appropriate context to nodeMethod, representing its fulfillment or rejection with a Promise. Upon each execution of the IPromiseFactory, nodeMethod is executed and its return value (if any) is provided as the fulfillment value when it completes.

If the nodeMethod immediately throws an exception when it is invoked, the exception is propagated; otherwise, any exception or error the method produced is encapsulated within the Promise as a rejection and provided reason.

The fulfillment value of the Promises created by this factory will vary depending upon the results provided to the callback of . If the callback provides no result value(s), the Promises is fulfilled with no result. If the callback is fulfilled with one result value (e.g. a callback that accepts "(error, value)"), the Promise is fulfilled with that one result value. Otherwise, the callback produces multiple result values (e.g. a callback that accepts "(error, arg1, arg2, arg3, ...)") and the Promise will be fulfilled with a single array of those result values (e.g. [arg1, arg2, arg3, ...]).

Note that invocations of the returned IPromiseFactory should always omit the last argument of nodeMethod (i.e. the completion callback) as it is being handled by this factory.

fromSyncMethod(method, context)

Creates a Promise-generating, asynchronous method (i.e. IPromiseFactory) from a synchronous method.

Parameters

method
A function to execute that optionally produces a value.
context (optional)
The context (i.e."this" value) applied to each execution of the method. If not specified (i.e. undefined), the "this" value under which the returned IPromiseFactory executes is used. This latter option is useful for encapsulating prototype-defined methods. Also note that a value of null is allowed and different from a value of undefined.

Return Value

An IPromiseFactory function that wraps method and, upon each invocation, applies the invocation parameters and the appropriate context to the wrapped method, representing its fulfillment or rejection with a Promise. Upon each execution of the IPromiseFactory, method is scheduled for future execution and its return value (if any) is provided as the fulfillment value when it completes. If the method throws an exception, the promise is rejected with the exception as the provided reason.

objectMethods(source, methodNames, factory, suffix, context)

Creates Promise-generating versions of a set of named functions on an object using the specified factory method, naming convention, and context. This provides a flexible means of instantly converting a set of methods with similar signatures or conversion patterns into a Promise pattern. The ideal situation is one in which the source is a prototype for a type, which would immediately and efficiently Promise-enable all instances.

Parameters

source
The source entity from which the methods specified by methodNames are accessed, and to which the resulting Promise - generating methods are assigned.
methodNames
An array of strings containing the names of the methods present on source that will be converted to Promise-generating versions.
factory
The method that will be executed on every method of source named by methodNames to produce an IPromiseFactory (i.e. Promise-generating version of the method). This method will be supplied a single method reference from <source and the value of context.
suffix (optional)
The suffix that will be applied to the original method name to form the destination method name on the source entity. The default value is 'Async'. For example, a method named 'myMethod' would be converted to a Promise-generating method named 'myMethodAsync'.
context (optional)
The optional context to which all created Promise-generating methods will be bound by factory. Though the precise effect depends upon the implementation of factory provided, this parameter should be left undefined / unspecified in almost all circumstances to ensure that the Promise-generating methods will not be bound to any specific instance, but rather their normal 'this' context. This provides the greatest flexibility.

Return Value

None

Exceptions

  • One or more methods specified by methodNames are not present on source.
  • One or more target method names are already present on source.

objectNodeAsyncMethods(source, methodNames, suffix, context)

Creates Promise-generating versions of a set of named Node.js-style asynchronous functions on an object using the specified naming convention and context. This provides a flexible means of instantly converting a set of asynchronous methods with Node.js-style signatures into a Promise pattern. The ideal situation is one in which the source is a prototype for a type, which would immediately and efficiently Promise-enable all named methods.

Parameters

source
The source entity from which the methods specified by methodNames are accessed, and to which the resulting Promise - generating methods are assigned.
methodNames
An array of strings containing the names of the asynchronous Node.js-style methods present on source that will be converted to Promise-generating versions.
suffix (optional)
The suffix that will be applied to the original method name to form the destination method name on the source entity. The default value is 'Async'. For example, a method named 'myMethod' would be converted to a Promise-generating method named 'myMethodAsync'.
context (optional)
The optional context (i.e. value of 'this') to which all created Promise-generating methods will be bound. If not specified (i.e.undefined), the "this" value under which the generated methods execute is used. Leaving this value undefined is highly-recommended, especially when source is a function prototype. It may, however, be advantageous to pass a value of null or an empty object when it is known that all methods require no context for proper execution.

Return Value

None

Exceptions

  • One or more methods specified by methodNames are not present on source.
  • One or more target method names are already present on source.

Example

To transform some of the DNS methods of Node.js into Promise-generating versions, execute the following command after referencing the Promises, Promises library as the variable Promises:

Promises.Convert.objectNodeAsyncMethods(dns, ['lookup', 'resolve', 'reverse'])

After the code is executed, the global dns namespace / object contains the methods lookupAsync, resolveAsync, and reverseAsync. These new methods each perform the same actions as their original versions and accept the same parameters, but they no longer require a callback method to be provided and will, instead, return a Promise that is fulfilled or rejected as documented by the fromNodeAsyncMethod method (which is the factory utilized).

objectSyncMethods(source, methodNames, suffix, context)

Creates Promise-generating versions of a set of named synchronous functions on an object using the specified naming convention and context. This provides a flexible means of instantly converting a set of synchronous methods into a Promise pattern. The ideal situation is one in which the source is a prototype for a type, which would immediately and efficiently Promise-enable all named methods.

Parameters

source
The source entity from which the methods specified by methodNames are accessed, and to which the resulting Promise - generating methods are assigned.
methodNames
An array of strings containing the names of the synchronous methods present on source that will be converted to Promise-generating versions.
suffix (optional)
The suffix that will be applied to the original method name to form the destination method name on the source entity. The default value is 'Async'. For example, a method named 'myMethod' would be converted to a Promise-generating method named 'myMethodAsync'.
context (optional)
The optional context (i.e. value of 'this') to which all created Promise-generating methods will be bound. If not specified (i.e.undefined), the "this" value under which the generated methods execute is used. Leaving this value undefined is highly-recommended, especially when source is a function prototype. It may, however, be advantageous to pass a value of null or an empty object when it is known that all methods require no context for proper execution.

Return Value

None

Exceptions

  • One or more methods specified by methodNames are not present on source.
  • One or more target method names are already present on source.

Example

To transform the Object.toString method to a Promise-generating version, execute the following command after referencing the Promises, Promises library as the variable Promises:

Promises.Convert.objectSyncMethods(Object.prototype, ['toString'])

After the code is executed, the global Object prototype contains the method toStringAsync. This new method performs the same action as their original version and accepts the same parameters, but the return value is a Promise that is fulfilled or rejected as documented by the fromSyncMethod method (which is the factory utilized).

Last edited Mar 21, 2014 at 7:02 AM by CommanderQ, version 1