@sdxc/http 0.0.0-pre.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,272 @@
1
+ /**
2
+ * JSON response helpers, one per HTTP status code, pairing a JSON body with
3
+ * its matching status and status text.
4
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
5
+ * @copyright Sergio Xalambrí 2026
6
+ */
7
+ type Init = Omit<ResponseInit, "status" | "statusText">;
8
+ /**
9
+ * Creates a JSON response with HTTP 200 OK status.
10
+ * Use for successful requests that return data.
11
+ * @param body - The JSON data to send
12
+ * @param init - Optional response options (headers, etc.)
13
+ * @returns A Response with JSON body and 200 status
14
+ * @example
15
+ * return ok({ user: { id: 1, name: "John" } });
16
+ * @example
17
+ * return ok({ message: "Operation successful" }, { headers: { "X-Custom": "value" } });
18
+ */
19
+ export declare function ok<T>(body: T, init?: Init): Response;
20
+ /**
21
+ * Creates a JSON response with HTTP 201 Created status.
22
+ * Use when a new resource has been successfully created.
23
+ * @param body - The JSON data to send (typically the created resource)
24
+ * @param init - Optional response options (headers, etc.)
25
+ * @returns A Response with JSON body and 201 status
26
+ * @example
27
+ * return created({ id: 123, name: "New Item" });
28
+ * @example
29
+ * return created({ user: newUser }, { headers: { Location: `/users/${newUser.id}` } });
30
+ */
31
+ export declare function created<T>(body: T, init?: Init): Response;
32
+ /**
33
+ * Creates a JSON response with HTTP 202 Accepted status.
34
+ * Use when a request has been accepted for processing but not yet completed.
35
+ * @param body - The JSON data to send (typically processing status)
36
+ * @param init - Optional response options (headers, etc.)
37
+ * @returns A Response with JSON body and 202 status
38
+ * @example
39
+ * return accepted({ jobId: "abc123", status: "processing" });
40
+ * @example
41
+ * return accepted({ message: "Request queued", estimatedTime: "5 minutes" });
42
+ */
43
+ export declare function accepted<T>(body: T, init?: Init): Response;
44
+ /**
45
+ * Creates a JSON response with HTTP 400 Bad Request status.
46
+ * Use when the request is malformed or contains invalid data.
47
+ * @param body - The JSON data to send (typically error details)
48
+ * @param init - Optional response options (headers, etc.)
49
+ * @returns A Response with JSON body and 400 status
50
+ * @example
51
+ * return badRequest({ error: "Invalid email format" });
52
+ * @example
53
+ * return badRequest({ errors: [{ field: "email", message: "Required" }] });
54
+ */
55
+ export declare function badRequest<T>(body: T, init?: Init): Response;
56
+ /**
57
+ * Creates a JSON response with HTTP 401 Unauthorized status.
58
+ * Use when authentication is required but missing or invalid.
59
+ * @param body - The JSON data to send (typically error message)
60
+ * @param init - Optional response options (headers, etc.)
61
+ * @returns A Response with JSON body and 401 status
62
+ * @example
63
+ * return unauthorized({ error: "Invalid credentials" });
64
+ * @example
65
+ * return unauthorized({ error: "Token expired", code: "TOKEN_EXPIRED" });
66
+ */
67
+ export declare function unauthorized<T>(body: T, init?: Init): Response;
68
+ /**
69
+ * Creates a JSON response with HTTP 402 Payment Required status.
70
+ * Use when payment is required to access the resource.
71
+ * @param body - The JSON data to send (typically payment details)
72
+ * @param init - Optional response options (headers, etc.)
73
+ * @returns A Response with JSON body and 402 status
74
+ * @example
75
+ * return paymentRequired({ error: "Subscription required" });
76
+ * @example
77
+ * return paymentRequired({ error: "Credit limit exceeded", upgradeUrl: "/billing" });
78
+ */
79
+ export declare function paymentRequired<T>(body: T, init?: Init): Response;
80
+ /**
81
+ * Creates a JSON response with HTTP 403 Forbidden status.
82
+ * Use when the user is authenticated but lacks permission.
83
+ * @param body - The JSON data to send (typically error message)
84
+ * @param init - Optional response options (headers, etc.)
85
+ * @returns A Response with JSON body and 403 status
86
+ * @example
87
+ * return forbidden({ error: "Access denied" });
88
+ * @example
89
+ * return forbidden({ error: "Admin privileges required", requiredRole: "admin" });
90
+ */
91
+ export declare function forbidden<T>(body: T, init?: Init): Response;
92
+ /**
93
+ * Creates a JSON response with HTTP 404 Not Found status.
94
+ * Use when the requested resource does not exist.
95
+ * @param body - The JSON data to send (typically error message)
96
+ * @param init - Optional response options (headers, etc.)
97
+ * @returns A Response with JSON body and 404 status
98
+ * @example
99
+ * return notFound({ error: "User not found" });
100
+ * @example
101
+ * return notFound({ error: "Post not found", id: postId });
102
+ */
103
+ export declare function notFound<T>(body: T, init?: Init): Response;
104
+ /**
105
+ * Creates a JSON response with HTTP 405 Method Not Allowed status.
106
+ * Use when the HTTP method is not supported for the resource.
107
+ * @param body - The JSON data to send (typically allowed methods)
108
+ * @param init - Optional response options (headers, etc.)
109
+ * @returns A Response with JSON body and 405 status
110
+ * @example
111
+ * return methodNotAllowed({ error: "POST not allowed", allowed: ["GET", "PUT"] });
112
+ * @example
113
+ * return methodNotAllowed({ error: "Method not supported" });
114
+ */
115
+ export declare function methodNotAllowed<T>(body: T, init?: Init): Response;
116
+ /**
117
+ * Creates a JSON response with HTTP 406 Not Acceptable status.
118
+ * Use when the server cannot produce a response matching the Accept headers.
119
+ * @param body - The JSON data to send (typically available formats)
120
+ * @param init - Optional response options (headers, etc.)
121
+ * @returns A Response with JSON body and 406 status
122
+ * @example
123
+ * return notAcceptable({ error: "Cannot produce requested format" });
124
+ * @example
125
+ * return notAcceptable({ available: ["application/json", "text/html"] });
126
+ */
127
+ export declare function notAcceptable<T>(body: T, init?: Init): Response;
128
+ /**
129
+ * Creates a JSON response with HTTP 409 Conflict status.
130
+ * Use when the request conflicts with the current state of the resource.
131
+ * @param body - The JSON data to send (typically conflict details)
132
+ * @param init - Optional response options (headers, etc.)
133
+ * @returns A Response with JSON body and 409 status
134
+ * @example
135
+ * return conflict({ error: "Email already exists" });
136
+ * @example
137
+ * return conflict({ error: "Version mismatch", currentVersion: 5 });
138
+ */
139
+ export declare function conflict<T>(body: T, init?: Init): Response;
140
+ /**
141
+ * Creates a JSON response with HTTP 410 Gone status.
142
+ * Use when the resource existed but has been permanently removed.
143
+ * @param body - The JSON data to send (typically removal info)
144
+ * @param init - Optional response options (headers, etc.)
145
+ * @returns A Response with JSON body and 410 status
146
+ * @example
147
+ * return gone({ error: "Resource has been deleted" });
148
+ * @example
149
+ * return gone({ error: "API version deprecated", migrateUrl: "/v2" });
150
+ */
151
+ export declare function gone<T>(body: T, init?: Init): Response;
152
+ /**
153
+ * Creates a JSON response with HTTP 412 Precondition Failed status.
154
+ * Use when a precondition header (If-Match, etc.) evaluates to false.
155
+ * @param body - The JSON data to send (typically precondition details)
156
+ * @param init - Optional response options (headers, etc.)
157
+ * @returns A Response with JSON body and 412 status
158
+ * @example
159
+ * return preconditionFailed({ error: "ETag mismatch" });
160
+ * @example
161
+ * return preconditionFailed({ error: "Resource modified", currentETag: "abc123" });
162
+ */
163
+ export declare function preconditionFailed<T>(body: T, init?: Init): Response;
164
+ /**
165
+ * Creates a JSON response with HTTP 413 Payload Too Large status.
166
+ * Use when the request body exceeds the server's size limit.
167
+ * @param body - The JSON data to send (typically size limits)
168
+ * @param init - Optional response options (headers, etc.)
169
+ * @returns A Response with JSON body and 413 status
170
+ * @example
171
+ * return payloadTooLarge({ error: "File too large", maxSize: "10MB" });
172
+ * @example
173
+ * return payloadTooLarge({ error: "Request body exceeds limit" });
174
+ */
175
+ export declare function payloadTooLarge<T>(body: T, init?: Init): Response;
176
+ /**
177
+ * Creates a JSON response with HTTP 415 Unsupported Media Type status.
178
+ * Use when the request Content-Type is not supported.
179
+ * @param body - The JSON data to send (typically supported types)
180
+ * @param init - Optional response options (headers, etc.)
181
+ * @returns A Response with JSON body and 415 status
182
+ * @example
183
+ * return unsupportedMediaType({ error: "Content-Type not supported" });
184
+ * @example
185
+ * return unsupportedMediaType({ supported: ["application/json", "multipart/form-data"] });
186
+ */
187
+ export declare function unsupportedMediaType<T>(body: T, init?: Init): Response;
188
+ /**
189
+ * Creates a JSON response with HTTP 422 Unprocessable Entity status.
190
+ * Use when the request is well-formed but contains semantic errors.
191
+ * @param body - The JSON data to send (typically validation errors)
192
+ * @param init - Optional response options (headers, etc.)
193
+ * @returns A Response with JSON body and 422 status
194
+ * @example
195
+ * return unprocessableEntity({ errors: { email: "Invalid format" } });
196
+ * @example
197
+ * return unprocessableEntity({ error: "Start date must be before end date" });
198
+ */
199
+ export declare function unprocessableEntity<T>(body: T, init?: Init): Response;
200
+ /**
201
+ * Creates a JSON response with HTTP 429 Too Many Requests status.
202
+ * Use when the client has exceeded the rate limit.
203
+ * @param body - The JSON data to send (typically rate limit info)
204
+ * @param init - Optional response options (headers, etc.)
205
+ * @returns A Response with JSON body and 429 status
206
+ * @example
207
+ * return tooManyRequests({ error: "Rate limit exceeded", retryAfter: 60 });
208
+ * @example
209
+ * return tooManyRequests({ error: "Too many requests", limit: 100, window: "1h" });
210
+ */
211
+ export declare function tooManyRequests<T>(body: T, init?: Init): Response;
212
+ /**
213
+ * Creates a JSON response with HTTP 500 Internal Server Error status.
214
+ * Use when an unexpected server error occurs.
215
+ * @param body - The JSON data to send (typically generic error message)
216
+ * @param init - Optional response options (headers, etc.)
217
+ * @returns A Response with JSON body and 500 status
218
+ * @example
219
+ * return internalServerError({ error: "Something went wrong" });
220
+ * @example
221
+ * return internalServerError({ error: "Internal error", requestId: "abc123" });
222
+ */
223
+ export declare function internalServerError<T>(body: T, init?: Init): Response;
224
+ /**
225
+ * Creates a JSON response with HTTP 501 Not Implemented status.
226
+ * Use when the server does not support the requested functionality.
227
+ * @param body - The JSON data to send (typically feature status)
228
+ * @param init - Optional response options (headers, etc.)
229
+ * @returns A Response with JSON body and 501 status
230
+ * @example
231
+ * return notImplemented({ error: "Feature not implemented" });
232
+ * @example
233
+ * return notImplemented({ error: "Coming soon", plannedRelease: "Q2 2024" });
234
+ */
235
+ export declare function notImplemented<T>(body: T, init?: Init): Response;
236
+ /**
237
+ * Creates a JSON response with HTTP 502 Bad Gateway status.
238
+ * Use when an upstream server returned an invalid response.
239
+ * @param body - The JSON data to send (typically upstream error info)
240
+ * @param init - Optional response options (headers, etc.)
241
+ * @returns A Response with JSON body and 502 status
242
+ * @example
243
+ * return badGateway({ error: "Upstream server error" });
244
+ * @example
245
+ * return badGateway({ error: "Invalid response from payment provider" });
246
+ */
247
+ export declare function badGateway<T>(body: T, init?: Init): Response;
248
+ /**
249
+ * Creates a JSON response with HTTP 503 Service Unavailable status.
250
+ * Use when the server is temporarily unavailable (maintenance, overload).
251
+ * @param body - The JSON data to send (typically availability info)
252
+ * @param init - Optional response options (headers, etc.)
253
+ * @returns A Response with JSON body and 503 status
254
+ * @example
255
+ * return serviceUnavailable({ error: "Service under maintenance" });
256
+ * @example
257
+ * return serviceUnavailable({ error: "Server overloaded", retryAfter: 300 });
258
+ */
259
+ export declare function serviceUnavailable<T>(body: T, init?: Init): Response;
260
+ /**
261
+ * Creates a JSON response with HTTP 504 Gateway Timeout status.
262
+ * Use when an upstream server did not respond in time.
263
+ * @param body - The JSON data to send (typically timeout info)
264
+ * @param init - Optional response options (headers, etc.)
265
+ * @returns A Response with JSON body and 504 status
266
+ * @example
267
+ * return gatewayTimeout({ error: "Upstream server timeout" });
268
+ * @example
269
+ * return gatewayTimeout({ error: "Database connection timeout", timeout: "30s" });
270
+ */
271
+ export declare function gatewayTimeout<T>(body: T, init?: Init): Response;
272
+ export {};
@@ -0,0 +1,316 @@
1
+ /**
2
+ * JSON response helpers, one per HTTP status code, pairing a JSON body with
3
+ * its matching status and status text.
4
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
5
+ * @copyright Sergio Xalambrí 2026
6
+ */
7
+ import { json } from "../response.js";
8
+ import * as StatusCode from "../status-code.js";
9
+ /**
10
+ * Creates a JSON response with HTTP 200 OK status.
11
+ * Use for successful requests that return data.
12
+ * @param body - The JSON data to send
13
+ * @param init - Optional response options (headers, etc.)
14
+ * @returns A Response with JSON body and 200 status
15
+ * @example
16
+ * return ok({ user: { id: 1, name: "John" } });
17
+ * @example
18
+ * return ok({ message: "Operation successful" }, { headers: { "X-Custom": "value" } });
19
+ */
20
+ export function ok(body, init) {
21
+ return json(body, { ...init, ...StatusCode.Ok });
22
+ }
23
+ /**
24
+ * Creates a JSON response with HTTP 201 Created status.
25
+ * Use when a new resource has been successfully created.
26
+ * @param body - The JSON data to send (typically the created resource)
27
+ * @param init - Optional response options (headers, etc.)
28
+ * @returns A Response with JSON body and 201 status
29
+ * @example
30
+ * return created({ id: 123, name: "New Item" });
31
+ * @example
32
+ * return created({ user: newUser }, { headers: { Location: `/users/${newUser.id}` } });
33
+ */
34
+ export function created(body, init) {
35
+ return json(body, { ...init, ...StatusCode.Created });
36
+ }
37
+ /**
38
+ * Creates a JSON response with HTTP 202 Accepted status.
39
+ * Use when a request has been accepted for processing but not yet completed.
40
+ * @param body - The JSON data to send (typically processing status)
41
+ * @param init - Optional response options (headers, etc.)
42
+ * @returns A Response with JSON body and 202 status
43
+ * @example
44
+ * return accepted({ jobId: "abc123", status: "processing" });
45
+ * @example
46
+ * return accepted({ message: "Request queued", estimatedTime: "5 minutes" });
47
+ */
48
+ export function accepted(body, init) {
49
+ return json(body, { ...init, ...StatusCode.Accepted });
50
+ }
51
+ /**
52
+ * Creates a JSON response with HTTP 400 Bad Request status.
53
+ * Use when the request is malformed or contains invalid data.
54
+ * @param body - The JSON data to send (typically error details)
55
+ * @param init - Optional response options (headers, etc.)
56
+ * @returns A Response with JSON body and 400 status
57
+ * @example
58
+ * return badRequest({ error: "Invalid email format" });
59
+ * @example
60
+ * return badRequest({ errors: [{ field: "email", message: "Required" }] });
61
+ */
62
+ export function badRequest(body, init) {
63
+ return json(body, { ...init, ...StatusCode.BadRequest });
64
+ }
65
+ /**
66
+ * Creates a JSON response with HTTP 401 Unauthorized status.
67
+ * Use when authentication is required but missing or invalid.
68
+ * @param body - The JSON data to send (typically error message)
69
+ * @param init - Optional response options (headers, etc.)
70
+ * @returns A Response with JSON body and 401 status
71
+ * @example
72
+ * return unauthorized({ error: "Invalid credentials" });
73
+ * @example
74
+ * return unauthorized({ error: "Token expired", code: "TOKEN_EXPIRED" });
75
+ */
76
+ export function unauthorized(body, init) {
77
+ return json(body, { ...init, ...StatusCode.Unauthorized });
78
+ }
79
+ /**
80
+ * Creates a JSON response with HTTP 402 Payment Required status.
81
+ * Use when payment is required to access the resource.
82
+ * @param body - The JSON data to send (typically payment details)
83
+ * @param init - Optional response options (headers, etc.)
84
+ * @returns A Response with JSON body and 402 status
85
+ * @example
86
+ * return paymentRequired({ error: "Subscription required" });
87
+ * @example
88
+ * return paymentRequired({ error: "Credit limit exceeded", upgradeUrl: "/billing" });
89
+ */
90
+ export function paymentRequired(body, init) {
91
+ return json(body, { ...init, ...StatusCode.PaymentRequired });
92
+ }
93
+ /**
94
+ * Creates a JSON response with HTTP 403 Forbidden status.
95
+ * Use when the user is authenticated but lacks permission.
96
+ * @param body - The JSON data to send (typically error message)
97
+ * @param init - Optional response options (headers, etc.)
98
+ * @returns A Response with JSON body and 403 status
99
+ * @example
100
+ * return forbidden({ error: "Access denied" });
101
+ * @example
102
+ * return forbidden({ error: "Admin privileges required", requiredRole: "admin" });
103
+ */
104
+ export function forbidden(body, init) {
105
+ return json(body, { ...init, ...StatusCode.Forbidden });
106
+ }
107
+ /**
108
+ * Creates a JSON response with HTTP 404 Not Found status.
109
+ * Use when the requested resource does not exist.
110
+ * @param body - The JSON data to send (typically error message)
111
+ * @param init - Optional response options (headers, etc.)
112
+ * @returns A Response with JSON body and 404 status
113
+ * @example
114
+ * return notFound({ error: "User not found" });
115
+ * @example
116
+ * return notFound({ error: "Post not found", id: postId });
117
+ */
118
+ export function notFound(body, init) {
119
+ return json(body, { ...init, ...StatusCode.NotFound });
120
+ }
121
+ /**
122
+ * Creates a JSON response with HTTP 405 Method Not Allowed status.
123
+ * Use when the HTTP method is not supported for the resource.
124
+ * @param body - The JSON data to send (typically allowed methods)
125
+ * @param init - Optional response options (headers, etc.)
126
+ * @returns A Response with JSON body and 405 status
127
+ * @example
128
+ * return methodNotAllowed({ error: "POST not allowed", allowed: ["GET", "PUT"] });
129
+ * @example
130
+ * return methodNotAllowed({ error: "Method not supported" });
131
+ */
132
+ export function methodNotAllowed(body, init) {
133
+ return json(body, { ...init, ...StatusCode.MethodNotAllowed });
134
+ }
135
+ /**
136
+ * Creates a JSON response with HTTP 406 Not Acceptable status.
137
+ * Use when the server cannot produce a response matching the Accept headers.
138
+ * @param body - The JSON data to send (typically available formats)
139
+ * @param init - Optional response options (headers, etc.)
140
+ * @returns A Response with JSON body and 406 status
141
+ * @example
142
+ * return notAcceptable({ error: "Cannot produce requested format" });
143
+ * @example
144
+ * return notAcceptable({ available: ["application/json", "text/html"] });
145
+ */
146
+ export function notAcceptable(body, init) {
147
+ return json(body, { ...init, ...StatusCode.NotAcceptable });
148
+ }
149
+ /**
150
+ * Creates a JSON response with HTTP 409 Conflict status.
151
+ * Use when the request conflicts with the current state of the resource.
152
+ * @param body - The JSON data to send (typically conflict details)
153
+ * @param init - Optional response options (headers, etc.)
154
+ * @returns A Response with JSON body and 409 status
155
+ * @example
156
+ * return conflict({ error: "Email already exists" });
157
+ * @example
158
+ * return conflict({ error: "Version mismatch", currentVersion: 5 });
159
+ */
160
+ export function conflict(body, init) {
161
+ return json(body, { ...init, ...StatusCode.Conflict });
162
+ }
163
+ /**
164
+ * Creates a JSON response with HTTP 410 Gone status.
165
+ * Use when the resource existed but has been permanently removed.
166
+ * @param body - The JSON data to send (typically removal info)
167
+ * @param init - Optional response options (headers, etc.)
168
+ * @returns A Response with JSON body and 410 status
169
+ * @example
170
+ * return gone({ error: "Resource has been deleted" });
171
+ * @example
172
+ * return gone({ error: "API version deprecated", migrateUrl: "/v2" });
173
+ */
174
+ export function gone(body, init) {
175
+ return json(body, { ...init, ...StatusCode.Gone });
176
+ }
177
+ /**
178
+ * Creates a JSON response with HTTP 412 Precondition Failed status.
179
+ * Use when a precondition header (If-Match, etc.) evaluates to false.
180
+ * @param body - The JSON data to send (typically precondition details)
181
+ * @param init - Optional response options (headers, etc.)
182
+ * @returns A Response with JSON body and 412 status
183
+ * @example
184
+ * return preconditionFailed({ error: "ETag mismatch" });
185
+ * @example
186
+ * return preconditionFailed({ error: "Resource modified", currentETag: "abc123" });
187
+ */
188
+ export function preconditionFailed(body, init) {
189
+ return json(body, { ...init, ...StatusCode.PreconditionFailed });
190
+ }
191
+ /**
192
+ * Creates a JSON response with HTTP 413 Payload Too Large status.
193
+ * Use when the request body exceeds the server's size limit.
194
+ * @param body - The JSON data to send (typically size limits)
195
+ * @param init - Optional response options (headers, etc.)
196
+ * @returns A Response with JSON body and 413 status
197
+ * @example
198
+ * return payloadTooLarge({ error: "File too large", maxSize: "10MB" });
199
+ * @example
200
+ * return payloadTooLarge({ error: "Request body exceeds limit" });
201
+ */
202
+ export function payloadTooLarge(body, init) {
203
+ return json(body, { ...init, ...StatusCode.PayloadTooLarge });
204
+ }
205
+ /**
206
+ * Creates a JSON response with HTTP 415 Unsupported Media Type status.
207
+ * Use when the request Content-Type is not supported.
208
+ * @param body - The JSON data to send (typically supported types)
209
+ * @param init - Optional response options (headers, etc.)
210
+ * @returns A Response with JSON body and 415 status
211
+ * @example
212
+ * return unsupportedMediaType({ error: "Content-Type not supported" });
213
+ * @example
214
+ * return unsupportedMediaType({ supported: ["application/json", "multipart/form-data"] });
215
+ */
216
+ export function unsupportedMediaType(body, init) {
217
+ return json(body, { ...init, ...StatusCode.UnsupportedMediaType });
218
+ }
219
+ /**
220
+ * Creates a JSON response with HTTP 422 Unprocessable Entity status.
221
+ * Use when the request is well-formed but contains semantic errors.
222
+ * @param body - The JSON data to send (typically validation errors)
223
+ * @param init - Optional response options (headers, etc.)
224
+ * @returns A Response with JSON body and 422 status
225
+ * @example
226
+ * return unprocessableEntity({ errors: { email: "Invalid format" } });
227
+ * @example
228
+ * return unprocessableEntity({ error: "Start date must be before end date" });
229
+ */
230
+ export function unprocessableEntity(body, init) {
231
+ return json(body, { ...init, ...StatusCode.UnprocessableEntity });
232
+ }
233
+ /**
234
+ * Creates a JSON response with HTTP 429 Too Many Requests status.
235
+ * Use when the client has exceeded the rate limit.
236
+ * @param body - The JSON data to send (typically rate limit info)
237
+ * @param init - Optional response options (headers, etc.)
238
+ * @returns A Response with JSON body and 429 status
239
+ * @example
240
+ * return tooManyRequests({ error: "Rate limit exceeded", retryAfter: 60 });
241
+ * @example
242
+ * return tooManyRequests({ error: "Too many requests", limit: 100, window: "1h" });
243
+ */
244
+ export function tooManyRequests(body, init) {
245
+ return json(body, { ...init, ...StatusCode.TooManyRequests });
246
+ }
247
+ /**
248
+ * Creates a JSON response with HTTP 500 Internal Server Error status.
249
+ * Use when an unexpected server error occurs.
250
+ * @param body - The JSON data to send (typically generic error message)
251
+ * @param init - Optional response options (headers, etc.)
252
+ * @returns A Response with JSON body and 500 status
253
+ * @example
254
+ * return internalServerError({ error: "Something went wrong" });
255
+ * @example
256
+ * return internalServerError({ error: "Internal error", requestId: "abc123" });
257
+ */
258
+ export function internalServerError(body, init) {
259
+ return json(body, { ...init, ...StatusCode.InternalServerError });
260
+ }
261
+ /**
262
+ * Creates a JSON response with HTTP 501 Not Implemented status.
263
+ * Use when the server does not support the requested functionality.
264
+ * @param body - The JSON data to send (typically feature status)
265
+ * @param init - Optional response options (headers, etc.)
266
+ * @returns A Response with JSON body and 501 status
267
+ * @example
268
+ * return notImplemented({ error: "Feature not implemented" });
269
+ * @example
270
+ * return notImplemented({ error: "Coming soon", plannedRelease: "Q2 2024" });
271
+ */
272
+ export function notImplemented(body, init) {
273
+ return json(body, { ...init, ...StatusCode.NotImplemented });
274
+ }
275
+ /**
276
+ * Creates a JSON response with HTTP 502 Bad Gateway status.
277
+ * Use when an upstream server returned an invalid response.
278
+ * @param body - The JSON data to send (typically upstream error info)
279
+ * @param init - Optional response options (headers, etc.)
280
+ * @returns A Response with JSON body and 502 status
281
+ * @example
282
+ * return badGateway({ error: "Upstream server error" });
283
+ * @example
284
+ * return badGateway({ error: "Invalid response from payment provider" });
285
+ */
286
+ export function badGateway(body, init) {
287
+ return json(body, { ...init, ...StatusCode.BadGateway });
288
+ }
289
+ /**
290
+ * Creates a JSON response with HTTP 503 Service Unavailable status.
291
+ * Use when the server is temporarily unavailable (maintenance, overload).
292
+ * @param body - The JSON data to send (typically availability info)
293
+ * @param init - Optional response options (headers, etc.)
294
+ * @returns A Response with JSON body and 503 status
295
+ * @example
296
+ * return serviceUnavailable({ error: "Service under maintenance" });
297
+ * @example
298
+ * return serviceUnavailable({ error: "Server overloaded", retryAfter: 300 });
299
+ */
300
+ export function serviceUnavailable(body, init) {
301
+ return json(body, { ...init, ...StatusCode.ServiceUnavailable });
302
+ }
303
+ /**
304
+ * Creates a JSON response with HTTP 504 Gateway Timeout status.
305
+ * Use when an upstream server did not respond in time.
306
+ * @param body - The JSON data to send (typically timeout info)
307
+ * @param init - Optional response options (headers, etc.)
308
+ * @returns A Response with JSON body and 504 status
309
+ * @example
310
+ * return gatewayTimeout({ error: "Upstream server timeout" });
311
+ * @example
312
+ * return gatewayTimeout({ error: "Database connection timeout", timeout: "30s" });
313
+ */
314
+ export function gatewayTimeout(body, init) {
315
+ return json(body, { ...init, ...StatusCode.GatewayTimeout });
316
+ }