i agree with this as it makes things more extensible without causing breaking changes

I used to have this: #362, loop in to have more context to discuss

I used to have this: #362, loop in to have more context to discuss

A lot of good points there.

From a pure consistency point of view, there are still some open points IMO. Having options.controls is a nice way to implement controls without breaking most composables, but many composables are controls: true by default and don't have controls: false. Pretty hard to write down, lets take this:

Obvious case

const focused = useWindowFocus() // has (currently) no controls, returns the value
const { focused } = useFocusWithin(target) // has (currently) no controls, returns the value wrapped into object

Solution (?):
useFocusWithin should just return (only) the value

const focused = useWindowFocus()
const focused = useFocusWithin(target)

Not so obvious case

const { history } = useRefHistory(counter)  // has controls, returns object with controls, no opt-out

Solution (?):

From a consistency view useRefHistory should return only history and should have options.controls (default false), and should return the controls when options.controls: true. (Breaking)

const history = useRefHistory(counter)

const { history,  undo, redo  } = useRefHistory(counter, {controls: true}) 

hard case

case 1

I could not find a simple example, but let us assume that useIdle has no lastActive and returns only the value like

const idle = useIdle(5 * 60 * 1000) // 5 min

console.log(idle.value) // true|false

Solution (?):
Now we want to add lastActive. What happens now? Does lastActive still count as controls?

case 2

Lets have a look at useClonded. Before this PR, useCloned could be implemented like this:

const cloned = useCloned(original, { clone: klona })
// or with controls
const { cloned, sync } = useCloned(original, { clone: klona, controls: true })

Solution (?):

Now we cannot add isModified. Same problem.

Maybe I am overcomplicating things here.

IMO related and interesting: #4537 (comment)

TLDR;
allow

const stop = useXYZ()
// and
const {stop, pause, resume} = useXYZ()

like vue 3.5 watcher

I don't think we need to "reverse readonly" - as they are expected to be readonly. I don't think an option is needed either. What I am thinking is that people might have the need to say I want a width value that respect window's width, while users can/might override that, which could be an need, but it's not useWindowSize's responsibility.

but if it reacreates a (shallow) ref from the returned readonly, there might be some performance overhead

I am thinking for recreating a ref (or writable computed) that mirrors the watched value, yes. I don't think performance is a concern here as it shouldn't be a widely needed feature either.

Why not computed? Computed does guarantee that the value is readonly, while readonly simply warns in development. Type-wise, it's also clearer imo. Computed are also super cheap.

readonly simply warns in development.

readonly(ref("asdf")) is not writeable:
https://play.vuejs.org/#eNp9kc9LwzAUx/+VZy7dYK6InkY3UBmoBxUVvORS2rcuM01C8jInpf+7rxmbO8gupe/7I/k80olb56bbiGImilB55QgCUnQLaVTrrCfowONqwp+ytkb/QA8rb1vIuJRJI01lTSBoQwPzY2jElVH2gFpb+LRe1xfZeCxNke+v4MN5IGydLgl5AijWV4uuS8f0fZHzlFRlXCTYXra2Rj2Xgn0pIGezyE/6YiIoMMhKNdNNsIa36Ya+FJVtndLoXxwpBpViBskZvJLxvp+SRj7i5KBXa6y+/tE3YTdoUrx6DOi3KMXRo9I3SHt7+f6MO/4/mkwfNafPmG8YrI4D4z52F03N2Ce5RPuY3kSZ5iMsd4QmHJYaQIdkn/JS8Ovcn1n9D/d6epN60vSi/wXjbK6O

I am thinking for recreating a ref (or writable computed) that mirrors the watched value

