refactor(downgrader): slim the converters down to what oRPC and schema libraries emit

README.md

@@ -21,7 +21,7 @@
   </a>
 </div>
 
-TypeScript tooling for the [OpenAPI Specification](https://spec.openapis.org/), maintained by [middleapi](https://github.com/middleapi). It lets you work with OpenAPI 3.0, 3.1, and 3.2 documents from one place: precise types for each version, and converters that move a document from a newer version to an older one without losing anything the older version can still express.
+TypeScript tooling for the [OpenAPI Specification](https://spec.openapis.org/), maintained by [middleapi](https://github.com/middleapi). It lets you work with OpenAPI 3.0, 3.1, and 3.2 documents from one place: precise types for each version, and small, fast converters that move a document from a newer version to an older one, covering what API frameworks such as [oRPC](https://orpc.dev) generate.
 
 | Package                                                                                                         | Description                                                                                         |
 | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |

packages/downgrader/benches/__shared__/api.ts

@@ -5,7 +5,7 @@ import type * as OpenAPIV3_2 from '@openapi-spec/types/v3.2'
 // a few paths and a webhook per resource, around shared schemas, parameters,
 // responses, and security schemes. It uses what each step has to rewrite:
 // 3.1 schemas with `null` in `type`, `const`, numeric exclusive bounds,
-// `examples`, `$defs`, and an `$id`; Path Items reused from
+// `examples`, and `$defs`; Path Items reused from
 // `components.pathItems`; webhooks; mutual TLS; and, in 3.2 only, `$self`,
 // the `query` method, streamed `itemSchema`s, reusable Media Type Objects,
 // Server `name`, Tag `summary`, `parent`, and `kind`, Response `summary`,
@@ -40,14 +40,13 @@ function sharedSchemas(): Record<string, OpenAPIV3_2.SchemaObject> {
       default: 'active',
     },
     Address: {
-      $id: 'https://api.example.com/schemas/address',
       type: 'object',
       required: ['line1', 'country'],
       properties: {
         line1: { type: 'string' },
         line2: { type: ['string', 'null'] },
         postalCode: { type: 'string', pattern: '^[0-9A-Z -]{3,10}$' },
-        country: { $ref: '#/$defs/Country' },
+        country: schemaRef('Address/$defs/Country'),
       },
       $defs: {
         Country: { type: 'string', minLength: 2, maxLength: 2, examples: ['US'] },

packages/downgrader/benches/__shared__/graphs.ts

@@ -3,8 +3,7 @@ import type * as OpenAPIV3_2 from '@openapi-spec/types/v3.2'
 
 // Small inputs that reach the same objects along exponentially many paths,
 // or around cycles. Converting each object once keeps the work linear, so a
-// regression here costs orders of magnitude, not percent. The tests that
-// count this work are the ones named "... once".
+// regression here costs orders of magnitude, not percent.
 
 function info(): OpenAPIV3_2.InfoObject {
   return { title: 'Graph', version: '1.0.0' }

packages/downgrader/benches/chained.bench.ts

@@ -1,11 +1,13 @@
 // There is no direct 3.2 → 3.0 converter: the two steps compose (see the
-// package README), and this is what that costs end to end.
+// package README), and this is what that costs end to end, as oRPC pays it
+// for every 3.0 document it generates.
 
 import type * as OpenAPIV3_2 from '@openapi-spec/types/v3.2'
 
 import { downgradeSpecV31ToV30, downgradeSpecV32ToV31 } from '@openapi-spec/downgrader'
 import { bench, describe } from 'vitest'
 import { corpusV32 } from '../tests/corpus'
+import { doc as orpcDocument } from '../tests/orpc-document'
 import { createApiV32 } from './__shared__/api'
 
 const API_100_RESOURCES = createApiV32(100)
@@ -21,6 +23,10 @@ describe('downgradeSpecV32ToV31 + downgradeSpecV31ToV30', () => {
     }
   })
 
+  bench('oRPC document', () => {
+    downgradeTwice(orpcDocument)
+  })
+
   bench('generated api, 100 resources', () => {
     downgradeTwice(API_100_RESOURCES)
   })