Forem: Oleg Isonen

Synchronized immutable state with time travel

Oleg Isonen — Tue, 05 Apr 2022 19:45:15 +0000

I am working on @webstudiois - an open-source visual development platform.
As part of the UI for the Webstudio Designer, a very interactive interface, I needed an undo/redo functionality and created a library for synchronizing state across the client, server, and multiple clients in future releases.

Challenge 1 - immutability

Is immutability a solved problem in EcmaScript? Not by a long shot.

We have got far, starting with initial attempts using abstractions like immutable which has a severe downside with interoperability. Then we went over to manually cloning objects and arrays using built-in language features like the spread operator, which makes it super unreadable to change complex structures. For example, nested objects or arrays with objects because you have to go inside whatever you want to change and then clone every object on your path to keep the object immutable.

Structured cloning is an API I look very much forward to, though it's not solving the same problem Immer does.

Immer is the first popular library to solve immutability in an interoperable way. It lets you work with regular objects, so you have no lock-in on Immer and can use vanilla functions that mutate anything you give them without causing any trouble. The most crucial feature of Immer for me, though, is patches generation.

import produce from "immer"
const nextState = produce(draft => {
  // Mutable behavior is allowed on the draft.
  draft[1].done = true
  draft.push({title: "Tweet about it"})
})(previousState)

Challenge 2 - syncing UI state to the server

When using immutable data structures, you mainly have only two options on how to save the changes to the server:

Send custom updates to the server using any APIs.

This is probably the most popular approach, which may work fine in simple cases, but won't scale well as your application grows.

You have to rely on each update implemented correctly because it usually ends up with custom logic for each update that prepares the data to be sent to the server. You also need to handle errors to let you reflect the server state on the client, making it hard to do, especially with an optimistic UI. Over time, this approach provides a large surface for potential errors.

It can't be undone easily.

When data you sent to the server was manually prepared for this update, undoing that update will also require you to write custom code that would undo the same update. In some cases, it becomes very complex, especially when you have to talk to multiple endpoints, and every endpoint also has to have a way to undo the change.
Sending entire snapshots to the server

Challenge 3 - sending the minimal updates to the server

It is super easy to update the server using snapshots, reflecting everything you want to be permanently stored. This makes sure the data on the server and the client is consistent, and it's super easy to keep it this way over time.

Downsides:

You have to potentially send massive payloads to the server, making it impossible to sync frequently and quickly
You can't easily build collaborative features because if two clients can update the same state, you have to figure out how to make a conflict resolution work with a snapshot. We already lost the information about who changed what and when.

Doing it this way, you can quickly run into conflicts even by opening two separate tabs. Also, you are limited in the ability to use iframes or web workers because if any of them require access to the state, they can't get easily synchronized without sending the entire state to them. This is a real deal-breaker since it will negate any potential benefit of using a web worker.

Challenge 4 - undo/redo the UI state

If some centralized store-like abstraction does not manage your UI state, undoing it becomes problematic because you have to make sure that every representation of a certain state is being updated.

In addition to that, you need to be able to distinguish multiple types of states:

Data state - essentially, what the server knows about your app and should be undoable
UI state - current state of the UI that is not reflected on the server and should not be undoable, e.g., a derrived state
Ephemeral state - a state that is temporarily reflected on the UI, and should not be undoable, e.g., a selected element

Having store-like abstraction to manage states requires you to manually define which state and action is undoable, which state is being reflected on the server, and which one is ephemeral if it's not a component's local state.

There are many edge cases, and managing that in a large app is not trivial.

Solution with autogenerated patches

All of the above challenges were a problem for me. I need a minimal amount of changes to be sent over the network. I need a way to easily undo/redo the changes. I need the ability to reflect changes inside an iframe. I need to reflect changes across tabs and windows for a collaborative editing experience.

Let me introduce you Immerhin.

Immerhin is a very thin abstraction on top of Immer that lets you use basically any state management (Redux-like stores etc.). I am personally using this tiny library react nano state with it.

Immerhin lets you declare a transaction to identify a single user action, which may update multiple states. Thanks to Immer, it enables you to mutate all those states without losing immutability. It uses Immer's patches and revise patches to send the minimal amount of changes to any consumers and enables undo/redo out of the box.

