This document discusses the challenges of adding type checking to JavaScript code using Flow. It notes that adding types revealed errors in the code and documentation. It also discusses challenges like defining types for third party libraries, refactoring code without unintended consequences, handling null values, and getting organizational buy-in for the new requirements of using a type system. The document emphasizes that while challenging, adding types is worthwhile to improve the scalability and maintenance of the codebase.

1. Flow for JavaScript
Imposing structure on a freeform world
Ikai Lan
@ikai

2. About me
• Ikai Lan, new to Medium, new to JavaScript
• … hopefully not new to programming
• Based out of San Francisco, but I love New York
City
•
Favorite emoji: 😐

3. Here tonight

4. Platform engineering

5. Why type checking?

6. “I want to build a
house … ”

7. “… so I got some raw materials,
and I built one.”

8. More people want to
move in …

9. Now you need some
rules, before things get
out of hand…

10. The array that wasn’t.
// Before the fix
getLatestPosts(userId) {
if (!userId) {
return Q.resolve(null)
}
// More code here to fetch posts and
// return a Promise
}

11. The array that wasn’t.
// Somewhere several layers up
// the stack
let result = client.getLatestPosts(currentUserId)
result.forEach((value) => { ... })

12. The array that wasn’t.
// Somewhere several layers up
// the stack
let result = client.getLatestPosts(currentUserId)
result.forEach((value) => { ... })
Uncaught TypeError: Cannot read property 'foreach' of
null(…)

13. The array that wasn’t.
getLatestPosts(userId) {
if (!userId) {
return Q.resolve([])
}
// More code here to fetch posts and
// return a Promise
}

14. The array that wasn’t.
getLatestPosts(userId) {
if (!userId) {
return Q.resolve([])
}
// More code here to fetch posts and
// return a Promise
}
[]

15. Yet, the docs …
/**
* @return {Promise<Array<Post>>} A sample of
* the user's posts
*/
getLatestPosts(userId) {
if (!userId) {
return Q.resolve(null)
}
// More code here to fetch posts and
// return a Promise
}

16. Yet, the docs …
/**
* @return {Promise<Array<Post>>} A sample of
* the user's posts
*/
getLatestPosts(userId) {
if (!userId) {
return Q.resolve(null)
}
// More code here to fetch posts and
// return a Promise
}
/**
* @return {Promise<Array<Post>>} A sample of
* the user's posts
*/

17. Without automatic checks,
there is decay …

18. I want an object!
- var recommendedPostRelationsPromise =
this._postUserService.getVotesForUserId(followedUserId,
recommendedSince)
+ var recommendedPostRelationsPromise =
this._postUserService.getVotesForUserId(followedUserId,
{votedAfter: recommendedSince})

19. I want an object!
- var recommendedPostRelationsPromise =
this._postUserService.getVotesForUserId(followedUserId,
recommendedSince)
+ var recommendedPostRelationsPromise =
this._postUserService.getVotesForUserId(followedUserId,
{votedAfter: recommendedSince})

20. What if that value is
undefined?
/**
* @returns an Array of only recent votes
*/
getVotesForUserId(userId, filterParams) {
// Limit results returned to items greater
// than this parameter
return queryForVotesAfter(
filterParams.recommendedSince)
}

21. This isn’t horror story
hour

22. Closure Flow
Google Facebook
Type annotations in docs Type annotations inline
Valid JavaScript Requires transformation
Convert entire codebase File-by-file

23. Closure Flow
Google Facebook
Type annotations in docs Type annotations inline
Valid JavaScript Requires transformation
Convert entire codebase File-by-file

24. How do we add types?
‘use strict’ // @flow
First line of a file to annotate

