Skip to content

Commit be8cc34

Browse files
plumapluma
committed
More cleanup
1 parent a2a07ca commit be8cc34

File tree

14 files changed

+604
-531
lines changed

14 files changed

+604
-531
lines changed

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,35 @@ This driver uses semantic versioning:
1919
### Changed
2020

2121
- Renamed `CollectionDropOptions` type to `DropCollectionOptions`
22+
2223
- Renamed `CollectionTruncateOptions` type to `TruncateCollectionOptions`
24+
2325
- Changed error type constructor signatures
2426

2527
The `request` property is now always positional and the `options` property
2628
is always optional.
2729

30+
- Moved configuration related types to new `config` module
31+
32+
The following types were moved: `Config`, `LoadBalancingStrategy`,
33+
`BasicAuthCredentials` and `BearerAuthCredentials`.
34+
35+
- Moved `ArangoErrorResponse` type to `connection` module
36+
37+
The type is now also no longer marked as internal.
38+
39+
- Moved internal utility functions to new `lib/util` module
40+
41+
These methods are all still marked as internal and should not be used
42+
directly.
43+
44+
- Closing a connection now closes all open requests
45+
46+
Previously in certain situations only the most recent request would be
47+
closed per server. Note that this still merely aborts the requests but
48+
does not guarantee the underlying connections are closed as these are
49+
handled by Node.js or the browser natively.
50+
2851
## [10.0.0-alpha.0] - 2024-11-28
2952

3053
This is a major release and breaks backwards compatibility.

