@prairielearn/trpc 0.0.0 → 1.0.0

package/dist/server.d.ts

@@ -0,0 +1,46 @@
+import { type TRPCDefaultErrorShape, TRPCError, type TRPC_ERROR_CODE_KEY } from '@trpc/server';
+/** Metadata serialized for a typed application-level error. */
+export interface AppErrorBase {
+    code: string;
+    message: string;
+    [key: string]: unknown;
+}
+type Values<T> = T[keyof T];
+/** Returns `fail` when `E` is not a member of at least one entry in `Map`. */
+type ErrorInvalidForAny<E, Map> = {
+    [K in keyof Map]: E extends Map[K] ? never : 'fail';
+}[keyof Map];
+/** Computes the error variants shared by every procedure in an error map. */
+type SharedProcedureErrors<Map> = Values<Map> extends infer E ? E extends unknown ? ErrorInvalidForAny<E, Map> extends never ? E : never : never : never;
+type ResolveAppErrorForThrow<T> = T extends {
+    code: string;
+} ? T : SharedProcedureErrors<T>;
+/** The metadata accepted by {@link throwAppError}. */
+export type AppErrorInput<T> = ResolveAppErrorForThrow<T> & {
+    message: string;
+};
+/** The tRPC error shape produced by {@link appErrorFormatter}. */
+export interface AppErrorShape extends TRPCDefaultErrorShape {
+    data: TRPCDefaultErrorShape['data'] & {
+        appError?: AppErrorBase;
+    };
+}
+/**
+ * Attaches typed application-error metadata to a tRPC error response.
+ *
+ * Pass this formatter to each authorization scope's context-bound `initTRPC.create()` call.
+ */
+export declare const appErrorFormatter: ({ shape, error, }: {
+    shape: TRPCDefaultErrorShape;
+    error: TRPCError;
+}) => AppErrorShape;
+/**
+ * Throws a typed application error.
+ *
+ * A direct procedure error type accepts all of that procedure's variants. A whole procedure error
+ * map accepts only variants shared by every procedure; this is intentionally narrower than the
+ * client-side whole-map resolution used by `getAppError`.
+ */
+export declare function throwAppError<T>(meta: AppErrorInput<T>, trpcCode?: TRPC_ERROR_CODE_KEY): never;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,qBAAqB,EAAE,SAAS,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAE/F,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAE5B,8EAA8E;AAC9E,KAAK,kBAAkB,CAAC,CAAC,EAAE,GAAG,IAAI;KAC/B,CAAC,IAAI,MAAM,GAAG,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,MAAM;CACpD,CAAC,MAAM,GAAG,CAAC,CAAC;AAEb,6EAA6E;AAC7E,KAAK,qBAAqB,CAAC,GAAG,IAC5B,MAAM,CAAC,GAAG,CAAC,SAAS,MAAM,CAAC,GACvB,CAAC,SAAS,OAAO,GACf,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,KAAK,GACtC,CAAC,GACD,KAAK,GACP,KAAK,GACP,KAAK,CAAC;AAEZ,KAAK,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAE5F,sDAAsD;AACtD,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,kEAAkE;AAClE,MAAM,WAAW,aAAc,SAAQ,qBAAqB;IAC1D,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;CACnE;AAWD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAG3B;IACD,KAAK,EAAE,qBAAqB,CAAC;IAC7B,KAAK,EAAE,SAAS,CAAC;CAClB,KAAG,aAMF,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EACtB,QAAQ,GAAE,mBAAmC,GAC5C,KAAK,CAEP","sourcesContent":["import { type TRPCDefaultErrorShape, TRPCError, type TRPC_ERROR_CODE_KEY } from '@trpc/server';\n\n/** Metadata serialized for a typed application-level error. */\nexport interface AppErrorBase {\n  code: string;\n  message: string;\n  [key: string]: unknown;\n}\n\ntype Values<T> = T[keyof T];\n\n/** Returns `fail` when `E` is not a member of at least one entry in `Map`. */\ntype ErrorInvalidForAny<E, Map> = {\n  [K in keyof Map]: E extends Map[K] ? never : 'fail';\n}[keyof Map];\n\n/** Computes the error variants shared by every procedure in an error map. */\ntype SharedProcedureErrors<Map> =\n  Values<Map> extends infer E\n    ? E extends unknown\n      ? ErrorInvalidForAny<E, Map> extends never\n        ? E\n        : never\n      : never\n    : never;\n\ntype ResolveAppErrorForThrow<T> = T extends { code: string } ? T : SharedProcedureErrors<T>;\n\n/** The metadata accepted by {@link throwAppError}. */\nexport type AppErrorInput<T> = ResolveAppErrorForThrow<T> & { message: string };\n\n/** The tRPC error shape produced by {@link appErrorFormatter}. */\nexport interface AppErrorShape extends TRPCDefaultErrorShape {\n  data: TRPCDefaultErrorShape['data'] & { appError?: AppErrorBase };\n}\n\nclass AppError extends TRPCError {\n  constructor(\n    public readonly meta: AppErrorBase,\n    trpcCode: TRPC_ERROR_CODE_KEY = 'BAD_REQUEST',\n  ) {\n    super({ code: trpcCode, message: meta.message });\n  }\n}\n\n/**\n * Attaches typed application-error metadata to a tRPC error response.\n *\n * Pass this formatter to each authorization scope's context-bound `initTRPC.create()` call.\n */\nexport const appErrorFormatter = ({\n  shape,\n  error,\n}: {\n  shape: TRPCDefaultErrorShape;\n  error: TRPCError;\n}): AppErrorShape => ({\n  ...shape,\n  data: {\n    ...shape.data,\n    ...(error instanceof AppError ? { appError: error.meta } : {}),\n  },\n});\n\n/**\n * Throws a typed application error.\n *\n * A direct procedure error type accepts all of that procedure's variants. A whole procedure error\n * map accepts only variants shared by every procedure; this is intentionally narrower than the\n * client-side whole-map resolution used by `getAppError`.\n */\nexport function throwAppError<T>(\n  meta: AppErrorInput<T>,\n  trpcCode: TRPC_ERROR_CODE_KEY = 'BAD_REQUEST',\n): never {\n  throw new AppError(meta as unknown as AppErrorBase, trpcCode);\n}\n"]}