Immerhin's current development state is not battle-tested and still lacks many features, so consider this as a project to follow for future releases or use for non-production projects. You can follow the repo or Webstudio's Twitter account for the updates on this.

Here is a small Codesandbox demo that shows how it can be used to have a shared state between 2 separate lists and have an undo/redo functionality with no extra logic to manage for undo/redo.

Here is how to use Immerhin:

Create container

Container is an object that has .value reflecting the current value and a .dispatch(nextValue) which will update all container subscribers. Immerhin only cares about those two properties. How you do the rest is up to you.

Example using react-nano-state:

import {createContainer} from 'react-nano-state';
const container1 = createContainer(initialValue);
const container2 = createContainer(initialValue);

Create a transaction

Transactions let Immerhin know which containers to update and which patches to apply. They are used to implement automatic undo and sync.

import store from 'immerhin';

// - generate patches
// - update states
// - inform all subscribers
// - register a transaction for potential undo/redo and sync calls
store.createTransaction(
  [container1, container2, ...rest],
  (value1, value2, ...rest) => {
    mutateValue(value1);
    mutateValue(value2);
    // ...
  }
);

Sending the changes

It's up to you how you send the changes. Immerhin provides a sync() function that gives you all accumulated changes so far and clears the stack.

// Setup periodic sync with a fetch, or do this with Websocket
setInterval(async () => {
  const entries = sync();
  await fetch("/patch", { method: "POST", payload: JSON.stringify(entries) });
}, 1000);

Undo/redo the changes

Since Immerhin knows everything from transactions, you just need to call store.undo() or store.redo() to update those containers with revised patches from Immer.

Downsides with Immerhin

Like with any solution, there are tradeoffs. Here are a few I could come up with so far:

Potentially, if one of the consumers did not receive the patches, their state is getting out of sync. Currently, Immerhin doesn't provide a way to work around this. If you have great ideas, please share them on Twitter or over the issues. An ordered id on each transaction could potentially be used to throw an error if something is missing and the client has to refetch.
Immer patches contain a path, but a path is essentially relative to the original object. Should there be inconsistency, the path is going to be wrong. Potentially we could use IDs instead of paths. Also if the previous problem is solved, this is not a huge deal because as soon as the update is out of sync, it can be rejected.
Immer uses patches spec identical to JSON patch with a difference on the path being an array, not a string.

Future of Immerhin

There is a bunch of missing features I really want to implement in the future, and Webstudio will need:

Conflict resolution
Sync mechanism between iframes and tabs

If you click on the "Try Webstudio" button on webstudio.is, you will see the designer interface that uses Immerhin. While the UI is very alpha, I am curious if you will already find obvious bugs with undo/redo functionality.

Webstudio - next generation visual development

Oleg Isonen — Sun, 20 Mar 2022 01:01:20 +0000

Let me show you how an open-source visual development tool will eliminate the friction between developers and designers, whether you are building a small landing page or a complex web application.

Goals

It is critical to understand the goals before jumping into tech because goals are the main driver behind all technical decisions.

We need a visual development tool that can harness the full power of the web platform by embracing its foundation: CSS and HTML.
We must give ownership over content back to the user.
We want to empower designers to contribute directly to the software by manipulating production code visually, no matter how complex that software may be.

Embracing web foundation

The purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise.
-- Ew Dijkstra

We want a tool that lets you express your product visually more precisely than using text. Code in text form depends on many external factors: build tools, interpreters, compilers, etc., making writing code for many cases way harder than it should be.

We want you to manipulate the result while staying true to web fundamentals. You are working with the same CSS properties and HTML elements as if you are writing code, and you will be learning the web fundamentals while building visually.

Visual object manipulation is a higher-level abstraction that enables building for the web even if you have no coding skills.

Fixing ownership

We all have jumped on the train using services that make it easy to publish on the web, but slowly we have all realized that we are not in control over our content anymore.

Several problems have emerged: expensive hosting, unwanted paywalls, government control, technical limitations.

Today, we can easily publish while avoiding all those problems by decoupling content creation and publishing.

Services like Vercel, Netlify, Fly, Cloudflare, and others make it easy to publish on the web without worrying about uptime or infrastructure maintenance and scalability. With Webstudio, you can publish to any infrastructure and stay in complete control. You could even publish on a blockchain. Thanks to Remix, this is already easy from the CLI and will be a one-click action directly from Webstudio later on.

