@ironcode/vas-lib 1.0.2 → 1.2.0

package/lib/entity/vas-base.model.d.ts

@@ -1,4 +1,9 @@
 import { VasBaseDto } from './vas-base.dto';
+import { VasUserDto } from './vas-user.dto';
+interface VasModelStatic<T extends VasBaseModel> {
+    new (...args: any[]): T;
+    fromDto(dto: Partial<VasBaseDto>): T;
+}
 /**
  * BaseEntityModel
  */
@@ -13,4 +18,7 @@ export declare class VasBaseModel implements VasBaseDto {
     createdByName: string;
     modifiedByName: string;
     constructor(id: string, created: string, serverCreated: string, createdBy: string, modified: string, serverModified: string, modifiedBy: string, createdByName: string, modifiedByName: string);
+    static fromDto(dto: Partial<VasBaseDto>): VasBaseModel;
+    static create<T extends VasBaseDto>(this: VasModelStatic<T>, user: VasUserDto, values?: Partial<T>): T;
 }
+export {};

package/lib/entity/vas-job.model.d.ts

@@ -5,6 +5,7 @@ import { VasFormModel } from './vas-form.model';
 import { VasJobDto } from './vas-job.dto';
 import { VasRestrictedAccountObjectModel } from './vas-restricted-account-object.model';
 import { GeoLocation } from '../model/geo-location';
+import { VasFormDto } from './vas-form.dto';
 export declare interface VasJobModelDynamicInterface {
     [s: string]: string | number | Record<string, VasFieldDtoValue>;
 }
@@ -54,8 +55,7 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
      */
     get dynamicProperties(): Array<string>;
     /**
-     * Returns a list of Job static properties i.e. those that are declared by
-     * the type
+     * Returns the list of properties of the Job type
      */
     get staticProperties(): Array<string>;
     /**
@@ -63,6 +63,13 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
      */
     static empty(): VasJobModel;
     static fromDto(dto: Partial<VasJobDto>): VasJobModel;
+    /**
+     * This method will instantiate a new JobModel. The difference with this
+     * method of instantiation is that we are coming from a relation frame i.e.
+     * the job has a list of {@link VasFieldDto} instead of a Job document.
+     *
+     */
+    static fromRelational(dto: Partial<VasJobDto>, form: VasFormDto): VasJobModel;
     /**
      * @param {VasFormModel} formModel
      * @return {Record<string, VasFieldDtoValue>}
@@ -75,7 +82,7 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
      * return a property regardless (because it uses the form to drive the logic)
      * @return {Record<string, VasFieldDtoValue>}
      */
