API.md

API Reference

Cancellable Promise with extra features

CPromise.CanceledError : CanceledError

CanceledError class

Kind: static property of CPromise

CPromise.AbortController : AbortController | AbortControllerEx

Refers to the AbortController class (native if available)

Kind: static property of CPromise

CPromise.AbortControllerEx : AbortControllerEx

AbortControllerEx class

Kind: static property of CPromise

CPromise.E_REASON_CANCELED

Generic cancellation reason

Kind: static property of CPromise

CPromise.E_REASON_DISPOSED

Cancellation reason for the case when the instance will be disposed

Kind: static property of CPromise

CPromise.E_REASON_TIMEOUT

Timeout cancellation reason

Kind: static property of CPromise

CPromise.E_REASON_UNMOUNTED

React specific canceled reason

Kind: static property of CPromise

CPromise.async : function

async decorator

Kind: static property of CPromise

CPromise.listen : function

listen decorator

Kind: static property of CPromise

CPromise.cancel : function

cancel decorator

Kind: static property of CPromise

CPromise.ReactComponent : function

cancel decorator

Kind: static property of CPromise

CPromise.atomic : function

make CPromise function atomic

Kind: static property of CPromise

CPromise.done : function

append done chain to the resulting promise of the decorated method

Kind: static property of CPromise

CPromise.timeout : function

timeout decorator

Kind: static property of CPromise

CPromise.innerWeight : function

innerWeight decorator

Kind: static property of CPromise

CPromise.label : function

label decorator

Kind: static property of CPromise

CPromise.canceled : function

label decorator

Kind: static property of CPromise

CPromise.progress : function

progress decorator

Kind: static property of CPromise

CPromise.promisify : function

Kind: static property of CPromise

CPromise~CPromise : object

Creates a new CPromise instance

Kind: inner namespace of CPromise
Extends: Promise

Param	Type	Description
[executor]	CPromiseExecutorFn	promise executor function that will be invoked in the context of the new CPromise instance
[options]	CPromiseOptions

• ~CPromise : object
  • instance
    • .signal : AbortSignal
    • .isPending ⇒ Boolean
    • .isCanceled ⇒ Boolean
    • .isCaptured ⇒ Boolean
    • .isPaused ⇒ Boolean
    • .isRejected ⇒ Boolean
    • .parent ⇒ CPromise | null
    • .onCancel(listener) ⇒ CPromise
    • .onPause(listener) ⇒ CPromise
    • .onResume(listener) ⇒ CPromise
    • .onCapture(listener) ⇒ CPromise
    • .onDone(listener)
    • .onSignal(listener)
    • .onSignal(signal, listener)
    • .totalWeight([weight]) ⇒ Number | CPromise
    • .innerWeight([weight]) ⇒ Number | CPromise
    • .progress([value], [data], [scope]) ⇒ Number | CPromise
    • .propagate(type, data, [scope]) ⇒ CPromise
    • .captureProgress([options]) ⇒ CPromise
    • .scopes([pendingOnly]) ⇒ Array.<CPromise>
    • .timeout([ms]) ⇒ Number | CPromise
    • .weight([weight]) ⇒ Number | CPromise
    • .label([label]) ⇒ Number | CPromise
    • .resolve(value) ⇒ CPromise
    • .reject(err) ⇒ CPromise
    • .pause(data) ⇒ Boolean
    • .resume(data) ⇒ Boolean
    • .atomic([type]) ⇒
    • .cancel([reason], [forced])
    • .emitSignal(type, [data], [handler], [locator]) ⇒ Boolean
    • .delay(ms) ⇒ CPromise
    • .aggregate([weight]) ⇒ CPromise
    • .then(onFulfilled, [onRejected]) ⇒ CPromise
    • .catch(onRejected, [filter]) ⇒ CPromise
    • .finally(onFinally) ⇒ Promise.<(T|void)>
    • .done(doneHandler) ⇒ CPromise
    • .canceled([onCanceled]) ⇒ CPromise
    • .listen(signal) ⇒ CPromise
    • .on(type, listener, [prepend]) ⇒ CPromise
    • .hasListener(event, listener) ⇒ boolean
    • .off(type, listener) ⇒ CPromise
    • .listenersCount(type) ⇒ Number
    • .hasListeners(type) ⇒ Boolean
    • .once(type, listener) ⇒ CPromise
    • .emit(type, ...args) ⇒ CPromise
    • .emitHook(type, ...args) ⇒ Boolean
    • .toString([entireChain]) ⇒ string
  • static
    • .version ⇒ string
    • .versionNumber ⇒ number
    • .isCanceledError(thing) ⇒ boolean
    • .delay(ms, value, [options]) ⇒ CPromise
    • .all(iterable, [options]) ⇒ CPromise
    • .race(pending) ⇒ CPromise
    • .allSettled(iterable, [options]) ⇒ CPromise
    • .retry(fn, [options]) ⇒ CPromise
    • .resolve([thing], [options]) ⇒ CPromise
    • .promisify(originalFn, [options]) ⇒ function
    • .run(generatorFn, [options]) ⇒ CPromise
    • .async([options])
    • .listen([signals])
    • .cancel([reason], signal)
    • .canceled(onCanceledChain)
    • .progress(onProgressHandler)
    • .ReactComponent(options)
    • .timeout(ms)
    • .label(str)
    • .innerWeight(weight)
    • .atomic(atomicType)
    • .done(doneHandler)
    • .isPromisifiedFn(fn) ⇒ * | boolean
    • .isCPromise(thing, [anyVersion]) ⇒ boolean

