diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b3d614fa4..c2938c7bf 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -171,6 +171,9 @@ importers: rehype-external-links: specifier: ^3.0.0 version: 3.0.0 + sharp: + specifier: ^0.33.2 + version: 0.33.2 tailwindcss: specifier: ^3.4.1 version: 3.4.1 @@ -186,6 +189,9 @@ importers: vite: specifier: ^5.1.3 version: 5.1.3(@types/node@20.11.19) + vite-imagetools: + specifier: ^6.2.9 + version: 6.2.9 vite-tsconfig-paths: specifier: ^4.3.1 version: 4.3.1(typescript@5.3.3)(vite@5.1.3) diff --git a/website/package.json b/website/package.json index 7dddc2450..d7711537c 100644 --- a/website/package.json +++ b/website/package.json @@ -49,11 +49,13 @@ "og-img": "^0.2.0", "postcss": "^8.4.35", "rehype-external-links": "^3.0.0", + "sharp": "^0.33.2", "tailwindcss": "^3.4.1", "tsm": "^2.3.0", "typescript": "^5.3.3", "undici": "^6.6.2", "vite": "^5.1.3", + "vite-imagetools": "^6.2.9", "vite-tsconfig-paths": "^4.3.1" }, "dependencies": { diff --git a/website/src/components/Header.tsx b/website/src/components/Header.tsx index 2e57179e3..6cb4fafd8 100644 --- a/website/src/components/Header.tsx +++ b/website/src/components/Header.tsx @@ -129,7 +129,8 @@ export const Header = component$(({ searchOpen }) => { > {[ { label: 'Guides', href: '/guides/' }, - { label: 'API reference', href: '/api/' }, + { label: 'API', href: '/api/' }, + { label: 'Blog', href: '/blog/' }, { label: 'Playground', href: '/playground/' }, ].map(({ label, href }) => ( ( +
+ +
+)); diff --git a/website/src/routes/blog/(posts)/should-we-change-valibots-api/index.mdx b/website/src/routes/blog/(posts)/should-we-change-valibots-api/index.mdx new file mode 100644 index 000000000..8ae7af6c8 --- /dev/null +++ b/website/src/routes/blog/(posts)/should-we-change-valibots-api/index.mdx @@ -0,0 +1,150 @@ +--- +cover: API Design +title: Should we change Valibot's API? +description: >- + Today I am writing this message to you to discuss the further development of Valibot's API. +published: 2024-02-29 +authors: + - fabian-hiller + - Demivan + - xcfox +--- + +import NpmDownloads from './npm-downloads.jpg?jsx'; + +# Should we change Valibot's API? + +Hi folks, I am [Fabian](https://twitter.com/FabianHiller), the creator and maintainer of Valibot. Today I am writing this message to you to discuss the further development of Valibot's API. With currently more than 80,000 weekly downloads, the library is growing into a serious open source project used by thousands of JavaScript and TypeScript developers around the world. + + + +In the last few days I received two [API proposals](https://github.com/fabian-hiller/valibot/discussions/453) from [@Demivan](https://github.com/Demivan) and [@xcfox](https://github.com/xcfox). Both of them addressed similar pain points of Valibot's current API design. As our v1 release is getting closer and closer, it is important to me to involve the community in such a big decision. + +## Current pain points + +Valibot's current mental model is divided into schemas, methods, validations, and transformations. Schemas validate data types like strings, numbers and objects. Methods are small utilities that help you use or modify a schema. Validations and transformations are used in the `pipe` argument of a schema. They can make changes to the input and check other details, such as the formatting of a string. + +```ts +// With Valibot's current API +const EmailSchema = string([toTrimmed(), email(), endsWith('@example.com')]); +``` + +A drawback of this API design is that the current pipeline implementation is not modular. This increases the initial bundle size of simple schemas like [`string`](https://valibot.dev/api/string/) by more than 200 bytes. This is almost 30% of the total bundle size. + +Another pain point is that the current pipeline implementation does not allow you to transform the data type. This forced me to add a [`transform`](https://valibot.dev/api/transform/) method, resulting in two places where transformations can happen. + +```ts +// With Valibot's current API +const NumberSchema = transform(string([toTrimmed(), decimal()]), (input) => { + return parseInt(input); +}); +``` + +Speaking of methods, it can quickly become confusing if you need to apply multiple methods to the same schema, as these functions must always be nested. + +```ts +// With Valibot's current API +const LengthSchema = brand( + transform(optional(string(), ''), (input) => input.length), + 'Length' +); +``` + +The last pain point that comes to mind is that the current API design gives you less control over the input and output type of a schema. When working with form libraries, it can be useful to have an input type of `string | null` for the initial values, but an output type of just `string` for a required field. + +## The `pipe` function + +After several design iterations, [@Demivan](https://github.com/Demivan) came up with the idea of a `pipe` function. Similar to the current `pipe` argument, it can be used for validations and transformations. The first argument is always a schema, followed by various actions or schemas. + +```ts +// With the new `pipe` function +const LoginSchema = object({ + email: pipe(string(), minLength(1), email()), + password: pipe(string(), minLength(8)), +}); + +// With Valibot's current API +const LoginSchema = object({ + email: string([minLength(1), email()]), + password: string([minLength(8)]), +}); +``` + +The big difference is that the `pipe` function also allows you to transform the data type. This would allow us to move methods like [`transform`](https://valibot.dev/api/transform/) and [`brand`](https://valibot.dev/api/brand/) into the pipeline. This prevents nesting of functions for these methods and simplifies the mental model. + +With the `pipe` function, the mental model is reduced to schemas, methods, and actions. Actions are always used within the `pipe` function to further validate and transform the input and type of a schema. + +> Alternative names for `pipe` are `flow` (idea by [@mtt-artis](https://github.com/mtt-artis)), `schema` (idea by [@genki](https://github.com/genki)), and `compose` (idea by [@MohammedEsafi](https://github.com/MohammedEsafi)), and `vali` (idea by [@Hugos68](https://github.com/Hugos68)). Please share your thoughts. + +## The advantages + +The `pipe` function makes Valibot even more modular, resulting in a smaller bundle size for very simple schemas without a pipeline. For very complex schemas it reduces function nesting when using [`transform`](https://valibot.dev/api/transform/) and [`brand`](https://valibot.dev/api/brand/). + +```ts +// With the new `pipe` function +const LengthSchema = pipe( + optional(string(), ''), + transform((input) => input.length), + brand('Length') +); + +// With Valibot's current API +const LengthSchema = brand( + transform(optional(string(), ''), (input) => input.length), + 'Length' +); +``` + +It also gives you more control over the input and output type, and simplifies the mental model by eliminating the confusion between the [`transform`](https://valibot.dev/api/transform/) method and the pipeline transformations of the current API. + +```ts +// With the new `pipe` function +const NumberSchema = pipe( + string(), + toTrimmed(), + decimal(), + transform(parseInt) +); + +// With Valibot's current API +const NumberSchema = transform( + string([toTrimmed(), decimal()]), + parseInt +); +``` + +Besides that, the `pipe` function would also allow us to easily add a [metadata feature](https://github.com/fabian-hiller/valibot/issues/373) to Valibot. This could be interesting when working with databases to define SQL properties like `PRIMARY KEY`. + +```ts +// With the new `pipe` function +const UserSchema = pipe( + object({ + id: pipe(string(), uuid(), primaryKey()), + name: pipe(string(), maxLength(32), unique()), + bio: pipe(string(), description('Text ...')), + }), + table('users') +); +``` + +## The disadvantages + +The main disadvantage of the `pipe` function is that it requires a bit more code to write for medium sized schemas, and for more complex schemas you may end up nesting multiple pipelines. + +```ts +// With the new `pipe` function +const NumberSchema = pipe( + union([pipe(string(), decimal()), pipe(number(), integer())]), + transform(Number) +); + +// With Valibot's current API +const NumberSchema = transform( + union([string([decimal()]), number([integer()])]), + Number +); +``` + +## Let's discuss + +Your opinion matters to me. I encourage everyone to share their thoughts. Even quick feedback like "I like this ... and I don't like that ..." is welcome and will help to shape Valibot's future API design. Please discuss with me on [GitHub](https://github.com/fabian-hiller/valibot/discussions/463) or share your thoughts on [Twitter](https://twitter.com/FabianHiller/status/1763253086464639035). diff --git a/website/src/routes/blog/(posts)/should-we-change-valibots-api/npm-downloads.jpg b/website/src/routes/blog/(posts)/should-we-change-valibots-api/npm-downloads.jpg new file mode 100644 index 000000000..610d7abe7 Binary files /dev/null and b/website/src/routes/blog/(posts)/should-we-change-valibots-api/npm-downloads.jpg differ diff --git a/website/src/routes/blog/index.tsx b/website/src/routes/blog/index.tsx new file mode 100644 index 000000000..84c958772 --- /dev/null +++ b/website/src/routes/blog/index.tsx @@ -0,0 +1,68 @@ +import { component$ } from '@builder.io/qwik'; +import { Link } from '@builder.io/qwik-city'; +import clsx from 'clsx'; + +export default component$(() => ( +
+
+

Blog

+

+ Official announcements, project updates and insightful content directly + from the Valibot core team. We're excited to share our journey with you! + Let's validate together! +

+

Latest posts

+
+
    + {[ + { + cover: 'API Design', + title: "Should we change Valibot's API?", + published: '2024-02-29', + authors: ['fabian-hiller', 'Demivan', 'xcfox'], + href: './should-we-change-valibots-api/', + }, + ].map((post) => ( +
  1. + +
    +
    +
    +
    + {post.cover} +
    +
    +

    + {post.title} +

    +
    +
    + {post.authors.map((author, index) => ( + 0 && '-ml-3' + )} + style={{ zIndex: post.authors.length - index }} + key={author} + width="56" + height="56" + src={`https://github.com/${author}.png?size=56`} + alt={`GitHub profile picture of ${author}`} + /> + ))} +
    + +
    + +
    2. + ))} +
+
+)); diff --git a/website/src/styles/root.css b/website/src/styles/root.css index 1e9a196ce..93681dd0f 100644 --- a/website/src/styles/root.css +++ b/website/src/styles/root.css @@ -84,6 +84,11 @@ @apply focus-ring rounded-md text-sky-600 underline decoration-slate-400 decoration-dashed underline-offset-[3px] focus-visible:outline-offset-4 focus-visible:ring-offset-[6px] dark:text-sky-400 dark:decoration-slate-600; } + /* Images */ + .mdx img { + @apply w-full rounded-2xl border-2 border-slate-200 lg:rounded-3xl lg:border-[3px] dark:border-slate-800; + } + /* Lists */ .mdx :is(ul, ol) { @apply space-y-2;