Интересное ограничение Typescript

При написании хука для более удобной работы со списками данных (объектов), столкнулся с интересной особенностью Typescript.

Для начала приведу пример (предполагаемого) использования:

// Если в качестве ключа используется параметр с именем id
const [list, handlers] = useListState<ItemType>();

// Если в качестве ключа необходимо указать конкретное имя поля
const [list, handlers] = useListState<ItemType>('someId');

Ключ необходим для таких методов как has, remove и т.п., благодаря чему в качестве аргумента достаточно будет передать значение этого поля. Например, для удаления элемента из списка достаточно вызвать:

handlers.remove('some-id-value');

Теперь давайте про Typescript. Если в качестве ключа я указал название поля с типом string, то и в методах типа remove, в качестве аргумента должна приниматься именно строка. В чём же проблема? А в том, что при указании типа до аргументов, а название ключа в аргументах, Typescript не поймёт вас и не сможет вывести необходимо значение в возвращаемом типе. Другими словами, и тип и ключ должны оба быть в одном месте:

// или до аргументов:
useListState<ItemType, 'someId'>('someId');

// или в аргументах:
useListState([] as ItemType[], 'someId');

В обоих случаях получается не так красиво как хотелось бы: в первом приходится дублировать имя ключа, а во втором вообще добавлять ещё один аргумент.

Есть и третий вариант решения (который тоже не очень):

// сначала необходимо создать хук с нужным типом
const useListState = createListState<ItemType>();

// а затем, при использовании, указывать ключ
useListState('someId');

Если что, вот ссылка на сам хук:
https://gist.github.com/SanichKotikov/510004365de8cafbd51623b581b5733c

Хотя кто знает, может решение всё же есть. Если найдёте, напишите.

Архитектура: функциональное проектирование

Я недавно писал про архитектуру на примере React компонентов, где в конце приводится схема слоёного “пирога”, на которой сверху данные, посередине управляющие компоненты, а снизу “глупые” компоненты. А теперь давайте попробуем взглянуть на код чуть глобальнее.

Итак, в целом весь наш код можно разделить на три условные категории:

Данные

Тут всё просто, данные есть данные, например пользователь в системе или транзакция в банковской системе. Их преимущество в том, что они прозрачны и могут быть интерпретированы по-разному.

Вычисления

Это преобразование данных без побочных эффектов. Они не зависят от места и времени выполнения, и всегда возвращают одинаковый результат при одинаковых входных данных. Другими словами, это чистые функции.

Действия

Действия напротив, зависят от места и времени выполнения. Можно сказать что это функции с побочными эффектами. Например, сохранение или чтение пользователя из базы является действиями.

Обратите внимание на порядок, в котором описаны эти категории, он не случаен. Данные — фундамент любого продукта, и как уже было сказано, они прозрачны и интерпретировать их можно как угодно. Далее идут вычисления (чистые функции), их проще писать и тестировать. Это довольно обширный пласт и может включать в себя много уровней, от работы с типами и структурами языка программирования до всевозможной бизнес-логики разных уровней. А замыкают всё действия, оперируя данными и вычислениями. Этот уровень больше подвержен ошибкам и в него чаще всего вносятся изменения, и при этом его может быть не так просто протестировать. Именно при работе с последним уровнем нужно быть максимально внимательным.

А теперь давайте вернёмся к примеру React компонентов, и возможно вы уже понимаете почему так важно стремиться к тому, что бы у вас было как можно больше “глупых” компонентов и как можно меньше “умных”. Да, всё просто, глупые компоненты являются вычислениями, а умные (управляющие) — действиями. Глупые компоненты реже меняются, их легко переиспользовать и они меньше подвержены ошибкам. Управляющие компоненты напротив, меняются чаще, их практически невозможно использовать повторно, и шанс допустить в них ошибку гораздо выше.

Есть ещё один важный момент — если вычисление использует действие, то оно автоматически становится действием, со всеми вытекающими!

#development #frontend #architecture

Архитектура: раскладываем код по папкам

