@typespec/http-server-js/dist/src/common/scalar.d.ts

TypeSpec HTTP server code generator for JavaScript

import { DiagnosticTarget, EncodeData, NoTarget, Scalar } from "@typespec/compiler";
import { JsContext, Module } from "../ctx.js";
import { HttpOperationParameter } from "@typespec/http";
/**
 * A specification of a TypeSpec scalar type.
 */
export interface ScalarInfo {
    /**
     * The TypeScript type that represents the scalar, or a function if the scalar requires a representation
     * that is not built-in.
     */
    type: MaybeDependent<string>;
    /**
     * A map of supported encodings for the scalar.
     */
    encodings?: {
        [target: string]: {
            /**
             * The default encoding for the target.
             */
            default?: MaybeDependent<ScalarEncoding>;
            /**
             * The encoding for the scalar when encoded using a particular method.
             */
            [encoding: string]: MaybeDependent<ScalarEncoding> | undefined;
        };
    };
    /**
     * A map of default encodings for the scalar.
     */
    defaultEncodings?: {
        /**
         * The default encoding pair to use for a given MIME type.
         */
        byMimeType?: {
            [contentType: string]: [string, string];
        };
        /**
         * The default encoding pair to use in the context of HTTP metadata.
         */
        http?: {
            [K in HttpOperationParameter["type"]]?: [string, string];
        };
    };
    /**
     * Whether or not this scalar can serve as a JSON-compatible type.
     *
     * If JSON serialization reaches a non-compatible scalar and no more encodings are available, it is treated as
     * an unknown type.
     */
    isJsonCompatible: boolean;
}
/**
 * A function that resolves a value dependent on the context and module it's requested from.
 */
export interface Dependent<T> {
    (ctx: JsContext, module: Module): T;
}
/**
 * A value that might be dependent.
 */
export type MaybeDependent<T> = T | Dependent<T>;
/**
 * A definition of a scalar encoding.
 */
export type ScalarEncoding = ScalarEncodingTemplates | ScalarEncodingVia;
/**
 * A definition of a scalar encoding with templates.
 */
export interface ScalarEncodingTemplates {
    /**
     * The template to use to encode the scalar.
     *
     * The position of the string "{}" in the template will be replaced with the value to encode.
     */
    encodeTemplate: MaybeDependent<string>;
    /**
     * The template to use to decode the scalar.
     *
     * The position of the string "{}" in the template will be replaced with the value to decode.
     */
    decodeTemplate: MaybeDependent<string>;
}
export interface ScalarEncodingVia {
    /**
     * If set, the name of the encoding to use as a base for this encoding.
     *
     * This can be used to define an encoding that is a modification of another encoding, such as a URL-encoded version
     * of a base64-encoded value, which depends on the base64 encoding.
     */
    via: string;
    /**
     * Optional encoding template, defaults to "{}"
     */
    encodeTemplate?: MaybeDependent<string>;
    /**
     * Optional decoding template, defaults to "{}"
     */
    decodeTemplate?: MaybeDependent<string>;
}
/**
 * Emits a declaration for a scalar type.
 *
 * This is rare in TypeScript, as the scalar will ordinarily be used inline, but may be desirable in some cases.
 *
 * @param ctx - The emitter context.
 * @param module - The module that the scalar is being emitted in.
 * @param scalar - The scalar to emit.
 * @returns a string that declares an alias to the scalar type in TypeScript.
 */
export declare function emitScalar(ctx: JsContext, scalar: Scalar, module: Module): Iterable<string>;
/**
 * Reports a scalar as unrecognized, so that the spec author knows it is treated as `unknown`.
 *
 * @param ctx - The emitter context.
 * @param scalar - The scalar that was not recognized.
 * @param target - The diagnostic target to report the error on.
 */
export declare function reportUnrecognizedScalar(ctx: JsContext, scalar: Scalar, target: DiagnosticTarget | typeof NoTarget): void;
/**
 * An encoder that encodes a scalar type to the `target` scalar type.
 *
 * The type that this encoder encodes _from_ is the type of the scalar that it is bound to. It _MUST_ be used only with expressions
 * of the type that represents the source scalar.
 */
export interface Encoder {
    /**
     * The target scalar type that this encoder encodes to.
     */
    readonly target: JsScalar;
    /**
     * Produces an expression that encodes the `subject` expression of the source type into the target.
     *
     * @param subject - An expression of the type that represents the source scalar.
     */
    encode(subject: string): string;
    /**
     * Produces an expression that decodes the `subject` expression from the target into the source type.
     *
     * @param subject - An expression of the type that represents the target scalar.
     */
    decode(subject: string): string;
}
/**
 * A representation of a TypeSpec scalar in TypeScript.
 */
export interface JsScalar {
    /**
     * The TypeScript type that represents the scalar.
     */
    readonly type: string;
    /**
     * The TypeSpec scalar that it represents, or "unknown" if the Scalar is not recognized.
     */
    readonly scalar: Scalar | "unknown";
    /**
     * Get an encoder that encodes this scalar type to a different scalar type using a given encoding.
     *
     * @param encoding - the encoding to use (e.g. "base64", "base64url", etc.)
     * @param target - the target scalar type to encode to
     * @returns an encoder that encodes this scalar type to the target scalar type using the given encoding, or undefined
     * if the encoding is not supported.
     */
    getEncoding(encoding: string, target: Scalar): Encoder | undefined;
    getEncoding(encoding: EncodeData): Encoder | undefined;
    /**
     * Get the default encoder for a given media type.
     *
     * @param mimeType - the media type to get the default encoder for (e.g. "application/json", "text/plain", etc.)
     * @returns an encoder that encodes this scalar type to the target scalar type using the given encoding, or undefined
     * if no default encoder is defined for the given media type.
     */
    getDefaultMimeEncoding(mimeType: string): Encoder | undefined;
    /**
     * Whether this scalar can be used directly in JSON serialization.
     *
     * If true, this scalar will be represented faithfully if it is passed to JSON.stringify or JSON.parse.
     */
    isJsonCompatible: boolean;
    /**
     * A map of encoders when this type is used in HTTP metadata.
     */
    readonly http: {
        readonly [K in HttpOperationParameter["type"]]: Encoder;
    };
}
/**
 * A JsScalar value that represents an unknown scalar.
 */
export declare const JS_SCALAR_UNKNOWN: JsScalar;
/**
 * Gets a TypeScript type that can represent a given TypeSpec scalar.
 *
 * Scalar recognition is recursive. If a scalar is not recognized, we will treat it as its parent scalar and try again.
 *
 * If no scalar in the chain is recognized, it will be treated as `unknown` and a warning will be issued.
 *
 * @param program - The program that contains the scalar
 * @param scalar - The scalar to get the TypeScript type for
 * @param diagnosticTarget - Where to report a diagnostic if the scalar is not recognized.
 * @returns a string containing a TypeScript type that can represent the scalar
 */
export declare function getJsScalar(ctx: JsContext, module: Module, scalar: Scalar, diagnosticTarget: DiagnosticTarget | typeof NoTarget): JsScalar;
//# sourceMappingURL=scalar.d.ts.map