DEV Community: Sergey Sova

classList API in forest

Sergey Sova — Mon, 04 Apr 2022 11:20:39 +0000

Forest is a reactive JavaScript/TypeScript rendering engine based on an effector — business logic manager.
The main idea of the forest is "initialize once, never render". Here we don't have such things as to render calls like in React.

Let's show you an example:

import { h, using } from 'forest'

function App() {
  h('div', {
    text: 'Hello',
    fn() {
      h('span', { text: 'World' })
    },
  })
}

using(document.querySelector('#root'), App)

I need to highlight 3 things:

There is no JSX or another specific syntax
Forest doesn't require return from components
Each function/component is called only once

Let's explain:

There is no JSX or another specific syntax

JSX looks like HTML, but do more with javascript embeds. But, when we trying to pass something that not looks like attributes, we need to build tricks:

function ReactComponent(props) {
  return <div
      onClick={handleClick}
      data-someid={props}
      style={{ height: props.height }}
      {...props.extras}
    >content</div>
}

Please note that we also have CSS custom attributes accessible from javascript. We can customize handlers setup (capture, preventDefault, stopPropagation, and so on). DOM API also supports setting many text nodes.

But JSX doesn't support them and for already solved tasks we have a very strange API.
Also, JSX requires passing all kinds of properties to the same place, to the same object, and it shifts responsibility to solve conflicts on end developers.
Also, any specific language requires installing specific tools and learning how to solve specific issues with the new language.

Data-attributes

JSX has anti-DX:

<div data-first={1} data-second={2} />
// instead of, ex:
<div data={{ first: 1, second: 2 }} />

Look at the DOM API:

element.dataset.first = 1
element.dataset.second = 2

Forest:

h('div', {
  data: { first: 1, second: 2 },
})

Event handlers

JSX compels libraries to invent the wheel with the naming of the props:

<div onClick={fn1} onClickCapture={fn2} />

But we have beautiful DOM API:

element.addEventListener('click', fn2, { capture: true })

Forest:

h('div', {
  handler: { click: fn1 },
})
h('div', {
  handler: { config: { capture: true }, on: { click: fn2 } },
})
// or in the same element
h('div', () => {
  spec({ handler: { click: fn1 } })
  spec({ handler: { config: { capture: true }, on: { click: fn2 } } })
})

Style properties

Ok, inline styles are not the best practice, but we have cases for them. What JSX can offer us?

<div style={{ height: 'auto', maxHeight: '100px' }} />

I need to remind, that inline styles allows to pass css custom properties:

<div style="height: auto; max-height: 100px; --color: black"></div>

Forest:

h('div', {
  style: { height: 'auto', maxHeight: '100px' },
  styleVar: { color: 'black' },
})

But JSX in React with TypeScript doesn't allow passing CSS custom properties without tears.

Whole picture

function ForestComponent({ fn, someId, height }) {
  h('div', {
    handler: { click: handleClick },
    data: { someId },
    style: { height: height },
    text: 'content',
    fn,
  })
}

Note, that each kind of properties and attributes is separated from each other, we don't need to solve conflicts. But also, in the forest way in the most cases we don't need props at all, just call spec() inside fn(){}:

function ForestComponent({ fn }) {
  h('div', {
    text: 'content',
    fn,
  })
}

ForestComponent({
  fn() {
    spec({
      handler: { click: handleClick },
      data: { someId },
      style: { height: height },
    })
  },
})

Yep, we like OCP from SOLID, and props allow it. But as you can see, you HAVE a choice.

Forest doesn't require `return` from components

React and JSX requires returning some elements from components because this library builds a diff-tree to compare with the previous view-state. Forest uses the same mechanism as react-hooks to solve the same problem.

It is called declarative stack-based DOM API. Proof of concept implementation.

When you called using with some App function, forest saves each call of h, spec, list, and other methods to the stack, it looks like virtual DOM, but you don't need to compare tree with each other. There is no render. Forest knows each point where is reactivity is applied: the user just passed effector Store instead of a literal value. When the store is updated, forest batches change and apply it to a DOM with 60 frames per second rate. Concurrent rendering out from the box.

This is why each function/component is called only once. And this is why you as a forest user need to change your habits to design forest components. You can't just put if where you want, you need to use reactive Store and visible properties to declaratively show/hide any element you want.

What was before `classList`

I need to explain how the spec() method works.

h("input", {
  attr: { type: "number" },
  fn() {
    spec({ attr: { class: "w-full" } })
  },
})

All method called inside fn(){} property applies on the input element created by h(). So, we can create children elements if we call h() inside fn(){}.

spec() just add new properties, handlers, and so on on the already created element. In our case we should have <input type="number" class="w-full" />.

But with string attributes, we will have some problems.

h("input", {
  attr: { class: "first" },
  fn() {
    spec({ attr: { class: "second" } })
  },
})

