patron-oop 1.45.0 → 1.46.0

package/docs/pages/source/source-race.html

@@ -0,0 +1,171 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Класс SourceRace</h1>
+
+<a
+  href="https://github.com/kosukhin/patron/blob/main/src/Guest/SourceRace.ts"
+  target="_blank"
+  class="inline-flex gap-1 items-center bg-gray-100 border-0 py-1 px-3 focus:outline-none hover:bg-gray-200 rounded text-base mt-4 md:mt-0 mb-4"
+>
+  <img
+    src="./assets/img/github_16.jpg"
+    width="16"
+    height="16"
+  />
+  SourceRace на GitHub
+</a>
+
+<p class="text-gray-600 text-lg mb-4">
+  Это
+  <link-dynamic href="/terminology/the-source">источник данных</link-dynamic>
+  предназначенный для получения данных только от первого ответившего источника.
+</p>
+
+<p class="text-gray-600 text-lg mb-4">
+  Это поведение может быть очень полезным, чтобы избавиться от условий в
+  приложении. Благодаря классу SourceRace каждый источник данных может сам
+  решить должен ли он вообще отдавать какую-либо информацию или можно
+  промолчать.
+</p>
+
+<p class="text-gray-600 text-lg mb-4">
+  Для примера сделаем программу, которая будет умножать на 2 четные числа и на 3
+  нечетные
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Пример 1.</p>
+<pre class="mb-4"><code class="language-js">import {
+  SourceMap,
+  SourceRace,
+  Source,
+  SourceWithPool,
+  give,
+  value,
+  GuestCast,
+  Private,
+} from "patron-oop";
+
+const isEven = (v) => v % 2 === 0;
+const isOdd = (v) => v % 2 !== 0;
+
+const nTimesSource = (condition, n, baseSource) => (guest) => {
+  value(
+    baseSource,
+    new GuestCast(guest, (value) => {
+      if (condition(value)) {
+        give(value * n, guest);
+      }
+    })
+  );
+};
+
+const source = new SourceWithPool([1, 2, 3, 4, 5]);
+const guestMapped = new SourceMap(
+  source,
+  new Private(
+    (itemSource) =>
+      new SourceRace([
+        nTimesSource(isEven, 2, itemSource),
+        nTimesSource(isOdd, 3, itemSource),
+      ])
+  )
+);
+
+guestMapped.value((v) => {
+  document.querySelector(".guest-result").textContent = v.join();
+});
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 1.</p>
+<div class="example mb-4">
+  <span class="guest-result">Результат = 0</span>
+</div>
+<script type="module">
+  import {
+    SourceMap,
+    SourceRace,
+    Source,
+    SourceWithPool,
+    give,
+    value,
+    GuestCast,
+    Private,
+  } from "patron-oop";
+
+  const isEven = (v) => v % 2 === 0;
+  const isOdd = (v) => v % 2 !== 0;
+
+  const nTimesSource = (condition, n, baseSource) => (guest) => {
+    value(
+      baseSource,
+      new GuestCast(guest, (value) => {
+        if (condition(value)) {
+          give(value * n, guest);
+        }
+      })
+    );
+  };
+
+  const source = new SourceWithPool([1, 2, 3, 4, 5]);
+  const guestMapped = new SourceMap(
+    source,
+    new Private(
+      (itemSource) =>
+        new SourceRace([
+          nTimesSource(isEven, 2, itemSource),
+          nTimesSource(isOdd, 3, itemSource),
+        ])
+    )
+  );
+
+  guestMapped.value((v) => {
+    document.querySelector(".guest-result").textContent = v.join();
+  });
+</script>
+
+<p class="text-gray-600 text-lg mb-4">
+  В программе использованы классы и функции:
+</p>
+
+<ul>
+  <li>
+    <link-dynamic href="/terminology/the-source">SourceMap</link-dynamic>
+    - для применения источника на каждый элемент внутри итерируемого источника
+  </li>
+  <li>
+    <link-dynamic href="/terminology/the-source">SourceRace</link-dynamic>
+    - для оборачивания набора источников, которым подходит значение на текущем
+    цикле итерации.
+  </li>
+  <li>
+    <link-dynamic href="/terminology/the-source">Source</link-dynamic>
+    - для представления данных итерируемых
+  </li>
+  <li>
+    <link-dynamic href="/terminology/the-source">give</link-dynamic>
+    - для передачи данных источнику
+  </li>
+  <li>
+    <link-dynamic href="/terminology/the-source">value</link-dynamic>
+    - для получения данных от источника
+  </li>
+  <li>
+    <link-dynamic href="/terminology/the-source">GuestCast</link-dynamic>
+    - для наследования представления гостя, возможно данные нужны патрону
+  </li>
+  <li>
+    <link-dynamic href="/terminology/the-source">Private</link-dynamic>
+    - для объявления новой композиции
+  </li>
+</ul>
+
+<p>&nbsp;</p>
+<p class="text-gray-600 text-lg mb-4">
+  Можно сказать, что код примера слишком сложный для такой простой задачи. Да
+  это правда, но пример показывает, что можно построить код таким образом, чтобы
+  классы или функции сами в зависимости от значения решали должны ли они
+  выполнять свою работу или нет
+</p>
+
+<p class="text-gray-600 text-lg mb-4">
+  Эта возможность - принимать решение давать свой ответ или нет внутри объектов
+  - может быть очень ценной для инкапсуляции логики и переиспользования
+</p>

