patron-oop 1.45.0 → 1.46.0

package/docs/pages/index.html

@@ -0,0 +1,72 @@
+<section class="text-gray-600 body-font">
+  <div
+    class="container mx-auto flex px-5 py-24 items-center justify-center flex-col"
+  >
+    <div class="text-center lg:w-2/3 w-full mb-10">
+      <h1
+        class="title-font sm:text-4xl text-3xl mb-4 font-medium text-gray-600"
+      >
+        Patron: responsibility, respect, result
+      </h1>
+      <p class="mb-8 leading-relaxed">
+        Библиотека предназначена для того, чтобы дать пользователю возможность
+        сконцентрироваться на разработке внутренней надёжной логики класса.
+        Классы, использующие библиотеку, становятся ответственными за те
+        результаты которые представляют и уважительно относятся к объектам с
+        которыми взаимодействуют
+      </p>
+    </div>
+    <div class="lg:w-2/3 w-full mb-14">
+      <h1
+        class="text-center title-font sm:text-4xl text-3xl mb-4 font-medium text-gray-600"
+      >
+        Patron - это протокол для общения между объектами
+      </h1>
+      <p class="mb-8 leading-relaxed">
+        В программе использующей Patron библиотеку есть объекты совместимые с
+        SourceType - это источники данных, такие объекты могу отдавать
+        данные. Есть объекты совместимые с GuestType - это потребители данных,
+        они могут принять данные
+      </p>
+      <div class="mb-4">
+        <h3 class="pb-3 text-xl font-semibold text-gray-600">
+          Сценарий 1. Диалог
+        </h3>
+        <p>
+          Объект А - источник данных, объект B - потребитель. Если объекту B
+          нужны какие-то данные, то B обращается к А через метод A.value
+          запрашивая данные. Когда А посчитает нужным, то А вернет B значение,
+          вызывая B.give
+        </p>
+      </div>
+      <div class="mb-4">
+        <h3 class="pb-3 text-xl font-semibold text-gray-600">
+          Сценарий 2. Расширение
+        </h3>
+        <p class="mb-2">
+          Объект А - источник данных запрашивающий случайное слово в интернете,
+          объект B - источник изменяющий в базовом источнике первым символ на
+          верхний регистр. Объект C - источник добавляющий в конец значения из
+          базового источника знак восклицания "!". Объект D - потребитель
+          результата, выводящий значение на экран
+        </p>
+        <p>
+          Получаем следующую композицию с = new C(new B(new A)), далее выражение
+          c.value(new D()) - Выводит результат на экран
+        </p>
+      </div>
+
+      <div class="mb-4">
+        <h3 class="pb-3 text-xl font-semibold text-gray-600">
+          Сценарий 3. Постоянный потребитель
+        </h3>
+        <p class="mb-2">
+          Объект А - источник данных, объект B - потребитель данных. Объект B
+          может представиться как 'patron', благодаря этому, объект А в случае,
+          если у него появится новое значение, будет знать что B нужно
+          оповестить о новом значении
+        </p>
+      </div>
+    </div>
+  </div>
+</section>

package/docs/pages/integrations/angular.html

@@ -0,0 +1,5 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Angular</h1>
+
+<p class="text-gray-600 text-lg mb-4">
+    Раздел в процессе наполнения.
+</p>

package/docs/pages/integrations/layout.html

@@ -0,0 +1,17 @@
+<div class="integrations-menu"></div>
+<div class="w-full sm:w-2/3 mt-4 sm:mt-0 mx-auto">
+  <div class="integrations-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="integrations-page-area"></div>
+</div>

package/docs/pages/integrations/react.html

@@ -0,0 +1,7 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">
+    React
+</h1>
+
+<p class="text-gray-600 text-lg mb-4">
+    Раздел в процессе наполнения.
+</p>

package/docs/pages/integrations/vue.html

