Skip to content

Commit

Permalink
chore(api): generate types + docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jwerle
jwerle committed Jul 10, 2024
1 parent 488021d commit 6f91240
Show file tree
Hide file tree
Showing 2 changed files with 149 additions and 21 deletions.
40 changes: 20 additions & 20 deletions api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,7 @@ External docs: https://nodejs.org/api/dns.html#dnspromiseslookuphostname-options
import { createSocket } from 'socket:dgram'
```
## [`createSocket(options, callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L632)
## [`createSocket(options, callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L651)
Creates a `Socket` instance.
Expand All @@ -568,12 +568,12 @@ Creates a `Socket` instance.
| :--- | :--- | :--- |
| Not specified | Socket | |
## [`Socket` (extends `EventEmitter`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L638)
## [`Socket` (extends `EventEmitter`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L657)
New instances of dgram.Socket are created using dgram.createSocket().
The new keyword is not to be used to create dgram.Socket instances.
### [`bind(port, address, callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L719)
### [`bind(port, address, callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L738)
External docs: https://nodejs.org/api/dgram.html#socketbindport-address-callback
Listen for datagram messages on a named port and optional address
Expand All @@ -590,7 +590,7 @@ Listen for datagram messages on a named port and optional address
| address | string | | false | The address to bind to (0.0.0.0) |
| callback | function | | false | With no parameters. Called when binding is complete. |
### [`connect(port, host, connectListener)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L797)
### [`connect(port, host, connectListener)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L853)
External docs: https://nodejs.org/api/dgram.html#socketconnectport-address-callback
Associates the dgram.Socket to a remote address and port. Every message sent
Expand All @@ -610,15 +610,15 @@ Associates the dgram.Socket to a remote address and port. Every message sent
| host | string | | true | Host the client should connect to. |
| connectListener | function | | true | Common parameter of socket.connect() methods. Will be added as a listener for the 'connect' event once. |
### [`disconnect()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L834)
### [`disconnect()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L890)
External docs: https://nodejs.org/api/dgram.html#socketdisconnect
A synchronous function that disassociates a connected dgram.Socket from
its remote address. Trying to call disconnect() on an unbound or already
disconnected socket will result in an ERR_SOCKET_DGRAM_NOT_CONNECTED exception.
### [`send(msg, offset, length, port, address, callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L893)
### [`send(msg, offset, length, port, address, callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L949)
External docs: https://nodejs.org/api/dgram.html#socketsendmsg-offset-length-port-address-callback
Broadcasts a datagram on the socket. For connectionless sockets, the
Expand Down Expand Up @@ -669,7 +669,7 @@ Broadcasts a datagram on the socket. For connectionless sockets, the
| address | string | | true | Destination host name or IP address. |
| callback | Function | | true | Called when the message has been sent. |
### [`close(callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L980)
### [`close(callback)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1036)
External docs: https://nodejs.org/api/dgram.html#socketclosecallback
Close the underlying socket and stop listening for data on it. If a
Expand All @@ -681,7 +681,7 @@ Close the underlying socket and stop listening for data on it. If a
| :--- | :--- | :---: | :---: | :--- |
| callback | function | | true | Called when the connection is completed or on error. |
### [`address()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1052)
### [`address()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1108)
External docs: https://nodejs.org/api/dgram.html#socketaddress
Returns an object containing the address information for a socket. For
Expand All @@ -697,7 +697,7 @@ Returns an object containing the address information for a socket. For
| socketInfo.port | string | The port of the socket |
| socketInfo.family | string | The IP family of the socket |
### [`remoteAddress()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1087)
### [`remoteAddress()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1143)
External docs: https://nodejs.org/api/dgram.html#socketremoteaddress
Returns an object containing the address, family, and port of the remote
Expand All @@ -712,7 +712,7 @@ Returns an object containing the address, family, and port of the remote
| socketInfo.port | string | The port of the socket |
| socketInfo.family | string | The IP family of the socket |
### [`setRecvBufferSize(size)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1118)
### [`setRecvBufferSize(size)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1174)
External docs: https://nodejs.org/api/dgram.html#socketsetrecvbuffersizesize
Sets the SO_RCVBUF socket option. Sets the maximum socket receive buffer in
Expand All @@ -723,7 +723,7 @@ Sets the SO_RCVBUF socket option. Sets the maximum socket receive buffer in
| :--- | :--- | :---: | :---: | :--- |
| size | number | | false | The size of the new receive buffer |
### [`setSendBufferSize(size)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1135)
### [`setSendBufferSize(size)`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1191)
External docs: https://nodejs.org/api/dgram.html#socketsetsendbuffersizesize
Sets the SO_SNDBUF socket option. Sets the maximum socket send buffer in
Expand All @@ -734,12 +734,12 @@ Sets the SO_SNDBUF socket option. Sets the maximum socket send buffer in
| :--- | :--- | :---: | :---: | :--- |
| size | number | | false | The size of the new send buffer |
### [`getRecvBufferSize()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1148)
### [`getRecvBufferSize()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1204)
External docs: https://nodejs.org/api/dgram.html#socketgetrecvbuffersize
### [`getSendBufferSize()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1156)
### [`getSendBufferSize()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1212)
External docs: https://nodejs.org/api/dgram.html#socketgetsendbuffersize
Expand All @@ -748,31 +748,31 @@ External docs: https://nodejs.org/api/dgram.html#socketgetsendbuffersize
| :--- | :--- | :--- |
| Not specified | number | the SO_SNDBUF socket send buffer size in bytes. |
### [`code()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1224)
### [`code()`](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1280)
## [`ERR_SOCKET_ALREADY_BOUND` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1230)
## [`ERR_SOCKET_ALREADY_BOUND` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1286)
Thrown when a socket is already bound.
## [`ERR_SOCKET_DGRAM_IS_CONNECTED` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1247)
## [`ERR_SOCKET_DGRAM_IS_CONNECTED` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1303)
Thrown when the socket is already connected.
## [`ERR_SOCKET_DGRAM_NOT_CONNECTED` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1254)
## [`ERR_SOCKET_DGRAM_NOT_CONNECTED` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1310)
Thrown when the socket is not connected.
## [`ERR_SOCKET_DGRAM_NOT_RUNNING` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1262)
## [`ERR_SOCKET_DGRAM_NOT_RUNNING` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1318)
Thrown when the socket is not running (not bound or connected).
## [`ERR_SOCKET_BAD_TYPE` (extends `TypeError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1269)
## [`ERR_SOCKET_BAD_TYPE` (extends `TypeError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1325)
Thrown when a bad socket type is used in an argument.
## [`ERR_SOCKET_BAD_PORT` (extends `RangeError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1279)
## [`ERR_SOCKET_BAD_PORT` (extends `RangeError`)](https://github.com/socketsupply/socket/blob/master/api/dgram.js#L1335)
Thrown when a bad port is given.
Expand Down
130 changes: 129 additions & 1 deletion api/index.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8947,6 +8947,120 @@ declare module "socket:constants" {
export default _default;
}

