Proposal: Generate path templating with colons instead of curly braces

[christoph-fricke]

First of all, thank you for this awesome library! Generating lightweight type definitions and feeding them into a lightweight api-client is a breeze of fresh air compared to other open-api generators. Working with it is a real joy!

I have started to think about this library and how it can interact with other tooling. While thinking about it, I have noticed a gap between generated path string literals and the rest of the JavaScript ecosystem.

OpenAPI defines path templates as segments that are wrapped in curly braces, e.g. /users/{id}. This format is also used in the generated path literals. However, most (if not all) JavaScript libraries and proposals use colons for path templates, e.g. /users/:id. Some examples:

1. Mock Service Worker (MSW), popular library for mocking API endpoints:
2. Fastify and Express
3. path-to-regex
4. Most notably, the experimental "URL Pattern API" proposals, which is implemented in Chromium and might get standardized.

Generating paths literals with colons could make it easier to combine the generated path types with these libraries, thus increasing the compatibility with the JS ecosystem.

I have been wondering if it is worth switching to a colon based path format. I would love to hear your thoughts and opinions about this. Have you thought about it before already?

[drwpow]

Thanks for the kind words!

Proposal-wise, this whole library is dependent upon OpenAPI’s conventions and standards. You’ve given an example of tools that use different standards from OpenAPI, but I’m not entirely sure how that applies because users are always starting from their schema when consuming this library.

Could you maybe give a code example of what you’re proposing?

[christoph-fricke]

When I stumbled upon this, I have been thinking about a wrapper around MSW, which I have further described in #1372. The wrapper accepts strings in the OpenAPI convention, since one goal is strict typing for URL paths, and has to convert all path fragments to the colon conventions.

Granted, the convention step does not appear to be that verbose after thinking more about it. The "problem" appears to be mostly an annoying indirection for utilities that use the generated paths to either wrap something or provide them to something that uses colons for path fragments.

Avoiding this indirection might make the compatibility with various tools more obvious.