feat: @amplienceContentType fieldOrder

[jonnoallcock]

New optional fieldOrder argument for @amplienceContentType. Allows the developer to explicitly control the propertyOrder in a given content type's JSON output.

Example:

The following schema:

type OrderedFields @amplienceContentType(fieldOrder: "c b a e d") {
  a: String!
  b: String!
  c: String!
  d: String!
  e: String!

  ignored: String @amplienceIgnore
  deliveryKey: String @amplienceDeliveryKey
}

Outputs:

{
  "$id": "https://schema-examples.com/ordered-fields",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "allOf": [
    { "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content" }
  ],
  "title": "Ordered Fields",
  "description": "Ordered Fields",
  "type": "object",
  "properties": {
    "_meta": {
      "type": "object",
      "title": "Delivery Key",
      "properties": {
        "deliveryKey": {
          "type": "string",
          "title": "Delivery Key",
          "description": "Set a delivery key for this content item"
        }
      }
    },
    "a": { "title": "A", "type": "string" },
    "b": { "title": "B", "type": "string" },
    "c": { "title": "C", "type": "string" },
    "d": { "title": "D", "type": "string" },
    "e": { "title": "E", "type": "string" }
  },
  "propertyOrder": ["_meta", "c", "b", "a", "e", "d"], // explicit propertyOrder
  "required": ["a", "b", "c", "d", "e"]
}

Validation

Must not specify fields with @amplienceDeliveryKey or @amplienceIgnore
(These are handled uniquely with regards to JSON output, so do not need specifying)

type Test @amplienceContentType(fieldOrder: "ignored a deliveryKey") {
  a: String
  ignored: @amplienceIgnore
  deliveryKey: @amplienceDeliveryKey
}

# Error:
# @amplienceContentType fieldOrder arguments must not specify fields with @amplienceDeliveryKey or @amplienceIgnore.
#   type Test
#     ignored
#     deliveryKey

Must specify all extant non-illegal fields

type Test @amplienceContentType(fieldOrder: "b a c") {
  a: String
  b: String
  c: String
  d: String
  e: String
}

# Error:
# @amplienceContentType fieldOrder arguments must specify every field defined within the type.
#   type Test
#     d
#     e

Must not specify unknown field names

type Test @amplienceContentType(fieldOrder: "unknownOne a b unknownTwo") {
  a: String
  b: String
}

# Error:
# @amplienceContentType fieldOrder arguments must not specify fields not defined within the type.
#   type Test
#     unknownOne
#     unknownTwo

[korsvanloon]

Can you run pnpm changeset? This should generate a file and please add that to this PR.
(I'll add this instruction in the README later ;) )

[korsvanloon]

The current behavior is to keep the GraphQL definition order. Can you tell me why this isn't sufficient? What problem is this PR trying to solve?

[jonnoallcock]

The current behavior is to keep the GraphQL definition order. Can you tell me why this isn't sufficient? What problem is this PR trying to solve?

Current behavior is actually to output fields in alphabetical order (see content-type.json). This results in some pretty counterintuitive content forms for our editors, so we wanted control over the output to improve that experience.

I was hoping for an automatic solution to respect definition order, but found that:

• the plugin receives fields already sorted
• the plugin does not receive any information pertaining to the original order and cannot infer it with the information it does have

This explicit argument felt a good compromise.

[korsvanloon]

Have you tried to disable sorting in the codegen file? Do you run into any other problems with that?

import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  overwrite: true,
  config: {
    sort: false,
  },
  generates: {
   ...

[jonnoallcock]

Have you tried to disable sorting in the codegen file? Do you run into any other problems with that?

import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  overwrite: true,
  config: {
    sort: false,
  },
  generates: {
   ...

...I did try that as a first attempt during investigation well before looking at a plugin solution, and found it didn't appear to work for whatever reason. Trying it now...it does. Suffice it to say I'm more than puzzled.

Where does that leave us with this feature? Reckon it's worth keeping for any potential use case, or dropping outright?

[korsvanloon]

I think it's because somehow the sort only works in the root config, and not in a config scoped within a generate.

I'll keep this PR open for a couple of weeks to be sure.
You might run into other issues, then we can merge this. If not I'll close this PR after a couple of weeks.