lasso/docs/javascript-api.md

Lasso.js is a build tool and runtime library for building and bundling all of the resources needed by a web application

JavaScript API
==============

## require('lasso')

### Methods

#### configure(config)

Configures the default lasso instance using the provided `config`. The `config` can either be an object or a path to a JSON file.

#### create(config)

Creates a new configured [Lasso](#Lasso-type) instance.

#### getDefaultLasso()

Returns the default [Lasso](#Lasso-type) instance.

#### lassoPage(options, callback)

Equivalent to `require('lasso').getDefaultLasso().lassoPage(options, callback)`. See [Lasso » lassoPage](#Lasso-lassoPage) below.

#### lassoResource(pageConfig, callback)

Equivalent to `require('lasso').getDefaultLasso().lassoResource(options, callback)`. See [Lasso » lassoResource](#Lasso-lassoResource) below.

## require('lasso/middleware')

### serveStatic(options)

Express middleware to serve up static files generated by Lasso.js.

Example usage:

```javascript
app.use(require('lasso/middleware').serveStatic());
```

- Supported options:
    - __lasso__ - The configured lasso instance (defaults to `require('lasso').getDefaultLasso()`)
    - __sendOptions__ - Options passed to the [send](https://github.com/pillarjs/send) module that is used to serve up static assets

<a name="Config-type"></a>

## Config

See [./lib/Config.js](./lib/Config.js)

<a name="Lasso-type"></a>

## Lasso

### Methods

<a name="Lasso-lassoPage"></a>

#### lassoPage(options, callback)

Processes all of the dependencies for a page to produce a set of static JS and CSS bundles, as well as any other static assets.

The result will be a [LassoPageResult](#LassoPageResult-type) instance that provides the list of generated URLs for all of the static bundles, as well as a list of the generated files.

Supported options:

- __dependencies__ - An array of dependencies
- __from__ - The base directory for calculating relative paths (optional)
- __packagePath__ - A path to a `browser.json` file
- __packagePaths__ - An array of paths to `browser.json` files

<a name="Lasso-lassoResource"></a>

#### lassoResource(path|buffer[, options]) : Promise

Sends any type of resource through the Lasso.js asset pipeline and returns a `Promise` that eventually resolves to a result object with the URL. If Lasso is configured to use the default file writer then the resource referenced by the path will be copied to the static output directory. The callback will be invoked when the resource is fully written and the URL to the output resource will be part of the object that the returned promise eventually resolves to. In addition, if Lasso is configured with fingerprints enabled then a fingerprint will be added to the output resource URL.

Example usage passing an asset path:

```javascript
const myLasso = require('lasso').getDefaultLasso();

myLasso.lassoResource('path/to/foo.png')
    .then(function(result) {
        var url = result.url; // URL for the output resource
    });
```

Example usage passing a buffer:

```javascript
const fs = require('fs');
const myLasso = require('lasso').getDefaultLasso();

const imgPath = nodePath.join(__dirname, 'ebay.png');

;(async function() {
  const buffer = await fs.promises.readFile(imgPath);

  const result = await lasso.lassoResource(buffer, {
      name: 'test',
      extension: 'png'
  });

   // URL for the output resource (e.g. /static/test-02827b0c.png)
  const { url } = await myLasso.lassoResource(buffer)
})();
```

Supported options:

- __cache__ (boolean) - Whether or not the result should be cached (the resource path will be used as the cache key). The default value is `true`.
- __name__ (string) - Name to prefix the buffer path
- __extension__ (string) - File extension to append to the end of a buffer path

#### lassoResource(path[, options], callback)

This method is similar to the other version that returns a `Promise` (`lassoResource(path[, options]) : Promise`), but if a `callback` function is provided as the last argument then the usage will be as follows:

```javascript
var myLasso = require('lasso').getDefaultLasso();
myLasso.lassoResource('path/to/foo.png', function(err, result) {
    if (err) {
        // Handle the error
    } else {
        var url = result.url; // URL for the output resource
    }
});
```

### Properties

#### config

The loaded [Config](#Config-type) config instance

<a name="LassoPageResult-type"></a>

## LassoPageResult

### Methods

#### getBodyHtml()

Short-hand for `lassoPageResult.getHtmlForSlot('body')`.

#### getCSSFiles()

Returns an array of all of file paths for all of the generated JavaScript bundles

#### getCSSUrls()

Returns an array of all of URLs for all of the generated CSS bundles

#### getHeadHtml()

Short-hand for `lassoPageResult.getHtmlForSlot('head')`.

#### getHtmlBySlot()

Returns the HTML markup for each slot. The returned object will be an object. For each property of the returned object, the name will be the slot name (e.g. `head`) and the value will be the HTML markup (e.g. `<link rel="stylesheet" type="text/css" href="static/style.less.css">`).

#### getHtmlForSlot(slotName)

Example usage:

```javascript
var headHtml = lassoPageResult.getHtmlForSlot('head');
var bodyHtml = lassoPageResult.getHtmlForSlot('body');
```

#### getJavaScriptFiles()

Returns an array of all of file paths for all of the generated JavaScript bundles

#### getJavaScriptUrls()

Returns an array of all of URLs for all of the generated JavaScript bundles

#### getOutputFiles()

Returns an array of all of file paths for all of the generated files