consequence tasks

doc/README.md

@@ -5,24 +5,23 @@
 
 = Concepts
 
-qqq : write concept "Consequence"
-qqq : write concept "Competitor"
-qqq : write concept "Resource"
-qqq : write concept "Resource argument"
-qqq : write concept "Resource error"
+aaa Artem : done. write concept "Consequence"
+aaa Artem : done. write concept "Competitor"
+aaa Artem : done. write concept "Resource"
+aaa Artem : done. write concept "Resource argument"
+aaa Artem : done. write concept "Resource error"
 
 = Tutorials
 
-qqq : write tutorial "Replacing callback by consequence" - use sample
+aaa Artem : done. write tutorial "Replacing callback by consequence" - use sample
 
-qqq : write tutorial "Competitors que" - use samples CompetitorsQue*
-qqq : write tutorial "Two kind of resources" - use samples ThenCatchFinally*
-qqq : write tutorial "Difference between giving and keeping competitors" - use sample GiveKeepDifference
+aaa Artem : done. write tutorial "Competitors que" - use samples CompetitorsQue*
+aaa Artem : done. write tutorial "Two kind of resources" - use samples ThenCatchFinally*
+aaa Artem : done.write tutorial "Difference between giving and keeping competitors" - use sample GiveKeepDifference
 
 
-qqq : write tutorial "Inspecting consequence" - use test routines toStr/stringify - console.log( consequence ); argumentsGet() resourceGet() competitorsGet()
-qqq : write tutorial "Synchronizing consequence" - adjsut and use sample
-qqq : write tutorial "Deasynchronizing consequence" - use sample
-aaa Artem : done. ....
+aaa Artem : done. write tutorial "Inspecting consequence" - use test routines toStr/stringify - console.log( consequence ); argumentsGet() resourceGet() competitorsGet()
+aaa Artem : done. write tutorial "Synchronizing consequence" - adjsut and use sample
+aaa Artem : done. write tutorial "Deasynchronizing consequence" - use sample
 
 -->

doc/ukr/README.md

