Note: This package is intended for testing purposes only. It is not suitable for production use.
The SDK contains 2 different parts:
- Auto generated code (based on Swagger Spec)
- Specific code dedicated to this SDK
A main part of the SDK is automatically generated from a Swagger Spec. The following folders contain the generated code:
- src/api: Containing the API calls files
- src/models/base: Models based of swagger definitions
The Code can be regenerated by running the following command:
yarn schematics @ama-sdk/sdk:typescript-core --spec-path [path to your swagger file]
Note that you can use npm exec
instead of yarn
for every command specified in this documentation.
There are 2 places where we can add custom code:
- src/helpers: should contain the helper functions to transform the data.
- src/models/custom: should contain the models specific to this SDK (mainly the helper functions return type).
You can extend a base model in 3 steps:
- Redirect the default model to your override:
// src/models/base/<model name>/index.ts
export * from "../../core/<model name>";
- Indicate to Swagger CodeGen that you have override the base model:
# in .swagger-codegen-ignore
src/models/base/<model name>/index.ts
- Create your core models
// src/models/core/<model name>/index.ts
export * from "./<model name>.ts";
export * from "./<model name>.reviver.ts";
// src/models/core/<model name>/<model name>.ts
import { <model name> as Base<model name> } from "../../base/<model name>/<model name>";
export interface <model name> extends BaseB<model name> {
// Additional fields
}
// src/models/core/<model name>/<model name>.reviver.ts
import { yourFunction } from "../../../helpers/<model name>";
import { revive<model name> as Base<model name> } from "../../base/<model name>/<model name>.reviver";
import { <model name> } from "./<model name>";
import {Reviver, utils} from "@ama-sdk/core";
export function revive<model name><T extends <model name> = <model name>>(data: any, dictionary?: any) {
// TODO: use BaseRevive<T> when ready
const revivedData: T | undefined = Base<model name>(data, dictionary) as T | undefined;
if (!revivedData) { return ; }
if (!revivedData.yourField) {
revivedData.yourField = yourFunction(revivedData);
}
return revivedData;
}
Some commands are provided to keep your SDK up-to-date.
yarn spec:regen
You can build and run UT with:
yarn test
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.
The Otter framework has introduced the utils.Date
and utils.DateTime
objects to replace the Date
implementation and convert the date returned by the API as if it were in the
timezone of the user.
Dates can be generated as utils.Date
or string
depending on the value of the stringifyDate
option. This ensures that the timezone will not impact the date.
In the case of date-time
object, the default type used is string
or native Date
depending on the stringifyDate
option value.
If you want to generate a date-time using utils.DateTime
, you can do it at property level thanks to the x-local-timezone
vendor.
As this field does not exist in the specification, it will not be part of the base model but of the core model instead (the first one being completely generated from the API specifications).
Simple example:
Flight:
type: "object"
required:
- departureDateTime
properties:
departureDateTime:
type: string
x-local-timezone: true
description: If this vendor extension is present send dates without their timezone
format: date-time
Base model generated
// 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):
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):
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):
export * from './flight';
export * from './flight.reviver';
And here (src/models/core/index.ts):
export * from './flight/index';
You can now use departureDateTimeConsideringTimezone to access the timezone information. See utils.Date for more information.