Open source is a requirement

To truly fix the ownership and give creators control over the tool, it is not enough to provide API and SDK. There is still a vendor lock-in in place because without the Designer or infrastructure, you can't continue development.

Making it open-source provides the maximum guarantee that the tool won't suddenly become restrictive or expensive. It is how we say that you can trust us because we keep no leverage. Webstudio can be seen as an open-source alternative to Webflow, though it is much more than that.

Fixing collaboration

Collaboration between design and business logic is still in bad shape. There are no great tools where a designer can build and maintain the design without a handover to a developer in complex projects.

Today designers build mostly static pictures and then hand them over to developers to turn them into code. In some tools like Figma, you can even build interactions and animations, but at the end of the day, it is still a mockup, not a real product. It improves communication but doesn't remove design handoff entirely.

Removing handoff is partially possible for marketing sites using tools like Webflow, but it's very limited in its capabilities, has a complete vendor lock-in, and is quite expensive on top of that.

We need a tool that decouples design from backend and business logic but still integrates with custom code easily.

Webstudio landing site is built with Webstudio

Webstudio is right now in the alpha stage, and it is so alpha that I don't recommend using it in production. It has lots of bugs and lots of missing essential features. That's why the landing site is also very basic, but it demonstrates very powerful architecture. The same architecture would allow me to build a site of virtually any complexity.

I built this landing site visually in Webstudio Designer, then generated a standalone Remix app, synchronized the data from Designer using Webstudio CLI, rendered the site inside Remix using Webstudio SDK and published it on Vercel as a serverless function. 😅 There is a lot to unpack there!

Building landing site visually

Whenever I write CSS in text form and then run it in the browser until it looks the way I want is a serious waste of time. Most of the time, I try to work this around by writing CSS directly in the browser dev tools first and then copy-paste them into the code.

Despite the Webstudio style panel is not ready by a long shot - it felt nice to build it that way, even as a developer who writes CSS as part of the job.

Webstudio style panel is an alternative to browser dev tool for CSS that produces production-ready CSS.

Integration with a custom codebase

I needed to integrate with a custom codebase instead of just publishing the site straight from Designer because I have a signup form that sends data to Notion. In the future, this will be possible using GraphQL bindings, but there will be many other reasons to integrate with a custom codebase, so this is a good proof of concept.

I generated a Remix app by running npx create-remix@latest which guided me through all options. I was going to deploy to Vercel, so I selected Vercel as a deployment target.

$ npx create-remix@latest
💿 Welcome to Remix! Let's get you set up with a new project.

? Where would you like to create your app? ./
? What type of app do you want to create? Just the basics
? Where do you want to deploy? Choose Remix if you're unsure, it's easy to change deployment targets.
  Express Server
  Architect (AWS Lambda)
  Fly.io
  Netlify
❯ Vercel
  Cloudflare Pages
  Cloudflare Workers

Sync the data

The first step is to download the data from Designer API. This is where Webstudio CLI helps - a simple command wstd sync <project id> --host https://alpha.webstudio.is downloads the data as JSON files and puts it in a local .webstudio folder. You don't have to worry about a particular data format because SDK components already know how to render it, so you only have to work with standard React components.

{
  "id": "6235c46edd57c1fddb8ee7ed",
  "root": {
    "component": "Box",
    "id": "6233a4152e5d952bb6fb2118",
    "style": {
      "fontFamily": {
        "type": "keyword",
        "value": "-apple-system, system-ui, Arial"
      },
      "fontSize": {
        "type": "unit",
        "unit": "px",
        "value": 14
      }
   },
    "children": [
      {
        "component": "Box",
        "id": "6230f40d9b138da42f55d3ed",
        "style": {
          "paddingBottom": {
            "type": "unit",
            "unit": "px",
            "value": 30
          }
        }
      }
    ]
  }
}

The data is simply provided to Remix's loader by importing JSON files.

export const loader = async () => {
  return await import(".webstudio");
};

Render components

The next step is to render that data. For this, I used Webstudio SDK that provides all necessary APIs to render React components in any React application as well as components to render a Remix Document.

I am not bound to this specific set of APIs, and I am free to render it with any other framework or just a different set of components. Over time Webstudio will provide adapters for different DOM and CSS rendering frameworks, from Sass and your favorite CSS-in-JS library to React or Vue.

