# thurl

> Thumbor URL builder

Latest version **0.1.1** (published 2020-09-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install thurl
pnpm add thurl
yarn add thurl
bun add thurl
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2020-09-10 |
| First published | 2020-09-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 13.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Timbo Slice Creative |
| Maintainers | timboslice |
| Keywords | thumbor, javascript, node, url, builder |

## Links

- npm: https://www.npmjs.com/package/thurl
- Repository: https://github.com/timboslicecreative/thurl
- Homepage: https://github.com/timboslicecreative/thurl#readme
- Issues: https://github.com/timboslicecreative/thurl/issues
- npm.io page: https://npm.io/package/thurl

## Dependencies (1)

- [crypto](https://npm.io/package/crypto.md) ^1.0.1

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2020-09-10
- 0.1.0 — 2020-09-10

## README

# Thurl - Thumbor Url Builder
Simple thumbor url builder that supports all adjustments in a single function call and can be used
securely with HMAC or insecurely.


## Installation

Using NPM
```
npm install --save thurl
```

Using Yarn
```
yarn add thurl
```

## Setup
Load the package and create an instance with your base thumbor url and security key if using secure urls.

```javascript
const thurl = new Thurl('<thumbor url>', '<thumbor security key>');
```

### Secure
Use thumbor in secure (hmac) mode by providing the thumbor security key when initialising Thurl.
It is not recommended to use a security key is using this library within the browser as the security key
will be exposed.

ES6
```javascript
import Thurl from 'thurl';
const thurl = new Thurl('http://thumbor.mydomain.com', 'abcdefghijklmnopqrstuvwxyz123');
```
CommonJS
```javascript
const Thurl = require('../lib/index.js');
const thurl = new Thurl('http://thumbor.mydomain.com', 'abcdefghijklmnopqrstuvwxyz123');
```
CommonJS  as a one liner
```javascript
const thurl = new (require('../lib/index.js'))('http://thumbor.mydomain.com', 'abcdefghijklmnopqrstuvwxyz123')
```

### Insecure
You can use thumbor in unsafe / insecure mode by omitting the key when initialising Thurl.

ES6
```javascript
const Thurl = import 'thurl';
const thurl = new Thurl('http://thumbor.mydomain.com');
```
CommonJS
```javascript
const Thurl = require('../lib/index.js');
const thurl = new Thurl('http://thumbor.mydomain.com');
```


## Usage
`thurl.build('image', {adjustments})`

All thumbor adjustments are supported in the adjustments object provided to the `build` function.
e.g. `thurl.build('image.jpg', {property: value})`

### Simple Adjustments

|Property |Type |Default |Usage |
|---|---|---|---|
|trim |Boolean |false |`{trim: true}` |
|crop |Object |null |`{crop: {left: 1, top: 1, right: 1, bottom: 1}}` |
|fit |String |null |`{fit: 'fit-in'}` |
|width |Number |null |`{width: 100}}` |
|height |Number |null |`{height: 100}}` |
|halign |String |null |`{halign: 'center'}}` |
|valign |String |null |`{valign: 'middle'}}` |
|smart |Boolean |false |`{smart: true}` |
|filter* |String or Array |null | *Read filters section |

Simple Adjustment Examples:
```javascript
// Url: 
const imageUrl = thurl.build('image.jpg')
// imageUrl = 'http://thumbor.mydomain.com/<hmac|unsafe>/image.jpg'

// Resize: 
const thumbnail = thurl.build('image.jpg', {width: 100, height: 100})
// thumbnail = 'http://thumbor.mydomain.com/<hmac|unsafe>/100x100/image.jpg'

// Resize & Crop: 
const thumbnail = thurl.build('image.jpg', {
    crop: { left: 5, top: 10, right: 15, bottom: 20 },
    width: 100, 
    height: 100
})
// thumbnail = 'http://thumbor.mydomain.com/<hmac|unsafe>/5x10:15x20/100x100/image.jpg'
```
See [https://thumbor.readthedocs.io/en/latest/usage.html](https://thumbor.readthedocs.io/en/latest/usage.html) for all adjustments.


### Filters
You can use any thumbor filter by specifying the name and providing the filter properties as a string, number or 
array of properties. 

Example `{blur: '12,25'}` `{blur: [12,25]}` `{brightness: -100}` `{brightness: '-100'}` `{brightness: [-100]}` are all valid. 

Filter Examples: 
```javascript
// Blur: 
const imageUrl = thurl.build('image.jpg', {blur: [12,25]})
// imageUrl = 'http://thumbor.mydomain.com/<hmac|unsafe>/filters:blur(12,25)/image.jpg'

// Blur & Resize: 
const thumbnail = thurl.build('image.jpg', {width: 100, height: 100, blur: '12,25'})
// thumbnail = 'http://thumbor.mydomain.com/<hmac|unsafe>/100x100/filters:blur(12,25)/image.jpg'

// Resize & Watermark
const imageUrl = thurl.build('image.jpg', {width: 1024, watermark: ['http:/www.abc.com/img.png', -10, -11, 15, 25, 20]})
// imageUrl = 'http://thumbor.mydomain.com/<hmac|unsafe>/1024x/filters:watermark(http:/www.abc.com/img.png,-10,-11,15,25,20)/image.jpg'
```
See [https://thumbor.readthedocs.io/en/latest/filters.html](https://thumbor.readthedocs.io/en/latest/filters.html) form more information about filters.

---
_Source: https://npm.io/package/thurl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._