👾 smth

6-data-storage/03-indexeddb/article.md

@@ -7,7 +7,7 @@ libs:
 
 IndexedDB - это встроенная база данных, более мощная, чем `localStorage`.
 
-- Хранилище ключей/значений: доступны несколько типов ключей, а значения могут быть (почти) любыми.
+- Хранит практически любые значения по ключам, несколько типов ключей
 - Поддерживает транзакции для надёжности.
 - Поддерживает запросы в диапазоне ключей и индексы.
 - Позволяет хранить больше данных, чем `localStorage`.
@@ -18,6 +18,12 @@ IndexedDB - это встроенная база данных, более мощ
 
 Мы также можем использовать `async/await` с помощью обёртки, которая основана на промисах, например <https://github.com/jakearchibald/idb>. Это очень удобно, но обёртка не идеальна, она не может полностью заменить события. Поэтому мы начнём с событий, а затем, когда разберёмся в IndexedDB, рассмотрим и обёртку.
 
+```smart header="Где хранятся данные?"
+Технически данные обычно хранятся в домашнем каталоге посетителя вместе с настройками браузера, расширениями и т.д.
+
+У разных браузеров и пользователей на уровне ОС есть свое собственное независимое хранилище.
+```
+
 ## Открыть базу данных
 
 Для начала работы с IndexedDB нужно открыть базу данных.
@@ -46,7 +52,9 @@ let openRequest = indexedDB.open(name, version);
 
 Это событие также сработает, если базы данных ещё не существует, так что в этом обработчике мы можем выполнить инициализацию.
 
-Например, когда мы впервые публикуем наше приложение, мы открываем базу данных с версией `1` и выполняем инициализацию в обработчике `upgradeneeded`:
+Допустим, мы опубликовали первую версию нашего приложения.
+
+Затем мы можем открыть базу данных с версией `1` и выполнить инициализацию в обработчике `upgradeneeded` вот так:
 
 ```js
 let openRequest = indexedDB.open("store", *!*1*/!*);
@@ -66,12 +74,13 @@ openRequest.onsuccess = function() {
 };
 ```
 
-Когда мы публикуем вторую версию:
+Затем, позже, мы публикуем 2-ю версию.
+
+Мы можем открыть его с версией `2` и выполнить обновление следующим образом:
 
 ```js
 let openRequest = indexedDB.open("store", *!*2*/!*);
 
-// проверить существование указанной версии базы данных, обновить по мере необходимости:
 openRequest.onupgradeneeded = function(event) {
  // версия существующей базы данных меньше 2 (или база данных не существует)
  let db = openRequest.result;
@@ -109,9 +118,12 @@ let deleteRequest = indexedDB.deleteDatabase(name)
 
 Раз уж мы говорим про версионирование, рассмотрим связанную с этим небольшую проблему.
 
-Допустим, посетитель открыл наш сайт во вкладке браузера, с базой версии 1.
+Допустим:
+1. Посетитель открыл наш сайт во вкладке браузера, с базой версии `1`.
+2. Затем мы выпустили обновление, так что наш код обновился.
+3. И затем тот же посетитель открыл наш сайт в другой вкладке.
 
-Затем мы выкатили обновление, и тот же посетитель открыл наш сайт в другой вкладке. Так что есть две вкладки, на которых открыт наш сайт, но в одной открыто соединение с базой версии 1, а другая пытается обновить версию базы в обработчике `upgradeneeded`.
+Так что есть две вкладки, на которых открыт наш сайт, но в одной открыто соединение с базой версии 1, а другая пытается обновить версию базы в обработчике `upgradeneeded`.
 
 Проблема заключается в том, что база данных всего одна на две вкладки, так как это один и тот же сайт, один источник. И она не может быть одновременно версии 1 и 2. Чтобы обновить на версию 2, все соединения к версии 1 должны быть закрыты.
 
@@ -133,27 +145,31 @@ openRequest.onsuccess = function() {
  *!*
  db.onversionchange = function() {
  db.close();
- alert("База данных устарела, пожалуста, перезагрузите страницу.")
+ alert("Database is outdated, please reload the page.")
  };
  */!*
 
- // ...база данных доступна как объект db...
+ // ...база данных готова, используйте ее...
 };
 
 *!*
 openRequest.onblocked = function() {
- // есть другое соединение к той же базе
- // и оно не было закрыто после срабатывания на нём db.onversionchange 
+ // это событие не должно срабатывать, если мы правильно обрабатываем onversionchange
+
+ // это означает, что есть еще одно открытое соединение с той же базой данных
+ // и он не был закрыт после того, как для него сработал db.onversionchange
 };
 */!*
 ```
 
