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

package/src/common/enum.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Enum } from "@typespec/compiler";
+import { JsContext } from "../ctx.js";
+import { parseCase } from "../util/case.js";
+import { emitDocumentation } from "./documentation.js";
+
+/**
+ * Emit an enum declaration.
+ *
+ * @param ctx - The emitter context.
+ * @param enum_ - The enum to emit.
+ */
+export function* emitEnum(ctx: JsContext, enum_: Enum): Iterable<string> {
+  yield* emitDocumentation(ctx, enum_);
+
+  const name = parseCase(enum_.name);
+
+  yield `export enum ${name.pascalCase} {`;
+
+  for (const member of enum_.members.values()) {
+    const nameCase = parseCase(member.name);
+    yield `  ${nameCase.pascalCase} = ${JSON.stringify(member.value)},`;
+  }
+
+  yield `}`;
+}

package/src/common/interface.ts

@@ -0,0 +1,264 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Interface, Operation, Type, UnionVariant, isErrorModel } from "@typespec/compiler";
+import { JsContext, Module, PathCursor } from "../ctx.js";
+import { parseCase } from "../util/case.js";
+import { getAllProperties } from "../util/extends.js";
+import { bifilter, indent } from "../util/iter.js";
+import { emitDocumentation } from "./documentation.js";
+import { emitTypeReference, isValueLiteralType } from "./reference.js";
+import { emitUnionType } from "./union.js";
+
+/**
+ * Emit an interface declaration.
+ *
+ * @param ctx - The emitter context.
+ * @param iface - The interface to emit.
+ * @param module - The module that this interface is written into.
+ */
+export function* emitInterface(ctx: JsContext, iface: Interface, module: Module): Iterable<string> {
+  const name = parseCase(iface.name).pascalCase;
+
+  yield* emitDocumentation(ctx, iface);
+  yield `export interface ${name}<Context = unknown> {`;
+  yield* indent(emitOperationGroup(ctx, iface.operations.values(), module));
+  yield "}";
+  yield "";
+}
+
+/**
+ * Emit a list of operation signatures.
+ *
+ * @param ctx - The emitter context.
+ * @param operations - The operations to emit.
+ * @param module - The module that the operations are written into.
+ */
+export function* emitOperationGroup(
+  ctx: JsContext,
+  operations: Iterable<Operation>,
+  module: Module,
+): Iterable<string> {
+  for (const op of operations) {
+    yield* emitOperation(ctx, op, module);
+    yield "";
+  }
+}
+
+/**
+ * Emit a single operation signature.
+ *
+ * @param ctx - The emitter context.
+ * @param op - The operation to emit.
+ * @param module - The module that the operation is written into.
+ */
+export function* emitOperation(ctx: JsContext, op: Operation, module: Module): Iterable<string> {
+  const opNameCase = parseCase(op.name);
+
+  const opName = opNameCase.camelCase;
+
+  const allParameters = getAllProperties(op.parameters);
+
+  const hasOptions = allParameters.some((p) => p.optional);
+
+  const returnTypeReference = emitTypeReference(ctx, op.returnType, op, module, {
+    altName: opNameCase.pascalCase + "Result",
+  });
+
+  const returnType = `Promise<${returnTypeReference}>`;
+
+  const params: string[] = [];
+
+  for (const param of allParameters) {
+    // If the type is a value literal, then we consider it a _setting_ and not a parameter.
+    // This allows us to exclude metadata parameters (such as contentType) from the generated interface.
+    if (param.optional || isValueLiteralType(param.type)) continue;
+
+    const paramNameCase = parseCase(param.name);
+    const paramName = paramNameCase.camelCase;
+
+    const outputTypeReference = emitTypeReference(ctx, param.type, param, module, {
+      altName: opNameCase.pascalCase + paramNameCase.pascalCase,
+    });
+
+    params.push(`${paramName}: ${outputTypeReference}`);
+  }
+
+  const paramsDeclarationLine = params.join(", ");
+
+  yield* emitDocumentation(ctx, op);
+
+  if (hasOptions) {
+    const optionsTypeName = opNameCase.pascalCase + "Options";
+
+    emitOptionsType(ctx, op, module, optionsTypeName);
+
+    const paramsFragment = params.length > 0 ? `${paramsDeclarationLine}, ` : "";
+
+    // prettier-ignore
+    yield `${opName}(ctx: Context, ${paramsFragment}options?: ${optionsTypeName}): ${returnType};`;
+    yield "";
+  } else {
+    // prettier-ignore
+    yield `${opName}(ctx: Context, ${paramsDeclarationLine}): ${returnType};`;
+    yield "";
+  }
+}
+
+/**
+ * Emit a declaration for an options type including the optional parameters of an operation.
+ *
+ * @param ctx - The emitter context.
+ * @param operation - The operation to emit the options type for.
+ * @param module - The module that the options type is written into.
+ * @param optionsTypeName - The name of the options type.
+ */
+export function emitOptionsType(
+  ctx: JsContext,
+  operation: Operation,
+  module: Module,
+  optionsTypeName: string,
+) {
+  module.imports.push({
+    binder: [optionsTypeName],
+    from: ctx.syntheticModule,
+  });
+
+  const options = [...operation.parameters.properties.values()].filter((p) => p.optional);
+
+  ctx.syntheticModule.declarations.push([
+    `export interface ${optionsTypeName} {`,
+    ...options.flatMap((p) => [
+      `  ${parseCase(p.name).camelCase}?: ${emitTypeReference(ctx, p.type, p, module, {
+        altName: optionsTypeName + parseCase(p.name).pascalCase,
+      })};`,
+    ]),
+    "}",
+    "",
+  ]);
+}
+
+export interface SplitReturnTypeCommon {
+  typeReference: string;
+  target: Type | [PathCursor, string] | undefined;
+}
+
+export interface OrdinarySplitReturnType extends SplitReturnTypeCommon {
+  kind: "ordinary";
+}
+
+export interface UnionSplitReturnType extends SplitReturnTypeCommon {
+  kind: "union";
+  variants: UnionVariant[];
+}
+
+export type SplitReturnType = OrdinarySplitReturnType | UnionSplitReturnType;
+
+const DEFAULT_NO_VARIANT_RETURN_TYPE = "never";
+const DEFAULT_NO_VARIANT_SPLIT: SplitReturnType = {
+  kind: "ordinary",
+  typeReference: DEFAULT_NO_VARIANT_RETURN_TYPE,
+  target: undefined,
+};
+
+export function isInfallible(split: SplitReturnType): boolean {
+  return (
+    (split.kind === "ordinary" && split.typeReference === "never") ||
+    (split.kind === "union" && split.variants.length === 0)
+  );
+}
+
+export function splitReturnType(
+  ctx: JsContext,
+  type: Type,
+  module: Module,
+  altBaseName: string,
+): [SplitReturnType, SplitReturnType] {
+  const successAltName = altBaseName + "Response";
+  const errorAltName = altBaseName + "ErrorResponse";
+
+  if (type.kind === "Union") {
+    const [successVariants, errorVariants] = bifilter(
+      type.variants.values(),
+      (v) => !isErrorModel(ctx.program, v.type),
+    );
+
+    const successTypeReference =
+      successVariants.length === 0
+        ? DEFAULT_NO_VARIANT_RETURN_TYPE
+        : successVariants.length === 1
+          ? emitTypeReference(ctx, successVariants[0].type, successVariants[0], module, {
+              altName: successAltName,
+            })
+          : emitUnionType(ctx, successVariants, module);
+
+    const errorTypeReference =
+      errorVariants.length === 0
+        ? DEFAULT_NO_VARIANT_RETURN_TYPE
+        : errorVariants.length === 1
+          ? emitTypeReference(ctx, errorVariants[0].type, errorVariants[0], module, {
+              altName: errorAltName,
+            })
+          : emitUnionType(ctx, errorVariants, module);
+
+    const successSplit: SplitReturnType =
+      successVariants.length > 1
+        ? {
+            kind: "union",
+            variants: successVariants,
+            typeReference: successTypeReference,
+            target: undefined,
+          }
+        : {
+            kind: "ordinary",
+            typeReference: successTypeReference,
+            target: successVariants[0]?.type,
+          };
+
+    const errorSplit: SplitReturnType =
+      errorVariants.length > 1
+        ? {
+            kind: "union",
+            variants: errorVariants,
+            typeReference: errorTypeReference,
+            // target: module.cursor.resolveRelativeItemPath(errorTypeReference),
+            target: undefined,
+          }
+        : {
+            kind: "ordinary",
+            typeReference: errorTypeReference,
+            target: errorVariants[0]?.type,
+          };
+
+    return [successSplit, errorSplit];
+  } else {
+    // No splitting, just figure out if the type is an error type or not and make the other infallible.
+
+    if (isErrorModel(ctx.program, type)) {
+      const typeReference = emitTypeReference(ctx, type, type, module, {
+        altName: altBaseName + "ErrorResponse",
+      });
+
+      return [
+        DEFAULT_NO_VARIANT_SPLIT,
+        {
+          kind: "ordinary",
+          typeReference,
+          target: type,
+        },
+      ];
+    } else {
+      const typeReference = emitTypeReference(ctx, type, type, module, {
+        altName: altBaseName + "SuccessResponse",
+      });
+      return [
+        {
+          kind: "ordinary",
+          typeReference,
+          target: type,
+        },
+        DEFAULT_NO_VARIANT_SPLIT,
+      ];
+    }
+  }
+}

