fetch-base64
Version:
A node package to retrieve fetch local or remote files in base64 encoding.
179 lines (118 loc) • 5.88 kB
Markdown
# Fetch Base64
[](https://travis-ci.org/gamell/fetch-base64)
A node package to fetch local or remote files in base64 encoding. Useful for inlining assets (images, web fonts, etc.) into HTML or CSS documents.
Disclaimer: I've only used this for images so far, but there is no reason why it shouldn't work for any other kind of files.
If you find a bug please report it [here](https://github.com/gamell/fetch-base64/issues).
# Usage
```js
const fetch = require('fetch-base64');
fetch.local('/path/to/image.jpg').then((data) => {
// data[0] contains the raw base64-encoded jpg
}).catch((reason) => {});
fetch.remote('http://domain.com/to/image.jpg').then((data) => {
// data[1] contains base64-encoded jpg with MimeType
}).catch((reason) => {});
fecth.auto('/remote/or/local/path/image.gif').then((data) => {
}).catch((reason) => {});
```
# Install
`npm install --save fetch-base64`
# API
### Return value
All the functions return a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) which when resolved will return an Array with two Strings (`data`):
- `data[0]` will contain the raw base64-encoded file. E.g.: `iVBORw0KGgoAAAANSUhEUg...`
- `data[1]` will contain the same information as `data[0]` and the mimeType. Useful if you want to embed the file into an HTMl or CSS document. E.g.: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...`
## `fetch.local(...paths)`
Fetch local files and return a promise with the file in base64 format.
### Params
- `...paths` `<string(s)>`: Single or multiple paths which will be combined using node's [`path.resolve()`](https://nodejs.org/docs/latest/api/path.html#path_path_resolve_from_to). You can pass multiple paths to resolve a relative path to an absolute path. Some examples of valid values for this parameter:
- `'/some/absolute/path/image.jpg'`
- `'/base/path/to/html', './img/animation.gif'`
## `fetch.remote(url)`
Fetch remote file in `url` and return a promise with the file in base64 format.
User Agent is spoofed to be same as Chrome's to avoid some restrictions, but fetching could still fail for other reasons.
### Params
- `url` `<string>`: URL where the file resides. Note that node must have access to the given URL.
## `fetch.remote(from, to)`
Resolve url using node's [`url.resolve(from, to)`](https://nodejs.org/api/url.html#url_url_resolve_from_to), fetch remote file and return a promise with the file in base64 format.
User Agent is spoofed to be same as Chrome's to avoid some restrictions, but fetching could still fail for other reasons.
### Params
- `from` `<string>`: The Base URL being resolved against.
- `to` `<string>`: The HREF URL being resolved.
See [`url.resolve()`](https://nodejs.org/api/url.html#url_url_resolve_from_to) for more information and examples.
## `fetch.remote(options)`
Advanced version of the `fetch.remote` where you can pass an `options` object containing:
- `paths` `<[string]>`: Array with 2 Strings representing `from` and `to` (see above).
- `url` `<string>`: The url to fetch. If both `paths` and `url` are passed, `paths` takes priority.
- `headers` `<object>`: Object containing key-value pairs with the desired HTTP Headers you want to attach to the fetch request.
User Agent will still be spoofed to be same as Chrome.
## `fetch.auto(...mixed)`
This function will do the *best effort* to automatically detect the kind of path passed (`remote` or `local`) and invoke the correspondent function.
It will use the `fetch.isRemote()` function to determine if a remote url or a local path has been passed **in the first parameter**.
### Params
- `...mixed` `<string(s)>`: Accepts the same parameters as `fetch.local(...paths)`, `fetch.remote(url)` or `fetch.remote(from, to)` - see above. Examples of valid calls:
- `fetch.auto('/base/path/to/html', './img/animation.gif');`
- `fetch.auto('http://some.domain/file.png');`
- `fetch.auto('http://some.domain/', 'file.png');`
# Utility functions
## `fetch.isLocal(path)`
Returns `true` if the passed path (`<string>`) is local. Returns `false` otherwise.
## `fetch.isRemote(path)`
Returns `true` if the passed path (`<string>`) is remote. Returns `false` otherwise.
# Examples
## Include package
```js
const fetch = require('fetch-base64');
```
## Local
```js
// will fetch image in /Users/bla/src/project/img/logo.jpg
const doFetchLocal = fetch.local('/Users/bla/src/project', './img/logo.jpg');
doFetchLocal.then((data) => {
console.log(`base64 image raw: ${data[0]}`);
}, (reason) => {
console.log(`Fetch Failed: ${reason}`)
});
```
## Remote
```js
const doFetchRemote = fetch.remote('https://somedomain.com/image.jpg');
doFetchRemote.then((data) => {
console.log(`base64 image with mimeType: ${data[1]}`);
}, (reason) => {
console.log(`Fetch Failed: ${reason}`)
});
```
```js
const doFetchRemote2 = fetch.remote('https://somedomain.com', '/image.jpg');
doFetchRemote2.then((data) => {
console.log(`base64 image with mimeType: ${data[1]}`);
}, (reason) => {
console.log(`Fetch Failed: ${reason}`)
});
```
```js
const doFetchRemote = fetch.remote({ url: 'https://somedomain.com/image.jpg', headers: { 'custom-header': 'foo' } });
doFetchRemote.then((data) => {
console.log(`base64 image with mimeType: ${data[1]}`);
}, (reason) => {
console.log(`Fetch Failed: ${reason}`)
});
```
## Auto
```js
const doFetchAuto = fetch.auto('https://somedomain.com/image.jpg');
doFetchAuto.then((data) => {
console.log(`base64 image: ${data[0]}`);
}, (reason) => {
console.log(`Fetch Failed: ${reason}`)
});
```
```js
const doFetchAuto2 = fetch.auto('/some/local/', '/path/', './image.jpg');
doFetchAuto2.then((data) => {
console.log(`base64 image: ${data[0]}`);
}, (reason) => {
console.log(`Fetch Failed: ${reason}`)
});
```