Add cascading calling utils

[xcfox]

What's the problem?

valibot currently only uses a nested methods, which is a little less readable than the chained calls of yup and zod.

Let's define a complex schema:

// zod
const Giraffe = z.object({
  name: z.coerce.string().default("Skyler").catch("unnamed").brand<"Giraffe">(),
  birthday: z.coerce.date().nullable(),
  hobbies : z.string().array().optional(),
});

// valibot
const Giraffe = object({
  name: brand(fallback(optional(coerce(string(), String), "Skyler"), () => "unnamed"), "Giraffe"),
  birthday: nullable(coerce(date(), Date)),
  hobbies: optional(array(string())),
})

The valibot version is less readable for two reasons:

1. It's harder to see the type of each field:

   • The type in zod is close to the field name and at the beginning of the statement.
   • valibot hides string() in the middle of a long sentence.

2. It's harder to understand the meaning of each argument:

   • zod uses chained calls, each argument is close to the method it applies to.
   • valibot uses nested calls, arguments and method names are far apart. For example, it takes a bit of thinking to realize that "Skyler" is the default value, not the fallback value.

What is the solution?

We can add utils for cascading calling to optimize readability:

using chained calls

const Giraffe = object({
  name: from(string())
    .to((it) => coerce(it, String))
    .apply(optional, 'Skyler')
    .apply(fallback, 'unnamed')
    .apply(brand, 'Giraffe')
    .done(),
  birthday: from(date())
    .to((it) => coerce(it, Date))
    .apply((it) => nullable(it))
    .done(),
  hobbies: optional(array(string())),
})

using functional calls

const Giraffe = object({
  name: of(
    optional(string(), 'Skyler'),
    apply(coerce, String),
    apply(fallback, () => 'unnamed'),
    apply(brand, 'Giraffe')
  ),
  birthday: of(nullable(date()), apply(coerce, Date)),
  hobbies: optional(array(string())),
})

This can also be used to add metadata

Cascading calls makes it easy to modify the schema, so we don't have to go through the trouble of implementing the metadata. We just need to add various little methods like fallback():

const Giraffe = object({
  name: of(
    string(),
    apply(describe, "name of the giraffe"),
    apply(index),
    apply(unique),
    apply(columnName, "giraffe_name")
  ),
})

[fabian-hiller]

Thanks for sharing your ideas. @Demivan suggested a different, but kind of similar API to me last week. I will try to investigate both proposals this week.

[xcfox]

Here are some other methods of cascading calling:

Built-in cascading method in schema

const Giraffe = object({
  name: string()
    .to(coerce, String)
    .to(optional, 'Skyler')
    .to(fallback, 'unnamed')
    .to(brand, 'Giraffe')
  birthday: date()
    .to(coerce, Date)
    .to(nullable, it)
  hobbies: array(string()).to(optional),
})

This writing style provides the best readability and DX:

• each type is closely to the field name,
• each argument is closely to the method,
• out-of-the-box chain call.

To implement this, we need to add a to method to each schema. The to method requires only three lines of code, which adds slightly to the size of the base package.

Using pipeline operator

const Giraffe = object({
  name: string()
    |> coerce(%, String)
    |> optional(%, 'Skyler')
    |> fallback(%, 'unnamed')
    |> brand(%, 'Giraffe')
  birthday: date()
    |> coerce(%, Date)
    |> nullable(%, it)
  hobbies: array(string()) |> optional(%),
})

This approach uses the yet-to-be-implemented pipeline operator syntax. This provides great readability. Compared to the Built-in cascading method which needs to show every method called, I think the Built-in cascading method is the best in terms of development experience.
Unfortunately, this proposal is still in stage 2, and it will probably be many years before we can use this method.

[fabian-hiller]

I assume this API design would require a complete rewrite of the library. How would you implement it? How would you make it typesafe? Are you interested in writing a small prof of concept for string, coernce, optional, fallback and brand? You could use the TypeScript or Valibot playground for this.

[xcfox]

Thanks to valibot's good API design, most APIs work perfectly with cascading calling, here is a small prof:

The only exception here is optional, where TypeScript can't correctly derive the type of a function due to its function overloading, and must use the lambda expression.
We also need to make sure that the first parameter of each method is a BaseSchema to ensure that we can pass in to methods, which valibot does!

I also recommend putting the to method directly into BaseSchema for best readability and development experience!

[Demivan]

@xcfox What do you think about API like this?

const Giraffe = object({
  name: pipe(string(),
    coerce(String),
    optional('Skyler'),
    fallback('unnamed'),
    brand('Giraffe')),
  birthday: pipe(date(),
    coerce(Date),
    nullable()),
  hobbies: pipe(array(string()), optional()),
})

