Astrologue-Website/developer/inversion/index.html

<!doctype html>
<html lang="en-nz">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Inversion — Astrologue Developer</title>
  <meta name="description" content="Inversion of control for the Web-Stack: a dependency-injection container for Vala with modules, scopes and three lifecycles, wired by field injection. Free software, LGPL-3.0-or-later.">
  <meta name="color-scheme" content="light dark">
  <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  <meta property="og:title" content="Inversion — Astrologue Developer">
  <meta property="og:description" content="A dependency injection (IoC) container for Vala: three lifecycles, field injection, multi-registration and scope-local registrations.">
  <meta property="og:type" content="website">
  <link rel="stylesheet" href="../../assets/css/style.css">
</head>
<body>
  <a class="skip-link" href="#main">Skip to content</a>

  <header class="masthead">
    <div class="container masthead__inner">
      <a class="brand" href="../../">
        <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
        <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
      </a>
      <nav class="site-nav" aria-label="Primary">
        <ul class="site-nav__list">
          <li><a href="../../">Home</a></li>
          <li><a href="../../#news">News</a></li>
          <li><a href="../../#download">Download</a></li>
          <li><a href="../" aria-current="page">Developer</a></li>
          <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
        </ul>
      </nav>
    </div>
  </header>

  <main id="main">

    <nav class="breadcrumb" aria-label="Breadcrumb">
      <div class="container">
        <ol>
          <li><a href="../../">Astrologue</a></li>
          <li><a href="../">Developer</a></li>
          <li aria-current="page">Inversion</li>
        </ol>
      </div>
    </nav>

    <section class="docs-header">
      <div class="container">
        <p class="kicker"><span>Foundation · The wiring of the Web-Stack</span></p>
        <h1>Inversion</h1>
        <p class="lede">A dependency injection (IoC) container for Vala — three lifecycles, field injection, multi-registration and scope-local registrations. It is how an Astrologue web application wires itself together at startup.</p>
        <dl class="docs-facts">
          <div><dt>Version</dt> <dd><code>0.2</code></dd></div>
          <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
          <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;inversion</code></dd></div>
          <div><dt>Language</dt> <dd>Vala</dd></div>
        </dl>
      </div>
    </section>

    <section class="band band--plain" id="docs">
      <div class="container docs-layout">

        <nav class="docs-toc" aria-label="On this page">
          <h2>On this page</h2>
          <ul>
            <li><a href="#overview">Overview</a></li>
            <li><a href="#features">Features</a></li>
            <li><a href="#installation">Installation</a></li>
            <li><a href="#usage">Usage &amp; documentation</a></li>
            <li><a href="#package">Package &amp; source</a></li>
          </ul>
        </nav>

        <div class="docs-prose">

          <header class="section-head" id="overview">
            <p class="kicker"><span>Overview</span></p>
            <h2>Why it exists</h2>
          </header>
          <p>Inversion is a dependency injection (IoC) container for Vala. Applications declare what they need; the container decides what concrete thing fills each need, and when a new instance is made versus shared. Nothing in the stack reaches out and constructs its own collaborators — the wiring lives in one place, and that place is testable.</p>
          <p>The Web-Stack is built around it. Spry's users and permissions, Invercargill-Sql's connections and sessions, an application's own services — all are registered in a container, resolved in scopes, and injected by field. The companion library <a href="../invercargill-sql-inversion/">Invercargill-Sql-Inversion</a> exists purely to make this container and the database layer one motion.</p>

          <header class="section-head" id="features">
            <p class="kicker"><span>Features</span></p>
            <h2>What it hands you</h2>
          </header>
          <ul class="docs-features">
            <li><strong>Three lifecycles.</strong> Transient — a new instance each time; Scoped — one per scope; Singleton — one per container.</li>
            <li><strong>Field injection.</strong> Dependencies resolve via <code>inject&lt;T&gt;()</code> in field initializers; no constructor plumbing.</li>
            <li><strong>Multi-registration.</strong> Register several implementations for one service type and resolve them all at once.</li>
            <li><strong>Scope-local registrations.</strong> Add registrations that only exist within a scope.</li>
            <li><strong>Fluent API.</strong> Chained registration methods keep configuration readable.</li>
            <li><strong>Registration metadata.</strong> Registrations carry typed metadata that other services can query — how the type provider of the data layer finds its mappers.</li>
          </ul>

          <header class="section-head" id="installation">
            <p class="kicker"><span>Installation</span></p>
            <h2>Getting the library</h2>
          </header>
          <figure class="code-plate">
            <pre><code>usm install inversion</code></pre>
            <figcaption>USM resolves <code>invercargill-1</code> itself.</figcaption>
          </figure>
          <p>From source:</p>
          <figure class="code-plate">
            <pre><code>git clone &lt;the Inversion repository&gt;
