Add export for core as a whole type.

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

packages/backend-openapi-utils/api-report.md

@@ -3,28 +3,642 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import type { ContentObject } from 'openapi3-ts';
+import { default as core_2 } from 'express-serve-static-core';
+import { FromSchema } from 'json-schema-to-ts';
+import { JSONSchema7 } from 'json-schema-to-ts';
+import type { OpenAPIObject } from 'openapi3-ts';
+import type { ParameterObject } from 'openapi3-ts';
+import type { ReferenceObject } from 'openapi3-ts';
+import type { RequestBodyObject } from 'openapi3-ts';
+import type { ResponseObject } from 'openapi3-ts';
 import { Router } from 'express';
+import type { SchemaObject } from 'openapi3-ts';
 
 // @public
-export interface ApiRouter<Doc extends core.Spec> extends Router {
+export interface ApiRouter<Doc extends RequiredDoc> extends Router {
   // (undocumented)
-  all: core.RequestMatcher<Doc, this, 'all'>;
+  all: DocRequestMatcher<Doc, this, 'all'>;
   // (undocumented)
-  delete: core.RequestMatcher<Doc, this, 'delete'>;
+  delete: DocRequestMatcher<Doc, this, 'delete'>;
   // (undocumented)
-  get: core.RequestMatcher<Doc, this, 'get'>;
+  get: DocRequestMatcher<Doc, this, 'get'>;
   // (undocumented)
-  head: core.RequestMatcher<Doc, this, 'head'>;
+  head: DocRequestMatcher<Doc, this, 'head'>;
   // (undocumented)
-  options: core.RequestMatcher<Doc, this, 'options'>;
+  options: DocRequestMatcher<Doc, this, 'options'>;
   // (undocumented)
-  patch: core.RequestMatcher<Doc, this, 'patch'>;
+  patch: DocRequestMatcher<Doc, this, 'patch'>;
   // (undocumented)
-  post: core.RequestMatcher<Doc, this, 'post'>;
+  post: DocRequestMatcher<Doc, this, 'post'>;
   // (undocumented)
-  put: core.RequestMatcher<Doc, this, 'put'>;
+  put: DocRequestMatcher<Doc, this, 'put'>;
 }
 
 // @public (undocumented)
-export namespace core {}
+type ComponentRef<
+  Doc extends RequiredDoc,
+  Type extends ComponentTypes<Doc>,
+  Ref extends ImmutableReferenceObject,
+> = Ref extends {
+  $ref: `#/components/${Type}/${infer Name}`;
+}
+  ? Name extends keyof Doc['components'][Type]
+    ? Doc['components'][Type][Name] extends ImmutableReferenceObject
+      ? ComponentRef<Doc, Type, Doc['components'][Type][Name]>
+      : Doc['components'][Type][Name]
+    : never
+  : never;
+
+// @public (undocumented)
+type ComponentTypes<Doc extends RequiredDoc> = Extract<
+  keyof Doc['components'],
+  string
+>;
+
+// @public (undocumented)
+type ConvertAll<T, R extends ReadonlyArray<unknown> = []> = T extends [
+  infer First extends JSONSchema7,
+  ...infer Rest,
+]
+  ? ConvertAll<Rest, [...R, FromSchema<First>]>
+  : R;
+
+// @public (undocumented)
+interface CookieObject extends ParameterObject {
+  // (undocumented)
+  in: 'cookie';
+  // (undocumented)
+  style?: 'form';
+}
+
+// @public (undocumented)
+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>;
+
+declare namespace core {
+  export {
+    RequiredDoc,
+    PathDoc,
+    ValueOf,
+    PathTemplate,
+    DocPath,
+    DocPathTemplate,
+    DocPathMethod,
+    MethodAwareDocPath,
+    DocOperation,
+    ComponentTypes,
+    ComponentRef,
+    SchemaRef,
+    ObjectWithContentSchema,
+    UnionToIntersection,
+    LastOf,
+    Push,
+    TuplifyUnion,
+    ConvertAll,
+    UnknownIfNever,
+    ToTypeSafe,
+    DiscriminateUnion,
+    MapDiscriminatedUnion,
+    PickOptionalKeys,
+    PickRequiredKeys,
+    OptionalMap,
+    RequiredMap,
+    FullMap,
+    Filter,
+    DocRequestHandler,
+    DocRequestHandlerParams,
+    DocRequestMatcher,
+    Immutable,
+    ImmutableObject,
+    ImmutableReferenceObject,
+    ImmutableOpenAPIObject,
+    ImmutableContentObject,
+    ImmutableRequestBodyObject,
+    ImmutableResponseObject,
+    ImmutableParameterObject,
+    HeaderObject,
+    ImmutableHeaderObject,
+    CookieObject,
+    ImmutableCookieObject,
+    QueryObject,
+    ImmutableQueryObject,
+    PathObject,
+    ImmutablePathObject,
+    ImmutableSchemaObject,
+    DocParameter,
+    DocParameters,
+    ResolveDocParameterSchema,
+    ParameterSchema,
+    MapToSchema,
+    ParametersSchema,
+    HeaderSchema,
+    CookieSchema,
+    PathSchema,
+    QuerySchema,
+    RequestBody,
+    RequestBodySchema,
+    RequestBodyToJsonSchema,
+    Response_2 as Response,
+    ResponseSchemas,
+    ResponseBodyToJsonSchema,
+  };
+}
+export { core };
+
+// @public (undocumented)
+type DiscriminateUnion<T, K extends keyof T, V extends T[K]> = Extract<
+  T,
+  Record<K, V>
+>;
+
+// @public (undocumented)
+type DocOperation<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+> = Doc['paths'][Path][Method];
+
+// @public (undocumented)
+type DocParameter<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  Parameter extends keyof Doc['paths'][Path][Method]['parameters'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['parameters'][Parameter] extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'parameters',
+        DocOperation<Doc, Path, Method>['parameters'][Parameter]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['parameters'][Parameter];
+
+// @public (undocumented)
+type DocParameters<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+> = DocOperation<Doc, Path, Method>['parameters'] extends ReadonlyArray<any>
+  ? {
+      [Index in keyof DocOperation<
+        Doc,
+        Path,
+        Method
+      >['parameters']]: DocParameter<Doc, Path, Method, Index>;
+    }
+  : never;
+
+// @public
+type DocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template> ? Template : never;
+}>;
+
+// @public (undocumented)
+type DocPathMethod<
+  Doc extends Pick<RequiredDoc, 'paths'>,
+  Path extends DocPathTemplate<Doc>,
+> = keyof Doc['paths'][DocPath<Doc, Path>];
+
+// @public (undocumented)
+type DocPathTemplate<Doc extends PathDoc> = PathTemplate<
+  Extract<keyof Doc['paths'], string>
+>;
+
+// @public
+type DocRequestHandler<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core_2.RequestHandler<
+  PathSchema<Doc, Path, Method>,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  QuerySchema<Doc, Path, Method>,
+  Record<string, string>
+>;
+
+// @public
+type DocRequestHandlerParams<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends keyof Doc['paths'][Path],
+> = core_2.RequestHandlerParams<
+  PathSchema<Doc, Path, Method>,
+  ResponseBodyToJsonSchema<Doc, Path, Method>,
+  RequestBodyToJsonSchema<Doc, Path, Method>,
+  QuerySchema<Doc, Path, Method>,
+  Record<string, string>
+>;
+
+// @public
+interface DocRequestMatcher<
+  Doc extends RequiredDoc,
+  T,
+  Method extends
+    | 'all'
+    | 'get'
+    | 'post'
+    | 'put'
+    | 'delete'
+    | 'patch'
+    | 'options'
+    | 'head',
+> {
+  // (undocumented)
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandler<Doc, Path, Method>>
+  ): T;
+  // (undocumented)
+  <Path extends MethodAwareDocPath<Doc, DocPathTemplate<Doc>, Method>>(
+    path: Path,
+    ...handlers: Array<DocRequestHandlerParams<Doc, Path, Method>>
+  ): T;
+}
+
+// @public (undocumented)
+type Filter<T, U> = T extends U ? T : never;
+
+// @public (undocumented)
+type FullMap<
+  T extends {
+    [key: string]: any;
+  },
+> = RequiredMap<T> & OptionalMap<T>;
+
+// @public (undocumented)
+interface HeaderObject extends ParameterObject {
+  // (undocumented)
+  in: 'header';
+  // (undocumented)
+  style: 'simple';
+}
+
+// @public (undocumented)
+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
+type Immutable<T> = T extends
+  | Function
+  | boolean
+  | number
+  | string
+  | null
+  | undefined
+  ? T
+  : T extends Map<infer K, infer V>
+  ? ReadonlyMap<Immutable<K>, Immutable<V>>
+  : T extends Set<infer S>
+  ? ReadonlySet<Immutable<S>>
+  : {
+      readonly [P in keyof T]: Immutable<T[P]>;
+    };
+
+// @public (undocumented)
+type ImmutableContentObject = ImmutableObject<ContentObject>;
+
+// @public (undocumented)
+type ImmutableCookieObject = ImmutableObject<CookieObject>;
+
+// @public (undocumented)
+type ImmutableHeaderObject = ImmutableObject<HeaderObject>;
+
+// @public (undocumented)
+type ImmutableObject<T> = {
+  readonly [K in keyof T]: Immutable<T[K]>;
+};
+
+// @public (undocumented)
+type ImmutableOpenAPIObject = ImmutableObject<OpenAPIObject>;
+
+// @public (undocumented)
+type ImmutableParameterObject = ImmutableObject<ParameterObject>;
+
+// @public (undocumented)
+type ImmutablePathObject = ImmutableObject<PathObject>;
+
+// @public (undocumented)
+type ImmutableQueryObject = ImmutableObject<QueryObject>;
+
+// @public (undocumented)
+type ImmutableReferenceObject = ImmutableObject<ReferenceObject>;
+
+// @public (undocumented)
+type ImmutableRequestBodyObject = ImmutableObject<RequestBodyObject>;
+
+// @public (undocumented)
+type ImmutableResponseObject = ImmutableObject<ResponseObject>;
+
+// @public (undocumented)
+type ImmutableSchemaObject = ImmutableObject<SchemaObject>;
+
+// @public (undocumented)
+type LastOf<T> = UnionToIntersection<
+  T extends any ? () => T : never
+> extends () => infer R
+  ? R
+  : never;
+
+// @public (undocumented)
+type MapDiscriminatedUnion<T extends Record<K, string>, K extends keyof T> = {
+  [V in T[K]]: DiscriminateUnion<T, K, V>;
+};
+
+// @public (undocumented)
+type MapToSchema<
+  Doc extends RequiredDoc,
+  T extends Record<string, ImmutableParameterObject>,
+> = {
+  [V in keyof T]: NonNullable<T[V]> extends ImmutableParameterObject
+    ? ParameterSchema<Doc, NonNullable<T[V]>['schema']>
+    : never;
+};
+
+// @public (undocumented)
+type MethodAwareDocPath<
+  Doc extends PathDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends keyof Doc['paths'][Path],
+> = ValueOf<{
+  [Template in Extract<
+    keyof Doc['paths'],
+    string
+  >]: Path extends PathTemplate<Template>
+    ? Method extends DocPathMethod<Doc, Path>
+      ? PathTemplate<Template>
+      : never
+    : never;
+}>;
+
+// @public (undocumented)
+type ObjectWithContentSchema<
+  Doc extends RequiredDoc,
+  Object extends {
+    content?: ImmutableContentObject;
+  },
+> = Object['content'] extends ImmutableContentObject
+  ? SchemaRef<Doc, Object['content']['application/json']['schema']>
+  : never;
+
+// @public (undocumented)
+type OptionalMap<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [P in Exclude<PickOptionalKeys<T>, undefined>]?: NonNullable<T[P]>;
+};
+
+// @public (undocumented)
+type ParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = ResolveDocParameterSchema<Doc, Schema> extends infer R
+  ? R extends ImmutableSchemaObject
+    ? R extends JSONSchema7
+      ? FromSchema<R>
+      : never
+    : never
+  : never;
+
+// @public (undocumented)
+type ParametersSchema<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+  FilterType extends ImmutableParameterObject,
+> = number extends keyof DocParameters<Doc, Path, Method>
+  ? MapToSchema<
+      Doc,
+      FullMap<
+        MapDiscriminatedUnion<
+          Filter<DocParameters<Doc, Path, Method>[number], FilterType>,
+          'name'
+        >
+      >
+    >
+  : never;
+
+// @public (undocumented)
+type PathDoc = Pick<ImmutableOpenAPIObject, 'paths'>;
+
+// @public (undocumented)
+interface PathObject extends ParameterObject {
+  // (undocumented)
+  in: 'path';
+  // (undocumented)
+  style?: 'simple' | 'label' | 'matrix';
+}
+
+// @public (undocumented)
+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
+type PathTemplate<Path extends string> =
+  Path extends `${infer Prefix}{${infer PathName}}${infer Suffix}`
+    ? `${Prefix}:${PathName}${PathTemplate<Suffix>}`
+    : Path;
+
+// @public (undocumented)
+type PickOptionalKeys<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [K in keyof T]: true extends T[K]['required'] ? never : K;
+}[keyof T];
+
+// @public (undocumented)
+type PickRequiredKeys<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [K in keyof T]: true extends T[K]['required'] ? K : never;
+}[keyof T];
+
+// @public (undocumented)
+type Push<T extends any[], V> = [...T, V];
+
+// @public (undocumented)
+interface QueryObject extends ParameterObject {
+  // (undocumented)
+  in: 'query';
+  // (undocumented)
+  style?: 'form' | 'deepObject' | 'pipeDelimited' | 'spaceDelimited';
+}
+
+// @public (undocumented)
+type QuerySchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ParametersSchema<Doc, DocPath<Doc, Path>, Method, ImmutableQueryObject>;
+
+// @public (undocumented)
+type RequestBody<
+  Doc extends RequiredDoc,
+  Path extends Extract<keyof Doc['paths'], string>,
+  Method extends keyof Doc['paths'][Path],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['requestBody'] extends ImmutableReferenceObject
+  ? 'requestBodies' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'requestBodies',
+        DocOperation<Doc, Path, Method>['requestBody']
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['requestBody'];
+
+// @public (undocumented)
+type RequestBodySchema<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = RequestBody<
+  Doc,
+  DocPath<Doc, Path>,
+  Method
+> extends ImmutableRequestBodyObject
+  ? ObjectWithContentSchema<Doc, RequestBody<Doc, DocPath<Doc, Path>, Method>>
+  : never;
+
+// @public
+type RequestBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ToTypeSafe<RequestBodySchema<Doc, Path, Method>>;
+
+// @public
+type RequiredDoc = Pick<ImmutableOpenAPIObject, 'paths' | 'components'>;
+
+// @public (undocumented)
+type RequiredMap<
+  T extends {
+    [key: string]: any;
+  },
+> = {
+  [P in Exclude<PickRequiredKeys<T>, undefined>]: NonNullable<T[P]>;
+};
+
+// @public (undocumented)
+type ResolveDocParameterSchema<
+  Doc extends RequiredDoc,
+  Schema extends ImmutableParameterObject['schema'],
+> = Schema extends ImmutableReferenceObject
+  ? 'parameters' extends ComponentTypes<Doc>
+    ? ComponentRef<Doc, 'parameters', Schema>
+    : never
+  : Schema;
+
+// @public (undocumented)
+type Response_2<
+  Doc extends RequiredDoc,
+  Path extends keyof Doc['paths'],
+  Method extends keyof Doc['paths'][Path],
+  StatusCode extends keyof DocOperation<Doc, Path, Method>['responses'],
+> = DocOperation<
+  Doc,
+  Path,
+  Method
+>['responses'][StatusCode] extends ImmutableReferenceObject
+  ? 'responses' extends ComponentTypes<Doc>
+    ? ComponentRef<
+        Doc,
+        'responses',
+        DocOperation<Doc, Path, Method>['responses'][StatusCode]
+      >
+    : never
+  : DocOperation<Doc, Path, Method>['responses'][StatusCode];
+
+// @public
+type ResponseBodyToJsonSchema<
+  Doc extends RequiredDoc,
+  Path extends PathTemplate<Extract<keyof Doc['paths'], string>>,
+  Method extends DocPathMethod<Doc, Path>,
+> = ToTypeSafe<ValueOf<ResponseSchemas<Doc, Path, Method>>>;
+
+// @public (undocumented)
+type ResponseSchemas<
+  Doc extends RequiredDoc,
+  Path extends DocPathTemplate<Doc>,
+  Method extends DocPathMethod<Doc, Path>,
+> = {
+  [StatusCode in keyof DocOperation<
+    Doc,
+    Path,
+    Method
+  >['responses']]: Response_2<
+    Doc,
+    Path,
+    Method,
+    StatusCode
+  > extends ImmutableResponseObject
+    ? ObjectWithContentSchema<Doc, Response_2<Doc, Path, Method, StatusCode>>
+    : never;
+};
+
+// @public (undocumented)
+type SchemaRef<Doc extends RequiredDoc, Schema> = Schema extends {
+  $ref: `#/components/schemas/${infer Name}`;
+}
+  ? 'schemas' extends keyof Doc['components']
+    ? Name extends keyof Doc['components']['schemas']
+      ? SchemaRef<Doc, Doc['components']['schemas'][Name]>
+      : never
+    : never
+  : {
+      [Key in keyof Schema]: SchemaRef<Doc, Schema[Key]>;
+    };
+
+// @public (undocumented)
+type ToTypeSafe<T> = UnknownIfNever<ConvertAll<TuplifyUnion<T>>[number]>;
+
+// @public (undocumented)
+type TuplifyUnion<
+  T,
+  L = LastOf<T>,
+  N = [T] extends [never] ? true : false,
+> = true extends N ? [] : Push<TuplifyUnion<Exclude<T, L>>, L>;
+
+// @public
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never;
+
+// @public (undocumented)
+type UnknownIfNever<P> = [P] extends [never] ? unknown : P;
+
+// @public
+type ValueOf<T> = T[keyof T];
 ```

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,