I think it is a little bit less verbose. Really similar to your pipeline operator example, but implemented as a function.

[xcfox]

This writeup is in line with valibot's current design thinking, but has two drawbacks:

1. It is less readable

prettier will format the code as follows:

const Giraffe = object({
  name: pipe(
    string(),
    coerce(String),
    optional('Skyler'),
    fallback('unnamed'),
    brand('Giraffe')
  ),
  birthday: pipe(date(), coerce(Date), nullable()),
  hobbies: optional(array(string())),
})

• It does not ensure that the field name and type are always on the same line
• Some types begin with pipe, some do not.

2. The pipe function is quite difficult to implement

look at the four thousand lines of code in ts-functional-pipe

[Demivan]

1.1 It does not ensure that the field name and type are always on the same line

I think it is quite easy to see that name is a string property in your formatted example.

How does your example work with transforms? What if you transform string property into number.

I don't think type validations should even be required in the pipeline. You should be able to just coerce and then run validations on the coerced value. There is no need to validate that type is a string if you run String() on it - it will always be a string.

2. The pipe function is quite difficult to implement

It is not difficult at all. Implementation is exactly one line. :) It just contains 4000 lines of automatically generated types.

[xcfox]

You are right, pipe works better with transform than chaining calls.

[fabian-hiller]

Both API proposals solve function nesting in many cases. I like that! @xcfox where would you put pipe actions like minLength?

@Demivan proposal makes Valibot even more modular, which reduces the bundle size in some cases and allows us to list everything in a logical order inside pipe. Also, pipe would allow us to easily add the metadata feature. One drawback is that the API is sometimes a bit more verbose when you nesting pipes. But overall I think is is readable and I see a lot of advantages.

// Multiple nested pipes
const NameSchema = v.pipe(
  v.optional(v.pipe(v.string(), v.toTrimmed(), v.minLength(1)), 'Skyler'),
  v.brand('Name')
);

// Current Valibot API
const NameSchema = v.brand(
  v.optional(v.string([v.toTrimmed(), v.minLength(1)]), 'Skyler'),
  'Name'
);

// Transform string or number to number
const NumberSchema = v.pipe(
  v.union([v.pipe(v.string(), v.decimal()), v.pipe(v.number(), v.integer())]),
  v.transform(Number)
);

// Current Valibot API
const UnionSchema = v.transform(
  v.union([v.string([v.decimal()]), v.number([v.integer()])]),
  Number
);

// Simple login schema
const LoginSchema = v.object({
  email: v.pipe(v.string(), v.minLength(1), v.email()),
  password: v.pipe(v.string(), v.minLength(8)),
});

// Current Valibot API
const LoginSchema = v.object({
  email: v.string([v.minLength(1), v.email()]),
  password: v.string([v.minLength(8)]),
});

Another cool thing is that pipe has the potential to simplify the mental model. It allows us to remove the pipe arguments from the schema functions. Whenever you want to pipe something into a schema, be it metadata, transformations, or validations, you use pipe. Also, pipe allows us to transform data in-between and calculate the correct input and output type.

const DateSchema = v.pipe(
  v.union([v.string(), v.number(), v.date()]),
  v.transform((input) => new Date(input)),
  v.date(),
  v.minValue(new Date('2000-01-01')),
  v.brand('Birthday'),
  v.description('Text...')
);

I am very grateful for your further ideas and feedback! With currently more than 80K weekly downloads, it is a big decision for me at this point to change the current API, but I will do it if I believe it will benefit most users in the long run.

[xcfox]

I agree with you about pipe method.

Do we keep the current pipe argument for each schema?
Keeping the pipe argument makes the code cleaner in case there is no transform, it also reduces breaking changes

const NumberSchema = v.pipe(
  v.union([v.string([v.decimal()]), v.number([v.integer()])]),
  v.transform(Number),
  v.number()
);

const LoginSchema = v.object({
  email: v.string([v.minLength(1), v.email()]),
  password: v.string([v.minLength(8)]),
});

const DateSchema = v.pipe(
  v.union([v.string(), v.number(), v.date()]),
  v.transform((input) => new Date(input)),
  v.date([v.minValue(new Date('2000-01-01')), v.brand('Birthday'), v.description('Text...')])
);

[fabian-hiller]

I prefer to keep the API to a minimum to make it very clear how to use it. Providing too many ways to achieve the same goal makes it difficult to use a library in the long run. Therefore, I plan to remove the pipe argument.