refactor: introduce @orpc/interop package for compatibility layer (#873)

unnoq · web-flow · commit d31094d6460f · 2025-08-13T16:11:53.000+07:00
A compatibility layer that builds &amp; re-exports upstream packages that
don't yet meet oRPC's requirements.

&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;
## Summary by CodeRabbit

- New Features
- Introduced @orpc/interop, providing entry points for json-schema-typed
(draft-07, 2019-09, 2020-12) and compression.

- Chores
- Migrated json-schema, openapi, and server to import from
@orpc/interop; removed direct compression dependencies; updated project
references.
- Adjusted Dependabot grouping and ESLint import restrictions;
simplified build configs.

- Documentation
- Updated interop README to clarify internal status and list included
packages.

- Tests
- Added smoke tests to verify interop exports for json-schema-typed
drafts and compression.
&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -22,7 +22,8 @@ updates:
           - '@antfu/eslint-config'
           - 'eslint-plugin-*'
           - '@hey-api/*'
-          - compression # inline dependency
+          - json-schema-typed # inline
+          - compression # inline
         update-types:
           - minor
           - patch
diff --git a/eslint.config.js b/eslint.config.js
@@ -27,15 +27,31 @@ export default antfu({
     'no-restricted-imports': ['error', {
       patterns: [{
         group: [
-          'json-schema-typed',
-          'json-schema-typed/*',
-          'openapi-types',
-          'openapi-types/*',
-          '@standard-schema/spec',
-          '@standard-schema/spec/*',
+          '/json-schema-typed',
+          '/openapi-types',
+          '/@standard-schema/spec',
+          '/compression',
         ],
         message: 'Please import from @orpc/* instead',
       }],
+      paths: [
+        {
+          name: '@opentelemetry/api',
+          allowImportNames: [
+            'AttributeValue',
+            'Context',
+            'ContextAPI',
+            'Exception',
+            'PropagationAPI',
+            'Span',
+            'SpanOptions',
+            'SpanStatusCode',
+            'TraceAPI',
+            'Tracer',
+          ],
+          message: 'Require explicit runtime import from @orpc/opentelemetry',
+        },
+      ],
     }],
   },
 }, {
@@ -57,6 +73,7 @@ export default antfu({
     'packages/*/playground/**',
   ],
   rules: {
+    'no-restricted-imports': 'off',
     'no-console': 'off',
     'perfectionist/sort-imports': 'off',
     'import/first': 'off',
diff --git a/packages/interop/.gitignore b/packages/interop/.gitignore
diff --git a/packages/interop/README.md b/packages/interop/README.md
@@ -1,3 +1,6 @@
+> [!WARNING]
+> This is an internal package. Breaking changes may be introduced without notice - use at your own risk.
+
 <div align="center">
   <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
 </div>
@@ -8,8 +11,8 @@
   <a href="https://codecov.io/gh/unnoq/orpc">
     <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
   </a>
-  <a href="https://www.npmjs.com/package/@orpc/json-schema-typed">
-    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fjson-schema-typed?logo=npm" />
+  <a href="https://www.npmjs.com/package/@orpc/interop">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Finterop?logo=npm" />
   </a>
   <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
     <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
@@ -60,9 +63,15 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
 - [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
 
-## `@orpc/json-schema-typed`
+## `@orpc/interop`
+
+A compatibility layer that builds & re-exports upstream packages that don't yet meet oRPC's requirements.
+
+**Included packages:**
+
+- [json-schema-typed](https://www.npmjs.com/package/json-schema-typed) to address issue [RemyRylan/json-schema-typed#116](https://github.com/RemyRylan/json-schema-typed/issues/116)
 
-Re-export of [json-schema-typed](https://www.npmjs.com/package/json-schema-typed) due to the upstream issue [RemyRylan/json-schema-typed#116](https://github.com/RemyRylan/json-schema-typed/issues/116).
+- [compression](https://www.npmjs.com/package/compression) for esm compatibility
 
 ## Sponsors
 
diff --git a/packages/interop/build.config.ts b/packages/interop/build.config.ts
@@ -2,6 +2,6 @@ import { defineBuildConfig } from 'unbuild'
 
 export default defineBuildConfig({
   rollup: {
-    inlineDependencies: ['json-schema-typed'],
+    inlineDependencies: true,
   },
 })
diff --git a/packages/interop/package.json b/packages/interop/package.json
@@ -0,0 +1,65 @@
+{
+  "name": "@orpc/interop",
+  "type": "module",
+  "version": "0.0.0",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/interop"
+  },
+  "keywords": [
+    "unnoq",
+    "orpc"
+  ],
+  "publishConfig": {
+    "exports": {
+      "./json-schema-typed": {
+        "types": "./dist/json-schema-typed/index.d.mts",
+        "import": "./dist/json-schema-typed/index.mjs",
+        "default": "./dist/json-schema-typed/index.mjs"
+      },
+      "./json-schema-typed/draft-07": {
+        "types": "./dist/json-schema-typed/draft-07.d.mts",
+        "import": "./dist/json-schema-typed/draft-07.mjs",
+        "default": "./dist/json-schema-typed/draft-07.mjs"
+      },
+      "./json-schema-typed/draft-2019-09": {
+        "types": "./dist/json-schema-typed/draft-2019-09.d.mts",
+        "import": "./dist/json-schema-typed/draft-2019-09.mjs",
+        "default": "./dist/json-schema-typed/draft-2019-09.mjs"
+      },
+      "./json-schema-typed/draft-2020-12": {
+        "types": "./dist/json-schema-typed/draft-2020-12.d.mts",
+        "import": "./dist/json-schema-typed/draft-2020-12.mjs",
+        "default": "./dist/json-schema-typed/draft-2020-12.mjs"
+      },
+      "./compression": {
+        "types": "./dist/compression/index.d.mts",
+        "import": "./dist/compression/index.mjs",
+        "default": "./dist/compression/index.mjs"
+      }
+    }
+  },
+  "exports": {
+    "./json-schema-typed": "./src/json-schema-typed/index.ts",
+    "./json-schema-typed/draft-07": "./src/json-schema-typed/draft-07.ts",
+    "./json-schema-typed/draft-2019-09": "./src/json-schema-typed/draft-2019-09.ts",
+    "./json-schema-typed/draft-2020-12": "./src/json-schema-typed/draft-2020-12.ts",
+    "./compression": "./src/compression/index.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b"
+  },
+  "devDependencies": {
+    "@types/compression": "^1.8.1",
+    "compression": "^1.8.1",
+    "json-schema-typed": "^8.0.1"
+  }
+}
diff --git a/packages/interop/src/compression/index.test.ts b/packages/interop/src/compression/index.test.ts
@@ -0,0 +1,3 @@
+it('exports something', async () => {
+  expect(Object.keys(await import('./index')).length).toBeGreaterThanOrEqual(1)
+})
diff --git a/packages/interop/src/compression/index.ts b/packages/interop/src/compression/index.ts
@@ -0,0 +1,4 @@
+// eslint-disable-next-line no-restricted-imports
+import compression from 'compression'
+
+export default compression
diff --git a/packages/interop/src/json-schema-typed/draft-07.test.ts b/packages/interop/src/json-schema-typed/draft-07.test.ts
@@ -0,0 +1,3 @@
+it('exports something', async () => {
+  expect(Object.keys(await import('./draft-07')).length).toBeGreaterThanOrEqual(1)
+})
diff --git a/packages/interop/src/json-schema-typed/draft-07.ts b/packages/interop/src/json-schema-typed/draft-07.ts
diff --git a/packages/interop/src/json-schema-typed/draft-2019-09.test.ts b/packages/interop/src/json-schema-typed/draft-2019-09.test.ts
@@ -0,0 +1,3 @@
+it('exports something', async () => {
+  expect(Object.keys(await import('./draft-2019-09')).length).toBeGreaterThanOrEqual(1)
+})
diff --git a/packages/interop/src/json-schema-typed/draft-2019-09.ts b/packages/interop/src/json-schema-typed/draft-2019-09.ts
diff --git a/packages/interop/src/json-schema-typed/draft-2020-12.test.ts b/packages/interop/src/json-schema-typed/draft-2020-12.test.ts
@@ -0,0 +1,3 @@
+it('exports something', async () => {
+  expect(Object.keys(await import('./draft-2020-12')).length).toBeGreaterThanOrEqual(1)
+})
diff --git a/packages/interop/src/json-schema-typed/draft-2020-12.ts b/packages/interop/src/json-schema-typed/draft-2020-12.ts
diff --git a/packages/interop/src/json-schema-typed/index.test.ts b/packages/interop/src/json-schema-typed/index.test.ts
@@ -0,0 +1,3 @@
+it('exports something', async () => {
+  expect(Object.keys(await import('./index')).length).toBeGreaterThanOrEqual(1)
+})
diff --git a/packages/interop/src/json-schema-typed/index.ts b/packages/interop/src/json-schema-typed/index.ts
diff --git a/packages/interop/tsconfig.json b/packages/interop/tsconfig.json
diff --git a/packages/json-schema-typed/package.json b/packages/json-schema-typed/package.json
diff --git a/packages/json-schema/package.json b/packages/json-schema/package.json
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@orpc/contract": "workspace:*",
-    "@orpc/json-schema-typed": "workspace:*",
+    "@orpc/interop": "workspace:*",
     "@orpc/openapi": "workspace:*",
     "@orpc/server": "workspace:*",
     "@orpc/shared": "workspace:*"
diff --git a/packages/json-schema/src/types.ts b/packages/json-schema/src/types.ts
@@ -1,7 +1,6 @@
-/* eslint-disable no-restricted-imports */
-import type * as Draft07 from '@orpc/json-schema-typed/draft-07'
-import type * as Draft2019 from '@orpc/json-schema-typed/draft-2019-09'
-import type * as Draft2020 from '@orpc/json-schema-typed/draft-2020-12'
+import type * as Draft07 from '@orpc/interop/json-schema-typed/draft-07'
+import type * as Draft2019 from '@orpc/interop/json-schema-typed/draft-2019-09'
+import type * as Draft2020 from '@orpc/interop/json-schema-typed/draft-2020-12'
 
 export type JsonSchema
   = | Draft2020.JSONSchema
diff --git a/packages/json-schema/tsconfig.json b/packages/json-schema/tsconfig.json
@@ -5,7 +5,7 @@
     { "path": "../server" },
     { "path": "../openapi" },
     { "path": "../contract" },
-    { "path": "../json-schema-typed" }
+    { "path": "../interop" }
   ],
   "include": ["src"],
   "exclude": [
diff --git a/packages/openapi/package.json b/packages/openapi/package.json
@@ -66,7 +66,7 @@
   "dependencies": {
     "@orpc/client": "workspace:*",
     "@orpc/contract": "workspace:*",
-    "@orpc/json-schema-typed": "workspace:*",
+    "@orpc/interop": "workspace:*",
     "@orpc/openapi-client": "workspace:*",
     "@orpc/server": "workspace:*",
     "@orpc/shared": "workspace:*",
diff --git a/packages/openapi/src/schema.ts b/packages/openapi/src/schema.ts
@@ -1,6 +1,5 @@
-/* eslint-disable no-restricted-imports */
-import type { JSONSchema, keywords } from '@orpc/json-schema-typed/draft-2020-12'
-import { ContentEncoding as JSONSchemaContentEncoding, Format as JSONSchemaFormat, TypeName as JSONSchemaTypeName } from '@orpc/json-schema-typed/draft-2020-12'
+import type { JSONSchema, keywords } from '@orpc/interop/json-schema-typed/draft-2020-12'
+import { ContentEncoding as JSONSchemaContentEncoding, Format as JSONSchemaFormat, TypeName as JSONSchemaTypeName } from '@orpc/interop/json-schema-typed/draft-2020-12'
 
 export { JSONSchemaContentEncoding, JSONSchemaFormat, JSONSchemaTypeName }
 export type { JSONSchema }
diff --git a/packages/openapi/tsconfig.json b/packages/openapi/tsconfig.json
@@ -6,7 +6,7 @@
     { "path": "../contract" },
     { "path": "../server" },
     { "path": "../standard-server" },
-    { "path": "../json-schema-typed" },
+    { "path": "../interop" },
     { "path": "../shared" }
   ],
   "include": ["src"],
diff --git a/packages/otel/src/instrumentation.ts b/packages/otel/src/instrumentation.ts
@@ -1,4 +1,5 @@
 import type { InstrumentationConfig, InstrumentationModuleDefinition } from '@opentelemetry/instrumentation'
+// eslint-disable-next-line no-restricted-imports
 import { context, propagation, trace } from '@opentelemetry/api'
 import { InstrumentationBase } from '@opentelemetry/instrumentation'
 import { setGlobalOtelConfig } from '@orpc/shared'
diff --git a/packages/server/build.config.ts b/packages/server/build.config.ts
diff --git a/packages/server/package.json b/packages/server/package.json
@@ -126,6 +126,7 @@
   "dependencies": {
     "@orpc/client": "workspace:*",
     "@orpc/contract": "workspace:*",
+    "@orpc/interop": "workspace:*",
     "@orpc/shared": "workspace:*",
     "@orpc/standard-server": "workspace:*",
     "@orpc/standard-server-aws-lambda": "workspace:*",
@@ -135,9 +136,7 @@
     "cookie": "^1.0.2"
   },
   "devDependencies": {
-    "@types/compression": "^1.8.1",
     "@types/ws": "^8.18.1",
-    "compression": "^1.8.1",
     "crossws": "^0.4.1",
     "next": "^15.4.5",
     "supertest": "^7.1.4",
diff --git a/packages/server/src/adapters/node/compression-plugin.ts b/packages/server/src/adapters/node/compression-plugin.ts
@@ -1,7 +1,7 @@
 import type { Context } from '../../context'
 import type { NodeHttpHandlerOptions } from './handler'
 import type { NodeHttpHandlerPlugin } from './plugin'
-import compression from 'compression'
+import compression from '@orpc/interop/compression'
 
 export interface CompressionPluginOptions extends compression.CompressionOptions {
 }
diff --git a/packages/server/tsconfig.json b/packages/server/tsconfig.json
@@ -8,7 +8,8 @@
     { "path": "../standard-server-node" },
     { "path": "../standard-server-aws-lambda" },
     { "path": "../standard-server-peer" },
-    { "path": "../shared" }
+    { "path": "../shared" },
+    { "path": "../interop" }
   ],
   "include": ["src"],
   "exclude": [
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+it('exports something', async () => {`
	`2`	`+ expect(Object.keys(await import('./index')).length).toBeGreaterThanOrEqual(1)`
	`3`	`+})`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+it('exports something', async () => {`
	`2`	`+ expect(Object.keys(await import('./draft-07')).length).toBeGreaterThanOrEqual(1)`
	`3`	`+})`