@gasket/core
Installation
Existing apps
npm install @gasket/core
Add a gasket.js
file to the root of your project.
This can be a .js
extension if your package.json has the type
field set to module
.
It is also possible to use with a .ts
extension if you have TypeScript configured.
// gasket.js
import { makeGasket } from '@gasket/core';
import LoggerPlugin from '@gasket/plugin-logger';
import MyPlugin from './my-plugin';
export default makeGasket({
plugins: [
LoggerPlugin,
MyPlugin
]
});
You can now import the Gasket instance from your gasket.js
file into your
application code.
With a Gasket, you can fire actions that will trigger lifecycles hooked
by plugins which encapsulate functionality allowing reuse across many applications.
Registered plugins
A plugin is a module that exports a name
and hooks
object
(See Plugins Guide).
In your gasket.js
file, you can import plugins and add them to the plugins
array of the Gasket configuration.
Lifecycles
When a new Gasket is created, there are two lifecycles synchronous executed followed by two asynchronous lifecycles.
You can determine when the asynchronous lifecycles have completed by verifying that the isReady
property on the Gasket instance has been resolved.
import gasket from './gasket.js';
gasket.isReady.then(() => {
gasket.actions.startServer();
});
The lifecycles are executed in the following order:
Synchronous lifecycles
Asynchronous lifecycles
init
The init
lifecycle allows the earliest entry to setting up a Gasket instance.
It can be used for setting up an initial state.
// gasket-plugin-example.js
const name = 'gasket-plugin-example';
let _initializedTime;
const hooks = {
init(gasket) {
_initializedTime = Date.now();
}
};
export default { name, hooks };
While it is possible to attach properties to the gasket
instance, it is not
recommended.
Instead, a plugin can register actions that can be executed to retrieve
values the plugin wishes to make available.
configure
The configure
lifecycle is the first lifecycle executed when a Gasket is
instantiated.
This allows any registered plugins to adjust the configuration before further
lifecycles are executed.
// gasket-plugin-example.js
const name = 'gasket-plugin-example';
const hooks = {
configure(gasket, gasketConfig) {
// Modify the configuration
return {
...gasketConfig,
example: true
};
}
};
export default { name, hooks };
In this example, we register an action getDoodads
that will only execute if the
example
configuration is set to true
.
It will then execute the doodads
lifecycle, allowing any registered plugin to
provide doodads.
prepare
The prepare
lifecycle is the first asynchronous lifecycle executed after the configure
lifecycle. It is used to add any additional setup that requires asynchronous operations.
// gasket-plugin-example.js
const name = 'gasket-plugin-example';
const hooks = {
async prepare(gasket) {
const asyncConfig = await getAsyncConfig();
gasket.config = {
...gasket.config,
...asyncConfig
};
}
};
export default { name, hooks };
ready
The ready
is the last lifecycle executed and is used to signal that
the Gasket instance is fully initialized and ready to be used.
After the ready
lifecycle has been executed, the isReady
property on the Gasket instance will be resolved signaling the last step of the Gasket instance initialization.
// gasket-plugin-example.js
const name = 'gasket-plugin-example';
const hooks = {
async ready(gasket) {
console.log('Gasket is ready!');
}
};
export default { name, hooks };
Actions
Plugins can register actions that can be fired by the application code where the Gasket is imported, or in other plugins.
// gasket-plugin-example.js
const name = 'gasket-plugin-example';
const actions = {
async getDoodads(gasket) {
if (gasket.config.example) {
const dodaads = await gasket.exec('dodaads');
return dodaads.flat()
}
}
};
export default { name, actions };
If a plugin needs to make properties available to other plugins, it should register an action that can be executed to retrieve the value.
// gasket-plugin-example.js
const name = 'gasket-plugin-example';
+ let _initializedTime;
+ const actions = {
+ getInitializedTime() {
+ return _initializedTime;
+ }
+ };
const hooks = {
init(gasket) {
- gasket.initializedTime = Date.now();
+ _initializedTime = Date.now();
},
configure(gasket) {
- const time = gasket.initializedTime;
+ const time = gasket.actions.getInitializedTime();
// do something with time...
}
};
- export default { name, hooks };
+ export default { name, actions, hooks };
Debugging
Gasket makes use of the debug module to provide various debug outputs. Gasket
packages and plugins use the gasket
namespace.
DEBUG=gasket:* npm run start
Tracing
You can narrow down to see the action and lifecycle execution order in the
console output under the gasket:trace
namespace.
DEBUG=gasket:trace* npm run start
The following symbols indicate the step and type of execution:
⋌
New Trace Branch★
Action Start◆
Synchronous Lifecycle Start◇
Asynchronous Lifecycle Start↪
Plugin lifecycle Hook
When ever the app or a plugin executes a lifecycle or an action, it will be
passed a traceable proxy object, which can be used to follow the execution
path of the application.
Any action or lifecycle that is executed from the root gasket
object will
start a new trace "branch".
New branches can be created by calling gasket.traceBranch()
to help debug
certain lifecycle flows.
Additionally, it is possible to start fresh traces by calling
gasket.traceRoot()
.
This method should will exit the current branch's trace history
and start a fresh.
Use this sparingly only for situations such as tracing handling for new requests.
Recursion Protection
Gasket uses the trace history to catch and prevent infinite recursion. If a lifecycle is executed more than once in the same trace history, it will throw an error and halt the execution.
While it is ok to execute the same action at various steps in an event chain,
you must avoid calling the same lifecycle from within itself.
Memoization can help avoid this issue, and using req
as a key can help for
request-specific memoization, which is also a good performance optimization.
// gasket-plugin-example.js
const reqMap = new WeakMap();
const name = 'gasket-plugin-example';
const actions = {
async getDoodads(gasket, req) {
if(!reqMap.has(req)) {
const doodads = await gasket.exec('doodads', req);
reqMap.set(req, doodads);
}
return reqMap.get(req);
}
};
const hooks = {
// ...
};
export default { name, actions, hooks };