cPromise.signal : AbortSignal

get promise abort signal object

Kind: instance property of CPromise

cPromise.isPending ⇒ Boolean

indicates if the promise is pending

Kind: instance property of CPromise

cPromise.isCanceled ⇒ Boolean

indicates if the promise is pending

Kind: instance property of CPromise

cPromise.isCaptured ⇒ Boolean

indicates if the promise progress is captured

Kind: instance property of CPromise

cPromise.isPaused ⇒ Boolean

indicates if the promise chain is paused

Kind: instance property of CPromise

cPromise.isRejected ⇒ Boolean

indicates if the promise is rejected

Kind: instance property of CPromise

cPromise.parent ⇒ CPromise | null

get parent promise

Kind: instance property of CPromise

cPromise.onCancel(listener) ⇒ CPromise

registers the listener for cancel event

Kind: instance method of CPromise

Param	Type
listener	OnCancelListener

cPromise.onPause(listener) ⇒ CPromise

registers the listener for pause event

Kind: instance method of CPromise

Param	Type
listener	OnPauseListener

cPromise.onResume(listener) ⇒ CPromise

registers the listener for resume event

Kind: instance method of CPromise

Param	Type
listener	OnResumeListener

cPromise.onCapture(listener) ⇒ CPromise

registers the listener for capture event

Kind: instance method of CPromise

Param	Type
listener	OnCaptureListener

cPromise.onDone(listener)

registers the listener for done event

Kind: instance method of CPromise

Param	Type
listener	CPDoneListener

cPromise.onSignal(listener)

registers the listener for done event

Kind: instance method of CPromise

Param	Type
listener	CPSignalListener

cPromise.onSignal(signal, listener)

registers the listener for done event

Kind: instance method of CPromise

Param	Type
signal	Signal
listener	CPSignalListener

cPromise.totalWeight([weight]) ⇒ Number | CPromise

Set or get the total weight of the inner chains

Kind: instance method of CPromise

Param	Type
[weight]	Number

cPromise.innerWeight([weight]) ⇒ Number | CPromise

Set or get the total weight of the inner chains

Kind: instance method of CPromise

Param	Type
[weight]	Number

cPromise.progress([value], [data], [scope]) ⇒ Number | CPromise

Set promise progress

Kind: instance method of CPromise

Param	Type	Description
[value]	Number	a number between [0, 1]
[data]	*	any data to send for progress event listeners
[scope]	CPromise	CPromise scope

cPromise.propagate(type, data, [scope]) ⇒ CPromise

emit propagate event that will propagate through each promise scope in the chain (bubbling)

Kind: instance method of CPromise

Param	Type	Default	Description
type	String | symbol		some type to identify the data kind
data	*		some data
[scope]	CPromise		CPromise scope

