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/

Compatible Libraries and Frameworks

This library is compatible with a range of TypeScript/JavaScript based libraries and frameworks, including:

ReactJS
Angular
NextJS
NestJS
VueJS
NodeJS
Typescript

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
  1. keys Array of keys which needs to be extracted.
  2. 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
    1. key Original key which may needs to use as original key value to calculate new key value.
    2. callback Callback method which will be use to declare new value calculation code
    3. newKey Optional new key to store calculated value
  - Second Parameters
    1. 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
}
```

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
1. newKey key that will be added with calculated value
2. 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
  1. obj Original Object
  2. 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
  1. email Email Address (EmailBasic type which is coming with this package)
  Assume we have this email:
```
test@test.com
```
  You can use below mentod to validate this email address
```
const validateSingleEmail = validateEmail('test@test.com')
```
EmailBasic type from this custom basic type, you can validate basic email on development
getEmail Check given email address is valid.
- Parameters
  1. email Email Address (EmailBasic type which is coming with this package)
  Assume we have this email:
```
test@test.com
```
  You can use below mentod to validate this email address
```
const validateSingleEmail = validateEmail('test@test.com')
```
  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
  1. obj Original Object
  2. 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
  1. 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
  1. 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": "john@example.com", "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
                    }
                ]
            }
        }
    ]
}

🚀 Author

@heshansw

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github/workflows		.github/workflows
.vscode		.vscode
dist		dist
samples		samples
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.prettierrc		.prettierrc
License.txt		License.txt
README.md		README.md
SECURITY.md		SECURITY.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
webpack.config.js		webpack.config.js

License

heshansw/simplemap

Folders and files

Latest commit

History

Repository files navigation

SimpleMap Typescript Utility Module (simplemap-ts-utility)

Introduction

Installation

Compatible Libraries and Frameworks

How to run locally

Available utility methods

Improvements

Email Validators (Available with v1.1.0)

Form Value Mappers (Available with v1.2.0)

Reorder Nested Object Array (Available with v1.3.0)

🚀 Author

About

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Languages