SimpleMap Typescript Utility Module (simplemap-ts-utility)

MIT License

Introduction

simplemap-ts-utility is a typescript based library. By using this library, you can import utility methods which can be used to manipulate typeScript objects, arrays, etc.

Available utility methods

• extract - Can be used to extract key: values from an existing object and create a new object.
  • Parameters
  • keys Array of keys which needs to be extracted.
  • object Original Object which will be used to extract keys.

  Assume we have this type:

  type Person = {
  name: string
  age: number
  country: string
  }
  
  const personOne: Person = {
  name: 'Test Name',
  age: 15,
  country: 'Sweden',
  }
  
  let personNameAge: Partial<Person> = extract(['name', 'age'])(personOne);
  

  Show extract Method Output
• changeN - This method can be used with this scenario. There is an object with numberical key value. And Object needs to be changed and add new key or replace existing key. This changed value should be calculated by using existing numerical key value.
  • First Parameters
  • keys Original key which may needs to use as original key value to calculate new key value.
  • callback Callback method which will be use to declare new value calculation code.
  • newKey Optional new key to store calculated value.
  • Second Parameters
  • obj Original Object.

  Assume we have this type:

  type Student = {
  name: string,
  age: number
  }
  

  and you have this Student

  const studentOne: Student = {
  name: 'Student Name 1',
  age: 18
  }
  

  Let say, you need to manipulate this object and add new key value as ageAfterTenYears, then you can use this changeN method like below.

  
  const calcAgeTenYears = (age: number) => age + 10;
  const changedStudent = changeN('age', calcAgeTenYears, 'ageAfterTenYears')(studentOne);
  

  Show changeN Method Output
• changeO - This method is bit similar to changeN. With this method, you can manipulate existing object and add a new key value pair with calculation.
  • First Parameters
  • newKey key that will be added with calculated value.
  • callback callback method which can be used to calculation implementation.
  • Second Parameter
  • obj original object which needs to be manipulate.

  Lets say you have this object type:

  type Student = {
  name: string,
  age: number
  }
  

  and you have this Student

  type Student = {
      name: string,
      dateOfBirth: Date
  }
  

  and you have this Student

  
  const studentOne: Student = {
      name: 'Student Name 1',
      dateOfBirth: new Date('1990-01-01')
  }
  

  So you need to have a method to calculate age of this Student and assign that age to new key age. You can do it like below.

  
  const calcAge = ({ dateOfBirth }, today = new Date()): number =>
      today.getMonth() < dateOfBirth.getMonth() ||
          (today.getMonth() === dateOfBirth.getMonth() && today.getDate() < dateOfBirth.getDate())
              ? today.getFullYear() - dateOfBirth.getFullYear() - 1
                  : today.getFullYear() - dateOfBirth.getFullYear();
                  
  const altStudentOne = changeO('age', calcAge)(studentOne);
      

  Show changeO Method Output
• extractA - This is the method can be used with object array to extract several keys inside object array and create a new object array. This uses extract method from above mentioned extract.
  • Parameters
  • array Original object array.
  • keys keys which needs to be extracted.

  Lets say you have below Object type:

  type Student {
      name: string,
      address: string,
      age: number
  }
  

  and you have an Student object array which is coming from an API like below

  const studentArray: Array<Student> = [
      { name: 'Student Name 1', age: 18, address: 'Malmö' },
      { name: 'Student Name 2', age: 17, address: 'Lund' },
      { name: 'Student Name 3', age: 16, address: 'Stockholm' },
      { name: 'Student Name 4', age: 18, address: 'Lund' }
  ]
  

  and now you need to have an object array which only contains name and age. Then you can use extractA method like below.

  
  const stdArrayNameAge: ArrayPartial<Student> = extractA(studentArray, ['name', 'age']);
  

  Then you can have new Array with information like below.

  
  [
      { name: 'Student Name 1', age: 18 },
      { name: 'Student Name 2', age: 17 },
      { name: 'Student Name 3', age: 16 },
      { name: 'Student Name 4', age: 18 }
  ]
      

  Show extractA Method Output
• changeA - This method is similar to changeO but this method can be used with Object Arrays. As same as earlier method, you can add new key value with calculation to an Object Array.
  • Parameters
  • array Original object array.
  • newKey new key which will use to have calculated value.
  • callback callback method, which will be used for new value calculation.

  We can use the same scenario as changeO. Lets say you have below mentioned type:

  type Student {
      name: string,
      dateOfBirth: Date
  }
  

  and then you have below mentioned object array which is coming from an API.

  const studentArray: Array<Student> = [
      { name: 'Student Name 1', dateOfBirth: new Date('1990-01-02') },
      { name: 'Student Name 2', dateOfBirth: new Date('1995-04-04') },
      { name: 'Student Name 3', dateOfBirth: new Date('1991-11-14') },
      { name: 'Student Name 4', dateOfBirth: new Date('1989-09-11') }
  ]
  

  So you need to append age calculation to this object array and you have same age calculation method as above. So you can use changeA method with this object array like below

  
  const stWithAgeArray = changeA(studentArray, 'age', calcAge);
  

  So new object array will looks like below.

  
  [
      { name: 'Student Name 1', dateOfBirth: new Date('1990-01-02'), age: 34 },
      { name: 'Student Name 2', dateOfBirth: new Date('1995-04-04'), age: 29 },
      { name: 'Student Name 3', dateOfBirth: new Date('1991-11-14'), age: 32 },
      { name: 'Student Name 4', dateOfBirth: new Date('1989-09-11'), age: 34 }
  ]
      

  Show changeA Method Output
