xypriss 9.10.21 → 9.10.23

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.
package/dist/index.d.ts CHANGED
@@ -2,6 +2,7 @@ import { Server, IncomingMessage, ServerResponse } from 'http';
2
2
  import { SecureCacheAdapter } from 'xypriss-security';
3
3
  import * as reliant_type from 'reliant-type';
4
4
  import { Readable, Writable } from 'node:stream';
5
+ import { XyPrisResponse as XyPrisResponse$2 } from 'xypriss';
5
6
 
6
7
  declare const LOG_LEVELS: readonly ["silent", "error", "warn", "info", "debug", "verbose"];
7
8
  type LogLevel = (typeof LOG_LEVELS)[number];
@@ -11142,6 +11143,549 @@ type IpSource = "cf-connecting-ip" | "true-client-ip" | "x-real-ip" | "x-forward
11142
11143
  declare function getIp(req: XyPrisRequest): string;
11143
11144
  declare function getIp(req: XyPrisRequest, enriched: true): GetIpResult;
11144
11145
 
11146
+ /**
11147
+ * @file Send.ts
11148
+ * @description Structured HTTP error & success response helper for the XyPriss framework.
11149
+ *
11150
+ * @copyright Copyright © 2025–2026 NEHONIX. All Rights Reserved.
11151
+ * @license NEHONIX Open Source License v2.0 (NOSL v2)
11152
+ * https://dll.nehonix.com/licenses/NOSL/v2
11153
+ *
11154
+ * This file is part of a NEHONIX open source project.
11155
+ * You may use, modify, and redistribute it freely — including for commercial
11156
+ * purposes — provided that NEHONIX is always credited as the original author.
11157
+ *
11158
+ * @author NEHONIX
11159
+ */
11160
+
11161
+ /**
11162
+ * All HTTP status keys supported by the `Send` helper.
11163
+ * Each key maps to a standard HTTP status code.
11164
+ *
11165
+ * — 2xx Success
11166
+ * — 3xx Redirection
11167
+ * — 4xx Client errors
11168
+ * — 5xx Server errors
11169
+ */
11170
+ type SupportedStatus = "OK" | "CREATED" | "ACCEPTED" | "NO_CONTENT" | "MOVED_PERMANENTLY" | "FOUND" | "NOT_MODIFIED" | "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "NOT_ACCEPTABLE" | "CONFLICT" | "GONE" | "UNPROCESSABLE_ENTITY" | "LOCKED" | "TOO_MANY_REQUEST" | "PAYLOAD_TOO_LARGE" | "UNSUPPORTED_MEDIA_TYPE" | "REQUEST_TIMEOUT" | "PRECONDITION_FAILED" | "EXPECTATION_FAILED" | "IM_A_TEAPOT" | "INTERNAL_SERVER_ERR" | "NOT_IMPLEMENTED" | "BAD_GATEWAY" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT";
11171
+ /**
11172
+ * Maps every {@link SupportedStatus} key to its corresponding HTTP status code.
11173
+ */
11174
+ type ISeConfigs = Record<SupportedStatus, number>;
11175
+ /**
11176
+ * Signature shared by all public dispatch methods.
11177
+ *
11178
+ * @param message - Human-readable description shown to the API consumer.
11179
+ * @param data - Optional payload to attach to the response body.
11180
+ */
11181
+ type TSendPropsFn = (message?: string, data?: unknown) => void;
11182
+ /**
11183
+ * Contract that the {@link Send} class must satisfy.
11184
+ */
11185
+ interface ISeResponder {
11186
+ ok: TSendPropsFn;
11187
+ created: TSendPropsFn;
11188
+ accepted: TSendPropsFn;
11189
+ noContent: () => void;
11190
+ movedPermanently: TSendPropsFn;
11191
+ found: TSendPropsFn;
11192
+ notModified: () => void;
11193
+ badRequest: TSendPropsFn;
11194
+ unauthorized: TSendPropsFn;
11195
+ forbidden: TSendPropsFn;
11196
+ notFound: TSendPropsFn;
11197
+ methodNotAllowed: TSendPropsFn;
11198
+ notAcceptable: TSendPropsFn;
11199
+ conflict: TSendPropsFn;
11200
+ gone: TSendPropsFn;
11201
+ unprocessableEntity: TSendPropsFn;
11202
+ locked: TSendPropsFn;
11203
+ tooManyRequest: TSendPropsFn;
11204
+ payloadTooLarge: TSendPropsFn;
11205
+ unsupportedMediaType: TSendPropsFn;
11206
+ requestTimeout: TSendPropsFn;
11207
+ preconditionFailed: TSendPropsFn;
11208
+ expectationFailed: TSendPropsFn;
11209
+ imATeapot: TSendPropsFn;
11210
+ internalError: TSendPropsFn;
11211
+ notImplemented: TSendPropsFn;
11212
+ badGateway: TSendPropsFn;
11213
+ serviceUnavailable: TSendPropsFn;
11214
+ gatewayTimeout: TSendPropsFn;
11215
+ }
11216
+ /**
11217
+ * Shape of every JSON response body produced by this helper.
11218
+ *
11219
+ * @property success - `true` for 2xx responses, `false` for everything else.
11220
+ * @property message - Human-readable summary of the outcome.
11221
+ * @property serverName - Identifier of the server that handled the request.
11222
+ * @property data - Optional payload (echoed from the caller when relevant).
11223
+ * @property details - Machine-readable metadata about the response.
11224
+ */
11225
+ interface IResTemplate {
11226
+ success: boolean;
11227
+ message: string;
11228
+ serverName?: string;
11229
+ data?: unknown;
11230
+ details: {
11231
+ /** Short label (e.g. `"Bad Request"`, `"OK"`). */
11232
+ error: string;
11233
+ /** Compact code derived from the status key (e.g. `"EBADR"`, `"SOK"`). */
11234
+ statusCode: number;
11235
+ /** The HTTP status code that was sent. */
11236
+ errorCode: string;
11237
+ };
11238
+ }
11239
+ /**
11240
+ * A structured HTTP response helper that standardises all responses across
11241
+ * the application — both success and error paths.
11242
+ *
11243
+ * Every method sends a JSON body conforming to {@link IResTemplate}, ensuring
11244
+ * consistent shapes for API consumers regardless of where the response
11245
+ * originates.
11246
+ *
11247
+ * @example
11248
+ * ```ts
11249
+ * const send = new Send(res);
11250
+ *
11251
+ * // ── 2xx ──────────────────────────────────────────────────────────────────
11252
+ * send.ok("User fetched.", { id: 1, name: "Alice" });
11253
+ * send.created("User created.", { id: 42 });
11254
+ * send.accepted("Your export is being processed.");
11255
+ * send.noContent();
11256
+ *
11257
+ * // ── 4xx ──────────────────────────────────────────────────────────────────
11258
+ * send.badRequest("The 'email' field is required.");
11259
+ * send.unauthorized("Please log in to continue.");
11260
+ * send.forbidden("You do not have permission to access this resource.");
11261
+ * send.notFound("User not found.", { userId: 42 });
11262
+ * send.methodNotAllowed("POST is not allowed on this endpoint.");
11263
+ * send.conflict("A user with this email already exists.");
11264
+ * send.gone("This resource has been permanently deleted.");
11265
+ * send.unprocessableEntity("Validation failed.", { fields: { email: "Invalid format" } });
11266
+ * send.tooManyRequest("Rate limit reached. Try again in 60 seconds.");
11267
+ * send.payloadTooLarge("File exceeds the 10 MB limit.");
11268
+ * send.unsupportedMediaType("Only application/json is accepted.");
11269
+ *
11270
+ * // ── 5xx ──────────────────────────────────────────────────────────────────
11271
+ * send.internalError("An unexpected error occurred.");
11272
+ * send.notImplemented("This feature is not yet available.");
11273
+ * send.serviceUnavailable("The server is temporarily down for maintenance.");
11274
+ * send.gatewayTimeout("The upstream service did not respond in time.");
11275
+ * ```
11276
+ */
11277
+ declare class Send implements ISeResponder {
11278
+ private readonly res;
11279
+ private readonly configs;
11280
+ private readonly serverName;
11281
+ private readonly includeServerName;
11282
+ /**
11283
+ * Creates a new `Send` instance bound to the given response object.
11284
+ *
11285
+ * @param res - The active `XyPrisResponse` to write into.
11286
+ * @param configs - Optional overrides for the default status-code registry
11287
+ * and display options.
11288
+ */
11289
+ constructor(res: XyPrisResponse$2, configs?: Partial<{
11290
+ statusCode: Partial<ISeConfigs>;
11291
+ includeServerName: boolean;
11292
+ }>);
11293
+ /**
11294
+ * Resolves the status code, builds the full response body, and flushes it.
11295
+ *
11296
+ * @param statusKey - One of the {@link SupportedStatus} keys.
11297
+ * @param label - Human-readable short label for the status type.
11298
+ * @param success - Whether this is a success response.
11299
+ * @param message - Optional caller-supplied message; falls back to `label`.
11300
+ * @param data - Optional payload to attach to the response body.
11301
+ */
11302
+ private dispatch;
11303
+ /**
11304
+ * Sends a **200 OK** response.
11305
+ *
11306
+ * The standard success response for GET, PUT, PATCH, or DELETE requests
11307
+ * that return a body.
11308
+ *
11309
+ * @param message - Human-readable confirmation.
11310
+ * @param data - Payload to return to the client.
11311
+ *
11312
+ * @example
11313
+ * send.ok("User fetched successfully.", { id: 1, name: "Alice" });
11314
+ */
11315
+ ok: TSendPropsFn;
11316
+ /**
11317
+ * Sends a **201 Created** response.
11318
+ *
11319
+ * Use after successfully creating a new resource.
11320
+ * Consider also setting a `Location` header pointing to the new resource.
11321
+ *
11322
+ * @param message - Human-readable confirmation.
11323
+ * @param data - The newly created resource or its identifier.
11324
+ *
11325
+ * @example
11326
+ * send.created("User created.", { id: 42 });
11327
+ */
11328
+ created: TSendPropsFn;
11329
+ /**
11330
+ * Sends a **202 Accepted** response.
11331
+ *
11332
+ * Use when the request has been accepted but processing will happen
11333
+ * asynchronously (e.g. background jobs, email dispatch, report generation).
11334
+ *
11335
+ * @param message - Human-readable explanation of what will happen.
11336
+ * @param data - Optional tracking info (e.g. job ID).
11337
+ *
11338
+ * @example
11339
+ * send.accepted("Your export is being processed.", { jobId: "abc-123" });
11340
+ */
11341
+ accepted: TSendPropsFn;
11342
+ /**
11343
+ * Sends a **204 No Content** response.
11344
+ *
11345
+ * Use after a successful DELETE or an action that produces no body.
11346
+ * RFC 7231 forbids a body for 204 — this method sends status only.
11347
+ *
11348
+ * @example
11349
+ * send.noContent();
11350
+ */
11351
+ noContent: () => void;
11352
+ /**
11353
+ * Sends a **301 Moved Permanently** response.
11354
+ *
11355
+ * Use when a resource has been permanently relocated. Clients and search
11356
+ * engines should update their references.
11357
+ *
11358
+ * @param message - Optional explanation or the new URL.
11359
+ * @param data - Optional payload (e.g. `{ location: "https://…" }`).
11360
+ *
11361
+ * @example
11362
+ * send.movedPermanently("This endpoint has moved.", { location: "/v2/users" });
11363
+ */
11364
+ movedPermanently: TSendPropsFn;
11365
+ /**
11366
+ * Sends a **302 Found** response.
11367
+ *
11368
+ * Use for temporary redirects. The client should continue using the
11369
+ * original URL for future requests.
11370
+ *
11371
+ * @param message - Optional explanation or the temporary URL.
11372
+ * @param data - Optional payload (e.g. `{ location: "https://…" }`).
11373
+ *
11374
+ * @example
11375
+ * send.found("Redirecting to login.", { location: "/auth/login" });
11376
+ */
11377
+ found: TSendPropsFn;
11378
+ /**
11379
+ * Sends a **304 Not Modified** response.
11380
+ *
11381
+ * Use with conditional requests (`If-None-Match`, `If-Modified-Since`).
11382
+ * Tells the client its cached version is still valid.
11383
+ *
11384
+ * @example
11385
+ * send.notModified();
11386
+ */
11387
+ notModified: () => void;
11388
+ /**
11389
+ * Sends a **400 Bad Request** response.
11390
+ *
11391
+ * Use when the client submits a malformed or invalid request
11392
+ * (e.g. missing required fields, invalid format, constraint violation).
11393
+ *
11394
+ * @param message - Human-readable explanation of why the request was rejected.
11395
+ * @param data - Optional payload (e.g. a list of validation errors per field).
11396
+ *
11397
+ * @example
11398
+ * send.badRequest("The 'username' field must be at least 3 characters.");
11399
+ * send.badRequest("Validation failed.", { fields: { email: "Invalid format" } });
11400
+ */
11401
+ badRequest: TSendPropsFn;
11402
+ /**
11403
+ * Sends a **401 Unauthorized** response.
11404
+ *
11405
+ * Use when the request lacks valid authentication credentials.
11406
+ * Despite the name, this is an *authentication* failure — not authorisation.
11407
+ *
11408
+ * @param message - Human-readable explanation (avoid leaking token details).
11409
+ * @param data - Optional payload (e.g. `{ authScheme: "Bearer" }`).
11410
+ *
11411
+ * @example
11412
+ * send.unauthorized("Authentication token is missing or expired.");
11413
+ */
11414
+ unauthorized: TSendPropsFn;
11415
+ /**
11416
+ * Sends a **403 Forbidden** response.
11417
+ *
11418
+ * Use when the client is authenticated but lacks permission to access
11419
+ * the resource. Unlike 401, re-authenticating will not help.
11420
+ *
11421
+ * @param message - Human-readable explanation of the permission boundary.
11422
+ * @param data - Optional payload (e.g. required role/scope info).
11423
+ *
11424
+ * @example
11425
+ * send.forbidden("You do not have permission to delete this resource.");
11426
+ * send.forbidden("Admin role required.", { requiredRole: "admin" });
11427
+ */
11428
+ forbidden: TSendPropsFn;
11429
+ /**
11430
+ * Sends a **404 Not Found** response.
11431
+ *
11432
+ * Use when the requested resource does not exist or has been permanently removed.
11433
+ *
11434
+ * @param message - Human-readable explanation of what could not be found.
11435
+ * @param data - Optional payload (e.g. the identifier that was looked up).
11436
+ *
11437
+ * @example
11438
+ * send.notFound("No user found with id '42'.");
11439
+ * send.notFound("Resource not found.", { id: "42" });
11440
+ */
11441
+ notFound: TSendPropsFn;
11442
+ /**
11443
+ * Sends a **405 Method Not Allowed** response.
11444
+ *
11445
+ * Use when the HTTP method used is not supported on the target endpoint.
11446
+ * Always pair this with an `Allow` header listing permitted methods.
11447
+ *
11448
+ * @param message - Human-readable explanation of the allowed methods.
11449
+ * @param data - Optional payload (e.g. `{ allowedMethods: ["GET", "POST"] }`).
11450
+ *
11451
+ * @example
11452
+ * send.methodNotAllowed("Only GET and POST are allowed on this route.");
11453
+ * send.methodNotAllowed("Method not allowed.", { allowedMethods: ["GET", "POST"] });
11454
+ */
11455
+ methodNotAllowed: TSendPropsFn;
11456
+ /**
11457
+ * Sends a **406 Not Acceptable** response.
11458
+ *
11459
+ * Use when the server cannot produce a response matching the client's
11460
+ * `Accept` header (content-type negotiation failure).
11461
+ *
11462
+ * @param message - Human-readable explanation of supported content types.
11463
+ * @param data - Optional payload (e.g. `{ supportedTypes: ["application/json"] }`).
11464
+ *
11465
+ * @example
11466
+ * send.notAcceptable("This API only serves application/json.");
11467
+ */
11468
+ notAcceptable: TSendPropsFn;
11469
+ /**
11470
+ * Sends a **408 Request Timeout** response.
11471
+ *
11472
+ * Use when the server times out waiting for the client to complete its
11473
+ * request within the allowed time window.
11474
+ *
11475
+ * @param message - Human-readable explanation of the timeout.
11476
+ * @param data - Optional payload (e.g. `{ timeoutMs: 5000 }`).
11477
+ *
11478
+ * @example
11479
+ * send.requestTimeout("The request took too long. Please try again.");
11480
+ */
11481
+ requestTimeout: TSendPropsFn;
11482
+ /**
11483
+ * Sends a **409 Conflict** response.
11484
+ *
11485
+ * Use when the request conflicts with the current state of the resource
11486
+ * (e.g. duplicate entry, optimistic-lock violation, concurrent edit clash).
11487
+ *
11488
+ * @param message - Human-readable explanation of the conflict.
11489
+ * @param data - Optional payload (e.g. the conflicting resource).
11490
+ *
11491
+ * @example
11492
+ * send.conflict("A user with this email already exists.");
11493
+ * send.conflict("Edit conflict detected.", { existingVersion: 3, yourVersion: 2 });
11494
+ */
11495
+ conflict: TSendPropsFn;
11496
+ /**
11497
+ * Sends a **410 Gone** response.
11498
+ *
11499
+ * Use when a resource has been *permanently* deleted and will not return.
11500
+ * Prefer 404 when you don't want to reveal whether the resource ever existed.
11501
+ *
11502
+ * @param message - Human-readable explanation of the permanent removal.
11503
+ * @param data - Optional payload (e.g. deletion date).
11504
+ *
11505
+ * @example
11506
+ * send.gone("This account has been permanently deleted.");
11507
+ */
11508
+ gone: TSendPropsFn;
11509
+ /**
11510
+ * Sends a **412 Precondition Failed** response.
11511
+ *
11512
+ * Use when a conditional request (`If-Match`, `If-Unmodified-Since`) fails
11513
+ * because the precondition evaluated to false on the server.
11514
+ *
11515
+ * @param message - Human-readable explanation of the failed precondition.
11516
+ * @param data - Optional payload (e.g. current ETag or last-modified date).
11517
+ *
11518
+ * @example
11519
+ * send.preconditionFailed("ETag mismatch — resource was modified since your last fetch.");
11520
+ */
11521
+ preconditionFailed: TSendPropsFn;
11522
+ /**
11523
+ * Sends a **413 Payload Too Large** response.
11524
+ *
11525
+ * Use when the request body exceeds the server's or route's size limit.
11526
+ *
11527
+ * @param message - Human-readable explanation including the size limit when safe.
11528
+ * @param data - Optional payload (e.g. `{ maxBytes: 10_485_760 }`).
11529
+ *
11530
+ * @example
11531
+ * send.payloadTooLarge("File exceeds the 10 MB limit.");
11532
+ * send.payloadTooLarge("Request body too large.", { maxBytes: 10_485_760 });
11533
+ */
11534
+ payloadTooLarge: TSendPropsFn;
11535
+ /**
11536
+ * Sends a **415 Unsupported Media Type** response.
11537
+ *
11538
+ * Use when the `Content-Type` or encoding sent by the client is not
11539
+ * supported by the endpoint.
11540
+ *
11541
+ * @param message - Human-readable explanation of accepted media types.
11542
+ * @param data - Optional payload (e.g. `{ acceptedTypes: ["application/json"] }`).
11543
+ *
11544
+ * @example
11545
+ * send.unsupportedMediaType("Only application/json payloads are accepted.");
11546
+ */
11547
+ unsupportedMediaType: TSendPropsFn;
11548
+ /**
11549
+ * Sends a **417 Expectation Failed** response.
11550
+ *
11551
+ * Use when the `Expect` request-header field could not be satisfied by
11552
+ * the server.
11553
+ *
11554
+ * @param message - Human-readable explanation of the unmet expectation.
11555
+ * @param data - Optional payload.
11556
+ *
11557
+ * @example
11558
+ * send.expectationFailed("The 'Expect: 100-continue' header could not be satisfied.");
11559
+ */
11560
+ expectationFailed: TSendPropsFn;
11561
+ /**
11562
+ * Sends a **418 I'm a Teapot** response.
11563
+ *
11564
+ * An April Fools' joke defined in RFC 2324. Occasionally used as a
11565
+ * catch-all for intentionally refused requests (e.g. blocking bots).
11566
+ *
11567
+ * @param message - Whatever you want. The world is your teapot.
11568
+ * @param data - Optional payload.
11569
+ *
11570
+ * @example
11571
+ * send.imATeapot("I refuse to brew coffee because I am, permanently, a teapot.");
11572
+ */
11573
+ imATeapot: TSendPropsFn;
11574
+ /**
11575
+ * Sends a **422 Unprocessable Entity** response.
11576
+ *
11577
+ * Use when the request is well-formed but contains semantic errors that
11578
+ * prevent it from being processed (e.g. domain validation failures,
11579
+ * business rule violations). Preferred over 400 for schema-valid but
11580
+ * logically invalid payloads.
11581
+ *
11582
+ * @param message - Human-readable explanation of why processing failed.
11583
+ * @param data - Optional payload (e.g. structured validation errors per field).
11584
+ *
11585
+ * @example
11586
+ * send.unprocessableEntity("The 'birthDate' must be in the past.");
11587
+ * send.unprocessableEntity("Validation errors.", { fields: { age: "Must be ≥ 18" } });
11588
+ */
11589
+ unprocessableEntity: TSendPropsFn;
11590
+ /**
11591
+ * Sends a **423 Locked** response.
11592
+ *
11593
+ * Use when the resource being accessed is locked (e.g. being edited by
11594
+ * another user, or under an administrative hold).
11595
+ *
11596
+ * @param message - Human-readable explanation of why the resource is locked.
11597
+ * @param data - Optional payload (e.g. lock owner, estimated unlock time).
11598
+ *
11599
+ * @example
11600
+ * send.locked("This document is currently being edited by another user.");
11601
+ * send.locked("Resource is locked.", { lockedBy: "alice@example.com", until: "2025-06-01T12:00:00Z" });
11602
+ */
11603
+ locked: TSendPropsFn;
11604
+ /**
11605
+ * Sends a **429 Too Many Requests** response.
11606
+ *
11607
+ * Use when the client has exceeded an allowed request rate or quota.
11608
+ * Consider pairing this with a `Retry-After` header at the middleware level.
11609
+ *
11610
+ * @param message - Human-readable explanation of the rate limit breach.
11611
+ * @param data - Optional payload (e.g. retry delay, remaining quota).
11612
+ *
11613
+ * @example
11614
+ * send.tooManyRequest("Rate limit reached. Try again in 60 seconds.");
11615
+ * send.tooManyRequest("Quota exceeded.", { retryAfter: 60 });
11616
+ */
11617
+ tooManyRequest: TSendPropsFn;
11618
+ /**
11619
+ * Sends a **500 Internal Server Error** response.
11620
+ *
11621
+ * Use for unexpected, unhandled server-side failures.
11622
+ * Avoid leaking internal stack traces or sensitive details in the message.
11623
+ *
11624
+ * @param message - Human-readable explanation safe to expose to the client.
11625
+ * @param data - Optional payload (use sparingly — never expose raw stack traces).
11626
+ *
11627
+ * @example
11628
+ * send.internalError("An unexpected error occurred. Please try again later.");
11629
+ */
11630
+ internalError: TSendPropsFn;
11631
+ /**
11632
+ * Sends a **501 Not Implemented** response.
11633
+ *
11634
+ * Use when the server does not support the functionality required to
11635
+ * fulfil the request (e.g. an HTTP method that is recognised but not
11636
+ * implemented on this server, or a feature under development).
11637
+ *
11638
+ * @param message - Human-readable explanation of what is not implemented.
11639
+ * @param data - Optional payload (e.g. planned availability date).
11640
+ *
11641
+ * @example
11642
+ * send.notImplemented("The PATCH method is not yet supported on this resource.");
11643
+ */
11644
+ notImplemented: TSendPropsFn;
11645
+ /**
11646
+ * Sends a **502 Bad Gateway** response.
11647
+ *
11648
+ * Use when this server, acting as a gateway or proxy, received an invalid
11649
+ * response from an upstream server.
11650
+ *
11651
+ * @param message - Human-readable explanation safe to expose to the client.
11652
+ * @param data - Optional payload (e.g. upstream service identifier).
11653
+ *
11654
+ * @example
11655
+ * send.badGateway("The payment provider returned an unexpected response.");
11656
+ */
11657
+ badGateway: TSendPropsFn;
11658
+ /**
11659
+ * Sends a **503 Service Unavailable** response.
11660
+ *
11661
+ * Use when the server is temporarily unable to handle the request due to
11662
+ * maintenance, overload, or a dependency outage. Pair with a
11663
+ * `Retry-After` header when the downtime window is known.
11664
+ *
11665
+ * @param message - Human-readable explanation including estimated recovery time when available.
11666
+ * @param data - Optional payload (e.g. `{ retryAfter: "2025-06-01T06:00:00Z" }`).
11667
+ *
11668
+ * @example
11669
+ * send.serviceUnavailable("Scheduled maintenance until 06:00 UTC.");
11670
+ * send.serviceUnavailable("Server overloaded.", { retryAfter: "2025-06-01T06:00:00Z" });
11671
+ */
11672
+ serviceUnavailable: TSendPropsFn;
11673
+ /**
11674
+ * Sends a **504 Gateway Timeout** response.
11675
+ *
11676
+ * Use when this server, acting as a gateway or proxy, did not receive a
11677
+ * timely response from an upstream server.
11678
+ *
11679
+ * @param message - Human-readable explanation of which upstream timed out.
11680
+ * @param data - Optional payload (e.g. upstream service name, timeout duration).
11681
+ *
11682
+ * @example
11683
+ * send.gatewayTimeout("The database did not respond within the allowed time.");
11684
+ * send.gatewayTimeout("Upstream timeout.", { service: "payments-api", timeoutMs: 5000 });
11685
+ */
11686
+ gatewayTimeout: TSendPropsFn;
11687
+ }
11688
+
11145
11689
  /**
11146
11690
  * Identifies the project root for a given caller path by traversing up the filesystem.
11147
11691
  */
