Astro's Content Collections: Support for Custom Object Transformations

[FlorianFlatscher]

Body

Summary

Enable Astro's content collections to support custom object transformations, such as converting dates using libraries like Luxon, by allowing configuration of the serialization process.

Background & Motivation

Currently, when using z.transform() in content collection schemas to construct custom objects (e.g., transforming dates with Luxon), Astro's serialization process encounters issues. This is because Astro serializes the result of the schema using the devalue library, which doesn't recognize custom object types by default. Although devalue supports registering custom types, Astro doesn't currently expose a way to modify its configuration. This limitation hinders developers from effectively utilizing powerful libraries like Luxon for data transformation within content collections. A related issue has been discussed in the Astro GitHub repository: withastro/astro#6764

Goals

• Allow developers to use z.transform() in content collection schemas to create custom objects without serialization errors.
• Provide a mechanism to configure the devalue library within Astro's configuration API to register custom types.
• Enhance Astro's flexibility and developer experience by supporting advanced data transformations in content collections.

Example

Consider a scenario where a developer wants to transform a date string into a Luxon DateTime object within a content collection schema:

import { z } from 'astro:content';
import { DateTime } from 'luxon';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date().transform((value) => DateTime.fromJSDate(value)),
  }),
});

Currently, this transformation results in a serialization error because devalue cannot handle the DateTime object. By allowing developers to configure devalue to recognize custom types, this transformation would work seamlessly, enabling more powerful and flexible data handling within Astro's content collections.

Implementing this proposal would significantly improve the developer experience by allowing the use of advanced data transformation libraries within Astro's content collections, thereby enhancing the framework's flexibility and capability.

[openscript]

Another goal of this could be to allow custom content loaders to transform the schema. Currently the content schema (input) and the content collection (output) need to match. To allow adding new attributes to a schema within a custom content loader would be another great goal, so a content loader can calculate new properties and add them to the output. An example would be reading the locale from the file path.