@joist/di 4.0.0-next.1 → 4.0.0-next.11

package/README.md

@@ -16,10 +16,10 @@ Allows you to inject services into other class instances (including custom eleme
 - [Hierarchical Injectors](#hierarchical-injectors)
 - [Custom Elements](#custom-elements)
 
-## Installation:
+## Installation
 
 ```BASH
-npm i @joist/di
+npm i @joist/di@next
 ```
 
 ## Injectors
@@ -53,7 +53,7 @@ Singleton services are great but the real benefit can be seen when passing insta
 `inject()` returns a function that will then return an instance of the requested service. This means that services are only created when they are needed and not when the class is constructed.
 
 ```ts
-@injectable
+@injectable()
 class App {
   #counter = inject(Counter);
 
@@ -80,7 +80,7 @@ class HttpService {
   }
 }
 
-@injectable
+@injectable()
 class ApiService {
   #http = inject(HttpService);
 
@@ -114,7 +114,7 @@ test('should return json', async () => {
 
 ### Service level providers
 
-Under the hood, each service decorated with `@injectable` creates its own injector. This means that it is possible to defined providers from that level down.
+Under the hood, each service decorated with `@injectable()` creates its own injector. This means that it is possible to defined providers from that level down.
 
 The below example will use this particular instance of Logger as wall as any other services injected into this service.
 
@@ -129,10 +129,10 @@ class ConsoleLogger implements Logger {
   }
 }
 
-@injectable
-class MyService {
-  static providers = [{ provide: Logger, use: ConsoleLogger }];
-}
+@injectable({
+  providers: [{ provide: Logger, use: ConsoleLogger }]
+})
+class MyService {}
 ```
 
 ### Factories
@@ -228,17 +228,43 @@ const app = new Injector();
 const url: string = await app.inject(URL_TOKEN);
 ```
 
+This allows you to dynamically import services
+
+```ts
+const HTTP_SERVICE = new StaticToken('HTTP_SERVICE', () => {
+  return import('./http.service.js').then((m) => new m.HttpService());
+});
+
+class HackerNewsService {
+  #http = inject(HTTP_SERVICE);
+
+  async getData() {
+    const http = await this.#http();
+
+    const url = new URL('https://hacker-news.firebaseio.com/v0/beststories.json');
+    url.searchParams.set('limitToFirst', count.toString());
+    url.searchParams.set('orderBy', '"$key"');
+
+    return http.fetchJson<string[]>(url);
+  }
+}
+
+const url: string = await app.inject(URL_TOKEN);
+```
+
 ## LifeCycle
 
 To help provide more information to services that are being created, joist will call several life cycle hooks as services are created. These hooks are defined using the provided symbols so there is no risk of naming colisions.
 
 ```ts
 class MyService {
-  [LifeCycle.onInit]() {
+  @created()
+  onCreated() {
     // called the first time a service is created. (not pulled from cache)
   }
 
-  [LifeCycle.onInject]() {
+  @injected()
+  onInjected() {
     // called every time a service is returned, whether it is from cache or not
   }
 }
@@ -246,12 +272,16 @@ class MyService {
 
 ## Hierarchical Injectors
 
-Injectors can be defined with a parent element. The top most parent will (by default) be where services are constructed and cached. Only if manually defined providers are found earlier in the chain will services be constructed lower. The injector resolution algorithm behaves as following.
+Injectors can be defined with a parent. The top most parent will (by default) be where services are constructed and cached. Only if manually defined providers are found earlier in the chain will services be constructed lower. The injector resolution algorithm behaves 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
-4. All clear, go ahead and construct and cache the requested service
+3. Do I have a parent?
+4. Does parent have a local instance or provider definition?
+5. If parent exists but no instance found, create instance in parent.
+6. If not parent, All clear, go ahead and construct and cache the requested service.
+
+Having injectors resolve this way means that all children have access to services created by their parents.
 
 ```mermaid
 graph TD
@@ -286,7 +316,7 @@ class Colors {
   secodnary = 'green';
 }
 
-@injectable
+@injectable()
 class MyElement extends HTMLElement {
   #colors = inject(Colors);
 
@@ -314,21 +344,20 @@ class Colors {
   secodnary = 'green';
 }
 
-@injectable
-class ColorCtx extends HTMLElement {
-  // services can be scoped to a particular injectable
-  static providers = [
+@injectable({
+  providers: [
     {
       provide: Colors,
       use: class implements Colors {
         primary = 'orange';
         secondary = 'purple';
-      },
-    },
+      }
+    }
   ]
-}
+})
+class ColorCtx extends HTMLElement {}
 
-@injectable
+@injectable()
 class MyElement extends HTMLElement {
   #colors = inject(Colors);
 
@@ -353,14 +382,3 @@ customElements.define('my-element', MyElement);
   <my-element></my-element>
 </color-ctx>
 ```
-
-### Environment
-
-When using @joist/di with custom elements a default root injector is created dubbed 'environment'. This is the injector that all other injectors will eventually stop at.
-If you need to define something in this environment you can do so with the `defineEnvironment` method.
-
-```ts
-import { defineEnvironment } from '@joist/di';
-
-defineEnvironment([{ provide: MyService, use: SomeOtherService }]);
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/di",
-  "version": "4.0.0-next.1",
+  "version": "4.0.0-next.11",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",
@@ -20,7 +20,7 @@
   "description": "Dependency Injection for Vanilla JS classes",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/deebloo/joist.git"
+    "url": "git+https://github.com/joist-framework/joist.git"
   },
   "keywords": [
     "TypeScript",
@@ -31,7 +31,7 @@
   "author": "deebloo",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/deebloo/joist/issues"
+    "url": "https://github.com/joist-framework/joist/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -57,17 +57,7 @@
     "test": {
       "command": "wtr --config wtr.config.mjs",
       "files": [
-        "target/**"
-      ],
-      "output": [],
-      "dependencies": [
-        "build",
-        "test:node"
-      ]
-    },
-    "test:node": {
-      "command": "node --test target/**/*.test-node.js",
-      "files": [
+        "wtr.config.mjs",
         "target/**"
       ],
       "output": [],

package/src/lib/dom-injector.test.ts

@@ -1,30 +1,28 @@
-import { expect } from '@open-wc/testing';
+import { assert } from 'chai';
 
 import { DOMInjector } from './dom-injector.js';
-import { INJECTABLE_MAP } from './injectable.js';
+import { injectables } from './injector.js';
 
-describe('DOMInjector', () => {
-  it('should attach an injector to a dom element', () => {
-    const root = document.createElement('div');
-    const app = new DOMInjector();
+it('should attach an injector to a dom element', () => {
+  const root = document.createElement('div');
+  const app = new DOMInjector();
 
-    app.attach(root);
+  app.attach(root);
 
-    const injector = INJECTABLE_MAP.get(root);
+  const injector = injectables.get(root);
 
-    expect(injector).to.equal(app);
-  });
+  assert.strictEqual(injector, app);
+});
 
-  it('should remove an injector associated with a dom element', () => {
-    const root = document.createElement('div');
-    const app = new DOMInjector();
+it('should remove an injector associated with a dom element', () => {
+  const root = document.createElement('div');
+  const app = new DOMInjector();
 
-    app.attach(root);
+  app.attach(root);
 
-    expect(INJECTABLE_MAP.get(root)).to.equal(app);
+  assert.strictEqual(injectables.get(root), app);
 
-    app.detach(root);
+  app.detach(root);
 
-    expect(INJECTABLE_MAP.get(root)).to.equal(undefined);
-  });
+  assert.strictEqual(injectables.get(root), undefined);
 });

package/src/lib/dom-injector.ts

@@ -1,12 +1,11 @@
-import { INJECTABLE_MAP } from './injectable.js';
-import { Injector } from './injector.js';
+import { injectables, Injector } from './injector.js';
 
 export class DOMInjector extends Injector {
   attach(root: HTMLElement) {
-    INJECTABLE_MAP.set(root, this);
+    injectables.set(root, this);
   }
 
   detach(root: HTMLElement) {
-    INJECTABLE_MAP.delete(root);
+    injectables.delete(root);
   }
 }

package/src/lib/inject.test.ts

@@ -1,30 +1,17 @@
-import { expect } from '@open-wc/testing';
+import { assert } from 'chai';
 
 import { inject } from './inject.js';
 import { injectable } from './injectable.js';
 import { Injector } from './injector.js';
 import { StaticToken } from './provider.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', () => {
+it('should throw error if called in constructor', () => {
+  assert.throws(() => {
     class FooService {
       value = '1';
     }
 
-    @injectable
+    @injectable()
     class BarService {
       foo = inject(FooService);
 
@@ -35,49 +22,39 @@ describe('inject', () => {
 
     const parent = new Injector();
 
-    try {
-      parent.inject(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 [LifeCycle.onInject] callback method.`
-      );
-    }
-  });
-
-  it('should use the calling injector as parent', () => {
-    class FooService {
-      value = '1';
-    }
-
-    @injectable
-    class BarService {
-      foo = inject(FooService);
-    }
+    parent.inject(BarService);
+  }, 'BarService is either not injectable or a service is being called in the constructor.');
+});
 
