@typespec/http-server-js 0.58.0-alpha.10-dev.3

package/src/common/reference.ts

@@ -0,0 +1,319 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import {
+  DiagnosticTarget,
+  IntrinsicType,
+  LiteralType,
+  Namespace,
+  NoTarget,
+  Type,
+  compilerAssert,
+  getEffectiveModelType,
+  getFriendlyName,
+  isArrayModelType,
+} from "@typespec/compiler";
+import { JsContext, Module, isImportableType } from "../ctx.js";
+import { reportDiagnostic } from "../lib.js";
+import { parseCase } from "../util/case.js";
+import { asArrayType, getArrayElementName } from "../util/pluralism.js";
+import { emitModelLiteral, emitWellKnownModel, isWellKnownModel } from "./model.js";
+import { createOrGetModuleForNamespace } from "./namespace.js";
+import { getJsScalar } from "./scalar.js";
+import { emitUnionType } from "./union.js";
+
+export type NamespacedType = Extract<Type, { namespace?: Namespace }>;
+
+/**
+ * Options for emitting a type reference.
+ */
+export interface EmitTypeReferenceOptions {
+  /**
+   * An optional alternative name to use for the type if it is not named.
+   */
+  altName?: string;
+
+  /**
+   * Require a declaration for types that may be represented anonymously.
+   */
+  requireDeclaration?: boolean;
+}
+
+/**
+ * Emits a reference to a host type.
+ *
+ * This function will automatically ensure that the referenced type is included in the emit graph, and will import the
+ * type into the current module if necessary.
+ *
+ * Optionally, a `preferredAlternativeName` may be supplied. This alternative name will be used if a declaration is
+ * required, but the type is anonymous. The alternative name can only be set once. If two callers provide different
+ * alternative names for the same anonymous type, the first one is used in all cases. If a declaration _is_ required,
+ * and no alternative name is supplied (or has been supplied in a prior call to `emitTypeReference`), this function will
+ * throw an error. Callers must be sure to provide an alternative name if the type _may_ have an unknown name. However,
+ * callers may know that they have previously emitted a reference to the type and provided an alternative name in that
+ * call, in which case the alternative name may be safely omitted.
+ *
+ * @param ctx - The emitter context.
+ * @param type - The type to emit a reference to.
+ * @param position - The syntactic position of the reference, for diagnostics.
+ * @param module - The module that the reference is being emitted into.
+ * @param preferredAlternativeName - An optional alternative name to use for the type if it is not named.
+ * @returns a string containing a reference to the TypeScript type that represents the given TypeSpec type.
+ */
+export function emitTypeReference(
+  ctx: JsContext,
+  type: Type,
+  position: DiagnosticTarget | typeof NoTarget,
+  module: Module,
+  options: EmitTypeReferenceOptions = {},
+): string {
+  switch (type.kind) {
+    case "Scalar":
+      // Get the scalar and return it directly, as it is a primitive.
+      return getJsScalar(ctx.program, type, position);
+    case "Model": {
+      // First handle arrays.
+      if (isArrayModelType(ctx.program, type)) {
+        const argumentType = type.indexer.value;
+
+        const argTypeReference = emitTypeReference(ctx, argumentType, position, module, {
+          altName: options.altName && getArrayElementName(options.altName),
+        });
+
+        if (isImportableType(ctx, argumentType) && argumentType.namespace) {
+          module.imports.push({
+            binder: [argTypeReference],
+            from: createOrGetModuleForNamespace(ctx, argumentType.namespace),
+          });
+        }
+
+        return asArrayType(argTypeReference);
+      }
+
+      // Now other well-known models.
+      if (isWellKnownModel(ctx, type)) {
+        return emitWellKnownModel(ctx, type, module, options.altName);
+      }
+
+      // Try to reduce the model to an effective model if possible.
+      const effectiveModel = getEffectiveModelType(ctx.program, type);
+
+      if (effectiveModel.name === "") {
+        // We might have seen the model before and synthesized a declaration for it already.
+        if (ctx.syntheticNames.has(effectiveModel)) {
+          const name = ctx.syntheticNames.get(effectiveModel)!;
+          module.imports.push({
+            binder: [name],
+            from: ctx.syntheticModule,
+          });
+          return name;
+        }
+
+        // Require preferredAlternativeName at this point, as we have an anonymous model that we have not visited.
+        if (!options.altName) {
+          return emitModelLiteral(ctx, effectiveModel, module);
+        }
+
+        // Anonymous model, synthesize a new model with the preferredName
+        ctx.synthetics.push({
+          kind: "anonymous",
+          name: options.altName,
+          underlying: effectiveModel,
+        });
+
+        module.imports.push({
+          binder: [options.altName],
+          from: ctx.syntheticModule,
+        });
+
+        ctx.syntheticNames.set(effectiveModel, options.altName);
+
+        return options.altName;
+      } else {
+        // The effective model is good for a declaration, so enqueue it.
+        ctx.typeQueue.add(effectiveModel);
+      }
+
+      const friendlyName = getFriendlyName(ctx.program, effectiveModel);
+
+      // The model may be a template instance, so we generate a name for it.
+      const templatedName = parseCase(
+        friendlyName
+          ? friendlyName
+          : effectiveModel.templateMapper
+            ? effectiveModel
+                .templateMapper!.args.map((a) => ("name" in a ? String(a.name) : ""))
+                .join("_") + effectiveModel.name
+            : effectiveModel.name,
+      );
+
+      if (!effectiveModel.namespace) {
+        throw new Error("UNREACHABLE: no parent namespace of named model in emitTypeReference");
+      }
+
+      const parentModule = createOrGetModuleForNamespace(ctx, effectiveModel.namespace);
+
+      module.imports.push({
+        binder: [templatedName.pascalCase],
+        from: parentModule,
+      });
+
+      return templatedName.pascalCase;
+    }
+    case "Union": {
+      if (type.variants.size === 0) return "never";
+      else if (type.variants.size === 1)
+        return emitTypeReference(ctx, [...type.variants.values()][0], position, module, options);
+
+      if (options.requireDeclaration) {
+        if (type.name) {
+          const nameCase = parseCase(type.name);
+
+          ctx.typeQueue.add(type);
+
+          module.imports.push({
+            binder: [nameCase.pascalCase],
+            from: createOrGetModuleForNamespace(ctx, type.namespace!),
+          });
+
+          return type.name;
+        } else {
+          const existingSyntheticName = ctx.syntheticNames.get(type);
+
+          if (existingSyntheticName) {
+            module.imports.push({
+              binder: [existingSyntheticName],
+              from: ctx.syntheticModule,
+            });
+
+            return existingSyntheticName;
+          } else {
+            const altName = options.altName;
+
+            if (!altName) {
+              throw new Error("UNREACHABLE: anonymous union without preferredAlternativeName");
+            }
+
+            ctx.synthetics.push({
+              kind: "anonymous",
+              name: altName,
+              underlying: type,
+            });
+
+            module.imports.push({
+              binder: [altName],
+              from: ctx.syntheticModule,
+            });
+
+            ctx.syntheticNames.set(type, altName);
+
+            return altName;
+          }
+        }
+      } else {
+        return emitUnionType(ctx, [...type.variants.values()], module);
+      }
+    }
+    case "Enum": {
+      ctx.typeQueue.add(type);
+
+      const name = parseCase(type.name).pascalCase;
+
+      module.imports.push({
+        binder: [name],
+        from: createOrGetModuleForNamespace(ctx, type.namespace!),
+      });
+
+      return name;
+    }
+    case "String":
+      return escapeUnsafeChars(JSON.stringify(type.value));
+    case "Number":
+    case "Boolean":
+      return String(type.value);
+    case "Intrinsic":
+      switch (type.name) {
+        case "never":
+          return "never";
+        case "null":
+          return "null";
+        case "void":
+          // It's a bit strange to have a void property, but it's possible, and TypeScript allows it. Void is simply
+          // only assignable from undefined or void itself.
+          return "void";
+        case "ErrorType":
+          compilerAssert(
+            false,
+            "ErrorType should not be encountered in emitTypeReference",
+            position === NoTarget ? type : position,
+          );
+          return "unknown";
+        case "unknown":
+          return "unknown";
+        default:
+          reportDiagnostic(ctx.program, {
+            code: "unrecognized-intrinsic",
+            format: { intrinsic: (type satisfies never as IntrinsicType).name },
+            target: position,
+          });
+          return "unknown";
+      }
+    case "Interface": {
+      if (type.namespace === undefined) {
+        throw new Error("UNREACHABLE: unparented interface");
+      }
+
+      const typeName = parseCase(type.name).pascalCase;
+
+      ctx.typeQueue.add(type);
+
+      const parentModule = createOrGetModuleForNamespace(ctx, type.namespace);
+
+      module.imports.push({
+        binder: [typeName],
+        from: parentModule,
+      });
+
+      return typeName;
+    }
+    case "ModelProperty": {
+      // Forward to underlying type.
+      return emitTypeReference(ctx, type.type, position, module, options);
+    }
+    default:
+      throw new Error(`UNREACHABLE: ${type.kind}`);
+  }
+}
+const UNSAFE_CHAR_MAP: { [k: string]: string } = {
+  "<": "\\u003C",
+  ">": "\\u003E",
+  "/": "\\u002F",
+  "\\": "\\\\",
+  "\b": "\\b",
+  "\f": "\\f",
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+  "\0": "\\0",
+  "\u2028": "\\u2028",
+  "\u2029": "\\u2029",
+};
+
+export function escapeUnsafeChars(s: string) {
+  return s.replace(/[<>/\\\b\f\n\r\t\0\u2028\u2029]/g, (x) => UNSAFE_CHAR_MAP[x]);
+}
+
+export type JsTypeSpecLiteralType = LiteralType | (IntrinsicType & { name: "null" });
+
+export function isValueLiteralType(t: Type): t is JsTypeSpecLiteralType {
+  switch (t.kind) {
+    case "String":
+    case "Number":
+    case "Boolean":
+      return true;
+    case "Intrinsic":
+      return t.name === "null";
+    default:
+      return false;
+  }
+}

