@znight/http 0.0.0-stage → 0.1.0

package/dist/compiler.d.mts

@@ -0,0 +1,156 @@
+import { _ as HttpMethod, y as HttpParamSource } from "./adapter-CGSceVEN.mjs";
+import { ClassRef, CompilerExtension, Location, StaticValue, ValueRef } from "@znight/compiler";
+/** Primitive coercions (`coerce.<kind>`). */
+type ScalarCoercion = "string" | "number" | "integer" | "boolean" | "bigint" | "date";
+/**
+ * How a raw value (route parameter, query value, header) is converted to the declared type of a
+ * handler parameter.
+ */
+type CoercionPlan = {
+  readonly kind: ScalarCoercion;
+} | {
+  readonly kind: "enum";
+  readonly values: readonly (string | number | boolean)[];
+} | {
+  readonly kind: "array";
+  readonly item: CoercionPlan;
+} | {
+  readonly kind: "optional";
+  readonly item: CoercionPlan;
+} | {
+  readonly kind: "raw";
+};
+/** The coercion of a handler parameter. */
+interface ParamCoercion {
+  readonly plan: CoercionPlan;
+  /**
+   * The coerced value does not have the declared type (branded primitives, enums, `null` without
+   * `undefined`): the generated expression is cast with `as never`.
+   */
+  readonly cast: boolean;
+}
+/** An upload parameter (`@UploadedFile` / `@UploadedFiles`). */
+interface UploadData {
+  /** Multipart field; `undefined`: any field. */
+  readonly field: string | undefined;
+  /** `@UploadedFiles`. */
+  readonly multiple: boolean;
+  /** A file must be sent (`required` option, else the parameter is not optional). */
+  readonly required: boolean;
+  /** `maxSize` in bytes (`Infinity` allowed). */
+  readonly maxSize: number | undefined;
+  /** `maxFiles` (`@UploadedFiles` only). */
+  readonly maxFiles: number | undefined;
+  /** `mimeTypes` patterns, as written. */
+  readonly mimeTypes: readonly string[] | undefined;
+  /** The injected value does not have the declared type (`node:buffer` File, `File | null`): `as never`. */
+  readonly cast: boolean;
+}
+/** A handler parameter. */
+interface HttpParamData {
+  /** Position in the handler signature. */
+  readonly index: number;
+  /** Parameter name (messages). */
+  readonly name: string;
+  readonly source: HttpParamSource;
+  /** Route parameter name, query key, lower-case header name or cookie name; `undefined` for the whole object. */
+  readonly key: string | undefined;
+  /** Declared (or inferred) type, formatted for humans. */
+  readonly type: string | undefined;
+  /** The parameter accepts `undefined` (`?`, `| undefined`, default value). */
+  readonly optional: boolean;
+  /** Standard Schema validating the value (its output is injected). */
+  readonly schema: ValueRef | undefined;
+  /** Coercion of a named value without schema. */
+  readonly coercion: ParamCoercion | undefined;
+  /** Upload parameter (`source` `file` / `files`). */
+  readonly upload?: UploadData;
+  /**
+   * The default value of the handler parameter (`@Query('page') page = 1` → `1`), when it is
+   * statically evaluable (literals, `const` references; references to exported bindings are left
+   * out). Informational (documentation): the handler applies its own default.
+   */
+  readonly defaultValue?: StaticValue;
+  /** Location of the parameter decorator. */
+  readonly location: Location;
+}
+/** A `createRouteDecorator` value (`route.meta[key]`) and the definition of its decorator. */
+interface MetaEntry {
+  readonly key: string;
+  /** Statically evaluated value; may be or contain references to exported bindings. */
+  readonly value: StaticValue;
+  /** Location of the decorator usage. */
+  readonly location: Location;
+  /** Decision group (`options.group ?? key`). */
+  readonly group: string;
+  /** The group is required (`options.required`). */
+  readonly required: boolean;
+  /** Display name of the decorator (`Roles`). */
+  readonly decorator: string;
+  /** Canonical identity of the decorator `const` (`src/auth/access.ts#Roles`). */
+  readonly identity: string;
+  /** Location of the decorator definition (`export const Roles = createRouteDecorator(...)`). */
+  readonly definition: Location;
+}
+/** Options of an `@Sse` route (`HttpRouteDefinition.sse`). */
+interface SseRouteData {
+  /** Heartbeat in ms; `0` disables it (`heartbeat: false`). Absent: the plugin default. */
+  readonly heartbeat?: number;
+  readonly retry?: number;
+  readonly maxDuration?: number;
+}
+/** A route: one route decorator of a handler. */
+interface HttpRouteData {
+  readonly method: HttpMethod;
+  /** Path of the route decorator as written (`undefined` when absent). */
+  readonly rawPath: string;
+  /** `normalizePath(rawPath)`. */
+  readonly path: string;
+  /** `joinPaths(controller base path, path)`. */
+  readonly fullPath: string;
+  readonly handler: string;
+  readonly status: number | undefined;
+  /** `@Header` entries, lower-case names, in source order. */
+  readonly headers: readonly (readonly [string, string])[];
+  readonly meta: readonly MetaEntry[];
+  readonly guards: readonly ClassRef[];
+  readonly interceptors: readonly ClassRef[];
+  readonly params: readonly HttpParamData[];
+  /** `false` when a parameter could not be analysed (an error was reported; it is missing from `params`). */
+  readonly complete: boolean;
+  /** `@Validate(S)` on a handler without `@Body()` parameter: the body is validated and discarded. */
+  readonly bodySchema: ValueRef | undefined;
+  /** `@BodyLimit` of the method (or of the controller), in bytes. */
+  readonly bodyLimit: number | undefined;
+  readonly rawResponse: boolean;
+  /** `@Sse` route: its options (`{}` without options). */
+  readonly sse?: SseRouteData;
+  /** Location of the route decorator. */
+  readonly location: Location;
+  /** Location of the path argument (the decorator when absent). */
+  readonly pathLocation: Location;
+}
+/** A controller (data stored by `analyzeClass`). */
+interface HttpControllerData {
+  /** Provider token of the controller. */
+  readonly token: string;
+  /** Canonical identity of the class (imported as a type by `invoke`). */
+  readonly identity: string;
+  readonly displayName: string;
+  /** Base path as written. */
+  readonly rawBasePath: string;
+  /** `normalizePath(rawBasePath)`. */
+  readonly basePath: string;
+  readonly guards: readonly ClassRef[];
+  readonly interceptors: readonly ClassRef[];
+  readonly meta: readonly MetaEntry[];
+  readonly routes: readonly HttpRouteData[];
+  /** Location of `@Controller`. */
+  readonly location: Location;
+  /** Location of the base path argument (the decorator when absent). */
+  readonly pathLocation: Location;
+}
+/** The `@znight/http` compiler extension. */
+declare const http: CompilerExtension<HttpControllerData>;
+export { type CoercionPlan, type HttpControllerData, type HttpParamData, type HttpRouteData, type MetaEntry, type ParamCoercion, type ScalarCoercion, type SseRouteData, type UploadData, http as default };
+//# sourceMappingURL=compiler.d.mts.map