@twicpics/url

@twicpics/url provides a simple yet expressive fluent API to generate TwicPics URLs.

Here are some examples of what it can do:

const builder = require( "@twicpics/url" );

// Create a url in one pass
const onePassUrl =
    builder
        .cover( "1:1" )
        .resize( 700 )
        .src( "image.jpg" )
        .url();

// Pre-crop an image then apply different transformations to it
const precrop =
    builder
        .src( "image.jpg" )
        .focus( "25p", "71p" )
        .crop( 560, 280 );

const squareUrl = precrop.cover( "1:1" ).url();
const landscapeUrl = precrop.cover( "16:9" ).url();

// Prepare manipulations to be applied to different sources
const square = builder.cover( "1:1" ).resize( 300 );
const landscape = builder.cover( "1:1" ).resize( 300 );

const squaredUrl = square.src( "image.jpg" ).url();
const squaredPrecrop = square.src( precrop ).url();

const landscapedUrl = landscape.src( "image.jpg" ).url();
const landscapedPrecrop = landscape.src( precrop ).url();

// Scope to a given base path
const root = builder.path( "root-path" );

const firstImageInRoot = scoped.src( "image1.jpg" ).url();
const secondImageInRoot = scoped.src( "image2.jpg" ).url();

Installation

Use npm install:

npm install @twicpics/url --save

This is a server-side package for NodeJS. You cannot use it client-side.

Usage

@twicpics/url is a CommonJS module that exports a single object. So you have to require the module then call the methods of said object:

// Get the builder
const builder = require( "@twicpics/url" );

// Use the builder
const myFirstUrl = builder.src( MY_IMAGE_URL ).resize( 300 ).url();

Preferably, and if you're in ESM mode, you can use an import statement:

// Get the builder
import builder from "@twicpics/url";

// Use the builder
const myFirstUrl = builder.src( MY_IMAGE_URL ).resize( 300 ).url();

The builder's API is fluent and each method call returns a new immutable object. As such you can re-use an existing object and create a totally new and independent URL:

const squared = builder.cover( "1:1" );

const url1 = squared.src( "image1.jpg" ).url();
const url2 = squared.src( "image2.jpg" ).url();

Last, but not least, any builder object can be used as a source image by another builder object. So you can create generic manipulations to be applied on different, eventually pre-transformed, images:

const square500 = builder.cover( 500, 500 );

// Use a multiple sources path for an image I don't own
const external =
    builder
        .path( MY_PATH )
        .multiple( MY_ENCRYPTION_KEY )
        .src( URL_TO_AN_IMAGE_I_DONT_OWN );

// Precrop an image I own
const precrop = builder.src( `image.png` ).crop( {
    x: 150,
    y: 256,
    width: 700,
    height: 889,
} );

// square the image I don't own
square500.src( external ).url();

// square the image I own
square500.src( precop ).url();

API

achromatopsia

achromatopsia()

achromatopsia( <level> )

Applies the achromatopsia color filter.

// full strength
builder.achromatopsia();

// half strength
builder.achromatopsia( 0.5 );

// disable filter
builder.achromatopsia( 0 );

auto

auto()

Shortcut for output( "auto" ).

avif

avif()

Shortcut for output( "avif" ).

background

background( <color> )

Sets the image background. This will show behind translucent pixels using alpha blending.

builder.background( `red` );

border

border( <color> )

Sets the image border. This will show in borders resulting from an inside transformation.

builder.border( `red` );

contain

contain( <expr> )

contain( <width> [, <height> ] )

contain( { width, height } )

Adds a contain transformation.

// These three lines are strictly equivalent
builder.contain( "500x400" );
builder.contain( 500, 400 );
builder.contain( {
    width: 500,
    height: 400,
} );

containMax

containMax( <expr> )

containMax( <width> [, <height> ] )

containMax( { width, height } )

Adds a contain-max transformation.

// These three lines are strictly equivalent
builder.containMax( "500x400" );
builder.containMax( 500, 400 );
builder.containMax( {
    width: 500,
    height: 400,
} );

containMin

containMin( <expr> )

containMin( <width> [, <height> ] )

containMin( { width, height } )

Adds a contain-min transformation.

// These three lines are strictly equivalent
builder.containMin( "500x400" );
builder.containMin( 500, 400 );
builder.containMin( {
    width: 500,
    height: 400,
} );

cover

cover( <expr> )

cover( <width> [, <height> ] )

cover( { width, height } )

Adds a cover transformation.

// These three lines are strictly equivalent
builder.cover( "500x400" );
builder.cover( 500, 400 );
builder.cover( {
    width: 500,
    height: 400,
} );

coverMax

coverMax( <expr> )

