fix: remove applyWhen in favor of explicit props overlap check with alwaysApply exception (#228)

# Description

<!-- Include a summary of the change made and also list the dependencies
that are required if any -->

Simplify applyWhen to just check for presence of props from the new
props key as discussed with @colbyfayock, add an alwaysApply key that
can be used for exceptions like SanitizePlugin that should always run
regardless of the presence of associated keys.

This is a rebased version of
#226.

## Issue Ticket Number

Fixes #<ISSUE_NUMBER>

<!-- Specify above which issue this fixes by referencing the issue
number (`#<ISSUE_NUMBER>`) or issue URL. -->
<!-- Example: Fixes
https://github.com/colbyfayock/cloudinary-util/issues/<ISSUE_NUMBER> -->

## Type of change

<!-- Please select all options that are applicable. -->

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] Fix or improve the documentation
- [ ] This change requires a documentation update

# Checklist

<!-- These must all be followed and checked. -->

- [ ] I have followed the contributing guidelines of this project as
mentioned in [CONTRIBUTING.md](/CONTRIBUTING.md)
- [ ] I have created an
[issue](https://github.com/colbyfayock/cloudinary-util/issues) ticket
for this PR
- [ ] I have checked to ensure there aren't other open [Pull
Requests](https://github.com/colbyfayock/cloudinary-util/pulls) for the
same update/change?
- [ ] I have performed a self-review of my own code
- [ ] I have run tests locally to ensure they all pass
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes needed to the documentation

Author: ssalbdivad

docs/src/components/SchemaTable/SchemaTable.tsx

@@ -59,7 +59,7 @@ export const SchemaTable = ({ schema, schemaKey }) => {
       };
 
       return property;
-    }
+    },
   );
 
   const sortedProperties = sortByKey(formattedProperties, "name");

packages/types/CHANGELOG.md

@@ -1,16 +1,14 @@
 # [@cloudinary-util/types-v2.0.0-beta.2](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/types-v2.0.0-beta.1...@cloudinary-util/types-v2.0.0-beta.2) (2024-10-22)
 
-
 ### Bug Fixes
 
