!GitHub Workflow Status
!npm

imgproxy-url-builder

A TypeScript helper library for building imgproxy URLs.

Installation

``sh
npm i --save @bitpatty/imgproxy-url-builder
`

Usage

You can import the param builder and chain your transformations. For a list of available transformations check the sections below.

`typescript
import pb from '@bitpatty/imgproxy-url-builder';

// Just the transformer params
// Returns rot:90/bl:10
pb().rotate(90).blur(10).build();

// The transformer params with the target image
// Returns /-/rot:90/bl:10/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZw
pb().rotate(90).blur(10).build({
path: 's3://mybucket/myimage.png',
});

// You can disable path encoding by setting 'plain' to true
// Returns /-/rot:90/bl:10/plain/s3://mybucket/myimage.png
pb().rotate(90).blur(10).build({
plain: true,
path: 's3://mybucket/myimage.png',
});

// To sign your URL provide the key and salt
// The path is required to sign your URL!
// Returns /TXf2QXtZkU-ULvrg0pLDqJlWUb7XdHkXD0h6NFWD-mo/rot:90/bl:10/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZw
pb()
.rotate(90)
.blur(10)
.build({
path: 's3://mybucket/myimage.png',
signature: {
key: 'a91bdcda48ce22cd7d8d3a0eda93',
salt: 'a91bdcda48ce22cd7d8d3a0eda93',
size: 32, // Optional, specify the signature size. Defaults to 32
},
});

// To automatically prepend the imgproxy URL
// provide it as the 'baseUrl' setting
// Returns https://my-imgproxy-instance.example.com/-/rot:90/bl:10/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZw
pb().rotate(90).blur(10).build({
path: 's3://mybucket/myimage.png',
baseUrl: 'https://my-imgproxy-instance.example.com',
});

// You can clone the current configuration for templating / reuse
const template = pb().rotate(90);
const copy = template.clone();

// To remove a modifier, use the unset function
const t = pb().rotate(90).blur(10);
t.unset('rotate');

// ... Or you can replace the previous setting by calling the
// modifier again
const t = pb().rotate(90).blur(10); // rotate: 90, blur: 10
t.rotate(34); // rotate: 34, blur: 10
`

Chaining Pipelines

Pipelines can be chained using the chain utility function:

`typescript
import pb, { chain } from '@bitpatty/imgproxy-url-builder';

// Returns bl:10/rot:90/-/bl:10/rot:270
chain([pb().blur(10).rotate(90), pb().blur(10).rotate(270)]);

// Returns /8q2Ey2URdWizZb8PgAUKMO6C2tD4aXOa2IbCMV9pTKA/bl:10/-/ar:true/dGVzdC5wbmc
chain({
buildOptions: {
path: 'test.png',
signature: {
key: '73757065722d7365637265742d6b6579', // super-secret-key
salt: '73757065722d7365637265742d73616c74', // super-secret-salt
},
},
builders: [pb().blur(10), pb().autoRotate()],
});
`

License

Published under the MIT License.

Modifiers

- adjust
- autoRotate
- background
- backgroundAlpha
- blur
- blurDetections
- brightness
- cacheBuster
- contrast
- crop
- disableAnimation
- dpi
- dpr
- drawDetections
- duotone
- enforceThumbnail
- enlarge
- expires
- extend
- extendAspectRatio
- fallbackImageUrl
- fileName
- format
- formatQuality
- gradient
- gravity
- hashsum
- jpegOptions
- keepCopyright
- maxBytes
- minHeight
- minWidth
- monochrome
- pad
- page
- pixelate
- pngOptions
- preset
- quality
- raw
- resize
- resizingAlgorithm
- returnAttachment
- rotate
- saturation
- sharpen
- skipProcessing
- stripColorProfile
- stripMetadata
- style
- trim
- unsharpen
- videoThumbnailKeyframes
- videoThumbnailSecond
- videoThumbnailTile
- watermark
- watermarkShadow
- watermarkSize
- watermarkText
- watermarkUrl
- zoom

$3

Defines the brightness, contrast, and saturation.

#### Example

`typescript
pb().adjust({
brightness: 100, // optional
contrast: 0.8, // optional
saturation: 0.9 // optional
});
`

$3

Automatically rotates the image based on the EXIF orientation parameter.

#### Example

`typescript
pb().autoRotate();
`

$3

Fills the image background with the specified color.

#### Example

`typescript
pb().background('ff0000');

pb().background({
r: 255,
g: 0,
b: 0
});
`

$3

Adds alpha channel to background.

#### Example

`typescript
pb().backgroundAlpha(0.4);
`

$3

Applies a gaussian blur filter to the image.

#### Example

`typescript
pb().blur(10);
`

$3

Detects objects of the provided classes and blurs them.

#### Example

`typescript
pb().blurDetections({
sigma: 10,
classNames: ['face']
});
`

$3

Adjusts the brightness of an image.

#### Example

`typescript
pb().brightness(-100);
`

$3

Adds a cache buster to the imgproxy params.

#### Example

`typescript
pb().cacheBuster("abcdef123");
`

$3

Adjust contrast of the resulting image.

#### Example

`typescript
pb().contrast(0.3);
`

$3

Crops the image.

#### Example

`typescript
pb().crop({
width: 100, // optional
height: 50, // optional
gravity: { // optional
type: GravityType.CENTER, // required
offset: { // optional
x: 20, // required
y: 20 // required
}
}
})
`

$3

Use a single frame of animated images.

#### Example

`typescript
pb().disableAnimation();
`

$3

When set, imgproxy will replace the image's DPI metadata with the provided value.

#### Example

`typescript
pb().dpi(300);
`

$3

Multiplies the dimensions according to the specified factor.

#### Example

`typescript
pb().dpr(18);
`

$3

Detects objects of the provided classes and draws their bounding boxes.

#### Example

`typescript
pb().drawDetections({
classNames: ["face"]
});
`

$3

Converts the image to duotone with specified intensity and colors.

#### Example

`typescript
pb().duotone({
intensity: 1.0, // required
color1: 'ff0000', // required
color2: '00ff00' // required
});
`

$3

If the source image has an embedded thumbnail, imgproxy will use the embedded thumbnail instead of the main image.

#### Example

`typescript
pb().enforceThumbnail();
`

$3

Enlarges the image if it is smaller than the given size.

#### Example

`typescript
pb().enlarge();
`

$3

Returns a 404 if the expiration date is reached.

#### Example

`typescript
pb().expires(new Date());