Примечание №1: под словом “компонент”, без приставки UI, будет подразумеваться именно компонент системы, а не интерфейса.

Примечание №2: какой бы вы подход не выбрали, этот, FSD, классический или ещё какой-то, это никак не скажется на качестве вашего кода и системы в целом. Правила это не главное, главное то как ими распорядиться.

Пришло время описать схему, по которой я “раскладываю код по папкам”, года так с 2019. Всё это время я пробовал менять в ней разные нюансы, сравнивал, делал выводы, но база оставалась всегда одна — фокус на предметной области. Максимально простое объяснение этой схемы можно выразить следующей строкой:

Feature/Segment/Component

Предположим, вы пишите приложение для сети общепита. В данном случае предметная область будет включать сотрудников, филиалы, меню и заказы. Добавим ко всему этому “базовую” функциональность и компоненты касающиеся самого приложения и получим верхний уровень структуры:

📁 _core
📁 _ui-kit*
📂 branch
📂 employee
📂 menu
📂 order
📁 app

Папку _core, в теории, можно переносить из проекта в проект, т.к. она не должна содержать ничего что относится к нашей предметной области. А вот что она должна содержать, так это всевозможные утилиты для работы с примитивами языка, api платформы (fetch, storages), какие-то базовые хуки (если мы используем React или SolidJS), типы и т.п. Компоненты из папки _core можно использовать в любой части системы, при этом сама папка не может импортировать что-либо из соседних папок.

В папке _ui-kit лежат все базовые UI компоненты: кнопки, поля ввода, выпадающие списки и т.п. Компоненты этой папки можно использовать в любой части системы, кроме папки _core. В случае если вы используете сторонний ui-kit, то возможно, разумнее будет положить свои дополнительные UI компоненты в _core/ui.

В папке app хранится всё, что относится к специфике текущего приложения, но при этом не относится ни к _core, ни к предметной области. Это может быть общая разметка, интеграции со сторонними сервисами, логирование ошибок и т.п. Эта папка может использовать любые другие, но её использовать ни кто не может.

Все остальные папки верхнего уровня — “фичи” предметной области. Эти папки могут использовать компоненты из любой другой, кроме app. Кстати, в использовании компонентов из одной фичи в другой нет ни чего плохого, главное чтобы не было циклических зависимостей.

Второй уровень — Segment

Этот уровень описывает сегменты из которых может состоять любая папка первого уровня. Перечислю основные:

📁 type — typescript типы;
📁 lib — утилиты и хуки;
📁 context — контексты и их типы;
📁 ui — “глупые” UI компоненты;
📂 api — общение с сервером;
📂 control — “умные” UI компоненты и провайдеры;
📂 page — страницы;

Сразу отмечу что порядок, в котором выстроен этот список, имеет важное значение — сегмент может использовать всё что расположено выше него, и не может использовать всё что ниже. Например, page может импортировать модули из api, а вот ui не может.

Второй момент, на который стоит обратить внимание — api, control и page являются “умными” сегментами, т.к именно тут сосредоточены “действия”. Всё остальное должно относится к “вычислениям” или “данным”.

Иногда я думаю над тем, что бы добавить этим трём папкам какой-то префикс, например !, который бы отличал их от остальных. Но пока это открытый вопрос.

[продолжение ниже]

#development #frontend #architecture

[продолжение]

Третий уровень — Component

Тут только одно, но очень важное, правило: компонент может быть как единственным файлом, так и папкой с экспортом через index-файл внутри. Другими словами, импорт любого компонента вашей системы должен быть из трёх составляющих:

import { component } from 'feature/segment/component';

Ещё один важный момент: в папках первого и второго уровней не должно быть ни одного index-файла. Кого-то это может возмутить, мол как же так, но стоит вам попробовать и вы поймёте всю прелесть этого решения. 😎 По сути, в этой системе “публичным” интерфейсом обладают только её компоненты.

Также допустимые импорты:

// Соседний компонент
import { component } from '../component';

// Соседний файл
import { component } from './component';

Примеры не допустимых импортов:

