@typespec/http-server-js 0.58.0-alpha.13-dev.8 → 0.58.0-alpha.13-dev.10

package/src/common/serialization/json.ts

@@ -38,7 +38,10 @@ import {
 /**
  * Memoization cache for requiresJsonSerialization.
  */
-const _REQUIRES_JSON_SERIALIZATION = new WeakMap<SerializableType | ModelProperty, boolean>();
+const _REQUIRES_JSON_SERIALIZATION = new WeakMap<
+  SerializableType | Scalar | ModelProperty,
+  boolean
+>();
 
 export function requiresJsonSerialization(
   ctx: JsContext,
@@ -46,7 +49,7 @@ export function requiresJsonSerialization(
   type: Type,
   diagnosticTarget: DiagnosticTarget | typeof NoTarget = NoTarget,
 ): boolean {
-  if (!isSerializable(type)) return false;
+  if (!isJsonSerializable(type)) return false;
 
   if (_REQUIRES_JSON_SERIALIZATION.has(type)) {
     return _REQUIRES_JSON_SERIALIZATION.get(type)!;
@@ -107,7 +110,7 @@ function propertyRequiresJsonSerialization(
     isHttpMetadata(ctx, property) ||
     getEncode(ctx.program, property) ||
     resolveEncodedName(ctx.program, property, "application/json") !== property.name ||
-    (isSerializable(property.type) &&
+    (isJsonSerializable(property.type) &&
       requiresJsonSerialization(ctx, module, property.type, property))
   );
 }
@@ -120,8 +123,8 @@ function isHttpMetadata(ctx: JsContext, property: ModelProperty): boolean {
   );
 }
 
-function isSerializable(type: Type): type is SerializableType | ModelProperty {
-  return type.kind === "ModelProperty" || isSerializableType(type);
+function isJsonSerializable(type: Type): type is SerializableType | Scalar | ModelProperty {
+  return type.kind === "ModelProperty" || type.kind === "Scalar" || isSerializableType(type);
 }
 
 export function* emitJsonSerialization(
@@ -194,10 +197,6 @@ function* emitToJson(
 
       return;
     }
-    case "Scalar": {
-      yield `throw new Error("Unimplemented: scalar JSON serialization");`;
-      return;
-    }
     case "Union": {
       const codeTree = differentiateUnion(ctx, module, type);
 
@@ -224,7 +223,7 @@ function* emitToJson(
   }
 }
 
-function transposeExpressionToJson(
+export function transposeExpressionToJson(
   ctx: SerializationContext,
   type: Type,
   expr: string,
@@ -400,12 +399,14 @@ function* emitFromJson(
           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,
+            expr = scalarEncoder.decode(
+              transposeExpressionFromJson(
+                ctx,
+                // Assertion: scalarEncoder.target.scalar is defined because we resolved an encoder.
+                scalarEncoder.target.scalar as Scalar,
+                expr,
+                module,
+              ),
             );
           } else {
             reportDiagnostic(ctx.program, {
@@ -433,10 +434,6 @@ function* emitFromJson(
 
       return;
     }
-    case "Scalar": {
-      yield `throw new Error("Unimplemented: scalar JSON serialization");`;
-      return;
-    }
     case "Union": {
       const codeTree = differentiateUnion(ctx, module, type);
 
@@ -464,7 +461,7 @@ function* emitFromJson(
   }
 }
 
-function transposeExpressionFromJson(
+export function transposeExpressionFromJson(
   ctx: SerializationContext,
   type: Type,
   expr: string,
@@ -507,13 +504,13 @@ function transposeExpressionFromJson(
 
       const encoder = getScalarEncoder(ctx, type, scalar);
 
-      const decoded = encoder.decode(expr);
-
       if (encoder.target.isJsonCompatible || !encoder.target.scalar) {
-        return decoded;
+        return encoder.decode(expr);
       } else {
         // Assertion: encoder.target.scalar is a scalar because "unknown" is JSON compatible.
-        return transposeExpressionFromJson(ctx, encoder.target.scalar as Scalar, decoded, module);
+        return encoder.decode(
+          transposeExpressionFromJson(ctx, encoder.target.scalar as Scalar, expr, module),
+        );
       }
     case "Union":
       if (!requiresJsonSerialization(ctx, module, type)) {

package/src/helpers/temporal/native.ts

@@ -0,0 +1,104 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+// Due to the lack of generally-available global type definitions for Temporal, we use `any` throughout this module.
+// When global.d.ts eventually has definitions for Temporal, we can unify this module with `polyfill.ts`.
+
+/**
+ * Parses an HTTP date string (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) into a `Temporal.Instant`.
+ * The date string must be in the format specified by RFC 7231.
+ *
+ * @param httpDate - The HTTP date string to parse.
+ * @throws {RangeError} If the date string is invalid or cannot be parsed.
+ * @returns The parsed `Temporal.Instant`.
+ */
+export function parseHttpDate(httpDate: string): any {
+  const timestamp = globalThis.Date.parse(httpDate);
+
+  if (isNaN(timestamp)) {
+    throw new RangeError(`Invalid HTTP date: ${httpDate}`);
+  }
+
+  return (globalThis as any).Temporal.Instant.fromEpochMilliseconds(timestamp);
+}
+
+/**
+ * Formats a `Temporal.Instant` into an HTTP date string (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`).
+ * The date string is formatted according to RFC 7231.
+ *
+ * @param instant - The `Temporal.Instant` to format.
+ * @returns The formatted HTTP date string.
+ */
+export function formatHttpDate(instant: any) {
+  const date = new Date(instant.epochMilliseconds);
+  return date.toUTCString();
+}
+
+/**
+ * Converts a `Temporal.Duration` to a number of seconds.
+ * 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 durationTotalSecondsBigInt 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
+ */
+export function durationTotalSeconds(duration: any): 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.days * 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
+ */
+export function durationTotalSecondsBigInt(duration: any): 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.days)
+  ) {
+    throw new Error("Duration components must be integers.");
+  }
+
+  return (
+    BigInt(duration.seconds) +
+    BigInt(duration.minutes) * 60n +
+    BigInt(duration.hours) * 60n * 60n +
+    BigInt(duration.days) * 24n * 60n * 60n
+  );
+}

package/src/helpers/temporal/polyfill.ts

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { Temporal } from "temporal-polyfill";
+
+/**
+ * Parses an HTTP date string (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) into a `Temporal.Instant`.
+ * The date string must be in the format specified by RFC 7231.
+ *
+ * @param httpDate - The HTTP date string to parse.
+ * @throws {RangeError} If the date string is invalid or cannot be parsed.
+ * @returns The parsed `Temporal.Instant`.
+ */
+export function parseHttpDate(httpDate: string): Temporal.Instant {
+  const timestamp = globalThis.Date.parse(httpDate);
+
+  if (isNaN(timestamp)) {
+    throw new RangeError(`Invalid HTTP date: ${httpDate}`);
+  }
+
+  return Temporal.Instant.fromEpochMilliseconds(timestamp);
+}
+
+/**
+ * Formats a `Temporal.Instant` into an HTTP date string (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`).
+ * The date string is formatted according to RFC 7231.
+ *
+ * @param instant - The `Temporal.Instant` to format.
+ * @returns The formatted HTTP date string.
+ */
+export function formatHttpDate(instant: Temporal.Instant) {
+  const date = new Date(instant.epochMilliseconds);
+  return date.toUTCString();
+}
+
+/**
+ * Converts a `Temporal.Duration` to a number of seconds.
+ * 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 durationTotalSecondsBigInt 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
+ */
+export function durationTotalSeconds(duration: Temporal.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.days * 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
+ */
+export function durationTotalSecondsBigInt(duration: Temporal.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.days)
+  ) {
+    throw new Error("Duration components must be integers.");
+  }
+
+  return (
+    BigInt(duration.seconds) +
+    BigInt(duration.minutes) * 60n +
+    BigInt(duration.hours) * 60n * 60n +
+    BigInt(duration.days) * 24n * 60n * 60n
+  );
+}

package/src/http/server/index.ts

@@ -40,7 +40,10 @@ import { emitMultipart, emitMultipartLegacy } from "./multipart.js";
 import { module as headerHelpers } from "../../../generated-defs/helpers/header.js";
 import { module as httpHelpers } from "../../../generated-defs/helpers/http.js";
 import { getJsScalar } from "../../common/scalar.js";
-import { requiresJsonSerialization } from "../../common/serialization/json.js";
+import {
+  requiresJsonSerialization,
+  transposeExpressionFromJson,
+} from "../../common/serialization/json.js";
 import { getFullyQualifiedTypeName } from "../../util/name.js";
 
 const DEFAULT_CONTENT_TYPE = "application/json";
@@ -274,6 +277,8 @@ function* emitRawServerOperation(
             yield `          return reject();`;
             yield `        }`;
             value = `Object.fromEntries(Object.entries(__recordBody).map(([key, value]) => [key, ${innerTypeName}.fromJsonObject(value)]))`;
+          } else if (body.type.kind === "Scalar") {
+            value = transposeExpressionFromJson(ctx, body.type, `JSON.parse(body)`, module);
           } else {
             value = `${bodyTypeName}.fromJsonObject(JSON.parse(body))`;
           }

package/src/lib.ts

@@ -14,6 +14,16 @@ to `true`, the emitter will only emit those types that are reachable from an HTT
   "omit-unreachable-types": boolean;
   /** If set to `true`, the emitter will not format the generated code using Prettier. */
   "no-format": boolean;
+
+  /**
+   * The type of datetime models to use for TypeSpecs DateTime and Duration types.
+   *
+   * Options:
+   * - `temporal-polyfill`: (Default) Uses the Temporal API from the `temporal-polyfill` package.
+   * - `temporal`: Uses the native Temporal API, requires that your target environment supports it. This will become the default setting in the future.
+   * - `date-duration`: Uses the built-in `Date` and a custom `Duration` type. Not recommended.
+   */
+  datetime?: "temporal-polyfill" | "temporal" | "date-duration";
 }
 
 const EmitterOptionsSchema: JSONSchemaType<JsEmitterOptions> = {
@@ -27,6 +37,13 @@ const EmitterOptionsSchema: JSONSchemaType<JsEmitterOptions> = {
       description:
         "If set to `true`, the emitter will generate a router that exposes an Express.js middleware function in addition to the ordinary Node.js HTTP server router.\n\nIf this option is not set to `true`, the `expressMiddleware` property will not be present on the generated router.",
     },
+    datetime: {
+      type: "string",
+      enum: ["temporal-polyfill", "temporal", "date-duration"],
+      default: "temporal-polyfill",
+      nullable: true,
+      description: "The type of datetime models to use for TypeSpecs DateTime and Duration types.",
+    },
     "omit-unreachable-types": {
       type: "boolean",
       default: false,

package/src/scripts/scaffold/data-mocks.ts

@@ -12,8 +12,10 @@ import { $ } from "@typespec/compiler/experimental/typekit";
 import { JsContext, Module } from "../../ctx.js";
 import { isUnspeakable, parseCase } from "../../util/case.js";
 
-import { module as dateTimeHelper } from "../../../generated-defs/helpers/datetime.js";
 import { KEYWORDS } from "../../util/keywords.js";
+import { getFullyQualifiedTypeName } from "../../util/name.js";
+
+import { module as dateTimeHelper } from "../../../generated-defs/helpers/datetime.js";
 
 /**
  * Generates a mock value for a TypeSpec Model.
@@ -24,16 +26,17 @@ import { KEYWORDS } from "../../util/keywords.js";
  * @throws Error if a property cannot be mocked
  */
 function mockModel(ctx: JsContext, module: Module, type: Model): string {
-  if ($.array.is(type)) {
+  const tk = $(ctx.program);
+  if (tk.array.is(type)) {
     return mockArray(ctx, module, type);
   }
 
-  if ($.record.is(type)) {
+  if (tk.record.is(type)) {
     return mockRecord(ctx, module, type);
   }
 
   const mock: string[][] = [];
-  const properties = $.model.getProperties(type, { includeExtended: true });
+  const properties = tk.model.getProperties(type, { includeExtended: true });
 
   // If no properties exist, return an empty object
   if (properties.size === 0) {
@@ -72,7 +75,8 @@ function mockModel(ctx: JsContext, module: Module, type: Model): string {
  * @returns A JavaScript string representation of the mock array
  */
 function mockArray(ctx: JsContext, module: Module, type: Model): string {
-  const elementType = $.array.getElementType(type);
+  const tk = $(ctx.program);
+  const elementType = tk.array.getElementType(type);
   const mockedType = mockType(ctx, module, elementType);
 
   // If we can't mock the element type, return an empty array
@@ -90,7 +94,8 @@ function mockArray(ctx: JsContext, module: Module, type: Model): string {
  * @returns A JavaScript string representation of the mock record
  */
 function mockRecord(ctx: JsContext, module: Module, type: Model): string {
-  const elementType = $.record.getElementType(type);
+  const tk = $(ctx.program);
+  const elementType = tk.record.getElementType(type);
   const mockedType = mockType(ctx, module, elementType);
 
   if (mockedType === undefined) {
@@ -134,23 +139,24 @@ function mockLiteral(type: LiteralType): string {
  * @returns A JavaScript string representation of the mock data, or undefined if the type cannot be mocked
  */
 export function mockType(ctx: JsContext, module: Module, type: Type): string | undefined {
-  if ($.model.is(type)) {
+  const tk = $(ctx.program);
+  if (tk.model.is(type)) {
     return mockModel(ctx, module, type);
   }
 
-  if ($.literal.is(type)) {
+  if (tk.literal.is(type)) {
     return mockLiteral(type);
   }
 
-  if ($.modelProperty.is(type)) {
+  if (tk.modelProperty.is(type)) {
     return mockModelProperty(ctx, module, type);
   }
 
-  if ($.scalar.is(type)) {
+  if (tk.scalar.is(type)) {
     return mockScalar(ctx, module, type);
   }
 
-  if ($.union.is(type)) {
+  if (tk.union.is(type)) {
     return mockUnion(ctx, module, type);
   }
 
@@ -186,18 +192,21 @@ function mockUnion(ctx: JsContext, module: Module, union: Union): string | undef
  * @returns A JavaScript string representation of a suitable mock value for the scalar type
  */
 function mockScalar(ctx: JsContext, module: Module, scalar: Scalar): string | undefined {
-  if ($.scalar.isBoolean(scalar) || $.scalar.extendsBoolean(scalar)) {
+  const tk = $(ctx.program);
+  const dateTimeMode = ctx.options.datetime ?? "temporal-polyfill";
+
+  if (tk.scalar.isBoolean(scalar) || tk.scalar.extendsBoolean(scalar)) {
     return JSON.stringify(true);
   }
-  if ($.scalar.isNumeric(scalar) || $.scalar.extendsNumeric(scalar)) {
+  if (tk.scalar.isNumeric(scalar) || tk.scalar.extendsNumeric(scalar)) {
     if (
-      $.scalar.extendsSafeint(scalar) ||
-      $.scalar.extendsInt32(scalar) ||
-      $.scalar.extendsUint32(scalar) ||
-      $.scalar.extendsFloat64(scalar)
+      tk.scalar.extendsSafeint(scalar) ||
+      tk.scalar.extendsInt32(scalar) ||
+      tk.scalar.extendsUint32(scalar) ||
+      tk.scalar.extendsFloat64(scalar)
     ) {
       return "42";
-    } else if ($.scalar.extendsInteger(scalar)) {
+    } else if (tk.scalar.extendsInteger(scalar)) {
       return "42n";
     } else {
       module.imports.push({ from: "decimal.js", binder: ["Decimal"] });
@@ -205,40 +214,96 @@ function mockScalar(ctx: JsContext, module: Module, scalar: Scalar): string | un
     }
   }
 
-  if ($.scalar.isUtcDateTime(scalar) || $.scalar.extendsUtcDateTime(scalar)) {
-    return "new Date()";
+  if (tk.scalar.isUtcDateTime(scalar)) {
+    if (dateTimeMode === "date-duration") {
+      return "new Date()";
+    } else {
+      if (dateTimeMode === "temporal-polyfill") {
+        module.imports.push({
+          from: "temporal-polyfill",
+          binder: ["Temporal"],
+        });
+      }
+
+      // Current instant
+      return "Temporal.Now.instant()";
+    }
+  }
+
+  if (
+    tk.scalar.isOffsetDateTime(scalar) ||
+    tk.scalar.isPlainDate(scalar) ||
+    tk.scalar.isPlainTime(scalar)
+  ) {
+    if (dateTimeMode === "date-duration") {
+      return "new Date()";
+    } else {
+      if (dateTimeMode === "temporal-polyfill") {
+        module.imports.push({
+          from: "temporal-polyfill",
+          binder: ["Temporal"],
+        });
+      }
+
+      // Current instant
+      switch ((scalar as Scalar).name) {
+        case "offsetDateTime":
+          return "Temporal.Now.zonedDateTimeISO()";
+        case "plainDate":
+          return "Temporal.Now.zonedDateTimeISO().toPlainDate()";
+        case "plainTime":
+          return "Temporal.Now.zonedDateTimeISO().toPlainTime()";
+        default:
+          throw new Error("Unexpected scalar type: " + (scalar as Scalar).name);
+      }
+    }
   }
 
-  if ($.scalar.isBytes(scalar) || $.scalar.extendsBytes(scalar)) {
+  if (getFullyQualifiedTypeName(scalar) === "TypeSpec.unixTimestamp32") {
+    return "Math.floor(new Date().getTime() / 1000)";
+  }
+
+  if (tk.scalar.isBytes(scalar) || tk.scalar.extendsBytes(scalar)) {
     return "new Uint8Array()";
   }
 
-  if ($.scalar.isDuration(scalar) || $.scalar.extendsDuration(scalar)) {
-    module.imports.push({
-      from: dateTimeHelper,
-      binder: ["Duration"],
-    });
+  if (tk.scalar.isDuration(scalar) || tk.scalar.extendsDuration(scalar)) {
+    if (dateTimeMode === "date-duration") {
+      module.imports.push({
+        from: dateTimeHelper,
+        binder: ["Duration"],
+      });
 
-    return 'Duration.parseISO8601("P1Y2M3DT4H5M6S")';
+      return 'Duration.parseISO8601("P1Y2M3DT4H5M6S")';
+    } else {
+      if (dateTimeMode === "temporal-polyfill") {
+        module.imports.push({
+          from: "temporal-polyfill",
+          binder: ["Temporal"],
+        });
+      }
+
+      return `Temporal.Duration.from({ years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6 })`;
+    }
   }
 
-  if ($.scalar.isOffsetDateTime(scalar) || $.scalar.extendsOffsetDateTime(scalar)) {
+  if (tk.scalar.isOffsetDateTime(scalar) || tk.scalar.extendsOffsetDateTime(scalar)) {
     return JSON.stringify("2022-01-01T00:00:00Z");
   }
 
-  if ($.scalar.isPlainDate(scalar) || $.scalar.extendsPlainDate(scalar)) {
+  if (tk.scalar.isPlainDate(scalar) || tk.scalar.extendsPlainDate(scalar)) {
     return JSON.stringify("2022-01-01");
   }
 
-  if ($.scalar.isPlainTime(scalar) || $.scalar.extendsPlainTime(scalar)) {
+  if (tk.scalar.isPlainTime(scalar) || tk.scalar.extendsPlainTime(scalar)) {
     return JSON.stringify("00:00:00");
   }
 
-  if ($.scalar.isUrl(scalar) || $.scalar.extendsUrl(scalar)) {
+  if (tk.scalar.isUrl(scalar) || tk.scalar.extendsUrl(scalar)) {
     return JSON.stringify("https://example.com");
   }
 
-  if ($.scalar.isString(scalar) || $.scalar.extendsString(scalar)) {
+  if (tk.scalar.isString(scalar) || tk.scalar.extendsString(scalar)) {
     return JSON.stringify("mock-string");
   }