[feature] (provider/directus) Add Sharp transforms to modifiers, add support for `key`ed transforms

[kheiner]

The current implementation of Directus Transforms is not typed appropriately, and not checked against any available functions. Directus uses Sharp on the backend, but not all functions work. There is also no implementation of the keyed transform option available in Directus.

The proposed enhancement should consider:

• (feature): Support for Keyed Transforms using the key string, stripping all other transforms supported by Nuxt/Image
  • (test): Ensure that key if present is not paired with other modifiers.
  • (playground): Identify Directus instance that has pre-configured keys in the public space for better explanation to developers.
    • Option 1: https://sandbox.directus.io using key=800w or key=1200w. (customized transforms)
    • Option 2: using key=system-[small/medium/large]-[cover/contain]
• (feature): Transforms should have typing for Image Operations, Color Manipulation, and Channel Manipulation as supported by Sharp.
• (fix): The current transforms are typed as string[] which is not valid. Transforms should fallback to a tuple of type [string, ...any[]][] to prevent errors with using transforms not typed explicitly. (Future proofing for new transforms added to Sharp & supported by Directus.)
• (docs): Update Docs ->
  • Provide a note that key requires setup in Directus. (Not actually true, see comment below)
  • Explicitly name Sharp Transforms that are supported (and link to details in Sharp Library)

I don't think this will break anything for existing users.

[kheiner]

The Directus SDK is typed as:

export type AssetsQuery =
    | { key: string }
    | {
            key?: never;
            fit?: 'cover' | 'contain' | 'inside' | 'outside';
            width?: number;
            height?: number;
            quality?: number;
            withoutEnlargement?: boolean;
            format?: 'auto' | 'jpg' | 'png' | 'webp' | 'tiff';
            focal_point_x?: number;
            focal_point_y?: number;
            transforms?: [string, ...any[]][];
      };

The Sharp Transform Types in Directus are:

export const TransformationMethods /*: readonly (keyof Sharp)[]*/ = [
    // Output options
    // https://sharp.pixelplumbing.com/api-output
    'toFormat',
    'jpeg',
    'png',
    'tiff',
    'webp',
    'avif',

    // Resizing
    // https://sharp.pixelplumbing.com/api-resize
    'resize',
    'extend',
    'extract',
    'trim',

    // Image operations
    // https://sharp.pixelplumbing.com/api-operation
    'rotate',
    'flip',
    'flop',
    'sharpen',
    'median',
    'blur',
    'flatten',
    'gamma',
    'negate',
    'normalise',
    'normalize',
    'clahe',
    'convolve',
    'threshold',
    'linear',
    'recomb',
    'modulate',

    // Color manipulation
    // https://sharp.pixelplumbing.com/api-colour
    'tint',
    'greyscale',
    'grayscale',
    'toColorspace',
    'toColourspace',

    // Channel manipulation
    // https://sharp.pixelplumbing.com/api-channel
    'removeAlpha',
    'ensureAlpha',
    'extractChannel',
    'bandbool',
] as const;

[kheiner]

I found a live sandbox for Directus that is configured with keys that can be used to test for Keyed Transformations. The currently configured key transformations are 800w and 1200w.
There are default keyed transforms since Directus 11.17.2

export const SYSTEM_ASSET_ALLOW_LIST: TransformationParams[] = [
    {
        key: 'system-small-cover',
        format: 'auto',
        transforms: [['resize', { width: 64, height: 64, fit: 'cover' }]],
    },
    {
        key: 'system-small-contain',
        format: 'auto',
        transforms: [['resize', { width: 64, fit: 'contain' }]],
    },
    {
        key: 'system-medium-cover',
        format: 'auto',
        transforms: [['resize', { width: 300, height: 300, fit: 'cover' }]],
    },
    {
        key: 'system-medium-contain',
        format: 'auto',
        transforms: [['resize', { width: 300, fit: 'contain' }]],
    },
    {
        key: 'system-large-cover',
        format: 'auto',
        transforms: [['resize', { width: 800, height: 800, fit: 'cover' }]],
    },
    {
        key: 'system-large-contain',
        format: 'auto',
        transforms: [['resize', { width: 800, fit: 'contain' }]],
    },
];

Note that the configuration of the Directus instance dictates the maximum amount of Transforms that can be processed with a default of 5.

[kheiner]

Trying to implement this and encountering an issue that I want to document: The tuple of transforms get duplicated as a result of Defu (Defu is performing as expected, arrays are concatenated)

image/src/runtime/image.ts

Line 93 in e3ce805

const _options = defu(options, preset, defaults as Partial<ImageOptions>)

The previous implementation creates a new set of transforms as a workaround to the duplication.

image/src/runtime/providers/directus.ts

Lines 18 to 20 in e3ce805

	const transforms = modifiers.transforms && Array.isArray(modifiers.transforms) && modifiers.transforms.length > 0
	? JSON.stringify(Array.from(new Set(modifiers.transforms.map(obj => JSON.stringify(obj)))).map(value => JSON.parse(value)))
	: undefined

The order of the transforms matter, see example:

Pipeline A Rotate → Extract → Flip	Pipeline B Extract → Rotate → Flip
[['rotate',45],['extract',{left:50,top:50,width:200,height:200}],['flip']]	[['extract',{left:50,top:50,width:200,height:200}],['rotate',45],['flip']]

Meaning that if you're loading transforms in your nuxt.config you will get unexpected transform behavior. Given the rarity of the issue and the possible workarounds by using the keyed transforms within Directus to chain appropriately in those rare cases, I'm planning on making a note of the issue in the docs, but not invest the time into modifying the Defu implementation to fix it right.