[TECH] Faciliter le build des seeds en base de données avec JSDoc

 #8212

api/db/database-builder/database-builder.js

@@ -6,13 +6,17 @@ import { databaseBuffer } from './database-buffer.js';
 import * as databaseHelpers from './database-helpers.js';
 import { factory } from './factory/index.js';
 
+/**
+ * @class DatabaseBuilder
+ * @property {Factory} factory
+ */
 class DatabaseBuilder {
   constructor({ knex, emptyFirst = true, beforeEmptyDatabase = () => undefined }) {
     this.knex = knex;
     this.databaseBuffer = databaseBuffer;
     this.tablesOrderedByDependencyWithDirtinessMap = [];
-    this.factory = factory;
     this.isFirstCommit = true;
+    this.factory = factory;
     this.emptyFirst = emptyFirst;
     this._beforeEmptyDatabase = beforeEmptyDatabase;
 

api/db/database-builder/factory/build-data-protection-officer.js

@@ -2,6 +2,30 @@ import { databaseBuffer } from '../database-buffer.js';
 
 const TABLE_NAME = 'data-protection-officers';
 
+/**
+ * @typedef {{
+ *  id: number,
+ *  firstName: string,
+ *  lastName: string,
+ *  email: string,
+ *  certificationCenterId: number,
+ *  createdAt: Date,
+ *  updatedAt: Date,
+ * }} CertificationCenter
+ */
+
+/**
+ * @typedef {{
+ *  id: number,
+ *  firstName: string,
+ *  lastName: string,
+ *  email: string,
+ *  certificationCenterId: number,
+ *  createdAt: Date,
+ *  updatedAt: Date,
+ * }} Organization
+ */
+
 function buildCertificationCenterDataProtectionOfficer({
   id = databaseBuffer.getNextId(),
   firstName,
@@ -52,6 +76,12 @@ function buildOrganizationDataProtectionOfficer({
   });
 }
 
+/**
+ * @typedef {{
+ *    withCertificationCenterId: function(Partial<CertificationCenter>): CertificationCenter,
+ *    withOrganizationId: function(Partial<Organization>): Organization,
+ * }} BuildDataProtectionOfficerFactory
+ */
 export {
   buildCertificationCenterDataProtectionOfficer as withCertificationCenterId,
   buildOrganizationDataProtectionOfficer as withOrganizationId,

api/db/database-builder/factory/build-organization-learner.js

@@ -4,6 +4,42 @@ import { databaseBuffer } from '../database-buffer.js';
 import { buildOrganization } from './build-organization.js';
 import { buildUser } from './build-user.js';
 
+/**
+ * @typedef SeedOrganizationLearner
+ * @type {object}
+ *
+ * @property {number} id
+ * @property {string} firstName
+ * @property {string} preferredLastName
+ * @property {string} lastName
+ * @property {string} middleName
+ * @property {string} thirdName
+ * @property {string} sex
+ * @property {string} birthdate
+ * @property {string} birthCity
+ * @property {string} birthCityCode
+ * @property {string} birthCountryCode
+ * @property {string} birthProvinceCode
+ * @property {string} MEFCode
+ * @property {string} status
+ * @property {string} nationalStudentId
+ * @property {string} division
+ * @property {string} studentNumber
+ * @property {string} email
+ * @property {string} educationalTeam
+ * @property {string} department
+ * @property {string} group
+ * @property {string} diploma
+ * @property {boolean} isDisabled
+ * @property {Date} createdAt
+ * @property {Date} updatedAt
+ * @property {number} organizationId
+ * @property {number} userId
+ * @property {number} deletedBy
+ * @property {Date} deletedAt
+ * @property {boolean} isCertifiable
+ * @property {Date} certifiableAt
+ */
 const buildOrganizationLearner = function ({
   id = databaseBuffer.getNextId(),
   firstName = 'first-name',
@@ -80,4 +116,9 @@ const buildOrganizationLearner = function ({
   });
 };
 
+/**
+ * @typedef {
+ *  function(Partial<SeedOrganizationLearner>): SeedOrganizationLearner
+ * } BuildOrganizationLearner
+ */
 export { buildOrganizationLearner };

api/db/database-builder/factory/build-training.js

@@ -1,5 +1,20 @@
 import { databaseBuffer } from '../database-buffer.js';
 
+/**
+ * @typedef {{
+ *  id: number,
+ *  title: string,
+ *  link: string,
+ *  type: string,
+ *  duration: string,
+ *  locale: string,
+ *  editorName: string,
+ *  editorLogoUrl: string,
+ *  createdAt: Date,
+ *  updatedAt: Date
+ * }} Training
+ */
+
 function buildTraining({
   id = databaseBuffer.getNextId(),
   title = 'title',
@@ -32,4 +47,9 @@ function buildTraining({
   });
 }
 
+/**
+ * @typedef {
+ *  function(Partial<Training>): Training
+ * } BuildTraining
+ */
 export { buildTraining };

api/db/database-builder/factory/build-user.js

@@ -56,6 +56,37 @@ function _generateAnEmailIfNecessary(email, id, lastName, firstName) {
   return null;
 }
 
+/**
+ * @typedef SeedUser
+ * @type {object}
+ *
+ * @property {number} id
+ * @property {string} firstName
+ * @property {string} lastName
+ * @property {string} email
+ * @property {string} username
+ * @property {boolean} cgu
+ * @property {string} lang
+ * @property {string} locale
+ * @property {Date} lastTermsOfServiceValidatedAt
+ * @property {Date} lastPixOrgaTermsOfServiceValidatedAt
+ * @property {Date} lastPixCertifTermsOfServiceValidatedAt
+ * @property {boolean} mustValidateTermsOfService
+ * @property {boolean} pixOrgaTermsOfServiceAccepted
+ * @property {boolean} pixCertifTermsOfServiceAccepted
+ * @property {boolean} hasSeenAssessmentInstructions
+ * @property {boolean} hasSeenNewDashboardInfo
+ * @property {boolean} hasSeenLevelSevenInfo
+ * @property {boolean} hasSeenFocusedChallengeTooltip
+ * @property {boolean} hasSeenOtherChallengesTooltip
+ * @property {boolean} isAnonymous
+ * @property {Date} createdAt
+ * @property {Date} updatedAt
+ * @property {Date} emailConfirmedAt
+ * @property {boolean} hasBeenAnonymised
+ * @property {number} hasBeenAnonymisedBy
+ * @property {Date} lastDataProtectionPolicySeenAt
+ */
 const buildUser = function buildUser({
   id = databaseBuffer.getNextId(),
   firstName = 'Billy',
@@ -403,4 +434,10 @@ buildUser.withCertificationCenterMembership = function buildUserWithCertificatio
   return user;
 };
 
+/**
+ * @typedef {
+ *  function(Partial<SeedUser>): SeedUser
+ * } BuildUser
+ */
+
 export { buildUser };

api/db/database-builder/factory/index.js

@@ -26,6 +26,18 @@ const organizationLearners = await importNamedExportsFromDirectory({
   ignoredFileNames: unwantedFiles,
 });
 
+/**
+ * Travail à continuer en scout-rule
+ * @see https://github.com/1024pix/pix/pull/8212
+ * @typedef {
+ *    {
+ *      buildTraining: BuildTraining,
+ *      buildDataProtectionOfficer: BuildDataProtectionOfficerFactory,
+ *      buildUser: BuildUser,
+ *      buildOrganizationLearner: BuildOrganizationLearner,
+ *    }
+ *  } Factory
+ */
 export const factory = {
   ...databaseBuilders,
   prescription: {