What value we should set for the class attribute? First or Second? Or we should merge? If merge, what if I need to override or disable some classes?

function Component({ fn }) {
  h("input", {
    attr: { class: "w-full text-red" },
    fn() { fn() },
  })
}

Component({ fn() {
  spec({ attr: { class: "w-20 text-blue" } }) // Oops! We already set w-full and text-red
}})

There we have the same problem with reactivity:

function Component({ $enabled }) {
  const $class = val`w-full ${$enabled.map(is => is ? 'text-red' : 'text-gray')}`;
  h('input', {
    attr: {
      class: $class,
      type: 'number',
    },
  })
}

What do we have now?

New API allows to set up each class independently. Proposal. It is based on browser API classList.

h("input", {
  classList: ["first"],
  fn() {
    spec({ classList: ["second"] })
  },
})

Now classes can be combined, because forest operates each class independently, instead of a string of something inside.
Also, you have reactivity out from the box:

function Component({ $enabled }) {
  h('input', {
    attr: {
      class: "w-full",
      type: 'number',
    },
    classList: {
      'text-red': $enabled,
      'text-gray': $enabled.map(is => !is),
    },
  })
}

Attribute class and classList will be merged. And nested spec() call also supported:

function Component({ fn }) {
  h("input", {
    classList: ["w-full", "text-red"],
    fn() { fn() },
  })
}

Component({ fn() {
  spec({
    classList: {
      "w-full": false,
      "w-20": true,
      "text-red": false,
      "text-blue": true,
    },
  })
}})

Thank you for the reading! 🧡 ☄️
Forest is still in the development stage, you can help us improve its API or ecosystem: github.com/effector ⭐️

Why utils & helpers is a dump

Sergey Sova — Tue, 23 Nov 2021 09:04:22 +0000

Let's start with how they appear. During project development, the programmer tries to put repetitive pieces of code into functions and reuse them. At some point, the same function is needed in two different modules, the inexperienced developer decides to move the function to a separate module. But for some reason stops at this solution, creating a directory/module of utils or helpers, without thinking about the future of this part of the program.

As the project grows, the number of functions in this directory grows. The number of developers in the project also grows. More and more functions appear. Often nobody follows the structure of these modules and it is quite possible that duplicated code will appear.

How to solve this?

Forget about the utils and helpers directories. These names don't really capture the essence of the content. And from the rules of clean code we remember, the name should be unambiguous and reflect the purpose. We have to wonder why we need to put functions in there in the first place. Why are they used in such different parts of the project?

Perhaps the answer is poor organization of the code of the whole project. If you examine the project carefully you can find a lot of code which can be put in a separate library. If this code cannot or should not be put in a proper library, it can be put in a library inside the project. In the case of JS, you can do this by creating a complete library inside lib/.

You need to give such a library a meaningful and unambiguous name, write documentation and tests. And all related code should be collected in this library. For example, put all the functions that work with dates in the internal library lib/datetime. The lib/ prefix will avoid name conflicts, and it will be possible to use simple and clear names. Of course, you can make an npm scope to simplify future npm publishing. For example, @lib/datetime.

How is this different from lib and helpers?

All code is put in a full-fledged library with a meaningful name, documentation and tests.
lib describes the contents explicitly: it's a library.
Refactoring, publishing and deleting this library become trivial tasks.

Using GQty with effector

Sergey Sova — Mon, 22 Nov 2021 14:32:56 +0000

Introduction

GQTY suggests using integration with React in the form of useQuery, useMutation hooks, and so on.

But when using a state manager, we face the problem of where to store data and a natural desire to move everything about the data and their loading to the state manager, but this creates a second problem - we have to manually transfer data from gqty hooks to the state manager.

Since our projects use effector as a state manager, we will consider the integration with it. First, you need to configure your local gqty instance. Please follow the original instructions at https://gqty.dev/docs/getting-started.

The differences will be in the Configuring Codegen section, the react property should be switched to false, this will not load your bundle with unused hooks, yes, I propose to completely abandon all gqty hooks. After that, you need to delete the generated files, including index.ts

Integration with effector comes down to using a standalone client inside the effects, documentation, and example at https://gqty.dev/docs/client/fetching-data and in the Core Client section of the gqty documentation. The effects already have load markers and load end events, both successful and error events.

Using with effector

Let's start with an example code to retrieve data (query):

import { query, resolved } from '../../api';

const readUserFx = createEffect((userId: string) => resolved(() => {
  const user = query.readUser({ userId })
  if (!user) return null;
  return {
    id: user.id!,
    username: user.username!,
    avatarUrl: user.avatarUrl!,
    tags: user.tags!.map(tag => tag),
    posts: user.posts!.map(post => ({
      id: post.id!,
      title: post.title!,
      content: post.content!,
    })),
  }
}))

Now we can figure out what's going on here and why.

