@joist/di 3.0.1 → 3.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/di",
-  "version": "3.0.1",
+  "version": "3.0.4",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
@@ -13,6 +13,7 @@
     }
   },
   "files": [
+    "src",
     "target"
   ],
   "sideEffects": false,

package/src/lib/environment.test.ts

@@ -0,0 +1,30 @@
+import { expect, fixture, html } from '@open-wc/testing';
+
+import { Injector } from './injector.js';
+import { environment, clearEnvironment } from './environment.js';
+import { injectable } from './injectable.js';
+import { inject } from './inject.js';
+
+describe('environment', () => {
+  afterEach(clearEnvironment);
+
+  it('should create a global Injector instance', () => {
+    expect(environment()).to.be.instanceOf(Injector);
+  });
+
+  it('should use the root injector when creating services', async () => {
+    @injectable
+    class MyService { }
+
+    @injectable
+    class MyElement extends HTMLElement {
+      my = inject(MyService);
+    }
+
+    customElements.define('env-1', MyElement);
+
+    const el = await fixture<MyElement>(html`<env-1></env-1>`);
+
+    expect(el.my()).to.equal(environment().get(MyService));
+  });
+});

package/src/lib/environment.ts

@@ -0,0 +1,17 @@
+import { Injector } from './injector.js';
+import { Provider } from './provider.js';
+
+const rootInjector = new Injector();
+
+export function environment(): Injector {
+  return rootInjector;
+}
+
+export function defineEnvironment(providers: Provider<any>[]) {
+  environment().providers = providers;
+}
+
+export function clearEnvironment(): void {
+  rootInjector.providers = [];
+  rootInjector.clear();
+}

package/src/lib/inject.test.ts

@@ -0,0 +1,71 @@
+import { expect } from '@open-wc/testing';
+
+import { inject } from './inject.js';
+import { injectable } from './injectable.js';
+import { Injector } from './injector.js';
+
+describe('inject', () => {
+  it('should work', () => {
+    class HelloService { }
+
+    @injectable
+    class HelloWorld extends HTMLElement {
+      hello = inject(HelloService);
+    }
+
+    customElements.define('inject-1', HelloWorld);
+
+    expect(new HelloWorld().hello()).to.be.instanceOf(HelloService);
+  });
+
+  it('should throw error if called in constructor', () => {
+    class FooService {
+      value = '1';
+    }
+
+    @injectable
+    class BarService {
+      foo = inject(FooService);
+
+      constructor() {
+        this.foo();
+      }
+    }
+
+    const parent = new Injector();
+
+    try {
+      parent.get(BarService);
+
+      throw new Error('Should not succeed');
+    } catch (err) {
+      const error = err as Error;
+
+      expect(error.message).to.equal(
+        `BarService is either not injectable or a service is being called in the constructor. \n Either add the @injectable to your class or use the onInject callback method.`
+      );
+    }
+  });
+
+  it('should use the calling injector as parent', () => {
+    class FooService {
+      value = '1';
+    }
+
+    @injectable
+    class BarService {
+      foo = inject(FooService);
+    }
+
+    const parent = new Injector([
+      {
+        provide: FooService,
+        use: class extends FooService {
+          value = '100';
+        },
+      },
+    ]);
+
+    expect(parent.get(BarService).foo().value).to.equal('100');
+  });
+});

package/src/lib/inject.ts

@@ -0,0 +1,20 @@
+import { ProviderToken } from './provider.js';
+import { Injectable } from './injector.js';
+
+export type Injected<T> = () => T;
+
+export function inject<This extends Injectable, T extends object>(
+  token: ProviderToken<T>
+): Injected<T> {
+  return function (this: This) {
+    if (this.injector$$ === undefined) {
+      const name = Object.getPrototypeOf(this.constructor).name;
+
+      throw new Error(
+        `${name} is either not injectable or a service is being called in the constructor. \n Either add the @injectable to your class or use the onInject callback method.`
+      );
+    }
+
+    return this.injector$$.get(token);
+  };
+}

package/src/lib/injectable.test.ts

