Correct Route Placeholder Useage with Typescript

[b-steel]

Reading the new docs I'm a bit curious about the best way to use route placeholders. How to declare them, how to use them in the client, how to get them to play nice with typescript, etc. My use case is we'd like our api to have both mobile/messages on which a find would return the messages for a user and admin/messages on which a find would return thing for all users. In this case I could register both endpoints but the route placeholders seems like it could be a handy solution.

For all my examples though I'm just using the one in the docs since it's nice and simple.

From the docs it says you can do

The path is a string that should be URL friendly and may contain / as a separator. path can also be / to register a service at the root level. A path may contain placeholders in the form of :userId/messages which will be included in params.route by a transport.

Question 1

First off I have a question about how I should pass the userId in this case when using the feathers client:

// Option a
client.service('messages').create('my message', {route:{userId:3}}) 
// Option b
client.service('3/messages').create('my message') 

Question 2

I have a problem with how the types are created and used (both in the server and the feathers client that can be used elsewhere). Basically if my servicePath includes a route placeholder then I have to add that servicePath to the service declarations to avoid having to put //@ts-ignore everywhere. But if I do that then when I call that service on a client it's very weird as well. I'll try to explain my possible scenarios below and I'm curious what you think is the best way to approach this or if there's something I'm missing.

Option 1: Route placeholder in the service path

I want to use

app.use(':userId/messages', new MessageService(getOptions(app), {})

but typescript doesn't like that unless I register it in the declarations the same way.

declare module '../declarations' {
  interface ServiceTypes {
    ':userId/messages': MessageTypes;
  }
}

Now everything works, but using the client is weird.

const client = getClient(transport)
client.service('messages') // <== typescript throws an error
client.service(':userId/messages') // <== typescript is fine but this is a bit weird

Option 2: Declare both services

Just like option 1 but in the services declaration it would be

declare module '../declarations' {
  interface ServiceTypes {
    ':userId/messages': MessageTypes;
    'messages': MessageTypes;
  }
}

which would tell typescript to allow the client to be used with client.service('messages) which is nice but there's some pollution of the autocompletion options with :userId/messages. That's not that big a deal though, I can work with that.

However, due to the two options that typescript allows, I'm curious about how I could run into trouble in the feathers app itself. Lets say in my feathers app I now call app.service('messages'), what will happen. I didn't register anything on this endpoint (I just added it to the declarations), will it still go to the messages endpoint but with userId:undefined or will something break? This is slightly related to my first question about how to call services with route placeholders.

Option 3: something else

In the example I could just put the userId in a query such as `client.service('messages').find({query:{userId:3}}). Or in my case since it's more of a global param for all interactions I could put it in the request headers and that might solve my issues.

Summary

Overall just wanted to get an answer to my question about how to use the route placeholder when calling a service and then see if you had any insights about how to deal with those typescript problems that each option brought up (or not if that's just how it is dealing with typescript).

Thanks for all the great stuff y'all are doing, this is a great project and I'm really excited about the schemas and typescript support that's coming with dove.

[daffl]

I think part of the issue is that there is an inconsistency between using placeholders on the client vs. the server. I'm not even sure if the placeholder would work on the client but you can definitely do

const client = getClient(transport)

client.service('3/messages')

The problem is that this can't be typed other than

import type { Service } from '@feathersjs/feathers'

declare module '../declarations' {
  interface ServiceTypes {
    [key: string]: Service;
  }
}

Since this is really a TypeScript limitation I don't think there is much that can be done here other than keeping things flat like suggested in the FAQ.

[b-steel]

Thanks for the info, it does seem like we're doing something a bit off with the non-flat route, I'll look into some other options

[b-steel]

For now I've just punted the issue down the road and haven't done much, but when I do I'll likely do as @daffl suggested (from the FAQ) and flatten the routes out and just use queries for things.

[daffl]

Being able to replace placeholders on the client was actually something I've been thinking about before. It would be a good feature to have and I think this can be done by updating the makeUrl function with params.route as the second parameter. Probably something like this:

  makeUrl(query: Query, id?: string | number | null, route?: { [key: string]: string }) {
    let url = this.base

    if (route) {
      Object.keys(route).forEach(key => {
        url = url.replace(`:${key}`, route[key])
      })
    }

    query = query || {}

    if (typeof id !== 'undefined' && id !== null) {
      url += `/${encodeURIComponent(id)}`
    }

    return url + this.getQuery(query)
  }

[mdartic]

Nice, I can make a PR for this feature if you think it's a good idea, and add some tests ?

[daffl]

That would be great. We'd probably want to do the same thing for the Socket.io client as well.

[mdartic]

I create the PR #3270 for the rest-client.
For the socket.io client, I don't really know how to handle it.
I'm gonna test it (as I never use it until... now ;-) ) and maybe I will ask for some help.