BaseNode

Base methods for synchronization nodes. Client and server nodes are based on this module.

Parameter	Type	Description
`nodeId`	`string`	Unique current machine name.
`log`	`L`	Logux log instance to be synchronized.
`connection`	`Connection`	Connection to remote node.
`options` ?	`NodeOptions<H>`	Synchronization options.

`BaseNode#authenticated`

Did we finish remote node authentication.

Type: boolean.

`BaseNode#connection`

Connection used to communicate to remote node.

Type: Connection.

`BaseNode#initializing`

Promise for node data initial loadiging.

Type: Promise<void>.

`BaseNode#lastReceived`

Latest remote node’s log added time, which was successfully synchronized. It will be saves in log store.

Type: number.

`BaseNode#lastSent`

Latest current log added time, which was successfully synchronized. It will be saves in log store.

Type: number.

`BaseNode#options`

Synchronization options.

Type: NodeOptions<H>.

`BaseNode#state`

Current synchronization state.

disconnected: no connection.
connecting: connection was started and we wait for node answer.
sending: new actions was sent, waiting for answer.
synchronized: all actions was synchronized and we keep connection.

node.on('state', () => {
  if (node.state === 'sending') {
    console.log('Do not close browser')
  }
})

Type: 'disconnected' | 'connecting' | 'sending' | 'synchronized'.

`BaseNode#timeFix`

Time difference between nodes.

Type: number.

`BaseNode#catch(listener)`

Disable throwing a error on error message and create error listener.

node.catch(error => {
  console.error(error)
})

Parameter	Type	Description
`listener`	`(error: LoguxError) => void`	The error listener.

Returns Unsubscribe. Unbind listener from event.

`BaseNode#destroy()`

Shut down the connection and unsubscribe from log events.

connection.on('disconnect', () => {
  server.destroy()
})

`BaseNode#on(event, listener)`

Subscribe for synchronization events. It implements nanoevents API. Supported events:

state: synchronization state was changed.
connect: custom check before node authentication. You can throw a LoguxError to send error to remote node.
error: synchronization error was raised.
clientError: when error was sent to remote node.
debug: when debug information received from remote node.
headers: headers was receive from remote node.

node.on('clientError', error => {
  logError(error)
})

Parameter	Type	Description
`event`	`'state' \| 'connect' \| 'debug' \| 'headers'`	Event name.
`listener`	`() => void`	The listener function.

Parameter	Type
`event`	`'error' \| 'clientError'`
`listener`	`(error: Error) => void`

Parameter	Type
`event`	`'debug'`
`listener`	`(type: 'error', data: string) => void`

Parameter	Type
`event`	`'headers'`
`listener`	`(headers: H) => void`

Returns Unsubscribe. Unbind listener from event.

`BaseNode#setLocalHeaders(headers)`

Set headers for current node.

if (navigator) {
  node.setLocalHeaders({ language: navigator.language })
}
node.connection.connect()

Parameter	Type	Description
`headers`	`object`	The data object will be set as headers for current node.

`BaseNode#waitFor(state)`

Return Promise until sync will have specific state.

If current state is correct, method will return resolved Promise.

await node.waitFor('synchronized')
console.log('Everything is synchronized')

Parameter	Type	Description
`state`	`'disconnected' \| 'connecting' \| 'sending' \| 'synchronized'`	The expected synchronization state value.

Returns Promise<void>. Promise until specific state.

Client

Base class for browser API to be extended in CrossTabClient.

Because this class could have conflicts between different browser tab, you should use it only if you are really sure, that application will not be run in different tab (for instance, if you are developing a kiosk app).

import { Client } from '@logux/client'

const userId = document.querySelector('meta[name=user]').content
const token = document.querySelector('meta[name=token]').content

const client = new Client({
  credentials: token,
  subprotocol: '1.0.0',
  server: 'wss://example.com:1337',
  userId: userId
})
client.start()

Parameter	Type	Description
`opts`	`ClientOptions`	Client options.

`Client#clientId`

Unique permanent client ID. Can be used to track this machine.

Type: string.

`Client#log`

Client events log.

client.log.add(action)

Type: L.

`Client#node`

Node instance to synchronize logs.

if (client.node.state === 'synchronized')

Type: ClientNode<H, L>.

`Client#nodeId`

Unique Logux node ID.

console.log('Client ID: ', client.nodeId)

Type: string.

`Client#options`

Client options.

console.log('Connecting to ' + client.options.server)

Type: ClientOptions.

`Client#tabId`

Unique tab ID. Can be used to add an action to the specific tab.

client.log.add(action, { tab: client.tabId })

Type: TabID.

`Client#changeUser(userId, token?)`

Disconnect from the server, update user, and connect again with new credentials.

onAuth(async (userId, token) => {
  showLoader()
  client.changeUser(userId, token)
  await client.node.waitFor('synchronized')
  hideLoader()
})

You need manually chang user ID in all browser tabs.

Parameter	Type	Description
`userId`	`string`	The new user ID.
`token` ?	`string`	Credentials for new user.

`Client#clean()`

Clear stored data. Removes action log from IndexedDB if you used it.

signout.addEventListener('click', () => {
  client.clean()
})

Returns Promise<void>. Promise when all data will be removed.

`Client#destroy()`

Disconnect and stop synchronization.

shutdown.addEventListener('click', () => {
  client.destroy()
})

`Client#on(event, listener)`

Subscribe for synchronization events. It implements Nano Events API. Supported events:

preadd: action is going to be added (in current tab).
add: action has been added to log (by any tab).
clean: action has been removed from log (by any tab).
user: user ID was changed.

client.on('add', (action, meta) => {
  dispatch(action)
})

Parameter	Type	Description
`event`	`'preadd' \| 'add' \| 'clean'`	The event name.
`listener`	`ClientActionListener`	The listener function.

Parameter	Type
`event`	`'user'`
`listener`	`(userId: string) => void`

Returns Unsubscribe. Unbind listener from event.

`Client#start()`

Connect to server and reconnect on any connection problem.

client.start()

ClientNode

Extends BaseNode.

Client node in synchronization pair.

Instead of server node, it initializes synchronization and sends connect message.

import { ClientNode } from '@logux/core'
const connection = new BrowserConnection(url)
const node = new ClientNode(nodeId, log, connection)

Parameter	Type	Description
`nodeId`	`string`	Unique current machine name.
`log`	`L`	Logux log instance to be synchronized.
`connection`	`Connection`	Connection to remote node.
`options` ?	`NodeOptions<H>`	Synchronization options.

`ClientNode#authenticated`

Did we finish remote node authentication.

Type: boolean.

`ClientNode#connected`

Is synchronization in process.

node.on('disconnect', () => {
  node.connected //=> false
})

Type: boolean.

`ClientNode#connection`

Connection used to communicate to remote node.

Type: Connection.

`ClientNode#initializing`

Promise for node data initial loadiging.

Type: Promise<void>.

`ClientNode#lastReceived`

Latest remote node’s log added time, which was successfully synchronized. It will be saves in log store.

Type: number.

`ClientNode#lastSent`

Latest current log added time, which was successfully synchronized. It will be saves in log store.

Type: number.

`ClientNode#localNodeId`

Unique current machine name.

console.log(node.localNodeId + ' is started')

Type: string.

`ClientNode#localProtocol`

Used Logux protocol.

if (tool.node.localProtocol !== 1) {
  throw new Error('Unsupported Logux protocol')
}

Type: number.

`ClientNode#log`

Log for synchronization.

Type: L.

`ClientNode#minProtocol`

Minimum version of Logux protocol, which is supported.

console.log(`You need Logux protocol ${node.minProtocol} or higher`)

Type: number.

`ClientNode#options`

Synchronization options.

Type: NodeOptions<H>.

`ClientNode#remoteHeaders`

Headers set by remote node. By default, it is an empty object.

let message = I18N_ERRORS[node.remoteHeaders.language || 'en']
node.log.add({ type: 'error', message })

Type: H | EmptyHeaders.

`ClientNode#remoteNodeId`

Unique name of remote machine. It is undefined until nodes handshake.

