angeloashmore
commented
3 years ago JavaScript users
An alternative to consider is JSDoc. Rather than adding to the API, we could document how JavaScript users can hook into the TypeScript types.
/** @type prismicH.HTMLMapSerializer */
const htmlMapSerializer = {
paragraph: ({ children }) => `<p>${children}</p>`,
};
/** @type prismicH.HTMLFunctionSerializer */
const htmlFunctionSerializer = (type, _node, _text, children) => {
switch (type) {
case prismicH.Element.paragraph:
return `<p>${children}</p>`;
}
};TypeScript
For TypeScript users, we could similarly recommend users type it like standard TypeScript. Like the JSDoc approach, this doesn't add to the API and follows existing TypeScript practices.
const htmlMapSerializer: prismicH.HTMLMapSerializer = {
paragraph: ({ children }) => `<p>${children}</p>`,
};
const htmlFunctionSerializer: prismicH.HTMLFunctionSerializer = (
type,
_node,
_text,
children,
) => {
switch (type) {
case prismicH.Element.paragraph:
return `<p>${children}</p>`;
}
};I personally would lean toward the JSDoc + explicit TS types approach since it builds on existing code. It also won't raise questions about what the defineHTML*Serializer functions are doing (e.g. "Will it modify my serializer?").
This method relies on documenting it and making it clearly available. The same is true for the defineHTML*Serializer functions, but using a function may be more familiar than using @type comments and explicit const types.
lihbr
samlfair
Is your feature request related to a problem? Please describe.
Function and map serializers are now beautifully typed but often defined outside of
asHTMLcalls for reusability purposes.This leads to forcing TypeScript users to specifically type their functions/map (which is fine), but also kills any IntelliSense JavaScript users might have had from them.
Describe the solution you'd like
Exposing two functions,
defineHTMLFunctionSerializeranddefineHTMLMapSerizlizer, that simply receive said arguments and return them, would allow to get seamless IntelliSense for both TypeScript and JavaScript users.Describe alternatives you've considered
n/a, haven't thought about it much tbh
Additional context
This is pattern somewhat adopted by other technologies, for example siroc: https://github.com/unjs/siroc/blob/main/src/core/package/index.ts#L100
I also adopted that pattern for the 11ty plugin: https://github.com/prismicio-community/eleventy-plugin-prismic/blob/master/src/definePrismicPluginOptions.ts