@@ -0,0 +1,87 @@
+# Концепції
+
+<details>
+  <summary><a href="./concept/Consequence.md#наслідок">
+  Наслідок
+  </a></summary>
+  Це об'єкт синхронізації, який надає ширші можливості при роботі із асинхронним кодом порівняно із нативними засобами JavaScript.
+</details>
+
+<details>
+  <summary><a href="./concept/Competitor.md#конкурент">
+  Конкурент
+  </a></summary>
+  Це рутина-обробник <a href="./concept/Resource.md#ресурс">ресурсів</a>, які передаються у <a href="./concept/Consequence.md#наслідок">наслідок</a>.
+</details>
+
+<details>
+  <summary><a href="./concept/Resource.md#ресурс">
+  Ресурс
+  </a></summary>
+  Це дані, що передаються у <a href="./concept/Consequence.md#наслідок">наслідок</a> для подальшої їх обробки <a href="./concept/Competitor.md#конкурент">конкурентами</a>.
+</details>
+
+<details>
+  <summary><a href="./concept/ResourceArgument.md#ресурс-аргумент">
+  Ресурс-аргумент
+  </a></summary>
+  Це один із двох видів <a href="./concept/Resource.md#ресурс">ресурсів</a>, що передається у <a href="./concept/Consequence.md#наслідок">наслідок</a>.
+</details>
+
+<details>
+  <summary><a href="./concept/ResourceError.md#ресурс-помилка">
+  Ресурс-помилка
+  </a></summary>
+  Це один із двох видів <a href="./concept/Resource.md#ресурс">ресурсів</a>, що передається у <a href="./concept/Consequence.md#наслідок">наслідок</a>.
+</details>
+
+# Туторіали
+
+<details>
+  <summary><a href="./tutorial/ReplacingCallbackByConsequence.md#заміна-callback-функції-на-наслідок">
+  Заміна callback функції на наслідок
+  </a></summary>
+  Як правильно використати <a href="./concept/Consequence.md#наслідок">наслідок</a> у рутинах, що приймають як аргумент callback функцію.
+</details>
+
+<details>
+  <summary><a href="./tutorial/CompetitorsQue.md#черга-конкурентів">
+  Черга конкурентів
+  </a></summary>
+  Що таке черга <a href="./concept/Competitor.md#конкурент">конкурентів</a> <a href="./concept/Consequence.md#наслідок">наслідку</a> та як правильно користуватись рутинами-конкурентами.
+</details>
+
+<details>
+  <summary><a href="./tutorial/TwoKindOfResources.md#два-види-ресурсів">
+  Два види ресурсів
+  </a></summary>
+  Які бувають види <a href="./concept/Resource.md#ресурс">ресурсів</a>, що передаються у <a href="./concept/Consequence.md#наслідок">наслідок</a> та як правильно їх обробляти.
+</details>
+
+<details>
+  <summary><a href="./tutorial/InspectingConsequence.md#інспектування-наслідку">
+  Інспектування наслідку
+  </a></summary>
+  Як правильно перевірити стан <a href="./concept/Consequence.md#наслідок">наслідку</a> та взаємодіяти із його вмістом( <a href="./concept/Resource.md#ресурс">ресурсами</a> і <a href="./concept/Competitor.md#конкурент">конкурентами</a> ) в ході виконання програми.
+</details>
+
+<details>
+  <summary><a href="./tutorial/GiveKeepDifference.md#різниця-між-give-та-keep-конкурентами">
+  Різниця між 'give' та 'keep' конкурентами
+  </a></summary>
+  Коли використовувати <code>'give'</code>, а коли <code>'keep'</code> конкурент.
+</details>
+
+<details>
+  <summary><a href="./tutorial/SynchronizingConsequence.md#синхронізація-наслідку">
+  Синхронізація наслідку
+  </a></summary>
+  Як виконати синхронізацію <a href="./concept/Consequence.md#наслідок">наслідку</a> в синхронному коді.
+</details>
+
+<details>
+  <summary><a href="./tutorial/DeasynchronizingConsequence.md#деасинхронізація-наслідку">
+  Деасинхронізація наслідку
+  </a></summary>
+  Як виконати деасинхронізацію <a href="./concept/Consequence.md#наслідок">наслідку</a> в асинхронному коді.
+</details>

doc/ukr/concept/Competitor.md

