feat: precedence config option

closes #81

CHANGELOG.md

@@ -10,6 +10,7 @@ Change Log
 - you can now pass an `opts` parameter when resolving i.e. `.resolve<A>({ optional: true })`
 - `resolveWith` now has a nicer syntax for ts inference: `.resolveWith<Foo, Dep1, Dep2>([ 'val1', 'val2' ])`. The original syntax i.e. `.resolveWith({ dep1: 'val1' })` is still valid.
 - removed the built-in dependency `$options`. You can no longer do `.resolve({ foo: 'someValue' })`
+- `precedence` option lets you determine if a factory should overwrite an existing factory or not
 
 #### Breaking Changes
 - if you attempt to resolve a global like `Window` without registering it first, rather than throw an error, you will now get the global variable

src/Jpex.ts

@@ -37,6 +37,7 @@ class Jpex implements IJpex {
     this.$$parent = parent;
     this.$$config = {
       lifecycle: (inherit ? parent?.$$config.lifecycle : void 0) ?? 'class',
+      precedence: 'active',
       globals: true,
       nodeModules: true,
       optional: false,

src/__tests__/precedence.test.ts

@@ -0,0 +1,100 @@
+import anyTest, { TestInterface } from 'ava';
+import { jpex as base, JpexInstance } from '..';
+
+const test: TestInterface<{
+  jpex: JpexInstance,
+  jpex2: JpexInstance,
+}> = anyTest;
+
+test.beforeEach((t) => {
+  const jpex = base.extend();
+  const jpex2 = jpex.extend();
+
+  t.context = {
+    jpex,
+    jpex2,
+  };
+});
+
+test('active overwrites an existing factory', (t) => {
+  const { jpex } = t.context;
+
+  type A = string;
+  jpex.factory<A>(() => 'a');
+  jpex.factory<A>(() => 'A', { precedence: 'active' });
+
+  const result = jpex.resolve<A>();
+
+  t.is(result, 'A');
+});
+
+test('active overwrites an inherited factory', (t) => {
+  const { jpex, jpex2 } = t.context;
+
+  type A = string;
+  jpex.factory<A>(() => 'a');
+  jpex2.factory<A>(() => 'A', { precedence: 'active' });
+
+  const result = jpex2.resolve<A>();
+
+  t.is(result, 'A');
+});
+
+test('defaults to active', (t) => {
+  const { jpex } = t.context;
+
+  type A = string;
+  jpex.factory<A>(() => 'a');
+  jpex.factory<A>(() => 'A');
+
+  const result = jpex.resolve<A>();
+
+  t.is(result, 'A');
+});
+
+test('passive is ignored over an existing factory', (t) => {
+  const { jpex } = t.context;
+
+  type A = string;
+  jpex.factory<A>(() => 'a');
+  jpex.factory<A>(() => 'A', { precedence: 'passive' });
+
+  const result = jpex.resolve<A>();
+
+  t.is(result, 'a');
+});
+
+test('passive is ignored over an inherited factory', (t) => {
+  const { jpex, jpex2 } = t.context;
+
+  type A = string;
+  jpex.factory<A>(() => 'a');
+  jpex2.factory<A>(() => 'A', { precedence: 'passive' });
+
+  const result = jpex2.resolve<A>();
+
+  t.is(result, 'a');
+});
+
+test('passive is used if it does not exist', (t) => {
+  const { jpex2 } = t.context;
+
+  type A = string;
+  jpex2.factory<A>(() => 'A', { precedence: 'passive' });
+
+  const result = jpex2.resolve<A>();
+
+  t.is(result, 'A');
+});
+
+test('inherits passive from config', (t) => {
+  const { jpex: base } = t.context;
+  const jpex = base.extend({ precedence: 'passive' });
+  type A = string;
+  jpex.factory<A>(() => 'a');
+  jpex.factory<A>(() => 'A');
+
+  const result = jpex.resolve<A>();
+
+  t.is(result, 'a');
+});

src/index.ts

@@ -6,6 +6,7 @@ import type {
   NamedParameters,
   Resolve,
   Lifecycle,
+  Precedence,
 } from './types';
 
 const jpex = new Jpex() as JpexInstance;
@@ -22,6 +23,7 @@ export type {
   SetupConfig,
   NamedParameters,
   Resolve,
+  Precedence,
 };
 
 export default jpex;

src/registers/factory.ts

@@ -21,6 +21,12 @@ function factory <T>(
     dependencies = null;
   }
 
+  const precedence = opts?.precedence ?? jpex.$$config.precedence;
+
+  if (precedence === 'passive' && jpex.$$factories[name]) {
+    return;
+  }
+
   const f: Factory = {
     fn,
     dependencies,

src/types/JpexInstance.ts

@@ -3,13 +3,23 @@ import {
   AnyFunction,
   Dependency,
   AnyConstructor,
-  SetupConfig,
   Factory,
+  Precedence,
 } from './';
 import { NamedParameters } from './BuiltIns';
 
+export interface SetupConfig {
+  inherit?: boolean,
+  lifecycle?: Lifecycle,
+  precedence?: Precedence,
+  optional?: boolean,
+  nodeModules?: boolean,
+  globals?: boolean,
+}
+
 export interface FactoryOpts {
   lifecycle?: Lifecycle,
+  precedence?: Precedence,
 }
 export interface ServiceOpts extends FactoryOpts {
   bindToInstance?: boolean,
@@ -72,6 +82,7 @@ export interface JpexInstance {
   },
   $$config: {
     lifecycle: Lifecycle,
+    precedence: Precedence,
     optional: boolean,
     nodeModules: boolean,
     globals: boolean,

src/types/index.ts

@@ -3,19 +3,13 @@ export * from './BuiltIns';
 
 export type Lifecycle = 'application' | 'class' | 'instance' | 'none';
 
+export type Precedence = 'active' | 'passive';
+
 export type AnyFunction<R = any> = (...args: any[]) => R;
 export interface AnyConstructor<T = any> {
   new (...args: any[]): T
 }
 
-export interface SetupConfig {
-  inherit?: boolean,
-  lifecycle?: Lifecycle,
-  optional?: boolean,
-  nodeModules?: boolean,
-  globals?: boolean,
-}
-
 export type Dependency = string;
 
 export interface Definition {