I think APISchema is a better name for this. I also think we should change the name of the generic Endpoint being used in the definition of Router up above to API as well.

It just makes more sense as we construct a router with an api.

const router = new Router(api)

I think API makes sense for the root-level object, but what about something like /clubs? It makes more sense (to me, at least) to call that an endpoint

Maybe I can create a typealias APISchema = EndpointSchema so we get the best of both names 🤔

But this interface describes our entire api, not just a single endpoint. It would make more sense to name the actual endpoint EndpointSchema.

Wait..are EndpointSchema and Children's definition mutually recursive?

Wait..are EndpointSchema and Children's definition mutually recursive?

Yep! The /clubs endpoint is also a fully-fledged Endpoint schema. /clubs/:id would be yet another layer in, but it also has an Endpoint schema. Altogether, it forms a tree, with our base API as the root.

That's why it's challenging to come up with a good name for things. I wouldn't really call the root API an "endpoint", but it quacks and walks like one. /clubs/:id sounds much more like an endpoint to me.

Since I never formally learned web dev, I don't really know what the proper terminology is. Are / and /clubs and /club/:id "endpoints" or "APIs"?

Since I never formally learned web dev, I don't really know what the proper terminology is. Are / and /clubs and /club/:id "endpoints" or "APIs"?

My definition is the "API" is the structure, grouping, and schema of all "endpoints".

Ok, then we can stick to "Endpoint".

Following your definition, maybe this makes sense:

type API = {
  root: Endpoint
}

Yeah I like that!

It would be clean if we could extract the body of the root endpoints into an API as well.

const API = {
  root: rootAPI,
  children: {
    '/clubs': clubsAPI,
    '/users': usersAPI
  }
}

What does the rootAPI object look like?

Same thing as clubsAPI, this would require changing the definition of EndpointSchema

const rootAPI = {
  methods: {
    get: {
      response: {
        body: t.literal('Water water water, loo loo loo'),
      },
    },
  },
}

So we're just moving .methods into .root.methods? This is adding more nesting on top of what is already too much nesting

Yes it adds more nesting and makes the type defs more messy, but I'd argue the overall shape and readability of our API object will be cleaner and easier to grok. I'll let you make the final decision on this one though.

Maybe we only do it on the root API object, as suggested here: #85 (comment)

Then we have

const rootEndpoint = {
  methods: {
    get: ...
  }
  children: {
    '/clubs': clubsEndpoint
  }
}

const api = {
  root: rootEndpoint
}

Yeah sounds good.

Matcher in the name TypedMatcher doesn't make any sense re: web development and API servers. The names of types that include API, Endpoint, Router etc make sense. TypedMatcher is too abstract, can we come up with a better name for this type?

It comes from Express itself, where the type is called RouterMatcher. I agree it's quite obscure, but I can't think of a better name. After all, it does match a path and direct control to a handler.

Why do we need this intermediary class of TypedAPIError along the class hierarchy chain? Can we just have FrozenRouterError and UnhandledPathError extend directly from Error?

At the moment it's functionally the same, but imagine if we want every API type runtime error to do something common (e.g. print out the endpoint). Then having that base class there would be useful. I'm just jumping the gun and doing it in advance.

Why do we need to freeze a Router? Is this to support statically checking if we have a handler for each of our API endpoints?

I'm trying to model (in runtime, for now) what we might eventually do in compile time. After you freeze a router, you shouldn't be able to modify it. A file might define a clubRouter and export clubRouter.freeze(), so that other files that import it can't modify it.

If Endpoint (the API Schema) is the root object aka Endpoint extends { methods: Schema.Methods } is true, why is the second value of the turnury expression the | of keyof Endpoint['children'] and Schema.RootPath?

So this is the weird thing about Endpoint. The .methods field corresponds to the methods available at the / endpoint. The .children field corresponds to the endpoints for the children. It's messy, but the / endpoint is fundamentally different from all the others in the sense that it can't have any further children.

Schema.RootPath is /, so this just means "if the endpoint has a .methods, then it supports the / path as well as all of its children"

Why do all the generic Paths in the Routers all/get/post/etc extend Get.Path? Do we have to create a different namespace for all the different http verbs?

So Get is the (possibly misnamed, open to suggestions) namespace for the utility that gets things from endpoints.

Get.Path<Endpoint> is the type that represents all paths you can take from Endpoint. It doesn't have anything to do with the HTTP verb GET.

Why do we need Partial<T> here?

I'm not sure actually, it's to signify that not every Path is guaranteed to be in .children. I'm not sure if this happens by default in Record, I didn't check

Did some looking into it; the code works without the Partial here. However, if you remove Partial from the definition of the similar Methods type, it won't work. If your type has a finite number of values (like MethodName), then Typescript expects every value to be a property in the corresponding record. Removing the Partial in the definition of Children works because there are infinitely many possible Paths.

tl;dr: if you want a record type where all the keys are optional, Partial<Record<K, V>> always works. Depending on K, you can sometimes get away with just doing Record<K, V>. To be safe, stick to always wrapping a Partial around your type, so that way your type definition works regardless of K.