docs: harmonize cleanup function naming

Author: johannschopplich

docs/api/auto-sizes.md

@@ -10,19 +10,19 @@ To lazy load images, refer to the [`lazyLoad`](/api/lazy-load) method.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `updateOnResize` | `boolean` | `false` | Install a debounced `ResizeObserver` that re-resolves `data-sizes="auto"` on viewport changes. The returned disposer disconnects it. |
+| `updateOnResize` | `boolean` | `false` | Install a debounced `ResizeObserver` that re-resolves `data-sizes="auto"` on viewport changes. The returned cleanup function disconnects it. |
 
 ## Return Value
 
-`autoSizes` returns a disposer. When called with `updateOnResize: false` (or no options), the disposer is a no-op. With `updateOnResize: true`, calling it disconnects every `ResizeObserver` created by that call:
+`autoSizes` returns a cleanup function. When called with `updateOnResize: false` (or no options), the cleanup is a no-op. With `updateOnResize: true`, calling it disconnects every `ResizeObserver` created by that call:
 
 ```ts
 import { autoSizes } from 'unlazy'
 
-const dispose = autoSizes('img[data-sizes="auto"]', { updateOnResize: true })
+const cleanup = autoSizes('img[data-sizes="auto"]', { updateOnResize: true })
 
 // Later, when cleaning up
-dispose()
+cleanup()
 ```
 
 ## Type Declarations
@@ -47,9 +47,9 @@ import { autoSizes } from 'unlazy'
 autoSizes()
 
 // Or: resolve and keep tracking on resize
-const dispose = autoSizes(undefined, { updateOnResize: true })
+const cleanup = autoSizes(undefined, { updateOnResize: true })
 ```
 
 ::: tip
-For most users, calling [`lazyLoad`](/api/lazy-load) with `updateSizesOnResize: true` is the simpler path – it delegates to `autoSizes` internally and bundles the disposer into the same cleanup callback.
+For most users, calling [`lazyLoad`](/api/lazy-load) with `updateSizesOnResize: true` is the simpler path – it delegates to `autoSizes` internally and bundles the cleanup into the same callback.
 :::

docs/api/lazy-load.md

@@ -30,7 +30,7 @@ Options can be passed to the function to customize its behavior:
 | `hash` | `boolean \| string` | `true` | Whether to use a hash for generating a blurry placeholder. Can be `true` (auto-detect from `data-blurhash`/`data-thumbhash`), `false` (disabled), or a hash string. |
 | `hashType` | `'blurhash' \| 'thumbhash'` | `'blurhash'` | The type of hash to use. Ignored when `hash` is boolean (auto-detected from data attributes). |
 | `placeholderSize` | `number` | `32` | The size of the longer edge for BlurHash decoding. Ignored for ThumbHash. |
-| `updateSizesOnResize` | `boolean` | `false` | Re-resolve `data-sizes="auto"` on viewport resize – applies to both `<img>` and `<source>` siblings inside a `<picture>`. Internally delegates to [`autoSizes`](/api/auto-sizes); the returned cleanup disconnects every observer. |
+| `updateSizesOnResize` | `boolean` | `false` | Re-resolve `data-sizes="auto"` on viewport resize – applies to both `<img>` and `<source>` siblings inside a `<picture>`. Internally delegates to [`autoSizes`](/api/auto-sizes); the returned cleanup function disconnects every observer. |
 | `onImageLoad` | `(image: HTMLImageElement) => void` | - | Callback invoked when an image loads successfully. |
 | `onImageError` | `(image: HTMLImageElement, error: Event) => void` | - | Callback invoked when an image fails to load. |
 

docs/api/trigger-load.md

@@ -10,18 +10,18 @@ The function performs the following operations:
 4. Swaps `data-src` and `data-srcset` to their standard counterparts.
 5. Invokes the optional `onImageLoad` callback when loading completes, or `onImageError` if loading fails. On failure, a synthetic `error` event also fires on the visible `<img>`.
 
-`triggerLoad` returns a disposer that detaches its listeners and, for standalone images, aborts the in-flight network fetch. Calling it after the load has already completed is a no-op.
+`triggerLoad` returns a cleanup function that detaches its listeners and, for standalone images, aborts the in-flight network fetch. Calling it after the load has already completed is a no-op.
 
 ::: tip
 `triggerLoad` is one-shot – it does not install any `ResizeObserver`. For ongoing source-size tracking on responsive `<picture>` layouts, pair it with [`autoSizes`](/api/auto-sizes) and `{ updateOnResize: true }`:
 
 ```ts