-* Add TypeScript Types for Cloudinary Product Gallery Widget ([#218](https://github.com/cloudinary-community/cloudinary-util/issues/218)) ([05cd33e](https://github.com/cloudinary-community/cloudinary-util/commit/05cd33e3948d486ac87600b798e0006789e2d914)), closes [#199](https://github.com/cloudinary-community/cloudinary-util/issues/199)
+- Add TypeScript Types for Cloudinary Product Gallery Widget ([#218](https://github.com/cloudinary-community/cloudinary-util/issues/218)) ([05cd33e](https://github.com/cloudinary-community/cloudinary-util/commit/05cd33e3948d486ac87600b798e0006789e2d914)), closes [#199](https://github.com/cloudinary-community/cloudinary-util/issues/199)
 
 # [@cloudinary-util/types-v2.0.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/types-v1.5.11...@cloudinary-util/types-v2.0.0-beta.1) (2024-10-18)
 
-
 ### Features
 
-* migrate Zod to pure TS w/ JSDoc, improve type safety and simplify parsing ([#217](https://github.com/cloudinary-community/cloudinary-util/issues/217)) ([f605f26](https://github.com/cloudinary-community/cloudinary-util/commit/f605f26f9de1d111c26d65dd3b8955491b357481))
+- migrate Zod to pure TS w/ JSDoc, improve type safety and simplify parsing ([#217](https://github.com/cloudinary-community/cloudinary-util/issues/217)) ([f605f26](https://github.com/cloudinary-community/cloudinary-util/commit/f605f26f9de1d111c26d65dd3b8955491b357481))
 
 # [@cloudinary-util/types-v1.5.11](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/types-v1.5.10...@cloudinary-util/types-v1.5.11) (2024-10-07)
 

packages/url-loader/CHANGELOG.md

@@ -1,43 +1,39 @@
 # [@cloudinary-util/url-loader-v6.0.0-beta.5](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v6.0.0-beta.4...@cloudinary-util/url-loader-v6.0.0-beta.5) (2024-10-31)
 
-
 ### Bug Fixes
 
-* make plugins and cloudinaryPluginProps tree-shakeable ([#227](https://github.com/cloudinary-community/cloudinary-util/issues/227)) ([163cb2f](https://github.com/cloudinary-community/cloudinary-util/commit/163cb2fdd05c7a3444cfb22edade79891f25ffd3))
+- make plugins and cloudinaryPluginProps tree-shakeable ([#227](https://github.com/cloudinary-community/cloudinary-util/issues/227)) ([163cb2f](https://github.com/cloudinary-community/cloudinary-util/commit/163cb2fdd05c7a3444cfb22edade79891f25ffd3))
 
 # [@cloudinary-util/url-loader-v6.0.0-beta.4](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v6.0.0-beta.3...@cloudinary-util/url-loader-v6.0.0-beta.4) (2024-10-25)
 
-
 ### Bug Fixes
 
-* adding applyWhen to streaming profile to prevent abr plugin from running ([ef7e57a](https://github.com/cloudinary-community/cloudinary-util/commit/ef7e57adc03afb0e08ebf2bb0053d34c12054523))
-* adding string and number back to replaceBackground ([672009a](https://github.com/cloudinary-community/cloudinary-util/commit/672009afb7797c540c0a6fdc31115f0c245ed8b2))
+- adding applyWhen to streaming profile to prevent abr plugin from running ([ef7e57a](https://github.com/cloudinary-community/cloudinary-util/commit/ef7e57adc03afb0e08ebf2bb0053d34c12054523))
+- adding string and number back to replaceBackground ([672009a](https://github.com/cloudinary-community/cloudinary-util/commit/672009afb7797c540c0a6fdc31115f0c245ed8b2))
 
 # [@cloudinary-util/url-loader-v6.0.0-beta.3](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v6.0.0-beta.2...@cloudinary-util/url-loader-v6.0.0-beta.3) (2024-10-24)
 
-
 ### Features
 
-* enumerate plugin props ([#224](https://github.com/cloudinary-community/cloudinary-util/issues/224)) ([731d545](https://github.com/cloudinary-community/cloudinary-util/commit/731d54511741f9bb56fc6b1d6e978a8f21d88082))
+- enumerate plugin props ([#224](https://github.com/cloudinary-community/cloudinary-util/issues/224)) ([731d545](https://github.com/cloudinary-community/cloudinary-util/commit/731d54511741f9bb56fc6b1d6e978a8f21d88082))
 
 # [@cloudinary-util/url-loader-v6.0.0-beta.2](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v6.0.0-beta.1...@cloudinary-util/url-loader-v6.0.0-beta.2) (2024-10-22)
 
-
 ### Bug Fixes
 
-* Add enum for format parameter ([#220](https://github.com/cloudinary-community/cloudinary-util/issues/220)) ([0ecd331](https://github.com/cloudinary-community/cloudinary-util/commit/0ecd331e1bfe9244bedc82fc8d61e228bdc00d4c)), closes [#142](https://github.com/cloudinary-community/cloudinary-util/issues/142)
+- Add enum for format parameter ([#220](https://github.com/cloudinary-community/cloudinary-util/issues/220)) ([0ecd331](https://github.com/cloudinary-community/cloudinary-util/commit/0ecd331e1bfe9244bedc82fc8d61e228bdc00d4c)), closes [#142](https://github.com/cloudinary-community/cloudinary-util/issues/142)
 
 # [@cloudinary-util/url-loader-v6.0.0-beta.1](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.10.5...@cloudinary-util/url-loader-v6.0.0-beta.1) (2024-10-18)
 
 ### Features
 
-* migrate Zod to pure TS w/ JSDoc, improve type safety and simplify parsing ([#217](https://github.com/cloudinary-community/cloudinary-util/issues/217)) ([f605f26](https://github.com/cloudinary-community/cloudinary-util/commit/f605f26f9de1d111c26d65dd3b8955491b357481))
+- migrate Zod to pure TS w/ JSDoc, improve type safety and simplify parsing ([#217](https://github.com/cloudinary-community/cloudinary-util/issues/217)) ([f605f26](https://github.com/cloudinary-community/cloudinary-util/commit/f605f26f9de1d111c26d65dd3b8955491b357481))
 
 # [@cloudinary-util/url-loader-v5.10.6](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.10.5...@cloudinary-util/url-loader-v5.10.6) (2024-10-22)
 
 ### Bug Fixes
 
-* Add enum for format parameter ([#220](https://github.com/cloudinary-community/cloudinary-util/issues/220)) ([0ecd331](https://github.com/cloudinary-community/cloudinary-util/commit/0ecd331e1bfe9244bedc82fc8d61e228bdc00d4c)), closes [#142](https://github.com/cloudinary-community/cloudinary-util/issues/142)
+- Add enum for format parameter ([#220](https://github.com/cloudinary-community/cloudinary-util/issues/220)) ([0ecd331](https://github.com/cloudinary-community/cloudinary-util/commit/0ecd331e1bfe9244bedc82fc8d61e228bdc00d4c)), closes [#142](https://github.com/cloudinary-community/cloudinary-util/issues/142)
 
 # [@cloudinary-util/url-loader-v5.10.5](https://github.com/cloudinary-community/cloudinary-util/compare/@cloudinary-util/url-loader-v5.10.4...@cloudinary-util/url-loader-v5.10.5) (2024-10-07)
 

packages/url-loader/src/lib/cloudinary.ts

@@ -40,7 +40,7 @@ import type { PluginOptions, PluginResults } from "../types/plugins.js";
 import type { VideoOptions } from "../types/video.js";
 import type {
   CloudinaryKey,
-  OptionsFor,
+  CtxParam,
   TransformationPlugin,
 } from "./plugin.js";
 import { entriesOf, throwError } from "./utils.js";
@@ -135,7 +135,7 @@ export interface ConstructUrlProps<
    */
   config?: ConfigOptions;
   // prioritize inferring assetType so available options can be derived from it
-  options: { assetType?: assetType } & OptionsFor<assetType>;
+  options: { assetType?: assetType } & CtxParam<assetType>;
 }
 
 export type CldAsset = CloudinaryImage | CloudinaryVideo;
@@ -214,12 +214,10 @@ export function constructCloudinaryUrl<
   const pluginEffects: PluginOptions = {};
 
   transformationPlugins.forEach(
-    ({ name, apply, strict, applyWhen, supports }: TransformationPlugin) => {
-      const shouldApply =
-        applyWhen === undefined ||
-        (typeof applyWhen === "string"
-          ? options[applyWhen as never] !== undefined
-          : applyWhen(options));
+    ({ name, apply, strict, supports, props }: TransformationPlugin) => {
+      const shouldApply = Object.keys(props).some(
+        (key) => options[key as never] !== undefined
+      );
 
       if (!shouldApply) return;
 
@@ -235,6 +233,9 @@ export function constructCloudinaryUrl<
         return;
       }
 
+      // we're actually passing options for both opts and ctx, but
+      // the second param is typed to only include the options
+      // declared by the plugin's `inferOwnOptions`
       const results: PluginResults = apply(cldAsset, options);
 
       const pluginOptions = results?.options ?? {};

packages/url-loader/src/lib/plugin.ts

@@ -18,59 +18,89 @@ export type AlwaysApply = () => true;
 
 export interface PluginDefinition<
   assetType extends SupportedAssetType,
-  when extends ApplyWhen,
   name extends string,
   options extends object,
+  alwaysApply extends boolean,
 > {
   name: name;
   supports: assetType;
-  apply: PluginApplication<assetType, when>;
+  apply: PluginApplicationDefinition<assetType, options, alwaysApply>;
   inferOwnOptions: options;
   props: Record<keyof options, true>;
-  applyWhen?: when | undefined;
+  alwaysApply?: alwaysApply;
   strict?: boolean;
 }
 
 export interface TransformationPlugin<
   assetType extends SupportedAssetType = SupportedAssetType,
-  when extends ApplyWhen = ApplyWhen,
   name extends string = string,
-  options extends object = object,
+  opts extends object = object,
+  alwaysApply extends boolean = boolean,
 > {
   name: name;
   supports: assetType;
-  apply: PluginApplication<assetType, when>;
-  inferOwnOptions: options;
-  props: Record<keyof options, true>;
-  applyWhen?: when | undefined;
+  apply: PluginApplication<assetType, opts, alwaysApply>;
+  inferOwnOptions: opts;
+  props: Record<keyof opts, true>;
+  alwaysApply: alwaysApply;
   strict?: boolean;
 }
 
-export type OptionsFor<
-  assetType extends SupportedAssetTypeInput,
-  when extends ApplyWhen = AlwaysApply,
-  options = assetType extends "all"
+export type OwnOptionsParam<
+  opts extends object,
+  alwaysApply extends boolean,
+> = opts &
+  // if there's only one owned key, we know it must be present if
+  // apply is being invoked, so require it so we don't have to recheck
+  // in the implementation unless alwaysApply is true
+  ([alwaysApply] extends [true]
+    ? {}
+    : { [k in singleKeyOf<opts>]: Exclude<opts[k], undefined> });
+
+export type CtxParam<assetType extends SupportedAssetTypeInput> =
+  assetType extends "all"
     ? AllOptions
     : assetType extends "video" | "videos"
       ? VideoOptions
-      : ImageOptions,
-> = [when] extends [keyof options]
-  ? // if the plugin applies based on a single key being defined, we know it will be
-    // present in the options passed to apply
-    options & { [k in when]: {} }
-  : options;
+      : ImageOptions;
+
+// extract the key if there is exactly one, otherwise never
+type singleKeyOf<opts> = {
+  [k in keyof opts]: keyof opts extends k ? k : never;
+}[keyof opts];
+
+export type PluginApplicationDefinition<
+  assetType extends SupportedAssetType,
+  opts extends object,
+  alwaysApply extends boolean,
+> = (
+  cldAsset: CldAsset,
+  /** Options owned by this plugin */
+  opts: OwnOptionsParam<opts, alwaysApply>,
+  ctx: CtxParam<assetType>,
+) => PluginResults;
 
 export type PluginApplication<
   assetType extends SupportedAssetType,
-  when extends ApplyWhen = AlwaysApply,
-> = (cldAsset: CldAsset, options: OptionsFor<assetType, when>) => PluginResults;
+  opts extends object,
+  alwaysApply extends boolean,
+> = (
+  cldAsset: CldAsset,
+  // externally, we want the wider assetType options as well
+  opts: OwnOptionsParam<opts, alwaysApply> & CtxParam<assetType>,
+) => PluginResults;
 
 export const plugin = <
   asset extends SupportedAssetType,
-  when extends ApplyWhen,
   name extends string,
-  options extends object,
+  opts extends object,
+  alwaysApply extends boolean,
 >(
-  def: PluginDefinition<asset, when, name, options>
-): TransformationPlugin<asset, when, name, options> =>
-  ({ strict: false, ...def }) as never;
+  def: PluginDefinition<asset, name, opts, alwaysApply>,
+): TransformationPlugin<asset, name, opts, alwaysApply> =>
+  ({
+    strict: false,
+    alwaysApply: false,
+    ...def,
+    apply: (cldAsset, ctx) => def.apply(cldAsset, ctx as never, ctx as never),
+  }) satisfies TransformationPlugin as never;

packages/url-loader/src/lib/upload.ts

@@ -14,11 +14,11 @@ export function generateSignatureCallback({
 }: GenerateSignatureCallback) {
   return function generateSignature(
     callback: (signature: string | null, error?: unknown) => void,
-    paramsToSign: object
+    paramsToSign: object,
   ) {
     if (typeof signatureEndpoint === "undefined") {
       throw Error(
-        "Failed to generate signature: signatureEndpoint property undefined."
+        "Failed to generate signature: signatureEndpoint property undefined.",
       );
     }
 

packages/url-loader/src/lib/utils.ts

@@ -33,7 +33,7 @@ export const entriesOf: <o extends object>(o: o) => entryOf<o>[] =
  */
 export const throwError: (
   message: string,
-  ctor?: new (message: string) => Error
+  ctor?: new (message: string) => Error,
 ) => never = (message, ctor = Error) => {
   throw new ctor(message);
 };

packages/url-loader/src/lib/video-player.ts

@@ -38,7 +38,7 @@ export interface GetVideoPlayerOptionsLogo {
 
 export function getVideoPlayerOptions(
   options: GetVideoPlayerOptions,
-  config: CloudinaryAssetConfiguration
+  config: CloudinaryAssetConfiguration,
 ) {
   const {
     autoplay,
@@ -63,7 +63,7 @@ export function getVideoPlayerOptions(
 
   if (!cloudName) {
     throw new Error(
-      "A Cloudinary Cloud name is required, please make sure your environment variable is set and configured in your environment."
+      "A Cloudinary Cloud name is required, please make sure your environment variable is set and configured in your environment.",
     );
   }
 
@@ -85,7 +85,7 @@ export function getVideoPlayerOptions(
 
   if (!publicId) {
     throw new Error(
-      "Video Player requires a src, please make sure to configure your src as a public ID or Cloudinary URL."
+      "Video Player requires a src, please make sure to configure your src as a public ID or Cloudinary URL.",
     );
   }
 

packages/url-loader/src/plugins/abr.ts

@@ -14,14 +14,13 @@ export const AbrPlugin = plugin({
   name: "Abr",
   supports: "video",
   inferOwnOptions: {} as AbrPlugin.Options,
-  applyWhen: 'streamingProfile',
   props: {
     streamingProfile: true,
   },
   apply: (asset, opts) => {
-    if (typeof opts.streamingProfile === "string") {
-      asset.addTransformation(`sp_${opts.streamingProfile}`);
-    }
+    if (typeof opts.streamingProfile !== "string") return {};
+
+    asset.addTransformation(`sp_${opts.streamingProfile}`);
 
     return {};
   },

packages/url-loader/src/plugins/cropping.ts

@@ -25,6 +25,14 @@ export declare namespace CroppingPlugin {
     crop?: CropMode | NestedOptions | ReadonlyArray<NestedOptions>;
     gravity?: Gravity;
     zoom?: Zoom;
+    /**
+     * @description Height of the given asset.
+     */
+    height?: string | number;
+    /**
+     * @description Width of the given asset.
+     */
+    width?: string | number;
   }
 
   export interface NestedOptions {
@@ -49,6 +57,8 @@ export const CroppingPlugin = plugin({
     crop: true,
     gravity: true,
     zoom: true,
+    height: true,
+    width: true,
   },
   // crop is applied even if the crop key is undefined
   apply: (asset, opts) => {