@znight/openapi 0.0.0-stage → 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,260 @@
+import { A as SecuritySchemeObject, C as PathItemObject, D as ResponseObject, E as RequestBodyObjectOf, M as ServerVariableObject, N as SpecificationExtensions, O as ResponseObjectOf, P as TagObject, S as ParameterObjectOf, T as RequestBodyObject, _ as OpenApiObject, a as ExternalDocumentationObject, b as ParameterLocation, c as InfoObject, d as LicenseObject, f as MediaTypeObject, g as OpenApiMethod, h as OAuthFlowsObject, i as ExampleObject, j as ServerObject, k as SecurityRequirementObject, l as JsonSchema, m as OAuthFlowObject, n as ContactObject, o as HeaderObject, p as MediaTypeObjectOf, r as EncodingObjectOf, s as HeaderObjectOf, t as ComponentsObject, u as JsonValue, v as OperationObject, w as ReferenceObject, x as ParameterObject, y as OperationObjectOf } from "./types-VzBexMKj.mjs";
+import { _ as SchemaConverterContext, a as buildOpenApiDocument, c as OpenApiMetadata, d as OperationTemplate, f as ParametersPlaceholder, g as SchemaConverter, h as BUILT_IN_CONVERTERS, i as OpenApiWarning, l as OpenApiOperationDefinition, m as SchemaTemplate, n as OpenApiBuildResult, o as OPENAPI_METADATA_VERSION, p as SchemaPlaceholder, r as OpenApiOperationView, s as OpenApiDocumentTemplate, t as BuildOpenApiOptions, u as OpenApiSchemaSlot, v as standardJsonSchemaConverter, y as valibotConverter } from "./build-BTUC96mY.mjs";
+import { ClassMarker, MethodMarker, Plugin, PluginContext, PluginOptions, PluginRootsContext, ProviderKey, TypedToken } from "@znight/core";
+import { GuardRef, PluginHttpRoutes, PluginHttpRoutesContext, PluginRoute, RouteDecorator, RouteMetaEntry, StandardSchemaV1 } from "@znight/http";
+/** A security scheme declared with {@link securityScheme}. */
+interface SecurityScheme {
+  /** Key of the scheme in `components.securitySchemes`. */
+  readonly name: string;
+  readonly definition: SecuritySchemeObject;
+}
+/** One scheme, several schemes that all apply (AND), or a scheme with scopes. */
+type SecurityRequirementInput = SecurityScheme | readonly SecurityScheme[] | {
+  readonly scheme: SecurityScheme;
+  readonly scopes: readonly string[];
+};
+/** Security of the routes carrying a route decorator (§5.5 of RFC 0002). */
+interface SecurityDecision {
+  /** A route decorator (`createRouteDecorator`) found in the route's effective metadata. */
+  readonly when: RouteDecorator<any>;
+  /** Requirements of the matching routes; `[]` means public. */
+  readonly security: readonly SecurityRequirementInput[];
+  /** `'value'`: the decorator value (a static string array) becomes the scopes of every requirement. */
+  readonly scopes?: "value";
+}
+/** Style of the default operation ids. */
+type OperationIdStyle = "controller.handler" | "handler" | "Controller_handler";
+/** Options of {@link OpenApiDocument}. */
+interface OpenApiDocumentOptions {
+  /** Title, version, description... (defaults: the JSDoc of the class, then `package.json`). */
+  readonly info?: Partial<InfoObject>;
+  readonly servers?: readonly ServerObject[];
+  /** Declared tags first, in this order; used tags are added, sorted. */
+  readonly tags?: readonly TagObject[];
+  readonly externalDocs?: ExternalDocumentationObject;
+  /** Default requirements of every operation: entries are alternatives (OR). Default: none. */
+  readonly security?: readonly SecurityRequirementInput[];
+  /** Security derived from route decorators; the first matching entry wins. */
+  readonly decisions?: readonly SecurityDecision[];
+  /** Ids of operations without `@ApiOperation({ operationId })`. Default `'controller.handler'`. */
+  readonly operationIds?: OperationIdStyle;
+  /** Standard error responses (400, 413, 415, declared 4XX/5XX). Default `true`. */
+  readonly errors?: boolean | {
+    readonly schema: StandardSchemaV1;
+    readonly contentType?: string;
+  };
+  /** ZNIGHT031 and ZNIGHT032 become errors. Default `false`. */
+  readonly strict?: boolean;
+  /** Read the JSDoc of controllers, handlers and types. Default `true`. */
+  readonly jsdoc?: boolean;
+  /** `x-*` fields of the root object. */
+  readonly extensions?: Readonly<Record<`x-${string}`, JsonValue>>;
+}
+/**
+ * Options of the document (one per application, optional). The class is never instantiated nor
+ * registered as a provider; its JSDoc gives the title (first line) and the description (the rest).
+ *
+ * ```ts
+ * /** Bookshelf API *\/
+ * @OpenApiDocument({ servers: [{ url: '/api' }], security: [ApiKey], decisions: [{ when: Public, security: [] }] })
+ * export class BookshelfApi {}
+ * ```
+ */
+export declare function OpenApiDocument(_options?: OpenApiDocumentOptions): ClassMarker;
+/**
+ * Declares a security scheme, read statically by the compiler. At runtime it returns a frozen
+ * `{ name, definition }`.
+ *
+ * ```ts
+ * export const ApiKey = securityScheme('apiKey', { type: 'apiKey', in: 'header', name: 'x-api-key' })
+ * ```
+ */
+export declare function securityScheme(name: string, definition: SecuritySchemeObject): SecurityScheme;
+/** Options of {@link ApiOperation}. */
+interface ApiOperationOptions {
+  readonly summary?: string;
+  readonly description?: string;
+  readonly operationId?: string;
+  readonly deprecated?: boolean;
+  readonly externalDocs?: ExternalDocumentationObject;
+  readonly extensions?: Readonly<Record<`x-${string}`, JsonValue>>;
+}
+/** Overrides the JSDoc and the defaults of an operation. */
+export declare function ApiOperation(_options: ApiOperationOptions): MethodMarker;
+/** Tags of the operations (class and method tags are merged, class tags first). */
+export declare function ApiTags(..._names: [string, ...string[]]): ClassMarker & MethodMarker;
+/** A response status: a code, `'2XX'`-like ranges, or `'default'`. */
+type ApiResponseStatus = number | `${1 | 2 | 3 | 4 | 5}XX` | "default";
+/** Options of {@link ApiResponse}. */
+interface ApiResponseOptions {
+  readonly description?: string;
+  /** Body schema (a Standard Schema, documented with its output JSON Schema). */
+  readonly schema?: StandardSchemaV1;
+  /** Media type(s) of the body. Default `application/json` (when the body has a schema). */
+  readonly contentType?: string | readonly string[];
+  readonly headers?: Readonly<Record<string, Partial<HeaderObject>>>;
+  readonly example?: JsonValue;
+}
+/**
+ * Declares or overrides a response (repeatable). The body type comes from `T`
+ * (`@ApiResponse<Book>(200)`) or from a Standard Schema in `schema`.
+ */
+export declare function ApiResponse<_T = never>(_status: ApiResponseStatus, _options?: ApiResponseOptions): MethodMarker;
+/** Options of {@link ApiBody}. */
+interface ApiBodyOptions {
+  readonly description?: string;
+  readonly required?: boolean;
+  readonly contentType?: string | readonly string[];
+  readonly schema?: StandardSchemaV1;
+}
+/** The body of a route that reads it itself (`ctx.parseBody()`, `ctx.bodyStream()`). */
+export declare function ApiBody<_T = never>(_options?: ApiBodyOptions): MethodMarker;
+/** Options of {@link ApiQuery} and {@link ApiHeader}. */
+interface ApiParameterOptions {
+  readonly description?: string;
+  readonly required?: boolean;
+  readonly deprecated?: boolean;
+  readonly example?: JsonValue;
+}
+/** A query parameter read outside the signature (`ctx.query`); its type is `T` (default `string`). */
+export declare function ApiQuery<_T = string>(_name: string, _options?: ApiParameterOptions): MethodMarker;
+/** A header read by a guard or an interceptor (`x-tenant`); its type is `T` (default `string`). */
+export declare function ApiHeader<_T = string>(_name: string, _options?: ApiParameterOptions): ClassMarker & MethodMarker;
+/**
+ * Security of the operations: the route's wins over the class's. Several arguments are
+ * alternatives (OR); no argument means public (`security: []`).
+ */
+export declare function ApiSecurity(..._requirements: SecurityRequirementInput[]): ClassMarker & MethodMarker;
+/** The controller or route is not documented. */
+export declare function ApiExclude(): ClassMarker & MethodMarker;
+/**
+ * The document of the application, provided by `OpenApiPlugin` (a singleton external declared in
+ * the manifest of `@znight/openapi`).
+ *
+ * ```ts
+ * @Injectable()
+ * export class GatewayRegistration implements OnReady {
+ *   constructor(private readonly openapi: OpenApi, private readonly gateway: GatewayClient) {}
+ *   async onReady(): Promise<void> {
+ *     await this.gateway.publish(await this.openapi.json())
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class OpenApi {
+  /** The frozen document (built on the first call in `'first-request'` mode, or when the plugin is disabled). */
+  abstract document(): Promise<OpenApiObject>;
+  /** The served JSON text (2 spaces, final newline). */
+  abstract json(): Promise<string>;
+  /** The YAML text (optional peer `yaml`). */
+  abstract yaml(): Promise<string>;
+  /** Static view of the operations, without any schema conversion. */
+  abstract readonly operations: readonly OpenApiOperationView[];
+}
+/** Tokens of the externals provided by `OpenApiPlugin` (declared in the package manifest). */
+export declare const OpenApiTokens: {
+  /** The {@link OpenApi} singleton. */
+  readonly OpenApi: TypedToken<OpenApi>;
+};
+/** The supported UIs. */
+type UiKind = "scalar" | "swagger";
+/** An asset of a UI package. */
+interface UiAsset {
+  /** Path in the package. */
+  readonly file: string;
+  /** SRI of the pinned CDN copy. */
+  readonly integrity: string;
+  readonly kind: "script" | "style";
+}
+/** A UI package pinned by this release (bumped by Renovate; checked by a network test). */
+interface UiPackage {
+  readonly name: string;
+  readonly version: string;
+  readonly assets: readonly UiAsset[];
+}
+/** jsDelivr. */
+export declare const CDN_ORIGIN = "https://cdn.jsdelivr.net";
+/** Pinned versions and SRI hashes of the UI assets. */
+export declare const UI_PACKAGES: Readonly<Record<UiKind, UiPackage>>;
+/** The UI option: a kind, or a kind with its JSON-serialisable configuration. */
+type OpenApiUiOption = UiKind | false | {
+  readonly scalar: Readonly<Record<string, JsonValue>>;
+} | {
+  readonly swagger: Readonly<Record<string, JsonValue>>;
+};
+/** Options of {@link OpenApiPlugin.configure}. */
+interface OpenApiPluginOptions {
+  /** `false` serves nothing and builds nothing (the `OpenApi` external still works). Default `true`. */
+  readonly enabled?: boolean;
+  /** Path of the JSON document, relative to the HTTP prefix. Default `'/openapi.json'`. */
+  readonly path?: string;
+  /** A path (`'/openapi.yaml'`) also serves YAML (`application/yaml`, optional peer `yaml`). Default `false`. */
+  readonly yaml?: string | false;
+  /** `'scalar'` (default), `'swagger'`, `false`, or `{ scalar: config }` / `{ swagger: config }`. */
+  readonly ui?: OpenApiUiOption;
+  /** Path of the UI page. Local assets are under `${uiPath}/_assets/`. Default `'/docs'`. */
+  readonly uiPath?: string;
+  /**
+   * `'local'` serves the UI package from `node_modules`, `'cdn'` the jsDelivr copy pinned by this
+   * release (with SRI), `'auto'` (default) local when the package is installed.
+   */
+  readonly assets?: "auto" | "local" | "cdn";
+  /** `'build'` (default) assembles the document from the metadata; `{ file }` serves a prebuilt `openapi.json`. */
+  readonly document?: "build" | {
+    readonly file: string | URL;
+  };
+  /** `'boot'` (default): built in `onBootstrap` (a failure fails the boot); `'first-request'`: built lazily. */
+  readonly build?: "boot" | "first-request";
+  /** Merged over the static `info`. */
+  readonly info?: Partial<InfoObject>;
+  /** Replaces the declared `servers`. */
+  readonly servers?: readonly ServerObject[];
+  readonly filter?: (operation: OpenApiOperationView) => boolean;
+  readonly transform?: (document: OpenApiObject) => OpenApiObject;
+  /** Extra converters, tried before the built-in ones. */
+  readonly converters?: readonly SchemaConverter[];
+  /** `'warn'`: a schema that cannot be converted becomes `{}` (ZNIGHT037 warning). Default `'error'`. */
+  readonly unrepresentable?: "error" | "warn";
+  /** Route metadata of the docs routes (`[Public.meta()]`): seen by guards and by the route decision check. */
+  readonly meta?: readonly RouteMetaEntry[];
+  /** Extra guards of the docs routes (classes or instances), after the global guards. */
+  readonly guards?: readonly GuardRef[];
+  /** `cache-control` of the document (revalidated with the ETag). Default `'no-cache'`. */
+  readonly cacheControl?: string;
+}
+/** A precomputed response body. */
+interface Body {
+  readonly bytes: Uint8Array;
+  readonly etag: string;
+  readonly contentType: string;
+}
+/** Everything served, computed once. */
+interface Served {
+  readonly document: OpenApiObject;
+  readonly json: Body;
+  readonly yaml: Body | undefined;
+}
+/** The OpenAPI plugin: `OpenApiPlugin.configure()` (name `openapi`). */
+export declare class OpenApiPlugin implements Plugin, PluginHttpRoutes {
+  #private;
+  readonly name = "openapi";
+  private constructor();
+  /**
+   * Creates the plugin. `options` may be a function of the container, evaluated once the container
+   * is ready: `OpenApiPlugin.configure(c => ({ enabled: c.get(ServerConfig).docs }))`.
+   */
+  static configure(options?: PluginOptions<OpenApiPluginOptions>): OpenApiPlugin;
+  /** The classes of the `guards` option (instances are left out): `TestApp` creates them at boot. */
+  initRoots(_context?: PluginRootsContext): readonly ProviderKey[];
+  register(ctx: PluginContext): void;
+  httpRoutes(context: PluginHttpRoutesContext): readonly PluginRoute[];
+  onBootstrap(ctx: PluginContext): Promise<void>;
+  onReady(ctx: PluginContext): void;
+  onDispose(): void;
+  /** The views of the operations (no schema conversion). */
+  get operations(): readonly OpenApiOperationView[];
+  /** The served document and bodies, built once (shared promise; a failure is retried on the next call). */
+  served(): Promise<Served>;
+}
+export { type ApiBodyOptions, type ApiOperationOptions, type ApiParameterOptions, type ApiResponseOptions, type ApiResponseStatus, BUILT_IN_CONVERTERS, type BuildOpenApiOptions, type ComponentsObject, type ContactObject, type EncodingObjectOf, type ExampleObject, type ExternalDocumentationObject, type HeaderObject, type HeaderObjectOf, type InfoObject, type JsonSchema, type JsonValue, type LicenseObject, type MediaTypeObject, type MediaTypeObjectOf, type OAuthFlowObject, type OAuthFlowsObject, OPENAPI_METADATA_VERSION, type OpenApiBuildResult, type OpenApiDocumentOptions, type OpenApiDocumentTemplate, type OpenApiMetadata, type OpenApiMethod, type OpenApiObject, type OpenApiOperationDefinition, type OpenApiOperationView, type OpenApiPluginOptions, type OpenApiSchemaSlot, type OpenApiUiOption, type OpenApiWarning, type OperationIdStyle, type OperationObject, type OperationObjectOf, type OperationTemplate, type ParameterLocation, type ParameterObject, type ParameterObjectOf, type ParametersPlaceholder, type PathItemObject, type ReferenceObject, type RequestBodyObject, type RequestBodyObjectOf, type ResponseObject, type ResponseObjectOf, type SchemaConverter, type SchemaConverterContext, type SchemaPlaceholder, type SchemaTemplate, type SecurityDecision, type SecurityRequirementInput, type SecurityRequirementObject, type SecurityScheme, type SecuritySchemeObject, type ServerObject, type ServerVariableObject, type SpecificationExtensions, type TagObject, type UiAsset, type UiKind, type UiPackage, buildOpenApiDocument, standardJsonSchemaConverter, valibotConverter };
+//# sourceMappingURL=index.d.mts.map