Introduction

All small and medium sized companies suffer the same problem: code is a mess and disorganized, there are multiple different naming conventions, folder and file conventions, and implementation conventions. Actions are classified in different ways and placed into different files and modules, which makes sense to some and is difficult to understand for others. There is not much consistency in the implementation of the look and feel, and CSS is all over the place in different implementations. Overall, there is no clear and systematic approach to the frontend that cleans up the conventions and implementation styles and at the same times keeps it simple.

This project is a solution to this problem. It is very few lines of code and is freely and openly licensed so it can be used at any company. All it does is create a convention to place all of your actions in one place, and actions manage state. As you will learn this solves the problem of managing vendor lockin, of testability of the code, of centralizing the knowledge base and of knowing where to find things. It is not an over-abstraction, it just treats everything as they are: as actions. All actions start at one state and end at another. If there are two main things in programming they are objects and actions. This project manages them both without any dependencies, so it is as secure as it can be.

Companies looking to take control of their code should start here. Gain control over the actions in the application. Shed the excess files that kept the actions siloed. Write tests for each action to verify its behavior. This will help improve the codebase. In addition, save the objects of your actions here. Keep configuration and settings and arbitrary data in one place to ease debuggability. To make it simple to stub out a complicated action. To help ease newcomers into the code, so they don't have to weed through a complicated network of imports and files. This will make the code easier to understand for everyone, and will increase the velocity at which product is developed.

Installation

npm install @7rabbit/ink

Illustration

Ink is a glorified "store". All a store is is "state", they both mean the same thing. We have taken one step further to take that "state" of one type of "thing" and created two types of things to simplify development: actions and objects. An action in JavaScript is simply a function. A function takes input and optionally returns output or otherwise causes an effect (or does nothing). An object is a piece of data, whether itself a function, or better, an object, set of bits, or an array, string, number, regex, etc.

This is a Hello World example.

import Ink from '@7rabbit/ink'

let ink = new Ink()
ink.attachModule(attachLogger)
ink.invokeAction('log', 'hello world')
ink.detachModule(attachLogger)
ink.invokeAction('log', 'hello world')

function attachLogger(ink) {
  ink.attachAction('log', log)

  return detachModule

  function detachModule() {
    ink.detachAction('log')
  }

  function log(x) {
    console.log(x)
  }
}

The rest of what follows is an API reference documenting every method on the ink object.

commitObject(name, object)

Stores an object by the key name.

attachObject(name, object)

If there already is an object stored by key name, then it throws an error, otherwise it stores object by the key name.

selectObject(name)

Returns the object with the key name.

expectObject(name)

If there is not an object stored by key name, then it throws an error, otherwise it returns the object with the key name.

detachObject(name)

Removes the object under the key name from the store.

commitAction(name, action)

Stores an action by the key name.

attachAction(name, action)

If there already is an action stored by key name, then it throws an error, otherwise it stores action by the key name.

selectAction(name)

Returns the action with the key name.

expectAction(name)

If there is not an action stored by key name, then it throws an error, otherwise it returns the action with the key name.

detachAction(name)

Removes the action under the key name from the store.

invokeAction(name, ...args)

Calls the action under the key name with args.

attachModule(module)

Applies the function module to the store.

detachModule(module)

Unapplies the function module to the store.