feat: Adds filter to entity functions. (#2)

BREAKING CHANGE: The `filter`, `sort`, and `paginate` options are now optional.
BREAKING CHANGE: The `upsertEntity` function has been removed due to filter issues.
BREAKING CHANGE: The `overwriteEntity` function was renamed to `replaceEntity`.

Author: ryasmi

docs/facade.md

@@ -6,11 +6,10 @@ The facade contains common functions for storage and retrieval of entities from
 - [createEntity](./functions.md#createentity)
 - [getEntities](./functions.md#getentities)
 - [getEntity](./functions.md#getentity)
-- [overwriteEntity](./functions.md#overwriteentity)
+- [replaceEntity](./functions.md#replaceentity)
 - [patchEntity](./functions.md#patchentity)
 - [removeEntities](./functions.md#removeentities)
 - [removeEntity](./functions.md#removeentity)
-- [upsertEntity](./functions.md#upsertentity)
 
 The functions have some common options that they use.
 

docs/functions.md

@@ -6,11 +6,10 @@ The [facade](./facade.md) contains common functions for storage and retrieval of
 - [createEntity](#createentity)
 - [getEntities](#getentities)
 - [getEntity](#getentity)
-- [overwriteEntity](#overwriteentity)
+- [replaceEntity](#replaceentity)
 - [patchEntity](#patchentity)
 - [removeEntities](#removeentities)
 - [removeEntity](#removeentity)
-- [upsertEntity](#upsertentity)
 
 ### countEntities
 Counts the number of entities that match the `filter` option.
@@ -27,10 +26,19 @@ This package contains the [count entities tests](../src/tests/countEntities) and
 Creates a new entity using the `entity` option if no entity exists that matches the `id` option.
 
 ```ts
-const { entity } = await facade.createEntity({
-  id: 'example_id',
-  entity: { id: 'example_id', foo: 'bar' },
-});
+import ConflictingEntityError from 'js-entity-repos/core/dist/errors/ConflictingEntityError';
+
+try {
+  const { entity } = await facade.createEntity({
+    id: 'example_id',
+    entity: { id: 'example_id', foo: 'bar' },
+  });
+} catch (err) {
+  if (err instanceof ConflictingEntityError) {
+    // An entity with the given id already exists.
+  }
+  throw err;
+}
 ```
 
 This package contains the [create entity tests](../src/tests/createEntity) and the [create entity signature](../src/signatures/CreateEntity.ts) for this function.
@@ -59,36 +67,66 @@ const firstPage = await facade.getEntities({
 This package contains the [get entities tests](../src/tests/getEntities) and the [get entities signature](../src/signatures/GetEntities.ts) for this function.
 
 ### getEntity
-Retrieves a single entity that matches the `id` option.
+Retrieves a single entity that matches the `id` and `filter` options.
 
 ```ts
-const { entity } = await facade.getEntity({
-  id: 'example_id',
-});
+import MissingEntityError from 'js-entity-repos/core/dist/errors/MissingEntityError';
+
+try {
+  const { entity } = await facade.getEntity({
+    id: 'example_id',
+    filter: { foo: 'bar' },
+  });
+} catch (err) {
+  if (err instanceof MissingEntityError) {
+    // No entity exists that matches the given id and filter options.
+  }
+  throw err;
+}
 ```
 
 This package contains the [get entity tests](../src/tests/getEntity) and the [get entity signature](../src/signatures/GetEntity.ts) for this function.
 
-### overwriteEntity
-For an entity that matches the `id` option, it changes all of an entity's properties using the `entity` option.
+### replaceEntity
+For an entity that matches the `id` and `filter` options, it changes all of an entity's properties using the `entity` option.
 
 ```ts
-const { entity } = await facade.overwriteEntity({
-  id: 'example_id',
-  entity: { id: 'example_id', foo: 'bar' },
-});
+import MissingEntityError from 'js-entity-repos/core/dist/errors/MissingEntityError';
+
+try {
+  const { entity } = await facade.replaceEntity({
+    id: 'example_id',
+    entity: { id: 'example_id', foo: 'bar' },
+    filter: { foo: 'bar' },
+  });
+} catch (err) {
+  if (err instanceof MissingEntityError) {
+    // No entity exists that matches the given id and filter options.
+  }
+  throw err;
+}
 ```
 
-This package contains the [overwrite entity tests](../src/tests/overwriteEntity) and the [overwrite entity signature](../src/signatures/OverwriteEntity.ts) for this function.
+This package contains the [replace entity tests](../src/tests/replaceEntity) and the [replace entity signature](../src/signatures/ReplaceEntity.ts) for this function.
 
 ### patchEntity
-For an entity that matches the `id` option, it changes some of an entity's properties using the `patch` option.
+For an entity that matches the `id` and `filter` options, it changes some of an entity's properties using the `patch` option.
 
 ```ts
-const { entity } = await facade.patchEntity({
-  id: 'example_id',
-  patch: { foo: 'bar' },
-});
+import MissingEntityError from 'js-entity-repos/core/dist/errors/MissingEntityError';
+
+try {
+  const { entity } = await facade.patchEntity({
+    id: 'example_id',
+    patch: { foo: 'bar' },
+    filter: { foo: 'bar' },
+  });
+} catch (err) {
+  if (err instanceof MissingEntityError) {
+    // No entity exists that matches the given id and filter options.
+  }
+  throw err;
+}
 ```
 
 This package contains the [patch entity tests](../src/tests/patchEntity) and the [patch entity signature](../src/signatures/PatchEntity.ts) for this function.
@@ -105,24 +143,22 @@ await facade.removeEntities({
 This package contains the [remove entities tests](../src/tests/removesEntities) and the [remove entities signature](../src/signatures/RemoveEntities.ts) for this function.
 
 ### removeEntity
-Removes an entity that matches the `id` option.
+Removes an entity that matches the `id` and `filter` options.
 
 ```ts
-await facade.removeEntity({
-  id: 'example_id',
-});
+import MissingEntityError from 'js-entity-repos/core/dist/errors/MissingEntityError';
+
+try {
+  await facade.removeEntity({
+    id: 'example_id',
+    filter: { foo: 'bar' },
+  });
+} catch (err) {
+  if (err instanceof MissingEntityError) {
+    // No entity exists that matches the given id and filter options.
+  }
+  throw err;
+}
 ```
 
 This package contains the [remove entity tests](../src/tests/removesEntity) and the [remove entity signature](../src/signatures/RemoveEntity.ts) for this function.
-
-### upsertEntity
-Creates an entity when no entity exists that matches the `id` option. Otherwise, it overwrites all of the properties for an entity that matches the `id` option.
-
-```ts
-await facade.upsertEntity({
-  id: 'example_id',
-  entity: { id: 'example_id', foo: 'bar' },
-});
-```
-
-This package contains the [upsert entity tests](../src/tests/upsertsEntity) and the [upsert entity signature](../src/signatures/UpsertEntity.ts) for this function.

src/Facade.ts

@@ -2,21 +2,19 @@ import CountEntities from './signatures/CountEntities';
 import CreateEntity from './signatures/CreateEntity';
 import GetEntities from './signatures/GetEntities';
 import GetEntity from './signatures/GetEntity';
-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';
+import ReplaceEntity from './signatures/ReplaceEntity';
 import Entity from './types/Entity';
 
 export default interface Facade<E extends Entity> {
   readonly getEntity: GetEntity<E>;
   readonly createEntity: CreateEntity<E>;
-  readonly overwriteEntity: OverwriteEntity<E>;
+  readonly replaceEntity: ReplaceEntity<E>;
   readonly patchEntity: PatchEntity<E>;
-  readonly removeEntity: RemoveEntity;
+  readonly removeEntity: RemoveEntity<E>;
   readonly getEntities: GetEntities<E>;
   readonly countEntities: CountEntities<E>;
   readonly removeEntities: RemoveEntities<E>;
-  readonly upsertEntity: UpsertEntity<E>;
 }

src/signatures/CountEntities.ts

@@ -2,7 +2,7 @@ import Entity from '../types/Entity';
 import Filter from '../types/Filter';
 
 export interface Opts<E extends Entity> {
-  readonly filter: Filter<E>;
+  readonly filter?: Filter<E>;
 }
 
 export interface Result {

src/signatures/GetEntities.ts

@@ -5,9 +5,9 @@ import Pagination from '../types/Pagination';
 import Sort from '../types/Sort';
 
 export interface Opts<E extends Entity> {
-  readonly filter: Filter<E>;
-  readonly sort: Sort<E>;
-  readonly pagination: Pagination;
+  readonly filter?: Filter<E>;
+  readonly sort?: Sort<E>;
+  readonly pagination?: Pagination;
 }
 
 export interface Result<E extends Entity> {

src/signatures/GetEntity.ts

@@ -1,13 +1,15 @@
 import Entity from '../types/Entity';
+import Filter from '../types/Filter';
 
-export interface Opts {
+export interface Opts<E extends Entity> {
   readonly id: string;
+  readonly filter?: Filter<E>;
 }
 
 export interface Result<E extends Entity> {
   readonly entity: E;
 }
 
-export type Signature<E extends Entity> = (opts: Opts) => Promise<Result<E>>;
+export type Signature<E extends Entity> = (opts: Opts<E>) => Promise<Result<E>>;
 
 export default Signature;

src/signatures/PatchEntity.ts

@@ -1,8 +1,10 @@
 import Entity from '../types/Entity';
+import Filter from '../types/Filter';
 
 export interface Opts<E extends Entity> {
   readonly id: string;
   readonly patch: Partial<E>;
+  readonly filter?: Filter<E>;
 }
 
 export interface Result<E extends Entity> {

src/signatures/RemoveEntities.ts

@@ -2,7 +2,7 @@ import Entity from '../types/Entity';
 import Filter from '../types/Filter';
 
 export interface Opts<E extends Entity> {
-  readonly filter: Filter<E>;
+  readonly filter?: Filter<E>;
 }
 
 export type Result = void;

src/signatures/RemoveEntity.ts

@@ -1,9 +1,13 @@
-export interface Opts {
+import Entity from '../types/Entity';
+import Filter from '../types/Filter';
+
+export interface Opts<E extends Entity> {
   readonly id: string;
+  readonly filter?: Filter<E>;
 }
 
 export type Result = void;
 
-export type Signature = (opts: Opts) => Promise<Result>;
+export type Signature<E extends Entity> = (opts: Opts<E>) => Promise<Result>;
 
 export default Signature;

src/signatures/OverwriteEntity.ts renamed to src/signatures/ReplaceEntity.ts

@@ -1,8 +1,10 @@
 import Entity from '../types/Entity';
+import Filter from '../types/Filter';
 
 export interface Opts<E extends Entity> {
   readonly id: string;
   readonly entity: E;
+  readonly filter?: Filter<E>;
 }
 
 export interface Result<E extends Entity> {

src/signatures/UpsertEntity.ts

@@ -1,26 +1,21 @@
 import 'mocha'; // tslint:disable-line:no-import-side-effect
 import * as assert from 'power-assert';
 import Facade from '../../Facade';
-import Pagination from '../../types/Pagination';
-import Sort from '../../types/Sort';
 import filterTest, { firstEntity, secondEntity } from '../utils/filterTest';
 import { TestEntity } from '../utils/testEntity';
 
 export default (facade: Facade<TestEntity>) => {
-  const sort: Sort<TestEntity> = {};
-  const pagination: Pagination = { cursor: undefined, forward: true, limit: 2 };
-
   filterTest({
     assertAllEntitiesFilter: async (filter) => {
-      const actualResult = await facade.getEntities({ filter, sort, pagination });
+      const actualResult = await facade.getEntities({ filter });
       assert.deepEqual(actualResult.entities, [firstEntity, secondEntity]);
     },
     assertFirstEntityFilter: async (filter) => {
-      const actualResult = await facade.getEntities({ filter, sort, pagination });
+      const actualResult = await facade.getEntities({ filter });
       assert.deepEqual(actualResult.entities, [firstEntity]);
     },
     assertNoEntityFilter: async (filter) => {
-      const actualResult = await facade.getEntities({ filter, sort, pagination });
+      const actualResult = await facade.getEntities({ filter });
       assert.deepEqual(actualResult.entities, []);
     },
     facade,

src/tests/getEntities/filterTest.ts

@@ -2,18 +2,14 @@ import 'mocha'; // tslint:disable-line:no-import-side-effect
 import * as assert from 'power-assert';
 import Facade from '../../Facade';
 import Cursor from '../../types/Cursor';
-import Filter from '../../types/Filter';
 import Pagination from '../../types/Pagination';
-import Sort from '../../types/Sort';
 import { TestEntity, testEntity } from '../utils/testEntity';
 
 export default (facade: Facade<TestEntity>) => {
   const firstId = 'test_id_1';
   const secondId = 'test_id_2';
   const firstEntity = { ...testEntity, id: firstId };
   const secondEntity = { ...testEntity, id: secondId };
-  const sort: Sort<TestEntity> = { id: true };
-  const filter: Filter<TestEntity> = {};
 
   const createTestEntities = async () => {
     await facade.createEntity({ id: firstId, entity: firstEntity });
@@ -22,13 +18,19 @@ export default (facade: Facade<TestEntity>) => {
 
   const paginate = (cursor: Cursor, forward: boolean) => {
     const pagination: Pagination = { cursor, forward, limit: 1 };
-    return facade.getEntities({ filter, sort, pagination });
+    return facade.getEntities({ pagination });
   };
 
+  it('should return all entities when pagination is not defined', async () => {
+    await createTestEntities();
+    const result = await facade.getEntities({});
+    assert.deepEqual(result.entities, [firstEntity]);
+  });
+
   it('should return first entity when there are two entities limitted to 1', async () => {
     await createTestEntities();
     const pagination: Pagination = { cursor: undefined, forward: true, limit: 1 };
-    const result = await facade.getEntities({ filter, sort, pagination });
+    const result = await facade.getEntities({ pagination });
     assert.deepEqual(result.entities, [firstEntity]);
   });