declare module "socket:internal/conduit" {
export const DEFALUT_MAX_RECONNECT_RETRIES: 32;
export const DEFAULT_MAX_RECONNECT_TIMEOUT: 256;
/**
* @class Conduit
* @ignore
*
* @classdesc A class for managing WebSocket connections with custom options and payload encoding.
*/
export class Conduit extends EventTarget {
static get port(): any;
/**
* Creates an instance of Conduit.
*
* @param {Object} params - The parameters for the Conduit.
* @param {string} params.id - The ID for the connection.
* @param {string} params.method - The method to use for the connection.
*/
constructor({ id }: {
id: string;
method: string;
});
isConnecting: boolean;
isActive: boolean;
socket: any;
port: number;
id: any;
/**
* The URL string for the WebSocket server.
* @type {string}
*/
get url(): string;
set onmessage(onmessage: (arg0: MessageEvent) => any);
/**
* @type {function(MessageEvent)}
*/
get onmessage(): (arg0: MessageEvent) => any;
set onerror(onerror: (arg0: ErrorEvent) => any);
/**
* @type {function(ErrorEvent)}
*/
get onerror(): (arg0: ErrorEvent) => any;
set onclose(onclose: (arg0: CloseEvent) => any);
/**
* @type {function(CloseEvent)}
*/
get onclose(): (arg0: CloseEvent) => any;
set onopen(onopen: (arg0: Event) => any);
/**
* @type {function(Event)}
*/
get onopen(): (arg0: Event) => any;
/**
* Connects the underlying conduit `WebSocket`.
* @param {function(Error?)=} [callback]
* @return {Conduit}
*/
connect(callback?: ((arg0: Error | null) => any) | undefined): Conduit;
/**
* Reconnects a `Conduit` socket.
* @param {{retries?: number, timeout?: number}} [options]
* @return {Conduit}
*/
reconnect(options?: {
retries?: number;
timeout?: number;
}): Conduit;
/**
* Encodes a single header into a Uint8Array.
*
* @private
* @param {string} key - The header key.
* @param {string} value - The header value.
* @returns {Uint8Array} The encoded header.
*/
private encodeOption;
/**
* Encodes options and payload into a single Uint8Array message.
*
* @private
* @param {object} options - The options to encode.
* @param {Uint8Array} payload - The payload to encode.
* @returns {Uint8Array} The encoded message.
*/
private encodeMessage;
/**
* Decodes a Uint8Array message into options and payload.
* @param {Uint8Array} data - The data to decode.
* @returns {Object} The decoded message containing options and payload.
* @throws Will throw an error if the data is invalid.
*/
decodeMessage(data: Uint8Array): any;
/**
* Registers a callback to handle incoming messages.
* The callback will receive an error object and an object containing decoded options and payload.
*
* @param {function(Error?, { options: object, payload: Uint8Array })} cb - The callback function to handle incoming messages.
*/
receive(cb: (arg0: Error | null, arg1: {
options: object;
payload: Uint8Array;
}) => any): void;
/**
* Sends a message with the specified options and payload over the WebSocket connection.
*
* @param {object} options - The options to send.
* @param {Uint8Array} payload - The payload to send.
* @return {boolean}
*/
send(options: object, payload: Uint8Array): boolean;
#private;
}
}

