fix: improve TS intellisense with getImage() options

[ArmandPhilippot]

Context: A few months ago we got a docs issue (withastro/docs#13301) regarding UnresolvedImageTransform. But, actually, there is no docs issue: layout and priority are already accepted. The confusion comes from the fact that TypeScript/Intellisense doesn't suggest them unlike the other predefined options.

Changes

• Reuses ImageSharedProps to build the ImageTransform type: now, we can declare only the props that use a different type (e.g. width) instead of duplicating them
• Adds an Undefinable utility type to keep the same behavior as before (with exactOptionalPropertyTypes removing | undefined would be breaking).
• Adds | undefined to inferSize for consistency with the other optional props.
• TS now complains when widths and densities are passed together to getImage(), matching the <Image /> behavior. As we seem to agree that <Image /> and getImage() should have the same signature (Incorrect snippet and outdated imports in astro:assets docs docs#14281 (comment)), I don't think this is an issue?
• getImage() props now have JSDoc (the caveat is that the examples use <Image /> not getImage())

You can download this Stackblitz repro locally to see that layout and priority are currently not suggested:

Before	After

Testing

Green CI.
I also tested manually with pnpm link: this fixes the issue and this doesn't break Astro.CustomImageProps.

Docs

Changeset added.
Docs PR: withastro/docs#14511 (even though this doesn't need this PR to be merged)

Closes withastro/docs#13301

[changeset-bot]

🦋 Changeset detected

Latest commit: 90f1453

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed]

Merging this PR will not alter performance

✅ 21 untouched benchmarks

---

_{Comparing armand/fix-intellisense-getimage (36cf5e6) with main (504333c)}

[kdelay]

Undefinable<> maps every key to optional, so a required key a user adds to Astro.CustomImageProps gets silently relaxed. Repro with interface CustomImageProps { token: string } and const t: ImageTransform = { src: 'a.png' }: TS2322 on main, no error here.

Re-intersecting it outside the mapped type keeps the fix: Simplify<Undefinable<...> & {...}> & Astro.CustomImageProps -> token required again, layout still typed, quality: undefined still fine under exactOptionalPropertyTypes.

Separately, widths + densities now errors where it compiled on main.

[ArmandPhilippot]

@kdelay Thanks! Indeed, I forgot to check Astro.CustomImageProps with a required prop. This is now fixed.

re: widths and densities... right, this is a behavior change but if <Image /> and getImage() should behave the same, I believe this was an oversight on main and this is the expected behavior (see docs for densities or widths). I added a changeset for this.

[Princesseuh]

Those types were so hard to get working in the first place I remember, ha. Glad to see them better