At the moment, SDK is using React and Stitches for rendering, but we look forward to a future where we can render without a framework at all and support all popular frameworks as well.

Custom logic

Remember I mentioned I needed custom code to send email from signup form to notion? We pass our custom Component to the Root component, and we override the SignupForm and SignupSuccess components. Inside those override components, we handle all form submission states and show the success message.

import {
  Root,
  useUserProps,
  WrapperComponent,
} from "@webstudio-is/sdk";
import { useLoaderData } from "remix";
import { SignupForm, SignupSuccess } from "~/signup/components";

const Component = (props) => {
  const { override } = useUserProps(props.id);

  if (override === "SignupForm") {
    return <SignupForm {...props} />;
  }

  if (override === "SignupSuccess") {
    return <SignupSuccess {...props} />;
  }

  return <WrapperComponent {...props} />;
};

export default function Index() {
  const data = useLoaderData();
  return <Root data={data} Component={Component} />;
}

Publishing

At this point, publishing is a no-brainer. You can push to git and setup Vercel to import from it or publish directly from CLI npm i -g vercel && vercel.

Next time you change design in Webstudio you have to run the sync CLI locally and publish the changes from your computer. In the future we will have an optional automation that will let you either publish automatically directly from Webstudio or create a Pull Request with changes and a link to preview, so that developers can review it before publishing.

Become part of this mission

Please don't hesitate to share your thoughts and ideas on github. Also don't forget to give it a star, because this is how we know you liked what you saw.

Is REST simpler than GraphQL?

Oleg Isonen — Sat, 19 Mar 2022 12:01:43 +0000

It came to my attention that many perceive GraphQL as a complex way to communicate with an API compared to REST. It seems there is a perception that REST is somehow simple and easy, and I think it's really not.

Let's compare apples to apples

When we compare GraphQL to REST, we usually don't compare the same thing because we take a simple REST API setup and compare it with a complex GraphQL setup.

To really compare adequately, we need to compare either a very simple setup in both cases or an equally complex setup. In this article, I am going to simplify the GraphQL setup to the level of a simple REST.

First of all, what's the biggest thing that makes you think GraphQL is complex? My bet is the client-side code that most people use. Let's remove it.

Let's take this GraphQL API https://api.spacex.land/graphql/ and try to avoid using any abstractions to fetch some data. GraphiQL UI gives us a way to learn what is being sent and received very easily, so I just need to grab the query from network UI in the Browser DevTools.

It sends an XHR request using POST to the endpoint. The GraphQL query of the request is this:

launchesPast(limit: 2) {
    mission_name
    launch_date_local    
    rocket {
        rocket_name
    }
}

This query is supposed to fetch a list of past SpaceX Rocket launches, limit the results to 2 items, and return mission name, launch date, and rocket name.

To actually send this request using built-in browser API, I would need to do this:

const endpoint = 'https://api.spacex.land/graphql/'
const method = 'POST'
const headers = {'content-type': 'application/json'}
const body = JSON.stringify({
    query: `{
        launchesPast(limit: 2) {
            mission_name
            launch_date_local    
            rocket {
                rocket_name
            }
        }
    }`,
    variables: null
})
const response = await fetch(endpoint, {method, headers, body})
const json = await response.json()

The JSON result we get looks like this:

{
  "data": {
    "launchesPast": [
      {
        "mission_name": "Starlink-15 (v1.0)",
        "launch_date_local": "2020-10-24T11:31:00-04:00",
        "rocket": {
          "rocket_name": "Falcon 9"
        }
      },
      {
        "mission_name": "Sentinel-6 Michael Freilich",
        "launch_date_local": "2020-11-21T09:17:00-08:00",
        "rocket": {
          "rocket_name": "Falcon 9"
        }
      }
    ]
  }
}

Let's see what we have to do to get the same result from a REST API by using browser APIs only. Since I don't really have the same API, I will just imagine what it would be if we had it:

const endpoint = 'https://api.spacex.land/launches/'
const method = 'GET'
const headers = {'content-type': 'application/json'}
// We use URLSearchParams here for the sake of encoding.
const query = new URLSearchParams()
query.append('limit', 2)
query.append( 'filter', [
    'mission_name', 
    'launch_date_local', 
    'rocket.rocket_name'
])
const response = await fetch(`${endpoint}?${query}`, {method, headers, body})
const json = await response.json()

