1 | /**
|
2 | * Function responsible to run the passed function and surround it with whatever needed.
|
3 | * The name has been inspired from the `act` function coming with React.
|
4 | *
|
5 | * This wrapper function is not supposed to throw. The received function f will never throw.
|
6 | *
|
7 | * Wrapping order in the following:
|
8 | *
|
9 | * - global act defined on `fc.scheduler` wraps wait level one
|
10 | * - wait act defined on `s.waitX` wraps local one
|
11 | * - local act defined on `s.scheduleX(...)` wraps the trigger function
|
12 | *
|
13 | * @remarks Since 3.9.0
|
14 | * @public
|
15 | */
|
16 | export type SchedulerAct = (f: () => Promise<void>) => Promise<void>;
|
17 | /**
|
18 | * Instance able to reschedule the ordering of promises for a given app
|
19 | * @remarks Since 1.20.0
|
20 | * @public
|
21 | */
|
22 | export interface Scheduler<TMetaData = unknown> {
|
23 | /**
|
24 | * Wrap a new task using the Scheduler
|
25 | * @remarks Since 1.20.0
|
26 | */
|
27 | schedule: <T>(task: Promise<T>, label?: string, metadata?: TMetaData, customAct?: SchedulerAct) => Promise<T>;
|
28 | /**
|
29 | * Automatically wrap function output using the Scheduler
|
30 | * @remarks Since 1.20.0
|
31 | */
|
32 | scheduleFunction: <TArgs extends any[], T>(asyncFunction: (...args: TArgs) => Promise<T>, customAct?: SchedulerAct) => (...args: TArgs) => Promise<T>;
|
33 | /**
|
34 | * Schedule a sequence of Promise to be executed sequencially.
|
35 | * Items within the sequence might be interleaved by other scheduled operations.
|
36 | *
|
37 | * Please note that whenever an item from the sequence has started,
|
38 | * the scheduler will wait until its end before moving to another scheduled task.
|
39 | *
|
40 | * A handle is returned by the function in order to monitor the state of the sequence.
|
41 | * Sequence will be marked:
|
42 | * - done if all the promises have been executed properly
|
43 | * - faulty if one of the promises within the sequence throws
|
44 | *
|
45 | * @remarks Since 1.20.0
|
46 | */
|
47 | scheduleSequence(sequenceBuilders: SchedulerSequenceItem<TMetaData>[], customAct?: SchedulerAct): {
|
48 | done: boolean;
|
49 | faulty: boolean;
|
50 | task: Promise<{
|
51 | done: boolean;
|
52 | faulty: boolean;
|
53 | }>;
|
54 | };
|
55 | /**
|
56 | * Count of pending scheduled tasks
|
57 | * @remarks Since 1.20.0
|
58 | */
|
59 | count(): number;
|
60 | /**
|
61 | * Wait one scheduled task to be executed
|
62 | * @throws Whenever there is no task scheduled
|
63 | * @remarks Since 1.20.0
|
64 | */
|
65 | waitOne: (customAct?: SchedulerAct) => Promise<void>;
|
66 | /**
|
67 | * Wait all scheduled tasks,
|
68 | * including the ones that might be created by one of the resolved task
|
69 | * @remarks Since 1.20.0
|
70 | */
|
71 | waitAll: (customAct?: SchedulerAct) => Promise<void>;
|
72 | /**
|
73 | * Wait as many scheduled tasks as need to resolve the received Promise
|
74 | *
|
75 | * Some tests frameworks like `supertest` are not triggering calls to subsequent queries in a synchronous way,
|
76 | * some are waiting an explicit call to `then` to trigger them (either synchronously or asynchronously)...
|
77 | * As a consequence, none of `waitOne` or `waitAll` cannot wait for them out-of-the-box.
|
78 | *
|
79 | * This helper is responsible to wait as many scheduled tasks as needed (but the bare minimal) to get
|
80 | * `unscheduledTask` resolved. Once resolved it returns its output either success or failure.
|
81 | *
|
82 | * Be aware that while this helper will wait eveything to be ready for `unscheduledTask` to resolve,
|
83 | * having uncontrolled tasks triggering stuff required for `unscheduledTask` might be a source a uncontrollable
|
84 | * and not reproducible randomness as those triggers cannot be handled and scheduled by fast-check.
|
85 | *
|
86 | * @remarks Since 2.24.0
|
87 | */
|
88 | waitFor: <T>(unscheduledTask: Promise<T>, customAct?: SchedulerAct) => Promise<T>;
|
89 | /**
|
90 | * Produce an array containing all the scheduled tasks so far with their execution status.
|
91 | * If the task has been executed, it includes a string representation of the associated output or error produced by the task if any.
|
92 | *
|
93 | * Tasks will be returned in the order they get executed by the scheduler.
|
94 | *
|
95 | * @remarks Since 1.25.0
|
96 | */
|
97 | report: () => SchedulerReportItem<TMetaData>[];
|
98 | }
|
99 | /**
|
100 | * Define an item to be passed to `scheduleSequence`
|
101 | * @remarks Since 1.20.0
|
102 | * @public
|
103 | */
|
104 | export type SchedulerSequenceItem<TMetaData = unknown> = {
|
105 | /**
|
106 | * Builder to start the task
|
107 | * @remarks Since 1.20.0
|
108 | */
|
109 | builder: () => Promise<any>;
|
110 | /**
|
111 | * Label
|
112 | * @remarks Since 1.20.0
|
113 | */
|
114 | label: string;
|
115 | /**
|
116 | * Metadata to be attached into logs
|
117 | * @remarks Since 1.25.0
|
118 | */
|
119 | metadata?: TMetaData;
|
120 | } | (() => Promise<any>);
|
121 | /**
|
122 | * Describe a task for the report produced by the scheduler
|
123 | * @remarks Since 1.25.0
|
124 | * @public
|
125 | */
|
126 | export interface SchedulerReportItem<TMetaData = unknown> {
|
127 | /**
|
128 | * Execution status for this task
|
129 | * - resolved: task released by the scheduler and successful
|
130 | * - rejected: task released by the scheduler but with errors
|
131 | * - pending: task still pending in the scheduler, not released yet
|
132 | *
|
133 | * @remarks Since 1.25.0
|
134 | */
|
135 | status: 'resolved' | 'rejected' | 'pending';
|
136 | /**
|
137 | * How was this task scheduled?
|
138 | * - promise: schedule
|
139 | * - function: scheduleFunction
|
140 | * - sequence: scheduleSequence
|
141 | *
|
142 | * @remarks Since 1.25.0
|
143 | */
|
144 | schedulingType: 'promise' | 'function' | 'sequence';
|
145 | /**
|
146 | * Incremental id for the task, first received task has taskId = 1
|
147 | * @remarks Since 1.25.0
|
148 | */
|
149 | taskId: number;
|
150 | /**
|
151 | * Label of the task
|
152 | * @remarks Since 1.25.0
|
153 | */
|
154 | label: string;
|
155 | /**
|
156 | * Metadata linked when scheduling the task
|
157 | * @remarks Since 1.25.0
|
158 | */
|
159 | metadata?: TMetaData;
|
160 | /**
|
161 | * Stringified version of the output or error computed using fc.stringify
|
162 | * @remarks Since 1.25.0
|
163 | */
|
164 | outputValue?: string;
|
165 | }
|
166 |
|
\ | No newline at end of file |