cPromise.captureProgress([options]) ⇒ CPromise

capture initial progress state of the chain

Kind: instance method of CPromise

Param	Type	Description
[options]	Object
options.throttle	Number	set min interval for firing progress event
options.innerWeight	Number	set weight of the nested promises

cPromise.scopes([pendingOnly]) ⇒ Array.<CPromise>

Returns all parent scopes that are in pending state

Kind: instance method of CPromise

Param	Type	Default
[pendingOnly]	boolean	false

cPromise.timeout([ms]) ⇒ Number | CPromise

timeout before the promise will be canceled

Kind: instance method of CPromise

Param	Type	Description
[ms]	Number	timeout in ms

cPromise.weight([weight]) ⇒ Number | CPromise

Sets the promise weight in progress capturing process

Kind: instance method of CPromise
Returns: Number | CPromise - returns weight if no arguments were specified

Param	Type	Description
[weight]	Number	any number greater or equal 0

cPromise.label([label]) ⇒ Number | CPromise

Sets the promise label

Kind: instance method of CPromise
Returns: Number | CPromise - returns weight if no arguments were specified

Param	Type	Description
[label]	String	any string

cPromise.resolve(value) ⇒ CPromise

Resolves the promise with given value

Kind: instance method of CPromise

Param
value

cPromise.reject(err) ⇒ CPromise

Rejects the promise with given error

Kind: instance method of CPromise

Param
err

cPromise.pause(data) ⇒ Boolean

Pause promise

Kind: instance method of CPromise

Param	Type
data	*

cPromise.resume(data) ⇒ Boolean

Resume promise

Kind: instance method of CPromise

Param	Type
data	*

cPromise.atomic([type]) ⇒

Make promise chain atomic (non-cancellable for external signals)

Kind: instance method of CPromise
Returns: CPromise

Param	Type
[type]	AtomicType

cPromise.cancel([reason], [forced])

throws the CanceledError that cause promise chain cancellation

Kind: instance method of CPromise

Param	Type	Default
[reason]	String | Error
[forced]	Boolean	false

cPromise.emitSignal(type, [data], [handler], [locator]) ⇒ Boolean

Emit a signal of the specific type

Kind: instance method of CPromise

Param	Type
type	Signal
[data]	*
[handler]	SignalHandler
[locator]	SignalLocator

cPromise.delay(ms) ⇒ CPromise

Returns a chain that will be resolved after specified timeout

Kind: instance method of CPromise

Param	Type
ms	Number

cPromise.aggregate([weight]) ⇒ CPromise

Aggregate promise chain into one promise

Kind: instance method of CPromise

Param	Type	Default
[weight]	number	1

cPromise.then(onFulfilled, [onRejected]) ⇒ CPromise

returns a CPromise. It takes up to two arguments: callback functions for the success and failure cases of the Promise.

Kind: instance method of CPromise

Param	Type
onFulfilled	onFulfilled
[onRejected]	onRejected

cPromise.catch(onRejected, [filter]) ⇒ CPromise

Catches rejection with optionally specified Error class

Kind: instance method of CPromise

Param	Type
onRejected	function
[filter]	Error

cPromise.finally(onFinally) ⇒ Promise.<(T|void)>

Add handler that will be invoked when promise settled

Kind: instance method of CPromise

Param	Type
onFinally	CPFinallyHandler

cPromise.done(doneHandler) ⇒ CPromise

Add a handler that will be called after the promise has been fulfilled, but unlike finally, the returned plain value will not be ignored

Kind: instance method of CPromise

Param	Type
doneHandler	CPDoneHandler

cPromise.canceled([onCanceled]) ⇒ CPromise

Catches CancelError rejection

Kind: instance method of CPromise

Param	Type
[onCanceled]	function

cPromise.listen(signal) ⇒ CPromise

Listen for abort signal

Kind: instance method of CPromise

Param	Type
signal	AbortSignal

cPromise.on(type, listener, [prepend]) ⇒ CPromise

adds a new listener

Kind: instance method of CPromise

Param	Type	Default
type	EventType
listener	function
[prepend]	Boolean	false

cPromise.hasListener(event, listener) ⇒ boolean

