[v2] OpenAPI To Contract

[KingSora]

Describe the feature

The way I'm using ORPC is to derive some of my contract (mainly input & output) from my database schema (via drizzle-orm). The problem here is that the contract has now drizzle-orm as its dependency which is not very ideal to have in the client build. Other solutions like TRPC don't have this limitations because the whole system is based on types which are non-existent at runtime, but this doesn't apply for the contract.

In v1 there was a possibility (although it was marked as "unstable") to create a contract from an OpenAPI spec file. This was achieved via hey-api and the corresponding orpc plugin. I already spotted a PR which should support orpc v2 (hey-api/hey-api#4195). Now my question is whether this method of creating a contract from a OpenAPI file is the main method going forward or whether orpc will give you a build-in way of doing that going forward? As of right now the docs for v2 (yes I know they are still work in progress) are not emntioning anything about this topic. I'm very certain that my case is not "exotic" and many users could and will face the same contract dependency problem.

Additional information

• Would you be willing to help implement this feature?

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[dinwwwh]

Hey API is the recommended method for deriving a contract from an OpenAPI spec.
If you usecase just to avoid import drizzle things in client, just use this: https://v2.orpc.dev/docs/contract/router#router-to-contract

[KingSora]

@dinwwwh thanks for the reply, maybe I can start a discussion about some improvements regarding minifyRouterContract. After looking at the function all it does is to turn a contract into a json by stripping everything from it except the meta. I would like to suggest an improvement where the whole contract can be serialized including the input & output schemas and their types. In fact half of the work seems to be already done.

As of right now orpc already does this input & output serialization via the corresponding converters like the ZodJsonSchemaConverter. The last two missing piece are the "conversion back to zod" and the types. The conversion back to zod could be handled directly by the corresponding converter. For the types there are tools like zod-to-ts which are handling exactly this.

So what I'm suggesting is to add a new feature "contract serialization" which creates a full, standalone contract that consists of:

• Runtime JSON representation that holds the meta (via minifyRouterContract) and schemas (via converters)
• Compiletime TypeScript Type representation via additional tools like zod-to-ts.

So the final API could look something like this:

const contractSerializer = new ContractSerializer({
  converters: [
    new ZodJsonSchemaConverter(),
  ],
  typeExtractors: [
    new ZodTypeExtractor(),
  ],
})

const contractJson = await contractSerializer.json(contract);
const contractDts = await contractSerializer.types(contract); // throws an error when no `typeExtractors` are defined
const contractTs = await contractSerializer.typescript(contract); // throws an error when no `typeExtractors` are defined

fs.writeFileSync('./contract.json', contractJson);
fs.writeFileSync('./contract.d.ts', contractDts);
fs.writeFileSync('./contract.ts', contractTs); // essentially `.json and .d.ts` in one file

I believe this could be a valuable feature since contracts could be shared as completely standalone .ts / .json + .d.ts files without the worry of exposing any internal logic / dependencies. You could call it a "openapi.json" just for orpc.

What do you think?