task: add io-ts-http api reference docs

bitgopatmcl · ericcrosson-bitgo · commit b1a809bea469 · 2022-03-30T14:37:23.000-05:00
Ticket: BG-39132
diff --git a/packages/io-ts-http/README.md b/packages/io-ts-http/README.md
@@ -2,7 +2,7 @@
 
 Runtime types for (de)serializing HTTP requests from both the client and server side
 
-## Usage
+## Overview
 
 The primary function in this library is `httpRequest`, which is used to build codecs
 which can parse a generic HTTP request into a more refined type. The generic HTTP
@@ -78,53 +78,6 @@ possible to encode the API contract (or at least as much of it that is possible
 express in the type system) and therefore someone calling the API can be confident that
 the server will correctly interpret a request if the arguments typecheck.
 
-## Other functions
+## Documentation
 
-### optional
-
-The `optional` function takes a codec and wraps it in one that also accepts `undefined`
-(specifically, not `null`):
-
-```typescript
-import { optional } from '@bitgo/io-ts-http';
-import * as t from 'io-ts';
-
-// This is effectively a runtime representation of `string | undefined`
-const stringOrUndefined = optional(t.string);
-```
-
-### optionalize
-
-In TypeScript, an object may have some keys that are required and others that are
-optional:
-
-```typescript
-type Example = {
-  needed: string;
-  notNeeded?: string;
-};
-```
-
-To build a codec for such a type in `io-ts`, this pattern is generally used:
-
-```typescript
-const Example = t.intersection([
-  t.type({
-    needed: t.string,
-  }),
-  t.partial({
-    notNeeded: t.string,
-  }),
-]);
-```
-
-The `optionalize` function makes this easier to do by accepting a similar set of
-arguments as `t.type` does, and if any of the properties allow `undefined` they become
-optional:
-
-```typescript
-const Example = optionalize({
-  needed: t.string,
-  notNeeded: optional(t.string),
-});
-```
+- [API Reference](docs/apiReference.md)
diff --git a/packages/io-ts-http/docs/apiReference.md b/packages/io-ts-http/docs/apiReference.md
@@ -0,0 +1,8 @@
+# API Reference
+
+## Table of Contents
+
+- [apiSpec](apiSpec.md)
+- [httpRoute](httpRoute.md)
+- [httpRequest](httpRequest.md)
+- [combinators](combinators.md)
diff --git a/packages/io-ts-http/docs/apiSpec.md b/packages/io-ts-http/docs/apiSpec.md
@@ -0,0 +1,45 @@
+# `apiSpec`
+
+Helper function for defining a collection of routes and associating them with operation
+names.
+
+## Usage
+
+The intended usage is to create a top-level export that uses `apiSpec` to define a
+service's API as a collection of operations linked to routes. This function itself does
+not do anything aside from enforce the correct type of the parameter passed to it.
+
+```typescript
+import { apiSpec } from '@bitgo/io-ts-http';
+
+import { GetMessage, CreateMessage } from './routes/message';
+import { GetUser, CreateUser, UpdateUser, DeleteUser } from './routes/user';
+
+/**
+ * Example service
+ *
+ * @version 1.0.0
+ */
+export const API = apiSpec({
+  'api.v1.message': {
+    get: GetMessage,
+    post: CreateMessage,
+  },
+  'api.v1.user': {
+    get: GetUser,
+    post: CreateUser,
+    put: UpdateUser,
+    delete: DeleteUser,
+  },
+});
+```
+
+Other packages are designed to read these API specs for various purposes such as
+creating a type-checked api client, binding functions to routes with automatic parsing
+and validating, and generating things such as an OpenAPI schema.
+
+## Metadata
+
+Currently, if a `@version` JSDoc tag is added to the exported API spec, it will be used
+as the API `version` when generating an OpenAPI schema. Support for other tags may be
+added in the future.
diff --git a/packages/io-ts-http/docs/combinators.md b/packages/io-ts-http/docs/combinators.md
@@ -0,0 +1,96 @@
+# Combinators
+
+`io-ts-http` currently exports a handful of combinators for `io-ts` codecs.
+
+## `optionalize`
+
+Provides an easy way to define object types with some required and some optional
+properties. It accepts the same props that `type` and `partial` do in `io-ts`, and
+behaves like a combination of the two. It works by figuring out which properties are
+capable of being `undefined`, and marking them as optional. For example:
+
+```typescript
+const Item = optionalize({
+  necessaryProperty: t.string,
+  maybeDefined: t.union([t.string, t.undefined]),
+});
+```
+
+defines a codec for the following type:
+
+```typescript
+type Item = {
+  necessaryProperty: string;
+  maybeDefined?: string;
+};
+```
+
+This same type could be defined with a combination of `intersection`, `type`, and
+`partial`, however it is much easier to read, especially when combined with the next
+combinator.
+
+## `optional`
+
+Designed to be paired with `optionalize` for readability. It accepts a codec and unions
+it with undefined. Thus:
+
+```typescript
+// typeof Foo = string | undefined
+const Foo = optional(t.string);
+```
+
+When used with `optionalize` it becomes easy to see which parameters are optional.
+
+## `flattened`
+
+Allows codecs to be defined where properties are flattened on decode and nested on
+encode. To illustrate:
+
+```typescript
+const Item = flattened({
+  first: {
+    second: t.string,
+  },
+});
+
+type DecodedType = {
+  second: string;
+};
+
+type EncodedType = {
+  first: {
+    second: string;
+  };
+};
+```
+
+You can have multiple top-level properties flattened into one object.
+
+```typescript
+const Item = flattened({
+  foo: {
+    fizz: t.string,
+  },
+  bar: {
+    buzz: t.number,
+  },
+});
+
+type DecodedType = {
+  fizz: string;
+  buzz: number;
+};
+
+type EncodedType = {
+  foo: {
+    fizz: string;
+  };
+  bar: {
+    buzz: number;
+  };
+};
+```
+
+The library tries to statically prevent defining multiple nested properties with the
+same key, but can't in all cases. If this is worked around, then it is undefined
+behavior.
diff --git a/packages/io-ts-http/docs/httpRequest.md b/packages/io-ts-http/docs/httpRequest.md
@@ -0,0 +1,70 @@
+# `httpRequest`
+
+Helper function for defining HTTP request codecs. These codecs have the property that
+the decoded type is a flattened combination of the query params, path params, headers,
+and body. It accepts an object containing codecs for query, path, header, and body
+params. The result is a codec where these parameters are all flattened into the result
+when decoded, and placed into their appropriate positions when encoded. All parameters
+are optional and default to the empty object `{}`
+
+## Usage
+
+Request with a single query parameter
+
+```typescript
+const Request = httpRequest({
+  query: {
+    message: t.string,
+  },
+});
+
+// Decoded type
+type DecodedRequest = {
+  message: string;
+};
+```
+
+Request with both query and path parameters
+
+```typescript
+const Request = httpRequest({
+  query: {
+    message: t.string,
+  },
+  params: {
+    id: NumberFromString,
+  },
+});
+
+// Decoded type
+type DecodedRequest = {
+  message: string;
+  id: number;
+};
+```
+
+Request with a body
+
+```typescript
+const Request = httpRequest({
+  params: {
+    id: NumberFromString,
+  },
+  body: {
+    content: t.string,
+    timestamp: DateFromISOString,
+  },
+});
+
+// Decoded type
+type DecodedRequest = {
+  id: number;
+  content: string;
+  timestamp: Date;
+};
+```
+
+## Limitations
+
+`httpRequest` currently assumes that a request body, if present, is an object type. A
+workaround for this is outlined in the [httpRoute](./httpRoute.md#Advanced%20Usage) doc.
diff --git a/packages/io-ts-http/docs/httpRoute.md b/packages/io-ts-http/docs/httpRoute.md
