Make Schema and Hooks the two hero's in Dove - some cli adjustment

After a great exchange of ideas with @daffl, the other day, I am submitting some revelations here, to wrap up. There is some low-hanging fruit that might help 5.0.0. to become not only very powerful but with a low threshold as well. I assume it will take none or hardly any code changes, only some cli and documentation.

There is a long list of unique selling points for Feathers, fast, and light-weight,... but what stands out for me are just two:

powerful typing Schema
compact Hooks with clearly understandable purposes

@philipimperato gave an excellent list of what these abilities can bring to your code.

When I look through the Discord discussions I see a lot of questions that, IMHO, arise from "self-inflicted wounds". It might be the transition paradigm to strong typed code we all went through. So, could we can make things more clear for newbies with a few little adjustments in the cli?

Separate hooks-file per service

Here I like to vote for pulling out the hooks code from the messages.ts to a new message.hooks.ts. The reason is that you usually only touch messages.ts once during setup, and you want that file as clean as possible to avoid mistakes. Hooks however you develop with all the time; so can use its own file.

Hooks folder

Seeing Hooks and Schema's as the two pillars Feathers stands on, I think we should standardize a hooks folder containing all the custom hooks. An index.ts will make them available to the parent hooks file.

Isolate Schema

The Schema is in Dove much more than it was in v4. It not only determines the database structure but also provides typing all over the app. Sublime! Much so, that it deserves to get the file just for itself, so let's isolate the Resolvers:

Resolvers

It took me some months (shame), but it now occurs to me that Resolvers are nothing else than advanced hooks. So, in the new setup, let us put them where they belong: in the hooks folder.

Resolver inclusion

For the hooks file, I would suggest not including the resolvers by default, but only as commented code suggestion. This signals to new users that resolvers are optional but still encouraged.

Finally

It's all just documentation and a bit of cli, I think, that would give us for each newly generated service:

/src/services/messages/
   hooks/
      my-first-hook.ts
      messagesDataResolver.ts
      messagesQueryResolver.ts
   messages.ts
   messages.hooks.ts
   messages.schema.ts
   messages.class.ts

I wish I could contribute more, but I am heading a new startup with great joy. Still, one day soon I like to volunteer for a marketing strategy for Feathers: a mastodon that can stand firm.

Thanks for summarizing this in an issue @tvld. This has made me understand your points better, here is what I think:

Separate hooks-file per service: I agree. Hooks tend to grow, its best to separate them from the start into a separate <service>/<service>.hooks.ts file.
Hooks folder: I agree. That's what I ended up doing to keep common hooks together. Hooks deserve a folder. This is already done by the CLI which creates the src/hooks/log-error.ts hook. So I think theres nothing to do here...
Isolate Schema I think I agree. The schema files are huge, even with typebox. And resolvers sort of get in the way when working with schemas, and schemas get in the way when working with resolvers. Maybe separating them (especially since resolvers are optional, this isn't clear when keeping them together) is best. However, they are very related, so keeping them together also makes sense in this way, but it definitively makes the .schema.ts files way harder to understand/skim-through especially at the start.
Resolvers: I think I agree. Not sure if they should go alongside hooks, or in their separate file/folder. But it is true they are "advanced hooks", so it would make sense to treat them as such, especially if we want to make clear the notion that resolvers are optional.
Resolver inclusion: I think I agree. Most of the debug work after porting from v4 to v5 was due to schemas. Having the resolvers commented-out by default would definitively help users starting out generating with the CLI to get it to work, before trying to make it perfect. Whenever you are ready to get the full benefits, simply comment it out, service-per-service event, this should make migration easier. If you prefer not using resolvers, then you can simply delete them (instead of having them polluting the .schema.ts file like they do now.

My biggest takeaway form this discussion: resolvers are simply (optional) "advanced hooks", it might be best to treat them as hooks altogether. In this way, thinking about feathers remains crow-like "lightweight" (feathers = services + schemas + hooks) instead of bloating the "essential" concepts with the new (and very cool and powerful) dove features (feathers = services + schemas + resolvers + hooks + ...). This way feathers remains feathers, the concepts are the same an as easy to grasp as before.

Another though: regarding update method which was removed from the CLI generated app by default. Is this a result of wanting to lean-out the schemas (to not have both patch and update, but only patch) as they can accomplish sort of the same? Or was there another valid reason for removing update method by default? I used to like how before, you would get ALL methods by default when generating a new service, and then you could remove some, or none. I feel this was motivated primarly in order to not have two schemas, one for path and another for update.

@miguelrk Thanks and I do agree with your summaries.
About the update; I disable them by default, so did not miss them. I suppose for some atomic purposes they could still be used, but I don't have any examples.

Interesting thoughts, I found myself close to what @tvld summarize.

I don't know if this could be useful, but here are what I'm doing actually with the v5 :

As I'm still learning the "Dove way" of thinking, I'm still asking myself where I have to put this sheet of code. (between resolver, or hook, mainly) For cleaning my brain, I separate files like this :

[myservice]/__mocks__ // if needed
[myservice]/[myservice].class.ts // the service, as a KnexAdapter or other
[myservice]/[myservice].abilities.ts // where the defineAbilities / casl stuff is
[myservice]/[myservice].hooks.ts // hooks definition
[myservice]/[myservice].schemas.ts // the typebox definition
[myservice]/[myservice].resolvers.ts
[myservice]/[myservice].service.ts // the configuration function given to app in services/index.ts
[myservice]/[myservice].test.ts // all the tests of the service

Using objection, I create a last file, the [myservice].model.ts that is the objection model.

I do like to rename my [myservice].service.ts in a more [myservice].ts as it could be clearer that it's the "default" file to load. It takes me some time in the crow/dove versions to understand differences between a file named service.ts and a class.ts, as the class.ts was containing a... service ! And, well, maybe this is the default now ? (I don't use so much the CLI...)

Concerning the hook folder, I find useful to have a dedicated src/hooks for commons hooks. For hooks used exclusively by the service itself, a dedicated [myservice]/[myhook].hook.ts is available, with a dedicated .test.ts file too.

A file is missing in [myservice] folder, it's the [myservice].shared.ts. I'm still learning on the api side, I don't investigate too much for now on the client side.

I agree with @miguelrk takeaway. Maybe too much files can create confusion for newcomers. Separation of concerns seems ok for me, maybe harder when we discover feathers ?

Don't know if those thoughts were useful, but that was my 2 cents ;-)

feathersjs / feathers