Documentation / @xo-cash/sync-client

Installation

git clone hgit@gitlab.com:GeneralProtocols/xo/sync-client.git
cd sync-client
npm ci

Running

There are 2 examples in the demo folder.

The suite will run general read/write operations on various clients.
The tui will allow you to write values into the console as well as monitor for updates.
npx tsx ./demo/suite.ts - Optionally, add sse | ws | encryped | encryptedPerResource to select a specific implementation to test. Defaults to all clients.
npx tsx ./demo/tui.ts - Optionally add false to use a SSE without encryption. Default is EncryptedClientPerResource

`abstract` BaseSyncClient

Defined in: source/shared/base-client.ts:30

A simple event emitter implementation.

Extends

EventEmitter<XOSyncClientEventMap<T>>

Type Parameters

Type Parameter	Default type	Description
`T`	`unknown`	The event map type.

Constructors

Constructor

new BaseSyncClient<T>(): BaseSyncClient<T>;

Returns

BaseSyncClient<T>

Inherited from

EventEmitter.constructor

Methods

connect()

abstract connect(): Promise<void>;

Defined in: source/shared/base-client.ts:34

Connects to the sync server

Returns

Promise<void>

disconnect()

abstract disconnect(): Promise<void>;

Defined in: source/shared/base-client.ts:39

Disconnects from the sync server

Returns

Promise<void>

emit()

emit<K>(type, payload): boolean;

Defined in: utils/dist/index.d.mts:70

Emit an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`T`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`payload`	`XOSyncClientEventMap`<`T`>[`K`]	The event payload.

Returns

boolean

True if there are listeners for the event, false otherwise.

Remarks

The caller is responsible for ensuring the payload suits the intended mutability requirements. By default, the payload will be mutable, so listeners may mutate the payload, effecting both the original object and the other listeners. To prevent this, the caller can use the Object.freeze or deepFreeze function to freeze the payload. This will need to be defined in the EventMap using the built-in Readonly type or the provided DeeplyReadonly type.

Inherited from

EventEmitter.emit

off()

off<K>(type, listener?): void;

Defined in: utils/dist/index.d.mts:56

Remove a listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`T`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener?`	`Listener`<`XOSyncClientEventMap`<`T`>[`K`]>	The listener function.

Returns

void

Inherited from

EventEmitter.off

on()

on<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: utils/dist/index.d.mts:42

Add a listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`T`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener`	`Listener`<`XOSyncClientEventMap`<`T`>[`K`]>	The listener function.
`debounceMilliseconds?`	`number`	The debounce time in milliseconds.

Returns

OffCallback

An off callback that can be called to stop listening for events.

Inherited from

EventEmitter.on

once()

once<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: utils/dist/index.d.mts:50