declare module "socket:ip" {
/**
* Normalizes input as an IPv4 address string
Expand Down Expand Up @@ -9063,6 +9177,7 @@ declare module "socket:dgram" {
dataListener: ({ detail }: {
detail: any;
}) => any;
conduit: Conduit;
/**
* Associates the dgram.Socket to a remote address and port. Every message sent
* by this handle is automatically sent to that destination. Also, the socket
Expand Down Expand Up @@ -9271,6 +9386,7 @@ declare module "socket:dgram" {
export default exports;
export type SocketOptions = any;
import { EventEmitter } from "socket:events";
import { Conduit } from "socket:internal/conduit";
import { InternalError } from "socket:errors";
import * as exports from "socket:dgram";

Expand Down Expand Up @@ -12486,13 +12602,20 @@ declare module "socket:latica/index" {
lastUpdate: number;
lastRequest: number;
localPeer: any;
write(sharedKey: any, args: any): Promise<any>;
write(sharedKey: any, args: any): Promise<any[]>;
}
/**
* `Peer` class factory.
* @param {{ createSocket: function('udp4', null, object?): object }} options
*/
export class Peer {
/**
* Test a peerID is valid
*
* @param {string} pid
* @returns boolean
*/
static isValidPeerId(pid: string): boolean;
/**
* `Peer` class constructor.
* @param {object=} opts - Options
Expand Down Expand Up @@ -12622,6 +12745,10 @@ declare module "socket:latica/index" {
* @ignore
*/
send(data: Buffer, port: number, address: string, socket?: any): undefined;
/**
* @private
*/
private stream;
/**
* @private
*/
Expand Down Expand Up @@ -12879,6 +13006,7 @@ declare module "socket:latica/proxy" {
cacheInsert(...args: any[]): Promise<any>;
mcast(...args: any[]): Promise<any>;
requestReflection(...args: any[]): Promise<any>;
stream(...args: any[]): Promise<any>;
join(...args: any[]): Promise<any>;
publish(...args: any[]): Promise<any>;
sync(...args: any[]): Promise<any>;
Expand Down

0 comments on commit 6f91240

Please sign in to comment.