Action-Manager is a framework for defining, invoking, organizing, and integrating action handlers.
Visit Action-Manager for more information.
yarn add action-manager
npm install action-managerCreate an action
const printTime: Action = {
handler: () => console.log(new Date().toISOString())
}Invoke an action (without context)
await invoke(printTime)Invoke an action with context and type parameters. The context, all context properties, and all type parameters are optional.
const printTime: Action<void, {
type: string
}, {
timeZone: 'EST'
}> = {
handler: () => console.log(new Date().toISOString())
}
await invoke(printTime,
{
// These are the targets of the action
targets: [],
// These are the action parameters
params: {type: 'log'},
// This is the environment
env: {timeZone: 'EST'}
}
)The only required property in the Action interface is the handler.
Handlers accept a single optional argument: the context.
const printTime: Action = {
handler: () => console.log(new Date().toISOString())
}The power of action-manager emerges as you begin to implement the optional properties.
const printTime: Action = {
id: 'print_time',
name: 'Print Time',
description: 'Print the current time, in ISO format, to the console.'
log: true,
handler: () => console.log(new Date().toISOString())
}The action can now be used to generate user interface items, such as buttons and menu items.
Although it is not required to type the targets, params, and environment, it is foolish not to. 😉
Action<TARGET,PARAMS,ENVIRONMENT>
| Parameter | Information | Default |
|---|---|---|
| TARGET | The action target type | any |
| PARAMS | The action params type | any |
| ENVIRONMENT | The action environment type | any |
These parameter types can be set to a specific type, any, or void.
There are many advantages to invoking an action instead of directly calling its handler.
[todo show examples]
There are several types of action widgets. These widgets are implemented using several libraries.
A context object is provided to the action handler as it's only parameter.
The context is also provided to MaybeRef properties.
The action context triages properties into three buckets.
Targets are the objects an action is to be performed on. Because actions indicate the cardinality of the targets they perform on, targets can be used not only for the handler, but for calculating user interface state. For instance, a delete action can work on 1 or more targets, while a compare action can require exactly two targets. In contrast, an open file action would not require any targets.
Parameters are properties that indicate on how the action should go about acting on the targets for a particular invocation.
The environment are common properties that typically remain the same for multiple actions.
[todo]
The asRef helper function allows the developer to treat action properties
as if it were a Ref, regardless of how they are implemented. This function also takes into consideration
if the action property returns a function, and if it already returns a Ref.
By only working with Refs, the developer can treat all properties as dynamically computed values.
For example, this example will work in any combination of action.name or action.nameRef being implemented.
<template>
<button>{{asRef(action, 'name')}}</button>
</template>To use asRef, you must initialize the system with your
framework one time, before calling the utility method.
Init example:
import {ref, unref, computed} from 'vue'
import {init} from 'action-manager'
// Init action-manager with your framework
init({ref, unref, computed})import {asRef} from 'action-manager'
// Implement name or nameRef
action: Action = {
nameRef: ()=> new Date().toString(),
handler() {
}
}
action2: Action = {
name: 'hello',
handler() {
}
}
// Get the Refs
const name1Ref = asRef(action1, 'name')
const name2Ref = asRef(action2, 'name')asValue is the same as asRef, but will return a non-reactive value.
This will call any computed functions and unwrap any refs.
const name = asValue(action, 'name')The invoke lifecycle includes several hooks that can be tapped. These are useful for logging or plugin development.
import {hooks} from 'action-manager'
// Called when an action is invoked, but not yet validated
hooks.actionWasInvoked.tap((action, context) => {
})
// Called when an action is validated, but not yet executed
hooks.actionWillExecute.tap((action, context) => {
})
// Called after an action is executed
hooks.actionDidExecute.tap((action, context, retValue) => {
})yarn testyarn buildHere is an example of how you might refactor your code to use action-manager.
Your existing code is hardwired to call a function:
function logMessage(message) {
console.log(message)
}<button onclick="logMessage('hello')">Log A Message</button>We start by wrapping the function in an action handler, and typing it.
We then call invoke on the action:
const logMessage: Action<void, {
message: string
}> = {
handler(context){
console.log(context.params.message)
}
}<button onclick="invoke(logMessage, {params: {message:'hello'}})">Log A Message</button>With this in place, and not really using much more code, we have enabled all sorts of additional functionality.
We start with defining an environment that will be sent into every action.
// We now make our action typed, and also allow it to log targets.
const logMessage: Action<any, {
message: string
}> = {
handler(context) {
console.log(context.params)
if (context.targets && context.targets.length > 0) {
console.log('TARGETS:')
for (let target of context.targets) {
console.log(target)
}
}
}
}Great, now our action can be used to log not just a message, but user selected items as well.
We can define an environment that will be sent into every action.
const env = {
// We could redirect to a file, use console.warn, do nothing, or whatever
log: (...args: any[]) => console.log(...args),
// A custom formatter for strings
format: (item: T) => {
if (typeof item === 'string') {
return item.toLowerCase()
} else {
return item
}
}
}
// This is a quick way to create a type from an existing object.
// You can create the type explicity if you desire.
type ENV = typeof env
// We now add the ENV type to our action, and use it
const logMessage: Action<any, {
message: string
}, ENV> = {
handler(context) {
context.env.log(context.env.format(context.params))
if (context.targets) {
for (let target of context.targets) {
context.env.log(context.env.format(target))
}
}
}
}This environment can be used in other projects. It can also be replaced by some mock when testing.
The extensibility of this design is now showing. We can add even more properties to enable all sorts of additional features.
const logMessage: Action<any, {
message: string
}> = {
id: 'logMessage',
name: 'Log Message',
description: 'Logs a message and/or action targets',
debug: true,
log: true,
confirm: {
message: 'Log it? Really?'
},
cardinality: 'any',
onError: ['prompt', 'log'],
status: {
message: 'Logging...'
},
usage: true,
handler(context) {
// ...
}
}
registerAction(logMessage)Because we registered our action, it can now be invoked by 'ID' instead of the object. This will reduce dependencies.
Widgets such as buttons, menu items, and search results can now use the action as meta-data to generate content.
The invoker can check cardinality to ensure the action is compatible with the context.
Our runtime can log and debug information when the action is invoked.
We have instructed the runtime:
So ALL OF THIS comes for free by just using actions instead of functions...
The benefits do not stop here. Most action properties support a
propnameRef alternative that can dynamically calculate and reactively update the value.
[todo]