-    getFields2(): Record<string, VasFieldDtoValue>;
+    protected getFields2(): Record<string, VasFieldDtoValue>;
     /**
      * Returns an object describing how many attachments were added to this job
      * (camera controls and files), and how many have not been uploaded yet.
@@ -88,18 +95,41 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
         total: number;
     };
     /**
-     * This method will hydrate the `fields` property of the model. The reason for
-     * this is that we have different ways to store the field data. One way, is
-     * we store them as dynamic properties of the job. For example job.foo.bar,
-     * where `foo` is the name of a Group, and `bar` is the name of a control.
-     * Thus, when we create a job using a form in the client, the job object will
-     * have its static properties (id, account, reference etc), and also a number
-     * of dynamic properties determined by the Groups and Controls. This kind of
-     * object is nice to work with in certain circumstances. However, the api
-     * works differently. In the API a Job is a record, and references a number of
-     * Field records. Each Field stores the value. Comparing these two models we
-     * have:
-     * A) job with dynamic properties, e.g.
+     * This method will return the dynamic property from the JobModel that
+     * represent a group (from a form).
+     *
+     * @param name the name of the group
+     * @param init if true (default) and group is not found, initialise an empty
+     * group, otherwise throw an error
+     */
+    getGroup(name: string, init?: boolean): Record<string, VasFieldDtoValue>;
+    /**
+     * @param path path segments
+     */
+    getValueByPath<T extends VasFieldDtoValue>(path?: string[]): T | undefined;
+    /**
+     * In order to understand why we need this method it is important to
+     * understand that within the system, Jobs can be represented in one of two
+     * ways, document and relational.
+     *
+     * The important distinction is how values submitted by a form are stored.
+     *
+     * Jobs stored as documents (JSON objects) will store user values, as dynamic
+     * properties of the document.
+     *
+     * Whereas, Jobs stored as relational, will store user values in an array of
+     * {@link VasFieldDto} objects.
+     *
+     * Depending on where we are in the system, either one of these approaches can
+     * be more useful than the other.
+     *
+     * This method, assumes that the JobModel has been instantiated from a
+     * document representation, and serves to hydrate the fields array. In order
+     * to achieve this, knowledge of the {@link VasFormDto} that created the job
+     * is required.
+     *
+     *
+     * Job in document representation
      * {
      *   id: <guid>,
      *   reference: "something"
@@ -109,7 +139,7 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
      *   }
      * }
      *
-     * B) job with fields
+     * Job in relational representation
      * {
      *   id: <guid>,
      *   reference: "something"
@@ -124,55 +154,15 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
      *   ]
      * }
      *
-     * So, what this method does is given a JobModel in the form of A, read all
-     * of those dynamic properties and set them into `fields`. Doing this requires
-     * knowledge of the Form that was used to create the job. Moreover, since the
-     * dynamic properties do not contain the ids of the fields, we also allow to
-     * pass in a `controlFieldIdMap`. This map stores the mapping between Control
-     * and the Field that was created in the Job to store the value for that
-     * Control. This is useful, if for example you want to compare a Job in form A
-     * with a Job in form B, for example if you want to update the Job on the API
-     * with a Job that was saved by a client in form A.
-     *
-     * E.g.
-     * Client -> API: client requests form
-     * User -> Client: user fills in the form and submits
-     * Client -> Firestore: client saves the Job in form A i.e. dynamic props
-     * Firestore -> Function: A function is triggered to sync the job to the API
-     * Function -> API: Function checks if job already exists, it receives 404
-     * Function -> Function: The function calls `hydrateFields(...)`
-     * Function -> API: The function POST the Job to /jobs
-     * Function -> API: The function POST each field to /fields
-     *
-     * Similarly, if the user updates the job
-     * Client -> API: client requests form
-     * User -> Client: user fills in the form and submits an update
-     * Client -> Firestore: client saves the Job in form A i.e. dynamic props
-     * Firestore -> Function: A function is triggered to sync the job to the API
-     * Function -> API: Function checks if job already exists, it receives 200
-     * Function -> Function: The function calls `hydrateFields(...)` passing in
-     *                       the map is made by iterating over the fields it
-     *                       received from the API and storing the mappings
-     *                       between controlId and fieldId for each field
-     * Function -> API: The function PATCH the Job to /jobs
-     * Function -> API: The function POST/PATCH each field to /fields
-     * treated as new
-     *
-     * @param {VasFormModel} formModel the VasFormModel that was used to create
-     * the job
-     * @param {Map<string, string>} controlFieldIdMap a mapping of control to
-     * field ids. This is used to determine whether a new id for the field should
-     * be generated, or to reuse an existing one from the map.
-     * @param {Array<string>} controlNames if a value is provided, it will be used
+     *
+     * @param formModel the VasFormModel that was used to create the job
+     * @param controlFieldIdMap This is used to determine the id each field.
+     * Either one will be found in the map, or a new one is generated.
+     * @param controlNames if a value is provided, it will be used
      * to filter the fields that are returned.
      * @return {Array<VasFieldDto>}
      */
     hydrateFields(formModel: VasFormModel, controlFieldIdMap?: Map<string, string>, controlNames?: Array<string>): void;
-    /**
-     * @param {string[]} path path segments
-     * @return {void}
-     */
-    getValueByPath<T extends VasFieldDtoValue>(path?: string[]): T | undefined;
     /**
      * A very non sophisticated way to set values in the job via paths
      *
@@ -187,14 +177,13 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
      *   }
      * }
      *
-     * @param {any} value the value to set
-     * @param {string[]} path path segments
+     * @param value the value to set
+     * @param path path segments
      */
     setValueByPath(value: VasFieldDtoValue, path?: string[]): void;
     /**
-     * @param {boolean} staticOnly if true, will only output values for the static
+     * @param staticOnly if true, will only output values for the static
      * properties in the dto
-     * @return {VasJobDto}
      */
     toDto(staticOnly?: boolean): VasJobDto;
     /**
@@ -221,7 +210,7 @@ export declare class VasJobModel extends VasRestrictedAccountObjectModel {
      *
      * @param {string} value a string with the syntax
      * @param {ParseSyntaxOptions} options
-     * @return {string} the results of parsing the syntax on this job
+     * @return the results of parsing the syntax on this job
      */
     parseSyntax(value: string, options?: ParseSyntaxOptions): string;
     /**

package/lib/entity/vas-note.model.d.ts

@@ -27,4 +27,5 @@ export declare class VasNoteModel extends VasJobDataModel implements VasNoteDto
      * @returns VasNoteDto
      */
     toDto(): VasNoteDto;
+    toApiDto(options?: any): Record<string, string | number | boolean>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ironcode/vas-lib",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "peerDependencies": {
     "angular2-uuid": "^1.1.1",
     "moment": "^2.0.0"