Skip to content

Commit 5bef1e3

Browse files
CrawlerCodeclaude
andcommitted
feat(client): match network errors in isRedmineRestError and export RuntimeRestError
Rename isRestError to isRedmineRestError. Without a status code it now also matches the runtime's RestError, which is thrown when the server can't be reached, so callers don't need an extra `error.name === "RestError"` check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 700f1cc commit 5bef1e3

3 files changed

Lines changed: 68 additions & 18 deletions

File tree

‎docs/content/docs/client/error-handling.mdx‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ When Redmine answers with a status code that isn't a success response of the ope
1414
| `response` | The raw response |
1515
| `message` | e.g. `Unexpected HTTP status code: 404 - HTTP 404 received for GET …` |
1616

17-
Network errors (server not reachable, invalid certificate) are thrown as they are, so they aren't a `RestError`.
17+
Network errors (server not reachable, invalid certificate) are thrown by the runtime as its own `RestError` class from `@typespec/ts-http-runtime`, exported as `RuntimeRestError`. It has a `code` such as `"ECONNREFUSED"`, but no `status`, so it isn't the exported `RestError`. See [Network errors](#network-errors).
1818

1919
## Status codes
2020

@@ -28,15 +28,15 @@ Network errors (server not reachable, invalid certificate) are thrown as they ar
2828

2929
## Checking the status
3030

31-
`isRestError` checks if an error is a `RestError`, optionally with the given status code. It compares the status as a number, so you don't have to convert the string:
31+
`isRedmineRestError` checks if an error is a `RestError` with the given status code. It compares the status as a number, so you don't have to convert the string:
3232

