@socketsupply/socket
Version:
A Cross-Platform, Native Runtime for Desktop and Mobile Apps — Create apps using HTML, CSS, and JavaScript. Written from the ground up to be small and maintainable.
1,144 lines (773 loc) • 123 kB
Markdown
# [Buffer](https://github.com/socketsupply/socket/blob/master/api/buffer.js)
Buffer module is a [third party](https://github.com/feross/buffer) vendor module provided by Feross Aboukhadijeh and other contributors (MIT License).
External docs: https://nodejs.org/api/buffer.html
# [Events](https://github.com/socketsupply/socket/blob/master/api/events.js)
Events module is a [third party](https://github.com/browserify/events/blob/main/events.js) module provided by Browserify and Node.js contributors (MIT License).
External docs: https://nodejs.org/api/events.html
<!-- This file is generated by bin/docs-generator/api-module.js -->
<!-- Do not edit this file directly. -->
# [application](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L14)
Provides Application level methods
Example usage:
```js
import { createWindow } from 'socket:application'
```
## [MAX_WINDOWS](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L62)
This is a `VariableDeclaration` named `MAX_WINDOWS` in `api/application.js`, it's exported but undocumented.
## [ApplicationWindowList](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L64)
This is a `ClassDeclaration` named `ApplicationWindowList` in `api/application.js`, it's exported but undocumented.
## [`addEventListener(type, listener, |boolean)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L191)
Add an application event `type` callback `listener` with `options`.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| type | string | | false | |
| listener | function(Event \| MessageEvent \| CustomEvent \| ApplicationURLEvent): boolean | | false | |
| |boolean | { once?: boolean | } options | false | |
## [`removeEventListener(type, listener)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L200)
Remove an application event `type` callback `listener` with `options`.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| type | string | | false | |
| listener | function(Event \| MessageEvent \| CustomEvent \| ApplicationURLEvent): boolean | | false | |
## [`getCurrentWindowIndex()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L208)
Returns the current window index
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | number | |
## [`createWindow(opts)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L243)
Creates a new window and returns an instance of ApplicationWindow.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| opts | object | | false | an options object |
| opts.aspectRatio | string | | true | a string (split on ':') provides two float values which set the window's aspect ratio. |
| opts.closable | boolean | | true | deterime if the window can be closed. |
| opts.minimizable | boolean | | true | deterime if the window can be minimized. |
| opts.maximizable | boolean | | true | deterime if the window can be maximized. |
| opts.margin | number | | true | a margin around the webview. (Private) |
| opts.radius | number | | true | a radius on the webview. (Private) |
| opts.index | number | | false | the index of the window. |
| opts.path | string | | false | the path to the HTML file to load into the window. |
| opts.title | string | | true | the title of the window. |
| opts.titlebarStyle | string | | true | determines the style of the titlebar (MacOS only). |
| opts.windowControlOffsets | string | | true | a string (split on 'x') provides the x and y position of the traffic lights (MacOS only). |
| opts.backgroundColorDark | string | | true | determines the background color of the window in dark mode. |
| opts.backgroundColorLight | string | | true | determines the background color of the window in light mode. |
| opts.width | number \| string | | true | the width of the window. If undefined, the window will have the main window width. |
| opts.height | number \| string | | true | the height of the window. If undefined, the window will have the main window height. |
| opts.minWidth | number \| string | 0 | true | the minimum width of the window |
| opts.minHeight | number \| string | 0 | true | the minimum height of the window |
| opts.maxWidth | number \| string | 100% | true | the maximum width of the window |
| opts.maxHeight | number \| string | 100% | true | the maximum height of the window |
| opts.resizable | boolean | true | true | whether the window is resizable |
| opts.frameless | boolean | false | true | whether the window is frameless |
| opts.utility | boolean | false | true | whether the window is utility (macOS only) |
| opts.shouldExitApplicationOnClose | boolean | false | true | whether the window can exit the app |
| opts.headless | boolean | false | true | whether the window will be headless or not (no frame) |
| opts.userScript | string | null | true | A user script that will be injected into the window (desktop only) |
| opts.protocolHandlers | string | | true | An array of protocol handler schemes to register with the new window (requires service worker) |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ApplicationWindow> | |
### [`radius()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L270)
### [`margin()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L275)
## [`getScreenSize()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L363)
Returns the current screen size.
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<{ width: number, height: number | >} |
## [`getWindows(indices)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L394)
Returns the ApplicationWindow instances for the given indices or all windows if no indices are provided.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| indices | number | | true | the indices of the windows |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ApplicationWindowList> | |
## [`getWindow(index)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L448)
Returns the ApplicationWindow instance for the given index
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| index | number | | false | the index of the window |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ApplicationWindow> | the ApplicationWindow instance or null if the window does not exist |
## [`getCurrentWindow()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L458)
Returns the ApplicationWindow instance for the current window.
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ApplicationWindow> | |
## [`exit(code)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L467)
Quits the backend process and then quits the render process, the exit code used is the final exit code to the OS.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| code | number | 0 | true | an exit code |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ipc.Result> | |
## [`setSystemMenu(options)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L564)
Set the native menu for the app.
Socket Runtime provides a minimalist DSL that makes it easy to create
cross platform native system and context menus.
Menus are created at run time. They can be created from either the Main or
Render process. The can be recreated instantly by calling the `setSystemMenu` method.
The method takes a string. Here's an example of a menu. The semi colon is
significant indicates the end of the menu. Use an underscore when there is no
accelerator key. Modifiers are optional. And well known OS menu options like
the edit menu will automatically get accelerators you dont need to specify them.
```js
socket.application.setSystemMenu({ index: 0, value: `
App:
Foo: f;
Edit:
Cut: x
Copy: c
Paste: v
Delete: _
Select All: a;
Other:
Apple: _
Another Test: T
!Im Disabled: I
Some Thing: S + Meta
---
Bazz: s + Meta, Control, Alt;
`)
```
Separators
To create a separator, use three dashes `---`.
Accelerator Modifiers
Accelerator modifiers are used as visual indicators but don't have a
material impact as the actual key binding is done in the event listener.
A capital letter implies that the accelerator is modified by the `Shift` key.
Additional accelerators are `Meta`, `Control`, `Option`, each separated
by commas. If one is not applicable for a platform, it will just be ignored.
On MacOS `Meta` is the same as `Command`.
Disabled Items
If you want to disable a menu item just prefix the item with the `!` character.
This will cause the item to appear disabled when the system menu renders.
Submenus
We feel like nested menus are an anti-pattern. We don't use them. If you have a
strong argument for them and a very simple pull request that makes them work we
may consider them.
Event Handling
When a menu item is activated, it raises the `menuItemSelected` event in
the front end code, you can then communicate with your backend code if you
want from there.
For example, if the `Apple` item is selected from the `Other` menu...
```js
window.addEventListener('menuItemSelected', event => {
assert(event.detail.parent === 'Other')
assert(event.detail.title === 'Apple')
})
```
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| options | object | | false | an options object |
| options.value | string | | false | the menu layout |
| options.index | number | | false | the window to target (if applicable) |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ipc.Result> | |
## [`setTrayMenu()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L571)
An alias to setSystemMenu for creating a tary menu
## [`setSystemMenuItemEnabled(value)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L580)
Set the enabled state of the system menu.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| value | object | | false | an options object |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ipc.Result> | |
## [`isPaused()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L588)
Predicate function to determine if application is in a "paused" state.
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | boolean | |
## [runtimeVersion](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L596)
Socket Runtime version.
## [debug](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L602)
Runtime debug flag.
## [config](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L608)
Application configuration.
## [backend](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L613)
The application's backend instance.
### [`open(opts)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L619)
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| opts | object | | false | an options object |
| opts.force | boolean | false | true | whether to force the existing process to close |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ipc.Result> | |
### [`close()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/application.js#L627)
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ipc.Result> | |
<!-- This file is generated by bin/docs-generator/api-module.js -->
<!-- Do not edit this file directly. -->
# [bluetooth](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/bluetooth.js#L12)
A high-level, cross-platform API for Bluetooth Pub-Sub
Example usage:
```js
import { Bluetooth } from 'socket:bluetooth'
```
## [`Bluetooth` (extends `EventEmitter`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/bluetooth.js#L32)
Create an instance of a Bluetooth service.
### [`constructor(serviceId)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/bluetooth.js#L40)
constructor is an example property that is set to `true`
Creates a new service with key-value pairs
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| serviceId | string | | false | Given a default value to determine the type |
### [`start()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/bluetooth.js#L90)
Start the Bluetooth service.
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ipc.Result> | |
### [`subscribe(id)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/bluetooth.js#L119)
Start scanning for published values that correspond to a well-known UUID.
Once subscribed to a UUID, events that correspond to that UUID will be
emitted. To receive these events you can add an event listener, for example...
```js
const ble = new Bluetooth(id)
ble.subscribe(uuid)
ble.on(uuid, (data, details) => {
// ...do something interesting
})
```
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| id | string | | true | A well-known UUID |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<ipc.Result> | |
### [`publish(id, value)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/bluetooth.js#L142)
Start advertising a new value for a well-known UUID
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| id | string | | true | A well-known UUID |
| value | string | | true | |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<void> | |
<!-- This file is generated by bin/docs-generator/api-module.js -->
<!-- Do not edit this file directly. -->
# [crypto](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L15)
Some high-level methods around the `crypto.subtle` API for getting
random bytes and hashing.
Example usage:
```js
import { randomBytes } from 'socket:crypto'
```
## [webcrypto](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L30)
External docs: https://developer.mozilla.org/en-US/docs/Web/API/Crypto
WebCrypto API
## [ready](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L59)
A promise that resolves when all internals to be loaded/ready.
## [`getRandomValues(buffer)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L74)
External docs: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues
Generate cryptographically strong random values into the `buffer`
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| buffer | TypedArray | | false | |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | TypedArray | |
## [`rand64()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L97)
Generate a random 64-bit number.
| Return Value | Type | Description |
| :--- | :--- | :--- |
| A random 64-bit number. | BigInt | |
## [RANDOM_BYTES_QUOTA](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L105)
Maximum total size of random bytes per page
## [MAX_RANDOM_BYTES](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L110)
Maximum total size for random bytes.
## [MAX_RANDOM_BYTES_PAGES](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L115)
Maximum total amount of allocated per page of bytes (max/quota)
## [`randomBytes(size)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L123)
Generate `size` random bytes.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| size | number | | false | The number of bytes to generate. The size must not be larger than 2**31 - 1. |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Buffer | A promise that resolves with an instance of socket.Buffer with random bytes. |
## [`createDigest(algorithm, message)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L150)
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| algorithm | string | | false | `SHA-1` | `SHA-256` | `SHA-384` | `SHA-512` |
| message | Buffer \| TypedArray \| DataView | | false | An instance of socket.Buffer, TypedArray or Dataview. |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise<Buffer> | A promise that resolves with an instance of socket.Buffer with the hash. |
## [`murmur3(value, seed)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/crypto.js#L161)
A murmur3 hash implementation based on https://github.com/jwerle/murmurhash.c
that works on strings and `ArrayBuffer` views (typed arrays)
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| value | string \| Uint8Array \| ArrayBuffer | | false | |
| seed | number | 0 | true | |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | number | |
<!-- This file is generated by bin/docs-generator/api-module.js -->
<!-- Do not edit this file directly. -->
# [dgram](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L13)
This module provides an implementation of UDP datagram sockets. It does
not (yet) provide any of the multicast methods or properties.
Example usage:
```js
import { createSocket } from 'socket:dgram'
```
## [`createSocket(options, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L662)
Creates a `Socket` instance.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| options | string \| Object | | false | either a string ('udp4' or 'udp6') or an options object |
| options.type | string | | true | The family of socket. Must be either 'udp4' or 'udp6'. Required. |
| options.reuseAddr | boolean | false | true | When true socket.bind() will reuse the address, even if another process has already bound a socket on it. Default: false. |
| options.ipv6Only | boolean | false | true | Default: false. |
| options.recvBufferSize | number | | true | Sets the SO_RCVBUF socket value. |
| options.sendBufferSize | number | | true | Sets the SO_SNDBUF socket value. |
| options.signal | AbortSignal | | true | An AbortSignal that may be used to close a socket. |
| callback | function | | true | Attached as a listener for 'message' events. Optional. |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Socket | |
## [`Socket` (extends `EventEmitter`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L668)
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/v0.6.0-rc.6/api/dgram.js#L752)
External docs: https://nodejs.org/api/dgram.html#socketbindport-address-callback
Listen for datagram messages on a named port and optional address
If the address is not specified, the operating system will attempt to
listen on all addresses. Once the binding is complete, a 'listening'
event is emitted and the optional callback function is called.
If binding fails, an 'error' event is emitted.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| port | number | | false | The port to listen for messages on |
| 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/v0.6.0-rc.6/api/dgram.js#L873)
External docs: https://nodejs.org/api/dgram.html#socketconnectport-address-callback
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
will only receive messages from that remote peer. Trying to call connect()
on an already connected socket will result in an ERR_SOCKET_DGRAM_IS_CONNECTED
exception. If the address is not provided, '0.0.0.0' (for udp4 sockets) or '::1'
(for udp6 sockets) will be used by default. Once the connection is complete,
a 'connect' event is emitted and the optional callback function is called.
In case of failure, the callback is called or, failing this, an 'error' event
is emitted.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| port | number | | false | Port the client should connect to. |
| 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/v0.6.0-rc.6/api/dgram.js#L910)
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/v0.6.0-rc.6/api/dgram.js#L969)
External docs: https://nodejs.org/api/dgram.html#socketsendmsg-offset-length-port-address-callback
Broadcasts a datagram on the socket. For connectionless sockets, the
destination port and address must be specified. Connected sockets, on the
other hand, will use their associated remote endpoint, so the port and
address arguments must not be set.
> The msg argument contains the message to be sent. Depending on its type,
different behavior can apply. If msg is a Buffer, any TypedArray, or a
DataView, the offset and length specify the offset within the Buffer where
the message begins and the number of bytes in the message, respectively.
If msg is a String, then it is automatically converted to a Buffer with
'utf8' encoding. With messages that contain multi-byte characters, offset,
and length will be calculated with respect to byte length and not the
character position. If msg is an array, offset and length must not be
specified.
> The address argument is a string. If the value of the address is a hostname,
DNS will be used to resolve the address of the host. If the address is not
provided or otherwise nullish, '0.0.0.0' (for udp4 sockets) or '::1'
(for udp6 sockets) will be used by default.
> If the socket has not been previously bound with a call to bind, the socket
is assigned a random port number and is bound to the "all interfaces"
address ('0.0.0.0' for udp4 sockets, '::1' for udp6 sockets.)
> An optional callback function may be specified as a way of reporting DNS
errors or for determining when it is safe to reuse the buf object. DNS
lookups delay the time to send for at least one tick of the Node.js event
loop.
> The only way to know for sure that the datagram has been sent is by using a
callback. If an error occurs and a callback is given, the error will be
passed as the first argument to the callback. If a callback is not given,
the error is emitted as an 'error' event on the socket object.
> Offset and length are optional but both must be set if either is used.
They are supported only when the first argument is a Buffer, a TypedArray,
or a DataView.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| msg | Buffer \| TypedArray \| DataView \| string \| Array | | false | Message to be sent. |
| offset | integer | | true | Offset in the buffer where the message starts. |
| length | integer | | true | Number of bytes in the message. |
| port | integer | | true | Destination port. |
| 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/v0.6.0-rc.6/api/dgram.js#L1067)
External docs: https://nodejs.org/api/dgram.html#socketclosecallback
Close the underlying socket and stop listening for data on it. If a
callback is provided, it is added as a listener for the 'close' event.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| callback | function | | true | Called when the connection is completed or on error. |
### [`address()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1143)
External docs: https://nodejs.org/api/dgram.html#socketaddress
Returns an object containing the address information for a socket. For
UDP sockets, this object will contain address, family, and port properties.
This method throws EBADF if called on an unbound socket.
| Return Value | Type | Description |
| :--- | :--- | :--- |
| socketInfo | Object | Information about the local socket |
| socketInfo.address | string | The IP address of the socket |
| socketInfo.port | string | The port of the socket |
| socketInfo.family | string | The IP family of the socket |
### [`remoteAddress()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1178)
External docs: https://nodejs.org/api/dgram.html#socketremoteaddress
Returns an object containing the address, family, and port of the remote
endpoint. This method throws an ERR_SOCKET_DGRAM_NOT_CONNECTED exception
if the socket is not connected.
| Return Value | Type | Description |
| :--- | :--- | :--- |
| socketInfo | Object | Information about the remote socket |
| socketInfo.address | string | The IP address of the socket |
| 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/v0.6.0-rc.6/api/dgram.js#L1209)
External docs: https://nodejs.org/api/dgram.html#socketsetrecvbuffersizesize
Sets the SO_RCVBUF socket option. Sets the maximum socket receive buffer in
bytes.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| size | number | | false | The size of the new receive buffer |
### [`setSendBufferSize(size)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1226)
External docs: https://nodejs.org/api/dgram.html#socketsetsendbuffersizesize
Sets the SO_SNDBUF socket option. Sets the maximum socket send buffer in
bytes.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| size | number | | false | The size of the new send buffer |
### [`getRecvBufferSize()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1239)
External docs: https://nodejs.org/api/dgram.html#socketgetrecvbuffersize
### [`getSendBufferSize()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1247)
External docs: https://nodejs.org/api/dgram.html#socketgetsendbuffersize
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | number | the SO_SNDBUF socket send buffer size in bytes. |
### [`code()`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1315)
## [`ERR_SOCKET_ALREADY_BOUND` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1321)
Thrown when a socket is already bound.
## [`ERR_SOCKET_DGRAM_IS_CONNECTED` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1338)
Thrown when the socket is already connected.
## [`ERR_SOCKET_DGRAM_NOT_CONNECTED` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1345)
Thrown when the socket is not connected.
## [`ERR_SOCKET_DGRAM_NOT_RUNNING` (extends `SocketError`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1353)
Thrown when the socket is not running (not bound or connected).
## [`ERR_SOCKET_BAD_TYPE` (extends `TypeError`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1360)
Thrown when a bad socket type is used in an argument.
## [`ERR_SOCKET_BAD_PORT` (extends `RangeError`)](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dgram.js#L1370)
Thrown when a bad port is given.
<!-- This file is generated by bin/docs-generator/api-module.js -->
<!-- Do not edit this file directly. -->
# [dns](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dns/index.js#L17)
This module enables name resolution. For example, use it to look up IP
addresses of host names. Although named for the Domain Name System (DNS),
it does not always use the DNS protocol for lookups. dns.lookup() uses the
operating system facilities to perform name resolution. It may not need to
perform any network communication. To perform name resolution the way other
applications on the same system do, use dns.lookup().
Example usage:
```js
import { lookup } from 'socket:dns'
```
## [`lookup(hostname, options, cb)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dns/index.js#L60)
External docs: https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback
Resolves a host name (e.g. `example.org`) into the first found A (IPv4) or
AAAA (IPv6) record. All option properties are optional. If options is an
integer, then it must be 4 or 6 – if options is 0 or not provided, then IPv4
and IPv6 addresses are both returned if found.
From the node.js website...
> With the all option set to true, the arguments for callback change to (err,
addresses), with addresses being an array of objects with the properties
address and family.
> On error, err is an Error object, where err.code is the error code. Keep in
mind that err.code will be set to 'ENOTFOUND' not only when the host name does
not exist but also when the lookup fails in other ways such as no available
file descriptors. dns.lookup() does not necessarily have anything to do with
the DNS protocol. The implementation uses an operating system facility that
can associate names with addresses and vice versa. This implementation can
have subtle but important consequences on the behavior of any Node.js program.
Please take some time to consult the Implementation considerations section
before using dns.lookup().
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| hostname | string | | false | The host name to resolve. |
| options | object \| intenumberger | | true | An options object or record family. |
| options.family | number \| string | 0 | true | The record family. Must be 4, 6, or 0. For backward compatibility reasons,'IPv4' and 'IPv6' are interpreted as 4 and 6 respectively. The value 0 indicates that IPv4 and IPv6 addresses are both returned. Default: 0. |
| cb | function | | false | The function to call after the method is complete. |
<!-- This file is generated by bin/docs-generator/api-module.js -->
<!-- Do not edit this file directly. -->
# [dns.promises](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dns/promises.js#L17)
This module enables name resolution. For example, use it to look up IP
addresses of host names. Although named for the Domain Name System (DNS),
it does not always use the DNS protocol for lookups. dns.lookup() uses the
operating system facilities to perform name resolution. It may not need to
perform any network communication. To perform name resolution the way other
applications on the same system do, use dns.lookup().
Example usage:
```js
import { lookup } from 'socket:dns/promises'
```
## [`lookup(hostname, opts)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/dns/promises.js#L37)
External docs: https://nodejs.org/api/dns.html#dnspromiseslookuphostname-options
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| hostname | string | | false | The host name to resolve. |
| opts | Object | | true | An options object. |
| opts.family | number \| string | 0 | true | The record family. Must be 4, 6, or 0. For backward compatibility reasons,'IPv4' and 'IPv6' are interpreted as 4 and 6 respectively. The value 0 indicates that IPv4 and IPv6 addresses are both returned. Default: 0. |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Promise | |
<!-- This file is generated by bin/docs-generator/api-module.js -->
<!-- Do not edit this file directly. -->
# [fs](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L26)
This module enables interacting with the file system in a way modeled on
standard POSIX functions.
The Application Sandbox restricts access to the file system.
iOS Application Sandboxing has a set of rules that limits access to the file
system. Apps can only access files in their own sandboxed home directory.
| Directory | Description |
| --- | --- |
| `Documents` | The app’s sandboxed documents directory. The contents of this directory are backed up by iTunes and may be set as accessible to the user via iTunes when `UIFileSharingEnabled` is set to `true` in the application's `info.plist`. |
| `Library` | The app’s sandboxed library directory. The contents of this directory are synchronized via iTunes (except the `Library/Caches` subdirectory, see below), but never exposed to the user. |
| `Library/Caches` | The app’s sandboxed caches directory. The contents of this directory are not synchronized via iTunes and may be deleted by the system at any time. It's a good place to store data which provides a good offline-first experience for the user. |
| `Library/Preferences` | The app’s sandboxed preferences directory. The contents of this directory are synchronized via iTunes. Its purpose is to be used by the Settings app. Avoid creating your own files in this directory. |
| `tmp` | The app’s sandboxed temporary directory. The contents of this directory are not synchronized via iTunes and may be deleted by the system at any time. Although, it's recommended that you delete data that is not necessary anymore manually to minimize the space your app takes up on the file system. Use this directory to store data that is only useful during the app runtime. |
Example usage:
```js
import * as fs from 'socket:fs';
```
## [`access(path, mode, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L111)
External docs: https://nodejs.org/api/fs.html#fsopenpath-flags-mode-callback
Asynchronously check access a file for a given mode calling `callback`
upon success or error.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| mode | string? \| function(Error?)? | F_OK(0) | true | |
| callback | function(Error?)? | | true | |
## [`accessSync(path, mode)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L143)
External docs: https://nodejs.org/api/fs.html#fsopenpath-flags-mode-callback
Synchronously check access a file for a given mode calling `callback`
upon success or error.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| mode | string? | F_OK(0) | true | |
## [`exists(path, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L160)
Checks if a path exists
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| callback | function(Boolean)? | | true | |
## [`existsSync(path, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L177)
Checks if a path exists
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| callback | function(Boolean)? | | true | |
## [`chmod(path, mode, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L197)
External docs: https://nodejs.org/api/fs.html#fschmodpath-mode-callback
Asynchronously changes the permissions of a file.
No arguments other than a possible exception are given to the completion callback
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| mode | number | | false | |
| callback | function(Error?) | | false | |
## [`chmodSync(path, mode)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L232)
External docs: https://nodejs.org/api/fs.html#fschmodpath-mode-callback
Synchronously changes the permissions of a file.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| mode | number | | false | |
## [`chown(path, uid, gid, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L256)
Changes ownership of file or directory at `path` with `uid` and `gid`.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string | | false | |
| uid | number | | false | |
| gid | number | | false | |
| callback | function | | false | |
## [`chownSync(path, uid, gid)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L294)
Changes ownership of file or directory at `path` with `uid` and `gid`.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string | | false | |
| uid | number | | false | |
| gid | number | | false | |
## [`close(fd, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L321)
External docs: https://nodejs.org/api/fs.html#fsclosefd-callback
Asynchronously close a file descriptor calling `callback` upon success or error.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| fd | number | | false | |
| callback | function(Error?)? | | true | |
## [`closeSync(fd)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L341)
Synchronously close a file descriptor.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| fd | number | | false | fd |
## [`copyFile(src, dest, flags, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L358)
External docs: https://nodejs.org/api/fs.html#fscopyfilesrc-dest-mode-callback
Asynchronously copies `src` to `dest` calling `callback` upon success or error.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| src | string | | false | The source file path. |
| dest | string | | false | The destination file path. |
| flags | number | | false | Modifiers for copy operation. |
| callback | function(Error=) | | true | The function to call after completion. |
## [`copyFileSync(src, dest, flags)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L401)
External docs: https://nodejs.org/api/fs.html#fscopyfilesrc-dest-mode-callback
Synchronously copies `src` to `dest` calling `callback` upon success or error.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| src | string | | false | The source file path. |
| dest | string | | false | The destination file path. |
| flags | number | | false | Modifiers for copy operation. |
## [`createReadStream(path, options)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L430)
External docs: https://nodejs.org/api/fs.html#fscreatewritestreampath-options
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| options | object? | | true | |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | ReadStream | |
## [`createWriteStream(path, options)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L475)
External docs: https://nodejs.org/api/fs.html#fscreatewritestreampath-options
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| options | object? | | true | |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | WriteStream | |
## [`fstat(fd, options, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L529)
External docs: https://nodejs.org/api/fs.html#fsfstatfd-options-callback
Invokes the callback with the <fs.Stats> for the file descriptor. See
the POSIX fstat(2) documentation for more detail.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| fd | number | | false | A file descriptor. |
| options | object? \| function? | | true | An options object. |
| callback | function? | | false | The function to call after completion. |
## [`fsync(fd, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L556)
Request that all data for the open file descriptor is flushed
to the storage device.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| fd | number | | false | A file descriptor. |
| callback | function | | false | The function to call after completion. |
## [`ftruncate(fd, offset, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L578)
Truncates the file up to `offset` bytes.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| fd | number | | false | A file descriptor. |
| offset | number= \| function | 0 | true | |
| callback | function? | | false | The function to call after completion. |
## [`lchown(path, uid, gid, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L606)
Chages ownership of link at `path` with `uid` and `gid.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string | | false | |
| uid | number | | false | |
| gid | number | | false | |
| callback | function | | false | |
## [`link(src, dest, )`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L645)
Creates a link to `dest` from `src`.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| src | string | | false | |
| dest | string | | false | |
| (Position 0) | function | | false | |
## [`open(path, flags, mode, options, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L733)
External docs: https://nodejs.org/api/fs.html#fsopenpath-flags-mode-callback
Asynchronously open a file calling `callback` upon success or error.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| flags | string? | r | true | |
| mode | string? | 0o666 | true | |
| options | object? \| function? | | true | |
| callback | function(Error?, number?)? | | true | |
## [`openSync(path, flags, mode, options)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L786)
Synchronously open a file.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| flags | string? | r | true | |
| mode | string? | 0o666 | true | |
| options | object? \| function? | | true | |
## [`opendir(path, options, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L833)
External docs: https://nodejs.org/api/fs.html#fsreaddirpath-options-callback
Asynchronously open a directory calling `callback` upon success or error.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| options | object? \| function(Error?, Dir?) | | true | |
| options.encoding | string? | utf8 | true | |
| options.withFileTypes | boolean? | false | true | |
| callback | function(Error?, Dir?)? | | false | |
## [`opendirSync(path, options)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L860)
External docs: https://nodejs.org/api/fs.html#fsreaddirpath-options-callback
Synchronously open a directory.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| options | object? \| function(Error?, Dir?) | | true | |
| options.encoding | string? | utf8 | true | |
| options.withFileTypes | boolean? | false | true | |
| Return Value | Type | Description |
| :--- | :--- | :--- |
| Not specified | Dir | |
## [`read(fd, buffer, offset, length, position, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L887)
External docs: https://nodejs.org/api/fs.html#fsreadfd-buffer-offset-length-position-callback
Asynchronously read from an open file descriptor.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| fd | number | | false | |
| buffer | object \| Buffer \| TypedArray | | false | The buffer that the data will be written to. |
| offset | number | | false | The position in buffer to write the data to. |
| length | number | | false | The number of bytes to read. |
| position | number \| BigInt \| null | | false | Specifies where to begin reading from in the file. If position is null or -1 , data will be read from the current file position, and the file position will be updated. If position is an integer, the file position will be unchanged. |
| callback | function(Error?, number?, Buffer?) | | false | |
## [`write(fd, buffer, offset, length, position, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L922)
External docs: https://nodejs.org/api/fs.html#fswritefd-buffer-offset-length-position-callback
Asynchronously write to an open file descriptor.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| fd | number | | false | |
| buffer | object \| Buffer \| TypedArray | | false | The buffer that the data will be written to. |
| offset | number | | false | The position in buffer to write the data to. |
| length | number | | false | The number of bytes to read. |
| position | number \| BigInt \| null | | false | Specifies where to begin reading from in the file. If position is null or -1 , data will be read from the current file position, and the file position will be updated. If position is an integer, the file position will be unchanged. |
| callback | function(Error?, number?, Buffer?) | | false | |
## [`readdir(path, options, callback)`](https://github.com/socketsupply/socket/blob/v0.6.0-rc.6/api/fs/index.js#L956)
External docs: https://nodejs.org/api/fs.html#fsreaddirpath-options-callback
Asynchronously read all entries in a directory.
| Argument | Type | Default | Optional | Description |
| :--- | :--- | :---: | :---: | :--- |
| path | string \| Buffer \| URL | | false | |
| options | object? \| function(Error?, object) | | true | |
| options.encoding ? utf8 | string? | | true | |
| options.withFileTypes ? false | boolean? | | true | |
| callback | function(Error?, object) | | false |