fix: time format should not have date type (#2471)

Author: jonaslagoni

docs/languages/TypeScript.md

@@ -7,6 +7,7 @@ There are special use-cases that each language supports; this document pertains
 <!-- toc -->
 
 - [Generate an interface instead of classes](#generate-an-interface-instead-of-classes)
+- [Date and time format mappings](#date-and-time-format-mappings)
 - [Generate different `mapType`s for an `object`](#generate-different-maptypes-for-an-object)
 - [Generate union types instead of enums](#generate-union-types-instead-of-enums)
 - [Generate serializer and deserializer functionality](#generate-serializer-and-deserializer-functionality)
@@ -28,6 +29,27 @@ Sometimes you don't care about classes, but rather have interfaces generated. Th
 
 Check out this [example out for a live demonstration](../../examples/typescript-interface).
 
+## Date and time format mappings
+
+JSON Schema string properties can specify a `format` keyword to indicate the expected data format. TypeScript maps these formats to appropriate types:
+
+| JSON Schema format | TypeScript type | Notes |
+|--------------------|-----------------|-------|
+| `date-time` | `Date` | ISO 8601 date-time strings (e.g., `"2023-01-01T10:00:00Z"`) |
+| `date` | `Date` | ISO 8601 date strings (e.g., `"2023-01-01"`) |
+| `time` | `string` | Time-only strings (e.g., `"14:30:00"`) |
+| Other formats | `string` | Email, URI, UUID, etc. |
+
+**Why is `time` mapped to `string`?**
+
+Time-only strings like `"14:30:00"` are not valid JavaScript `Date` constructor arguments. Passing them to `new Date()` produces unreliable results (implementation-dependent behavior). Therefore, `format: time` is mapped to `string` to preserve the time value as-is.
+
+When using the marshalling preset, the unmarshal function will:
+- Convert `date-time` and `date` values to `Date` objects using `new Date(value)`
+- Keep `time` values as strings without Date conversion
+
+Check out this [example for a live demonstration of date and time handling](../../examples/typescript-generate-marshalling).
+
 ## Generate different `mapType`s for an `object`
 
 Typescript offers different `mapType`s which can simplify the use based on the needs. This behavior can be changed through the `mapType` configuration.

examples/typescript-generate-marshalling/__snapshots__/index.spec.ts.snap

@@ -2,35 +2,71 @@
 
 exports[`Should be able to generate ts data model with marshal und unmarshal functions and should log expected output to console 1`] = `
 Array [
-  "class Test {
+  "class Meeting {
   private _email?: string;
+  private _createdAt?: Date;
+  private _meetingDate?: Date;
+  private _meetingTime?: string;
 
   constructor(input: {
     email?: string,
+    createdAt?: Date,
+    meetingDate?: Date,
+    meetingTime?: string,
   }) {
     this._email = input.email;
+    this._createdAt = input.createdAt;
+    this._meetingDate = input.meetingDate;
+    this._meetingTime = input.meetingTime;
   }
 
   get email(): string | undefined { return this._email; }
   set email(email: string | undefined) { this._email = email; }
 
+  get createdAt(): Date | undefined { return this._createdAt; }
+  set createdAt(createdAt: Date | undefined) { this._createdAt = createdAt; }
+
+  get meetingDate(): Date | undefined { return this._meetingDate; }
+  set meetingDate(meetingDate: Date | undefined) { this._meetingDate = meetingDate; }
+
+  get meetingTime(): string | undefined { return this._meetingTime; }
+  set meetingTime(meetingTime: string | undefined) { this._meetingTime = meetingTime; }
+
   public marshal() : string {
     let json = '{'
     if(this.email !== undefined) {
       json += \`\\"email\\": \${typeof this.email === 'number' || typeof this.email === 'boolean' ? this.email : JSON.stringify(this.email)},\`;
     }
+    if(this.createdAt !== undefined) {
+      json += \`\\"createdAt\\": \${typeof this.createdAt === 'number' || typeof this.createdAt === 'boolean' ? this.createdAt : JSON.stringify(this.createdAt)},\`;
+    }
+    if(this.meetingDate !== undefined) {
+      json += \`\\"meetingDate\\": \${typeof this.meetingDate === 'number' || typeof this.meetingDate === 'boolean' ? this.meetingDate : JSON.stringify(this.meetingDate)},\`;
+    }
+    if(this.meetingTime !== undefined) {
+      json += \`\\"meetingTime\\": \${typeof this.meetingTime === 'number' || typeof this.meetingTime === 'boolean' ? this.meetingTime : JSON.stringify(this.meetingTime)},\`;
+    }
   
     //Remove potential last comma 
     return \`\${json.charAt(json.length-1) === ',' ? json.slice(0, json.length-1) : json}}\`;
   }
 
-  public static unmarshal(json: string | object): Test {
+  public static unmarshal(json: string | object): Meeting {
     const obj = typeof json === \\"object\\" ? json : JSON.parse(json);
-    const instance = new Test({} as any);
+    const instance = new Meeting({} as any);
 
     if (obj[\\"email\\"] !== undefined) {
       instance.email = obj[\\"email\\"];
     }
+    if (obj[\\"createdAt\\"] !== undefined) {
+      instance.createdAt = obj[\\"createdAt\\"] == null ? undefined : new Date(obj[\\"createdAt\\"]);
+    }
+    if (obj[\\"meetingDate\\"] !== undefined) {
+      instance.meetingDate = obj[\\"meetingDate\\"] == null ? undefined : new Date(obj[\\"meetingDate\\"]);
+    }
+    if (obj[\\"meetingTime\\"] !== undefined) {
+      instance.meetingTime = obj[\\"meetingTime\\"];
+    }
   
   
     return instance;

examples/typescript-generate-marshalling/index.ts

@@ -13,13 +13,28 @@ const generator = new TypeScriptGenerator({
 });
 const jsonSchemaDraft7 = {
   $schema: 'http://json-schema.org/draft-07/schema#',
-  $id: 'Test',
+  $id: 'Meeting',
   type: 'object',
   additionalProperties: false,
   properties: {
     email: {
       type: 'string',
       format: 'email'
+    },
+    // date-time and date map to Date type
+    createdAt: {
+      type: 'string',
+      format: 'date-time'
+    },
+    meetingDate: {
+      type: 'string',
+      format: 'date'
+    },
+    // time maps to string (not Date) because time-only strings
+    // like "14:30:00" are not valid Date constructor arguments
+    meetingTime: {
+      type: 'string',
+      format: 'time'
     }
   }
 };

src/generators/typescript/TypeScriptConstrainer.ts

@@ -32,7 +32,9 @@ export const TypeScriptDefaultTypeMapping: TypeScriptTypeMapping = {
   },
   String({ constrainedModel }): string {
     const format = constrainedModel?.options?.format;
-    if (format === 'date-time' || format === 'date' || format === 'time') {
+    // Only date-time and date are valid Date constructor arguments
+    // time (e.g., "14:30:00") is NOT valid, so keep as string
+    if (format === 'date-time' || format === 'date') {
       return applyNullable(constrainedModel, 'Date');
     }
     return applyNullable(constrainedModel, 'string');

src/generators/typescript/presets/utils/UnmarshalFunction.ts

@@ -40,9 +40,10 @@ function renderUnmarshalProperty(
   }
 
   // Date-typed properties need string→Date conversion
+  // Note: 'time' is excluded - time-only strings (e.g., "14:30:00") are not valid Date constructor arguments
   if (
     model instanceof ConstrainedStringModel &&
-    ['date', 'date-time', 'time'].includes(model.options?.format ?? '')
+    ['date', 'date-time'].includes(model.options?.format ?? '')
   ) {
     // Null check prevents new Date(null) → epoch date
     return `${modelInstanceVariable} == null ? ${nullValue} : new Date(${modelInstanceVariable})`;

test/generators/typescript/TypeScriptConstrainer.spec.ts

@@ -88,6 +88,53 @@ describe('TypeScriptConstrainer', () => {
       });
       expect(type).toEqual('string');
     });
+
+    test('should render Date type for format: date-time', () => {
+      const model = new ConstrainedStringModel(
+        'test',
+        undefined,
+        { format: 'date-time' },
+        ''
+      );
+      const type = TypeScriptDefaultTypeMapping.String({
+        constrainedModel: model,
+        options: TypeScriptGenerator.defaultOptions,
+        dependencyManager: undefined as never
+      });
+      expect(type).toEqual('Date');
+    });
+
+    test('should render Date type for format: date', () => {
+      const model = new ConstrainedStringModel(
+        'test',
+        undefined,
+        { format: 'date' },
+        ''
+      );
+      const type = TypeScriptDefaultTypeMapping.String({
+        constrainedModel: model,
+        options: TypeScriptGenerator.defaultOptions,
+        dependencyManager: undefined as never
+      });
+      expect(type).toEqual('Date');
+    });
+
+    test('should render string type for format: time', () => {
+      // time-only strings (e.g., "14:30:00") are not valid Date constructor arguments
+      // so format: time should map to string, not Date
+      const model = new ConstrainedStringModel(
+        'test',
+        undefined,
+        { format: 'time' },
+        ''
+      );
+      const type = TypeScriptDefaultTypeMapping.String({
+        constrainedModel: model,
+        options: TypeScriptGenerator.defaultOptions,
+        dependencyManager: undefined as never
+      });
+      expect(type).toEqual('string');
+    });
   });
   describe('Boolean', () => {
     test('should render type', () => {

test/generators/typescript/preset/MarshallingPreset.spec.ts

@@ -154,8 +154,9 @@ describe('Marshalling preset', () => {
       // Should use new Date() conversion for date format
       expect(result).toContain('new Date(obj["birthDate"])');
 
-      // Should use new Date() conversion for time format
-      expect(result).toContain('new Date(obj["meetingTime"])');
+      // Should NOT use new Date() for time format
+      // time-only strings (e.g., "14:30:00") are not valid Date constructor arguments
+      expect(result).not.toContain('new Date(obj["meetingTime"])');
 
       // Should NOT use new Date() for regular strings
       expect(result).not.toContain('new Date(obj["regularString"])');

test/generators/typescript/preset/__snapshots__/MarshallingPreset.spec.ts.snap

@@ -4,15 +4,15 @@ exports[`Marshalling preset date unmarshal should convert date-formatted string
 "class DateTest {
   private _createdAt: Date;
   private _birthDate?: Date;
-  private _meetingTime?: Date;
+  private _meetingTime?: string;
   private _regularString?: string;
   private _optionalDate?: Date;
   private _additionalProperties?: Map<string, any>;
 
   constructor(input: {
     createdAt: Date,
     birthDate?: Date,
-    meetingTime?: Date,
+    meetingTime?: string,
     regularString?: string,
     optionalDate?: Date,
     additionalProperties?: Map<string, any>,
@@ -31,8 +31,8 @@ exports[`Marshalling preset date unmarshal should convert date-formatted string
   get birthDate(): Date | undefined { return this._birthDate; }
   set birthDate(birthDate: Date | undefined) { this._birthDate = birthDate; }
 
-  get meetingTime(): Date | undefined { return this._meetingTime; }
-  set meetingTime(meetingTime: Date | undefined) { this._meetingTime = meetingTime; }
+  get meetingTime(): string | undefined { return this._meetingTime; }
+  set meetingTime(meetingTime: string | undefined) { this._meetingTime = meetingTime; }
 
   get regularString(): string | undefined { return this._regularString; }
   set regularString(regularString: string | undefined) { this._regularString = regularString; }
@@ -82,7 +82,7 @@ exports[`Marshalling preset date unmarshal should convert date-formatted string
       instance.birthDate = obj[\\"birthDate\\"] == null ? undefined : new Date(obj[\\"birthDate\\"]);
     }
     if (obj[\\"meetingTime\\"] !== undefined) {
-      instance.meetingTime = obj[\\"meetingTime\\"] == null ? undefined : new Date(obj[\\"meetingTime\\"]);
+      instance.meetingTime = obj[\\"meetingTime\\"];
     }
     if (obj[\\"regularString\\"] !== undefined) {
       instance.regularString = obj[\\"regularString\\"];