Merge pull request #17 from alphamanuscript/add-create-entity-3

Allows creating entities

Author: habbes

README.md

@@ -2,4 +2,7 @@
 
 The Surix Javascript SDK is a set of libraries and utilities used to interact with the Surix platform in Node.js or browsers using Javascript.
 
-
+| Name         | Description                            |
+|--------------|----------------------------------------|
+| [client](packages/client/README.md)       | An SDK to help interact with surix API |
+| [data-helpers](packages/data-helpers/README.md) | Has helper functions for simplicity    |

packages/client/README.md

@@ -39,6 +39,38 @@ const project = client.project('projectId');
 
 ### Entities
 
+#### `project.entities.create(entity: Entity)`
+
+Creates a given entity
+
+```javascript
+const entity = {
+  data: {
+    name: 'My Awesome Name'
+  },
+  tags: []
+}
+
+const savedEntity = await project.entities.create(entity)
+
+console.log(savedEntity.get('name'))
+```
+
+Note: Before the entity is created, it is expanded (using `expandEntity` function in `@surix/data-helpers`) to a raw entity that includes the types information using the type of the values provided in the data field.
+The entity above would be converted to:
+
+```javascript
+{
+  data: {
+    name: {
+      type: 'text',
+      value: 'My Awesome Name'
+    }
+  },
+  tags: []
+}
+```
+Dates are expanded as `text` for now and will correctly be expanded to `datetime` in future versions of `@surix/data-helpers`. Arrays are not supported for now.
 #### `project.entities.get(id: string)`
 
 Fetches an entity by ID.

packages/client/package.json

@@ -62,7 +62,7 @@
     "webpack-cli": "^3.1.2"
   },
   "dependencies": {
-    "@surix/data-helpers": "^0.6.0",
+    "@surix/data-helpers": "^0.7.1",
     "axios": "^0.18.0"
   }
 }

packages/client/src/project/entities.ts

@@ -1,17 +1,24 @@
-import { ApiEntity, wrapEntity, wrapEntityArray, WrappedEntity } from '@surix/data-helpers';
+import { ApiEntity,  expandEntity, wrapEntity, wrapEntityArray, WrappedEntity} from '@surix/data-helpers';
 import { AxiosInstance } from 'axios';