Add a one-time listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`T`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener`	`Listener`<`XOSyncClientEventMap`<`T`>[`K`]>	The listener function.
`debounceMilliseconds?`	`number`	The debounce time in milliseconds.

Returns

OffCallback

An off callback that can be called to stop listening for events.

Inherited from

EventEmitter.once

read()

read(resourceId): Promise<Resource<T>[]>;

Defined in: source/shared/base-client.ts:75

Reads a value from a resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to read from

Returns

Promise<Resource<T>[]>

The resource with the read value

readMany()

abstract readMany(resourceIds): Promise<ResourcesRecord<T>>;

Defined in: source/shared/base-client.ts:96

Reads multiple values from resources

Parameters

Parameter	Type	Description
`resourceIds`	`string`[]	The resource IDs to read from

Returns

Promise<ResourcesRecord<T>>

The resources with the read values

removeAllListeners()

removeAllListeners(): void;

Defined in: utils/dist/index.d.mts:74

Remove all listeners.

Returns

void

Inherited from

EventEmitter.removeAllListeners

abstract subscribe(resourceId): Promise<void>;

Defined in: source/shared/base-client.ts:102

Subscribes to a resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to subscribe to

Returns

Promise<void>

unsubscribe()

abstract unsubscribe(resourceId): Promise<void>;

Defined in: source/shared/base-client.ts:108

Unsubscribes from a resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to unsubscribe from

Returns

Promise<void>

waitFor()

waitFor<K>(
   type, 
   predicate, 
   timeoutMs?): Promise<XOSyncClientEventMap<T>[K]>;

Defined in: utils/dist/index.d.mts:82

Wait for an event to be emitted that matches the provided predicate function's criteria.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`T`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`predicate`	(`payload`) => `boolean`	Predicate function to filter for whether the event payload matches the criteria.
`timeoutMs?`	`number`	The timeout in milliseconds.

Returns

Promise<XOSyncClientEventMap<T>[K]>

The event payload.

Inherited from

EventEmitter.waitFor

write()

write(resourceId, value): Promise<Resource<T>[]>;

Defined in: source/shared/base-client.ts:47

Sign and write one resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to write to
`value`	`T`	The value to write

Returns

Promise<Resource<T>[]>

The Resource Object with the decoded value

writeMany()

abstract writeMany(resources): Promise<ResourcesRecord<T>>;

Defined in: source/shared/base-client.ts:68

Writes multiple values to resources

Parameters

Parameter	Type	Description
`resources`	`Record`<`string`, `T`>	The resources to write to

Returns

Promise<ResourcesRecord<T>>

The resources with the written values

decodeBlobValue()

static decodeBlobValue<T>(instance): Resource<T>;

Defined in: source/shared/base-client.ts:236

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`instance`	{ `blob`: `Uint8Array`<`ArrayBuffer`>; `publicKey`: `string`; `resourceId`: `string`; `signature`: `string`; `timestamp`: `number`; }
`instance.blob`	`Uint8Array`<`ArrayBuffer`>
`instance.publicKey`	`string`
`instance.resourceId`	`string`
`instance.signature`	`string`
`instance.timestamp`	`number`

Returns

Resource<T>

decodeResourcesResponse()

static decodeResourcesResponse<T>(response): ResourcesRecord<T>;

Defined in: source/shared/base-client.ts:215

Decodes the 'blob' field of the Resource Object from the server from a read/write

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type	Description
`response`	{ `resources`: `z.ZodRecord`<`z.ZodString`, `z.ZodObject`<{ `instances`: `z.ZodArray`<`z.ZodObject`<{ `blob`: `z.ZodCustom`<`Uint8Array`<`ArrayBuffer`>, `Uint8Array`<`ArrayBuffer`>>; `publicKey`: `z.ZodString`; `resourceId`: `z.ZodString`; `signature`: `z.ZodString`; `timestamp`: `z.ZodNumber`; }, `z.core.$strip`>>; }, `z.core.$strip`>>; }	The ResourceResponse Object from the server from a read/write
`response.resources`	`z.ZodRecord`<`z.ZodString`, `z.ZodObject`<{ `instances`: `z.ZodArray`<`z.ZodObject`<{ `blob`: `z.ZodCustom`<`Uint8Array`<`ArrayBuffer`>, `Uint8Array`<`ArrayBuffer`>>; `publicKey`: `z.ZodString`; `resourceId`: `z.ZodString`; `signature`: `z.ZodString`; `timestamp`: `z.ZodNumber`; }, `z.core.$strip`>>; }, `z.core.$strip`>>	-

Returns

ResourcesRecord<T>

The Resource Object with the decoded value

deriveResourcePrivateKey()

static deriveResourcePrivateKey(privateKey, resourceId): Uint8Array;

Defined in: source/shared/base-client.ts:116

Derives the resource private key from the private key and resource ID

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to derive the resource private key from
`resourceId`	`string`	The resource ID to derive the resource private key from

Returns

Uint8Array

The resource private key

signPayload()

static signPayload(privateKey, payload): SignedPayload;

Defined in: source/shared/base-client.ts:130

Signs a payload with the private key and returns the public key and signature

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the payload with
`payload`	`string`	The payload to sign

Returns

SignedPayload

The public key and signature

signRequest()

static signRequest(
   privateKey, 
   path, 
   body): AuthenticatedRequestHeaders;

Defined in: source/shared/base-client.ts:190

Signs a request with the private key and returns the public key, timestamp, and signature

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the request with
`path`	`string`	The path of the request
`body`	`unknown`	The body of the request

Returns

AuthenticatedRequestHeaders

The public key, timestamp, and signature

signWriteRequest()

static signWriteRequest(
   privateKey, 
   resourceId, 
   value): WriteRequest;

Defined in: source/shared/base-client.ts:163

Signs a write request with the private key and returns the write request

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the write request with
`resourceId`	`string`	The resource ID to write to
`value`	`Uint8Array`	The value to write

Returns

WriteRequest

The write request

SSEClient

Defined in: source/sse/client.ts:6

A simple event emitter implementation.

Extends

BaseSyncClient<PayloadType>

Type Parameters

Type Parameter	Default type	Description
`PayloadType`	`unknown`	The event map type.

Constructors

Constructor

new SSEClient<PayloadType>(url, privateKey): SSEClient<PayloadType>;

Defined in: source/sse/client.ts:23

Creates a new SSE client

Parameters

Parameter	Type	Description
`url`	`string`	The URL of the server
`privateKey`	`PrivateKey`	The private key to use for authentication

Returns

SSEClient<PayloadType>

Overrides

BaseSyncClient.constructor

Methods

connect()

connect(): Promise<void>;

Defined in: source/sse/client.ts:44

Connects to the server

Returns

Promise<void>

Overrides

BaseSyncClient.connect

disconnect()

disconnect(): Promise<void>;

Defined in: source/sse/client.ts:59

Disconnects from the server

Returns

Promise<void>

Overrides

BaseSyncClient.disconnect

emit()

emit<K>(type, payload): boolean;

Defined in: utils/dist/index.d.mts:70

Emit an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`payload`	`XOSyncClientEventMap`<`PayloadType`>[`K`]	The event payload.

Returns

boolean

True if there are listeners for the event, false otherwise.

Remarks

Inherited from

BaseSyncClient.emit

handleOnConnectionUpdated()

handleOnConnectionUpdated(value): Promise<void>;

Defined in: source/sse/client.ts:215

Parameters

Parameter	Type
`value`	`"connected"` \| `"disconnected"`

Returns

Promise<void>

off()

off<K>(type, listener?): void;

Defined in: utils/dist/index.d.mts:56

Remove a listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener?`	`Listener`<`XOSyncClientEventMap`<`PayloadType`>[`K`]>	The listener function.