• sort - This method can be used to sort an Array object based on key inside the object array using desc or asc way.
  • Parameters
  • array Original object array.
  • key the key which used to sort the array.
  • order Sorting Order, You can use constant coming with library for ASC: SortOrder.ASC, DESC: SortOrder.DESC. This is an optional parameter. in default order will be arrange in ASC order.

  So lets say you have above used stWithAgeArray Array. and you need to sort object array by age in descending order. You can use sort method like below.

  const descAgeStudents = sort(stWithAgeArray, 'age', SortOrder.DESC);
  

  and then you have below mentioned object array which is coming from an API.

  So the order will be arranged age descending order like below.

  [
      { name: 'Student Name 1', dateOfBirth: new Date('1990-01-02'), age: 34 },
      { name: 'Student Name 4', dateOfBirth: new Date('1989-09-11'), age: 34 },
      { name: 'Student Name 3', dateOfBirth: new Date('1991-11-14'), age: 32 },
      { name: 'Student Name 2', dateOfBirth: new Date('1995-04-04'), age: 29 }
  ]
  

  Show sort Method Output
• get - This method can be used to get value from an object by providing the key path.
  • Parameters
  • obj Original Object.
  • keyPath Key path which will be used to retrieve value. when you call this method, your IDE will suggest available keypaths

  So lets say you have below mentioned type of Object

  type Person = {
      name: string,
      age: number,
      location: {
          city: {
              name: string,
              zipCode: string
          },
          country: string
      }
  }
  

  And then lets say you need to retrieve city name of a person from below mentioned person information

  const person: Person = {
      name: 'Test Person 1',
      age: 30,
      location: {
          city: {
              name: 'Copanhagen',
              zipCode: '1050'
          },
          country: 'Denmark'
      }
  }
  

  So now you need to get the city name. you can use the get method as mentioned below.

  const personCity = get(person, 'location.city')

  So then you can have city value as Copanhagen

  Show get Method Output
• getKeyVal - This method is kind of similar to get method. But here, by using this method, You can directly get value in an object by using key. Will use the same example as above Let say you need to get the zipCode value for above person using this method. You can use it as below.
  • Parameters
  • obj Original Object.
  • key key which needs to be retrieved

  And then lets say you need to retrieve city name of a person from below mentioned person information

  const personZipCode = getKeyVal(person, 'zipCode')
  

  So then, you can directly get the value of zipcode which is 1050 But, let's say you have duplicated key names inside nested object. Then, this method will only retieve the first finding value.

  Show getKeyVal Method Output

Email Validators

• validateEmail - Check given email address is valid.
  • Parameters
  • email Email Address.

  Assume we have this email:

  test@test.com
  

  const validateSingleEmail = validateEmail('test@test.com')
  

  Validate Email
• getEmail - Get email from nested key path (if email address is valid)
  • Parameters
  • obj Original Object
  • path key path

  Assume we have this is the object:

  type User = {
      name: string
      contact: {
          email: EmailBasic
          address: string
      }
  }
  

  EmailBasic is a type coming with this package which you can use

  const userData: User = {
      name: 'heshan',
      contact: {
          email: 'test@test.com',
          address: 'Malmö',
      },
  }
  

  try {
      const emailAddress = getEmail(userData, 'contact.email')
  } catch (ex) {
      console.log(ex)
  }
  

  Get Email Address
• validateEmailObject - In Same way you can use this method which will return the entire object, if the email address is valid
  • Parameters
  • obj Original Object
  • path key path

  
  try {
      return validateEmailObject(userData, 'contact.email')
  } catch (ex) {
      return ex
  }
                  

• autoValidateEmail - Validate an object if the object contains key which contains word 'email'
  • Parameters
  • obj Original Object

  We can use the same object as above but this time we will put an invalid email

  type User = {
      name: string
      contact: {
          email: EmailBasic
          address: string
      }
  }
  

  EmailBasic is a type coming with this package which you can use

  const userData: User = {
      name: 'heshan',
      contact: {
          email: 'test@test',
          address: 'Malmö',
      },
  }
  

  try {
      const emailObj = autoValidateEmail(userData)
  } catch (ex) {
      console.log(ex)
  }
  

  Validate Email Address

Form Data Mapping

• getFormData - Can directly retieve form input element data as an object
  • Parameters
  • event Submit Event
  Typescript Version

  
  type EmailUser = {
      name: string
      email: EmailBasic
  }
  
  document.getElementById('formId').addEventListener('submit', (event: SubmitEvent) => {
      try {
          return getFormData(e) as EmailUser
      } catch (ex) {
          return ex  
      }
  })
                  

  React Version

  
  <form id='formId' onSubmit={handleSubmit}></form>
  
  
  handleSubmit = (event) => {
      try {
          const formData = getFormData(event) as EmailUser
      } catch (ex) {
          console.error(ex);
      }
  };
                  

  Improvement with v1.2.1

  With minor version update, you can use new attribute called decimal. If an input field contains attribute decimal, form submission will validate input field and if input field contains non decimal value, form submission will trigger an error

  
  <input name='amount' decimal/>
                  

  If there is an error with decimal, you can see error like

  {"name":"DECIMAL_ERROR","message":"amount"}

  Message will contain error input field name

  Submit

Nested Object Array Re-Order

• Lets say you want to reorder nested object array by providing from the nested key to be used for reorder

  Lets say you have this data set

  
  type InnerStudent = {
      studentName: string
      age: number
  }
                      
  type Class = {
      className: string
      year: string
      studentData: {
          students: Array
      }
  }
                      
  type School = {
      schoolName: string
      address: string
      classes: Array
  }
                  

  You can get reordered result by using below method with nested key path to be reordered as the 2nd paramater

  const reordered = reOrder(schoolData, 'classes.studentData.students.studentName')