How we use TypeScript at IO.italia.it

1. FEDERICO FEROLDI ● TS-CONF 2019

3. PASSIVE
GOVERNMENT

4. PROACTIVE
GOVERNMENT

5. LEARN MORE AT IO.ITALIA.IT

6. 60+K
LINES OF CODE
30+
CONTRIBUTORS
1700+
PULL REQUESTS
100%
OPEN SOURCE

7. APP BACKEND PLATFORM API
EMAIL
HIGH LEVEL
ARCHITECTURE
PUBLIC
ADMINISTRATION
BANK OR
PAYMENT PROCESSOR

8. WHY TYPESCRIPT?

9. FULLSTACK
MOBILE
REACT-NATIVE
WEB
REACT
BACKEND
NODEJS, EXPRESS, AZURE FUNCTIONS
TOOLING
NODEJS

10. – nobody ever
“I love when we discover
bugs in production.”
LESS BUGS

11. SELF DOCUMENTING

12. IO-APP
REACT-NATIVE
IO-ONBOARDING
REACT
IO-BACKEND
NODEJS, EXPRESS
IO-FUNCTIONS
AZURE FUNCTIONS
IO-FUNCTIONS-COMMONS
SHARED FUNCTIONS CODE
IO-TS-COMMONS
SPECIALIZED TYPES, TYPE SAFE REQUEST/RESPONSES, RETRIABLE TASKS, POT DATA
IO-SPID-COMMONS
SHARED SPID CODE
IO-PAGOPA-COMMONS
SHARED SPID CODE
IO-TS
RUNTIME AND COMPILE TIME TYPES
FP-TS
OPTION, EITHER, ETC…
ARCHITECTURE

13. TYPESAFE REST
CLIENT/SERVER

14. TYPESAFE REQUESTS
AND RESPONSES
+ OPENAPI SPECSgen-api-models
IO-TS MODELS + REQUEST TYPES
TYPED CLIENT TYPED SERVER
GENERATES
TYPESCRIPT CODE
RUNTIME INSTANCES

15. PAYLOAD
(SWAGGER)
CreatedMessageWithContent:
type: object
properties:
id:
type: string
fiscal_code:
$ref: "#/FiscalCode"
time_to_live:
$ref: "#/TimeToLiveSeconds"
created_at:
$ref: "#/Timestamp"
content:
$ref: "#/MessageContent"
sender_service_id:
type: string
required:
- id
- fiscal_code
- created_at
}PROP TYPES
}REQUIRED PROPS

16. import { FiscalCode } from "./FiscalCode";
import { TimeToLiveSeconds } from "./TimeToLiveSeconds";
import { Timestamp } from "./Timestamp";
import { MessageContent } from "./MessageContent";
import * as t from "io-ts";
// required attributes
const CreatedMessageWithContentR = t.interface({
id: t.string, fiscal_code: FiscalCode, created_at: Timestamp,
content: MessageContent, sender_service_id: t.string
});
// optional attributes
const CreatedMessageWithContentO = t.partial({ time_to_live: TimeToLiveSeconds
});
export const CreatedMessageWithContent = t.exact(
t.intersection([CreatedMessageWithContentR, CreatedMessageWithContentO],
"CreatedMessageWithContent"));
export type CreatedMessageWithContent = t.TypeOf<
typeof CreatedMessageWithContent
>;
PAYLOAD
(IO-TS)
}TYPE
DEPENDENCIES
RUNTIME
TYPE
COMPILE TIME TYPE

17. OPERATION
(SWAGGER)
"/messages/{id}":
parameters:
- name: id
in: path
type: string
required: true
get:
operationId: getUserMessage
responses:
"200":
schema:
$ref: "#/definitions/CreatedMessageWithContent"
"400":
schema:
$ref: "#/definitions/ProblemJson"
"404":
schema:
$ref: "#/definitions/ProblemJson"
"429":
}PATH PARAMETER
}RESPONSES
OPERATION NAME

18. OPERATION
(SERVER)
public readonly getMessage = (
req: express.Request
): Promise<
| IResponseErrorInternal
| IResponseErrorValidation
| IResponseErrorNotFound
| IResponseErrorTooManyRequests
| IResponseSuccessJson<CreatedMessageWithContent>
>
}RESPONSES
STATUS AND
PAYLOAD TYPE
interface IResponse<T> {
readonly kind: T;
readonly apply: (response: express.Response) => void;
readonly detail?: string;
}
DISCRIMINATES RESPONSE
TYPE (STATUS)
GENERATES EXPRESS
HTTP RESPONSE
EXTRA INFO FOR LOGGING