Check whether the listener is already registered to the specific event

Kind: instance method of CPromise

Param	Type
event	EventType
listener	function

cPromise.off(type, listener) ⇒ CPromise

removes the listener

Kind: instance method of CPromise

Param	Type
type	EventType
listener	function

cPromise.listenersCount(type) ⇒ Number

returns listeners count of the specific event type

Kind: instance method of CPromise

Param	Type
type	EventType

cPromise.hasListeners(type) ⇒ Boolean

checks if there are listeners of a specific type

Kind: instance method of CPromise

Param	Type
type	String | Symbol

cPromise.once(type, listener) ⇒ CPromise

add 'once' listener

Kind: instance method of CPromise

Param	Type
type	EventType
listener	function

cPromise.emit(type, ...args) ⇒ CPromise

emits the event

Kind: instance method of CPromise

Param	Type
type	EventType
...args

cPromise.emitHook(type, ...args) ⇒ Boolean

Emits event as a hook. If some listener return true, this method will immediately return true as the result. Else false will be retuned

Kind: instance method of CPromise

Param	Type
type	EventType
...args

cPromise.toString([entireChain]) ⇒ string

Render promise to String

Kind: instance method of CPromise

Param	Type	Default	Description
[entireChain]	boolean	false	render the entire promise chain

CPromise.version ⇒ string

CPromise version string

Kind: static property of CPromise

CPromise.versionNumber ⇒ number

CPromise version number

Kind: static property of CPromise

CPromise.isCanceledError(thing) ⇒ boolean

Checks if thing is an CanceledError instance

Kind: static method of CPromise

Param
thing

CPromise.delay(ms, value, [options]) ⇒ CPromise

Returns a CPromise that will be resolved after specified timeout

Kind: static method of CPromise

Param	Type	Default	Description
ms	Number		delay before resolve the promise with specified value
value
[options]	object
[options.progressTick]	number	1000	progress timer tick, must be >= 100ms

CPromise.all(iterable, [options]) ⇒ CPromise

Returns a single CPromise that resolves to an array of the results of the input promises. If one fails then other promises will be canceled immediately

Kind: static method of CPromise

Param	Type
iterable	Iterable | Generator | GeneratorFunction | array
[options]	CPAllOptions

Example

CPromise.all(function*(){
    yield axios.get(url1);
    yield axios.get(url2);
    yield axios.get(url3);
}, {concurrency: 1}).then(console.log)

CPromise.race(pending) ⇒ CPromise

returns a promise that fulfills or rejects as soon as one of the promises in an iterable fulfills or rejects, with the value or reason from that promise. Other pending promises will be canceled immediately

Kind: static method of CPromise

Param	Type
pending	Iterable

CPromise.allSettled(iterable, [options]) ⇒ CPromise

returns a promise that resolves after all of the given promises have either fulfilled or rejected

Kind: static method of CPromise

Param	Type
iterable	Iterable | Generator | GeneratorFunction
[options]	CPAllOptions

CPromise.retry(fn, [options]) ⇒ CPromise

Retry async operation

Kind: static method of CPromise

Param	Type	Default
fn	CPGeneratorRetryFunction | CPRetryFunction
[options]	Object
[options.args]	Array
[options.retries]	Number
[options.delayWeight]	Number
[options.delay]	Number | CPRetryDelayResolver
[options.scopeArg]	Boolean	false

CPromise.resolve([thing], [options]) ⇒ CPromise

Converts thing to CPromise using the following rules:

• CPromise instance returns as is
• Objects with special method defined with key Symbol.for('toCPromise') will be converted using this method The result will be cached for future calls
• Thenable wraps into a new CPromise instance, if thenable has the cancel method it will be used for canceling
• Generator function will be resolved to CPromise
• Array will be resoled via CPromise.all, arrays with one element (e.g. [[1000]]) will be resolved via CPromise.race

This method returns null if the conversion failed.

Kind: static method of CPromise

Param	Type
[thing]	*
[options]	resolveOptionsObject | Boolean

CPromise.promisify(originalFn, [options]) ⇒ function

Converts callback styled function|GeneratorFn|AsyncFn to CPromise async function

