feat: Add controller.set() (#3105)

Author: ntucker

.changeset/big-jars-drum.md

@@ -0,0 +1,7 @@
+---
+'@data-client/test': patch
+'@data-client/img': patch
+'@data-client/ssr': patch
+---
+
+Support 0.13 of @data-client/react

.changeset/empty-shoes-crash.md

@@ -0,0 +1,14 @@
+---
+'@data-client/react': minor
+'@data-client/core': minor
+---
+
+Add controller.set()
+
+```ts
+ctrl.set(Todo, { id: '5' }, { id: '5', title: 'tell me friends how great Data Client is' });
+```
+
+BREAKING CHANGE:
+- actionTypes.SET_TYPE -> actionTypes.SET_RESPONSE_TYPE
+- SetAction -> SetResponseAction

docs/core/api/Controller.md

@@ -31,6 +31,7 @@ class Controller {
   invalidate(endpoint, ...args): Promise<void>;
   invalidateAll({ testKey }): Promise<void>;
   resetEntireStore(): Promise<void>;
+  set(queryable, ...args, response): Promise<void>;
   setResponse(endpoint, ...args, response): Promise<void>;
   setError(endpoint, ...args, error): Promise<void>;
   resolve(endpoint, { args, response, fetchedAt, error }): Promise<void>;
@@ -358,6 +359,14 @@ function UserName() {
 }
 ```
 
+## set(queryable, ...args, value) {#set}
+
+Updates any [Queryable](/rest/api/schema#queryable) [Schema](/rest/api/schema#schema-overview).
+
+```ts
+ctrl.set(Todo, { id: '5' }, { id: '5', title: 'tell me friends how great Data Client is' });
+```
+
 ## setResponse(endpoint, ...args, response) {#setResponse}
 
 Stores `response` in cache for given [Endpoint](/rest/api/Endpoint) and args.

packages/core/src/actionTypes.ts

@@ -1,5 +1,6 @@
 export const FETCH_TYPE = 'rdc/fetch' as const;
 export const SET_TYPE = 'rdc/set' as const;
+export const SET_RESPONSE_TYPE = 'rdc/setresponse' as const;
 export const OPTIMISTIC_TYPE = 'rdc/optimistic' as const;
 export const RESET_TYPE = 'rdc/reset' as const;
 export const SUBSCRIBE_TYPE = 'rdc/subscribe' as const;

packages/core/src/actions.ts

@@ -1,5 +1,7 @@
 import type {
+  Denormalize,
   EndpointInterface,
+  Queryable,
   ResolveType,
   UnknownError,
 } from '@data-client/normalizr';
@@ -15,6 +17,7 @@ import type {
   OPTIMISTIC_TYPE,
   INVALIDATEALL_TYPE,
   EXPIREALL_TYPE,
+  SET_RESPONSE_TYPE,
 } from './actionTypes.js';
 import type { EndpointUpdateFunction } from './controller/types.js';
 
@@ -27,33 +30,48 @@ type EndpointDefault = EndpointInterface & {
 
 /* SET */
 export interface SetMeta {
+  args: readonly any[];
+  fetchedAt: number;
+  date: number;
+  expiresAt: number;
+}
+
+export interface SetAction<S extends Queryable = any> {
+  type: typeof SET_TYPE;
+  schema: S;
+  meta: SetMeta;
+  value: Denormalize<S>;
+}
+
+/* setResponse */
+export interface SetResponseMeta {
   args: readonly any[];
   key: string;
   fetchedAt: number;
   date: number;
   expiresAt: number;
 }
-export interface SetActionSuccess<
+export interface SetResponseActionSuccess<
   E extends EndpointAndUpdate<E> = EndpointDefault,
 > {
-  type: typeof SET_TYPE;
+  type: typeof SET_RESPONSE_TYPE;
   endpoint: E;
-  meta: SetMeta;
+  meta: SetResponseMeta;
   payload: ResolveType<E>;
   error?: false;
 }
-export interface SetActionError<
+export interface SetResponseActionError<
   E extends EndpointAndUpdate<E> = EndpointDefault,
 > {
-  type: typeof SET_TYPE;
+  type: typeof SET_RESPONSE_TYPE;
   endpoint: E;
-  meta: SetMeta;
+  meta: SetResponseMeta;
   payload: UnknownError;
   error: true;
 }
-export type SetAction<E extends EndpointAndUpdate<E> = EndpointDefault> =
-  | SetActionSuccess<E>
-  | SetActionError<E>;
+export type SetResponseAction<
+  E extends EndpointAndUpdate<E> = EndpointDefault,
+> = SetResponseActionSuccess<E> | SetResponseActionError<E>;
 
 /* FETCH */
 export interface FetchMeta<A extends readonly any[] = readonly any[]> {
@@ -81,7 +99,7 @@ export interface OptimisticAction<
 > {
   type: typeof OPTIMISTIC_TYPE;
   endpoint: E;
-  meta: SetMeta;
+  meta: SetResponseMeta;
   error?: false;
 }
 
@@ -144,6 +162,7 @@ export type ActionTypes =
   | FetchAction
   | OptimisticAction
   | SetAction
+  | SetResponseAction
   | SubscribeAction
   | UnsubscribeAction
   | InvalidateAction

packages/core/src/controller/Controller.ts

@@ -5,7 +5,6 @@ import type {
   Denormalize,
   Queryable,
   SchemaArgs,
-  NI,
 } from '@data-client/normalizr';
 import {
   ExpiryStatus,
@@ -27,6 +26,7 @@ import createInvalidate from './createInvalidate.js';
 import createInvalidateAll from './createInvalidateAll.js';
 import createReset from './createReset.js';
 import createSet from './createSet.js';
+import createSetResponse from './createSetResponse.js';
 import {
   createUnsubscription,
   createSubscription,
@@ -183,9 +183,26 @@ export default class Controller<
   resetEntireStore = (): Promise<void> => this.dispatch(createReset());
 
   /**
-   * Stores response in cache for given Endpoint and args.
+   * Sets value for the Queryable and args.
    * @see https://dataclient.io/docs/api/Controller#set
    */
+  set = <S extends Queryable>(
+    schema: S,
+    ...rest: readonly [...SchemaArgs<S>, any]
+  ): Promise<void> => {
+    const value: Denormalize<S> = rest[rest.length - 1];
+    const action = createSet(schema, {
+      args: rest.slice(0, rest.length - 1) as SchemaArgs<S>,
+      value,
+    });
+    // TODO: reject with error if this fails in reducer
+    return this.dispatch(action);
+  };
+
+  /**
+   * Sets response for the Endpoint and args.
+   * @see https://dataclient.io/docs/api/Controller#setResponse
+   */
   setResponse = <
     E extends EndpointInterface & {
       update?: EndpointUpdateFunction<E>;
@@ -195,15 +212,15 @@ export default class Controller<
     ...rest: readonly [...Parameters<E>, any]
   ): Promise<void> => {
     const response: ResolveType<E> = rest[rest.length - 1];
-    const action = createSet(endpoint, {
+    const action = createSetResponse(endpoint, {
       args: rest.slice(0, rest.length - 1) as Parameters<E>,
       response,
     });
     return this.dispatch(action);
   };
 
   /**
-   * Stores the result of Endpoint and args as the error provided.
+   * Sets an error response for the Endpoint and args.
    * @see https://dataclient.io/docs/api/Controller#setError
    */
   setError = <
@@ -215,7 +232,7 @@ export default class Controller<
     ...rest: readonly [...Parameters<E>, Error]
   ): Promise<void> => {
     const response: Error = rest[rest.length - 1];
-    const action = createSet(endpoint, {
+    const action = createSetResponse(endpoint, {
       args: rest.slice(0, rest.length - 1) as Parameters<E>,
       response,
       error: true,
@@ -247,7 +264,7 @@ export default class Controller<
           error?: false | undefined;
         },
   ): Promise<void> => {
-    return this.dispatch(createSet(endpoint, meta as any));
+    return this.dispatch(createSetResponse(endpoint, meta as any));
   };
 
   /**

packages/core/src/controller/createSet.ts

@@ -1,60 +1,22 @@
-import type { EndpointInterface, ResolveType } from '@data-client/normalizr';
+import type { Queryable, SchemaArgs } from '@data-client/normalizr';
 
 import ensurePojo from './ensurePojo.js';
-import { EndpointUpdateFunction } from './types.js';
 import { SET_TYPE } from '../actionTypes.js';
 import type { SetAction, SetMeta } from '../types.js';
 
-export default function createSet<
-  E extends EndpointInterface & {
-    update?: EndpointUpdateFunction<E>;
-  },
->(
-  endpoint: E,
-  options: {
-    args: readonly [...Parameters<E>];
-    response: Error;
-    fetchedAt?: number;
-    error: true;
-  },
-): SetAction<E>;
-
-export default function createSet<
-  E extends EndpointInterface & {
-    update?: EndpointUpdateFunction<E>;
-  },
->(
-  endpoint: E,
-  options: {
-    args: readonly [...Parameters<E>];
-    response: ResolveType<E>;
-    fetchedAt?: number;
-    error?: false;
-  },
-): SetAction<E>;
-
-export default function createSet<
-  E extends EndpointInterface & {
-    update?: EndpointUpdateFunction<E>;
-  },
->(
-  endpoint: E,
+export default function createSet<S extends Queryable>(
+  schema: S,
   {
     args,
     fetchedAt,
-    response,
-    error = false,
+    value,
   }: {
-    args: readonly [...Parameters<E>];
-    response: any;
+    args: readonly [...SchemaArgs<S>];
+    value: any;
     fetchedAt?: number;
-    error?: boolean;
   },
-): SetAction<E> {
-  const expiryLength: number =
-    error ?
-      endpoint.errorExpiryLength ?? 1000
-    : endpoint.dataExpiryLength ?? 60000;
+): SetAction<S> {
+  const expiryLength: number = 60000;
   /* istanbul ignore next */
   if (process.env.NODE_ENV === 'development' && expiryLength < 0) {
     throw new Error('Negative expiry length are not allowed.');
@@ -65,15 +27,13 @@ export default function createSet<
     fetchedAt: fetchedAt ?? now,
     date: now,
     expiresAt: now + expiryLength,
-    key: endpoint.key(...args),
   };
 
-  const action: SetAction<E> = {
+  const action: SetAction<S> = {
     type: SET_TYPE,
-    payload: response,
-    endpoint: endpoint,
+    value,
+    schema,
     meta,
   };
-  if (error) (action as any).error = true;
   return action;
 }

packages/core/src/controller/createSetResponse.ts

@@ -0,0 +1,79 @@
+import type { EndpointInterface, ResolveType } from '@data-client/normalizr';
+
+import ensurePojo from './ensurePojo.js';
+import { EndpointUpdateFunction } from './types.js';
+import { SET_RESPONSE_TYPE } from '../actionTypes.js';
+import type { SetResponseAction, SetResponseMeta } from '../types.js';
+
+export default function createSetResponse<
+  E extends EndpointInterface & {
+    update?: EndpointUpdateFunction<E>;
+  },
+>(
+  endpoint: E,
+  options: {
+    args: readonly [...Parameters<E>];
+    response: Error;
+    fetchedAt?: number;
+    error: true;
+  },
+): SetResponseAction<E>;
+
+export default function createSetResponse<
+  E extends EndpointInterface & {
+    update?: EndpointUpdateFunction<E>;
+  },
+>(
+  endpoint: E,
+  options: {
+    args: readonly [...Parameters<E>];
+    response: ResolveType<E>;
+    fetchedAt?: number;
+    error?: false;
+  },
+): SetResponseAction<E>;
+
+export default function createSetResponse<
+  E extends EndpointInterface & {
+    update?: EndpointUpdateFunction<E>;
+  },
+>(
+  endpoint: E,
+  {
+    args,
+    fetchedAt,
+    response,
+    error = false,
+  }: {
+    args: readonly [...Parameters<E>];
+    response: any;
+    fetchedAt?: number;
+    error?: boolean;
+  },
+): SetResponseAction<E> {
+  const expiryLength: number =
+    error ?
+      endpoint.errorExpiryLength ?? 1000
+    : endpoint.dataExpiryLength ?? 60000;
+  /* istanbul ignore next */
+  if (process.env.NODE_ENV === 'development' && expiryLength < 0) {
+    throw new Error('Negative expiry length are not allowed.');
+  }
+  const now = Date.now();
+  const meta: SetResponseMeta = {
+    args: args.map(ensurePojo),
+    fetchedAt: fetchedAt ?? now,
+    date: now,
+    expiresAt: now + expiryLength,
+    key: endpoint.key(...args),
+  };
+
+  const action: SetResponseAction<E> = {
+    type: SET_RESPONSE_TYPE,
+    payload: response,
+    endpoint: endpoint,
+    meta,
+  };
+  if (error) (action as any).error = true;
+  return action;
+}