DEV Community: jkonieczny

Vue's reactivity is a trap

jkonieczny — Mon, 11 Mar 2024 18:36:15 +0000

Vue's reactivity is awesome, but it has a "little" drawback: it messes up with the references. Things that should work, that TypeScript says is fine, suddenly isn't fine.

I won't even talk about nested Refs with enforced typing, it's complete chaos you simply can't currently manage without becoming a master in parkour (or just cast as any, but it's not a good way).

Even in daily use, the reactivity might cause a lot of confusing problems, if you don't know how it works underneath.

A simple array

Look at this code:

let notifications = [] as Notification[];
function showNotification(notification: Notification) {
  const { autoclose = 5000 } = notification; 
  notifications.push(notification);

  function removeNotification() {
    notifications = notifications
      .filter((inList) => inList != notification);
  }

  if (autoclose > 0) {
    setTimeout(removeNotification, autoclose);
  }

  return removeNotification;
}

It's fine, right? If autoclose is no zero, it will remove the notification from the list automatically. We can also call the returned function to close it manually. Clear and nice, the removeNotification will work fine even if called twice, it will remove only the thing that is exactly the element we pushed to the array.

Okay, but it's not reactive. Now look at this:

const notifications = ref<Notification[]>([]);
function showNotification(notification: Notification) {
  const { autoclose = 5000 } = notification; 
  notifications.value.push(notification);

  function removeNotification() {
    notifications.value = notifications.value
      .filter((inList) => inList != notification);
  }

  if (autoclose > 0) {
    setTimeout(removeNotification, autoclose);
  }

  return removeNotification;
}

It's the same, so it should work, right? We get the array iterate through the items and filter out the item that is the same as we added. But it doesn't. It is because the notification object we receive as an argument is most likely a plain JS object, while the item in the array is a Proxy.

How to deal with that?

Use Vue's API

If you don't want to modify the object for some reason, you can just get the actual item in the array with toRaw (explained here). Then the function should look like this:

function removeNotification() {
  notifications.value = notifications.value
    .filter(i => toRaw(i) != notification);
}

In short, the function toRaw returns the actual instance under Proxy, that way you can simply compare the instances and it should be fine.

However, this might be problematic, later you will know why.

Just use an ID/Symbol

Simplest and most obvious solution. Add into Notification an ID or a UUID. You don't want to generate one in a code that invokes the notification every time to keep it simple like showNotification({ title: "Done!", type: "success" }), so put it here:

type StoredNotification = Notification & {
  __uuid: string;
};
const notifications = ref<StoredNotification[]>([]);
function showNotification(notification: Notification) {
  const { autoclose = 5000 } = notification;
  const stored = {
    ...notification,
    __uuid: uuidv4(),
  }
  notifications.value.push(stored);

  function removeNotification() {
    notifications.value = notifications.value
      .filter((inList) => inList.__uuid != stored.__uuid);
  }
  // ...
}

Since JS runtime environment is single threaded, we don't send it anywhere, we can just make a counter and generated id like:

let _notificationId = 1;
function getNextNotificationId() {
  const id = _notificationId++;
  return `n-${id++}`;
}
// ...
const stored = {
 ...notification,
 __uuid: getNextNotificationId(),
}

Really, as long as this __uuid won't be sent anywhere, this one should be fine, at least for the first 2⁵³ times it was called. Or just use date timestamp with an incrementing value.

If you are worried about the 2⁵³ being the maximum safe integer value, you can do this:

function getNextNotificationId() {
  const id = _notificationId++;
  if (_notificationId > 1000000) _notificationId = 1;
  return `n-${new Date().getTime()}-${id++}`;
}

It solves the problem here, but it's not what I wanted to write about.

Use shallow reactivity

Why use deep reactivity, if it's not needed? Seriously, I am aware, that it's simple, the performance is good, but... Why use deep reactivity, when it's not even utilized?

Nothing in the given object will have to change. It's most likely a definition for a notification to show, with some labels, maybe with some actions (functions), but it won't change anything inside. Just replace ref with shallowRef, and voila!

const notifications = shallowRef<Notification[]>([]);

Now notifications.value will return the source array. However, it's easy to forget that that way the array won't be reactive itself, we can't call .push , because it won't trigger any effects. That's why if we just replace ref with shallowRef it will look like it's updating only when items are removed from the array because that's when we are reassigning the array with the new instance. We need to replace this:

notifications.value.push(stored);

with this:

notifications.value = [...notifications.value, stored];

That way notifications.value will return a plain array of plain objects we can safely compare with ==.

Let's summarize some information and explain some things:

Plain JS object – it's a simple raw JS object, without any wrappers, console.log will print just { title: 'foo' }, no magic attached.
ref and shallowRef instances directly print an object of a class named RefImpl with a field (or rather getter) .value and some other private fields, we shouldn't deal with.
ref's .value returns the same thing that returns reactive, a Proxy that mimics the given value, therefore it will print Proxy(Object) {title: 'foo'}. Every non-primitive nested field will also be a Proxy.
shallowRef's .value returns the plain JS object. Just like that, only the .value is reactive here (normally, I'll explain later), and no nested fields are.

We can summarize it with this:

plain: {title: 'foo'}
deep: RefImpl {__v_isShallow: false, dep: undefined, __v_isRef: true, _rawValue: {…}, _value: Proxy(Object)}
deepValue: Proxy(Object) {title: 'foo'}
shallow: RefImpl {__v_isShallow: true, dep: undefined, __v_isRef: true, _rawValue: {…}, _value: {…}}
shallowValue: {title: 'foo'}

Now look at this code:

const raw = { label: "foo" };
const deep = ref(raw);
const shallow = shallowRef(raw);
const wrappedShallow = shallowRef(deep);
const list = ref([deep.value]);
const res = {
  compareRawToOriginal: toRaw(list.value[0]) == raw,
  compareToRef: list.value[0] == deep.value,
  compareRawToRef: toRaw(list.value[0]) == deep.value,
  compareToShallow: toRaw(list.value[0]) == shallow.value,
  compareToRawedRef: toRaw(list.value[0]) == toRaw(deep.value),
  compareToShallowRef: list.value[0] == shallow,
  compareToWrappedShallow: deep == wrappedShallow,
}

And the result:

{
  "compareRawToOriginal": true,
  "compareToRef": true,
  "compareRawToRef": false,
  "compareToShallow": true,
  "compareToRawedRef": true,
  "compareToShallowRef": false,
  "compareToWrappedShallowRef": true
}

Explanation:

compareOriginal (toRaw(list.value[0]) == raw): toRaw(l.value[0]) will return the same thing raw is: a plain JS object instance. It confirms what we expect.
compareToRef (list.value[0] == deep.value): deep.value is a Proxy, the same as the array's proxy will use, no need to create another wrapper, right? Also, there is another mechanism working here
compareRawToRef (toRaw(list.value[0]) == deep.value): we are comparing a "rawed" object to Proxy. Earlier we proved that toRaw(l.value[0]) is the same as raw, therefore it can't be a Proxy.
compareToShallow (toRaw(list.value[0]) == shallow.value): here however we are comparing raw (returned through toRaw) to value stored by shallowRef, which isn't reactive, so Vue doesn't return any Proxy here, just the plain object, which means the raw . No magic here, as we expected.
compareToRawedRef (toRaw(list.value[0]) == toRaw(deep.value)): But again, if we compare toRaw(l.value[0]) with toRaw(deep.value), it will be the same raw object. Anyway, we proven earlier that l.value[0] is the same thing as deep.value . This one is even marked as an error in TypeScript
compareToShallowRef (list.value[0] == shallow): obviously false, since shallowRef's Proxy won't be the same as ref's Proxy.
compareToWrappedShallowRef (deep == wrappedShallow): this one is... a WTF. For some reason, shallowRef if is given a ref, it just returns that ref (here). It makes perfect sense if both source and expected refs are the same type (shallow or deep), but here... it's just... weird.

Summarizing:

deep.value == list[0].value (a reactive inside)
shallow.value == raw (plain object, no magic)
toRef(deep.value) == toRef(list[0].value) == raw == shallow.value (getting plain object)
wrappedShallow == deep , therefore wrappedShallow.value == deep.value (reusing reactive created for the target)

Now with the second item, created from a shallowRef's value or raw directly:

const list = ref([shallow.value]);

{
  "compareRawToOriginal": true,
  "compareToRef": true,
  "compareRawToRef": false,
  "compareToShallow": true,
  "compareToRawedRef": true,
  "compareToShallowRef": false
}

Well, no surprises, let's focus on the most interesting ones:

compareToRef (list.value[0] == deep.value): we are comparing Proxy returned by the list with ref's .value created from the same source. why is it true? How can it be? Vue internally uses a WeakMap to store references to all reactives, so when it creates one, it can check if one is already created and reuses it. That's how two separate ref created from the same source will see each other changes. Those refs will have the same .value.
compareRawToRef (toRaw(list.value[0]) == deep.value): we again compare a plain object with RefImpl.
compareToShallowRef (list.value[0] == shallow): even if the item was created from the shallowRef's value, the list is deep reactive and it returns deep reactive RefImpl, which all fields are reactive. The left side here contains Proxy, right side is an instance.

So what about it?

Even if we replace ref with shallowRef for the list, if the value given as argument was reactive, the list will contain a reactive element, even if it's not deep reactive.

const notification = ref({ title: "foo" });

showNotification(notification.value);

The value added to the array will be Proxy, not the { title: 'foo' }. Gladly, the == will compare it correctly, since the object returned by .value will change as well. However, if we do toRaw on one side, == won't compare the objects correctly.

Conclusion

While deep reactivity in Vue is awesome, it's also full of traps we must be careful of. We need to remember that when working with deep reactive objects, we constantly work with proxies, not the actual JS objects.

Try to avoid at all costs comparing reactive object instances with ==, if you really have to, make sure you do it correctly, maybe using toRaw on both sides might be required. Instead, try to add unique identifiers, ID, UUID, or use an existing unique per-item primitive values you can safely compare. If it's an item from the database, it's most likely it has a unique ID or UUID (and probably date of modification, if that matters too).

Don't ever think about using Ref's as other Ref's initial value. Use its .value, or get the right value by toValue or toRaw, depends on how hard you want your code to be debuggable.

Use shallow reactivity, when it's convenient. Or rather: use deep reactivity when it's needed. In most cases, you don't need deep reactivity. Sure, it's nice to be able to write just v-model="form.name", instead of rewriting the whole object, but do you need a read-only list received from the backend to be reactive?

With a huge array, I've managed to get twice better performance when rendering, while it's not impressive difference between 2ms and 4ms, the difference between 200ms and 400ms is noticeable. The more complicated the data structure is (nested objects and arrays), the bigger the difference will be.

Vue's reactivity typing is a mess. As long as you do simple stuff, it's fine. However, when you start doing weird stuff, you'll need to do even weirder stuff to deal with the consequences, but you probably, just go too far with doing weird stuff and you should just take a few steps backward. I won't even dive into storing Refs inside other Refs, this is even more messed up.

TLDR;

Don't nest Refs. Use the values (myRef.value) instead, but remember that it might contain a reactive, even if you get it from shallowRef
If you need (for some reason) to compare object instances with ==, use toRaw to make sure you are comparing plain JS objects, however, it's better to compare primitive unique values, like IDs or UUIDs

But this is just an article with some information, if you know what you are doing, feel free to experiment.

Vue's new `defineModel`

jkonieczny — Thu, 01 Feb 2024 23:39:42 +0000

It was available as a macro for some time, experimental in 3.3, and now stable in 3.4. An amazing feature that shortens your code a lot and prevents you from having to think of a name used inside the component for the Ref proxy made with useVModel or manual computed.

This article was written with Vue v3.4.15, things may change in newer versions.

What is it and why is it awesome?

Previously, if we wanted to make a prop that would sync its value, we had to write this monstrosity:

const props = defineProps<{
  modelValue: Item
}>();

const emit = defineEmits<{
  (e: 'update:modelValue', v: Item): void
}>();

const innerValue = useVModel(props, 'modelValue', emit);

