@typespec/http-server-js 0.58.0-alpha.12-dev.0 → 0.58.0-alpha.12-dev.1

package/src/common/serialization/index.ts

@@ -55,9 +55,15 @@ export function emitSerialization(ctx: JsContext): void {
     const serializations = _SERIALIZATIONS_MAP.get(type)!;
 
     const requiredSerializations = new Set<SerializationContentType>(
-      [...serializations].filter((serialization) =>
-        isSerializationRequired(ctx, type, serialization),
-      ),
+      [...serializations].filter((serialization) => {
+        const isSynthetic = ctx.syntheticNames.has(type) || !type.namespace;
+
+        const module = isSynthetic
+          ? ctx.syntheticModule
+          : createOrGetModuleForNamespace(ctx, type.namespace!);
+
+        return isSerializationRequired(ctx, module, type, serialization);
+      }),
     );
 
     if (requiredSerializations.size > 0) {
@@ -68,12 +74,13 @@ export function emitSerialization(ctx: JsContext): void {
 
 export function isSerializationRequired(
   ctx: JsContext,
+  module: Module,
   type: Type,
   serialization: SerializationContentType,
 ): boolean {
   switch (serialization) {
     case "application/json": {
-      return requiresJsonSerialization(ctx, type);
+      return requiresJsonSerialization(ctx, module, type);
     }
     default:
       throw new Error(`Unreachable: serialization content type ${serialization satisfies never}`);

package/src/common/serialization/json.ts

@@ -3,10 +3,12 @@
 
 import {
   BooleanLiteral,
+  DiagnosticTarget,
   IntrinsicType,
   ModelProperty,
   NoTarget,
   NumericLiteral,
+  Scalar,
   StringLiteral,
   Type,
   compilerAssert,
@@ -17,12 +19,15 @@ import {
 } from "@typespec/compiler";
 import { getHeaderFieldOptions, getPathParamOptions, getQueryParamOptions } from "@typespec/http";
 import { JsContext, Module } from "../../ctx.js";
-import { parseCase } from "../../util/case.js";
+import { reportDiagnostic } from "../../lib.js";
+import { access, parseCase } from "../../util/case.js";
 import { differentiateUnion, writeCodeTree } from "../../util/differentiate.js";
 import { UnimplementedError } from "../../util/error.js";
 import { indent } from "../../util/iter.js";
+import { keywordSafe } from "../../util/keywords.js";
+import { getFullyQualifiedTypeName } from "../../util/name.js";
 import { emitTypeReference, escapeUnsafeChars } from "../reference.js";
-import { getJsScalar } from "../scalar.js";
+import { Encoder, JS_SCALAR_UNKNOWN, JsScalar, getJsScalar } from "../scalar.js";
 import { SerializableType, SerializationContext, requireSerialization } from "./index.js";
 
 /**
@@ -30,7 +35,12 @@ import { SerializableType, SerializationContext, requireSerialization } from "./
  */
 const _REQUIRES_JSON_SERIALIZATION = new WeakMap<SerializableType | ModelProperty, boolean>();
 
-export function requiresJsonSerialization(ctx: JsContext, type: Type): boolean {
+export function requiresJsonSerialization(
+  ctx: JsContext,
+  module: Module,
+  type: Type,
+  diagnosticTarget: DiagnosticTarget | typeof NoTarget = NoTarget,
+): boolean {
   if (!isSerializable(type)) return false;
 
   if (_REQUIRES_JSON_SERIALIZATION.has(type)) {
@@ -48,28 +58,31 @@ export function requiresJsonSerialization(ctx: JsContext, type: Type): boolean {
     case "Model": {
       if (isArrayModelType(ctx.program, type)) {
         const argumentType = type.indexer.value;
-        requiresSerialization = requiresJsonSerialization(ctx, argumentType);
+        requiresSerialization = requiresJsonSerialization(ctx, module, argumentType);
         break;
       }
 
       requiresSerialization = [...type.properties.values()].some((property) =>
-        propertyRequiresJsonSerialization(ctx, property),
+        propertyRequiresJsonSerialization(ctx, module, property),
       );
       break;
     }
     case "Scalar": {
-      const scalar = getJsScalar(ctx.program, type, type);
-      requiresSerialization = scalar === "Uint8Array" || getEncode(ctx.program, type) !== undefined;
+      const scalar = getJsScalar(ctx, module, type, diagnosticTarget);
+      requiresSerialization =
+        !scalar.isJsonCompatible ||
+        getEncode(ctx.program, type) !== undefined ||
+        scalar.getDefaultMimeEncoding("application/json") !== undefined;
       break;
     }
     case "Union": {
       requiresSerialization = [...type.variants.values()].some((variant) =>
-        requiresJsonSerialization(ctx, variant),
+        requiresJsonSerialization(ctx, module, variant),
       );
       break;
     }
     case "ModelProperty":
-      requiresSerialization = requiresJsonSerialization(ctx, type.type);
+      requiresSerialization = requiresJsonSerialization(ctx, module, type.type);
       break;
   }
 
@@ -78,12 +91,17 @@ export function requiresJsonSerialization(ctx: JsContext, type: Type): boolean {
   return requiresSerialization;
 }
 
-function propertyRequiresJsonSerialization(ctx: JsContext, property: ModelProperty): boolean {
+function propertyRequiresJsonSerialization(
+  ctx: JsContext,
+  module: Module,
+  property: ModelProperty,
+): boolean {
   return !!(
     isHttpMetadata(ctx, property) ||
     getEncode(ctx.program, property) ||
     resolveEncodedName(ctx.program, property, "application/json") !== property.name ||
-    (isSerializable(property.type) && requiresJsonSerialization(ctx, property.type))
+    (isSerializable(property.type) &&
+      requiresJsonSerialization(ctx, module, property.type, property))
   );
 }
 
@@ -132,12 +150,40 @@ function* emitToJson(
         const encodedName =
           resolveEncodedName(ctx.program, property, "application/json") ?? property.name;
 
-        const expr = transposeExpressionToJson(
-          ctx,
-          property.type,
-          `input.${property.name}`,
-          module,
-        );
+        const propertyName = keywordSafe(parseCase(property.name).camelCase);
+
+        let expr: string = access("input", propertyName);
+
+        const encoding = getEncode(ctx.program, property);
+
+        if (property.type.kind === "Scalar" && encoding) {
+          const scalar = getJsScalar(ctx, module, property.type, property.type);
+          const scalarEncoder = scalar.getEncoding(encoding.encoding ?? "default", encoding.type);
+
+          if (scalarEncoder) {
+            expr = transposeExpressionToJson(
+              ctx,
+              // Assertion: scalarEncoder.target.scalar is defined because we resolved an encoder.
+              scalarEncoder.target.scalar as Scalar,
+              scalarEncoder.encode(expr),
+              module,
+            );
+          } else {
+            reportDiagnostic(ctx.program, {
+              code: "unknown-encoding",
+              target: NoTarget,
+              format: {
+                encoding: encoding.encoding ?? "<default>",
+                type: getFullyQualifiedTypeName(property.type),
+                target: getFullyQualifiedTypeName(encoding.type),
+              },
+            });
+
+            // We treat this as unknown from here on out. The encoding was not deciphered.
+          }
+        } else {
+          expr = transposeExpressionToJson(ctx, property.type, expr, module);
+        }
 
         yield `  ${encodedName}: ${expr},`;
       }
@@ -151,12 +197,12 @@ function* emitToJson(
       return;
     }
     case "Union": {
-      const codeTree = differentiateUnion(ctx, type);
+      const codeTree = differentiateUnion(ctx, module, type);
 
       yield* writeCodeTree(ctx, codeTree, {
         subject: "input",
         referenceModelProperty(p) {
-          return "input." + parseCase(p.name).camelCase;
+          return access("input", parseCase(p.name).camelCase);
         },
         renderResult(type) {
           return [`return ${transposeExpressionToJson(ctx, type, "input", module)};`];
@@ -179,15 +225,15 @@ function transposeExpressionToJson(
       if (isArrayModelType(ctx.program, type)) {
         const argumentType = type.indexer.value;
 
-        if (requiresJsonSerialization(ctx, argumentType)) {
-          return `${expr}?.map((item) => ${transposeExpressionToJson(ctx, argumentType, "item", module)})`;
+        if (requiresJsonSerialization(ctx, module, argumentType)) {
+          return `(${expr})?.map((item) => ${transposeExpressionToJson(ctx, argumentType, "item", module)})`;
         } else {
           return expr;
         }
       } else if (isRecordModelType(ctx.program, type)) {
         const argumentType = type.indexer.value;
 
-        if (requiresJsonSerialization(ctx, argumentType)) {
+        if (requiresJsonSerialization(ctx, module, argumentType)) {
           return `Object.fromEntries(Object.entries(${expr}).map(([key, value]) => [String(key), ${transposeExpressionToJson(
             ctx,
             argumentType,
@@ -197,7 +243,7 @@ function transposeExpressionToJson(
         } else {
           return expr;
         }
-      } else if (!requiresJsonSerialization(ctx, type)) {
+      } else if (!requiresJsonSerialization(ctx, module, type)) {
         return expr;
       } else {
         requireSerialization(ctx, type, "application/json");
@@ -207,18 +253,20 @@ function transposeExpressionToJson(
       }
     }
     case "Scalar":
-      const scalar = getJsScalar(ctx.program, type, type);
+      const scalar = getJsScalar(ctx, module, type, NoTarget);
 
-      switch (scalar) {
-        case "Uint8Array":
-          // Coerce to Buffer if we aren't given a buffer. This avoids having to do unholy things to
-          // convert through an intermediate and use globalThis.btoa. v8 does not support Uint8Array.toBase64
-          return `((${expr} instanceof Buffer) ? ${expr} : Buffer.from(${expr})).toString('base64')`;
-        default:
-          return expr;
+      const encoder: Encoder = getScalarEncoder(ctx, type, scalar);
+
+      const encoded = encoder.encode(expr);
+
+      if (encoder.target.isJsonCompatible || !encoder.target.scalar) {
+        return encoded;
+      } else {
+        // Assertion: encoder.target.scalar is a scalar because "unknown" is JSON compatible.
+        return transposeExpressionToJson(ctx, encoder.target.scalar as Scalar, encoded, module);
       }
     case "Union":
-      if (!requiresJsonSerialization(ctx, type)) {
+      if (!requiresJsonSerialization(ctx, module, type)) {
         return expr;
       } else {
         requireSerialization(ctx, type, "application/json");
@@ -269,6 +317,48 @@ function transposeExpressionToJson(
   }
 }
 
+function getScalarEncoder(ctx: SerializationContext, type: Scalar, scalar: JsScalar) {
+  const encoding = getEncode(ctx.program, type);
+
+  let encoder: Encoder;
+
+  if (encoding) {
+    const encodingName = encoding.encoding ?? "default";
+    const scalarEncoder = scalar.getEncoding(encodingName, encoding.type);
+
+    // TODO - we should detect this before realizing models and use a transform to represent
+    // the defective scalar as the encoding target type.
+    // See: https://github.com/microsoft/typespec/issues/6376
+    if (!scalarEncoder) {
+      reportDiagnostic(ctx.program, {
+        code: "unknown-encoding",
+        target: NoTarget,
+        format: {
+          encoding: encoding.encoding ?? "<default>",
+          type: getFullyQualifiedTypeName(type),
+          target: getFullyQualifiedTypeName(encoding.type),
+        },
+      });
+
+      encoder = {
+        target: JS_SCALAR_UNKNOWN,
+        encode: (expr) => expr,
+        decode: (expr) => expr,
+      };
+    } else {
+      encoder = scalarEncoder;
+    }
+  } else {
+    // No encoding specified, use the default content type encoding for json
+    encoder = scalar.getDefaultMimeEncoding("application/json") ?? {
+      target: JS_SCALAR_UNKNOWN,
+      encode: (expr) => expr,
+      decode: (expr) => expr,
+    };
+  }
+  return encoder;
+}
+
 function literalToExpr(type: StringLiteral | BooleanLiteral | NumericLiteral): string {
   switch (type.kind) {
     case "String":
@@ -292,14 +382,42 @@ function* emitFromJson(
         const encodedName =
           resolveEncodedName(ctx.program, property, "application/json") ?? property.name;
 
-        const expr = transposeExpressionFromJson(
-          ctx,
-          property.type,
-          `input["${encodedName}"]`,
-          module,
-        );
+        let expr = access("input", encodedName);
+
+        const encoding = getEncode(ctx.program, property);
+
+        if (property.type.kind === "Scalar" && encoding) {
+          const scalar = getJsScalar(ctx, module, property.type, property.type);
+          const scalarEncoder = scalar.getEncoding(encoding.encoding ?? "default", encoding.type);
+
+          if (scalarEncoder) {
+            expr = transposeExpressionFromJson(
+              ctx,
+              // Assertion: scalarEncoder.target.scalar is defined because we resolved an encoder.
+              scalarEncoder.target.scalar as Scalar,
+              scalarEncoder.decode(expr),
+              module,
+            );
+          } else {
+            reportDiagnostic(ctx.program, {
+              code: "unknown-encoding",
+              target: NoTarget,
+              format: {
+                encoding: encoding.encoding ?? "<default>",
+                type: getFullyQualifiedTypeName(property.type),
+                target: getFullyQualifiedTypeName(encoding.type),
+              },
+            });
+
+            // We treat this as unknown from here on out. The encoding was not deciphered.
+          }
+        } else {
+          expr = transposeExpressionFromJson(ctx, property.type, expr, module);
+        }
+
+        const propertyName = keywordSafe(parseCase(property.name).camelCase);
 
-        yield `  ${property.name}: ${expr},`;
+        yield `  ${propertyName}: ${expr},`;
       }
 
       yield "};";
@@ -311,13 +429,13 @@ function* emitFromJson(
       return;
     }
     case "Union": {
-      const codeTree = differentiateUnion(ctx, type);
+      const codeTree = differentiateUnion(ctx, module, type);
 
       yield* writeCodeTree(ctx, codeTree, {
         subject: "input",
         referenceModelProperty(p) {
           const jsonName = resolveEncodedName(ctx.program, p, "application/json") ?? p.name;
-          return "input[" + JSON.stringify(jsonName) + "]";
+          return access("input", jsonName);
         },
         renderResult(type) {
           return [`return ${transposeExpressionFromJson(ctx, type, "input", module)};`];
@@ -340,15 +458,15 @@ function transposeExpressionFromJson(
       if (isArrayModelType(ctx.program, type)) {
         const argumentType = type.indexer.value;
 
-        if (requiresJsonSerialization(ctx, argumentType)) {
-          return `${expr}?.map((item: any) => ${transposeExpressionFromJson(ctx, argumentType, "item", module)})`;
+        if (requiresJsonSerialization(ctx, module, argumentType)) {
+          return `(${expr})?.map((item: any) => ${transposeExpressionFromJson(ctx, argumentType, "item", module)})`;
         } else {
           return expr;
         }
       } else if (isRecordModelType(ctx.program, type)) {
         const argumentType = type.indexer.value;
 
-        if (requiresJsonSerialization(ctx, argumentType)) {
+        if (requiresJsonSerialization(ctx, module, argumentType)) {
           return `Object.fromEntries(Object.entries(${expr}).map(([key, value]) => [key, ${transposeExpressionFromJson(
             ctx,
             argumentType,
@@ -358,7 +476,7 @@ function transposeExpressionFromJson(
         } else {
           return expr;
         }
-      } else if (!requiresJsonSerialization(ctx, type)) {
+      } else if (!requiresJsonSerialization(ctx, module, type)) {
         return `${expr} as ${emitTypeReference(ctx, type, NoTarget, module)}`;
       } else {
         requireSerialization(ctx, type, "application/json");
@@ -368,16 +486,20 @@ function transposeExpressionFromJson(
       }
     }
     case "Scalar":
-      const scalar = getJsScalar(ctx.program, type, type);
+      const scalar = getJsScalar(ctx, module, type, type);
 
-      switch (scalar) {
-        case "Uint8Array":
-          return `Buffer.from(${expr}, 'base64')`;
-        default:
-          return expr;
+      const encoder = getScalarEncoder(ctx, type, scalar);
+
+      const decoded = encoder.decode(expr);
+
+      if (encoder.target.isJsonCompatible || !encoder.target.scalar) {
+        return decoded;
+      } else {
+        // Assertion: encoder.target.scalar is a scalar because "unknown" is JSON compatible.
+        return transposeExpressionFromJson(ctx, encoder.target.scalar as Scalar, decoded, module);
       }
     case "Union":
-      if (!requiresJsonSerialization(ctx, type)) {
+      if (!requiresJsonSerialization(ctx, module, type)) {
         return expr;
       } else {
         requireSerialization(ctx, type, "application/json");

package/src/helpers/datetime.ts

@@ -0,0 +1,235 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+// #region Duration
+
+/**
+ * Regular expression for matching ISO8601 duration strings.
+ *
+ * Yields:
+ * - 0: the full match
+ * - 1: the sign (optional)
+ * - 2: years (optional)
+ * - 3: months (optional)
+ * - 4: weeks (optional)
+ * - 5: days (optional)
+ * - 6: hours (optional)
+ * - 7: minutes (optional)
+ * - 8: seconds (optional)
+ */
+const ISO8601_DURATION_REGEX =
+  /^(-)?P(?:((?:\d*[.,])?\d+)Y)?(?:((?:\d*[.,])?\d+)M)?(?:((?:\d*[.,])?\d+)W)?(?:((?:\d*[.,])?\d+)D)?(?:T(?:((?:\d*[.,])?\d+)H)?(?:((?:\d*[.,])?\d+)M)?(?:((?:\d*[.,])?\d+)S)?)?$/;
+
+/**
+ * A duration of time, measured in years, months, weeks, days, hours, minutes, and seconds.
+ *
+ * The values may be fractional and are not normalized (e.g. 36 hours is not the same duration as 1 day and 12 hours
+ * when accounting for Daylight Saving Time changes or leap seconds).
+ *
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
+ */
+export interface Duration {
+  /**
+   * "+" if the duration is positive, "-" if the duration is negative.
+   */
+  sign: "+" | "-";
+  /**
+   * The number of years in the duration.
+   */
+  years: number;
+  /**
+   * The number of months in the duration.
+   */
+  months: number;
+  /**
+   * The number of weeks in the duration.
+   */
+  weeks: number;
+  /**
+   * The number of days in the duration.
+   */
+  days: number;
+  /**
+   * The number of hours in the duration.
+   */
+  hours: number;
+  /**
+   * The number of minutes in the duration.
+   */
+  minutes: number;
+  /**
+   * The number of seconds in the duration.
+   */
+  seconds: number;
+}
+
+export const Duration = Object.freeze({
+  /**
+   * Parses an ISO8601 duration string into an object.
+   *
+   * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
+   *
+   * @param duration - the duration string to parse
+   * @returns an object containing the parsed duration
+   */
+  parseISO8601(duration: string, maxLength: number = 100): Duration {
+    duration = duration.trim();
+    if (duration.length > maxLength)
+      throw new Error(`ISO8601 duration string is too long: ${duration}`);
+
+    const match = duration.match(ISO8601_DURATION_REGEX);
+
+    if (!match) throw new Error(`Invalid ISO8601 duration: ${duration}`);
+
+    return {
+      sign: match[1] === undefined ? "+" : (match[1] as Duration["sign"]),
+      years: parseFloatNormal(match[2]),
+      months: parseFloatNormal(match[3]),
+      weeks: parseFloatNormal(match[4]),
+      days: parseFloatNormal(match[5]),
+      hours: parseFloatNormal(match[6]),
+      minutes: parseFloatNormal(match[7]),
+      seconds: parseFloatNormal(match[8]),
+    };
+
+    function parseFloatNormal(match: string | undefined): number {
+      if (match === undefined) return 0;
+
+      const normalized = match.replace(",", ".");
+
+      const parsed = parseFloat(normalized);
+
+      if (isNaN(parsed))
+        throw new Error(`Unreachable: Invalid number in ISO8601 duration string: ${match}`);
+
+      return parsed;
+    }
+  },
+  /**
+   * Writes a Duration to an ISO8601 duration string.
+   *
+   * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
+   *
+   * @param duration - the duration to write to a string
+   * @returns a string in ISO8601 duration format
+   */
+  toISO8601(duration: Duration): string {
+    const sign = duration.sign === "+" ? "" : "-";
+
+    const years =
+      duration.years !== 0 && !isNaN(Number(duration.years)) ? `${duration.years}Y` : "";
+    const months =
+      duration.months !== 0 && !isNaN(Number(duration.months)) ? `${duration.months}M` : "";
+    const weeks =
+      duration.weeks !== 0 && !isNaN(Number(duration.weeks)) ? `${duration.weeks}W` : "";
+    const days = duration.days !== 0 && !isNaN(Number(duration.days)) ? `${duration.days}D` : "";
+
+    let time = "";
+
+    const _hours = duration.hours !== 0 && !isNaN(Number(duration.hours));
+    const _minutes = duration.minutes !== 0 && !isNaN(Number(duration.minutes));
+    const _seconds = duration.seconds !== 0 && !isNaN(Number(duration.seconds));
+
+    if (_hours || _minutes || _seconds) {
+      const hours = _hours ? `${duration.hours}H` : "";
+      const minutes = _minutes ? `${duration.minutes}M` : "";
+      const seconds = _seconds ? `${duration.seconds}S` : "";
+
+      time = `T${hours}${minutes}${seconds}`;
+    }
+
+    return `${sign}P${years}${months}${weeks}${days}${time}`;
+  },
+
+  /**
+   * Gets the total number of seconds in a duration.
+   *
+   * This method will throw an Error if the duration contains any years, months, weeks, or days, as those require a reference
+   * point to calculate the total number of seconds.
+   *
+   * WARNING: If the total number of seconds is larger than the maximum safe integer in JavaScript, this method will
+   * lose precision. @see Duration.totalSecondsBigInt for a BigInt alternative.
+   *
+   * @param duration - the duration to calculate the total number of seconds for
+   * @returns the total number of seconds in the duration
+   */
+  totalSeconds(duration: Duration): number {
+    if (
+      duration.years !== 0 ||
+      duration.months !== 0 ||
+      duration.weeks !== 0 ||
+      duration.days !== 0
+    ) {
+      throw new Error(
+        "Cannot calculate total seconds for a duration with years, months, weeks, or days.",
+      );
+    }
+
+    return (
+      duration.seconds +
+      duration.minutes * 60 +
+      duration.hours * 60 * 60 +
+      duration.weeks * 7 * 24 * 60 * 60
+    );
+  },
+
+  /**
+   * Gets the total number of seconds in a duration.
+   *
+   * This method will throw an Error if the duration contains any years, months, weeks, or days, as those require a reference
+   * point to calculate the total number of seconds. It will also throw an error if any of the components are not integers.
+   *
+   * @param duration - the duration to calculate the total number of seconds for
+   * @returns the total number of seconds in the duration
+   */
+  totalSecondsBigInt(duration: Duration): bigint {
+    if (
+      duration.years !== 0 ||
+      duration.months !== 0 ||
+      duration.weeks !== 0 ||
+      duration.days !== 0
+    ) {
+      throw new Error(
+        "Cannot calculate total seconds for a duration with years, months, weeks, or days.",
+      );
+    }
+
+    if (
+      !Number.isInteger(duration.seconds) ||
+      !Number.isInteger(duration.minutes) ||
+      !Number.isInteger(duration.hours) ||
+      !Number.isInteger(duration.weeks)
+    ) {
+      throw new Error(
+        "Cannot calculate total seconds as a BigInt for a duration with non-integer components.",
+      );
+    }
+
+    return (
+      BigInt(duration.seconds) +
+      BigInt(duration.minutes) * 60n +
+      BigInt(duration.hours) * 60n * 60n +
+      BigInt(duration.weeks) * 7n * 24n * 60n * 60n
+    );
+  },
+
+  /**
+   * Creates a duration from a total number of seconds.
+   *
+   * The result is not normalized, so it will only contain a seconds field.
+   */
+  fromTotalSeconds(seconds: number): Duration {
+    return {
+      sign: seconds < 0 ? "-" : "+",
+      years: 0,
+      months: 0,
+      weeks: 0,
+      days: 0,
+      hours: 0,
+      minutes: 0,
+      seconds: Math.abs(seconds),
+    };
+  },
+});
+
+// #endregion