Code Examples

Importing the Module

The following code shows a typical import for using the Bali Component Framework™.

const debug = 1;  // debug level: 0..3
const bali = require('bali-component-framework').api(debug);

The debug level can be set to one of the following values:

• 0 - no logging to console.log or console.error will occur
• 1 - exceptions will be logged to console.error
• 2 - additional validation of arguments passed into the API will occur
• 3 - detailed information will be logged to console.log

An Example Catalog Component

This code creates a catalog component from a JavaScript object.

const catalog = bali.catalog({
    $transaction: bali.tag(),  // generate a new unique tag
    $timestamp: bali.moment(),  // now
    $consumer: '"Derk Norton"',
    $merchant: '<https://www.starbucks.com/>',
    $amount: '4.95($currency: $USD)'
});
console.log('catalog: ' + catalog);

The resulting catalog is displayed using Bali Document Notation™, or BDN for short.

catalog: [
    $transaction: #PJG67WY8S78AZ8LG4CCWZ0119273AV3V
    $timestamp: <2020-02-01T16:11:01.601>
    $consumer: "Derk Norton"
    $merchant: <https://www.starbucks.com/>
    $amount: 4.95($currency: $USD)
]

Notice that a catalog consists of a list of attributes, each consisting of a key and an associated value. In this example, each key is a symbol which is denoted by the $ prefix. The keys however, may be any element type. Also, unlike many programming languages, there is no need to separate each attribute by a comma when each attribute is on a different line.

An Example List Component

This code creates a list component using the keys from the previous example.

const list = bali.list(catalog.getKeys());
console.log('list: ' + list);

The resulting list is also displayed in BDN.

list: [
    $transaction
    $timestamp
    $consumer
    $merchant
    $amount
]

Notice that the items in the list are in the same order as the keys in the catalog. Also notice that collections like catalogs and lists are always displayed within square brackets when formatted in Bali Document Notation™.

An Example Set Component

This code creates a set component using the items in the list from the previous example.

const set = bali.set(list);  // automatically ordered
console.log('set: ' + set);

The resulting set, also a type of collection.

set: [
    $amount
    $consumer
    $merchant
    $timestamp
    $transaction
]($type: /nebula/collections/Set/v1)

Notice that the items in the set are automatically ordered in their natural order. A set also does not allow any duplicate values. Since the BDN for a set looks the same as that for the list it is parameterized with the collection type in the parenthesis following the set itself. The value of the $type attribute in the parameterization /nebula/collections/Set/v1 is a name element. Each name references a component stored in the Bali Nebula™. In this case the referenced component defines the first version of the collection type Set.

Sorting Items in a List

The next code example shows how we can manually sort the items that are in our original list.

list.sortItems();
console.log('sorted list: ' + list);

The resulting list shows the items sorted in their natural order.

sorted list: [
    $amount
    $consumer
    $merchant
    $timestamp
    $transaction
]

Note that a custom comparison algorithm may be passed into the sortItems(algorithm) method to achieve a different desired ordering.

Sorting Associations in a Catalog

Similarly, the next example shows how we can manually sort the associations that are in our original catalog.

catalog.sortItems();
console.log('sorted catalog: ' + catalog);

Again, a custom comparison algorithm may be passed into the sort method for a catalog.

sorted catalog: [
    $amount: 4.95($currency: $USD)
    $consumer: "Derk Norton"
    $merchant: <https://www.starbucks.com/>
    $timestamp: <2020-02-01T16:11:01.601>
    $transaction: #PJG67WY8S78AZ8LG4CCWZ0119273AV3V
]

Comparing Two Components

We can compare any two components for equality. Two components are considered equal if their Bali Document Notation™ representations are identical. For example, we can compare the list of keys from our sorted catalog with our sorted list of keys that we created earlier.

const keys = catalog.getKeys();
const areEqual = bali.areEqual(keys, list);
console.log('are equal: ' + areEqual);

They should be equal.

are equal: true

And they are.