fix(gatsby): always add both childField and childrenField in GraphQL

[vladar]

Description

Before this PR we create only one of the child fields depending on the number of elements in the node children array.

E.g. when children array contains 1 item we create this field:

type Foo {
  childBar: Bar
}

But when children array contains 2+ items, we create this field:

type Foo {
  childrenBar: [Bar]
}

The problem is that it relies on inference. And if at some point in time you had a single child node and then suddenly added a second child node - your schema will change from childBar to childrenBar and your queries will break.

With this PR we always add both fields instead:

type Foo {
  childBar: Bar
  childrenBar: [Bar]
}

In this case, childBar will always return the first child from the array of node children. And then it is up to users to pick the most appropriate field for their queries.

This also deprecates the many argument of the childOf directive ¹

This is a non-breaking change. Also required to unblock #28483

Credits for this idea go to @pieh

Documentation

• [childOf directive]¹
• [Child/parent fields]²
• [Schema generation]³

Related Issues

#28483

Footnotes

1. https://www.gatsbyjs.com/docs/reference/graphql-data-layer/schema-customization/#defining-child-relations ↩ ↩²

2. https://www.gatsbyjs.com/docs/schema-inference/#childparent-fields ↩

3. https://www.gatsbyjs.com/docs/schema-generation/#4-parent--children-relationships ↩

[vladar]

That's basically the essence of this PR. Other changed files are just tests/docs updates.

[vladar]

Same change, just in the different codepath

[vladar]

And one more entry. Other changes are mostly chores and don't have any effect on behavior.

[pieh]

Just to leave papar trail for the future from our offline chat:

do you think, given that we will add both of them, it would help a little to add description to those fields?

gatsby/packages/gatsby/src/schema/schema.js

Lines 1067 to 1100 in 2bb4214

	const createChildrenField = typeName => {
	return {
	[fieldNames.convenienceChildren(typeName)]: {
	type: () => [typeName],
	resolve(source, args, context) {
	const { path } = context
	return context.nodeModel.getNodesByIds(
	{ ids: source.children, type: typeName },
	{ path }
	)
	},
	},
	}
	}
	const createChildField = typeName => {
	return {
	[fieldNames.convenienceChild(typeName)]: {
	type: () => typeName,
	resolve(source, args, context) {
	const { path } = context
	const result = context.nodeModel.getNodesByIds(
	{ ids: source.children, type: typeName },
	{ path }
	)
	if (result && result.length > 0) {
	return result[0]
	} else {
	return null
	}
	},
	},
	}
	}

another question is wether we should split PR due to docs site building from master branch for now
similar case to ( #28666 )

[pieh]

Thank you!