fix: use intersection for DateTime, DateTimeOffset type definitions (#373)

Author: Waleed-KH

docs/reference/dates.md

@@ -3,8 +3,8 @@
 
 | C# Type          | JS Type     |
 |------------------|--------------------------------------------------------|
-| `DateTime`       | `Date \| { kind?: 'utc' \| 'local' \| 'unspecified' }` |
-| `DateTimeOffset` | `Date \| { offset?: number }`                          |
+| `DateTime`       | `Date & { kind?: 'utc' \| 'local' \| 'unspecified' }` |
+| `DateTimeOffset` | `Date & { offset?: number }`                          |
 | `TimeSpan`       | `number` (milliseconds)                                |
 
 ## JS Date / .NET DateTime & DateTimeOffset
@@ -30,7 +30,7 @@ interoperability, both types of .NET values are convertible to and from JS `Date
 accomplished by adding either a `kind` or `offset` property to a regular `Date` object.
 
 ```TypeScript
-type DateTime = Date | { kind?: 'utc' | 'local' | 'unspecified' }
+type DateTime = Date & { kind?: 'utc' | 'local' | 'unspecified' }
 ```
 
 When a .NET `DateTime` is marshalled to a JS `Date`, the date's UTC timestamp value becomes the
@@ -43,7 +43,7 @@ with `Utc` kind. (Defaulting to `Unspecified` would be more likely to result in
 conversions to/from local-time.)
 
 ```TypeScript
-type DateTimeOffset = Date | { offset?: number }
+type DateTimeOffset = Date & { offset?: number }
 ```
 
 When a .NET `DateTimeOffset` is marshalled to a JS `Date`, the UTC timestamp value _without the

src/NodeApi.Generator/TypeDefinitionsGenerator.cs

@@ -746,18 +746,18 @@ interface IDisposable { dispose(): void; }
         if (_emitDateTimeOffset)
         {
             s.Insert(insertIndex, _isSystemAssembly ? @"
-declare namespace js { type DateTimeOffset = Date | { offset?: number } }
+declare namespace js { type DateTimeOffset = Date & { offset?: number } }
 " : @"
-type DateTimeOffset = Date | { offset?: number }
+type DateTimeOffset = Date & { offset?: number }
 ");
         }
 
         if (_emitDateTime)
         {
             s.Insert(insertIndex, _isSystemAssembly ? @"
-declare namespace js { type DateTime = Date | { kind?: 'utc' | 'local' | 'unspecified' } }
+declare namespace js { type DateTime = Date & { kind?: 'utc' | 'local' | 'unspecified' } }
 " : @"
-type DateTime = Date | { kind?: 'utc' | 'local' | 'unspecified' }
+type DateTime = Date & { kind?: 'utc' | 'local' | 'unspecified' }
 ");
         }
     }

test/TestCases/napi-dotnet/complex_types.js

@@ -81,15 +81,15 @@ ComplexTypes.testEnum = enumType.Two;
 assert.strictEqual(ComplexTypes.testEnum, enumType.Two);
 
 // DateTime
-/** @type {Date | { kind: 'utc' | 'local' | 'unspecified' }} */
+/** @type {Date & { kind: 'utc' | 'local' | 'unspecified' }} */
 const dateValue = ComplexTypes.dateTime;
 assert(dateValue instanceof Date);
 assert.strictEqual(dateValue.valueOf(), new Date('2023-04-05T06:07:08').valueOf());
 assert.strictEqual(dateValue.kind, 'unspecified');
 ComplexTypes.dateTime = new Date('2024-03-02T11:00');
 assert.strictEqual(ComplexTypes.dateTime.valueOf(), new Date('2024-03-02T11:00').valueOf());
 assert.strictEqual(ComplexTypes.dateTime.kind, 'utc');
-/** @type {Date | { kind: 'utc' | 'local' | 'unspecified' }} */
+/** @type {Date & { kind: 'utc' | 'local' | 'unspecified' }} */
 const dateValue2 = new Date('2024-03-02T11:00');
 dateValue2.kind = 'local';
 ComplexTypes.dateTime = dateValue2;
@@ -110,15 +110,15 @@ ComplexTypes.timeSpan = (2*24*60*60 + 23*60*60 + 34*60 + 45) * 1000;
 assert.strictEqual(ComplexTypes.timeSpan, (2*24*60*60 + 23*60*60 + 34*60 + 45) * 1000);
 
 // DateTimeOffset
-/** @type {Date | { offset: number }} */
+/** @type {Date & { offset: number }} */
 const dateTimeOffsetValue = ComplexTypes.dateTimeOffset;
 assert(dateTimeOffsetValue instanceof Date);
 // A negative offset means the UTC time is later than the local time,
 // so the offset is added to the local time to get the expected UTC time here.
 assert.strictEqual(dateTimeOffsetValue.valueOf(), Date.UTC(2023, 3, 5, 6, 7, 8) + 90 * 60 * 1000);
 assert.strictEqual(dateTimeOffsetValue.offset, -90);
 assert.strictEqual(dateTimeOffsetValue.toString(), '2023-04-05 06:07:08.000 -01:30');
-/** @type {Date | { offset: number }} */
+/** @type {Date & { offset: number }} */
 const dateTimeOffsetValue2 = new Date(Date.UTC(2024, 2, 2, 1, 0, 0));
 dateTimeOffsetValue2.offset = 120;
 ComplexTypes.dateTimeOffset = dateTimeOffsetValue2;