UNPKG

@merchise/action-queue

Version:

A coordinated queue of actions

164 lines (100 loc) • 5.28 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
# A coordinated queue of actions The class `ActionQueue` allows to create a FIFO, LIFO and replacement of actions. An action is a function that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). ## API ### `new ActionQueue(options)` Creates a new action queue. You can pass an object with options: - `createPromises`, it should be a bool to indicate if the functions 'append', 'prepend' and 'replace' should create and promises. Defaults to true. - `rejectCanceled`, it should be a bool to indicate if we reject the promises (if `createPromises` is also true) that are cancelled while still in the queue. See the methods `replace` and `clear` below. - `workers`, if present it should a small integer to indicate the amount of actions the queue can run concurrently. We advice that you really small number: max. 10. The default is 1, which means no concurrency. Ignored if not a number, or smaller than 1. ### `append(fn, ...args)` Push a new action using a FIFO strategy. The new action is going to be executed after all current pending actions in the queue. If the option `createPromises` is true, return a promise that is equivalent to the one that would be returned by the action after it starts running. This promise will resolve only if/when the action runs and resolves, and it will reject when the action rejects or is cancelled. If `createPromises` is false, return undefined. Any additional `args` passed to this method is stored and passed to callbacks. ### `prepend(fn, ...args)` Prepend a new action using a LIFO strategy. If a current action is already running don't cancel it, instead queue the given action to be run later but before any other action in the queue. If the option `createPromises` is true, return a promise that is equivalent to the one that would be returned by the action after it starts running. This promise will resolve only if/when the action runs and resolves, and it will reject when the action rejects or is cancelled. If `createPromises` is false, return undefined. Any additional `args` passed to this method is stored and passed to callbacks. ### `replace(fn, ...args)` Cancel all pending and running actions in the queue and replace it with a new action. This is the same as calling `clear` and then `append`. ### `replace_pending(fn, ...args)` Replaces the entire queue with the given action without canceling running actions. ### `clear()` Cancel all pending and running actions in the queue. ### `then(callback)` Register a callback to be called when any of the actions is completed successfully without being cancelled from the queue. The callbacks will receive all arguments the underlying Promise yields when resolving plus the extra `args` passed in `append` or `prepend`. ### `catch(callback)` Register a callback to be called when any of the actions is rejected without being cancelled. The callbacks will receive all arguments the underlying Promise yields when resolving plus the extra `args` passed in `append` or `prepend`. ### `finally(callback)` Register a callback to be called when any of the actions is resolved, rejected or cancelled (evicted from the queue). The callbacks will receive all arguments the underlying Promise yields when resolving plus the extra `args` passed in `append` or `prepend`. If the action was actually cancelled, there's no result and only the extra `args` are passed. ### `oncancel(callback)` Register a callback to be called when any of the actions is cancelled (evicted from the queue). The callbacks will receive the extra `args` passed in `append` or `prepend`. ### `length()` Return the length of queue including the running action. ### `promise()` Return a promise that resolves/rejects just as soon as the first pending/running action resolves/rejects. Cancelations don't affect the promise. If the running action gets cancelled midway, this promise will take over on the next action. If no action is scheduled to be next, we wait. The only way this promise is rejected, is if the running action is rejected. The only way this promise is resolved, is when the running action is resolved. When the same queue is used several times, calls to promise may return different promises. ### `info()` Return an object with the running and pending jobs in the queue. The result is an object with two properties: `running` and `pending`. Each contains an array of objects the properties: - `args`; which is an array (possibly empty) with the extra arguments passed to `append`, `prepend` or `replace`. - `cancel`; a function that allows to cancel this particular action - `promise`; the promise attached to this action (undefined if `createPromises` is false). ### `busy()` Return True if the queue is busy, either running or has actions waiting. This might True even if the queue is paused. ### `pause()` Pause the queue. This has no effect on the currently running action (if any); if we was running it will finish. But no new actions are going to be executed. If the queue is already paused, do nothing. ### `resume()` Resume the queue. If the queue is not paused, do nothing. ### `paused()` Return True if the queue is paused.