../../something, ../../../something и т.п.
../component/file-inside
domain/segment/component/file-inside

Из этих примеров должно быть понятно, что схема не подразумевает глубокой вложенности папок, всё должно быть максимально плоско.

Думается мне, этим постом можно закрыть серию про архитектуру, по крайней мере на какое-то время.

П.С. Пишите хорошие (маленькие) функции, и хорошая архитектура сама подтянется.

#frontend #development #architecture

Интересное мнение про найм в современных реалиях:
https://habr.com/p/882392/

Одна из важнейших особенностей работы над большим проектом — цена изменений!

Речь, конечно же, про изменения которые так или иначе касаются всего проекта, какие-то базовые библиотеки, функции, компоненты, подходы и т.п. В общем, всё то, чем постоянно приходится пользоваться и без чего не может обойтись практически ни одна страница проекта.

Сразу хочу предупредить, что какие-то локальные изменения, в последствии, тоже могут стать глобальными. Другими словами, не стоит думать что, например, я вот сейчас тут добавлю какую-то новую модную библиотеку и это ни чего не будет стоить. Вполне может оказаться так, что будет. Добавить что-то в проект и выпилить это потом из него, это далеко не одно и тоже! Помните про это.

Но давайте вернёмся к глобальным частям. Иногда так получается, что некоторые вещи в проекте, которые изначально казались удобными, “вдруг” становятся не такими уж и удобными, и вам приходит мысль это дело исправить. Первое и самое важное, что нужно сделать в этот момент — очень хорошо подумать, ведь ваше новое решение, которое вам в моменте покажется удобным, через пол года может “снова” оказаться не таким уж и удобным. И даже когда вам покажется что вы ну уж точно всё продумали, сделайте паузу, скушайте тви… посоветуйтесь с опытными коллегами, почитайте что-то на релевантную тему и т.д.

Отдельное внимание стоит обратить на моменты, когда планируете не заменить что-то, а сделать аналогичное (только “лучше”) рядом. Рекомендую всё-таки подумать именно над заменой, а к варианту “рядом” обращаться только в крайних случаях. Тут вы возможно хотите возразить, мол мы старый подход/функцию/компонент/библиотеку потом постепенно выпилим. Не выпилите! 🤪

Маленький, но очень важный совет: если всё же делаете “рядом”, например какую-то функцию. Пометьте устаревший вариант как deprecated, только не забудь указать причину или рекомендации, например:

/** @deprecated use %name% from %path% */

И кстати, если содержимое старой функции можно заменить вызовом новой, это также стоит сделать. Как минимум вы удалите лишний код, а как максимум “источник” правды останется один.

Если всего этого не делать, то ваш большой проект, который со временем станет ещё больше, может превратиться в месиво разных подходов, библиотек делающих одно и тоже, одинаковых компонентов и т.п. Иногда лучше жить с одним не очень хорошо, но работающим решением, чем плодить сущности делающие одно и тоже.

#development

Overrides в package.json (NPM)

Пока многие сидят на yarn и pnpm, а может и ещё чём-то, npm тоже не стоит на месте. На днях обнаружил что в нём тоже есть overrides, причём уже довольно давно 😅

Overrides позволяет переопределять версии вложенных пакетов:

"devDependencies": {
  "@storybook/builder-vite": "8.5.6",
  "storybook-solidjs-vite": "1.0.0-beta.6"
},
"overrides": {
  "storybook-solidjs-vite": {
    "@storybook/builder-vite": "$@storybook/builder-vite"
  }
}

Конкретно в этом случае, в пакете storybook-solidjs-vite используется последняя не стабильная версия пакета @storybook/builder-vite. Переопределение версии позволяет избавиться от ошибки запуска storybook.

Кстати, символ $ позволяет переопределять версию на ту, которую мы определили в своих зависимостях, в данном случае в devDependencies.

Вот полная дока:
https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#overrides

#development #frontend #package #npm

Делюсь лайфхаком как узнавать о новых фишках html, css и js которые уже работают в последних версиях браузеров: После очередного обновления Safari заходим на https://webkit.org и смотрим там описание что добавили 😅

