feat(qwik-router): isServerError() guard; export ServerError value from the runtime entry

Author: maiieul

.changeset/is-server-error-guard.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': minor
+---
+
+feat: `isServerError()` guard for narrowing errors in `catch` blocks (around `submit()` or `resolveValue()`) — structural, since `instanceof` doesn't survive client-side deserialization. `ServerError` is now also exported as a value from `@qwik.dev/router`.

packages/docs/src/routes/api/qwik-router-middleware-request-handler/api.json

@@ -356,6 +356,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/types.ts",
       "mdFile": "router.internalrequest.md"
     },
+    {
+      "name": "isServerError",
+      "id": "isservererror",
+      "hierarchy": [
+        {
+          "name": "isServerError",
+          "id": "isservererror"
+        }
+      ],
+      "kind": "Function",
+      "content": "Checks whether an error is a `ServerError` (carries `status` and `data`<!-- -->). Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.\n\n\n```typescript\nexport declare function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nerr\n\n\n</td><td>\n\n[ServerError](#servererror-variable)<!-- -->&lt;E&gt; \\| Error \\| undefined\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nerr is [ServerError](#servererror-variable)<!-- -->&lt;E&gt;",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts",
+      "mdFile": "router.isservererror.md"
+    },
     {
       "name": "mergeHeadersCookies",
       "id": "mergeheaderscookies",

packages/docs/src/routes/api/qwik-router-middleware-request-handler/index.mdx

@@ -872,6 +872,48 @@ export type InternalRequest = false | "loader" | "action";
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/types.ts)
 