-Здесь мы делаем две вещи:
+...Другими словами, здесь мы делаем две вещи:
 
-1. Добавляем обработчик `db.onversionchange` после успешного открытия базы, чтобы узнать о попытке параллельного обновления.
-2. Добавляем обработчик `openRequest.onblocked` для ситуаций, когда старое соединение не было закрыто. Такого не произойдёт, если мы закрываем его в `db.onversionchange`.
+1. Прослушиватель `db.onversionchange` сообщает нам о попытке параллельного обновления, если текущая версия базы данных устарела.
+2. Прослушиватель `OpenRequest.onblocked` сообщает нам об обратной ситуации: в другом месте есть соединение с устаревшей версией, и оно не закрывается, поэтому новое соединение установить невозможно.
 
-Есть и другие варианты. Например, мы можем более "мягко" закрыть соединение в `db.onversionchange`, предложить пользователю сохранить данные перед этим. Новое обновляющее соединение будет заблокировано сразу после того как обработчик `db.onversionchange` завершится, не закрыв соединение, и мы можем в новой вкладке попросить посетителя закрыть старые для обновления.
+Мы можем более изящно обращаться с вещами в `db.onversionchange`, например предлагать посетителю сохранить данные до закрытия соединения и так далее.
+
+Или альтернативным подходом было бы не закрывать базу данных в `db.onversionchange`, а вместо этого использовать обработчик `onblocked` (на новой вкладке), чтобы предупредить посетителя, что более новая версия не может быть загружена, пока они не закроют другие вкладки.
 
 Такой конфликт при обновлении происходит редко, но мы должны как-то его обрабатывать, хотя бы поставить обработчик `onblocked`, чтобы наш скрипт не "умирал" молча, удивляя посетителя.
 