‎src/config.ts‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
/**
2+
* ```ts
3+
* import type { Config } from "arangojs/config";
4+
* ```
5+
*
6+
* The "config" module provides configuration related types for TypeScript.
7+
*
8+
* @packageDocumentation
9+
*/
10+
import * as errors from "./errors.js";
11+
12+
//#region Shared types
13+
/**
14+
* Determines the behavior when multiple URLs are used:
15+
*
16+
* - `"NONE"`: No load balancing. All requests will be handled by the first
17+
* URL in the list until a network error is encountered. On network error,
18+
* arangojs will advance to using the next URL in the list.
19+
*
20+
* - `"ONE_RANDOM"`: Randomly picks one URL from the list initially, then
21+
* behaves like `"NONE"`.
22+
*
23+
* - `"ROUND_ROBIN"`: Every sequential request uses the next URL in the list.
24+
*/
25+
export type LoadBalancingStrategy = "NONE" | "ROUND_ROBIN" | "ONE_RANDOM";
26+
//#endregion
27+
28+
//#region Credentials
29+
/**
30+
* Credentials for HTTP Basic authentication.
31+
*/
32+
export type BasicAuthCredentials = {
33+
/**
34+
* Username to use for authentication, e.g. `"root"`.
35+
*/
36+
username: string;
37+
/**
38+
* Password to use for authentication. Defaults to an empty string.
39+
*/
40+
password?: string;
41+
};
42+
43+
/**
44+
* Credentials for HTTP Bearer token authentication.
45+
*/
46+
export type BearerAuthCredentials = {
47+
/**
48+
* Bearer token to use for authentication.
49+
*/
50+
token: string;
51+
};
52+
53+
/**
54+
* Determines if the given credentials are for Bearer token authentication.
55+
*/
56+
export function isBearerAuth(auth: BasicAuthCredentials | BearerAuthCredentials): auth is BearerAuthCredentials {
57+
return auth.hasOwnProperty("token");
58+
}
59+
//#endregion
60+
61+
//#region Config
62+
/**
63+
* Options for configuring arangojs.
64+
*/
65+
export type Config = {
66+
/**
67+
* Name of the database to use.
68+
*
69+
* Default: `"_system"`
70+
*/
71+
databaseName?: string;
72+
/**
73+
* Base URL of the ArangoDB server or list of server URLs.
74+
*
75+
* When working with a cluster, the method {@link databases.Database#acquireHostList}
76+
* can be used to automatically pick up additional coordinators/followers at
77+
* any point.
78+
*
79+
* When running ArangoDB on a unix socket, e.g. `/tmp/arangodb.sock`, the
80+
* following URL formats are supported for unix sockets:
81+
*
82+
* - `unix:///tmp/arangodb.sock` (no SSL)
83+
* - `http+unix:///tmp/arangodb.sock` (or `https+unix://` for SSL)
84+
* - `http://unix:/tmp/arangodb.sock` (or `https://unix:` for SSL)
85+
*
86+
* Additionally `ssl` and `tls` are treated as synonymous with `https` and
87+
* `tcp` is treated as synonymous with `http`, so the following URLs are
88+
* considered identical:
89+
*
90+
* - `tcp://127.0.0.1:8529` and `http://127.0.0.1:8529`
91+
* - `ssl://127.0.0.1:8529` and `https://127.0.0.1:8529`
92+
* - `tcp+unix:///tmp/arangodb.sock` and `http+unix:///tmp/arangodb.sock`
93+
* - `ssl+unix:///tmp/arangodb.sock` and `https+unix:///tmp/arangodb.sock`
94+
* - `tcp://unix:/tmp/arangodb.sock` and `http://unix:/tmp/arangodb.sock`
95+
* - `ssl://unix:/tmp/arangodb.sock` and `https://unix:/tmp/arangodb.sock`
96+
*
97+
* See also `auth` for passing authentication credentials.
98+
*
99+
* Default: `"http://127.0.0.1:8529"`
100+
*/
101+
url?: string | string[];
102+
/**
103+
* Credentials to use for authentication.
104+
*
105+
* See also {@link databases.Database#useBasicAuth} and
106+
* {@link databases.Database#useBearerAuth}.
107+
*
108+
* Default: `{ username: "root", password: "" }`
109+
*/
110+
auth?: BasicAuthCredentials | BearerAuthCredentials;
111+
/**
112+
* Numeric representation of the ArangoDB version the driver should expect.
113+
* The format is defined as `XYYZZ` where `X` is the major version, `Y` is
114+
* the zero-filled two-digit minor version and `Z` is the zero-filled two-digit
115+
* bugfix version, e.g. `30102` for 3.1.2, `20811` for 2.8.11.
116+
*
117+
* Depending on this value certain methods may become unavailable or change
118+
* their behavior to remain compatible with different versions of ArangoDB.
119+
*
120+
* Default: `31100`
121+
*/
122+
arangoVersion?: number;
123+
/**
124+
* Determines the behavior when multiple URLs are provided:
125+
*
126+
* - `"NONE"`: No load balancing. All requests will be handled by the first
127+
* URL in the list until a network error is encountered. On network error,
128+
* arangojs will advance to using the next URL in the list.
129+
*
130+
* - `"ONE_RANDOM"`: Randomly picks one URL from the list initially, then
131+
* behaves like `"NONE"`.
132+
*
133+
* - `"ROUND_ROBIN"`: Every sequential request uses the next URL in the list.
134+
*
135+
* Default: `"NONE"`
136+
*/
137+
loadBalancingStrategy?: LoadBalancingStrategy;
138+
/**
139+
* Determines the behavior when a request fails because the underlying
140+
* connection to the server could not be opened
141+
* (i.e. [`ECONNREFUSED` in Node.js](https://nodejs.org/api/errors.html#errors_common_system_errors)):
142+
*
143+
* - `false`: the request fails immediately.
144+
*
145+
* - `0`: the request is retried until a server can be reached but only a
146+
* total number of times matching the number of known servers (including
147+
* the initial failed request).
148+
*
149+
* - any other number: the request is retried until a server can be reached
150+
* or the request has been retried a total of `maxRetries` number of times
151+
* (not including the initial failed request).
152+
*
153+
* When working with a single server, the retries (if any) will be made to
154+
* the same server.
155+
*
156+
* This setting currently has no effect when using arangojs in a browser.
157+
*
158+
* **Note**: Requests bound to a specific server (e.g. fetching query results)
159+
* will never be retried automatically and ignore this setting.
160+
*
161+
* **Note**: To set the number of retries when a write-write conflict is
162+
* encountered, see `retryOnConflict` instead.
163+
*
164+
* Default: `0`
165+
*/
166+
maxRetries?: false | number;
167+
/**
168+
* Maximum number of parallel requests arangojs will perform. If any
169+
* additional requests are attempted, they will be enqueued until one of the
170+
* active requests has completed.
171+
*
172+
* **Note:** when using `ROUND_ROBIN` load balancing and passing an array of
173+
* URLs in the `url` option, the default value of this option will be set to
174+
* `3 * url.length` instead of `3`.
175+
*
176+
* Default: `3`
177+
*/
178+
poolSize?: number;
179+
/**
180+
* (Browser only.) Determines whether credentials (e.g. cookies) will be sent
181+
* with requests to the ArangoDB server.
182+
*
183+
* If set to `same-origin`, credentials will only be included with requests
184+
* on the same URL origin as the invoking script. If set to `include`,
185+
* credentials will always be sent. If set to `omit`, credentials will be
186+
* excluded from all requests.
187+
*
188+
* Default: `same-origin`
189+
*/
190+
credentials?: "omit" | "include" | "same-origin";
191+
/**
192+
* If set to `true`, requests will keep the underlying connection open until
193+
* it times out or is closed. In browsers this prevents requests from being
194+
* cancelled when the user navigates away from the page.
195+
*
196+
* Default: `true`
197+
*/
198+
keepalive?: boolean;
199+
/**
200+
* Callback that will be invoked with the finished request object before it
201+
* is finalized. In the browser the request may already have been sent.
202+
*
203+
* @param req - Request object or XHR instance used for this request.
204+
*/
205+
beforeRequest?: (req: globalThis.Request) => void | Promise<void>;
206+
/**
207+
* Callback that will be invoked when the server response has been received
208+
* and processed or when the request has been failed without a response.
209+
*
210+
* The originating request will be available as the `request` property
211+
* on either the error or response object.
212+
*
213+
* @param err - Error encountered when handling this request or `null`.
214+
* @param res - Response object for this request, if no error occurred.
215+
*/
216+
afterResponse?: (err: errors.NetworkError | null, res?: globalThis.Response & { request: globalThis.Request; }) => void | Promise<void>;
217+
/**
218+
* Callback that will be invoked when a request
219+
*
220+
* @param err - Error encountered when handling this request.
221+
*/
222+
onError?: (err: Error) => void | Promise<void>;
223+
/**
224+
* If set to a positive number, requests will automatically be retried at
225+
* most this many times if they result in a write-write conflict.
226+
*
227+
* Default: `0`
228+
*/
229+
retryOnConflict?: number;
230+
/**
231+
* An object with additional headers to send with every request.
232+
*
233+
* If an `"authorization"` header is provided, it will be overridden when
234+
* using {@link databases.Database#useBasicAuth}, {@link databases.Database#useBearerAuth} or
235+
* the `auth` configuration option.
236+
*/
237+
headers?: Headers | Record<string, string>;
238+
/**
239+
* If set to `true`, arangojs will generate stack traces every time a request
240+
* is initiated and augment the stack traces of any errors it generates.
241+
*
242+
* **Warning**: This will cause arangojs to generate stack traces in advance
243+
* even if the request does not result in an error. Generating stack traces
244+
* may negatively impact performance.
245+
*/
246+
precaptureStackTraces?: boolean;
247+
/**
248+
* Limits the number of values of server-reported response queue times that
249+
* will be stored and accessible using {@link databases.Database#queueTime}. If set to
250+
* a finite value, older values will be discarded to make room for new values
251+
* when that limit is reached.
252+
*
253+
* Default: `10`
254+
*/
255+
responseQueueTimeSamples?: number;
256+
};
257+
//#endregion

0 commit comments

Comments
 (0)