Pluggable

Write your framework or application code in a functional style, and Pluggable will allow consumers of your code to override or transform any part of execution.

Async is fully supported via Promises, and a code analytics tool is made available to compile a dependency graph with metadata for all pluggables you've defined in your code.

Define a pluggable

A pluggable function is defined like so:

const myFunctionName = pluggable(function myFunctionName (myArg) {
  // reference functions this.depA, this.depB, and this.depC
}, { depA, depB, depC });

It's normal function equivalent would look like:

function myFunctionName (myArg) {
  // reference functions depA, depB, and depC
}

Define a plugin

const myPlugin = function (override, transform) {
  // Any data to persist direct pluggable invocation should be defined here.

  // Use `override` if you'd like to completely change the implementation of
  // a pluggable function.
  override("somePluggableDependency", function (username) {
    if (CONDITION) {
      return somethingOtherThanDefaultValue;
    }
    // If you'd like to only override a pluggable's behavior in certain
    // circumstances, you can CONTINUE to the next pluggable override
    // or the default behavior.
    return override.CONTINUE;
  });

  // Use `transform` if you'd like to modify the output of a pluggable function.
  transform("getUserData", function (value, args) {
    // You have access to the pluggable function's output as `value` here.
    // You have access to the originally-passed arguments as `arg` here.
    return Object.assign({}, value, { iveBeenTransformed: true });
  });
}

Get a pluggable context and invocation

import { getBaseContext } from "pluggable";
const cxt = getBaseContext(
  { anything: "you want to go in this goes here" },
  [ AllOfYour, Plugins, GoHere ]
);
myPluggableFunction.call(cxt, allOf, your, normalArgs);

Full Example

How this works is more easily explained using an example. Imagine you had a module that looked something like this:

import github from "github";

function buildSummaryString (userData) {
  const [signupDate, projects, contactInfo] = userData;
  return `User "${username}" signed up on ${signupDate} and has ${projects.length} projects.`;
}

function getUserData (username) {
  return Promise.all(
    github.getSignupDate(username),
    github.getProjects(username),
    github.getContactInfo(username)
  );
}

function getUserSummaries (usernames) {
  return Promise.all(usernames.map(username => {
    return getUserData(username).then(buildSummaryString);
  }));
}

// Which would be used like so.
getUserSummaries(["divmain"]).then(console.log);

This is a simple pattern of inputs and outputs - it is easy to test, and easy to reason about.

However, what if you'd like to allow consumers of this module to modify the behavior of one of the functions. What if they want to add additional information, or what if they want to override the behavior altogether? That's where pluggable comes in.

First, let's rewrite the above example using pluggables - then we'll look at how to modify behavior.

import github from "github";
import { pluggable } from "pluggable";

const buildSummaryString = pluggable(function buildSummaryString (userData) {
  const [signupDate, projects, contactInfo] = userData;
  return `User "${username}" signed up on ${signupDate} and has ${projects.length} projects.`;
});

const getUserData = pluggable(function getUserData (username) {
  return Promise.all(
    github.getSignupDate(username),
    github.getProjects(username),
    github.getContactInfo(username)
  );
});

const getUserSummaries = pluggable(function getUserSummaries (usernames) {
  return Promise.all(usernames.map(username => {
    return this.getUserData(username).then(this.buildSummaryString.bind(this));
  }));
}, { buildSummaryString, getUserData });

You'll want to especially take note of the changes in getUserSummaries. Instead of referring to getUserData and buildSummaryString directly, it refers to this.getUserData and this.buildSummaryString. Under the hood, pluggable creates this contexts that make pluggable dependencies available.

Now lets look at how this might be invoked:

import { getBaseContext } from "pluggable";
const cxt = getBaseContext();
getUserSummaries.call(cxt, ["divmain"]);

There's not much extra here beyond the original implementation, aside from providing a context for the function invocation.

Now let's look at how you might implement a caching plugin.

const cacheUserData = function (override, transform) {
  const cache = {};

  override("getUserData", function (username) {
    if (username in cache) {
      return cache[username];
    }
    return override.CONTINUE;
  });

  // NOTE: we're not actually transforming the output here, although we could.
  transform("getUserData", function (userData, args) {
    const [username] = args;
    cache[username] = userData;
    return userData;
  });
}

You'd invoke getUserSummaries like so:

import { getBaseContext } from "pluggable";
const cxt = getBaseContext({}, [ cacheUserData ]);
getUserSummaries.call(cxt, ["divmain"]);