I am sure you would agree that the complexity between these two examples is very similar if we really compare the same thing from the client setup code perspective.

A hidden difference

When we compare a primitive type of usage, they seem very similar. There aren't many benefits for one over another, though when you look closely, you will recognize that even here, GraphQL has solved a few big problems already:

GraphQL dictates a single way of requesting the data. You don't have to agree with your team on when to use which HTTP method, query-string, or paths, how to structure the URL, how to specify additional parameters like the limit of results and fields to return. Even in this primitive example, you can see that GraphQL, as the name implies, is a language where REST is just a pattern that is flexible enough to allow your team to build inconsistent and messy APIs.
The shape of the query is also the shape of data you will receive quite literally. This is another missing piece in the REST contract where you usually have no way of specifying the shape of the data, while in practice, a change in the shape will likely break your application.

The core reason why we need GraphQL

We often talk of HTTP APIs as some simple data fetching mechanism. You send a request, you get some data - easy enough, sure. We really fail to mention that it's not just some data most of the time, it's a contract.

API is a contract between two parties that is supposed to specify how exactly I can get and send the data, what data in which shape I am going to receive, and finally, what type it is gonna have. Potentially you can have all that with REST too, but that's where GraphQL helps you to do it consistently.

It has become super relevant as we entered the age of distributed systems and microservices. A complex application consists of dozens or hundreds of APIs, some of which are often provided by a 3rd party. When all of them vary in the level of safety and precision, how robust is your application going to be in the end, really? How many bugs do you think are created because of weak contracts? 10%? 20%? 30%?

Advanced usage

While you can use GraphQL for very simple use cases - you still get many benefits, but it doesn't stop there. It offers solutions for mutating data, describing types of data, conditional query logic, composing data from multiple sources, and much more. It really shows the difference between a language and a pattern.

Despite that GraphQL is best for dynamic data, it's still possible to implement caching and avoid slow responses for complex schemas.

For example, a startup GraphCDN created a caching layer on top of CDN that works with any GraphQL API implementation. It is only possible because GraphQL makes you specify everything that is needed by design to allow smart caching.
Not only is GraphCDN able to avoid doing unnecessary computation on your application servers - it does so using edge computing. That means a client has a much shorter response time after the initial response was cached because the client will receive a response from a server geolocated nearby.

Last words on UI architecture before an AI takes over

Oleg Isonen — Sun, 22 Aug 2021 10:36:27 +0000

“Big Ball of Mud” is the current state of the UI architecture, despite component-based composition.

Components are not enough

Components and composition are just one piece of architecture. You still need to know how to compose pieces without recreating the “Big Ball of Mud” using a new (not really) shiny components-based approach.

Components are too generic to actually solve architectural problems. They are comparable to the bricks. You can for sure use bricks to build a house, but there is so much more to building a house that bricks aren’t even 10% of what you need to use.

New Architecture?

We spent decades defining methodologies and principles for great architecture and yet here we are — every new job will surprise you with new ways of creating an utterly broken architecture.

Is everyone stupid? Did nobody read about SoC, SOLID, DRY, KISS, WTF, GoF, GRASP YAGNI, WTF, Atomic Design, DDD, Onion, Clean Architecture, etc?

I am sure everyone heard at least one or two of those and maybe even understood them, so what’s the problem? Why can’t we have a better architecture in practice?

Maybe all we need is another, “better” architecture that solves all the problems? (Not really)

Theory vs. practice

These are the most popular reasons why your organization will inevitably fail at the architectural level:

Many well-known principles and methodologies are conflicting.
Requirements change over time.
Organizational restructuring.
There are no generic good ways to enforce a particular architecture.
Poor communication of the applied architecture.
Practical implementation difficulties.

Conflicting principles

Let’s take one example: DRY — Don’t Repeat Yourself vs. High Cohesion — keep related code close.

In theory, they both sound great, though both of them fall apart when you have 2 independent features that need the same function. I understand this is too theoretical and it never happened to YOU in the real world /s, but bear with me for a second.

As soon as you have to share a function between 2 features you have 3 options:

