fabian-hiller / valibot

The modular and type safe schema library for validating structural data 🤖
https://valibot.dev
MIT License
5.88k stars 181 forks source link

docs: add `arrayAsync` schema & `ArraySchemaAsync` type #699

Closed EltonLobo07 closed 1 month ago

EltonLobo07 commented 2 months ago

Since this is my first PR related to the website, I have a few questions. Can you answer them? 

Questions:

  1. Variable names for async schemas in the examples: The naming rule followed is the same as Valibot's schema name rule. So if the example is related to an async schema of an object array, the name would be ObjectArraySchemaAsync instead of just ObjectArraySchema. Logically, it doesn't matter, but I think the examples have a lot of weight, and we should do our best to show how to name and use a certain feature. Your thoughts? Should I change the variable names in the examples?
  2. Related to "Related Schemas" section: I assume any async schema has the same related sync schemas + every related sync schema's async version if present. Example: If array is related to custom then arrayAsync will be related to custom and customAsync. I made this assumption because any related async schema can be added inside the array schema, because of which array schema will be changed to arrayAsync schema to follow the "async only inside async schemas" rule. Is this a safe assumption to make? If my assumption is wrong, how would you recommend finding related async schemas?
  3. Related to "Related Actions" section: I have included the async actions too, just for completeness. Do you think it is a good idea? As far as I know, it is not a requirement to use an async schema to use an async action, just that the method has to be async. Am I missing something?
  4. Related to "Related Utils" section: How are isKindOf and isTypeOf utils related to the array or arrayAsync schemas?

    Some potential issues I found that may need to be fixed or completed:

    1. isOfType reference webpage's "Generics" section might be incorrect.
    2. Reference webpages are missing for: ArrayIssue, parserAsync, pipeAsync, safeParserAsync, rawCheckAsync, rawTransformAsync and InferIssue.
fabian-hiller commented 2 months ago

Thanks a lot for this PR. You code looks good.

  1. I am not sure what to do with the examples. I do not recommend to just copy the sync ones, because we recommend to use the async version only if you really need it, so as not to harm the runtime performance unnecessarily. The async version is only needed, for example, if you are validating against your database and need to make a network request. Maybe we should remove the examples for now and add them later. What do you think is best?

  2. Your assumption is correct.

  3. I recommend adding the ### Async header at the end with all related async APIs (including schemas and actions).

  4. Every schema and action contains a kind and type property. Both utils are type guards that can be used to check these properties.

isOfType reference webpage's "Generics" section might be incorrect.

Good catch! Feel free to fix it.

Reference webpages are missing

Don't worry about ArrayIssue. I will add all ...Issue types in the next weeks. If you are interested and have time, you can help me with that.

Feel free to add blank routes for parserAsync, pipeAsync, safeParserAsync, rawCheckAsync and rawTransformAsync. Don't forget to also add them to the menu.md file in alphabetical order.

I am very grateful for your contributions and am interested in passing on some of the sponsorship money the project receives to you in the long run. I don't have the setup for this yet, but I hope to figure it out in the next few months. Maybe we can also find a partner organisations who will support you financially so that you can spend more of your time on Valibot.

EltonLobo07 commented 2 months ago

Thanks for answering the questions.

Regarding the examples, I agree that the async schema's examples shouldn't be a copy of its sync schema's examples. I'll try to come up with some good async examples. During the review, if you don't like the examples, you can remove them. We can always add examples later. I'll make a few more changes based on your answers to this PR. I will let you know once I am done. Also, I'll fix the isOfType "Generics" section and add blank routes for missing webpages shortly. 

Regarding the sponsorship, it will definitely help me, but it is not necessary. I plan to help a lot anyway, but I agree - it will help me spend more time on Valibot. Thank you!

EltonLobo07 commented 2 months ago

I wanted to let you know that I have made the planned changes. You can start reviewing whenever you are free to start the review process.

fabian-hiller commented 2 months ago

Thank you! The examples are great! I only changed them a little. Since the examples are similar, I think the first one is enough. Let's move the second one with the username to the objectAsync API reference. I plan to review and merge this PR later or tomorrow.


Backup of objectAsync example:

import { isUsernameAvailable } from '~/api';

const ProfileSchema = v.objectAsync({
  username: v.pipeAsync(
    v.string(),
    v.checkAsync(
      isUsernameAvailable,
      'The username is already in use by another user.'
    )
  ),
  avatar: v.pipe(v.string(), v.url()),
});
fabian-hiller commented 1 month ago

Thanks again! I have sorted the related async APIs alphabetically, matched the description of arrayAsync with the JSDoc in the source code, and removed the word "asynchronous" from the explanation because the data type is still validated synchronously. arrayAsync only provides the ability to validate the array items asynchronously, but I don't think we need to mention this as we describe the general concept in more detail in our async validation guide.