@@ -0,0 +1,144 @@
+import { expect, fixture, html } from '@open-wc/testing';
+
+import { injectable } from './injectable.js';
+import { inject } from './inject.js';
+import { Injector } from './injector.js';
+
+describe('@injectable()', () => {
+  it('should allow a custom element to be injected with deps', () => {
+    class Foo {}
+    class Bar {}
+
+    @injectable
+    class MyElement extends HTMLElement {
+      foo = inject(Foo);
+      bar = inject(Bar);
+    }
+
+    customElements.define('injectable-1', MyElement);
+
+    const el = document.createElement('injectable-1') as MyElement;
+
+    expect(el.foo()).to.be.instanceOf(Foo);
+  });
+
+  it('should locally override a provider', () => {
+    class Foo {}
+
+    class Bar extends Foo {}
+
+    const MyElement = injectable(
+      class {
+        static providers = [{ provide: Foo, use: Bar }];
+
+        foo = inject(Foo);
+      }
+    );
+
+    const el = new MyElement();
+
+    expect(el.foo()).to.be.instanceOf(Bar);
+  });
+
+  it('should call the onInject lifecycle hook', () => {
+    class A {}
+
+    @injectable
+    class B {
+      a = inject(A);
+
+      onInject() {
+        expect(this.a()).to.be.instanceOf(A);
+      }
+    }
+
+    new Injector().get(B);
+  });
+
+  it('should handle parent HTML Injectors', async () => {
+    @injectable
+    class A {}
+
+    const B = injectable(
+      class {
+        a = inject(A);
+      }
+    );
+
+    class AltA implements A {}
+
+    @injectable
+    class Parent extends HTMLElement {
+      static providers = [
+        { provide: B, use: B },
+        { provide: A, use: AltA },
+      ];
+    }
+
+    @injectable
+    class Child extends HTMLElement {
+      b = inject(B);
+    }
+
+    customElements.define('injectable-parent-1', Parent);
+    customElements.define('injectable-child-1', Child);
+
+    const el = await fixture(html`
+      <injectable-parent-1>
+        <injectable-child-1></injectable-child-1>
+      </injectable-parent-1>
+    `);
+
+    const child = el.querySelector<Child>('injectable-child-1')!;
+
+    expect(child.b().a()).to.be.instanceOf(AltA);
+  });
+
+  it('should handle changing contexts', async () => {
+    class A {}
+    class AltA implements A {}
+
+    @injectable
+    class Ctx1 extends HTMLElement {
+      static providers = [{ provide: A, use: A }];
+    }
+
+    @injectable
+    class Ctx2 extends HTMLElement {
+      static providers = [{ provide: A, use: AltA }];
+    }
+
+    @injectable
+    class Child extends HTMLElement {
+      a = inject(A);
+    }
+
+    customElements.define('ctx-1', Ctx1);
+    customElements.define('ctx-2', Ctx2);
+    customElements.define('ctx-child', Child);
+
+    const el = await fixture(html`
+      <div>
+        <ctx-1>
+          <ctx-child></ctx-child>
+        </ctx-1>
+
+        <ctx-2></ctx-2>
+      </div>
+    `);
+
+    const ctx2 = el.querySelector('ctx-2')!;
+
+    let child = el.querySelector<Child>('ctx-child')!;
+
+    expect(child.a()).to.be.instanceOf(A);
+
+    child.remove();
+
+    ctx2.append(child);
+
+    child = el.querySelector<Child>('ctx-child')!;
+
+    expect(child.a()).to.be.instanceOf(AltA);
+  });
+});

package/src/lib/injectable.ts

@@ -0,0 +1,69 @@
+import { ProviderToken } from './provider.js';
+import { Injectable, Injector } from './injector.js';
+import { environment } from './environment.js';
+
+export function injectable<T extends ProviderToken<any>>(Base: T, _?: unknown) {
+  return class InjectableNode extends Base implements Injectable {
+    injector$$ = new Injector(Base.providers);
+
+    constructor(..._: any[]) {
+      super();
+
+      try {
+        if (this instanceof HTMLElement) {
+          this.addEventListener('finddiroot', (e) => {
+            const parentInjector = findInjectorRoot(e);
+
+            if (parentInjector !== null) {
+              this.injector$$.setParent(parentInjector);
+            } else {
+              this.injector$$.setParent(environment());
+            }
+          });
+        }
+      } catch {}
+    }
+
+    onInject() {
+      if (super.onInject) {
+        super.onInject();
+      }
+    }
+
+    connectedCallback() {
+      try {
+        if (this instanceof HTMLElement) {
+          this.dispatchEvent(new Event('finddiroot'));
+
+          if (super.connectedCallback) {
+            super.connectedCallback();
+          }
+        }
+      } catch {}
+    }
+
+    disconnectedCallback() {
+      this.injector$$.setParent(undefined);
+
+      if (super.disconnectedCallback) {
+        super.disconnectedCallback();
+      }
+    }
+  };
+}
+
+function findInjectorRoot(e: Event): Injector | null {
+  const path = e.composedPath();
+
+  // find firt parent
+  // skips the first item which is the target
+  for (let i = 1; i < path.length; i++) {
+    const part = path[i];
+
+    if ('injector$$' in part && part.injector$$ instanceof Injector) {
+      return part.injector$$;
+    }
+  }
+
+  return null;
+}