pb().expires(1661431326);
`

$3

Extends the image if it is smaller than the given size.

#### Example

`typescript
pb().extend();

pb().extend({
gravity: {
type: GravityType.NORTH // required
offset: { // optional
x: 10; // required
y: 20; // required
}
}
});
`

$3

Extends the image to the requested aspect ratio.

#### Example

`typescript
pb().extendAspectRatio();

pb().extendAspectRatio({
gravity: {
type: GravityType.NORTH // required
offset: { // optional
x: 10; // required
y: 20; // required
}
}
});
`

$3

Sets a custom fallback image by specifying its URL.

#### Example

`typescript
pb().fallbackImageUrl('https://example.com');
`

$3

Sets the filename for the Content-Disposition header.

#### Example

`typescript
// Not encoded
pb().fileName('filename.png');

// Encoded
pb().fileName('ZmlsZW5hbWUucG5n', true);
`

$3

Specifies the resulting image format.

#### Example

`typescript
pb().format('png');
`

$3

Sets the desired quality for each format.

#### Example

`typescript
pb().formatQuality({
jpeg: 100,
png: 50,
// ...
});
`

$3

Places a gradient on the processed image.

#### Example

`typescript
pb().gradient({
opacity: 1, // required
color: 'ababab', // optional
direction: 'up', // optional
start: 0.0, // optional
stop: 0.7 // optional
});
`

$3

Sets the gravity.

#### Example

`typescript
pb().gravity({
type: GravityType.NORTH // required
offset: { // optional
x: 10, // required
y: 20 // required
}
});
`

$3

When hashsum_type is not none, imgproxy will calculate the hashsum of the source image and compare it with the provided hashsum.

#### Example

`typescript
pb().hashsum({
hashsum: 'ABCDEF', // required
type: HashsumType.NONE // optional
});
`

$3

Allows redefining JPEG saving options.

#### Example

`typescript
pb().jpegOptions({
progressive: boolean, // optional
noSubsample: boolean, // optional
trellisQuant: boolean, // optional
overshootDeringing: boolean, // optional
optimizeScans: boolean, // optional
quantizationTable: 7 // optional
});
`

$3

Preserve the copyright info while stripping metadata.

#### Example

`typescript
pb().keepCopyright();
`

$3

Limits the file size to the specified number of bytes.

#### Example

`typescript
pb().maxBytes(10);
`

$3

Defines the minimum height of the resulting image.

#### Example

`typescript
pb().minHeight(100);
`

$3

Defines the minimum width of the resulting image.

#### Example

`typescript
pb().minWidth(100);
`

$3

Converts the image to monochrome.

#### Example

`typescript
pb().monochrome({
intensity: 0.3, // required
color: 'ff0000' // optional
});
`

$3

Applies the specified padding to the image.

#### Example

`typescript
pb().pad({
top: 100, // optional (Note: sets all other sides if not set explicitly)
right: 100, // optional
bottom: 10, // optional
left: 10 // optional
});
`

$3

When source image supports pagination (PDF, TIFF) or animation (GIF, WebP), this option allows specifying the page to use.

#### Example

`typescript
pb().page(10);
`

$3

Apply the pixelate filter to the resulting image.

#### Example

`typescript
pb().pixelate(5);
`

$3

Allows redefining PNG saving options.

#### Example

`typescript
pb().pngOptions({
interlaced: true, // optional
quantize: false, // optional
quantization_colors: 10 // optional
});
`

$3

Sets one or many presets to be used by the imgproxy.

#### Example

`typescript
pb().preset('mypreset');

pb().preset(['preset1', 'preset2']);
`

$3

Redefines the quality of the resulting image.

#### Example

`typescript
pb().quality(80);
`

$3

Returns a raw unprocessed and unchecked source image

#### Example

`typescript
pb().raw();
`

$3

Resizes the image.

#### Example

`typescript
pb().resize({
type: ResizeType.AUTO, // optional
width: 100, // optional
height: 50 // optional
});
`

$3

Defines the algorithm that imgproxy will use for resizing.

#### Example

`typescript
pb().resizingAlgorithm(ResizingAlgorithm.NEAREST));
`

$3

Returns attachment in the Content-Disposition header.

#### Example

`typescript
pb().returnAttachment();
`

$3

Rotates the image by the specified angle.

#### Example

`typescript
pb().rotate(90);
`

$3

Adjust saturation of the resulting image.

#### Example

`typescript
pb().saturation(0.3);
`

$3

Applies a sharpen filter to the image.

#### Example

`typescript
pb().sharpen(3);
`

$3

Skip the processing of the listed formats.

#### Example

`typescript
pb().skipProcessing(['png', 'svg']);
`

$3

Strips the color profile from the image.

#### Example

`typescript
pb().stripColorProfile();
`

$3

Strips the metadata from the image.

#### Example

`typescript
pb().stripMetadata();
`

$3

Prepend a