Branded Types в TypeScript

Branded types — полезный инструмент, хотя и используют его довольно редко.

Почти все данные с которыми мы работаем в коде, так или иначе, сводятся к примитивам. При этом, по смыслу, одни строки могут сильно отличаться от других, собственно, как и числа. Простой пример:

interface User {
  id: string;
  name: string;
  phone: string;
  email: string;
}

С точки зрения бизнес логики все эти строковые поля имеют разный тип данных, и работать с ними нужно по-разному, но для нашего кода всё это просто строки. Другими словами, типы как бы есть, но их как бы и нет… Ситуация усложняется, если у вас большая распределённая система и сервисам нужно точно знать какие данные передавать друг другу.

В идеале, тип пользователя должен выглядеть вот так:

interface User {
  id: UUID;
  name: string;
  phone: PhoneString;
  email: EmailString;
}

Хочу сразу обратить внимание на ещё один важный нюанс, который на примере интерфейса пользователя может быть не так очевиден — читабельность. Например, понятно что поле phone содержит телефон, хотя строки с телефонами тоже бывают разные. А вот что по вашему может содержать следующее поле?

recipientExternalId: string;

Наверное, какой-то id, хотя на деле всё что угодно. Но если использовать branded types, всё становится очевидным:

recipientExternalId: PhoneString;

Что же из себя представляют эти branded types?

По сути, это особый вид примитива, например строки:

type PhoneString = string & { __brand: 'PhoneString' };

Однако для TypeScript это будет отдельный тип. Другими словами, если функция форматирования телефона принимает в качестве аргумента PhoneString, обычную строку передать не получится:

function formatPhone(phone: PhoneString): string {
  return phone.replace(
    /^(\d)?(\d{3})(\d{3})(\d{4})$/,
    '+$1 ($2) $3-$4'
  );
}

formatPhone('11111111111');
// => TS Error:
// Argument of type 'string' is not assignable
// to parameter of type 'PhoneString'.

Важно: объект в branded types должен быть уникален для каждого нового типа.

П.С. Можно кстати сделать специальную утилиту:

declare const __brand: unique symbol;
type Branded<T, B extends string> = T & { [__brand]: B };

type PhoneString = Branded<string, 'PhoneString'>;
type EmailString = Branded<string, 'EmailString'>;

#development #frontend #typescript

Попался доклад про дата-ориентированное программирование.
https://youtu.be/oukpjkET6j4

Минимальный фронтовый Dockerfile с поддержкой Brotli

Brotli — алгоритм сжатия данных. Наравне с gzip, позволяет уменьшить размер передаваемых по сети данных, но делает это несколько эффективнее. Если gzip можно использовать “из коробки”, то вот brotli приходится настраивать руками.

# build container
FROM node:20-alpine AS builder

WORKDIR /app
COPY . .

RUN npm i
RUN npm run build

# runtime container
FROM alpine

RUN apk add brotli nginx nginx-mod-http-brotli

COPY --from=builder /app/dist /usr/share/nginx/html
COPY ./nginx/nginx.conf /etc/nginx/http.d/default.conf

CMD ["nginx", "-g", "daemon off;"]
EXPOSE 80
EXPOSE 443

Для включения, также, необходимо добавить несколько строк в ваш nginx.conf:

brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/javascript application/json;

#development #frontend #docker #nginx

Код 10 летней давности 😱

Наткнулся на свою реализацию всем известной игры “Змейка”, было такое тестовое задание. Коду почти 10 лет, там даже es6 ещё нет. 😅

Работает как на клавиатуре (на стрелочках), так и на телефонах (тап по сторонам игрового поля).

Код: https://github.com/SanichKotikov/test-snake-game/blob/master/index.html

Игра: https://sanichkotikov.github.io/test-snake-game/

П.С. Кто помнит для чего эта точка с запятой в начале кода? 😅

;(function (){
  // code
})();

Минимальный “джентльменский набор” для стилизации разметки