Returns

void

Inherited from

BaseSyncClient.off

on()

on<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: utils/dist/index.d.mts:42

Add a listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener`	`Listener`<`XOSyncClientEventMap`<`PayloadType`>[`K`]>	The listener function.
`debounceMilliseconds?`	`number`	The debounce time in milliseconds.

Returns

OffCallback

An off callback that can be called to stop listening for events.

Inherited from

BaseSyncClient.on

once()

once<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: utils/dist/index.d.mts:50

Add a one-time listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener`	`Listener`<`XOSyncClientEventMap`<`PayloadType`>[`K`]>	The listener function.
`debounceMilliseconds?`	`number`	The debounce time in milliseconds.

Returns

OffCallback

An off callback that can be called to stop listening for events.

Inherited from

BaseSyncClient.once

read()

read(resourceId): Promise<Resource<PayloadType>[]>;

Defined in: source/shared/base-client.ts:75

Reads a value from a resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to read from

Returns

Promise<Resource<PayloadType>[]>

The resource with the read value

Inherited from

BaseSyncClient.read

readMany()

readMany(resourceIds): Promise<ResourcesRecord<PayloadType>>;

Defined in: source/sse/client.ts:177

Send a POST /data/read request to the server

Parameters

Parameter	Type	Description
`resourceIds`	`string`[]	The resource IDs to read

Returns

Promise<ResourcesRecord<PayloadType>>

The resources with the read values

Overrides

BaseSyncClient.readMany

reconnect()

reconnect(): Promise<void>;

Defined in: source/sse/client.ts:66

Reconnects to the server

Returns

Promise<void>

removeAllListeners()

removeAllListeners(): void;