package/src/lib/injector.test.ts

@@ -0,0 +1,86 @@
+import { expect } from '@open-wc/testing';
+
+import { Injector } from './injector.js';
+import { inject } from './inject.js';
+import { injectable } from './injectable.js';
+
+describe('Injector', () => {
+  it('should create a new instance of a single provider', () => {
+    class A { }
+
+    const app = new Injector();
+
+    expect(app.get(A)).to.be.instanceOf(A);
+    expect(app.get(A)).to.equal(app.get(A));
+  });
+
+  it('should inject providers in the correct order', () => {
+    class A { }
+    class B { }
+
+    @injectable
+    class MyService {
+      a = inject(A);
+      b = inject(B);
+    }
+
+    const app = new Injector();
+    const instance = app.get(MyService);
+
+    expect(instance.a()).to.be.instanceOf(A);
+    expect(instance.b()).to.be.instanceOf(B);
+  });
+
+  it('should create a new instance of a provider that has a full dep tree', () => {
+    class A { }
+
+    @injectable
+    class B {
+      a = inject(A);
+    }
+
+    @injectable
+    class C {
+      b = inject(B);
+    }
+
+    @injectable
+    class D {
+      c = inject(C);
+    }
+
+    @injectable
+    class E {
+      d = inject(D);
+    }
+
+    const app = new Injector();
+    const instance = app.get(E);
+
+    expect(instance.d().c().b().a()).to.be.instanceOf(A);
+  });
+
+  it('should override a provider if explicitly instructed', () => {
+    class A { }
+
+    @injectable
+    class B {
+      a = inject(A);
+    }
+
+    class AltA extends A { }
+    const app = new Injector([{ provide: A, use: AltA }]);
+
+    expect(app.get(B).a()).to.be.instanceOf(AltA);
+  });
+
+  it('should return an existing instance from a parent injector', () => {
+    class A { }
+
+    const parent = new Injector();
+
+    const app = new Injector([], parent);
+
+    expect(parent.get(A)).to.equal(app.get(A));
+  });
+});

package/src/lib/injector.ts

