Proposal: Make created or modified timestamps explicit about graphql

[danstarns]

Not a bad idea, although I wouldn't say it's any more explicit than the current way of doing it. What if you wanted upserted... then you have to apply two directives?

type Movie {
    id: ID
    upsertedAt: DateTime! @CreatedDate @LastModifiedDate
}

[Andy2003]

I think we need to consider the size and surface area of the library, if we introduce lots and lots of directives for each use case; how will that be to document & remember?

You can define a partial schema containing all the frameworks types (like e.g. DeleteInfo) and directives, add it to your npm package the IDE will allow code completion and documentation for your types:

"""
some nice doc
"""
directive @CreatedDate on FIELD_DEFINITION

Additionally you can define where the user can place the directive.

Plus adding more directives restricts users in implementing there own.

come on...
but you can prefix all directives with neo4j

[darrellwarde]

Just for your information @Andy2003, with this we're taking the direction:

directive @timestamp(operation: TimestampEvent! = UPSERT) on FIELD_DEFINITION
enum TimestampEvent{
  CREATE,
  UPDATE,
  UPSERT
}

That would mean if someone wanted a general timestamp of the last update or creation, they just use @timestamp. And then if someone wanted two separate create and update fields, they would have @timestamp(operation: CREATE) and @timestamp(operation: UPDATE).

[danstarns]

Where do you see each directive mentioned being applied? On the type definition? Or a field?

[Andy2003]

on the field

[Andy2003]

type Movie {
    id: ID
    createdAt: DateTime! @CreatedDate
    updatedAt: DateTime! @LastModifiedDate
}

[Andy2003]

then you have to apply two directives?

Yes, this looks very familiar to me as a Java user :-)

[darrellwarde]

Not a bad idea, although I wouldn't say it's any more explicit than the current way of doing it. What if you wanted upserted... then you have to apply two directives?

type Movie {
    id: ID
    upsertedAt: DateTime! @CreatedDate @LastModifiedDate
}

Personally not a fan of this at all, in my opinion would have to come up with a cleaner way of implementing this.

[danstarns]

One could argue just make a @Upserted directive and jobs a gooden. I think we need to consider the size and surface area of the library, if we introduce lots and lots of directives for each use case; how will that be to document & remember? Plus adding more directives restricts users in implementing there own.

[Andy2003]

Personally not a fan of this at all, in my opinion would have to come up with a cleaner way of implementing this.

So if you stay with @autogenerate, you should at least make the operations argument an enum array.

[darrellwarde]

I think we need to consider the size and surface area of the library, if we introduce lots and lots of directives for each use case; how will that be to document & remember?

You can define a partial schema containing all the frameworks types (like e.g. DeleteInfo) and directives, add it to your npm package the IDE will allow code completion and documentation for your types:

"""
some nice doc
"""
directive @CreatedDate on FIELD_DEFINITION

Additionally you can define where the user can place the directive.

Love this, code completion for our directives would be a game changer.

[Andy2003]

This is the reason, why I extracted the directives and made them "static". So the Intellij graphql plugin will scan the whole project for *.graphql files and provides you with code completion.

[Andy2003]

[darrellwarde]

Yep, completely onboard with this, definitely going on the roadmap!

Time for me to relax for the evening. 😪 Thanks for all of the feedback on this, it's really valuable. Have a good weekend!

[darrellwarde]

This has now been implemented and will be in the next release. In the end, the definition is as follows:

enum TimestampOperation {
    CREATE
    UPDATE
}

"""Instructs @neo4j/graphql to generate timestamps on particular events, which will be available as the value of the specified field."""
directive @timestamp(
    """Which events to generate timestamps on. Defaults to both create and update."""
    operations: [TimestampOperation!]! = [CREATE, UPDATE]
) on FIELD_DEFINITION