Defined in: utils/dist/index.d.mts:74

Remove all listeners.

Returns

void

Inherited from

BaseSyncClient.removeAllListeners

subscribe(resourceId): Promise<void>;

Defined in: source/sse/client.ts:199

Destroy the current SSE Session, then re-create it with the additional resource ID in the subscription list

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to add to the subscription list

Returns

Promise<void>

Overrides

BaseSyncClient.subscribe

unsubscribe()

unsubscribe(resourceId): Promise<void>;

Defined in: source/sse/client.ts:209

Destroy the current SSE Session, then re-create it without the resource ID in the subscription list

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to remove from the subscription list

Returns

Promise<void>

Overrides

BaseSyncClient.unsubscribe

waitFor()

waitFor<K>(
   type, 
   predicate, 
   timeoutMs?): Promise<XOSyncClientEventMap<PayloadType>[K]>;

Defined in: utils/dist/index.d.mts:82

Wait for an event to be emitted that matches the provided predicate function's criteria.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`predicate`	(`payload`) => `boolean`	Predicate function to filter for whether the event payload matches the criteria.
`timeoutMs?`	`number`	The timeout in milliseconds.

Returns

Promise<XOSyncClientEventMap<PayloadType>[K]>

The event payload.

Inherited from

BaseSyncClient.waitFor

write()

write(resourceId, value): Promise<Resource<PayloadType>[]>;

Defined in: source/shared/base-client.ts:47

Sign and write one resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to write to
`value`	`PayloadType`	The value to write

Returns

Promise<Resource<PayloadType>[]>

The Resource Object with the decoded value

Inherited from

BaseSyncClient.write

writeMany()

writeMany(resources): Promise<ResourcesRecord<PayloadType>>;

Defined in: source/sse/client.ts:145

Send a POST /data/write request to the server

Parameters

Parameter	Type	Description
`resources`	`Record`<`string`, `PayloadType`>	The resources to write

Returns

Promise<ResourcesRecord<PayloadType>>

The Resource Object with the decoded value

Overrides

BaseSyncClient.writeMany

decodeBlobValue()

static decodeBlobValue<T>(instance): Resource<T>;

Defined in: source/shared/base-client.ts:236

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`instance`	{ `blob`: `Uint8Array`<`ArrayBuffer`>; `publicKey`: `string`; `resourceId`: `string`; `signature`: `string`; `timestamp`: `number`; }
`instance.blob`	`Uint8Array`<`ArrayBuffer`>
`instance.publicKey`	`string`
`instance.resourceId`	`string`
`instance.signature`	`string`
`instance.timestamp`	`number`

Returns

Resource<T>

Inherited from

BaseSyncClient.decodeBlobValue

decodeResourcesResponse()

static decodeResourcesResponse<T>(response): ResourcesRecord<T>;

Defined in: source/shared/base-client.ts:215

Decodes the 'blob' field of the Resource Object from the server from a read/write

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type	Description
`response`	{ `resources`: `z.ZodRecord`<`z.ZodString`, `z.ZodObject`<{ `instances`: `z.ZodArray`<`z.ZodObject`<{ `blob`: `z.ZodCustom`<`Uint8Array`<`ArrayBuffer`>, `Uint8Array`<`ArrayBuffer`>>; `publicKey`: `z.ZodString`; `resourceId`: `z.ZodString`; `signature`: `z.ZodString`; `timestamp`: `z.ZodNumber`; }, `z.core.$strip`>>; }, `z.core.$strip`>>; }	The ResourceResponse Object from the server from a read/write
`response.resources`	`z.ZodRecord`<`z.ZodString`, `z.ZodObject`<{ `instances`: `z.ZodArray`<`z.ZodObject`<{ `blob`: `z.ZodCustom`<`Uint8Array`<`ArrayBuffer`>, `Uint8Array`<`ArrayBuffer`>>; `publicKey`: `z.ZodString`; `resourceId`: `z.ZodString`; `signature`: `z.ZodString`; `timestamp`: `z.ZodNumber`; }, `z.core.$strip`>>; }, `z.core.$strip`>>	-

Returns

