Added documentation for @typePolicy #586

AnthonyMDev · 2025-01-24T20:38:39Z

This PR adds documentation for the new @typePolicy feature.

svc-apollo-docs · 2025-01-24T20:38:43Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 2 changed, 1 removed

* (developer-tools)/ios/(latest)/client-directives.mdx
* (developer-tools)/ios/(latest)/caching/cache-key-resolution.mdx
- (developer-tools)/ios/(latest)/caching/programmatic-cache-keys.mdx

Build ID: 0b2e31899f329a3565584542

URL: https://www.apollographql.com/docs/deploy-preview/0b2e31899f329a3565584542

netlify · 2025-01-24T20:39:01Z

✅ Deploy Preview for eclectic-pie-88a2ba ready!

Name	Link
🔨 Latest commit	`f59b862`
🔍 Latest deploy log	https://app.netlify.com/sites/eclectic-pie-88a2ba/deploys/679409261dbf7400080b7789
😎 Deploy Preview	https://deploy-preview-586--eclectic-pie-88a2ba.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify · 2025-01-24T20:39:04Z

✅ Deploy Preview for apollo-ios-docc canceled.

Name	Link
🔨 Latest commit	`7eb6767`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-ios-docc/deploys/67980c6911ef3200088f5a2c

docs/source/caching/cache-key-resolution.mdx

Meschreiber

Just left some superficial copyedit suggestions. I realize some of the suggesting (like using or ) may make these pages inconsistent with formatting on other pages and so you may want to leave them out for now.

Meschreiber · 2025-01-24T21:18:41Z

docs/source/config.json

We might want to remove this file as long as it's not being used. Will confirm with @BlenderDude if this is something we can bring back first.

docs/source/caching/cache-key-resolution.mdx

Meschreiber · 2025-01-24T21:35:09Z

docs/source/caching/cache-key-resolution.mdx


-1. `let uniqueKeyGroup: String?`
+Declarative cache keys work by adding directives to your backend schema types to indicate how cache keys should be resolved for those times. To do this, you can extend your backend schema by creating a schema extension file with the file extension `.graphqls`. You can add any number of schema extension files to your project.


I found this a little hard to follow, so I tried breaking it up into shorter sentences. Does this still capture things accurately?

Suggested change

Declarative cache keys work by adding directives to your backend schema types to indicate how cache keys should be resolved for those times. To do this, you can extend your backend schema by creating a schema extension file with the file extension `.graphqls`. You can add any number of schema extension files to your project.

To use declarative cache keys, you add directives to your backend schema types. The directives indicate how to resolve cache keys. To use these directives, you extend your backend schema by creating a schema extension file with the file extension `.graphqls`. You can add any number of schema extension files to your project.

docs/source/caching/cache-key-resolution.mdx

Meschreiber · 2025-01-24T23:18:10Z

docs/source/caching/programmatic-cache-keys.mdx

+
+ The code generation engine creates this file if it doesn't exist yet, but never overwrites an existing `SchemaConfiguration.swift` file. This means you can edit your schema configuration without those changes being overwritten on subsequent code generation runs.
+
+> *Tip:* You can configure the location of the generated schema types with the [`output.schemaTypes` option in your code generation configuration](./../code-generation/codegen-configuration).


Suggested change

> *Tip:* You can configure the location of the generated schema types with the [`output.schemaTypes` option in your code generation configuration](./../code-generation/codegen-configuration).

<Tip>

You can configure the location of the generated schema types with the [`output.schemaTypes` option in your code generation configuration](./../code-generation/codegen-configuration).

</Tip>

Meschreiber · 2025-01-24T23:19:15Z

docs/source/caching/programmatic-cache-keys.mdx