cd Inversion
meson setup build
ninja -C build
ninja -C build install</code></pre>
            <figcaption>GLib, GObject and Invercargill are the whole dependency set.</figcaption>
          </figure>
          <figure class="code-plate">
            <pre><code>valac --pkg inversion-0.1 my-program.vala</code></pre>
            <figcaption>The binding pulls in its <code>.deps</code> chain automatically.</figcaption>
          </figure>

          <header class="section-head" id="usage">
            <p class="kicker"><span>Usage &amp; documentation</span></p>
            <h2>Quick start, from the README</h2>
          </header>
          <p>Define a service, register an implementation, resolve it through a scope:</p>
          <figure class="code-plate">
            <pre><code>using Inversion;

// Define your service
public interface Logger : Object {
    public abstract void log(string message);
}

public class ConsoleLogger : Object, Logger {
    public void log(string message) {
        stdout.printf("[LOG] %s\n", message);
    }
}

// Register and resolve
var container = new Container();
container.register_singleton&lt;ConsoleLogger&gt;((scope) =&gt; new ConsoleLogger())
    .as_type(typeof(Logger));

var scope = container.create_scope();
var logger = scope.resolve&lt;Logger&gt;();
logger.log("Hello!");</code></pre>
            <figcaption>Verbatim from the README's Quick Start.</figcaption>
          </figure>
          <h3>Lifecycles</h3>
          <p>One registration per lifetime policy:</p>
          <figure class="code-plate">
            <pre><code>container.register_transient&lt;MyService&gt;((s) =&gt; new MyService());
container.register_scoped&lt;MyService&gt;((s) =&gt; new MyService());
container.register_singleton&lt;MyService&gt;((s) =&gt; new MyService());</code></pre>
            <figcaption>Transient: new instance every resolve. Scoped: one per scope. Singleton: one per container.</figcaption>
          </figure>
          <h3>Field injection</h3>
          <p>Dependencies are injected using the <code>inject&lt;T&gt;()</code> function in field initializers — resolved automatically when the owning class is created:</p>
          <figure class="code-plate">
            <pre><code>public class UserService : Object {
    private Logger logger = inject&lt;Logger&gt;();

    public void greet(string name) {
        this.logger.log(@"Hello, $name!");
    }
}

var userService = scope.resolve&lt;UserService&gt;();</code></pre>
            <figcaption>And <code>inject_all&lt;T&gt;()</code> brings in every implementation: <code>private Lot&lt;Logger&gt; loggers = inject_all&lt;Logger&gt;();</code></figcaption>
          </figure>
          <h3>Multiple implementations</h3>
          <figure class="code-plate">
            <pre><code>container.register_singleton&lt;FileLogger&gt;((s) =&gt; new FileLogger())
    .as_type(typeof(Logger));
container.register_singleton&lt;ConsoleLogger&gt;((s) =&gt; new ConsoleLogger())
    .as_type(typeof(Logger));