ResourcesRecord<T>

The Resource Object with the decoded value

Inherited from

BaseSyncClient.decodeResourcesResponse

deriveResourcePrivateKey()

static deriveResourcePrivateKey(privateKey, resourceId): Uint8Array;

Defined in: source/shared/base-client.ts:116

Derives the resource private key from the private key and resource ID

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to derive the resource private key from
`resourceId`	`string`	The resource ID to derive the resource private key from

Returns

Uint8Array

The resource private key

Inherited from

BaseSyncClient.deriveResourcePrivateKey

signPayload()

static signPayload(privateKey, payload): SignedPayload;

Defined in: source/shared/base-client.ts:130

Signs a payload with the private key and returns the public key and signature

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the payload with
`payload`	`string`	The payload to sign

Returns

SignedPayload

The public key and signature

Inherited from

BaseSyncClient.signPayload

signRequest()

static signRequest(
   privateKey, 
   path, 
   body): AuthenticatedRequestHeaders;

Defined in: source/shared/base-client.ts:190

Signs a request with the private key and returns the public key, timestamp, and signature

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the request with
`path`	`string`	The path of the request
`body`	`unknown`	The body of the request

Returns

AuthenticatedRequestHeaders

The public key, timestamp, and signature

Inherited from

BaseSyncClient.signRequest

signWriteRequest()

static signWriteRequest(
   privateKey, 
   resourceId, 
   value): WriteRequest;

Defined in: source/shared/base-client.ts:163

Signs a write request with the private key and returns the write request

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the write request with
`resourceId`	`string`	The resource ID to write to
`value`	`Uint8Array`	The value to write

Returns

WriteRequest

The write request

Inherited from

BaseSyncClient.signWriteRequest

WsClient

Defined in: source/ws/client.ts:42

Minimal WebSocket client for the XO sync server.

one connection is opened at /ws, on demand: every request awaits the connection first, so callers never need to wait for one themselves;
request IDs correlate concurrent read/write/unsubscribe calls;
subscriptions are remembered and re-sent on every new socket, because the server drops a socket's topics when it closes; and
a dropped connection fails pending requests and is reopened with backoff until disconnect() is called. Requests made in the meantime wait for it.

Heartbeats and request timeouts are not implemented.

Extends

BaseSyncClient<PayloadType>

Type Parameters

Type Parameter	Default type
`PayloadType`	`unknown`

Constructors

Constructor

new WsClient<PayloadType>(
   url, 
   privateKey, 
   options?): WsClient<PayloadType>;

Defined in: source/ws/client.ts:65

Parameters

Parameter	Type
`url`	`string`
`privateKey`	`PrivateKey`
`options?`	`Partial`<`WsClientOptions`>

Returns

WsClient<PayloadType>

Overrides

BaseSyncClient.constructor

Methods

connect()

connect(): Promise<void>;

Defined in: source/ws/client.ts:75

Connect, and keep reconnecting on drops until disconnect() is called.

Returns

Promise<void>

Overrides

BaseSyncClient.connect

disconnect()

disconnect(): Promise<void>;

Defined in: source/ws/client.ts:88

Close the socket and stop reconnecting.

Closing a WebSocket automatically removes all of its server-side topics, so disconnect does not need to send an unsubscribe request first. Subscriptions are kept, and are replayed if the client connects again.

Resolves without waiting for the socket to finish closing; connection-updated fires when it does.

Returns

Promise<void>

Overrides

BaseSyncClient.disconnect

emit()

emit<K>(type, payload): boolean;

Defined in: utils/dist/index.d.mts:70

Emit an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`payload`	`XOSyncClientEventMap`<`PayloadType`>[`K`]	The event payload.

Returns

boolean

True if there are listeners for the event, false otherwise.

Remarks

Inherited from

BaseSyncClient.emit

off()

off<K>(type, listener?): void;

Defined in: utils/dist/index.d.mts:56

