31:T4c4,md`# Preload a list of images preload is an asynchrounous function that downloads and caches a list of images into an index (a Map object). It's useful in interactive animations to have a change in image source reflected instantaneously. ~~~javascript import {preload} from '@severo/preload-a-list-of-images' images = await preload(urls, options) ~~~ Parameters: - urls (*required*): an array of images URLs - options: an object - ignoreExceptions: boolean, defaults to false. If true, catch the exceptions and return undefined instead of HTMLImageElement objects. - throttle: boolean, default to false. If true, rate-limits the image requests using [throttled-queue](see https://www.npmjs.com/package/throttled-queue) - throttleNumber: number, defaults to 1. Maximum number of requests per period of time. - throttlePeriod: number, defaults to 1000. Period of time in ms. - throttleEquallySpaced: boolean, defaults to false. If true, equally spaces the requests to avoid requests bursts. Returns: - a Map which keys are the urls and values are HTMLImageElement objects ## Example `32:[] 2f:{"title":"Preload a list of images","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":51,"value":"images.get(idx)","pinned":false,"hidden":false,"mode":"ojs"},{"id":23,"value":"viewof idx = selectFlat({\n options: urls,\n value: urls[0],\n output: true,\n description: \"your choice\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":46,"value":"images = await preload(urls)","pinned":true,"hidden":false,"mode":"ojs"},{"id":98,"value":"md`## Example: caught exceptions`","pinned":false,"hidden":false,"mode":"ojs"},{"id":107,"value":"faultyImgs.get(faultyIdx) || html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":109,"value":"viewof faultyIdx = selectFlat({\n options: faultyUrls,\n value: faultyUrls[0],\n output: true,\n description: \"your choice\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":115,"value":"faultyImgs = await preload(faultyUrls, { ignoreExceptions: true })","pinned":true,"hidden":false,"mode":"ojs"},{"id":101,"value":"faultyUrls = {\n const shuffle = str =>\n str\n .split('')\n .sort(function() {\n return 0.5 - Math.random();\n })\n .join('');\n return urls.map(url => (Math.random() > 0.2 ? url : shuffle(url)));\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":162,"value":"md`## Example: duplicates\n\nNote that the index Map (duplicateImages) only contains 2 entries.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":167,"value":"duplicateImages.get(duplicateIdx)","pinned":false,"hidden":false,"mode":"ojs"},{"id":169,"value":"viewof duplicateIdx = selectFlat({\n options: duplicateUrls,\n value: duplicateUrls[0],\n output: true,\n description: \"your choice\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":164,"value":"duplicateImages = await preload(duplicateUrls)","pinned":false,"hidden":false,"mode":"ojs"},{"id":175,"value":"duplicateUrls = urls.map((_, i) => (i % 2 ? urls[0] : urls[1]))","pinned":false,"hidden":false,"mode":"ojs"},{"id":213,"value":"md`## Example: throttle\n\nImage requests are limited to 2 requests every 500ms, equally spaced in time.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":216,"value":"throttleImgs.get(throttleIdx)","pinned":false,"hidden":false,"mode":"ojs"},{"id":218,"value":"viewof throttleIdx = selectFlat({\n options: urls,\n value: urls[0],\n output: true,\n description: \"your choice\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":224,"value":"throttleImgs = await preload(urls, {\n throttle: true,\n throttleNumber: 2,\n throttlePeriod: 500,\n throttleEquallySpaced: true\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":18,"value":"md`---\n\n## Credits\n\nDeveloped for the [LIRIS M2i project](https://projet.liris.cnrs.fr/mi2/) by Sylvain Lesage.\n\nselectFlat input control by Philippe Rivière.\n\nEmojis by GitHub.\n\n2022-01-14: Fixed throttle-queue import. Thanks [Alexandre Damiron](https://observablehq.com/@alexandredamiron)\n\n---\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":14,"value":"// Preload all images\npreload = async (\n urls,\n {\n ignoreExceptions = false,\n throttle = false,\n throttleNumber = 1,\n throttlePeriod = 1000,\n throttleEquallySpaced = false\n } = {\n ignoreExceptions: false,\n throttle: false,\n throttleNumber: 1,\n throttlePeriod: 1000,\n throttleEquallySpaced: false\n }\n) => {\n const f = throttle\n ? throttledQueue(throttleNumber, throttlePeriod, throttleEquallySpaced)\n : fn => fn();\n return Promise.all(\n [...new Set(urls)].map(\n src =>\n new Promise((resolve, reject) =>\n f(() =>\n fetchImage(src)\n .then(img => resolve([src, img]))\n .catch(e => {\n if (ignoreExceptions) {\n resolve([src, undefined]);\n } else {\n reject(e);\n }\n })\n )\n )\n )\n ).then(imgs => new Map(imgs));\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"fetchImage = src => {\n const img = new Image();\n img.crossOrigin = \"anonymous\";\n img.src = src;\n return img.decode().then(() => img);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":25,"value":"urls = d3\n .json(\"https://api.github.com/emojis\")\n .then(d => Object.values(d).slice(0, 20))","pinned":false,"hidden":false,"mode":"ojs"},{"id":21,"value":"import { selectFlat } from \"@fil/selectflat\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":197,"value":"// TODO:\n// - retry after an error\n// - exponential backoff\nthrottledQueue = (\n await import(\"https://cdn.jsdelivr.net/npm/throttled-queue/+esm\")\n).throttledQueue","pinned":false,"hidden":false,"mode":"ojs"},{"id":26,"value":"d3 = require('d3@5')","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W32","stdlib":"1","titling":"auto"}