console.log('Connected to ' + node.remoteNodeId)

Type: string | undefined.

`ClientNode#remoteProtocol`

Remote node Logux protocol. It is undefined until nodes handshake.

if (node.remoteProtocol >= 5) {
  useNewAPI()
} else {
  useOldAPI()
}

Type: number | undefined.

`ClientNode#remoteSubprotocol`

Remote node’s application subprotocol version in SemVer format.

It is undefined until nodes handshake. If remote node will not send on handshake its subprotocol, it will be set to 0.0.0.

if (semver.satisfies(node.remoteSubprotocol, '>= 5.0.0') {
  useNewAPI()
} else {
  useOldAPI()
}

Type: string | undefined.

`ClientNode#state`

Current synchronization state.

disconnected: no connection.
connecting: connection was started and we wait for node answer.
sending: new actions was sent, waiting for answer.
synchronized: all actions was synchronized and we keep connection.

node.on('state', () => {
  if (node.state === 'sending') {
    console.log('Do not close browser')
  }
})

Type: 'disconnected' | 'connecting' | 'sending' | 'synchronized'.

`ClientNode#timeFix`

Time difference between nodes.

Type: number.

`ClientNode#catch(listener)`

Disable throwing a error on error message and create error listener.

node.catch(error => {
  console.error(error)
})

Parameter	Type	Description
`listener`	`(error: LoguxError) => void`	The error listener.

Returns Unsubscribe. Unbind listener from event.

`ClientNode#destroy()`

Shut down the connection and unsubscribe from log events.

connection.on('disconnect', () => {
  server.destroy()
})

`ClientNode#on(event, listener)`

Subscribe for synchronization events. It implements nanoevents API. Supported events:

state: synchronization state was changed.
connect: custom check before node authentication. You can throw a LoguxError to send error to remote node.
error: synchronization error was raised.
clientError: when error was sent to remote node.
debug: when debug information received from remote node.
headers: headers was receive from remote node.

node.on('clientError', error => {
  logError(error)
})

Parameter	Type	Description
`event`	`'state' \| 'connect' \| 'debug' \| 'headers'`	Event name.
`listener`	`() => void`	The listener function.

Parameter	Type
`event`	`'error' \| 'clientError'`
`listener`	`(error: Error) => void`

Parameter	Type
`event`	`'debug'`
`listener`	`(type: 'error', data: string) => void`

Parameter	Type
`event`	`'headers'`
`listener`	`(headers: H) => void`

Returns Unsubscribe. Unbind listener from event.

`ClientNode#setLocalHeaders(headers)`

Set headers for current node.

if (navigator) {
  node.setLocalHeaders({ language: navigator.language })
}
node.connection.connect()

Parameter	Type	Description
`headers`	`object`	The data object will be set as headers for current node.

`ClientNode#waitFor(state)`

Return Promise until sync will have specific state.

If current state is correct, method will return resolved Promise.

await node.waitFor('synchronized')
console.log('Everything is synchronized')

Parameter	Type	Description
`state`	`'disconnected' \| 'connecting' \| 'sending' \| 'synchronized'`	The expected synchronization state value.

Returns Promise<void>. Promise until specific state.

Connection

Abstract interface for connection to synchronize logs over it. For example, WebSocket or Loopback.

`Connection#connected`

Is connection is enabled.

Type: boolean.

`Connection#destroy`

Optional method to disconnect and unbind all even listeners.

Type: () => void.

`Connection#connect()`

Start connection. Connection should be in disconnected state from the beginning and start connection only on this method call.

This method could be called again if connection moved to disconnected state.

Returns Promise<void>. Promise until connection will be established.

`Connection#disconnect(reason?)`

Finish current connection.

Parameter	Type	Description
`reason` ?	`'error' \| 'timeout' \| 'destroy'`	Disconnection reason.

`Connection#on(event, listener)`

Subscribe for connection events. It implements nanoevents API. Supported events:

connecting: connection establishing was started.
connect: connection was established by any side.
disconnect: connection was closed by any side.
message: message was receive from remote node.
error: error during connection, sending or receiving.

Parameter	Type	Description
`event`	`'connecting' \| 'connect' \| 'disconnect'`	Event name.
`listener`	`() => void`	Event listener.

Parameter	Type
`event`	`'error'`
`listener`	`(error: Error) => void`

Parameter	Type
`event`	`'message'`
`listener`	`(msg: Message) => void`

Parameter	Type
`event`	`'disconnect'`
`listener`	`(reason: string) => void`

Returns Unsubscribe. Unbind listener from event.

`Connection#send(message)`

Send message to connection.

Parameter	Type	Description
`message`	`Message`	The message to be sent.

CrossTabClient

Extends Client.

Low-level browser API for Logux.

Instead of Client, this class prevents conflicts between Logux instances in different tabs on single browser.

import { CrossTabClient } from '@logux/client'

const userId = document.querySelector('meta[name=user]').content
const token = document.querySelector('meta[name=token]').content

const client = new CrossTabClient({
  subprotocol: '1.0.0',
  server: 'wss://example.com:1337',
  userId,
  token
})
client.start()

Parameter	Type	Description
`opts`	`ClientOptions`	Client options.

`CrossTabClient#clientId`

Unique permanent client ID. Can be used to track this machine.

Type: string.

`CrossTabClient#connected`

Is leader tab connected to server.

Type: boolean.

`CrossTabClient#log`

Client events log.

client.log.add(action)

Type: L.

`CrossTabClient#node`

Node instance to synchronize logs.

if (client.node.state === 'synchronized')

Type: ClientNode<H, L>.

`CrossTabClient#nodeId`

Unique Logux node ID.

console.log('Client ID: ', client.nodeId)

Type: string.

`CrossTabClient#options`

Client options.

console.log('Connecting to ' + client.options.server)

Type: ClientOptions.

`CrossTabClient#role`

Current tab role. Only leader tab connects to server. followers just listen to events from leader.

client.on('role', () => {
  console.log('Tab role:', client.role)
})

Type: 'leader' | 'candidate' | 'follower'.

`CrossTabClient#state`

Leader tab synchronization state. It can differs from client.node.state (because only the leader tab keeps connection).

client.on('state', () => {
  if (client.state === 'disconnected' && client.state === 'sending') {
    showCloseWarning()
  }
})

Type: 'disconnected' | 'connecting' | 'sending' | 'synchronized'.

`CrossTabClient#tabId`

Unique tab ID. Can be used to add an action to the specific tab.

client.log.add(action, { tab: client.tabId })

Type: TabID.

`CrossTabClient#changeUser(userId, token?)`

Disconnect from the server, update user, and connect again with new credentials.

onAuth(async (userId, token) => {
  showLoader()
  client.changeUser(userId, token)
  await client.node.waitFor('synchronized')
  hideLoader()
})

You need manually chang user ID in all browser tabs.

Parameter	Type	Description
`userId`	`string`	The new user ID.
`token` ?	`string`	Credentials for new user.

`CrossTabClient#clean()`

Clear stored data. Removes action log from IndexedDB if you used it.

signout.addEventListener('click', () => {
  client.clean()
})

Returns Promise<void>. Promise when all data will be removed.

`CrossTabClient#destroy()`

Disconnect and stop synchronization.

shutdown.addEventListener('click', () => {
  client.destroy()
})

`CrossTabClient#on(event, listener)`

Subscribe for synchronization events. It implements nanoevents API. Supported events:

preadd: action is going to be added (in current tab).
add: action has been added to log (by any tab).
clean: action has been removed from log (by any tab).
role: tab role has been changed.
state: leader tab synchronization state has been changed.
user: user ID was changed.

client.on('add', (action, meta) => {
  dispatch(action)
})

Parameter	Type	Description
`event`	`'role' \| 'state'`	The event name.
`listener`	`() => void`	The listener function.

Parameter	Type
`event`	`'user'`
`listener`	`(userId: string) => void`

Parameter	Type
`event`	`'preadd' \| 'add' \| 'clean'`
`listener`	`ClientActionListener`

Returns Unsubscribe. Unbind listener from event.

`CrossTabClient#start()`

Connect to server and reconnect on any connection problem.

client.start()

`CrossTabClient#waitFor(state)`

Wait for specific state of the leader tab.

await client.waitFor('synchronized')
hideLoader()

Parameter	Type	Description
`state`	`'disconnected' \| 'connecting' \| 'sending' \| 'synchronized'`	State name

Returns Promise<void>.

IndexedStore

Extends LogStore.

IndexedDB store for Logux log.

import { IndexedStore } from '@logux/client'
const client = new CrossTabClient({
  …,
  store: new IndexedStore()
})

import IndexedStore from '@logux/client/indexed-store'
const createStore = createLoguxCreator({
  …,
  store: new IndexedStore()
})

Parameter	Type	Description
`name` ?	`string`	Database name to run multiple Logux instances on same web page.

`IndexedStore#name`

Database name.

Type: string.

`IndexedStore#add(action, meta)`

Add action to store. Action always will have type property.

Parameter	Type	Description
`action`	`Action`	The action to add.
`meta`	`Meta`	Action’s metadata.

Returns Promise<Meta | false>. Promise with meta for new action or false if action with same meta.id was already in store.

`IndexedStore#byId(id)`

Return action by action ID.

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise <[Action, Meta] | [null, null]>. Promise with array of action and metadata.

`IndexedStore#changeMeta(id, diff)`

Change action metadata.

Parameter	Type	Description
`id`	`ID`	Action ID.
`diff`	`Partial<Meta>`	Object with values to change in action metadata.

Returns Promise<boolean>. Promise with true if metadata was changed or false on unknown ID.

`IndexedStore#clean()`

Remove all data from the store.

Returns Promise<void>. Promise when cleaning will be finished.

`IndexedStore#get(opts?)`

Return a Promise with first page. Page object has entries property with part of actions and next property with function to load next page. If it was a last page, next property should be empty.

This tricky API is used, because log could be very big. So we need pagination to keep them in memory.

Parameter	Type	Description
`opts` ?	`GetOptions`	Query options.

Returns Promise<Page>. Promise with first page.

`IndexedStore#getLastAdded()`

Return biggest added number in store. All actions in this log have less or same added time.

Returns Promise<number>. Promise with biggest added number.

`IndexedStore#getLastSynced()`

Get added values for latest synchronized received/sent events.

Returns Promise<LastSynced>. Promise with added values

`IndexedStore#remove(id)`

Remove action from store.

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise<[Action, Meta] | false>. Promise with entry if action was in store.

`IndexedStore#removeReason(reason, criteria, callback)`

Remove reason from action’s metadata and remove actions without reasons.

Parameter	Type	Description
`reason`	`string`	The reason name.
`criteria`	`Criteria`	Criteria to select action for reason removing.
`callback`	`ActionListener`	Callback for every removed action.

Returns Promise<void>. Promise when cleaning will be finished.

`IndexedStore#setLastSynced(values)`

Set added value for latest synchronized received or/and sent events.

Parameter	Type	Description
`values`	`LastSynced`	Object with latest sent or received values.

Returns Promise<void>. Promise when values will be saved to store.

LocalConnection

Extends Connection.

`LocalConnection#connected`

Is connection is enabled.

Type: boolean.

`LocalConnection#destroy`

Optional method to disconnect and unbind all even listeners.

Type: () => void.

`LocalConnection#connect()`

Start connection. Connection should be in disconnected state from the beginning and start connection only on this method call.

This method could be called again if connection moved to disconnected state.

Returns Promise<void>. Promise until connection will be established.

`LocalConnection#disconnect(reason?)`

Finish current connection.

Parameter	Type	Description
`reason` ?	`'error' \| 'timeout' \| 'destroy'`	Disconnection reason.

`LocalConnection#on(event, listener)`

Subscribe for connection events. It implements nanoevents API. Supported events:

connecting: connection establishing was started.
connect: connection was established by any side.
disconnect: connection was closed by any side.
message: message was receive from remote node.
error: error during connection, sending or receiving.

Parameter	Type	Description
`event`	`'connecting' \| 'connect' \| 'disconnect'`	Event name.
`listener`	`() => void`	Event listener.

Parameter	Type
`event`	`'error'`
`listener`	`(error: Error) => void`

Parameter	Type
`event`	`'message'`
`listener`	`(msg: Message) => void`

Parameter	Type
`event`	`'disconnect'`
`listener`	`(reason: string) => void`

Returns Unsubscribe. Unbind listener from event.

`LocalConnection#other()`

Returns LocalConnection.

`LocalConnection#send(message)`

Send message to connection.

Parameter	Type	Description
`message`	`Message`	The message to be sent.

LocalPair

Two paired loopback connections.

import { LocalPair, ClientNode, ServerNode } from '@logux/core'
const pair = new LocalPair()
const client = new ClientNode('client', log1, pair.left)
const server = new ServerNode('server', log2, pair.right)

Parameter	Type	Description
`delay` ?	`number`	Delay for connection and send events. Default is `1`.

`LocalPair#delay`

Delay for connection and send events to emulate real connection latency.

Type: number.

`LocalPair#left`

First connection. Will be connected to right one after connect().

new ClientNode('client, log1, pair.left)

Type: LocalConnection.

`LocalPair#right`

Second connection. Will be connected to right one after connect().

new ServerNode('server, log2, pair.right)

Type: LocalConnection.

Log

Stores actions with time marks. Log is main idea in Logux. In most end-user tools you will work with log and should know log API.

import Log from '@logux/core'
const log = new Log({
  store: new MemoryStore(),
  nodeId: 'client:134'
})

log.on('add', beeper)
log.add({ type: 'beep' })

Parameter	Type	Description
`opts`	`LogOptions<S>`	Log options.

`Log#nodeId`

Unique node ID. It is used in action IDs.

Type: string.

`Log#store`

Log store.

Type: S.

`Log#add(action, meta?)`

Add action to log.

It will set id, time (if they was missed) and added property to meta and call all listeners.

removeButton.addEventListener('click', () => {
  log.add({ type: 'users:remove', user: id })
})

Parameter	Type	Description
`action`	`Action`	The new action.
`meta` ?	`Partial<ClientMeta>`	Open structure for action metadata.

Returns Promise<ClientMeta | false>. Promise with meta if action was added to log or false if action was already in log.

`Log#byId(id)`

Does log already has action with this ID.

if (action.type === 'logux/undo') {
  const [undidAction, undidMeta] = await log.byId(action.id)
  log.changeMeta(meta.id, { reasons: undidMeta.reasons })
}

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise <[Action, ClientMeta] | [null, null]>. Promise with array of action and metadata.

`Log#changeMeta(id, diff)`

Change action metadata. You will remove action by setting reasons: [].

await process(action)
log.changeMeta(action, { status: 'processed' })

Parameter	Type	Description
`id`	`ID`	Action ID.
`diff`	`Partial<ClientMeta>`	Object with values to change in action metadata.

Returns Promise<boolean>. Promise with true if metadata was changed or false on unknown ID.

`Log#each(callback)`

Iterates through all actions, from last to first.

Return false from callback if you want to stop iteration.

log.each((action, meta) => {
  if (compareTime(meta.id, lastBeep) <= 0) {
    return false;
  } else if (action.type === 'beep') {
    beep()
    lastBeep = meta.id
    return false;
  }
})

Parameter	Type	Description
`callback`	`ActionIterator`	Function will be executed on every action.

Parameter	Type	Description
`opts`	`GetOptions`	Iterator options.
`callback`	`ActionIterator`	Function will be executed on every action.

Parameter	Type
`callback`	`ActionIterator`

Returns Promise<void>. When iteration will be finished by iterator or end of actions.

`Log#generateId()`

Generate next unique action ID.

const id = log.generateId()

Returns ID. Unique ID for action.

`Log#on(event, listener)`

Subscribe for log events. It implements nanoevents API. Supported events:

preadd: when somebody try to add action to log. It fires before ID check. The best place to add reason.
add: when new action was added to log.
clean: when action was cleaned from store.

const unbind = log.on('add', (action, meta) => {
  if (action.type === 'beep') beep()
})
function disableBeeps () {
  unbind()
}

Parameter	Type	Description
`event`	`'preadd' \| 'add' \| 'clean'`	The event name.
`listener`	`ActionListener`	The listener function.

Returns Unsubscribe. Unbind listener from event.

`Log#removeReason(reason, criteria?)`

Remove reason tag from action’s metadata and remove actions without reason from log.

onSync(lastSent) {
  log.removeReason('unsynchronized', { maxAdded: lastSent })
}

Parameter	Type	Description
`reason`	`string`	The reason name.
`criteria` ?	`Criteria`	Criteria to select action for reason removing.

Returns Promise<void>. Promise when cleaning will be finished.

LogStore

Every Store class should provide 8 standard methods.

Parameter	Type	Description
`action`	`Action`	The action to add.
`meta`	`Meta`	Action’s metadata.

`LogStore#add(action, meta)`

Add action to store. Action always will have type property.

Parameter	Type	Description
`action`	`Action`	The action to add.
`meta`	`Meta`	Action’s metadata.

Returns Promise<Meta | false>. Promise with meta for new action or false if action with same meta.id was already in store.

`LogStore#byId(id)`

Return action by action ID.

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise <[Action, Meta] | [null, null]>. Promise with array of action and metadata.

`LogStore#changeMeta(id, diff)`

Change action metadata.

Parameter	Type	Description
`id`	`ID`	Action ID.
`diff`	`Partial<Meta>`	Object with values to change in action metadata.

Returns Promise<boolean>. Promise with true if metadata was changed or false on unknown ID.

`LogStore#clean()`

Remove all data from the store.

Returns Promise<void>. Promise when cleaning will be finished.

`LogStore#get(opts?)`

Return a Promise with first page. Page object has entries property with part of actions and next property with function to load next page. If it was a last page, next property should be empty.

This tricky API is used, because log could be very big. So we need pagination to keep them in memory.

Parameter	Type	Description
`opts` ?	`GetOptions`	Query options.

Returns Promise<Page>. Promise with first page.

`LogStore#getLastAdded()`

Return biggest added number in store. All actions in this log have less or same added time.

Returns Promise<number>. Promise with biggest added number.

`LogStore#getLastSynced()`

Get added values for latest synchronized received/sent events.

Returns Promise<LastSynced>. Promise with added values

`LogStore#remove(id)`

Remove action from store.

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise<[Action, Meta] | false>. Promise with entry if action was in store.

`LogStore#removeReason(reason, criteria, callback)`

Remove reason from action’s metadata and remove actions without reasons.

Parameter	Type	Description
`reason`	`string`	The reason name.
`criteria`	`Criteria`	Criteria to select action for reason removing.
`callback`	`ActionListener`	Callback for every removed action.

Returns Promise<void>. Promise when cleaning will be finished.

`LogStore#setLastSynced(values)`

Set added value for latest synchronized received or/and sent events.

Parameter	Type	Description
`values`	`LastSynced`	Object with latest sent or received values.

Returns Promise<void>. Promise when values will be saved to store.

LoguxError

Extends Error.

Logux error in logs synchronization.

if (error.name === 'LoguxError') {
  console.log('Server throws: ' + error.description)
}

Parameter	Type	Description
`type`	`T`	The error code.
`options` ?	`LoguxErrorOptions[T]`	The error option.
`received` ?	`boolean`	Was error received from remote node.

`LoguxError.description(type, options?)`

Return a error description by it code.

Parameter	Type	Description
`type`	`K`	The error code.
`options` ?	`LoguxErrorOptions[K]`	The errors options depends on error code.

Returns string.

`LoguxError#description`

Human-readable error description.

console.log('Server throws: ' + error.description)

Type: string.

`LoguxError#message`

Full text of error to print in debug message.

Type: string.

`LoguxError#name`

Always equal to LoguxError. The best way to check error class.

if (error.name === 'LoguxError') {

Type: 'LoguxError'.

`LoguxError#options`

Error options depends on error type.

if (error.type === 'timeout') {
  console.error('A timeout was reached (' + error.options + ' ms)')
}

Type: LoguxErrorOptions[T].

`LoguxError#received`

Was error received from remote client.

Type: boolean.

`LoguxError#stack`

Calls which cause the error.

Type: string.

`LoguxError#type`

The error code.

if (error.type === 'timeout') {
  fixNetwork()
}

Type: T.

LoguxVuexStore

Extends VuexStore.

Parameter	Type
`options`	`LoguxVuexStoreOptions<S>`

`LoguxVuexStore#client`

Logux synchronization client.

Type: C.

`LoguxVuexStore#commit`

Add action to log with Vuex compatible API.

Type: LoguxVuexCommit.

`LoguxVuexStore#dispatch`

Type: VuexDispatch.

`LoguxVuexStore#getters`

Type: any.

`LoguxVuexStore#initialize`

Promise until loading the state from log store.

Type: Promise<void>.

`LoguxVuexStore#log`

The Logux log.

Type: L.

`LoguxVuexStore#state`

Type: S.

`LoguxVuexStore#hasModule(path)`

Parameter	Type
`path`	`string`

Parameter	Type
`path`	`string[]`

Returns boolean.

`LoguxVuexStore#hotUpdate(options)`

Parameter	Type
`options`	`{ actions?: ActionTree<S, S>, getters?: GetterTree<S, S>, modules?: ModuleTree<S>, mutations?: MutationTree<S> }`

`LoguxVuexStore#install(app, injectKey?)`

Parameter	Type
`app`	`App`
`injectKey` ?	`InjectionKey<Store<any>> \| string`

`LoguxVuexStore#on(event, listener)`

Subscribes for store events. Supported events:

change: when store was changed by action.

store.on('change', (state, prevState, action, meta) => {
  console.log(state, prevState, action, meta)
})

Parameter	Type	Description
`event`	`'change'`	The event name.
`listener`	`StateListener<S>`	The listener function.

Returns Unsubscribe. Unbind listener from event.

`LoguxVuexStore#registerModule(path, module, options?)`

Parameter	Type
`path`	`string`
`module`	`Module<T, S>`
`options` ?	`ModuleOptions`

Parameter	Type
`path`	`string[]`
`module`	`Module<T, S>`
`options` ?	`ModuleOptions`

`LoguxVuexStore#replaceState(state)`

Parameter	Type
`state`	`S`

Parameter	Type
`fn`	`(mutation: P, state: S) => any`
`options` ?	`SubscribeOptions`

Returns () => void.

`LoguxVuexStore#subscribeAction(fn, options?)`

Parameter	Type
`fn`	`SubscribeActionOptions<P, S>`
`options` ?	`SubscribeOptions`

Returns () => void.

`LoguxVuexStore#unregisterModule(path)`

Parameter	Type
`path`	`string`

Parameter	Type
`path`	`string[]`

`LoguxVuexStore#watch(getter, cb, options?)`

Parameter	Type
`getter`	`(state: S, getters: any) => T`
`cb`	`(value: T, oldValue: T) => void`
`options` ?	`WatchOptions`

Returns () => void.

MemoryStore

Extends LogStore.

Simple memory-based log store.

It is good for tests, but not for server or client usage, because it store all data in memory and will lose log on exit.

import { MemoryStore } from '@logux/core'

var log = new Log({
  nodeId: 'server',
  store: new MemoryStore()
})

`MemoryStore#entries`

Actions in the store.

Type: [Action, Meta][].

`MemoryStore#add(action, meta)`

Add action to store. Action always will have type property.

Parameter	Type	Description
`action`	`Action`	The action to add.
`meta`	`Meta`	Action’s metadata.

Returns Promise<Meta | false>. Promise with meta for new action or false if action with same meta.id was already in store.

`MemoryStore#byId(id)`

Return action by action ID.

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise <[Action, Meta] | [null, null]>. Promise with array of action and metadata.

`MemoryStore#changeMeta(id, diff)`

Change action metadata.

Parameter	Type	Description
`id`	`ID`	Action ID.
`diff`	`Partial<Meta>`	Object with values to change in action metadata.

Returns Promise<boolean>. Promise with true if metadata was changed or false on unknown ID.

`MemoryStore#clean()`

Remove all data from the store.

Returns Promise<void>. Promise when cleaning will be finished.

`MemoryStore#get(opts?)`

Return a Promise with first page. Page object has entries property with part of actions and next property with function to load next page. If it was a last page, next property should be empty.

This tricky API is used, because log could be very big. So we need pagination to keep them in memory.

Parameter	Type	Description
`opts` ?	`GetOptions`	Query options.

Returns Promise<Page>. Promise with first page.

`MemoryStore#getLastAdded()`

Return biggest added number in store. All actions in this log have less or same added time.

Returns Promise<number>. Promise with biggest added number.

`MemoryStore#getLastSynced()`

Get added values for latest synchronized received/sent events.

Returns Promise<LastSynced>. Promise with added values

`MemoryStore#remove(id)`

Remove action from store.

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise<[Action, Meta] | false>. Promise with entry if action was in store.

`MemoryStore#removeReason(reason, criteria, callback)`

Remove reason from action’s metadata and remove actions without reasons.

Parameter	Type	Description
`reason`	`string`	The reason name.
`criteria`	`Criteria`	Criteria to select action for reason removing.
`callback`	`ActionListener`	Callback for every removed action.

Returns Promise<void>. Promise when cleaning will be finished.

`MemoryStore#setLastSynced(values)`

Set added value for latest synchronized received or/and sent events.

Parameter	Type	Description
`values`	`LastSynced`	Object with latest sent or received values.

Returns Promise<void>. Promise when values will be saved to store.

Reconnect

Extends Connection.

Wrapper for Connection for reconnecting it on every disconnect.

import { ClientNode, Reconnect } from '@logux/core'
const recon = new Reconnect(connection)
new ClientNode(nodeId, log, recon, options)

Parameter	Type	Description
`connection`	`Connection`	The connection to be reconnectable.
`options` ?	`ReconnectOptions`	Reconnection options.

`Reconnect#attempts`

Fails attempts since the last connected state.

Type: number.

`Reconnect#connected`

Is connection is enabled.

Type: boolean.

`Reconnect#connecting`

Are we in the middle of connecting.

Type: boolean.

`Reconnect#connection`

Wrapped connection.

Type: Connection.

`Reconnect#destroy`

Unbind all listeners and disconnect. Use it if you will not need this class anymore.

Type: () => void.

`Reconnect#options`

Reconnection options.

Type: ReconnectOptions.

`Reconnect#reconnecting`

Should we reconnect connection on next connection break. Next connect call will set to true.

function lastTry () {
  recon.reconnecting = false
}

Type: boolean.

`Reconnect#connect()`

Start connection. Connection should be in disconnected state from the beginning and start connection only on this method call.

This method could be called again if connection moved to disconnected state.

Returns Promise<void>. Promise until connection will be established.

`Reconnect#disconnect(reason?)`

Finish current connection.

Parameter	Type	Description
`reason` ?	`'error' \| 'timeout' \| 'destroy'`	Disconnection reason.

`Reconnect#on(event, listener)`

Subscribe for connection events. It implements nanoevents API. Supported events:

connecting: connection establishing was started.
connect: connection was established by any side.
disconnect: connection was closed by any side.
message: message was receive from remote node.
error: error during connection, sending or receiving.

Parameter	Type	Description
`event`	`'connecting' \| 'connect' \| 'disconnect'`	Event name.
`listener`	`() => void`	Event listener.

Parameter	Type
`event`	`'error'`
`listener`	`(error: Error) => void`

Parameter	Type
`event`	`'message'`
`listener`	`(msg: Message) => void`

Parameter	Type
`event`	`'disconnect'`
`listener`	`(reason: string) => void`

Returns Unsubscribe. Unbind listener from event.

`Reconnect#send(message)`

Send message to connection.

Parameter	Type	Description
`message`	`Message`	The message to be sent.

TestLog

Extends Log.

Log to be used in tests. It already has memory store, node ID, and special test timer.

Use TestTime to create test log.

import { TestTime } from '@logux/core'

it('tests log', () => {
  const log = TestTime.getLog()
})

it('tests 2 logs', () => {
  const time = new TestTime()
  const log1 = time.nextLog()
  const log2 = time.nextLog()
})

`TestLog#nodeId`

Unique node ID. It is used in action IDs.

Type: string.

`TestLog#store`

Log store.

Type: LogStore.

`TestLog#actions()`

Return all action (without metadata) inside log, sorted by created time.

This shortcut works only with MemoryStore.

expect(log.action).toEqual([
  { type: 'A' }
])

Returns Action[].

`TestLog#add(action, meta?)`

Add action to log.

It will set id, time (if they was missed) and added property to meta and call all listeners.

removeButton.addEventListener('click', () => {
  log.add({ type: 'users:remove', user: id })
})

Parameter	Type	Description
`action`	`Action`	The new action.
`meta` ?	`Partial<ClientMeta>`	Open structure for action metadata.

Returns Promise<ClientMeta | false>. Promise with meta if action was added to log or false if action was already in log.

`TestLog#byId(id)`

Does log already has action with this ID.

if (action.type === 'logux/undo') {
  const [undidAction, undidMeta] = await log.byId(action.id)
  log.changeMeta(meta.id, { reasons: undidMeta.reasons })
}

Parameter	Type	Description
`id`	`ID`	Action ID.

Returns Promise <[Action, ClientMeta] | [null, null]>. Promise with array of action and metadata.

`TestLog#changeMeta(id, diff)`

Change action metadata. You will remove action by setting reasons: [].

await process(action)
log.changeMeta(action, { status: 'processed' })

Parameter	Type	Description
`id`	`ID`	Action ID.
`diff`	`Partial<ClientMeta>`	Object with values to change in action metadata.

Returns Promise<boolean>. Promise with true if metadata was changed or false on unknown ID.

`TestLog#each(callback)`

Iterates through all actions, from last to first.

Return false from callback if you want to stop iteration.

log.each((action, meta) => {
  if (compareTime(meta.id, lastBeep) <= 0) {
    return false;
  } else if (action.type === 'beep') {
    beep()
    lastBeep = meta.id
    return false;
  }
})

Parameter	Type	Description
`callback`	`ActionIterator`	Function will be executed on every action.

Parameter	Type	Description
`opts`	`GetOptions`	Iterator options.
`callback`	`ActionIterator`	Function will be executed on every action.

Parameter	Type
`callback`	`ActionIterator`

Returns Promise<void>. When iteration will be finished by iterator or end of actions.

`TestLog#entries()`

Return all entries (with metadata) inside log, sorted by created time.

This shortcut works only with MemoryStore.

expect(log.action).toEqual([
  [{ type: 'A' }, { id: '1 test1 0', time: 1, added: 1, reasons: ['t'] }]
])

Returns [Action, Meta][].

`TestLog#generateId()`

Generate next unique action ID.

const id = log.generateId()

Returns ID. Unique ID for action.

`TestLog#on(event, listener)`

Subscribe for log events. It implements nanoevents API. Supported events:

preadd: when somebody try to add action to log. It fires before ID check. The best place to add reason.
add: when new action was added to log.
clean: when action was cleaned from store.

const unbind = log.on('add', (action, meta) => {
  if (action.type === 'beep') beep()
})
function disableBeeps () {
  unbind()
}

Parameter	Type	Description
`event`	`'preadd' \| 'add' \| 'clean'`	The event name.
`listener`	`ActionListener`	The listener function.

Returns Unsubscribe. Unbind listener from event.

`TestLog#removeReason(reason, criteria?)`

Remove reason tag from action’s metadata and remove actions without reason from log.

onSync(lastSent) {
  log.removeReason('unsynchronized', { maxAdded: lastSent })
}

Parameter	Type	Description
`reason`	`string`	The reason name.
`criteria` ?	`Criteria`	Criteria to select action for reason removing.

Returns Promise<void>. Promise when cleaning will be finished.

TestPair

Extends LocalPair.

Two paired loopback connections with events tracking to be used in Logux tests.

import { TestPair } from '@logux/core'
it('tracks events', async () => {
  const pair = new TestPair()
  const client = new ClientNode(pair.right)
  await pair.left.connect()
  expect(pair.leftEvents).toEqual('connect')
  await pair.left.send(msg)
  expect(pair.leftSent).toEqual([msg])
})

Parameter	Type	Description
`delay` ?	`number`	Delay for connection and send events. Default is `1`.

`TestPair#delay`

Delay for connection and send events to emulate real connection latency.

Type: number.

`TestPair#left`

First connection. Will be connected to right one after connect().

new ClientNode('client, log1, pair.left)

Type: LocalConnection.

`TestPair#leftEvents`

Emitted events from left connection.

await pair.left.connect()
pair.leftEvents //=> [['connect']]

Type: string[][].

`TestPair#leftNode`

Node instance used in this test, connected with left.

function createTest () {
  test = new TestPair()
  test.leftNode = ClientNode('client', log, test.left)
  return test
}

Type: BaseNode<{ }, TestLog>.

`TestPair#leftSent`

Sent messages from left connection.

await pair.left.send(msg)
pair.leftSent //=> [msg]

Type: Message[].

`TestPair#right`

Second connection. Will be connected to right one after connect().

new ServerNode('server, log2, pair.right)

Type: LocalConnection.

`TestPair#rightEvents`

Emitted events from right connection.

await pair.right.connect()
pair.rightEvents //=> [['connect']]

Type: string[][].

`TestPair#rightNode`

Node instance used in this test, connected with right.

function createTest () {
  test = new TestPair()
  test.rightNode = ServerNode('client', log, test.right)
  return test
}

Type: BaseNode<{ }, TestLog>.

`TestPair#rightSent`

Sent messages from right connection.

await pair.right.send(msg)
pair.rightSent //=> [msg]

Type: Message[].

`TestPair#clear()`

Clear all connections events and messages to test only last events.

await client.connection.connect()
pair.clear() // Remove all connecting messages
await client.log.add({ type: 'a' })
expect(pair.leftSent).toEqual([
  ['sync', …]
])

`TestPair#wait(receiver?)`

Return Promise until next event.

pair.left.send(['test'])
await pair.wait('left')
pair.leftSend //=> [['test']]

Parameter	Type	Description
`receiver` ?	`'left' \| 'right'`	Wait for specific receiver event.

Returns Promise<void>. Promise until next event.

TestTime

Creates special logs for test purposes.

Real logs use real time in actions ID, so log content will be different on every test execution.

To fix it Logux has special logs for tests with simple sequence timer. All logs from one test should share same time. This is why you should use log creator to share time between all logs in one test.

import { TestTime } from '@logux/core'

it('tests log', () => {
  const log = TestTime.getLog()
})

it('tests 2 logs', () => {
  const time = new TestTime()
  const log1 = time.nextLog()
  const log2 = time.nextLog()
})

`TestTime.getLog(opts?)`

Shortcut to create time and generate single log. Use it only if you need one log in test.

it('tests log', () => {
  const log = TestTime.getLog()
})

Parameter	Type	Description
`opts` ?	`TestLogOptions`	Log options.

Returns TestLog.

`TestTime#lastId`

Last letd number in log’s nodeId.

Type: number.

`TestTime#nextLog(opts?)`

Return next test log in same time.

it('tests 2 logs', () => {
  const time = new TestTime()
  const log1 = time.nextLog()
  const log2 = time.nextLog()
})

Parameter	Type	Description
`opts` ?	`TestLogOptions`	Log options.

Returns TestLog.

WsConnection

Extends Connection.

Logux connection for browser WebSocket.

import { WsConnection } from '@logux/core'

const connection = new WsConnection('wss://logux.example.com/')
const node = new ClientNode(nodeId, log, connection, opts)

Parameter	Type	Description
`url`	`string`	WebSocket server URL.
`Class` ?	`any`
`opts` ?	`any`	Extra option for WebSocket constructor.

`WsConnection#connected`

Is connection is enabled.

Type: boolean.

`WsConnection#destroy`

Optional method to disconnect and unbind all even listeners.

Type: () => void.

`WsConnection#ws`

WebSocket instance.

Type: WS.

`WsConnection#connect()`

Start connection. Connection should be in disconnected state from the beginning and start connection only on this method call.

This method could be called again if connection moved to disconnected state.

Returns Promise<void>. Promise until connection will be established.

`WsConnection#disconnect(reason?)`

Finish current connection.

Parameter	Type	Description
`reason` ?	`'error' \| 'timeout' \| 'destroy'`	Disconnection reason.

`WsConnection#on(event, listener)`

Subscribe for connection events. It implements nanoevents API. Supported events:

connecting: connection establishing was started.
connect: connection was established by any side.
disconnect: connection was closed by any side.
message: message was receive from remote node.
error: error during connection, sending or receiving.

Parameter	Type	Description
`event`	`'connecting' \| 'connect' \| 'disconnect'`	Event name.
`listener`	`() => void`	Event listener.

Parameter	Type
`event`	`'error'`
`listener`	`(error: Error) => void`

Parameter	Type
`event`	`'message'`
`listener`	`(msg: Message) => void`

Parameter	Type
`event`	`'disconnect'`
`listener`	`(reason: string) => void`

Returns Unsubscribe. Unbind listener from event.

`WsConnection#send(message)`

Send message to connection.

Parameter	Type	Description
`message`	`Message`	The message to be sent.

Functions

`attention(client)`

Highlight tabs on synchronization errors.

import { attention } from '@logux/client'
attention(client)

Parameter	Type	Description
`client`	`Client`	Observed Client instance.

Returns () => void. Unbind listener.

`badge(client, opts)`

Display Logux widget in browser.

import { badge, badgeEn } from '@logux/client'
import { badgeStyles } from '@logux/client/badge/styles'

badge(client, {
 messages: badgeEn,
 styles: {
   ...badgeStyles,
   synchronized: { backgroundColor: 'green' }
 },
 position: 'top-left'
})

Parameter	Type	Description
`client`	`Client`	Observed Client instance.
`opts`	`BadgeOptions`	Widget settings.

Returns () => void. Unbind badge listener and remove widget from DOM.

`confirm(client)`

Show confirm popup, when user close tab with non-synchronized actions.

import { confirm } from '@logux/client'
confirm(client)

Parameter	Type	Description
`client`	`Client`	Observed Client instance.

Returns () => void. Unbind listener.

`createStoreCreator(client, options?)`

Connects Logux client to Vuex’s createStore function.

import { CrossTabClient, createStoreCreator } from '@logux/vuex'

const client = new CrossTabClient({
  subprotocol: '1.0.0',
  server: process.env.NODE_ENV === 'development'
    ? 'ws://localhost:31337'
    : 'wss://logux.example.com',
  userId: 'anonymous',
  token: ''
})

const createStore = createStoreCreator(client)

const store = createStore({
  state: {},
  mutations: {},
  actions: {},
  modules: {}
})

store.client.start()

Parameter	Type	Description
`client`	`C`	Logux Client.
`options` ?	`LoguxVuexOptions`	Logux Vuex options.

Returns createStore<L, C>. Vuex’s createStore function, compatible with Logux Client.

`eachStoreCheck(test)`

Pass all common tests for Logux store to callback.

import { eachStoreCheck } from '@logux/core'

eachStoreCheck((desc, creator) => {
  it(desc, creator(() => new CustomStore()))
})

Parameter	Type	Description
`test`	`(name: string, testCreator: (storeCreator: () => LogStore) => () => void) => void`	Callback to create tests in your test framework.

`favicon(client, links)`

Change favicon to show Logux synchronization status.

import { favicon } from '@logux/client'
favicon(client, {
  normal: '/favicon.ico',
  offline: '/offline.ico',
  error: '/error.ico'
})

Parameter	Type	Description
`client`	`Client`	Observed Client instance.
`links`	`FaviconLinks`	Favicon links.

Returns () => void. Unbind listener.

`isFirstOlder(firstMeta, secondMeta)`

Compare time, when log entries were created.

It uses meta.time and meta.id to detect entries order.

import { isFirstOlder } from '@logux/core'
if (isFirstOlder(lastBeep, meta) {
  beep(action)
  lastBeep = meta
}

Parameter	Type	Description
`firstMeta`	`Meta \| undefined`	Some action’s metadata.
`secondMeta`	`Meta \| undefined`	Other action’s metadata.

Returns boolean.

`log(client, messages?)`

Display Logux events in browser console.

import { log } from '@logux/client'
log(client, { ignoreActions: ['user/add'] })

Parameter	Type	Description
`client`	`Client`	Observed Client instance.
`messages` ?	`LogMessages`	Disable specific message types.

Returns () => void. Unbind listener.

`parseId(id)`

Parse meta.id or Node ID into component: user ID, client ID, node ID.

import { parseId } from '@logux/core'
const { userId, clientId } = parseId(meta.id)

Parameter	Type	Description
`id`	`string`	Action or Node ID

Returns IDComponents.

`status(client, callback, options?)`

Low-level function to show Logux synchronization status with your custom UI. It is used in badge widget.

import { status } from '@logux/client'
status(client, current => {
  updateUI(current)
})

Parameter	Type	Description
`client`	`Client`	Observed Client instance.
`callback`	`StatusListener`
`options` ?	`StatusOptions`

Returns () => void. Unbind listener.

`useStore(injectKey?)`

Composable function that injects store into the component.

import { useStore } from '@logux/vuex'

export default {
  setup () {
    let store = useStore()
    store.commit.sync('user/rename')
  }
}

Parameter	Type
`injectKey` ?	`InjectionKey<LoguxVuexStore<S, L, C>> \| string`

Returns LoguxVuexStore<S, L, C>. Store instance.

`useSubscription(channels, options?)`

Composable function that subscribes for channels during component initialization and unsubscribes on unmount.

It watches for channels changes and returns isSubscribing flag that indicates loading state.

<template>
  <div v-if="isSubscribing">Loading</div>
  <h1 v-else>{{ user.name }}</h1>
</template>

<script>
import { toRefs } from 'vue'
import { useStore, useSubscription } from '@logux/vuex'

export default {
  props: ['userId'],
  setup (props) {
    let store = useStore()
    let { userId } = toRefs(props)
    let isSubscribing = useSubscription(() => [`user/${userId.value}`])

    let user = computed(() => store.state.users[userId.value])

    return { isSubscribing, user }
  }
})
</script>

Parameter	Type	Description
`channels`	`Channels`	Channels to subscribe.
`options` ?	`useSubscriptionOptions`	Options.

Returns Ref<boolean>. true during data loading.

Variables

Component-wrapper that subscribes for channels during component initialization and unsubscribes on unmount.

It watches for channels changes and isSubscribing indicates loading state.

<template>
  <subscribe :channels="channels" v-slot="{ isSubscribing }">
    <h1 v-if="isSubscribing">Loading</h1>
    <h1 v-else>{{ user.name }}</h1>
  </subscribe>
</template>

<script>
import { toRefs, computed } from 'vue'
import { useStore, Subscribe } from '@logux/vuex'

export default {
  components: { Subscribe },
  props: ['userId'],
  setup (props) {
    let store = useStore()
    let { userId } = toRefs(props)

    let user = computed(() => store.state.users[userId.value])
    let channels = computed(() => [`users/${userId.value}`])

    return {
      user,
      channels
    }
  }
}
</script>

Type: { }.

`badgeEn`

English translation for widget.

Type: BadgeMessages.

`badgeRu`

Russian translation for widget.

Type: BadgeMessages.

`badgeStyles`

Type: BadgeStyles.

Types

`Action`

Property	Type	Description
`type`	`string`	Action type name.

`ActionIterator(action, meta)`

Parameter	Type
`action`	`Action`
`meta`	`ClientMeta`

Returns boolean | void.

`ActionListener(action, meta)`

Parameter	Type
`action`	`Action`
`meta`	`ClientMeta`

`AnyAction`

Type: Action & { [extra: string]: any }.

`Authentificator(nodeId, token, headers)`

Parameter	Type
`nodeId`	`string`
`token`	`string`
`headers`	`H \| { }`

Returns Promise<boolean>.

`BadgeMessages`

Type: { denied: string, disconnected: string, error: string, protocolError: string, sending: string, syncError: string, synchronized: string, wait: string }.

`BadgeOptions`

Property	Type	Description
`duration` ?	`number`	Synchronized state duration. Default is `3000`.
`messages`	`BadgeMessages`	Widget text for different states.
`position` ?	`'top-left' \| 'top-center' \| 'top-right' \| 'middle-left' \| 'middle-center' \| 'middle-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'`	Widget position. Default is `bottom-right`.
`styles`	`BadgeStyles`	Inline styles for different states.

`BadgeStyles`

Type: { base: object, connecting: object, disconnected: object, error: object, icon: { disconnected: string, error: string, protocolError: string, sending: string, synchronized: string, wait: string }, protocolError: object, sending: object, synchronized: object, text: object, wait: object }.

`Channel`

Type: string | { channel: string }.

`Channels`

Type: ComputedGetter<Channel[]> | ComputedRef<Channel[]> | Channel[].

`ClientActionListener(action, meta)`

Parameter	Type
`action`	`Action`
`meta`	`ClientMeta`

`ClientMeta`

Extends Meta.

Property	Type	Description
`added`	`number`	Sequence number of action in current log. Log fills it.
`id`	`ID`	Action unique ID. Log sets it automatically.
`keepLast` ?	`string`	Set value to `reasons` and this reason from old action.
`reasons`	`string[]`	Why action should be kept in log. Action without reasons will be removed.
`subprotocol` ?	`string`	Set code as reason and remove this reasons from previous actions.
`time`	`number`	Action created time in current node time. Milliseconds since UNIX epoch.
`noAutoReason` ?	`boolean`	Disable setting `timeTravel` reason.
`sync` ?	`boolean`	This action should be synchronized with other browser tabs and server.
`tab` ?	`TabID`	Action should be visible only for browser tab with the same `client.tabId`.

`ClientOptions`

Property	Type	Description
`allowDangerousProtocol` ?	`boolean`	Do not show warning when using `ws://` in production.
`attempts` ?	`number`	Maximum reconnection attempts. Default is `Infinity`.
`maxDelay` ?	`number`	Maximum delay between reconnections. Default is `5000`.
`minDelay` ?	`number`	Minimum delay between reconnections. Default is `1000`.
`ping` ?	`number`	Milliseconds since last message to test connection by sending ping. Default is `10000`.
`prefix` ?	`string`	Prefix for `IndexedDB` database to run multiple Logux instances in the same browser. Default is `logux`.
`server`	`string \| Connection`	Server URL.
`store` ?	`LogStore`	Store to save log data. Default is `MemoryStore`.
`subprotocol`	`string`	Client subprotocol version in SemVer format.
`time` ?	`TestTime`	Test time to test client.
`timeout` ?	`number`	Timeout in milliseconds to break connection. Default is `20000`.
`token` ?	`string \| TokenGenerator`	Client credentials for authentication.
`userId`	`string`	User ID.

`Criteria`

Property	Type	Description
`id` ?	`ID`	Remove reason only for action with `id`.
`maxAdded` ?	`number`	Remove reason only for actions with lower `added`.
`minAdded` ?	`number`	Remove reason only for actions with bigger `added`.
`olderThan` ?	`Meta`	Remove reason only older than specific action.
`youngerThan` ?	`Meta`	Remove reason only younger than specific action.

`EmptyHeaders`

Type: { [key: string]: undefined }.

`FaviconLinks`

Property	Type	Description
`error` ?	`string`	Error favicon link.
`normal` ?	`string`	Default favicon link. By default, it will be taken from current favicon.
`offline` ?	`string`	Offline favicon link.

`Filter(action, meta)`

Parameter	Type
`action`	`Action`
`meta`	`Meta`

Returns Promise<boolean>.

`GetOptions`

Property	Type	Description
`order` ?	`'created' \| 'added'`	Sort entries by created time or when they was added to current log.

`ID`

Action unique ID accross all nodes.

"1564508138460 380:R7BNGAP5:px3-J3oc 0"

Type: string.

`IDComponents`

Type: { clientId: string, nodeId: string, userId: string | undefined }.

`LastSynced`

Property	Type	Description
`received`	`number`	The `added` value of latest received event.
`sent`	`number`	The `added` value of latest sent event.

`LogMessages`

Property	Type	Description
`add` ?	`boolean`	Disable action added messages.
`clean` ?	`boolean`	Disable action cleaned messages.
`error` ?	`boolean`	Disable error messages.
`ignoreActions` ?	`string[]`	Disable action messages with specific types.
`role` ?	`boolean`	Disable tab role messages.
`state` ?	`boolean`	Disable connection state messages.
`user` ?	`boolean`	Disable user ID changing.

`LogOptions`

Property	Type	Description
`nodeId`	`string`	Unique current machine name.
`store`	`S`	Store for log.

`LoguxErrorOptions`

Type: { bruteforce: void, timeout: number, unknown-message: string, wrong-credentials: void, wrong-format: string, wrong-protocol: Versions, wrong-subprotocol: Versions }.

`LoguxVuexAction`

Type: Action & VuexPayload.

`LoguxVuexActionContext`

`LoguxVuexActionHandler`

Type: (this: LoguxVuexStore<R>, injectee: LoguxVuexActionContext<S, R>, payload?: any) => any.

`LoguxVuexActionObject`

`LoguxVuexActionTree`

`LoguxVuexCommit(type, payload?, options?)`

Parameter	Type
`type`	`string`
`payload` ?	`any`
`options` ?	`CommitOptions`

Parameter	Type
`payloadWithType`	`A`
`options` ?	`CommitOptions`

Parameter	Type
`type`	`string`
`payload` ?	`any`
`options` ?	`CommitOptions`

Parameter	Type
`payloadWithType`	`P`
`options` ?	`CommitOptions`

`LoguxVuexCommit#crossTab(type, payload?, meta?)`

Adds cross-tab action to log and updates store state. This action will be visible only for all tabs.

store.commit.crossTab(
  { type: 'CHANGE_FAVICON', favicon },
  { reasons: ['lastFavicon'] }
).then(meta => {
  store.log.removeReason('lastFavicon', { maxAdded: meta.added - 1 })
})

Parameter	Type	Description
`type`	`string`	Action type.
`payload` ?	`any`	Action’s payload.
`meta` ?	`Partial<ClientMeta>`	Action’s metadata.

Parameter	Type	Description
`action`	`A`	Action.
`meta` ?	`Partial<ClientMeta>`	Action’s metadata.

Returns Promise<ClientMeta>. Promise when action will be processed by the server.

`LoguxVuexCommit#local(type, payload?, meta?)`

Adds local action to log and updates store state. This action will be visible only for current tab.


store.commit.local(
  { type: 'OPEN_MENU' },
  { reasons: ['lastMenu'] }
).then(meta => {
  store.log.removeReason('lastMenu', { maxAdded: meta.added - 1 })
})

Parameter	Type	Description
`type`	`string`	Action type.
`payload` ?	`any`	Action’s payload.
`meta` ?	`Partial<ClientMeta>`	Action’s metadata.

Parameter	Type	Description
`action`	`A`	Action.
`meta` ?	`Partial<ClientMeta>`	Action’s metadata.

Returns Promise<ClientMeta>. Promise when action will be processed by the server.

`LoguxVuexCommit#sync(type, payload?, meta?)`

Adds sync action to log and updates store state. This action will be visible only for server and all browser tabs.

store.commit.sync(
  { type: 'CHANGE_NAME', name },
  { reasons: ['lastName'] }
).then(meta => {
  store.log.removeReason('lastName', { maxAdded: meta.added - 1 })
})

Parameter	Type	Description
`type`	`string`	Action type.
`payload` ?	`any`	Action’s payload.
`meta` ?	`Partial<ClientMeta>`	Action’s metadata.

Parameter	Type	Description
`action`	`A`	Action.
`meta` ?	`Partial<ClientMeta>`	Action’s metadata.

Returns Promise<ClientMeta>. Promise when action will be processed by the server.

`LoguxVuexNativeAction`

Type: LoguxVuexActionHandler<S, R> | LoguxVuexActionObject<S, R>.

`LoguxVuexOptions`

Property	Type	Description
`cleanEvery` ?	`number`	How often we need to clean log from old actions. Default is every `25` actions.
`onMissedHistory` ?	`(action: Action) => void`	Callback when there is no history to replay actions accurate.
`reasonlessHistory` ?	`number`	How many actions without `meta.reasons` will be kept for time travel. Default is `1000`.
`saveStateEvery` ?	`number`	How often save state to history. Default is `50`.

`LoguxVuexStoreOptions`

`Mapper(action, meta)`

Parameter	Type
`action`	`Action`
`meta`	`Meta`

Returns Promise<[Action, Meta]>.

`Message`

`Meta`

Property	Type	Description
`added`	`number`	Sequence number of action in current log. Log fills it.
`id`	`ID`	Action unique ID. Log sets it automatically.
`keepLast` ?	`string`	Set value to `reasons` and this reason from old action.
`reasons`	`string[]`	Why action should be kept in log. Action without reasons will be removed.
`subprotocol` ?	`string`	Set code as reason and remove this reasons from previous actions.
`time`	`number`	Action created time in current node time. Milliseconds since UNIX epoch.

`NodeOptions`

Property	Type	Description
`auth` ?	`Authentificator<H>`	Function to check client credentials.
`fixTime` ?	`boolean`	Detect difference between client and server and fix time in synchronized actions.
`inFilter` ?	`Filter`	Function to filter actions from remote node. Best place for access control.
`inMap` ?	`Mapper`	Map function to change remote node’s action before put it to current log.
`outFilter` ?	`Filter`	Filter function to select actions to synchronization.
`outMap` ?	`Mapper`	Map function to change action before sending it to remote client.
`ping` ?	`number`	Milliseconds since last message to test connection by sending ping.
`subprotocol` ?	`string`	Application subprotocol version in SemVer format.
`timeout` ?	`number`	Timeout in milliseconds to wait answer before disconnect.
`token` ?	`string \| TokenGenerator`	Client credentials. For example, access token.

`Page`

Property	Type	Description
`entries`	`[Action, Meta][]`	Pagination page.
`next` ?	`() => Promise<Page>`

`ReconnectOptions`

Property	Type	Description
`attempts` ?	`number`	Maximum reconnecting attempts.
`maxDelay` ?	`number`	Maximum delay between reconnecting.
`minDelay` ?	`number`	Minimum delay between reconnecting.

`StateListener(state, prevState, action, meta)`

Parameter	Type
`state`	`S`
`prevState`	`S`
`action`	`A`
`meta`	`ClientMeta`

`StatusListener(current, details)`

Parameter	Type
`current`	`'synchronized' \| 'synchronizedAfterWait' \| 'disconnected' \| 'connecting' \| 'connectingAfterWait' \| 'protocolError' \| 'syncError' \| 'error' \| 'denied' \| 'wait'`
`details`	`undefined \| Error \| { action: Action, meta: ClientMeta }`

`StatusOptions`

Property	Type	Description
`duration` ?	`number`	Synchronized state duration. Default is `3000`.

Property	Type	Description
`nodeId`	`string`	Unique log name.
`store`	`LogStore`	Store for log. Will use `MemoryStore` by default.

Parameter	Type	Description
`options`	`LoguxVuexStoreOptions<S>`	Vuex store options.

Returns LoguxVuexStore<S, L, C>. Vuex store, compatible with Logux Client.

`useSubscriptionOptions`

Property	Type	Description
`debounce` ?	`number`	Delay in milliseconds to avoid returning `true` when switching between `channels`.
`store` ?	`LoguxVuexStore`	Logux Vuex store.