package/dist/server.js

@@ -0,0 +1,31 @@
+import { TRPCError } from '@trpc/server';
+class AppError extends TRPCError {
+    meta;
+    constructor(meta, trpcCode = 'BAD_REQUEST') {
+        super({ code: trpcCode, message: meta.message });
+        this.meta = meta;
+    }
+}
+/**
+ * Attaches typed application-error metadata to a tRPC error response.
+ *
+ * Pass this formatter to each authorization scope's context-bound `initTRPC.create()` call.
+ */
+export const appErrorFormatter = ({ shape, error, }) => ({
+    ...shape,
+    data: {
+        ...shape.data,
+        ...(error instanceof AppError ? { appError: error.meta } : {}),
+    },
+});
+/**
+ * Throws a typed application error.
+ *
+ * A direct procedure error type accepts all of that procedure's variants. A whole procedure error
+ * map accepts only variants shared by every procedure; this is intentionally narrower than the
+ * client-side whole-map resolution used by `getAppError`.
+ */
+export function throwAppError(meta, trpcCode = 'BAD_REQUEST') {
+    throw new AppError(meta, trpcCode);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,SAAS,EAA4B,MAAM,cAAc,CAAC;AAoC/F,MAAM,QAAS,SAAQ,SAAS;IAEZ,IAAI;IADtB,YACkB,IAAkB,EAClC,QAAQ,GAAwB,aAAa;QAE7C,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;oBAHjC,IAAI;IAItB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,EAChC,KAAK,EACL,KAAK,GAIN,EAAiB,EAAE,CAAC,CAAC;IACpB,GAAG,KAAK;IACR,IAAI,EAAE;QACJ,GAAG,KAAK,CAAC,IAAI;QACb,GAAG,CAAC,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D;CACF,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAsB,EACtB,QAAQ,GAAwB,aAAa;IAE7C,MAAM,IAAI,QAAQ,CAAC,IAA+B,EAAE,QAAQ,CAAC,CAAC;AAChE,CAAC","sourcesContent":["import { type TRPCDefaultErrorShape, TRPCError, type TRPC_ERROR_CODE_KEY } from '@trpc/server';\n\n/** Metadata serialized for a typed application-level error. */\nexport interface AppErrorBase {\n  code: string;\n  message: string;\n  [key: string]: unknown;\n}\n\ntype Values<T> = T[keyof T];\n\n/** Returns `fail` when `E` is not a member of at least one entry in `Map`. */\ntype ErrorInvalidForAny<E, Map> = {\n  [K in keyof Map]: E extends Map[K] ? never : 'fail';\n}[keyof Map];\n\n/** Computes the error variants shared by every procedure in an error map. */\ntype SharedProcedureErrors<Map> =\n  Values<Map> extends infer E\n    ? E extends unknown\n      ? ErrorInvalidForAny<E, Map> extends never\n        ? E\n        : never\n      : never\n    : never;\n\ntype ResolveAppErrorForThrow<T> = T extends { code: string } ? T : SharedProcedureErrors<T>;\n\n/** The metadata accepted by {@link throwAppError}. */\nexport type AppErrorInput<T> = ResolveAppErrorForThrow<T> & { message: string };\n\n/** The tRPC error shape produced by {@link appErrorFormatter}. */\nexport interface AppErrorShape extends TRPCDefaultErrorShape {\n  data: TRPCDefaultErrorShape['data'] & { appError?: AppErrorBase };\n}\n\nclass AppError extends TRPCError {\n  constructor(\n    public readonly meta: AppErrorBase,\n    trpcCode: TRPC_ERROR_CODE_KEY = 'BAD_REQUEST',\n  ) {\n    super({ code: trpcCode, message: meta.message });\n  }\n}\n\n/**\n * Attaches typed application-error metadata to a tRPC error response.\n *\n * Pass this formatter to each authorization scope's context-bound `initTRPC.create()` call.\n */\nexport const appErrorFormatter = ({\n  shape,\n  error,\n}: {\n  shape: TRPCDefaultErrorShape;\n  error: TRPCError;\n}): AppErrorShape => ({\n  ...shape,\n  data: {\n    ...shape.data,\n    ...(error instanceof AppError ? { appError: error.meta } : {}),\n  },\n});\n\n/**\n * Throws a typed application error.\n *\n * A direct procedure error type accepts all of that procedure's variants. A whole procedure error\n * map accepts only variants shared by every procedure; this is intentionally narrower than the\n * client-side whole-map resolution used by `getAppError`.\n */\nexport function throwAppError<T>(\n  meta: AppErrorInput<T>,\n  trpcCode: TRPC_ERROR_CODE_KEY = 'BAD_REQUEST',\n): never {\n  throw new AppError(meta as unknown as AppErrorBase, trpcCode);\n}\n"]}

package/dist/server.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server.test.d.ts.map

package/dist/server.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.test.d.ts","sourceRoot":"","sources":["../src/server.test.ts"],"names":[],"mappings":"","sourcesContent":["import { TRPCError } from '@trpc/server';\nimport { TRPC_ERROR_CODES_BY_KEY } from '@trpc/server/rpc';\nimport { assert, describe, expectTypeOf, it } from 'vitest';\n\nimport type { AppError } from './client.js';\nimport { appErrorFormatter, throwAppError } from './server.js';\n\ninterface WholeErrorMap {\n  First: { code: 'FIRST_ONLY'; first: string } | { code: 'SHARED'; shared: string };\n  Second: { code: 'SECOND_ONLY'; second: string } | { code: 'SHARED'; shared: string };\n}\n\ndescribe('typed application errors', () => {\n  it('serializes typed metadata through the error formatter', () => {\n    const error = assert.throws(() => {\n      throwAppError<WholeErrorMap['First']>(\n        {\n          code: 'FIRST_ONLY',\n          message: 'Expected failure',\n          first: 'detail',\n        },\n        'CONFLICT',\n      );\n    });\n    assert.instanceOf(error, TRPCError);\n\n    const result = appErrorFormatter({\n      error,\n      shape: {\n        message: error.message,\n        code: TRPC_ERROR_CODES_BY_KEY.CONFLICT,\n        data: { code: 'CONFLICT', httpStatus: 409 },\n      },\n    });\n\n    assert.deepEqual(result.data.appError, {\n      code: 'FIRST_ONLY',\n      message: 'Expected failure',\n      first: 'detail',\n    });\n  });\n\n  it('keeps whole-map server errors narrower than whole-map client errors', () => {\n    type WholeMapThrowInput = Parameters<typeof throwAppError<WholeErrorMap>>[0];\n\n    expectTypeOf<WholeMapThrowInput['code']>().toEqualTypeOf<'SHARED'>();\n    expectTypeOf<AppError<WholeErrorMap>['code']>().toEqualTypeOf<\n      'FIRST_ONLY' | 'SECOND_ONLY' | 'SHARED' | 'UNKNOWN'\n    >();\n  });\n});\n"]}

package/dist/server.test.js

@@ -0,0 +1,34 @@
+import { TRPCError } from '@trpc/server';
+import { TRPC_ERROR_CODES_BY_KEY } from '@trpc/server/rpc';
+import { assert, describe, expectTypeOf, it } from 'vitest';
+import { appErrorFormatter, throwAppError } from './server.js';
+describe('typed application errors', () => {
+    it('serializes typed metadata through the error formatter', () => {
+        const error = assert.throws(() => {
+            throwAppError({
+                code: 'FIRST_ONLY',
+                message: 'Expected failure',
+                first: 'detail',
+            }, 'CONFLICT');
+        });
+        assert.instanceOf(error, TRPCError);
+        const result = appErrorFormatter({
+            error,
+            shape: {
+                message: error.message,
+                code: TRPC_ERROR_CODES_BY_KEY.CONFLICT,
+                data: { code: 'CONFLICT', httpStatus: 409 },
+            },
+        });
+        assert.deepEqual(result.data.appError, {
+            code: 'FIRST_ONLY',
+            message: 'Expected failure',
+            first: 'detail',
+        });
+    });
+    it('keeps whole-map server errors narrower than whole-map client errors', () => {
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+    });
+});
+//# sourceMappingURL=server.test.js.map

package/dist/server.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.test.js","sourceRoot":"","sources":["../src/server.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAG5D,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAO/D,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE;YAC/B,aAAa,CACX;gBACE,IAAI,EAAE,YAAY;gBAClB,OAAO,EAAE,kBAAkB;gBAC3B,KAAK,EAAE,QAAQ;aAChB,EACD,UAAU,CACX,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAEpC,MAAM,MAAM,GAAG,iBAAiB,CAAC;YAC/B,KAAK;YACL,KAAK,EAAE;gBACL,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,IAAI,EAAE,uBAAuB,CAAC,QAAQ;gBACtC,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE;aAC5C;SACF,CAAC,CAAC;QAEH,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE;YACrC,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,kBAAkB;YAC3B,KAAK,EAAE,QAAQ;SAChB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAG7E,YAAY,EAA8B,CAAC,aAAa,EAAY,CAAC;QACrE,YAAY,EAAmC,CAAC,aAAa,EAE1D,CAAC;IACN,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { TRPCError } from '@trpc/server';\nimport { TRPC_ERROR_CODES_BY_KEY } from '@trpc/server/rpc';\nimport { assert, describe, expectTypeOf, it } from 'vitest';\n\nimport type { AppError } from './client.js';\nimport { appErrorFormatter, throwAppError } from './server.js';\n\ninterface WholeErrorMap {\n  First: { code: 'FIRST_ONLY'; first: string } | { code: 'SHARED'; shared: string };\n  Second: { code: 'SECOND_ONLY'; second: string } | { code: 'SHARED'; shared: string };\n}\n\ndescribe('typed application errors', () => {\n  it('serializes typed metadata through the error formatter', () => {\n    const error = assert.throws(() => {\n      throwAppError<WholeErrorMap['First']>(\n        {\n          code: 'FIRST_ONLY',\n          message: 'Expected failure',\n          first: 'detail',\n        },\n        'CONFLICT',\n      );\n    });\n    assert.instanceOf(error, TRPCError);\n\n    const result = appErrorFormatter({\n      error,\n      shape: {\n        message: error.message,\n        code: TRPC_ERROR_CODES_BY_KEY.CONFLICT,\n        data: { code: 'CONFLICT', httpStatus: 409 },\n      },\n    });\n\n    assert.deepEqual(result.data.appError, {\n      code: 'FIRST_ONLY',\n      message: 'Expected failure',\n      first: 'detail',\n    });\n  });\n\n  it('keeps whole-map server errors narrower than whole-map client errors', () => {\n    type WholeMapThrowInput = Parameters<typeof throwAppError<WholeErrorMap>>[0];\n\n    expectTypeOf<WholeMapThrowInput['code']>().toEqualTypeOf<'SHARED'>();\n    expectTypeOf<AppError<WholeErrorMap>['code']>().toEqualTypeOf<\n      'FIRST_ONLY' | 'SECOND_ONLY' | 'SHARED' | 'UNKNOWN'\n    >();\n  });\n});\n"]}

package/package.json

@@ -1,10 +1,45 @@
 {
   "name": "@prairielearn/trpc",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @prairielearn/trpc",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+  "version": "1.0.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrairieLearn/PrairieLearn.git",
+    "directory": "packages/trpc"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "exports": {
+    "./client": "./dist/client.js",
+    "./express": "./dist/express.js",
+    "./react": "./dist/react.js",
+    "./server": "./dist/server.js"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.4",
+    "@trpc/client": "^11.18.0",
+    "@trpc/server": "^11.18.0",
+    "react": "^19.2.8",
+    "react-bootstrap": "3.0.0-beta.5"
+  },
+  "dependencies": {
+    "@types/react": "^19.2.18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/react-dom": "^19.2.4",
+    "@typescript/native-preview": "beta",
+    "@vitest/coverage-v8": "^4.1.10",
+    "jsdom": "^29.1.1",
+    "react-dom": "^19.2.8",
+    "vitest": "^4.1.10",
+    "@prairielearn/tsconfig": "^2.1.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsgo",
+    "dev": "tsgo --watch --preserveWatchOutput",
+    "test": "vitest run --coverage"
+  }
+}

package/src/client.test.tsx

@@ -0,0 +1,84 @@
+import { TRPCClientError } from '@trpc/client';
+import { TRPCError } from '@trpc/server';
+import { TRPC_ERROR_CODES_BY_KEY } from '@trpc/server/rpc';
+import { assert, describe, it } from 'vitest';
+
+import { getAppError, renderAppError } from './client.js';
+import { appErrorFormatter, throwAppError } from './server.js';
+
+interface ExpectedError {
+  code: 'EXPECTED';
+  detail: string;
+}
+
+describe('getAppError', () => {
+  it('extracts typed metadata from a tRPC client error', () => {
+    const serverError = assert.throws(() => {
+      throwAppError<ExpectedError>({
+        message: 'Expected failure',
+        code: 'EXPECTED',
+        detail: 'more context',
+      });
+    });
+    assert.instanceOf(serverError, TRPCError);
+
+    const errorShape = appErrorFormatter({
+      error: serverError,
+      shape: {
+        message: serverError.message,
+        code: TRPC_ERROR_CODES_BY_KEY.BAD_REQUEST,
+        data: {
+          code: 'BAD_REQUEST',
+          httpStatus: 400,
+        },
+      },
+    });
+    const error = new TRPCClientError(errorShape.message, {
+      result: { error: errorShape },
+    });
+
+    assert.deepEqual(getAppError<ExpectedError>(error), {
+      code: 'EXPECTED',
+      message: 'Expected failure',
+      detail: 'more context',
+    });
+  });
+
+  it('uses UNKNOWN for ordinary errors', () => {
+    assert.deepEqual(getAppError<ExpectedError>(new Error('Unexpected failure')), {
+      code: 'UNKNOWN',
+      message: 'Unexpected failure',
+    });
+  });
+});
+
+describe('renderAppError', () => {
+  it('uses an exhaustive renderer for a known code', () => {
+    const error = { code: 'EXPECTED' as const, message: 'Expected failure', detail: 'context' };
+
+    assert.equal(
+      renderAppError(error, {
+        EXPECTED: ({ message, detail }) => `${message}: ${detail}`,
+      }),
+      'Expected failure: context',
+    );
+  });
+
+  it('falls back to the message when a stale client receives an unknown runtime code', () => {
+    interface KnownError {
+      code: 'EXPECTED';
+      message: string;
+    }
+    const staleClientError = {
+      code: 'ADDED_AFTER_DEPLOY',
+      message: 'The server still explains the failure',
+    } as unknown as KnownError;
+
+    assert.equal(
+      renderAppError(staleClientError, {
+        EXPECTED: ({ message }) => message,
+      }),
+      'The server still explains the failure',
+    );
+  });
+});

package/src/client.ts

@@ -0,0 +1,54 @@
+import { TRPCClientError } from '@trpc/client';
+import type { ReactNode } from 'react';
+
+/**
+ * Resolves client error types to the variants a component may receive.
+ *
+ * Unlike the server's whole-map resolution, a whole map becomes the union of its procedure errors
+ * because a component may handle failures from several procedures.
+ */
+type ResolveClientAppError<T> = T extends { code: string }
+  ? T
+  : T[keyof T] extends { code: string }
+    ? T[keyof T]
+    : never;
+
+/** The resolved, non-null return type of {@link getAppError}. */
+export type AppError<T> =
+  | (ResolveClientAppError<T> & { message: string })
+  | { code: 'UNKNOWN'; message: string };
+
+/** An exhaustive renderer map for every statically known application-error code. */
+export type AppErrorRenderers<E extends { code: string; message: string }> = {
+  [K in E['code']]: (error: Extract<E, { code: K }>) => ReactNode;
+};
+
+/**
+ * Extracts typed application metadata from a tRPC client error.
+ *
+ * Pass a procedure entry for a single operation. Pass a whole error map only when one component
+ * handles failures from several procedures; in that case the result is their union.
+ */
+export function getAppError<T>(error: unknown): AppError<T> | null {
+  if (error instanceof TRPCClientError) {
+    const appError = (error.data as { appError?: ResolveClientAppError<T> } | undefined)?.appError;
+    if (appError) return { ...appError, message: error.message };
+    return { code: 'UNKNOWN', message: error.message };
+  }
+  if (error instanceof Error) return { code: 'UNKNOWN', message: error.message };
+  return null;
+}
+
+/**
+ * Renders an application error with an exhaustive map for statically known variants.
+ *
+ * If a newer server sends a code unknown to a stale browser bundle, the server message is rendered
+ * instead of attempting to call a missing renderer.
+ */
+export function renderAppError<E extends { code: string; message: string }>(
+  error: E,
+  renderers: AppErrorRenderers<E>,
+): ReactNode {
+  const render = renderers[error.code as E['code']] as ((error: E) => ReactNode) | undefined;
+  return render ? render(error) : error.message;
+}

package/src/express.test.ts

@@ -0,0 +1,66 @@
+import { TRPC_ERROR_CODES_BY_KEY } from '@trpc/server/rpc';
+import { assert, describe, it } from 'vitest';
+
+import { formatTrpcErrorResponse, isMultipartRequest, isTrpcRequest } from './express.js';
+
+describe('isTrpcRequest', () => {
+  it('requires both the tRPC header and mount path segment', () => {
+    assert.isTrue(
+      isTrpcRequest({
+        header: (name) => (name === 'X-TRPC' ? 'true' : undefined),
+        originalUrl: '/pl/course/1/trpc/widgets.list?input=%7B%7D',
+      }),
+    );
+    assert.isFalse(
+      isTrpcRequest({
+        header: (name) => (name === 'X-TRPC' ? 'true' : undefined),
+        originalUrl: '/pl/course/1/not-trpc',
+      }),
+    );
+  });
+});
+
+describe('isMultipartRequest', () => {
+  it('matches the header name and media type case-insensitively', () => {
+    assert.isTrue(
+      isMultipartRequest({
+        headers: { 'Content-Type': 'Multipart/Form-Data; boundary=example' },
+      }),
+    );
+  });
+
+  it('rejects non-multipart and missing content types', () => {
+    assert.isFalse(isMultipartRequest({ headers: { 'content-type': 'application/json' } }));
+    assert.isFalse(isMultipartRequest({ headers: {} }));
+  });
+});
+
+describe('formatTrpcErrorResponse', () => {
+  it('maps an HTTP status to its tRPC error code', () => {
+    const response = formatTrpcErrorResponse({ status: 403, message: 'Request failed' });
+
+    assert.equal(response.error.json.code, TRPC_ERROR_CODES_BY_KEY.FORBIDDEN);
+    assert.equal(response.error.json.data.code, 'FORBIDDEN');
+    assert.equal(response.error.json.data.httpStatus, 403);
+  });
+
+  it('falls back to INTERNAL_SERVER_ERROR for an unknown status', () => {
+    const response = formatTrpcErrorResponse({ status: 418, message: 'Unexpected status' });
+
+    assert.equal(response.error.json.code, TRPC_ERROR_CODES_BY_KEY.INTERNAL_SERVER_ERROR);
+    assert.equal(response.error.json.data.code, 'INTERNAL_SERVER_ERROR');
+    assert.equal(response.error.json.data.httpStatus, 418);
+  });
+
+  it('includes a stack only when one is supplied', () => {
+    const withStack = formatTrpcErrorResponse({
+      status: 500,
+      message: 'Failed',
+      stack: 'stack trace',
+    });
+    const withoutStack = formatTrpcErrorResponse({ status: 500, message: 'Failed' });
+
+    assert.equal(withStack.error.json.data.stack, 'stack trace');
+    assert.notProperty(withoutStack.error.json.data, 'stack');
+  });
+});

package/src/express.ts

@@ -0,0 +1,103 @@
+import { TRPC_ERROR_CODES_BY_KEY, type TRPC_ERROR_CODE_KEY } from '@trpc/server/rpc';
+
+export interface TrpcRequestLike {
+  header(name: string): string | undefined;
+  originalUrl: string;
+}
+
+export interface RequestWithHeaders {
+  headers: Record<string, string | string[] | undefined>;
+}
+
+/**
+ * Returns true for a tRPC HTTP-link request whose procedure is mounted below a `trpc` path segment.
+ */
+export function isTrpcRequest(req: TrpcRequestLike): boolean {
+  // This header is spoofable; the URL path is what Express actually uses to dispatch.
+  if (req.header('X-TRPC') !== 'true') return false;
+  const pathOnly = req.originalUrl.split('?')[0];
+  const segments = pathOnly.split('/');
+  return segments.at(-2) === 'trpc';
+}
+
+/**
+ * Returns true when a request has a multipart/form-data content type.
+ *
+ * Use this to skip JSON and URL-encoded body parsers for file uploads and tRPC `FormData` inputs.
+ * Even when those parsers do not consume multipart data, they can assign an empty `req.body` that
+ * prevents the tRPC Express adapter from reading the original stream.
+ */
+export function isMultipartRequest(req: RequestWithHeaders): boolean {
+  const contentTypeEntry = Object.entries(req.headers).find(
+    ([headerName]) => headerName.toLowerCase() === 'content-type',
+  );
+  const contentType = contentTypeEntry?.[1];
+  const value = Array.isArray(contentType) ? contentType[0] : contentType;
+  return value?.toLowerCase().startsWith('multipart/form-data') ?? false;
+}
+
+const HTTP_STATUS_TO_TRPC_ERROR_CODE: Partial<Record<number, TRPC_ERROR_CODE_KEY>> = {
+  400: 'BAD_REQUEST',
+  401: 'UNAUTHORIZED',
+  402: 'PAYMENT_REQUIRED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  405: 'METHOD_NOT_SUPPORTED',
+  408: 'TIMEOUT',
+  409: 'CONFLICT',
+  412: 'PRECONDITION_FAILED',
+  413: 'PAYLOAD_TOO_LARGE',
+  415: 'UNSUPPORTED_MEDIA_TYPE',
+  422: 'UNPROCESSABLE_CONTENT',
+  428: 'PRECONDITION_REQUIRED',
+  429: 'TOO_MANY_REQUESTS',
+  499: 'CLIENT_CLOSED_REQUEST',
+  500: 'INTERNAL_SERVER_ERROR',
+  501: 'NOT_IMPLEMENTED',
+  502: 'BAD_GATEWAY',
+  503: 'SERVICE_UNAVAILABLE',
+  504: 'GATEWAY_TIMEOUT',
+};
+
+export interface TrpcErrorResponse {
+  error: {
+    json: {
+      message: string;
+      code: number;
+      data: {
+        code: TRPC_ERROR_CODE_KEY;
+        httpStatus: number;
+        stack?: string;
+      };
+    };
+  };
+}
+
+/**
+ * Formats an error thrown before the tRPC adapter as a SuperJSON-compatible tRPC response.
+ */
+export function formatTrpcErrorResponse({
+  status,
+  message,
+  stack,
+}: {
+  status: number;
+  message: string;
+  stack?: string;
+}): TrpcErrorResponse {
+  const code = HTTP_STATUS_TO_TRPC_ERROR_CODE[status] ?? 'INTERNAL_SERVER_ERROR';
+
+  return {
+    error: {
+      json: {
+        message,
+        code: TRPC_ERROR_CODES_BY_KEY[code],
+        data: {
+          code,
+          httpStatus: status,
+          ...(stack === undefined ? {} : { stack }),
+        },
+      },
+    },
+  };
+}

package/src/react.test.tsx

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+
+import { QueryClient } from '@tanstack/react-query';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, assert, describe, it } from 'vitest';
+
+import { AppErrorAlert, QueryClientProviderDebug } from './react.js';
+
+const testGlobal = globalThis as typeof globalThis & {
+  document: { createElement(tagName: string): Parameters<typeof createRoot>[0] };
+  IS_REACT_ACT_ENVIRONMENT?: boolean;
+  window: Window;
+};
+
+afterEach(() => {
+  delete testGlobal.window.__TANSTACK_QUERY_CLIENT__;
+  delete testGlobal.IS_REACT_ACT_ENVIRONMENT;
+});
+
+describe('AppErrorAlert', () => {
+  it('renders an error from a JSX element', () => {
+    const error = { code: 'EXPECTED' as const, message: 'Rendered application error' };
+    const markup = renderToStaticMarkup(
+      <AppErrorAlert
+        error={error}
+        render={{ EXPECTED: ({ message }) => <span>{message}</span> }}
+      />,
+    );
+
+    assert.include(markup, 'Rendered application error');
+  });
+});
+
+describe('QueryClientProviderDebug', () => {
+  it('exposes the client to browser devtools', async () => {
+    testGlobal.IS_REACT_ACT_ENVIRONMENT = true;
+    const client = new QueryClient();
+    const root = createRoot(testGlobal.document.createElement('div'));
+
+    assert.isUndefined(testGlobal.window.__TANSTACK_QUERY_CLIENT__);
+    await act(async () => {
+      root.render(
+        <QueryClientProviderDebug client={client}>
+          <span>Child</span>
+        </QueryClientProviderDebug>,
+      );
+    });
+    assert.strictEqual(testGlobal.window.__TANSTACK_QUERY_CLIENT__, client);
+
+    await act(async () => root.unmount());
+    client.clear();
+  });
+});

