[docs] sync docs with types (#2299)

benmccann · web-flow · commit 5ac76064b58d · 2021-08-26T12:03:36.000-07:00
diff --git a/documentation/docs/04-hooks.md b/documentation/docs/04-hooks.md
@@ -17,30 +17,47 @@ If unimplemented, defaults to `({ request, resolve }) => resolve(request)`.
 ```ts
 // handle TypeScript type definitions
 
-type Headers = Record<string, string>;
+export type RequestHeaders = Record<string, string>;
 
-type Request<Locals = Record<string, any>> = {
+/** Only value that can be an array is set-cookie. For everything else we assume string value */
+export type ResponseHeaders = Record<string, string | string[]>;
+
+export type RawBody = null | Uint8Array;
+
+export interface IncomingRequest {
 	method: string;
 	host: string;
-	headers: Headers;
 	path: string;
-	params: Record<string, string>;
 	query: URLSearchParams;
-	rawBody: Uint8Array;
+	headers: RequestHeaders;
+	rawBody: RawBody;
+}
+
+export type ParameterizedBody<Body = unknown> = Body extends FormData
+	? ReadOnlyFormData
+	: (string | RawBody | ReadOnlyFormData) & Body;
+
+export interface ServerRequest<Locals = Record<string, any>, Body = unknown>
+	extends IncomingRequest {
+	params: Record<string, string>;
 	body: ParameterizedBody<Body>;
-	locals: Locals; // populated by hooks handle
-};
+	locals: Locals;
+}
+
+export type StrictBody = string | Uint8Array;
 
-type Response = {
+export interface ServerResponse {
 	status: number;
-	headers: Headers;
-	body?: string | Uint8Array;
-};
-
-type Handle<Locals = Record<string, any>> = (input: {
-	request: Request<Locals>;
-	resolve: (request: Request<Locals>) => Response | Promise<Response>;
-}) => Response | Promise<Response>;
+	headers: ResponseHeaders;
+	body?: StrictBody;
+}
+
+export interface Handle<Locals = Record<string, any>> {
+	(input: {
+		request: ServerRequest<Locals>;
+		resolve(request: ServerRequest<Locals>): MaybePromise<ServerResponse>;
+	}): MaybePromise<ServerResponse>;
+}
 ```
 
 To add custom data to the request, which is passed to endpoints, populate the `request.locals` object, as shown below.
@@ -71,7 +88,7 @@ During development, if an error occurs because of a syntax error in your Svelte
 If unimplemented, SvelteKit will log the error with default formatting.
 
 ```ts
-type HandleError = HandleError<Locals = Record<string, any>> {
+export interface HandleError<Locals = Record<string, any>> {
 	(input: { error: Error & { frame?: string }; request: ServerRequest<Locals> }): void;
 }
 ```
@@ -95,9 +112,9 @@ If unimplemented, session is `{}`.
 ```ts
 // getSession TypeScript type definition
 
-type GetSession<Locals = Record<string, any>, Session = any> = {
-	(request: Request<Locals>): Session | Promise<Session>;
-};
+export interface GetSession<Locals = Record<string, any>, Session = any> {
+	(request: ServerRequest<Locals>): MaybePromise<Session>;
+}
 ```
 
 ```js
@@ -127,7 +144,9 @@ This function allows you to modify (or replace) a `fetch` request for an externa
 For example, your `load` function might make a request to a public URL like `https://api.yourapp.com` when the user performs a client-side navigation to the respective page, but during SSR it might make sense to hit the API directly (bypassing whatever proxies and load balancers sit between it and the public internet).
 
 ```ts
-type ExternalFetch = (req: Request) => Promise<Response>;
+export interface ExternalFetch {
+	(req: Request): Promise<Response>;
+}
 ```
 
 ```js