-const disposeSizes = autoSizes(image, { updateOnResize: true })
-const disposeLoad = triggerLoad(image)
+const cleanupSizes = autoSizes(image, { updateOnResize: true })
+const cleanupLoad = triggerLoad(image)
 
 // Later
-disposeSizes()
-disposeLoad()
+cleanupSizes()
+cleanupLoad()
 ```
 :::
 
@@ -37,11 +37,11 @@ import { triggerLoad } from 'unlazy'
 const image = document.querySelector<HTMLImageElement>('.priority-image')!
 
 // Load immediately with callbacks
-const dispose = triggerLoad(image, {
+const cleanup = triggerLoad(image, {
   onImageLoad: img => console.log('Loaded:', img.src),
   onImageError: (img, error) => console.error('Failed to load:', img, error),
 })
 
 // Later, cancel the load if it hasn't completed yet
-dispose()
+cleanup()
 ```

docs/guide/migration.md

@@ -17,28 +17,28 @@ The deprecated `loadImage` alias is gone. Replace every call site with `triggerL
 
 ### `triggerLoad` Signature
 
-`triggerLoad` now takes an options object instead of positional callbacks, and returns a disposer that detaches listeners and (for standalone images) aborts the in-flight network fetch:
+`triggerLoad` now takes an options object instead of positional callbacks, and returns a cleanup function that detaches listeners and (for standalone images) aborts the in-flight network fetch:
 
 ```diff
 - triggerLoad(image, onLoad, onError)
-+ const dispose = triggerLoad(image, { onImageLoad: onLoad, onImageError: onError })
-+ // Optional: dispose() to cancel before the load completes
++ const cleanup = triggerLoad(image, { onImageLoad: onLoad, onImageError: onError })
++ // Optional: cleanup() to cancel before the load completes
 ```
 
 ### `autoSizes` Owns Ongoing Size Tracking
 
-`triggerLoad` is one-shot again – it no longer accepts `updateSizesOnResize`. Ongoing re-resolution of `data-sizes="auto"` lives on [`autoSizes`](/api/auto-sizes), which now accepts `{ updateOnResize: true }` and returns a disposer:
+`triggerLoad` is one-shot again – it no longer accepts `updateSizesOnResize`. Ongoing re-resolution of `data-sizes="auto"` lives on [`autoSizes`](/api/auto-sizes), which now accepts `{ updateOnResize: true }` and returns a cleanup function:
 
 ```diff
 - triggerLoad(image, { updateSizesOnResize: true })
-+ const disposeSizes = autoSizes(image, { updateOnResize: true })
-+ const disposeLoad = triggerLoad(image)
-+ // Later: disposeSizes(); disposeLoad()
++ const cleanupSizes = autoSizes(image, { updateOnResize: true })
++ const cleanupLoad = triggerLoad(image)
++ // Later: cleanupSizes(); cleanupLoad()
 ```
 
 For the common case, [`lazyLoad`](/api/lazy-load) keeps `updateSizesOnResize` and delegates to `autoSizes` internally – no caller change needed.
 
-`autoSizes` itself now always returns a function. With no options, the returned disposer is a no-op; with `updateOnResize: true`, it disconnects every `ResizeObserver` created by the call. Passing an `<img>` inside a `<picture>` walks to every `<source data-sizes="auto">` sibling in the same call, replacing the previous need to invoke `autoSizes` separately on each source.
+`autoSizes` itself now always returns a function. With no options, the returned cleanup is a no-op; with `updateOnResize: true`, it disconnects every `ResizeObserver` created by the call. Passing an `<img>` inside a `<picture>` walks to every `<source data-sizes="auto">` sibling in the same call, replacing the previous need to invoke `autoSizes` separately on each source.
 
 ### `isLazyLoadingSupported` Removal
 

docs/guide/usage.md

@@ -104,16 +104,16 @@ import { autoSizes } from 'unlazy'
 autoSizes()
 ```
 
