feat: enumerate plugin props (#224)

# Description

Based on a conversation with @colbyfayock, this adds back enumerated
props for each plugin.

They're collected via two top-level exports, `cloudinaryPluginProps` and
`cloudinaryPluginKeys`, so we can expose which props are handled by
cloudinary without all the implementation details of each plugin.

Author: ssalbdivad

packages/url-loader/src/index.ts

@@ -1,6 +1,8 @@
 // URL Construction & Plugins
 
 export {
+  cloudinaryPluginKeys,
+  cloudinaryPluginProps,
   constructCloudinaryUrl,
   transformationPlugins,
   type AnalyticsOptions,

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

@@ -38,14 +38,25 @@ import type {
 import type { ImageOptions } from "../types/image.js";
 import type { PluginOptions, PluginResults } from "../types/plugins.js";
 import type { VideoOptions } from "../types/video.js";
-import type { OptionsFor, TransformationPlugin } from "./plugin.js";
+import type {
+  CloudinaryKey,
+  OptionsFor,
+  TransformationPlugin,
+} from "./plugin.js";
 import { entriesOf, throwError } from "./utils.js";
 
+export const cloudinaryPluginProps = {} as Record<CloudinaryKey, true>;
+
 const validatePlugins = <const plugins extends readonly TransformationPlugin[]>(
   ...plugins: plugins extends validatePlugins<plugins>
     ? plugins
     : validatePlugins<plugins>
-) => plugins;
+) => {
+  plugins.forEach((plugin) => {
+    Object.assign(cloudinaryPluginProps, plugin.props);
+  });
+  return plugins;
+};
 
 export const transformationPlugins = validatePlugins(
   // Some features *must* be the first transformation applied
@@ -87,6 +98,11 @@ export const transformationPlugins = validatePlugins(
   ZoompanPlugin
 );
 
+// important this comes after `validatePlugins` is called so we've collected the props
+export const cloudinaryPluginKeys: readonly CloudinaryKey[] = Object.keys(
+  cloudinaryPluginProps
+) as never;
+
 export interface AnalyticsOptions extends IAnalyticsOptions {}
 
 export interface ConfigOptions extends CloudinaryAssetConfiguration {}

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

@@ -4,7 +4,9 @@ import type { PluginResults } from "../types/plugins.js";
 import type { VideoOptions } from "../types/video.js";
 import type { CldAsset } from "./cloudinary.js";
 
-interface AllOptions extends AssetOptions, ImageOptions, VideoOptions {}
+export interface AllOptions extends AssetOptions, ImageOptions, VideoOptions {}
+
+export type CloudinaryKey = keyof AllOptions & {};
 
 export type SupportedAssetType = "image" | "video" | "all";
 
@@ -24,6 +26,7 @@ export interface PluginDefinition<
   supports: assetType;
   apply: PluginApplication<assetType, when>;
   inferOwnOptions: options;
+  props: Record<keyof options, true>;
   applyWhen?: when | undefined;
   strict?: boolean;
 }
@@ -38,6 +41,7 @@ export interface TransformationPlugin<
   supports: assetType;
   apply: PluginApplication<assetType, when>;
   inferOwnOptions: options;
+  props: Record<keyof options, true>;
   applyWhen?: when | undefined;
   strict?: boolean;
 }

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

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

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

@@ -44,6 +44,12 @@ export const CroppingPlugin = plugin({
   name: "Cropping",
   supports: "all",
   inferOwnOptions: {} as CroppingPlugin.Options,
+  props: {
+    aspectRatio: true,
+    crop: true,
+    gravity: true,
+    zoom: true,
+  },
   // crop is applied even if the crop key is undefined
   apply: (asset, opts) => {
     let crops: Array<CroppingPlugin.NestedOptions> = [];

packages/url-loader/src/plugins/default-image.ts

@@ -15,6 +15,7 @@ export const DefaultImagePlugin = plugin({
   name: "DefaultImage",
   supports: "image",
   inferOwnOptions: {} as DefaultImagePlugin.Options,
+  props: { defaultImage: true },
   apply: (asset, opts) => {
     const { defaultImage } = opts;
 

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

@@ -21,6 +21,61 @@ export const EffectsPlugin = plugin({
   name: "Effects",
   supports: "all",
   inferOwnOptions: {} as EffectsPlugin.Options,
+  props: {
+    angle: true,
+    art: true,
+    autoBrightness: true,
+    autoColor: true,
+    autoContrast: true,
+    assistColorblind: true,
+    background: true,
+    blackwhite: true,
+    blur: true,
+    blurFaces: true,
+    blurRegion: true,
+    border: true,
+    brightness: true,
+    brightnessHSB: true,
+    cartoonify: true,
+    color: true,
+    colorize: true,
+    contrast: true,
+    displace: true,
+    distort: true,
+    fillLight: true,
+    gamma: true,
+    gradientFade: true,
+    grayscale: true,
+    hue: true,
+    improve: true,
+    loop: true,
+    multiply: true,
+    negate: true,
+    noise: true,
+    oilPaint: true,
+    opacity: true,
+    outline: true,
+    pixelate: true,
+    pixelateFaces: true,
+    pixelateRegion: true,
+    radius: true,
+    redeye: true,
+    replaceColor: true,
+    saturation: true,
+    screen: true,
+    sepia: true,
+    shadow: true,
+    sharpen: true,
+    shear: true,
+    simulateColorblind: true,
+    tint: true,
+    trim: true,
+    unsharpMask: true,
+    vectorize: true,
+    vibrance: true,
+    vignette: true,
+    effects: true,
+  },
   apply: (cldAsset, options) => {
     // Handle any top-level effect props
 

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

@@ -14,6 +14,9 @@ export const EnhancePlugin = plugin({
   name: "Enhance",
   supports: "image",
   inferOwnOptions: {} as EnhancePlugin.Options,
+  props: {
+    enhance: true,
+  },
   apply: (cldAsset, options) => {
     if (options.enhance) {
       cldAsset.addTransformation("e_enhance");

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

@@ -28,6 +28,9 @@ export const ExtractPlugin = plugin({
   supports: "image",
   applyWhen: "extract",
   inferOwnOptions: {} as ExtractPlugin.Options,
+  props: {
+    extract: true,
+  },
   apply: (cldAsset, { extract }) => {
     const properties = [];
 

packages/url-loader/src/plugins/fill-background.ts

@@ -28,6 +28,9 @@ export const FillBackgroundPlugin = plugin({
   name: "FillBackground",
   supports: "image",
   inferOwnOptions: {} as FillBackgroundPlugin.Options,
+  props: {
+    fillBackground: true,
+  },
   apply: (cldAsset, options) => {
     const { fillBackground } = options;