Skip to content

Reactified JavaScript functions for Vue

License

Notifications You must be signed in to change notification settings

vueuse/vue-chemistry

Repository files navigation

Vue Chemistry

The science that deals with the properties, composition, and structure of states, the transformations they undergo during reactions.

Reactified JavaScript functions for Vue, powered by reactify from VueUse.

Reactified? What?

In JavaScript, for most of the time, you are dealing with procedural functions. Which means after the calculation/transformation, the result won't know relationships with its sources, for example

function sum(x, y) {
  return x + y
}

let a = 1
const b = 2

const c = sum(a, b) // c = a + b = 3

a = 2

console.log(c) // still 3, not 4

On the other hand, in Spreadsheets apps like Microsoft Excel or Google Sheets, formulas are always up-to-update whenever their source changes.

Vue's reactivity system is a way to approach the reactiveness in JavaScript. In the Composition API, we are kinda mixing the procedural and reactivity together (which is good and flexible). But what it will be like to have a complete reactive developing experience?

Introducing Vue Chemistry, a set of reactified JavaScript functions letting you enjoy the pure reactiveness!

From the example above, now we can have:

import { set } from 'vue-chemistry/core'
import { sum } from 'vue-chemistry/math'
import { log } from 'vue-chemistry/console'

const a = ref(1)
const b = ref(2)

const c = sum(a, b) // c = a + b = 3

set(a, 2) // shorthand for a.value = 2

log(c) // it's 4 (2 + 2)!

Cool, but, how is that possible?

We are basically making functions accepting Ref as their arguments and then wrapper their result with computed. This makes them automatically collect dependency sources and re-evaluate when the sources get changed. Note that the ComputedRef is also a Ref which means the operations are chainable!

An example for comparsion:

// procedural function
function sum(x: number, y: number) {
  return x + y
}
import type { ComputedRef, Ref } from 'vue'
import { computed, unref } from 'vue'

// reactified function
function sum(
  x: number | Ref<number>,
  y: number | Ref<number>
): ComputedRef<number> {
  return computed(() => unref(x) + unref(y))
}

If you want to convert a normal function into a "reactified" one, you can use reactify() function. The source code can be found here (deadly simple!).

import { reactify } from 'vue-chemistry/core'

function sum(x: number, y: number) {
  return x + y
}

const reactifiedSum = reactify(sum)

Install

npm i vue-chemistry

Usage

Functions available in the following namespaces

// see the auto-completion for the full functions list
import { pow, round, sin, sqrt, sum } from 'vue-chemistry/math'
import { toLowerCase, toString } from 'vue-chemistry/string'
import { parseFloat, parseInt } from 'vue-chemistry/number'
import { parse, stringify } from 'vue-chemistry/json'
import { isFalsy } from 'vue-chemistry/boolean'
import { log } from 'vue-chemistry/console'
import { set } from 'vue-chemistry/core'
// or
import * as Math from 'vue-chemistry/math'
Math.sin(a)

Or to have everything in one place:

import { log, parse, parseInt, sqrt } from 'vue-chemistry'

Examples

import { set } from 'vue-chemistry/core'
import { log } from 'vue-chemistry/console'
import { pow, sqrt, sum } from 'vue-chemistry/math'

// Math       _________
//       c = √ a² + b²
const a = ref(3)
const b = ref(4)
const c = sqrt(sum(pow(a, 2), pow(b, 2)))
log(c) // 5

set(a, 5) // shorthand for a.value = 5
set(b, 12)
log(c) // 13
import { parse, stringify } from 'vue-chemistry/json'
import { log } from 'vue-chemistry/console'

// JSON
//
const obj = ref({ foo: 'bar' })
const str = stringify(obj)
const clone = parse(str)

log(str) // {"foo":"bar"}

obj.value.no = 42
log(str) // {"foo":"bar","no":42}
import { set } from 'vue-chemistry/core'
import { log } from 'vue-chemistry/console'
import { rs, toUpperCase } from 'vue-chemistry/string'

// String
//         rs - Reactive String
const name = ref('foo')
const message = rs`Hello ${toUpperCase(name)}!`
log(message) // Hello FOO!
set(name, 'Anthony')
log(message) // Hello ANTHONY!
import { set } from 'vue-chemistry/core'
import { log } from 'vue-chemistry/console'
import { rs } from 'vue-chemistry/string'
import { dec, multiply } from 'vue-chemistry/match'

// String 2
//
const x = ref(9)
const y = ref(9)
const z = ref(7)
const equation = rs`${x} x ${y} + ${z} = ${sum(multiply(x, y), z)}`
log(equation) //   9 x 9 + 7 = 88
set(x, 98)
dec(z)
log(equation) //  98 x 9 + 6 = 888
set(x, 987)
dec(z)
log(equation) // 987 x 9 + 5 = 8888
import { is, log, rs, set, ternary } from 'vue-chemistry'

// String 3
//
const mode = ref('light')

const isDark = is(mode, 'dark')
const icon = rs`mdi-${ternary(isDark, 'moon', 'sun')}`

log(icon) // mdi-sun

set(mode, 'dark')

log(icon) // mdi-moon

Sponsors

This project is part of my Sponsor Program

License

MIT