README

Object System

This library provides a way for you to organize and standardize individual components. It can serve as the 'glue' or 'broker' between a bunch of disparate objects within a system. This library was extracted from the following use case:

Create a system for a collection of individual, framework-independent UI components.

An extreme (not advisable) example of this would be:

We have a library with multiple UI components written in jQuery, Angular, and React. How can we get them all to work together by communicating with each other?

Using this library we could accomplish this by:

Wrapping each component in a constructor function
Making sure the object that it creates contains a publicly accessible 'receive' property of action functions.

Then, we can make calls like this:

message('SomeComponentName', 'someAction', { something: true, somethingElse: 0 });

In non-single page web applications, the client-side life-cycle begins over and over again and usually does not handle as much global/application-level state as a single page application would. Therefore, our front-end object/global state manager can be simplified. In this scenario, this library may be all you need because it allows you to:

Independently develop and encapsulate UI components
Allow the independent components to talk to each together
Forget about order of operations around declaration of components

Installation

This library could be consumed as either a pure TypeScript library or as its trans-compiled ES2015 JavaScript counterpart.

To install through NPM:

npm install --save @bluemarblepayroll/object-system

To install through Yarn:

yarn add @bluemarblepayroll/object-system

Examples

React Example: Todo Application

This example is provided as a standalone webpage located at: test/examples/todo_app.html

Consider the following example of a Todo UI component written in React:

class TodoList extends React.Component {

  static defaultProps = {
    items: [],
    title: 'Todo'
  };

  constructor(props) {
    super(props);

    this.state = {
      items: Immutable.fromJS(props.items),
      title: props.title
    };

    this.receive = {
      add: (msgId, args) => {
        let newNote = Immutable.fromJS({
          notes: args.notes
        });

        this.setState({
          items: this.state.items.push(newNote)
        });
      }
    }
  }

  render() {
    return(
      <div>
        <h2>{this.state.title}</h2>
        <table>
          <tbody>
            {this.renderRows()}
          </tbody>
        </table>
      </div>
    );
  }

  renderRows() {
    return this.state.items.map( (item, index) =>
      <tr key={index}>
        <td>{item.get('notes')}</td>
        <td><button onClick={this.deleteItem.bind(this, index)}>Delete</button></td>
      </tr>
    );
  }

  deleteItem(index) {
    console.log(`[TodoList] Deleting item at index: ${index}`);

    this.setState({
      items: this.state.items.delete(index)
    });
  }
}

The component above knows how to render the HTML of the list itself. In order for items to be added, it will listen, or "receive" messages as implemented in the constructor. The key here is all instance of the object needs is to respond to 'receive' and implement whatever actions as keys ('add' in our example.)

You can also choose to implement a method called receiveMessage(msgId, action, args), instead of having the object contain a property called 'receive.' In this case, the method could look like this:

receiveMessage(msgId, action, args) {
  if (action === 'add') {
    let newNote = Immutable.fromJS({
      notes: args.notes
    });

    this.setState({
      items: this.state.items.push(newNote)
    });
  } else {
    throw `Cant handle action: ${action}`;
  }
}

Complimenting this list component would be a basic form component:

import { message } from '@bluemarblepayroll/object-system';

class TodoForm extends React.Component {

  static defaultProps = {
    formName: ''
  };

  render() {
    return(
      <div>
        <input ref="notes" />
        <button onClick={this.addItem.bind(this)}>Add</button>
      </div>
    );
  }

  clearField() {
    this.refs.notes.value = '';
  }

  addItem() {
    message(this.props.formName, 'add', { notes: this.refs.notes.value });
    this.clearField();
  }
}

This form is as basic as it gets: a textbox and a button. When the button is clicked, it will send a message to another form (identified the formName property) to add another item.

Tying this together would be the HTML:

<div id="TodoList1"></div>
<div id="TodoForm1"></div>

And the JavaScript that registers the React components and calls to make them:

import { make, register } from '@bluemarblepayroll/object-system';

function reactConstructor(reactClass) {
  return (name, opts, domElement) => ReactDOM.render(React.createElement(reactClass, opts), domElement);
}

register('TodoList', reactConstructor(TodoList));
register('TodoForm', reactConstructor(TodoForm));

let listOptions = {
  title: 'Things I Need To Get Done',
  items: [
    { notes: 'Example 1' },
    { notes: 'Example 2' }
  ]
};

let formOptions = {
  formName: 'TodoList1'
};

make('TodoList', 'TodoList1', listOptions, document.getElementById('TodoList1'));
make('TodoForm', 'TodoForm1', formOptions, document.getElementById('TodoForm1'));

Voilà! You have installed a basic component manager on top of a basic component architecture!

Contributing

Development Environment Configuration

Basic steps to take to get this repository compiling:

Install Node.js (check package.json for versions supported.)
Install Yarn package manager (npm install -g yarn)
Clone the repository (git clone git@github.com:bluemarblepayroll/object-system.git)
Navigate to the root folder (cd object-system)
Install dependencies (yarn)

Compiling

To compile the TypeScript source down to JavaScript, run:

yarn run build

Running Tests

To execute the test suite run:

yarn run test

Linting

yarn run lint

Publishing

Note: ensure you have proper authorization before trying to publish new versions.

After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:

Merge Pull Request into master
Update package.json version number
Update CHANGELOG.md
Push master to remote and ensure CI builds master successfully
Build the project locally: yarn run build
Perform a dry run: npm publish --access public --dry-run. Inspect packaging, ensure all files (including dist) are included.
Publish package to NPM: npm publish --access public
Tag master with new version: git tag <version>
Push tags remotely: git push origin --tags

License

This project is MIT Licensed.

Usage no npm install needed!