@@ -0,0 +1,105 @@
+import { ProviderToken, Provider } from './provider.js';
+
+// defines available properties that will be on a class instance that can use the inject function
+export type Injectable = object & {
+  injector$$?: Injector;
+  onInject?(): void;
+};
+
+/**
+ * Injectors create and store instances of services.
+ * A service is any constructable class.
+ * When calling Injector.get, the injector will resolve as following.
+ *
+ * 1. Do I have a cached instance locally?
+ * 2. Do I have a local provider definition for the token?
+ * 3. Do I have a parent? Check parent for 1 and 2
+ * 5. All clear, go ahead and construct and cache the requested service
+ *
+ * RootInjector |--> InjectorA |--> InjectorB
+ *                             |--> InjectorC
+ *                             |--> InjectorD |--> InjectorE
+ *
+ * in the above tree, if InjectorE requests a service, it will navigate up to the RootInjector and cache.
+ * If Inject B then requests the same token, it will recieve the same cached instance from RootInjector.
+ */
+export class Injector {
+  // ke track of isntances. One Token can have one instance
+  #instances = new WeakMap<ProviderToken<any>, any>();
+
+  #parent: Injector | undefined = undefined;
+
+  constructor(public providers: Provider<any>[] = [], parent?: Injector) {
+    this.setParent(parent);
+  }
+
+  // resolves and retuns and instance of the requested service
+  get<T extends Injectable>(token: ProviderToken<T>): T {
+    // check for a local instance
+    if (this.#instances.has(token)) {
+      return this.#instances.get(token)!;
+    }
+
+    const provider = this.#findProvider(token);
+
+    // check for a provider definition
+    if (provider) {
+      return this.#createAndCache<T>(provider.use);
+    }
+
+    // check for a parent and attempt to get there
+    if (this.#parent) {
+      return this.#parent.get(token);
+    }
+
+    return this.#createAndCache(token);
+  }
+
+  setParent(parent: Injector | undefined) {
+    this.#parent = parent;
+  }
+
+  clear() {
+    this.#instances = new WeakMap();
+  }
+
+  #createAndCache<T extends Injectable>(token: ProviderToken<T>): T {
+    const instance = new token();
+
+    this.#instances.set(token, instance);
+
+    if (instance.injector$$ instanceof Injector) {
+      /**
+       * set the this injector instance as a parent.
+       * this means that each calling injector will be the parent of what it creates.
+       * this allows the created service to navigate up it's chain to find a root
+       */
+      instance.injector$$.setParent(this);
+
+      /**
+       * the on inject lifecycle hook should be called after the parent is defined.
+       * this ensures that services are initialized when the chain is settled
+       * this is required since the parent is set after the instance is constructed
+       */
+      if (instance.onInject) {
+        instance.onInject();
+      }
+    }
+
+    return instance;
+  }
+
+  #findProvider(token: ProviderToken<any>): Provider<any> | undefined {
+    if (!this.providers) {
+      return undefined;
+    }
+
+    for (let i = 0; i < this.providers.length; i++) {
+      if (this.providers[i].provide === token) {
+        return this.providers[i];
+      }
+    }
+
+    return undefined;
+  }
+}

package/src/lib/provider.ts

@@ -0,0 +1,10 @@
+export type ProviderToken<T> = {
+  providers?: Provider<any>[];
+
+  new(...args: any[]): T;
+};
+
+export interface Provider<T> {
+  provide: ProviderToken<T>;
+  use: ProviderToken<T>;
+}

package/src/lib.ts

@@ -0,0 +1,5 @@
+export { Injector, Injectable } from './lib/injector.js';
+export { Provider, ProviderToken } from './lib/provider.js';
+export { injectable } from './lib/injectable.js';
+export { inject, Injected } from './lib/inject.js';
+export { defineEnvironment, clearEnvironment } from './lib/environment.js';

package/target/lib/environment.d.ts

@@ -1,3 +1,5 @@
 import { Injector } from './injector.js';
+import { Provider } from './provider.js';
 export declare function environment(): Injector;
+export declare function defineEnvironment(providers: Provider<any>[]): void;
 export declare function clearEnvironment(): void;

package/target/lib/environment.js

@@ -3,6 +3,9 @@ const rootInjector = new Injector();
 export function environment() {
     return rootInjector;
 }
+export function defineEnvironment(providers) {
+    environment().providers = providers;
+}
 export function clearEnvironment() {
     rootInjector.providers = [];
     rootInjector.clear();

package/target/lib/environment.js.map

@@ -1 +1 @@
-{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/lib/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,YAAY,GAAG,IAAI,QAAQ,EAAE,CAAC;AAEpC,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,YAAY,CAAC,SAAS,GAAG,EAAE,CAAC;IAC5B,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/lib/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,MAAM,YAAY,GAAG,IAAI,QAAQ,EAAE,CAAC;AAEpC,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAA0B;IAC1D,WAAW,EAAE,CAAC,SAAS,GAAG,SAAS,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,YAAY,CAAC,SAAS,GAAG,EAAE,CAAC;IAC5B,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC"}

package/target/lib.d.ts

@@ -2,3 +2,4 @@ export { Injector, Injectable } from './lib/injector.js';
 export { Provider, ProviderToken } from './lib/provider.js';
 export { injectable } from './lib/injectable.js';
 export { inject, Injected } from './lib/inject.js';
+export { defineEnvironment, clearEnvironment } from './lib/environment.js';

package/target/lib.js

@@ -1,4 +1,5 @@
 export { Injector } from './lib/injector.js';
 export { injectable } from './lib/injectable.js';
 export { inject } from './lib/inject.js';
+export { defineEnvironment, clearEnvironment } from './lib/environment.js';
 //# sourceMappingURL=lib.js.map

package/target/lib.js.map

@@ -1 +1 @@
-{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAc,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAY,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAc,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAY,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}