Add export for core as a whole type.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>

packages/backend-openapi-utils/src/index.ts

@@ -19,6 +19,7 @@
  *
  * @packageDocumentation
  */
+import * as core from './types';
 
+export { core };
 export type { ApiRouter } from './router';
-export * from './types';

packages/backend-openapi-utils/src/router.ts

@@ -14,26 +14,26 @@
  * limitations under the License.
  */
 import { Router } from 'express';
-import { core } from './types';
+import { DocRequestMatcher, RequiredDoc } from './types';
 
 /**
  * Typed Express router based on an OpenAPI 3.1 spec.
  * @public
  */
-export interface ApiRouter<Doc extends core.Spec> extends Router {
-  get: core.RequestMatcher<Doc, this, 'get'>;
+export interface ApiRouter<Doc extends RequiredDoc> extends Router {
+  get: DocRequestMatcher<Doc, this, 'get'>;
 
-  post: core.RequestMatcher<Doc, this, 'post'>;
+  post: DocRequestMatcher<Doc, this, 'post'>;
 
-  all: core.RequestMatcher<Doc, this, 'all'>;
+  all: DocRequestMatcher<Doc, this, 'all'>;
 
-  put: core.RequestMatcher<Doc, this, 'put'>;
+  put: DocRequestMatcher<Doc, this, 'put'>;
 
-  delete: core.RequestMatcher<Doc, this, 'delete'>;
+  delete: DocRequestMatcher<Doc, this, 'delete'>;
 
-  patch: core.RequestMatcher<Doc, this, 'patch'>;
+  patch: DocRequestMatcher<Doc, this, 'patch'>;
 
-  options: core.RequestMatcher<Doc, this, 'options'>;
+  options: DocRequestMatcher<Doc, this, 'options'>;
 
-  head: core.RequestMatcher<Doc, this, 'head'>;
+  head: DocRequestMatcher<Doc, this, 'head'>;
 }

packages/backend-openapi-utils/src/types/common.ts

@@ -27,13 +27,18 @@ import {
 
 /**
  * Basic OpenAPI spec with paths and components properties enforced.
+ * @public
  */
 export type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
 
+/**
+ * @public
+ */
 export type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
 
 /**
  * Get value types of `T`.
+ * @public
  */
 export type ValueOf<T> = T[keyof T];
 
@@ -45,6 +50,8 @@ export type ValueOf<T> = T[keyof T];
  * const path: PathTemplate<"/posts/{postId}/comments/{commentId}"> = "/posts/:postId/comments/:commentId";
  * const pathWithoutParams: PathTemplate<"/posts/comments"> = "/posts/comments";
  * ```
+ *
+ * @public
  */
 export type PathTemplate<Path extends string> =
   Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
@@ -64,6 +71,8 @@ export type PathTemplate<Path extends string> =
  * const specPathWithParams: DocPath<typeof spec, "/posts/:postId/comments/:commentId"> = "/posts/{postId}/comments/{commentId}";
  * const specPathWithoutParams: DocPath<typeof spec, "/posts/comments"> = "/posts/comments";
  * ```
+ *
+ * @public
  */
 export type DocPath<
   Doc extends PathDoc,
@@ -75,15 +84,24 @@ export type DocPath<
   >]: Path extends PathTemplate<Template> ? Template : never;
 }>;
 
+/**
+ * @public
+ */
 export type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
   Extract<keyof Doc['paths'], string>
 >;
 
+/**
+ * @public
+ */
 export type DocPathMethod<
   Doc extends Pick<RequiredDoc, 'paths'>,
   Path extends DocPathTemplate<Doc>,
 > = keyof Doc['paths'][DocPath<Doc, Path>];
 
+/**
+ * @public
+ */
 export type MethodAwareDocPath<
   Doc extends PathDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
@@ -99,17 +117,26 @@ export type MethodAwareDocPath<
     : never;
 }>;
 
+/**
+ * @public
+ */
 export type DocOperation<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
 > = Doc['paths'][Path][Method];
 
+/**
+ * @public
+ */
 export type ComponentTypes<Doc extends RequiredDoc> = Extract<
   keyof Doc['components'],
   string
 >;
 