25. Flow annotated JavaScript
buildQuery(path, options) {
buildQuery(path: string,
options: GoSocialRequestOptions): string {

26. Flow annotated JavaScript
buildQuery(path, options) {
buildQuery(path: string,
options: GoSocialRequestOptions): string {
Parameter types

27. Flow annotated JavaScript
buildQuery(path, options) {
buildQuery(path: string,
options: GoSocialRequestOptions): string {
Return type

28. Lint
Flow
Test

29. Lint
Flow
Test
Which methods in files with @flow
are missing annotations?

30. Lint
Flow
Test
Do the types match up? Do they
make sense?

31. server/graph/common/goSocialClient.js:382
382: .then((result: any): Array<T> => {
^^^^^^^^ array type. This type is incompatible with
12: onFulfill?: (value: R) => KewPromise<U> | U,
^^^^^^^^^^^^^^^^^ union: type application of identifier
`KewPromise` | type parameter `U` of call of method `then`. See lib: style-guide/flow-interfaces.js:
12
Member 1:
12: onFulfill?: (value: R) => KewPromise<U> | U,
^^^^^^^^^^^^^ type application of identifier `KewPromise`. See
lib: style-guide/flow-interfaces.js:12
Error:
382: .then((result: any): Array<T> => {
^^^^^^^^ array type. This type is incompatible with
12: onFulfill?: (value: R) => KewPromise<U> | U,
^^^^^^^^^^^^^ KewPromise. See lib: style-guide/flow-
interfaces.js:12
Member 2:
381: return this.request(requestData)
^ type parameter `U` of call of method `then`
Error:
382: .then((result: any): Array<T> => {
^^^^^^^^ array type. This type is incompatible with
373: fetchObjects<T: RpcSchema>(Ctor: Class<T>, options: GoSocialRequestOptions): Promise<T> {
^ some incompatible instantiation of `T`
When flow complains …

32. Lint
Flow
Test
Do the unit and functional tests
still pass? Manual poking

33. type GoSocialRequestOptions = {
method?: string,
requestType?: string,
type?: string,
path?: string,
udpEvent?: Object,
shape?: string,
query?: Object,
properties?: Object,
}
{} as a parameter

34. What makes this project challenging?

35. We needed to figure out
the dependency graph.

36. LoginService
AuthManager
UserManager
Depends on …
Depends on …
Why the dependency graph
matters

37. Our graph 😭 😭 😭

38. The method docs are out of date.

39. Remember this?
/**
* @return {Promise<Array<Post>>} A sample of
* the user's posts
*/
getLatestPosts(userId) {
if (!userId) {
return Q.resolve(null)
}
// More code here to fetch posts and
// return a Promise
}

40. We have to define interfaces for
third party libraries

41. // Source: https://github.com/moment/moment/blob/develop/moment.d.ts
declare class Moment {
subtract(val: number, unit: string): this;
add(amount: number, unitOfTime: string): this;
diff(b: Moment, unitOfTime?: string, round?: boolean): number;
startOf(unit: string): this;
valueOf(): number;
}
declare module 'moment' {
declare function utc(): Moment;
declare function exports(): Moment;
}

42. Mistakes are buried
layers deep - changes need to
be made that don’t result in
unintended consequences

43. OCaml 😐

44. One more thing: nulls.

45. create(tag: Tag): Promise<?Tag>
This value is NOT allowed to be null

46. create(tag: Tag): Promise<?Tag>
This value is allowed to be null!

47. create(tag: Tag): Promise<Tag> {
let tag = null;
if (someCondition) {
tag = new Tag()
}
return Q.resolve(tag)
}
No ‘?’ to show that return type is nullable
ERROR

48. create(tag: Tag): Promise<?Tag> {
let tag = null;
if (someCondition) {
tag = new Tag()
}
return Q.resolve(tag)
}
‘?’ shows that return type is nullable
Correct!

49. Now everything this touches
• Has to null check (via a conditional) - subtle
changes in how code works
• Or accept a type ?Tag, which means “nullable
type”
• Adding to existing code can be tricky without
introducing subtle changes

50. But this is also good
• Makes us really think about which methods will
always have a valid object, which will not
• Will lead to better API design long term

51. But it can be confusing
function myNullableString(input: ?string): number {
return input.length;
}
function callerOfMyNullableString(input: string): number {
return myNullableString(input);
}

52. function myNullableString(input: ?string): number {
return input.length;
}
function callerOfMyNullableString(input: string): number {
return myNullableString(input);
}
input: ?string
input: string
This is valid

53. This is not valid
function myArray(input: Array<?string>): number {
return input.length;
}
function callerOfMyArray(input: Array<string>): number
{
return myArrayWithNullableObjects(input);
}

54. Here’s why
function myArray(input: Array<?string>): number
{
input.append(null);
return input.length;
}
function callerOfMyArray(input: Array<string>): number {
return myArrayWithNullableObjects(input);
}
No longer valid!

55. Organizational challenges
• General organization buy-in
• Flow is almost an entirely new language that
people need to learn
• Working against a moving target
• Funny things that happen after merges

56. To recap
• We are finding it hard to scale development
without types
• Adding types to untyped code has a number of
challenges, technical and otherwise
• We believe the payoff will be totally worth it.

57. Thank you!
• Thanks to Kelly, Nick, Gianni for being great
teammates and teaching me everything
• Thanks to Madeline for organizing this great
event!
• Image source: unsplash.com

58. Q&A
• If you come up with someone, just ask one of us!
• Twitter/Medium: @ikai