docsSchema typings conflict with defineCollection typings

[seangwright]

What version of starlight are you using?

0.10.2

What version of astro are you using?

3.1.4

What package manager are you using?

npm

What operating system are you using?

Windows

What browser are you using?

Brave

Describe the Bug

The TypeScript typings for docsSchema don't match the typings for defineCollection and produce a typing error.

// config.ts
import { defineCollection } from "astro:content";
import { docsSchema, i18nSchema } from "@astrojs/starlight/schema";

export const collections = {
  docs: defineCollection({ schema: docsSchema() }), // error!
  i18n: defineCollection({ type: "data", schema: i18nSchema() }),
};

Error message:

[{
	"resource": "/path/to/src/content/config.ts",
	"owner": "typescript",
	"code": "2322",
	"severity": 8,
	"message": "Type '({ image }: { image: ImageFunction; }) => z.ZodObject<{ title: z.ZodString; description: z.ZodOptional<z.ZodString>; editUrl: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>>; ... 9 more ...; pagefind: z.ZodDefault<...>; }, \"strip\", z.ZodTypeAny, { ...; }, { ...; }>' is not assignable to type 'ZodObject<{ title: ZodString; description: ZodOptional<ZodString>; editUrl: ZodDefault<ZodOptional<ZodUnion<[ZodString, ZodBoolean]>>>; ... 9 more ...; pagefind: ZodDefault<...>; }, \"strip\", ZodTypeAny, { ...; }, { ...; }> | ((context: SchemaContext) => ZodObject<...>) | ((context: SchemaContext) => ZodObject<...>) ...'.\n  Type '({ image }: { image: ImageFunction; }) => z.ZodObject<{ title: z.ZodString; description: z.ZodOptional<z.ZodString>; editUrl: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>>; ... 9 more ...; pagefind: z.ZodDefault<...>; }, \"strip\", z.ZodTypeAny, { ...; }, { ...; }>' is not assignable to type '(context: SchemaContext) => ZodObject<{ title: ZodString; description: ZodOptional<ZodString>; editUrl: ZodDefault<ZodOptional<ZodUnion<[ZodString, ZodBoolean]>>>; ... 9 more ...; pagefind: ZodDefault<...>; }, \"strip\", ZodTypeAny, { ...; }, { ...; }>'.\n    Types of parameters '__0' and 'context' are incompatible.\n      Type 'SchemaContext' is not assignable to type '{ image: ImageFunction; }'.\n        The types of 'image()._getCached().shape' are incompatible between these types.\n          Type '{ src: ZodString; width: ZodNumber; height: ZodNumber; format: ZodUnion<[ZodLiteral<\"png\">, ZodLiteral<\"jpg\">, ZodLiteral<\"jpeg\">, ... 4 more ..., ZodLiteral<...>]>; }' is not assignable to type '{ src: ZodString; width: ZodNumber; height: ZodNumber; format: ZodUnion<[ZodLiteral<\"png\">, ZodLiteral<\"jpg\">, ZodLiteral<\"jpeg\">, ZodLiteral<...>, ZodLiteral<...>, ZodLiteral<...>, ZodLiteral<...>]>; }'.",
	"source": "ts",
	"startLineNumber": 5,
	"startColumn": 36,
	"endLineNumber": 5,
	"endColumn": 48,
	"relatedInformation": [
		{
			"startLineNumber": 5,
			"startColumn": 36,
			"endLineNumber": 5,
			"endColumn": 48,
			"message": "Did you mean to call this expression?",
			"resource": "/path/to/src/content/config.ts"
		}
	]
}]

However, everything builds correctly.

When I remove the function execution of docsSchema to satisfy the type requirements, I get a compilation error:

[vite] Error when evaluating SSR module /path/to/node_modules/@astrojs/starlight/index.astro: failed to import "/node_modules/@astrojs/starlight/utils/routing.ts"
|- TypeError: schema.safeParseAsync is not a function
    at getEntryData (file:////path/to/node_modules/astro/dist/content/utils.js:74:33)
    at getContentEntryModule (file:////path/to/node_modules/astro/dist/content/vite-plugin-content-imports.js:151:41)
    at async TransformContext.transform (file:////path/to/node_modules/astro/dist/content/vite-plugin-content-imports.js:73:67)     
    at async Object.transform (file:////path/to/node_modules/vite/dist/node/chunks/dep-df561101.js:44283:30)
    at async loadAndTransform (file:////path/to/node_modules/vite/dist/node/chunks/dep-df561101.js:54950:29)
    at async instantiateModule (file:////path/to/node_modules/vite/dist/node/chunks/dep-df561101.js:55875:10)

 error   schema.safeParseAsync is not a function
  File:
    /path/to/src/content/docs/examples/admin/module.md?astroContentCollectionEntry=true

So, either the types are incorrect or my project is misconfigured even though I'm following the docs.

Link to Minimal Reproducible Example

No response

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thanks for the report!

Presumably a type changed in a recent Astro release. As you noted, I don't think any functionality should break, so it's an issue for type checking only. Might be image metadata related? We had to copy-paste a type related to those at one point, so seems like something that could get out of sync.

[HiDeoo]

The issue seems to be related to a change in Astro v3.1.1 and more specifically withastro/astro#8568.

We would need to update the ImageFunction definition to add avif and bump the required Astro version.

type ImageFunction = () => z.ZodObject<{
	src: z.ZodString;
	width: z.ZodNumber;
	height: z.ZodNumber;
	format: z.ZodUnion<
		[
			z.ZodLiteral<'png'>,
			z.ZodLiteral<'jpg'>,
			z.ZodLiteral<'jpeg'>,
			z.ZodLiteral<'tiff'>,
			z.ZodLiteral<'webp'>,
			z.ZodLiteral<'gif'>,
			z.ZodLiteral<'svg'>,
+			z.ZodLiteral<'avif'>,
		]
	>;
}>;

[delucis]

Ahhh, yeah, makes sense. Annoying that we need to sync manually and that this causes type errors depending on Astro version used. Let’s ask if we can get that type to import instead of needing to duplicate it.

In the meantime, we can probably do some nice refactors thanks to withastro/astro#8672 and require astro@^3.2 as a breaking change. That would make it safe for us to also update this to include the new avif support.

ImageFunction is exported from astro:content, but I remember we couldn’t import from there in our schema file for some reason. We had to switch to importing Zod from astro/zod in #33. Might be worth double checking that’s still the case. (Edit: I double checked, still seems to have issues.)

[delucis]

Update — I figured it out! #775

It actually seems to be safe to import the SchemaContext type from astro:content even though importing Zod from there doesn’t work.

[HiDeoo]

Update — I figured it out! #775

It actually seems to be safe to import the SchemaContext type from astro:content even though importing Zod from there doesn’t work.

Oh, clever idea to split the imports! 🧠