@celosiajs/core
Version:
CelosiaJS Core. A framework for REST API based on Express.js
347 lines (346 loc) • 13.8 kB
TypeScript
import { Response } from 'express';
import { OutgoingHttpHeader, OutgoingHttpHeaders } from 'http';
import { Socket } from 'net';
import { CookieOptions, DownloadOptions, JSON, OutgoingHeaderValue, OutgoingHeaders, SendFileOptions } from '..';
declare class CelosiaResponse<Body = JSON> {
protected _expressResponse: Response;
protected _cachedExtensionsProxy: CelosiaJS.CelosiaResponse<Body> | null;
constructor(expressResponse: Response);
/**
* User-defined extensions method.
* Register by using `ExtensionsRegistry.registerCelosiaResponseExtension`.
*/
get extensions(): CelosiaJS.CelosiaResponse<Body>;
/**
* Express response object.
*/
get expressResponse(): Response<any, Record<string, any>>;
/**
* Reference to the CelosiaInstance currently handling this request.
*/
get instance(): import("./CelosiaInstance").default<boolean>;
/**
* CelosiaRequest for this request.
*/
get request(): import("./CelosiaRequest").default<import("..").EmptyObject, import("..").EmptyObject, import("..").EmptyObject, import("..").EmptyObject>;
/**
* Set status `code`.
*/
status(statusCode: number): this;
/**
* Set the response HTTP status code to `statusCode` and send its string representation as the response body.
*
* Examples:
*
* response.sendStatus(200); // equivalent to response.status(200).send('OK')
* response.sendStatus(403); // equivalent to response.status(403).send('Forbidden')
* response.sendStatus(404); // equivalent to response.status(404).send('Not Found')
* response.sendStatus(500); // equivalent to response.status(500).send('Internal Server Error')
*/
sendStatus(statusCode: number): this;
/**
* Send a response.
*
* Examples:
*
* response.send(new Buffer('wahoo'));
* response.send({ some: 'json' });
* response.send('<p>some html</p>');
* response.status(404).send('Sorry, cant find that');
*/
send(body?: Body): this;
/**
* Send JSON response.
*
* Examples:
*
* response.json(null);
* response.json({ user: 'tj' });
* response.status(500).json('oh noes!');
* response.status(404).json('I dont have that');
*/
json(json: Body extends JSON ? Body : never): this;
/**
* Transfer the file at the given `path`.
*
* Automatically sets the _Content-Type_ response header field.
* The callback `fn(err)` is invoked when the transfer is complete
* or when an error occurs. Be sure to check `response.headersSent`
* if you wish to attempt responding, as the header and some data
* may have already been transferred.
*
* Options:
*
* - `maxAge` defaulting to 0 (can be string converted by `ms`)
* - `root` root directory for relative filenames
* - `headers` object of headers to serve with file
* - `dotfiles` serve dotfiles, defaulting to false; can be `"allow"` to send them
*
* Other options are passed along to `send`.
*/
sendFile(path: string, options?: SendFileOptions): Promise<void>;
/**
* Transfer the file at the given `path` as an attachment.
*
* Optionally providing an alternate attachment `filename`,
* and optional callback `fn(err)`. The callback is invoked
* when the data transfer is complete, or when an error has
* ocurred. Be sure to check `response.headersSent` if you plan to respond.
*
* The optional options argument passes through to the underlying
* response.sendFile() call, and takes the exact same parameters.
*
* This method uses `response.sendFile()`.
*/
download(path: string, filename?: string, options?: DownloadOptions): Promise<void>;
/**
* Set _Content-Disposition_ header to _attachment_ with optional `filename`.
*/
attachment(filename: string): this;
/**
* Set _Content-Type_ response header with `type` through `mime.lookup()`
* when it does not contain "/", or set the Content-Type to `type` otherwise.
*
* Examples:
*
* response.contentType('.html');
* response.contentType('html');
* response.contentType('json');
* response.contentType('application/json');
* response.contentType('png');
*/
contentType(type: string): this;
write(body: Body): this;
/**
* Set header `field` to `val`, or pass
* an object of header fields.
*
* Examples:
*
* response.header('Foo', ['bar', 'baz']);
* response.header('Accept', 'application/json');
* response.header({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
*/
header(name: string): OutgoingHeaderValue | undefined;
header(name: string, value: OutgoingHeaderValue | undefined): this;
header(headers: OutgoingHeaders): this;
get headers(): OutgoingHttpHeaders;
/**
* Property indicating if HTTP headers has been sent for the response.
*/
get headersSent(): boolean;
/** Clear cookie `name`. */
clearCookie(name: string, options?: CookieOptions): this;
/**
* Set cookie `name` to `value`, with the given `options`.
*
* Options:
*
* - `maxAge` max-age in milliseconds, converted to `expires`
* - `signed` sign the cookie
* - `path` defaults to "/"
*
* Examples:
*
* // "Remember Me" for 15 minutes
* response.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });
*
* // save as above
* response.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })
*/
cookie(name: string, value: string, options?: CookieOptions): this;
/**
* Set the location header to `url`.
*
* The given `url` can also be the name of a mapped url, for
* example by default express supports "back" which redirects
* to the _Referrer_ or _Referer_ headers or "/".
*
* Examples:
*
* response.location('/foo/bar').;
* response.location('http://example.com');
* response.location('../login'); // /blog/post/1 -> /blog/login
*
* Mounting:
*
* When an application is mounted and `response.location()`
* is given a path that does _not_ lead with "/" it becomes
* relative to the mount-point. For example if the application
* is mounted at "/blog", the following would become "/blog/login".
*
* response.location('login');
*
* While the leading slash would result in a location of "/login":
*
* response.location('/login');
*/
location(url: string): this;
/**
* Redirect to the given `url` with optional response `status`
* defaulting to 302.
*
* The resulting `url` is determined by `response.location()`, so
* it will play nicely with mounted apps, relative paths,
* `"back"` etc.
*
* Examples:
*
* response.redirect('back');
* response.redirect('/foo/bar');
* response.redirect('http://example.com');
* response.redirect(301, 'http://example.com');
* response.redirect('http://example.com', 301);
* response.redirect('../login'); // /blog/post/1 -> /blog/login
*/
redirect(url: string): this;
redirect(status: number, url: string): this;
/**
* When using implicit headers (not calling `response.writeHead()` explicitly),
* this property controls the status code that will be sent to the client when
* the headers get flushed.
*
* ```js
* response.statusCode = 404;
* ```
*
* After response header was sent to the client, this property indicates the
* status code which was sent out.
*/
get statusCode(): number;
/**
* When using implicit headers (not calling `response.writeHead()` explicitly),
* this property controls the status message that will be sent to the client when
* the headers get flushed. If this is left as `undefined` then the standard
* message for the status code will be used.
*
* ```js
* response.statusMessage = 'Not found';
* ```
*
* After response header was sent to the client, this property indicates the
* status message which was sent out.
*/
get statusMessage(): string;
/**
* If set to `true`, Node.js will check whether the `Content-Length` header value and the size of the body, in bytes, are equal.
* Mismatching the `Content-Length` header value will result
* in an `Error` being thrown, identified by `code:``'ERR_HTTP_CONTENT_LENGTH_MISMATCH'`.
*/
get strictContentLength(): boolean;
assignSocket(socket: Socket): void;
detachSocket(socket: Socket): void;
/**
* Sends an HTTP/1.1 100 Continue message to the client, indicating that
* the request body should be sent. See the `'checkContinue'` event on `Server`.
*/
writeContinue(callback?: () => void): void;
/**
* Sends an HTTP/1.1 103 Early Hints message to the client with a Link header,
* indicating that the user agent can preload/preconnect the linked resources.
* The `hints` is an object containing the values of headers to be sent with
* early hints message. The optional `callback` argument will be called when
* the response message has been written.
*
* **Example**
*
* ```js
* const earlyHintsLink = '</styles.css>; rel=preload; as=style';
* response.writeEarlyHints({
* 'link': earlyHintsLink,
* });
*
* const earlyHintsLinks = [
* '</styles.css>; rel=preload; as=style',
* '</scripts.js>; rel=preload; as=script',
* ];
* response.writeEarlyHints({
* 'link': earlyHintsLinks,
* 'x-trace-id': 'id for diagnostics',
* });
*
* const earlyHintsCallback = () => console.log('early hints message sent');
* response.writeEarlyHints({
* 'link': earlyHintsLinks,
* }, earlyHintsCallback);
* ```
* @param hints An object containing the values of headers
* @param callback Will be called when the response message has been written
*/
writeEarlyHints(hints: Record<string, string | string[]>, callback?: () => void): void;
/**
* Sends a response header to the request. The status code is a 3-digit HTTP
* status code, like `404`. The last argument, `headers`, are the response headers.
* Optionally one can give a human-readable `statusMessage` as the second
* argument.
*
* `headers` may be an `Array` where the keys and values are in the same list.
* It is _not_ a list of tuples. So, the even-numbered offsets are key values,
* and the odd-numbered offsets are the associated values. The array is in the same
* format as `request.rawHeaders`.
*
* Returns a reference to the `ServerResponse`, so that calls can be chained.
*
* ```js
* const body = 'hello world';
* response
* .writeHead(200, {
* 'Content-Length': Buffer.byteLength(body),
* 'Content-Type': 'text/plain',
* })
* .end(body);
* ```
*
* This method must only be called once on a message and it must
* be called before `response.end()` is called.
*
* If `response.write()` or `response.end()` are called before calling
* this, the implicit/mutable headers will be calculated and call this function.
*
* When headers have been set with `response.setHeader()`, they will be merged
* with any headers passed to `response.writeHead()`, with the headers passed
* to `response.writeHead()` given precedence.
*
* If this method is called and `response.setHeader()` has not been called,
* it will directly write the supplied header values onto the network channel
* without caching internally, and the `response.getHeader()` on the header
* will not yield the expected result. If progressive population of headers is
* desired with potential future retrieval and modification, use `response.setHeader()` instead.
*
* ```js
* // Returns content-type = text/plain
* const server = http.createServer((req, res) => {
* res.setHeader('Content-Type', 'text/html');
* res.setHeader('X-Foo', 'bar');
* res.writeHead(200, { 'Content-Type': 'text/plain' });
* res.end('ok');
* });
* ```
*
* `Content-Length` is read in bytes, not characters. Use `Buffer.byteLength()` to determine the length of the body in bytes. Node.js
* will check whether `Content-Length` and the length of the body which has
* been transmitted are equal or not.
*
* Attempting to set a header field name or value that contains invalid characters
* will result in a \[`Error`\]\[\] being thrown.
*/
writeHead(statusCode: number, statusMessage?: string, headers?: OutgoingHttpHeaders | OutgoingHttpHeader[]): this;
writeHead(statusCode: number, headers?: OutgoingHttpHeaders | OutgoingHttpHeader[]): this;
/**
* Sends a HTTP/1.1 102 Processing message to the client, indicating that
* the request body should be sent.
*/
writeProcessing(): void;
/**
* Send a json containing "Internal Server Error" or the predefined error in `CelosiaInstance` creation response with 500 status code
*/
sendInternalServerError(): this;
/**
* Adds the field to the Vary response header, if it is not there already.
* Examples:
*
* response.vary('User-Agent');
*/
vary(field: string): this;
}
export default CelosiaResponse;