Skip to content

Commit 70ec663

Browse files
lucas42lucas42
committed
Improve API documentation
Hides private functions from the existing `API.md` (but adds an `API - Internal.md` which includes them). Makes the documentation for public functions clearer and more verbose. Fixes #1
1 parent eabc331 commit 70ec663

File tree

4 files changed

+209
-114
lines changed

4 files changed

+209
-114
lines changed

‎docs/API - Internal.md

+159
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
## Functions
2+
3+
<dl>
4+
<dt><a href="#queueAndAttemptRequest">queueAndAttemptRequest(request)</a> ⇒ <code>Promise.&lt;Response&gt;</code></dt>
5+
<dd><p>Stores a request in the queue and then attempts to send it to the server.
6+
If there are existing requests in the queue, those will be attempted first to ensure they are sent in the intended order.
7+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
8+
Existing PUT and DELETE requests in the queue for the same URL will be dropped if the method is PUT or DELETE.</p>
9+
</dd>
10+
<dt><a href="#queueRequest">queueRequest(request)</a> ⇒ <code>Promise.&lt;number&gt;</code> ℗</dt>
11+
<dd><p>Stores a request object in indexDB</p>
12+
</dd>
13+
<dt><a href="#attemptRequest">attemptRequest(requestid, request)</a> ⇒ <code>Promise.&lt;Response&gt;</code> ℗</dt>
14+
<dd><p>Attempts to fetch a request from the queue. If successful, the request is removed from the queue.</p>
15+
</dd>
16+
<dt><a href="#removeFromQueue">removeFromQueue(requestid)</a> ⇒ <code>Promise</code> ℗</dt>
17+
<dd><p>Removes a request from the queue</p>
18+
</dd>
19+
<dt><a href="#getOutstandingRequestsAndIds">getOutstandingRequestsAndIds()</a> ⇒ <code>Promise.&lt;Array.&lt;{id: number, request: Request}&gt;&gt;</code> ℗</dt>
20+
<dd><p>Fetches all the outstanding requests, along with their IDs from indexDB
21+
NB: getOutstandRequests is a simplified public wrapper for this function, which doesn&#39;t expose the internal requestids</p>
22+
</dd>
23+
<dt><a href="#getOutstandingRequests">getOutstandingRequests()</a> ⇒ <code>Promise.&lt;Array.&lt;Request&gt;&gt;</code></dt>
24+
<dd><p>Fetches all the outstanding requests from the queue</p>
25+
</dd>
26+
<dt><a href="#syncRequests">syncRequests()</a> ⇒ <code>Promise</code></dt>
27+
<dd><p>Asynchronously attempts to send queued requests to the server in order.
28+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
29+
To avoid any race conditions, only one attempt to sync the queue will happen at a time.
30+
If called when an existing attempt is being made, another attempt will be made after the current one completes.</p>
31+
</dd>
32+
<dt><a href="#attemptOutstandingRequests">attemptOutstandingRequests()</a> ⇒ <code>Promise</code> ℗</dt>
33+
<dd><p>Attempts to fetch an outstanding requests, and if successful remove them from the queue.
34+
Stops after the first failure and doesn&#39;t attempt any subsequent requests in the queue.
35+
NB: Calling this function whilst a previous invocation hasn&#39;t completed yet, may cause a race condition. Use the <code>syncRequests</code> function to avoid this.</p>
36+
</dd>
37+
<dt><a href="#pruneQueueByUrl">pruneQueueByUrl(url)</a> ⇒ <code>Promise</code> ℗</dt>
38+
<dd><p>Removes all PUT or DELETE requests to the given URL from the queue
39+
This is because a subsequest request will make these unneeded</p>
40+
</dd>
41+
<dt><a href="#regularSync">regularSync()</a> ℗</dt>
42+
<dd><p>Attempts to sync any requests in the queue every 5 minutes
43+
If there are no requests in the queue, the impact of this should be negligible</p>
44+
</dd>
45+
</dl>
46+
47+
<a name="queueAndAttemptRequest"></a>
48+
49+
## queueAndAttemptRequest(request) ⇒ <code>Promise.&lt;Response&gt;</code>
50+
Stores a request in the queue and then attempts to send it to the server.
51+
If there are existing requests in the queue, those will be attempted first to ensure they are sent in the intended order.
52+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
53+
Existing PUT and DELETE requests in the queue for the same URL will be dropped if the method is PUT or DELETE.
54+
55+
**Kind**: global function
56+
**Returns**: <code>Promise.&lt;Response&gt;</code> - A promise which resolves with a "202 Added to Queue" response once the request has been successfully added to the queue.
57+
58+
| Param | Type | Description |
59+
| --- | --- | --- |
60+
| request | <code>Request</code> | A Request object from the Fetch API. Must not be in an "unusable" state. |
61+
62+
<a name="queueRequest"></a>
63+
64+
## queueRequest(request) ⇒ <code>Promise.&lt;number&gt;</code> ℗
65+
Stores a request object in indexDB
66+
67+
**Kind**: global function
68+
**Returns**: <code>Promise.&lt;number&gt;</code> - A promise which resolves with a unique requestid when succesfully stored (or rejects on failure)
69+
**Access**: private
70+
71+
| Param | Type | Description |
72+
| --- | --- | --- |
73+
| request | <code>Request</code> | A Request object from the Fetch API |
74+
75+
<a name="attemptRequest"></a>
76+
77+
## attemptRequest(requestid, request) ⇒ <code>Promise.&lt;Response&gt;</code> ℗
78+
Attempts to fetch a request from the queue. If successful, the request is removed from the queue.
79+
80+
**Kind**: global function
81+
**Returns**: <code>Promise.&lt;Response&gt;</code> - A promise which resolves with the requests response following removal from the queue (or rejects on failure)
82+
**Access**: private
83+
84+
| Param | Type | Description |
85+
| --- | --- | --- |
86+
| requestid | <code>number</code> | The unique ID for this request stored in indexDB |
87+
| request | <code>Request</code> | A Request object from the Fetch API |
88+
89+
<a name="removeFromQueue"></a>
90+
91+
## removeFromQueue(requestid) ⇒ <code>Promise</code> ℗
92+
Removes a request from the queue
93+
94+
**Kind**: global function
95+
**Returns**: <code>Promise</code> - A promise which resolves when succesfully removed (or rejects on failure)
96+
**Access**: private
97+
98+
| Param | Type | Description |
99+
| --- | --- | --- |
100+
| requestid | <code>number</code> | The unique ID for the request to remove from indexDB+ |
101+
102+
<a name="getOutstandingRequestsAndIds"></a>
103+
104+
## getOutstandingRequestsAndIds() ⇒ <code>Promise.&lt;Array.&lt;{id: number, request: Request}&gt;&gt;</code> ℗
105+
Fetches all the outstanding requests, along with their IDs from indexDB
106+
NB: getOutstandRequests is a simplified public wrapper for this function, which doesn't expose the internal requestids
107+
108+
**Kind**: global function
109+
**Returns**: <code>Promise.&lt;Array.&lt;{id: number, request: Request}&gt;&gt;</code> - An array containing requests and their associated requestids
110+
**Access**: private
111+
<a name="getOutstandingRequests"></a>
112+
113+
## getOutstandingRequests() ⇒ <code>Promise.&lt;Array.&lt;Request&gt;&gt;</code>
114+
Fetches all the outstanding requests from the queue
115+
116+
**Kind**: global function
117+
**Returns**: <code>Promise.&lt;Array.&lt;Request&gt;&gt;</code> - An array of outstanding requests in the order they are to be sent to the server
118+
<a name="syncRequests"></a>
119+
120+
## syncRequests() ⇒ <code>Promise</code>
121+
Asynchronously attempts to send queued requests to the server in order.
122+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
123+
To avoid any race conditions, only one attempt to sync the queue will happen at a time.
124+
If called when an existing attempt is being made, another attempt will be made after the current one completes.
125+
126+
**Kind**: global function
127+
**Returns**: <code>Promise</code> - A promise which resolves when all requests have been succesfully removed from the queue, or rejects after encountering the first failure
128+
<a name="attemptOutstandingRequests"></a>
129+
130+
## attemptOutstandingRequests() ⇒ <code>Promise</code> ℗
131+
Attempts to fetch an outstanding requests, and if successful remove them from the queue.
132+
Stops after the first failure and doesn't attempt any subsequent requests in the queue.
133+
NB: Calling this function whilst a previous invocation hasn't completed yet, may cause a race condition. Use the `syncRequests` function to avoid this.
134+
135+
**Kind**: global function
136+
**Returns**: <code>Promise</code> - A promise which resolves when all requests have been succesfully removed from the queue, or rejects after encountering the first failure
137+
**Access**: private
138+
<a name="pruneQueueByUrl"></a>
139+
140+
## pruneQueueByUrl(url) ⇒ <code>Promise</code> ℗
141+
Removes all PUT or DELETE requests to the given URL from the queue
142+
This is because a subsequest request will make these unneeded
143+
144+
**Kind**: global function
145+
**Returns**: <code>Promise</code> - A promise which resolves when the pruning has completed
146+
**Access**: private
147+
148+
| Param | Type | Description |
149+
| --- | --- | --- |
150+
| url | <code>string</code> | The URL of requests to prune from the queue |
151+
152+
<a name="regularSync"></a>
153+
154+
## regularSync() ℗
155+
Attempts to sync any requests in the queue every 5 minutes
156+
If there are no requests in the queue, the impact of this should be negligible
157+
158+
**Kind**: global function
159+
**Access**: private

