Merge pull request #559 from nowcommunity/validator-documentation

Validator documentation

Author: EeroAnt

backend/src/api-tests/reference/create.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, beforeAll, afterAll, describe, it, expect } from '@jest/globals'
 import { ReferenceDetailsType } from '../../../../frontend/src/backendTypes'
 //import { LogRow } from '../../services/write/writeOperations/types'
-import { newReferenceBasis } from './data'
+import { newReferenceBasis, emptyReferenceBasis } from './data'
 import { login, logout, resetDatabase, send, /*testLogRows,*/ resetDatabaseTimeout, noPermError } from '../utils'
 import { pool } from '../../utils/db'
 import Prisma from '../../../prisma/generated/now_test_client'
@@ -43,14 +43,38 @@ describe('Creating new reference works', () => {
     expect(journal_id).toBeDefined()
   })
 
-  it.skip('Adding "removed" in rowstate of authors & journal deletes author and clear journal data from reference', async () => {
+  it('Adding "removed" in rowstate of authors & journal deletes author and clear journal data from reference', async () => {
     const { status: getReqStatus } = await send<{ rid: number }>(`reference/`, 'PUT', {
       reference: {
         ...createdRef,
-        ref_authors: createdRef!.ref_authors.map(ref_author => ({
-          ...ref_author,
-          rowState: 'removed',
-        })),
+        //changing type_id to 2 since journals are mandatory on type 1
+        ref_type_id: 2,
+        ref_authors: [
+          {
+            rid: undefined,
+            au_num: 1,
+            author_surname: 'testiauthor',
+            author_initials: 'testi-initials',
+            field_id: 2,
+            rowState: 'removed',
+          },
+          {
+            rid: undefined,
+            au_num: 2,
+            author_surname: 'testiauthor2',
+            author_initials: 'testi-initials2',
+            field_id: 2,
+            rowState: 'removed',
+          },
+          {
+            rid: undefined,
+            au_num: 1,
+            author_surname: 'testiauthor3',
+            author_initials: 'testi-initials3',
+            field_id: 12,
+            rowState: 'new',
+          },
+        ],
         ref_journal: {
           ...createdRef!.ref_journal,
           rowState: 'removed',
@@ -62,7 +86,7 @@ describe('Creating new reference works', () => {
     const updatedRef = resultBody
     const { ref_authors, ref_journal, journal_id } = updatedRef
 
-    expect(ref_authors.length).toEqual(0) //authors have been removed from the reference
+    expect(ref_authors.length).toEqual(1) //authors have been removed from the reference
     expect(journal_id).toBeNull() //journal id set to null
     expect(ref_journal).toBeNull() //no journal fetched
 
@@ -74,13 +98,14 @@ describe('Creating new reference works', () => {
 
     const { body, status: getReqStatus3 } = await send(`reference/authors/${createdRef?.rid}`, 'GET')
     expect(getReqStatus3).toEqual(200)
-    expect(body.length).toEqual(0) // Authors should be deleted from db
+    expect(body.length).toEqual(1) // Authors should be deleted from db
   })
 
-  it.skip('Removing author / journal data from reference should clear the data from db', async () => {
+  it('Removing author / journal data from reference should clear the data from db', async () => {
     const { status: getReqStatus } = await send<{ rid: number }>(`reference/`, 'PUT', {
       reference: {
         ...createdRef,
+        ref_type_id: 2,
         ref_authors: [createdRef!.ref_authors[0]],
         ref_journal: null,
       },
@@ -107,6 +132,47 @@ describe('Creating new reference works', () => {
     expect(body.length).toEqual(1) //Unused authors should be deleted from db
   })
 
+  it('All validators fail with empty reference', async () => {
+    const { body: resultBody, status: getReqStatus } = await send('reference/', 'PUT', {
+      reference: { ...emptyReferenceBasis },
+    })
+    expect(getReqStatus).toEqual(403)
+    expect(resultBody.length).toEqual(8) //There should be 8 validation errors
+  })
+
+  it('All validators pass with correct data', async () => {
+    const { body: resultBody, status: getReqStatus } = await send<{ rid: number }>('reference/', 'PUT', {
+      reference: {
+        ...emptyReferenceBasis,
+        title_primary: 'title_primary',
+        date_primary: 2020,
+        title_secondary: 'title_secondary',
+        title_series: 'title_series',
+        gen_notes: 'gen_notes',
+        exact_date: '2024-11-18',
+        ref_authors: [
+          {
+            rid: undefined,
+            au_num: 1,
+            author_surname: 'testiauthor',
+            author_initials: 'testi-initials',
+            field_id: 2,
+            rowState: 'new',
+          },
+        ],
+        ref_journal: {
+          journal_title: 'testijournal',
+          short_title: 'shorttitle',
+          alt_title: 'alttitle',
+          ISSN: 'issn',
+          rowState: 'new',
+        },
+      },
+    })
+    expect(getReqStatus).toEqual(200)
+    expect(typeof resultBody.rid).toEqual('number')
+  })
+
   it('Creation fails without permissions', async () => {
     logout()
     const { body: resultBodyNoPerm, status: resultStatusNoPerm } = await send('reference/', 'PUT', {

backend/src/api-tests/reference/data.ts

@@ -79,3 +79,31 @@ export const newReferenceBasis: EditDataType<ReferenceDetailsType> = {
     rowState: 'new',
   },
 }
+
+export const emptyReferenceBasis: EditDataType<ReferenceDetailsType> = {
+  ref_type_id: 14,
+  title_primary: null,
+  date_primary: null,
+  volume: null,
+  issue: null,
+  start_page: null,
+  end_page: null,
+  publisher: null,
+  pub_place: null,
+  title_secondary: null,
+  date_secondary: null,
+  title_series: null,
+  issn_isbn: null,
+  ref_abstract: null,
+  web_url: null,
+  misc_1: null,
+  misc_2: null,
+  gen_notes: null,
+  printed_language: null,
+  exact_date: null,
+  used_morph: null,
+  used_now: null,
+  used_gene: null,
+  ref_authors: [],
+  ref_journal: {},
+}

frontend/src/validators/README.md

@@ -9,6 +9,9 @@ Validators are created as objects with the following fields. Only `name` is requ
 - `asString` Either "true" to just require a string, or a function which can do more complex validation for the string value
 - `asNumber` Same as asString but for numbers: Set to `true` to require a valid number, or set the function to both require a valid number (checked automatically if function is supplied) and apply more custom validations in the function body
 - `miscCheck` is used to simply run any check you want. Currently it's used to e.g. validate the low_bound and up_bound fields of a time unit in the timeUnit validator.
+- `miscArray` is used to run any check you want on arrays. Used for example in reference validators to check all authors are in correct format, author name is set etc.
+- `condition` used to set some condition for when a validator is run. Happens before the check for if a value is required. Used for example in references to only run validators for for certain fields since they are only mandatory on some reference types, not all. Although using 'required' instead may now be possible after changes to it.
+- `useEditData` A boolean for if you want to pass editData to the different checks of a validator instead of just the data of the field being validated. Used in references since some validators need to pass editData to a common function. Again, using 'required' instead may be possible after its changes
 
 Example:
 
@@ -27,6 +30,10 @@ To know if user is creating a new entry or editing existing one, check if the id
 
 ### Note!
 
+At the moment you can only create validators for existing and defined fields of editData. This is limiting in some cases and creating validators that check multiple fields (as is necessary in references) requires some trickery. Similarly you cannot create multiple validators for the same field.
+
+Validators are only run if the data is defined! If the value of a key of editData == undefined, the data is not checked even if it is set as required in the validator. Similarly if a key does not exist in editData, it will not be checked even if the data would be required. This is also the case in backend. This may lead to mistakes getting into the db if some data must be set but it is not defined at all.
+
 The files in this folder, and also backendTypes.d.ts, cannot
 
 - Use path aliases in imports