Agree, BTW in my project I have many use case like this so I created a sugar for syncRef 😂 (related #3549)

function refSync<T>(value: MaybeRefOrGetter<T>, source: MaybeRefOrGetter<T> = value) {
  const newRef = ref(toValue(value))
  syncRef(newRef, toRef(source), { direction: 'rtl' })
  return newRef
}

@OrbisK Like this, I guess we could add to the table shallowReadonly instead, since it avoids deep proxy conversion. However, I'm not too fond of it:

Pros

• Everything will be consistent and we will not have unintended side effects
• We are not dealing with large data structures and the side effect of conversion is one time only, unlike when assigning refs, which is something we do more frequently during composables usage.
  Cons
• A little bit more costly.

I am up to that! I think we could do that for most of the composables with an option to change back. I'd imagine changing ref to shallowRef won't affect 80% of the use cases.

I think we could do that for most of the composables with an option to change back

This may also be related to the readonly discussion. If it is readonly anyway, and we can use shallow internally, I see no reason to return a deep reactive value. (depends on how the descibed util will work.)

This is something I was already thinking in doing as well, so cool to see not just me is on board! 🙌🙌🙌

I think we should use MaybeRefOrGetter/toValue.

I think toValue does not 100% replace unref

It depends on the case. Sometimes it might be needed for some ref's to contain functions (in that case, to properly detect the change, they must be refs). However, if the expected values are not functions, I would use MaybeRefOrGetter/toValue everywhere it's possible.

Maybe. This could provide a better user experience.

We can ensure each composables has UseXXXOptions and UseXXXReturn to replace ReturnType, which would make the Type Declarations cleaner.

like this:

I am working on apply Twoslash to the whole document of VueUse. (Draft PR: #4560)

Related issues:

• useTimeout and useTimeoutFn | should be renamed to closed to browser behavior
• useInterval and useIntervalFn | should be renamed to closed to browser behavior

Thank you @OrbisK, I opened the this issue above because I found the naming of useTimeout and useInterval did not align properly with setTimeout and setInterval. To have the proper browser behavior, we need to use useTimeoutFn and useIntervalFn. I understand that the current nomenclature is that all composable accepting a callback ends in ...Fn, but this cause confusion for Browser / Node API since the is no native equivalent for useTimeout and useInterval which behave more like a ref and a counter.

I suggest something different: tryDispose

See vuejs/core#12681

Initial feedback in that issue makes me wonder if it will be ever fixed. To be completely sure that an effect is disposed appropriately, and simplify the usage, I believe we should mix all the functions into this single one that:

- If current effect scope is detected -> onScopeDispose
- Else if current instance is detected -> onUnmounted
- Else do nothing

(The logic is super simple, but I'm on my phone, so using pseidocode)

I would opt to explicitly define every return type

do you have an example of a particularly complex one which is currently inferred? but would be difficult to explicitly type

I also prefer explicitly defining every return type.

As I did in the image, this allows users to have a clearer understanding of the exported types when they view them through .d.ts type definitions.

#4548 (reply in thread)

do you have an example of a particularly complex one which is currently inferred?

Its not always this way. But lets look at this example.

This does not work:

type UseCounterReturn = {
  count: ShallowRef<number>
}

function useCounter(initialValue: MaybeRef<Number>): UseCounterReturn{
  const count = shallowRef(initialValue)
  
  return {count}
  /*------^^^^^: Type 'Ref<Number, Number> | ShallowRef<Number, Number> | WritableComputedRef<Number, Number>' is not assignable to type 'ShallowRef<number>'.
  Type 'Ref<Number, Number>' is not assignable to type 'ShallowRef<number>' */ 
}

Playground

Because

const a = ref("a")
const shallow = shallowRef(a)

console.log(shallow) // this does log ref("a") - not shallowRef("a")

Related internal discord messages: https://discord.com/channels/937808017016119440/1319226903995092992/1346917517075157013

We have 2 solutions for this:

  const count = shallowRef(initialValue) as ShallowRef<number>

OR

type UseCounterReturn<I> = {
  count: Ref extends I ? I extends Ref ? IfAny<I, ShallowRef<I>, I> : ShallowRef<I> : ShallowRef<I>
}

OR

type UseCounterReturn = {
  count: Ref<number>
}

The second one is the actual returned type.

TLDR:

we will go for

type UseCounterReturn = {
  count: Ref<number>
}

because the shallowRef() of a MaybeRef can be ref, shallow or even computed.