feat: Adds the upsert function.

Author: ryasmi

docs/facade.md

@@ -10,6 +10,7 @@ The facade contains common functions for storage and retrieval of entities from
 - [patchEntity](#patchentity)
 - [removeEntities](#removeentities)
 - [removeEntity](#removeentity)
+- [upsertEntity](#upsertentity)
 
 The facade in this package is a TypeScript interface, but concrete implementations of the interface include:
 
@@ -86,3 +87,11 @@ await facade.removeEntity({
   id: { id: 'example_id' },
 });
 ```
+
+### upsertEntity
+```ts
+await facade.upsertEntity({
+  id: { id: 'example_id' },
+  entity: { id: 'example_id', foo: 'bar' },
+});
+```

src/Facade.ts

@@ -6,6 +6,7 @@ import OverwriteEntity from './signatures/OverwriteEntity';
 import PatchEntity from './signatures/PatchEntity';
 import RemoveEntities from './signatures/RemoveEntities';
 import RemoveEntity from './signatures/RemoveEntity';
+import UpsertEntity from './signatures/UpsertEntity';
 
 export default interface Facade<Id, Entity> {
   readonly getEntity: GetEntity<Id, Entity>;
@@ -16,4 +17,5 @@ export default interface Facade<Id, Entity> {
   readonly getEntities: GetEntities<Entity>;
   readonly countEntities: CountEntities<Entity>;
   readonly removeEntities: RemoveEntities<Entity>;
+  readonly upsertEntity: UpsertEntity<Id, Entity>;
 }

src/signatures/UpsertEntity.ts

@@ -0,0 +1,12 @@
+export interface Opts<Id, Entity> {
+  readonly id: Id;
+  readonly entity: Entity;
+}
+
+export interface Result<Entity> {
+  readonly entity: Entity;
+}
+
+export type Signature<Id, Entity> = (opts: Opts<Id, Entity>) => Promise<Result<Entity>>;
+
+export default Signature;

src/signatures/index.ts

@@ -6,6 +6,7 @@ import OverwriteEntity from './OverwriteEntity';
 import PatchEntity from './PatchEntity';
 import RemoveEntities from './RemoveEntities';
 import RemoveEntity from './RemoveEntity';
+import UpsertEntity from './UpsertEntity';
 
 export type CountEntitiesSignature<Entity> = CountEntities<Entity>;
 export type CreateEntitySignature<Entity> = CreateEntity<Entity>;
@@ -15,3 +16,4 @@ export type OverwriteEntitySignature<Id, Entity> = OverwriteEntity<Id, Entity>;
 export type PatchEntitySignature<Id, Entity> = PatchEntity<Id, Entity>;
 export type RemoveEntitiesSignature<Entity> = RemoveEntities<Entity>;
 export type RemoveEntitySignature<Id> = RemoveEntity<Id>;
+export type UpsertEntitySignature<Id, Entity> = UpsertEntity<Id, Entity>;

src/tests/index.ts

@@ -8,6 +8,7 @@ import overwriteEntityTest from './overwriteEntity/test';
 import patchEntityTest from './patchEntity/test';
 import removeEntitiesTest from './removeEntities/test';
 import removeEntityTest from './removeEntity/test';
+import upsertEntityTest from './upsertEntity/test';
 import { TestEntity, TestId } from './utils/testEntity';
 
 export const facadeTest = (facade: Facade<TestId, TestEntity>) => {
@@ -24,5 +25,6 @@ export const facadeTest = (facade: Facade<TestId, TestEntity>) => {
     countEntitiesTest(facade);
     getEntitiesTest(facade);
     removeEntitiesTest(facade);
+    upsertEntityTest(facade);
   });
 };

src/tests/upsertEntity/test.ts

@@ -0,0 +1,29 @@
+import 'mocha'; // tslint:disable-line:no-import-side-effect
+import * as assert from 'power-assert';
+import Facade from '../../Facade';
+import { TestEntity, testEntity, testId, TestId } from '../utils/testEntity';
+
+export default (facade: Facade<TestId, TestEntity>) => {
+  describe('upsertEntity', () => {
+    it('should create when identifier does not exist', async () => {
+      const createdEntity = await facade.upsertEntity({ id: testId, entity: testEntity });
+      const retrievedEntity = await facade.getEntity({ id: testId });
+      assert.deepEqual(createdEntity, testEntity);
+      assert.deepEqual(retrievedEntity, testEntity);
+    });
+
+    it('should overwrite when identifier does exist', async () => {
+      const testOverwrite: TestEntity = {
+        ...testId,
+        booleanProp: false,
+        numberProp: 2,
+        stringProp: 'test_string_prop_overwrite',
+      };
+      await facade.createEntity({ entity: testEntity });
+      const overwrittenEntity = await facade.upsertEntity({ id: testId, entity: testOverwrite });
+      const retrievedEntity = await facade.getEntity({ id: testId });
+      assert.deepEqual(overwrittenEntity, testOverwrite);
+      assert.deepEqual(retrievedEntity, testOverwrite);
+    });
+  });
+};