coverMax( <width> [, <height> ] )

coverMax( { width, height } )

Adds a cover-max transformation.

// These three lines are strictly equivalent
builder.coverMax( "500x400" );
builder.coverMax( 500, 400 );
builder.coverMax( {
    width: 500,
    height: 400,
} );

coverMin

coverMin( <expr> )

coverMin( <width> [, <height> ] )

coverMin( { width, height } )

Adds a cover-min transformation.

// These three lines are strictly equivalent
builder.coverMin( "500x400" );
builder.coverMin( 500, 400 );
builder.coverMin( {
    width: 500,
    height: 400,
} );

crop

crop( <expr> )

crop( <width>[, <height> [, <x> [, <y> ] ] ] )

crop( { x, y, width, height } )

Adds a crop transformation.

// The following three lines create the same crop without origin
builder.crop( "500x400" );
builder.crop( 500, 400 );
builder.crop( {
    width: 500,
    height: 400,
} );

// The following three lines create the same crop with origin
builder.crop( "500x400@15x20" );
builder.crop( 500, 400, 15, 20 );
builder.crop( {
    x: 15,
    y: 20,
    width: 500,
    height: 400,
} );

deuteranopia

deuteranopia()

deuteranopia( <level> )

Applies the deuteranopia color filter.

// full strength
builder.deuteranopia();

// half strength
builder.deuteranopia( 0.5 );

// disable filter
builder.deuteranopia( 0 );

flip

flip( <axis> )

Creates a flip transformation.

// On both axis
builder.flip( "both" );
// On the x axis
builder.flip( "x" );
// On the y axis
builder.flip( "y" );

focus

focus( <expr> )

focus( <x> [, <y> ] )

focus( { x, y } )

Sets the focus point.

// These three lines set the exact same focus point
builder.focus( "67x987" );
builder.focus( 67, 987 );
builder.focus( {
    x: 67,
    y: 987,
} );
// This lines uses the smart crop
builder.focus( "auto" );

inside

inside( <expr> )

inside( <width> [, <height> ] )

inside( { width, height } )

Adds an inside transformation.

// These three lines are strictly equivalent
builder.inside( "500x400" );
builder.inside( 500, 400 );
builder.inside( {
    width: 500,
    height: 400,
} );

heif

heif()

Shortcut for output( "heif" ).

host

host( <location> )

Sets the TwicPics instance that is targetted.

By default, the builder will target https://i.twic.pics. Use host() to specify another location.

If no protocol is specified, the builder will default to https://.

// Target http://my-company.twic.pics
builder.host( "http://my-company.twic.pics" );

// Target https://my-brand.twic.pics
builder.host( "my-brand.twic.pics" );
builder.host( "https://my-brand.twic.pics" );

image

image()

Shortcut for output( "image" ).

jpeg

jpeg()

Shortcut for output( "jpeg" ).

maincolor

maincolor()

Shortcut for output( "maincolor" ).

max

max( <expr> )

max( <width> [, <height> ] )

max( { width, height } )

Adds a max transformation.

// These three lines are strictly equivalent
builder.max( "500x400" );
builder.max( 500, 400 );
builder.max( {
    width: 500,
    height: 400,
} );

meancolor

meancolor()

Shortcut for output( "meancolor" ).

min

min( <expr> )

min( <width> [, <height> ] )

min( { width, height } )

Adds a min transformation.

// These three lines are strictly equivalent
builder.min( "500x400" );
builder.min( 500, 400 );
builder.min( {
    width: 500,
    height: 400,
} );

multiple

multiple( <key> )

Provides the encryption key for a multiple sources path.

Further calls to src() will expect a full-fledged URL.

Use path(), prior or after the call to multiple(), in order to target the actual multiple sources path if it's not the root of your domain.

builder
    .path( `targetPath` )
    .multiple( myKey )
    .src( `https://mydomain.com/image.png` );

output

output( <type> )

Sets the image output format.

Accepted types are:

• "auto"
• "avif"
• "image"
• "heif"
• "jpeg"
• "maincolor"
• "meancolor"
• "png"
• "preview"
• "webp"

builder.output( "webp" );

path

path( [ <segment>... ] )

Adds a list of path segments to be prepended to the final src.

builder.path( "path", "to" ).src( "image.png" ).url()
    === "http://<domain>/path/to/image.png";

placeholder

placeholder( [ <expression> ] )

placeholder( [ <width>, <height> ] [, <background> [, <text> ] ] )

placeholder( [ <width>, <height> ] [, <colorExpression> ] )

placeholder( { [ <width>, <height> ] [, <background> [, <text> ] ] } )

Specifies the placeholder on which the current manipulation has to be performed.