Kind: static method of CPromise

Param	Type
originalFn	function | GeneratorFunction | AsyncFunction
[options]	PromisifyOptions | function | Boolean

CPromise.run(generatorFn, [options]) ⇒ CPromise

Resolves the generator to an CPromise instance

Kind: static method of CPromise

Param	Type	Description
generatorFn	GeneratorFunction
[options]	Object
[options.args]	Array
[options.resolveSignatures]	Boolean	resolve extra signatures (like arrays with CPromise.all)
[options.scopeArg]	Boolean	pass the CPromise scope as the first argument to the generator function
[options.context]	*

CPromise.async([options])

Decorator to make CPromise async function from generator, ECMA async or callback-styled method

Kind: static method of CPromise

Param	Type
[options]	object
[options.timeout]	number
[options.label]	string
[options.innerWeight]	number
[options.weight]	number
[options.listen]	AbortControllerId | AbortController | AbortSignal | Array.<(AbortControllerId|AbortController|AbortSignal)>
[options.atomic]	AtomicType

CPromise.listen([signals])

Decorator to subscribe CPromise async method to the internal or external controller

Kind: static method of CPromise

Param	Type
[signals]	AbortControllerId | AbortController | AbortSignal | Array.<(AbortControllerId|AbortController|AbortSignal)>

CPromise.cancel([reason], signal)

Decorator to cancel internal or external abort controller before the decorated function invocation. Can be used as a plain function by passing a object context with .call or .apply methods

Kind: static method of CPromise

Param	Type
[reason]	string
signal	AbortControllerId | AbortController

Example

el.onclick= ()=> cancel.call(this, reason, 'myControllerId'); - to use the decorator as a plain function

CPromise.canceled(onCanceledChain)

Decorator to add an onCanceled rejection handler to the resulting promise of the decorated method

Kind: static method of CPromise

Param	Type
onCanceledChain	function | GeneratorFunction

CPromise.progress(onProgressHandler)

Decorator to subscribe the handler to the onProgress event of the resulting promise

Kind: static method of CPromise

Param	Type
onProgressHandler	ProgressDecoratorHandler

CPromise.ReactComponent(options)

Decorate class as React component

Kind: static method of CPromise

Param	Type
options	boolean | ReactComponentDecoratorOptions

CPromise.timeout(ms)

Decorator to set timeout for the resulting promise of the decorated function

Kind: static method of CPromise

Param	Type
ms	number

CPromise.label(str)

Decorator to set label for the resulting promise of the decorated function

Kind: static method of CPromise

Param	Type
str	string

CPromise.innerWeight(weight)

Decorator to set innerWeight for the resulting promise of the decorated function

Kind: static method of CPromise

Param	Type
weight	number

CPromise.atomic(atomicType)

Decorator to set timeout for the resulting promise of the decorated function

Kind: static method of CPromise

Param	Type
atomicType	AtomicType

CPromise.done(doneHandler)

append done chain to the resulting promise of the decorated method

Kind: static method of CPromise

Param	Type
doneHandler	CPDecoratorDoneHandler

CPromise.isPromisifiedFn(fn) ⇒ * | boolean

Returns promisification strategy that was used to the original function

Kind: static method of CPromise

Param	Type
fn	function

CPromise.isCPromise(thing, [anyVersion]) ⇒ boolean

Check whether object is CPromise instance

Kind: static method of CPromise

Param	Type	Default
thing	*
[anyVersion]	boolean	false

CPromise~EventType : String | Symbol

Kind: inner typedef of CPromise

CPromise~CPromiseExecutorFn : function

Kind: inner typedef of CPromise
this: CPromise

Param	Type
resolve	function
reject	function
scope	CPromise

CPromise~PromiseOptionsObject : Object

Kind: inner typedef of CPromise
Properties

Name	Type	Default	Description
label	String
timeout	Number
weight	Number
[nativeController]	Boolean	false	prefer native AbortController class as the internal signal

CPromise~CPromiseOptions : PromiseOptionsObject | String | Number

If value is a number it will be considered as the value for timeout option If value is a string it will be considered as a label

Kind: inner typedef of CPromise

CPromise~OnCancelListener : function

