feat: pixel density descriptors (#624)

.changeset/friendly-frogs-chew.md

@@ -0,0 +1,5 @@
+---
+'imagetools-core': minor
+---
+
+feat: add `basePixels` directive for outputting pixel density descriptors

.changeset/nervous-grapes-notice.md

@@ -0,0 +1,5 @@
+---
+'imagetools-core': major
+---
+
+breaking: improve types

.changeset/tricky-readers-flash.md

@@ -0,0 +1,6 @@
+---
+'imagetools-core': major
+'vite-imagetools': major
+---
+
+breaking: simplify picture, image, and srcset output formats and remove source output format. This is both simpler and will enable pixel density descriptors

packages/core/src/__tests__/output-formats.test.ts

@@ -1,4 +1,4 @@
-import { urlFormat, metadataFormat, imgFormat, pictureFormat, sourceFormat, srcsetFormat } from '../output-formats'
+import { urlFormat, metadataFormat, imgFormat, pictureFormat, srcsetFormat } from '../output-formats'
 import { describe, test, expect } from 'vitest'
 
 describe('url format', () => {
@@ -65,10 +65,7 @@ describe('image format', () => {
  ])
 
  expect(output).toStrictEqual({
- srcset: [
- { src: '/foo-100.webp', w: 100 },
- { src: '/foo-50.webp', w: 50 }
- ],
+ srcset: '/foo-100.webp 100w, /foo-50.webp 50w',
  src: '/foo-100.webp',
  w: 100,
  h: 50
@@ -86,8 +83,8 @@ describe('picture format', () => {
 
  expect(output).toStrictEqual({
  sources: {
- avif: [{ src: '/foo.avif', w: 100 }],
- webp: [{ src: '/foo.webp', w: 100 }]
+ avif: '/foo.avif 100w',
+ webp: '/foo.webp 100w'
  },
  img: {
  src: '/foo.jpg',
@@ -109,18 +106,9 @@ describe('picture format', () => {
 
  expect(output).toStrictEqual({
  sources: {
- avif: [
- { src: '/foo-100.avif', w: 100 },
- { src: '/foo-50.avif', w: 50 }
- ],
- webp: [
- { src: '/foo-100.webp', w: 100 },
- { src: '/foo-50.webp', w: 50 }
- ],
- jpeg: [
- { src: '/foo-100.jpg', w: 100 },
- { src: '/foo-50.jpg', w: 50 }
- ]
+ avif: '/foo-100.avif 100w, /foo-50.avif 50w',
+ webp: '/foo-100.webp 100w, /foo-50.webp 50w',
+ jpeg: '/foo-100.jpg 100w, /foo-50.jpg 50w'
  },
  img: {
  src: '/foo-100.jpg',
@@ -131,7 +119,7 @@ describe('picture format', () => {
  })
 })
 
-describe('source format', () => {
+describe('srcset format', () => {
  test('single image', () => {
  const output = srcsetFormat()([{ src: '/foo.jpg', width: 500 }])
 
@@ -147,23 +135,3 @@ describe('source format', () => {
  expect(output).toEqual('/foo.jpg 500w, /bar.jpg 300w')
  })
 })
-
-describe('srcset format', () => {
- test('single image', () => {
- const output = sourceFormat()([{ src: '/foo.jpg', width: 500 }])
-
- expect(output).toEqual([{ src: '/foo.jpg', w: 500 }])
- })
-
- test('multiple images', () => {
- const output = sourceFormat()([
- { src: '/foo.jpg', width: 500 },
- { src: '/bar.jpg', width: 300 }
- ])
-
- expect(output).toEqual([
- { src: '/foo.jpg', w: 500 },
- { src: '/bar.jpg', w: 300 }
- ])
- })
-})

packages/core/src/lib/apply-transforms.ts

@@ -7,7 +7,7 @@ export async function applyTransforms(
  image: Sharp,
  removeMetadata = true
 ): Promise<TransformResult> {
- image[METADATA] = await image.metadata()
+ image[METADATA] = { ...(await image.metadata()) }
 
  if (removeMetadata) {
  // delete the private metadata

packages/core/src/lib/metadata.ts

@@ -1,10 +1,11 @@
 import { Sharp } from 'sharp'
+import { ImageMetadata } from '../types'
 
 export const METADATA = Symbol('image metadata')
 
 declare module 'sharp' {
  interface Sharp {
- [METADATA]: Record<string, unknown>
+ [METADATA]: ImageMetadata
  }
 }
 

packages/core/src/output-formats.ts

@@ -1,34 +1,35 @@
-import type { ImageConfig, Img, OutputFormat, Picture, Source } from './types.js'
+import type { ImageMetadata, Img, OutputFormat, Picture } from './types.js'
 
 export const urlFormat: OutputFormat = () => (metadatas) => {
  const urls: string[] = metadatas.map((metadata) => metadata.src as string)
 
  return urls.length == 1 ? urls[0] : urls
 }
 
-export const srcsetFormat: OutputFormat = () => (metadatas) => {
- const sources = metadatas.map((meta) => `${meta.src} ${meta.width}w`)
-
- return sources.join(', ')
-}
+export const srcsetFormat: OutputFormat = () => metadatasToSourceset
 
 export const metadataFormat: OutputFormat = (whitelist) => (metadatas) => {
- if (whitelist) {
- metadatas = metadatas.map((cfg) => Object.fromEntries(Object.entries(cfg).filter(([k]) => whitelist.includes(k))))
- }
+ const result = whitelist
+ ? metadatas.map((cfg) => Object.fromEntries(Object.entries(cfg).filter(([k]) => whitelist.includes(k))))
+  : metadatas
 
- metadatas.forEach((m) => delete m.image)
+ result.forEach((m) => delete m.image)
 
- return metadatas.length === 1 ? metadatas[0] : metadatas
+ return result.length === 1 ? result[0] : result
 }
 
-const metadataToSource = (m: ImageConfig) => ({ src: m.src, w: m.width }) as Source
+const metadatasToSourceset = (metadatas: ImageMetadata[]) =>
+ metadatas
+ .map((meta) => {
+ const density = meta.pixelDensityDescriptor
+ return density ? `${meta.src} ${density}` : `${meta.src} ${meta.width}w`
+ })
+ .join(', ')
 
 /** normalizes the format for use in mime-type */
-const format = (m: ImageConfig) => (m.format as string).replace('jpg', 'jpeg')
-
-export const sourceFormat: OutputFormat = () => (metadatas) => {
- return metadatas.map((m) => metadataToSource(m))
+const getFormat = (m: ImageMetadata) => {
+ if (!m.format) throw new Error(`Could not determine image format`)
+ return m.format.replace('jpg', 'jpeg')
 }
 
 export const imgFormat: OutputFormat = () => (metadatas) => {
@@ -49,25 +50,22 @@ export const imgFormat: OutputFormat = () => (metadatas) => {
  }
 
  if (metadatas.length >= 2) {
- result.srcset = []
- for (let i = 0; i < metadatas.length; i++) {
- result.srcset.push(metadataToSource(metadatas[i]))
- }
+ result.srcset = metadatasToSourceset(metadatas)
  }
 
  return result
 }
 
 /** fallback format should be specified last */
 export const pictureFormat: OutputFormat = () => (metadatas) => {
- const fallbackFormat = [...new Set(metadatas.map((m) => format(m)))].pop()
+ const fallbackFormat = [...new Set(metadatas.map((m) => getFormat(m)))].pop()
 
  let largestFallback
  let largestFallbackSize = 0
  let fallbackFormatCount = 0
  for (let i = 0; i < metadatas.length; i++) {
  const m = metadatas[i]
- if (format(m) === fallbackFormat) {
+ if (getFormat(m) === fallbackFormat) {
  fallbackFormatCount++
  if ((m.width as number) > largestFallbackSize) {
  largestFallback = m
@@ -76,22 +74,27 @@ export const pictureFormat: OutputFormat = () => (metadatas) => {
  }
  }
 
- const sources: Record<string, Source[]> = {}
+ const sourceMetadatas: Record<string, ImageMetadata[]> = {}
  for (let i = 0; i < metadatas.length; i++) {
  const m = metadatas[i]
- const f = format(m)
+ const f = getFormat(m)
  // we don't need to create a source tag for the fallback format if there is
  // only a single image in that format
  if (f === fallbackFormat && fallbackFormatCount < 2) {
  continue
  }
- if (sources[f]) {
- sources[f].push(metadataToSource(m))
+ if (sourceMetadatas[f]) {
+ sourceMetadatas[f].push(m)
  } else {
- sources[f] = [metadataToSource(m)]
+ sourceMetadatas[f] = [m]
  }
  }
 
+ const sources: Record<string, string> = {}
+ for (const [key, value] of Object.entries(sourceMetadatas)) {
+ sources[key] = metadatasToSourceset(value)
+ }
+
  const result: Picture = {
  sources,
  // the fallback should be the largest image in the fallback format
@@ -108,7 +111,6 @@ export const pictureFormat: OutputFormat = () => (metadatas) => {
 
 export const builtinOutputFormats = {
  url: urlFormat,
- source: sourceFormat,
  srcset: srcsetFormat,
  img: imgFormat,
  picture: pictureFormat,

packages/core/src/transforms/__tests__/background.spec.ts

@@ -2,11 +2,13 @@ import sharp, { Sharp } from 'sharp'
 import { join } from 'path'
 import { getBackground } from '../background'
 import { describe, beforeEach, test, expect } from 'vitest'
+import { METADATA } from '../../lib/metadata'
 
 describe('background', () => {
  let img: Sharp
  beforeEach(() => {
  img = sharp(join(__dirname, '../../__tests__/__fixtures__/pexels-allec-gomes-5195763.png'))
+ img[METADATA] = { chromaSubsampling: '' }
  })
 
  test('keyword: "background"', () => {

packages/core/src/transforms/__tests__/fit.spec.ts

@@ -2,11 +2,13 @@ import { getFit, FitValue } from '../fit'
 import { join } from 'path'
 import sharp, { Sharp } from 'sharp'
 import { describe, beforeEach, test, expect } from 'vitest'
+import { METADATA } from '../../lib/metadata'
 
 describe('fit', () => {
  let img: Sharp
  beforeEach(() => {
  img = sharp(join(__dirname, '../../__tests__/__fixtures__/pexels-allec-gomes-5195763.png'))
+ img[METADATA] = { chromaSubsampling: '' }
  })
 
  test('keyword "fit"', () => {
@@ -45,7 +47,6 @@ describe('fit', () => {
 
  describe('arguments', () => {
  test('invalid', () => {
- //@ts-expect-error invalid args
  const res = getFit({ fit: 'invalid' }, img)
 
  expect(res).toBeUndefined()

packages/core/src/transforms/__tests__/format.spec.ts

@@ -45,7 +45,7 @@ describe('format', () => {
  })
 
  test('valid', () => {
- const formats: FormatValue[] = ['avif', 'jpg', 'jpeg', 'png', 'heif', 'heic', 'webp', 'tiff']
+ const formats: FormatValue[] = ['avif', 'jpg', 'jpeg', 'png', 'heif', 'webp', 'tiff']
 
  for (const f of formats) {
  const res = format({ format: f }, dirCtx)
@@ -97,12 +97,6 @@ describe('format', () => {
  expect(metadata).toHaveProperty('format', 'heif')
  })
 
- test('heic', async () => {
- const { metadata } = await applyTransforms([format({ format: 'heic' }, dirCtx)!], img)
-
- expect(metadata).toHaveProperty('format', 'heic')
- })
-
  test('tiff', async () => {
  const { image } = await applyTransforms([format({ format: 'tiff' }, dirCtx)!], img)
 

packages/core/src/transforms/__tests__/kernel.spec.ts

@@ -2,11 +2,13 @@ import { getKernel, KernelValue } from '../kernel'
 import { join } from 'path'
 import sharp, { Sharp } from 'sharp'
 import { describe, beforeEach, expect, test } from 'vitest'
+import { METADATA } from '../../lib/metadata'
 
 describe('kernel', () => {
  let img: Sharp
  beforeEach(() => {
  img = sharp(join(__dirname, '../../__tests__/__fixtures__/pexels-allec-gomes-5195763.png'))
+ img[METADATA] = { chromaSubsampling: '' }
  })
 
  test('keyword "kernel"', () => {

packages/core/src/transforms/__tests__/lossless.spec.ts

@@ -2,11 +2,13 @@ import sharp, { Sharp } from 'sharp'
 import { getLossless } from '../lossless'
 import { join } from 'path'
 import { describe, beforeEach, expect, test } from 'vitest'
+import { METADATA } from '../../lib/metadata'
 
 describe('lossless', () => {
  let img: Sharp
  beforeEach(() => {
  img = sharp(join(__dirname, '../../__tests__/__fixtures__/pexels-allec-gomes-5195763.png'))
+ img[METADATA] = { chromaSubsampling: '' }
  })
 
  test('keyword "lossless"', () => {

packages/core/src/transforms/__tests__/position.spec.ts

@@ -2,11 +2,13 @@ import { getPosition, PositionValue } from '../position'
 import sharp, { Sharp } from 'sharp'
 import { join } from 'path'
 import { describe, beforeEach, expect, test } from 'vitest'
+import { METADATA } from '../../lib/metadata'
 
 describe('position', () => {
  let img: Sharp
  beforeEach(() => {
  img = sharp(join(__dirname, '../../__tests__/__fixtures__/pexels-allec-gomes-5195763.png'))
+ img[METADATA] = { chromaSubsampling: '' }
  })
 
  test('keyword "position"', () => {

packages/core/src/transforms/__tests__/progressive.spec.ts

@@ -2,11 +2,13 @@ import sharp, { Sharp } from 'sharp'
 import { getProgressive } from '../progressive'
 import { join } from 'path'
 import { describe, beforeEach, expect, test } from 'vitest'
+import { METADATA } from '../../lib/metadata'
 
 describe('progressive', () => {
  let img: Sharp
  beforeEach(() => {
  img = sharp(join(__dirname, '../../__tests__/__fixtures__/pexels-allec-gomes-5195763.png'))
+ img[METADATA] = { chromaSubsampling: '' }
  })
 
  test('keyword "progressive"', () => {

packages/core/src/transforms/__tests__/quality.spec.ts

@@ -2,11 +2,13 @@ import { getQuality } from '../quality'
 import sharp, { Sharp } from 'sharp'
 import { join } from 'path'
 import { describe, beforeEach, expect, test, it } from 'vitest'
+import { METADATA } from '../../lib/metadata'
 
 describe('quality', () => {
  let img: Sharp
  beforeEach(() => {
  img = sharp(join(__dirname, '../../__tests__/__fixtures__/pexels-allec-gomes-5195763.png'))
+ img[METADATA] = { chromaSubsampling: '' }
  })
 
  test('keyword "quality"', () => {

packages/core/src/transforms/background.ts

@@ -1,5 +1,5 @@
 import { TransformOption } from '../types.js'
-import { setMetadata } from '../lib/metadata.js'
+import { METADATA } from '../lib/metadata.js'
 
 export interface BackgroundOptions {
  background: string
@@ -8,7 +8,7 @@ export interface BackgroundOptions {
 export const getBackground: TransformOption<BackgroundOptions, string> = ({ background }, image) => {
  if (typeof background !== 'string' || !background.length) return
 
- setMetadata(image, 'background', background)
+ image[METADATA].backgroundDirective = background
 
  return background
 }