Karl

Karl is an ES6 Image preloader. It requires zero dependencies.

Install

``shell script

$ npm i @runmeetly/karl

$ yarn add @runmeetly/karl

`

TL;DR

`javascript
import PngFile from "./images/pngs/image.png";
import SvgFile from "./images/svgs/image.svg";
import { Karl } from "@runmeetly/karl";

Karl.preload(PngFile);
Karl.preload(SvgFile);
Karl.preload("/path/to/image/file.png");
Karl.preload(BASE64_PNG_OR_SVG_DATA);

Karl.preloadMaterialTextIcon("close");
Karl.preloadMaterialTextIcon("add");
Karl.preloadMaterialTextIcon("arrow_up");

Karl.withBackend(MyCustomBackend).preload(PngFile);
Karl.withBackend(MyCustomBackend).preloadMaterialTextIcon("person");
`

API

Karl has a small API surface - but can prove rather powerful.
Karl exposes a couple functions, preload(), preloadMaterialTextIcon(),
and withBackend().

preload accepts a single parameter of basically anything - as
long as it ultimately represents image data. A path to a file,
a Webpack parsed import, base 64 encoded png or svg data - anything.
It optionally accepts callbacks for onLoaded and onError events.
It is optional to attach callbacks, and in many cases you won't need to.
Karl will always attempt to preload the image data you pass it silently.
Once you call preload, the image will be cached for later use and will
persist for as long as the backend and the browser allows.

preloadMaterialTextIcon accepts a single parameter which is the name of a
material-icons text icon. It will preload the icon by creating a hidden div
at the bottom of your document body. This will help prevent instances where
upon the first load of the material-icon, you would briefly see the actual
text while the CSS icon is loading. Once you call preloadMaterialTextIcon,
the div will be inserted only once and will persist for as long as the
backend and the browser allows.

NOTE: preloadMaterialTextIcon does not set up the project to work with
Material Icon fonts automatically - you must do this setup manually.

withBackend is a more advanced method, and accepts an object which
conforms to the PreloaderBackend interface. A backend implementation
is backed by whatever kind of storage you want - the default
implementation is simply in-memory. A backend has both contains and
insert functions. contains is called with a key parameter from
the preload method - and should return a boolean based on whether that
key is already cached in the backend. insert is called with a key
and a value, and should insert the value into the backend and mark it
with the key.

The withBackend returns a new Karl, which exposes the preload and
preloadMaterialTextIcon methods and is powered by your provided backend.

For most cases, you will be fine using the default backend, which is
automatically injected for you when you call Karl.preload() or
Karl.preloadMaterialTextIcon().

Caveats

Browsers are ultimately in control of when and how they allocate their
resources. If you ask Karl to preload a whole bunch of images - the
browser can at its discretion evict previously loaded images.

Karl may not be perfect, but he's trying his best.

Credit

Karl is primarily developed and maintained by
Peter at
Meetly.

License

`
Copyright 2019 Meetly Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
``