@typespec/http-server-js 0.58.0-alpha.13-dev.7 → 0.58.0-alpha.13-dev.9

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,