liveblocks / liveblocks-schema Goto Github PK

Moved to liveblocks/liveblocks#796, for public visibility.

Moved to liveblocks/liveblocks#797, for public visibility.

Since we're in this weird dialect which is a mix of GraphQL and TypeScript, our schema language can currently look inconsistent from both angles, which isn't great. There has been something about the built-in types that has been itching, and I finally can put to words what I'm not happy with. This issue describes that, and offers a solution we can take right now to fix it.

We've been following GraphQL's built-in types and naming conventions for the most part, forcing all type names to start with a capital letter, including the built-in globally available ones:

• String
• Int
• Float
• Boolean
• Null 🤔

These are built-in types in GraphQL. Except that the Null type isn't—GraphQL has no such type. Yet, because I wanted to stick with the convention of using capitalized letters for types, it's now named Null, which is neither a type in GraphQL nor TypeScript 🤔 The spelling with a capital N may thus be surprising and unfamiliar to all users, whether they are familiar with GraphQL or TypeScript.

Definitely the worst of both worlds! 😞

Alternatively, we could swing it completely around and make all the built-in types lowercased, following an approach that would be closer to TypeScript's conventions. It would also play better towards @GuillaumeSalles's preference for adoption over purity long standing desire to be able to copy/paste existing TypeScript types and require fewer changes to the code to make it work.

• string
• number*
• boolean
• null

If we take that approach, we would drop the Int and Float types and instead use the number type from TypeScript. It would replace Float directly, and it would mean we no longer have a type for Int as a built-in, but hang on… I have a proposal for re-introducing it in a more generic way (see below)!

Proposal: switch to lowercased built-ins

The more I think about it, the more I like the idea of using lowercased type names for the built-in types. This matches TypeScript conventions, where all custom types are spelled with a capital, but the built-in scalars are spelled with lowercase.

This also plays better to Guillaume's long standing desire to make it easier to copy/paste existing type definitions from TypeScript (which existing customers already have) and paste them into the schema editor, requiring fewer changes to the syntax than it does currently.

Here is my proposal, that I think would be consistent:

• We remove Int and Float built-in types
• We spell the other built-in types with lowercase, following TypeScript: string, number, boolean, null
• We allow opting-in to a standard library of custom data validators we provide, see propsal below

Proposal: allow opting-in to more data validation types

Besides the built-in types, we could offer more data validation types out of the box, for common scenarios. For example:

• Regexes
• Whole numbers (welcome back, Int 👋)
• Positive numbers
• Numbers within a range
• Email address
• URLs
• ISO8601 date strings
• etc.

It would be a bad idea to make all of those types availalble as globals, mostly because they may conflict with custom types people will add themselves. But, we can offer them as sort of a standard library of "built-in types" which we can offer, and that people can voluntarily opt into if they want even stricter validations.

I'd love to offer some kind of "import" statement, that would allow you to use them in your schema.

use Email, Int, Positive

type Storage {
  amountToWithdraw: Positive
  timestamp: Int
  email: Email
  website: URL  # ❌ Unknown type 'URL', did you mean to import it?
}

(Alternative syntaxes for use <name> could be scalar <name> (which is the GraphQL syntax for this), or import <name>. The latter doens't have the preference, because it's such a departure for TS users.)

What's important is that you cannot just put any name there. You can only import the names from a given list of validators we'll offer as a sort of standard library (and which is publicly documented). I would suggest to use capitalized names for those standard library types. The beauty is that it would no longer make Int an exception case, but a special case of a more generic and future-proof language construct that is very powerful and will be great to use in many apps!

People cannot write their own validators directly (because performance is key and we would always want to review it), but we could offer ways they could contribute to the list eventually since it's open sourced. But we can offer a very rich suite of data validators for common use cases like this, "batteries included" style.

Rollout plan

We introduce one last breaking change now first, before customers are going to be using the language in the wild.

Phase 1 (now, ASAP): Move to lowercased built-ins
We already have a lot of schemas in our DB for testing reasons. We can add a "backward compatible" mode to the parser, that will interpret Int and Float as aliases to the number type, String as an alias to the string type, etc. That mode is then used when parsing existing schemas documents from our DB. But when saving new schema documents, we use a stricter parse mode, which will error on encountering Int, and will suggest to write number instead. This way, new documents will at least not add any maintenance.

It means we temporarily drop support for using Int (whole number) validation, but we'll add back support for that soon, in a much better way!

We'll also update the Schema syntax doc page to match the new syntax.

Phase 2 (during private beta): Offer extra data validators
We'll add support for opting-in to a library of custom data validators we'll offer as a "batteries included" offering. Then, Int is just one of the many custom number validators we'll offer, along with many others, like regexes, numeric range checks, email addresses, URLs, dates, etc etc.