|
1 | | -<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@libreworks/container</title><meta name="description" content="Documentation for @libreworks/container"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="index.html" class="title">@libreworks/container</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@libreworks/container</h1></div><div class="tsd-panel tsd-typography"><h1 id="libreworkscontainer" class="tsd-anchor-link">@libreworks/container<a href="#libreworkscontainer" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><p><a href="https://github.com/libreworks/container/blob/main/LICENSE"><img src="https://img.shields.io/github/license/libreworks/container" alt="MIT"></a> |
| 1 | +<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@libreworks/container</title><meta name="description" content="Documentation for @libreworks/container"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="index.html" class="title">@libreworks/container</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@libreworks/container</h1></div><div class="tsd-panel tsd-typography"><h1 id="libreworkscontainer" class="tsd-anchor-link">@libreworks/container<a href="#libreworkscontainer" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1> |
| 2 | +<p><a href="https://github.com/libreworks/container/blob/main/LICENSE"><img src="https://img.shields.io/github/license/libreworks/container" alt="MIT"></a> |
2 | 3 | <a href="https://www.npmjs.com/package/@libreworks/container"><img src="https://img.shields.io/npm/v/@libreworks/container" alt="npm"></a> |
3 | 4 | <a href="https://github.com/libreworks/container/actions/workflows/release.yml"><img src="https://img.shields.io/github/workflow/status/libreworks/container/release/main?label=release" alt="GitHub Workflow Status (branch)"></a> |
4 | 5 | <a href="https://github.com/libreworks/container/releases"><img src="https://img.shields.io/github/v/release/libreworks/container?sort=semver" alt="GitHub release (latest SemVer)"></a> |
5 | 6 | <a href="https://codecov.io/gh/libreworks/container"><img src="https://codecov.io/gh/libreworks/container/branch/main/graph/badge.svg?token=OHTRGNTSPO" alt="codecov"></a></p> |
6 | 7 | <p>A simple asynchronous dependency injection container and event target.</p> |
7 | | -<h2 id="installation" class="tsd-anchor-link">Installation<a href="#installation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">@libreworks/container</span> |
| 8 | +<h2 id="installation" class="tsd-anchor-link">Installation<a href="#installation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> |
| 9 | +<pre><code class="shell"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">@libreworks/container</span> |
8 | 10 | </code><button type="button">Copy</button></pre> |
9 | 11 |
|
10 | 12 | <p>This library conforms to ECMAScript Modules (ESM). You can import this module using ESM or TypeScript syntax.</p> |
11 | 13 | <pre><code class="TypeScript"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">Builder</span><span class="hl-1">, </span><span class="hl-4">Container</span><span class="hl-1">, </span><span class="hl-4">Producer</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">"@libreworks/container"</span><span class="hl-1">;</span> |
12 | 14 | </code><button type="button">Copy</button></pre> |
13 | 15 |
|
14 | 16 | <p>If you're using CommonJS, you must use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import">dynamic imports</a> instead.</p> |
15 | | -<h2 id="usage" class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>You can use this library to create a graph of objects with intertwined dependencies. These objects and values can even be produced asynchronously.</p> |
16 | | -<h3 id="container" class="tsd-anchor-link">Container<a href="#container" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>A container provides named values.</p> |
| 17 | +<h2 id="usage" class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> |
| 18 | +<p>You can use this library to create a graph of objects with intertwined dependencies. These objects and values can even be produced asynchronously.</p> |
| 19 | +<h3 id="container" class="tsd-anchor-link">Container<a href="#container" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3> |
| 20 | +<p>A container provides named values.</p> |
17 | 21 | <pre><code class="typescript"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">Foobar</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">"your-package-name-here"</span><span class="hl-1">;</span><br/><br/><span class="hl-5">// Assume we created a Container.</span><br/><span class="hl-6">declare</span><span class="hl-1"> </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">container</span><span class="hl-1">: </span><span class="hl-8">Container</span><span class="hl-1">;</span><br/><span class="hl-5">// Retrieve a value by its name.</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">myObject</span><span class="hl-1">: </span><span class="hl-8">Foobar</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">container</span><span class="hl-1">.</span><span class="hl-0">get</span><span class="hl-1">(</span><span class="hl-2">"MyObject"</span><span class="hl-1">);</span><br/><span class="hl-5">// Retrieve multiple values by their names.</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">allObjects</span><span class="hl-1">: </span><span class="hl-8">Foobar</span><span class="hl-1">[] = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">container</span><span class="hl-1">.</span><span class="hl-0">getAll</span><span class="hl-1">([</span><span class="hl-2">"MyObject"</span><span class="hl-1">, </span><span class="hl-2">"Another"</span><span class="hl-1">]);</span><br/><span class="hl-5">// Retrieve values by tag.</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">taggedByMe</span><span class="hl-1">: </span><span class="hl-8">Foobar</span><span class="hl-1">[] = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">container</span><span class="hl-1">.</span><span class="hl-0">getAllTagged</span><span class="hl-1">(</span><span class="hl-2">"my-tag"</span><span class="hl-1">);</span> |
18 | 22 | </code><button type="button">Copy</button></pre> |
19 | 23 |
|
20 | | -<h4 id="events" class="tsd-anchor-link">Events<a href="#events" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>The <code>Container</code> class extends the <code>EventTarget</code> class (<a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget">see MDN docs</a>).</p> |
21 | | -<h3 id="builder" class="tsd-anchor-link">Builder<a href="#builder" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>In order to put together a <code>Container</code>, you can use the <code>Builder</code> class.</p> |
| 24 | +<h4 id="events" class="tsd-anchor-link">Events<a href="#events" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4> |
| 25 | +<p>The <code>Container</code> class extends the <code>EventTarget</code> class (<a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget">see MDN docs</a>).</p> |
| 26 | +<h3 id="builder" class="tsd-anchor-link">Builder<a href="#builder" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3> |
| 27 | +<p>In order to put together a <code>Container</code>, you can use the <code>Builder</code> class.</p> |
22 | 28 | <pre><code class="typescript"><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">builder</span><span class="hl-1"> = </span><span class="hl-6">new</span><span class="hl-1"> </span><span class="hl-0">Builder</span><span class="hl-1">()</span><br/><span class="hl-1"> </span><span class="hl-5">// Register a constant</span><br/><span class="hl-1"> .</span><span class="hl-0">constant</span><span class="hl-1">(</span><span class="hl-2">"ExampleValue"</span><span class="hl-1">, </span><span class="hl-2">"Lorem ipsum dolor sit amet"</span><span class="hl-1">)</span><br/><span class="hl-1"> </span><span class="hl-5">// Register an array.</span><br/><span class="hl-1"> .</span><span class="hl-0">constant</span><span class="hl-1">(</span><span class="hl-2">"my.numbers"</span><span class="hl-1">, [</span><span class="hl-9">1</span><span class="hl-1">, </span><span class="hl-9">2</span><span class="hl-1">, </span><span class="hl-9">3</span><span class="hl-1">, </span><span class="hl-9">5</span><span class="hl-1">, </span><span class="hl-9">8</span><span class="hl-1">, </span><span class="hl-9">13</span><span class="hl-1">, </span><span class="hl-9">21</span><span class="hl-1">])</span><br/><span class="hl-1"> </span><span class="hl-5">// Register an object created synchronously.</span><br/><span class="hl-1"> .</span><span class="hl-0">register</span><span class="hl-1">(</span><span class="hl-2">"RandomName"</span><span class="hl-1">, () </span><span class="hl-6">=></span><span class="hl-1"> </span><span class="hl-4">AnotherClass</span><span class="hl-1">.</span><span class="hl-0">doSomething</span><span class="hl-1">())</span><br/><span class="hl-1"> </span><span class="hl-5">// Register an object created asynchronously.</span><br/><span class="hl-1"> .</span><span class="hl-0">register</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-2">"an-async-value"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">async</span><span class="hl-1"> (</span><span class="hl-4">c</span><span class="hl-1">) </span><span class="hl-6">=></span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">myNumbers</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">c</span><span class="hl-1">.</span><span class="hl-0">get</span><span class="hl-1">(</span><span class="hl-2">"my.numbers"</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-3">return</span><span class="hl-1"> </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-0">createNewThingy</span><span class="hl-1">(</span><span class="hl-4">myNumbers</span><span class="hl-1">);</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> [</span><span class="hl-2">"my-tag"</span><span class="hl-1">, </span><span class="hl-2">"AnotherTag"</span><span class="hl-1">, </span><span class="hl-2">"Yet another"</span><span class="hl-1">]</span><br/><span class="hl-1"> );</span><br/><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">container</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">builder</span><span class="hl-1">.</span><span class="hl-0">build</span><span class="hl-1">();</span><br/><br/><span class="hl-5">// Use the get method's generic type if you prefer.</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">anAsyncValue</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">container</span><span class="hl-1">.</span><span class="hl-0">get</span><span class="hl-1"><</span><span class="hl-8">MyClassName</span><span class="hl-1">>(</span><span class="hl-2">"an-async-value"</span><span class="hl-1">);</span> |
23 | 29 | </code><button type="button">Copy</button></pre> |
24 | 30 |
|
25 | 31 | <p>You provide a name and a "factory" function when you call the <code>register</code> method. The factory function needs to return the value you want to register; it can be asynchronous or return a <code>Promise</code> as well.</p> |
26 | 32 | <p>Once the container is built, a call to <code>get</code> using the same name will invoke the factory function. The container provides itself as the first argument. That way, you can recursively locate other dependencies immediately before constructing the return value.</p> |
27 | 33 | <p>Since the container is an <code>EventTarget</code>, the factory function could broadcast an event, or the value returned by the factory function can register itself as an event listener. This feature allows objects inside the container to communicate in a loosely-coupled way.</p> |
28 | 34 | <p>The factory function will only ever be invoked once, no matter how many times <code>get</code> is invoked.</p> |
29 | | -<h4 id="eager-creation" class="tsd-anchor-link">Eager Creation<a href="#eager-creation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>Normally, values are lazy-loaded; they are created on-demand. However, you can provide the <code>@eager</code> tag when you call the <code>register</code> method to ensure your objects initialize themselves when the container is created.</p> |
| 35 | +<h4 id="eager-creation" class="tsd-anchor-link">Eager Creation<a href="#eager-creation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4> |
| 36 | +<p>Normally, values are lazy-loaded; they are created on-demand. However, you can provide the <code>@eager</code> tag when you call the <code>register</code> method to ensure your objects initialize themselves when the container is created.</p> |
30 | 37 | <pre><code class="typescript"><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">builder</span><span class="hl-1"> = </span><span class="hl-6">new</span><span class="hl-1"> </span><span class="hl-0">Builder</span><span class="hl-1">().</span><span class="hl-0">register</span><span class="hl-1">(</span><span class="hl-2">"FooBar"</span><span class="hl-1">, () </span><span class="hl-6">=></span><span class="hl-1"> </span><span class="hl-6">new</span><span class="hl-1"> </span><span class="hl-0">Thingy</span><span class="hl-1">(), [</span><br/><span class="hl-1"> </span><span class="hl-2">"@eager"</span><span class="hl-1">,</span><br/><span class="hl-1">]);</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">container</span><span class="hl-1"> = </span><span class="hl-3">await</span><span class="hl-1"> </span><span class="hl-4">builder</span><span class="hl-1">.</span><span class="hl-0">build</span><span class="hl-1">();</span><br/><span class="hl-5">// Thingy has already been instantiated.</span> |
31 | 38 | </code><button type="button">Copy</button></pre> |
32 | 39 |
|
|
![libreworksautomation[bot]](https://avatars.githubusercontent.com/in/1099252?v=4&size=40){kind=avatar}
0 commit comments