README
async-preloader
Assets preloader using ES2017 async/await and fetch.
Install
npm install --save async-preloader
Documentation
Quick start
This section covers the basic usage of AsyncPreloader
. For more informations about async/await, see Async functions - making promises friendly. Usage in Node.js environment is limited to its capacity to handle fetch
requests. Polyfills like node-fetch
and xmldom
might come handy.
Preload items and retrieve them
import AsyncPreloader from "async-preloader";
const items = [
{ id: "myDefaultFile", src: "assets/default" },
{ id: "myTextFile", src: "assets/text.txt" },
{ id: "myJsonFile", src: "assets/json.json" },
{ id: "myImageFile", src: "assets/image.jpg" },
{ id: "myVideoFile", src: "assets/video.mp4" },
{ id: "myAudioFile", src: "assets/audio.mp3" },
{ id: "myXmlFile", src: "assets/xml.xml" },
{ id: "mySvgFile", src: "assets/xml.svg" },
{ id: "myHtmlFile", src: "assets/xml.html" },
{ id: "myDefaultXmlFile", src: "assets/xml", loader: "Xml" },
{ id: "myFont", src: `assets/font.ttf` },
{ id: "Space Regular", loader: "Font", fontOptions: { timeout: 10000 } },
// Can be retrieved with the src property eg. AsyncPreloader.items.get("assets/fileWithoutId")
{ src: "assets/fileWithoutId" },
];
// Pass an array of LoadItem
//
// Returns a Promise with an array of LoadedValue
const pItems = AsyncPreloader.loadItems(items);
pItems
.then((items) => {
const element = AsyncPreloader.items.get("myVideoFile");
document.body.appendChild(element);
})
.catch((error) => console.error("Error loading items", error));
Note: Font loader is will try to detect the font in the page using FontFaceObserver when no src is specified.
Load items from a manifest file
It works in a similar fashion as createjs's PreloadJS.
import AsyncPreloader from "async-preloader";
// Pass the file url and an optional path of the property to get in the JSON file.
// It will load the file using the Json loader and look for the path key expecting an array of `LoadItem`s.
// Default path is "items" eg the default manifest would look like this:
// `{ "items": [ { "src": "assets/file1" }, { "src": "assets/file2" }] }`
//
// Returns a Promise with an array of LoadedValue
const pItems = AsyncPreloader.loadManifest(
"assets/manifest.json",
"data.preloader.items"
);
pItems
.then((items) => useLoadedItemsFromManifest(items)) // or AsyncPreloader.items.get("src or id")
.catch((error) => console.error("Error loading items", error));
Advanced usage
This section takes a closer look at the options of AsyncPreloader
.
loaders directly
Load a single item by using theimport AsyncPreloader from "async-preloader";
// Pass a LoadItem
//
// Returns a Promise with the LoadedValue
const pItem = AsyncPreloader.loadJson({ src: "assets/json.json" });
pItem
.then((item) => useLoadedItem(item))
.catch((error) => console.error("Error loading item", error));
Note: Using the loaders directly won't add the item to the items
Map.
Alternatively you could use AsyncPreloader.loadItem
and rely on the file extension or add { loader: "Json"}
to the item.
ArrayBuffer
instead of the default Blob
Get an You can specify how the response is handle by using the body
key in a LoadItem
.
Typical use case: get an ArrayBuffer for the WebAudio API to decode the data with baseAudioContext.decodeAudioData()
.
import AsyncPreloader from "async-preloader";
const audioContext = new AudioContext();
const pItem = AsyncPreloader.loadAudio({
src: "assets/audio.mp3",
body: "arrayBuffer",
});
pItem
.then((item) => audioContext.decodeAudioData(item))
.then((decodedData) => useDecodedData(decodedData))
.catch((error) => console.error("Error decoding audio", error));
Getting the progress
Since fetch
doesn't support Progress events
yet, you might want to get a per file progress.
import AsyncPreloader from "async-preloader";
const items = [
{ id: "myDefaultFile", src: "assets/default" }, // ...
];
let loadedCount = 0;
async function preload() {
await Promise.all(
items.map(async (item) => {
const data = await AsyncPreloader.loadItem(item);
loadedCount++;
console.log(`Progress: ${(100 * loadedCount) / items.length}%`);
})
);
}
await preload();
Abort one or more loadItem(s) request(s)
To abort a loadItem(s) call, you can create an AbortController
instance and pass its signal to options.
const controller = new AbortController();
const timeoutId = setTimeout(() => {
controller.abort();
}, 150);
try {
await AsyncPreloader.loadItems(
items.map((item) => ({
...item,
options: { ...(item.options || {}), signal: controller.signal },
}))
);
} catch (error) {
if (error.name === "AbortError") console.log("Request was aborted");
} finally {
clearTimeout(timeoutId);
}
Note: the example above uses the async functions (which is the core of this module). You'll need to transpile it if you are targeting older browsers (namely IE11). See support here.
License
MIT © Damien Seguin