Let feature A import that function from feature B directly and marry both features together in the sense one has to know about the existence of the other.
Move that shared function into some “shared” directory and use it from both places.
Copy that function into both features

If you are reusing that function, you are breaking “High Cohesion”. If you are copying — you are breaking DRY.

And this is just one simple example, there are many more.

Changing requirements

In the modern world of startups, every company starts with some small prototype that can be manufactured quickly and then hopes to evolve it into something better.

When building things quick and dirty — you don’t have time for good architecture, let alone you don’t know yet what “good” means for that particular product.

Product is changing and so are the requirements. You either have decades of experience and can predict what architecture needs to be because you saw this very same thing happening already or you will start with some baseline architecture that minimizes your risks.

Organizational restructuring

It’s not a secret that the architecture needs to not only be designed around the product requirements but also around the people working on it.

If you have a team of 2 engineers, exchanging information, agreeing on architecture, and keeping things consistent is one million times easier than having a team of 20 people. (please teach me the math here /s)

Every product starts with a small team and then adds the team members over time. People join, people leave and communication pathways change all the time.

Can we have an architecture that is correct no matter how many people work on the product?

Enforcing an architecture

If a magical tool existed that could enforce every principle and every architectural decision that is used on a product, we could have a consistent architecture and much better communication of it.

People don’t read docs. They don’t read not because they don’t know how to, but because they don’t know what those words mean in their specific context, and learning it is hard work.

Tools can tell a person to read something when they are about to make a mistake or create an inconsistency, but creating such tools is hard because many violations of principles are hard to detect in code.

We definitely need tools to communicate architecture, and yet, do we know many tools that try to do that at least on some basic level?

Poor communication

Documentation is hard. Documentation of principles and methodologies is harder. Documenting them well as a by-product of some product work — impossible.

Your internal documentation around principles and architecture will always suck unless you have people who have a serious level of dedication for the topic — aka “architect”.

How many companies have you worked for that have people with architectural roles?

Tactics vs. logistics

One dude said once:

“The amateurs discuss tactics: the professionals discuss logistics.”

Tactics in our context are the same as abstract principles and methodologies. Those are just words that don’t tell you what to do in your context because they are too abstract and conflicting.

The missing piece in the industry is a set of principles that can be well understood and applied in practice that go along with tools that help to enforce them.

This is the logistics analogy.

Solution

Am I here to just criticize the current state or to move the needle? Well, without agreeing on critiques we can’t move on to something better. Can we come up with something better? I believe so.

I expressed some ideas in my talk in 2018 with the title “Feature Driven Architecture” https://www.youtube.com/watch?v=BWAeYuWFHhs

There is nothing fundamentally new in it, it is a collection of well-known ideas put together into a single practical architecture.

If you like and retweet this article hard enough, I might work on defining those ideas and examples more clearly in this repository https://github.com/kof/feature-driven-architecture

Features are everything

The word "features" is the most common to describe application-level components. An application will have features added, removed, modified. It will have big features, small features, life-changing features. Features that make you proud of yourself, features that will embarrass the entire company. Features are the most important piece of every application.

This is why it is so important to make it your life goal as an architect of an application to make sure a feature can be added, removed, or extended with the least amount of work.

Being able to completely remove a feature without leaving pieces of logic left behind spread over the entire application is the key to a maintainable product.

An ultimate test for any architecture should be to remove a feature directory from the file system and the application should stay fully functional without it.

An ideal feature contains everything it needs.

Principles of a feature

These are the most important principles that have to be followed in a Feature Driven Architecture:

1. A feature can not know other features or its consumers.

It’s simple — you will break one feature when you change the other otherwise. You also can’t remove one feature without affecting another, if you break this principle.

2. A feature has to express its dependencies declaratively.

If there is data or any other dependencies — it has to express them declaratively and a consumer should be able to provide them.

Much like a component, features don’t live in a vacuum, they have dependencies. To name a few: data, static artifacts like images, libraries, functions shared between features, knowledge of app architecture, build system, and more.

Dependencies are what makes it hard to build features that are fully encapsulated and integrate well with the rest of the application. That’s why on the architectural level we can only define basic rules of behavior, but not the specifics around implementation details because those will vary depending on your stack and particular business requirements.

An ideal feature doesn’t have dependencies.

3. Be disposable

Much like a component, a feature has to be disposable. You need to architect the feature so that you can remove it easily. That’s the whole point.

