# Actions
Logux actions are very similar to [Redux actions]. JSON objects describe what was changed in the [application state]. If the user does something, the client should create action to change the state. State changes will update UI.
For instance, if user press Like button, your application will create an action:
```js
{ type: 'like/add', postId: 39678 }
```
Actions are immutable. You can’t change action. If you want to change the data or revert changes, you need to add a new action.
There are only two mandatory requirements for actions:
1. They must have `type` property with a string value.
2. You can use only string, number, boolean, `null`, array, and object as values. All values should be serializable to JSON. This is why functions, class instances, `Symbol`, `BigInt` is prohibited.
[application state]: ./state.md
[Redux actions]: https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow#actions
## Atomic Actions
We recommend keeping actions atomic. It means that action should not contain current state. For instance, it is better to generate `likes/add` and `likes/remove` on the client, rather than `likes/set` with the exact number.
The server can send old action made by another user when this client was offline (for instance, other users will set like to the post too). In this case, Logux Redux will revert own recent actions, add old changes from the server, and replay own actions again. As a result, action will be applied again to a different state. Atomic `likes/add` will work great, but non-atomic `likes/set` will override other changes.
You can use CRDT as inspiration to create atomic actions.
## System Actions
Logux has a few built-in actions with `logux/` prefix.
### `logux/processed`
```js
{ type: 'logux/processed', id: '1560954012838 380:Y7bysd:O0ETfc 0' }
```
Logux Server response with `logux/processed` when it received and processed the action from the client. `action.id` of `logux/processed` will be equal to `meta.id` of received action.
### `logux/undo`
```js
{ type: 'logux/undo', id: '1560954012838 380:Y7bysd:O0ETfc 0', action: { type: 'likes/add' } reason: 'error' }
```
This action asks clients to revert action. `action.id` is equal to `meta.id` of reverted action and `action.action` is the original reverted action. Logux Server sends this action on any error during action processing. In this case, `logux/processed` will not be sent.
There are 4 standard `reason` values in the action:
- `error`
- `denied`
- `unknownType`
- `wrongChannel`
A developer can create `logux/undo` at any moment on the server even after `logux/processed` was sent.
Node.js
```js
server.undo(action, meta, 'too late')
```
Django
```python
self.undo('too late')
```
Ruby on Rails
```ruby
Logux.undo(meta, reason: 'too late')
```
Redux client
```js
store.dispatch.sync({
type: 'logux/undo',
id: meta.id,
action: action,
reason: 'too late'
})
```
Vuex client
```js
store.commit.sync({
type: 'logux/undo',
id: meta.id,
action: action,
reason: 'too late'
})
```
Pure JS client
```js
client.log.add(
{ type: 'logux/undo', id: meta.id, action: action, reason: 'too late' },
{ sync: true }
)
```
Redux client
There are four ways to add action to Logux Redux.
1. The **standard Redux** way to dispatch actions. Action will _not_ be sent to the server or another browser tab. There is no way to set action’s meta in this method.
```js
store.dispatch(action)
```
This way is the best for small UI states, like to open/close menu.
2. **Local action with metadata**. Action will _not_ be sent to the server or another browser tab. Compare to standard Redux way, `dispatch.local` can set action’s meta.
```js
store.dispatch.local(action, meta)
```
3. **Cross-tab action.** It sends action to all tabs in this browser.
```js
store.dispatch.crossTab(action)
store.dispatch.crossTab(action, meta)
```
This method is the best for local data like client settings, which you will save to `localStorage`.
4. **Server actions.** It sends action to the server _and_ all tabs in this browser.
```js
store.dispatch.sync(action)
store.dispatch.sync(action, meta)
```
This method is the best for models. For instance, when the user adds a new comment or changed the post.
Vuex client
There are four ways to add action to Logux Vuex.
1. The **standard Vuex** way to commit mutations. Action will _not_ be sent to the server or another browser tab. There is no way to set action’s meta in this method.
```js
store.commit(action)
store.commit(type, payload)
```
This way is the best for small UI states, like to open/close menu.
2. **Local action with metadata**. Action will _not_ be sent to the server or another browser tab. Compare to standard Vuex way, `commit.local` can set action’s meta.
```js
store.commit.local(action, meta)
```
3. **Cross-tab action.** It sends action to all tabs in this browser.
```js
store.commit.crossTab(action)
store.commit.crossTab(action, meta)
```
This method is the best for local data like client settings, which you will save to `localStorage`.
4. **Server actions.** It sends action to the server _and_ all tabs in this browser.
```js
store.commit.sync(action)
store.commit.sync(action, meta)
```
This method is the best for models. For instance, when the user adds a new comment or changed the post.
Pure JS client
1. **Local action.** Action will _not_ be sent to the server or another browser tab.
```js
client.log.add(action, { tab: client.id })
```
This way is the best for small UI states, like opened/closed menu state.
2. **Cross-tab action.** It sends action to all tabs in this browser.
```js
client.log.add(action, meta)
```
This method is the best to work with local data like client settings, which you will save to `localStorage`.
3. **Send to server.** It sends action to the server _and_ all tabs in this browser.
```js
client.log.add(action, { sync: true })
```
This method is the best for working with models. For instance, when the user adds a new comment or changed the post.
Redux client
Actions added by `dispatch.sync()` and `dispatch.crossTab()` will be visible to all browser tabs.
```js
// All browser tabs will receive these actions
store.dispatch.crossTab(action)
store.dispatch.sync(action)
// Only current browser tab will receive these actions
store.dispatch(action)
store.dispatch.local(action)
```
`client.log.type(type, fn)` and `client.log.on('add', fn)` will not see cross-tab actions. You must set listeners by `client.on(type, fn)` and `client.on('add', fn)`.
Reducers will see cross-tab actions, you do not need to do anything.
Vuex client
Actions added by `commit.sync()` and `commit.crossTab()` will be visible to all browser tabs.
```js
// All browser tabs will receive these actions
store.commit.crossTab(action)
store.commit.sync(action)
// Only current browser tab will receive these actions
store.commit(action)
store.commit.local(action)
```
`client.log.type(type, fn)` and `client.log.on('add', fn)` will not see cross-tab actions. You must set listeners by `client.on(type, fn)` and `client.on('add', fn)`.
Mutations will see cross-tab actions, you do not need to do anything.
Pure JS client
Any action without explicit `meta.tab` will be sent to all browser tabs.
```js
// All browser tabs will receive this action
client.log.add(action)
// Only current browser tab will receive this action
client.log.add(action, { tab: client.tabId })
```
`client.log.type(type, fn)` and `client.log.on('add', fn)` will not see cross-tab actions. You must set listeners by `client.on(type, fn)` and `client.on('add', fn)`.
Redux client
```js
store.dispatch.sync({ type: 'likes/add', postId })
```
Vuex client
```js
store.commit.sync({ type: 'likes/add', postId })
```
Pure JS client
```js
client.log.add({ type: 'likes/add', postId }, { sync: true })
```
Redux client
```js
import { badge, badgeEn } from '@logux/client'
import { badgeStyles } from '@logux/client/badge/styles'
badge(store.client, { messages: badgeMessages, styles: badgeStyles })
```
Vuex client
```js
import { badge, badgeEn } from '@logux/client'
import { badgeStyles } from '@logux/client/badge/styles'
badge(store.client, { messages: badgeMessages, styles: badgeStyles })
```
Pure JS client
```js
import { badge, badgeEn } from '@logux/client'
import { badgeStyles } from '@logux/client/badge/styles'
badge(client, { messages: badgeEn, styles: badgeStyles })
```
Redux client
```js
showLoader()
try {
await dispatch.sync({ type: 'likes/add', postId })
} catch {
showError()
}
hideLoader()
```
Vuex client
```js
showLoader()
try {
await commit.sync({ type: 'likes/add', postId })
} catch {
showError()
}
hideLoader()
```
Pure JS client
```js
showLoader()
try {
await client.sync({ type: 'likes/add', postId })
hideLoader()
} catch {
showError()
}
```
Redux client
```js
import { confirm } from '@logux/client'
confirm(store.client)
```
Vuex client
```js
import { confirm } from '@logux/client'
confirm(store.client)
```
Pure JS client
```js
import { confirm } from '@logux/client'
confirm(client)
```
Node.js
```js
server.type('likes/add', {
async access (ctx, action, meta) {
let user = db.findUser(ctx.userId)
return !user.isTroll && user.canRead(action.postId)
},
…
})
```
Django
```python
class AddLikesAction(ActionCommand):
action_type = 'likes/add'
def access(self, action: Action, meta: Meta) -> bool:
user = User.objects.get(id=meta.user_id)
return not user.is_troll and user.can_read(action['payload']['postId'])
…
```
Ruby on Rails
```ruby
# app/logux/policies/channels/likes.rb
module Policies
module Channels
class Likes < Policies::Base
def add?
user = User.find(user_id)
!user.troll? && user.can_read? action[:postId]
end
end
end
end
```
Node.js
```js
server.type('likes/add', {
…
resend (ctx, action, meta) {
return `posts/${ action.postId }`
},
…
})
```
Django
```python
class AddLikesAction(ActionCommand):
action_type = 'likes/add'
…
def resend(self, action: Action, meta: Optional[Meta]) -> List[str]:
return [f"users/{action['payload']['userId']}"]
…
```
Ruby on Rails
_Under construction. Until `resend` will be implemented in the gem._
Node.js
```js
server.type('likes/add', {
…
async process (ctx, action, meta) {
await db.query(
'UPDATE posts SET like = like + 1 WHERE post.id = ?', action.postId
)
}
})
```
Django
```python
class AddLikesAction(ActionCommand):
action_type = 'likes/add'
…
def process(self, action: Action, meta: Meta) -> None:
Post.objects.filter(id=action['postId']).update(count=F('likes') + 1)
```
Ruby on Rails
_Under construction. Until `resend` will be implemented in the gem._
Node.js
The most universal way is:
```js
someService.on('error', () => {
server.log.add({ type: 'someService/error' }, { channels: ['admins'] })
})
```
But, in most of the cases, you will return actions in channel `load` callback. You can return `action`, `[action1, action2]` or `[[action1, meta1], [action2, meta2]]`.
```js
server.channel('user/:id', {
…
async load (ctx, action, meta) {
ler user = await db.first('users', { id: ctx.params.id })
return { type: 'users/add', user }
}
})
```
Django
`logux_add` function adds Action to Logux and available at any part of code.
```python
from logux.core import logux_add
logux_add({ type: 'someService/error' }, { 'channels': ['admins'] })
```
You can return actions (`action`, `[action1, action2]` or `[[action1, meta1]]`) in channel’s `load` method.
```python
class UserChannel(ChannelCommand):
channel_pattern = r'^user/(?P\w+)$'
…
def load(self, action: Action, meta: Meta) -> Action:
user = User.objects.get(pk=self.params['user_id'])
return {'type': 'user/add', 'payload': {'user': user} }
```
Ruby on Rails
```ruby
some_service.on(:error) do
Logux.add({ type: 'someService/error' }, { channels: ['admins'] })
end
```
_Under construction. Until `send_back` will be implemented in the gem._