Collections reference() API docs do not match current behavior #11303
Comments
|
Thanks for filing this on the docs repo, as it appears that yes, the behaviour has changed! It seems @KianNH (in the original issue filed) described when and how validation occurs, and how it differs from when it did in v4:
And @florian-lefebvre stated:
Florian, can you provide some context/examples of when and how it does work so that we can make sure in docs we are saying when/why to use This should be updated in docs to properly describe the intended/recommended use case of |
|
Indeed |
The point I have been attempting to make is that this behavior would still be just as similar even if you didn't use So as a developer, what reason do I have to use |
|
Noting that you didn't really answer my question, @florian-lefebvre ! You didn't give me an example of when or now to use |
|
For a single reference, I'd say it's just a handy helper to avoid writing the queried collection explicitly: // Using `author: reference("authors")`, we can use this:
const author = await getEntry(blogPost.data.author);
// Using `author: z.string()`, we would need to write:
const author = await getEntry("authors", blogPost.data.author);So, yes, without validation, I don't think there's a real reason to favor one over the other. It may just seem more convenient to some or if wrapped in a generic helper function to process collection entries (ie. when we don't know in advance the collection name to use). I guess this is more useful with complex types. I don't know if an union of references is possible... But, for example, when using an array of references: // Using `authors: z.array(reference("authors"))`, we can use this:
const authors = await getEntries(blogPost.data.authors);
// Using `authors: z.array(z.string())`, we would need to write:
const authors = await getEntries(blogPost.data.authors.map((author) => ({collection: "authors", id: author}));I could be wrong but I think, with the |
|
Yeah i think Armand is quite right there. Btw I realized I thought all this time we were talking about |
📚 Subject area/topic
Content Collections API Reference
📋 Page(s) affected (or suggested, for new content)
https://docs.astro.build/en/reference/modules/astro-content/#reference
📋 Description of content that is out-of-date or incorrect
No validation of entries occurs in v5, as originally reported in withastro/astro#13268. Moreover, without some alternative explanation, this may leave developers wondering what reason there is to use the
reference()API at all in v5.From discussion in the original reported issue, this is apparently a regression to be tackled in v6, though I do not know where that is tracked since the issue in question has been closed (as "not planned", which sends the opposite message) and locked.
🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)
No response
The text was updated successfully, but these errors were encountered: