Merge pull request #219 from inversify/docs/add-container-api-page

Add container api examples

packages/docs/tools/inversify-code-examples/src/examples/containerApiGet.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/containerApiGet.ts

@@ -0,0 +1,18 @@
+import { Container } from 'inversify';
+
+interface Weapon {
+  damage: number;
+}
+
+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/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/containerApiGetAsync.ts

@@ -0,0 +1,18 @@
+import { Container } from 'inversify';
+
+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/containerApiGetNamed.int.spec.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { Katana, katana, Shuriken, shuriken } from './containerApiGetNamed';
+
+describe('Container API (getNamed)', () => {
+  it('should provide Katana weapon', () => {
+    expect(katana).toBeInstanceOf(Katana);
+    expect(shuriken).toBeInstanceOf(Shuriken);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/containerApiGetNamed.ts

@@ -0,0 +1,24 @@
+import { Container } from 'inversify';
+
+interface Weapon {
+  readonly damage: number;
+}
+
+export class Katana implements Weapon {
+  public readonly damage: number = 10;
+}
+
+export class Shuriken implements Weapon {
+  public readonly damage: number = 5;
+}
+
+// Begin-example
+const container: Container = new Container();
+container.bind<Weapon>('Weapon').to(Katana).whenTargetNamed('japanese');
+container.bind<Weapon>('Weapon').to(Shuriken).whenTargetNamed('chinese');
+
+const katana: Weapon = container.getNamed<Weapon>('Weapon', 'japanese');
+const shuriken: Weapon = container.getNamed<Weapon>('Weapon', 'chinese');
+// End-example
+
+export { katana, shuriken };

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

@@ -0,0 +1,15 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  Katana,
+  katana,
+  Shuriken,
+  shuriken,
+} from './containerApiGetNamedAsync';
+
+describe('Container API (getNamed)', () => {
+  it('should provide Katana weapon', async () => {
+    expect(await katana).toBeInstanceOf(Katana);
+    expect(await shuriken).toBeInstanceOf(Shuriken);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/containerApiGetNamedAsync.ts

@@ -0,0 +1,36 @@
+import { Container } from 'inversify';
+
+interface Weapon {
+  damage: number;
+}
+
+export class Katana implements Weapon {
+  public readonly damage: number = 10;
+}
+
+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())
+  .whenTargetNamed('melee');
+container
+  .bind<Weapon>('Weapon')
+  .toDynamicValue(async () => new Shuriken())
+  .whenTargetNamed('ranged');
+
+const katana: Promise<Weapon> = container.getNamedAsync<Weapon>(
+  'Weapon',
+  'melee',
+);
+const shuriken: Promise<Weapon> = container.getNamedAsync<Weapon>(
+  'Weapon',
+  'ranged',
+);
+// End-example
+
+export { katana, shuriken };

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

@@ -0,0 +1,10 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { Katana, katana, Shuriken, shuriken } from './containerApiGetTagged';
+
+describe('Container API (getTagged)', () => {
+  it('should provide weapon services', () => {
+    expect(katana).toBeInstanceOf(Katana);
+    expect(shuriken).toBeInstanceOf(Shuriken);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/containerApiGetTagged.ts

@@ -0,0 +1,38 @@
+import { Container } from 'inversify';
+
+interface Weapon {
+  readonly damage: number;
+}
+
+export class Katana implements Weapon {
+  public readonly damage: number = 10;
+}
+
+export class Shuriken implements Weapon {
+  public readonly damage: number = 5;
+}
+
+// Begin-example
+const container: Container = new Container();
+container
+  .bind<Weapon>('Weapon')
+  .to(Katana)
+  .whenTargetTagged('faction', 'samurai');
+container
+  .bind<Weapon>('Weapon')
+  .to(Shuriken)
+  .whenTargetTagged('faction', 'ninja');
+
+const katana: Weapon = container.getTagged<Weapon>(
+  'Weapon',
+  'faction',
+  'samurai',
+);
+const shuriken: Weapon = container.getTagged<Weapon>(
+  'Weapon',
+  'faction',
+  'ninja',
+);
+// End-example
+
+export { katana, shuriken };

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

@@ -0,0 +1,15 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  Katana,
+  katana,
+  Shuriken,
+  shuriken,
+} from './containerApiGetTaggedAsync';
+
+describe('Container API (getTagged)', () => {
+  it('should provide weapon services', async () => {
+    expect(await katana).toBeInstanceOf(Katana);
+    expect(await shuriken).toBeInstanceOf(Shuriken);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/containerApiGetTaggedAsync.ts

@@ -0,0 +1,38 @@
+import { Container } from 'inversify';
+
+interface Weapon {
+  readonly damage: number;
+}
+
+export class Katana implements Weapon {
+  public readonly damage: number = 10;
+}
+
+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())
+  .whenTargetTagged('faction', 'samurai');
+container
+  .bind<Weapon>('Weapon')
+  .toDynamicValue(async () => new Shuriken())
+  .whenTargetTagged('faction', 'ninja');
+
+const katana: Promise<Weapon> = container.getTaggedAsync<Weapon>(
+  'Weapon',
+  'faction',
+  'samurai',
+);
+const shuriken: Promise<Weapon> = container.getTaggedAsync<Weapon>(
+  'Weapon',
+  'faction',
+  'ninja',
+);
+// End-example
+
+export { katana, shuriken };

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  gameContainer,
+  Katana,
+  Ninja,
+  NINJA_EXPANSION_TYPES,
+  Samurai,
+  SAMURAI_EXPANSION_TYPES,
+  Shuriken,
+} from './containerApiMerge';
+
+describe('Container API (merge)', () => {
+  it('should provide expected services', () => {
+    expect(
+      gameContainer.get<Ninja>(NINJA_EXPANSION_TYPES.Ninja),
+    ).toBeInstanceOf(Ninja);
+    expect(
+      gameContainer.get<Shuriken>(NINJA_EXPANSION_TYPES.Shuriken),
+    ).toBeInstanceOf(Shuriken);
+    expect(
+      gameContainer.get<Samurai>(SAMURAI_EXPANSION_TYPES.Samurai),
+    ).toBeInstanceOf(Samurai);
+    expect(
+      gameContainer.get<Katana>(SAMURAI_EXPANSION_TYPES.Katana),
+    ).toBeInstanceOf(Katana);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/containerApiMerge.ts

@@ -0,0 +1,65 @@
+/* eslint-disable @typescript-eslint/typedef */
+import { Container, injectable, interfaces } from 'inversify';
+
+// Begin-example
+@injectable()
+class Ninja {
+  public readonly name: string = 'Ninja';
+}
+
+@injectable()
+class Shuriken {
+  public readonly name: string = 'Shuriken';
+}
+
+const NINJA_EXPANSION_TYPES = {
+  Ninja: 'Ninja',
+  Shuriken: 'Shuriken',
+} satisfies Record<string, string>;
+
+const ninjaExpansionContainer: Container = new Container();
+
+ninjaExpansionContainer.bind<Ninja>(NINJA_EXPANSION_TYPES.Ninja).to(Ninja);
+ninjaExpansionContainer
+  .bind<Shuriken>(NINJA_EXPANSION_TYPES.Shuriken)
+  .to(Shuriken);
+
+@injectable()
+class Samurai {
+  public readonly name: string = 'Samurai';
+}
+
+@injectable()
+class Katana {
+  public name = 'Katana';
+}
+
+const SAMURAI_EXPANSION_TYPES = {
+  Katana: 'Katana',
+  Samurai: 'Samurai',
+} satisfies Record<string, string>;
+
+const samuraiExpansionContainer: Container = new Container();
+samuraiExpansionContainer
+  .bind<Samurai>(SAMURAI_EXPANSION_TYPES.Samurai)
+  .to(Samurai);
+samuraiExpansionContainer
+  .bind<Katana>(SAMURAI_EXPANSION_TYPES.Katana)
+  .to(Katana);
+
+const gameContainer: interfaces.Container = Container.merge(
+  ninjaExpansionContainer,
+  samuraiExpansionContainer,
+);
+
+// End-example
+
+export {
+  gameContainer,
+  Katana,
+  Ninja,
+  NINJA_EXPANSION_TYPES,
+  Samurai,
+  SAMURAI_EXPANSION_TYPES,
+  Shuriken,
+};

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

@@ -0,0 +1,13 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  isBoundAfterGet,
+  isBoundBeforeGet,
+} from './containerApiOptionsAutoBindInjectable';
+
+describe('Container API options (autoBindInjectable)', () => {
+  it('should auto bind ninja', () => {
+    expect(isBoundAfterGet).toBe(true);
+    expect(isBoundBeforeGet).toBe(false);
+  });
+});

packages/docs/tools/inversify-code-examples/src/examples/containerApiOptionsAutoBindInjectable.ts

@@ -0,0 +1,19 @@
+import { Container } from 'inversify';
+
+class Ninja {}
+
+// Begin-example
+const container: Container = new Container({ autoBindInjectable: true });
+
+// Exclude-from-example
+export const isBoundBeforeGet: boolean = container.isBound(Ninja);
+
+// returns false
+container.isBound(Ninja);
+// returns a Ninja
+container.get(Ninja);
+// returns true
+container.isBound(Ninja);
+// End-example
+
+export const isBoundAfterGet: boolean = container.isBound(Ninja);

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

@@ -0,0 +1,13 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  container,
+  Ninja,
+  NinjaMaster,
+} from './containerApiOptionsAutoBindInjectablePrecedence';
+
+describe('Container API options (autoBindInjectable, precedence)', () => {
+  it('should provide ninja according to manual binding', () => {
+    expect(container.get(Ninja)).toBeInstanceOf(NinjaMaster);
+  });
+});