package/src/common/model.ts

@@ -0,0 +1,160 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import {
+  Model,
+  getFriendlyName,
+  isTemplateDeclaration,
+  isTemplateInstance,
+} from "@typespec/compiler";
+import { JsContext, Module } from "../ctx.js";
+import { isUnspeakable, parseCase } from "../util/case.js";
+import { indent } from "../util/iter.js";
+import { KEYWORDS } from "../util/keywords.js";
+import { getFullyQualifiedTypeName } from "../util/name.js";
+import { asArrayType, getArrayElementName, getRecordValueName } from "../util/pluralism.js";
+import { emitDocumentation } from "./documentation.js";
+import { emitTypeReference } from "./reference.js";
+
+/**
+ * Emit a model declaration.
+ *
+ * @param ctx - The emitter context.
+ * @param model - The model to emit.
+ * @param module - The module that this model is written into.
+ * @param altName - An alternative name to use for the model if it is not named.
+ */
+export function* emitModel(
+  ctx: JsContext,
+  model: Model,
+  module: Module,
+  altName?: string,
+): Iterable<string> {
+  const isTemplate = isTemplateInstance(model);
+  const friendlyName = getFriendlyName(ctx.program, model);
+
+  if (isTemplateDeclaration(model)) {
+    return;
+  }
+
+  const modelNameCase = parseCase(
+    friendlyName
+      ? friendlyName
+      : isTemplate
+        ? model.templateMapper!.args.map((a) => ("name" in a ? String(a.name) : "")).join("_") +
+          model.name
+        : model.name,
+  );
+
+  if (model.name === "" && !altName) {
+    throw new Error("UNREACHABLE: Anonymous model with no altName");
+  }
+
+  yield* emitDocumentation(ctx, model);
+
+  const ifaceName = model.name === "" ? altName! : modelNameCase.pascalCase;
+
+  const extendsClause = model.baseModel
+    ? `extends ${emitTypeReference(ctx, model.baseModel, model, module)} `
+    : "";
+
+  yield `export interface ${ifaceName} ${extendsClause}{`;
+
+  for (const field of model.properties.values()) {
+    // Skip properties with unspeakable names.
+    if (isUnspeakable(field.name)) {
+      continue;
+    }
+
+    const nameCase = parseCase(field.name);
+    const basicName = nameCase.camelCase;
+
+    const typeReference = emitTypeReference(ctx, field.type, field, module, {
+      altName: modelNameCase.pascalCase + nameCase.pascalCase,
+    });
+
+    const name = KEYWORDS.has(basicName) ? `_${basicName}` : basicName;
+
+    yield* indent(emitDocumentation(ctx, field));
+
+    const questionMark = field.optional ? "?" : "";
+
+    yield `  ${name}${questionMark}: ${typeReference};`;
+    yield "";
+  }
+
+  yield "}";
+  yield "";
+}
+
+export function emitModelLiteral(ctx: JsContext, model: Model, module: Module): string {
+  const properties = [...model.properties.values()]
+    .map((prop) => {
+      if (isUnspeakable(prop.name)) {
+        return undefined;
+      }
+
+      const nameCase = parseCase(prop.name);
+      const questionMark = prop.optional ? "?" : "";
+
+      const name = KEYWORDS.has(nameCase.camelCase) ? `_${nameCase.camelCase}` : nameCase.camelCase;
+
+      return `${name}${questionMark}: ${emitTypeReference(ctx, prop.type, prop, module)}`;
+    })
+    .filter((p) => !!p);
+
+  return `{ ${properties.join("; ")} }`;
+}
+
+/**
+ * Determines whether a model is an instance of a well-known model, such as TypeSpec.Record or TypeSpec.Array.
+ */
+export function isWellKnownModel(ctx: JsContext, type: Model): boolean {
+  const fullName = getFullyQualifiedTypeName(type);
+  return ["TypeSpec.Record", "TypeSpec.Array", "TypeSpec.Http.HttpPart"].includes(fullName);
+}
+
+/**
+ * Emits a well-known model, such as TypeSpec.Record or TypeSpec.Array.
+ *
+ * @param ctx - The emitter context.
+ * @param type - The model to emit.
+ * @param module - The module that this model is written into.
+ * @param preferredAlternativeName - An alternative name to use for the model if it is not named.
+ */
+export function emitWellKnownModel(
+  ctx: JsContext,
+  type: Model,
+  module: Module,
+  preferredAlternativeName?: string,
+): string {
+  switch (type.name) {
+    case "Record": {
+      const arg = type.indexer!.value;
+      return `{ [k: string]: ${emitTypeReference(ctx, arg, type, module, {
+        altName: preferredAlternativeName && getRecordValueName(preferredAlternativeName),
+      })} }`;
+    }
+    case "Array": {
+      const arg = type.indexer!.value;
+      return asArrayType(
+        emitTypeReference(ctx, arg, type, module, {
+          altName: preferredAlternativeName && getArrayElementName(preferredAlternativeName),
+        }),
+      );
+    }
+    case "HttpPart": {
+      const argument = type.templateMapper!.args[0];
+
+      if (!(argument.entityKind === "Type" && argument.kind === "Model")) {
+        throw new Error("UNREACHABLE: HttpPart must have a Model argument");
+      }
+
+      return emitTypeReference(ctx, argument, type, module, {
+        altName: preferredAlternativeName && `${preferredAlternativeName}HttpPart`,
+      });
+    }
+    default:
+      throw new Error(`UNREACHABLE: ${type.name}`);
+  }
+}