@@ -182,6 +198,7 @@ IndexedDB использует [стандартный алгоритм сери
 Но для начала нужно создать хранилище.
 
 Синтаксис для создания хранилища объектов:
+
 ```js
 db.createObjectStore(name[, keyOptions]);
 ```
@@ -196,6 +213,7 @@ db.createObjectStore(name[, keyOptions]);
 Если при создании хранилища не указать `keyOptions`, то нам потребуется явно указать ключ позже, при сохранении объекта.
 
 Например, это хранилище объектов использует свойство `id` как ключ:
+
 ```js
 db.createObjectStore('books', {keyPath: 'id'});
 ```
@@ -205,6 +223,7 @@ db.createObjectStore('books', {keyPath: 'id'});
 Это техническое ограничение. Вне обработчика мы сможем добавлять/удалять/обновлять данные, но хранилища объектов могут быть созданы/удалены/изменены только во время обновления версии базы данных.
 
 Для обновления версии базы есть два основных подхода:
+
 1. Мы можем реализовать функции обновления по версиям: с 1 на 2, с 2 на 3 и т.д. Потом в `upgradeneeded` сравнить версии (например, была 2, сейчас 4) и запустить операции обновления для каждой промежуточной версии (2 на 3, затем 3 на 4).
 2. Или мы можем взять список существующих хранилищ объектов, используя `db.objectStoreNames`. Этот объект является [DOMStringList](https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#domstringlist), в нём есть метод `contains(name)`, используя который можно проверить существование хранилища. Посмотреть, какие хранилища есть и создать те, которых нет.
 
@@ -224,7 +243,6 @@ openRequest.onupgradeneeded = function() {
 };
 ```
 
-
 Чтобы удалить хранилище объектов:
 
 ```js
@@ -238,6 +256,7 @@ db.deleteObjectStore('books')
 Транзакция - это группа операций, которые должны быть или все выполнены, или все не выполнены (всё или ничего).
 
 Например, когда пользователь что-то покупает, нам нужно:
+
 1. Вычесть деньги с его счёта.
 2. Отправить ему покупку.
 
@@ -460,10 +479,13 @@ request.onerror = function(event) {
 ## Поиск по ключам
 
 Есть два основных вида поиска в хранилище объектов:
-1. По ключу или по диапазону ключей. То есть: по `book.id` в хранилище "books".
-2. По полям объекта, например, `book.price`.
 
-Сначала давайте разберёмся с ключами и диапазоном ключей `(1)`.
+1. По значению ключа или диапазону ключей. В нашем хранилище "books" это будет значение или диапазон значений `book.id `.
+2. С помощью другого поля объекта, например `book.price`. Для этого потребовалась дополнительная структура данных, получившая название "index".
+
+### По ключу
+
+Сначала давайте разберемся с первым типом поиска: по ключу.
 
 Методы поиска поддерживают либо точные ключи, либо так называемые "запросы с диапазоном" -- [IDBKeyRange](https://www.w3.org/TR/IndexedDB/#keyrange) объекты, которые задают "диапазон ключей".
 
@@ -474,7 +496,9 @@ request.onerror = function(event) {
 - `IDBKeyRange.bound(lower, upper, [lowerOpen], [upperOpen])` означает: между `lower` и `upper`, включительно, если соответствующий `open` равен `true`.
 - `IDBKeyRange.only(key)` -- диапазон, который состоит только из одного ключа `key`, редко используется.
 
-Все методы поиска принимают аргумент `query`, который может быть либо точным ключом, либо диапазоном ключей:
+Очень скоро мы увидим практические примеры их использования.
+
+Для выполнения фактического поиска существуют следующие методы. Они принимают аргумент `query`, который может быть либо точным ключом, либо диапазоном ключей:
 
 - `store.get(query)` -- поиск первого значения по ключу или по диапазону.
 - `store.getAll([query], [count])` -- поиск всех значений, можно ограничить, передав `count`.
@@ -509,7 +533,6 @@ books.getAllKeys(IDBKeyRange.lowerBound('js', true))
 Поэтому запросы, которые возвращают много значений, всегда возвращают их в порядке сортировки по ключу.
 ```
 
-
 ## Поиск по индексированному полю
 
 Для поиска по другим полям объекта нам нужно создать дополнительную структуру данных, называемую "индекс" (index).
@@ -592,6 +615,7 @@ let request = priceIndex.getAll(IDBKeyRange.upperBound(5));
 - **`delete(query)`** -- производит удаление соответствующих запросу значений.
 
 Например:
+
 ```js
 // удалить книгу с id='js'
 books.delete('js');
@@ -610,6 +634,7 @@ request.onsuccess = function() {
 ```
 
 Чтобы удалить всё:
+
 ```js
 books.clear(); // очищаем хранилище.
 ```
@@ -618,9 +643,7 @@ books.clear(); // очищаем хранилище.
 
 Такие методы как `getAll/getAllKeys` возвращают массив ключей/значений.
 
-Но хранилище объектов может быть огромным, больше, чем доступно памяти.
-
-Тогда метод `getAll` вернёт ошибку при попытке получить все записи в массиве.
+Но хранилище объектов может быть огромным, больше, чем доступно памяти. Тогда метод `getAll` вернёт ошибку при попытке получить все записи в массиве.
 
 Что делать?
 
@@ -631,6 +654,7 @@ books.clear(); // очищаем хранилище.
 Так как хранилище объектов внутренне отсортировано по ключу, курсор проходит по хранилищу в порядке хранения ключей (по возрастанию по умолчанию).
 
 Синтаксис:
+
 ```js
 // как getAll, но с использованием курсора:
 let request = store.openCursor([query], [direction]);
@@ -728,7 +752,6 @@ try {
 } catch(err) {
  console.log('ошибка', err.message);
 }
-
 ```
 
 Теперь у нас красивый "плоский асинхронный" код и, конечно, будет работать `try..catch`.
@@ -771,6 +794,7 @@ await inventory.add({ id: 'js', price: 10, created: new Date() }); // Ошибк
 Следующий `inventory.add` после `fetch` `(*)` не сработает, сгенерируется ошибка "inactive transaction", потому что транзакция уже завершена и закрыта к этому времени.
 
 Решение такое же, как при работе с обычным IndexedDB: либо создать новую транзакцию, либо разделить задачу на части.
+
 1. Подготовить данные и получить всё, что необходимо.
 2. Затем сохранить в базу данных.
 
@@ -803,8 +827,7 @@ IndexedDB можно рассматривать как "localStorage на сте
 
 1. Подключить обёртку над промисами, например [idb](https://github.com/jakearchibald/idb).
 2. Открыть базу данных: `idb.openDb(name, version, onupgradeneeded)`
- - Создание хранилищ объектов и индексов происходит в обработчике `onupgradeneeded`.
- - Обновление версии - либо сравнивая номера версий, либо можно проверить что существует, а что нет.
+ - Создайте хранилища объектов и индексы в обработчике `onupgradeneeded` или выполните обновление версии, если это необходимо
 3. Для запросов:
  - Создать транзакцию `db.transaction('books')` (можно указать readwrite, если надо).
  - Получить хранилище объектов `transaction.objectStore('books')`.