@spfxappdev/utility
This package contains some useful extensions for String
and Array
and some more functions that need less lines of code and make the code more readable.
Installation
npm i @spfxappdev/utility
Demo
You can find some exmplaes/demo applications at codesandbox.io or GitHub
Functions
Usage
- import one of the functions in your project (in this example the function
isset
is imported)
import { isset } from '@spfxappdev/utility';
API
- asyncFn
- cssClasses
- getDeepOrDefault
- getUrlParameter
- isFunction
- isNullOrEmpty
- isset
- issetDeep
- isValidEmail
- promiseQueue
- randomString
- replaceNonAlphanumeric
- stripHTML
- toBoolean
asyncFn
A wrapper function to handle a await function and their results/errors.
Examples
Instead of using this:
try {
const result = await myAsyncFunction();
console.log(result);
//Do things with result
}
catch (error) {
console.error("An error occurred", error);
throw "Whatever";
}
You can use the asyncFn
-function like this
import { asyncFn } from '@spfxappdev/utility';
const [result, error] = await asyncFn(myAsyncFunction);
if(error) {
throw "Whatever";
}
console.log(result);
//Do things with result
cssClasses
A utility function for conditionally joining css class names together.
Examples
import { cssClasses } from '@spfxappdev/utility';
cssClasses('spfx-app-dev', 'theme'); // => 'spfx-app-dev theme'
cssClasses('spfx-app-dev', { theme: false }); // => 'spfx-app-dev'
cssClasses({ 'spfx-app-dev': true }); // => 'spfx-app-dev'
cssClasses({ 'spfx-app-dev': false }); // => ''
cssClasses({ spfx-app-dev: true }, { theme: true }); // => 'spfx-app-dev theme'
cssClasses({ spfx-app-dev: true, theme: true }); // => 'spfx-app-dev theme'
cssClasses('spfx-app-dev', { theme: true, active: false }, 'item'); // => 'spfx-app-dev theme item'
cssClasses(null, false, 'spfx-app-dev', undefined, 0, 1, { theme: null }, ''); // => 'spfx-app-dev'
const arr = ['theme', { active: true, item: false }]; cssClasses('spfx-app-dev', arr); // => 'spfx-app-dev theme active'
getDeepOrDefault
Gets a nested property from an specific object or default, if not isset.
Examples
import { getDeepOrDefault } from '@spfxappdev/utility';
//VARIABLES
const simpleArray: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 }
];
const myObj = {
My: {
nested: {
property: "Hello from nested Property"
}
},
items: simpleArray
};
//VARIABLES END
// try get myObj.My.nested.property
getDeepOrDefault(myObj, "My.nested.property"); //=> "Hello from nested Property"
//ARRAY
getDeepOrDefault(myObj, "items.2") //=> { id: "tA2en", name: "Dev", sequence: 3 }
//TypeSafe
const arr: ISimpleItem[] = getDeepOrDefault<ISimpleItem[]>(myObj, "items");
console.log(arr[0].name);
//Default value
getDeepOrDefault(myObj, "404", "this string is returend as default, because 404 does not exist in myObj")
getUrlParameter
Get's the Value of a specific Url-Parameter
Examples
import { getUrlParameter } from '@spfxappdev/utility';
getUrlParameter('myParam', 'https://spfx-app.dev?myParam=1'); // => '1'
getUrlParameter('myParam2', 'https://spfx-app.dev?myParam=1'); // => null
getUrlParameter('myParam2'); // => Using window.location.href as URL
isFunction
Determines wheter the property is a Function
.
Examples
import { isFunction } from '@spfxappdev/utility';
const myObj = { a: { nestedA: { nestedNestedA: 'a' }}};
const myFunc = () => { return a};
isFunction(myObj); // => false
isFunction(myFunc); // => true
isFunction(undefined) // => false
isNullOrEmpty
Determines if the provided property is null
or empty (or whitespace if string-value).
Examples
import { isNullOrEmpty } from '@spfxappdev/utility';
isNullOrEmpty("this is a string") // ==> false
isNullOrEmpty(1) // ==> false
isNullOrEmpty(() => { }) // ==> true
isNullOrEmpty(null) // ==> true
isNullOrEmpty(undefined) // ==> true
isNullOrEmpty([]) // ==> true
isNullOrEmpty([1,2]) // ==> false
isNullOrEmpty({}) // ==> false
isNullOrEmpty("") // ==> true
isNullOrEmpty(" ") // ==> true
isset
Determines if the provided property is set.
Examples
import { isset } from '@spfxappdev/utility';
isset("this is a string") // ==> true
isset(1) // ==> true
isset(() => { }) // ==> true
isset(null) // ==> false
isset(undefined) // ==> false
isset([]) // ==> true
isset([1,2]) // ==> true
isset({}) // ==> true
isset("") // ==> true
isset(" ") // ==> true
issetDeep
Determines if the provided property is set deep/nested
Examples
import { issetDeep } from '@spfxappdev/utility';
const myObj = {
My: {
nested: {
property: "Hello from nested Property"
}
},
items: [1,2,3,4]
};
issetDeep(myObj, "My.nested.property"); // ==> true
issetDeep(myObj, "items.2"); // ==> true
issetDeep(myObj, "404"); // ==> false
isValidEmail
Checks if the passed value is a valid email
Examples
import { isValidEmail } from '@spfxappdev/utility';
isValidEmail('seryoga@spfx-app.dev'); // ==> true
isValidEmail('spfx-app.dev'); // ==> false
isValidEmail('my@mail.c'); // ==> false
isValidEmail('my@mail.12'); // ==> false
isValidEmail('my@mail.co'); // ==> true
promiseQueue
Executes a list of Promise one after one (in a queu). An Error/reject will not stop the next promise call.
Examples
import { promiseQueue, PromiseQueue, toParameterlessPromiseQueueFunc } from '@spfxappdev/utility';
const promise1 = toParameterlessPromiseQueueFunc(this.dummyPromise, true, 10000);
const promise2 = this.parameterlessPromiseFunc;
const promise3 = toParameterlessPromiseQueueFunc(this.dummyPromise, false, 2000);
const promise4 = toParameterlessPromiseQueueFunc(this.dummyPromise, true, 600);
await promiseQueue([promise1, promise2, promise3, promise4], 0);
//OR (with callback and error-handling)
const promises: Array<PromiseQueue<any>> = [
{ promiseFunc: promise1, callback: onSuccessFunc, onError: onErrorFunc},
{ promiseFunc: promise2, callback: onSuccessFuncPromise, onError: onErrorFunc},
{ promiseFunc: promise3, callback: onSuccessFunc, onError: onErrorFuncPromise},
{ promiseFunc: promise4, callback: onSuccessFunc, onError: onErrorFunc}
];
await promiseQueue(promises, 0)
randomString
Generates a new and random string
Examples
import { randomString } from '@spfxappdev/utility';
randomString(); // ==> tA2en
randomString(15); // ==> G4XBtQcgDSHWdQG
randomString(6, 'abcdef0123456789'); // ==> fe693c ==> random hex color
replaceNonAlphanumeric
Replaces all non-alphanumeric characters (incl. underscores) with the passed value
Examples
import { randomString } from '@spfxappdev/utility';
replaceNonAlphanumeric('This is a text: 1234567890ß!"§$%&/()=?+#____<---->'); // ==> Thisisatext1234567890____
replaceNonAlphanumeric('This is a text: öäü1234567890ß!"§$%&/()=?+#____<---->', '*') // ==> This*is*a*text*****1234567890**************____******
stripHTML
Strips the HTML and returns only the text content
Examples
import { stripHTML } from '@spfxappdev/utility';
stripHTML(`<div class='abc'>Hello <strong>spfxappdev</strong></div>)`) // ==> Hello spfxappdev
stripHTML('Hello spfxappdev'); // ==> Hello spfxappdev
toBoolean
Converts a value to a boolean
Examples
import { toBoolean } from '@spfxappdev/utility';
toBoolean(''); // => false
toBoolean('1'); // => true
toBoolean('42'); // => false
toBoolean(1); // => true
toBoolean(0); // => false
toBoolean(true); // => true
toBoolean(false); // => false
toBoolean(undefined) // => false
String-Extensions
The String Extensions extend the String Prototype. So you can use the following methods directly on a string
variable.
Note: The variable must not be undefined or null. Otherwise an exception is thrown (see example below).
let undefinedString: string;
undefinedString.StartsWith("error"); //Throws an error, because the variable is not defined.
Usage
- import the extensions
import '@spfxappdev/utility/lib/extensions/StringExtensions';
API
Contains
Returns a value indicating whether a specified substring occurs within this string.
Examples
"Hello @spfxappdev/utility".Contains('@SPFxAppDev/Utility'); // ==> true (ignore case)
"Hello @spfxappdev/utility".Contains('@SPFxAppDev/Utility', false); // ==> false
"Hello @spfxappdev/utility".Contains('404'); // ==> false
EndsWith
Determines whether the ending of a string instance matches a specified string.
Examples
"Hello @spfxappdev/utility".EndsWith('@SPFxAppDev/Utility'); // ==> true (ignore case)
"Hello @spfxappdev/utility".EndsWith('@SPFxAppDev/Utility', false); // ==> false
"Hello @spfxappdev/utility".EndsWith('@spfxappdev'); // ==> false
Equals
Determines whether two String objects have the same value.
Examples
"Hello @spfxappdev/utility".Equals('HeLlO @SPFxAppDev/UTILITY'); // ==> true (ignore case)
"Hello @spfxappdev/utility".Equals('HeLlO @SPFxAppDev/UTILITY', false); // ==> false
"Hello @spfxappdev/utility".Equals('404'); // ==> false
IndexOf
Reports the zero-based index of the first occurrence of a specified Unicode character or string within this instance. The method returns -1 if the character or string is not found in this instance.
Examples
"Hello @spfxappdev/utility".IndexOf('@SPFxAppDev/Utility'); // ==> 6 (ignore case)
"Hello @spfxappdev/utility".IndexOf('@SPFxAppDev/Utility', false); // ==> -1
"Hello @spfxappdev/utility".IndexOf('404'); // ==> -1
Insert
Returns a new string in which a specified string is inserted at a specified index position in this instance.
Examples
"Hello @spfxappdev/utility".Insert(5, " from"); // ==> Hello from @spfxappdev/utility
"Hello @spfxappdev/utility".Insert(255, " insert to end"); // ==> Hello @spfxappdev/utility insert to end
IsEmpty
Determines whether a String is empty or whitespace.
Examples
"Hello @spfxappdev/utility".IsEmpty()); // ==> false
"".IsEmpty(); // ==> true
" ".IsEmpty(); // ==> true
StartsWith
Determines whether the beginning of this string instance matches a specified string.
Examples
"Hello @spfxappdev/utility".StartsWith('hello'); // ==> true (ignore case)
"Hello @spfxappdev/utility".StartsWith('hello', false); // ==> false
"Hello @spfxappdev/utility".StartsWith('@spfxappdev'); // ==> false
Array-Extensions
Usage
- import the extensions
import '@spfxappdev/utility/lib/extensions/ArrayExtensions';
API
- AddAt
- Contains
- Count
- FirstOrDefault
- IndexOf
- LastOrDefault
- OrderBy
- OrderByDescending
- OrderByMultiple
- OrderByMultipleDescending
- RemoveAt
- Where
AddAt
Add one or more items at specified index.
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 }
];
myArr.AddAt(0, { id: randomString(), name: "First Item", sequence: 0 });
myArr.AddAt(1, { id: randomString(), name: "Second Item", sequence: 1 });
myArr.AddAt(1000, { id: randomString(), name: "LAST Item", sequence: 10000 });
myArr.AddAt(-3, { id: randomString(), name: "LAST Item - 3", sequence: 10000 });
//Result:
myArr = [
{"id":"Vb9Lq","name":"First Item","sequence":0},
{"id":"aCrdT","name":"Second Item","sequence":1},
{"id":"bjdvY","name":"App","sequence":2},
{"id":"fb80g","name":"LAST Item - 3","sequence":10000},
{"id":"g4JQl","name":"SPFx","sequence":1},
{"id":"oYHgy","name":"Dev","sequence":3},
{"id":"XYcxD","name":"LAST Item","sequence":10000}
];
Contains
Determines whether an array contains a particular element that satisfies the condition
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 }
];
const containsSpfxItem: boolean = myArr.Contains(i => i.name.Equals("spfx"));
console.log(containsSpfxItem); //true
const contains404Item: boolean = myArr.Contains(i => i.name.Equals("404"));
console.log(contains404Item); //false
const multipleConditions: boolean = myArr.Contains(i => i.name.Equals("404") || i.name.Equals("spfx"));
console.log(multipleConditions); // true
const emptyArrayContains: boolean = [].Contains(i => (i as any).name.Equals("404") || (i as any).name.Equals("spfx"));
console.log(emptyArrayContains); //false
Count
Determines whether an array contains a particular element that satisfies the condition
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
{ id: randomString(), name: "App", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 5 }
];
const totalAppItems: number = myArr.Count(i => i.name.Equals("app"));
console.log(totalAppItems); //==> 2
const total404Items: number = myArr.Count(i => i.name.Equals("404"));
console.log(total404Items); // ==> 0
const totalAppOrDevItems: number = myArr.Count(i => i.name.Equals("app") || i.name.Equals("dEv"));
console.log(totalAppOrDevItems); // ==> 5
const emptyArrayCount: number = [].Count(i => (i as any).name.Equals("404") || (i as any).name.Equals("spfx"));
console.log(emptyArrayCount); // ==> 0
FirstOrDefault
Returns the first element of a the array, or the first element that satisfies the condition (by predicateFunc
), or defaultValue
if no element is found.
predicateFunc
is optional. If not specified the first element (index == 0) will be returned or defaultValue
Note: Since v1.1.0 the Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
{ id: randomString(), name: "App", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 5 }
];
const spfxItem: ISimpleItem|null = myArr.FirstOrDefault(i => i.name.Equals("spfx"));
console.log(spfxItem); // ==> { id: "g4JQl", name: "SPFx", sequence: 1 }
const firstItem: ISimpleItem|null = myArr.FirstOrDefault();
console.log(firstItem); // ==> { id: "bjdvY", name: "App", sequence: 2 }
const defaultItem: ISimpleItem|null = myArr.FirstOrDefault(i => i.name.Equals("404"), { id: randomString(), name: "This is item is the default item, because the searched item was not found", sequence: 404 });
console.log(defaultItem); // ==> { id: "6xcPO", name: "This is item is the default item, because the searched item was not found", sequence: 404 }
const defaultNullItem: ISimpleItem|null = myArr.FirstOrDefault(i => i.name.Equals("404"));
console.log(defaultNullItem); // ==> null
IndexOf
Returns the first index of element of a sequence, or -1
if no element is found.
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
{ id: randomString(), name: "App", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 5 }
];
const spfxItemIndex: number = myArr.IndexOf(i => i.name.Equals("spfx"));
console.log(spfxItemIndex); // ==> 1
const notFoundIndex: number = myArr.IndexOf(i => i.name.Equals("404"));
console.log(notFoundIndex); // ==> -1
LastOrDefault
Returns the last element of a the array, or the last element that satisfies the condition (by predicateFunc
), or defaultValue
if no element is found.
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
{ id: randomString(), name: "SPFx", sequence: 4 },
{ id: randomString(), name: "SPFx", sequence: 5 },
{ id: randomString(), name: "SPFx", sequence: 6 },
{ id: randomString(), name: "Dev", sequence: 1000 }
];
const spfxItem: ISimpleItem|null = myArr.LastOrDefault(i => i.name.Equals("spfx"));
console.log(spfxItem); // ==> {id: 't9Rhm', name: 'SPFx', sequence: 6}
const lastItem: ISimpleItem|null = myArr.LastOrDefault();
console.log(lastItem); // ==> {id: 'Uqyvt', name: 'Dev', sequence: 1000}
const defaultItem: ISimpleItem|null = myArr.LastOrDefault(i => i.name.Equals("404"), { id: randomString(), name: "This is item is the default item, because the searched item was not found", sequence: 404 });
console.log(defaultItem); // ==> {id: 'L3g64', name: 'This is item is the default item, because the searched item was not found', sequence: 404}
const defaultNullItem: ISimpleItem|null = myArr.LastOrDefault(i => i.name.Equals("404"));
console.log(defaultNullItem); // ==> null
const emptyArrCheck: ISimpleItem|null = [].LastOrDefault(i => (i as any).name.Equals("404"));
console.log(emptyArrCheck); // ==> null
OrderBy
Sorts the elements of a sequence in ascending order.
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 }
];
myArr.OrderBy(i => i.sequence);
console.log(myArr); // ==> [{id: 'g4JQl', name: 'SPFx', sequence: 1},{id: 'bjdvY', name: 'App', sequence: 2},{id: 'oYHgy', name: 'Dev', sequence: 3}]
myArr.OrderBy(i => i.name);
console.log(myArr); // ==> [{id: 'bjdvY', name: 'App', sequence: 2},,{id: 'oYHgy', name: 'Dev', sequence: 3},{id: 'g4JQl', name: 'SPFx', sequence: 1}]
OrderByDescending
Sorts the elements of a sequence in descending order.
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 }
];
myArr.OrderByDescending(i => i.sequence);
console.log(myArr); // ==> [{id: 'oYHgy', name: 'Dev', sequence: 3},{id: 'bjdvY', name: 'App', sequence: 2},{id: 'g4JQl', name: 'SPFx', sequence: 1}]
myArr.OrderByDescending(i => i.name);
console.log(myArr); // ==> [{id: 'g4JQl', name: 'SPFx', sequence: 1},{id: 'oYHgy', name: 'Dev', sequence: 3},{id: 'bjdvY', name: 'App', sequence: 2}]
OrderByMultiple
Sorts the elements of a sequence in ascending order (first by a then by b then by c etc.).
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
{ id: randomString(), name: "App", sequence: 1 }
];
myArr.OrderByMultiple([(item) => item.name, (item) => item.sequence]);
console.log(myArr); // ==> [{id: 'EceZ9', name: 'App', sequence: 1},{id: 'bjdvY', name: 'App', sequence: 2},{id: 'oYHgy', name: 'Dev', sequence: 3},{id: 'g4JQl', name: 'SPFx', sequence: 1}]
OrderByMultipleDescending
Sorts the elements of a sequence in descending order (first by a then by b then by c etc.)
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
{ id: randomString(), name: "App", sequence: 1 }
];
myArr.OrderByMultipleDescending([(item) => item.name, (item) => item.sequence]);
console.log(myArr); // ==> [{id: 'g4JQl', name: 'SPFx', sequence: 1},{id: 'oYHgy', name: 'Dev', sequence: 3},{id: 'bjdvY', name: 'App', sequence: 2},{id: 'Kp45S', name: 'App', sequence: 1}]
RemoveAt
Remove the item(s) at specified index
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "First Item", sequence: 0 },
{ id: randomString(), name: "Second Item", sequence: 1 },
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: 'LAST Item - 3', sequence: 10000},
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
{ id: randomString(), name: "App", sequence: 1 },
{ id: randomString(), name: "LAST Item", sequence: 10000 }
];
//Remove 2 items, starting at index 0
myArr.RemoveAt(0, 2);
console.log(myArr); // ==> [{id: 'bjdvY', name: 'App', sequence: 2},{id: 'feIpa', name: 'LAST Item - 3', sequence: 10000},{id: 'g4JQl', name: 'SPFx', sequence: 1},{id: 'oYHgy', name: 'Dev', sequence: 3},{id: '7yL7k', name: 'LAST Item', sequence: 10000}]
//remove the item at index 2
myArr.RemoveAt(2);
console.log(myArr); // ==> [{id: 'bjdvY', name: 'App', sequence: 2},{id: 'feIpa', name: 'LAST Item - 3', sequence: 10000},{id: 'oYHgy', name: 'Dev', sequence: 3},{id: '7yL7k', name: 'LAST Item', sequence: 10000}]
myArr.RemoveAt(-3);
console.log(myArr); // ==> [{id: 'bjdvY', name: 'App', sequence: 2},{id: 'oYHgy', name: 'Dev', sequence: 3},{id: '7yL7k', name: 'LAST Item', sequence: 10000}]
Where
Filters a sequence of values based on a predicate.
Examples
const myArr: ISimpleItem[] = [
{ id: randomString(), name: "App", sequence: 2 },
{ id: randomString(), name: "SPFx", sequence: 1 },
{ id: randomString(), name: "Dev", sequence: 3 },
];
const allItemsWhereSequenceGt1: ISimpleItem[] = myArr.Where(i => i.sequence > 1);
console.log(allItemsWhereSequenceGt1); //==> [{ id: 'bjdvY', name: "App", sequence: 2 },{id: 'oYHgy', name: 'Dev', sequence: 3}]
const notFoundItems: ISimpleItem[] = myArr.Where(i => i.name.Equals("404"));
console.log(notFoundItems); // ==> []