From 8051f61d01c433c076107110502e1c035d54085d Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 12:59:03 +0530 Subject: [PATCH 01/23] refactor: improve type safety in transformation string construction and update supported transforms --- src/constants/supportedTransforms.ts | 186 ++++----------- src/interfaces/Transformation.ts | 332 ++++++++++++++++++++++++++- src/url/builder.ts | 8 +- 3 files changed, 375 insertions(+), 151 deletions(-) diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index d7fd27b..8ccc1c4 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -1,166 +1,64 @@ /** - * @link https://docs.imagekit.io/features/image-transformations + * @link https://imagekit.io/docs/transformations */ const supportedTransforms: { [key: string]: string } = { - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#width-w - */ - width: "w", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#height-h - */ - height: "h", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#aspect-ratio-ar - */ aspectRatio: "ar", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#quality-q - */ - quality: "q", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#crop-crop-modes-and-focus - */ + background: "bg", + border: "b", crop: "c", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#crop-crop-modes-and-focus - */ cropMode: "cm", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#focus-fo - */ + DPR: "dpr", focus: "fo", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#examples-focus-using-cropped-image-coordinates - */ + quality: "q", x: "x", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#examples-focus-using-cropped-image-coordinates - */ + xCenter: "xc", y: "y", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#format-f - */ + yCenter: "yc", + height: "h", + width: "w", format: "f", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#radius-r - */ + videoCodec: "vc", + audioCodec: "ac", radius: "r", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#background-color-bg - */ - background: "bg", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#border-b - */ - border: "b", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#rotate-rt - */ rotation: "rt", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#rotate-rt - */ rotate: "rt", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#blur-bl - */ blur: "bl", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#named-transformation-n - */ named: "n", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#progressive-image-pr - */ - progressive: "pr", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#lossless-webp-and-png-lo - */ - lossless: "lo", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#trim-edges-t - */ - trim: "t", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#image-metadata-md - */ - metadata: "md", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#color-profile-cp - */ - colorProfile: "cp", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#default-image-di - */ defaultImage: "di", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#dpr-dpr - */ - dpr: "dpr", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#sharpen-e-sharpen - */ - effectSharpen: "e-sharpen", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#unsharp-mask-e-usm - */ - effectUSM: "e-usm", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#contrast-stretch-e-contrast - */ - effectContrast: "e-contrast", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#grayscale-e-grayscale - */ - effectGray: "e-grayscale", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#original-image-orig - */ + flip: "fl", original: "orig", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#shadow-e-shadow - */ + startOffset: "so", + endOffset: "eo", + duration: "du", + streamingResolutions: "sr", + eGrayscale: "e-grayscale", + eRemoveDotBg: "e-removedotbg", + eUpscale: "e-upscale", + eRetouch: "e-retouch", + eGenvar: "e-genvar", + eDropshadow: "e-dropshadow", + eChangeBg: "e-changebg", + eBgRemove: "e-bgremove", + eContrast: "e-contrast", + eShadow: "e-shadow", + eSharpen: "e-sharpen", + eUSM: "e-usm", + eGradient: "e-gradient", + effectContrast: "e-contrast", effectShadow: "e-shadow", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#gradient-e-gradient - */ + effectSharpen: "e-sharpen", + effectUSM: "e-usm", effectGradient: "e-gradient", - - /** - * @link https://docs.imagekit.io/features/image-transformations/conditional-transformations - */ - raw: "raw", + effectGray: "e-grayscale", + progressive: "pr", + lossless: "lo", + colorProfile: "cp", + metadata: "md", + opacity: "o", + trim: "t", + zoom: "z", + page: "pg", + raw: "raw", } diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 0c74022..bbeba79 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -1,5 +1,331 @@ -import supportedTransforms from "../constants/supportedTransforms"; - export type TransformationPosition = "path" | "query"; -export type Transformation = Partial; +/** + * The SDK provides easy to use names for transformations. These names are converted to the corresponding transformation string before being added to the URL. + * SDKs are updated regularly to support new transformations. If you want to use a transformation that is not supported by the SDK, you can use the `raw` parameter to pass the transformation string directly. + * @link https://imagekit.io/docs/transformations + */ +export interface Transformation { + /** + * The width of the output. If a value between 0 and 1 is used, it’s treated + * as a percentage (e.g., `0.4` -> 40% of original width). You can also supply + * arithmetic expressions (e.g., `"iw_div_2"`). + */ + width?: number | string; + + /** + * The height of the output. If a value between 0 and 1 is used, it’s treated + * as a percentage (e.g., `0.5` -> 50% of original height). You can also supply + * arithmetic expressions (e.g., `"ih_mul_0.5"`). + */ + height?: number | string; + + /** + * Specifies the aspect ratio for the output, e.g., `"ar-4-3"`. + * Typically used with either width or height (not both). + * Example usage: `aspectRatio = "4:3"` or `"4_3"` or an expression like `"iar_div_2"`. + */ + aspectRatio?: number | string; + + /** + * Specify the background that can be used along with some cropping strategies while resizing an image: + * - A solid color: `"red"`, `"F3F3F3"`, `"AAFF0010"`. + * - A blurred background: `"blurred"`, `"blurred_25_N15"`, etc. + * - Expand the image boundaries using generative fill: `genfill`. Optionally control the background scene by passing text prompt: `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. + */ + background?: string; + + /** + * Add a border to the output media. Accepts `_`, + * e.g. `"5_FFF000"` (5px yellow border), or an expression like `"ih_div_20_FF00FF"`. + */ + border?: string; + + /** + * @link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus + */ + crop?: string; + + /** + * @link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus + */ + cropMode?: string; + + /** + * Possible values 0.1 to 5 or `auto` for automatic DPR calculation. + * @link https://imagekit.io/docs/image-resize-and-crop#dpr---dpr + */ + DPR?: number + + /** + * This parameter can be used along with pad resize, maintain ratio, or extract crop to change the behavior of padding or cropping + * @link https://imagekit.io/docs/image-resize-and-crop#focus---fo + */ + focus?: string; + + /** + * Used to specify the quality of the output image for lossy formats like JPEG, WebP, and AVIF. A large quality number indicates a larger output image size with high quality. A small quality number indicates a smaller output image size with lower quality. + */ + quality?: number; + + /** + * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + */ + x?: number | string; + + /** + * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + */ + xCenter?: number | string; + + /** + * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + */ + y?: number | string; + + /** + * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + */ + yCenter?: number | string; + + /** + * Output format for images or videos, e.g., `"jpg"`, `"png"`, `"webp"`, `"mp4"`, `"auto"`. + * ImageKit will automatically determine the format based on device support even if you do not specify it. + */ + format?: string; + + /** + * Video codec, e.g., `"h264"`, `"vp9"`, `"av1"`. + */ + videoCodec?: string; + + /** + * Audio codec, e.g., `"aac"`, `"opus"`. + */ + audioCodec?: string; + + /** + * Corner radius for rounded corners (e.g., `20`) or `"max"` for circular/oval shapes. + */ + radius?: number | "max"; + + /** + * Rotation in degrees. Positive values rotate clockwise; you can + * also use e.g. `"N40"` for counterclockwise or `"auto"` to read EXIF data. + * For videos only 0 , 90 , 180 , 270 and 360 values are supported. + */ + rotation?: number | string; + + /** + * @deprecated Alias of `rotation`. + * Prefer using `rotation` for clarity. + */ + rotate?: number | string; + + /** + * Gaussian blur level. Ranges 1–100 or an expression like `"bl-10"`. Possible values include integers between 1 and 100. + */ + blur?: number; + + /** + * @link https://imagekit.io/docs/transformations#named-transformations + */ + named?: string; + + /** + * Fallback image if the resource is not found, e.g., a URL or path. + * @link https://imagekit.io/docs/image-transformation#default-image---di + */ + defaultImage?: string; + + /** + * It is used to flip/mirror an image horizontally, vertically, or in both directions. + * Possible values - h (horizontal), v (vertical), h_v (horizontal and vertical) + */ + flip?: "h" | "v" | "h_v" | "v_h"; + + /** + * Whether to serve the original file without any transformations if `true`. + */ + original?: boolean + + /** + * Start offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. + * Also supports arithmetic expressions. + */ + startOffset?: number | string; + + /** + * End offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. + * Usually used with `startOffset` to define a time window. + * Also supports arithmetic expressions. + */ + endOffset?: number | string; + + /** + * Duration (in seconds) for trimming videos. e.g., `5` or `"10.5"`. + * Typically used with `startOffset` to specify length from the start point. + * Also supports arithmetic expressions. + */ + duration?: number | string; + + /** + * Resolutions for adaptive bitrate streaming (videos). + * e.g., `240_360_480_720_1080` will generate 5 representations and manifest. + * @link https://imagekit.io/docs/adaptive-bitrate-streaming + */ + streamingResolutions?: string; + + /** + * Enable grayscale effect for images. + */ + eGrayscale?: true; + + /** + * Use third-party background removal. + * See also `eBgRemove` for ImageKit's in-house background removal which is 90% cheaper. + */ + eRemoveDotBg?: true + + /** + * Upscale images beyond their original dimensions with AI. + */ + eUpscale?: true + + /** + * Retouch (AI-based) for improving faces or product shots. + */ + eRetouch?: true + + /** + * Generate variations of an image using AI. + */ + eGenvar?: true + + /** + * Add an AI-based drop shadow around a foreground object on a transparent or removed background. + * You can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`. + * @link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow + */ + eDropshadow?: true | string + + /** + * Change background using AI. Provide a prompt or base64-encoded prompt. e.g. `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. + */ + eChangeBg?: string; + + /** + * ImageKit’s in-house background removal. + */ + eBgRemove?: true + + /** + * Auto-enhance contrast for an image (contrast stretch). + */ + eContrast?: true + + /** + * Add a drop shadow under non-transparent pixels (non-AI method). Check `eDropshadow` for AI-based shadows. + * @link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow + */ + eShadow?: true | string + + /** + * Sharpen the image or specify intensity, e.g., `e-sharpen-10`. + */ + eSharpen?: true | number + + /** + * Unsharp mask for advanced sharpening, e.g., `"2-2-0.8-0.024"`. + */ + eUSM?: true | string; + + /** + * Add a linear gradient overlay. e.g., + * @link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient + */ + eGradient?: true | string; + + /** + * @deprecated Use `eContrast` instead. + */ + effectContrast?: number | string; + + /** + * @deprecated Use `eShadow` instead. + */ + effectShadow?: number | string; + + /** + * @deprecated Use `eSharpen` instead. + */ + effectSharpen?: number | string; + + /** + * @deprecated Use `eUSM` instead. + */ + effectUSM?: number | string; + + /** + * @deprecated Use `eGradient` instead. + */ + effectGradient?: string; + + /** + * @deprecated Use `eGrayscale` instead. + */ + effectGray?: boolean | string; + + /** + * Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image. This helps you maintain a fast perceived load time. + */ + progressive?: boolean; + + /** + * Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. + */ + lossless?: boolean + + /** + * It specifies whether the output image should contain the color profile initially available with the original image. + */ + colorProfile?: boolean; + + /** + * By default, ImageKit removes all metadata as part of automatic image compression. Set this to `true` to preserve metadata. + */ + metadata?: boolean; + + /** + * It is used to specify the opacity level of the output image. + * @link https://imagekit.io/docs/effects-and-enhancements#opacity---o + */ + opacity?: number; + + /** + * Useful with images that have a solid or nearly solid background with the object in the center. This parameter trims the background from the image, leaving only the central object in the output image. + * @link https://imagekit.io/docs/effects-and-enhancements#trim-edges---t + */ + trim?: true | number; + + /** + * This parameter accepts a number that determines how much to zoom in or out of the cropped area. + * It must be used along with fo-face or fo- + * @link https://imagekit.io/docs/image-resize-and-crop#zoom---z + */ + zoom?: number; + + /** + * Extract specific page/frame from multi-page or layered files (PDF, PSD, AI), + * Pick by number e.g., `2`. Or 2nd and 3rd layers combined using `3-4`. + * Or pick a layer from PSD by name, e.g., `name-layer-4`. + * @link https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files + */ + page?: number | string; + + /** + * Pass any transformation that is not directly supported by the SDK. This transformation is passed as it is in the URL. + */ + raw?: string; +} + diff --git a/src/url/builder.ts b/src/url/builder.ts index 485b41a..be00e3f 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -82,21 +82,21 @@ function constructTransformationString(transformation: Transformation[] | undefi for (var i = 0, l = transformation.length; i < l; i++) { var parsedTransformStep = []; for (var key in transformation[i]) { - if(transformation[i][key] === undefined || transformation[i][key] === null ) + if(transformation[i][key as keyof Transformation] === undefined || transformation[i][key as keyof Transformation] === null ) continue; var transformKey = transformationUtils.getTransformKey(key); if (!transformKey) { transformKey = key; } - if (transformation[i][key] === "-") { + if (transformation[i][key as keyof Transformation] === "-") { parsedTransformStep.push(transformKey); } else if (key === "raw") { parsedTransformStep.push(transformation[i][key]); } else { - var value = transformation[i][key]; + var value = transformation[i][key as keyof Transformation]; if (transformKey === "di") { - value = removeTrailingSlash(removeLeadingSlash(value || "")); + value = removeTrailingSlash(removeLeadingSlash(value as string || "")); value = value.replace(/\//g, "@@"); } parsedTransformStep.push([transformKey, value].join(transformationUtils.getTransformKeyValueDelimiter())); From 8fa1219c80062dd7401349ab97a8d4e37a84f025 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 13:53:50 +0530 Subject: [PATCH 02/23] refactor: enhance type safety and clarity in Transformation interface --- src/interfaces/Transformation.ts | 74 ++++++++------------------------ 1 file changed, 19 insertions(+), 55 deletions(-) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index bbeba79..bc0bc67 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -44,12 +44,12 @@ export interface Transformation { /** * @link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus */ - crop?: string; + crop?: "force" | "at_max" | "at_max_enlarge" | "at_least" | "maintain_ratio"; /** * @link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus */ - cropMode?: string; + cropMode?: "pad_resize" | "extract" | "pad_extract"; /** * Possible values 0.1 to 5 or `auto` for automatic DPR calculation. @@ -116,12 +116,6 @@ export interface Transformation { */ rotation?: number | string; - /** - * @deprecated Alias of `rotation`. - * Prefer using `rotation` for clarity. - */ - rotate?: number | string; - /** * Gaussian blur level. Ranges 1–100 or an expression like `"bl-10"`. Possible values include integers between 1 and 100. */ @@ -147,7 +141,7 @@ export interface Transformation { /** * Whether to serve the original file without any transformations if `true`. */ - original?: boolean + original?: true /** * Start offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. @@ -179,107 +173,77 @@ export interface Transformation { /** * Enable grayscale effect for images. */ - eGrayscale?: true; + grayScale?: true; /** * Use third-party background removal. - * See also `eBgRemove` for ImageKit's in-house background removal which is 90% cheaper. + * See also `removeBackground` for ImageKit's in-house background removal which is 90% cheaper. */ - eRemoveDotBg?: true + removeBackgroundThirdParty?: true /** * Upscale images beyond their original dimensions with AI. */ - eUpscale?: true + upscale?: true /** * Retouch (AI-based) for improving faces or product shots. */ - eRetouch?: true + retouch?: true /** - * Generate variations of an image using AI. + * Generate variation of an image using AI. This will generate a new image with slight variations from the original image. The variations include changes in color, texture, and other visual elements. However, the model will try to preserve the structure and essence of the original image. */ - eGenvar?: true + generateVariation?: true /** * Add an AI-based drop shadow around a foreground object on a transparent or removed background. * You can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`. * @link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow */ - eDropshadow?: true | string + AIDropshadow?: string /** * Change background using AI. Provide a prompt or base64-encoded prompt. e.g. `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. */ - eChangeBg?: string; + changeBackground?: string; /** * ImageKit’s in-house background removal. */ - eBgRemove?: true + removeBackground?: true /** * Auto-enhance contrast for an image (contrast stretch). */ - eContrast?: true + contrastStretch?: true /** * Add a drop shadow under non-transparent pixels (non-AI method). Check `eDropshadow` for AI-based shadows. * @link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow */ - eShadow?: true | string + shadow?: string /** * Sharpen the image or specify intensity, e.g., `e-sharpen-10`. */ - eSharpen?: true | number + sharpen?: true | number /** * Unsharp mask for advanced sharpening, e.g., `"2-2-0.8-0.024"`. */ - eUSM?: true | string; + unsharpMask?: string; /** * Add a linear gradient overlay. e.g., * @link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient */ - eGradient?: true | string; - - /** - * @deprecated Use `eContrast` instead. - */ - effectContrast?: number | string; - - /** - * @deprecated Use `eShadow` instead. - */ - effectShadow?: number | string; - - /** - * @deprecated Use `eSharpen` instead. - */ - effectSharpen?: number | string; - - /** - * @deprecated Use `eUSM` instead. - */ - effectUSM?: number | string; - - /** - * @deprecated Use `eGradient` instead. - */ - effectGradient?: string; - - /** - * @deprecated Use `eGrayscale` instead. - */ - effectGray?: boolean | string; + gradient?: string; /** * Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image. This helps you maintain a fast perceived load time. */ - progressive?: boolean; + progressiveJPEG?: boolean; /** * Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. From 63b01cdef0e1949e27e2c518009cbe60a495d66a Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 16:34:34 +0530 Subject: [PATCH 03/23] refactor: update transformation interface and supported transforms for improved clarity and consistency --- src/constants/supportedTransforms.ts | 53 ++++++++++++++++----------- src/interfaces/Transformation.ts | 55 +++++++++++++++++++++++----- src/url/builder.ts | 13 +++++-- test/url-generation.js | 2 +- 4 files changed, 88 insertions(+), 35 deletions(-) diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index 8ccc1c4..cc3ac6f 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -1,7 +1,10 @@ /** * @link https://imagekit.io/docs/transformations */ -const supportedTransforms: { [key: string]: string } = { +export const supportedTransforms: { [key: string]: string } = { + // Basic sizing & layout + width: "w", + height: "h", aspectRatio: "ar", background: "bg", border: "b", @@ -14,14 +17,11 @@ const supportedTransforms: { [key: string]: string } = { xCenter: "xc", y: "y", yCenter: "yc", - height: "h", - width: "w", format: "f", videoCodec: "vc", audioCodec: "ac", radius: "r", rotation: "rt", - rotate: "rt", blur: "bl", named: "n", defaultImage: "di", @@ -31,25 +31,31 @@ const supportedTransforms: { [key: string]: string } = { endOffset: "eo", duration: "du", streamingResolutions: "sr", - eGrayscale: "e-grayscale", - eRemoveDotBg: "e-removedotbg", - eUpscale: "e-upscale", - eRetouch: "e-retouch", - eGenvar: "e-genvar", - eDropshadow: "e-dropshadow", - eChangeBg: "e-changebg", - eBgRemove: "e-bgremove", - eContrast: "e-contrast", - eShadow: "e-shadow", - eSharpen: "e-sharpen", - eUSM: "e-usm", - eGradient: "e-gradient", - effectContrast: "e-contrast", - effectShadow: "e-shadow", + + // Old deprecated mappings effectSharpen: "e-sharpen", effectUSM: "e-usm", - effectGradient: "e-gradient", + effectContrast: "e-contrast", effectGray: "e-grayscale", + effectShadow: "e-shadow", + effectGradient: "e-gradient", + + // AI & advanced effects + grayscale: "e-grayscale", + aiBGRemoveExternal: "e-removedotbg", + aiUpscale: "e-upscale", + aiRetouch: "e-retouch", + aiVariation: "e-genvar", + aiDropShadow: "e-dropshadow", + aiChangeBackground: "e-changebg", + aiRemoveBackground: "e-bgremove", + contrastStretch: "e-contrast", + shadow: "e-shadow", + sharpen: "e-sharpen", + unsharpMask: "e-usm", + gradient: "e-gradient", + + // Other flags & finishing progressive: "pr", lossless: "lo", colorProfile: "cp", @@ -58,8 +64,13 @@ const supportedTransforms: { [key: string]: string } = { trim: "t", zoom: "z", page: "pg", + + + + // Raw pass-through raw: "raw", -} +}; + export default supportedTransforms \ No newline at end of file diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index bc0bc67..3e333ad 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -173,45 +173,45 @@ export interface Transformation { /** * Enable grayscale effect for images. */ - grayScale?: true; + grayscale?: true; /** * Use third-party background removal. * See also `removeBackground` for ImageKit's in-house background removal which is 90% cheaper. */ - removeBackgroundThirdParty?: true + aiBGRemoveExternal?: true /** * Upscale images beyond their original dimensions with AI. */ - upscale?: true + aiUpscale?: true /** * Retouch (AI-based) for improving faces or product shots. */ - retouch?: true + aiRetouch?: true /** * Generate variation of an image using AI. This will generate a new image with slight variations from the original image. The variations include changes in color, texture, and other visual elements. However, the model will try to preserve the structure and essence of the original image. */ - generateVariation?: true + aiVariation?: true /** * Add an AI-based drop shadow around a foreground object on a transparent or removed background. * You can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`. * @link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow */ - AIDropshadow?: string + aiDropShadow?: string /** * Change background using AI. Provide a prompt or base64-encoded prompt. e.g. `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. */ - changeBackground?: string; + aiChangeBackground?: string; /** * ImageKit’s in-house background removal. */ - removeBackground?: true + aiRemoveBackground?: true /** * Auto-enhance contrast for an image (contrast stretch). @@ -243,7 +243,7 @@ export interface Transformation { /** * Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image. This helps you maintain a fast perceived load time. */ - progressiveJPEG?: boolean; + progressive?: boolean; /** * Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. @@ -291,5 +291,42 @@ export interface Transformation { * Pass any transformation that is not directly supported by the SDK. This transformation is passed as it is in the URL. */ raw?: string; + + // old as it is but deprecated + + /** + * @deprecated Use `rotation` instead. + */ + rotate?: string; + + /** + * @deprecated Use `sharpen` instead. + */ + effectSharpen?: string; + + /** + * @deprecated Use `unsharpMask` instead. + */ + effectUSM?: string; + + /** + * @deprecated Use `contrastStretch` instead. + */ + effectContrast?: string; + + /** + * @deprecated Use `grayscale` instead. + */ + effectGray?: string; + + /** + * @deprecated Use `shadow` instead. + */ + effectShadow?: string; + + /** + * @deprecated Use `gradient` instead. + */ + effectGradient?: string; } diff --git a/src/url/builder.ts b/src/url/builder.ts index be00e3f..043e8dc 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -82,19 +82,24 @@ function constructTransformationString(transformation: Transformation[] | undefi for (var i = 0, l = transformation.length; i < l; i++) { var parsedTransformStep = []; for (var key in transformation[i]) { - if(transformation[i][key as keyof Transformation] === undefined || transformation[i][key as keyof Transformation] === null ) - continue; + let value = transformation[i][key as keyof Transformation]; + if (value === undefined || value === null) { + continue; + } + var transformKey = transformationUtils.getTransformKey(key); if (!transformKey) { transformKey = key; } - if (transformation[i][key as keyof Transformation] === "-") { + if (value === "-") value = true; + + if (["e-grayscale", "e-contrast", "e-removedotbg", "e-bgremove", "e-upscale", "e-retouch", "e-genvar"].includes(transformKey) && value === true) { parsedTransformStep.push(transformKey); } else if (key === "raw") { parsedTransformStep.push(transformation[i][key]); } else { - var value = transformation[i][key as keyof Transformation]; + value = transformation[i][key as keyof Transformation]; if (transformKey === "di") { value = removeTrailingSlash(removeLeadingSlash(value as string || "")); value = value.replace(/\//g, "@@"); diff --git a/test/url-generation.js b/test/url-generation.js index 4091692..b31020b 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -317,7 +317,7 @@ describe("URL generation", function () { }] }) - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast-true,e-grayscale-true,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); }); }); From 95d954e834235bf3d9782989466f31ff37c75b2d Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 16:53:09 +0530 Subject: [PATCH 04/23] refactor: enhance transformation string construction and add tests for transformation behavior --- src/url/builder.ts | 16 +++++-- test/url-generation.js | 97 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 108 insertions(+), 5 deletions(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index 043e8dc..5f1848b 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -92,9 +92,19 @@ function constructTransformationString(transformation: Transformation[] | undefi transformKey = key; } - if (value === "-") value = true; - - if (["e-grayscale", "e-contrast", "e-removedotbg", "e-bgremove", "e-upscale", "e-retouch", "e-genvar"].includes(transformKey) && value === true) { + if ( + ["e-grayscale", "e-contrast", "e-removedotbg", "e-bgremove", "e-upscale", "e-retouch", "e-genvar"].includes(transformKey) + ) { + if (value === true || value === "-" || value === "true") { + parsedTransformStep.push(transformKey); + } else { + // Any other value means that the effect should be applied + continue; + } + } else if ( + ["e-sharpen", "e-shadow", "e-gradient", "e-usm", "e-dropshadow"].includes(transformKey) && + value.toString().trim() === "" + ) { parsedTransformStep.push(transformKey); } else if (key === "raw") { parsedTransformStep.push(transformation[i][key]); diff --git a/test/url-generation.js b/test/url-generation.js index b31020b..ce6ba93 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -49,7 +49,7 @@ describe("URL generation", function () { }); it('should generate the url without sdk-version', function () { - const ik = new ImageKit({...initializationParams, sdkVersion: ""}) + const ik = new ImageKit({ ...initializationParams, sdkVersion: "" }) const url = ik.url({ path: "/test_path.jpg", @@ -231,7 +231,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:-/test_path.jpg`); }); - + /** * Provided to provide support to a new transform without sdk update */ @@ -281,6 +281,99 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg/test_path1.jpg`); }); + it('skip transformation if it is false', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + effectContrast: false + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg/test_path1.jpg`); + }); + + it('include just key if value is empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + shadow: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,e-shadow/test_path1.jpg`); + }); + + it('include value if set', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + shadow: "bl-15_st-40_x-10_y-N5" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,e-shadow-bl-15_st-40_x-10_y-N5/test_path1.jpg`); + }); + + it('trim with true as boolean', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + trim: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,t-true/test_path1.jpg`); + }); + + it('trim with true as string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + trim: "true" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,t-true/test_path1.jpg`); + }); + + it('ai remove background', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackground: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-bgremove/test_path1.jpg`); + }); + + it('ai remove background true as string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackground: "true" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-bgremove/test_path1.jpg`); + }); + + it('ai remove background other than true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackground: "false" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); + }); + it('All combined', function () { const url = imagekit.url({ path: "/test_path.jpg", From 60447ca2e90654ac366478630b82694c4138bf41 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 16:58:22 +0530 Subject: [PATCH 05/23] refactor: clean up supportedTransforms and improve type definition for original property --- src/constants/supportedTransforms.ts | 2 -- src/interfaces/Transformation.ts | 2 +- test/url-generation.js | 3 ++- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index cc3ac6f..13d3d9b 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -65,8 +65,6 @@ export const supportedTransforms: { [key: string]: string } = { zoom: "z", page: "pg", - - // Raw pass-through raw: "raw", }; diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 3e333ad..e39cd1b 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -141,7 +141,7 @@ export interface Transformation { /** * Whether to serve the original file without any transformations if `true`. */ - original?: true + original?: boolean; /** * Start offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. diff --git a/test/url-generation.js b/test/url-generation.js index ce6ba93..cbc2f4b 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -406,11 +406,12 @@ describe("URL generation", function () { effectShadow: 'bl-15_st-40_x-10_y-N5', effectGradient: 'from-red_to-white', original: true, + page: "2_4", raw: "h-200,w-300,l-image,i-logo.png,l-end" }] }) - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); }); }); From d07979fff690f348abcc18bc1f86a409c029a7c0 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 16:58:54 +0530 Subject: [PATCH 06/23] chore: bump version to 3.1.0 in package.json and package-lock.json --- package-lock.json | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 464ee1c..b1f0c3f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "imagekit-javascript", - "version": "3.0.2", + "version": "3.1.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index d101e93..1938f2e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "imagekit-javascript", - "version": "3.0.2", + "version": "3.1.0", "description": "Javascript SDK for using ImageKit.io in the browser", "main": "dist/imagekit.cjs.js", "module": "dist/imagekit.esm.js", From c96900aae42080174693557bb6b8a1a6751ca865 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 17:04:31 +0530 Subject: [PATCH 07/23] refactor: correct comment to clarify transformation effect application logic --- src/url/builder.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index 5f1848b..0e0f596 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -98,7 +98,7 @@ function constructTransformationString(transformation: Transformation[] | undefi if (value === true || value === "-" || value === "true") { parsedTransformStep.push(transformKey); } else { - // Any other value means that the effect should be applied + // Any other value means that the effect should not be applied continue; } } else if ( @@ -109,7 +109,6 @@ function constructTransformationString(transformation: Transformation[] | undefi } else if (key === "raw") { parsedTransformStep.push(transformation[i][key]); } else { - value = transformation[i][key as keyof Transformation]; if (transformKey === "di") { value = removeTrailingSlash(removeLeadingSlash(value as string || "")); value = value.replace(/\//g, "@@"); From 91445e044125e9a47c0bae5598cabbf53cd2990e Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 17:14:26 +0530 Subject: [PATCH 08/23] refactor: standardize property names for transformation interface and supported transforms --- src/constants/supportedTransforms.ts | 3 ++- src/interfaces/Transformation.ts | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index 13d3d9b..ee0189b 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -10,7 +10,7 @@ export const supportedTransforms: { [key: string]: string } = { border: "b", crop: "c", cropMode: "cm", - DPR: "dpr", + dpr: "dpr", focus: "fo", quality: "q", x: "x", @@ -39,6 +39,7 @@ export const supportedTransforms: { [key: string]: string } = { effectGray: "e-grayscale", effectShadow: "e-shadow", effectGradient: "e-gradient", + rotate: "rt", // AI & advanced effects grayscale: "e-grayscale", diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index e39cd1b..36174c8 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -55,7 +55,7 @@ export interface Transformation { * Possible values 0.1 to 5 or `auto` for automatic DPR calculation. * @link https://imagekit.io/docs/image-resize-and-crop#dpr---dpr */ - DPR?: number + dpr?: number /** * This parameter can be used along with pad resize, maintain ratio, or extract crop to change the behavior of padding or cropping From 3cdcc0800acf9f69630fa0015787ef72ebb49ce2 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 17:31:33 +0530 Subject: [PATCH 09/23] refactor: update documentation links to use the correct markdown format --- src/constants/supportedTransforms.ts | 2 +- src/index.ts | 17 ++------ src/interfaces/Transformation.ts | 60 +++++++++++++++++----------- src/interfaces/UploadOptions.ts | 2 +- src/interfaces/UploadResponse.ts | 7 ++-- src/interfaces/UrlOptions.ts | 5 ++- 6 files changed, 49 insertions(+), 44 deletions(-) diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index ee0189b..3be6194 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -1,5 +1,5 @@ /** - * @link https://imagekit.io/docs/transformations + * {@link https://imagekit.io/docs/transformations} */ export const supportedTransforms: { [key: string]: string } = { // Basic sizing & layout diff --git a/src/index.ts b/src/index.ts index c6d0bc3..9b88b33 100644 --- a/src/index.ts +++ b/src/index.ts @@ -55,27 +55,16 @@ class ImageKit { } /** - * You can add multiple origins in the same ImageKit.io account. - * URL endpoints allow you to configure which origins are accessible through your account and set their preference order as well. - * - * @see {@link https://github.com/imagekit-developer/imagekit-nodejs#url-generation} - * @see {@link https://docs.imagekit.io/integration/url-endpoints} - * - * @param urlOptions + * A utility function to generate asset URL. It applies the specified transformations and other parameters to the URL. */ url(urlOptions: UrlOptions): string { return url(urlOptions, this.options); } /** - * You can upload files to ImageKit.io media library from your server-side using private API key authentication. - * - * File size limit - * The maximum upload file size is limited to 25MB. - * - * @see {@link https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload} + * For uploading files directly from the browser to ImageKit.io. * - * @param uploadOptions + * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload} */ upload(uploadOptions: UploadOptions, options?: Partial): Promise> upload(uploadOptions: UploadOptions, callback: (err: Error | null, response: IKResponse | null) => void, options?: Partial): void; diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 36174c8..6785353 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -3,7 +3,8 @@ export type TransformationPosition = "path" | "query"; /** * The SDK provides easy to use names for transformations. These names are converted to the corresponding transformation string before being added to the URL. * SDKs are updated regularly to support new transformations. If you want to use a transformation that is not supported by the SDK, you can use the `raw` parameter to pass the transformation string directly. - * @link https://imagekit.io/docs/transformations + * + * {@link https://imagekit.io/docs/transformations} */ export interface Transformation { /** @@ -42,24 +43,26 @@ export interface Transformation { border?: string; /** - * @link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus + * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus} */ crop?: "force" | "at_max" | "at_max_enlarge" | "at_least" | "maintain_ratio"; /** - * @link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus + * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus} */ cropMode?: "pad_resize" | "extract" | "pad_extract"; /** * Possible values 0.1 to 5 or `auto` for automatic DPR calculation. - * @link https://imagekit.io/docs/image-resize-and-crop#dpr---dpr + * + * {@link https://imagekit.io/docs/image-resize-and-crop#dpr---dpr} */ dpr?: number /** * This parameter can be used along with pad resize, maintain ratio, or extract crop to change the behavior of padding or cropping - * @link https://imagekit.io/docs/image-resize-and-crop#focus---fo + * + * {@link https://imagekit.io/docs/image-resize-and-crop#focus---fo} */ focus?: string; @@ -69,22 +72,22 @@ export interface Transformation { quality?: number; /** - * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} */ x?: number | string; /** - * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} */ xCenter?: number | string; /** - * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} */ y?: number | string; /** - * @link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} */ yCenter?: number | string; @@ -122,13 +125,14 @@ export interface Transformation { blur?: number; /** - * @link https://imagekit.io/docs/transformations#named-transformations + * {@link https://imagekit.io/docs/transformations#named-transformations} */ named?: string; /** * Fallback image if the resource is not found, e.g., a URL or path. - * @link https://imagekit.io/docs/image-transformation#default-image---di + * + * {@link https://imagekit.io/docs/image-transformation#default-image---di} */ defaultImage?: string; @@ -166,7 +170,8 @@ export interface Transformation { /** * Resolutions for adaptive bitrate streaming (videos). * e.g., `240_360_480_720_1080` will generate 5 representations and manifest. - * @link https://imagekit.io/docs/adaptive-bitrate-streaming + * + * {@link https://imagekit.io/docs/adaptive-bitrate-streaming} */ streamingResolutions?: string; @@ -199,7 +204,8 @@ export interface Transformation { /** * Add an AI-based drop shadow around a foreground object on a transparent or removed background. * You can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`. - * @link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow + * + * {@link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow} */ aiDropShadow?: string @@ -219,24 +225,28 @@ export interface Transformation { contrastStretch?: true /** - * Add a drop shadow under non-transparent pixels (non-AI method). Check `eDropshadow` for AI-based shadows. - * @link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow + * This adds a shadow under solid objects in an input image with a transparent background. Check `eDropshadow` for AI-based shadows. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow} */ shadow?: string /** - * Sharpen the image or specify intensity, e.g., `e-sharpen-10`. + * It is used to sharpen the input image. It is useful when highlighting the edges and finer details within an image. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen} */ sharpen?: true | number /** - * Unsharp mask for advanced sharpening, e.g., `"2-2-0.8-0.024"`. + * Unsharp Masking (USM) is an image sharpening technique. This transform allows you to apply and control unsharp masks on your images. */ unsharpMask?: string; /** - * Add a linear gradient overlay. e.g., - * @link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient + * The gradient formed is a linear gradient containing two colors, and it can be customized. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient} */ gradient?: string; @@ -262,20 +272,23 @@ export interface Transformation { /** * It is used to specify the opacity level of the output image. - * @link https://imagekit.io/docs/effects-and-enhancements#opacity---o + * + * {@link https://imagekit.io/docs/effects-and-enhancements#opacity---o} */ opacity?: number; /** * Useful with images that have a solid or nearly solid background with the object in the center. This parameter trims the background from the image, leaving only the central object in the output image. - * @link https://imagekit.io/docs/effects-and-enhancements#trim-edges---t + * + * {@link https://imagekit.io/docs/effects-and-enhancements#trim-edges---t} */ trim?: true | number; /** * This parameter accepts a number that determines how much to zoom in or out of the cropped area. * It must be used along with fo-face or fo- - * @link https://imagekit.io/docs/image-resize-and-crop#zoom---z + * + * {@link https://imagekit.io/docs/image-resize-and-crop#zoom---z} */ zoom?: number; @@ -283,7 +296,8 @@ export interface Transformation { * Extract specific page/frame from multi-page or layered files (PDF, PSD, AI), * Pick by number e.g., `2`. Or 2nd and 3rd layers combined using `3-4`. * Or pick a layer from PSD by name, e.g., `name-layer-4`. - * @link https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files + * + * {@link https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files} */ page?: number | string; diff --git a/src/interfaces/UploadOptions.ts b/src/interfaces/UploadOptions.ts index 092f263..9a45479 100644 --- a/src/interfaces/UploadOptions.ts +++ b/src/interfaces/UploadOptions.ts @@ -23,7 +23,7 @@ interface Transformation{ /** * Options used when uploading a file * - * @link https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload#request-structure-multipart-form-data + * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#Request} */ export interface UploadOptions { /** diff --git a/src/interfaces/UploadResponse.ts b/src/interfaces/UploadResponse.ts index e3e2f93..b38cf27 100644 --- a/src/interfaces/UploadResponse.ts +++ b/src/interfaces/UploadResponse.ts @@ -4,13 +4,14 @@ * image - only search in image type files * non-image - only search in files which are not image, e.g., JS or CSS or video files. * - * @link https://docs.imagekit.io/api-reference/media-api/list-and-search-files + * {@link https://imagekit.io/docs/api-reference/digital-asset-management-dam/list-and-search-assets} */ export type FileType = "all" | "image" | "non-image"; /** * Metadata object structure - * @link https://docs.imagekit.io/api-reference/metadata-api#metadata-object-structure + * + * {@link https://imagekit.io/docs/api-reference/file-metadata/get-uploaded-file-metadata#Responses} * * Contents of Object * @@ -96,7 +97,7 @@ export interface Metadata { /** * Response from uploading a file * - * @link https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload#response-code-and-structure-json + * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#Responses} */ export interface UploadResponse { /** diff --git a/src/interfaces/UrlOptions.ts b/src/interfaces/UrlOptions.ts index c6af45d..5d1d38c 100644 --- a/src/interfaces/UrlOptions.ts +++ b/src/interfaces/UrlOptions.ts @@ -5,7 +5,8 @@ export interface UrlOptionsBase { /** * An array of objects specifying the transformations to be applied in the URL. * The transformation name and the value should be specified as a key-value pair in each object. - * @link https://docs.imagekit.io/features/image-transformations/chained-transformations + * + * {@link https://imagekit.io/docs/transformations#chained-transformations} */ transformation?: Array; /** @@ -49,6 +50,6 @@ export interface UrlOptionsPath extends UrlOptionsBase { /** * Options for generating an URL * - * @link https://github.com/imagekit-developer/imagekit-javascript#url-generation + * {@link https://github.com/imagekit-developer/imagekit-javascript#url-generation} */ export type UrlOptions = UrlOptionsSrc | UrlOptionsPath; From 7d7837a4ff8b58063ef602ccc00e180b26901b06 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 18 Mar 2025 17:41:43 +0530 Subject: [PATCH 10/23] refactor: improve comment clarity for third-party background removal in Transformation interface --- src/interfaces/Transformation.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 6785353..8130ac9 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -181,8 +181,7 @@ export interface Transformation { grayscale?: true; /** - * Use third-party background removal. - * See also `removeBackground` for ImageKit's in-house background removal which is 90% cheaper. + * Use third-party background removal. Use `removeBackground` - ImageKit's in-house background removal which is 90% cheaper. */ aiBGRemoveExternal?: true From 0d105fb947d80f54ed0e19fde7e9a55f76d3451d Mon Sep 17 00:00:00 2001 From: "ImageKit.io" <45416977+imagekitio@users.noreply.github.com> Date: Wed, 19 Mar 2025 07:44:33 +0530 Subject: [PATCH 11/23] Update src/interfaces/Transformation.ts Co-authored-by: Abhinav Dhiman <8640877+ahnv@users.noreply.github.com> --- src/interfaces/Transformation.ts | 67 ++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 8130ac9..67c363c 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -11,6 +11,8 @@ export interface Transformation { * The width of the output. If a value between 0 and 1 is used, it’s treated * as a percentage (e.g., `0.4` -> 40% of original width). You can also supply * arithmetic expressions (e.g., `"iw_div_2"`). + * + * {@link https://imagekit.io/docs/image-resize-and-crop#width---w} */ width?: number | string; @@ -18,6 +20,8 @@ export interface Transformation { * The height of the output. If a value between 0 and 1 is used, it’s treated * as a percentage (e.g., `0.5` -> 50% of original height). You can also supply * arithmetic expressions (e.g., `"ih_mul_0.5"`). + * + * {@link https://imagekit.io/docs/image-resize-and-crop#height---h} */ height?: number | string; @@ -25,20 +29,32 @@ export interface Transformation { * Specifies the aspect ratio for the output, e.g., `"ar-4-3"`. * Typically used with either width or height (not both). * Example usage: `aspectRatio = "4:3"` or `"4_3"` or an expression like `"iar_div_2"`. + * + * {@link https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar} */ aspectRatio?: number | string; /** * Specify the background that can be used along with some cropping strategies while resizing an image: * - A solid color: `"red"`, `"F3F3F3"`, `"AAFF0010"`. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#solid-color-background} + * * - A blurred background: `"blurred"`, `"blurred_25_N15"`, etc. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#blurred-background} + * * - Expand the image boundaries using generative fill: `genfill`. Optionally control the background scene by passing text prompt: `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. + * + * {@link https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill} */ background?: string; /** * Add a border to the output media. Accepts `_`, * e.g. `"5_FFF000"` (5px yellow border), or an expression like `"ih_div_20_FF00FF"`. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#border---b} */ border?: string; @@ -68,6 +84,8 @@ export interface Transformation { /** * Used to specify the quality of the output image for lossy formats like JPEG, WebP, and AVIF. A large quality number indicates a larger output image size with high quality. A small quality number indicates a smaller output image size with lower quality. + * + * {@link https://imagekit.io/docs/image-optimization#quality---q} */ quality?: number; @@ -94,21 +112,29 @@ export interface Transformation { /** * Output format for images or videos, e.g., `"jpg"`, `"png"`, `"webp"`, `"mp4"`, `"auto"`. * ImageKit will automatically determine the format based on device support even if you do not specify it. + * + * {@link https://imagekit.io/docs/image-optimization#format---f} */ format?: string; /** * Video codec, e.g., `"h264"`, `"vp9"`, `"av1"`. + * + * {@link https://imagekit.io/docs/video-optimization#video-codec---vc} */ videoCodec?: string; /** * Audio codec, e.g., `"aac"`, `"opus"`. + * + * {@link https://imagekit.io/docs/video-optimization#audio-codec---ac} */ audioCodec?: string; /** * Corner radius for rounded corners (e.g., `20`) or `"max"` for circular/oval shapes. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#radius---r} */ radius?: number | "max"; @@ -116,11 +142,15 @@ export interface Transformation { * Rotation in degrees. Positive values rotate clockwise; you can * also use e.g. `"N40"` for counterclockwise or `"auto"` to read EXIF data. * For videos only 0 , 90 , 180 , 270 and 360 values are supported. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#rotate---rt} */ rotation?: number | string; /** * Gaussian blur level. Ranges 1–100 or an expression like `"bl-10"`. Possible values include integers between 1 and 100. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#blur---bl} */ blur?: number; @@ -139,17 +169,23 @@ export interface Transformation { /** * It is used to flip/mirror an image horizontally, vertically, or in both directions. * Possible values - h (horizontal), v (vertical), h_v (horizontal and vertical) + * + * {@link https://imagekit.io/docs/effects-and-enhancements#flip---fl} */ flip?: "h" | "v" | "h_v" | "v_h"; /** * Whether to serve the original file without any transformations if `true`. + * + * {@link https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true} */ original?: boolean; /** * Start offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. * Also supports arithmetic expressions. + * + * {@link https://imagekit.io/docs/trim-videos#start-offset---so} */ startOffset?: number | string; @@ -157,6 +193,8 @@ export interface Transformation { * End offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. * Usually used with `startOffset` to define a time window. * Also supports arithmetic expressions. + * + * {@link https://imagekit.io/docs/trim-videos#end-offset---eo} */ endOffset?: number | string; @@ -164,6 +202,8 @@ export interface Transformation { * Duration (in seconds) for trimming videos. e.g., `5` or `"10.5"`. * Typically used with `startOffset` to specify length from the start point. * Also supports arithmetic expressions. + * + * {@link https://imagekit.io/docs/trim-videos#duration---du} */ duration?: number | string; @@ -177,26 +217,36 @@ export interface Transformation { /** * Enable grayscale effect for images. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale} */ grayscale?: true; /** * Use third-party background removal. Use `removeBackground` - ImageKit's in-house background removal which is 90% cheaper. + * + * {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg} */ aiBGRemoveExternal?: true /** * Upscale images beyond their original dimensions with AI. + * + * {@link https://imagekit.io/docs/ai-transformations#upscale-e-upscale} */ aiUpscale?: true /** * Retouch (AI-based) for improving faces or product shots. + * + * {@link https://imagekit.io/docs/ai-transformations#retouch-e-retouch} */ aiRetouch?: true /** * Generate variation of an image using AI. This will generate a new image with slight variations from the original image. The variations include changes in color, texture, and other visual elements. However, the model will try to preserve the structure and essence of the original image. + * + * {@link https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar} */ aiVariation?: true @@ -210,16 +260,22 @@ export interface Transformation { /** * Change background using AI. Provide a prompt or base64-encoded prompt. e.g. `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. + * + * {@link https://imagekit.io/docs/ai-transformations#change-background-e-changebg} */ aiChangeBackground?: string; /** * ImageKit’s in-house background removal. + * + * {@link https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove} */ aiRemoveBackground?: true /** * Auto-enhance contrast for an image (contrast stretch). + * + * {@link https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast} */ contrastStretch?: true @@ -239,6 +295,8 @@ export interface Transformation { /** * Unsharp Masking (USM) is an image sharpening technique. This transform allows you to apply and control unsharp masks on your images. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm} */ unsharpMask?: string; @@ -251,21 +309,29 @@ export interface Transformation { /** * Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image. This helps you maintain a fast perceived load time. + * + * {@link https://imagekit.io/docs/image-optimization#progressive-image---pr} */ progressive?: boolean; /** * Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. + * + * {@link https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo} */ lossless?: boolean /** * It specifies whether the output image should contain the color profile initially available with the original image. + * + * {@link https://imagekit.io/docs/image-optimization#color-profile---cp} */ colorProfile?: boolean; /** * By default, ImageKit removes all metadata as part of automatic image compression. Set this to `true` to preserve metadata. + * + * {@link https://imagekit.io/docs/image-optimization#image-metadata---md} */ metadata?: boolean; @@ -343,3 +409,4 @@ export interface Transformation { effectGradient?: string; } + From f9007a234c6ea6caa6f358d366d70aeb288ec1cd Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 08:40:18 +0530 Subject: [PATCH 12/23] add test cases --- README.md | 101 +++++++----- src/constants/supportedTransforms.ts | 2 +- src/interfaces/Transformation.ts | 58 ++++--- src/url/builder.ts | 9 +- test/url-generation.js | 235 ++++++++++++++++++++++++++- 5 files changed, 329 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index b996815..b7780b0 100644 --- a/README.md +++ b/README.md @@ -150,14 +150,14 @@ https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw- The `.url()` method accepts the following parameters -| Option | Description | -| :----------------| :----------------------------- | -| urlEndpoint | Optional. The base URL to be appended before the path of the image. If not specified, the URL Endpoint specified at the time of SDK initialization is used. For example, https://ik.imagekit.io/your_imagekit_id/endpoint/ | -| path | Conditional. This is the path at which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | -| src | Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | -| transformation | Optional. An array of objects specifying the transformation to be applied in the URL. The transformation name and the value should be specified as a key-value pair in the object. Different steps of a [chained transformation](https://docs.imagekit.io/features/image-transformations/chained-transformations) can be specified as different objects of the array. The complete list of supported transformations in the SDK and some examples of using them are given later. If you use a transformation name that is not specified in the SDK, it gets applied as it is in the URL. | -| transformationPostion | Optional. The default value is `path`, which places the transformation string as a path parameter in the URL. It can also be specified as `query`, which adds the transformation string as the query parameter `tr` in the URL. If you use the `src` parameter to create the URL, then the transformation string is always added as a query parameter. | -| queryParameters | Optional. These are the other query parameters that you want to add to the final URL. These can be any query parameters and are not necessarily related to ImageKit. Especially useful if you want to add some versioning parameters to your URLs. | +| Option | Description | +| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| urlEndpoint | Optional. The base URL to be appended before the path of the image. If not specified, the URL Endpoint specified at the time of SDK initialization is used. For example, https://ik.imagekit.io/your_imagekit_id/endpoint/ | +| path | Conditional. This is the path at which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | +| src | Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | +| transformation | Optional. An array of objects specifying the transformation to be applied in the URL. The transformation name and the value should be specified as a key-value pair in the object. Different steps of a [chained transformation](https://docs.imagekit.io/features/image-transformations/chained-transformations) can be specified as different objects of the array. The complete list of supported transformations in the SDK and some examples of using them are given later. If you use a transformation name that is not specified in the SDK, it gets applied as it is in the URL. | +| transformationPostion | Optional. The default value is `path`, which places the transformation string as a path parameter in the URL. It can also be specified as `query`, which adds the transformation string as the query parameter `tr` in the URL. If you use the `src` parameter to create the URL, then the transformation string is always added as a query parameter. | +| queryParameters | Optional. These are the other query parameters that you want to add to the final URL. These can be any query parameters and are not necessarily related to ImageKit. Especially useful if you want to add some versioning parameters to your URLs. | #### Examples of generating URLs @@ -294,40 +294,55 @@ See the complete list of transformations supported in ImageKit [here](https://do If you want to generate transformations in your application and add them to the URL as it is, use the `raw` parameter. -| Supported Transformation Name | Translates to parameter | -|-------------------------------|-------------------------| -| height | h | -| width | w | -| aspectRatio | ar | -| quality | q | -| crop | c | -| cropMode | cm | -| x | x | -| y | y | -| focus | fo | -| format | f | -| radius | r | -| background | bg | -| border | b | -| rotation | rt | -| blur | bl | -| named | n | -| progressive | pr | -| lossless | lo | -| trim | t | -| metadata | md | -| colorProfile | cp | -| defaultImage | di | -| dpr | dpr | -| effectSharpen | e-sharpen | -| effectUSM | e-usm | -| effectContrast | e-contrast | -| effectGray | e-grayscale | -| effectShadow | e-shadow | -| effectGradient | e-gradient | -| original | orig | -| raw | The string provided in raw will be added in the URL as it is. | - +| Supported Transformation Name | Translates to parameter | +| ----------------------------- | ------------------------------------------------------------- | +| width | w | +| height | h | +| aspectRatio | ar | +| quality | q | +| aiRemoveBackground | e-bgremove (ImageKit powered) | +| aiRemoveBackgroundExternal | e-removedotbg (Using third party) | +| aiUpscale | e-upscale | +| aiRetouch | e-retouch | +| aiVariation | e-genvar | +| aiDropShadow | e-dropshadow | +| aiChangeBackground | e-changebg | +| crop | c | +| cropMode | cm | +| x | x | +| y | y | +| focus | fo | +| format | f | +| radius | r | +| background | bg | +| border | b | +| rotation | rt | +| blur | bl | +| named | n | +| dpr | dpr | +| progressive | pr | +| lossless | lo | +| trim | t | +| metadata | md | +| colorProfile | cp | +| defaultImage | di | +| original | orig | +| videoCodec | vc | +| audioCodec | ac | +| grayscale | e-grayscale | +| contrastStretch | e-contrast | +| shadow | e-shadow | +| sharpen | e-sharpen | +| unsharpMask | e-usm | +| gradient | e-gradient | +| opacity | o | +| zoom | z | +| page | pg | +| startOffset | so | +| endOffset | eo | +| duration | du | +| streamingResolutions | sr | +| raw | The string provided in raw will be added in the URL as it is. | ### File Upload @@ -512,4 +527,4 @@ try { // {'content-type': 'application/json', 'x-request-id': 'ee560df4-d44f-455e-a48e-29dfda49aec5'} console.log(response.$ResponseMetadata.headers); } -``` \ No newline at end of file +``` diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index 3be6194..bbc560f 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -43,13 +43,13 @@ export const supportedTransforms: { [key: string]: string } = { // AI & advanced effects grayscale: "e-grayscale", - aiBGRemoveExternal: "e-removedotbg", aiUpscale: "e-upscale", aiRetouch: "e-retouch", aiVariation: "e-genvar", aiDropShadow: "e-dropshadow", aiChangeBackground: "e-changebg", aiRemoveBackground: "e-bgremove", + aiRemoveBackgroundExternal: "e-removedotbg", contrastStretch: "e-contrast", shadow: "e-shadow", sharpen: "e-sharpen", diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 67c363c..a963f8f 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -1,5 +1,7 @@ export type TransformationPosition = "path" | "query"; +type StreamingResolution = "240" | "360" | "480" | "720" | "1080" | "1440" | "2160"; + /** * The SDK provides easy to use names for transformations. These names are converted to the corresponding transformation string before being added to the URL. * SDKs are updated regularly to support new transformations. If you want to use a transformation that is not supported by the SDK, you can use the `raw` parameter to pass the transformation string directly. @@ -110,26 +112,29 @@ export interface Transformation { yCenter?: number | string; /** - * Output format for images or videos, e.g., `"jpg"`, `"png"`, `"webp"`, `"mp4"`, `"auto"`. - * ImageKit will automatically determine the format based on device support even if you do not specify it. + * Output format for images or videos, e.g., `"jpg"`, `"png"`, `"webp"`, `"mp4"`, `"auto"`. You can also pass `orig` which works only for images and will return the image in the original format. + * + * ImageKit will automatically deliver images and videos in best possible format based on the device support unless you disable it from the dashboard settings or override it using the `format` parameter. * * {@link https://imagekit.io/docs/image-optimization#format---f} + * + * {@link https://imagekit.io/docs/video-optimization#format---f}} */ - format?: string; + format?: "auto" | "webp" | "jpg" | "jpeg" | "png" | "gif" | "svg" | "mp4" | "webm" | "avif" | "orig"; /** - * Video codec, e.g., `"h264"`, `"vp9"`, `"av1"`. + * Video codec, e.g., `"h264"`, `"vp9"`, `"av1"` or `"none"`. * * {@link https://imagekit.io/docs/video-optimization#video-codec---vc} */ - videoCodec?: string; + videoCodec?: "h264" | "vp9" | "av1" | "none"; /** - * Audio codec, e.g., `"aac"`, `"opus"`. + * Audio codec, e.g., `"aac"`, `"opus"` or `"none"`. * * {@link https://imagekit.io/docs/video-optimization#audio-codec---ac} */ - audioCodec?: string; + audioCodec?: "aac" | "opus" | "none"; /** * Corner radius for rounded corners (e.g., `20`) or `"max"` for circular/oval shapes. @@ -208,12 +213,11 @@ export interface Transformation { duration?: number | string; /** - * Resolutions for adaptive bitrate streaming (videos). - * e.g., `240_360_480_720_1080` will generate 5 representations and manifest. + * Provide an array of resolutions (e.g. `["240", "360", "480", "720", "1080"]`). * * {@link https://imagekit.io/docs/adaptive-bitrate-streaming} */ - streamingResolutions?: string; + streamingResolutions?: StreamingResolution[]; /** * Enable grayscale effect for images. @@ -222,13 +226,6 @@ export interface Transformation { */ grayscale?: true; - /** - * Use third-party background removal. Use `removeBackground` - ImageKit's in-house background removal which is 90% cheaper. - * - * {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg} - */ - aiBGRemoveExternal?: true - /** * Upscale images beyond their original dimensions with AI. * @@ -252,11 +249,13 @@ export interface Transformation { /** * Add an AI-based drop shadow around a foreground object on a transparent or removed background. - * You can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`. + * Optionally, you can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`. + * + * Pass `true` for default drop shadow or a string for custom drop shadow. * * {@link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow} */ - aiDropShadow?: string + aiDropShadow?: true | string /** * Change background using AI. Provide a prompt or base64-encoded prompt. e.g. `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. @@ -272,6 +271,13 @@ export interface Transformation { */ aiRemoveBackground?: true + /** + * Use third-party background removal. Use `aiRemoveBackground` - ImageKit's in-house background removal which is 90% cheaper. + * + * {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg} + */ + aiRemoveBackgroundExternal?: true + /** * Auto-enhance contrast for an image (contrast stretch). * @@ -282,13 +288,17 @@ export interface Transformation { /** * This adds a shadow under solid objects in an input image with a transparent background. Check `eDropshadow` for AI-based shadows. * + * Pass `true` for default shadow or a string for custom shadow. + * * {@link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow} */ - shadow?: string + shadow?: true | string /** * It is used to sharpen the input image. It is useful when highlighting the edges and finer details within an image. * + * Pass `true` for default sharpening or a number for custom sharpening. + * * {@link https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen} */ sharpen?: true | number @@ -296,16 +306,20 @@ export interface Transformation { /** * Unsharp Masking (USM) is an image sharpening technique. This transform allows you to apply and control unsharp masks on your images. * + * Pass `true` for default unsharp mask or a string for custom unsharp mask. + * * {@link https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm} */ - unsharpMask?: string; + unsharpMask?: true | string; /** * The gradient formed is a linear gradient containing two colors, and it can be customized. * + * Pass `true` for default gradient or a string for custom gradient. + * * {@link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient} */ - gradient?: string; + gradient?: true | string; /** * Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image. This helps you maintain a fast perceived load time. diff --git a/src/url/builder.ts b/src/url/builder.ts index 0e0f596..b91c13b 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -103,7 +103,7 @@ function constructTransformationString(transformation: Transformation[] | undefi } } else if ( ["e-sharpen", "e-shadow", "e-gradient", "e-usm", "e-dropshadow"].includes(transformKey) && - value.toString().trim() === "" + (value.toString().trim() === "" || value === true || value === "true") ) { parsedTransformStep.push(transformKey); } else if (key === "raw") { @@ -113,6 +113,13 @@ function constructTransformationString(transformation: Transformation[] | undefi value = removeTrailingSlash(removeLeadingSlash(value as string || "")); value = value.replace(/\//g, "@@"); } + if (transformKey === "sr" && Array.isArray(value)) { + value = value.join("_"); + } + // Special case for trim with empty string - should be treated as true + if (transformKey === "t" && value.toString().trim() === "") { + value = "true"; + } parsedTransformStep.push([transformKey, value].join(transformationUtils.getTransformKeyValueDelimiter())); } } diff --git a/test/url-generation.js b/test/url-generation.js index cbc2f4b..71fd206 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -374,6 +374,204 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); }); + it('gradient with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + gradient: "ld-top_from-green_to-00FF0010_sp-1" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient-ld-top_from-green_to-00FF0010_sp-1/test_path1.jpg`); + }); + + it('gradient with empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + gradient: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient/test_path1.jpg`); + }); + + it('gradient with true value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + gradient: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient/test_path1.jpg`); + }); + + it('aiDropShadow with true value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiDropShadow: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow/test_path1.jpg`); + }); + + it('aiDropShadow with empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiDropShadow: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow/test_path1.jpg`); + }); + + it('aiDropShadow with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiDropShadow: "az-45" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow-az-45/test_path1.jpg`); + }); + + it('shadow with true value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + shadow: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow/test_path1.jpg`); + }); + + it('shadow with empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + shadow: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow/test_path1.jpg`); + }); + + it('shadow with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + shadow: "bl-15_st-40_x-10_y-N5" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow-bl-15_st-40_x-10_y-N5/test_path1.jpg`); + }); + + it('sharpen with true value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + sharpen: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen/test_path1.jpg`); + }); + + it('sharpen with empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + sharpen: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen/test_path1.jpg`); + }); + + it('sharpen with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + sharpen: 10 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen-10/test_path1.jpg`); + }); + + it('unsharpMask with true value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + unsharpMask: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm/test_path1.jpg`); + }); + + it('unsharpMask with empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + unsharpMask: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm/test_path1.jpg`); + }); + + it('unsharpMask with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + unsharpMask: "2-2-0.8-0.024" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm-2-2-0.8-0.024/test_path1.jpg`); + }); + + it('trim with true value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + trim: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-true/test_path1.jpg`); + }); + + it('trim with empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + trim: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-true/test_path1.jpg`); + }); + + it('trim with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + trim: 5 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-5/test_path1.jpg`); + }); + it('All combined', function () { const url = imagekit.url({ path: "/test_path.jpg", @@ -399,20 +597,39 @@ describe("URL generation", function () { colorProfile: true, defaultImage: "/folder/file.jpg/", //trailing and leading slash case dpr: 3, - effectSharpen: 10, - effectUSM: "2-2-0.8-0.024", - effectContrast: true, - effectGray: true, - effectShadow: 'bl-15_st-40_x-10_y-N5', - effectGradient: 'from-red_to-white', + x: 10, + y: 20, + xCenter: 30, + yCenter: 40, + flip: "h", + opacity: 0.8, + zoom: 2, + // Video transformations + videoCodec: "h264", + audioCodec: "aac", + startOffset: 5, + endOffset: 15, + duration: 10, + streamingResolutions: ["1440", "1080"], + // AI transformations + grayscale: true, + aiUpscale: true, + aiRetouch: true, + aiVariation: true, + aiDropShadow: true, + aiChangeBackground: "prompt-car", + aiRemoveBackground: true, + contrastStretch: true, + shadow: 'bl-15_st-40_x-10_y-N5', + sharpen: 10, + unsharpMask: "2-2-0.8-0.024", + gradient: 'from-red_to-white', original: true, page: "2_4", raw: "h-200,w-300,l-image,i-logo.png,l-end" }] }) - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,x-10,y-20,xc-30,yc-40,fl-h,o-0.8,z-2,vc-h264,ac-aac,so-5,eo-15,du-10,sr-1440_1080,e-grayscale,e-upscale,e-retouch,e-genvar,e-dropshadow,e-changebg-prompt-car,e-bgremove,e-contrast,e-shadow-bl-15_st-40_x-10_y-N5,e-sharpen-10,e-usm-2-2-0.8-0.024,e-gradient-from-red_to-white,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); }); }); - - From 4b123f56a14b47562c603572eee2b6e473c2ed76 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 08:45:57 +0530 Subject: [PATCH 13/23] test: add comprehensive URL generation tests for transformation parameters --- test/url-generation.js | 295 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) diff --git a/test/url-generation.js b/test/url-generation.js index 71fd206..98e54be 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -374,6 +374,39 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); }); + it('ai remove background external', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackgroundExternal: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-removedotbg/test_path1.jpg`); + }); + + it('ai remove background external true as string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackgroundExternal: "true" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-removedotbg/test_path1.jpg`); + }); + + it('ai remove background external other than true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackgroundExternal: "false" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); + }); + it('gradient with string value', function () { const url = imagekit.url({ path: "/test_path1.jpg", @@ -572,6 +605,268 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-5/test_path1.jpg`); }); + // Width parameter tests + it('width with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + width: 400 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-400/test_path1.jpg`); + }); + + it('width with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + width: "400" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-400/test_path1.jpg`); + }); + + it('width with arithmetic expression', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + width: "iw_div_2" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-iw_div_2/test_path1.jpg`); + }); + + // Height parameter tests + it('height with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + height: 300 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300/test_path1.jpg`); + }); + + it('height with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + height: "300" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300/test_path1.jpg`); + }); + + it('height with arithmetic expression', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + height: "ih_mul_0.5" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-ih_mul_0.5/test_path1.jpg`); + }); + + // AspectRatio parameter tests + it('aspectRatio with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aspectRatio: "4:3" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-4:3/test_path1.jpg`); + }); + + it('aspectRatio with alternate format', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aspectRatio: "4_3" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-4_3/test_path1.jpg`); + }); + + it('aspectRatio with expression', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aspectRatio: "iar_div_2" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-iar_div_2/test_path1.jpg`); + }); + + // Background parameter tests + it('background with solid color', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + background: "FF0000" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-FF0000/test_path1.jpg`); + }); + + it('background with blurred option', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + background: "blurred" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-blurred/test_path1.jpg`); + }); + + it('background with genfill option', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + background: "genfill" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-genfill/test_path1.jpg`); + }); + + // Crop parameter tests + it('crop with force value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + crop: "force" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:c-force/test_path1.jpg`); + }); + + it('crop with at_max value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + crop: "at_max" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:c-at_max/test_path1.jpg`); + }); + + // CropMode parameter tests + it('cropMode with pad_resize value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + cropMode: "pad_resize" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:cm-pad_resize/test_path1.jpg`); + }); + + it('cropMode with extract value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + cropMode: "extract" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:cm-extract/test_path1.jpg`); + }); + + // Focus parameter tests + it('focus with string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + focus: "center" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:fo-center/test_path1.jpg`); + }); + + it('focus with face detection', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + focus: "face" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:fo-face/test_path1.jpg`); + }); + + // Quality parameter test + it('quality with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + quality: 80 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:q-80/test_path1.jpg`); + }); + + // Coordinate parameters tests + it('x with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + x: 10 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:x-10/test_path1.jpg`); + }); + + it('y with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + y: 20 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:y-20/test_path1.jpg`); + }); + + it('xCenter with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + xCenter: 30 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:xc-30/test_path1.jpg`); + }); + + it('yCenter with number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + yCenter: 40 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:yc-40/test_path1.jpg`); + }); + it('All combined', function () { const url = imagekit.url({ path: "/test_path.jpg", From 6d72361be54e4c7f93fa92505b82ef14dd1f5dc5 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 09:01:53 +0530 Subject: [PATCH 14/23] update test cases descriptions and one test case --- README.md | 5 +- test/url-generation.js | 193 +++++++++++++++++++++++++---------------- 2 files changed, 120 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index b7780b0..11285a3 100644 --- a/README.md +++ b/README.md @@ -311,6 +311,8 @@ If you want to generate transformations in your application and add them to the | cropMode | cm | | x | x | | y | y | +| xCenter | xc | +| yCenter | yc | | focus | fo | | format | f | | radius | r | @@ -337,12 +339,13 @@ If you want to generate transformations in your application and add them to the | gradient | e-gradient | | opacity | o | | zoom | z | -| page | pg | +| page | pg | | startOffset | so | | endOffset | eo | | duration | du | | streamingResolutions | sr | | raw | The string provided in raw will be added in the URL as it is. | +| flip | fl | ### File Upload diff --git a/test/url-generation.js b/test/url-generation.js index 98e54be..126a85d 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -9,19 +9,19 @@ describe("URL generation", function () { var imagekit = new ImageKit(initializationParams); - it('no path no src', function () { + it('should return an empty string when neither path nor src is provided', function () { const url = imagekit.url({}); expect(url).equal(""); }); - it('invalid src url', function () { + it('should return an empty string for an invalid src URL', function () { const url = imagekit.url({ src: "/" }); expect(url).equal(""); }); - it('no transformation path', function () { + it('should generate a valid URL when a path is provided without transformation', function () { const url = imagekit.url({ path: "/test_path.jpg" }); @@ -29,7 +29,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg`); }); - it('no transformation src', function () { + it('should generate a valid URL when a src is provided without transformation', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg" }); @@ -37,7 +37,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg`); }); - it('Undefined parameters with path', function () { + it('should generate a valid URL when undefined transformation parameters are provided with path', function () { const url = imagekit.url({ path: "/test_path_alt.jpg", transformation: undefined, @@ -48,7 +48,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg`); }); - it('should generate the url without sdk-version', function () { + it('should generate the URL without sdk version', function () { const ik = new ImageKit({ ...initializationParams, sdkVersion: "" }) const url = ik.url({ @@ -62,7 +62,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400/test_path.jpg`); }); - it('should generate the correct url with path param', function () { + it('should generate the correct URL with a valid path and transformation', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -74,7 +74,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400/test_path.jpg`); }); - it('should generate the correct url with path param with multiple leading slash', function () { + it('should generate the correct URL when the provided path contains multiple leading slashes', function () { const url = imagekit.url({ path: "///test_path.jpg", transformation: [{ @@ -87,7 +87,7 @@ describe("URL generation", function () { }); - it('should generate the correct url with path param with overidden urlEndpoint', function () { + it('should generate the correct URL when the urlEndpoint is overridden', function () { const url = imagekit.url({ urlEndpoint: "https://ik.imagekit.io/test_url_endpoint_alt", path: "/test_path.jpg", @@ -101,7 +101,7 @@ describe("URL generation", function () { }); - it('should generate the correct url with path param with transformationPostion as query', function () { + it('should generate the correct URL with transformationPosition as query parameter when path is provided', function () { const url = imagekit.url({ path: "/test_path.jpg", transformationPosition: "query", @@ -114,7 +114,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300%2Cw-400`); }); - it('should generate the correct url with src param', function () { + it('should generate the correct URL with a valid src parameter and transformation', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg", transformation: [{ @@ -126,7 +126,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300%2Cw-400`); }); - it('should generate the correct url with transformationPostion as query', function () { + it('should generate the correct URL with transformationPosition as query parameter when src is provided', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg", transformationPosition: "query", @@ -139,7 +139,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300%2Cw-400`); }); - it('should generate the correct url with query params properly merged', function () { + it('should merge query parameters correctly in the generated URL', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?t1=v1", queryParameters: { t2: "v2", t3: "v3" }, @@ -153,7 +153,7 @@ describe("URL generation", function () { }); - it('should generate the correct chained transformation', function () { + it('should generate the correct URL with chained transformations', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -168,7 +168,7 @@ describe("URL generation", function () { }); - it('should generate the correct chained transformation url with new undocumented tranforamtion parameter', function () { + it('should generate the correct URL with chained transformations including a new undocumented transformation parameter', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -182,7 +182,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400:rndm_trnsf-abcd/test_path.jpg`); }); - it('Overlay image', function () { + it('should generate the correct URL when overlay image transformation is provided', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -195,7 +195,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,l-image,i-overlay.jpg,w-100,b-10_CDDC39,l-end/test_path.jpg`); }); - it('Overlay image with slash in path', function () { + it('should generate the correct URL when overlay image transformation contains a slash in the overlay path', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -208,7 +208,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,l-image,i-/path/to/overlay.jpg,w-100,b-10_CDDC39,l-end/test_path.jpg`); }); - it('Border', function () { + it('should generate the correct URL when border transformation is applied', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -221,7 +221,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,b-20_FF0000/test_path.jpg`); }); - it('transformation with empty key and empty value', function () { + it('should generate the correct URL when transformation has empty key and value', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -229,13 +229,13 @@ describe("URL generation", function () { }] }) - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:-/test_path.jpg`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg`); }); /** * Provided to provide support to a new transform without sdk update */ - it('transformation with undefined transform', function () { + it('should generate the correct URL when an undefined transform is provided', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -246,7 +246,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:undefined-transform-true/test_path.jpg`); }); - it('transformation with empty value', function () { + it('should generate the correct URL when transformation key has an empty value', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -257,7 +257,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-/test_path.jpg`); }); - it('transformation with - value', function () { + it('should generate the correct URL when transformation key has \'-\' as its value', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -268,7 +268,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-contrast/test_path.jpg`); }); - it('skip transformation if it is undefined or null', function () { + it('should skip transformation parameters that are undefined or null', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -281,7 +281,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg/test_path1.jpg`); }); - it('skip transformation if it is false', function () { + it('should skip transformation parameters that are false', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -293,7 +293,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg/test_path1.jpg`); }); - it('include just key if value is empty string', function () { + it('should include only the key when transformation value is an empty string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -305,7 +305,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,e-shadow/test_path1.jpg`); }); - it('include value if set', function () { + it('should include both key and value when transformation parameter value is provided', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -317,7 +317,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,e-shadow-bl-15_st-40_x-10_y-N5/test_path1.jpg`); }); - it('trim with true as boolean', function () { + it('should generate the correct URL when trim transformation is set to true as a boolean', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -329,7 +329,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,t-true/test_path1.jpg`); }); - it('trim with true as string', function () { + it('should generate the correct URL when trim transformation is set to true as a string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -341,7 +341,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,t-true/test_path1.jpg`); }); - it('ai remove background', function () { + it('should generate the correct URL for AI background removal when set to true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -352,7 +352,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-bgremove/test_path1.jpg`); }); - it('ai remove background true as string', function () { + it('should generate the correct URL for AI background removal when \'true\' is provided as a string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -363,7 +363,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-bgremove/test_path1.jpg`); }); - it('ai remove background other than true', function () { + it('should not apply AI background removal when value is not true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -374,7 +374,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); }); - it('ai remove background external', function () { + it('should generate the correct URL for external AI background removal when set to true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -385,7 +385,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-removedotbg/test_path1.jpg`); }); - it('ai remove background external true as string', function () { + it('should generate the correct URL for external AI background removal when \'true\' is provided as a string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -396,7 +396,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-removedotbg/test_path1.jpg`); }); - it('ai remove background external other than true', function () { + it('should not apply external AI background removal when value is not true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -407,7 +407,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); }); - it('gradient with string value', function () { + it('should generate the correct URL when gradient transformation is provided as a string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -418,7 +418,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient-ld-top_from-green_to-00FF0010_sp-1/test_path1.jpg`); }); - it('gradient with empty string', function () { + it('should generate the correct URL when gradient transformation is provided as an empty string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -429,7 +429,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient/test_path1.jpg`); }); - it('gradient with true value', function () { + it('should generate the correct URL when gradient transformation is set to true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -440,7 +440,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient/test_path1.jpg`); }); - it('aiDropShadow with true value', function () { + it('should generate the correct URL when AI drop shadow transformation is set to true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -451,7 +451,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow/test_path1.jpg`); }); - it('aiDropShadow with empty string', function () { + it('should generate the correct URL when AI drop shadow transformation is provided as an empty string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -462,7 +462,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow/test_path1.jpg`); }); - it('aiDropShadow with string value', function () { + it('should generate the correct URL when AI drop shadow transformation is provided with a specific string value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -473,7 +473,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow-az-45/test_path1.jpg`); }); - it('shadow with true value', function () { + it('should generate the correct URL when shadow transformation is set to true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -484,7 +484,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow/test_path1.jpg`); }); - it('shadow with empty string', function () { + it('should generate the correct URL when shadow transformation is provided as an empty string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -495,7 +495,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow/test_path1.jpg`); }); - it('shadow with string value', function () { + it('should generate the correct URL when shadow transformation is provided with a specific string value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -506,7 +506,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow-bl-15_st-40_x-10_y-N5/test_path1.jpg`); }); - it('sharpen with true value', function () { + it('should generate the correct URL when sharpen transformation is set to true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -517,7 +517,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen/test_path1.jpg`); }); - it('sharpen with empty string', function () { + it('should generate the correct URL when sharpen transformation is provided as an empty string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -528,7 +528,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen/test_path1.jpg`); }); - it('sharpen with number value', function () { + it('should generate the correct URL when sharpen transformation is provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -539,7 +539,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen-10/test_path1.jpg`); }); - it('unsharpMask with true value', function () { + it('should generate the correct URL when unsharpMask transformation is set to true', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -550,7 +550,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm/test_path1.jpg`); }); - it('unsharpMask with empty string', function () { + it('should generate the correct URL when unsharpMask transformation is provided as an empty string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -561,7 +561,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm/test_path1.jpg`); }); - it('unsharpMask with string value', function () { + it('should generate the correct URL when unsharpMask transformation is provided with a string value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -572,7 +572,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm-2-2-0.8-0.024/test_path1.jpg`); }); - it('trim with true value', function () { + it('should generate the correct URL for trim transformation when set to true (boolean)', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -583,7 +583,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-true/test_path1.jpg`); }); - it('trim with empty string', function () { + it('should generate the correct URL for trim transformation when provided as an empty string', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -594,7 +594,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-true/test_path1.jpg`); }); - it('trim with number value', function () { + it('should generate the correct URL for trim transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -606,7 +606,7 @@ describe("URL generation", function () { }); // Width parameter tests - it('width with number value', function () { + it('should generate the correct URL for width transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -617,7 +617,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-400/test_path1.jpg`); }); - it('width with string value', function () { + it('should generate the correct URL for width transformation when provided with a string value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -628,7 +628,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-400/test_path1.jpg`); }); - it('width with arithmetic expression', function () { + it('should generate the correct URL for width transformation when provided with an arithmetic expression', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -640,7 +640,7 @@ describe("URL generation", function () { }); // Height parameter tests - it('height with number value', function () { + it('should generate the correct URL for height transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -651,7 +651,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300/test_path1.jpg`); }); - it('height with string value', function () { + it('should generate the correct URL for height transformation when provided with a string value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -662,7 +662,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300/test_path1.jpg`); }); - it('height with arithmetic expression', function () { + it('should generate the correct URL for height transformation when provided with an arithmetic expression', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -674,7 +674,7 @@ describe("URL generation", function () { }); // AspectRatio parameter tests - it('aspectRatio with string value', function () { + it('should generate the correct URL for aspectRatio transformation when provided with a string value in colon format', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -685,7 +685,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-4:3/test_path1.jpg`); }); - it('aspectRatio with alternate format', function () { + it('should generate the correct URL for aspectRatio transformation when provided with an alternate underscore format', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -696,7 +696,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-4_3/test_path1.jpg`); }); - it('aspectRatio with expression', function () { + it('should generate the correct URL for aspectRatio transformation when provided with an arithmetic expression', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -708,7 +708,7 @@ describe("URL generation", function () { }); // Background parameter tests - it('background with solid color', function () { + it('should generate the correct URL for background transformation when provided with a solid color', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -719,7 +719,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-FF0000/test_path1.jpg`); }); - it('background with blurred option', function () { + it('should generate the correct URL for background transformation when provided with the blurred option', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -730,7 +730,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-blurred/test_path1.jpg`); }); - it('background with genfill option', function () { + it('should generate the correct URL for background transformation when provided with the genfill option', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -742,7 +742,7 @@ describe("URL generation", function () { }); // Crop parameter tests - it('crop with force value', function () { + it('should generate the correct URL for crop transformation when provided with force value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -753,7 +753,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:c-force/test_path1.jpg`); }); - it('crop with at_max value', function () { + it('should generate the correct URL for crop transformation when provided with at_max value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -765,7 +765,7 @@ describe("URL generation", function () { }); // CropMode parameter tests - it('cropMode with pad_resize value', function () { + it('should generate the correct URL for cropMode transformation when provided with pad_resize', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -776,7 +776,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:cm-pad_resize/test_path1.jpg`); }); - it('cropMode with extract value', function () { + it('should generate the correct URL for cropMode transformation when provided with extract value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -788,7 +788,7 @@ describe("URL generation", function () { }); // Focus parameter tests - it('focus with string value', function () { + it('should generate the correct URL for focus transformation when provided with a string value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -799,7 +799,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:fo-center/test_path1.jpg`); }); - it('focus with face detection', function () { + it('should generate the correct URL for focus transformation when face detection is specified', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -811,7 +811,7 @@ describe("URL generation", function () { }); // Quality parameter test - it('quality with number value', function () { + it('should generate the correct URL for quality transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -823,7 +823,7 @@ describe("URL generation", function () { }); // Coordinate parameters tests - it('x with number value', function () { + it('should generate the correct URL for x coordinate transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -834,7 +834,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:x-10/test_path1.jpg`); }); - it('y with number value', function () { + it('should generate the correct URL for y coordinate transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -845,7 +845,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:y-20/test_path1.jpg`); }); - it('xCenter with number value', function () { + it('should generate the correct URL for xCenter transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -856,7 +856,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:xc-30/test_path1.jpg`); }); - it('yCenter with number value', function () { + it('should generate the correct URL for yCenter transformation when provided with a number value', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -867,7 +867,46 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:yc-40/test_path1.jpg`); }); - it('All combined', function () { + it('Including deprecated properties', function () { + const url = imagekit.url({ + path: "/test_path.jpg", + transformation: [{ + height: 300, + width: 400, + aspectRatio: '4-3', + quality: 40, + crop: 'force', + cropMode: 'extract', + focus: 'left', + format: 'jpeg', + radius: 50, + bg: "A94D34", + border: "5-A94D34", + rotation: 90, + blur: 10, + named: "some_name", + progressive: true, + lossless: true, + trim: 5, + metadata: true, + colorProfile: true, + defaultImage: "/folder/file.jpg/", //trailing and leading slash case + dpr: 3, + effectSharpen: 10, + effectUSM: "2-2-0.8-0.024", + effectContrast: true, + effectGray: true, + effectShadow: 'bl-15_st-40_x-10_y-N5', + effectGradient: 'from-red_to-white', + original: true, + raw: "h-200,w-300,l-image,i-logo.png,l-end" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); + }); + + it('should generate the correct URL when comprehensive transformations, including video and AI transformations, are applied', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ From d9fa8ffec7771a0f4f2a9cf6e7233f0806b3c5d1 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 09:25:41 +0530 Subject: [PATCH 15/23] fix: handle empty transformation keys in URL construction --- src/url/builder.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index b91c13b..29e13f8 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -92,6 +92,10 @@ function constructTransformationString(transformation: Transformation[] | undefi transformKey = key; } + if (transformKey === "") { + continue; + } + if ( ["e-grayscale", "e-contrast", "e-removedotbg", "e-bgremove", "e-upscale", "e-retouch", "e-genvar"].includes(transformKey) ) { @@ -123,7 +127,9 @@ function constructTransformationString(transformation: Transformation[] | undefi parsedTransformStep.push([transformKey, value].join(transformationUtils.getTransformKeyValueDelimiter())); } } - parsedTransforms.push(parsedTransformStep.join(transformationUtils.getTransformDelimiter())); + if (parsedTransformStep.length) { + parsedTransforms.push(parsedTransformStep.join(transformationUtils.getTransformDelimiter())); + } } return parsedTransforms.join(transformationUtils.getChainTransformDelimiter()); From 40deb6b8fcd1ac70b3436b6db66e562d29428517 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 09:37:20 +0530 Subject: [PATCH 16/23] chore: add CHANGELOG.md and update README to include changelog reference --- CHANGELOG.md | 23 ++++++++++++++++++++ README.md | 61 ++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 73 insertions(+), 11 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..aace157 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog + +## SDK Version 3.0.0 + +### Breaking Changes + +- **Overlay Syntax Update** + In version 3.0.0, the old overlay syntax parameters for transformations (e.g., `oi`, `ot`, `obg`, and others as detailed [here](https://docs.imagekit.io/features/image-transformations/overlay)) have been removed. These parameters are deprecated and will now return errors when used in URLs. + + **Action Required:** + Migrate to the new layers syntax which supports overlay nesting, offers improved positional control, and allows more transformations at the layer level. For a quick start, refer to the [examples](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#examples). Use the `raw` transformation parameter to implement this migration. + +--- + +## SDK Version 2.0.0 + +### Breaking Changes + +- **Authentication Process Update** + Previously, client-side file uploads required the SDK to be initialized with both the `publicKey` and `authenticationEndpoint` to fetch security parameters (`signature`, `token`, and `expire`). + + **Action Required:** + With version 2.0.0, you must now generate the security parameters (`signature`, `token`, and `expire`) yourself, eliminating the need for the `authenticationEndpoint`. When invoking the SDK's upload method, be sure to include these parameters along with other [upload options](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). For further details, consult the documentation [here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#signature-generation-for-client-side-file-upload). diff --git a/README.md b/README.md index 11285a3..1bf0125 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,13 @@ # ImageKit.io Javascript SDK +## Table of Contents +- [Changelog](#changelog) +- [Installation](#installation) +- [Initialization](#initialization) +- [Demo Application](#demo-application) +- [Usage](#usage) + ![gzip size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=gzip&label=gzip) ![brotli size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=brotli&label=brotli) ![Node CI](https://github.com/imagekit-developer/imagekit-javascript/workflows/Node%20CI/badge.svg) @@ -15,16 +22,7 @@ Javascript SDK for [ImageKit](https://imagekit.io/) provides URL generation for ImageKit is complete media storage, optimization, and transformation solution that comes with an [image and video CDN](https://imagekit.io/features/imagekit-infrastructure). It can be integrated with your existing infrastructure - storage like AWS S3, web servers, your CDN, and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes. ## Changelog -### SDK Version 3.0.0 -#### Breaking changes -**1. Overlay syntax update** -* In version 3.0.0, we've removed the old overlay syntax parameters for transformations, such as `oi`, `ot`, `obg`, and [more](https://docs.imagekit.io/features/image-transformations/overlay). These parameters are deprecated and will start returning errors when used in URLs. Please migrate to the new layers syntax that supports overlay nesting, provides better positional control, and allows more transformations at the layer level. You can start with [examples](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#examples) to learn quickly. -* You can migrate to the new layers syntax using the `raw` transformation parameter. -### SDK Version 2.0.0 -#### Breaking changes -**1. Authentication Process Update:** -* Previously, when using client side file upload, the SDK required the `publicKey` and `authenticationEndpoint` parameters during SDK initialization to fetch security parameters (`signature`, `token`, and `expire`). -* In version 2.0.0, we've updated the authentication process for the SDK. As a user of the SDK, you are now responsible for generating the security parameters (`signature`, `token`, and `expire`) yourself. This means you no longer need to provide the `authenticationEndpoint`. When using the SDK's upload method, make sure to pass these security parameters explicitly along with other [upload options](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). For guidance on generating these security parameters, please refer to the documentation available [here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#signature-generation-for-client-side-file-upload). +For a detailed history of changes, please refer to [CHANGELOG.md](CHANGELOG.md). ## Installation @@ -288,7 +286,48 @@ var imageURL = imagekit.url({ https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-iw_div_4,h-ih_div_2,b-cw_mul_0.05_yellow ``` -#### List of supported transformations +### Key Advanced Transformations + +#### Background Removal + +```js +var imageURL = imagekit.url({ + path: "/sample-image.jpg", + transformation: [{ + aiRemoveBackground: true + }] +}); +console.log("Background Removed Image URL:", imageURL); +// Expected: https://ik.imagekit.io/your_imagekit_id/tr:e-bgremove/sample-image.jpg +``` + +#### Upscaling + +```js +var upscaledURL = imagekit.url({ + path: "/sample-image.jpg", + transformation: [{ + aiUpscale: true + }] +}); +console.log("Upscaled Image URL:", upscaledURL); +// Expected: https://ik.imagekit.io/your_imagekit_id/tr:e-upscale/sample-image.jpg +``` + +#### AI Drop Shadow + +```js +var dropShadowURL = imagekit.url({ + path: "/sample-image.jpg", + transformation: [{ + aiDropShadow: "az-45" + }] +}); +console.log("Image URL with Drop Shadow:", dropShadowURL); +// Expected: https://ik.imagekit.io/your_imagekit_id/tr:e-dropshadow-az-45/sample-image.jpg +``` + +### List of supported transformations See the complete list of transformations supported in ImageKit [here](https://docs.imagekit.io/features/image-transformations). The SDK gives a name to each transformation parameter e.g. `height` for `h` and `width` for `w` parameter. It makes your code more readable. If the property does not match any of the following supported options, it is added as it is. From ed31f5534f3177f045fcfd159d068363cca1217e Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 09:50:35 +0530 Subject: [PATCH 17/23] update readme --- README.md | 622 +++++++++++++++++------------------------------------- 1 file changed, 195 insertions(+), 427 deletions(-) diff --git a/README.md b/README.md index 1bf0125..f465a47 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,22 @@ [ImageKit.io](https://imagekit.io) -# ImageKit.io Javascript SDK +# ImageKit.io JavaScript SDK + +Lightweight JavaScript SDK for generating optimized URLs for images and videos, and for handling file uploads via ImageKit. ## Table of Contents -- [Changelog](#changelog) - [Installation](#installation) - [Initialization](#initialization) +- [URL Generation](#url-generation) + - [Basic URL Generation](#basic-url-generation) + - [Advanced URL Generation Examples](#advanced-url-generation-examples) + - [Supported Transformations](#supported-transformations) + - [Handling Unsupported Transformations](#handling-unsupported-transformations) +- [File Upload](#file-upload) + - [Basic Upload Example](#basic-upload-example) + - [Promise-based Upload Example](#promise-based-upload-example) - [Demo Application](#demo-application) -- [Usage](#usage) +- [Changelog](#changelog) ![gzip size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=gzip&label=gzip) ![brotli size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=brotli&label=brotli) @@ -17,279 +26,140 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ImagekitIo) -Javascript SDK for [ImageKit](https://imagekit.io/) provides URL generation for image & video resizing and provides an interface for file upload. This SDK is lightweight and has no dependency. You can also use this as an ES module. - -ImageKit is complete media storage, optimization, and transformation solution that comes with an [image and video CDN](https://imagekit.io/features/imagekit-infrastructure). It can be integrated with your existing infrastructure - storage like AWS S3, web servers, your CDN, and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes. - -## Changelog -For a detailed history of changes, please refer to [CHANGELOG.md](CHANGELOG.md). - ## Installation ### Using npm -Install `imagekit-javascript` -``` +Install the SDK via npm: +```bash npm install imagekit-javascript --save -#or +# or yarn add imagekit-javascript ``` -Now import ImageKit +Then import ImageKit: ```js -import ImageKit from "imagekit-javascript" - -// or -const ImageKit = require("imagekit-javascript") +import ImageKit from "imagekit-javascript"; +// or with CommonJS: +const ImageKit = require("imagekit-javascript"); ``` ### Using CDN -You can download a specific version of this SDK from a global CDN. +You can also use the global CDN: + +Download a specific version: ``` https://unpkg.com/imagekit-javascript@1.3.0/dist/imagekit.min.js ``` - -For the latest version, remove the version number i.e. +Or for the latest version, remove the version number: ``` https://unpkg.com/imagekit-javascript/dist/imagekit.min.js ``` - -Now load it using a ` ``` ## Initialization -`urlEndpoint` is required to use the SDK. You can get URL-endpoint from your ImageKit dashboard - https://imagekit.io/dashboard#url-endpoints - -``` +Initialize the SDK with your URL endpoint. For URL generation: +```js var imagekit = new ImageKit({ urlEndpoint: "https://ik.imagekit.io/your_imagekit_id" -}); -``` - -`publicKey` parameter is required if you want to use the SDK for client-side file upload. You can get this parameter from the developer section in your ImageKit dashboard - https://imagekit.io/dashboard#developers +}); ``` +For client-side file uploads, include your public key: +```js var imagekit = new ImageKit({ publicKey: "your_public_api_key", urlEndpoint: "https://ik.imagekit.io/your_imagekit_id", -}); -``` - -*Note: Do not include your Private Key in any client-side code, including this SDK or its initialization. If you pass the `privateKey` parameter while initializing this SDK, it throws an error* - -## Demo Application - -The fastest way to get started is by running the demo application in [samples/sample-app](https://github.com/imagekit-developer/imagekit-javascript/tree/master/samples/sample-app) folder. Follow these steps to run the application locally: - -``` -git clone https://github.com/imagekit-developer/imagekit-javascript.git - -cd imagekit-javascript -``` - -Create a file `.env` using `sample.env` in the directory `samples/sample-app` and fill in your `PRIVATE_KEY`, `PUBLIC_KEY` and `URL_ENDPOINT` from your [imageKit dashboard](https://imagekit.io/dashboard#developers). `SERVER_PORT` must also be included as per the `sample.env` file. - -Now start the sample application by running: - -``` -// Run it from the project root -yarn startSampleApp -``` - -## Usage -You can use this SDK for URL generation and client-side file uploads. - -### URL Generation - -**1. Using image path and image hostname or endpoint** - -This method allows you to create an URL to access a file using the relative file path and the ImageKit URL endpoint (`urlEndpoint`). The file can be an image, video, or any other static file supported by ImageKit. - -``` -var imageURL = imagekit.url({ - path: "/default-image.jpg", - urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", - transformation: [{ - "height": "300", - "width": "400" - }] -}); -``` - -This results in a URL like - -``` -https://ik.imagekit.io/your_imagekit_id/endpoint/tr:h-300,w-400/default-image.jpg -``` - -**2. Using full image URL** - -This method allows you to add transformation parameters to an absolute URL. For example, if you have configured a custom CNAME and have absolute asset URLs in your database or CMS, you will often need this. - - -``` -var imageURL = imagekit.url({ - src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg", - transformation: [{ - "height": "300", - "width": "400" - }] }); ``` +*Note: Never include your private key in client-side code. If provided, the SDK throws an error.* -This results in a URL like - -``` -https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400 -``` +## URL Generation +The SDK’s `.url()` method enables you to generate optimized image and video URLs with a variety of transformations. -The `.url()` method accepts the following parameters +### Basic URL Generation -| Option | Description | -| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| urlEndpoint | Optional. The base URL to be appended before the path of the image. If not specified, the URL Endpoint specified at the time of SDK initialization is used. For example, https://ik.imagekit.io/your_imagekit_id/endpoint/ | -| path | Conditional. This is the path at which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | -| src | Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | -| transformation | Optional. An array of objects specifying the transformation to be applied in the URL. The transformation name and the value should be specified as a key-value pair in the object. Different steps of a [chained transformation](https://docs.imagekit.io/features/image-transformations/chained-transformations) can be specified as different objects of the array. The complete list of supported transformations in the SDK and some examples of using them are given later. If you use a transformation name that is not specified in the SDK, it gets applied as it is in the URL. | -| transformationPostion | Optional. The default value is `path`, which places the transformation string as a path parameter in the URL. It can also be specified as `query`, which adds the transformation string as the query parameter `tr` in the URL. If you use the `src` parameter to create the URL, then the transformation string is always added as a query parameter. | -| queryParameters | Optional. These are the other query parameters that you want to add to the final URL. These can be any query parameters and are not necessarily related to ImageKit. Especially useful if you want to add some versioning parameters to your URLs. | +1. **Using an Image Path with a URL Endpoint** + ```js + var imageURL = imagekit.url({ + path: "/default-image.jpg", + urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", + transformation: [{ + "height": "300", + "width": "400" + }] + }); + ``` + *Result Example:* + ``` + https://ik.imagekit.io/your_imagekit_id/endpoint/tr:h-300,w-400/default-image.jpg + ``` + +2. **Using a Full Image URL (src)** + ```js + var imageURL = imagekit.url({ + src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg", + transformation: [{ + "height": "300", + "width": "400" + }] + }); + ``` + *Result Example:* + ``` + https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400 + ``` -#### Examples of generating URLs +### Advanced URL Generation Examples -**1. Chained Transformations as a query parameter** -``` +#### Chained Transformations +Apply multiple transformations by passing an array: +```js var imageURL = imagekit.url({ path: "/default-image.jpg", - urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", transformation: [{ "height": "300", "width": "400" }, { "rotation": 90 }], - transformationPosition: "query" -}); -``` -``` -https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400%3Art-90 -``` - -**2. Sharpening and contrast transforms and a progressive JPG image** - -There are some transforms like [Sharpening](https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation) that can be added to the URL with or without any other value. To use such transforms without specifying a value, specify the value as "-" in the transformation object. Otherwise, specify the value that you want to be added to this transformation. - -``` -var imageURL = imagekit.url({ - src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg", - transformation: [{ - "format": "jpg", - "progressive": "true", - "effectSharpen": "-", - "effectContrast": "1" - }] + transformationPosition: "query" // Use query parameter for transformations }); ``` +*Result Example:* ``` -//Note that because `src` parameter was used, the transformation string gets added as a query parameter `tr` -https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=f-jpg%2Cpr-true%2Ce-sharpen%2Ce-contrast-1 +https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-300%2Cw-400%3Art-90 ``` -**3. Adding overlays** - -ImageKit.io enables you to apply overlays to [images](https://docs.imagekit.io/features/image-transformations/overlay-using-layers) and [videos](https://docs.imagekit.io/features/video-transformation/overlay) using the raw parameter with the concept of [layers](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#layers). The raw parameter facilitates incorporating transformations directly in the URL. A layer is a distinct type of transformation that allows you to define an asset to serve as an overlay, along with its positioning and additional transformations. - -**Text as overlays** - -You can add any text string over a base video or image using a text layer (l-text). - -For example: - +#### Overlays and Effects +*Text Overlay Example:* ```js var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", transformation: [{ "width": 400, - "height": 300 + "height": 300, "raw": "l-text,i-Imagekit,fs-50,l-end" }] }); ``` -**Sample Result URL** -``` -https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-text,i-Imagekit,fs-50,l-end/default-image.jpg -``` - -**Image as overlays** - -You can add an image over a base video or image using an image layer (l-image). - -For example: - +*Image Overlay Example:* ```js var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", transformation: [{ "width": 400, - "height": 300 + "height": 300, "raw": "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end" }] }); ``` -**Sample Result URL** -``` -https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end/default-image.jpg -``` - -**Solid color blocks as overlays** - -You can add solid color blocks over a base video or image using an image layer (l-image). - -For example: - -```js -var imageURL = imagekit.url({ - src: "https://ik.imagekit.io/your_imagekit_id/img/sample-video.mp4", - transformation: [{ - "width": 400, - "height": 300 - "raw": "l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end" - }] -}); -``` -**Sample Result URL** -``` -https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/img/sample-video.mp4 -``` - -**4. Arithmetic expressions in transformations** - -ImageKit allows use of [arithmetic expressions](https://docs.imagekit.io/features/arithmetic-expressions-in-transformations) in certain dimension and position-related parameters, making media transformations more flexible and dynamic. - -For example: - -```js -var imageURL = imagekit.url({ - src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", - transformation: [{ - "width": "iw_div_4", - "height": "ih_div_2", - "border": "cw_mul_0.05_yellow" - }] -}); -``` - -**Sample Result URL** -``` -https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-iw_div_4,h-ih_div_2,b-cw_mul_0.05_yellow -``` - -### Key Advanced Transformations - -#### Background Removal +#### AI and Advanced Transformations +*Background Removal:* ```js var imageURL = imagekit.url({ path: "/sample-image.jpg", @@ -297,12 +167,8 @@ var imageURL = imagekit.url({ aiRemoveBackground: true }] }); -console.log("Background Removed Image URL:", imageURL); -// Expected: https://ik.imagekit.io/your_imagekit_id/tr:e-bgremove/sample-image.jpg ``` - -#### Upscaling - +*Upscaling:* ```js var upscaledURL = imagekit.url({ path: "/sample-image.jpg", @@ -310,12 +176,8 @@ var upscaledURL = imagekit.url({ aiUpscale: true }] }); -console.log("Upscaled Image URL:", upscaledURL); -// Expected: https://ik.imagekit.io/your_imagekit_id/tr:e-upscale/sample-image.jpg ``` - -#### AI Drop Shadow - +*Drop Shadow:* ```js var dropShadowURL = imagekit.url({ path: "/sample-image.jpg", @@ -323,250 +185,156 @@ var dropShadowURL = imagekit.url({ aiDropShadow: "az-45" }] }); -console.log("Image URL with Drop Shadow:", dropShadowURL); -// Expected: https://ik.imagekit.io/your_imagekit_id/tr:e-dropshadow-az-45/sample-image.jpg ``` -### List of supported transformations - -See the complete list of transformations supported in ImageKit [here](https://docs.imagekit.io/features/image-transformations). The SDK gives a name to each transformation parameter e.g. `height` for `h` and `width` for `w` parameter. It makes your code more readable. If the property does not match any of the following supported options, it is added as it is. - -If you want to generate transformations in your application and add them to the URL as it is, use the `raw` parameter. - -| Supported Transformation Name | Translates to parameter | -| ----------------------------- | ------------------------------------------------------------- | -| width | w | -| height | h | -| aspectRatio | ar | -| quality | q | -| aiRemoveBackground | e-bgremove (ImageKit powered) | -| aiRemoveBackgroundExternal | e-removedotbg (Using third party) | -| aiUpscale | e-upscale | -| aiRetouch | e-retouch | -| aiVariation | e-genvar | -| aiDropShadow | e-dropshadow | -| aiChangeBackground | e-changebg | -| crop | c | -| cropMode | cm | -| x | x | -| y | y | -| xCenter | xc | -| yCenter | yc | -| focus | fo | -| format | f | -| radius | r | -| background | bg | -| border | b | -| rotation | rt | -| blur | bl | -| named | n | -| dpr | dpr | -| progressive | pr | -| lossless | lo | -| trim | t | -| metadata | md | -| colorProfile | cp | -| defaultImage | di | -| original | orig | -| videoCodec | vc | -| audioCodec | ac | -| grayscale | e-grayscale | -| contrastStretch | e-contrast | -| shadow | e-shadow | -| sharpen | e-sharpen | -| unsharpMask | e-usm | -| gradient | e-gradient | -| opacity | o | -| zoom | z | -| page | pg | -| startOffset | so | -| endOffset | eo | -| duration | du | -| streamingResolutions | sr | -| raw | The string provided in raw will be added in the URL as it is. | -| flip | fl | - -### File Upload - -The SDK provides a simple interface using the `.upload()` method to upload files to the ImageKit Media Library. - -The `upload()` method requires mandatory `file` and the `fileName` parameter. In addition, it accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). - -Also, before making an upload request, please ensure you have generated mandatory security parameters: `signature`, `token`, and `expire`. To generate these security parameters, refer to the [documentation here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#signature-generation-for-client-side-file-upload). Obtain the parameters using a secure method and pass them, along with the mandatory `file` and `fileName` parameters, to the `upload()` method. - -You can pass other parameters supported by the ImageKit upload API using the same parameter name as specified in the upload API documentation. For example, to specify tags for a file at the time of upload, use the `tags` parameter as specified in the [documentation here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). - - -#### Sample usage +#### Arithmetic Expressions in Transformations +```js +var imageURL = imagekit.url({ + src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", + transformation: [{ + "width": "iw_div_4", + "height": "ih_div_2", + "border": "cw_mul_0.05_yellow" + }] +}); +``` + +### Supported Transformations + +The SDK supports various transformations which are translated to URL parameters as follows: + +| Transformation Name | URL Parameter | +| -------------------------- | ------------------------------------------------------------- | +| width | w | +| height | h | +| aspectRatio | ar | +| quality | q | +| aiRemoveBackground | e-bgremove | +| aiRemoveBackgroundExternal | e-removedotbg | +| aiUpscale | e-upscale | +| aiRetouch | e-retouch | +| aiVariation | e-genvar | +| aiDropShadow | e-dropshadow | +| aiChangeBackground | e-changebg | +| crop | c | +| cropMode | cm | +| x | x | +| y | y | +| xCenter | xc | +| yCenter | yc | +| focus | fo | +| format | f | +| radius | r | +| background | bg | +| border | b | +| rotation | rt | +| blur | bl | +| named | n | +| dpr | dpr | +| progressive | pr | +| lossless | lo | +| trim | t | +| metadata | md | +| colorProfile | cp | +| defaultImage | di | +| original | orig | +| videoCodec | vc | +| audioCodec | ac | +| grayscale | e-grayscale | +| contrastStretch | e-contrast | +| shadow | e-shadow | +| sharpen | e-sharpen | +| unsharpMask | e-usm | +| gradient | e-gradient | +| opacity | o | +| zoom | z | +| page | pg | +| startOffset | so | +| endOffset | eo | +| duration | du | +| streamingResolutions | sr | +| raw | The string provided in raw will be added in the URL as it is. | +| flip | fl | + +### Handling Unsupported Transformations + +If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. + +## File Upload + +The SDK offers a simple interface via the `.upload()` method to upload files to the ImageKit Media Library. This method requires the following: +- **file** (mandatory) +- **fileName** (mandatory) +- Security parameters: **signature**, **token**, and **expire** + +Before invoking the upload, generate the necessary security parameters as per the [ImageKit Upload API documentation](https://imagekit.io/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload). + +### Basic Upload Example + +Below is an HTML form example that uses a callback for handling the upload response: + ```html -
+
- - + ``` -If the upload succeeds, `err` will be `null`, and the `result` will be the same as what is received from ImageKit's servers. -If the upload fails, `err` will be the same as what is received from ImageKit's servers, and the `result` will be null. - -## Tracking upload progress using custom XMLHttpRequest -You can use a custom XMLHttpRequest object as the following to bind `progress` or any other events for a customized implementation. +### Promise-based Upload Example +You can also use promises for a cleaner asynchronous approach: ```js -var fileSize = file.files[0].size; -var customXHR = new XMLHttpRequest(); -customXHR.upload.addEventListener('progress', function (e) { - if (e.loaded <= fileSize) { - var percent = Math.round(e.loaded / fileSize * 100); - console.log(`Uploaded ${percent}%`); - } - - if(e.loaded == e.total){ - console.log("Upload done"); - } -}); - imagekit.upload({ - xhr: customXHR, file: file.files[0], fileName: "abc1.jpg", - tags: ["tag1"], token: 'generated_token', signature: 'generated_signature', - expire: 'generated_expire', - extensions: [ - { - name: "aws-auto-tagging", - minConfidence: 80, - maxTags: 10 - } - ] + expire: 'generated_expire' }).then(result => { console.log(result); -}).then(error => { - console.log(error); -}) +}).catch(error => { + console.error(error); +}); ``` -## Access request-id, other response headers, and HTTP status code -You can access `$ResponseMetadata` on success or error object to access the HTTP status code and response headers. +## Demo Application -```js -// Success -var response = await imagekit.upload({ - file: file.files[0], - fileName: "abc1.jpg", - tags: ["tag1"], - token: 'generated_token', - signature: 'generated_signature', - expire: 'generated_expire', - extensions: [ - { - name: "aws-auto-tagging", - minConfidence: 80, - maxTags: 10 - } - ] -}); -console.log(response.$ResponseMetadata.statusCode); // 200 - -// { 'content-length': "300", 'content-type': 'application/json', 'x-request-id': 'ee560df4-d44f-455e-a48e-29dfda49aec5'} -console.log(response.$ResponseMetadata.headers); - -// Error -try { - await imagekit.upload({ - file: file.files[0], - fileName: "abc1.jpg", - tags: ["tag1"], - token: 'generated_token', - signature: 'generated_signature', - expire: 'generated_expire', - extensions: [ - { - name: "aws-auto-tagging", - minConfidence: 80, - maxTags: 10 - } - ] - }); -} catch (ex) { - console.log(response.$ResponseMetadata.statusCode); // 400 +For the fastest way to get started, check out the demo application in the [samples/sample-app](https://github.com/imagekit-developer/imagekit-javascript/tree/master/samples/sample-app) folder. - // {'content-type': 'application/json', 'x-request-id': 'ee560df4-d44f-455e-a48e-29dfda49aec5'} - console.log(response.$ResponseMetadata.headers); -} +To run the demo locally: +```bash +git clone https://github.com/imagekit-developer/imagekit-javascript.git +cd imagekit-javascript ``` +Then, create a `.env` file in the `samples/sample-app` directory based on `sample.env` and provide your `PRIVATE_KEY`, `PUBLIC_KEY`, and `URL_ENDPOINT` from your ImageKit dashboard. Finally, start the demo: +```bash +yarn startSampleApp +``` + +## Changelog + +For a detailed history of changes, please refer to [CHANGELOG.md](CHANGELOG.md). From b9e554d14e926c9d318163052e8326e17807b73c Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 09:51:29 +0530 Subject: [PATCH 18/23] change badge position --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index f465a47..f42aa71 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,14 @@ # ImageKit.io JavaScript SDK +![gzip size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=gzip&label=gzip) +![brotli size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=brotli&label=brotli) +![Node CI](https://github.com/imagekit-developer/imagekit-javascript/workflows/Node%20CI/badge.svg) +[![npm version](https://img.shields.io/npm/v/imagekit-javascript)](https://www.npmjs.com/package/imagekit-javascript) +[![codecov](https://codecov.io/gh/imagekit-developer/imagekit-javascript/branch/master/graph/badge.svg)](https://codecov.io/gh/imagekit-developer/imagekit-javascript) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ImagekitIo) + Lightweight JavaScript SDK for generating optimized URLs for images and videos, and for handling file uploads via ImageKit. ## Table of Contents @@ -18,14 +26,6 @@ Lightweight JavaScript SDK for generating optimized URLs for images and videos, - [Demo Application](#demo-application) - [Changelog](#changelog) -![gzip size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=gzip&label=gzip) -![brotli size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=brotli&label=brotli) -![Node CI](https://github.com/imagekit-developer/imagekit-javascript/workflows/Node%20CI/badge.svg) -[![npm version](https://img.shields.io/npm/v/imagekit-javascript)](https://www.npmjs.com/package/imagekit-javascript) -[![codecov](https://codecov.io/gh/imagekit-developer/imagekit-javascript/branch/master/graph/badge.svg)](https://codecov.io/gh/imagekit-developer/imagekit-javascript) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ImagekitIo) - ## Installation ### Using npm From 02751f37319fc40ac395bf9cf1ecb7bc4c3f6f45 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 10:00:49 +0530 Subject: [PATCH 19/23] docs: enhance README with detailed SDK initialization and transformation usage --- README.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f42aa71..7a36e6e 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ And include it in your HTML: ## Initialization -Initialize the SDK with your URL endpoint. For URL generation: +Initialize the SDK by specifying your URL endpoint. You can obtain your URL endpoint from [https://imagekit.io/dashboard/url-endpoints](https://imagekit.io/dashboard/url-endpoints) and your public API key from [https://imagekit.io/dashboard/developer/api-keys](https://imagekit.io/dashboard/developer/api-keys). For URL generation: ```js var imagekit = new ImageKit({ urlEndpoint: "https://ik.imagekit.io/your_imagekit_id" @@ -201,7 +201,11 @@ var imageURL = imagekit.url({ ### Supported Transformations -The SDK supports various transformations which are translated to URL parameters as follows: +The SDK gives a name to each transformation parameter e.g. height for h and width for w parameter. It makes your code more readable. If the property does not match any of the following supported options, it is added as it is. + +If you want to generate transformations in your application and add them to the URL as it is, use the raw parameter. + +Check ImageKit [transformation documentation](https://imagekit.io/docs/transformations) for more details. | Transformation Name | URL Parameter | | -------------------------- | ------------------------------------------------------------- | @@ -209,8 +213,8 @@ The SDK supports various transformations which are translated to URL parameters | height | h | | aspectRatio | ar | | quality | q | -| aiRemoveBackground | e-bgremove | -| aiRemoveBackgroundExternal | e-removedotbg | +| aiRemoveBackground | e-bgremove (ImageKit powered) | +| aiRemoveBackgroundExternal | e-removedotbg (Using third party) | | aiUpscale | e-upscale | | aiRetouch | e-retouch | | aiVariation | e-genvar | @@ -246,6 +250,7 @@ The SDK supports various transformations which are translated to URL parameters | sharpen | e-sharpen | | unsharpMask | e-usm | | gradient | e-gradient | +| flip | fl | | opacity | o | | zoom | z | | page | pg | @@ -254,12 +259,22 @@ The SDK supports various transformations which are translated to URL parameters | duration | du | | streamingResolutions | sr | | raw | The string provided in raw will be added in the URL as it is. | -| flip | fl | ### Handling Unsupported Transformations If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. +For example: +```js +var imageURL = imagekit.url({ + path: "/test_path.jpg", + transformation: [{ + "newparam": "cool" + }] +}); +// Generated URL: https://ik.imagekit.io/test_url_endpoint/tr:newparam-cool/test_path.jpg +``` + ## File Upload The SDK offers a simple interface via the `.upload()` method to upload files to the ImageKit Media Library. This method requires the following: From 010e9a04e2c3e25301b222f9bd2e5e53f4ab6dbf Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 10:08:15 +0530 Subject: [PATCH 20/23] docs: update README with quick demo references and remove outdated instructions --- README.md | 14 +++----------- test/url-generation.js | 2 ++ 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 7a36e6e..e45b80b 100644 --- a/README.md +++ b/README.md @@ -338,17 +338,9 @@ imagekit.upload({ ## Demo Application -For the fastest way to get started, check out the demo application in the [samples/sample-app](https://github.com/imagekit-developer/imagekit-javascript/tree/master/samples/sample-app) folder. - -To run the demo locally: -```bash -git clone https://github.com/imagekit-developer/imagekit-javascript.git -cd imagekit-javascript -``` -Then, create a `.env` file in the `samples/sample-app` directory based on `sample.env` and provide your `PRIVATE_KEY`, `PUBLIC_KEY`, and `URL_ENDPOINT` from your ImageKit dashboard. Finally, start the demo: -```bash -yarn startSampleApp -``` +For a quick demonstration of the SDK features, refer to our test examples: +- URL Generation examples can be found in [test/url-generation.js](./test/url-generation.js) +- File Upload examples can be found in [test/upload.js](./test/upload.js) ## Changelog diff --git a/test/url-generation.js b/test/url-generation.js index 126a85d..40c7e38 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -867,6 +867,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:yc-40/test_path1.jpg`); }); + // This is done just to test how SDK constructs URL, the actual transformation is not valid. it('Including deprecated properties', function () { const url = imagekit.url({ path: "/test_path.jpg", @@ -906,6 +907,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); }); + // This is done just to test how SDK constructs URL, the actual transformation is not valid it('should generate the correct URL when comprehensive transformations, including video and AI transformations, are applied', function () { const url = imagekit.url({ path: "/test_path.jpg", From 2ccfcf2187394fcd7356ffac5345e71dfa5c3750 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 10:08:22 +0530 Subject: [PATCH 21/23] docs: update README to rename 'Demo Application' section to 'Test Examples' --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e45b80b..2b06eea 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Lightweight JavaScript SDK for generating optimized URLs for images and videos, - [File Upload](#file-upload) - [Basic Upload Example](#basic-upload-example) - [Promise-based Upload Example](#promise-based-upload-example) -- [Demo Application](#demo-application) +- [Test Examples](#test-examples) - [Changelog](#changelog) ## Installation @@ -336,7 +336,7 @@ imagekit.upload({ }); ``` -## Demo Application +## Test Examples For a quick demonstration of the SDK features, refer to our test examples: - URL Generation examples can be found in [test/url-generation.js](./test/url-generation.js) From 8b3067d353199744364e5e36338d749d09ca45d4 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 10:33:54 +0530 Subject: [PATCH 22/23] feat: add static file serving and update image handling in Pug template --- samples/sample-app/server/server.js | 1 + samples/sample-app/views/index.pug | 18 ++++++++++++++++-- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/samples/sample-app/server/server.js b/samples/sample-app/server/server.js index 5942f56..6558660 100644 --- a/samples/sample-app/server/server.js +++ b/samples/sample-app/server/server.js @@ -8,6 +8,7 @@ const path = require('path'); const pugTemplatePath = path.join(__dirname, "../views/index.pug"); const app = express(); +app.use(express.static('static')) app.use(cors()); app.set('view engine', 'pug'); diff --git a/samples/sample-app/views/index.pug b/samples/sample-app/views/index.pug index 6f0b44f..91d398f 100644 --- a/samples/sample-app/views/index.pug +++ b/samples/sample-app/views/index.pug @@ -1,5 +1,6 @@ html body + img(id="my-image") h3 Imagekit Demo form(action='#' onSubmit='upload(event)') input(type='file' id='file1') @@ -18,7 +19,8 @@ html p img(src="") - script(type='text/javascript' src="https://unpkg.com/imagekit-javascript/dist/imagekit.min.js") + // Copy paste manually from dist + script(type='text/javascript' src="./imagekit.min.js") script. try { var imagekit = new ImageKit({ @@ -26,8 +28,20 @@ html urlEndpoint: "!{urlEndpoint}", }); + window.imagekit = imagekit; + var url = imagekit.url({ + src: "https://ik.imagekit.io/demo/default-image.jpg", + transformation: [{ + height: 100 + }] + }) + + var img = document.getElementById("my-image"); + console.log(url); + img.src = url; + function upload(e) { e.preventDefault(); @@ -119,4 +133,4 @@ html } } catch(ex) { console.log(ex); - } \ No newline at end of file + } From 7530fd3db0f41e013f84ab6290628dfff87d9d4e Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Wed, 19 Mar 2025 10:41:15 +0530 Subject: [PATCH 23/23] docs: update CHANGELOG with corrected links for overlay syntax and file upload parameters --- CHANGELOG.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aace157..03d7092 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,10 +5,10 @@ ### Breaking Changes - **Overlay Syntax Update** - In version 3.0.0, the old overlay syntax parameters for transformations (e.g., `oi`, `ot`, `obg`, and others as detailed [here](https://docs.imagekit.io/features/image-transformations/overlay)) have been removed. These parameters are deprecated and will now return errors when used in URLs. + In version 3.0.0, the old overlay syntax parameters for transformations (e.g., `oi`, `ot`, `obg`, and others as detailed [here](https://imagekit.io/docs/add-overlays-on-images)) have been removed. These parameters are deprecated and will now return errors when used in URLs. **Action Required:** - Migrate to the new layers syntax which supports overlay nesting, offers improved positional control, and allows more transformations at the layer level. For a quick start, refer to the [examples](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#examples). Use the `raw` transformation parameter to implement this migration. + Migrate to the new layers syntax which supports overlay nesting, offers improved positional control, and allows more transformations at the layer level. For a quick start, refer to the [examples](https://imagekit.io/docs/add-overlays-on-images). Use the `raw` transformation parameter to implement this migration. --- @@ -20,4 +20,4 @@ Previously, client-side file uploads required the SDK to be initialized with both the `publicKey` and `authenticationEndpoint` to fetch security parameters (`signature`, `token`, and `expire`). **Action Required:** - With version 2.0.0, you must now generate the security parameters (`signature`, `token`, and `expire`) yourself, eliminating the need for the `authenticationEndpoint`. When invoking the SDK's upload method, be sure to include these parameters along with other [upload options](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). For further details, consult the documentation [here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#signature-generation-for-client-side-file-upload). + With version 2.0.0, you must now generate the security parameters (`signature`, `token`, and `expire`) yourself, eliminating the need for the `authenticationEndpoint`. When invoking the SDK's upload method, be sure to include these parameters along with other [upload options](https://imagekit.io/docs/api-reference/upload-file/upload-file#Request). For further details, consult the documentation [here](https://imagekit.io/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload).