simplemap-ts-utility
v1.3.1
Published
SimpleMap Typescript Utility Module
Downloads
8
Readme
SimpleMap Typescript Utility Module (simplemap-ts-utility)
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.
Installation
Install simplemap-ts-utility with npm
npm i simplemap-ts-utility
- npm package: https://www.npmjs.com/package/simplemap-ts-utility
- Demo: https://heshansw.github.io/simplemap/
How to run locally
- First you need to download the code from github repository: https://github.com/heshansw/simplemap
- Then run
npm i
on root folder to install dev dependencies - Finally run
npm start
(which will open webpack serve)
Available utility methods
These are the available Typescript object manipulation 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 }
And we have this object
const personOne: Person = { name: 'Test Name', age: 15, country: 'Sweden', }
Lets assume we need to extract name and age, and then create a new Object. Then we can use extract method.
let personNameAge: Partial<Person> = extract(['name', 'age'])(personOne)
personNameAge will contain name and age
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.
Parameters
- First Parameters
- key 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 that you have this object 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)
so then new changedStudent object will looks like below.
{ name: 'Student Name 1', age: 18, ageAfterTenYears: 28 }
- First Parameters
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, 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 }: Partial<StudentNew>, today = new Date() ): number => (dateOfBirth && today.getMonth() < dateOfBirth.getMonth()) || (today.getMonth() === (dateOfBirth as Date).getMonth() && today.getDate() < (dateOfBirth as Date).getDate()) ? today.getFullYear() - (dateOfBirth as Date).getFullYear() - 1 : today.getFullYear() - (dateOfBirth as Date).getFullYear() const altStudentOne = changeO('age', calcAge)(studentOne)
Then new altStudentOne object will looks like below
{ name: 'Student Name 1', dateOfBirth: new Date('1990-01-01'), age: 34 }
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: Array<Partial<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 } ]
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 } ]
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)
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, }, ]
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
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
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.Note: this method will be improved with the next version
Improvements
Email Validators (Available with v1.1.0)
validateEmail Check given email address is valid.
Parameters
- email Email Address (EmailBasic type which is coming with this package)
Assume we have this email:
[email protected]
You can use below mentod to validate this email address
const validateSingleEmail = validateEmail('[email protected]')
EmailBasic type from this custom basic type, you can validate basic email on development
getEmail Check given email address is valid.
Parameters
- email Email Address (EmailBasic type which is coming with this package)
Assume we have this email:
[email protected]
You can use below mentod to validate this email address
const validateSingleEmail = validateEmail('[email protected]')
if email is valid, email will be returned. otherwise error exception will get returned.
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
You can use below mentod to validate object email
try { return validateEmailObject(userData, 'contact.email') } catch (ex) { return ex }
if email is valid, email will be returned. otherwise error exception will get returned.
autoValidateEmail Validate an object if the object contains key which contains word 'email'
Parameters
- obj Original Object
Lets say you have an object which needs to be validated if the object has any key value with key contains word 'email'. Then you can use this method.
Lets say you have below mentioned object
const userDataError: User = { name: 'heshan', contact: { email: 'test@#.c', address: 'Malmö', }, }
So this object has an invalid email address. So this will return Error.
try { return autoValidateEmail(userData) } catch (ex) { return ex }
if email is valid, email will be returned. otherwise error exception will get returned.
Error: INVALID_EMAIL
Form Value Mappers (Available with v1.2.0)
getFormData Can map form data directly to object using this method. If form has an input type with email, this method will use our own validateEmail method and validate the email input value.
Parameters
- event Submit Event
Need to pass form Submit event.
Lets say you have below mentioned form (Please note that this example uses React. But this feature can be used with any framework/library or with vanilla Typescript / Javascript). But input name is required
<form id="formDataModel" onSubmit="{handleSubmit}"> <input placeholder="name" required name="name" type="text" /> <input placeholder="email" required name="email" type="email" /> <input placeholder="grade" name="grade" type="text" /> <button type="submit">Submit</button> </form>
So this object has an invalid email address. So this will return Error.
type EmailUser = { name: string email: EmailBasic } handleSubmit = (event: SubmitEvent) => { try { const formData = getFormData(event) as EmailUser } catch (ex) { console.error(ex) } }
Please wrap this method with a try catch block. If there is an issue with form data validations, the event will go to catch block. for an example below error will be triggered on invalid email address
Error: INVALID_EMAIL
For this example, when the form is submitted, formData will be like below,
{ "name": "John", "email": "[email protected]", "grade": "A" }
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
Further improvements on this method and form related improvements will be there will next versions.
Reorder Nested Object Array (Available with v1.3.0)
Now you can reorder nested object array on ASC or DESC order and return reordered object in same structure as the original object
reOrder Reorder nested object array
Parameters
- originalObject Original Object
- keyPath Nested Key Path to be reordered
- SortOrder Sorting Order (SortOrder.ASC for Ascending and SortOrder.DESC for descending)
Lets say you have this data set
{ "schoolName": "Doe School", "address": "Stockholm", "classes": [ { "className": "Class 01", "year": "Year 01", "studentData": { "students": [ { "studentName": "Philip Larry", "age": 16 }, { "studentName": "John Doe", "age": 18 }, { "studentName": "Alex Numan", "age": 15 }, { "studentName": "Joe Max", "age": 20 }, { "studentName": "Remy Max", "age": 21 } ] } }, { "className": "Class 02", "year": "Year 01", "studentData": { "students": [ { "studentName": "Bale Larry", "age": 16 }, { "studentName": "John Doe", "age": 18 }, { "studentName": "Andersson", "age": 15 }, { "studentName": "Joe Max", "age": 20 } ] } } ] }
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' )
So studentName reordered object will look like below
{ "schoolName": "Doe School", "address": "Stockholm", "classes": [ { "className": "Class 01", "year": "Year 01", "studentData": { "students": [ { "studentName": "Alex Numan", "age": 15 }, { "studentName": "Joe Max", "age": 20 }, { "studentName": "John Doe", "age": 18 }, { "studentName": "Philip Larry", "age": 16 }, { "studentName": "Remy Max", "age": 21 } ] } }, { "className": "Class 02", "year": "Year 01", "studentData": { "students": [ { "studentName": "Andersson", "age": 15 }, { "studentName": "Bale Larry", "age": 16 }, { "studentName": "Joe Max", "age": 20 }, { "studentName": "John Doe", "age": 18 } ] } } ] }