Write fieldparams.md content

Author: wravery

doc/fieldparams.md

@@ -0,0 +1,81 @@
+# Common Field Parameters
+
+The `resolveField` methods generated by `schemagen` will unpack any arguments
+matching the `schema` from the `query` and pass those to the `getField` method
+defined by the implementer. However, the implementer might need to inspect
+shared state or `directives` from the `query`, so the `resolveField` method
+also packs that information into a `graphql::service::FieldParams` struct and
+passes it to every `getField` method as the first parameter.
+
+## Details of Field Parameters
+
+The `graphql::service::FieldParams` struct is declared in [GraphQLService.h](../include/graphqlservice/GraphQLService.h):
+```cpp
+// Pass a common bundle of parameters to all of the generated Object::getField accessors in a SelectionSet
+struct SelectionSetParams
+{
+	// The lifetime of each of these borrowed references is guaranteed until the future returned
+	// by the accessor is resolved or destroyed. They are owned by the OperationData shared pointer. 
+	const std::shared_ptr<RequestState>& state;
+	const response::Value& operationDirectives;
+	const response::Value& fragmentDefinitionDirectives;
+
+	// Fragment directives are shared for all fields in that fragment, but they aren't kept alive
+	// after the call to the last accessor in the fragment. If you need to keep them alive longer,
+	// you'll need to explicitly copy them into other instances of response::Value.
+	const response::Value& fragmentSpreadDirectives;
+	const response::Value& inlineFragmentDirectives;
+};
+
+// Pass a common bundle of parameters to all of the generated Object::getField accessors.
+struct FieldParams : SelectionSetParams
+{
+	explicit FieldParams(const SelectionSetParams& selectionSetParams, response::Value&& directives);
+
+	// Each field owns its own field-specific directives. Once the accessor returns it will be destroyed,
+	// but you can move it into another instance of response::Value to keep it alive longer.
+	response::Value fieldDirectives;
+};
+```
+
+### Request State
+
+The `SelectionSetParams::state` member is a reference to the
+`std::shared_ptr<graphql::service::RequestState>` parameter passed to
+`Request::resolve` (see [resolvers.md](./resolvers.md) for more info):
+```cpp
+// The RequestState is nullable, but if you have multiple threads processing requests and there's any
+// per-request state that you want to maintain throughout the request (e.g. optimizing or batching
+// backend requests), you can inherit from RequestState and pass it to Request::resolve to correlate the
+// asynchronous/recursive callbacks and accumulate state in it.
+struct RequestState : std::enable_shared_from_this<RequestState>
+{
+};
+```
+
+### Scoped Directives
+
+Each of the `directives` members contains the values of the `directives` and
+any of their arguments which were in effect at that scope of the `query`.
+Implementers may inspect those values in the call to `getField` and alter their
+behavior based on those custom `directives`.
+
+As noted in the comments, the `fragmentSpreadDirectives` and
+`inlineFragmentDirectives` are borrowed `const` references, shared accross
+calls to multiple `getField` methods, but they will not be kept alive after
+the relevant `SelectionSet` has been resolved. The `fieldDirectives` member is
+passed by value and is not shared with other `getField` method calls, but it
+will not be kept alive after that call returns. It's up to the implementer to
+capture the values in these `directives` which they might need for asynchronous
+evaulation after the call to the current `getField` method has returned.
+
+The implementer does not need to capture the values of `operationDirectives`
+or `fragmentDefinitionDirectives` because those are kept alive until the
+`operation` and all of its `std::future` results are resolved. Although they
+passed by `const` reference, the reference should always be valid as long as
+there's a pending result from the `getField` call.
+
+## Related Documents
+
+1. The `getField` methods are discussed in more detail in [resolvers.md](./resolvers.md).
+2. Built-in and custom `directives` are discussed in [directives.md](./directives.md).

doc/resolvers.md

@@ -73,7 +73,7 @@ In this example, the `resolveId` method invokes `getId`:
 virtual service::FieldResult<response::IdType> getId(service::FieldParams&& params) const override;
 ```
 
-There are also a couple of interesting quirks in this example:
+There are a couple of interesting quirks in this example:
 1. The `Appointment object` implements and inherits from the `Node interface`,
 which already declared `getId` as a pure-virtual method. That's what the
 `override` keyword refers to.
@@ -87,4 +87,10 @@ will throw a `std::runtime_error`, which the `resolver` converts into an entry
 in the `response errors` collection:
 ```cpp
 throw std::runtime_error(R"ex(Appointment::getId is not implemented)ex");
-```
+```
+
+Although the `id field` does not take any arguments according to the sample
+[schema](../samples/today/schema.today.graphql), this example also shows how
+every `getField` method takes a `graphql::service::FieldParams` struct as
+its first parameter. There are more details on this in the [fieldparams.md](./fieldparams.md)
+document.