Screens

If one feature doesn’t know any other feature, there has to be something else that knows all the features, otherwise, we will render a vacuum.

Screens have to follow the same principles we described for the feature for the exact same reasons. In addition, it acts as a features manager:

1. Doesn’t know about other screens

2. Renders the features

A screen can import a feature and access its public API, including its rendering interface and its declaration of dependencies. The screen’s main goal is to render the features on the screen.

3. Provides dependencies

In case a feature can not satisfy its dependencies itself, a screen will have to provide them. It could be static artifacts, data, or anything else. Important is that if a feature can provide those things itself — it should. I can only see the need to express dependencies when the dependency is outside of features scope or it is something 2+ features on the screen depend on, so it would potentially make sense to hoist the logic to the screen.

4. Connects the features

Sometimes one feature depends on something that some other feature has or does, but since features can’t know about each other, this dependency has to be expressed via a simplified protocol.

If the dependency is data — one feature has to express what data it requires via an interface and the screen will pipe that data from one feature into another while trying to keep the least amount of knowledge about its contents.

The more screen knows about each feature — the harder will it be to remove a feature from the screen.

Clusters

Sometimes a set of independent features is used on 2+ screens together as a set. You don’t need a cluster to achieve that if a feature is fully self-contained, but if a feature has dependencies provided by the screen — you would have to duplicate the setup logic that wires up those features 2+ times for each screen.

If that setup code a feature needs is trivial — you may want to avoid having a cluster to avoid the need for this additional abstraction.

But if you end up needing a cluster — the rules it follows are similar to a feature:

Doesn’t know about other clusters
Doesn’t know about screens
Knows all features from that cluster and exposes a declarative interface for the screen.
Provides features with dependencies just like a screen.

Shared

Sometimes you need to share a function between features, screens, or clusters that has business awareness. This is where a “shared” space comes in handy.

Shared space has one rule to follow — it can’t directly depend on anything outside of “shared” except the libraries. It can’t depend on a feature, screen or a cluster.

Libraries

The final and the most low-level piece is a library. A library has no knowledge about business logic. It can be published to or installed from an Open Source repository and can be shared between businesses. You can have a lib directory inside the product or you can treat the installed package from an external source as a lib. One example is the node_modules package, if it doesn’t contain a business-aware logic — it's a library.

To sum it up, my proposal is to split an application by a number of principled types that would let your application be maintainable, guided by the need to have built-in discoverability, disposability, and scalability. The proposed types are in the order from higher to a lower level of abstraction:

Screens
Clusters
Features
Shared
Libraries

I am certain the constraints I expressed are basic and there is more to it. We need to work on a well-defined spec for them. I am also certain that enforcing those constraints should be automated one way or another and we need to build tools and interfaces to make a consistent architecture.

Why React’s Model is successful

Oleg Isonen — Tue, 07 Apr 2020 10:06:49 +0000

Throughout the history of React there have been many ways to describe what it does that makes its programming model successful and for sure there are multiple aspects to it, but let's have a look into its foundation — components.

One of the most important characteristics for building large software is its maintainability and the most scalable mental framework for maintainability is the ability to delete and replace pieces of the system. So what makes React so special about code removal?

Props

Props are the main way for a React component to receive information. It is its standard input interface. Props are pretty much the same to a React component as arguments are to a function, but with a small but important difference — components are automatically “subscribed” to the latest version of props and are getting executed automatically by React.

Another interesting detail about props is that they can contain any data type, which can be used as a backchannel for communication. For example, by calling a function a child component received over props, it can communicate back to the parent component.

Children

Children is a mechanism that gives React components 2 abilities: composition and nesting. What I mean is a particular kind of composition — the ability to render a component A inside of component B without component B knowing anything about component A. This can be achieved as well using props, in fact, “children” is a special key in props, but that’s an implementation detail. What’s important is that it enables nesting:

<ComponentA><ComponentB /></ComponentA>

Elements

React elements is generally speaking a platform-agnostic description of renderable nodes. It’s a spec that component returns to React and describes components React needs to initialize and what props and children they will receive.
The fact that we usually use JSX to describe elements or even that JSX is transpiled to a React.createElement() function call is just another implementation detail.