‎docs/API.md

+27-104
Original file line numberDiff line numberDiff line change
@@ -1,129 +1,52 @@
11
## Functions
22

33
<dl>
4-
<dt><a href="#queueAndAttemptRequest">queueAndAttemptRequest(request)</a> ⇒ <code>Promise</code></dt>
5-
<dd><p>Stores a request in the queue and then attempts to send it to the server</p>
4+
<dt><a href="#queueAndAttemptRequest">queueAndAttemptRequest(request)</a> ⇒ <code>Promise.&lt;Response&gt;</code></dt>
5+
<dd><p>Stores a request in the queue and then attempts to send it to the server.
6+
If there are existing requests in the queue, those will be attempted first to ensure they are sent in the intended order.
7+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
8+
Existing PUT and DELETE requests in the queue for the same URL will be dropped if the method is PUT or DELETE.</p>
69
</dd>
7-
<dt><a href="#queueRequest">queueRequest(request)</a> ⇒ <code>Promise.&lt;number&gt;</code></dt>
8-
<dd><p>Stores a request object in indexDB</p>
10+
<dt><a href="#getOutstandingRequests">getOutstandingRequests()</a> ⇒ <code>Promise.&lt;Array.&lt;Request&gt;&gt;</code></dt>
11+
<dd><p>Fetches all the outstanding requests from the queue</p>
912
</dd>
10-
<dt><a href="#attemptRequest">attemptRequest(requestid, request)</a> ⇒ <code>Promise.&lt;Response&gt;</code></dt>
11-
<dd><p>Attempts to fetch a request from the queue. If successful, the request is removed from the queue.</p>
12-
</dd>
13-
<dt><a href="#removeFromQueue">removeFromQueue(requestid)</a> ⇒ <code>Promise</code></dt>
14-
<dd><p>Removes a request from the queue</p>
15-
</dd>
16-
<dt><a href="#getOutstandingRequestsAndIds">getOutstandingRequestsAndIds()</a> ⇒ <code>Array.&lt;{id: number, request: Request}&gt;</code></dt>
17-
<dd><p>Fetches all the outstanding requests, along with their IDs from indexDB
18-
NB: getOutstandRequests is a simplified public wrapper for this function, which doesn&#39;t expose the internal requestids</p>
19-
</dd>
20-
<dt><a href="#getOutstandingRequests">getOutstandingRequests()</a> ⇒ <code>Array.&lt;Request&gt;</code></dt>
21-
<dd><p>Fetches all the outstanding requests from indexDB</p>
22-
</dd>
23-
<dt><a href="#syncRequests">syncRequests()</a></dt>
24-
<dd><p>Starts off an asynchronous function to sync up any outstanding requests with the server
25-
Ensures there&#39;s only one running at a time to avoid race conditions</p>
26-
</dd>
27-
<dt><a href="#attemptOutstandingRequests">attemptOutstandingRequests()</a> ⇒ <code>Promise</code></dt>
28-
<dd><p>Attempts to fetch an outstanding requests, and if successful remove them from the queue.
29-
Stops after the first failure and doesn&#39;t attempt any subsequent requests in the queue.
30-
NB: Calling this function whilst a previous invocation hasn&#39;t completed yet, may cause a race condition. Use the <code>syncRequests</code> function to avoid this.</p>
31-
</dd>
32-
<dt><a href="#pruneQueueByUrl">pruneQueueByUrl(url)</a> ⇒ <code>Promise</code></dt>
33-
<dd><p>Removes all PUT or DELETE requests to the given URL from the queue
34-
This is because a subsequest request will make these unneeded</p>
13+
<dt><a href="#syncRequests">syncRequests()</a> ⇒ <code>Promise</code></dt>
14+
<dd><p>Asynchronously attempts to send queued requests to the server in order.
15+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
16+
To avoid any race conditions, only one attempt to sync the queue will happen at a time.
17+
If called when an existing attempt is being made, another attempt will be made after the current one completes.</p>
3518
</dd>
3619
</dl>
3720

