Skip to content

Commit 8d76a59

Browse files
baelterbaelter
authored
Add inline JSDoc to all public class fields (#195)
1 parent 4f2e18d commit 8d76a59

12 files changed

Lines changed: 81 additions & 66 deletions

‎src/amqp-base-client.ts‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,25 +13,38 @@ export const MIN_FRAME_SIZE = 8192
1313
* Implements everything except how to connect, send data and close the socket
1414
*/
1515
export abstract class AMQPBaseClient {
16+
/** Virtual host to connect to. */
1617
vhost: string
18+
/** Username for authentication. */
1719
username: string
20+
/** Password for authentication. */
1821
password: string
22+
/** Connection name, visible in the RabbitMQ management UI. */
1923
name?: string
24+
/** Platform identifier sent in client properties. */
2025
platform?: string
26+
/** Open channels, indexed by channel id. */
2127
channels: AMQPChannel[]
2228
protected connectPromise?: [(conn: AMQPBaseClient) => void, (err: Error) => void]
2329
protected closePromise?: [(value?: void) => void, (err: Error) => void]
2430
protected onUpdateSecretOk?: (value?: void) => void
31+
/** Whether the connection is closed. */
2532
closed = true
33+
/** Set when the server has blocked publishing (connection.blocked reason). */
2634
blocked?: string
35+
/** Maximum number of channels negotiated with the server. */
2736
channelMax = 0
37+
/** Maximum frame size in bytes negotiated with the server. */
2838
frameMax: number
39+
/** Heartbeat interval in seconds. */
2940
heartbeat: number
41+
/** Callback for connection-level errors. */
3042
onerror: (error: AMQPError) => void
43+
/** Logger instance, or undefined to disable logging. */
3144
logger: Logger | undefined
32-
/** Used for string -> arraybuffer when publishing */
45+
/** @internal Used for string -> arraybuffer when publishing. */
3346
readonly textEncoder: InstanceType<typeof TextEncoder> = new TextEncoder()
34-
// Buffer pool for publishes, let multiple microtasks publish at the same time but save on allocations
47+
/** @internal Buffer pool for publishes. Lets multiple microtasks publish concurrently while saving on allocations. */
3548
readonly bufferPool: AMQPView[] = []
3649

3750
/**

‎src/amqp-channel.ts‎

Lines changed: 24 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,26 @@ import type { AMQPProperties } from "./amqp-properties.js"
1010
* Represents an AMQP Channel. Almost all actions in AMQP are performed on a Channel.
1111
*/
1212
export class AMQPChannel {
13+
/** The connection this channel belongs to. */
1314
readonly connection: AMQPBaseClient
15+
/** Channel number. */
1416
readonly id: number
17+
/** Active consumers on this channel, keyed by consumer tag. */
1518
readonly consumers = new Map<string, AMQPConsumer | AMQPGeneratorConsumer>()
1619
private rpcQueue: Promise<unknown> = Promise.resolve(true)
1720
private readonly rpcCallbacks: [(value?: unknown) => void, (err?: Error) => void][] = []
1821
private readonly unconfirmedPublishes: [number, (confirmId: number) => void, (err?: Error) => void][] = []
22+
/** Whether the channel has been closed. */
1923
closed = false
24+
/** @internal Monotonic confirm sequence number. */
2025
confirmId = 0
26+
/** @internal In-progress delivery being assembled from frames. */
2127
delivery?: AMQPMessage
28+
/** @internal In-progress basicGet response being assembled. */
2229
getMessage?: AMQPMessage
30+
/** @internal In-progress returned message being assembled. */
2331
returned?: AMQPMessage
32+
/** Callback for channel-level errors. */
2433
onerror: (reason: string) => void
2534
/**
2635
* @param connection - The connection this channel belongs to
@@ -117,29 +126,20 @@ export class AMQPChannel {
117126
}
118127

119128
/**
120-
* Consume from a queue. Messages will be delivered asynchronously.
121-
* @param queue - name of the queue to poll
122-
* @param param
123-
* @param [param.tag=""] - tag of the consumer, will be server generated if left empty
124-
* @param [param.noAck=true] - if messages are removed from the server upon delivery, or have to be acknowledged
125-
* @param [param.exclusive=false] - if this can be the only consumer of the queue, will return an Error if there are other consumers to the queue already
126-
* @param [param.args={}] - custom arguments
127-
* @param {function(AMQPMessage) : void | Promise<void>} callback - will be called for each message delivered to this consumer
129+
* Consume from a queue. Messages are delivered asynchronously to the callback.
130+
* @param queue - name of the queue
131+
* @param params - consumer options
132+
* @param callback - called for each delivered message
128133
*/
129134
basicConsume(
130135
queue: string,
131136
params: ConsumeParams,
132137
callback: (msg: AMQPMessage) => void | Promise<void>,
133138
): Promise<AMQPConsumer>
134139
/**
135-
* Consume from a queue. Messages will be delivered asynchronously through an AsyncGenerator at `consumer.messages`.
136-
* @param queue - name of the queue to poll
137-
* @param param
138-
* @param [param.tag=""] - tag of the consumer, will be server generated if left empty
139-
* @param [param.noAck=true] - if messages are removed from the server upon delivery, or have to be acknowledged
140-
* @param [param.exclusive=false] - if this can be the only consumer of the queue, will return an Error if there are other consumers to the queue already
141-
* @param [param.args={}] - custom arguments
142-
* @return {AMQPGeneratorConsumer} - Consumer with an AsyncGenerator for messages at `consumer.messages`
140+
* Consume from a queue via an async generator at `consumer.messages`.
141+
* @param queue - name of the queue
142+
* @param params - consumer options
143143
*/
144144
basicConsume(queue: string, params: ConsumeParams): Promise<AMQPGeneratorConsumer>
145145
basicConsume(
@@ -987,26 +987,17 @@ export type QueueParams = {
987987
exclusive?: boolean
988988
}
989989

990-
/* * @param [param.tag=""] - tag of the consumer, will be server generated if left empty
991-
* @param [param.noAck=true] - if messages are removed from the server upon delivery, or have to be acknowledged
992-
* @param [param.exclusive=false] - if this can be the only consumer of the queue, will return an Error if there are other consumers to the queue already
993-
* @param [param.args={}] - custom arguments */
994-
995990
export type ConsumeParams = {
996-
/**
997-
* tag of the consumer, will be server generated if left empty
998-
*/
991+
/** Consumer tag. Server-generated if empty.
992+
* @defaultValue `""` */
999993
tag?: string
1000-
/**
1001-
* if messages are removed from the server upon delivery, or have to be acknowledged
1002-
*/
994+
/** If true, messages are auto-acknowledged on delivery.
995+
* @defaultValue `true` */
1003996
noAck?: boolean
1004-
/**
1005-
* if this can be the only consumer of the queue, will return an Error if there are other consumers to the queue already
1006-
*/
997+
/** Fail if other consumers already exist on the queue.
998+
* @defaultValue `false` */
1007999
exclusive?: boolean
1008-
/**
1009-
* custom arguments
1010-
*/
1000+
/** Custom arguments.
1001+
* @defaultValue `{}` */
10111002
args?: Record<string, any> // eslint-disable-line @typescript-eslint/no-explicit-any
10121003
}

‎src/amqp-consumer.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,11 @@ import type { AMQPMessage } from "./amqp-message.js"
66
* A consumer, subscribed to a queue
77
*/
88
export class AMQPConsumer {
9+
/** Channel this consumer is attached to. */
910
readonly channel: AMQPChannel
11+
/** Server-assigned consumer tag. */
1012
readonly tag: string
13+
/** Callback invoked for each delivered message. */
1114
readonly onMessage: (msg: AMQPMessage) => void | Promise<void>
1215
protected closed = false
1316
protected closedError?: Error

‎src/amqp-error.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
import type { AMQPBaseClient } from "./amqp-base-client.js"
22

33
/**
4-
* An error, can be both AMQP level errors or socket errors
5-
* @property {string} message
6-
* @property {AMQPBaseClient} connection - The connection the error was raised on
4+
* An error from the AMQP protocol or the underlying socket.
75
*/
86
export class AMQPError extends Error {
7+
/** The connection the error was raised on. */
98
connection: AMQPBaseClient
109
/**
1110
* @param message - Error description

‎src/amqp-exchange.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,7 @@ export class AMQPExchange {
2929

3030
/**
3131
* Publish a message to this exchange.
32-
* @param [options.routingKey=""] - routing key
33-
* @param [options.confirm=true] - wait for broker confirmation
32+
* @param options - routing key, publish properties; set `confirm: false` to skip broker confirmation
3433
* @returns `this` for chaining
3534
*/
3635
async publish(body: Body, options: ExchangePublishOptions = {}): Promise<AMQPExchange> {

‎src/amqp-message.ts‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,33 +2,33 @@ import type { AMQPChannel } from "./amqp-channel.js"
22
import type { AMQPProperties } from "./amqp-properties.js"
33

44
/**
5-
* AMQP message
6-
* @property {AMQPChannel} channel - Channel this message was delivered on
7-
* @property {string} exchange - The exchange the message was published to
8-
* @property {string} routingKey - The routing key the message was published with
9-
* @property {object} properties - Message metadata
10-
* @property {number} bodySize - Byte size of the body
11-
* @property {Uint8Array} body - The raw message body
12-
* @property {number} deliveryTag - The deliveryTag of this message
13-
* @property {boolean} redelivered - The consumer tag, if deliveried to a consumer
14-
* @property {string?} consumerTag - The consumer tag, if deliveried to a consumer
15-
* @property {number?} messageCount - Number of messages left in queue (when polling)
16-
* @property {number} replyCode - Code if message was returned
17-
* @property {string} replyText - Error message on why message was returned
5+
* AMQP message.
186
*/
197
export class AMQPMessage {
8+
/** Channel this message was delivered on. */
209
channel: AMQPChannel
10+
/** Exchange the message was published to. */
2111
exchange = ""
12+
/** Routing key the message was published with. */
2213
routingKey = ""
14+
/** Message metadata (content-type, headers, etc.). */
2315
properties: AMQPProperties = {}
16+
/** Byte size of the body. */
2417
bodySize = 0
18+
/** Raw message body as bytes from the wire. */
2519
body: Uint8Array | null = null
2620
bodyPos = 0
21+
/** Server-assigned delivery tag for ack/nack/reject. */
2722
deliveryTag = 0
23+
/** Consumer tag, if delivered to a consumer. */
2824
consumerTag = ""
25+
/** Whether the message has been redelivered by the server. */
2926
redelivered = false
27+
/** Number of messages remaining in the queue (only set by basicGet). */
3028
messageCount?: number
29+
/** Reply code if the message was returned. */
3130
replyCode?: number
31+
/** Reason the message was returned. */
3232
replyText?: string
3333
private acked = false
3434

‎src/amqp-queue.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ export class AMQPQueue {
4848

4949
/**
5050
* Publish a message directly to this queue (via the default exchange).
51-
* @param [options.confirm=true] - wait for broker confirmation
51+
* @param options - publish properties; set `confirm: false` to skip broker confirmation
5252
* @returns `this` for chaining
5353
*/
5454
async publish(body: Body, options: QueuePublishOptions = {}): Promise<AMQPQueue> {

‎src/amqp-socket-client.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,15 @@ import * as tls from "tls"
1212
* AMQP 0-9-1 client over TCP socket.
1313
*/
1414
export class AMQPClient extends AMQPBaseClient {
15+
/** Underlying TCP socket, set after connect. */
1516
socket?: net.Socket | undefined
17+
/** Whether TLS is enabled. */
1618
readonly tls: boolean
19+
/** Server hostname. */
1720
readonly host: string
21+
/** Server port. */
1822
readonly port: number
23+
/** TLS options passed to `tls.connect`. */
1924
readonly tlsOptions: AMQPTlsOptions | undefined
2025
private readonly insecure: boolean
2126
private framePos: number

‎src/amqp-subscription.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export interface ConsumerDefinition {
1313
}
1414

1515
/**
16-
* A persistent queue subscription returned by {@link AMQPSession.subscribe}.
16+
* A persistent queue subscription returned by {@link AMQPQueue.subscribe}.
1717
*
1818
* Remains valid across reconnections — the underlying channel and consumer tag
1919
* are swapped in-place after each reconnect. Use `cancel()` to unsubscribe and
@@ -62,7 +62,7 @@ export class AMQPSubscription {
6262

6363
/**
6464
* A persistent queue subscription that yields messages via an async iterator.
65-
* Returned by {@link AMQPSession.subscribe} when no callback is provided.
65+
* Returned by {@link AMQPQueue.subscribe} when no callback is provided.
6666
*
6767
* Bridges across reconnections — the iterator continues yielding after each
6868
* reconnect without the caller needing to re-subscribe.

‎src/amqp-tls-options.ts‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
import type { TlsOptions } from "tls"
22

3-
/** Additional TLS options, for more info check https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions
4-
* @cert Cert chains in PEM format. One cert chain should be provided per private key.
5-
* @key Private keys in PEM format. PEM allows the option of private keys being encrypted.
6-
* Encrypted keys will be decrypted with AMQPTlsOptions.passphrase.
7-
* @pfx PFX or PKCS12 encoded private key and certificate chain.
8-
* pfx is an alternative to providing key and cert individually.
9-
* PFX is usually encrypted, if it is, passphrase will be used to decrypt it.
10-
* @passphrase Shared passphrase used for a single private key and/or a PFX.
11-
* @ca Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla.
3+
/**
4+
* TLS options passed to `tls.createSecureContext`.
5+
*
6+
* - `cert` — Cert chains in PEM format. One cert chain per private key.
7+
* - `key` — Private keys in PEM format. Encrypted keys are decrypted with `passphrase`.
8+
* - `pfx` — PFX/PKCS12 encoded private key and certificate chain (alternative to key + cert).
9+
* - `passphrase` — Shared passphrase for a single private key and/or PFX.
10+
* - `ca` — Override trusted CA certificates (defaults to Mozilla's curated list).
11+
*
12+
* See https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions
1213
*/
1314
export type AMQPTlsOptions = Pick<TlsOptions, "key" | "cert" | "pfx" | "passphrase" | "ca">

0 commit comments

Comments
 (0)