Skip to content

Add recipes and a page for people coming from other libraries - #1064

Open
kean wants to merge 1 commit into
mainfrom
docs/recipes-and-coming-from
Open

kean wants to merge 1 commit into
mainfrom
docs/recipes-and-coming-from

Conversation

@kean

@kean kean commented Oct 31, 2026

Copy link
Copy Markdown
Owner

Seven features that Kingfisher or SDWebImage have as options have a working answer in Nuke that was never written down. This adds a Recipes article for them, and a Coming From Another Library article that maps 53 Kingfisher, SDWebImage, and AsyncImage APIs to Nuke, with what has no counterpart. Docs only, no API.

The seven gaps are the recipe rows in the feature table of report 06: retry, fallback sources, Low Data Mode, per-request expiration, pinning, a decode memory limit, and HDR.

Proof

RecipesSnippets.swift from this PR, unchanged, ran in a scratch package on an iOS 27.0 simulator, against a stub DataLoading with scripted failures. 12 tests in 1 suite passed, twice. The only substitution was shorter retry delays.

Recipe Scenario What happened
Retry Timeout, 503, then success Image delivered, 3 attempts
Retry 404 No image, 1 attempt
Retry Cancel during the 1 s delay 1 attempt, none after
Retry Connection lost after partial data Fails, 1 attempt
Retry 6 images backing off 1 s, then a 7th 7th waited 0.90 s and 0.93 s, against 0.8 ms and 1.7 ms with no wrapper
Fallback Primary and first mirror return 404 Second mirror used, calls primary, mirror1, mirror2, cached under the primary
Low Data Mode, loader URLError with .constrained Calls hires, lowres, image delivered
Low Data Mode, view path Same isConstrained true, then the low-data URL. Nothing cached under the full-size URL
Lifetime ttl 0.2 s Short-lived gone after 0.4 s, the other still cached
Pinning One pinned, one regular Each in its own DataCache, pinned cache has sweeps off
Memory limit 60 MB maxPixelSize 3965
Memory limit 1,600 bytes, a 64×48 image 20×15, 1,200 bytes
HDR PQ and HLG HEIC, PQ AVIF, default pipeline 16 bpc, isHighDynamicRange true
HDR Same, through HDRDecoder 10 bpc, isHighDynamicRange true

The HDR run changed the recipe. The report expected a custom decoder for all HDR, but on iOS an image that's HDR in itself survives the default pipeline, because preparingForDisplay() keeps its depth. So the decoder is now only for gain maps.

Checks on the articles:

Check Result
Swift samples in the two articles, verbatim in Tests/DocumentationSnippets 18 of 18
make snippets, iOS Passes
Table rows 53 rows, 59 Nuke code spans, every one in a compiled snippet or llms-api.txt
Competitor names Each one found by grep in Kingfisher 8.14.0, SDWebImage 5.21.7, and SDWebImageSwiftUI 3.1.4 sources. The AsyncImage rows come from report 06, which read the iOS 27.1 SDK
Docbuild of Nuke No new issue, rateLimiter is the existing one
make llms, --check Clean, both articles in ARTICLE_ORDER

Not verified:

  • No real network and no real Low Data Mode: the constrained error is synthesized, as it was in the report.
  • The SwiftUI samples (RetryableImage, AvatarView, LowDataImage) are compiled only. The logic behind LowDataImage ran, without the view.
  • HDRDecoder has not seen a gain map. I couldn't encode one on the simulator (three attempts with kCGImageDestinationEncodeToISOGainmap), so the article calls it a starting point. HDR ran on a simulator, not on an HDR display.
  • allowedDynamicRange(.high) and preferredImageDynamicRange are from Apple's docs, and weren't watched on screen.
  • The disk-cache paragraph on Kingfisher and SDWebImage comes from report 06.

Fallback, Low Data Mode, per-request lifetime, pinning, memory limits, and HDR each have an answer that needs no new API, but none of them was written down. Retrying is left to the retry policy.
@kean
kean force-pushed the docs/recipes-and-coming-from branch from be9627c to 280310b Compare November 3, 2026 00:51
@kean kean added this to the 14.1.0 milestone Nov 8, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant