Application

Provides Application level methods

Example usage:

import { createWindow } from 'socket:application'

createWindow(opts)

Creates a new window and returns an instance of ApplicationWindow.

getScreenSize()

Returns the current screen size.

getWindows(indices)

Returns the ApplicationWindow instances for the given indices or all windows if no indices are provided.

getWindow(index)

Returns the ApplicationWindow instance for the given index

getCurrentWindow()

Returns the ApplicationWindow instance for the current window.

exit(code)

Quits the backend process and then quits the render process, the exit code used is the final exit code to the OS.

setSystemMenu(options)

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.

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...

window.addEventListener('menuItemSelected', event => {
  assert(event.detail.parent === 'Other')
  assert(event.detail.title === 'Apple')
})

setSystemMenuItemEnabled(value)

Set the enabled state of the system menu.

runtimeVersion

Socket Runtime version.

debug

Runtime debug flag.

config

Application configuration.

backend

The application's backend instance.

open(opts)

close()

Bluetooth

A high-level, cross-platform API for Bluetooth Pub-Sub

Example usage:

import { Bluetooth } from 'socket:bluetooth'

Bluetooth (extends EventEmitter)

Create an instance of a Bluetooth service.

constructor(serviceId)

constructor is an example property that is set to true Creates a new service with key-value pairs

start()

Start the Bluetooth service.

subscribe(id )

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...

const ble = new Bluetooth(id)
ble.subscribe(uuid)
ble.on(uuid, (data, details) => {
  // ...do something interesting
})

publish(id, value)

Start advertising a new value for a well-known UUID

Crypto

Some high-level methods around the crypto.subtle API for getting random bytes and hashing.

Example usage:

import { randomBytes } from 'socket:crypto'

webcrypto

WebCrypto API

ready

A promise that resolves when all internals to be loaded/ready.

getRandomValues(buffer)

External docs: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues

Generate cryptographically strong random values into the buffer

rand64()

This is a FunctionDeclaration named rand64 in api/crypto.js, it's exported but undocumented.

RANDOM_BYTES_QUOTA

Maximum total size of random bytes per page

MAX_RANDOM_BYTES

Maximum total size for random bytes.

MAX_RANDOM_BYTES_PAGES

Maximum total amount of allocated per page of bytes (max/quota)

randomBytes(size)

Generate size random bytes.

createDigest(algorithm, message)

Dgram

This module provides an implementation of UDP datagram sockets. It does not (yet) provide any of the multicast methods or properties.

Example usage:

import { createSocket } from 'socket:dgram'

createSocket(options, callback)

Creates a Socket instance.

Socket (extends EventEmitter)

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)

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.

connect(port, host, connectListener)

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.

disconnect()

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)

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.

close(callback)

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.

address()

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.

remoteAddress()

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.

setRecvBufferSize(size)

External docs: https://nodejs.org/api/dgram.html#socketsetrecvbuffersizesize

Sets the SO_RCVBUF socket option. Sets the maximum socket receive buffer in bytes.

setSendBufferSize(size)

External docs: https://nodejs.org/api/dgram.html#socketsetsendbuffersizesize

Sets the SO_SNDBUF socket option. Sets the maximum socket send buffer in bytes.

getRecvBufferSize()

External docs: https://nodejs.org/api/dgram.html#socketgetrecvbuffersize

getSendBufferSize()

External docs: https://nodejs.org/api/dgram.html#socketgetsendbuffersize

ERR_SOCKET_ALREADY_BOUND (extends SocketError)

Thrown when a socket is already bound.

ERR_SOCKET_DGRAM_IS_CONNECTED (extends SocketError)

Thrown when the socket is already connected.

ERR_SOCKET_DGRAM_NOT_CONNECTED (extends SocketError)

Thrown when the socket is not connected.

ERR_SOCKET_DGRAM_NOT_RUNNING (extends SocketError)

Thrown when the socket is not running (not bound or connected).

ERR_SOCKET_BAD_TYPE (extends TypeError)

Thrown when a bad socket type is used in an argument.

ERR_SOCKET_BAD_PORT (extends RangeError)

Thrown when a bad port is given.

DNS

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:

import { lookup } from 'socket:dns'

lookup(hostname, opts, cb)

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().

DNS.promises

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:

import { lookup } from 'socket:dns/promises'

lookup(hostname, opts)

External docs: https://nodejs.org/api/dns.html#dnspromiseslookuphostname-options

Event