And without useVModel:

const innerValue = computed({
  get: () => props.modelValue,
  set: (v) => emit('update:modelValue', v),
});

We have to repeat the name "modelValue" 3 times (or 4 without useVModel). If we wanted to use it in our template, it would have to have a different name from the prop (that's why I used innerValue). Now it all shortens to this:

const modelValue = defineModel<Item>();

And that's it. 7 generic lines of code were reduced into one. We can use the same name for variable and prop, and the type here will be Ref<Item|undefined>, we'll fix it later.

Set custom name

We can have multiple v-model on a component, so each has to have a different name. The default name is "modelValue", but if we want to specify the name of the model, we have to pass it through the first argument:

const innerValue = defineModel<Item>("myValue");

We can define more than one model that way:

const innerValue = defineModel<Item>(); // default modelValue
const viewType = defineModel<ViewType>("viewType");

The compiler will warn you if two models have the same name, no worries.

Set the default value or required

The second (or the first, if we are fine with "modelValue" as the name) argument is an object to set up the prop. We can set default value with default field, which is either a primitive value, or a function that returns the instance of object (for object types):

// when it's object
const innerValue = defineModel<Item>({ default: () => newItem() );
// when it's a primitive
const primitiveValue = defineModel<number>(
  "count", { default: 10 }
);

And field required to make the field... required, remove the | undefined from type:

const innerValue = defineModel<Item>({ required: true });

And now we have Ref<Item> instead of Ref<Item | undefined>.

What if v-model isn't passed?

If we use defineModel, but we won't pass any prop (via either v-model or just by normal prop), the Ref will be undefined by default (unless we provide default), but we can still mutate the value and we won't lose any changes. It acts like a wrapper with a local copy:

const props = defineProps<{
  modelValue?: Item
}>();
const emit = defineEmits(['update:modelValue'])

const innerValue = ref(props.modelValue);
watch(() => props.modelValue, (newValue) => {
  if (newValue != innerValue.value) {
    innerValue.value = newValue;
  }
});
watch(innerValue, (newValue) => {
  emit('update:modelValue', newValue);
});

The actual implementation is of course a bit more complicated, but no need to care about it.

Reactivity

Here comes the problematic one... While we should not mutate props (and their fields), we should emit new values. Therefore, we shouldn't assign anything to innerValue.value's fields, but instead overwrite the innerValue.value which will cause the emit:

innerValue.value = {
  ...innerValue.value,
  [key]: value
};

However, if the prop value was reactive, therefore the innerValue.value's fields will be reactive as well. If you don't care much about good practices, you can easily use v-model="innerValue.field" for your input and it will work well.

Mutating fields won't call the emit.

You can of course use toProxy (explained here) to keep it clean without having to manually write emits.

Modifiers! And what the...

Now something "new": we can pass custom modifiers to the v-model, just like we do for inputs: after a dot. It's pretty easily explained in the official docs, so in short: we can now pass modifiers like v-model.trim.lower="myValue" and get them with:

const [modelValue, modelModifiers] = defineModel({
  set(value) {
    let toEmit = value;
    if (modelModifiers.trim) {
      toEmit = toEmit.trim();
    }
    if (modelModifiers.lower) {
      toEmit = toEmit.toLowerCase();
    }
    return value
  }
});

Basically, any part after a dot lands in modelModifiers as a boolean field (either true or undefined). modelModifiers is not reactive, which might be useful.

Power of static modifiers

All props are reactive, which is nice, but also... annoying, especially if you want to configure the component to act in a way that it shouldn't ever change. It won't, but you can't just ignore the props changes. Okay, you can, but it's not a nice way.

What I mean, is that you can pass a bunch of strings, that you can be sure will never change during the lifetime of the component, therefore there is no need to care about them changing!

For example:

<ViewComponent type="horizontal" v-model:context="context">
</ViewComponent>

In this template, we know that type will never change, but inside the component type will be reactive, eslint will not allow us to read it losing the reactivity (unless you disable that rule, but don't).

We can now do this:

<ViewComponent v-model.horizontal:context="context">
</ViewComponent>

And inside:

type Options = "horizontal" | "vertical" | "scaled";
const [context, modifiers] = defineModel<ContextType, Options>()

const viewType = modifiers.horizontal ? "horizontal" : "vertical";
const scaled = modifiers.scaled;

if (viewType == "horizontal") {
  // constant sets for horizontal with no need to care 
  // that the `viewType` would ever change
}

It's just an empty example presenting the idea and maybe in the future it won't be working that way — maybe modifiers will become reactive? We don't know, I'm just presenting a quick idea, don't take it too seriously.

What's under the hood?

Okay, but there were no breaking changes here, defineModel is "just" another macro that is compiled into an "old" component defining method via defineComponent. What happens under the hood and documentation doesn't mention it (though it should!), is that there is added another prop, and it's kinda tricky.

In the simplest example with the default modelValue, the SFC compiler produces something like this:

const __sfc__ = _defineComponent({
  __name: 'Comp',
  props: {
    "modelValue": { type: String, ...{
  } },
    "modelModifiers": {},
  },
  emits: ["update:modelValue"],
});

In case where we also have defineProps with one prop called viewType:

const __sfc__ = _defineComponent({
  __name: 'Comp',
  props: /*#__PURE__*/_mergeModels({
    viewType: { type: String, required: true }
  }, {
    "modelValue": { type: String, ...{
  } },
    "modelModifiers": {},
  }),
});

In short, _mergeModels just merges those two objects. The first one will contain props from defineProps, second the ones produced by defineModel (all of them).

We can notice the new prop called modelModifiers, that's the one produced by defineModel. It's always produced and added, whether we use them or not, probably because otherwise if we try to pass some modifiers without them being defined, they would unnecessarily taint $attrs.

So, underneath, modifiers are reactive, but it's obfuscated in the code. But what's the problem here?

Vue adds new hidden props without informing us directly. If we have a modelValue, there is another prop called modelModifiers. Also, this name is always a special case.

If we create any other name, there will be defined props called name and nameModifiers, which also causes a conflict if we have one model called modelValue and other... model .

const modelValue = defineModel<string>();
const model2 = defineModel<string>("model");
const viewType = defineModel<string>("viewType");

Will produce this:

props: {
  "modelValue": { type: String },
  "modelModifiers": {},
  "model": { type: String },
  "modelModifiers": {},
  "viewType": { type: String },
  "viewTypeModifiers": {},
},

I don't think I need to say that this is just wrong... modelModifiers appears twice, I hope they will write a name collision detector here, or, since the fact of another prop is being created, they will make the names more unique.

In short: with defineModel you need to remember that a prop with the suffix Modifiers is virtually added. Also, don't use props that end with "Modifier" yourself, or be careful with that.

From the renderer's viewpoint

If we look at the compiled template, there will be no surprise, that the modifiers are passed just like other attributes/props:

_createVNode($setup["Comp"], {
  modelValue: $setup.msg,
  "onUpdate:modelValue": _cache[1] || (_cache[1] = $event => (($setup.msg) = $event)),
  modelModifiers: { trim: true, lower: true },
  class: "item-renderer",
  viewType: $setup.msg,
  "onUpdate:viewType": _cache[2] || (_cache[2] = $event => (($setup.msg) = $event)),
  viewTypeModifiers: { horizontal: true }
}, null, 8 /* PROPS */, ["modelValue", "viewType"])

Again, in short: no magic here. An object literal is passed. Anyway, attributes and event listeners also land there. But events always have the on* prefix.

Summary

Among other new features that Vue 3.4 brought, defineModel is the most noticeable one (I know that performance is important, but it doesn't change the way you write your code), which will make writing components easier and faster. But it also brings a new feature.

Modifiers are awesome, but you need to remember it adds virtual props.

With that new feature, code will be shorter, and easier to read and you'll have more possibilities.

EDIT

Okay, it looks like the official docs were supplemented with missing information about additional props being added, when using modifiers, in the expanding Pre 3.4 Usage vue sections.

Event Bus with Vue 3 and TypeScript

jkonieczny — Mon, 04 Dec 2023 19:41:53 +0000

Vue 3 removed the beloved Event Bus used in Vue 2, but nothing is lost! Vue's internal Event Bus became obsolete and unnecessary in the Vue itself. It was quite useful, especially before we got provide/inject.

It allowed communication between components, even siblings, without using a global store (which also isn't a good place to share information about events) or even knowing (having the reference to instance) the receiver/target.

What is an Event Bus (Its simplified version)?

In simple words, it's a bus on which we put some events, inform that something happened, and some others receive them and handle them. Its purpose is not to store data, like global storage (like Pinia), but to broadcast events, just that: like get on a scene and say something. To notify subscribers (those among the audience, who are interested) that something just happened. Every event has its name/title/type (depending on how the creator of the Event Bus called it), and body (this might be optional, also it depends on the implementation of Event Bus).

The entity that sends an event to the Event Bus we call a publisher, while the entity that receives it a subscriber. Subscriber signs to the Event Bus to listen to events of such type (or name, title...). The Event Bus object we can call emitter. Its instance is used to both send events and subscribe to listen to them.

From the publisher's point of view: you send an event and you don't care what happens to it. You did your job.

Subscriber listens to the events of chosen types and handles them. It doesn't matter where the event comes from, just that the event happened and that's all it should care about.

Emitter does the job of sending the events to the subscribers who are interested in those events, so you don't have to check the type of event manually.

The diagram above shows that the message of type foo is sent to the subscribers that listen to that kind of event, and the third subscriber that listens only to bar and baz won't receive that event.

Of course, it was the simplest implementation of the event bus possible, there are more complex implementations that require validation, verification of events, caching them, queuing, notifying publishers about what happened, etc.

A bit of history, how did it work in Vue 2?

Skip this part, if you don't care.

In Vue 2 every component was an event bus and had methods $on, $off, $once and $emit, now we have only the last one, and events are solved more natively.

The easiest way was to use the $root component (the main component, created via new Vue) because it was easily accessible through this.$root. Another way, was to use an empty Vue instance exported somewhere with a simple export new Vue({}).

Using it was rather... annoying:



export const defineComponent({
  //
  methods: {
    onDataChange (args: any) {
      console.log(args)
    }
  },
  created () {
    this.$root.$on("data-change", this.onDataChange);
  },
  destroyed () {
    this.$root.$off("data-change", this.onDataChange);
  }
});

Each event we were listening to had to be released manually. But it was possible to deal with it using a mixin:



export const WithEventBusMixin = {
  methods: {
    onEvent(key, cb) {
      this._releaseAtDestroy = this._eventsToRelease ?? [];
      this.$root.$on(key, cb);
      this._releaseAtDestroy.push(() => this.$root.$off(key, cb));
    },
  },
  destroyed() {
    this._releaseAtDestroy?.forEach(cb => cb());
  }
}

Then we could do this:



export const defineComponent({
  //
  mixins: [WithEventBusMixin],
  methods: {
    onDataChange (args: any) {
      console.log(args)
    }
  },
  created () {
    this.onEvent("data-change", this.onDataChange);
  },
});

Much easier, but we are still lacking something... Typing! Sure, we could create multiple WithEventBusMixin variants to type onEvent arguments, but again, we would have to have a different onEvent method name for every mixin. Don't even make me write a dynamic mixin ever again.

Now just use Mitt

Mitt is a small (200 bytes) library that provides the same functionality. It doesn't have many updates, because it's simply perfect and there are not many things to improve there. It gets the job done. Don't be frightened, if in 2 years npm will say it's 2 years old. This library is just perfect with no bloatware. In the worst case, just copy-paste its code to your app.

In Mitt underneath there is a map of an array of handlers for each type. It means it doesn't track actual subscribers, it just allows you to add a handler to a type of event and remove it. Every handler must be unsubscribed manually. Also, there is no 'publisher' per se, you can emit an event from any place you have access to the event bus instance (called Emitter).

We use it similarly to how we used event buses in Vue 2. We mount listeners with on, unmount with off, and emit with... emit. It's painlessly easy to use it, we first create a bus:



import mitt from "mitt";
type EventBus = {
  foo: string;
}
export const eventBus = mitt<EventBus>();

We can import that object anywhere and send an event on it anytime with a simple:



eventBus.emit("foo", "bar");

It will notify every listener who listens to the event with the type "foo".

Then we can subscribe to these events it in components (or anywhere, those are simple JS objects, not associated with Vue's context):



import { eventBus } from "src/utils/eventBus";

function onFoo (val: string) {
  console.log("Foo happened", val)
}
eventBus.on("foo", onFoo);
onUnmounted(() => eventBus.off("foo", onFoo));

Sure, the type EventBus = {} isn't required, but I strongly recommend typing every event bus. It will prevent any typos in types of events (Mitt uses 'type' for 'name' of the event). Here again, we have to manually unsubscribe from the event, otherwise, the onFoo will be called even after the component is unmounted and removed.

Simple wrapper for mitt

It's nice to not have to remember to unsubscribe manually after each subscribe, so we just write a wrapper that does it for us:



import { Emitter } from "mitt";

export function useMittEvent<
  T extends Record<string, unknown>,
  K extends keyof T
>(mitt: Emitter<T>, key: K, fn: (e: T[K]) => any) {
  mitt.on(key, fn);
  onUnmounted(() => mitt.off(key, fn));
}

This will help you keep the typing, by just providing the event bus instance. Then we use it:



useMittEvent(eventBus, "foo", (val) => {
  //
});

It will subscribe to the event type just on the call and unsubscribe when the component is unmounted.

This might not be too useful when we want to listen to multiple events (too many lines, repeating), so we can write a more universal wrapper that handles multiple event types at once. We will pass the handlers through an object, subscribe to the events in the loop, and do the same to unsubscribe.



type Handler<T = unknown> = (event: T) => void;
type EventHandlers<T extends Record<string, unknown>> = {
  [K in keyof T]: (event: T[K]) => void;
};

export function useMittEvents<T extends Record<string, unknown>>(
  mitt: Emitter<T>,
  handlers: EventHandlers<T>
) {
  for (const key of Object.keys(handlers)) {
    mitt.on(key, handlers[key]);
  }
  function cleanup() {
    for (const key of Object.keys(handlers)) {
      mitt.off(key, handlers[key]);
    }
  };
  onUnmounted(cleanup);
  return cleanup;
}

It returns the function to unmount the listeners if you want to do it manually for some reason.

TypeScript will have a few problems here: It won't check the type correctness directly on on and off methods, but it doesn't matter, since we got it covered in the generics. Now we can use this composable easily in our component:



type EventBus = {
  foo: string;
  bar: number,
};
export const eventBus = mitt<EventBus>();
//
useMittEvents(eventBus, {
  foo(str) { // `str` is string
    console.log("valid", str);
  },
  bar(num) { // `num` is number
    console.log("valid", num);
  },
  baz(v) { // error!
    console.log("invalid", v);
  },
});

Or with arrow functions, to make it shorter in this particular case:



useMittEvents(eventBus, {
  foo: (str) => console.log("valid", str),
  bar: (num) => console.log("valid", num),
  baz: (v) => console.log("invalid", v), // error
});

And that's it, we made a simple wrapper for mitt without installing any other heavy dependency.

Dedicated listener

If passing eventBus the instance is too much, you can write a dedicated wrapper for a bus using the eventBus directly:



export function useMyEvents(handlers: EventHandlers<EventBus>) {
  const keys = Object.keys(handlers) as Array<keyof EventBus>;
  for (const key of keys) {
    eventBus.on(key, handlers[key] as never);
  }
  const cleanup = () => {
    for (const key of keys) {
      eventBus.off(key, handlers[key] as never);
    }
  };
  onUnmounted(cleanup);
  return cleanup;
}

And yeah... here we have to do the dirty trick as never... Or write another wrapper:



function wrapEventBus<T extends Record<string, unknown>>(
  mitt: Emitter<T>
) {
  return (ev: EventHandlers<T>) => useMittEvents(mitt, ev);
}

const useMyEvents = wrapEventBus(eventBus);

And use the same:



useMyEvents({
  foo: (str) => console.log("valid", str),
  bar: (num) => console.log("valid", num),
  baz: (v) => console.log("invalid", v), // still error!
});

Mitt within provide/inject

Sometimes you don't want a global event bus, just... local. Sometimes we want to separate contexts, like using the same component for multiple views, each one working separately, like multiple windows running withing an operating system.

Anyway, we would need to start by defining a Symbol for that:



export const LocalEventBus: InjectionKey<Emitter<MyEvents>> 
  = Symbol("myEventBus");

It will be used for both provide and inject. Now we will need to create a local instance for the bus in the component and provide it:



const localBus = mitt<MyEvents>();
provide(LocalEventBus, localBus);

It would be nice to wrap it in a composable. Then in child components, we can use a modified wrapper:



export function useMyEvents(handlers: EventHandlers<EventBus>) {
  // get current context event bus
  const eventBus = inject(LocalEventBus);
  if (eventBus == null) // if not found
    throw new Error("No event bus found within this context");
  // it's fine, use the instance
  const keys = Object.keys(handlers) as Array<keyof EventBus>;
  for (const key of keys) {
    eventBus.on(key, handlers[key] as never);
  }
  // ... clean
}

If we'll use useMyEvents not within the context that provides this Event Bus, it will throw an error.

It would be also nice to make sure if the component that created the localBus cleaned it up upon its onUnmounted:



onUnmounted(() => {
  localBus.all.clear()
});

It's a bit dirty way, but it will remove every listener within the mitt instance. all is the mentioned Map that contains all listeners, if we call clear method on it, it will do the job. There really is no magic underneath there, everything relies on that Map.

Summary

While they took away a pretty useful feature with Vue 3, mitt, a really small library, fulfills that gap easily. Mitt also provides wildcard type "*", but I've decided to not cover that here. Also, types could be Symbols, but with TypeScritp it shouldn't be needed, there are no performance advantages to using Symbols here.

Maybe Vue lost its useful feature, but it's nothing that couldn't be replaced. Event Buses are still useful and powerful tools on the front end to propagate events.

The declarative approach in Vue 3, think twice before using `watch` or mutating your state

jkonieczny — Fri, 03 Nov 2023 19:59:32 +0000

What does "declarative" mean?

"Declarative" means that we declare what results we want to achieve, not how. Of course, we still need to implement how it should happen, but we separate those two things: we separately define the state and define what comes out of it.

That's how the thing should work in Vue: State ⇒ Calculated intermediate states ⇒ Result. We should keep the mutable state as simple as possible, with as little dependency on each other as possible. If there is a dependency, we should consider, if it should be a result of something else, and setting it should change other conditions, so eventually we will get the desired result.

In terms of Vue, it would mean that we define "what we want to achieve", using reactive data, producing results, instead of mutating state.

A simple example

Let's do a task: "Display a square given by user number". With Vanilla JS we don't have much choice, it would need to look like this:

const input = document.querySelector("input");
const result = document.querySelector(".result");

input.addEventListener("change", (event) => {
  const value = parseFloat(event.target.value) || 0;
  result.textContent = `${value * value}`;
});

With Vue, we receive the values in refs, we can listen to the state changes, and just update the state, the renderer will update the DOM, so we will just focus on the script side:

const input = ref(""); // binded to <input> via v-model
const result = ref(0); // just displayed
// logic
watch(input, (value) => {
  const a = parseFloat(value) || 0;
  result.value = a * a;
});

Okay... simple... Now the next task is to multiply two numbers given by users. And here comes this abomination:

// from <input>
const inputA = ref("");
const inputB = ref("");
// to display in HTML:
const result = ref(0);

// logic
watch(inputA, (value) => {
  const a = parseFloat(value) || 0;
  const b = parseFloat(inputB.value) || 0;
  result.value = a * b;
});

watch(inputB, (value) => {
  const b = parseFloat(value) || 0;
  const a = parseFloat(inputA.value) || 0;
  result.value = a * b;
});

Oh... My... Sure it works, but... How do we know what result is actually? It's a loose state that should be, as the name says, a result of something, but we need to look for what it does in code somewhere else. Let's represent it on a diagram (the dashed line represents usage of a value, not actual dependency):

Okay, maybe I've exaggerated the problem here, but it was a simple example, there could be a much more complicated state where it wouldn't be that obvious that such a thing happens, you'll see it in the next example. Here, it would probably be solved with this code:

watch([inputA, inputB], (valueA, valueB) => {
  const a = parseFloat(valueA) || 0;
  const b = parseFloat(valueB) || 0;
  result.value = a * b;
});

Which would be simplified into this:

Much better, but but still, we can't be sure that somewhere there wasn't the original watch left mutating resutlt. The problem with this approach is that result can be set somewhere and tracking it may not be easy. Much better would be to define it as a computed:

const result = computed(() => {
  const a = parseFloat(inputA.value) || 0;
  const b = parseFloat(inputB.value) || 0;
  return a * b;
});

That way we can be sure of what result says, and how is computed, and that nowhere else its value would be overwritten. What's the difference here between watch and computed, if the result is the same?

The first one is more imperative: you react to something being changed and mutate a different state.

The second one is declarative: you declare result as a result of multiplying two numbers. You don't care why or where they are changing.

Sure, it's a simple example where it's easy to track the watchers, but it might have much more dependencies. Anyway, the advantages of this approach:

result is read-only, as it should be
we know exactly what result's value is, where it comes from
automatically tracks used dependencies required to calculate it
will be lazily calculated exactly when it's needed (no performance penalty, when it's not used)
easy to expand with further dependencies
can be easily wrapped and exported into another file as a reusable composable function

But what's most important: the result state will result directly from the input state.

💡
Sure, this approach might be suboptimal compared to the watch, but I don't think anyone would care about the difference between 10ns and 20ns.

Building URL query with filters, sorting, and pagination

While the filters and paginations are rather simple, you don't want to keep keys like sort[name] in your code. The sort[x] is often unique.

Let's see how bad we can it make:

const queryItems = ref<Record<string, string>>({});
const sortKey = ref("name");
const order = ref<"asc" | "desc" | null>("asc")

watch(sortKey, (newKey, oldKey) => {
  // when key changes
  if (oldKey) { // delete old key, if were any
    delete queryItems.value[`sort[${oldKey}]`];
  }
  order.value = "asc"; // reset the order
  // assign the new query key
  queryItems.value[`sort[${newKey}]`] = order.value; 
}, { immediate: true });

watch(order, (newOrder) => {
  // when order changes
  if (newOrder) {
    // update the query item value
    queryItems.value[`sort[${sortKey.value}]`] = newOrder;
  } else {
    // if none, then just disable it by deleting it
    delete queryItems.value[`sort[${sortKey.value}]`];
  }
});

I'll omit the non-reactive dependencies now because everything would have to be connected:

Please, if you see a code like that in your Code Review, reject it. For multiple reasons:

using delete (explained below)
mutating a state in a watch that is watched by another watch
create and delete a dynamic key in queryItems, no real reference to anything
multiple watches mutating a state, just no! It's making a mess in the code, look at the diagram!
no validation of type for sort[x], sure, you could add a pattern in TypeScript for queryItems, but... no.

What can go wrong?

for some reason, sort[x] may remain unremoved from queryItems
might get into an infinite loop
Hot Module Reload could make your life hell here during the development

⭐
okay, I might be a bit oversensitive here, because sometimes delete is the fastest way to achieve something. But seriously, avoid using that, especially in reactive data. It's a very... uncivilized tool

Notice that if sortKey changes while the order was "desc" or null, the second watch will be called, mutating the queryItem redundantly. Someone might also get an idea of setting sortKey to null, when the order is set to null. You don't want to debug it in runtime if something bad will happen.

First, the sortKey and order are connected and it would be nice to keep them in one object:

type Sort = {
  key: string;
  order: "asc" | "desc";
};

const sort = ref<Sort | null>({
  key: string;
  order: "asc";
});

That way we can simply disable sorting by setting it to null. Then, the actual filters will be put into a ref called filters, only for filters, no sorting, no paginations. The same thing we can do with pagination, also keep it in a separate object: {page: number, itemPerPage: number} | null. And then, at the end, merge them all in a computed using spread operator:

const queryItems = computed(() => {
  // a helper object
  const sortQuery = sort.value ? {
    [`sort[${sort.value.name}]`]: sort.value.order
  } : null;

  const query = {
    ...filters.value,
    ...sortQuery,
    ...pagination.values
  }
  return new URLSearchParams(Object.entries(query)).toString();
});

const { data: list, pending } = useFetch(`/list?${queryItems.value}`);

We keep our hands clean with the dirty sort[name] key, so it's easier to debug it. If sortKey or pagination.value will result in being null, and nothing bad will happen (no fields will be added).

You might also want to filter out null and undefined values from the query object: Object.entries(query).filter(([k,v]) => v != null) .

Clean and simple, we have an initial state and produce a result. In this case, it's nice to create a composable helper:

export function useQueryBuilder(opt: {
  filters?: MaybeRef<Record<string, string>>,
  sort?: MaybeRef<Sort | null>,
  pagination?: MaybeRef<Pagination | null>,
}) {
  return computed(() => {
    const $sort = unref(sort);
    const sortQuery = $sort ? {
      [`sort[${$sort.name}]`]: $sort.order
    } : null;

    const query = {
      ...unref(filters),
      ...sortQuery,
      ...unref(pagination),
    }

    return new URLSearchParams(
      Object.entries(query).filter(([k, v]) => v != null)
    ).toString();
  });
};

Notice that instead of using .value we use unref, because we might want to allow to set filters, sort, or pagination that are not reactive, unref allows to use either. You can also make it a whole URL builder with type checking.

A bit more complicated example

The user switches between 2 versions of a form. How to organize that?

Well, at first, we would need to define the ref containing the form: one of two versions, let's call them Form1 and Form2, with the default version Form1 . How bad can it be done?

<AccountTypeSwitch @change="setType"/>

type AccountType = "personal" | "company"
const form = ref(/*  */);

const personalFields = ["firstName", "lastName", "birthdate"];
const companyFields = ["companyName", "taxNumber"];

function setType(newAccountType: AccountType) {
  form.value.type = newAccountType;
  if (newAccountType == "personal") {
    companyFields.forEach(field => {
      delete form.value[field]
    });
    personalFields.forEach(field => {
      form.value[field] = "";
    });
  } else {
    personalFields.forEach(field => {
      delete form.value[field]
    });
    companyFields.forEach(field => {
      form.value[field] = "";
    });
  }
}

async function send() {
  const { type, ...toSend } = form.value;
  await register(toSend);
}

First, there is no synchronization between currently selected account type, and what AccountTypeSwitch displays as current.

Second, the type is a mess. Good luck with typing it in TypeScript.

The other solution was to keep everything in the object, without removing/reinitializing the fields in the setter and then remove unwanted fields in the function send... this is just terrible.

We have an additional field type that has to be removed before sending to the API, one big object in which we are deleting fields dynamically... Even if we change the delete to overwriting the object without these fields it will be terrible.

How to fix this mess?

The best solution would be just to do 2 separate components with both forms, but what if it's just a part of a bigger form? We would need to somehow merge the data before sending.

Right, merge before sending, don't keep it all together whole the time! Divide and conquer! Let's say that it's a registration form with choosing an account type: personal or company.

If you'll try to keep the form in a type, that keeps both options, you will make a huge mess. Split the form into smaller portions of data, then merge them together before sending, depending on selected choices.

type AccountType = "personal" | "company"
const accountType = ref<AccountType>("personal");

const accountForm = ref(/* */);
const personalForm = ref(/* */);
const companyForm = ref(/* */);

const resultForm = computed(() => {
  const accountTypeForm = 
    accountType.value == "personal" 
      ? personalForm.value
      : companyForm.value;
  return {
    ...accountForm.value,
    ...accountTypeForm,
  }
});

It's still clean. We can also take a different approach: we can have a ref that will receive a form to add, but then, we need to give control to the component with the form. What I mean, is to create RegisterPersonalForm.vue and RegisterCompanyForm.vue, each would contain its own part of the form, and emit the ready part of the form:

<keep-alive>
  <RegisterPersonalForm
    v-if="accountType == 'personal'"
    @stored="accountTypeForm = $event"
  />
  <RegisterCompanyForm
    v-else-if="accountType == 'company'"
    @stored="accountTypeForm = $event"
  />
</keep-alive>

const accountTypeForm = ref<RegisterPersonal | RegisterCompany>();

const resultForm = computed(() => {
  return {
    ...accountForm.value,
    ...accountTypeForm.value,
  }
});

We can't use accountTypeForm with v-model for both components, because the types will be incompatible: what if the user filled some for the personal option, then switched to the company?

That's why the form data will be stored inside those components, and to not lose them, we use <keep-alive>, they will emit event stored when we want... maybe on blur, maybe on any change... Or maybe on the button NEXT, if we implement steps. That's also how we can prevent our state in the main component from being invalid.

But stop here!

There is a catch. If we switch the mode, the event won't be emitted, therefore we will keep old data in the accountTypeForm. The newest state is being kept in the components, so listening to the accountType change, we won't be able to set the right state in our accountTypeForm.

We could add a prop selectedAaccountType to those components and when it matches the component type to emit:

const props = defineProps<{
  currentAccountType: string;
}>();

watch(() => props.currentAccountType, (type) => {
  if (type == "personal") emit("store", form.value);
})

but it would be a bad practice I call render-driven logic (logic is controlled by a rendering state). So let's abandon this idea.

Switch back to two refs:

<RegisterPersonalForm
  v-if="accountType == 'personal'"
  v-model="personalForm"
/>
<RegisterCompanyForm
  v-else-if="accountType == 'company'"
  v-model="companyForm"
/>

If real-time update is what we want, we simply just use the prop fields (they will be reactive, however, it's considered bad practice and is forbidden by eslint by default), or use a wrapper for fields like toFormProxy :

const modelValue = defineModel<RegisterPersonal>();
const form = toFormProxy(modelValue);

If we want to update the form data on the button click:

const modelValue = defineModel<RegisterPersonal>();

const emit = defineEmits({
  stored: (_: RegisterPersonal) => true
});
// we will work on local copy
const form = ref(structuredClone(modelValue.value));

watch(modelValue, (value) => form.value = structuredClone(value));

// on `NEXT` with validation:
function next() {
  try {
    const v = validate(form.value);
    modelValue.value = v;
  } catch(error) {
    notify.error("Validation error")
  }
}

We can declare every part of the form like that, or every step. We will keep our state clear, and make it easier to implement the SKIP option (just emit null like that). Going back to the form's main component that builds the body for the request, we might do it like this:

const accountTypeForm = computed(() => {
  if (accountType.value == "personal") {
    return personalForm.value;
  } else if (accountType.value == "company") {
    return personalForm.value;
  }
  throw new Error("Unknown account type");
})

const resultForm = computed(() => {
  return {
    ...accountForm.value,
    ...accountTypeForm.value,
  };
});

And again, we have a multi-level requests body builder, where we keep logic to the minimum, solving problems as early as possible.

Conclusion

Keep things simple. The declarative approach makes it easier to debug and track why things change. You build a result on the given state, not mutate the result state ad hoc, because "it fits here and it should be sent like that".

Every result state should be reconstructable at any moment, without having to recreate every step user made. That way it's easy to find the place, where something goes wrong.

Using v-model with custom setters

jkonieczny — Wed, 09 Aug 2023 21:36:36 +0000

In the previous article we created a proxy for array, so we could easily use v-model on items of a sorted and filtered array. This time we will write an actual Proxy for an object, so we could write our own setters and still use simple v-model, instead of splitting it into :model-value and @update:modelValue. Creating computeds for each field separately isn't a nice way to achieve it. Then how?

Why?

Case: a picker for an item, but when the item is set, we want also to set it’s category in separate field (there can be picked category without selected item, that's why it's in separate field too).

If we are setting an item, the category must match the item’s category. When we change category, we must ensure that the currently selected item matches the category or clear it. Let’s define our form:



type EntryModel = {
  id: number | null;
  name: string;
  category: CategoryModel | null;
  item: ItemModel | null;
  // ...
};

type ItemModel = {
  id: number | null;
  name: string;
  category: CategoryModel;
  // ...
};

const form = ref<EntryModel>({
  //...
});

We might do it in several ways:

Just leave validation

We could just leave a validation that checks if item has the category equal to the category in entry and force user to change it.

You should definitely have validation for that, just in case, but it’s nice to help user automate things, that can be done automatically.

Using `watch`

We could simply just watch the item being changed and react on it:



watch(() => form.value.item, (newItem) => {
  if (newItem == null) return;
  if (form.value.category?.id != newItem.category?.id) 
    form.value.category = newItem.category;
});

watch(() => form.value.category, (newCategory) => {
  if (form.value.item?.category.id == newCategory?.id) return;
  form.value.item = null;
});

Simple and… terrible. We will have to be sure we installed that watch only once. While it’s simple to write, its making a mess in the data flow which might end with endless loop. Notice that if we set here an item, the item watch will react and will probably change category, after which the watcher on it will be also called later.

Of course, if the data is valid, it should end here, but in more complex network of dependencies it might cause the infinite loop. It’s also hard to track what is changed and why. Also we need to remember, that watch will notice the change if form.value.category will change, even if the new instance will have the same id, we would need to listen to the id field then.

And what if we’d like to cancel the change, because some dependencies weren’t met, and we couldn’t check them while displaying the list of items to pick? It also might be important to know what user actually tried to set. We could also ask user that the action might have more consequences than changing that one value.

Also, we are watching instances here, not ids. If we assign the same category, but using different instance, the watcher will be called.

Just… no. This. Is. A. Mess.

Using dedicated setter

as I mentioned before, we could write a dedicated setter, we have to assign model-value prop and event separately:



<CategoryPicker
  :model-value="form.category"
  @update:modelValue="setCategory"
/>
<ItemPicker
  :model-value="form.item"
  @update:modelValue="setItem"
/>

And then have the setter written in our setup:



const setCategory = (newCategory: CategoryModel) => {
  form.value.category = newCategory.newItem;
  if (form.value.item?.category?.id != newCategory?.id) {
    form.value.item = null;
  }
}

const setItem = (newItem: ItemModel) => {
  form.value.item = newItem.newItem;
  if (form.value.category.id != newItem.category.id) {
    // if it's required
    form.value.category = newItem.category;
  }
}

It will be executed in one tick, so no worries about unnecessary rerendering. It’s possible also to chain the setters, but we would have again to be careful to not get into infinite loop (actually, here we would get a stack overflow error):



const setItem = (newItem: ItemModel) => {
  form.value.item = newItem.newItem;
  if (form.value.category.id != newItem.category.id) {
    // if it's required
    setCategory(newItem.category);
  }
}

We could also do it with one assignment (we will focus on one setter):



const setItem = (item: ItemModel) => {
  const category = form.value.category.id == item.category.id 
    ? form.value.category 
    : item.category
  form.value = {
    ...form.value,
    item,
    category,
  };
}

This one might be preferred if form is already a modelValue and we want to emit a single event. That way we could also make it async, and before anything would be set:



const setItem = async (item: ItemModel) => {
  const category = form.value.category.id == item.category.id 
    ? form.value.category 
    : item.category
  const res = await checkIfCanBeAssigned({ entry: form.value, item, category });
  if (!res) return;
  form.value = {
    ...form.value,
    item,
    category,
  };
}

We would need to block the inputs in the meantime, but we won’t focus on that now.

Writing an actual proxy

Proxy is the core of Vue’s reactivity. It’s pretty everywhere, so why we shouldn’t write our own? We can’t write our own class with getters and setters, writing a loop with Object.defineProperty is a mess, while we have a much simpler solution.

Basically, Proxy is an object, that calls getters for every field we try to read and setter, when we try to set any. It allows us to track every read and write on the object, let’s look at simpliest Proxy (not TS compatible here):



const proxy = new Proxy(form.value, {
  get (target, key) {
    return target[key];
  },
  set (target, key, value) {
    target[key] = value;
    return true;
  },
});

It simply… doesn’t do anything, just returns fields and sets… What’s interesting, we just wrote something that reactive does! With that, we can set fields with simple proxy.category = and that will just work fine! Why? We give it form.value as a target. We receive that object in getter and setter. Assuming that it was reactive (and ref is deeply reactive), then target[key] = value will be equal to form.value[key] = value. Of course it will fail if the form.value will change (by reassigning the instance by form.value = {...}). So we have to wrap it with a computed:



const proxy = computed({
  get () {
    return new Proxy(form.value, {
      get (target, key) {
        return target[key];
      },
      set (target, key, value) {
        target[key] = value;
        return true;
      }
    });
  },
  set (v) {
    form.value = v;
  }
});

Now when form.value will be reassigned, the computed will return new Proxy instance targeting the new instance, but again, we need to get to the fields by proxy.value, but it shouldn’t be a problem. It’s still just a Ref<T>.

Okay, but what about our setters? We have just one here, right? Yeah, and we need to expand it. First, we need to form an interface. How setter should actually look like?

The most important is that we need to be able to set the field that we originally tried to set, but we found that we need to also be able to set other fields at the same time as well, or… none at all.

How about to make the setter a function, that returns a Partial<T | null> with the fields we want to set (or none, if null)? As arguments we would receive the object itself and value we want to set



const setters = {
  item: async (item: ItemModel) => {
    const category = form.value.category.id == item.category.id 
      ? form.value.category 
      : item.category
    const res = await checkIfCanBeAssigned({ entry: form.value, item, category });
    if (!res) return null; //we set literally nothing
    return { // set just those two fields
      item,
      category,
    };
  },
  category: async (category: CategoryModel) => {
    const item = form.value.item?.category.id == category.id 
      ? form.value.item // keep current
      : null; // clear
    const res = await checkIfCanBeAssigned({ entry: form.value, item, category });
    if (!res) return null;
    return {
      item,
      category,
    };
  }
};

We can end the setter at any moment returning an object. What type should be setters of?



type ProxySetters<T extends object> = Partial<{
  [K in keyof T]: (
    target: T,
    value: T[K]
  ) => Partial<T> | null | Promise<Partial<T> | null>;
}>;

It means, it’s a partial (we don’t need to cover every field) object of the given type T (which must be an object), where key is the name of a field and value is a function that returns Partial<T>, synchronous or asynchronous. Now we need to wrap it into a composable:



export function toProxy<T extends object>(opt: {
  target: Ref<T>,
  setters: ProxySetters<T>,
}) {
  const proxy = computed({
    get () {
      return new Proxy(opt.target.value, {
        get (target: T, key: string) {
          return target[key as keyof T];
        },
        set (target: T, key: string, value: any) {
          const setterFn = opt.setters[key as keyof T];
          if (setterFn) {
            // custom setter available, call it
            const toSet = setterFn(target, value);
            // here we can debug the changes, maybe write your own devtools here?
            opt.target.value = {
              ...opt.target.value,
              ...toSet,
            };
          } else {
            // no custom setter, just apply value
            opt.target.value[key as keyof T] = value;
          }
          return true;
        }
      });
    },
    set (v) {
      opt.target.value = v;
    }
  });

  return {
    proxy
  };
}

We need to do some casting, because TS is sometimes a bit too overprotective, key is typed as string, because user can try to get any field (by either .field or ["field"]), so we need to prepare for any situation), but… we don’t have to care about it here. Outside the Proxy object will be visible as T anyway. Moreover, value is typed as any and… we can’t protect it. TS won’t allow on it’s level to call setter with incompatible type anyway, so again, we don’t have to care about it here, just trust TS.

The problem is that setter can not be async, but… we can easily just return the true and wait for the result with then, like in not so good old times. Let’s focus on the setter in that case:



if (key in opt.setters) {
  const toSet = opt.setters(target, value);
  if (toSet instanceof Promise) {
    toSet.then((toSet) => { // yes, overshadowing
      opt.target.value = {
        ...opt.target.value,
        ...toSet,
      };
    });
  } else {
    // just set, it's the result object
    opt.target.value = {
      ...opt.target.value,
      ...toSet,
    };
  }
  return true;
}

Or following the DRY rule:



function setFields(toSet: Partial<T> | null) {
  if (toSet == null) return; // nothing to do
  // again... devtools? Logs?
  opt.target.value = {
    ...opt.target.value,
    ...toSet,
  };
  // or: Object.assign(opt.target.value, toSet);
  // if you really need to avoid overriding the object instance
};

if (key in opt.setters) {
  const toSet = opt.setters(target, value);
  if (toSet instanceof Promise) {
    toSet.then(setFields);
  } else {
    setFields(toSet);
  }
  return true;
}

Now it will work both synchronous and asynchronous! But as I mentioned earlier, the asynchronous setter could last a few seconds during which user could try to do something, it’s wise to lock the form for the time data being set.

Let’s set the rule: we can run only one setter at one time. No more. It would be also nice to know which field we are currently setting. Let’s add a variable:



const currentlySetting = ref<keyof T>();

when it’s value is undefined, then no setter is running. Otherwise, it will contain the name of the setter. At the beginning of the Proxy’s setter, we need to put a guard:



set (target: T, key: string, value: any) {
  if (currentlySetting.value) return false;
  // ...
}

We don’t even need to know what user is trying to set, we just don’t care, we shouldn’t allow any changes before the previous ones aren’t done. For synchronous there is no reason to set the variable, but calling the setter we don’t know yet if it will return Promise or not, therefore we need to modify our function:



if (currentlySettting.value) return false;
const setterFn = opt.setters[key as keyof T];
if (setterFn) {
  currentlySetting.value = key;
  const toSet = setterFn(target, value);
  if (toSet instanceof Promise) {
    toSet
      .then(setFields)
      .finally(() => currentlySetting.value = undefined);
  } else {
    setFields(toSet);
    currentlySetting.value = undefined;
  }
  return true;
}

If the function will not be asynchronous currentlySetting will be set and unset in the same Vue’s tick, so there will be actually no change at all. Even if we would put a watch on it, we won’t register any change. But if the setter will be asynchronous, setting the undefined will happen in different tick and the change will be noticed by computed, even if the setter will end without calling any async task.

And we might also want a helper isProcessing, that will return if any field is being setted asynchronically. As I mentioned, if the currentlySetting will be set to anything and back to undefined in the same tick, it won’t change to true at all.



return {
  proxy,
  currentlySettting, //if we need to know exactly which field
  isProcessing: computed(() => currentlySetting.value != undefined),
};

Now in our form we can lock the fields:



<ItemPicker
  v-model="proxy.item"
  :loading="currentlySetting == 'item'"
  :disabled="isProcessing"
/>

Or just put an overlay on the whole form or even screen. The best thing is that we don’t even need to care about it in the setters, it’s wrapped inside.

Let’s summarize the code



export type ProxySetters<T extends object> = Partial<{
  [K in keyof T]: (target: T, value: T[K]) => Partial<T> | Promise<Partial<T>>
}>;

export function toProxy<T extends object>(opt: {
  target: Ref<T>;
  setters: ProxySetters<T>;
}) {
  // <(string & {})> -- a trick for "any string, but still suggest the keys"
  const currentlySetting = ref<keyof T | (string & {})>();

  function setFields(toSet: Partial<T>) {
    opt.target.value = {
      ...opt.target.value,
      ...toSet,
    };
  }

  const proxy = computed({
    get() {
      return new Proxy(opt.target.value, {
        get(target: T, key: string) {
          return target[key as keyof T];
        },
        set(target: T, key: string, value: any) {
          if (currentlySetting.value) return false;
          const setterFn = opt.setters[key as keyof T];
          if (setterFn) {
            currentlySetting.value = key;
            const toSet = setterFn(target, value);
            if (toSet instanceof Promise) {
              toSet
                .then(setFields)
                .finally(() => (currentlySetting.value = undefined));
            } else {
              setFields(toSet);
              currentlySetting.value = undefined;
            }
          } else {
            opt.target.value[key as keyof T] = value;
          }
          return true;
        },
      });
    },
    set(v) {
      opt.target.value = v;
    },
  });

  return {
    proxy,
    currentlySetting,
    isProcessing: computed(() => currentlySetting.value != undefined),
  };
}

Why and how it would work?

How I mentioned before, when the proxy.value is accessed, it returns a new Proxy. At this level it acts list like any computed returning an object. The returned object will be reactive… in some way, but you shouldn’t see any difference. There is only one getter and one setter here, but inside it returns the field from reactive object: proxy.value.name is equivalent to calling a function that will return the same thing. Therefore, the dependency will be mounted.

The setter… it depends on the strategy. In case of opt.target.value[key as keyof T] = value; there is no creating any new instance, but the reactivity should notify all this field’s listeners that it changed its value.

If the setFields will be called, there will be new instance, then the computed will be outdated and will return new value. It will cause rerender of every component that uses that instance directly. It shouldn’t be any problem anyway.

Also it is perfectly safe to use alongside with the original target, omiting the Proxy mechanism, if not required (however, I would avoid that, it’s not why we implement that thing, to accidentally assign something omiting the setter!)

You can expand the opt argument with another options to let developer choose the strategy on specific places.

Async setters

They are a bit tricky…Let’s take a case where we put a setter on a text field, that checks if every character is lowercase, let’s have a ref:



const item = ref({
  id: 1,
  name: "lorem",
  description: "ipsum",
});

and make a proxy:



const { proxy, isProcessing } = toProxy({
  target: item,
  setters: {
    name: async (obj, val) => {
      if (val == val.toLowerCase()) {
        return { name: val };
      }
      // a function that resolves after 500ms
      await delay(500);
      return {
        name: val.toLowerCase()
      }
    },
  },
});

The problem is that isProcessing will be set to true, because we have here a few Vue’s ticks. The name setter here is itself async, therefore it will return Promise. It means the currentlySetting won’t be set back to undefined in the same tick. It means the template will be in the meantime rerendered and we might lose the focus on the input element.

It shouldn’t be a problem for dropdown pickers, but for text inputs it will be critical. We should make an old-fashion function that just returns a Promise:



const { proxy, isProcessing } = toProxy({
  target: item,
  setters: {
    name: (obj, val) => {
      if (val == val.toLowerCase()) {
        // returned synchronically, in the same tick
        return { name: val };
      }
      // return a Promise
      return delay(500).then(() => ({
        name: val.toLowerCase(),
      }));
    },
  },
});

Now if everything will be fine, no uppercase letter would appear, it will return a synchronous object. Otherwise, it will return a Promise and will have to wait for it to end.

Dialogs and more complex controllers

Using the async setters you can ask user for something, maybe user wasn’t aware of the consequences of flipping single switch? Let’s say we have a form, where we have a switch and a list of elements. If the switch goes off, it will remove all elements. We then just can’t use the watch method here, because we can’t allow the change to happen, if user won’t allow that! It’s possible to solve with a simple async setter (using Quasar’s Dialog plugin):



setters: {
  enabled: (obj, enabled) => {
    if (enabled || obj.items.length == 0) return { enabled };
    return new Promise((resolve) => {
      Dialog.create({
        title: 'Confirm',
        message: 'This action will remove all items in list',
        cancel: true,
        persistent: true
      }).onOk(() => {
        resolve({ enabled, items: [] })
      }).onCancel(() => {
        resolve(null);
      });
    });
  }
}

In this case it either updates the enabled field, if it’s enabling or the list is empty, or asks users if they are aware of the consequences first.

While you have to provide setters in the exact form, it doesn’t need to be that simple. You can write complex controllers:



// global utility
function ask<T extends object>(
  title: string,
  message: string,
  onOk: () => Partial<T>
): Promise<Partial<T> | null> {
  return new Promise((resolve) => {
    Dialog.create({
      title,
      message,
      cancel: true,
      persistent: true,
    })
      .onOk(() => {
        resolve(onOk());
      })
      .onCancel(() => resolve(null));
  });
}

function useItemForm(item: Ref<Item>) {
  // loose utilities and setters
  function setEnabled(enabled: boolean) {
    return { enabled };
  }

  // can be defined separately
  const setters = {
    enabled: (obj, enabled) => {
      if (enabled || obj.items.length == 0) return setEnabled(enabled);
      return ask<Item>(
        "Confirm",
        "This action will remove all items in list",
        () => setEnabled(enabled)
      );
    },
  } satisfies ProxySetters<Item>;

  return toProxy({
    target: item,
    setters,
  });
}

We can easily test it separately from Vue components, making the testing much faster and easier. Notice also that setters have no dependencies on Vue, which mean you can share this code with your Node.js backend!

Chaining setters

We can still chain the setters here. Of course, there is a risk of making infinite loop here, so be careful to avoid that. Maybe if we set the category, we just know we need to clean the item. It’s still not wise to allow to make circular dependency between setters, but you can make some easier. Having setters declared separately, like above (with satisfies, not setters: ProxySetters<T>), we can just call another setter with changed object:



 const setters = {
  // ... other setters
  item: async (obj, item) => {
    const setCategory = item?.category.id != obj.category.id 
      ? await setters.category(
          {...obj, item}, // we can fake the original object with overwritten values
          item?.category ?? null // provide a value to set
        ) 
      : {}; // no need to change anything
    return {
      ...setCategory, //  could also change the `item`, or literally nothing
      item, // but we set it here anyway
    };
  },
} satisfies ProxySetter<Type>;

We might not know if changing category shouldn’t change also something else (or it’s logic is more complicated and we don’t want to repeat it). That way, whatever else it changes, it will change. Changing category could require asking user for confirmation, se we should make it async (it’s not a text field, so it shouldn’t be a problem).

And still, in this case, I wouldn’t recommend calling item setter from category setter, as it might cause stack overflow. It would be better here to avoid calling other setters, if changing is not required.

On the way, we can fake the original item, simulating some changes being done already. We might call two setters one after another, and pass to the second one the modified object with applied changes from the first setter.

No actual change on original item the Ref is referring to will happen, until the original setter wouldn’t return the object with changes to perform. We can also perform a validation before saving the changes on the original object and reject them, if validator would find any problem.

Two strategies at the same time

What if we want to use both strategies at the same time? Proxy is a magical object in which you can program both getters and setters for any key, it is just a virtual interface for an actual object. We could easily manipulate it, by adding another set of fields, prefixed with $, assuming there aren’t any already, it should work fine. We will need to add a cast:



return new Proxy(opt.target.value, {
  /// ...
}) as T & {
  [K in keyof T as `$${string & K}`]: T[K];
};

Define the actual setter strategies:



function setFields(toSet: Partial<T> | null) {
  if (toSet == null) return;
  Object.assign(opt.target.value, toSet);
}

function setByReassign(toSet: Partial<T> | null) {
  if (toSet == null) return;
  opt.target.value = {
    ...opt.target.value,
    ...toSet,
  };
}

We will need to modify our getter too:



get(target: T, key: string) {
  if (key.toString().startsWith('$')) {
    return target[key.substring(1) as keyof T];
  }
  return target[key as keyof T];
},

and about setter, we need to first decide which strategy should be used:



set(target: T, _key: string, value: any) {
  const reassign = _key.startsWith('$');
  const setter = reassign ? setByReassign : setFields;
  const key = reassign ? _key.substring(1): _key;
  // ...

And later replace setFields with setter.

Now if the original object had field name, it will have also a field called $name, which getter will return just name, and setter will update the object by replacing it’s instance.

But seriously… it would be better to just return 2 types of proxies. This is just an example of what proxies are able to do.

Track fields that changed

Another nice feature we can implement here, is tracking the fields that changed. Having a function being called on every set, we can track fields that changed and mark them on form or even allow to undo the change.

We would need to store the original object first, with structuredClone, then in setters setFields and setByReassign we would have to call this:



const original = structuredClone(opt.target.value);
const changedFields = ref(new Set<string>());

// this one we will call in setters:
function setChanged(toSet: Partial<T>) {
  for (const [key, value] of Object.entries(toSet)) {
    if (value != original[key]) changedFields.add(key);
    // if it's the same as original, unmark that it changed
    else changedFields.delete(key);
  }
} 

// this one we will just expose:
function restoreField(key: keyof T & string) {
  if (!changedFields.value.has(key)) return;
  proxy.value[key] = original[key]; //call the setter
}

The new setter will update the changedFields status. That way we could inform user that nothing changed in the form.

Presented listener won’t work fine, if the component will be recreated or created twice and the value change will happen outside the proxy. It also doesn’t track changes in nested objects.

Ignore field with Symbol

Sometimes writting setters, we will have to either set other field or not. We could just return a partial without that field, but sometimes it would mean returning 2 different objects, splitting the code into two branches.

Other idea is to return the field as undefined value, which would mean “no fiels”, but what if in that object undefined would be a valid value, along null and any other? JS offers an unique objects that are their own types: Symbols. Let’s create a symbol called IgnoreField:



export const IgnoreField: unique symbol = Symbol("ignore");

Now if we would want to ignore the field, we would just return this symbol at the field. We will need to redefine our types, replace Partial<T> (in ProxySetters) with:



export type ProxyPartialSetter<T extends object> = {
  [K in keyof T]?: T[K] | typeof IgnoreField;
};

It means: object, that is essentially a Partial of T, but allows to assign FieldIgnore at any field. Next, we will need to write a function that will clear the returned object from fields containing that setter:



function clearupSetters<T extends Object>(toSet: ProxyPartialSetter<T>): Partial<T> {
  const copy = {...toSet};
  for(const key of Object.keys(copy)) {
    if (copy[key as keyof T] == IgnoreField) {
      delete copy[key as keyof T];
    }
  }
  return copy as Partial<T>;
}

Sure, functional purists will hate me now, so now a functional approach:



function clearupSetters<T extends Object>(
  toSet: ProxyPartialSetter<T>
): Partial<T> {
  return Object.fromEntries(
    Object.entries(toSet).filter(([key, value]) => value != IgnoreField)
  ) as Partial<T>;
}

It’s slower (at the time of Chrome 115), but if you really put “readibility” of a 5-lines function above performance, then it’s up to you. Also, the first variant without copying the object is even faster, so if you don’t care what happens to this object and don’t want to lose additional nanoseconds, feel free to avoid copying it before removing fields.

Next, we need to modify our setters:



function setFields(toSet: ProxyPartialSetter<T> | null) {
  if (toSet == null) return;
  Object.assign(opt.target.value, clearupSetters(toSet));
}

And that’s it, now we can write setters like:



const setters = {

  item: (obj, item) => ({

    item,

    category: item?.category?.id == obj.category?.id 

      ? IgnoreField // nothing will be changed

      : item?.category

  })

}

Conclusion

Just as wrapping the arrays, we can wrap an object in a Proxy and write our own setters, adding some more functionalities, like locking whole form when asynchronous setters are working. The performance impact of this solution is negligible, especially if we won’t use full instance overwrite and we won't use setters for text fields.

With this solution, we can easily handle async setters without the need to implement it in each setter. All that without having to care about it in the template.

This is just the beginning. We could modify it to return much more complex structures, nested proxies with their own setters etc.

[Vue] Arrays and v-model on it's items with a simple wrapper

jkonieczny — Sat, 15 Jul 2023 12:36:30 +0000

Arrays and v-model in Vue 3

Vue’s template compiler deals with arrays with v-for directive, with assisting :key for better performance (and not only!). While everything is easy for basic displaying. We encourage the first problem when we try to use v-model inside:



<div v-for="(item, idx) in items" :key="idx">
  <input v-model="item" />
</div>

And here we go… While items is of type Ref<string[]>, the item here is just string , it won’t even compile, because v-model tries to mount a handler for the event "update:modelValue", which tries to assign the new value to item, which is basically a local variable in template renderer. If we use just :model-value="item", the template compiler will generate the code:



return (_openBlock(true), _createElementBlock(_Fragment, null, _renderList(items.value, (item, idx) => {
  return (_openBlock(), _createElementBlock("div", { key: idx }, [
    _createElementVNode("input", { "model-value": item }, null, 8 /* PROPS */, _hoisted_1)
  ]))
}), 128 /* KEYED_FRAGMENT */))

As you see, item here is literally a local variable, an argument of a function, to which you shouldn’t assign anything (it wouldn’t have any actual effect).

It’s not a problem if the array is an array of objects and we are mutating its fields, the objects here will keep the reactivity and Vue will allow mutating them without a problem. The problem will start, when using a different component there that will return a new object, instead of mutating the original one, for example, a picker for category, tags (that aren’t stored as just plain text).

Simple solution: use the array instance

Vue 3’s reactivity is awesome and works flawlessly with arrays, we can literally just mutate an item in an array, so we can go that way: instead of using the item instance, we can use the index from the v-for (idx) and source array:



<div v-for="(item, idx) in items" :key="idx">
  <input v-model="items[idx]" />
</div>

And now everything works as expected! The generated code looks like this:



return (_openBlock(true), _createElementBlock(_Fragment, null, _renderList(items.value, (item, idx) => {
  return (_openBlock(), _createElementBlock("div", { key: idx }, [
    _withDirectives(_createElementVNode("input", {
      "onUpdate:modelValue": $event => ((items.value[idx]) = $event)
    }, null, 8 /* PROPS */, _hoisted_1), [
      [_vModelText, items.value[idx]]
    ])
  ]))
}), 128 /* KEYED_FRAGMENT */))

We see that we use idx item of items array for both setting the model-value prop and to set in "update:modelValue". The item from the v-for is not used at all.

This is a simple solution that will work in most simple cases.

What if the case isn’t simple?

The solution above assumes that we are working on an existing array, I mean… ref. What if it would be a computed? Maybe we want to filter a list first?



const items = ref(['foo', 'bar']);
const search = ref('');
const filteredList = computed(() => {
  if (search.value.length == 0) return items.value;
  return items.value.filter(item => item.includes(search.value));
});

We can’t just replace the items with filteredList in v-for and keep the items[idx] in the input tag, because the given idx won’t be the index of the item in the original array!

Again, if we mutate the items field, it wouldn’t be any issue here. The returned array will still contain reactive objects.

Sure, we could check if the element should be displayed in the template:



<div 
  v-for="(item, idx) in items" 
  :key="idx" 
  v-if="search.includes(item)"
>
  <input v-model="items[idx]" />
</div>

But this solution is… just wrong, against Vue’s style guide. We need to remember that v-for is above the v-if directive, meaning that we can hide that way every item separately. But then, it will make the checks with every component rerender, even if nothing in the array changes!

Store the list of indices

One of the solutions is to provide an array of indexes instead:



const filteredIdx = computed(() => {
  if (search.value.length == 0) {
    return items.value.map((_, idx) => idx);
  }
  return items.value
    .map((item, idx) => item.includes(search.value) ? idx : null)
    .filter(i => i != null)
});

Then we can write the template:



<div v-for="idx in filteredIdx" :key="idx">
  <input v-model="items[idx]" />
</div>

This solution also lets you display the items in a different order than the original array, before mapping the items to indices, sort the array (copying the array first by [...items.value].sort or by using the new toSorted method!).

Rather a clean solution, but if we would like to use the filtered array in a child component, we would have to provide both data: array and filtered list.

Wrap the array, but it’s not as simple as you think it is

Anyway, we need to keep the original index here, so… we better construct a type for a wrapped arrays… but how?

We could simply wrap it into an object:



type WrappedArray<T> = {
  array: Ref<T[]>,
  indices: Ref<number[]>;
};

and use it providing both as reactive values, but no, don’t do this. We better do a reactive wrapper for an array

Reactive array proxy

We could write a proxy object that still acts like a normal array, but can handle mutations on original array (or update it whole, by creating new array instance). We will have array of types:



type ProxyArrayItem<T> = { value: T, idx: number};

The value field here will be reactive, we could do item.value = newItem and it should work, replacing the item on the specific index in original array. We will allow to filter the items and sort them, so we will have the function header:



export function toArrayProxy<T>(opt: {
  array: Ref<T[]>;
  sort?: (a: T, b: T) => number;
  filter?: (a: T) => boolean;
}): ComputedRef<ProxyArrayItem<T>[]> {
  // return proxyArray
}

Next, we need an inner function that will return indices of items to show:



function indices(): number[] {
  const { filter, sort } = opt;
  let arr = opt.array.value.map((item, idx) => {
   return { value: item, idx }
  });
  if (filter) arr = arr.filter((i) => filter(i.value));
  if (sort) arr = arr.sort((a, b) => sort(a.value, b.value));
  return arr.map(i => i.idx);
}

A hidden bonus here: the filter and sort functions can use reactive data and if indices is used in a computed, it will be recalculated when dependency will update.

And then, we need to create the array that will wrap it:



const proxyArray = computed(() => {
  return indices().map(c => /* what? */);
}));

And yeah, what should we put there? Basically returning the { value: opt.array.value[c], idx: c } won’t provide reactivity for value. Here we have a few possible approaches. Computed’s value returns exactly what it’s getter returns, so here we return a raw array of objects. We want the field value (the array’s item’s) to point at the original array, with both getter and setter.

Just use another `computed` inside!…?

Easiest approach:



const proxyArray = computed(() => {
  return indices().map(idx => computed({
    get: () => opt.array.value[idx],
    set: (newValue) => opt.array.value[idx] = newValue,
  }));
});

But then we won’t know, what is the real index in the original array, if we need it ever.

Also, we have another reactive element here… Well, n reactive elements, each array item is separate reactive object.

Take a look at what we actually need here… Getter should return opt.array.value[idx], where idx is returned from indices. Setter should… depends on the approach:

just set opt.array.value[idx] = newValue
call setter given in options, or assign to opt.array.value = newArray, where newArray can be either done by any method of replacing an item in array:
- copy array and replace item
- use .splice(idx, 1, newValue)
- use new method .with(idx, newValue)

We could easily provide just those setters and getters or… do it like it Vue does, but without using another level of reactivity! Here is where a simple object with a getter and setter comes in:



const proxyArray = computed(() => {
  return indices().map(idx => ({
    idx,
    get value () {
      return opt.array.value[idx];
    },
    set value(newValue) {
      opt.array.value[idx] = newValue;
    },
  }));
});

So, basically, what happens here? Let see:



<div v-for="(item, i) in proxyArray" :key="i">
    <ItemEditor v-model="item.value"/>
</div>

What happens here?



return (_openBlock(true), _createElementBlock(_Fragment, null, _renderList(_unref(proxy), (item, i) => {
    return (_openBlock(), _createElementBlock("div", { key: i }, [
      _createVNode(ItemEditor, {
        modelValue: item.value,
        "onUpdate:modelValue": ($event) => ((item.value) = $event)
      }, null, 8 /* PROPS */, ["modelValue", "onUpdate:modelValue"])
    ]))
  }), 128 /* KEYED_FRAGMENT */))

Let’s see, then modelValue: item.value actually calls the getter, which returns opt.array.value[idx], which means we depend on given opt.array (the component will rerender when we change the array) and on the array items opt.array.value[idx].

On the other side, onUpdate:modelValue makes a simple assignation to .value, which calls the setter, which does opt.array.value[idx] = newValue. Everything we need. Of course, as I mentioned, we can change the way it’s assigned.

This setter will cause the update of the component it’s changing because the array items themselves were reactive before.

Logically, value acts exactly like array’s item. Underneath it’s done by getter and setter and using a cached item, so getter doesn’t hit the array each time we try to get the item. If the item in array will change, there will be new instance of ArrayProxyItem created anyway, caused by the dependency created while mapping items in function indices. If T is an object, it will remain reactive and will be the same instance as in the array.

Further development

We got it done easily, but why not make a step forward? We could easily make some common jobs easier with this solution, like removing items! Just add a method to returned items:



const proxyArray = computed(() => {
  return indices().map(idx => ({
    idx,
    get value () {
      return opt.array.value[idx];
    },
    set value(newValue) {
      opt.array.value[idx] = newValue;
    },
    delete: () => opt.array.value.splice(idx, 1),
  }));
});

And we can use it directly in the template:



<div v-for="(item, i) in proxyArray" :key="i">
    <ItemEditor v-model="item.value" @remove="item.delete"/>
</div>

Further optimizations

JavaScript is a nice runtime environment, but sadly, it encourages developers to make the code slow… Sure, “no premature optimization”, but seriously… Don’t set up the traps in places you will regret later! If you are building something low-level, keep it fast and optimized, so you don’t have to care that much about optimization on high-level code (your components). Many web pages are using way too much resources, don’t join them!

I won’t talk about how the conventional for loop (for (const item of items)) is much faster than the .forEach. Look at the upper code… What happens here? While it looks clean, underneath the shiny shell of JavaScript it’s a hell… 3 closures!

Here comes the hated Object-Oriented Programming… Classes! Okay, it’s not so “object-oriented”, because we are going to use just one single class, but still.

We had previously declared the type ProxyArrayItem<T> and… forgot about it. Now let’s change the type into an actual class:



class ArrayProxyItem<T> {
  constructor(private array: Ref<T[]>, public idx: number) {}
  get value() {
    return this.array.value[this.idx];
  }
  set value(newValue) {
    this.array.value[this.idx] = newValue;
  }
  delete() {
    this.array.value.splice(this.idx, 1);
  }
}

Not the we will have 3 class methods instead of 3 closures per every(!) item of array, while having still the same access interface.

The only difference is just creating the proxy array:



const proxyArray = computed(() => {
  return indices().map(idx => new ArrayProxyItem(opt.array, idx));
});

A silly micro benchmark (without Vue’s part) that tests 1000 array elements says that this method is over 20 times faster when creating. But micro benchmarks are often just a curiosity that has little significance.

Sure, it might be lost in the all the work our JS app has to do, but… why waste time and memory, when it can be saved? Especially if it’s something that could be done without that layer of abstraction, we are doing it only to write code easier.

Results for different approaches:

raw print: 17 MiB heap, 25ms render (and total)
computed: 48 MiB heap, 10.1ms creation, 20.0ms render, 30.1ms total
closures: 36 MiB heap, 13.7ms creation, 23,6ms render, 37.3ms total
classes: 24 MiB heap, 7.8ms creation, 24ms render, 31.8ms total

Well, the worst is the approach using closures. Twice that long as using classes or computers. Computeds don’t provide the functionality we need, so it’s a different problem. There are no significant differences in rendering, the benchmark wasn’t done on clean system, so we need to apply a big measurement error.

For heap usage, those are peeks I found with setInterval each 1ms. I’ve measured it multiple times, and results were always similar: with classes the peek never was as high as the others. Don’t trust those measures too much, those measures are not trustworthy, just the overall observation is that using classes had the lowest footprint memory. Computeds and closures were getting higher. I tried using profiler, but it also doesn’t find the actual peeks, and the observations were similar. I know, those tests were done with vite server, without devtools opened, but still the differences are noticable. Also note, that for raw print, there was used just one array, instead of 100.

Somehow rendering is fastest for computeds… It’s probably because it caches the item. Let’s do that in out class:



class ArrayProxyItem<T> {
  _cache: T;
  constructor(private array: Ref<T[]>, public idx: number) {
    this._cache = array.value[idx];
  }
  get value() {
    return this._cache;
  }
  set value(newValue) {
   this.array.value[this.idx] = newValue;
  }
  delete() {
    this.array.value.splice(this.idx, 1);
  }
}

And we’ve managed to get down a few ms for objects for type, but it gets worse for primitives. It’s hard to find the best solution. The _cache will still be reactive, if it ever change (the item instance, either object as whole or if it’s primitive) the proxyArray computed should create a new proxy for that item anyway.

There might be a much bigger performance penalty when mutating data using nested computeds, but it’s a deeper problem, much harder to measure

Final code



export class ArrayProxyItem<T> {
  _cache: T;
  constructor(private array: Ref<T[]>, public idx: number) {
    this._cache = array.value[idx];
  }
  get value() {
    return this._cache;
  }
  set value(newValue) {
    this.array.value[this.idx] = newValue;
  }
  delete() {
    this.array.value.splice(this.idx, 1);
  }
}

// export type ProxyArrayItem<T> = { value: T, idx: number};
export function toArrayProxy<T>(opt: {
  array: Ref<T[]>;
  sort?: (a: T, b: T) => number;
  filter?: (a: T) => boolean;
}) {

  function indices(): number[] {
    const { filter, sort } = opt;
    let arr = opt.array.value.map((item, idx) => {
      return { value: item, idx };
    });
    if (filter) arr = arr.filter((i) => filter(i.value));
    if (sort) arr = [...arr].sort((a, b) => sort(a.value, b.value));
    return arr.map((i) => i.idx);

  const proxyArray = computed(() => {
    return indices().map((idx) => new ArrayProxyItem(opt.array, idx));
  });

  return proxyArray;
}

After using the cache, it works more like that:

The constructor copies the item (reference to it, if it's object) to local cache, so the original array doesn’t have to be used anymore, when we are reading the value. If you use ArrayProxyItem, the dependency will be installed only on the T object (if it’s reactive! A primitive won’t be reactive here, but it’s not any problem here), not on the array. If the item’s field change, everything will work fine on both ArrayProxyItem's value and directly on the source array. If the item will change, there will be another array of ArrayProxyItem created, so the cached reference isn’t any problem. Also again, if the new array will contain the same references, components won’t have to trigger updating the view.

I know it sounds complicated but… Thanks to the reactivity in Vue it just works.

Implementing different storing strategies

As I said, if we want to keep the vue/no-mutating-props rule, we should take different approach to the setter, like reassigning whole array (pick one):



class ArrayProxyItem<T> {
  set value(newValue) {
    // newest approach, fast*
    this.array.value = this.array.value.with(this.idx, newValue);
    // older functional approach, slow
    this.array.value = this.array.value.map((item, i) => i == idx ? newValue : item)
        // copying, patching, aplying; ugly but fastest
    const arr = [...this.array.value];
        arr[this.idx] = newValue;
    this.array.value = arr;
  }
}

This will allow you to use a computed as an array, which setter emits update:modelValue event. You can do the same with delete method (pick one):



class ArrayProxyItem<T> {
  delete() {
    // filter the item out; nice, but slower
    this.array.value = this.array.value.filter((_, idx) => this.idx != idx);
    // copy, remove with splice, apply; looking ugly, but fast
    const arr = [...this.array.value];
        arr[this.idx].splice(this.idx, 1);
    this.array.value = arr;
  }
}

The main difference is that without overwriting the array’s instance, watch won’t react on the change. Watching array is another wide problem. The proxyArray computed will react on any change here, because it reads the items.

While I wouldn’t recommend implementing both in the ArrayProxyItem, I would suggest implement both strategies with interfaces and use whatever version you need. Maybe add an option to toArrayProxy to select the updating strategy?

Practical usage

The proxy implements two things: sorting and filtering. That means, having an array, you wrap it and display in different order, or hide some items:



const search = ref("");
const todos: ref<TodoItem[]>([]);
const todosList = toArrayProxy({
  array: todos,
  filter: (item) => {
    // don't show subtasks here
    if (item.parent == null) return false;
    // if user typed something in search, filter the items
    if (search.value.length == 0) return true;
    return item.content.includes(search.value);
  },
  sort: (a, b) => {
    return a.priority - b.priority;
  }
});

That way we could use the new array to display, modify and remove items from the list.

If the list is returned from backend, it might be better to delete it by request and reload the whole list, but for optimization we could request the delete and just continue working without that item (this is the same thing we would achieve by reloading the array, but with reloading, we would lose the other unsaved changes, if there are any). If we wouldn’t sort, the items would remain in the same order, so we could use the index in original array for features like “add item directly after that one”.

We could still improve this by adding another functionalities, like listeners to change: triggers called when item is removed, moved etc.

Conclusion

We’ve managed to write a wrapper for an array, so we can use a completely reordered and filtered array in v-for and still use v-model to mutate the original array with that. If we are not printing huge amounts of data, the performance. The given solution still brings a lot of places to improve performance and usability.

Using the class approach results in fewer dependencies to track compared to using nested computeds which creates another layer. Therefore, in the long term, this approach should be much more performant. Anyway, it makes many cases using arrays a lot easier, especially if we want to simply use v-model on items directly.

Writing a composable function to fetch data from REST API in Vue.js

jkonieczny — Wed, 28 Apr 2021 22:06:57 +0000

Composition API is best thing that happened to Vue. It makes it possible to write reusable parts of components (logic) in clear and TypeScript friendly way. New reactivity system introduced with Composition API (both Vue 3 and plugin for Vue 2) allows to write pretty clear and universal code.

Let's start with defining what we need to make request. There is always an endpoint and maybe some parameters: filters, pagination, ordering.... Whatever, it's not our problem here, we'll deal with it later.

Simple URL listener

At first, we'll write simple URL listener that will reload the data, when it's been update

const useUrlQuery = <T>(url: string | Ref<string>) => {
  const result = ref<T | null>(null);
  const reload = async () => {
    const res = await fetch(unref(url));
    const data = await res.json();
    result.value = data;
  };
  if (isRef(url)) { // if url is reactive
    watch(url, reload);
  }
  reload();
  return {
    result,
    reload,
  };
};

And we are done. We can use it as simple as that:

setup () {
  const page = ref(0);
  const url = computed(() => `/items?page=${page.value}`);
  const { result: list } = useUrlQuery<ItemType[]>(url);
  return {
    list,
    page
  };
}

We provide url that is either just string or reactive that contains string. computed is reactive and compatible with Ref<T>, it's value is read-only, if set is not implemented, so we don't have to type separately for ref and computed. If we type something as T | Ref<T>, it means it might, but doesn't have to be reactive and when we want to use it's value, we should use unref(val) instead of trying to get into .value property (if it's used inside computed or watch, it will count it as dependency if it is reactive). Later we check if url is reactive and mount a watcher if it is. Also thanks to that we are watching a primitive at the end, it means it won't run if it won't change.

Notice that we rename result into list here. We use JavaScript's destructuring with renaming fields. That way we can avoid any name conflict, which is might happen with mixins.

Whenever page will change, url will be recomputed and fire watch(url, reload). At initial state, result will be null, so we might want to add some default value, to avoid the type T | null. Also we'd like to know, if there is a request ongoing. We'll add isLoading state and error:

const useUrlQuery = <T, K = T | null>(
  url: string | Ref<string>,
  initial: K
) => {
  const result = ref<K>(initial);
  const state = reactive({
    isLoading: false,
    error: null as any,
  });

  const reload = async () => {
    state.isLoading = true;
    try {
      const res = await fetch(unref(url));
      const data = await res.json();
      result.value = data;
    } catch (e) {
      state.error = e;
    } finally {
      state.isLoading = false;
    }
  };

  if (isRef(url)) {
    watch(url, reload);
  }

  return {
    ...toRefs(state),
    result,
    reload,
  };
};

In case K to be T, TypeScript won't consider there other type than the one provided, so you won't have to write the type manually (you can also assume null to be default), if it's endpoint for list, you can easily pass empty array and cast it into array type ([] as ItemType[]), or put a placeholder object.

Now we can use isLoading to notify users that the list they are seeing is not yet updated. You can add a spinner, hide list, whatever you designed for that case.

setup () {
  const { result: list, isLoading, error } = useUrlQuery('/items', [] as ItemType[]);
  return {
    list,
    isLoading,
    error,
  }
}

HINT: page number from URL

const route = useRoute();
const url = computed(() => `/items/?page=${route.params.page}`);

Guard

But sometimes requests are longer, and sometimes happens to a situation that we receive response from newer query before older one finishes. That is a case when for example we remove some filters, or we just fast between pages and backend will need some more time to get one. For example: we are at page 1. We click "page 2". It starts loading, but before it finishes, we jump to third. Third page has only one element, so backend responds before it finishes the request for second page. Composable sets data for third page, and them BUM! Response for second page comes and fires the reload that was fired much earlier and replaces result to that for invalid page.

We have few approaches here. If we are using native fetch, we might use AbortController. It's simple change:

  let controller: AbortController | null = null;
  const reload = async () => {
    controller?.abort();
    state.isLoading = true;
    try {
      controller = new AbortController();
      const res = await fetch(unref(url), { signal: controller.signal });
      result.value = await res.json();
      state.isLoading = false;
    } catch (e: any) {
            if(e.name === "AbortError") {
        // request was aborted
        return;
      }
      // will set error and disable `isLoading` only if it wasn't aborted
      state.isLoading = false; 
      state.error = e;
    }
  };

And that's it! But that is a case when we use native Fetch. We also had to remove finally section, because there is a case (abort) in which we don't set isLoading to false If you use Axios, you'd need it's own approach. We might also let developer provide their own async function that will return the state, in that case either we'll have to force to provide a function to abort request, or protect it from storing invalid result.

try {
  const forUrl = url.value;
  // fetch
  const data = await res.json();
  ****if (url.value == forUrl) {
    result.value = data; //set only if url is still the same
  }
**} //...**

With that solution we can listen to actual URL and accept result only if it didn't changed. This also will accept former response in case we switched from page 1 to 2, then to 3 and back to 2. If the first request for page 2 will finish when page 2 was really selected, it will accept this response in that case (also will accept last one, but nothing will change, if no change happened in database).

This also could lead to further optimizations, like caching last few results which we could implement easily.

URL builder

Now that we have a composable that will listen to url changes and update it's local state, we should work. Building URL manually might be chaotic, that's what URLSearchParams is for. We'll implement a builder that will build query parameters from object:

type ParamType = string | number | boolean;
type ParamsType = Record<string, ParamType>;
export const useParamBuilder = (params: ParamsType | Ref<ParamsType>) => {
  return computed(() => {
        const search = new URLSearchParams();
    const obj = unwrap(params); // unwrap in case if it's Ref
    const entries = Object.entries(obj)
      .filter(e => e[1] != null)
      .filter(e => typeof e[1] == "string" ? e[1].length > 0 : true)
      .sort(([a], [b]) => a > b ? 1 : a < b ? -1 : 0);
    entries.forEach(([key, value]) => search.append(key, value.toString()));
    return search
  });
}

export const useUrlParams = (base: string, params: Readonly<Ref<URLSearchParams>>) => {
  return computed(() => `${base}?${params.value.toString()}`);
}

Implementation doesn't matter here that much, here we just put strings, numbers and booleans into query. At first we filter out nulls and empty strings, then we sort entries by key alphabetically, to have them in the same order (it is important to have watch noticing the difference correctly).

const filter = ref<ItemFilters>({
  active: false,
  search: "", //will be filtered out if empty,
  category_id: null, //filtered out if null
});

const { result: list } = useUrlQuery(
  useUrlParams('/items', useParamBuilder(fitler)),
  []
);

return {
  list
}

Of course you can merge those two composables into one, if you won't use them separately.

export const useUrlParams = (base: string, params: Ref<Record<string, string|number|boolean>) => {
  return computed(() => {
    const search = new URLSearchParams();
    const obj = params.value;
    const entries = Object.entries(obj)
      .filter(e => e[1] != null)
      .filter(e => typeof   e[1] == "string" ? e[1].length > 0 : true)
      .sort(([a], [b]) => a > b ? 1 : a < b ? -1 : 0);
    entries.forEach(([key, value]) => search.append(key, value.toString()));
    return `${base}?${params.value.toString()}`
  });
}
// in setup:
const { result: list } = useUrlQuery(
  useUrlParams('/items', fitler),
  []
);

That way we packed functionality of almost every fetching data from REST API in single one composable function.

Example ToDo list component

<template>
  <div>
    <h1>TODOS:</h1>
    <input :value="filters.search" @input="setSearch" placeholder="search" />
    <ul class="todo-list" :class="{ 'is-loading': isLoading }">
      <li class="todo-item" v-for="item in list" :key="item.id">
        <input type="checkbox" :value="item.done" @change="setDone(item)" />
        {{ item.text }}
      </li>
    </ul>
        <button @click="reload">Reload</button>
  </div>
</template>
<script lang="ts">
import { defineComponent, reactive, computed } from "vue";
import { useUrlParams, useUrlQuery } from "@/composables/useApiRequest";
import debounce from "lodash/debounce";

type TodoItem = {
  id: number;
  text: string;
  done: boolean;
};

const defaultPlaceholder = [
  { id: 1, text: "Perform fetch", done: false },
] as TodoItem[]

export default defineComponent({
  name: "TodoListComponent",
  setup() {
    const state = reactive({
      loading: false,
    });
    const filters = reactive({
      done: false,
      search: "",
    });
    const url = useUrlParams("/todos", filters);
    const { result: list, reload, isLoading: listLoading } = useUrlQuery(url, defaultPlaceholder);

    const setDone = async (item: TodoItem) => {
      state.loading = true;
      try {
        const response = await fetch(`/todos/${item.id}`, {
          method: "PATCH",
          body: JSON.stringify({ done: !item.done }),
        });
        await response.json(); // ignore response
        await reload();
      } catch (e) {
        console.error(e);
      } finally {
        state.loading = false;
      }
    };

    const setSearch = debounce((event: InputEvent) => {
      filters.search = (event.target as HTMLInputElement).value;
    }, 200); // prevent reloading after each character

    return {
      isLoading: computed(() => listLoading.value || state.loading),
      filters,
      list,
      reload,
      setDone,
      setSearch,
    };
  },
});
</script>

<style scoped>
.is-loading {
  opacity: 0.5;
  pointer-events: none;
}
.todo-list {
  margin: 0;
  padding: 0;
}
.todo-item {
  cursor: pointer;
}
</style>

Code doesn't focus on layout, just example usage of written composable. This article focused only on GET request that listens to URL.

Conclusion

With new Vue's Composition API we are able to delegate logic outside the component and reuse it without having to care about names conflicts, like it happen with mixins, it's also much easier to parametrize composables than mixins. It's easy, safe and speeds up the development. This was just an example, another time I'll provide some more examples of usage of this new API.

DEV Community: jkonieczny

Vue's reactivity is a trap

A simple array

Use Vue's API

Just use an ID/Symbol

Use shallow reactivity

So what about it?

Conclusion

TLDR;

Vue's new `defineModel`

What is it and why is it awesome?

Set custom name

Set the default value or required

What if v-model isn't passed?

Reactivity

Modifiers! And what the...

Power of static modifiers

What's under the hood?

From the renderer's viewpoint

Summary

EDIT

Event Bus with Vue 3 and TypeScript

What is an Event Bus (Its simplified version)?

A bit of history, how did it work in Vue 2?

Now just use Mitt

Simple wrapper for mitt

Dedicated listener

Mitt within provide/inject

Summary

The declarative approach in Vue 3, think twice before using `watch` or mutating your state

What does "declarative" mean?

A simple example

Building URL query with filters, sorting, and pagination

A bit more complicated example

How to fix this mess?

But stop here!

Conclusion

Using v-model with custom setters

Why?

Just leave validation

Using watch

Using dedicated setter

Writing an actual proxy

Async setters

Dialogs and more complex controllers

Chaining setters

Two strategies at the same time

Track fields that changed

Ignore field with Symbol

Conclusion

[Vue] Arrays and v-model on it's items with a simple wrapper

Arrays and v-model in Vue 3

Simple solution: use the array instance

What if the case isn’t simple?

Store the list of indices

Wrap the array, but it’s not as simple as you think it is

Reactive array proxy

Just use another computed inside!…?

Further development

Further optimizations

Final code

Implementing different storing strategies

Practical usage

Conclusion

Writing a composable function to fetch data from REST API in Vue.js

Simple URL listener

HINT: page number from URL

Guard

URL builder

Example ToDo list component

Conclusion

Using `watch`

Just use another `computed` inside!…?