+
+To configure how cache keys are computed from a response object, you can create and return [`CacheKeyInfo`](#cachekeyinfo) values from your implementation of [`cacheKeyInfo(for:object:)`](https://www.apollographql.com/docs/ios/docc/documentation/apolloapi/schemaconfiguration/cachekeyinfo(for:object:)).
+
+> **Note:** When specifying **cache IDs**, make sure that you are always fetching the fields used to construct those IDs in your operations. Any response objects that don't contain the **cache ID** fields will not be able to be [merged via cache normalization](./introduction#normalizing-responses).


Suggested change

> **Note:** When specifying **cache IDs**, make sure that you are always fetching the fields used to construct those IDs in your operations. Any response objects that don't contain the **cache ID** fields will not be able to be [merged via cache normalization](./introduction#normalizing-responses).

<Note>

When specifying **cache IDs**, make sure that you are always fetching the fields used to construct those IDs in your operations. Any response objects that don't contain the **cache ID** fields will not be able to be [merged via cache normalization](./introduction#normalizing-responses).

</Note>

Meschreiber · 2025-01-24T23:21:03Z

docs/source/caching/programmatic-cache-keys.mdx

+}
+```
+
+## Caveats & limitations


Suggested change

## Caveats & limitations

## Caveats and limitations

Meschreiber · 2025-01-24T23:21:44Z

docs/source/caching/programmatic-cache-keys.mdx

+
+1. While the cache key for an object can use a field from another nested object, if the fields on the referenced object are changed in another operation, the cache key for the dependent object will not be updated. For nested objects that are not normalized with their own cache key, this will never occur, but if the nested object is an entity with its own cache key, it can be mutated independently. In that case, any other objects whose cache keys are dependent on the mutated entity will not be updated automatically. You must take care to update those entities manually with a cache mutation.
+
+2. The `object` passed to this function represents data for an object in an specific operation model, not a type in your schema. This means that [aliased fields](https://spec.graphql.org/draft/#sec-Field-Alias) will be keyed on their alias name, not the name of the field on the schema type.


Suggested change

2. The `object` passed to this function represents data for an object in an specific operation model, not a type in your schema. This means that [aliased fields](https://spec.graphql.org/draft/#sec-Field-Alias) will be keyed on their alias name, not the name of the field on the schema type.

2. The `object` passed to this function represents data for an object in a specific operation model, not a type in your schema. This means that [aliased fields](https://spec.graphql.org/draft/#sec-Field-Alias) will be keyed on their alias name, not the name of the field on the schema type.

Meschreiber · 2025-01-24T23:22:02Z

docs/source/client-directives.mdx

+`directive @typePolicy(module: String!) repeatable on OBJECT | INTERFACE`
+
+Adds an type policy to a type that can be used to resolve cache keys for objects of that type.


Suggested change

Adds an type policy to a type that can be used to resolve cache keys for objects of that type.

Adds a type policy to a type that can be used to resolve cache keys for objects of that type.

docs/source/caching/cache-key-resolution.mdx

martinbonnin · 2025-01-27T17:12:18Z

docs/source/caching/cache-key-resolution.mdx

@@ -8,181 +8,66 @@ The normalized cache computes a **cache key** for each object that is stored in

 > To learn more, read about how the cache [normalizes objects by cache key](./introduction#normalizing-objects-by-cache-key).

-## `CacheKeyInfo`
+For most uses cases, you can configure cache keys declaratively using the methods described here. For advanced use cases not supported by declarative cache keys, you can configure cache keys [programmatically](./programmatic-cache-keys).


Might just be me but clicking "programmatic cache keys" in the preview makes a 404 (link is https://www.apollographql.com/docs/deploy-preview/1f96ea7a044024b699863083/ios/caching/programmatic-cache-keys)

docs/source/caching/cache-key-resolution.mdx

martinbonnin · 2025-01-27T17:22:20Z

docs/source/caching/cache-key-resolution.mdx

 ```

