collar.js

1.0.0

A better way to make your code comprehensible.

Get Started Get Docs
Notice: We have recently published our first major release version 1.0.0, please upgrade your collar.js, collar.js-dev-client, and collar-dev-server to version 1.+
What is collar.js

collar.js = an asynchronous library + visualization development tool

Building high quality software relies on a good understanding of the code. However, it is hard to understand the code when LoC increase.

In chinese, there is an old saying : 提 ti 纲 gang 挈 qie 领 ling, literally means to lift the clothes by its collar. Figuratively means to concentrate on the main points or to bring out the essentials.

This is how collar.js can help you to build high quality software : build your code's main data flows (as clothes' collar) with collar.js and visualize it to make it much easier to understand. collar.js is not just a visualization tool, it builds with several dev tools to help you understand your code easier in an interactive way.

Visualized development, directly translate your thought into code, record and playback your data flow, debug visually
Asynchronous programming, fluent and simple API (less than 20). Compatible with your exsting code.
Single responsibility principle. collar.js has 4 basic elements : sensor, filter, processor, and actuator.
Frontend and backend support. collar.js works in both browser and nodejs.
Get Started
  1. Install collar.js
  2. Require collar.js in your module, and create a namespace
    • for nodejs
      
      const collar = require("collar.js");
      const ns = collar.ns("your.module.namespace");
                    
    • for browser
      
      const ns = collar.ns("your.module.namespace");
                    
  3. Build your work flow with collar
    • A greeting example:
      
      ns.sensor("send name", function(){
          this.send({
            name : "John"
          });
        })
        .map("generate greeting words", signal => {
          let name = signal.get("name");
          return signal.new({
            greeting : `Hello! ${name}`
          });
        })
        .do("print greeting", signal => {
          console.log(signal.get("greeting"));
        })
                    
  4. Visualize your code by enabling the development tool.
    1. Install collar.js development tool (last version: 1.0.0)
      
      sudo npm install collar-dev-server -g
      sudo npm install collar.js-dev-client --save-dev
                    

      Or download browser version directly:
    2. Run collar.js development tool
      
      collar-dev-server
                    
    3. At the beginning of your module, enable collar development tool
      
      const DevToolAddon = require("collar.js-dev-client");
      collar.use(new DevToolAddon());
                    

      for browser app, you can simply include `collar-dev-client.min.js` in your web page
      
      <script src="js/collar.min.js"></script>
      <script src="js/collar-dev-client.min.js"></script>
      <script>
      // your flow goes here
      </script>
                    
    4. Run your module, and check collar development tool, your code is visualized as following:
Examples
Example: spaceship game

This example demonstrates how to create a 2D game with collar.js. It helps you understand how a 2D game works. The game is based on a general 2D game model made by collar.js, and built with javascript 2D game engine : Phaser.js. With collar.js, you can easily create a 2D game with different game engines.

Demo Tutorial
Example: Frontend login module

This example demonstrates a frontend login module with collar.js. You will learn how easy it is to translate your thoughts into collar.js data flow, and how you can demonstrate your code to others with collarjs' record & playback features.

Demo Tutorial
Example: Backend authentication module

This example demonstrates how to create a backend authentication module with collar.js. It is a follow-up example of the 'Frontend login module' example. You will learn how to wire up different modules together to build an application, and how to integrate collar.js module into your existing application.

Source Code Tutorial
Example: Code a carousel

This example demonstrates how to create a carousel web module with collar.js. You will learn how to wrap a module to a node like async API, and how to call it in a non-interruptible way.

Demo Source Code Tutorial
Example: File Name Shortener

A desktop application to help you shorten local file names. The cross platform UI and desktop support is powered by electron. Collar.js is used to build the business logic.

Source Code Download for Mac OS