docs: document SortRelatedRecordsMutation and the Mutation union

Author: runspired

warp-drive-packages/core/src/types/cache/mutations.ts

@@ -1,4 +1,8 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Cache } from '../cache.ts';
 import type { ResourceKey } from '../identifier.ts';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { Operation } from './operations.ts';
 
 export interface AddToResourceRelationshipMutation {
   op: 'add';
@@ -43,27 +47,51 @@ export interface ReplaceRelatedRecordsMutation {
   index?: number;
 }
 
+/**
+ * Reorders the local (uncommitted) state of a `to-many` relationship.
+ */
 export interface SortRelatedRecordsMutation {
+  /**
+   * The name of the mutation
+   */
   op: 'sortRelatedRecords';
+  /**
+   * The cache key for the resource whose relationship is being reordered
+   */
   record: ResourceKey;
+  /**
+   * The name of the relationship to reorder
+   */
   field: string;
+  /**
+   * The relationship's members in their new order
+   */
   value: ResourceKey[];
 }
-// A Mutation is an action that updates
-// the local state of the Cache in some
-// manner.
-// Most Mutations are in theory also
-// Operations; with the difference being
-// that the change should be applied as
-// "local" or "dirty" state instead of
-// as "remote" or "clean" state.
-//
-// Note: this RFC does not publicly surface
-// any of the mutations listed here as
-// "operations", though the (private) Graph
-// already expects and utilizes these.
-// and we look forward to an RFC that makes
-// the Graph a fully public API.
+
+/**
+ * A `Mutation` is an action that updates the local (uncommitted or "dirty")
+ * state of the {@link Cache} in some manner.
+ *
+ * Most Mutations are in theory also {@link Operation | Operations}; the
+ * difference is that the change should be applied as local/dirty state
+ * instead of as remote/clean state.
+ *
+ * Mutations are applied via {@link Cache.mutate}.
+ *
+ * See also:
+ * - {@link ReplaceRelatedRecordsMutation}
+ * - {@link ReplaceRelatedRecordMutation}
+ * - {@link RemoveFromResourceRelationshipMutation}
+ * - {@link AddToResourceRelationshipMutation}
+ * - {@link SortRelatedRecordsMutation}
+ *
+ * @privateRemarks
+ * Note: this RFC does not publicly surface any of the mutations listed
+ * here as "operations", though the (private) Graph already expects and
+ * utilizes these, and we look forward to an RFC that makes the Graph a
+ * fully public API.
+ */
 export type Mutation =
   | ReplaceRelatedRecordsMutation
   | ReplaceRelatedRecordMutation