feat: Add RestEndpoint.remove (#3623)

Author: ntucker

.changeset/shy-bugs-melt.md

@@ -0,0 +1,28 @@
+---
+'@data-client/rest': patch
+---
+
+Add RestEndpoint.remove
+
+Creates a PATCH endpoint that both removes an entity from a Collection and updates the entity with the provided body data.
+
+```ts
+const getTodos = new RestEndpoint({
+  path: '/todos',
+  schema: new schema.Collection([Todo]),
+});
+
+// Removes Todo from collection AND updates it with new data
+await ctrl.fetch(getTodos.remove, {}, { id: '123', title: 'Done', completed: true });
+```
+
+```ts
+// Remove user from group list and update their group
+await ctrl.fetch(
+  UserResource.getList.remove,
+  { group: 'five' },
+  { id: 2, username: 'user2', group: 'newgroup' }
+);
+// User is removed from the 'five' group list
+// AND the user entity is updated with group: 'newgroup'
+```

docs/rest/api/Collection.md

@@ -15,10 +15,10 @@ import { postFixtures,getInitialInterceptorData } from '@site/src/fixtures/posts
 
 `Collections` define mutable [Lists (Array)](./Array.md) or [Maps (Values)](./Values.md).
 
-This means they can grow and shrink. You can add to `Collection(Array)` with [.push](#push) or [.unshift](#unshift) and
-`Collections(Values)` with [.assign](#assign).
+This means they can grow and shrink. You can add to `Collection(Array)` with [.push](#push) or [.unshift](#unshift),
+remove from `Collection(Array)` with [.remove](#remove), and add to `Collections(Values)` with [.assign](#assign).
 
-[RestEndpoint](./RestEndpoint.md) provides [.push](./RestEndpoint.md#push), [.unshift](./RestEndpoint.md#unshift), [.assign](./RestEndpoint.md#assign)
+[RestEndpoint](./RestEndpoint.md) provides [.push](./RestEndpoint.md#push), [.unshift](./RestEndpoint.md#unshift), [.assign](./RestEndpoint.md#assign), [.remove](./RestEndpoint.md#remove)
 and [.getPage](./RestEndpoint.md#getpage)/ [.paginated()](./RestEndpoint.md#paginated) extenders when using `Collections`
 
 ## Usage

docs/rest/api/RestEndpoint.md

@@ -853,6 +853,23 @@ This is a convenience to add newly created Entities to a [Values](./Values.md) [
 When this `RestEndpoint`'s schema contains a [Collection](./Collection.md), this returned a new
 RestEndpoint with its parents properties, but with [method](#method): 'POST' and schema: [Collection.push](./Collection.md#assign)
 
+### remove
+
+This is a convenience to remove Entities from a [Collection](./Collection.md).
+
+When this `RestEndpoint`'s schema contains a [Collection](./Collection.md), this returns a new
+RestEndpoint with its parents properties, but with [method](#method): 'PATCH' and schema: [Collection.remove](./Collection.md#remove)
+
+```tsx
+const getTodos = new RestEndpoint({
+  path: '/todos',
+  schema: new schema.Collection([Todo]),
+});
+
+// Update Todo and remove from collection
+await ctrl.fetch(getTodos.remove, {}, { id: '123', title: 'Done' });
+```
+
 ### getPage
 
 An endpoint to retrieve the next page using [paginationField](#paginationfield) as the searchParameter key. Schema

packages/rest/src/RestEndpoint.js

@@ -267,6 +267,14 @@ Response (first 300 characters): ${text.substring(0, 300)}`;
       name: this.name + '.create',
     });
   }
+
+  get remove() {
+    return this.extend({
+      method: 'PATCH',
+      schema: extractCollection(this.schema, s => s.remove),
+      name: this.name + '.remove',
+    });
+  }
 }
 
 const tryParse = input => {

packages/rest/src/RestEndpointTypes.ts

@@ -185,6 +185,19 @@ export interface RestInstance<
       body: Record<string, OptionsToAdderBodyArgument<O>> | FormData;
     }
   >;
+  /** Remove item(s) (PATCH) from collection
+   * @see https://dataclient.io/rest/api/RestEndpoint#remove
+   */
+  remove: RemoveEndpoint<
+    F,
+    ExtractCollection<S>['remove'],
+    Exclude<O, 'body' | 'method'> & {
+      body:
+        | OptionsToAdderBodyArgument<O>
+        | OptionsToAdderBodyArgument<O>[]
+        | FormData;
+    }
+  >;
 }
 
 export type RestEndpointExtendOptions<
@@ -400,6 +413,28 @@ export type AddEndpoint<
   true,
   Omit<O, 'method'> & { method: 'POST' }
 >;
+export type RemoveEndpoint<
+  F extends FetchFunction = FetchFunction,
+  S extends Schema | undefined = any,
+  O extends {
+    path: string;
+    body: any;
+    searchParams?: any;
+  } = { path: string; body: any },
+> = RestInstanceBase<
+  RestFetch<
+    'searchParams' extends keyof O ?
+      O['searchParams'] extends undefined ?
+        PathArgs<Exclude<O['path'], undefined>>
+      : O['searchParams'] & PathArgs<Exclude<O['path'], undefined>>
+    : PathArgs<Exclude<O['path'], undefined>>,
+    O['body'],
+    ResolveType<F>
+  >,
+  S,
+  true,
+  Omit<O, 'method'> & { method: 'PATCH' }
+>;
 
 type OptionsBodyDefault<O extends RestGenerics> =
   'body' extends keyof O ? O

packages/rest/src/__tests__/RestEndpoint.ts

@@ -360,6 +360,10 @@ describe('RestEndpoint', () => {
     expect(getArticleList3.unshift.name).toMatchSnapshot();
   });
 
+  it('remove: should extend name of parent endpoint', () => {
+    expect(getArticleList3.remove.name).toMatchSnapshot();
+  });
+
   // TODO: but we need a Values collection
   // it('assign: should extend name of parent endpoint', () => {
   //   expect(getArticleList3.assign.name).toMatchSnapshot();
@@ -1482,6 +1486,20 @@ describe('RestEndpoint.fetch()', () => {
     expect(noColletionEndpoint.push.schema).toBeFalsy();
   });
 
+  it('without Collection in schema - endpoint.remove schema should be null', () => {
+    const noColletionEndpoint = new RestEndpoint({
+      urlPrefix: 'http://test.com/article-paginated/',
+      path: ':group',
+      name: 'get',
+      schema: {
+        nextPage: '',
+        data: { results: [PaginatedArticle] },
+      },
+      method: 'GET',
+    });
+    expect(noColletionEndpoint.remove.schema).toBeFalsy();
+  });
+
   it('without Collection in schema - endpoint.getPage should throw', () => {
     const noColletionEndpoint = new RestEndpoint({
       urlPrefix: 'http://test.com/article-paginated/',

packages/rest/src/__tests__/__snapshots__/RestEndpoint.ts.snap

@@ -4,6 +4,8 @@ exports[`RestEndpoint getPage: should extend name of parent endpoint 1`] = `"htt
 
 exports[`RestEndpoint push: should extend name of parent endpoint 1`] = `"http://test.com/article-paginated.create"`;
 
+exports[`RestEndpoint remove: should extend name of parent endpoint 1`] = `"http://test.com/article-paginated.remove"`;
+
 exports[`RestEndpoint unshift: should extend name of parent endpoint 1`] = `"http://test.com/article-paginated.create"`;
 
 exports[`RestEndpoint.fetch() should reject if content-type does not exist with schema 1`] = `[NetworkError: Unexpected text response for schema CoolerArticle]`;

packages/rest/src/__tests__/resource-construction.test.ts

@@ -24,6 +24,7 @@ describe('resource()', () => {
     readonly username: string = '';
     readonly email: string = '';
     readonly isAdmin: boolean = false;
+    readonly group: string = '';
 
     pk() {
       return this.id?.toString();
@@ -705,6 +706,112 @@ describe('resource()', () => {
       );
   });
 
+  it('UserResource.getList.remove should work', async () => {
+    mynock
+      .patch(`/groups/five/users`)
+      .reply(200, (uri, body: any) => ({ ...body }));
+
+    const { result, controller } = renderDataClient(
+      () => {
+        return {
+          user2: useQuery(User, { id: 2 }),
+          groupFive: useCache(UserResource.getList, { group: 'five' }),
+        };
+      },
+      {
+        initialFixtures: [
+          {
+            endpoint: UserResource.getList,
+            args: [{ group: 'five' }],
+            response: [
+              {
+                id: 1,
+                username: 'user1',
+                email: '[email protected]',
+                group: 'five',
+              },
+              {
+                id: 2,
+                username: 'user2',
+                email: '[email protected]',
+                group: 'five',
+              },
+            ],
+          },
+        ],
+      },
+    );
+
+    expect(result.current.groupFive).toEqual([
+      User.fromJS({
+        id: 1,
+        username: 'user1',
+        email: '[email protected]',
+        group: 'five',
+      }),
+      User.fromJS({
+        id: 2,
+        username: 'user2',
+        email: '[email protected]',
+        group: 'five',
+      }),
+    ]);
+
+    // Verify the remove endpoint can be called and completes successfully
+    await act(async () => {
+      const response = await controller.fetch(
+        UserResource.getList.remove,
+        { group: 'five' },
+        {
+          id: 2,
+          username: 'user2',
+          email: '[email protected]',
+          group: 'newgroup',
+        },
+      );
+      expect(response.id).toEqual(2);
+    });
+
+    // should remove the user from the list
+    expect(result.current.groupFive).toEqual([
+      User.fromJS({
+        id: 1,
+        username: 'user1',
+        email: '[email protected]',
+        group: 'five',
+      }),
+    ]);
+
+    // should also update the removed entity with the body data
+    expect(result.current.user2?.group).toEqual('newgroup');
+
+    () =>
+      controller.fetch(
+        UserResource.getList.remove,
+        // @ts-expect-error
+        { id: 'five' },
+        { id: 1 },
+      );
+    // @ts-expect-error
+    () => controller.fetch(UserResource.getList.remove, { username: 'never' });
+    // @ts-expect-error
+    () => controller.fetch(UserResource.getList.remove, 1, 'hi');
+    () =>
+      controller.fetch(
+        UserResource.getList.remove,
+        { group: 'five' },
+        // @ts-expect-error
+        { sdf: 'never' },
+      );
+    () =>
+      controller.fetch(
+        UserResource.getList.remove,
+        // @ts-expect-error
+        { sdf: 'five' },
+        { id: 1 },
+      );
+  });
+
   it.each([
     {
       response: {

packages/rest/src/extractCollection.ts

@@ -26,6 +26,7 @@ export type ExtractCollection<S extends Schema | undefined> =
       push: any;
       unshift: any;
       assign: any;
+      remove: any;
       schema: Schema;
     }
   ) ?