-import { ProjectEntities, Query, TagList } from '../types';
+import {  Entity, ProjectEntities, Query } from '../types';
 
 export function getProjectEntities (projectId: string, apiClient: AxiosInstance): ProjectEntities {
   return {
-    async get (entityId: string): Promise<WrappedEntity> {
+    async get(entityId: string): Promise<WrappedEntity> {
       const res = await apiClient.get<ApiEntity>(`/projects/${projectId}/entities/${entityId}`);
       return wrapEntity(res.data);
     },
     async query(query: Query = {}): Promise<WrappedEntity[]> {
       const res = await apiClient.post<ApiEntity[]>(`/projects/${projectId}/entities/query`, query);
       const entities = res.data;
       return wrapEntityArray(entities);
+    },
+    async create(entity: Entity): Promise<WrappedEntity> {
+      const expandedEntity = expandEntity(entity);
+      const res = await apiClient.post<ApiEntity>(
+        `/projects/${projectId}/entities`, expandedEntity);
+      const returnedEntity = res.data;
+      return wrapEntity(returnedEntity);
     }
   };
 }

packages/client/src/project/tests/__snapshots__/entities.test.ts.snap

@@ -11,10 +11,8 @@ EntityWrapper {
     },
     "data": Object {
       "name": Object {
-        "label": "Label",
-        "name": "name",
         "type": "text",
-        "value": "Foo",
+        "value": "name",
       },
     },
     "tags": Array [
@@ -27,6 +25,33 @@ EntityWrapper {
 }
 `;
 
+exports[`Project Entities query create should return an error 1`] = `
+EntityWrapper {
+  "_entity": Object {
+    "entity": Object {
+      "_id": "e1",
+      "createdAt": "2017-02-22T09:19:33.885Z",
+      "createdBy": Object {
+        "_id": "u1",
+        "type": "user",
+      },
+      "data": Object {
+        "name": Object {
+          "type": "text",
+          "value": "name",
+        },
+      },
+      "tags": Array [
+        "t1",
+      ],
+      "updatedAt": "2018-10-22T09:19:33.885Z",
+    },
+  },
+  "createdAt": Date { NaN },
+  "updatedAt": Date { NaN },
+}
+`;
+
 exports[`Project Entities query should return the entities transformed to array of WrappedEntity 1`] = `
 Array [
   EntityWrapper {
@@ -39,10 +64,8 @@ Array [
       },
       "data": Object {
         "name": Object {
-          "label": "Label",
-          "name": "name",
           "type": "text",
-          "value": "Foo",
+          "value": "name",
         },
       },
       "tags": Array [
@@ -63,10 +86,8 @@ Array [
       },
       "data": Object {
         "name": Object {
-          "label": "Label",
-          "name": "name",
           "type": "text",
-          "value": "Bar",
+          "value": "name",
         },
       },
       "tags": Array [

packages/client/src/project/tests/entities.test.ts

@@ -16,9 +16,7 @@ describe('Project Entities', () => {
       data: {
         name: {
           type: 'text',
-          value: 'Foo',
-          name: 'name',
-          label: 'Label'
+          value: 'name'
         }
       }
     },
@@ -31,9 +29,7 @@ describe('Project Entities', () => {
       data: {
         name: {
           type: 'text',
-          value: 'Bar',
-          name: 'name',
-          label: 'Label'
+          value: 'name'
         }
       }
     }
@@ -86,5 +82,36 @@ describe('Project Entities', () => {
         expect(apiClient.post).toHaveBeenCalledWith(`/projects/project1/entities/query`, {});
       });
     });
+
+    describe('create', () => {
+      const userEntity = {
+        data: {
+          name: 'someone 1'
+        },
+        tags: []
+      }
+      let apiClient: AxiosInstance;
+      async function callMockCreate (entity: any): Promise<dataHelpers.WrappedEntity> {
+        apiClient = api.getApiClient('http://baseurl', 'somekey');
+        jest.spyOn(apiClient, 'post').mockReturnValue(Promise.resolve({ data: 
+          { entity } }));
+        jest.spyOn(dataHelpers, 'wrapEntity');
+        const project = getProjectApi('project1', apiClient);
+        const ent = await project.entities.create(entity);
+        return ent;
+      }
+      it('should call POST /projects/:pid/entities endpoint with entity', async () => {
+        const entity = userEntity;
+        const expectedEntity = dataHelpers.expandEntity(entity)
+        await callMockCreate(entity);
+        expect(apiClient.post).toHaveBeenCalledWith('/projects/project1/entities', expectedEntity);
+      });
+      it('should return an error', async () => {
+        const ent = apiEntities[0];
+        const entity = await callMockCreate(ent);
+        expect(dataHelpers.wrapEntity).toHaveBeenCalledWith(ent);
+        expect(entity).toMatchSnapshot();
+      });
+    });
   }); 
 });

packages/client/src/types.ts

@@ -9,6 +9,7 @@ export interface Project {
 export interface ProjectEntities {
   get(id: string): Promise<WrappedEntity>;
   query(query?: Query): Promise<WrappedEntity[]>;
+  create(entity: any): Promise<WrappedEntity>;
 }
 
 export interface ProjectFiles {
@@ -31,4 +32,45 @@ export interface TagListItem {
   name: string;
 }
 
-export type TagList = TagListItem[];
+export type TagList = TagListItem[];
+
+export enum FieldType {
+  TEXT = 'text',
+  BOOLEAN = 'boolean',
+  NUMBER = 'number',
+  DATETIME = 'datetime',
+  PHONE = 'phone',
+  EMAIL = 'email',
+  FILE = 'file',
+  OBJECT = 'object',
+  LIST = 'list'
+}
+
+export interface FieldPair {
+  type: FieldType;
+  value: RawEntityData | string | RawEntityData[] | number;
+}
+
+export interface RawEntityField extends FieldPair {
+}
+
+export interface RawEntityData {
+  [fieldName: string]: RawEntityField;
+}
+
+/**
+ * this interface describe the shape of the entity
+ * as used within the system and the API
+ */
+export interface RawEntity {
+  data: RawEntityData;
+  tags?: string[];
+}
+
+export interface DataField {
+  [fieldName: string]: string | number | object | boolean;
+}
+export interface Entity {
+  data: DataField;
+  tags?: string[];
+}

packages/data-helpers/README.md

@@ -37,6 +37,35 @@ const {
 } = require('@surix/data-helpers')
 ```
 
+### `expnadEntity`
+
+Converts a user friendly version of an entity to the raw version of the entity.  
+*Note: For now, dates are interpreted `text` type but will be updated to `datatime` in future*
+```javascript
+import { expandEntity } from '@surix/data-helpers';
+
+const entity = {
+  data: {
+    name: 'My Name',
+    age: 12,
+    children: [
+      {
+        name: 'Some name'
+      }
+    ],
+    address: {
+      location: 'Nairobi'
+    },
+    isOldEnough: true
+  },
+  tags: []
+};
+
+const expandedEntity = expandEntity(entity);
+```
+
+**Note:** `Date()` will be converted to a string. `new Date()` will be converted to `datetime` so if you want dated treated correctly, you can use `new Date()`
+
 ### `wrapEntity`
 
 ```javascript

packages/data-helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surix/data-helpers",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Utilities for making it easy to work with Surix data",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",

packages/data-helpers/src/expand-entity/expand-entity.ts

@@ -0,0 +1,56 @@
+import { DataField, Entity, RawEntity, RawEntityData } from '../types';
+
+function expandEntity (entity: Entity): RawEntity {
+    const { data } = entity;
+    const convertedData = expandEntityData(data);
+    // delete entity.data;
+    // @ts-ignore
+    return { ...entity, data: convertedData };
+}
+
+function expandEntityData (data: DataField): RawEntityData {
+    const expandedEntity = Object.keys(data)
+        .reduce((expanded, key) => {
+        let converted = {};
+        switch(typeof data[key]) {
+            case 'object':
+                if(Array.isArray(data[key])) {
+                    converted = {
+                        type: 'list',
+                        // @ts-ignore
+                        value: data[key].map(item => expandEntityData(item))
+                    };
+                } else if (data[key] instanceof Date) {
+                    converted = {
+                        type: 'datetime',
+                        value: data[key]
+                    };
+                } else {
+                    converted = {
+                        type: 'object',
+                        // @ts-ignore
+                        value: expandEntityData(data[key])
+                    }
+                }
+                break;
+            case 'string':
+                converted = {
+                    type: 'text',
+                    value: data[key]
+                };
+                break;
+            default:
+                converted = { 
+                    type: typeof data[key],
+                    value: data[key]
+                };
+                break;
+        }
+        return { ...expanded, [key]: converted };
+        }, {});
+    return expandedEntity;
+  }
+
+export {
+    expandEntity
+};

packages/data-helpers/src/expand-entity/index.ts

@@ -0,0 +1 @@
+export { expandEntity } from './expand-entity';