Creating guidelines to better standardize functions.

[wheatjs]

I was thinking it would be a good idea if we created some guidelines for standardizing functions across vueuse. For example due to some oversights when I wrote useMediaControls we now have some issues like in #514. So I was thinking it would be a good idea to have some guidelines for common patterns. Here are some of my ideas for a few rules;

• Two-Way data flow: If a property can be updated in both directions, from the function and when using the function, then it should be returned from the object.

  Don't

  const volume = ref(100)
  const {} = useMediaControls(target, {
    volume,
  })

  Do

  const { volume } = useMediaControls(target)
  
  volume.value = 100

• One-way data flow: If a property is only able to be configured from the outside, then it should be a config option

  Don't

  const { poster } = useMediaControls(target)
  
  poster.value = '[link to poster image]'

  Do

  const poster = ref('[link to poster image]')
  const {} = useMediaControls(target, {
    poster,
  })

• Controls:

  If a function is often used without controls, it is preferable to provide a controls option as introduced here feat!: introduce controls option #362.

  Don't

  const { timestamp, pause, resume } = useTimestamp()

  Do

  const { timestamp, pause, resume } = useTimestamp({ controls: true })
  const myTimestamp = useTimestamp()

  If it is likely that a function will use controls, prefer just to return the controls without the need for the controls option.

  Don't

  const { pause, resume } = useRafFn(() => {}, { controls: true })

  Do

  const { pause, resume } = useRafFn(() => {})

These are just a few ideas I had to help better align all the functions. Of course this has the potential to introduce quite a few breaking changes. The rules I listed are probably not perfect, but I think they provide a decent starting point.

@vueuse/collaborators

[antfu]

@wheatjs Thanks for drafting this! Guess we should have this for a long time but I didn't figure out a clear way to state them out. Later once we finalize the details, we could have it as a guide in our docs.

A few feedback:

• I am not sure if "One-way" / "Two-way" data flow is clear enough to be distinguishable. For me I kinda think we could support both whenever we can. Refer to https://talks.antfu.me/2021/composable-vue/16?clicks=3

• For the controls part, could have the Do example like

  const timestamp = useTimestamp()
  const { timestamp, pause, resume } = useTimestamp({ controls: true })

And also a few more guidelines that come to my mind:

• Use configurableWindow (etc.) when using global variables like window to be flexible when working with multi-windows, testing mocks, and SSR.
• Use options object as arguments whenever possible to be more flexible for future extensions.
• Use ref over reactive whenever possible
• Use shallowRef to hold hug data / payload
• When involved with Web APIs that are not yet implemented by the browser widely, also outputs isSupported flag
• When using watch or watchEffect internally, also make the immediate and flush options configurable whenever possible
• Use tryOnUnmounted to clear the side-effects gracefully

[wheatjs]

Yeah I think these are all really good points. One question I have is how would you propose handling the volume issue discussed here #514

Since the volume value can be updated via an event listener we can really pass a computedRef into it

[antfu]

Would you like to sort them out and create a new page in the docs? Thanks

[cawa-93]

create a new page in the docs

Shouldn't they be included in the CONTRIBUTING.md (is it possible to integrate it into the documentation?)? When I wonder "What are the rules in this repo" CONTRIBUTING.md - the first thing I look at.

[antfu]

Yeah, we could link to the page in CONTRIBUTING.md. The reason I prefer to have a separate page is that this topic is quite long while the CONTRIBUTING.md is already quite complex, mixing them together will make the page too harangue. Make our guidelines not only help the contributors to have a reference, it could also potentially benefits others making their own composables.

[wheatjs]

Sure, I'll make a PR later today

[wheatjs]

• Avoid using console logs