Remove a listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener?`	`Listener`<`XOSyncClientEventMap`<`PayloadType`>[`K`]>	The listener function.

Returns

void

Inherited from

BaseSyncClient.off

on()

on<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: utils/dist/index.d.mts:42

Add a listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener`	`Listener`<`XOSyncClientEventMap`<`PayloadType`>[`K`]>	The listener function.
`debounceMilliseconds?`	`number`	The debounce time in milliseconds.

Returns

OffCallback

An off callback that can be called to stop listening for events.

Inherited from

BaseSyncClient.on

once()

once<K>(
   type, 
   listener, 
   debounceMilliseconds?): OffCallback;

Defined in: utils/dist/index.d.mts:50

Add a one-time listener for an event.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`listener`	`Listener`<`XOSyncClientEventMap`<`PayloadType`>[`K`]>	The listener function.
`debounceMilliseconds?`	`number`	The debounce time in milliseconds.

Returns

OffCallback

An off callback that can be called to stop listening for events.

Inherited from

BaseSyncClient.once

read()

read(resourceId): Promise<Resource<PayloadType>[]>;

Defined in: source/shared/base-client.ts:75

Reads a value from a resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to read from

Returns

Promise<Resource<PayloadType>[]>

The resource with the read value

Inherited from

BaseSyncClient.read

readMany()

readMany(resourceIds): Promise<ResourcesRecord<PayloadType>>;

Defined in: source/ws/client.ts:177

Reads multiple values from resources

Parameters

Parameter	Type	Description
`resourceIds`	`string`[]	The resource IDs to read from

Returns

Promise<ResourcesRecord<PayloadType>>

The resources with the read values

Overrides

BaseSyncClient.readMany

removeAllListeners()

removeAllListeners(): void;

Defined in: utils/dist/index.d.mts:74

Remove all listeners.

Returns

void

Inherited from

BaseSyncClient.removeAllListeners

subscribe(resourceId): Promise<void>;

Defined in: source/ws/client.ts:224

Subscribe to one resource topic, now and on every future socket.

The server never replies to a successful subscribe (the route stays pending until the topic is removed), so this resolves once the frame is sent. A failed subscribe comes back as an error message that matches no pending request, which handleMessage() reports through emitError().

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to subscribe to

Returns

Promise<void>

Overrides

BaseSyncClient.subscribe

unsubscribe()

unsubscribe(resourceId): Promise<void>;

Defined in: source/ws/client.ts:237

Unsubscribe from one resource topic.

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to unsubscribe from

Returns

Promise<void>

Overrides

BaseSyncClient.unsubscribe

waitFor()

waitFor<K>(
   type, 
   predicate, 
   timeoutMs?): Promise<XOSyncClientEventMap<PayloadType>[K]>;

Defined in: utils/dist/index.d.mts:82

Wait for an event to be emitted that matches the provided predicate function's criteria.

Type Parameters

Type Parameter
`K` extends keyof `XOSyncClientEventMap`<`PayloadType`>

Parameters

Parameter	Type	Description
`type`	`K`	The event type.
`predicate`	(`payload`) => `boolean`	Predicate function to filter for whether the event payload matches the criteria.
`timeoutMs?`	`number`	The timeout in milliseconds.

Returns

Promise<XOSyncClientEventMap<PayloadType>[K]>

The event payload.

Inherited from

BaseSyncClient.waitFor

write()

write(resourceId, value): Promise<Resource<PayloadType>[]>;

Defined in: source/shared/base-client.ts:47

Sign and write one resource

Parameters

Parameter	Type	Description
`resourceId`	`string`	The resource ID to write to
`value`	`PayloadType`	The value to write

Returns

Promise<Resource<PayloadType>[]>

The Resource Object with the decoded value

Inherited from

BaseSyncClient.write

writeMany()

writeMany(resourcesToWrite): Promise<ResourcesRecord<PayloadType>>;

Defined in: source/ws/client.ts:192

Writes multiple values to resources

Parameters

Parameter	Type	Description
`resourcesToWrite`	`Record`<`string`, `PayloadType`>	The resources to write to

Returns

Promise<ResourcesRecord<PayloadType>>

The resources with the written values

Overrides

BaseSyncClient.writeMany

decodeBlobValue()

static decodeBlobValue<T>(instance): Resource<T>;