Kind: inner typedef of CPromise

Param	Type
reason	CanceledError

CPromise~OnPauseListener : function

Kind: inner typedef of CPromise

CPromise~OnResumeListener : function

Kind: inner typedef of CPromise

CPromise~OnCaptureListener : function

Kind: inner typedef of CPromise

Param	Type
CPromise	scope

CPromise~CPDoneListener ⇒ CPromise

Kind: inner typedef of CPromise

Param	Type
value	*
isRejected	boolean

CPromise~CPSignalListener ⇒ Boolean

Kind: inner typedef of CPromise

Param	Type
type	Signal
data	*

CPromise~AtomicType : number | boolean | "disabled" | "detached" | "await"

Kind: inner typedef of CPromise

CPromise~Signal : String | Symbol

Kind: inner typedef of CPromise

CPromise~SignalHandler ⇒ Boolean

Kind: inner typedef of CPromise
this: {CPromise}

Param	Type
data	*
type	Signal
scope	CPromise

CPromise~SignalLocator ⇒ Boolean

Kind: inner typedef of CPromise
this: {CPromise}

Param	Type
data	*
type	Signal
scope	CPromise
isRoot	Boolean

CPromise~CPFinallyHandler : function

Kind: inner typedef of CPromise
this: CPromise

Param	Type
settledValue	*
isRejected	boolean
scope	CPromise

CPromise~CPDoneHandler : function

Kind: inner typedef of CPromise
this: CPromise

Param	Type
settledValue	*
isRejected	boolean
scope	CPromise

CPromise~CPAllOptions : object

Kind: inner typedef of CPromise
Properties

Name	Type	Description
[concurrency]	number	limit concurrency of promise being run simultaneously
[mapper]	function	function to map each element
[ignoreResults]	boolean	do not collect results
[signatures]	boolean	use advanced signatures for vales resolving

CPromise~CPRetryFunction ⇒ *

Kind: inner typedef of CPromise

Param	Type
attempt	number
args	array

CPromise~CPGeneratorRetryFunction ⇒ *

Kind: inner typedef of CPromise

Param	Type
scope	CPromise
attempt	number
args	array

CPromise~CPRetryDelayResolver ⇒ number

Kind: inner typedef of CPromise
Returns: number - a delay in ms before next attempt

Param	Type
attempt	number
retries	number

CPromise~resolveOptionsObject : Object

Kind: inner typedef of CPromise
Properties

Name	Type	Default
[resolveSignatures]	Boolean	true
[atomic]	AtomicType	true
[args]	*

CPromise~PromisifyFinalizeFn : function

Kind: inner typedef of CPromise

Param	Type
result	*
scope	CPromise

CPromise~CPPromisifyDecoratorFn ⇒ function

Kind: inner typedef of CPromise

Param	Type	Description
originalFn	function	function to decorate
options	PromisifyOptions

CPromise~PromisifyOptions : Object

Kind: inner typedef of CPromise
Properties

Name	Type	Default	Description
[multiArgs]	Boolean		aggregate all passed arguments to an array
[finalize]	PromisifyFinalizeFn		aggregate all passed arguments to an array
[fnType]	"plain" | "generator" | "async"
[scopeArg]	boolean		pass the CPromise scope as the first argument to the generator function
[decorator]	function		CPPromisifyDecoratorFn
[alignArgs]	boolean		align passed arguments to function definition for callback-styled function
[once]	boolean	true	don't promisify already promisified function
[types]	array.<('plain'|'async'|'generator')>		function types to promisify

CPromise~AbortControllerId : string | symbol

Kind: inner typedef of CPromise

CPromise~ProgressDecoratorHandler : function

Kind: inner typedef of CPromise

Param	Type
progress	number
scope	CPromise
data	*
context	object

CPromise~ReactComponentDecoratorOptions : object

Kind: inner typedef of CPromise
Properties

Name	Type	Default
[subscribeAll]	boolean	false
[bindListeners]	boolean	true
[bindMethods]	boolean	true

CPromise~CPDecoratorDoneHandler : function

Kind: inner typedef of CPromise

Param	Type
value	*
isRejected	boolean
scope	CPromise
context	object