@clocklimited/darkroom-url-builder

Darkroom URL builder

A module that builds URLs for your darkroom resources.

Installing

npm install @clocklimited/darkroom-url-builder
yarn add @clocklimited/darkroom-url-builder

var createDarkroomUrlBuilder = require('@clocklimited/darkroom-url-builder')

API

var builder = createDarkroomUrlBuilder(darkroomHost{s}, salt)

Returns a function that creates URL builder instances. darkroomHost{s} and salt are required, as these are both used in the composition of the URLs.

If multiple darkroom hosts are provided (as an array), a round-robin approach to url generation will be used. See round-robin-hosts for more info.

var b = builder()

Create a new URL builder instance. Every time you want to build a new URL, you start with this function.

b.resource(String:uri)

Set the resource you want a URL for. This is the URI that darkroom gave you when you posted or cropped your asset.

Returns b for chaining.

b.width(Number:n) (optional)

Set the width of the asset you want to receive.

Returns b for chaining.

b.height(Number:n) (optional)

Set the height of the asset you want to receive.

Returns b for chaining.

b.quality(Number:n) (optional)

Set the quality of the asset you want to receive.

Returns b for chaining.

b.gravity(String:n) (optional)

Set the direction that the image gravitates to. Should be one of: NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast

Returns b for chaining.

b.filename(String:name) (optional)

Set the filename of the asset you want to receive. This is for vanity of the URL and has no bearing on the response format or content-type headers.

Returns b for chaining.

b.url()

Builds a URL pointing to the resource described by the combination of width, height filename settings. If width and height are not set, the URL will point to the original resource, otherwise it will be constrained in one or both dimensions.

Note that darkroom will not distort the resource beyond its original aspect ratio. If you set width and height to something other than the original aspect ratio, you have no control of what part of the image is cropped. You should use the darkroom cropping API to create a new resource and create a URL for that instead.

Darkroom will only constrain images to the dimensions, it will not upscale. e.g.: if the original resource is 400px wide, asking for an 800px will return an image no bigger than 400px.

b.info()

Builds a URL that points to a JSON endpoint describing the resource's dimensions.

Example usage:

var createDarkroomUrlBuilder = require('darkroom-url-builder')
  , builder = createDarkroomUrlBuilder('http://darkroom.io', 'salty')

var thumb = builder()
  .resource('00000000000000000000000000000000')
  .width(100)
  .filename('test.jpeg')
  .url()

console.log(thumb)
//-> http://darkroom.io/100/00000000000000000000000000000000:2f314341b9d1d41f1b54b07be8d0cd1a/test.jpeg

var original = builder()
  .resource('00000000000000000000000000000000')
  .filename('test.jpeg')
  .url()

console.log(original)
//-> http://darkroom.io/original/00000000000000000000000000000000:9f847ee652ef4eed45a39625ef30193f/test.jpeg

var info = builder()
  .resource('0b8bafa96885483bc2778976a514334e')
  .info()

console.log(info)
//-> http://darkroom.io/info/0b8bafa96885483bc2778976a514334e:bc2afc01898e3b8e2613793be6cd7598

Round robin hosts

If you are looking to improve your page speed but have quite a few darkroom assets slowing you down, you may have seen advice such as the following from the various page speed tools:

Parallelize downloads across hostnames

This page makes xx parallelisable requests to darkroom.domain.com. Increase download parallelization by distributing these requests across multiple hostnames

In order to achieve this with darkroom url builder, you can simply pass in a list of darkroom hosts for it to use. For each url generated it will use the subsequent item in the list as the hostname, looping back to the first item when the list is exhausted. For example:

var urls = [ 'http://darkroom1.io', 'http://darkroom2.io', 'http://darkroom3.io' ]
  , builder = createDarkroomUrlBuilder(urls, 'test salt')

builder()
  .resource('uid')
  .height(100)
  .width(100)
  .filename('jim.jpeg')
  .url() //-> http://darkroom1.io…

builder()
  .resource('uid')
  .height(100)
  .width(100)
  .filename('jim.jpeg')
  .url() //-> http://darkroom2.io…

builder()
  .resource('uid')
  .height(100)
  .width(100)
  .filename('jim.jpeg')
  .url() //-> http://darkroom3.io…

builder()
  .resource('uid')
  .height(100)
  .width(100)
  .filename('jim.jpeg')
  .url() //-> http://darkroom1.io…

Obviously the DNS work to get all of the hosts pointing the same darkroom instance is up to the user.

CLI API

darkroom-url-builder also comes with a tiny command line application to save you from having to spin up a node REPL to get the URL of an image.

Usage: darkroom-url-builder darkroomUrl salt uri

$ darkroom-url-builder http://0.0.0.0:17999 salt f113b531524b64968a21be183307c7b7
http://0.0.0.0:17999/original/f113b531524b64968a21be183307c7b7:70615591bd5472c9a9ffff9396b7ba20

Tests

Run the tests with npm test. Generate a coverage report with npm test --coverage.