Any call down the line to placeholder() or src() after a call to placeholder() will result in an exception.

// placeholder:auto
builder.placeholder();

// placeholder:blue
builder.placeholder( "blue" ); 
builder.placeholder( null, null, "blue" ); 
builder.placeholder( {
    "background": "blue",
} );

// placeholder:white/auto
builder.placeholder( "white/auto" );
builder.placeholder( null, null, "white/auto" );
builder.placeholder( null, null, null, "white" ); 
builder.placeholder( {
    "text": "white",
} );

// placeholder:400x300
builder.placeholder( 400, 300 ); 
builder.placeholder( {
    "width": 400,
    "height": 300,
} );

// placeholder:black/red
builder.placeholder( "black/red" );
builder.placeholder( null, null, "red", "black" );
builder.placeholder( {
    "background": "red",
    "text": "black",
} );

// placeholder:400x300:black/red
builder.placeholder( "400x300:black/red" );
builder.placeholder( 400, 300, "black/red" );
builder.placeholder( 400, 300, "red", "black" );
builder.placeholder( {
    "width": 400,
    "height": 300,
    "background": "red",
    "text": "black",
} );

png

png()

Shortcut for output( "png" ).

preview

preview()

Shortcut for output( "preview" ).

protanopia

protanopia()

protanopia( <level> )

Applies the protanopia color filter.

// full strength
builder.protanopia();

// half strength
builder.protanopia( 0.5 );

// disable filter
builder.protanopia( 0 );

quality

quality( <level> )

Sets the image quality.

level must be between 1 & 100.

builder.quality( 20 );

qualityMax

qualityMax( <level> )

Sets the maximum image quality.

level must be between 1 & 100.

builder.qualityMax( 80 );

qualityMin

qualityMin( <level> )

Sets the minimum image quality.

level must be between 1 & 100.

builder.qualityMin( 50 );

resize

resize( <expr> )

resize( <width> [, <height> ] )

resize( { width, height } )

Adds a resize transformation.

// These three lines are strictly equivalent
builder.resize( "500x400" );
builder.resize( 500, 400 );
builder.resize( {
    width: 500,
    height: 400,
} );

resizeMax

resizeMax( <expr> )

resizeMax( <width> [, <height> ] )

resizeMax( { width, height } )

Adds a resize-max transformation.

// These three lines are strictly equivalent
builder.resizeMax( "500x400" );
builder.resizeMax( 500, 400 );
builder.resizeMax( {
    width: 500,
    height: 400,
} );

resizeMin

resizeMin( <expr> )

resizeMin( <width> [, <height> ] )

resizeMin( { width, height } )

Adds a resize-min transformation.

// These three lines are strictly equivalent
builder.resizeMin( "500x400" );
builder.resizeMin( 500, 400 );
builder.resizeMin( {
    width: 500,
    height: 400,
} );

src

src( <url> )

src( <builder object> )

Sets the source image on which the current manipulation has to be performed.

If a URL is provided than it will be used as the master image to transform.

builder.resize( 300 ).src( MY_IMAGE ); // generated a 300 pixels-wide version of MY_IMAGE

If a builder object is provided than its source will be used as the new manipulation's source while its transformations will be prepended to the current ones.

const precrop = builder.src( MY_IMAGE ).crop( {
    x: 150,
    y: 256,
    width: 700,
    height: 889,
} );

// This will first crop MY_IMAGE then apply a cover=500x500
builder.cover( 500, 500 ).src( precop );

toString

toString()

Generates the URL as a string. Note that you must have provided an image URL using .src() prior to this call or an exception will be thrown.

builder.toString(); // throws an exception
builder.src( MY_IMAGE_URL ).toString(); // works

tritanopia

tritanopia()

tritanopia( <level> )

Applies the tritanopia color filter.

// full strength
builder.tritanopia();

// half strength
builder.tritanopia( 0.5 );

// disable filter
builder.tritanopia( 0 );

truecolor

truecolor( <bool> )

truecolor( <expr> )

Sets truecolor status.

builder.truecolor( true );
builder.truecolor( false );
builder.truecolor( "on" );
builder.truecolor( "off" );

turn

turn( <angle> )

turn( <direction> )

Creates a turn transformation.

// Using angles
builder.turn( 90 );
builder.turn( -90 );
// Using directions
builder.turn( "flip" );
builder.turn( "left" );
builder.turn( "right" );

url

url()

Alias of toString.

webp

webp()

Shortcut for output( "webp" ).

zoom

zoom( <level> )

Adds a zoom transformation.

builder.zoom( "1.5" );
builder.zoom( 2 );

License

© TwicPics, 2018-2023 – licensed under the MIT license.