package/docs/pages/source/source-sequence.html

@@ -0,0 +1,160 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">
+  Класс SourceSequence
+</h1>
+
+<a
+  href="https://github.com/kosukhin/patron/blob/main/src/Source/SourceSequence.ts"
+  target="_blank"
+  class="inline-flex gap-1 items-center bg-gray-100 border-0 py-1 px-3 focus:outline-none hover:bg-gray-200 rounded text-base mt-4 md:mt-0 mb-4"
+>
+  <img
+    src="./assets/img/github_16.jpg"
+    width="16"
+    height="16"
+  />
+  SourceSequence на GitHub
+</a>
+
+<p class="text-gray-600 text-lg mb-4">
+  Класс <b>SourceSequence</b> работает так же как и
+  <link-dynamic href="/source/source-map">SourceMap</link-dynamic>
+  , но перебирает источнники данных последовательно а не параллельно
+</p>
+
+<p class="text-gray-600 text-lg mb-4">
+  Такое поведение - последовательного перебора элементов может быть полезно либо
+  в случаях перебора синхронных данных, что позволяет экономить память не
+  оборачивая каждый источник данных в лишние объекты, либо в случаях когда по
+  бизнес логике нужно сделать последовательный перебор источников данных.
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Пример 1.</p>
+<pre class="mb-4"><code class="language-js">import {
+  Source,
+  Patron,
+  GuestCast,
+  SourceWithPool,
+  SourceSequence,
+  PrivateClass,
+  give,
+  isSource,
+} from "patron-oop";
+
+class X3 {
+  constructor(baseNumber) {
+    this.baseNumber = baseNumber;
+  }
+
+  value(guest) {
+    this.baseNumber.value(
+      new GuestCast(guest, (v) => {
+        give(v * 3, guest);
+      })
+    );
+    return this;
+  }
+}
+
+const tillResult = new SourceWithPool(9);
+const numSource = (num) =>
+  new Source((guest) =>
+    setTimeout(() => {
+      tillResult.value((theValue) => {
+        tillResult.give(theValue - 1);
+      });
+      give(num, guest);
+    }, 1000)
+  );
+
+const source = new SourceWithPool([
+  numSource(1),
+  numSource(2),
+  numSource(3),
+  numSource(4),
+  numSource(5),
+  numSource(6),
+  numSource(7),
+  numSource(8),
+  numSource(9),
+]);
+const sequence = new SourceSequence(source, new PrivateClass(X3));
+
+sequence.value((v) => {
+  document.querySelector(".guest-result").textContent = v.join();
+});
+tillResult.value(
+  new Patron((v) => {
+    document.querySelector(
+      ".guest-result"
+    ).textContent = `Результат через ${v} сек.`;
+  })
+);
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 1.</p>
+<div class="example mb-4">
+  <span class="guest-result">Result here</span>
+</div>
+
+<script type="module">
+  import {
+    Source,
+    Patron,
+    GuestCast,
+    SourceWithPool,
+    SourceSequence,
+    PrivateClass,
+    give,
+    isSource,
+  } from "patron-oop";
+
+  class X3 {
+    constructor(baseNumber) {
+      this.baseNumber = baseNumber;
+    }
+
+    value(guest) {
+      this.baseNumber.value(
+        new GuestCast(guest, (v) => {
+          give(v * 3, guest);
+        })
+      );
+      return this;
+    }
+  }
+
+  const tillResult = new SourceWithPool(9);
+  const numSource = (num) =>
+    new Source((guest) =>
+      setTimeout(() => {
+        tillResult.value((theValue) => {
+          tillResult.give(theValue - 1);
+        });
+        give(num, guest);
+      }, 1000)
+    );
+
+  const source = new SourceWithPool([
+    numSource(1),
+    numSource(2),
+    numSource(3),
+    numSource(4),
+    numSource(5),
+    numSource(6),
+    numSource(7),
+    numSource(8),
+    numSource(9),
+  ]);
+  const sequence = new SourceSequence(source, new PrivateClass(X3));
+
+  sequence.value((v) => {
+    document.querySelector(".guest-result").textContent = v.join();
+  });
+  tillResult.value(
+    new Patron((v) => {
+      document.querySelector(
+        ".guest-result"
+      ).textContent = `Результат через ${v} сек.`;
+    })
+  );
+</script>

