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.
var getres = require('getres')
getres(
{
photo: {
src: 'https://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.
yarn add getresYou 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 => { })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 |
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).
All of these examples use ES6 syntax which may require transpilation to work across browsers.
In one giant ball of config this demonstrates most of the functionality of getres including:
- Loading different resource types:
text(default),jsonandimage. - Using a
parserfunction to transform the resource. - Hooking into individual resource loading with the
cbfunction. - Accessing the
resourcetree using promises instead of callbacks. - Hooking into progress events.
import getres from 'getres'
// TODO: LOADER!
getres.register()
getres({
text: {
src: 'https://example.com/my.txt'
},
parsedText: {
src: 'https://example.com/my.txt',
parser: (resource) => resource.toUpperCase(),
cb: (err, resource) => {
if (err) {
console.error(err)
return
}
console.log('resource', resource)
}
},
json: {
src: 'https://example.com/my.json',
type: 'json'
},
image: {
src: 'https://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)
})getres({
image: {
src: 'https://example.com/my.txt',
type: ''
},
cube: {
src: [
'https://example.com/pos-x.png',
'https://example.com/neg-x.png',
'https://example.com/pos-y.png',
'https://example.com/neg-y.png',
'https://example.com/pos-z.png',
'https://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)
})getres({
image: {
src: 'https://example.com/my.txt',
type: ''
},
cube: {
src: {
xp: 'https://example.com/pos-x.png',
xn: 'https://example.com/neg-x.png',
yp: 'https://example.com/pos-y.png',
yn: 'https://example.com/neg-y.png',
zp: 'https://example.com/pos-z.png',
zn: 'https://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)
})getres({
text: { src: 'https://example.com/text.txt' }
images: {
alpha: {
src: 'https://example.com/alpha.png',
type: 'image'
},
beta: {
src: 'https://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)
})getres({
sync: {
src: 'https://example.com/foo.txt',
parser: (resource) => resource.toUpperCase()
},
async: {
src: 'https://example.com/bar.txt',
parser: (resource, cb) => {
setTimeout(() => {
cb(resource.toUpperCase())
}, 1000)
}
},
(err, resource) => {}
}getres.register(
'twinsen',
(node, cb) => {
cb(null, 'Twinsen ' + node.src)
}
)
getres(
{
zoe: {
src: 'some-file',
type: 'twinsen'
}
}
).then(({ zoe }) => { /* */ })To test:
npm testContributions welcome!
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.