Defined in: source/shared/base-client.ts:236

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type
`instance`	{ `blob`: `Uint8Array`<`ArrayBuffer`>; `publicKey`: `string`; `resourceId`: `string`; `signature`: `string`; `timestamp`: `number`; }
`instance.blob`	`Uint8Array`<`ArrayBuffer`>
`instance.publicKey`	`string`
`instance.resourceId`	`string`
`instance.signature`	`string`
`instance.timestamp`	`number`

Returns

Resource<T>

Inherited from

BaseSyncClient.decodeBlobValue

decodeResourcesResponse()

static decodeResourcesResponse<T>(response): ResourcesRecord<T>;

Defined in: source/shared/base-client.ts:215

Decodes the 'blob' field of the Resource Object from the server from a read/write

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Parameters

Parameter	Type	Description
`response`	{ `resources`: `z.ZodRecord`<`z.ZodString`, `z.ZodObject`<{ `instances`: `z.ZodArray`<`z.ZodObject`<{ `blob`: `z.ZodCustom`<`Uint8Array`<`ArrayBuffer`>, `Uint8Array`<`ArrayBuffer`>>; `publicKey`: `z.ZodString`; `resourceId`: `z.ZodString`; `signature`: `z.ZodString`; `timestamp`: `z.ZodNumber`; }, `z.core.$strip`>>; }, `z.core.$strip`>>; }	The ResourceResponse Object from the server from a read/write
`response.resources`	`z.ZodRecord`<`z.ZodString`, `z.ZodObject`<{ `instances`: `z.ZodArray`<`z.ZodObject`<{ `blob`: `z.ZodCustom`<`Uint8Array`<`ArrayBuffer`>, `Uint8Array`<`ArrayBuffer`>>; `publicKey`: `z.ZodString`; `resourceId`: `z.ZodString`; `signature`: `z.ZodString`; `timestamp`: `z.ZodNumber`; }, `z.core.$strip`>>; }, `z.core.$strip`>>	-

Returns

ResourcesRecord<T>

The Resource Object with the decoded value

Inherited from

BaseSyncClient.decodeResourcesResponse

deriveResourcePrivateKey()

static deriveResourcePrivateKey(privateKey, resourceId): Uint8Array;

Defined in: source/shared/base-client.ts:116

Derives the resource private key from the private key and resource ID

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to derive the resource private key from
`resourceId`	`string`	The resource ID to derive the resource private key from

Returns

Uint8Array

The resource private key

Inherited from

BaseSyncClient.deriveResourcePrivateKey

httpToWsUrl()

static httpToWsUrl(httpUrl): string;

Defined in: source/ws/client.ts:393

Helper to convert an HTTP URL to a WebSocket URL

Parameters

Parameter	Type	Description
`httpUrl`	`string`	The HTTP URL to convert

Returns

string

The WebSocket URL

signPayload()

static signPayload(privateKey, payload): SignedPayload;

Defined in: source/shared/base-client.ts:130

Signs a payload with the private key and returns the public key and signature

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the payload with
`payload`	`string`	The payload to sign

Returns

SignedPayload

The public key and signature

Inherited from

BaseSyncClient.signPayload

signRequest()

static signRequest(
   privateKey, 
   path, 
   body): AuthenticatedRequestHeaders;

Defined in: source/shared/base-client.ts:190

Signs a request with the private key and returns the public key, timestamp, and signature

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the request with
`path`	`string`	The path of the request
`body`	`unknown`	The body of the request

Returns

AuthenticatedRequestHeaders

The public key, timestamp, and signature

Inherited from

BaseSyncClient.signRequest

signWriteRequest()

static signWriteRequest(
   privateKey, 
   resourceId, 
   value): WriteRequest;

Defined in: source/shared/base-client.ts:163

Signs a write request with the private key and returns the write request

Parameters

Parameter	Type	Description
`privateKey`	`Uint8Array`	The private key to sign the write request with
`resourceId`	`string`	The resource ID to write to
`value`	`Uint8Array`	The value to write

Returns

WriteRequest

The write request

Inherited from