3821
<a name="queueAndAttemptRequest"></a>
3922

40-
## queueAndAttemptRequest(request) ⇒ <code>Promise</code>
41-
Stores a request in the queue and then attempts to send it to the server
42-
43-
**Kind**: global function
44-
45-
| Param | Type | Description |
46-
| --- | --- | --- |
47-
| request | <code>Request</code> | A Request object from the Fetch API, which isn't unusable |
48-
49-
<a name="queueRequest"></a>
50-
51-
## queueRequest(request) ⇒ <code>Promise.&lt;number&gt;</code>
52-
Stores a request object in indexDB
53-
54-
**Kind**: global function
55-
**Returns**: <code>Promise.&lt;number&gt;</code> - A promise which resolves with a unique requestid when succesfully stored (or rejects on failure)
56-
57-
| Param | Type | Description |
58-
| --- | --- | --- |
59-
| request | <code>Request</code> | A Request object from the Fetch API |
60-
61-
<a name="attemptRequest"></a>
62-
63-
## attemptRequest(requestid, request) ⇒ <code>Promise.&lt;Response&gt;</code>
64-
Attempts to fetch a request from the queue. If successful, the request is removed from the queue.
23+
## queueAndAttemptRequest(request) ⇒ <code>Promise.&lt;Response&gt;</code>
24+
Stores a request in the queue and then attempts to send it to the server.
25+
If there are existing requests in the queue, those will be attempted first to ensure they are sent in the intended order.
26+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
27+
Existing PUT and DELETE requests in the queue for the same URL will be dropped if the method is PUT or DELETE.
6528