-For responsive layouts where the display width changes – fluid containers, breakpoint switches, orientation changes – pass `{ updateOnResize: true }` to keep `sizes` synced. `autoSizes` returns a disposer – call it when you no longer need the observer:
+For responsive layouts where the display width changes – fluid containers, breakpoint switches, orientation changes – pass `{ updateOnResize: true }` to keep `sizes` synced. `autoSizes` returns a cleanup function – call it when you no longer need the observer:
 
 ```ts
-const dispose = autoSizes(undefined, { updateOnResize: true })
+const cleanup = autoSizes(undefined, { updateOnResize: true })
 
 // Later, when unmounting
-dispose()
+cleanup()
 ```
 
-The same behavior is available on [`lazyLoad`](/api/lazy-load) via `updateSizesOnResize: true`, which delegates to `autoSizes` internally and bundles the disposer into the same cleanup callback.
+The same behavior is available on [`lazyLoad`](/api/lazy-load) via `updateSizesOnResize: true`, which delegates to `autoSizes` internally and bundles the cleanup into the same callback.
 
 ## Custom Selectors
 

packages/core/src/lazyLoad.ts

@@ -29,7 +29,7 @@ export function lazyLoad<T extends HTMLImageElement>(
     onImageError,
   }: UnLazyLoadOptions = {},
 ): () => void {
-  const cleanupHandlers = new Set<() => void>()
+  const cleanups = new Set<() => void>()
 
   // @ts-expect-error: Build-time variable
   if (typeof __UNLAZY_LOGGING__ === 'undefined' || __UNLAZY_LOGGING__)
@@ -50,7 +50,7 @@ export function lazyLoad<T extends HTMLImageElement>(
 
     // Resolve `data-sizes="auto"` for the img and any picture-source siblings,
     // optionally installing a single `ResizeObserver` to retrack on resize
-    cleanupHandlers.add(autoSizes(image, { updateOnResize: updateSizesOnResize }))
+    cleanups.add(autoSizes(image, { updateOnResize: updateSizesOnResize }))
 
     // Generate the blurry placeholder from a Blurhash or ThumbHash string if applicable
     if (
@@ -85,12 +85,12 @@ export function lazyLoad<T extends HTMLImageElement>(
       if (onImageLoad) {
         const loadHandler = () => onImageLoad(image)
         image.addEventListener('load', loadHandler, { once: true })
-        cleanupHandlers.add(() => image.removeEventListener('load', loadHandler))
+        cleanups.add(() => image.removeEventListener('load', loadHandler))
       }
       if (onImageError) {
         const errorHandler = (event: Event) => onImageError(image, event)
         image.addEventListener('error', errorHandler, { once: true })
-        cleanupHandlers.add(() => image.removeEventListener('error', errorHandler))
+        cleanups.add(() => image.removeEventListener('error', errorHandler))
       }
       swapPictureSources(image)
       swapDataAttribute(image, 'srcset')
@@ -107,24 +107,24 @@ export function lazyLoad<T extends HTMLImageElement>(
 
     // Load the image immediately if is already in the viewport
     if (image.complete && image.naturalWidth > 0) {
-      cleanupHandlers.add(triggerLoad(image, { onImageLoad, onImageError }))
+      cleanups.add(triggerLoad(image, { onImageLoad, onImageError }))
       continue
     }
 
     // Otherwise, load the image when it enters the viewport
     const loadHandler = () => {
-      cleanupHandlers.add(triggerLoad(image, { onImageLoad, onImageError }))
+      cleanups.add(triggerLoad(image, { onImageLoad, onImageError }))
     }
     image.addEventListener('load', loadHandler, { once: true })
 
-    cleanupHandlers.add(
+    cleanups.add(
       () => image.removeEventListener('load', loadHandler),
     )
   }
 
   return () => {
-    for (const fn of cleanupHandlers) fn()
-    cleanupHandlers.clear()
+    for (const fn of cleanups) fn()
+    cleanups.clear()
   }
 }
 
@@ -135,7 +135,7 @@ export function lazyLoad<T extends HTMLImageElement>(
  * resolves them too. With `{ updateOnResize: true }`, a debounced
  * `ResizeObserver` retracks the rendered width on viewport changes.
  *
- * @returns A disposer that disconnects every observer created by this call.
+ * @returns A cleanup function that disconnects every observer created by this call.
  * Calling it on a one-shot invocation is a no-op.
  */
 export function autoSizes<T extends HTMLImageElement | HTMLSourceElement>(
@@ -152,22 +152,22 @@ export function autoSizes<T extends HTMLImageElement | HTMLSourceElement>(
   selectorsOrElements: string | T | NodeListOf<T> | T[] = 'img[data-sizes="auto"], source[data-sizes="auto"]',
   { updateOnResize = false }: AutoSizesOptions = {},
 ): () => void {
-  const disposers: (() => void)[] = []
+  const cleanups: (() => void)[] = []
 
   for (const element of toElementArray<T>(selectorsOrElements))
-    disposers.push(observeAutoSizes(element, updateOnResize))
+    cleanups.push(observeAutoSizes(element, updateOnResize))
 
   return () => {
-    for (const fn of disposers) fn()
-    disposers.length = 0
+    for (const fn of cleanups) fn()
+    cleanups.length = 0
   }
 }
 
 // #region triggerLoad
 /**
  * Triggers the loading of a lazy image by swapping `data-src`/`data-srcset` to `src`/`srcset`.
  *
- * @returns A disposer that detaches listeners and, for standalone images, aborts any
+ * @returns A cleanup function that detaches listeners and, for standalone images, aborts any
  * in-flight network fetch by clearing the temporary image's `src`. Calling it after the
  * load completes is a no-op.
  *
@@ -194,34 +194,34 @@ export function triggerLoad(
   image: HTMLImageElement,
   { onImageLoad, onImageError }: TriggerLoadOptions = {},
 ): () => void {
-  const disposers: (() => void)[] = []
-  const dispose = () => {
-    for (const d of disposers) d()
-    disposers.length = 0
+  const cleanups: (() => void)[] = []
+  const cleanup = () => {
+    for (const fn of cleanups) fn()
+    cleanups.length = 0
   }
 
   if (isDescendantOfPicture(image)) {
     if (onImageLoad) {
       const handler = () => onImageLoad(image)
       image.addEventListener('load', handler, { once: true })
-      disposers.push(() => image.removeEventListener('load', handler))
+      cleanups.push(() => image.removeEventListener('load', handler))
     }
     if (onImageError) {
       const handler = (event: Event) => onImageError(image, event)
       image.addEventListener('error', handler, { once: true })
-      disposers.push(() => image.removeEventListener('error', handler))
+      cleanups.push(() => image.removeEventListener('error', handler))
     }
 
     swapPictureSources(image)
     swapDataAttribute(image, 'srcset')
     swapDataAttribute(image, 'src')
-    return dispose
+    return cleanup
   }
 
   const { srcset: dataSrcset, src: dataSrc, sizes: dataSizes } = image.dataset
 
   if (!dataSrcset && !dataSrc)
-    return dispose
+    return cleanup
 
   const temporaryImage = new Image()
 
@@ -240,7 +240,7 @@ export function triggerLoad(
   temporaryImage.addEventListener('load', loadHandler, { once: true })
   temporaryImage.addEventListener('error', errorHandler, { once: true })
 
-  disposers.push(() => {
+  cleanups.push(() => {
     temporaryImage.removeEventListener('load', loadHandler)
     temporaryImage.removeEventListener('error', errorHandler)
     // Empty `src` aborts the pending fetch per HTML "update the image data".
@@ -262,7 +262,7 @@ export function triggerLoad(
   if (dataSrc)
     temporaryImage.src = dataSrc
 
-  return dispose
+  return cleanup
 }
 
 // #region createPlaceholderFromHash

packages/core/src/types.ts

@@ -77,7 +77,7 @@ export interface AutoSizesOptions {
   /**
    * Whether `data-sizes="auto"` should retrack the rendered width on viewport
    * resize. Sets up a debounced `ResizeObserver` per call; the returned
-   * disposer disconnects it.
+   * cleanup function disconnects it.
    *
    * @default false
    */

packages/core/test/triggerLoad.browser.test.ts

@@ -148,57 +148,57 @@ describe('triggerLoad (browser)', () => {
     expect(nativeError).toHaveBeenCalled()
   })
 
-  it('disposer cancels an in-flight standalone preload', async () => {
+  it('cleanup cancels an in-flight standalone preload', async () => {
     const img = document.createElement('img')
     img.dataset.src = TINY_PNG
     document.body.appendChild(img)
 
     const onImageLoad = vi.fn()
-    const dispose = triggerLoad(img, { onImageLoad })
-    dispose()
+    const cleanup = triggerLoad(img, { onImageLoad })
+    cleanup()
 
     await new Promise(resolve => setTimeout(resolve, 200))
 
     expect(onImageLoad).not.toHaveBeenCalled()
   })
 
-  it('disposer cancels an in-flight picture-wrapped load', async () => {
+  it('cleanup cancels an in-flight picture-wrapped load', async () => {
     const picture = document.createElement('picture')
     const img = document.createElement('img')
     img.dataset.src = TINY_PNG
     picture.appendChild(img)
     document.body.appendChild(picture)
 
     const onImageLoad = vi.fn()
-    const dispose = triggerLoad(img, { onImageLoad })
-    dispose()
+    const cleanup = triggerLoad(img, { onImageLoad })
+    cleanup()
 
     await new Promise(resolve => setTimeout(resolve, 200))
 
     expect(onImageLoad).not.toHaveBeenCalled()
   })
 
-  it('tolerates calling the disposer twice', () => {
+  it('tolerates calling cleanup twice', () => {
     const img = document.createElement('img')
     img.dataset.src = TINY_PNG
     document.body.appendChild(img)
 
-    const dispose = triggerLoad(img, { onImageLoad: vi.fn() })
-    dispose()
-    expect(() => dispose()).not.toThrow()
+    const cleanup = triggerLoad(img, { onImageLoad: vi.fn() })
+    cleanup()
+    expect(() => cleanup()).not.toThrow()
   })
 
-  it('disposer is a no-op when called after the load completes', async () => {
+  it('cleanup is a no-op when called after the load completes', async () => {
     const img = document.createElement('img')
     img.dataset.src = TINY_PNG
     document.body.appendChild(img)
 
     const onImageLoad = vi.fn()
-    let dispose!: () => void
+    let cleanup!: () => void
 
     await new Promise<void>((resolve, reject) => {
       const timer = setTimeout(() => reject(new Error('load did not complete')), 2000)
-      dispose = triggerLoad(img, {
+      cleanup = triggerLoad(img, {
         onImageLoad: (image) => {
           onImageLoad(image)
           clearTimeout(timer)
@@ -207,7 +207,7 @@ describe('triggerLoad (browser)', () => {
       })
     })
 
-    expect(() => dispose()).not.toThrow()
+    expect(() => cleanup()).not.toThrow()
     expect(onImageLoad).toHaveBeenCalledTimes(1)
   })