package/src/react.tsx

@@ -0,0 +1,53 @@
+import { type QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { type ReactNode, useEffect } from 'react';
+import { Alert, type AlertProps } from 'react-bootstrap';
+
+import { type AppErrorRenderers, renderAppError } from './client.js';
+
+declare global {
+  interface Window {
+    __TANSTACK_QUERY_CLIENT__?: QueryClient;
+  }
+}
+
+/** Renders an application error inside a Bootstrap alert. */
+export function AppErrorAlert<E extends { code: string; message: string }>({
+  error,
+  onDismiss,
+  variant = 'danger',
+  className,
+  render,
+}: {
+  error: E | null | undefined;
+  onDismiss?: () => void;
+  variant?: AlertProps['variant'];
+  className?: string;
+  render: AppErrorRenderers<E>;
+}) {
+  if (!error) return null;
+
+  return (
+    <Alert variant={variant} dismissible={!!onDismiss} className={className} onClose={onDismiss}>
+      {renderAppError(error, render)}
+    </Alert>
+  );
+}
+
+/** Provides a TanStack Query client and exposes it to browser devtools. */
+export function QueryClientProviderDebug({
+  client,
+  children,
+}: {
+  client: QueryClient;
+  children: ReactNode;
+}) {
+  // Expose the page's query client after mount so the browser extension can discover it.
+  useEffect(() => {
+    const browserWindow = (globalThis as { window?: Window }).window;
+    if (!browserWindow) return;
+
+    browserWindow.__TANSTACK_QUERY_CLIENT__ = client;
+  }, [client]);
+
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}