@gasket/core

@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 three lifecycles executed in the following order:

1. init
2. actions
3. configure

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. 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 hooks = {
  init(gasket) {
-    gasket.initializedTime = Date.now();
+    _initializedTime = Date.now();
  },
+  actions() {
+    return {
+      getInitializedTime() {
+        return _initializedTime;
+      }
+    }
+  },
  configure(gasket) {
-    const time = gasket.initializedTime;
+    const time = gasket.actions.getInitializedTime();
  }
};

export default { name, hooks };

actions

The actions lifecycle is the second lifecycle executed when a Gasket is created. This will let plugins 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 hooks = {
  actions(gasket) {
    return {
      async getDoodads() {
        if(gasket.config.example) {
          const dodaads = await gasket.exec('dodaads');
          return dodaads.flat()
        }
      }
    }
  }
};

export default { name, hooks };

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.