-If the JSON response `object` has no `id` field, the function returns `nil` and the cache will normalize the object using the [default response path normalization](./introduction#normalizing-responses).
+Apollo iOS will now resolve the cache key for all objects with a `__typename` of `"Book"` by using the value of their `id` field. The concrete type of the object is always prepended to the cache key. This means that a `Book` object with an `id` of `456` will resolve to have a cache key of `Book:456`.


Might be worth adding that either:

it's the user responsibility to make sure all the key fields are queried

or that the codegen is doing it automatically

I think it is 1. right now? Either case, it's an important consideration for the system to work.

Co-authored-by: Maria Elisabeth Schreiber <[email protected]> Co-authored-by: Martin Bonnin <[email protected]>

x-sheep · 2025-01-27T21:38:55Z

docs/source/client-directives.mdx

+### `@typePolicy(keyFields: String!)`
+
+`directive @typePolicy(module: String!) repeatable on OBJECT | INTERFACE`


Suggested change

`directive @typePolicy(module: String!) repeatable on OBJECT | INTERFACE`

`directive @typePolicy(keyFields: String!) on OBJECT | INTERFACE`

calvincestari · 2025-01-27T21:47:55Z

I don't think the deploy preview is correctly updating. This one has the correct commit hash (d1ba913) but it didn't actually deploy.

@Meschreiber - is there a way to force a new docs preview to be built on the last commit in this PR?

Meschreiber · 2025-01-27T22:34:37Z

docs/source/caching/programmatic-cache-keys.mdx

+```swift showLineNumbers=false
+CacheKeyInfo(id: "123", uniqueKeyGroup: "Animal")
+Apollo iOS would construct a cache key of `"Animal:123"`.
+


Looks like the formatting is off here, high probability it was from a previous suggestion of mine 😅.

Edit: looks like you can't leave a suggestion with a closing codeblock correctly, but it should be this:

CacheKeyInfo(id: "123", uniqueKeyGroup: "Animal")

calvincestari

Everything looks good in the preview, going to merge.

AnthonyMDev requested a review from Meschreiber January 24, 2025 20:39

AnthonyMDev marked this pull request as ready for review January 24, 2025 20:47

calvincestari reviewed Jan 24, 2025

View reviewed changes

docs/source/caching/cache-key-resolution.mdx Outdated Show resolved Hide resolved

docs/source/caching/cache-key-resolution.mdx Outdated Show resolved Hide resolved

docs/source/caching/cache-key-resolution.mdx Show resolved Hide resolved

Meschreiber approved these changes Jan 24, 2025

View reviewed changes

x-sheep reviewed Jan 25, 2025

View reviewed changes

docs/source/caching/cache-key-resolution.mdx Outdated Show resolved Hide resolved

martinbonnin reviewed Jan 27, 2025

View reviewed changes

Switch sidebar

bc43e94

calvincestari mentioned this pull request Jan 27, 2025

Switch sidebar #591

Closed

AnthonyMDev and others added 4 commits January 27, 2025 13:19

Added documentation for @typePolicy

ca278fe

PR review fixes

fb9936f

Apply suggestions from code review

1c07b03

Co-authored-by: Maria Elisabeth Schreiber <[email protected]> Co-authored-by: Martin Bonnin <[email protected]>

More updates from code review

d74bceb

AnthonyMDev force-pushed the type-policy-docs branch from 4e7e506 to d74bceb Compare January 27, 2025 21:20

svc-secops and others added 7 commits January 27, 2025 13:21

chore(deps): update dependency rollup to v4.32.0 (#589)

86da61c

ci: Use trigger event with base branch context (#592)

2896c00

Added documentation for @typePolicy

887075d

PR review fixes

ae9b214

Apply suggestions from code review

402bad8

Co-authored-by: Maria Elisabeth Schreiber <[email protected]> Co-authored-by: Martin Bonnin <[email protected]>

More updates from code review

e9d0e38

Merge branch 'Meschreiber-move-docs-sidebar' into type-policy-docs

d1ba913

x-sheep reviewed Jan 27, 2025

View reviewed changes

Meschreiber reviewed Jan 27, 2025

View reviewed changes

Adds closing codeblock ticks

7eb6767

calvincestari approved these changes Jan 27, 2025

View reviewed changes

calvincestari merged commit 47e819a into main Jan 27, 2025
25 checks passed

calvincestari deleted the type-policy-docs branch January 27, 2025 23:25

BobaFetters pushed a commit that referenced this pull request Jan 27, 2025

Added documentation for @typePolicy (#586)

78d3132

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added documentation for @typePolicy #586

Added documentation for @typePolicy #586

AnthonyMDev commented Jan 24, 2025

svc-apollo-docs commented Jan 24, 2025 •

edited

Loading

netlify bot commented Jan 24, 2025 •

edited

Loading

netlify bot commented Jan 24, 2025 •

edited

Loading

Meschreiber left a comment

Meschreiber Jan 24, 2025

Meschreiber Jan 24, 2025

Meschreiber Jan 24, 2025

Meschreiber Jan 24, 2025

Meschreiber Jan 24, 2025

Meschreiber Jan 24, 2025

Meschreiber Jan 24, 2025

martinbonnin Jan 27, 2025

martinbonnin Jan 27, 2025

x-sheep Jan 27, 2025

calvincestari commented Jan 27, 2025

Meschreiber Jan 27, 2025 •

edited

Loading

calvincestari left a comment


		1. `let uniqueKeyGroup: String?`
		Declarative cache keys work by adding directives to your backend schema types to indicate how cache keys should be resolved for those times. To do this, you can extend your backend schema by creating a schema extension file with the file extension `.graphqls`. You can add any number of schema extension files to your project.

	Declarative cache keys work by adding directives to your backend schema types to indicate how cache keys should be resolved for those times. To do this, you can extend your backend schema by creating a schema extension file with the file extension `.graphqls`. You can add any number of schema extension files to your project.
	To use declarative cache keys, you add directives to your backend schema types. The directives indicate how to resolve cache keys. To use these directives, you extend your backend schema by creating a schema extension file with the file extension `.graphqls`. You can add any number of schema extension files to your project.


		The code generation engine creates this file if it doesn't exist yet, but never overwrites an existing `SchemaConfiguration.swift` file. This means you can edit your schema configuration without those changes being overwritten on subsequent code generation runs.

		> Tip: You can configure the location of the generated schema types with the [`output.schemaTypes` option in your code generation configuration](./../code-generation/codegen-configuration).


		To configure how cache keys are computed from a response object, you can create and return [`CacheKeyInfo`](#cachekeyinfo) values from your implementation of [`cacheKeyInfo(for:object:)`](https://www.apollographql.com/docs/ios/docc/documentation/apolloapi/schemaconfiguration/cachekeyinfo(for:object:)).

		> Note: When specifying cache IDs, make sure that you are always fetching the fields used to construct those IDs in your operations. Any response objects that don't contain the cache ID fields will not be able to be [merged via cache normalization](./introduction#normalizing-responses).


		1. While the cache key for an object can use a field from another nested object, if the fields on the referenced object are changed in another operation, the cache key for the dependent object will not be updated. For nested objects that are not normalized with their own cache key, this will never occur, but if the nested object is an entity with its own cache key, it can be mutated independently. In that case, any other objects whose cache keys are dependent on the mutated entity will not be updated automatically. You must take care to update those entities manually with a cache mutation.

		2. The `object` passed to this function represents data for an object in an specific operation model, not a type in your schema. This means that [aliased fields](https://spec.graphql.org/draft/#sec-Field-Alias) will be keyed on their alias name, not the name of the field on the schema type.

		`directive @typePolicy(module: String!) repeatable on OBJECT \| INTERFACE`

		Adds an type policy to a type that can be used to resolve cache keys for objects of that type.

	Adds an type policy to a type that can be used to resolve cache keys for objects of that type.
	Adds a type policy to a type that can be used to resolve cache keys for objects of that type.

		### `@typePolicy(keyFields: String!)`

		`directive @typePolicy(module: String!) repeatable on OBJECT \| INTERFACE`

	`directive @typePolicy(module: String!) repeatable on OBJECT \| INTERFACE`
	`directive @typePolicy(keyFields: String!) on OBJECT \| INTERFACE`

Added documentation for @typePolicy #586

Added documentation for @typePolicy #586

Conversation

AnthonyMDev commented Jan 24, 2025

svc-apollo-docs commented Jan 24, 2025 • edited Loading

✅ Docs preview ready

netlify bot commented Jan 24, 2025 • edited Loading

✅ Deploy Preview for eclectic-pie-88a2ba ready!

netlify bot commented Jan 24, 2025 • edited Loading

✅ Deploy Preview for apollo-ios-docc canceled.

Meschreiber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

calvincestari commented Jan 27, 2025

Meschreiber Jan 27, 2025 • edited Loading

Choose a reason for hiding this comment

calvincestari left a comment

Choose a reason for hiding this comment

svc-apollo-docs commented Jan 24, 2025 •

edited

Loading

netlify bot commented Jan 24, 2025 •

edited

Loading

netlify bot commented Jan 24, 2025 •

edited

Loading

Meschreiber Jan 27, 2025 •

edited

Loading