Type system: Limited or complete

[jamiebuilds]

So with the type system inside of dx we have three options:

1. Use a limited subset of Flow/TypeScript easily expressed by dx - tags:
2. Create our own type system using dx - tags:
3. Borrow Flow's /*:: comment type syntax */

I think to start it'd probably be best to just use a limited subset, and in the future we can add support for Flow's comment syntax as a standalone thing. I don't think that we should create our own type system.

[jamiebuilds]

The only problem with this is object types, which we need to have but basing it off the existing JSDoc syntax is a lot of work for something that looks crappy in the end:

class Project {
  // Assign the project to an employee.
  // - param: `employee` `Object` - The employee who is responsible for the project.
  // - param: `employee.name` `string` - The name of the employee.
  // - param: `employee.department` `string` - The employee's department.
  assign(employee) {
    // ...
  }
}

And you can't simply create an object syntax because it won't let you document properties:

class Project {
  // Assign the project to an employee.
  // - param: `{ name: string, department: string }` `employee` - The employee who is responsible for the project.
  assign(employee) {
    // ...
  }
}

It's fine in Flow or TypeScript because we can do:

// The employee who is responsible for the project.
interface Employee {
  // The name of the employee.
  name: string;
  // The employee's department.
  department: string;
}

class Project {
  // Assign the project to an employee.
  // - param: The employee who is responsible for the project.
  assign(employee: Employee) {
    // ...
  }
}

Maybe it's worth creating our own way to declare interfaces?

Or maybe we should suck it up and use the JSDoc-like syntax

[tmcw]

I really dislike the JSDoc style here, in large part because, despite representing a list, it doesn't actually require any kind of order. So properties of an object might be defined after another param.

As a middle point, we could nest properties as nested lists:

class Project {
  // Assign the project to an employee.
  // - param: `employee` `Object` - The employee who is responsible for the project.
  //   - `.name` `string` - The name of the employee.
  //   - `.department` `string` - The employee's department.
  assign(employee) {
    // ...
  }
}

[anandthakker]

I'm mostly 👍 on a barebones nested-list approach to object types if dx is going to have its own type system.

Couple other questions about that prospect, though:

• Would it be able to express Array<specific object type>? If so, we might need some sort of typedef mechanism, in order to define/document an array's item type (and avoid redundancy documenting nested object property types).
• Would it be able to express nullable/maybe types?
• How about an any type?
• Would having such a type system inevitably lead to the expectation that the dx parser (or a companion module) could typecheck code against the documented types?

It's so easy for a home grown type system to become a rabbit hole... I lean slightly towards thinking that dx itself should only support JS primitives and namepath-addressable classes, and if you want more, you have to use typescript or flow (or flow comments).

[jamiebuilds]

I'm tempted more and more to make dx require TypeScript or Flow

[tmcw]

Yep, that's where I'm thinking too - from #2 -

In Flow files, interpret 'documentation types' as Flow syntax, and in TypeScript, the same. In normal javascript files, the default should be Flow.

Maybe there shouldn't be an opinionated default like that and you should be required to choose one or the other, but anyway - would love to avoid inventing yetanothertypesystem.

[jamiebuilds]

We could always start with Flow/TypeScript and add support for JavaScript later