3333
```ts
34-
import { isRestError } from "redmine-api-client";
34+
import { isRedmineRestError } from "redmine-api-client";
3535

3636
try {
3737
await client.issuesClient.createIssue({ issue: { projectId: 1, subject: "" } });
3838
} catch (error) {
39-
if (isRestError(error, 422)) {
39+
if (isRedmineRestError(error, 422)) {
4040
console.error(error.body?.errors); // ["Subject cannot be blank"]
4141
} else {
4242
throw error;
@@ -58,6 +58,28 @@ if (error instanceof RestError) {
5858
`body` is typed as `any`, as each status code has its own body. Only `422` responses have `errors`, so access them with optional chaining.
5959
</Callout>
6060

61+
## Network errors
62+
63+
Without a status code, `isRedmineRestError` matches error responses and network errors, e.g. to show one message for every failed request:
64+
65+
```ts
66+
try {
67+
await client.issuesClient.getIssue(1);
68+
} catch (error) {
69+
if (isRedmineRestError(error)) {
70+
toast.error(`API error: ${error.message}`);
71+
} else {
72+
throw error;
73+
}
74+
}
75+
```
76+
77+
The narrowed error is a `RestError` or the runtime's error, so only their shared properties (`name`, `message`, `request`, `response`) are available without further checks. Use `error instanceof RestError` or `error instanceof RuntimeRestError` to tell them apart. With a status code, network errors never match, as they have no status.
78+
79+
<Callout>
80+
The runtime retries network errors a few times with a backoff before throwing. Pass `retryOptions: { maxRetries: 0 }` to the client options to fail right away.
81+
</Callout>
82+
6183
## Not found
6284

6385
To treat a missing resource as `undefined` instead of an error:
@@ -67,7 +89,7 @@ const findIssue = async (id: number) => {
6789
try {
6890
return (await client.issuesClient.getIssue(id)).issue;
6991
} catch (error) {
70-
if (isRestError(error, 404)) return undefined;
92+
if (isRedmineRestError(error, 404)) return undefined;
7193
throw error;
7294
}
7395
};
Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,35 @@
1+
import { isRestError as isRuntimeRestError, RestError as RuntimeRestError } from "@typespec/ts-http-runtime";
12
import { RestError } from "../../../generated/redmine-api-client/dist/helpers/error.js";
23

34
// The error the generated operations throw for unexpected status codes, which the generated client doesn't export
45
export { RestError };
6+
// The error the runtime throws for network errors, e.g. the server isn't reachable
7+
export { RuntimeRestError };
58

69
/**
7-
* Checks if `error` is a `RestError`, optionally with the given HTTP status code.
10+
* Checks if `error` is a `RestError` of an error response, or a network error, e.g. the server isn't reachable.
11+
* Network errors are the runtime's own `RestError` class, without `status` but with a `code` such as `"ECONNREFUSED"`.
12+
*
13+
* @example
14+
* if (isRedmineRestError(error)) toast.error(`API error: ${error.message}`);
15+
*/
16+
export function isRedmineRestError(error: unknown): error is RestError | RuntimeRestError;
17+
/**
18+
* Checks if `error` is a `RestError` with the given HTTP status code. Network errors have no status, so they never match.
819
*
920
* @example
1021
* try {
1122
* await client.issuesClient.createIssue({ issue: { projectId: 1, subject: "" } });
1223
* } catch (error) {
13-
* if (isRestError(error, 422)) console.error(error.body?.errors);
24+
* if (isRedmineRestError(error, 422)) console.error(error.body?.errors);
1425
* else throw error;
1526
* }
1627
*/
17-
export function isRestError(error: unknown, status?: number): error is RestError {
18-
// `status` is a string, as the runtime returns it
19-
return error instanceof RestError && (status === undefined || Number(error.status) === status);
28+
export function isRedmineRestError(error: unknown, status: number): error is RestError;
29+
export function isRedmineRestError(error: unknown, status?: number): boolean {
30+
if (error instanceof RestError) {
31+
// `status` is a string, as the runtime returns it
32+
return status === undefined || Number(error.status) === status;
33+
}
34+
return status === undefined && isRuntimeRestError(error);
2035
}

‎packages/redmine-api-client/tests/specs/errors.test.ts‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { describe, expect, it } from "vitest";
2-
import { isRestError, RestError } from "../../src/index.js";
2+
import { isRedmineRestError, RedmineClient, RestError, RuntimeRestError } from "../../src/index.js";
33
import { createFakeRedmine } from "../helpers/fakeRedmine.js";
44

55
describe("RestError", () => {
@@ -19,20 +19,33 @@ describe("RestError", () => {
1919
});
2020
});
2121

22-
describe("isRestError", () => {
22+
describe("isRedmineRestError", () => {
2323
it("checks the status code", async () => {
2424
const { client } = createFakeRedmine(() => ({ status: 404 }));
2525

2626
const error = await client.issuesClient.getIssue(1).catch((error: unknown) => error);
2727

28-
expect(isRestError(error)).toBe(true);
29-
expect(isRestError(error, 404)).toBe(true);
30-
expect(isRestError(error, 403)).toBe(false);
28+
expect(isRedmineRestError(error)).toBe(true);
29+
expect(isRedmineRestError(error, 404)).toBe(true);
30+
expect(isRedmineRestError(error, 403)).toBe(false);
3131
});
3232

3333
it("rejects other errors", () => {
34-
expect(isRestError(new Error("fetch failed"))).toBe(false);
35-
expect(isRestError(Object.assign(new Error(), { status: "404" }), 404)).toBe(false);
36-
expect(isRestError(undefined)).toBe(false);
34+
expect(isRedmineRestError(new Error("fetch failed"))).toBe(false);
35+
expect(isRedmineRestError(Object.assign(new Error(), { status: "404" }), 404)).toBe(false);
36+
expect(isRedmineRestError(undefined)).toBe(false);
37+
});
38+
39+
it("matches network errors without a status code", async () => {
40+
// Nothing listens on port 1, so the connection is refused (without retries, which would back off)
41+
const client = new RedmineClient("https://127.0.0.1:1", { key: "test" }, { retryOptions: { maxRetries: 0 } });
42+
43+
const error = await client.issuesClient.getIssue(1).catch((error: unknown) => error);
44+
45+
expect(error).not.toBeInstanceOf(RestError);
46+
expect(error).toBeInstanceOf(RuntimeRestError);
47+
expect(error).toMatchObject({ code: "ECONNREFUSED" });
48+
expect(isRedmineRestError(error)).toBe(true);
49+
expect(isRedmineRestError(error, 404)).toBe(false);
3750
});
3851
});

0 commit comments

Comments
 (0)