// Get all implementations
var allLoggers = scope.resolve_all&lt;Logger&gt;();</code></pre>
            <figcaption>From the README.</figcaption>
          </figure>
          <h3>Scopes with their own registrations</h3>
          <figure class="code-plate">
            <pre><code>var scope = container.create_scope();

// Add a registration only available in this scope
scope.register_singleton&lt;RequestContext&gt;((s) =&gt; new RequestContext())
    .as_type(typeof(Context));</code></pre>
            <figcaption>Scopes manage scoped instance lifetime and can carry local registrations.</figcaption>
          </figure>
          <p>The repository's <code>examples/</code> directory walks each feature end to end — <code>BasicUsage.vala</code>, <code>LifecycleDemo.vala</code>, <code>InjectionDemo.vala</code>, <code>MultiRegistration.vala</code> and <code>ScopeRegistrationDemo.vala</code> — and the library's test suite runs through <code>meson test</code> and USM's <code>test</code> exec.</p>

          <header class="section-head" id="package">
            <p class="kicker"><span>Package &amp; source</span></p>
            <h2>The ledger</h2>
          </header>
          <dl class="docs-package">
            <div><dt>Version</dt><dd><code>0.2</code> (from <code>MANIFEST.usm</code>)</dd></div>
            <div><dt>Licence</dt><dd>LGPL-3.0-or-later — free to run, study, share and improve; the LGPL keeps it free to link from any program.</dd></div>
            <div><dt>Package</dt><dd><code>usm install inversion</code></dd></div>
            <div><dt>Provides</dt><dd><code>libinversion-0.1.so</code>, <code>inversion-0.1.h</code>, <code>inversion-0.1.vapi</code> + <code>.deps</code>, <code>inversion-0.1.gir</code>, <code>inversion-0.1.typelib</code>, <code>inversion-0.1.pc</code></dd></div>
            <div><dt>Needs at runtime</dt><dd>GLib, GObject, and <code>libinvercargill-1.so</code>.</dd></div>
            <div><dt>Source</dt><dd>The repository <code>Tilo15/Inversion</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
          </dl>

          <nav class="docs-siblings" aria-label="Neighbours in the catalogue">
            <p>Its neighbours:</p>
            <ul>
              <li><a href="../invercargill-json/">Invercargill-Json</a></li>
              <li><a href="../invercargill-sql/">Invercargill-Sql</a></li>
              <li><a href="../invercargill-sql-inversion/">Invercargill-Sql-Inversion</a></li>
            </ul>
          </nav>

          <nav class="docs-pager" aria-label="Project pages">
            <a class="docs-pager__link docs-pager__link--prev" href="../invercargill-json/">
              <span>Previous</span>
              <strong>Invercargill-Json</strong>
            </a>
            <p class="docs-pager__up"><a href="../">All eleven</a></p>
            <a class="docs-pager__link docs-pager__link--next" href="../invercargill-sql/">
              <span>Next in the catalogue</span>
              <strong>Invercargill-Sql</strong>
            </a>
          </nav>

        </div>
      </div>
    </section>

  </main>

  <footer class="site-footer">
    <div class="container">
      <div class="footer-grid">
        <div class="foot-brand">
          <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
          <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
        </div>
        <nav aria-label="The four freedoms">
          <p class="foot-title">The Four Freedoms</p>
          <ol class="freedoms">
            <li><strong>Run</strong> the software as you wish, for any purpose.</li>
            <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
            <li><strong>Share</strong> copies so you can help others.</li>
            <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
          </ol>
        </nav>
        <nav aria-label="Site">
          <p class="foot-title">Site</p>
          <ul class="foot-list">
            <li><a href="../../">Home</a></li>
            <li><a href="../../#news">News</a></li>
            <li><a href="../../#download">Download</a></li>
            <li><a href="../">Developer</a></li>
          </ul>
        </nav>
      </div>
      <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
    </div>
  </footer>
</body>
</html>