@@ -0,0 +1,102 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Vue</h1>
+
+<p class="text-gray-600 text-lg mb-4">
+  Библиотека Patron интегрируется в Vue без каких-либо проблем. Например, чтобы
+  <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>
+  привязать к ref можно использовать такой класс (Листинг 1).
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Листинг 1.</p>
+<pre
+  class="mb-4"
+><code class="language-js">class VueRefPatron&lt;T&gt; implements GuestType&lt;T&gt; {
+    private readonly innerRef: Ref&lt;T | undefined&gt;;
+
+    public constructor(defaultValue: T | undefined = undefined) {
+        this.innerRef = ref(defaultValue);
+    }
+
+    public ref() {
+        return this.innerRef;
+    }
+
+    public give(value: T) {
+        this.innerRef.value = value;
+        return this;
+    }
+
+    public introduction() {
+        return &#39;patron&#39; as const;
+    }
+}
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-4">
+  Класс VueRefPatron можно использовать как посетителя для разных источников
+  данных, связывая таким образом источники данных с системой реактивности Vue.
+</p>
+
+<h3 class="pb-3 text-xl font-semibold text-gray-600">
+  Источники в шаблоне Vue
+</h3>
+
+<p class="text-gray-600 text-lg mb-4">
+  Также в шаблонах можно использовать заготовку из листинга 2, для того, чтобы
+  концентрироваться на разработке чистых компонентов, ожидающих простые данные,
+  вместо того, чтобы смешивать логику получения данных и логику компонентов.
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Листинг 2.</p>
+<pre class="mb-4"><code class="language-html">
+&lt;template&gt;
+  &lt;div&gt;
+    &lt;slot v-if=&quot;!data&quot; name=&quot;fallback&quot; /&gt;
+    &lt;slot v-else :data=&quot;data&quot; /&gt;
+  &lt;/div&gt;
+&lt;/template&gt;
+
+&lt;script lang=&quot;ts&quot;&gt;
+import { Source, Guest, Patron } from &#39;patron-oop&#39;;
+import { defineComponent, ref } from &#39;vue&#39;;
+import { PropType } from &#39;vue/types/v3-component-props&#39;;
+
+export default defineComponent({
+  name: &#39;Source&#39;,
+  emits: [&#39;input&#39;],
+  props: {
+    source: {
+      type: Object as PropType&lt;Source&lt;any&gt;&gt;,
+      required: true,
+    },
+  },
+  setup(props, { emit }) {
+    const data = ref(null);
+    props.source.value(
+      new Patron(
+        new Guest(value =&gt; {
+          data.value = value;
+          emit(&#39;input&#39;, value);
+        })
+      )
+    );
+    return {
+      data,
+    };
+  },
+});
+&lt;/script&gt;
+
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-4">
+  В результате компонент Source можно использовать, чтобы оборачивать другие
+  компоненты, требующие данные, передать в компонент источник данных, результат
+  работы которого будет в пропсе data в слоте default.
+</p>

package/docs/pages/patron/index.html

@@ -0,0 +1,140 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Класс Patron</h1>
+
+<a href="https://github.com/kosukhin/patron/blob/main/src/Patron/Patron.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" />
+  Patron на 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-guest">
+      гостя
+    </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">
+  Это поведение полезно в случаях, когда нужно из просто посетителя(гостя)
+  сделать постоянного посетиеля(патрона). Это будет означать что если у
+  <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-0 font-bold">Пример 1.</p>
+<pre class="mb-4"><code class="language-js">import {
+  Patron,
+  SourceWithPool,
+  Source,
+  GuestDisposable,
+  isPatronInPools,
+} from "patron-oop";
+
+const source = new SourceWithPool(1);
+const timer = new Source((guest) => {
+  source.value(guest);
+  const repeat = () => {
+    if (!isPatronInPools(guest)) {
+      return;
+    }
+    source.value((value) => {
+      setTimeout(() => {
+        source.give(value + 1);
+        repeat();
+      }, 1000);
+    });
+  };
+  repeat();
+});
+
+timer.value(
+  new Patron(
+    new GuestDisposable(
+      (value) => {
+        const el = document.querySelector(".patron-result");
+        if (el) {
+          el.textContent = `Секунд прошло ${value}`;
+        }
+      },
+      () => {
+        return !document.querySelector(".patron-result");
+      }
+    )
+  )
+);
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 1.</p>
+<div class="example mb-4">
+  <span class="patron-result">Result here</span>
+</div>
+<script type="module">
+  import {
+    Patron,
+    SourceWithPool,
+    Source,
+    GuestDisposable,
+    isPatronInPools,
+  } from "patron-oop";
+
+  const source = new SourceWithPool(1);
+  const timer = new Source((guest) => {
+    source.value(guest);
+    const repeat = () => {
+      if (!isPatronInPools(guest)) {
+        return;
+      }
+      source.value((value) => {
+        setTimeout(() => {
+          source.give(value + 1);
+          repeat();
+        }, 1000);
+      });
+    };
+    repeat();
+  });
+
+  timer.value(
+    new Patron(
+      new GuestDisposable(
+        (value) => {
+          const el = document.querySelector(".patron-result");
+          if (el) {
+            el.textContent = `Секунд прошло ${value}`;
+          }
+        },
+        () => {
+          return !document.querySelector(".patron-result");
+        }
+      )
+    )
+  );
+</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="/source">Source</a>
+  <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="/guest/guest-disposable">GuestDisposable</a>
+  <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="/source/source-with-pool">SourceWithPool</a>
+  <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="/utils/is-patron-in-pools">isPatronInPools</a>
+</p>

package/docs/pages/patron/patron-applied.html

@@ -0,0 +1,66 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Класс PatronApplied</h1>
+
+<a href="https://github.com/kosukhin/patron/blob/main/src/Patron/PatronApplied.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" />
+  PatronApplied на GitHub
+</a>
+
+<p class="text-gray-600 text-lg mb-4">
+  Класс PatronApplied под капотом использует GuestApplied, только является патроном.
+</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 { Guest, PatronApplied, SourceWithPool } from "patron-oop";
+
+window.source = new SourceWithPool(20);
+
+const guest = new Guest((value) => {
+  document.querySelector(
+    ".guest-result"
+  ).textContent = `Double value is ${value}`;
+});
+
+window.source.value(
+  new PatronApplied(guest, (x) => x * 2)
+);
+</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>
+<button
+  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"
+  onclick="source.give(40)"
+>
+  Дать источнику значение 40
+</button>
+<button
+  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"
+  onclick="source.give(25)"
+>
+  Дать источнику значение 25
+</button>
+<script type="module">
+  import { Guest, PatronApplied, SourceWithPool } from "patron-oop";
+
+  window.source = new SourceWithPool(20);
+
+  const guest = new Guest((value) => {
+    document.querySelector(
+      ".guest-result"
+    ).textContent = `Double value is ${value}`;
+  });
+
+  window.source.value(
+    new PatronApplied(guest, (x) => x * 2)
+  );
+</script>

package/docs/pages/patron/patron-executor-applied.html

@@ -0,0 +1,94 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Класс PatronExecutorApplied</h1>
+
+<a
+  href="https://github.com/kosukhin/patron/blob/main/src/Patron/PatronExecutorApplied.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"
+  />
+  PatronExecutorApplied на GitHub
+</a>
+
+<p class="text-gray-600 text-lg mb-4">
+  Класс PatronExecutorApplied под капотом использует GuestExecutorApplied, только является патроном.
+</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 { Guest, PatronExecutorApplied, Patron, SourceWithPool } from "patron-oop";
+
+window.source = new SourceWithPool(20);
+
+const loadingSource = new SourceWithPool('');
+
+const guest = new Guest((value) => {
+  document.querySelector(
+    ".guest-result"
+  ).textContent = `value is ${value}`;
+});
+
+loadingSource.value(new Patron(guest));
+
+window.source.value(
+  new PatronExecutorApplied(guest, (guestFn) => {
+    return v => {
+      loadingSource.give('Загрузка...');
+      setTimeout(() => {
+        guestFn(v);
+      }, 5000)
+    }
+  })
+);
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 1.</p>
+<div class="example mb-4">
+  <span class="guest-result">Результат через 5 сек...</span>
+</div>
+<button
+  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"
+  onclick="source.give(40)"
+>
+  Дать источнику значение 40
+</button>
+<button
+  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"
+  onclick="source.give(25)"
+>
+  Дать источнику значение 25
+</button>
+<script type="module">
+  import { Guest, PatronExecutorApplied, Patron, SourceWithPool } from "patron-oop";
+
+  window.source = new SourceWithPool(20);
+
+  const loadingSource = new SourceWithPool('');
+
+  const guest = new Guest((value) => {
+    document.querySelector(
+      ".guest-result"
+    ).textContent = `value is ${value}`;
+  });
+
+  loadingSource.value(new Patron(guest));
+
+  window.source.value(
+    new PatronExecutorApplied(guest, (guestFn) => {
+      return v => {
+        loadingSource.give('Загрузка...');
+        setTimeout(() => {
+          guestFn(v);
+        }, 5000)
+      }
+    })
+  );
+</script>

package/docs/pages/patron/patron-once.html

@@ -0,0 +1,110 @@
+<h1 class="pb-3 text-xl font-semibold text-gray-600">Класс PatronOnce</h1>
+
+<a
+  href="https://github.com/kosukhin/patron/blob/main/src/Patron/PatronOnce.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"
+  />
+  PatronOnce на 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-patron"
+    >
+      патрона
+    </a>
+  </span>
+  , который будет выполнен только один раз и удалит себя после получения первого
+  значения
+</p>
+
+<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">
+  Схожий результат можно получить при использовании классов GuestDisposable или
+  GuestPool или SourceEmpty
+</p>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Пример 1.</p>
+<pre class="mb-4"><code class="language-js">import { SourceWithPool, PatronOnce } from "patron-oop";
+
+const source = new SourceWithPool("один раз");
+source.value(
+  new PatronOnce((value) => {
+    document.querySelector(
+      ".patron-once-result"
+    ).textContent = `Результат ${value}`;
+  })
+);
+
+setTimeout(() => {
+  source.give("два раза");
+});
+setTimeout(() => {
+  source.give("три раза");
+});
+</code></pre>
+
+<p class="text-gray-600 text-lg mb-0 font-bold">Результат 1.</p>
+<div class="example mb-4">
+  <span class="patron-once-result">Нет результата!</span>
+</div>
+<script type="module">
+  import { SourceWithPool, PatronOnce } from "patron-oop";
+
+  const source = new SourceWithPool("один раз");
+  source.value(
+    new PatronOnce((value) => {
+      document.querySelector(
+        ".patron-once-result"
+      ).textContent = `Результат ${value}`;
+    })
+  );
+
+  setTimeout(() => {
+    source.give("два раза");
+  });
+  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="/guest/guest-pool"
+    >GuestPool</a
+  >
+  <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="/guest/guest-disposable"
+    >GuestDisposable</a
+  >
+  <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="/source"
+    >Source</a
+  >
+</p>