README.md

getres

Universal resource loading (browser and Node.js) designed to work with HTML5 Canvas and WebGL. Supports loading text, JSON, binary and images (using custom loaders). The API interface for getres is heavily inspired by that of resl, differing mainly in the ability to run in Node.js as well as the browser.

getres is lightweight and compatible with IE9+ and all other modern browsers with support for promises optional.

Simple example

var getres = require('getres')

getres(
  {
    photo: {
      src: 'http://example.com/photo.jpg',
      type: 'image',
    }
  },
  function (err, resources) {
    if (err) {
      console.error(err)
      return
    }
    console.log('photo', resources.photo)
  }
)

This example uses ES5 and traditional callbacks. See further down the README for more examples which include: loading multiple resources; loading arrays; objects and nested resources; using the parser function; use of promises; and hooking into progress events.

Getting started

yarn add getres

API

You can use getres with or without promises. First without:

import getres from 'getres'

getres(
  config,
  (err, res) => { },
  (progress) => { } /* Optional */
)

Now with promises:

getres(config)
  .then(res => { })
  .catch(err => { })

/* Or with progress listener */
getres(config, null, function (progress) { })
  .then(res => { })
  .catch(err => { })

Config

An object where the keys correspond to the name of each resource and the value is itself an object with the following properties or key(s) for nested resources:

Name	Description	Default
src	Resource URL(s) to load. Can be a string, array or object
type	text, json or image	text
parser	A function used to transform the resource (optional). The function can directly return the transformed resource or pass the transformed resource to a callback e.g. for async.
cb	A function to hook into an individual resource's load events (optional)
credentials	For CORS	false

Using promises

To use promises you must ensure the environment supports these already. For some older browsers you may need to use a suitable polyfill. Alternatively you can also set your own promise library with getres.Promise = require('bluebird') (swap Bluebird for your library of choice).

Examples

All of these examples use ES6 syntax which may require transpilation to work across browsers.

Kitchen sink example

In one giant ball of config this demonstrates most of the functionality of getres including:

• Loading different resource types: text (default), json and image.
• Using a parser function to transform the resource.
• Hooking into individual resource loading with the cb function.
• Accessing the resource tree using promises instead of callbacks.
• Hooking into progress events.

import getres from 'getres'

// TODO: LOADER!
getres.register()

getres({
  text: {
    src: 'http://example.com/my.txt'
  },
  parsedText: {
    src: 'http://example.com/my.txt',
    parser: (resource) => resource.toUpperCase(),
    cb: (err, resource) => {
      if (err) {
        console.error(err)
        return
      }
      console.log('resource', resource)
    }
  },
  json: {
    src: 'http://example.com/my.json',
    type: 'json'
  },
  image: {
    src: 'http://example.com/my.jpg',
    type: 'image'
  },
  null, // Indicates you want to use promises
  (progressEvent)
    => { /* Do something with progress event */ }
}).then(({ text, parsedText, json, image }) => {
  /* Do something with resources */
}).catch((err) => {
  console.error(err)
})

Source array example

getres({
  image: {
    src: 'http://example.com/my.txt',
    type: ''
  },
  cube: {
    src: [
      'http://example.com/pos-x.png',
      'http://example.com/neg-x.png',
      'http://example.com/pos-y.png',
      'http://example.com/neg-y.png',
      'http://example.com/pos-z.png',
      'http://example.com/neg-z.png'
    ],
    type: 'image'
  }
}).then(({ image, cube }) => {
  console.log('image', image)
  console.log(
    'cube x, -x, y, -y, z, -z:',
    cube[0], cube[1], cube[2], cube[3], cube[4], cubemap[5]
  )
}).catch((err) => {
  console.error(err)
})

Source object example

getres({
  image: {
    src: 'http://example.com/my.txt',
    type: ''
  },
  cube: {
    src: {
      xp: 'http://example.com/pos-x.png',
      xn: 'http://example.com/neg-x.png',
      yp: 'http://example.com/pos-y.png',
      yn: 'http://example.com/neg-y.png',
      zp: 'http://example.com/pos-z.png',
      zn: 'http://example.com/neg-z.png'
    },
    type: 'image'
  }
}).then(({ image, cube }) => {
  console.log('image', image)
  console.log(
    'cube x, -x, y, -y, z, -z:',
    cube.xp, cube.xn, cube.yp, cube.yn, cube.yp, cube.yn
  )
}).catch((err) => {
  console.error(err)
})

Nested example

getres({
  text: { src: 'http://example.com/text.txt' }
  images: {
    alpha: {
      src: 'http://example.com/alpha.png',
      type: 'image'
    },
    beta: {
      src: 'http://example.com/beta.png',
      type: 'image'
    }
  }
}).then(({ text, images }) => {
  console.log('text', text)
  console.log('images', images.alpha, images.beta)
}).catch((err) => {
  console.error(err)
})

Sync and async parser

getres({
  sync: {
    src: 'http://example.com/foo.txt',
    parser: (resource) => resource.toUpperCase()
  },
  async: {
    src: 'http://example.com/bar.txt',
    parser: (resource, cb) => {
      setTimeout(() => {
        cb(resource.toUpperCase())
      }, 1000)
    }
  },
  (err, resource) => {}
}

Register custom loader

getres.register(
  'twinsen',
  (node, cb) => {
    cb(null, 'Twinsen ' + node.src)
  }
)

getres(
  {
    zoe: {
      src: 'some-file',
      type: 'twinsen'
    }
  }
).then(({ zoe }) => { /* */ })

Development

To test:

npm test

Contributions welcome!

Credits

getres was created after trying and failing to get resl working across Node.js and the browser, with a view to using it headlessly with the excellent regl WebGL library and headless-gl. So, the API resemblance between both libraries is strong. Thanks to mikolalysenko and contributors for all of the above.

getres uses superagent behind the scenes to make HTTP requests.