package/src/common/scalar.ts

@@ -0,0 +1,173 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { DiagnosticTarget, NoTarget, Program, Scalar, formatDiagnostic } from "@typespec/compiler";
+import { JsContext } from "../ctx.js";
+import { reportDiagnostic } from "../lib.js";
+import { parseCase } from "../util/case.js";
+import { UnimplementedError } from "../util/error.js";
+import { getFullyQualifiedTypeName } from "../util/name.js";
+
+/**
+ * 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 scalar - The scalar to emit.
+ * @returns a string that declares an alias to the scalar type in TypeScript.
+ */
+export function emitScalar(ctx: JsContext, scalar: Scalar): string {
+  const jsScalar = getJsScalar(ctx.program, scalar, scalar.node.id);
+
+  const name = parseCase(scalar.name).pascalCase;
+
+  return `type ${name} = ${jsScalar};`;
+}
+
+/**
+ * Get the string parsing template for a given scalar.
+ *
+ * It is common that a scalar type is encoded as a string. For example, in HTTP path parameters or query parameters
+ * where the value may be an integer, but the APIs expose it as a string. In such cases the parse template may be
+ * used to coerce the string value to the correct scalar type.
+ *
+ * The result of this function contains the string "{}" exactly once, which should be replaced with the text of an
+ * expression evaluating to the string representation of the scalar.
+ *
+ * For example, scalars that are represented by JS `number` are parsed with the template `Number({})`, which will
+ * convert the string to a number.
+ *
+ * @param ctx - The emitter context.
+ * @param scalar - The scalar to parse from a string
+ * @returns a template expression string that can be used to parse a string into the scalar type.
+ */
+export function parseTemplateForScalar(ctx: JsContext, scalar: Scalar): string {
+  const jsScalar = getJsScalar(ctx.program, scalar, scalar);
+
+  switch (jsScalar) {
+    case "string":
+      return "{}";
+    case "number":
+      return "Number({})";
+    case "bigint":
+      return "BigInt({})";
+    case "Uint8Array":
+      return "Buffer.from({}, 'base64')";
+    default:
+      throw new UnimplementedError(`parse template for scalar '${jsScalar}'`);
+  }
+}
+
+/**
+ * Get the string encoding template for a given scalar.
+ * @param ctx
+ * @param scalar
+ */
+export function encodeTemplateForScalar(ctx: JsContext, scalar: Scalar): string {
+  const jsScalar = getJsScalar(ctx.program, scalar, scalar);
+
+  switch (jsScalar) {
+    case "string":
+      return "{}";
+    case "number":
+      return "String({})";
+    case "bigint":
+      return "String({})";
+    case "Uint8Array":
+      return "{}.toString('base64')";
+    default:
+      throw new UnimplementedError(`encode template for scalar '${jsScalar}'`);
+  }
+}
+
+const __JS_SCALARS_MAP = new Map<Program, Map<Scalar, string>>();
+
+function getScalarsMap(program: Program): Map<Scalar, string> {
+  let scalars = __JS_SCALARS_MAP.get(program);
+
+  if (scalars === undefined) {
+    scalars = createScalarsMap(program);
+    __JS_SCALARS_MAP.set(program, scalars);
+  }
+
+  return scalars;
+}
+
+function createScalarsMap(program: Program): Map<Scalar, string> {
+  const entries = [
+    [program.resolveTypeReference("TypeSpec.bytes"), "Uint8Array"],
+    [program.resolveTypeReference("TypeSpec.boolean"), "boolean"],
+    [program.resolveTypeReference("TypeSpec.string"), "string"],
+    [program.resolveTypeReference("TypeSpec.float32"), "number"],
+    [program.resolveTypeReference("TypeSpec.float64"), "number"],
+
+    [program.resolveTypeReference("TypeSpec.uint32"), "number"],
+    [program.resolveTypeReference("TypeSpec.uint16"), "number"],
+    [program.resolveTypeReference("TypeSpec.uint8"), "number"],
+    [program.resolveTypeReference("TypeSpec.int32"), "number"],
+    [program.resolveTypeReference("TypeSpec.int16"), "number"],
+    [program.resolveTypeReference("TypeSpec.int8"), "number"],
+
+    [program.resolveTypeReference("TypeSpec.safeint"), "number"],
+    [program.resolveTypeReference("TypeSpec.integer"), "bigint"],
+    [program.resolveTypeReference("TypeSpec.plainDate"), "Date"],
+    [program.resolveTypeReference("TypeSpec.plainTime"), "Date"],
+    [program.resolveTypeReference("TypeSpec.utcDateTime"), "Date"],
+  ] as const;
+
+  for (const [[type, diagnostics]] of entries) {
+    if (!type) {
+      const diagnosticString = diagnostics.map((x) => formatDiagnostic(x)).join("\n");
+      throw new Error(`failed to construct TypeSpec -> JavaScript scalar map: ${diagnosticString}`);
+    } else if (type.kind !== "Scalar") {
+      throw new Error(
+        `type ${(type as any).name ?? "<anonymous>"} is a '${type.kind}', expected 'scalar'`,
+      );
+    }
+  }
+
+  return new Map<Scalar, string>(entries.map(([[type], scalar]) => [type! as Scalar, scalar]));
+}
+
+/**
+ * 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 function getJsScalar(
+  program: Program,
+  scalar: Scalar,
+  diagnosticTarget: DiagnosticTarget | typeof NoTarget,
+): string {
+  const scalars = getScalarsMap(program);
+
+  let _scalar: Scalar | undefined = scalar;
+
+  while (_scalar !== undefined) {
+    const jsScalar = scalars.get(_scalar);
+
+    if (jsScalar !== undefined) {
+      return jsScalar;
+    }
+
+    _scalar = _scalar.baseScalar;
+  }
+
+  reportDiagnostic(program, {
+    code: "unrecognized-scalar",
+    target: diagnosticTarget,
+    format: {
+      scalar: getFullyQualifiedTypeName(scalar),
+    },
+  });
+
+  return "unknown";
+}

package/src/common/serialization/index.ts

@@ -0,0 +1,124 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Model, NoTarget, Scalar, Type, Union } from "@typespec/compiler";
+import { JsContext, Module, completePendingDeclarations } from "../../ctx.js";
+import { UnimplementedError } from "../../util/error.js";
+import { indent } from "../../util/iter.js";
+import { createOrGetModuleForNamespace } from "../namespace.js";
+import { emitTypeReference } from "../reference.js";
+import { emitJsonSerialization, requiresJsonSerialization } from "./json.js";
+
+export type SerializableType = Model | Scalar | Union;
+
+export function isSerializableType(t: Type): t is SerializableType {
+  return t.kind === "Model" || t.kind === "Scalar" || t.kind === "Union";
+}
+
+export type SerializationContentType = "application/json";
+
+const _SERIALIZATIONS_MAP = new WeakMap<SerializableType, Set<SerializationContentType>>();
+
+export function requireSerialization(
+  ctx: JsContext,
+  type: Type,
+  contentType: SerializationContentType,
+): void {
+  if (!isSerializableType(type)) {
+    throw new UnimplementedError(`no implementation of JSON serialization for type '${type.kind}'`);
+  }
+
+  let serializationsForType = _SERIALIZATIONS_MAP.get(type);
+
+  if (!serializationsForType) {
+    serializationsForType = new Set();
+    _SERIALIZATIONS_MAP.set(type, serializationsForType);
+  }
+
+  serializationsForType.add(contentType);
+
+  ctx.serializations.add(type);
+}
+
+export interface SerializationContext extends JsContext {}
+
+export function emitSerialization(ctx: JsContext): void {
+  completePendingDeclarations(ctx);
+
+  const serializationContext: SerializationContext = {
+    ...ctx,
+  };
+
+  while (!ctx.serializations.isEmpty()) {
+    const type = ctx.serializations.take()!;
+
+    const serializations = _SERIALIZATIONS_MAP.get(type)!;
+
+    const requiredSerializations = new Set<SerializationContentType>(
+      [...serializations].filter((serialization) =>
+        isSerializationRequired(ctx, type, serialization),
+      ),
+    );
+
+    if (requiredSerializations.size > 0) {
+      emitSerializationsForType(serializationContext, type, serializations);
+    }
+  }
+}
+
+export function isSerializationRequired(
+  ctx: JsContext,
+  type: Type,
+  serialization: SerializationContentType,
+): boolean {
+  switch (serialization) {
+    case "application/json": {
+      return requiresJsonSerialization(ctx, type);
+    }
+    default:
+      throw new Error(`Unreachable: serialization content type ${serialization satisfies never}`);
+  }
+}
+
+function emitSerializationsForType(
+  ctx: SerializationContext,
+  type: SerializableType,
+  serializations: Set<SerializationContentType>,
+): void {
+  const isSynthetic = ctx.syntheticNames.has(type) || !type.namespace;
+
+  const module = isSynthetic
+    ? ctx.syntheticModule
+    : createOrGetModuleForNamespace(ctx, type.namespace!);
+
+  const typeName = emitTypeReference(ctx, type, NoTarget, module);
+
+  const serializationCode = [`export const ${typeName} = {`];
+
+  for (const serialization of serializations) {
+    serializationCode.push(
+      ...indent(emitSerializationForType(ctx, type, serialization, module, typeName)),
+    );
+  }
+
+  serializationCode.push("} as const;");
+
+  module.declarations.push(serializationCode);
+}
+
+function* emitSerializationForType(
+  ctx: SerializationContext,
+  type: SerializableType,
+  contentType: SerializationContentType,
+  module: Module,
+  typeName: string,
+): Iterable<string> {
+  switch (contentType) {
+    case "application/json": {
+      yield* emitJsonSerialization(ctx, type, module, typeName);
+      break;
+    }
+    default:
+      throw new Error(`Unreachable: serialization content type ${contentType satisfies never}`);
+  }
+}