@@ -11447,5 +11991,5 @@ declare class XStatic {
11447
11991
  */
11448
11992
  declare function Router(): XyPrissRouter;
11449
11993
 
11450
- export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, Plugin, PluginHookIds, Router, SecurityMiddleware, Upload, XJsonResponseHandler, XStatic, XyGuard, MultiServerApp as XyPMS, XyPrissRouter, XyPrissXHSC, __cfg__, __const__, __sys__, createOptimalCache, createServer, getCallerProjectRoot, getIp, getMime, getMimes, identifyProjectRoot, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
11451
- export type { ArchiveOptions, BatchRenameChange, CacheConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, GetIpResult, IpSource, MonitorSnapshot, MultiServerConfig, NetworkStats, NextFunction, PerformanceConfig, PluginCreator, PluginServer, ProcessInfo, ProcessMonitorSnapshot, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RoutRateLimit, RouteConfig, RouteGuard, RouteMeta, RouteOptions, ParamType as RouteParamType, SecurityConfig, ServerOptions$1 as ServerOptions, XyPrisRequest$1 as XRequest, XyPrisResponse$1 as XResponse, XemsTypes, XyPrisRequest$1 as XyPrisRequest, XyPrisResponse$1 as XyPrisResponse, XyPrissApp, XyPrissPlugin };
11994
+ export { ConfigurationManager as CM, ConfigurationManager as Configs, FileUploadAPI as FLA, FileUploadAPI, Plugin, PluginHookIds, Router, SecurityMiddleware, Send, Upload, XJsonResponseHandler, XStatic, XyGuard, MultiServerApp as XyPMS, XyPrissRouter, XyPrissXHSC, __cfg__, __const__, __sys__, createOptimalCache, createServer, getCallerProjectRoot, getIp, getMime, getMimes, identifyProjectRoot, initializeFileUpload, mergeWithDefaults, mergeWithDefaults as mwdef, quickServer, uploadAny, uploadArray, uploadFields, uploadSingle, xems };
11995
+ export type { ArchiveOptions, BatchRenameChange, CacheConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, GetIpResult, IResTemplate, ISeConfigs, ISeResponder, IpSource, MonitorSnapshot, MultiServerConfig, NetworkStats, NextFunction, PerformanceConfig, PluginCreator, PluginServer, ProcessInfo, ProcessMonitorSnapshot, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RoutRateLimit, RouteConfig, RouteGuard, RouteMeta, RouteOptions, ParamType as RouteParamType, SecurityConfig, ServerOptions$1 as ServerOptions, SupportedStatus, TSendPropsFn, XyPrisRequest$1 as XRequest, XyPrisResponse$1 as XResponse, XemsTypes, XyPrisRequest$1 as XyPrisRequest, XyPrisResponse$1 as XyPrisResponse, XyPrissApp, XyPrissPlugin };
package/package.json CHANGED
@@ -15,8 +15,10 @@
15
15
  "reliant-type": "^2.1.5",
16
16
  "strulink": "^1.2.0",
17
17
  "xss": "^1.0.15",
18
- "xypriss-compression": "^1.0.6",
19
- "xypriss-security": "^2.1.16"
18
+ "xypriss-compression": "^1.0.6"
19
+ },
20
+ "peerDependencies": {
21
+ "xypriss-security": ">=2.1.16"
20
22
  },
21
23
  "description": "XyPriss is a high-performance, TypeScript-first hyper-system web framework powered by a native Go core (XHSC), featuring robust multi-tenant sandboxing, secure native file streaming, and zero Express dependencies.",
22
24
  "devDependencies": {
@@ -68,6 +70,6 @@
68
70
  },
69
71
  "type": "module",
70
72
  "types": "./dist/index.d.ts",
71
- "version": "9.10.21"
73
+ "version": "9.10.23"
72
74
  }
73
75