@ama-sdk/schematics 9.1.0-alpha.25 → 9.1.0-alpha.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ama-sdk/schematics",
-  "version": "9.1.0-alpha.25",
+  "version": "9.1.0-alpha.26",
   "description": "Swagger specification SDK Generator by schematics",
   "scripts": {
     "nx": "nx",
@@ -41,7 +41,7 @@
     }
   },
   "peerDependencies": {
-    "@ama-sdk/core": "^9.1.0-alpha.25",
+    "@ama-sdk/core": "^9.1.0-alpha.26",
     "@angular-devkit/core": "~16.0.5",
     "@angular-devkit/schematics": "~16.0.5",
     "@angular-devkit/schematics-cli": "~16.0.5",
@@ -52,7 +52,7 @@
   "dependencies": {
     "@angular-devkit/core": "~16.0.5",
     "@angular-devkit/schematics": "~16.0.5",
-    "@o3r/dev-tools": "^9.1.0-alpha.25",
+    "@o3r/dev-tools": "^9.1.0-alpha.26",
     "js-yaml": "^4.1.0",
     "minimatch": "^9.0.0",
     "rxjs": "^7.8.1",
@@ -61,14 +61,14 @@
     "tslib": "^2.5.3"
   },
   "devDependencies": {
-    "@ama-sdk/core": "^9.1.0-alpha.25",
+    "@ama-sdk/core": "^9.1.0-alpha.26",
     "@angular-devkit/schematics-cli": "~16.0.5",
     "@angular-eslint/eslint-plugin": "~16.0.3",
     "@angular/cli": "~16.0.5",
     "@nx/jest": "~16.5.0",
-    "@o3r/build-helpers": "^9.1.0-alpha.25",
-    "@o3r/eslint-plugin": "^9.1.0-alpha.25",
-    "@o3r/schematics": "^9.1.0-alpha.25",
+    "@o3r/build-helpers": "^9.1.0-alpha.26",
+    "@o3r/eslint-plugin": "^9.1.0-alpha.26",
+    "@o3r/schematics": "^9.1.0-alpha.26",
     "@openapitools/openapi-generator-cli": "~2.7.0",
     "@schematics/angular": "~16.0.5",
     "@types/jest": "~29.5.2",

package/schematics/typescript/shell/templates/base/readme.md

@@ -109,11 +109,95 @@ You can build and run UT with:
 yarn test
 ```
 
-## Vendor extensions
+## Manage dates
+
+### The timezone issue
+Managing dates with timezones has always been a bit painful in front end applications.
+Let's give a concrete example to understand the problem:
+An API returns the date and hour of your flight in the timezone of the airport location. In our use case, let's say the departure airport is on GTM+7 : 2023-07-10T00:37:00.000+07:00.
+The timezone sent is the one from the airport, here GMT+7. If you just use the Date(), the computer browser will convert this in its own timezone.
+For example, if the user is in GMT+2 you will end up displaying the following: 2023-07-09T19:37:00.000+02:00.
+This is not what you want. You want the exact date time of the flight at the airport timezone, not the one of your user's computer.
+However, there might be cases where you might still need the timezone information.
+For example, you want to be able to display that the flight is in X hours.
+You will need to compute this information with the two timezones -- the airport's and the user's.
+
+### Solution proposed to remove the timezone: utils.DateTime
+We have introduced the utils.Date object to replace the Date implementation and ignore the timezone.
+As we need to get rid of the timezones more often than not, this will be our default behavior.
+By default, the Date models are replaced with utils.Date.
+
+When we need to keep the timezone information, we create a new field directly in the SDK.
+As this field does not exist in the specification, it will not be part of the base model but of the core model instead.
+
+Simple example:
+```yaml
+  Flight:
+    type: "object"
+    required:
+      - departureDateTime
+    properties:
+      departureDateTime:
+        type: string
+        format: date-time
+```
+Base model generated
+```typescript
+// flight.ts generated in base models
+export interface Flight {
+  /** @see utils.DateTime */
+  departureDateTime: utils.DateTime;
+}
+```
+You need to create a core model to store the timezone information (src/models/core/flight.ts):
+```typescript
+import type { IgnoreEnum } from '@ama-sdk/core';
+import type { Flight } from '../../base/flight/flight';
+export type FlightStopCoreIfy<T extends IgnoreEnum<Flight>> = T & {
+  /** Departure date time of the flight considering timezone */
+  departureDateTimeConsideringTimezone?: Date;
+};
+```
+
+And an associated reviver (src/models/core/flight.reviver.ts):
+```typescript
+import type { Flight } from '../../base/flight/flight';
+import type { reviveFlight } from '../../base/flight/flight.reviver';
+import type { FlightCoreIfy } from './flight';
+
+/**
+ * @param baseRevive
+ */
+export function reviveFlightFactory<R extends typeof reviveFlight>(baseRevive: R) {
+  const reviver = <T extends Flight = Flight>(data: any, dictionaries?: any) => {
+    const originalData: any = {...data};
+    const revivedData = baseRevive<FlightCoreIfy<T>>(data, dictionaries);
+    if (!revivedData) {
+      return;
+    }
+    revivedData.departureDateTimeConsideringTimezone = originalData.departureDateTimeConsideringTimezone && new Date(originalData.departureDateTimeConsideringTimezone)
+      || originalData.departureDateTime && new Date(originalData.departureDateTime);
+    return revivedData;
+  };
+  return reviver;
+}
+```
+
+And export it here (src/models/core/flight/index.ts):
+```typescript
+export * from './flight';
+export * from './flight.reviver';
+```
+
+And here (src/models/core/index.ts):
+```typescript
+export * from './flight/index';
+```
 
-These are some of the available configurations using vendor extensions in the swagger spec
+You can now use departureDateTimeConsideringTimezone to access the timezone information.
+See [utils.Date](https://github.com/AmadeusITGroup/otter/blob/main/packages/%40ama-sdk/core/src/fwk/date.ts) for more information.
 
-### Manage timezone in date
+### How to keep the timezone (prevent Date replacement with utils.Date)
 
 In order to add the timezone to your timestamp property you can add the x-date-timezone extension in your yaml, for example: