fix(image-service-reference): add API reference blocks + fix snippets

[ArmandPhilippot]

Description (required)

• Adds Type/Since block to follow the API references format.
• Fixes some code snippets that contained Typescript issues (because Astro uses Typescript, and we're showing Typescript files (import type))

You can check the details per heading below. I'm using an expandable content here because the list to track all the changes is quite long. 😅

Show details

• External Services:
  • Adds missing type import
  • Adds a new condition in the if statement because options.width can be undefined
• Local Services:
  • Moves AstroConfig["image"] as type parameter to avoid overriding imageConfig type in each hook
  • Adds missing params variable in parseURL (see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/services/service.ts#L374)
  • Fixes transform method
    • Adds async because this is always asynchronous (and Typescript complains without it)
    • Removes the return type to be consistent with the others (this is not required)
    • Renames one of the buffer to prevent conflicts
    • Adds await before mySuperLibraryThatEncodesImages to justify the asynchronousity and because I think most of the time this would be an async call.
• getConfiguredImageService & imageConfig:
  • No updates to the code snippet because it would require ~20 additional lines to prevent Typescript errors... since we're linking to a working example below, I think it's okay to keep it as is.
• Hooks:
  • Adds <Since /> for each hook. Most were added in 2.1.0 (see Implement RFC "A core story for images" astro#6344 and the related docs PR Add assets page #2779) and validateOptions was added in 2.1.4 (see Add validateOptions hook to Image Service API astro#6555)
  • getURL():
    • Fixes the return type (can be a Promise, see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/services/service.ts#L46)
    • Fixes the code snippet showing the ImageTransform type (no alt but fit and position, see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/types.ts#L82-L93)
  • parseUrl():
    • Fixes the return type (can be a Promise, see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/services/service.ts#L96-L99)
  • getSrcSet():
    • Fixes the return type (UnresolvedSrcSetValue not SrcSetValue, see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/services/service.ts#L53-L56)
    • Replaces SrcSetValue with UnresolvedSrcSetValue in the code snippet, they are not exactly the same type (see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/types.ts#L57-L65)
  • transform():
    • Fixes the return type (always a Promise and OutputFormat should be ImageOutputFormat, see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/services/service.ts#L104-L108)
  • validateOptions():
    • Fixes the return type (can be a Promise, see https://github.com/withastro/astro/blob/24b04c159ff2e5e1b15efcf8f3a77a131b5a9f92/packages/astro/src/assets/services/service.ts#L75-L78)
• Utilities:
  • Adds a missing export (emitImageMetadata) in astro/assets/utils
  • Adds a missing src property in generateTransformHash() example
  • Updates the types format (in other pages, we use => instead of : to represent the return type... so let's stay consistent?)

Related issues & labels (optional)

• Suggested label: code snippet update, consistency/formatting

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	af7c240
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68c2e5f78c64240008590ac2
😎 Deploy Preview	https://deploy-preview-12230--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/reference/image-service-reference.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[sarah11918]

Thank you for this very detailed PR @ArmandPhilippot and sorry it took me a while to get around to it! I only spotted one thing, but otherwise just looking at syntax (and trusting you to have done all the research 😅 ) , what I am in a position to review LGTM!

Is there someone else you think we should ping to pull in here for a more technical review of this?

[ArmandPhilippot]

No worries, anyone could have reviewed this one I think! I mean there is no new content, I only:

• fixed some TypeScript errors in code blocks, without any functional changes. Copying and pasting into a new Astro project should be enough to check for any errors!
• collected types/since information. I don't think I missed any links to help review this! 😆 What I forgot to mention is that I replaced LocalImageTransform with the actual type (as we did in transform) because LocalImageTransform is not exported/public. That's why this is a bit more verbose than the source code (ie. { src: string, [key: string]: any }).

So, thank you for taking the time for this one! 🙌🏽

I don't see anyone in particular we should ping to look into this. Maybe JSPark if he has the time, since he's both technical and sufficiently thorough to spot any mistake/oversight?
I'll ping him, unless you can think of someone else. I don't think we need someone from core to do that... unless one of them gets bored. 😅

[sarah11918]

OK @ArmandPhilippot I leave this completely to you! If you're happy with my having proofread it, and it LGTM, you are welcome to merge it as NWTWWHB! (I'm sure jspark will alert us of any errors when translating, and we can fix them then! 😂 )

So go ahead whenever you feel comfortable! 💜

[yanthomasdev]

LGTM!