Polymorphic IDs

This package adds support to ChilliCream's HotChocolate for polymorphic Relay / Global IDs so that you can pass the database id in as an ID in an input/argument and it'll be accepted.

For example, if you read the description of an ID type in GitHub's GraphQL API, it says:

When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

The following becomes possible (on args/input fields annotated with HotChocolate's [ID] attribute).

# Schema
type Query {
  booking(id: ID!): Booking
}

# Query
query {
  bookingByGlobalId: booking(id: "TheGlobalIdValue7sghdyg=") { ... }
  
  bookingByDbId: booking(id: 1) { ... }
  
  bookingByDbIdString: booking(id: "1") { ... }
}

More details

Why would you do this?

1. To achieve friendly URLs, like /booking/123, you need to be able to get a booking by its database id (123) as the client doesn't have the global ID. But it's nasty to have to expose a bookingByDbId(id: Int!) field to do so.
2. For easier debugging. As humans we use database ids. So if you've got one, you can just pass it on through.

What's supported?

Arguments / input fields are noticed whether they're declared with the [ID] attribute or the fluent-style .ID() (e.g. descriptor.Field(x => x.SomeId).ID()); both have polymorphic id handling added.

When a field declares an explicit type name via the attribute (e.g. [ID("Booking")]), an incoming global id is validated to actually belong to that type — a global id for a different type is rejected, just like Hot Chocolate's built-in behaviour. Raw database ids carry no type name, so they're always accepted (that's the whole point).

Limitation: this type-name validation is not applied to the fluent .ID("Booking") form. Fluent ids are still fully handled (raw db ids and global ids both work), but the explicit type name passed to .ID(...) isn't visible to us (Hot Chocolate keeps it inside its own formatter), so a global id of the wrong type won't be rejected on a fluently-declared field. Use the [ID("Booking")] attribute if you need that check. If you'd like this supported for fluent fields too, give issue #16 a 👍.

Arrays of IDs are handled (but only v2+ can support arrays of nullable IDs ([ID] or [ID]!) due to a bug in Hot Chocolate v11).

IDs that are internally represented with int, Guid, long or string, and their nullable equivalents will be handled. You can opt-out of each's support as required.

For integer-based IDs, you can pass "1" or 1 and both will be accepted.

For all other types, you need to pass the string value, e.g.

• "26a2dc8f-4dab-408c-88c6-523a0a89a2b5" for a guid-based ID
• "123456789" for a long-based ID

Any downsides?

1. Strings are a problem. It's difficult to distinguish between the global id format and a string database id. As such, in this case, we try to read it as a global id and if that throws we consider it a database id. The one problem being that invalid global ids, e.g. you missed one char, will be considered a database id. If you don't have string db ids, it's a good idea to just turn off their handling so an invalid global id would still throw (see setup below).
2. There's a performance hit to the interception, but it'd be barely measurable.
3. Once you go down this path, it's very difficult to go back as your clients will start to rely on this.

Setup

Install a compatible version of the package from NuGet

dotnet add package AutoGuru.HotChocolate.PolymorphicIds

Configure it on your schema (ISchemaBuilder) or executor (IRequestExecutorBuilder):

.AddGlobalObjectIdentification() // Required since Hot Chocolate v12.6.0+
.AddPolymorphicIds(new PolymorphicIdsOptions
{
    HandleGuidIds = false,    // true by default
    HandleIntIds = true,      // true by default
    HandleLongIds = false,    // true by default
    HandleStringIds = false,  // true by default
});

Adding a dbId field declaratively

At AutoGuru we add a dbId field to all our nodes. Since this is essentially the same as declaring the node's id field, we've got some helpers for this that can be found here.

Currently this is a manual/explicit thing you need to do, but in future this will ideally become automatic via a type interceptor if I can figure out how to get that to work (last attempt failed :P).

Compatibility

We depend on HotChocolate.Types (previously HotChocolate.Execution, which Hot Chocolate stopped publishing as a standalone package in v16) which can bring breaking changes from time to time and require a major bump our end. Compatibility is listed below.

We strive to match Hot Chocolate's supported .NET target frameworks, though this might not always be possible.

HotChocolate	Polymorphic IDs	Our docs
v16.0.0	v7	right here
v15.0.0	v6	/v6/main branch
v14.0.0	v5	/v5/main branch
v13.0.0	v4	/v4/main branch
v12.6.0*	v3	/v3/main branch
v12.0.0	v2	/v2/main branch
v11.1.0	v1	/v1/main branch

* Denotes unexpected binary incompatibility / breaking change in Hot Chocolate