Libraries

Node Style Libraries

• directory with an index.js in it.
• directory with a package.json file in it. The package.json file must have a main attribute pointing to a javascript file.
• npm style: directory with a package.json file, with lots of attributes, including name, version, dependencies, main, etc.

Most commonly, a node style library will contain a 'lib' folder in which the javascript source will be.

Node libraries are usually installed to a well known location (node_modules) - usually automatically by npm -- and the whole public api is accessed by requiring the module by name:

var MyLibAPI = require('MyLib');

Caplin Style Libraries

• directory with a library.manifest file in it.
• directory with a src directory in it.

Caplin Libraries must currently be installed to the appropriate location (sdk\libs\javascript or sdk\libs\javascript\thirdparty). The public API consists of classes (somewhat like a java jar), which are referenced through namespaces.

var MyClassInMyLib = new caplin.mylib.MyClassInMyLib();

BladeRunnerJS Style Libraries

We want to support both kinds of library - where the public api is provided or where it is a bag of classes that can be used.

var MyLibAPI = require('MyLib');
var MyClassInMyLib = require('MyLib/MyClass');

This is supported by node currently, but requires that the MyClass.js file is at the top level of the folder. This is ugly and causes a problem for organising test code and other kinds of assets.

The proposal is to add some optional BladeRunnerJS specific options to the package.json file, e.g srcRoot:

{
  "name": "MyLib",
  "version": "0.0.1",
  "description": "A library.",
  "main": "./lib/api.js",
  "srcRoot": "./src"
}

If there is a srcRoot, then when you require something inside a library, it will get rewritten. so just as require('MyLib') gives you the result of getting <libraries location>\MyLib\lib\api.js, so require('MyLib/MyClass') will give you the result of getting <libraries location>\MyLib\src\MyClass.js - the srcRoot has been added into the path.

Obviously node.js will not pick this up, so libraries that must work both with BladeRunnerJS and node will need to provide both a srcRoot and a main, and code that uses it will have to know which mechanism to use.

Bundling

All libraries live in directories in <libraries location>.

The bundler will detect attempts to require(moduleIdentifier).

moduleIdentifier may be relative (in which case it starts with . or ..) or may refer to a library, or may refer to a module inside a library.

the moduleIdentifier is resolved:

• if it is relative, the current path is prepended and then then whole identifier is normalised.
• if it refers to a library, the package.json is read, and the contents of the main attribute is normalised relative to the library location.
• if it refers to a module inside a library, the package.json is read. If there is a srcRoot, the srcRoot is inserted between the library identifier and the rest of the path. The result is normalised.

If the resolved module Identifier refers to a javascript file, then it will be bundled, as will any javascript files it requires, as will any resources in the directory structure between its current directory structure and the top of the libraries directory structure.

If the resolved module Identifier does not refer to a javascript file, then we will throw an error.

The bundler is not able to detect dynamic requires (i.e. where the thing required is a string variable from somewhere else), so these must be included through the alias mechanism, in conjunction with the configuration files (as happens in CT).

Working with current code

The module system will have a boolean configuration that will create globals in the browser.So if you require('caplin/grid/GridView'), it will automatically create a global caplin.grid.GridView.

While we support old style code, the bundler must work both with requires and with global references.

so it must detect both

require('./grid/GridView'); (from within caplin)

and any reference to

caplin.grid.GridView

As indicating a dependency on the code in /caplin/src/grid/GridView.js.