package/docs/pages/source/source-with-pool.html

@@ -0,0 +1,102 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Класс SourceWithPool</h1>
+
+<a
+  href="https://github.com/kosukhin/patron/blob/main/src/Source/SourceWithPool.ts"
+  target="_blank"
+  class="inline-flex gap-1 items-center bg-gray-100 border-0 py-1 px-3 focus:outline-none hover:bg-gray-200 rounded text-base mt-4 md:mt-0 mb-4"
+>
+  <img
+    src="./assets/img/github_16.jpg"
+    width="16"
+    height="16"
+  />
+  SourceWithPool на GitHub
+</a>
+
+<p class="text-gray-600 text-lg mb-4">
+  Предназначен для представления данных в виде&nbsp;<span
+    class="dynamic-navigation"
+  >
+    <a
+      class="inline-block whitespace-nowrap rounded-[0.27rem] bg-primary-100 px-[0.65em] pb-[0.25em] pt-[0.35em] text-center align-baseline text-[0.75em] font-bold leading-none text-white bg-slate-900"
+      href="/terminology/the-source"
+    >
+      источника
+    </a> </span
+  >, который умеет оповещать своих
+  <span class="dynamic-navigation">
+    <a
+      class="inline-block whitespace-nowrap rounded-[0.27rem] bg-primary-100 px-[0.65em] pb-[0.25em] pt-[0.35em] text-center align-baseline text-[0.75em] font-bold leading-none text-white bg-slate-900"
+      href="/terminology/the-patron"
+    >
+      патронов
+    </a>
+  </span>
+  об изменении данных
+</p>
+
+<p class="text-gray-600 text-lg mb-4">
+  Полезно в случаях, когда есть какие-то данные, которые могут изменяться со
+  временем. В этом случае данные полезно обернуть в SourceWithPool, чтобы посетители
+  данных могли сами решить нужно их уведомлять или не нужно и они сами себя
+  удалят из PatronPool внутри SourceWithPool
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Пример 1.</p>
+<pre class="mb-4"><code class="language-js">import { SourceWithPool, Patron } from "patron-oop";
+
+const source = new SourceWithPool("один");
+source.value((value) => {
+  document.querySelector(
+    ".source-result-1"
+  ).textContent = `Результат гостя = ${value}`;
+});
+source.value(
+  new Patron((value) => {
+    document.querySelector(
+      ".source-result-2"
+    ).textContent = `Результат патрона = ${value}`;
+  })
+);
+
+setTimeout(() => {
+  source.give("два");
+});
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 1.</p>
+<div class="example mb-4">
+  <div class="source-result-1">Нет результата!</div>
+  <div class="source-result-2">Нет результата!</div>
+</div>
+<script type="module">
+  import { SourceWithPool, Patron } from "patron-oop";
+
+  const source = new SourceWithPool("один");
+  source.value((value) => {
+    document.querySelector(
+      ".source-result-1"
+    ).textContent = `Результат гостя = ${value}`;
+  });
+  source.value(
+    new Patron((value) => {
+      document.querySelector(
+        ".source-result-2"
+      ).textContent = `Результат патрона = ${value}`;
+    })
+  );
+
+  setTimeout(() => {
+    source.give("два");
+  });
+</script>
+
+<div class="font-bold mt-8">Смотрите также</div>
+
+<p class="text-gray-600 text-lg mb-4 dynamic-navigation">
+  <a
+    class="inline-block whitespace-nowrap rounded-[0.27rem] bg-primary-100 px-[0.65em] pb-[0.25em] pt-[0.35em] text-center align-baseline text-[0.75em] font-bold leading-none text-white bg-slate-900"
+    href="/patron"
+    >Patron</a
+  >
+</p>