19. OPERATION
(SERVER)
function toExpressHandler<T>(
handler: (req: express.Request) => Promise<IResponse<T>>
): (req: express.Request, res: express.Response) => void {
return (req, res) =>
handler(req).then(response => response.apply(res));
}
TYPE SAFE
CONTROLLER
RUNS CONTROLLER FOR
HTTP REQUEST
APPLIES IResponse TO
HTTP RESPONSE

20. GENERIC
OPERATION
(CLIENT)
interface IBaseApiRequestType<
M extends RequestMethod,
P,
H extends RequestHeaderKey,
Q extends string,
R> {
readonly method: M;
readonly url: (params: P) => string;
readonly query: (params: P) => RequestQuery<Q>;
readonly headers: RequestHeaderProducer<P, H>;
readonly response_decoder: ResponseDecoder<R>;
}
“GET” | “POST” | “PUT” | “DELETE”
INPUT PARAMETERS
DECODES RAW HTTP RESPONSE

21. GENERIC
RESPONSE
DECODER
(CLIENT)
type ResponseDecoder<R> = (response: Response) =>
Promise<t.Validation<R> | undefined>;
COMPILE TIME DESCRIPTION
OF A RESPONSE
interface IResponseType<S extends number, T> {
readonly status: S;
readonly value: T;
}
IO-TS VALIDATION RESULT OF DECODING
RAW HTTP RESPONSE

22. OPERATION
(CLIENT)
// Request type definition
export type GetUserMessageT = r.IGetApiRequestType<
{ readonly id: string; readonly Bearer: string },
"Authorization",
never,
| r.IResponseType<200, CreatedMessageWithContent>
| r.IResponseType<400, ProblemJson>
| r.IResponseType<401, undefined>
| r.IResponseType<404, ProblemJson>
| r.IResponseType<429, ProblemJson>
| r.IResponseType<500, ProblemJson>
>;
INPUT PARAMS
OPERATION NAME
}RESPONSES
STATUS AND
PAYLOAD TYPE
REQUIRED
HEADERS

23. RESPONSE
DECODER
(CLIENT)
DECODES RAW HTTP
RESPONSE, RETURNS
UNION OF RESPONSE
STATUS AND PAYLOADS

24. OPERATION
DEFINITION
(CLIENT)
DYNAMIC URL FROM
TYPED INPUT PARAMS
MUST TYPE CHECK
AGAINST REQUEST
TYPE
const getMessageT: GetUserMessageT = {
method: "get",
url: params => `/api/v1/messages/${params.id}`,
query: _ => ({}),
headers: tokenHeaderProducer,
response_decoder: getUserMessageDefaultDecoder()
};
DEFAULT RUNTIME
RESPONSE DECODER
USED TO GENERATE
CLIENT METHOD AT
RUNTIME

25. OPERATION
CLIENT
CREATES CLIENT FROM RUNTIME DEFINITION
TYPED INPUT
PARAMS IO-TS VALIDATION
ERRORS
UNION OF RESPONSE
TYPES AND PAYLOADS

26. TYPE REFINEMENTBY
FILTERING ON
RESPONSE STATUS
DISCRIMINTED UNION
ON STATUS
TYPE === ProblemJson
TYPE === CreatedMessageWithContent

27. • SERVER AND CLIENT FROM SAME OPENAPI SPEC
• ENCODER AND DECODER FROM SINGLE IO-TS TYPE
• TYPE CHECKED RESPONSES IN SERVER
• TYPE CHECKED REQUEST PARAMETERS IN CLIENT
• RICH RESPONSE TYPE WITH ALL STATUS AND PAYLOADS
• TYPE REFINEMENT BY FILTERING ON RESPONSE STATUS
BENEFITS

28. HANDLING STATES
OF REMOTE DATA

29. None NoneLoading Some<T>
NoneError<E>NoneUpdating<T>
SomeLoading<T>
SomeError<T, E>SomeUpdating<T>
OPTIONAL VALUE WITH
LOADING STATES
type Pot<T, E> =
None | NoneLoading | NoneUpdating<T> | NoneError<E> |
Some<T> | SomeLoading<T> | SomeUpdating<T> | SomeError<T, E>;
CONTAINED
VALUE
ERROR
toLoading toLoading
toLoading
toLoading
toUpdating
toUpdating
toUpdating toUpdating
toError toError
toError
toError

