Improve errors for invalid IDs in content collections

[louisescher]

Changes

This PR improves the error messages for IDs in content collections.

IDs in content collections have always been required to be strings, however the error message when passing (for example) a number would look like this:

[ContentLoaderInvalidDataError] todos entry is missing an ID.
Entry missing ID:
{
  "userId": 1,
  "title": "delectus aut autem",
  "completed": false
}

This would even be the case if the original entry looked like this:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

This PR changes these error messages so that they throw a new and more verbose AstroError based on the Zod validation.
For this to work, the parsing logic had to be moved from the functions return type schema to an external schema, and the validation had to be moved into the simpleLoader function itself due to performance issues with Zod when using z.function().returns(...).

Testing

The changes in this PR should be covered by the existing tests as no behavior has been added or changed.

Docs

/cc @withastro/maintainers-docs for feedback!

A docs PR has been made here

[changeset-bot]

🦋 Changeset detected

Latest commit: 56c5cfa

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-hq]

CodSpeed Performance Report

Merging #12892 will not alter performance

_{Comparing louisescher:verbose-id-errors (56c5cfa) with main (694e4cd)}

Summary

✅ 6 untouched benchmarks

[ascorbic]

Great! A definite improvement. Could you add a test, checking that it throws the right error when passed a number for ID? Also can you add a patch changeset? Thanks!

[louisescher]

@ascorbic Will do!

[sarah11918]

Just commenting on the error message for docs in general! I indicated a couple of places (but would apply throughout if appropriate) where this might be targeted specifically to IDs, if that is in fact what this is solely focused on.

I'll leave it to y'all, but just pointing out that if it makes sense to be more specific, it's often more helpful and informative to the user! (Also easier to come up with another error name in the case of a different kind of "invalid" result. 😄 )

[sarah11918]

Suggested change

	* A content loader returned an invalid result.
	* A content loader returned an invalid `id`.

Like the title of your PR, if the reason this entry is invalid is only and exactly because of the ID, would it be more helpful to specify this here?

[louisescher]

I've tried keeping the error as agnostic as possible so it can be used for other validation that might be needed in the future. The actual error content does include the following line:
"Property id has to be a string"
And right below that it shows the entry that caused this error.

Edit: The actual error message is supplied by the validation schema itself, meaning that this error can easily be extended with further error messages for other properties if needed.

[sarah11918]

Just checking on this because I'm totally not sure whether this is how we've handled error messages in the past! I'm not sure we've had one that "means different things" and gets a different message based on exactly what went wrong. Usually it's one particular error, but the dynamic part of the message is e.g. identifying the file name or something like that.

Would love for someone to confirm this! Maybe @ematipico would be in a good position to judge this.

[louisescher]

Ah fair enough, didn't know that. Gonna wait for Ema's input then

[sarah11918]

Suggested change

	export const ContentLoaderReturnsInvalidResult = {
	export const ContentLoaderReturnsInvalidId = {

Just an e.g. based on my earlier question. There are probably lots of ways an entry can be invalid, so does it make sense to entirely base this on invalid ID

[louisescher]

See reply on previous change request