collar.js

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.

Get Started

1. Install collar.js
   • Install from npm

     
     npm install collar.js --save
                   

   • or download 'collar.min.js' directly
     Download collar.min.js (v1.0.0)
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:
      collar-dev-client.min.js
   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