30. EXAMPLE
REACT
type State = {
calendars: pot.Pot<ReadonlyArray<Calendar>, ResourceError>;
};
<Content style={styles.content}>
{pot.isLoading(calendars) && <Text>Loading...</Text>}
{pot.isError(calendars) && <Text>{calendars.error}</Text>}
{pot.isSome(calendars) && (
{calendars.value.map(calendar => (
<CalendarItem
key={calendar.id}
calendar={calendar}
/>
))}
LOADING STATE, NO DATA
ERROR STATE
LOADED STATE, DATA AVAILABLE

31. • ENCAPSULATES STATES OF REMOTE DATA
• SENSIBLE STATE TRANSITIONS
• USEFUL FOR HANDLING STATES IN UI (isLoading, isUpdating, …)
• HELPERS: MAP, FOLD, TOOPTION, TOUNDEFINED
• STORES PREVIOUS VALUE IN CASE OF ERROR (ROLLBACK)
BENEFITS

32. TAGGED IO-TS TYPES

33. type Tagged<T, A, O = A, I = t.mixed> = t.Type<A & T, O & T, I>;
const tag = <T>() => <A, O = A, I = t.mixed>(
type: t.Type<A, O, I>
): Tagged<T, A, O, I> => type as any;
TAG BASE TYPE

34. interface IPatternStringTag<P extends string> {
readonly pattern: P;
readonly kind: "IPatternStringTag";
}
const PatternString = <P extends string, T extends IPatternStringTag<P>>(
p: P
): Tagged<T, string> =>
tag<T>()(
t.refinement(
t.string,
s => s.match(p) !== null,
`string that matches the pattern "${p}"`
)
);
type PatternString<P extends string> = string & IPatternStringTag<P>;
TYPED STRING
PATTERN

35. TYPED STRING
PATTERN
const FiscalCode = PatternString(
"^[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z]
[0-9LMNPQRSTUV]{3}[A-Z]$"
);
export type FiscalCode = t.TypeOf<typeof FiscalCode>;

36. interface IWithinRangeNumberTag<L extends number,
H extends number> {
readonly lower: L;
readonly higher: H;
readonly kind: "IWithinRangeNumberTag";
}
const WithinRangeNumber = <L extends number, H extends number,
T extends IWithinRangeNumberTag<L, H>
>(
l: L,
h: H
): Tagged<T, number> =>
tag<T>()(
t.refinement(t.number, s => s >= l && s < h, `number >= ${l} and < ${h}`)
);
type WithinRangeNumber<L extends number, H extends number> = number &
IWithinRangeNumberTag<L, H>;
TYPED NUMBER
IN RANGE

37. LINTING

38. SHARED TSLINT RULES PACKAGE (IO-TSLINT-RULES)
TSLINT
SHARED RULES
{
"defaultSeverity": "error",
"extends": [
"italia-tslint-rules/strong"
]
}

39. TSLINT
CUSTOM RULES
1) TYPE CHECK ON YIELD RETURN VALUE
TSLINT WILL CHECK THAT THESE TWO
TYPES ARE COMPATIBLE
2) ERROR ON TSLINT-DISABLE

40. LEARNING / GOTCHAS

41. • DEVELOPERS WILL FALL BACK TO “ANY”
• DEVELOPERS WILL DISABLE TSLINT (SEE CUSTOM RULE)
• @TYPES VERSION MISMATCH (WILL HAVE CORRECT TYPES?)
• LONG BUILD TIMES (TSLINT + TSC + JEST)
• INTEROP WITH PURESCRIPT?
TYPESCRIPT

42. • AWESOME FOUNDATION
• QUICK WINS (OPTION, EITHER)
• HARD TO MASTER FUNCTIONAL PARADIGMS (BETTER INTRO?)
• DO NOT MIX VERSIONS!!! (USE yarn-deduplicate)
IO-TS / FP-TS

43. THANK YOU
• FOLLOW US @TEAMDIGITALEIT @PAGOPA #PROGETTOIO
• EXPLORE GITHUB.COM/TEAMDIGITALE
• PRs WELCOME! (DOCUMENTATION, TESTS, FP IDIOMS)
• WE ARE HIRING: PAGOPA.GOV.IT