Есть куча разных подходов, языков и инструментов для стилизации разметки, но мой выбор всегда был, и наверное будет, в пользу чистого CSS. Почему именно так — отдельный вопрос, сейчас не об этом.

CSS modules

Для начала, необходимо решить проблему именования. Нет именования — нет проблемы. 😎 CSS modules полностью закрывает этот вопрос, и избавляет нас от необходимости придумывать уникальные имена CSS классов в рамках проекта. Например, в Vite конфигурация может выглядеть следующим образом:

css: {
  modules: {
    localsConvention: 'dashesOnly',
  },
},

CSS custom properties + CSS nesting

Кастомные свойства, они же переменные, поддерживаются всеми браузерами с 2017 года. Сегодня их можно использовать как есть, без каких либо дополнительных инструментов. Например, для поддержки нескольких тем оформления, или просто как глобальные константы:

:root {
  --color-primary: #7f56d9;
  --color-accent: #89e469;
  --color-warning: #e9ae56;
  --color-danger: #ff0000;
}

Для вложенных селекторов существует спецификация CSS Nesting, которая поддерживается основными браузерами с 2023 года. На данный момент такой поддержки всё ещё маловато, поэтому тут не обойтись без инструментов, например npm пакета postcss-nesting.

PostCSS + Autoprefixer

Ну и конечно, куда же без этой парочки. Как бы ни старались разработчики браузеров, всё ещё существуют CSS свойства с разными префиксами. Нет ни какой пользы в том, чтобы писать их самостоятельно, лучше доверить это дело автоматизации.

import nesting from 'postcss-nesting';
import autoprefixer from 'autoprefixer';

export default {
  plugins: [
    nesting({}),
    autoprefixer({ flexbox: 'no-2009' }),
  ],
};

Вот и весь набор! Всё максимально просто и компактно.

#frontend #development #npm #css #postcss

CSS content-visibility

Оптимизировать скорость отображения большого количества элементов можно не только через Javascript. Хороший пример — CSS свойство content-visibility, которое напрямую влияет на такие этапы как recalculate styles, layout и paint. Для примера, рассмотрим простой SolidJS код отображения списка из 1898 emoji разделённых на 9 групп:

https://github.com/SanichKotikov/solid-emoji-demo
(компонент EmojiList)

Если запустить приведённый выше пример, и посмотреть во вкладку Performance инструментов разработки браузера, вы увидите что бОльшая часть времени уходит не на выполнение Javascript, а на тот самый layout. Происходит это потому, что браузеру нужно “посчитать” весь список полностью, несмотря на то что пользователь видит только малую его часть. Вот тут нам и пригодится content-visibility, с помощью которого мы можем “попросить” браузер не считать то, что пользователь ещё не видит (в нашем случае группы).

Обратите внимание, что “спрятанный” таким образом контент остаётся достижимым для таких операций как поиск на странице, в отличие от виртуализации на Javascript.

Важное примечание: Цифры приведённые ниже — MacBook M1. Для сравнения, iPhone 12 pro в режиме сбережения энергии будет в 4 раза медленнее! Кстати, именно такое замедление CPU является рекомендованным в Chrome.

Recalculate:  ~6 ms
Layout:       ~24 ms
Paint:        ~4 ms
Общее время:  ~56 ms

Добавим оптимизацию и посмотрим что изменится.

{
  'content-visibility': 'auto',
  'contain-intrinsic-size': `auto ${size}px`,
}

Recalculate:  ~2 ms
Layout:       ~12 ms
Paint:        ~2 ms
Общее время:  ~37 ms

Кстати, без свойства contain-intrinsic-size, которое “бронирует” место под содержимое групп, “магии” не получится.

По итогу, можно сказать что “двумя строчками CSS” мы сократили время отображения списка на ~34%. Да, можно сократить ещё, но об этом в другой раз.

П.С. Вычислять высоту через JS не обязательно, можно заранее посчитать и указать среднее значение в CSS. Однако в таком случае бегунок прокрутки может иногда прыгать.

#frontend #development #solidjs #css #performance