6629
**Kind**: global function
67-
**Returns**: <code>Promise.&lt;Response&gt;</code> - A promise which resolves with the requests response following removal from the queue (or rejects on failure)
30+
**Returns**: <code>Promise.&lt;Response&gt;</code> - A promise which resolves with a "202 Added to Queue" response once the request has been successfully added to the queue.
6831

6932
| Param | Type | Description |
7033
| --- | --- | --- |
71-
| requestid | <code>number</code> | The unique ID for this request stored in indexDB |
72-
| request | <code>Request</code> | A Request object from the Fetch API |
34+
| request | <code>Request</code> | A Request object from the Fetch API. Must not be in an "unusable" state. |
7335

74-
<a name="removeFromQueue"></a>
75-
76-
## removeFromQueue(requestid) ⇒ <code>Promise</code>
77-
Removes a request from the queue
78-
79-
**Kind**: global function
80-
**Returns**: <code>Promise</code> - A promise which resolves when succesfully removed (or rejects on failure)
81-
82-
| Param | Type | Description |
83-
| --- | --- | --- |
84-
| requestid | <code>number</code> | The unique ID for the request to remove from indexDB+ |
85-
86-
<a name="getOutstandingRequestsAndIds"></a>
87-
88-
## getOutstandingRequestsAndIds() ⇒ <code>Array.&lt;{id: number, request: Request}&gt;</code>
89-
Fetches all the outstanding requests, along with their IDs from indexDB
90-
NB: getOutstandRequests is a simplified public wrapper for this function, which doesn't expose the internal requestids
91-
92-
**Kind**: global function
93-
**Returns**: <code>Array.&lt;{id: number, request: Request}&gt;</code> - An array containing requests and their associated requestids
9436
<a name="getOutstandingRequests"></a>
9537

