Update and structure validator API

[thetutlage]

Discussion thread for Validator API changes.

From

schema.create({
  title: schema.string({ trim: true }, [rules.unique({ table: 'posts', column: 'title' })]),
  slug: schema.string({ trim: true }, [rules.unique({ table: 'posts', column: 'slug' })]),
  excerpt: schema.string.optional(),
  content: schema.string.optional(),
  description: schema.string.optional(),
})

To

schema.create({
  title: schema.string([ 
    modifiers.trim(),
    modifiers.escape(),
    modifiers.casefy('titleCase'),
    rules.minLength(4),
    rules.unique({ table: 'posts', column: 'title' })
  ]),
  slug: schema.string([ 
    modifiers.trim(), 
    modifiers.slugify({ table: 'posts', column: 'slug' }), 
    rules.unique({ table: 'posts', column: 'slug' })
  ]),
  excerpt: schema.string.optional(),
  content: schema.string.optional(),
  description: schema.string.optional(),
})

Full Rendered Proposal
Original PR

[thetutlage]

@bitkidd. What you think about moving optional and allowNull also to rules.

schema.create({
  title: schema.string([
    rules.allowNull(),
    rules.optional(),
  ]),
})

If we go with the current API, then allowNull will implemented as follows.

schema.create({
  title: schema.string.optional.allowNull(),
})

I think, either we should have chain-able API or everything should be moved to rules.

[bitkidd]

That is a great idea and makes optional more predictable and easily discoverable.

[thetutlage]

Someone wondering, why not create a chainable API. For example:

title: schema
  .string()
  .trim()
  .escape()
  .casefy('titleCase')
  .minLength(4)
  .unique({ table: 'posts', column: 'title' })

The issue with this approach is composibility. How will you extract these rules to its own variable and then apply them on different schemas?

With existing API (an array of rules), we can compose rules as follows.

const optionalString = [
  rules.optional(),
  rules.allowNull()
]

And then mix it as follows.

title: schema.string([
  ...optionalString,
  rules.escape()
])

[bitkidd]

Yes, another problem that I see with chainable API is inability to understand right away what the method does, does it mutate the value or just validate, for example for the Date schema we can have two .format methods, one can validate the format and ask the user to provide exact one, another may mutate the date to an expected format. This leads to a strict convention about the naming of the methods, that basically replicates the same division into rules and modifiers.

[RomainLanz]

We already discussed in private with the core team how we could make the Validator API better. And this RFC is in line with our thought.

I believe an array syntax like propose can be the best for the DX in terms of visibility. It also allows the developer to easily extract rules, add them dynamically, or even create inline rules.

As @targos said in the PR, we should also see how we can help the developer know what rules/modifiers are for what types.

I do not know if there is a typing system we can do to solve this. For the moment, I believe having a sub-object with the type under rules, and modifiers is the most straightforward solution.

title: schema.string([
  rules.common.optional()
  rules.common.allowNull()
  modifiers.string.trim()
])

[thetutlage]

Alright, so we don't have any push back on not making these changes. I believe, I have to dig a little into the code myself, since some of the changes needs a better integration with TypeScript. For example:

When someone uses the rule rules.allowNull, the field should be a union of schemaType | null. So basically, rules will have the power to mutate the type of the field.

@bitkidd You okay if I go ahead and start the modification process?

[bitkidd]

Yes, sure, If I can help somehow with this, I'm ready :)