package/src/common/namespace.ts

@@ -0,0 +1,243 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Namespace, getNamespaceFullName } from "@typespec/compiler";
+import {
+  DeclarationType,
+  JsContext,
+  Module,
+  ModuleBodyDeclaration,
+  createModule,
+  isModule,
+} from "../ctx.js";
+import { parseCase } from "../util/case.js";
+import { UnimplementedError } from "../util/error.js";
+import { cat, indent, isIterable } from "../util/iter.js";
+import { OnceQueue } from "../util/once-queue.js";
+import { emitOperationGroup } from "./interface.js";
+
+/**
+ * Enqueue all declarations in the namespace to be included in the emit, recursively.
+ *
+ * @param ctx - The emitter context.
+ * @param namespace - The root namespace to begin traversing.
+ */
+export function visitAllTypes(ctx: JsContext, namespace: Namespace) {
+  const { enums, interfaces, models, unions, namespaces, scalars, operations } = namespace;
+
+  for (const type of cat<DeclarationType>(
+    enums.values(),
+    interfaces.values(),
+    models.values(),
+    unions.values(),
+    scalars.values(),
+  )) {
+    ctx.typeQueue.add(type);
+  }
+
+  for (const ns of namespaces.values()) {
+    visitAllTypes(ctx, ns);
+  }
+
+  if (operations.size > 0) {
+    // If the operation has any floating operations in it, we will synthesize an interface for them in the parent module.
+    // This requires some special handling by other parts of the emitter to ensure that the interface for a namespace's
+    // own operations is properly imported.
+    if (!namespace.namespace) {
+      throw new UnimplementedError("no parent namespace in visitAllTypes");
+    }
+
+    const parentModule = createOrGetModuleForNamespace(ctx, namespace.namespace);
+
+    parentModule.declarations.push([
+      // prettier-ignore
+      `/** An interface representing the operations defined in the '${getNamespaceFullName(namespace)}' namespace. */`,
+      `export interface ${parseCase(namespace.name).pascalCase}<Context = unknown> {`,
+      ...indent(emitOperationGroup(ctx, operations.values(), parentModule)),
+      "}",
+    ]);
+  }
+}
+
+/**
+ * Create a module for a namespace, or get an existing module if one has already been created.
+ *
+ * @param ctx - The emitter context.
+ * @param namespace - The namespace to create a module for.
+ * @returns the module for the namespace.
+ */
+export function createOrGetModuleForNamespace(
+  ctx: JsContext,
+  namespace: Namespace,
+  root: Module = ctx.globalNamespaceModule,
+): Module {
+  if (ctx.namespaceModules.has(namespace)) {
+    return ctx.namespaceModules.get(namespace)!;
+  }
+
+  if (!namespace.namespace) {
+    throw new Error("UNREACHABLE: no parent namespace in createOrGetModuleForNamespace");
+  }
+
+  const parent =
+    namespace.namespace === ctx.globalNamespace
+      ? root
+      : createOrGetModuleForNamespace(ctx, namespace.namespace);
+  const name = namespace.name === "TypeSpec" ? "typespec" : parseCase(namespace.name).kebabCase;
+
+  const module: Module = createModule(name, parent, namespace);
+
+  ctx.namespaceModules.set(namespace, module);
+
+  return module;
+}
+
+/**
+ * Get a reference to the interface representing the namespace's floating operations.
+ *
+ * This does not check that such an interface actually exists, so it should only be called in situations where it is
+ * known to exist (for example, if an operation comes from the namespace).
+ *
+ * @param ctx - The emitter context.
+ * @param namespace - The namespace to get the interface reference for.
+ * @param module - The module the the reference will be written to.
+ */
+export function emitNamespaceInterfaceReference(
+  ctx: JsContext,
+  namespace: Namespace,
+  module: Module,
+): string {
+  if (!namespace.namespace) {
+    throw new Error("UNREACHABLE: no parent namespace in emitNamespaceInterfaceReference");
+  }
+
+  const namespaceName = parseCase(namespace.name).pascalCase;
+
+  module.imports.push({
+    binder: [namespaceName],
+    from: createOrGetModuleForNamespace(ctx, namespace.namespace),
+  });
+
+  return namespaceName;
+}
+
+/**
+ * Emits a single declaration within a module. If the declaration is a module, it is enqueued for later processing.
+ *
+ * @param ctx - The emitter context.
+ * @param decl - The declaration to emit.
+ * @param queue - The queue to add the declaration to if it is a module.
+ */
+function* emitModuleBodyDeclaration(
+  ctx: JsContext,
+  decl: ModuleBodyDeclaration,
+  queue: OnceQueue<Module>,
+): Iterable<string> {
+  if (isIterable(decl)) {
+    yield* decl;
+  } else if (typeof decl === "string") {
+    yield* decl.split(/\r?\n/);
+  } else {
+    if (decl.declarations.length > 0) {
+      queue.add(decl);
+    }
+  }
+}
+
+/**
+ * Gets a file path from a given module to another module.
+ */
+function computeRelativeFilePath(from: Module, to: Module): string {
+  const fromIsIndex = from.declarations.some((d) => isModule(d));
+  const toIsIndex = to.declarations.some((d) => isModule(d));
+
+  const relativePath = (fromIsIndex ? from.cursor : from.cursor.parent!).relativePath(to.cursor);
+
+  if (relativePath.length === 0 && !toIsIndex)
+    throw new Error("UNREACHABLE: relativePath returned no fragments");
+
+  if (relativePath.length === 0) return "./index.js";
+
+  const prefix = relativePath[0] === ".." ? "" : "./";
+
+  const suffix = toIsIndex ? "/index.js" : ".js";
+
+  return prefix + relativePath.join("/") + suffix;
+}
+
+/**
+ * Deduplicates, consolidates, and writes the import statements for a module.
+ */
+function* writeImportsNormalized(ctx: JsContext, module: Module): Iterable<string> {
+  const allTargets = new Set<string>();
+  const importMap = new Map<string, Set<string>>();
+  const starAsMap = new Map<string, string>();
+  const extraStarAs: [string, string][] = [];
+
+  for (const _import of module.imports) {
+    // check for same module and continue
+    if (_import.from === module) continue;
+
+    const target =
+      typeof _import.from === "string"
+        ? _import.from
+        : computeRelativeFilePath(module, _import.from);
+
+    allTargets.add(target);
+
+    if (typeof _import.binder === "string") {
+      if (starAsMap.has(target)) {
+        extraStarAs.push([_import.binder, target]);
+      } else {
+        starAsMap.set(target, _import.binder);
+      }
+    } else {
+      const binders = importMap.get(target) ?? new Set<string>();
+      for (const binder of _import.binder) {
+        binders.add(binder);
+      }
+      importMap.set(target, binders);
+    }
+  }
+
+  for (const target of allTargets) {
+    const binders = importMap.get(target);
+    const starAs = starAsMap.get(target);
+
+    if (binders && starAs) {
+      yield `import ${starAs}, { ${[...binders].join(", ")} } from "${target}";`;
+    } else if (binders) {
+      yield `import { ${[...binders].join(", ")} } from "${target}";`;
+    } else if (starAs) {
+      yield `import ${starAs} from "${target}";`;
+    }
+
+    yield "";
+  }
+
+  for (const [binder, target] of extraStarAs) {
+    yield `import ${binder} from "${target}";`;
+  }
+}
+
+/**
+ * Emits the body of a module file.
+ *
+ * @param ctx - The emitter context.
+ * @param module - The module to emit.
+ * @param queue - The queue to add any submodules to for later processing.
+ */
+export function* emitModuleBody(
+  ctx: JsContext,
+  module: Module,
+  queue: OnceQueue<Module>,
+): Iterable<string> {
+  yield* writeImportsNormalized(ctx, module);
+
+  if (module.imports.length > 0) yield "";
+
+  for (const decl of module.declarations) {
+    yield* emitModuleBodyDeclaration(ctx, decl, queue);
+    yield "";
+  }
+}