96-
## getOutstandingRequests() ⇒ <code>Array.&lt;Request&gt;</code>
97-
Fetches all the outstanding requests from indexDB
38+
## getOutstandingRequests() ⇒ <code>Promise.&lt;Array.&lt;Request&gt;&gt;</code>
39+
Fetches all the outstanding requests from the queue
9840

9941
**Kind**: global function
100-
**Returns**: <code>Array.&lt;Request&gt;</code> - An array containing Fetch API Request objects
42+
**Returns**: <code>Promise.&lt;Array.&lt;Request&gt;&gt;</code> - An array of outstanding requests in the order they are to be sent to the server
10143
<a name="syncRequests"></a>
10244

103-
## syncRequests()
104-
Starts off an asynchronous function to sync up any outstanding requests with the server
105-
Ensures there's only one running at a time to avoid race conditions
106-
107-
**Kind**: global function
108-
<a name="attemptOutstandingRequests"></a>
109-
110-
## attemptOutstandingRequests() ⇒ <code>Promise</code>
111-
Attempts to fetch an outstanding requests, and if successful remove them from the queue.
112-
Stops after the first failure and doesn't attempt any subsequent requests in the queue.
113-
NB: Calling this function whilst a previous invocation hasn't completed yet, may cause a race condition. Use the `syncRequests` function to avoid this.
45+
## syncRequests() ⇒ <code>Promise</code>
46+
Asynchronously attempts to send queued requests to the server in order.
47+
Succesful requests are removed from the queue. The first unsuccessful request blocks subsequent requests.
48+
To avoid any race conditions, only one attempt to sync the queue will happen at a time.
49+
If called when an existing attempt is being made, another attempt will be made after the current one completes.
11450

11551
**Kind**: global function
11652
**Returns**: <code>Promise</code> - A promise which resolves when all requests have been succesfully removed from the queue, or rejects after encountering the first failure
117-
<a name="pruneQueueByUrl"></a>
118-
119-
## pruneQueueByUrl(url) ⇒ <code>Promise</code>
120-
Removes all PUT or DELETE requests to the given URL from the queue
121-
This is because a subsequest request will make these unneeded
122-
123-
**Kind**: global function
124-
**Returns**: <code>Promise</code> - A promise which resolves when the pruning has completed
125-
126-
| Param | Type | Description |
127-
| --- | --- | --- |
128-
| url | <code>string</code> | The URL of requests to prune from the queue |
129-

0 commit comments

Comments
 (0)