JSPM

Overview

This project provides the foundation for the Bali Cloud Environment™. It contains a framework of classes designed to run in both the cloud on NodeJS servers and in your browser. It defines the Bali Document Notation™ which allows the two to communicate similar to JSON based web services. For the latest documentation on this project click here.

WARNING

This project is still in its early stages and the classes and interfaces to the classes are likely to change. Nevertheless, the project in its current state should work well as a better JSON solution for capturing information and rendering it in a human and computer readable way. A compiler for the Bali Document Notation™ and the Bali Cloud Environment™ should be available sometime in 2019.

Contents

• Project Description
• Bali Components
• Bali Elements
• Bali Collections
• Getting Started
• Contributing

Project Description

This project contains a JavaScript/NodeJS based implementation of the Bali Component Framework™. The framework is like JSON on steroids. It supports a much richer set of primitive types (13 in all) and collection types (6 in all) than JSON supports. It also provides powerful high-level programming constructs that integrate directly with the Bali Cloud Environment™. Everything in this framework is a Bali component and inherits from the bali.Component class. Each component can be turned into a portable document format called the Bali Document Notation™. Similarly, a string containing Bali Document Notation™ can be parsed into its corresponding Bali components. This project provides all of the JavaScript/NodeJS modules that are required to work with Bali components and Bali Document Notation™ strings.

Example Document

To whet your appetite here is a short example Bali document showing some of the capabilities of the Bali Document Notation™:

[
    $transactionId: #LYZ6PJ9GBABSF18MQMBSJDV7KAPV4MS7
    $timestamp: <2017-12-30T17:38:35.726>($city: "Madrid", $country: "Spain")
    $consumer: [
        $accountId: #SFNYCS6WTNCAVQ43DDS9HQJQX2A1XAPZ
        $email: <jane.smith@gmail.com>
    ]
    $merchant: [
        $accountId: #GYR0D0N7D7RGLAMM50TA7YYP9TRCYFF0
        $name: "Cool Deals R Us"
    ]
    $items: [
        [
            $name: "Hover Board"
            $version: v2.65
            $quantity: 1
            $price: 142.00($USD)
        ]
        [
            $name: "Hover Battery Packs"
            $version: v15.3.7
            $quantity: 2
            $price: 16.00($USD)
        ]
    ]
    $tax: 10.77($EUR)
    $total: 184.77($EUR)
]

The document itself is fairly straight forward. It captures the information associated with a payment from a consumer to a merchant. The example is overly simple but should give you the gist of the power behind the Bali Component Framework™.

Bali Components

The bali.Component class provides the foundation for all other classes in the Bali Component Framework™. It defines canonical implementations for common methods that all classes should implement like:

• toString() - Returns a consistently formatted string containing the Bali Document Notation™ form of this component.
• isEqualTo(that) - Returns whether or not the canonical string format of this component is equal to the canonical string format of that component.
• comparedTo(that) - Returns a signum value showing how this component compares to that component using their natural ordering: -1 if this < that; 0 if this = that; and 1 if this > that.
• getHash() - Returns a unique canonical integer hash value for this component so that it can be used efficiently in a hash table.

Component Framework

The following UML class diagram shows a high-level view of the base component classes.

This framework implements several of the Gang of Four Design Patterns including the Composite, Iterator, and Visitor patterns.

The component classes are split into two types of components:

• bali.Element - Elemental components are atomic in nature and not generally broken down into smaller pieces.
• bali.Composite - Composite components are made up of smaller subcomponents.

Complex nested component structures can be constructed out of composite components. A bali.Visitor component is designed to visit each subcomponent in a complex component and perform tasks based on the type of visited component. For example, any component can be visited by a bali.ComponentFormatter visitor which generates the corresponding Bali Document Notation™ text string for the component.

Component Details

The following UML class diagram shows the details for the base component classes.

Notice that in addition to the canonical methods defined by the bali.Component class a component may be parameterized to further constrain its type and behavior. In the example transaction document above the numbers representing currency amounts where parameterized with the currency type ($USD or $EUR). Also the timestamp was parameterized with the location information ($city: "Madrid", $country: "Spain") that can be used to determine the timezone for the timestamp.

Bali Elements

Element Framework

The following UML class diagram shows a high-level view of the concrete element classes.

Each element class encapsulates a specific elemental type of data.

Bali Collections

The bali.Collection class provides the foundation for the collection classes in the Bali Component Framework™. Collections are groups of subcomponents referred to as items that are maintained and ordered following different rules depending on the specific collection type.

Collection Framework

The following UML class diagram shows a high-level view of both the abstract and concrete collection classes.

Each concrete collection class enforces different rules for managing its items:

• bali.Tree - A tree maintains a collection of children components that are maintained in the order in which they were added. Each node in the tree has a specified type which defines the semantics of each of its children nodes.
• bali.Stack - A stack is a collection of items that are added and removed sequentially and strictly enforces the "last in, first out" (aka LIFO) ordering.
• bali.Set - A set is an ordered collection that automatically orders its items in their natural order and does not allow duplicate items.
• bali.Range - A range is a collection that constrains an other collection to a specific subset of its items by specifying the first and last item to be included in the range.
• bali.List - A list is a collection that maintains its items in the order in which they were added, but also allows its items to be sorted if desired using a bali.Comparator component.
• bali.Catalog - A catalog is like a list collection whose items are bali.Association components each containing a key that is mapped to a value, both of which are also components. A catalog collection may also be sorted based on its keys if desired.

There are also several types of helper classes that work with collections to perform specific tasks:

• bali.Iterator - An iterator component moves over a collection allowing a program to look at the items in the collection one at a time in order, either moving forwards through the collection or backwards through the collection.
• bali.Sorter - A sorter component implements a specific sorting algorithm and can be used to sort any sortable collection like a bali.List or bali.Catalog. The default sorting algorithm is a merge sort.
• bali.Comparator - A comparator component can be used to compare two other components (usually items in a collection) for their ordering. The default comparator determines the "natural" ordering of the two components.

A sorter may be passed a specific comparator which it will then use to compare items while sorting them. Similarly, a collection can be passed a specific sorter when asking it to sort its items.

Collection Details

The following UML class diagram shows the details for the abstract collection classes.

Sequential Collection Details

And the next UML class diagram shows the details for the fixed collection classes.

Ordered Collection Details

The next UML class diagram shows the details for the ordered collection classes.

Sortable Collection Details

And the last UML class diagram shows the details for the sortable collection classes.

Getting Started

To install this NodeJS package and get started using it do the following:

npm install bali-component-framework
node
> var bali = require('bali-component-framework');
> Object.keys(bali)
[ 'types',
  'Component',
  'Visitor',
  'Element',
  'Composite',
  'Collection',
  'Comparator',
  'Iterator',
  'Sorter',
  'Angle',
  'Binary',
  'Complex',
  'Duration',
  'Identifier',
  'Moment',
  'Percent',
  'Probability',
  'Reference',
  'Symbol',
  'Tag',
  'Template',
  'Text',
  'Version',
  'Association',
  'Block',
  'Source',
  'Procedure',
  'Parameters',
  'List',
  'Catalog',
  'Set',
  'Range',
  'Stack',
  'Tree',
  'formatter',
  'parser',
  'codex' ]
> 

Contributing

Project contributers are always welcome. Create a fork of the project and add cool new things to the framework. When you are ready to contribute the changes create subsequent "pull request". Any questions and comments can be sent to craterdog@gmail.com.