RFC: createResource() per-endpoint customization option

[ntucker]

Adding endpoints option to createResource.

This is a specialization that reduces the verbosity of the common case of simple endpoint customizations, additional endpoints, or excluding default endpoints.

Before

const BaseTodoResource = createResource({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
  schema: Todo,
});
export const TodoResource = {
  ...BaseTodoResource,
  getList: BaseTodoResource.getList.extend({
    process(todos) {
      // for demo purposes we'll only use the first seven
      return todos.slice(0, 7);
    },
  }),
  partialUpdate: BaseTodoResource.partialUpdate.extend({
    getOptimisticResponse(snap, { id }, body) {
      return {
        id,
        ...body,
      };
    },
  }),
  delete: BaseTodoResource.delete.extend({
    getOptimisticResponse(snap, params) {
      return params;
    },
  }),
  queryRemaining: new Query(
    new schema.All(Todo),
    (entries, { userId } = {}) => {
      if (userId !== undefined)
        return entries.filter(todo => todo.userId === userId && !todo.completed)
          .length;
      return entries.filter(todo => !todo.completed).length;
    },
  ),
};

After

const TodoResource = createResource({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
  schema: Todo,
  endpoints: {
    getList: {
      process(todos) {
        return todos.slice(0, 7);
      },
    },
    partialUpdate: {
      getOptimisticResponse(snap, params, body) {
        return {
          id: params.id,
          ...body,
        };
      },
    },
    delete: {
      getOptimisticResponse(snap, params) {
        return params;
      },
    },
    // exclude update
    update: null,
    // add a new endpoint
    current: {
      path: '/todo',
      schema: Todo,
    },
    // sending a non-POJO lets you use other 'Endpoint constructors' like Query
    queryRemaining: new Query(
        new schema.All(Todo),
        (entries, { userId } = {}) => {
          if (userId !== undefined)
            return entries.filter(todo => todo.userId === userId && !todo.completed)
              .length;
          return entries.filter(todo => !todo.completed).length;
        },
      )
    }
  }
});

Design choices

We chose a named option vs second arg mainly due to the way formatters behave (prettier) making it way too indented. This also has the advantage of easily allowing further customizations by different names

Credits

@Dav3rs

[taystack]

Would it be more consistent to extend the custom endpoints with the parent's values automatically?

const TodoResource = createResource({
  schema: Todo,
  endpoints: {
    current: {
      path: '/todo',
      // schema: Todo <-- implicitly extends parent's values.
    }
  },
})

[ntucker]

Final solution in #2715