package/docs/pages/source/source.html

@@ -0,0 +1,167 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Класс Source</h1>
+
+<a
+  href="https://github.com/kosukhin/patron/blob/main/src/Source/Source.ts"
+  target="_blank"
+  class="inline-flex gap-1 items-center bg-gray-100 border-0 py-1 px-3 focus:outline-none hover:bg-gray-200 rounded text-base mt-4 md:mt-0 mb-4"
+>
+  <img
+    src="./assets/img/github_16.jpg"
+    width="16"
+    height="16"
+  />
+  Source на GitHub
+</a>
+
+<p class="text-gray-600 text-lg mb-4">
+  Предназначен для создания объектов, которые будут
+  <span class="dynamic-navigation">
+    <a
+      class="inline-block whitespace-nowrap rounded-[0.27rem] bg-primary-100 px-[0.65em] pb-[0.25em] pt-[0.35em] text-center align-baseline text-[0.75em] font-bold leading-none text-white bg-slate-900"
+      href="/terminology/the-source"
+    >
+      источниками данных
+    </a>
+  </span>
+  , логика этих объектов основана на переданной функции-колбэке
+</p>
+
+<p class="text-gray-600 text-lg mb-4">
+  Полезно в случаях, когда нужно создать новый объект с уникальным поведением по
+  генерации данных без создания для этого отдельного класса
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Пример 1.</p>
+<pre class="mb-4"><code class="language-js">import {
+    Source,
+    give
+} from 'patron-oop';
+
+const timestamp = new Source((guest) => {
+    give(Date.now(), guest);
+});
+timestamp.value((timestamp) => {
+    console.log('timestamp is', timestamp);
+});
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 1.</p>
+<div class="example mb-4">
+  <span class="guest-result">Result here</span>
+</div>
+<script type="module">
+  import { Source, give } from "patron-oop";
+
+  const timestamp = new Source((guest) => {
+    give(Date.now(), guest);
+  });
+  timestamp.value((timestamp) => {
+    document.querySelector(
+      ".guest-result"
+    ).textContent = `timestamp is ${timestamp}`;
+  });
+</script>
+
+<p class="text-gray-600 text-lg mb-4">
+  Источником данных может быть не только объект, но и функция вида
+  <em>(guest) => guest('value')</em>. Напрямую можно обратиться к такому
+  источнику через функцию
+  <link-reloadable
+    target-blank
+    href="https://github.com/kosukhin/patron/blob/main/src/Source/Source.ts#L11"
+  >
+    value
+  </link-reloadable>
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Пример 2.</p>
+<pre class="mb-4"><code class="language-js">import {
+  give,
+  value
+} from "patron-oop";
+
+const helloSource = (guest) => {
+  setTimeout(() => {
+    give("Hello world", guest);
+  }, 1000);
+};
+
+value(helloSource, (greeting) => {
+  document.querySelector(
+    ".guest-result-2"
+  ).textContent = `greeting is "${greeting}"`;
+});
+</code></pre>
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 2.</p>
+<div class="example mb-4">
+  <span class="guest-result-2">Result here</span>
+</div>
+<script type="module">
+  import { give, value } from "patron-oop";
+
+  const helloSource = (guest) => {
+    setTimeout(() => {
+      give("Hello world", guest);
+    }, 1000);
+  };
+
+  value(helloSource, (greeting) => {
+    document.querySelector(
+      ".guest-result-2"
+    ).textContent = `greeting is "${greeting}"`;
+  });
+</script>
+
+<p class="text-gray-600 text-lg mb-4">
+  Или можно передать источник-функцию в виде зависимости объектам, которые
+  ожидают интерфейс SourceType, в примере ниже используется комбинация
+  <link-dynamic href="/guest/source-all">SourceAll</link-dynamic>
+  и источников-фукнций
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Пример 3.</p>
+<pre class="mb-4"><code class="language-js">import {
+  SourceAll,
+  give,
+  value
+} from "patron-oop";
+
+const all = new SourceAll();
+value(give.bind(null, 1), all.guestKey("one"));
+value(give.bind(null, 2), all.guestKey("two"));
+
+all.value(({ one, two }) => {
+  document.querySelector(".guest-result-3").textContent = `one + two = "${
+    one + two
+  }"`;
+});
+</code></pre>
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 3.</p>
+<div class="example mb-4">
+  <span class="guest-result-3">Result here</span>
+</div>
+<script type="module">
+  import { SourceAll, give, value } from "patron-oop";
+
+  const all = new SourceAll();
+  value(give.bind(null, 1), all.guestKey("one"));
+  value(give.bind(null, 2), all.guestKey("two"));
+
+  all.value(({ one, two }) => {
+    document.querySelector(".guest-result-3").textContent = `one + two = "${
+      one + two
+    }"`;
+  });
+</script>
+
+<p class="text-gray-600 text-lg mb-4">
+  Интересный факт, что с помощью частичного применения(bind) можно превратить
+  функцию <b>give</b> в <b>источник данных</b>, передав только первый аргумент
+</p>
+
+<div class="font-bold mt-8">Смотрите также</div>
+
+<p class="text-gray-600 text-lg mb-4 dynamic-navigation">
+  <link-dynamic href="/utils/give">give</link-dynamic>
+  <link-dynamic href="/utils/value">value</link-dynamic>
+</p>

