fix(createEntity): Adds id option for conflict errors.

BREAKING CHANGE: createEntity requires id option.

Author: ryasmi

docs/functions.md

@@ -24,10 +24,11 @@ const { count } = await facade.countEntities({
 This package contains the [count entities tests](../src/tests/countEntities) and the [count entities signature](../src/signatures/CountEntities.ts) for this function.
 
 ### createEntity
-Creates a new entity using the `entity` option.
+Creates a new entity using the `entity` option if no entity exists that matches the `id` option.
 
 ```ts
 const { entity } = await facade.createEntity({
+  id: { id: 'example_id' },
   entity: { id: 'example_id', foo: 'bar' },
 });
 ```

src/Facade.ts

@@ -10,7 +10,7 @@ import UpsertEntity from './signatures/UpsertEntity';
 
 export default interface Facade<Id, Entity> {
   readonly getEntity: GetEntity<Id, Entity>;
-  readonly createEntity: CreateEntity<Entity>;
+  readonly createEntity: CreateEntity<Id, Entity>;
   readonly overwriteEntity: OverwriteEntity<Id, Entity>;
   readonly patchEntity: PatchEntity<Id, Entity>;
   readonly removeEntity: RemoveEntity<Id>;

src/signatures/CreateEntity.ts

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

src/signatures/index.ts

@@ -9,7 +9,7 @@ import RemoveEntity from './RemoveEntity';
 import UpsertEntity from './UpsertEntity';
 
 export type CountEntitiesSignature<Entity> = CountEntities<Entity>;
-export type CreateEntitySignature<Entity> = CreateEntity<Entity>;
+export type CreateEntitySignature<Id, Entity> = CreateEntity<Id, Entity>;
 export type GetEntitiesSignature<Entity> = GetEntities<Entity>;
 export type GetEntitySignature<Id, Entity> = GetEntity<Id, Entity>;
 export type OverwriteEntitySignature<Id, Entity> = OverwriteEntity<Id, Entity>;

src/tests/createEntity/test.ts

@@ -2,17 +2,17 @@ import * as assertRejects from 'assert-rejects';
 import 'mocha'; // tslint:disable-line:no-import-side-effect
 import ConflictingEntityError from '../../errors/ConflictingEntityError';
 import Facade from '../../Facade';
-import { TestEntity, testEntity, TestId } from '../utils/testEntity';
+import { TestEntity, testEntity, testId, TestId } from '../utils/testEntity';
 
 export default (facade: Facade<TestId, TestEntity>) => {
   describe('createEntity', () => {
     it('should not error when identifier does not exist', async () => {
-      await facade.createEntity({ entity: testEntity });
+      await facade.createEntity({ id: testId, entity: testEntity });
     });
 
     it('should error when identifier does exist', async () => {
-      await facade.createEntity({ entity: testEntity });
-      const promise = facade.createEntity({ entity: testEntity });
+      await facade.createEntity({ id: testId, entity: testEntity });
+      const promise = facade.createEntity({ id: testId, entity: testEntity });
       await assertRejects(promise, ConflictingEntityError);
     });
   });

src/tests/getEntities/paginationTest.ts

@@ -5,7 +5,7 @@ import Cursor from '../../types/Cursor';
 import Filter from '../../types/Filter';
 import Pagination from '../../types/Pagination';
 import Sort from '../../types/Sort';
-import { TestEntity, testEntity, TestId } from '../utils/testEntity';
+import { TestEntity, testEntity, testId, TestId } from '../utils/testEntity';
 
 export default (facade: Facade<TestId, TestEntity>) => {
   const firstEntity = { ...testEntity, id: 'first_entity_id' };
@@ -14,8 +14,8 @@ export default (facade: Facade<TestId, TestEntity>) => {
   const filter: Filter<TestEntity> = {};
 
   const createTestEntities = async () => {
-    await facade.createEntity({ entity: firstEntity });
-    await facade.createEntity({ entity: secondEntity });
+    await facade.createEntity({ id: testId, entity: firstEntity });
+    await facade.createEntity({ id: testId, entity: secondEntity });
   };
 
   const paginate = (cursor: Cursor, forward: boolean) => {

src/tests/getEntities/sortTest.ts

@@ -4,7 +4,7 @@ import Facade from '../../Facade';
 import Filter from '../../types/Filter';
 import Pagination from '../../types/Pagination';
 import Sort from '../../types/Sort';
-import { TestEntity, testEntity, TestId } from '../utils/testEntity';
+import { TestEntity, testEntity, TestId, testId } from '../utils/testEntity';
 
 export default (facade: Facade<TestId, TestEntity>) => {
   const firstEntity = { ...testEntity, stringProp: 'a', numberProp: 1 };
@@ -21,38 +21,38 @@ export default (facade: Facade<TestId, TestEntity>) => {
   };
 
   it('should sort by one ascending property when entities are ordered', async () => {
-    await facade.createEntity({ entity: firstEntity });
-    await facade.createEntity({ entity: secondEntity });
+    await facade.createEntity({ id: testId, entity: firstEntity });
+    await facade.createEntity({ id: testId, entity: secondEntity });
     await assertSort([firstEntity, secondEntity], { stringProp: true });
   });
 
   it('should sort by one ascending property when entities are unordered', async () => {
-    await facade.createEntity({ entity: secondEntity });
-    await facade.createEntity({ entity: firstEntity });
+    await facade.createEntity({ id: testId, entity: secondEntity });
+    await facade.createEntity({ id: testId, entity: firstEntity });
     await assertSort([firstEntity, secondEntity], { stringProp: true });
   });
 
   it('should sort by one descending property when entities are ordered', async () => {
-    await facade.createEntity({ entity: secondEntity });
-    await facade.createEntity({ entity: firstEntity });
+    await facade.createEntity({ id: testId, entity: secondEntity });
+    await facade.createEntity({ id: testId, entity: firstEntity });
     await assertSort([secondEntity, firstEntity], { stringProp: false });
   });
 
   it('should sort by one descending property when entities are unordered', async () => {
-    await facade.createEntity({ entity: firstEntity });
-    await facade.createEntity({ entity: secondEntity });
+    await facade.createEntity({ id: testId, entity: firstEntity });
+    await facade.createEntity({ id: testId, entity: secondEntity });
     await assertSort([secondEntity, firstEntity], { stringProp: false });
   });
 
   it('should sort by two properties when ascending first and descending second', async () => {
-    await facade.createEntity({ entity: firstEntity });
-    await facade.createEntity({ entity: secondEntity });
+    await facade.createEntity({ id: testId, entity: firstEntity });
+    await facade.createEntity({ id: testId, entity: secondEntity });
     await assertSort([secondEntity, firstEntity], { stringProp: true, numberProp: false });
   });
 
   it('should sort by two properties when descending first and ascending second', async () => {
-    await facade.createEntity({ entity: firstEntity });
-    await facade.createEntity({ entity: secondEntity });
+    await facade.createEntity({ id: testId, entity: firstEntity });
+    await facade.createEntity({ id: testId, entity: secondEntity });
     await assertSort([secondEntity, firstEntity], { stringProp: false, numberProp: true });
   });
 };

src/tests/getEntity/test.ts

@@ -13,7 +13,7 @@ export default (facade: Facade<TestId, TestEntity>) => {
     });
 
     it('should not error when identifier does exist', async () => {
-      await facade.createEntity({ entity: testEntity });
+      await facade.createEntity({ id: testId, entity: testEntity });
       const retrievedEntity = await facade.getEntity({ id: testId });
       assert.deepEqual(retrievedEntity, testEntity);
     });

src/tests/overwriteEntity/test.ts

@@ -19,7 +19,7 @@ export default (facade: Facade<TestId, TestEntity>) => {
         numberProp: 2,
         stringProp: 'test_string_prop_overwrite',
       };
-      await facade.createEntity({ entity: testEntity });
+      await facade.createEntity({ id: testId, entity: testEntity });
       const overwrittenEntity = await facade.overwriteEntity({ id: testId, entity: testOverwrite });
       const retrievedEntity = await facade.getEntity({ id: testId });
       assert.deepEqual(overwrittenEntity, testOverwrite);

src/tests/patchEntity/test.ts

@@ -24,7 +24,7 @@ export default (facade: Facade<TestId, TestEntity>) => {
       const testPatch: Partial<TestEntity> = {
         stringProp: 'test_string_prop_patch',
       };
-      await facade.createEntity({ entity: testEntity });
+      await facade.createEntity({ id: testId, entity: testEntity });
       await assertPatch(testPatch);
     });
 
@@ -34,7 +34,7 @@ export default (facade: Facade<TestId, TestEntity>) => {
         numberProp: 2,
         stringProp: 'test_string_prop_patch',
       };
-      await facade.createEntity({ entity: testEntity });
+      await facade.createEntity({ id: testId, entity: testEntity });
       await assertPatch(testPatch);
     });
   });