-    const parent = new Injector([
-      {
-        provide: FooService,
-        use: class extends FooService {
-          value = '100';
-        }
+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.inject(BarService).foo().value).to.equal('100');
-  });
+  assert.strictEqual(parent.inject(BarService).foo().value, '100');
+});
 
-  it('should inject a static token', () => {
-    const TOKEN = new StaticToken('test', () => 'Hello World');
+it('should inject a static token', () => {
+  const TOKEN = new StaticToken('test', () => 'Hello World');
 
-    @injectable
-    class HelloWorld {
-      hello = inject(TOKEN);
-    }
+  @injectable()
+  class HelloWorld {
+    hello = inject(TOKEN);
+  }
 
-    expect(new HelloWorld().hello()).to.equal('Hello World');
-  });
+  assert.strictEqual(new HelloWorld().hello(), 'Hello World');
 });

package/src/lib/inject.ts

@@ -1,19 +1,17 @@
 import { InjectionToken } from './provider.js';
-import { INJECTABLE_MAP } from './injectable.js';
+import { injectables } from './injector.js';
 
 export type Injected<T> = () => T;
 
-export function inject<This extends object, T>(
-  token: InjectionToken<T>
-): Injected<T> {
+export function inject<This extends object, T>(token: InjectionToken<T>): Injected<T> {
   return function (this: This) {
-    const injector = INJECTABLE_MAP.get(this);
+    const injector = injectables.get(this);
 
     if (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 [LifeCycle.onInject] callback method.`
+        `${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 [LifeCycle.onInject] callback method.`
       );
     }
 

package/src/lib/injectable-el.test.ts

@@ -0,0 +1,130 @@
+import { assert } from 'chai';
+
+import { inject } from './inject.js';
+import { injectable } from './injectable.js';
+
+it('should allow services to be injected into custom element', () => {
+  class Foo {}
+
+  @injectable()
+  class MyElement extends HTMLElement {
+    foo = inject(Foo);
+  }
+
+  customElements.define('injectable-1', MyElement);
+
+  const el = new MyElement();
+
+  assert.instanceOf(el.foo(), Foo);
+});
+
+it('should allow services to be injected into custom elements that has been extended', () => {
+  class Foo {}
+
+  class MyBaseElement extends HTMLElement {}
+
+  @injectable()
+  class MyElement extends MyBaseElement {
+    foo = inject(Foo);
+  }
+
+  customElements.define('injectable-2', MyElement);
+
+  const el = new MyElement();
+
+  assert.instanceOf(el.foo(), Foo);
+});
+
+it('should handle parent HTML Injectors', async () => {
+  @injectable()
+  class A {}
+
+  @injectable()
+  class B {
+    a = inject(A);
+  }
+
+  class AltA implements A {}
+
+  @injectable({
+    providers: [
+      { provide: B, use: B },
+      { provide: A, use: AltA }
+    ]
+  })
+  class Parent extends HTMLElement {}
+
+  @injectable()
+  class Child extends HTMLElement {
+    b = inject(B);
+  }
+
+  customElements.define('injectable-parent-1', Parent);
+  customElements.define('injectable-child-1', Child);
+
+  const el = document.createElement('div');
+  el.innerHTML = /*html*/ `
+    <injectable-parent-1>
+      <injectable-child-1></injectable-child-1>
+    </injectable-parent-1>
+  `;
+
+  document.body.append(el);
+
+  const child = el.querySelector<Child>('injectable-child-1')!;
+
+  assert.instanceOf(child.b().a(), AltA);
+
+  el.remove();
+});
+
+it('should handle changing contexts', async () => {
+  class A {}
+  class AltA implements A {}
+
+  @injectable({
+    providers: [{ provide: A, use: A }]
+  })
+  class Ctx1 extends HTMLElement {}
+
+  @injectable({
+    providers: [{ provide: A, use: AltA }]
+  })
+  class Ctx2 extends HTMLElement {}
+
+  @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 = document.createElement('div');
+  el.innerHTML = /*html*/ `
+    <div>
+      <ctx-1>
+        <ctx-child></ctx-child>
+      </ctx-1>
+
+      <ctx-2></ctx-2>
+    </div>
+  `;
+
+  document.body.append(el);
+
+  const ctx2 = el.querySelector('ctx-2')!;
+
+  let child = el.querySelector<Child>('ctx-child')!;
+
+  assert.instanceOf(child.a(), A);
+
+  child.remove();
+
+  ctx2.append(child);
+
+  child = el.querySelector<Child>('ctx-child')!;
+
+  assert.instanceOf(child.a(), AltA);
+});

package/src/lib/injectable-el.ts

@@ -0,0 +1,63 @@
+import { injectables, Injector } from './injector.js';
+import { ConstructableToken } from './provider.js';
+
+export function injectableEl<T extends ConstructableToken<HTMLElement>>(
+  Base: T,
+  _ctx: ClassDecoratorContext
+) {
+  return class InjectablElement extends Base {
+    constructor(..._: any[]) {
+      super();
+
+      /**
+       * Listen for the finddiroot event.
+       * This is event is triggered when the element is connected to the dom
+       * This event will bubble up until it finds a parent injector which is then attached
+       * This will also work through shadow roots (that are not "closed")
+       */
+      this.addEventListener('finddiroot', (e) => {
+        const parentInjector = findInjectorRoot(e);
+
+        if (parentInjector) {
+          injectables.get(this)?.setParent(parentInjector);
+        }
+      });
+    }
+
+    connectedCallback() {
+      if (this.isConnected) {
+        this.dispatchEvent(new Event('finddiroot', { bubbles: true }));
+
+        if (super.connectedCallback) {
+          super.connectedCallback();
+        }
+      }
+    }
+
+    disconnectedCallback() {
+      injectables.get(this)?.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];
+
+    const injector = injectables.get(part);
+
+    if (injector) {
+      return injector;
+    }
+  }
+
+  return null;
+}