+/**
+ * @public
+ */
 export type ComponentRef<
   Doc extends RequiredDoc,
   Type extends ComponentTypes<Doc>,
@@ -122,6 +149,9 @@ export type ComponentRef<
     : never
   : never;
 
+/**
+ * @public
+ */
 export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
   $ref: `#/components/schemas/${infer Name}`;
 }
@@ -132,6 +162,9 @@ export type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
     : never
   : { [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]> };
 
+/**
+ * @public
+ */
 export type ObjectWithContentSchema<
   Doc extends RequiredDoc,
   Object extends { content?: ImmutableContentObject },
@@ -143,6 +176,8 @@ export type ObjectWithContentSchema<
  * From {@link https://stackoverflow.com/questions/71393738/typescript-intersection-not-union-type-from-json-schema}
  *
  * StackOverflow says not to do this, but union types aren't possible any other way.
+ *
+ * @public
  */
 export type UnionToIntersection<U> = (
   U extends any ? (k: U) => void : never
@@ -150,20 +185,32 @@ export type UnionToIntersection<U> = (
   ? I
   : never;
 
+/**
+ * @public
+ */
 export type LastOf<T> = UnionToIntersection<
   T extends any ? () => T : never
 > extends () => infer R
   ? R
   : never;
 
+/**
+ * @public
+ */
 export type Push<T extends any[], V> = [...T, V];
 
+/**
+ * @public
+ */
 export type TuplifyUnion<
   T,
   L = LastOf<T>,
   N = [T] extends [never] ? true : false,
 > = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
 
+/**
+ * @public
+ */
 export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   infer First extends JSONSchema7,
   ...infer Rest,
@@ -171,15 +218,27 @@ export type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
   ? ConvertAll<Rest, [...R, FromSchema<First>]>
   : R;
 
+/**
+ * @public
+ */
 export type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
 
+/**
+ * @public
+ */
 export type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
 
+/**
+ * @public
+ */
 export type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
   T,
   Record<K, V>
 >;
 
+/**
+ * @public
+ */
 export type MapDiscriminatedUnion<
   T extends Record<K, string>,
   K extends keyof T,
@@ -187,23 +246,41 @@ export type MapDiscriminatedUnion<
   [V in T[K]]: DiscriminateUnion<T, K, V>;
 };
 
+/**
+ * @public
+ */
 export type PickOptionalKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? never : K;
 }[keyof T];
 
+/**
+ * @public
+ */
 export type PickRequiredKeys<T extends { [key: string]: any }> = {
   [K in keyof T]: true extends T[K]['required'] ? K : never;
 }[keyof T];
 
+/**
+ * @public
+ */
 export type OptionalMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
 };
 