+<h2 id="isservererror">isServerError</h2>
+
+Checks whether an error is a `ServerError` (carries `status` and `data`). Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.
+
+```typescript
+export declare function isServerError<E>(
+  err: ServerError<E> | Error | undefined,
+): err is ServerError<E>;
+```
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+err
+
+</td><td>
+
+[ServerError](#servererror-variable)&lt;E&gt; \| Error \| undefined
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+err is [ServerError](#servererror-variable)&lt;E&gt;
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts)
+
 <h2 id="mergeheaderscookies">mergeHeadersCookies</h2>
 
 ```typescript

packages/docs/src/routes/api/qwik-router/api.json

@@ -334,7 +334,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface FormSubmitCompletedDetail<T, ERROR = unknown> \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nerror\n\n\n</td><td>\n\n\n</td><td>\n\n[ServerError](#servererror-variable)<!-- -->&lt;ERROR&gt; \\| undefined\n\n\n</td><td>\n\nThe `ServerError` from a returned `fail()` or a failed validator.\n\n\n</td></tr>\n<tr><td>\n\nstatus\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nvalue\n\n\n</td><td>\n\n\n</td><td>\n\nT \\| undefined\n\n\n</td><td>\n\nThe action's successful return value. `undefined` when the action failed or aborted.\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface FormSubmitCompletedDetail<T, ERROR = unknown> \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nerror\n\n\n</td><td>\n\n\n</td><td>\n\n[ServerError](#servererror-variable)<!-- -->&lt;ERROR&gt; \\| undefined\n\n\n</td><td>\n\nThe `ServerError` from a returned `fail()` or a failed validator.\n\n\n</td></tr>\n<tr><td>\n\nstatus\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nvalue\n\n\n</td><td>\n\n\n</td><td>\n\nT \\| undefined\n\n\n</td><td>\n\nThe action's successful return value. `undefined` when the action failed.\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/form-component.tsx",
       "mdFile": "router.formsubmitsuccessdetail.md"
     },
@@ -408,6 +408,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
       "mdFile": "router.httperrorprops.md"
     },
+    {
+      "name": "isServerError",
+      "id": "isservererror",
+      "hierarchy": [
+        {
+          "name": "isServerError",
+          "id": "isservererror"
+        }
+      ],
+      "kind": "Function",
+      "content": "Checks whether an error is a `ServerError` (carries `status` and `data`<!-- -->). Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.\n\n\n```typescript\nexport declare function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nerr\n\n\n</td><td>\n\n[ServerError](#servererror-variable)<!-- -->&lt;E&gt; \\| Error \\| undefined\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nerr is [ServerError](#servererror-variable)<!-- -->&lt;E&gt;",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts",
+      "mdFile": "router.isservererror.md"
+    },
     {
       "name": "JSONObject",
       "id": "jsonobject",

packages/docs/src/routes/api/qwik-router/index.mdx

@@ -1048,7 +1048,7 @@ T \| undefined
 
 </td><td>
 
-The action's successful return value. `undefined` when the action failed or aborted.
+The action's successful return value. `undefined` when the action failed.
 
 </td></tr>
 </tbody></table>
@@ -1115,6 +1115,48 @@ export type HttpStatus = {
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts)
 
+<h2 id="isservererror">isServerError</h2>
+
+Checks whether an error is a `ServerError` (carries `status` and `data`). Structural rather than `instanceof` so it also matches ServerErrors that crossed a serialization boundary.
+
+```typescript
+export declare function isServerError<E>(
+  err: ServerError<E> | Error | undefined,
+): err is ServerError<E>;
+```
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+err
+
+</td><td>
+
+[ServerError](#servererror-variable)&lt;E&gt; \| Error \| undefined
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+err is [ServerError](#servererror-variable)&lt;E&gt;
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/middleware/request-handler/fail.ts)
+
 <h2 id="jsonobject">JSONObject</h2>
 
 ```typescript

packages/qwik-router/src/middleware/request-handler/fail.ts

@@ -65,6 +65,23 @@ export function getFailMeta(value: Failed): FailMeta {
   return value[FailBrand];
 }
 
+/**
+ * Checks whether an error is a `ServerError` (carries `status` and `data`). Structural rather than
+ * `instanceof` so it also matches ServerErrors that crossed a serialization boundary.
+ *
+ * @public
+ */
+export function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;
+/** @public */
+export function isServerError<T = unknown>(err: unknown): err is ServerError<T>;
+export function isServerError(err: unknown): boolean {
+  return (
+    err instanceof Error &&
+    typeof (err as { status?: unknown }).status === 'number' &&
+    'data' in err
+  );
+}
+
 export function failToServerError(value: FailReturn<Record<string, any>>): ServerError {
   const { ...payload } = value;
   return new ServerError(getFailMeta(value).status, payload);

packages/qwik-router/src/middleware/request-handler/index.ts

@@ -8,7 +8,7 @@ export { isStaticPath } from './static-paths';
 export { mergeHeadersCookies } from './cookie';
 
 export { ServerError } from './server-error';
-export { FailBrand } from './fail';
+export { FailBrand, isServerError } from './fail';
 export type { Failed, FailMeta, FailReturn, ExcludeFail, FailPayload } from './fail';
 export { AbortMessage, RedirectMessage } from './redirect-handler';
 export { RewriteMessage } from './rewrite-handler';

packages/qwik-router/src/middleware/request-handler/middleware.request-handler.api.md

@@ -123,6 +123,12 @@ export function getNotFound(prefix: string): string;
 // @public
 export type InternalRequest = false | 'loader' | 'action';
 
+// @public
+export function isServerError<E>(err: ServerError<E> | Error | undefined): err is ServerError<E>;
+
+// @public (undocumented)
+export function isServerError<T = unknown>(err: unknown): err is ServerError<T>;
+
 // Warning: (ae-internal-missing-underscore) The name "isStaticPath" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal

packages/qwik-router/src/middleware/request-handler/server-error.unit.ts

@@ -1,4 +1,5 @@
 import { describe, expect, expectTypeOf, test } from 'vitest';
+import { isServerError } from './fail';
 import { ServerError } from './server-error';
 
 describe('ServerError payload flattening', () => {
@@ -56,3 +57,14 @@ describe('ServerError payload flattening', () => {
     expectTypeOf(err.data.message).toEqualTypeOf<string[]>();
   });
 });
+
+describe('isServerError', () => {
+  test('matches real instances and serialization-shaped plain Errors', () => {
+    expect(isServerError(new ServerError(404, { reason: 'x' }))).toBe(true);
+    const wireShaped = Object.assign(new Error('x'), { status: 404, data: { reason: 'x' } });
+    expect(isServerError(wireShaped)).toBe(true);
+    expect(isServerError(new Error('network'))).toBe(false);
+    expect(isServerError(undefined)).toBe(false);
+    expect(isServerError({ status: 404, data: {} })).toBe(false);
+  });
+});

packages/qwik-router/src/runtime/src/index.ts

@@ -90,7 +90,8 @@ export {
   zodQrl,
 } from './server-functions';
 export { routeLoader$, routeLoaderQrl } from './route-loaders';
-export type { ServerError } from '../../middleware/request-handler/server-error';
+export { isServerError } from '../../middleware/request-handler/fail';
+export { ServerError } from '../../middleware/request-handler/server-error';
 export { ServiceWorkerRegister } from './sw-component';
 export {
   useContent,