Skip to content

Commit e158263

Browse files
bombillazobombillazo
authored
Add JSDocs (denodrivers#451)
* chore : add JSDocs * chore: fix port type in client config * chore: fix client config type * chore: remove import statments from JSDocs examples * chore: fix JSDocs examples code * chore: format deno files * chore: fix grammar in comment
1 parent ac33655 commit e158263

File tree

9 files changed

+430
-272
lines changed

9 files changed

+430
-272
lines changed

‎client.ts

Lines changed: 101 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ import {
1919
import { Transaction, type TransactionOptions } from "./query/transaction.ts";
2020
import { isTemplateString } from "./utils/utils.ts";
2121

22+
/**
23+
* The Session representing the current state of the connection
24+
*/
2225
export interface Session {
2326
/**
2427
* This is the code for the transaction currently locking the connection.
@@ -43,19 +46,31 @@ export interface Session {
4346
transport: "tcp" | "socket" | undefined;
4447
}
4548

49+
/**
50+
* An abstract class used to define common database client properties and methods
51+
*/
4652
export abstract class QueryClient {
4753
#connection: Connection;
4854
#terminated = false;
4955
#transaction: string | null = null;
5056

57+
/**
58+
* Create a new query client
59+
*/
5160
constructor(connection: Connection) {
5261
this.#connection = connection;
5362
}
5463

64+
/**
65+
* Indicates if the client is currently connected to the database
66+
*/
5567
get connected(): boolean {
5668
return this.#connection.connected;
5769
}
5870

71+
/**
72+
* The current session metadata
73+
*/
5974
get session(): Session {
6075
return {
6176
current_transaction: this.#transaction,
@@ -71,6 +86,9 @@ export abstract class QueryClient {
7186
}
7287
}
7388

89+
/**
90+
* Close the connection to the database
91+
*/
7492
protected async closeConnection() {
7593
if (this.connected) {
7694
await this.#connection.end();
@@ -87,8 +105,7 @@ export abstract class QueryClient {
87105
* In order to create a transaction, use the `createTransaction` method in your client as follows:
88106
*
89107
* ```ts
90-
* import { Client } from "./client.ts";
91-
*
108+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
92109
* const client = new Client();
93110
* const transaction = client.createTransaction("my_transaction_name");
94111
*
@@ -101,8 +118,7 @@ export abstract class QueryClient {
101118
* the client without applying any of the changes that took place inside it
102119
*
103120
* ```ts
104-
* import { Client } from "./client.ts";
105-
*
121+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
106122
* const client = new Client();
107123
* const transaction = client.createTransaction("transaction");
108124
*
@@ -119,8 +135,7 @@ export abstract class QueryClient {
119135
* the transaction
120136
*
121137
* ```ts
122-
* import { Client } from "./client.ts";
123-
*
138+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
124139
* const client = new Client();
125140
* const transaction = client.createTransaction("transaction");
126141
*
@@ -145,17 +160,15 @@ export abstract class QueryClient {
145160
* - Repeatable read: This isolates the transaction in a way that any external changes to the data we are reading
146161
* won't be visible inside the transaction until it has finished
147162
* ```ts
148-
* import { Client } from "./client.ts";
149-
*
163+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
150164
* const client = new Client();
151165
* const transaction = await client.createTransaction("my_transaction", { isolation_level: "repeatable_read" });
152166
* ```
153167
*
154168
* - Serializable: This isolation level prevents the current transaction from making persistent changes
155169
* if the data they were reading at the beginning of the transaction has been modified (recommended)
156170
* ```ts
157-
* import { Client } from "./client.ts";
158-
*
171+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
159172
* const client = new Client();
160173
* const transaction = await client.createTransaction("my_transaction", { isolation_level: "serializable" });
161174
* ```
@@ -168,8 +181,7 @@ export abstract class QueryClient {
168181
* is to in conjuction with the repeatable read isolation, ensuring the data you are reading does not change
169182
* during the transaction, specially useful for data extraction
170183
* ```ts
171-
* import { Client } from "./client.ts";
172-
*
184+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
173185
* const client = new Client();
174186
* const transaction = await client.createTransaction("my_transaction", { read_only: true });
175187
* ```
@@ -180,8 +192,7 @@ export abstract class QueryClient {
180192
* you can do the following:
181193
*
182194
* ```ts
183-
* import { Client } from "./client.ts";
184-
*
195+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
185196
* const client_1 = new Client();
186197
* const client_2 = new Client();
187198
* const transaction_1 = client_1.createTransaction("transaction_1");
@@ -246,47 +257,52 @@ export abstract class QueryClient {
246257
}
247258

248259
/**
249-
* This method allows executed queries to be retrieved as array entries.
250-
* It supports a generic interface in order to type the entries retrieved by the query
260+
* Execute queries and retrieve the data as array entries. It supports a generic in order to type the entries retrieved by the query
251261
*
252262
* ```ts
253-
* import { Client } from "./client.ts";
254-
*
263+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
255264
* const my_client = new Client();
256265
*
257-
* const {rows} = await my_client.queryArray(
266+
* const { rows: rows1 } = await my_client.queryArray(
258267
* "SELECT ID, NAME FROM CLIENTS"
259268
* ); // Array<unknown[]>
260-
* ```
261-
*
262-
* You can pass type arguments to the query in order to hint TypeScript what the return value will be
263-
* ```ts
264-
* import { Client } from "./client.ts";
265269
*
266-
* const my_client = new Client();
267-
* const { rows } = await my_client.queryArray<[number, string]>(
270+
* const { rows: rows2 } = await my_client.queryArray<[number, string]>(
268271
* "SELECT ID, NAME FROM CLIENTS"
269272
* ); // Array<[number, string]>
270273
* ```
274+
*/
275+
async queryArray<T extends Array<unknown>>(
276+
query: string,
277+
args?: QueryArguments,
278+
): Promise<QueryArrayResult<T>>;
279+
/**
280+
* Use the configuration object for more advance options to execute the query
271281
*
272-
* It also allows you to execute prepared statements with template strings
282+
* ```ts
283+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
284+
* const my_client = new Client();
285+
* const { rows } = await my_client.queryArray<[number, string]>({
286+
* text: "SELECT ID, NAME FROM CLIENTS",
287+
* name: "select_clients",
288+
* }); // Array<[number, string]>
289+
* ```
290+
*/
291+
async queryArray<T extends Array<unknown>>(
292+
config: QueryOptions,
293+
): Promise<QueryArrayResult<T>>;
294+
/**
295+
* Execute prepared statements with template strings
273296
*
274297
* ```ts
275-
* import { Client } from "./client.ts";
298+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
276299
* const my_client = new Client();
277300
*
278301
* const id = 12;
279302
* // Array<[number, string]>
280303
* const {rows} = await my_client.queryArray<[number, string]>`SELECT ID, NAME FROM CLIENTS WHERE ID = ${id}`;
281304
* ```
282305
*/
283-
async queryArray<T extends Array<unknown>>(
284-
query: string,
285-
args?: QueryArguments,
286-
): Promise<QueryArrayResult<T>>;
287-
async queryArray<T extends Array<unknown>>(
288-
config: QueryOptions,
289-
): Promise<QueryArrayResult<T>>;
290306
async queryArray<T extends Array<unknown>>(
291307
strings: TemplateStringsArray,
292308
...args: unknown[]
@@ -324,71 +340,58 @@ export abstract class QueryClient {
324340
}
325341

326342
/**
327-
* This method allows executed queries to be retrieved as object entries.
328-
* It supports a generic interface in order to type the entries retrieved by the query
343+
* Executed queries and retrieve the data as object entries. It supports a generic in order to type the entries retrieved by the query
329344
*
330345
* ```ts
331-
* import { Client } from "./client.ts";
332-
*
346+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
333347
* const my_client = new Client();
334348
*
335-
* {
336-
* const { rows } = await my_client.queryObject(
337-
* "SELECT ID, NAME FROM CLIENTS"
338-
* ); // Record<string, unknown>
339-
* }
349+
* const { rows: rows1 } = await my_client.queryObject(
350+
* "SELECT ID, NAME FROM CLIENTS"
351+
* ); // Record<string, unknown>
340352
*
341-
* {
342-
* const { rows } = await my_client.queryObject<{id: number, name: string}>(
343-
* "SELECT ID, NAME FROM CLIENTS"
344-
* ); // Array<{id: number, name: string}>
345-
* }
353+
* const { rows: rows2 } = await my_client.queryObject<{id: number, name: string}>(
354+
* "SELECT ID, NAME FROM CLIENTS"
355+
* ); // Array<{id: number, name: string}>
346356
* ```
347-
*
348-
* You can also map the expected results to object fields using the configuration interface.
349-
* This will be assigned in the order they were provided
357+
*/
358+
async queryObject<T>(
359+
query: string,
360+
args?: QueryArguments,
361+
): Promise<QueryObjectResult<T>>;
362+
/**
363+
* Use the configuration object for more advance options to execute the query
350364
*
351365
* ```ts
352-
* import { Client } from "./client.ts";
353-
*
366+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
354367
* const my_client = new Client();
355368
*
356-
* {
357-
* const {rows} = await my_client.queryObject(
358-
* "SELECT ID, NAME FROM CLIENTS"
359-
* );
360-
*
361-
* console.log(rows); // [{id: 78, name: "Frank"}, {id: 15, name: "Sarah"}]
362-
* }
363-
*
364-
* {
365-
* const {rows} = await my_client.queryObject({
366-
* text: "SELECT ID, NAME FROM CLIENTS",
367-
* fields: ["personal_id", "complete_name"],
368-
* });
369-
*
370-
* console.log(rows); // [{personal_id: 78, complete_name: "Frank"}, {personal_id: 15, complete_name: "Sarah"}]
371-
* }
369+
* const { rows: rows1 } = await my_client.queryObject(
370+
* "SELECT ID, NAME FROM CLIENTS"
371+
* );
372+
* console.log(rows1); // [{id: 78, name: "Frank"}, {id: 15, name: "Sarah"}]
373+
*
374+
* const { rows: rows2 } = await my_client.queryObject({
375+
* text: "SELECT ID, NAME FROM CLIENTS",
376+
* fields: ["personal_id", "complete_name"],
377+
* });
378+
* console.log(rows2); // [{personal_id: 78, complete_name: "Frank"}, {personal_id: 15, complete_name: "Sarah"}]
372379
* ```
373-
*
374-
* It also allows you to execute prepared statements with template strings
380+
*/
381+
async queryObject<T>(
382+
config: QueryObjectOptions,
383+
): Promise<QueryObjectResult<T>>;
384+
/**
385+
* Execute prepared statements with template strings
375386
*
376387
* ```ts
377-
* import { Client } from "./client.ts";
378-
*
388+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
379389
* const my_client = new Client();
380390
* const id = 12;
381391
* // Array<{id: number, name: string}>
382392
* const { rows } = await my_client.queryObject<{id: number, name: string}>`SELECT ID, NAME FROM CLIENTS WHERE ID = ${id}`;
383393
* ```
384394
*/
385-
async queryObject<T>(
386-
query: string,
387-
args?: QueryArguments,
388-
): Promise<QueryObjectResult<T>>;
389-
async queryObject<T>(
390-
config: QueryObjectOptions,
391-
): Promise<QueryObjectResult<T>>;
392395
async queryObject<T>(
393396
query: TemplateStringsArray,
394397
...args: unknown[]
@@ -431,6 +434,9 @@ export abstract class QueryClient {
431434
return await this.#executeQuery<T>(query);
432435
}
433436

437+
/**
438+
* Resets the transaction session metadata
439+
*/
434440
protected resetSessionMetadata() {
435441
this.#transaction = null;
436442
}
@@ -441,8 +447,7 @@ export abstract class QueryClient {
441447
* statements asynchronously
442448
*
443449
* ```ts
444-
* import { Client } from "./client.ts";
445-
*
450+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
446451
* const client = new Client();
447452
* await client.connect();
448453
* await client.queryArray`UPDATE MY_TABLE SET MY_FIELD = 0`;
@@ -453,8 +458,7 @@ export abstract class QueryClient {
453458
* for concurrency capabilities check out connection pools
454459
*
455460
* ```ts
456-
* import { Client } from "./client.ts";
457-
*
461+
* import { Client } from "https://deno.land/x/postgres/mod.ts";
458462
* const client_1 = new Client();
459463
* await client_1.connect();
460464
* // Even if operations are not awaited, they will be executed in the order they were
@@ -472,6 +476,9 @@ export abstract class QueryClient {
472476
* ```
473477
*/
474478
export class Client extends QueryClient {
479+
/**
480+
* Create a new client
481+
*/
475482
constructor(config?: ClientOptions | ConnectionString) {
476483
super(
477484
new Connection(createParams(config), async () => {
@@ -481,9 +488,15 @@ export class Client extends QueryClient {
481488
}
482489
}
483490

491+
/**
492+
* A client used specifically by a connection pool
493+
*/
484494
export class PoolClient extends QueryClient {
485495
#release: () => void;
486496

497+
/**
498+
* Create a new Client used by the pool
499+
*/
487500
constructor(config: ClientConfiguration, releaseCallback: () => void) {
488501
super(
489502
new Connection(config, async () => {
@@ -493,6 +506,9 @@ export class PoolClient extends QueryClient {
493506
this.#release = releaseCallback;
494507
}
495508

509+
/**
510+
* Releases the client back to the pool
511+
*/
496512
release() {
497513
this.#release();
498514

0 commit comments

Comments
 (0)