+/**
+ * @public
+ */
 export type RequiredMap<T extends { [key: string]: any }> = {
   [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
 };
 
+/**
+ * @public
+ */
 export type FullMap<T extends { [key: string]: any }> = RequiredMap<T> &
   OptionalMap<T>;
 
+/**
+ * @public
+ */
 export type Filter<T, U> = T extends U ? T : never;

packages/backend-openapi-utils/src/types/express.ts

@@ -21,8 +21,9 @@ import { ResponseBodyToJsonSchema } from './responses';
 
 /**
  * Typed express request handler.
+ * @public
  */
-type DocRequestHandler<
+export type DocRequestHandler<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
@@ -36,8 +37,9 @@ type DocRequestHandler<
 
 /**
  * Typed express error handler / request handler union type.
+ * @public
  */
-type DocRequestHandlerParams<
+export type DocRequestHandlerParams<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends keyof Doc['paths'][Path],
@@ -51,6 +53,7 @@ type DocRequestHandlerParams<
 
 /**
  * Superset of the express router path matcher that enforces typed request and response bodies.
+ * @public
  */
 export interface DocRequestMatcher<
   Doc extends RequiredDoc,

packages/backend-openapi-utils/src/types/immutable.ts

@@ -31,6 +31,8 @@ import type {
 /**
  * From {@link https://github.com/microsoft/TypeScript/issues/13923#issuecomment-653675557}, allows
  *  us to convert from `as const` to the various OpenAPI types documented in `openapi3-ts`.
+ *
+ * @public
  */
 export type Immutable<T> = T extends
   | Function
@@ -46,46 +48,93 @@ export type Immutable<T> = T extends
   ? ReadonlySet<Immutable<S>>
   : { readonly [P in keyof T]: Immutable<T[P]> };
 
+/**
+ * @public
+ */
 export type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
 
+/**
+ * @public
+ */
 export type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
 
+/**
+ * @public
+ */
 export type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
 
+/**
+ * @public
+ */
 export type ImmutableContentObject = ImmutableObject<ContentObject>;
 
+/**
+ * @public
+ */
 export type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
 
+/**
+ * @public
+ */
 export type ImmutableResponseObject = ImmutableObject<ResponseObject>;
 
+/**
+ * @public
+ */
 export type ImmutableParameterObject = ImmutableObject<ParameterObject>;
 
-interface HeaderObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface HeaderObject extends ParameterObject {
   in: 'header';
   style: 'simple';
 }
 
+/**
+ * @public
+ */
 export type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
 
-interface CookieObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface CookieObject extends ParameterObject {
   in: 'cookie';
   style?: 'form';
 }
 
+/**
+ * @public
+ */
 export type ImmutableCookieObject = ImmutableObject<CookieObject>;
 
-interface QueryObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface QueryObject extends ParameterObject {
   in: 'query';
   style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
 }
 
+/**
+ * @public
+ */
 export type ImmutableQueryObject = ImmutableObject<QueryObject>;
 
-interface PathObject extends ParameterObject {
+/**
+ * @public
+ */
+export interface PathObject extends ParameterObject {
   in: 'path';
   style?: 'simple' | 'label' | 'matrix';
 }
-
+/**
+ * @public
+ */
 export type ImmutablePathObject = ImmutableObject<PathObject>;
 
+/**
+ * @public
+ */
 export type ImmutableSchemaObject = ImmutableObject<SchemaObject>;

packages/backend-openapi-utils/src/types/index.ts

@@ -14,32 +14,9 @@
  * limitations under the License.
  */
 
-import type { RequiredDoc } from './common';
-import type { DocRequestMatcher } from './express';
-
-/**
- * @public
- */
-export namespace core {
-  /**
-   * @internal
-   */
-  export type Spec = RequiredDoc;
-
-  /**
-   * @internal
-   */
-  export type RequestMatcher<
-    Doc extends RequiredDoc,
-    T,
-    Method extends
-      | 'all'
-      | 'get'
-      | 'post'
-      | 'put'
-      | 'delete'
-      | 'patch'
-      | 'options'
-      | 'head',
-  > = DocRequestMatcher<Doc, T, Method>;
-}
+export * from './common';
+export * from './express';
+export * from './immutable';
+export * from './params';
+export * from './requests';
+export * from './responses';

packages/backend-openapi-utils/src/types/params.ts

@@ -37,7 +37,10 @@ import {
 } from './common';
 import { FromSchema, JSONSchema7 } from 'json-schema-to-ts';
 
-type DocParameter<
+/**
+ * @public
+ */
+export type DocParameter<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -56,7 +59,10 @@ type DocParameter<
     : never
   : DocOperation<Doc, Path, Method>['parameters'][Parameter];
 
-type DocParameters<
+/**
+ * @public
+ */
+export type DocParameters<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -70,7 +76,10 @@ type DocParameters<
     }
   : never;
 
-type ResolveDocParameterSchema<
+/**
+ * @public
+ */
+export type ResolveDocParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
 > = Schema extends ImmutableReferenceObject
@@ -79,7 +88,10 @@ type ResolveDocParameterSchema<
     : never
   : Schema;
 
-type ParameterSchema<
+/**
+ * @public
+ */
+export type ParameterSchema<
   Doc extends RequiredDoc,
   Schema extends ImmutableParameterObject['schema'],
 > = ResolveDocParameterSchema<Doc, Schema> extends infer R
@@ -90,7 +102,10 @@ type ParameterSchema<
     : never
   : never;
 
-type MapToSchema<
+/**
+ * @public
+ */
+export type MapToSchema<
   Doc extends RequiredDoc,
   T extends Record<string, ImmutableParameterObject>,
 > = {
@@ -99,7 +114,10 @@ type MapToSchema<
     : never;
 };
 
-type ParametersSchema<
+/**
+ * @public
+ */
+export type ParametersSchema<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -116,24 +134,36 @@ type ParametersSchema<
     >
   : never;
 
+/**
+ * @public
+ */
 export type HeaderSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableHeaderObject>;
 
+/**
+ * @public
+ */
 export type CookieSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableCookieObject>;
 
+/**
+ * @public
+ */
 export type PathSchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
   Method extends DocPathMethod<Doc, Path>,
 > = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutablePathObject>;
 
+/**
+ * @public
+ */
 export type QuerySchema<
   Doc extends RequiredDoc,
   Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,

packages/backend-openapi-utils/src/types/requests.ts

@@ -35,7 +35,10 @@ import {
   ImmutableRequestBodyObject,
 } from './immutable';
 
-type RequestBody<
+/**
+ * @public
+ */
+export type RequestBody<
   Doc extends RequiredDoc,
   Path extends Extract<keyof Doc['paths'], string>,
   Method extends keyof Doc['paths'][Path],
@@ -53,7 +56,10 @@ type RequestBody<
     : never
   : DocOperation<Doc, Path, Method>['requestBody'];
 
-type RequestBodySchema<
+/**
+ * @public
+ */
+export type RequestBodySchema<
   Doc extends RequiredDoc,
   Path extends DocPathTemplate<Doc>,
   Method extends DocPathMethod<Doc, Path>,
@@ -67,6 +73,7 @@ type RequestBodySchema<
 
 /**
  * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
  */
 export type RequestBodyToJsonSchema<
   Doc extends RequiredDoc,

packages/backend-openapi-utils/src/types/responses.ts

@@ -24,7 +24,6 @@ import type {
   ObjectWithContentSchema,
   RequiredDoc,
   DocOperation,
-  DocPath,
   DocPathMethod,
   DocPathTemplate,
   PathTemplate,
@@ -33,11 +32,14 @@ import type {
 } from './common';
 import { ImmutableReferenceObject, ImmutableResponseObject } from './immutable';
 
-type Response<
+/**
+ * @public
+ */
+export type Response<
   Doc extends RequiredDoc,
   Path extends keyof Doc['paths'],
   Method extends keyof Doc['paths'][Path],
-  StatusCode extends keyof Doc['paths'][Path]['responses'],
+  StatusCode extends keyof DocOperation<Doc, Path, Method>['responses'],
 > = DocOperation<
   Doc,
   Path,
@@ -52,43 +54,27 @@ type Response<
     : never
   : DocOperation<Doc, Path, Method>['responses'][StatusCode];
 
-type Responses<
+/**
+ * @public
+ */
+export type ResponseSchemas<
   Doc extends RequiredDoc,
-  Path extends keyof Doc['paths'],
-  Method extends keyof Doc['paths'][Path],
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
 > = {
   [StatusCode in keyof DocOperation<Doc, Path, Method>['responses']]: Response<
     Doc,
     Path,
     Method,
     StatusCode
-  >;
-};
-
-type ResponseSchema<
-  Doc extends RequiredDoc,
-  Object extends ImmutableResponseObject,
-> = ObjectWithContentSchema<Doc, Object>;
-
-type ResponseSchemas<
-  Doc extends RequiredDoc,
-  Path extends DocPathTemplate<Doc>,
-  Method extends DocPathMethod<Doc, Path>,
-> = {
-  [StatusCode in keyof Responses<Doc, DocPath<Doc, Path>, Method>]: Responses<
-    Doc,
-    DocPath<Doc, Path>,
-    Method
-  >[StatusCode] extends ImmutableResponseObject
-    ? ResponseSchema<
-        Doc,
-        Responses<Doc, DocPath<Doc, Path>, Method>[StatusCode]
-      >
+  > extends ImmutableResponseObject
+    ? ObjectWithContentSchema<Doc, Response<Doc, Path, Method, StatusCode>>
     : never;
 };
 
 /**
  * Transform the OpenAPI request body schema to a typesafe JSON schema.
+ * @public
  */
 export type ResponseBodyToJsonSchema<
   Doc extends RequiredDoc,