React has created a system that allows a component to receive data, express what needs to be rendered in return and allows it to get composed. This is the foundation and the main reason why React’s approach to building user interfaces scales — each component implements the same interface and can be replaced. In addition, the fact that React application is a tree, by replacing a single component you are able to replace an entire subtree it renders, giving you the ability to replace large building blocks at once.

It’s not about VirtualDOM, JSX, hooks, state, context, performance or pure functions. Even though they are all important, they are just implementation details.

How to kill creativity: The Definitive Guide

Oleg Isonen — Thu, 02 Jan 2020 19:09:34 +0000

I woke up today with a bunch of ideas about how a particular problem could be solved or at least what could be a better attempt than what I had so far because the problem is non-trivial and there is no standard well-known way to do it.

At the same time, I realized why it took me so long.

I was blocked for over a year

The problem I was thinking about was something I started to work on over a year ago. I did a prototype, settled on one particular implementation and then realized the problem is hard and doing it that way will result in too many problems later. This realization made me feel frustrated. I stopped working on it and thinking about it.

A few days ago I decided to look at it again and I struggled to figure out what I was thinking as I did that initial prototype. I couldn't understand most of the code I wrote, it's been frustrating, I was staring at it for the entire day until I decided to throw it away. Luckily I had integration tests, so I could drop the implementation and rewrite it from scratch. Within a few hours, I rediscovered most of the problems I had over a year ago and why I stopped working on it. The difference now was though that I am determined to solve it, so I kept thinking about it and woke up with a bunch of ideas today.

What I learned out of it blew my mind: I was able to think about potential different solutions because I didn't have a definitive answer.

I don't like reading books

It might come surprising to you to hear that from someone from a tech industry since we are considered "intelligent" by the rest of the world. It's not like I don't like to read at all, in fact sometimes I enjoy doing so. I am reading stuff every day, but the only reason I do so is I am searching for a particular information or I read some short blog posts about a topic I care about. I never read a book from the beginning till the end just because it was recommended.

Today I realized I don't like reading a particular type of content: the one that gives you a definitive answer to everything it touches. It turns out I enjoy discovering things much more than I enjoy learning the facts.

I realize not every book is a definitive guide, there are tons of books that spark your imagination and let you think creatively, I never realized that this is what makes me like one over another.

A book or a blog post that gives you a definitive answer to a problem diminishes your ability to think creatively. Ultimately it creates an internal conflict and builds up a wall between the solution and the reader.

My biggest learning so far

If you are writing a book, an article or even a tweet. If you are trying to propose a solution to a group of people. When people have different opinions about literally everything - the worst thing you can do is to provide a definitive solution.

Instead, one could provide a clear problem-definition and eventually name a few potential ideas which could be thought of but shouldn't come over as a definitive solution. The last part is the most critical because the second your receiver realizes there is a solution already provided, you are taking their ability to think creatively.

Gifting a joy of discovery to your receiver is the best thing you can do as someone who tries to convey a message or foster productivity.

What happens in the brain of a receiver-person

When you announce a solution to a group of people that is supposed to solve that problem, this is what I feel is happening in their brains:

They realize their help is not needed, their presence is a pure formality, the value of oneself is starting to fade.
There is not much one can do now, especially if the author is the leader of the group, because it makes it even more clear that the solution is set in stones.
Anything a receiver will say from now on that goes against that solution is going to be received as critique and potentially create conflict.
It upsets the receiver and blocks their ability to process new information.

A friend pointed out to me there is a scientific research about this topic in case you want to study this.

The worst thing about it

The short-term effect is going to be forgotten soon enough, but the long term effect of this solution-giving approach is truly harmful to any organization.
A one-off event usually doesn't change much, but if it happens often enough, the result is - you are building a culture where people don't think on their own.
Once this becomes a natural way of thinking within the same group of people, this group will neither think critically nor creatively anymore, they will just follow the orders. We know plenty of examples of such cultures: military, police, religions. People in all of those groups tend to show blindness in critical and creative thinking towards their leaders and foundations of that particular culture.

There is an exception to every rule, but we are talking about a tendency here.

I don't know why, but this realization today made me somehow feel free and happy once again, so I wrote it in the hope it will do the same for you.
Today I wasn't lazy and wrote it as a blog post, but most of the time I share thoughts on twitter, so if you are interested in my low-quality award-losing content, follow me there @oleg008.