|
| 1 | +/// <reference types="node" /> |
| 2 | + |
| 3 | +import * as fs from "fs"; |
| 4 | +import * as m from "mime"; |
| 5 | +import * as stream from "stream"; |
| 6 | + |
| 7 | +/** |
| 8 | + * Create a new SendStream for the given path to send to a res. |
| 9 | + * The req is the Node.js HTTP request and the path is a urlencoded path to send (urlencoded, not the actual file-system path). |
| 10 | + */ |
| 11 | +declare function send(req: stream.Readable, path: string, options?: send.SendOptions): send.SendStream; |
| 12 | + |
| 13 | +declare namespace send { |
| 14 | + const mime: typeof m; |
| 15 | + interface SendOptions { |
| 16 | + /** |
| 17 | + * Enable or disable accepting ranged requests, defaults to true. |
| 18 | + * Disabling this will not send Accept-Ranges and ignore the contents of the Range request header. |
| 19 | + */ |
| 20 | + acceptRanges?: boolean | undefined; |
| 21 | + |
| 22 | + /** |
| 23 | + * Enable or disable setting Cache-Control response header, defaults to true. |
| 24 | + * Disabling this will ignore the maxAge option. |
| 25 | + */ |
| 26 | + cacheControl?: boolean | undefined; |
| 27 | + |
| 28 | + /** |
| 29 | + * Set how "dotfiles" are treated when encountered. |
| 30 | + * A dotfile is a file or directory that begins with a dot ("."). |
| 31 | + * Note this check is done on the path itself without checking if the path actually exists on the disk. |
| 32 | + * If root is specified, only the dotfiles above the root are checked (i.e. the root itself can be within a dotfile when when set to "deny"). |
| 33 | + * 'allow' No special treatment for dotfiles. |
| 34 | + * 'deny' Send a 403 for any request for a dotfile. |
| 35 | + * 'ignore' Pretend like the dotfile does not exist and 404. |
| 36 | + * The default value is similar to 'ignore', with the exception that this default will not ignore the files within a directory that begins with a dot, for backward-compatibility. |
| 37 | + */ |
| 38 | + dotfiles?: "allow" | "deny" | "ignore" | undefined; |
| 39 | + |
| 40 | + /** |
| 41 | + * Byte offset at which the stream ends, defaults to the length of the file minus 1. |
| 42 | + * The end is inclusive in the stream, meaning end: 3 will include the 4th byte in the stream. |
| 43 | + */ |
| 44 | + end?: number | undefined; |
| 45 | + |
| 46 | + /** |
| 47 | + * Enable or disable etag generation, defaults to true. |
| 48 | + */ |
| 49 | + etag?: boolean | undefined; |
| 50 | + |
| 51 | + /** |
| 52 | + * If a given file doesn't exist, try appending one of the given extensions, in the given order. |
| 53 | + * By default, this is disabled (set to false). |
| 54 | + * An example value that will serve extension-less HTML files: ['html', 'htm']. |
| 55 | + * This is skipped if the requested file already has an extension. |
| 56 | + */ |
| 57 | + extensions?: string[] | string | boolean | undefined; |
| 58 | + |
| 59 | + /** |
| 60 | + * Enable or disable the immutable directive in the Cache-Control response header, defaults to false. |
| 61 | + * If set to true, the maxAge option should also be specified to enable caching. |
| 62 | + * The immutable directive will prevent supported clients from making conditional requests during the life of the maxAge option to check if the file has changed. |
| 63 | + * @default false |
| 64 | + */ |
| 65 | + immutable?: boolean | undefined; |
| 66 | + |
| 67 | + /** |
| 68 | + * By default send supports "index.html" files, to disable this set false or to supply a new index pass a string or an array in preferred order. |
| 69 | + */ |
| 70 | + index?: string[] | string | boolean | undefined; |
| 71 | + |
| 72 | + /** |
| 73 | + * Enable or disable Last-Modified header, defaults to true. |
| 74 | + * Uses the file system's last modified value. |
| 75 | + */ |
| 76 | + lastModified?: boolean | undefined; |
| 77 | + |
| 78 | + /** |
| 79 | + * Provide a max-age in milliseconds for http caching, defaults to 0. |
| 80 | + * This can also be a string accepted by the ms module. |
| 81 | + */ |
| 82 | + maxAge?: string | number | undefined; |
| 83 | + |
| 84 | + /** |
| 85 | + * Serve files relative to path. |
| 86 | + */ |
| 87 | + root?: string | undefined; |
| 88 | + |
| 89 | + /** |
| 90 | + * Byte offset at which the stream starts, defaults to 0. |
| 91 | + * The start is inclusive, meaning start: 2 will include the 3rd byte in the stream. |
| 92 | + */ |
| 93 | + start?: number | undefined; |
| 94 | + } |
| 95 | + |
| 96 | + interface SendStream extends stream.Stream { |
| 97 | + /** |
| 98 | + * @deprecated pass etag as option |
| 99 | + * Enable or disable etag generation. |
| 100 | + */ |
| 101 | + etag(val: boolean): SendStream; |
| 102 | + |
| 103 | + /** |
| 104 | + * @deprecated use dotfiles option |
| 105 | + * Enable or disable "hidden" (dot) files. |
| 106 | + */ |
| 107 | + hidden(val: boolean): SendStream; |
| 108 | + |
| 109 | + /** |
| 110 | + * @deprecated pass index as option |
| 111 | + * Set index `paths`, set to a falsy value to disable index support. |
| 112 | + */ |
| 113 | + index(paths: string[] | string): SendStream; |
| 114 | + |
| 115 | + /** |
| 116 | + * @deprecated pass root as option |
| 117 | + * Set root `path`. |
| 118 | + */ |
| 119 | + root(paths: string): SendStream; |
| 120 | + |
| 121 | + /** |
| 122 | + * @deprecated pass root as option |
| 123 | + * Set root `path`. |
| 124 | + */ |
| 125 | + from(paths: string): SendStream; |
| 126 | + |
| 127 | + /** |
| 128 | + * @deprecated pass maxAge as option |
| 129 | + * Set max-age to `maxAge`. |
| 130 | + */ |
| 131 | + maxage(maxAge: string | number): SendStream; |
| 132 | + |
| 133 | + /** |
| 134 | + * Emit error with `status`. |
| 135 | + */ |
| 136 | + error(status: number, error?: Error): void; |
| 137 | + |
| 138 | + /** |
| 139 | + * Check if the pathname ends with "/". |
| 140 | + */ |
| 141 | + hasTrailingSlash(): boolean; |
| 142 | + |
| 143 | + /** |
| 144 | + * Check if this is a conditional GET request. |
| 145 | + */ |
| 146 | + isConditionalGET(): boolean; |
| 147 | + |
| 148 | + /** |
| 149 | + * Strip content-* header fields. |
| 150 | + */ |
| 151 | + removeContentHeaderFields(): void; |
| 152 | + |
| 153 | + /** |
| 154 | + * Respond with 304 not modified. |
| 155 | + */ |
| 156 | + notModified(): void; |
| 157 | + |
| 158 | + /** |
| 159 | + * Raise error that headers already sent. |
| 160 | + */ |
| 161 | + headersAlreadySent(): void; |
| 162 | + |
| 163 | + /** |
| 164 | + * Check if the request is cacheable, aka responded with 2xx or 304 (see RFC 2616 section 14.2{5,6}). |
| 165 | + */ |
| 166 | + isCachable(): boolean; |
| 167 | + |
| 168 | + /** |
| 169 | + * Handle stat() error. |
| 170 | + */ |
| 171 | + onStatError(error: Error): void; |
| 172 | + |
| 173 | + /** |
| 174 | + * Check if the cache is fresh. |
| 175 | + */ |
| 176 | + isFresh(): boolean; |
| 177 | + |
| 178 | + /** |
| 179 | + * Check if the range is fresh. |
| 180 | + */ |
| 181 | + isRangeFresh(): boolean; |
| 182 | + |
| 183 | + /** |
| 184 | + * Redirect to path. |
| 185 | + */ |
| 186 | + redirect(path: string): void; |
| 187 | + |
| 188 | + /** |
| 189 | + * Pipe to `res`. |
| 190 | + */ |
| 191 | + pipe<T extends NodeJS.WritableStream>(res: T): T; |
| 192 | + |
| 193 | + /** |
| 194 | + * Transfer `path`. |
| 195 | + */ |
| 196 | + send(path: string, stat?: fs.Stats): void; |
| 197 | + |
| 198 | + /** |
| 199 | + * Transfer file for `path`. |
| 200 | + */ |
| 201 | + sendFile(path: string): void; |
| 202 | + |
| 203 | + /** |
| 204 | + * Transfer index for `path`. |
| 205 | + */ |
| 206 | + sendIndex(path: string): void; |
| 207 | + |
| 208 | + /** |
| 209 | + * Transfer index for `path`. |
| 210 | + */ |
| 211 | + stream(path: string, options?: {}): void; |
| 212 | + |
| 213 | + /** |
| 214 | + * Set content-type based on `path` if it hasn't been explicitly set. |
| 215 | + */ |
| 216 | + type(path: string): void; |
| 217 | + |
| 218 | + /** |
| 219 | + * Set response header fields, most fields may be pre-defined. |
| 220 | + */ |
| 221 | + setHeader(path: string, stat: fs.Stats): void; |
| 222 | + } |
| 223 | +} |
| 224 | + |
| 225 | +export = send; |
0 commit comments