BaseSyncClient.signWriteRequest

AuthenticatedRequestHeaders

type AuthenticatedRequestHeaders = object;

Defined in: source/shared/base-client.ts:7

Resource

type Resource<PayloadType> = z.infer<typeof BaseSyncClient.resourceInstanceSchema> & object;

Defined in: source/shared/base-client.ts:24

Type Declaration

Name	Type	Defined in
`value`	`PayloadType`	source/shared/base-client.ts:25

Type Parameters

Type Parameter	Default type
`PayloadType`	`unknown`

ResourcesRecord

type ResourcesRecord<PayloadType> = Record<string, {
  instances: Resource<PayloadType>[];
}>;

Defined in: source/shared/base-client.ts:28

Type Parameters

Type Parameter	Default type
`PayloadType`	`unknown`

SignedPayload

type SignedPayload = object;

Defined in: source/shared/base-client.ts:13

WsClientOptions

type WsClientOptions = object;

Defined in: source/ws/client.ts:20

Properties

onError

onError: (error) => void;

Defined in: source/ws/client.ts:26

Called for transport errors and malformed server messages.

Parameters

Parameter	Type
`error`	`Error`

Returns

void

onMessage

onMessage: (message) => void;

Defined in: source/ws/client.ts:23

Called for server-pushed events and uncorrelated server errors.

Parameters

Parameter	Type
`message`	`WsMessage`

Returns

void

XOSyncClientEventMap

type XOSyncClientEventMap<T> = object;

Defined in: source/shared/base-client.ts:15

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Installation ​

Running ​

abstract BaseSyncClient ​

Extends ​

Extended by ​

Type Parameters ​

Constructors ​

Constructor ​

Returns ​

Inherited from ​

Methods ​

connect() ​

Returns ​

disconnect() ​

Returns ​

emit() ​

Type Parameters ​

Parameters ​

Returns ​

Remarks ​

Inherited from ​

off() ​

Type Parameters ​

Parameters ​

Returns ​

Inherited from ​

on() ​

Type Parameters ​

Parameters ​

Returns ​

Inherited from ​

once() ​

Type Parameters ​

Parameters ​

Returns ​

Inherited from ​

read() ​

Parameters ​

Returns ​

readMany() ​

Parameters ​

Returns ​

removeAllListeners() ​

Returns ​

Inherited from ​

subscribe() ​

Parameters ​

Returns ​

unsubscribe() ​

Parameters ​

Returns ​

waitFor() ​

Type Parameters ​

Parameters ​

Returns ​

Inherited from ​

write() ​

Parameters ​

Returns ​

writeMany() ​

Parameters ​

Returns ​

decodeBlobValue() ​

Type Parameters ​

Parameters ​

Returns ​

decodeResourcesResponse() ​

Type Parameters ​

Parameters ​

Returns ​

deriveResourcePrivateKey() ​

Parameters ​

Returns ​

signPayload() ​

Parameters ​

Returns ​

signRequest() ​

Parameters ​

Returns ​

signWriteRequest() ​

Installation

Running

`abstract` BaseSyncClient

Extends

Extended by

Type Parameters

Constructors

Constructor

Returns

Inherited from

Methods

connect()

Returns

disconnect()

Returns

emit()

Type Parameters

Parameters

Returns

Remarks

Inherited from

off()

Type Parameters

Parameters

Returns

Inherited from

on()

Type Parameters

Parameters

Returns

Inherited from

once()

Type Parameters

Parameters

Returns

Inherited from

read()

Parameters

Returns

readMany()

Parameters

Returns

removeAllListeners()

Returns

Inherited from

subscribe()

Parameters

Returns

unsubscribe()

Parameters

Returns

waitFor()

Type Parameters

Parameters

Returns

Inherited from

write()

Parameters

Returns

writeMany()

Parameters

Returns

decodeBlobValue()

Type Parameters

Parameters

Returns

decodeResourcesResponse()

Type Parameters

Parameters

Returns

deriveResourcePrivateKey()

Parameters

Returns

signPayload()

Parameters

Returns

signRequest()

Parameters

Returns

signWriteRequest()