This is a VariableDeclaration named Event in api/events.js, it's exported but undocumented.

CustomEvent

This is a VariableDeclaration named CustomEvent in api/events.js, it's exported but undocumented.

MessageEvent

This is a VariableDeclaration named MessageEvent in api/events.js, it's exported but undocumented.

ErrorEvent

This is a VariableDeclaration named ErrorEvent in api/events.js, it's exported but undocumented.

File System

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.

Example usage:

import * as fs from 'socket:fs';

access(path, mode , callback)

External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fsopenpath-flags-mode-callback

Asynchronously check access a file for a given mode calling callback upon success or error.

chmod(path, mode, callback)

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

close(fd, callback)

Asynchronously close a file descriptor calling callback upon success or error.

copyFile()

This is a FunctionDeclaration named copyFile in api/fs/index.js, it's exported but undocumented.

createReadStream(path, options)

External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fscreatewritestreampath-options

createWriteStream(path, options)

External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fscreatewritestreampath-options

fstat(fd, options, callback)

External docs: https://nodejs.org/dist/latest-v16.x/docs/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.

open(path, flags , mode , callback)

Asynchronously open a file calling callback upon success or error.

opendir(path, options, callback)

Asynchronously open a directory calling callback upon success or error.

read(fd, buffer, offset, length, position, callback)

Asynchronously read from an open file descriptor.

readdir(path, options, callback)

Asynchronously read all entries in a directory.

readFile(path, options, callback)

stat(path, options, callback)

writeFile(path, data, options, callback)

writev()

This is a FunctionDeclaration named writev in api/fs/index.js, it's exported but undocumented.

FS.promises

• 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.

Example usage:

import fs from 'socket:fs/promises'

access(path, mode, options)

External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesaccesspath-mode

Asynchronously check access a file.

chmod(path, mode)

External docs: https://nodejs.org/api/fs.html#fspromiseschmodpath-mode

mkdir(path, options)

Asynchronously creates a directory.

open(path, flags, mode)

External docs: https://nodejs.org/api/fs.html#fspromisesopenpath-flags-mode

Asynchronously open a file.

opendir(path, options)

External docs: https://nodejs.org/api/fs.html#fspromisesopendirpath-options

readdir(path, options)

External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesreaddirpath-options

readFile(path, options)

External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromisesreadfilepath-options

stat(path, options)

External docs: https://nodejs.org/api/fs.html#fspromisesstatpath-options

writeFile(path, data, options)

External docs: https://nodejs.org/dist/latest-v16.x/docs/api/fs.html#fspromiseswritefilefile-data-options

IPC

This is a low-level API that you don't need unless you are implementing a library on top of Socket SDK. A Socket SDK app has two or three processes.

• The Render process, is the UI where the HTML, CSS, and JS are run.
• The Bridge process, is the thin layer of code that manages everything.
• The Main process, is for apps that need to run heavier compute jobs. And unlike electron it's optional.

The Bridge process manages the Render and Main process, it may also broker data between them.

The Binding process uses standard input and output as a way to communicate. Data written to the write-end of the pipe is buffered by the OS until it is read from the read-end of the pipe.

The IPC protocol uses a simple URI-like scheme. Data is passed as ArrayBuffers.

ipc://command?key1=value1&key2=value2...

Example usage:

import { send } from 'socket:ipc'

emit(name, value, target , options)

Emit event to be dispatched on window object.

send(command, value, options)

Sends an async IPC command request with parameters.

OS

This module provides normalized system information from all the major operating systems.

Example usage:

import { arch, platform } from 'socket:os'

arch()

This is a FunctionDeclaration named arch in api/os.js, it's exported but undocumented.

cpus()

This is a FunctionDeclaration named cpus in api/os.js, it's exported but undocumented.

networkInterfaces()

This is a FunctionDeclaration named networkInterfaces in api/os.js, it's exported but undocumented.

platform()

This is a FunctionDeclaration named platform in api/os.js, it's exported but undocumented.

type()

This is a FunctionDeclaration named type in api/os.js, it's exported but undocumented.

isWindows()

This is a FunctionDeclaration named isWindows in api/os.js, it's exported but undocumented.

tmpdir()

This is a FunctionDeclaration named tmpdir in api/os.js, it's exported but undocumented.

EOL

This is a VariableDeclaration named EOL in api/os.js, it's exported but undocumented.

rusage()

This is a FunctionDeclaration named rusage in api/os.js, it's exported but undocumented.