package/docs/pages/source.html

@@ -0,0 +1,68 @@
+<section class="text-gray-600 body-font">
+  <div class="py-1 mx-auto flex flex-col">
+    <div class="lg:w-4/6 mx-auto w-full">
+      <div class="flex flex-col sm:flex-row w-full">
+        <div class="sm:w-1/3 text-center w-full">
+          <div
+            class="flex flex-col items-center text-center justify-center source-menu"
+          >
+            <h2 class="font-medium title-font text-gray-900 text-lg">
+              <a href="/source"> Source </a>
+            </h2>
+            <div class="w-12 h-1 bg-indigo-500 rounded mt-2 mb-4"></div>
+            <ul class="text-gray-900">
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-active"> SourceActive </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-all"> SourceAll </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-applied"> SourceApplied </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-dynamic"> SourceDynamic </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-executor-applied"> SourceExecutorApplied </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-map"> SourceMap </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-once"> SourceOnce </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-race"> SourceRace </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-sequence"> SourceSequence </a>
+              </li>
+              <li class="w-full border-b-2 border-neutral-100 py-4">
+                <a href="/source/source-with-pool"> SourceWithPool </a>
+              </li>
+            </ul>
+          </div>
+        </div>
+        <div
+          class="sm:w-2/3 sm:pl-8 sm:border-l border-gray-200 sm:border-t-0 border-t mt-4 sm:mt-0"
+        >
+          <div class="source-loader">
+            <div class="w-full flex justify-center">
+              <div
+                class="inline-block h-8 w-8 animate-spin rounded-full border-4 border-solid border-current border-e-transparent align-[-0.125em] text-indigo-500 motion-reduce:animate-[spin_1.5s_linear_infinite]"
+                role="status"
+              >
+                <span
+                  class="!absolute !-m-px !h-px !w-px !overflow-hidden !whitespace-nowrap !border-0 !p-0 ![clip:rect(0,0,0,0)]"
+                  >Loading...</span
+                >
+              </div>
+            </div>
+          </div>
+          <div class="source-page-area"></div>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>

package/docs/pages/terminology/guest.html

@@ -0,0 +1,14 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Гость</h1>
+
+<p class="text-gray-600 text-lg mb-4">
+  Гость - это посетитель, который является функцией или объектом без
+  introduction или объектом с методом introduction, который возвращает значение
+  'guest'
+</p>
+
+<p class="text-gray-600 text-lg mb-4">
+  Гость получает значение от источника данных один раз. Но библиотека имеет
+  механики на случай если у источника данных нет данных на текущий момент, то
+  можно задать гостю значение при первом появлении данных. Для этих механик
+  смотрите: GuestPool, PatronOnce, SourceEmpty
+</p>

package/docs/pages/terminology/index.html

@@ -0,0 +1,6 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Терминология</h1>
+
+<p class="text-gray-600 text-lg mb-4">
+  Раздел посвящен терминам, которые требуют раскрытия и не могут(или не должны)
+  быть раскрыты в описаниях классов и функций библиотеки
+</p>