query.readUser({ userId }) doesn't send a query to the server the first time, it only returns a Proxy object so that we can gather the list of fields we need to make a valid query.

In the return expression, we list the fields that we want to get from the query; this is how we describe fields when writing a regular graphQL query.

Exclamation marks in expressions like user.username! are needed to prove to the typescript that the value in the field is certain, otherwise, it will be a string | undefined, which is not the case. https://github.com/gqty-dev/gqty/issues/261

resolved() is a magic function that helps gqty gather the fields the user needs to execute the query. The first time, before executing a query, resolved sets a Proxy instance in the query variable, which collects all the fields accessed by the developer inside the resolved(callback). After the callback is executed, resolved sends the request to the server and returns Promise to the developer. When the server returns the response, resolved substitutes it in the query variable and calls the callback again, already with real data, and then resolves the promise. Note that this is a rough description of the process necessary to explain what's going on.

Any nested data, you also need to select, as well as arrays, even if they are simple, otherwise, you will fall into the data Proxy-objects, which, to put it mildly, are not very pleasant to work with.

But it doesn't look like a convenient solution! Yes, and there are a few ways to simplify life:

Step 1: Create type-caster functions

import { query, resolved, User, Post } from '../../api';

function getPost(post: Post) {
  return {
      id: post.id!,
      title: post.title!,
      content: post.content!,
    }
}

function getUser(user: User) {
  return {
    id: user.id!,
    username: user.username!,
    avatarUrl: user.avatarUrl!,
    tags: user.tags!.map(tag => tag),
    posts: user.posts!.map(getPost),
  }
}

const readUserFx = createEffect((userId: string) => resolved(() => {
  const user = query.readUser({ userId })
  if (!user) return null;
  return getUser(user)
}))

Here it's simple, just put the repeated object getters into functions and reuse them, it's better to put such getters next to the API definition.

Step 2. Use helper functions from gqty

https://gqty.dev/docs/client/helper-functions

import { selectFields } from 'gqty'
import { query, resolved, User } from '../../api'

function getUser(user: User) {
  return selectFields(user, [
    'id',
    'username',
    'avatarUrl',
    'tags',
    'posts.id',
    'posts.title',
    'posts.content',
  ])
}

const readUserFx = createEffect((userId: string) =>
  resolved(() => {
    const user = query.readUser({userId})
    if (!user) return null
    return getUser(user)
  })
)

It is important to read the documentation and carefully check the operation of gqty methods under different conditions.

Step 3. Put all the effects in a separate API layer.

// api.layer.ts
import { selectFields } from 'gqty'
import { query, resolved, User } from './index'

export function getUser(user: User) {
  return selectFields(user, [
    'id',
    'username',
    'avatarUrl',
    'tags',
    'posts.id',
    'posts.title',
    'posts.content',
  ])
}

export const readUserFx = createEffect((userId: string) =>
  resolved(() => {
    const user = query.readUser({userId})
    if (!user) return null
    return getUser(user)
  })
)

// pages/users/model.ts
import { attach } from 'effector'
import * as api from '../../api/api.layer'

const readUserFx = attach({ effect: api.readUserFx })

Now all models can reuse graphQL queries in the same way, without even thinking about how exactly the query is run and what fields get under the hood. But if they need to query additional fields or perform the query differently, they can easily build their query by reusing getUser-like getters.

Why we need `attach`

In the example, I used the attach method instead of using api.readUserFx directly, for one very important reason:

// pages/users/model.ts
import * as api from '../../api/api.layer'

sample({
  clock: api.readUserFx.done,
  target: showNotification,
})

If we write code without attach, subscribing directly to any effect events, these events will be triggered every time any other model triggers that effect. And since in an application different models can subscribe to the same effect, all the scripts in which the effect is involved will be triggered, without regard to whether the page is open now or not, or whether a certain script triggered the effect or not.

// pages/users/model.ts
import * as api from '../../api/api.layer'

const readUserFx = attach({ effect: api.readUserFx })

sample({
  clock: readUserFx.done,
  target: showNotification,
})

Using attach we create a local copy of the original effect. If each model creates a local effect, and only subscribes and runs its local copy, there won't be any problems with overlapping different scripts.

But keep in mind that running the local effect still triggers events and triggers the parent effect, and if someone subscribes to the global api.readUserFx, they will get all the reactions from all the models, this is useful when building an error handling system.

DEV Community: Sergey Sova

classList API in forest

There is no JSX or another specific syntax

Data-attributes

Event handlers

Style properties

Whole picture

Forest doesn't require return from components

What was before classList

What do we have now?

Why utils & helpers is a dump

How to solve this?

How is this different from lib and helpers?

Using GQty with effector

Introduction

Using with effector

Step 1: Create type-caster functions

Step 2. Use helper functions from gqty

Step 3. Put all the effects in a separate API layer.

Why we need attach

Forest doesn't require `return` from components

What was before `classList`

Why we need `attach`