TypeScript обещает ускориться в 10 раз к 7 версии… Что тут ещё сказать, ждём! 😎

https://devblogs.microsoft.com/typescript/typescript-native-port/

Интересный момент при замере performance в Chrome

Обратил внимание на интересный момент во вкладке Performance, где при использовании кнопки “Record and reload” фаза Layout существенно медленнее чем при обычной записи. Скорее всего причина в “накладных расходах”, таких как замеры Largest Contentful Paint, Cumulative Layout Shift и т.п. При этом, в скорости выполнения JS разницы не заметил.

В продолжении темы оптимизации

В прошлом посте я рассказывал про оптимизацию средствами CSS, на примере конкретного свойства. Пришло время поговорить и про JS.

Возьмём всё тот же код с использованием SolidJS: https://github.com/SanichKotikov/solid-emoji-demo

Примечание: В этот раз все цифры будут указаны с учётом 4х кратного замедления, т.к. они ближе к цифрам в реальных условиях. Плюс, замеры производились на production сборке.

В качестве отправной точки возьмём код, в котором стили объявлены через свойство style из JS:

Script        ~54 ms
Recalculate:  ~7 ms
Layout:       ~19 ms
PrePaint:     ~2 ms
Paint:        ~7 ms

Выносим всю стилизацию, кроме contain-intrinsic-height, из JS в CSS файл, и сразу получаем следующий результат:

Script        ~24 ms
Recalculate:  ~3 ms
Layout:       ~19 ms
PrePaint:     ~1.3 ms
Paint:        ~6.3 ms

Выполнение JS кода, а также recalculate style, сократились примерно в двое. Кстати, если использовать emotion/css, то это практически ни как не повлияет на изначальные цифры. Делаем очевидный вывод — стилизация через JS (в рантайме) имеет свои накладные расходы.

Интересно, что если унести и contain-intrinsic-height в CSS, само собой с каким-то усреднённым значением, то это может замедлить Layout до ~24 ms.

Как ещё можно сократить время выполнения JS в таком, казалось бы, простом коде? Избавимся от “конструкций” библиотеки (в нашем случае SolidJS), там где это возможно.

Во-первых, избавимся от отдельного компонента EmojiButton, т.к. в нём нет ни какого практического смысла. Запомните, чем больше в проекте компонентов, тем он медленнее, в том числе и на этапе сборки.

Во-вторых, заменим For на обычный .map, т.к. список emoji статический, и в этом компоненте тут нет какого-то особого смысла. Попутно можно удалить и createMemo, по той же причине. Кстати, компонент Index медленнее чем For.

В итоге, получаем ещё немного прироста в выполнении JS:

Script        ~19 ms

П.С. Изменения можно посмотреть в том же репозитории, ветки css и js.

#development #performance #solidjs #javascript

Data Flow и модификация данных

Data Flow (поток данных) — концепция, описывающая движение данных между различными компонентами системы.

Желательно избегать модификации данных на всём пути этого потока, однако бывают различные ситуации, в том числе и бизнес требования, когда модифицировать данные всё же приходится. Самый простой пример — сортировка. И вот тут возникает главный вопрос — а где именно эти данные модифицировать? Универсальный (простой) ответ — максимально близко к тому месту, где это требуется.

Например, если речь идёт о какой-то локальной сортировке в одном или нескольких UI компонентах, тогда желательно это делать именно там. Грубой ошибкой, в данном случае, будет сортировка в модуле API.

И наоборот, если модификация продиктована разницей именования полей между фронтом и беком, идеальным местом будет модуль API.

Внутренние отступы кнопок в мобильном Safari

Столкнулся с занятной особенностью мобильного Safari. Если явно не указать внутренние боковые отступы (paddings) у элемента button, браузер проставит их автоматически отталкиваясь от размера шрифта.

Кстати, если вы хотите полностью сбросить стили кнопок по умолчанию:

button {
  padding: 0;
  margin: 0;
  font-size: inherit;
  border: none;
  background: none;
  appearance: none;
}

#development #css #safari