[shiny]

I'm working on a similar thing, tho I don't intend to extract it into a library (yet). I was inspired by Gary Bernhardt's blog post [1] and video [2].

I have an endpoints.ts file, shared between client/server, which has something like:

  export type Endpoints = {
    createProduct: {
      path: '/api/products.json';
      method: 'POST';
      clientSends: { name: string };
      serverResponds: ProductJSON;
    };
  }

The client can do `makeRequest('createProduct', ...)` and the Express server can use `registerEndpoint('createProduct', ...)` which must adhere to the schema defined above.

TypeScript's structural typing helps a lot here.

Of course, I can "lose" typing through things like raw SQL queries (working on a mini db helper library to help with that), but so I'll have to validate that the endpoints return what they say they do through tests (probs using io-ts).

I'm just getting started (coming from Rails). Not sure what the "correct" way to do this is, but my approach works so far. Would also be nice to have a generic way to create REST endpoints for a given resource, but meh.

[1]: https://www.executeprogram.com/blog/porting-to-typescript-so...

[2]: https://www.youtube.com/watch?v=GrnBXhsr0ng

[eyelidlessness]

Let me give you a head start: what you want in TypeScript is type guards. You pair runtime validation with type refinement, and if you start with good composable primitives, you can declare runtime structures and get compile time safety for “free”. That’s how io-ts and the various other libraries in that space work.

If you combine that with generics on whatever function defines your routes, you can validate API boundaries and business logic boundaries in the compiler. This applies to any boundary (I could link to Gary Bernhardt on that topic but I’m on phone), and you can do it as generically (like you said, io-ts) or specifically (take a look at zapatos for type safe SQL) as you like.

For HTTP boundaries, I’ll drop some pseudocode of how I’m doing this in my library:

    type HTTPVerb =
      | 'delete'
      | 'get'
      | 'head'
      | 'options'
      | 'patch'
      | 'post'
      | 'put'
      | 'trace';

    interface HTTPRequest {
      readonly method: HTTPVerb;
      // ...
    }

    type HTTPRequestDecoder<I>     = (request: HTTPRequest) => I;
    type HTTPResponseEncoder<O, R> = (output: O) => R;
    type HTTPRoute                 = IrrelevantForThisPost;

    type Handler<I, O> = (input: I) => O;

    type HTTPRouteFactory = <I, O, R>(
      path:    string,
      decoder: HTTPRequestDecoder<I>,
      handler: Handler<I, O>,
      encoder: HTTPResponseEncoder<O, R>
    ) => HTTPRoute;

    type Route = {
      readonly [K in HTTPVerb]: HTTPRouteFactory;
    };

[shiny]

Awesome, thanks a ton. Sounds like your lib would be perfect for me. Also, kudos to somehow typing that on your phone.

Looks like I need to incorporate encoders/decoders into my scheme. I might just steal that code outright.

Thanks for the Zapatos rec, that looks perfect.

fyi, my current generic method sigs looks like:

  export const makeRequest = <Name extends keyof Endpoints>(
    _name: Name,
    method: Endpoints[Name]['method'],
    path: Endpoints[Name]['path'],
    props: {
      data: Endpoints[Name]['clientSends'];
      onSuccess: (json: Endpoints[Name]['serverResponds']) => void;
      onError: (json: any) => void;
    }
  ) => { // ...

Dropping all of these typing shenanigans and going back to Elixir/Phoenix is always half-tempting, but I will soldier on for now...