Merge pull request #321 from inversify/feat/update-next-container-api…

…-docs

Update next container api docs

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGet.int.spec.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { Katana, katana } from './containerApiGet';
+
+describe('Container API (get)', () => {
+  it('should provide Katana weapon', () => {
+    expect(katana).toBeInstanceOf(Katana);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGet.ts

@@ -0,0 +1,19 @@
+import { Container, injectable } from 'inversify7';
+
+interface Weapon {
+  damage: number;
+}
+
+@injectable()
+export class Katana implements Weapon {
+  public readonly damage: number = 10;
+}
+
+// Begin-example
+const container: Container = new Container();
+container.bind<Weapon>('Weapon').to(Katana);
+
+const katana: Weapon = container.get<Weapon>('Weapon');
+// End-example
+
+export { katana };

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGetAll.int.spec.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { Katana, Shuriken, weapons } from './containerApiGetAll';
+
+describe('Container API (getAll)', () => {
+  it('should provide weapons', () => {
+    expect(weapons).toStrictEqual([new Katana(), new Shuriken()]);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGetAll.ts

@@ -0,0 +1,25 @@
+import { Container, injectable } from 'inversify7';
+
+interface Weapon {
+  damage: number;
+}
+
+@injectable()
+export class Katana implements Weapon {
+  public readonly damage: number = 10;
+}
+
+@injectable()
+export class Shuriken implements Weapon {
+  public readonly damage: number = 5;
+}
+
+// Begin-example
+const container: Container = new Container();
+container.bind<Weapon>('Weapon').to(Katana);
+container.bind<Weapon>('Weapon').to(Shuriken);
+
+const weapons: Weapon[] = container.getAll<Weapon>('Weapon'); // returns Weapon[]
+// End-example
+
+export { weapons };

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGetAllAsync.int.spec.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { Katana, Shuriken, weapons } from './containerApiGetAllAsync';
+
+describe('Container API (getAllAsync)', () => {
+  it('should provide weapons', async () => {
+    expect(await weapons).toStrictEqual([new Katana(), new Shuriken()]);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGetAllAsync.ts

@@ -0,0 +1,25 @@
+import { Container, injectable } from 'inversify7';
+
+interface Weapon {
+  damage: number;
+}
+
+@injectable()
+export class Katana implements Weapon {
+  public readonly damage: number = 10;
+}
+
+@injectable()
+export class Shuriken implements Weapon {
+  public readonly damage: number = 5;
+}
+
+// Begin-example
+const container: Container = new Container();
+container.bind<Weapon>('Weapon').toDynamicValue(async () => new Katana());
+container.bind<Weapon>('Weapon').to(Shuriken);
+
+const weapons: Promise<Weapon[]> = container.getAllAsync<Weapon>('Weapon'); // returns Weapon[]
+// End-example
+
+export { weapons };

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGetAsync.int.spec.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { Level1, level1 } from './containerApiGetAsync';
+
+describe('Container API (getAsync)', () => {
+  it('should provide async service', async () => {
+    expect(await level1).toBeInstanceOf(Level1);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiGetAsync.ts

@@ -0,0 +1,19 @@
+import { Container, injectable } from 'inversify7';
+
+@injectable()
+export class Level1 {}
+
+// Begin-example
+async function buildLevel1(): Promise<Level1> {
+  return new Level1();
+}
+
+const container: Container = new Container();
+container
+  .bind('Level1')
+  .toDynamicValue(async (): Promise<Level1> => buildLevel1());
+
+const level1: Promise<Level1> = container.getAsync<Level1>('Level1'); // Returns Promise<Level1>
+// End-example
+
+export { level1 };

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiIsBound.int.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  isKatanaBound,
+  isKatanaSymbolBound,
+  isNinjaBound,
+  isWarriorSymbolBound,
+} from './containerApiIsBound';
+
+describe('Container API (isBound)', () => {
+  it('should detect bound and not bound services', async () => {
+    expect(isKatanaBound).toBe(false);
+    expect(isKatanaSymbolBound).toBe(false);
+    expect(isNinjaBound).toBe(true);
+    expect(isWarriorSymbolBound).toBe(true);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiIsBound.ts

@@ -0,0 +1,39 @@
+import { Container, injectable } from 'inversify7';
+
+// Begin-example
+interface Warrior {
+  kind: string;
+}
+
+const katanaSymbol: symbol = Symbol.for('Katana');
+const warriorSymbol: symbol = Symbol.for('Warrior');
+
+@injectable()
+class Ninja implements Warrior {
+  public readonly kind: string = 'ninja';
+}
+
+@injectable()
+class Katana {}
+
+const container: Container = new Container();
+container.bind<Warrior>(Ninja).to(Ninja);
+container.bind<Warrior>(warriorSymbol).to(Ninja);
+
+// returns true
+const isNinjaBound: boolean = container.isBound(Ninja);
+// returns true
+const isWarriorSymbolBound: boolean = container.isBound(warriorSymbol);
+// returns false
+const isKatanaBound: boolean = container.isBound(Katana);
+// returns false
+const isKatanaSymbolBound: boolean = container.isBound(katanaSymbol);
+
+// End-example
+
+export {
+  isKatanaBound,
+  isKatanaSymbolBound,
+  isNinjaBound,
+  isWarriorSymbolBound,
+};

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiIsCurrentBound.int.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  isKatanaBound,
+  isKatanaSymbolBound,
+  isNinjaBound,
+  isWarriorSymbolBound,
+} from './containerApiIsCurrentBound';
+
+describe('Container API (isCurrentBound)', () => {
+  it('should detect bound and not bound services', async () => {
+    expect(isKatanaBound).toBe(true);
+    expect(isKatanaSymbolBound).toBe(true);
+    expect(isNinjaBound).toBe(false);
+    expect(isWarriorSymbolBound).toBe(false);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiIsCurrentBound.ts

@@ -0,0 +1,46 @@
+import { Container, injectable } from 'inversify7';
+
+// Begin-example
+interface Warrior {
+  kind: string;
+}
+
+const katanaSymbol: symbol = Symbol.for('Katana');
+const warriorSymbol: symbol = Symbol.for('Warrior');
+
+@injectable()
+class Ninja implements Warrior {
+  public readonly kind: string = 'ninja';
+}
+
+@injectable()
+class Katana {}
+
+const container: Container = new Container();
+container.bind<Warrior>(Ninja).to(Ninja);
+container.bind<Warrior>(warriorSymbol).to(Ninja);
+
+const containerChild: Container = new Container({ parent: container });
+
+containerChild.bind<Katana>(Katana).to(Katana);
+containerChild.bind<Katana>(katanaSymbol).to(Katana);
+
+// returns false
+const isNinjaBound: boolean = containerChild.isCurrentBound(Ninja);
+// returns false
+const isWarriorSymbolBound: boolean =
+  containerChild.isCurrentBound(warriorSymbol);
+// returns true
+const isKatanaBound: boolean = containerChild.isCurrentBound(Katana);
+// returns true
+const isKatanaSymbolBound: boolean =
+  containerChild.isCurrentBound(katanaSymbol);
+
+// End-example
+
+export {
+  isKatanaBound,
+  isKatanaSymbolBound,
+  isNinjaBound,
+  isWarriorSymbolBound,
+};

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiOnActivation.int.spec.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { katana } from './containerApiOnActivation';
+
+describe('Container API (onActivation)', () => {
+  it('should provide activated service', () => {
+    expect(katana.damage).toBe(12);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiOnActivation.ts

@@ -0,0 +1,36 @@
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+import { Container, ResolutionContext } from 'inversify7';
+
+// Begin-example
+interface Weapon {
+  damage: number;
+}
+
+export class Katana implements Weapon {
+  #damage: number = 10;
+
+  public get damage(): number {
+    return this.#damage;
+  }
+
+  public improve(): void {
+    this.#damage += 2;
+  }
+}
+
+const container: Container = new Container();
+container.bind<Weapon>('Weapon').to(Katana);
+container.onActivation(
+  'Weapon',
+  (_context: ResolutionContext, katana: Katana): Katana | Promise<Katana> => {
+    katana.improve();
+
+    return katana;
+  },
+);
+
+// Katana.damage is 12
+const katana: Weapon = container.get<Weapon>('Weapon');
+// End-example
+
+export { katana };

packages/docs/tools/inversify-code-examples/src/examples/v7/containerApiOnDeactivation.ts

@@ -0,0 +1,29 @@
+import { Container } from 'inversify7';
+
+void (async () => {
+  // Begin-example
+  interface Weapon {
+    damage: number;
+  }
+
+  class Katana implements Weapon {
+    readonly #damage: number = 10;
+
+    public get damage(): number {
+      return this.#damage;
+    }
+  }
+
+  const container: Container = new Container();
+
+  container.bind<Weapon>('Weapon').to(Katana).inSingletonScope();
+
+  container.get('Weapon');
+
+  container.onDeactivation('Weapon', (weapon: Weapon): void | Promise<void> => {
+    console.log(`Deactivating weapon with damage ${weapon.damage.toString()}`);
+  });
+
+  await container.unbind('Weapon');
+  // End-example
+})();