Dove CLI Generated Boilerplate Confusion

[jamesvillarrubia]

First...
I'm ramping up a new project and decided to test out v5. The CLI generated the service, class, resolver, and schema files. They are (particularly with typescript) pretty dense. My concern is with ramping up my team on Feathers v5 in the future. I've had success before because Feathers cli generated service were pretty light compared to the boilerplate of Nest, etc.

Is there any plan to lean down the templates or abstract out default resolvers and schema functions and allow for overrides? Now my team will have to learn what to do with 4 schemas, 4 resolvers, and 4 hook types. Before... 80% of building service was writing hooks in separate files and layering in the structure in the .hooks file. One of the benefits to Feathers that my teams liked was that it was easy to pickup and hard to screw up. I'm worried about the added upfront complexity leading to worse code and influencing adoption.

Second...
To be honest, I'm still unclear myself about the order of operations and intended purposes for hooks, resolvers, validations, properties, converters, etc. I'm basically using trial and error to figure it out. It seems like what used to be in hooks can now be in like 5 places, but the right/intended place to do any one thing is unclear in the docs. Is there anyway we could get to some sort of flow diagram of the various steps? Here's roughly the flow as I understand it:

Middleware Before service()
    Service() /buttons/{id}

        [HOOKS]
        Hook Around() before next
            Hook Before()

                [DataResolver (DR)]
                DR - Validate Before
                    DR - Converter()
                         DR - Property ()
                            DR - Validate After

                                [DB Adapter]
                                    create/update/patch/get/find/delete
                                
                                [HOOKS]
                                Hook Error (if applicable)

                            [Result Resolver (RR)]
                            RR - Validate Before
                        RR - Converter()
                    RR - Property()
                RR - Validate After
            
            [HOOKS]
            Hook After
        Hooks Around() after next
    
Middleware After Service

[daffl]

As you mentioned I think a few of those points are things that should be added to the documentation specifically to the CLI guide (https://dove.feathersjs.com/guides/cli/index.html) I am working on. Since hooks still work as is (in addition to the new - but as always entirely optional - hook type that allows to control a before, after and error flow in the same hook function), everything done in schemas and resolvers can still also be done in hooks (in fact, both schema validation and resolvers are just a hook and part of the flow as can be seen e.g. in https://github.com/feathersjs/feathers-chat/blob/dove/typescript-api/src/services/messages/messages.class.ts#L10). A basic description of the hook flow can be found in https://dove.feathersjs.com/api/hooks.html#hook-flow - I am talking to our designer about adding more diagrams for this as well.

However schemas and resolvers do address several things that have been a persistent source of confusion and potential security problems in Feathers and that were causing issues both for beginners and in larger more advanced app:

• Having things open by default, even if it is documented, led to many insecure applications where developers just ended up allowing any authenticated user to do anything. Now all security restrictions can be kept together in one resolver file, allowing to e.g. easily limit the request to the current user or prevent certain users from editing or seeing certain properties.
• Populating related entities was cumbersome - and sending them to external clients securely even more so. Resolvers have a built-in way that always ensures that only secure data is sent to clients both, in responses (even when nested) and in real-time events.
• Large hook chains can be difficult to debug and follow, spreading the data model and validation across many different files. Being able to look at how all data is processed in two files made things a lot more concise - even if it is initially more boilerplate.
• Not having a data or query schema led to reinventing a few wheels to improve security like setting multi: true in the adapters and a custom configuration for sanitising queries. A lot of this can be avoided with a standardised validation system.
• The common JSON schema format is very powerful from auto-generating API specs to inferring TypeScript types that can even be used in client apps (most everybody else is still duplicating their data model and types in one form or another)

As an example, here is the populating the user code from the v4 chat guide:

// Use this hook to manipulate incoming or outgoing data.
// For more information on hooks see: http://docs.feathersjs.com/api/hooks.html
import { Hook, HookContext } from '@feathersjs/feathers';

export default (): Hook => {
  return async (context: HookContext) => {
    // Get `app`, `method`, `params` and `result` from the hook context
    const { app, method, result, params } = context;
    // Function that adds the user to a single message object
    const addUser = async (message: any) => {
      // Get the user based on their id, pass the `params` along so
      // that we get a safe version of the user data
      const user = await app.service('users').get(message.userId, params);

      // Merge the message content to include the `user` object
      return {
        ...message,
        user
      };
    };

    // In a find method we need to process the entire page
    if (method === 'find') {
      // Map all data to include the `user` information
      context.result.data = await Promise.all(result.data.map(addUser));
    } else {
      // Otherwise just update the single result
      context.result = await addUser(result);
    }

    return context;
  };
}

There is a lot going on here and you kind of really have to know about Feathers internals - e.g. how to process the data differently on find, that the response is in context.result etc. This specific hook won't even work anymore if you e.g. disable pagination.

In a resolver it looks like this:

// Resolver for the data that is being returned
export const messagesResultResolver = resolve<MessagesResult, HookContext>({
  schema: messagesResultSchema,
  validate: false,
  properties: {
    user: async (_value, message, context) => {
      // Associate the user that sent the message
      return context.app.service('users').get(message.userId)
    }
  }
})

I found this pattern repeated in many different places that I used schemas in. A multi line hook or even an entire separate library (like authentication hooks or the various populate libraries) could be replaced with a one- or two-line resolver. If felt very similar to how the Feathers service concept got rid of a lot of the boilerplate you'd have to do in other more traditional API frameworks.

As for how to look at it conceptually my rule of thumb (that I will also document more) is:

• Schemas for the data type definitions
• Resolvers for setting properties based on a context. A resolver should have no side effects which means that it only returns a data value and should never modify or create any data.
• Hooks for side effects like modifying data, sending an email, logging, profiling etc.

[jamesvillarrubia]

This is very helpful, thank you. I saw reference to "converters" in the resolver docs as well. How should I consider those?

[daffl]

It basically allows you to convert one kind of data to a completely different format. The properties resolvers will run on the converted data. One use case for this would be using the event sourcing pattern.