@prairielearn/trpc 0.0.0 → 1.0.0

package/src/server.test.ts

@@ -0,0 +1,51 @@
+import { TRPCError } from '@trpc/server';
+import { TRPC_ERROR_CODES_BY_KEY } from '@trpc/server/rpc';
+import { assert, describe, expectTypeOf, it } from 'vitest';
+
+import type { AppError } from './client.js';
+import { appErrorFormatter, throwAppError } from './server.js';
+
+interface WholeErrorMap {
+  First: { code: 'FIRST_ONLY'; first: string } | { code: 'SHARED'; shared: string };
+  Second: { code: 'SECOND_ONLY'; second: string } | { code: 'SHARED'; shared: string };
+}
+
+describe('typed application errors', () => {
+  it('serializes typed metadata through the error formatter', () => {
+    const error = assert.throws(() => {
+      throwAppError<WholeErrorMap['First']>(
+        {
+          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', () => {
+    type WholeMapThrowInput = Parameters<typeof throwAppError<WholeErrorMap>>[0];
+
+    expectTypeOf<WholeMapThrowInput['code']>().toEqualTypeOf<'SHARED'>();
+    expectTypeOf<AppError<WholeErrorMap>['code']>().toEqualTypeOf<
+      'FIRST_ONLY' | 'SECOND_ONLY' | 'SHARED' | 'UNKNOWN'
+    >();
+  });
+});

package/src/server.ts

@@ -0,0 +1,77 @@
+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 };
+}
+
+class AppError extends TRPCError {
+  constructor(
+    public readonly meta: AppErrorBase,
+    trpcCode: TRPC_ERROR_CODE_KEY = 'BAD_REQUEST',
+  ) {
+    super({ code: trpcCode, message: meta.message });
+  }
+}
+
+/**
+ * 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: TRPCDefaultErrorShape;
+  error: TRPCError;
+}): AppErrorShape => ({
+  ...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<T>(
+  meta: AppErrorInput<T>,
+  trpcCode: TRPC_ERROR_CODE_KEY = 'BAD_REQUEST',
+): never {
+  throw new AppError(meta as unknown as AppErrorBase, trpcCode);
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@prairielearn/tsconfig/tsconfig.package-node.json",
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    dir: `${import.meta.dirname}/src`,
+    coverage: {
+      reporter: ['html', 'text-summary', 'cobertura'],
+      include: ['src/**/*.{ts,tsx}'],
+    },
+  },
+});