@typespec/http-server-js 0.58.0-alpha.15-dev.0 → 0.58.0-alpha.15-dev.2

package/src/common/scalar.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation
 // Licensed under the MIT license.
 
-import { DiagnosticTarget, NoTarget, Program, Scalar } from "@typespec/compiler";
+import { DiagnosticTarget, EncodeData, NoTarget, Program, Scalar } from "@typespec/compiler";
 import { JsContext, Module } from "../ctx.js";
 import { reportDiagnostic } from "../lib.js";
 import { parseCase } from "../util/case.js";
@@ -715,11 +715,11 @@ const __JS_SCALARS_MAP = new WeakMap<Program, ScalarStore>();
 /**
  * Gets the scalar store for a given program.
  */
-function getScalarStore(ctx: JsContext, module: Module): ScalarStore {
+function getScalarStore(ctx: JsContext): ScalarStore {
   let scalars = __JS_SCALARS_MAP.get(ctx.program);
 
   if (scalars === undefined) {
-    scalars = createScalarStore(ctx, module);
+    scalars = createScalarStore(ctx);
     __JS_SCALARS_MAP.set(ctx.program, scalars);
   }
 
@@ -729,7 +729,7 @@ function getScalarStore(ctx: JsContext, module: Module): ScalarStore {
 /**
  * Initializes a scalar store for a given program.
  */
-function createScalarStore(ctx: JsContext, module: Module): ScalarStore {
+function createScalarStore(ctx: JsContext): ScalarStore {
   const m = new Map<Scalar, Contextualized<JsScalar>>();
 
   for (const [scalarName, scalarInfo] of SCALARS) {
@@ -773,7 +773,17 @@ function createJsScalar(
 
       scalar,
 
-      getEncoding(encoding: string, target: Scalar): Encoder | undefined {
+      getEncoding(encodeDataOrString: EncodeData | string, target?: Scalar): Encoder | undefined {
+        let encoding: string = "default";
+
+        if (typeof encodeDataOrString === "string") {
+          encoding = encodeDataOrString;
+          target = target!;
+        } else {
+          encoding = encodeDataOrString.encoding ?? "default";
+          target = encodeDataOrString.type;
+        }
+
         const encodingTable = scalarInfo.encodings?.[getFullyQualifiedTypeName(target)];
         let encodingSpec = encodingTable?.[encoding] ?? encodingTable?.[encoding.toLowerCase()];
 
@@ -1034,6 +1044,7 @@ export interface JsScalar {
    * 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.
@@ -1128,7 +1139,7 @@ export function getJsScalar(
   scalar: Scalar,
   diagnosticTarget: DiagnosticTarget | typeof NoTarget,
 ): JsScalar {
-  const scalars = getScalarStore(ctx, module);
+  const scalars = getScalarStore(ctx);
 
   let _scalar: Scalar | undefined = scalar;
 

package/src/common/union.ts

@@ -25,13 +25,6 @@ export function emitUnionType(ctx: JsContext, variants: UnionVariant[], module:
     const name = emitTypeReference(ctx, v.type, v, module);
 
     variantTypes.push(name);
-
-    // if (isImportableType(ctx, v.type)) {
-    //   module.imports.push({
-    //     binder: [name],
-    //     from: createOrGetModuleForNamespace(ctx, v.type.namespace!),
-    //   });
-    // }
   }
 
   return variantTypes.join(" | ");
@@ -72,5 +65,5 @@ export function* emitUnion(
     }),
   );
 
-  yield `export type ${name} = ${variantTypes.join(" | ")};`;
+  yield `export type ${name} = ${variantTypes.length === 0 ? "never" : variantTypes.join(" | ")};`;
 }

package/src/ctx.ts

@@ -27,6 +27,8 @@ import { parseCase } from "./util/case.js";
 import { UnimplementedError } from "./util/error.js";
 import { createOnceQueue, OnceQueue } from "./util/once-queue.js";
 
+import { unsafe_Mutator } from "@typespec/compiler/experimental";
+import { MetadataInfo } from "@typespec/http";
 import { createModule as initializeHelperModule } from "../generated-defs/helpers/index.js";
 
 export type DeclarationType = Model | Enum | Union | Interface | Scalar;
@@ -135,6 +137,10 @@ export interface JsContext {
   serializations: OnceQueue<SerializableType>;
 
   gensym: (name: string) => string;
+
+  metadataInfo?: MetadataInfo;
+
+  canonicalizationCache: { [vfKey: string]: unsafe_Mutator | undefined };
 }
 
 export async function createInitialContext(
@@ -211,6 +217,8 @@ export async function createInitialContext(
     gensym: (name) => {
       return gensym(jsCtx, name);
     },
+
+    canonicalizationCache: {},
   };
 
   return jsCtx;
@@ -359,6 +367,20 @@ export interface Import {
   from: Module | string;
 }
 
+/**
+ * A module that does not exist and is not emitted. Use this for functions that require a module but you only
+ * want to analyze the type and not emit any relative paths.
+ *
+ * For example, this is used internally to canonicalize operation types, because it calls some functions that
+ * require a module, but canonicalizing the operation does not itself emit any code.
+ */
+export const NoModule: Module = {
+  name: "",
+  cursor: createPathCursor(),
+  imports: [],
+  declarations: [],
+};
+
 /**
  * An output module within the module tree.
  */

package/src/http/operation.ts

@@ -0,0 +1,340 @@
+import {
+  getParameterVisibilityFilter,
+  getReturnTypeVisibilityFilter,
+  isVisible,
+  Model,
+  ModelProperty,
+  Operation,
+  Program,
+  Tuple,
+  Type,
+  Union,
+  UnionVariant,
+  VisibilityFilter,
+} from "@typespec/compiler";
+import {
+  unsafe_mutateSubgraph as mutateSubgraph,
+  unsafe_Mutator as Mutator,
+  unsafe_MutatorFlow as MutatorFlow,
+} from "@typespec/compiler/experimental";
+import { $ } from "@typespec/compiler/typekit";
+import { useStateMap } from "@typespec/compiler/utils";
+import {
+  createMetadataInfo,
+  getHttpOperation,
+  getVisibilitySuffix,
+  HttpVisibilityProvider,
+  isApplicableMetadataOrBody,
+  resolveRequestVisibility,
+  Visibility,
+} from "@typespec/http";
+import { JsContext, NoModule } from "../ctx.js";
+import { createStateSymbol } from "../lib.js";
+import { resolveEncodingChain } from "../util/encoding.js";
+
+const CANONICAL_VISIBILITY = Visibility.Read;
+
+const [getCachedCanonicalOperation, setCachedCanonicalOperation] = useStateMap<
+  Operation,
+  Operation
+>(createStateSymbol("CanonicalOperationCache"));
+
+/**
+ * Gets the 'canonicalized' version of an operation.
+ *
+ * This is the version of the operation that is accurate to `@typespec/http` interpretation of the
+ * operation.
+ *
+ * - Implicit visibility is applied to the parameters and return type according to the HTTP verb.
+ * - Properties and scalars that have unrecognized encoding chains are replaced by their lowest recognized
+ *   logical type.
+ *
+ * @param ctx
+ * @param operation
+ * @returns
+ */
+export function canonicalizeHttpOperation(ctx: JsContext, operation: Operation): Operation {
+  let canonical = getCachedCanonicalOperation(ctx.program, operation);
+
+  if (canonical) return canonical;
+
+  const metadataInfo = (ctx.metadataInfo ??= createMetadataInfo(ctx.program, {
+    canonicalVisibility: CANONICAL_VISIBILITY,
+  }));
+
+  canonical = _canonicalizeHttpOperation();
+
+  setCachedCanonicalOperation(ctx.program, operation, canonical);
+
+  return canonical;
+
+  function _canonicalizeHttpOperation(): Operation {
+    const [httpOperation] = getHttpOperation(ctx.program, operation);
+
+    const httpVisibilityProvider = HttpVisibilityProvider();
+
+    const parameterVisibilityFilter = getParameterVisibilityFilter(
+      ctx.program,
+      operation,
+      httpVisibilityProvider,
+    );
+
+    const httpParameterVisibility = resolveRequestVisibility(
+      ctx.program,
+      operation,
+      httpOperation.verb,
+    );
+
+    const parameterMutator = bindMutator(httpParameterVisibility, parameterVisibilityFilter);
+
+    const mutatedParameters = cachedMutateSubgraph(
+      ctx.program,
+      parameterMutator,
+      operation.parameters,
+    ).type as Model;
+
+    const returnTypeVisibilityFilter = getReturnTypeVisibilityFilter(
+      ctx.program,
+      operation,
+      httpVisibilityProvider,
+    );
+
+    // For return types, the visibility is always Visibility.Read, but we could have a
+    // custom returnTypeVisibilityFilter that is more restrictive. We will always use
+    // Visibility.Read as the HTTP visibility for suffixing and metadataInfo tests, but
+    // still check visibility based on the configured filter.
+    const returnTypeMutator = bindMutator(Visibility.Read, returnTypeVisibilityFilter);
+
+    const mutatedReturnType = isCanonicalizationSubject(operation.returnType)
+      ? cachedMutateSubgraph(ctx.program, returnTypeMutator, operation.returnType).type
+      : operation.returnType;
+
+    const clonedOperation = $(ctx.program).type.clone(operation);
+
+    clonedOperation.parameters = mutatedParameters;
+    clonedOperation.returnType = mutatedReturnType;
+
+    $(ctx.program).type.finishType(clonedOperation);
+
+    return clonedOperation;
+  }
+
+  function bindMutator(httpVisibility: Visibility, visibilityFilter: VisibilityFilter): Mutator {
+    const cacheKey =
+      String(httpVisibility) + "--" + VisibilityFilter.toCacheKey(ctx.program, visibilityFilter);
+
+    const cached = ctx.canonicalizationCache[cacheKey];
+
+    if (cached) return cached;
+
+    const visibilitySuffix = getVisibilitySuffix(httpVisibility, CANONICAL_VISIBILITY);
+
+    const primaryMutator: Mutator = {
+      name: "CanonicalizeHttpOperation",
+      Model: {
+        filter: () => MutatorFlow.DoNotRecur,
+        replace: (model, clone, program, realm) => {
+          let modified = false;
+
+          const indexer = model.indexer;
+
+          if (indexer) {
+            if ($(realm).array.is(model)) {
+              // Array items have a bit of a special visibility concern
+
+              const { type: mutated } = isCanonicalizationSubject(indexer.value)
+                ? cachedMutateSubgraph(program, arrayItemMutator, indexer.value)
+                : { type: indexer.value };
+
+              clone.indexer = { key: indexer.key, value: mutated };
+            } else {
+              const { type: mutated } = isCanonicalizationSubject(indexer.value)
+                ? cachedMutateSubgraph(program, primaryMutator, indexer.value)
+                : { type: indexer.value };
+
+              clone.indexer = { key: indexer.key, value: mutated };
+            }
+
+            modified ||= indexer.value !== clone.indexer.value;
+          }
+
+          for (const [name, property] of model.properties) {
+            if (isVisible(program, property, visibilityFilter)) {
+              const mutated = cachedMutateSubgraph(program, mpMutator, property)
+                .type as ModelProperty;
+
+              clone.properties.set(name, mutated);
+
+              modified ||= property.type !== mutated.type;
+            } else {
+              clone.properties.delete(name);
+              realm.remove(property);
+              modified = true;
+            }
+          }
+
+          if (clone.name) clone.name = clone.name + visibilitySuffix;
+
+          return modified ? clone : model;
+        },
+      },
+      Union: {
+        filter: () => MutatorFlow.DoNotRecur,
+        replace: (union, clone, program, realm) => {
+          let modified = false;
+          for (const [name, variant] of union.variants) {
+            const { type: mutated } = isCanonicalizationSubject(variant.type)
+              ? cachedMutateSubgraph(program, primaryMutator, variant.type)
+              : variant;
+
+            clone.variants.set(
+              name,
+              $(realm).unionVariant.create({
+                name: variant.name,
+                type: mutated,
+                union: clone,
+              }),
+            );
+
+            modified ||= variant.type !== mutated;
+          }
+
+          if (clone.name) clone.name = clone.name + visibilitySuffix;
+
+          return modified ? clone : union;
+        },
+      },
+      ModelProperty: {
+        filter: () => MutatorFlow.DoNotRecur,
+        replace: (modelProperty, clone, program, realm) => {
+          // Passthrough -- but with encoding decay.
+          const encoders = resolveEncodingChain(ctx, NoModule, modelProperty, modelProperty.type);
+
+          if (encoders.canonicalType !== modelProperty.type) {
+            return encoders.canonicalType;
+          } else {
+            return modelProperty;
+          }
+        },
+      },
+      UnionVariant: {
+        filter: () => MutatorFlow.DoNotRecur,
+        replace: (variant, clone, program, realm) => {
+          const { type: mutated } = isCanonicalizationSubject(variant.type)
+            ? cachedMutateSubgraph(program, primaryMutator, variant.type)
+            : variant;
+
+          clone.type = mutated;
+
+          return mutated !== variant.type ? clone : variant;
+        },
+      },
+      Tuple: {
+        filter: () => MutatorFlow.DoNotRecur,
+        replace: (tuple, clone, program, realm) => {
+          let modified = false;
+          clone.values = [...tuple.values];
+          for (const [idx, value] of tuple.values.map((v, idx) => [idx, v] as const)) {
+            const { type: mutated } = isCanonicalizationSubject(value)
+              ? cachedMutateSubgraph(program, primaryMutator, value)
+              : { type: value };
+
+            clone.values[idx] = mutated;
+
+            modified ||= value !== mutated;
+          }
+
+          return modified ? clone : tuple;
+        },
+      },
+      Scalar: {
+        filter: () => MutatorFlow.DoNotRecur,
+        replace: (scalar, clone, program, realm) => {
+          // Passthrough -- but with encoding decay.
+          const encoders = resolveEncodingChain(ctx, NoModule, scalar, scalar);
+
+          return encoders.canonicalType;
+        },
+      },
+    };
+
+    const arrayItemMutator =
+      httpVisibility & Visibility.Item
+        ? primaryMutator
+        : bindMutator(httpVisibility | Visibility.Item, visibilityFilter);
+
+    const mpMutator: Mutator = {
+      name: primaryMutator.name + "ModelProperty",
+      ModelProperty: {
+        filter: () => MutatorFlow.DoNotRecur,
+        replace: (modelProperty, clone, program, realm) => {
+          let modified = false;
+          const { type: originalCanonicalType } = isCanonicalizationSubject(modelProperty.type)
+            ? cachedMutateSubgraph(ctx.program, primaryMutator, modelProperty.type)
+            : { type: modelProperty.type };
+
+          const encodingChain = resolveEncodingChain(
+            ctx,
+            NoModule,
+            modelProperty,
+            originalCanonicalType,
+          );
+
+          clone.type = encodingChain.canonicalType;
+
+          modified ||= modelProperty.type !== clone.type;
+
+          if (
+            metadataInfo.isPayloadProperty(modelProperty, httpVisibility) &&
+            !isApplicableMetadataOrBody(ctx.program, modelProperty, httpVisibility) &&
+            metadataInfo.isOptional(modelProperty, httpVisibility)
+          ) {
+            clone.optional = true;
+            modified ||= !modelProperty.optional;
+          }
+
+          return modified ? clone : modelProperty;
+        },
+      },
+    };
+
+    return (ctx.canonicalizationCache[cacheKey] = primaryMutator);
+  }
+}
+
+type CanonicalizationSubject = Model | Union | ModelProperty | UnionVariant | Tuple;
+
+function isCanonicalizationSubject(t: Type): t is CanonicalizationSubject {
+  return (
+    t.kind === "Model" ||
+    t.kind === "Union" ||
+    t.kind === "ModelProperty" ||
+    t.kind === "UnionVariant" ||
+    t.kind === "Tuple" ||
+    t.kind === "Scalar"
+  );
+}
+
+const MUTATOR_RESULT = Symbol.for("TypeSpec.HttpServerJs.MutatorResult");
+
+interface MutatorResultCache {
+  [MUTATOR_RESULT]: WeakMap<CanonicalizationSubject, ReturnType<typeof mutateSubgraph>>;
+}
+
+function cachedMutateSubgraph(
+  program: Program,
+  mutator: Mutator,
+  type: CanonicalizationSubject,
+): ReturnType<typeof mutateSubgraph> {
+  const cache = ((mutator as unknown as MutatorResultCache)[MUTATOR_RESULT] ??= new WeakMap());
+
+  let cached = cache.get(type);
+
+  if (cached) return cached;
+
+  cached = mutateSubgraph(program, [mutator], type);
+
+  cache.set(type, cached);
+
+  return cached;
+}

package/src/http/server/index.ts

@@ -14,6 +14,7 @@ import {
   HttpOperation,
   HttpOperationParameter,
   getHeaderFieldName,
+  getHttpOperation,
   isBody,
   isHeader,
   isStatusCode,
@@ -46,6 +47,7 @@ import {
   transposeExpressionFromJson,
 } from "../../common/serialization/json.js";
 import { getFullyQualifiedTypeName } from "../../util/name.js";
+import { canonicalizeHttpOperation } from "../operation.js";
 
 const DEFAULT_CONTENT_TYPE = "application/json";
 
@@ -96,12 +98,15 @@ function* emitRawServerOperation(
   module: Module,
   responderNames: Pick<Names, "isHttpResponder" | "httpResponderSym">,
 ): Iterable<string> {
-  const op = operation.operation;
+  let op = operation.operation;
   const operationNameCase = parseCase(op.name);
 
   const container = op.interface ?? op.namespace!;
   const containerNameCase = parseCase(container.name);
 
+  op = canonicalizeHttpOperation(ctx, op);
+  [operation] = getHttpOperation(ctx.program, op);
+
   module.imports.push({
     binder: [containerNameCase.pascalCase],
     from: createOrGetModuleForNamespace(ctx, container.namespace!),

package/src/http/server/router.ts

@@ -8,6 +8,7 @@ import {
   HttpVerb,
   OperationContainer,
   getHeaderFieldName,
+  getHttpOperation,
   isHeader,
 } from "@typespec/http";
 import {
@@ -24,6 +25,7 @@ import { HttpContext } from "../index.js";
 import { module as headerHelpers } from "../../../generated-defs/helpers/header.js";
 import { module as routerHelper } from "../../../generated-defs/helpers/router.js";
 import { differentiateModelTypes, writeCodeTree } from "../../util/differentiate.js";
+import { canonicalizeHttpOperation } from "../operation.js";
 
 /**
  * Emit a router for the HTTP operations defined in a given service.
@@ -484,11 +486,13 @@ interface RouteParameter {
 function createRouteTree(ctx: HttpContext, service: HttpService): RouteTree {
   // First get the Route for each operation in the service.
   const routes = service.operations.map(function (operation) {
-    const segments = getRouteSegments(ctx, operation);
+    const canonicalOperation = canonicalizeHttpOperation(ctx, operation.operation);
+    const [httpOperation] = getHttpOperation(ctx.program, canonicalOperation);
+    const segments = getRouteSegments(ctx, httpOperation);
     return {
-      operation: operation.operation,
+      operation: canonicalOperation,
       container: operation.container,
-      verb: operation.verb,
+      verb: httpOperation.verb,
       parameters: segments.filter((segment) => typeof segment !== "string"),
       segments,
     } as Route;

package/src/lib.ts

@@ -174,6 +174,6 @@ export const $lib = createTypeSpecLibrary({
   },
 });
 
-const { reportDiagnostic } = $lib;
+const { reportDiagnostic, createStateSymbol } = $lib;
 
-export { reportDiagnostic };
+export { createStateSymbol, reportDiagnostic };

package/src/scripts/scaffold/bin.mts

@@ -28,6 +28,7 @@ import { module as httpHelperModule } from "../../../generated-defs/helpers/http
 import { module as routerModule } from "../../../generated-defs/helpers/router.js";
 import { emitOptionsType } from "../../common/interface.js";
 import { emitTypeReference, isValueLiteralType } from "../../common/reference.js";
+import { canonicalizeHttpOperation } from "../../http/operation.js";
 import { JsEmitterOptions } from "../../lib.js";
 import { getAllProperties } from "../../util/extends.js";
 import { bifilter, indent } from "../../util/iter.js";
@@ -609,8 +610,9 @@ function getAllExternalDependencies(ctx: JsContext): Set<string> {
     for (const _import of module.imports) {
       if (
         typeof _import.from === "string" &&
-        !_import.from.startsWith(".") &&
-        !_import.from.startsWith("/")
+        !_import.from.startsWith(".") && // is a relative path
+        !_import.from.startsWith("/") && // is an absolute path
+        !_import.from.startsWith("node:") // is node builtin
       ) {
         externalDependencies.add(_import.from);
       } else if (typeof _import.from !== "string") {
@@ -700,7 +702,7 @@ function* emitControllerOperationHandlers(
   let importNotImplementedError = false;
   for (const httpOperation of httpOperations) {
     // TODO: unify construction of signature with emitOperation in common/interface.ts
-    const op = httpOperation.operation;
+    const op = canonicalizeHttpOperation(ctx, httpOperation.operation);
 
     const opNameCase = parseCase(op.name);
 

package/src/util/encoding.ts

@@ -0,0 +1,87 @@
+import { getEncode, ModelProperty, Scalar, Type } from "@typespec/compiler";
+import { Encoder, getJsScalar } from "../common/scalar.js";
+import { JsContext, Module } from "../ctx.js";
+
+/**
+ * A resolved encoding chain for a model property or scalar.
+ */
+export interface ResolvedEncodingChain {
+  /**
+   * The canonical type of the property -- a.k.a. the logical type that the service implementor will use.
+   */
+  canonicalType: Type;
+  /**
+   * The ultimate encoding target. This will always be the same as the `.type` of the last encoder in the chain, or
+   * the same as the canonical type if there are no encoders.
+   */
+  targetType: Type;
+  /**
+   * The chain of encoders tht apply to the canonical type. These are applied in order front-to-back to encode the
+   * canonical type into the target type, and are applied back-to-front to decode the canonical type from the target type.
+   */
+  encoders: Encoder[];
+}
+
+const ENCODE_SOURCES: { [k in "ModelProperty" | "Scalar"]: (t: ModelProperty | Scalar) => Type } = {
+  ModelProperty: (t) => (t as ModelProperty).type,
+  Scalar: (t) => t,
+};
+
+/**
+ * Resolves the chain of `@encode` encoders that apply to a given property with a given canonical (logical) type.
+ *
+ * @param ctx - The context to use for resolving encoders.
+ * @param module - The module that the property is defined in.
+ * @param encodeSource - The original property to resolve encoders for.
+ * @param canonicalType - The canonical type of the property -- this might be different from the type of the property itself.
+ * @returns A resolved encoding chain describing the final canonical type, the ultimate target type of the chain, and the encoders that apply to the property in order.
+ */
+export function resolveEncodingChain(
+  ctx: JsContext,
+  module: Module,
+  encodeSource: ModelProperty | Scalar,
+  canonicalType: Type,
+): ResolvedEncodingChain {
+  let encoders: Encoder[] = [];
+  let targetType: Type = canonicalType;
+
+  for (const [kind, select] of Object.entries(ENCODE_SOURCES)) {
+    while (encodeSource.kind === kind) {
+      const s = select(encodeSource);
+      const encoding = getEncode(ctx.program, encodeSource);
+
+      if (!encoding) break;
+
+      targetType = encodeSource = encoding.type;
+
+      if (s.kind !== "Scalar") {
+        // Decay because we don't know how to encode anything other than a scalar.
+        // Should be unreachable?
+        decay(encoding.type);
+      } else {
+        const sourceJsScalar = getJsScalar(ctx, module, s, encodeSource);
+
+        const encoder = sourceJsScalar.getEncoding(encoding);
+
+        if (encoder) {
+          encoders.push(encoder);
+        } else {
+          // Decay because we don't know what the encoding is.
+          // Invalidate the entire chain and set the current encoding.type as the canonical type.
+          decay(encoding.type);
+        }
+      }
+    }
+  }
+
+  return {
+    canonicalType,
+    targetType,
+    encoders,
+  };
+
+  function decay(t: ModelProperty | Scalar) {
+    encoders = [];
+    canonicalType = encodeSource = t;
+  }
+}