uptime()

This is a FunctionDeclaration named uptime in api/os.js, it's exported but undocumented.

uname()

This is a FunctionDeclaration named uname in api/os.js, it's exported but undocumented.

hrtime()

This is a FunctionDeclaration named hrtime in api/os.js, it's exported but undocumented.

availableMemory()

This is a FunctionDeclaration named availableMemory in api/os.js, it's exported but undocumented.

Peer

External docs: https://socketsupply.co/guides/#p2p-guide

Provides a higher level API over the stream-relay protocol.

Example usage:

import { Peer } from 'socket:peer'

Peer (extends EventEmitter)

The Peer class is an EventEmitter. It emits events when new network events are received (.on), it can also emit new events to the network (.emit).

import { Peer } from 'socket:peer'

const pair = await Peer.createKeys()
const clusterId = await Peer.createClusterId()

const peer = new Peer({ ...pair, clusterId })

peer.on('greeting', (value, peer, address, port) => {
  console.log(value)
})

window.addEventListener('load', () => {
  const value = { english: 'hello, world' }
  const packet = await peer.emit('greeting', value)
}, { once: true }})

constructor(options)

Peer class constructor.

createKeys()

A method that will generate a public and private key pair. The ed25519 pair can be stored by an app with a secure API.

createClusterId()

Create a clusterId from random bytes

emit(event, message)

Emits a message to the network

join()

Starts the process of connecting to the network.

Path

Example usage:

import { Path } from 'socket:path'

Path (extends URL)

A container for a parsed Path.

cwd(opts)

Computes current working directory for a path

resolve(options, components)

Resolves path components to an absolute path.

relative(options, from, to)

Computes the relative path from from to to.

join(options, components)

Joins path components. This function may not return an absolute path.

dirname(options, components)

Computes directory name of path.

basename(options, components)

Computes base name of path.

extname(options, path)

Computes extension name of path.

normalize(options, path)

Computes normalized path

format(options, path)

Formats Path object into a string.

parse(path)

Parses input path into a Path instance.

from(input, cwd)

Creates a Path instance from input and optional cwd.

constructor(pathname, cwd )

Path class constructor.

isRelative()

true if the path is relative, otherwise `false.

value()

The working value of this path.

source()

The original source, unresolved.

parent()

Computed parent path.

root()

Computed root in path.

dir()

Computed directory name in path.

base()

Computed base name in path.

name()

Computed base name in path without path extension.

ext()

Computed extension name in path.

drive()

The computed drive, if given in the path.

toURL()

toString()

Converts this Path instance to a string.

Process

Example usage:

import process from 'socket:process'

nextTick()

This is a FunctionDeclaration named nextTick in api/process.js, it's exported but undocumented.

homedir()

hrtime(time)

Computed high resolution time as a BigInt.

exit(code)

memoryUsage()

This is a FunctionDeclaration named memoryUsage in api/process.js, it's exported but undocumented.

Window

External docs: module:Application Application

Provides ApplicationWindow class and methods

Usaully you don't need to use this module directly, instance of ApplicationWindow are returned by the methods of the {@link module:Application Application} module.

ApplicationWindow

Represents a window in the application

index()

Get the index of the window

getSize()

Get the size of the window

getTitle()

Get the title of the window

getStatus()

Get the status of the window

close()

Close the window

show()

Shows the window

hide()

Hides the window

setTitle(title)

Sets the title of the window

setSize(opts)

Sets the size of the window

navigate(path)

Navigate the window to a given path

showInspector()

Opens the Web Inspector for the window

setBackgroundColor(opts)

Sets the background color of the window

setContextMenu(options)

Opens a native context menu.

showOpenFilePicker(options)

Shows a native open file dialog.

showSaveFilePicker(options)

Shows a native save file dialog.

showDirectoryFilePicker(options)

Shows a native directory dialog.

send(options)

Sends an IPC message to the window or to qthe backend.

openExternal(options)

Opens an URL in the default browser.

addListener(event, cb)

Adds a listener to the window.

on(event, cb)

Adds a listener to the window. An alias for addListener.

once(event, cb)

Adds a listener to the window. The listener is removed after the first call.

removeListener(event, cb)

Removes a listener from the window.

removeAllListeners(event)

Removes all listeners from the window.

off(event, cb)

Removes a listener from the window. An alias for removeListener.

constants

This is a VariableDeclaration named constants in api/window.js, it's exported but undocumented.