[v6] Update content loader reference

[ArmandPhilippot]

Description (required)

Content Loader API:

• Small fixes:
  • indentation again in a code snippet, not easy to fix in GitHub reviews 🙄
  • a link was redirecting to the homepage instead of a heading on the same page
  • typo
  • replace content with htmlContent in the Article interface
  • add parenthesis to headings using a function name
• Updates a sentence in "Distributing your loader" because we were only talking about live loaders but the same applies to build time loaders
• Updates "Creating live loader error types" example: the constructor takes an optional code but we never assign it while we're using it later
• Updates live loaders code snippets around error in try...catch block: error in the catch statement is inferred as unknown, so Typescript complains when using error.message. One solution is to use error: any if we want to avoid Typescript errors. But HiDeoo suggested a better approach!
• Updates LiveLoader type parameters (see below for the why... my explanation is a bit long 😁 )
• Adds missing types/link in types
• Improves (try at least) the differentiation between the LiveLoader object and type (based on a previous T&D).
• Removes renderMarkdown() mention in LiveDataEntry.rendered: this is only available for build-time loaders. This is still in the RFC Unresolved questions.

astro:content:

• Fixes getLiveCollection()/getLiveEntry() code snippets
• Adds docs for LiveDataCollectionResult and LiveDataEntryResult (note: this is imported from astro, not astro:content)

TODO: check astro:content new descriptions/code snippets, this is more of a draft at the moment.

Regarding LiveLoader filters/type parameters:

In short: if you use Typescript and have filters, you must provide the types, don't forget them.

Now, the detailed explanation:

I built Astro v6 (instead of using the experimental flag, to be safe) and I used it in a minimal project to check our code snippets. If we want to show valid examples without Typescript errors (well, except for things not implemented like fetchFromCMS), the LiveLoader type is a bit more complex to handle than what we describe.

When I copy/paste the "Example live loader" code snippet:

• the destructured filter in loadCollection is inferred as undefined, which is fine: no Typescript errors (unless the user has a typed function instead of fetchFromCMS).
• the destructured filter in loadEntry is inferred as never, which means Typescript complains about filter.id (Property 'id' does not exist on type 'never'.ts(2339)).

Which is a bit odd because of:

export interface LoadEntryContext<TEntryFilter = never> {
    filter: TEntryFilter extends never ? {
        id: string;
    } : TEntryFilter;

It should fallback to {id: string} but it doesn't seem to work. Typescript still think it's never.

So, from my understanding, this means:

• In a JS file, without any type annotations, this is not an issue.
• In a TS file, LiveLoader<Article> means the loader doesn't accept any filters and so, we need to use:
  • LiveLoader<Article, Record<string, any>> if only loadEntry() accepts filters.
  • LiveLoader<Article, never, Record<string, any>> if only loadCollection() accepts filters.
  • LiveLoader<Article, Record<string, any>, Record<string, any>> if both accepts filters.

I also updated the "Error handling in live loaders" code snippets because:

• We can't use undefined as type parameter (Type 'undefined' does not satisfy the constraint 'Record<string, any>'.ts(2344)).
• If we use never instead, we can't show filter (ie. the loader doesn't accept any filters)
• If we don't want to provide a type, we'll need Record<string, any> or a custom one (e.g. imported alongside MyData).

Since the goal is to show error handling, I think we can use never here and we don't need to show filter.

I think systematically displaying the filters types each time filter is used will help people understand that they are required.

Related issues & labels (optional)

• To merge in: [v6] New content collections guide includes live collections #12604
• Suggested label: v6

[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/content-loader-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-content.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]

Thanks Armand! I had one note so far around the loader object, and wonder whether @HiDeoo has comments for the updated examples in lines 300-600ish

[HiDeoo]

Left a few comments.

I'm personally not bother at all with the generic types position. If the type of an object accept multiple generic types, I definitely want to know about them immediately, even before knowing what the properties of the object are considering such types could impact the properties.

[sarah11918]

Just tiny nits/fixes below, but holy cow is this good!! I get excited just reading it. 😆

(Approving, but leaving the feedback to address as you see fit and then merge when you're happy!)

[sarah11918]

This new section is so good! And so exciting! I am so happy about this!

[ArmandPhilippot]

Glad you like it! It bothered me a bit because this is not astro:content, but yeah I think this makes sense. And, this is better than leaving things undocumented!

We might need similar sections in other modules where we don't show everything importable from astro but only the things relevant to the current API! I guess that leaves me with something to do later. 😆

[ArmandPhilippot]

I pushed one more commit I was about to push when I saw your approval: two read more links for entries/entry in astro:content. I don't think this change your approval, and the wording can always be updated in your PR so I guess I can mark this PR ready for review 😆 and merge it! Thank you both for your reviews ❤️