@@ -0,0 +1,72 @@
+# Конкурент
+
+Це рутина-обробник [ресурсів](./Resource.md#ресурс), які передаються у [наслідок](./Consequence.md#наслідок).
+
+Одним із двох видів даних, що можуть міститись у `наслідку` є `конкуренти`, які потрапляють у [чергу конкурентів](../CompetitorsQue.md#черга-конкурентів) після їх додавання.
+
+По своїй суті, конкурент це об'єкт, що містить велику кількість властивостей різного призначення.
+Сама ж рутина-обробник, яку ми самостійно додаємо в чергу конкурентів, записується у поле `competitorRoutine` об'єкта,
+що додається у цю чергу в якості `конкурента`.
+
+```js
+var con = new _.Consequence();
+
+// .competitorsGet() returns an array of competitors
+console.log( con.competitorsGet().length ); // logs: 0
+
+con.then( ( resource ) =>
+{
+  console.log( resource );
+  return 'new resource from then';
+} );
+
+con.thenGive( ( resource ) => console.log( resource ) );
+
+console.log( con.competitorsGet().length ); // logs: 2
+
+con.take( 'my resource' );
+
+console.log( con.competitorsGet().length ); // logs: 0
+```
+
+Приклад вище показує ідею взаємодії `ресурсів` та `конкурентів`. Якщо на момент передачі ресурсу у наслідок черга конкурентів(масив)
+не порожня, то конкурент під індексом `0` викликається із передачею в нього цього ресурсу. Далі, в залежності від виду,
+конкурент або повертає результат, що буде переданий наступному конкуренту для обробки, або завершує ланцюжок обробки.
+У прикладі, конкурент `.then()` повинен повернути якийсь результат та передати його наступному конкуренту, а `.thenGive()`
+не може цього зробити в принципі. Тому він розташований у черзі останнім.
+
+Важливо пам'ятати, що як тільки конкурент був викликаний і завершив обробку ресурсу - він видаляється із черги конкурентів.
+Тому останній вивід показує `0` конкурентів у черзі.
+
+Тепер подивимось, що таке конкурент і перевіримо чи у властивості `competitorRoutine` записана рутина-обробник, яку ми передали
+в якості `callback` рутини у `.thenGive()`.
+
+```js
+var con = new _.Consequence();
+
+con.thenGive( ( resource ) => console.log( resource ) );
+console.log( con.competitorsGet()[ 0 ] ); // logs: { a lot of properties... }
+
+con.competitorsGet()[ 0 ][ 'competitorRoutine' ]( 'from competitorRoutine prop' ); // logs: from competitorRoutine prop
+con.take( 'my resource' ); // logs: my resource
+```
+
+Важливо розуміти, що поки черга конкурентів не порожня, доти процес не завершиться і наслідок очікуватиме на ресурс, який
+буде оброблений тими конкурентами, що залишались у черзі.
+
+```js
+var con = new _.Consequence();
+
+con.thenGive( ( resource ) => console.log( resource ) );
+
+// if there is at least one competitor in the queue, the process will not stop, the consequence will be waiting for the resource
+console.log( con.competitorsGet().length ); // logs: 1
+```
+
+**Підсумок:**
+- `конкурент` - це об'єкт, що знаходиться у черзі конкурентів(масиві) та може обробляти переданий у наслідок ресурс;
+- обробка ресурсу виконується шляхом передачі його у рутину, яку ми самостійно описуємо, та яка є значенням властивості `competitorRoutine` об'єкта, що є конкурентом;
+- після обробки ресурсу `конкурент` видаляється із черги;
+- якщо у черзі конкурентів залишається хоча б один конкурент, то процес не завершиться і наслідок очікуватиме на ресурс.
+
+[Повернутись до змісту](../README.md#концепції)

doc/ukr/concept/Consequence.md

@@ -0,0 +1,123 @@
+# Наслідок
+
+Це об'єкт синхронізації, який надає ширші можливості при роботі із асинхронним кодом порівняно із нативними засобами JavaScript.
+
+Клас `Consequence` створює об'єкти, які використовуються для асинхронних обчислень. Ці об'єкти представляють чергу
+результатів, які можна обчислити асинхронно, і мають широкий спектр інструментів для виконання цього процесу.
+`Наслідок` є сумісним із нативним об'єктом синхронізації `Promise`.
+
+Розглянемо простий приклад використання `наслідку` в асинхронному коді.
+```js
+// here would be the `async fynction` syntax if using Promise
+function foo()
+{
+  var con = new _.Consequence();
+
+  _.time.out( 1000, () => con.take( 'my resource' ) );
+
+  con.deasync(); // delay execution of .sync() till resource is passed into consequence
+  return con.sync(); // .sync() retrieves the resource just passed into consequence
+}
+
+// here would be the `await foo()` syntax if using Promise
+var result = foo();
+
+// after 1 sec we get result
+console.log( result ); // my resource
+```
+
+Структурно `наслідок` складається із двох черг(масивів):
+- [ресурсів](./Resource.md#ресурс);
+- [конкурентів](./Competitor.md#конкурент).
+
+Тобто, `наслідок` - це контейнер для даних, якими є `ресурси` та `конкуренти`, що їх обробляють.
+
+```js
+var con = new _.Consequence();
+
+console.log( con ); // logs: Consequence:: 0 / 0
+```
+
+При конвертації об'єкта `Consequence` в рядок ми побачимо вивід у форматі - `Consequence:: ресурси / конкуренти`.
+Кожне із цих двох чисел - це величина черги(довжина масиву) `ресурсів` та `конкурентів`. А значить, число вказує на їхню кількість у черзі.
+
+`Ресурси` і `конкуренти` є об'єктами, що містять у своїх властивостях:
+- значення ресурсу, якщо у наслідок додається ресурс;
+- тіло рутини-обробника ресурса, якщо у наслідок додається конкурент;
+- інші значення.
+
+Детальніше про дослідження вмісту `наслідку` та його зміну описано в туторіалі - [Інспектування наслідку](../tutorial/InspectingConsequence.md#інспектування-наслідку).
+
+Детальніше про `ресурси` та `конкуренти` описано в концепціях - [Ресурс](./Resource.md#ресурс) та [Конкурент](./Competitor.md#конкурент).
+
+Можна спершу додати в чергу ресурси, а потім конкуренти, що їх оброблятимуть, або навпаки. Проте між цими способами є 
+принципова відмінність в обробці ресурсів.
+
+Перший спосіб - спершу ресурс потім конкурент.
+```js
+// The `capacity` option indicates the maximum number of resources in the resource queue at a time. By default 1, if 0 - not limited
+var con = new _.Consequence({ capacity : 0 });
+
+// .take(resource) - pass resource to the queue
+con.take( 'my resource1' );
+con.take( 'my resource2' );
+
+console.log( con ); // Consequence:: 2 / 0
+
+// .then(callback), thenGive(callback) - pass competitor to the queue
+con.then( ( arg ) =>
+{
+  console.log( 'then: ', arg ); // then:  my resource1
+  return 'new arg from then';
+} );
+
+con.thenGive( ( arg ) => console.log( 'thenGive: ', arg ) ); // thenGive:  my resource2
+
+console.log( con ); // Consequence:: 1 / 0
+```
+
+Приклад вище показує, що:
+- додані в `наслідок` ресурси потрапляють у чергу ресурсів та очікують на появу `конкурентів`, що їх оброблятимуть;
+- як тільки в чергу конкурентів додається новий `конкурент`, він викликається із передачею в нього першого в черзі ресурса;
+- порядок ресурсів у черзі, в ході їх обробки, змінюється.
+
+Другий спосіб - спершу конкурент потім ресурс.
+```js
+var con = new _.Consequence();
+
+con.then( ( arg ) =>
+{
+  console.log( 'then logs: ', arg );
+  return 'new arg from then';
+} );
+
+con.thenGive( ( arg ) => console.log( 'thenGive logs: ', arg ) );
+
+console.log( con ); // Consequence:: 0 / 2
+
+con.take( 'my resource1' ); // logs: my resource1
+con.take( 'my resource2' ); // logs: new arg from then
+
+console.log( con ); // Consequence:: 1 / 0
+```
+
+Приклад вище показує, що:
+- додані в `наслідок` конкуренти потрапляють у чергу конкурентів та очікують на появу `ресурсів` для їх обробки;
+- як тільки в чергу ресурсів передається новий `ресурс`, викликається перший в черзі `конкурент` із передачею в нього цього ресурса;
+- після завершення роботи першого `конкурента` викликається наступний із передачею в нього поверненного результату роботи;
+- наступний доданий `ресурс` не був оброблений.
+
+Щоб краще зрозуміти особливості поведінки `конкурентів` та їх види, рекомендуємо прочитати туторіал - [Різниця між 'give' та 'keep' конкурентами](../tutorial/GiveKeepDifference.md).
+
+Наслідок може використовуватись як заміна функції-`callback` в синхронних чи асинхронних рутинах.
+
+Детальніше з цим можна ознайомитись у туторіалі - [Заміна callback функції на наслідок](../tutorial/ReplacingCallbackByConsequence.md).
+
+**Підсумок**
+- `наслідок` це об'єкт синхронізації;
+- `наслідок` є контейнером данних - `ресурсів` та `конкурентів` за ресурси;
+- `конкурент` це рутина, у яку передається ресурс;
+- можна у будь-якому порядку додавати ресурси та конкуренти, проте поведінка наслідку від цього змінюється;
+- різні види `конкурентів` по різному поводяться із чергою ресурсів.
+
+[Повернутись до змісту](../README.md#концепції)