hlp 3.6.3 → 3.6.5

package/README.md

@@ -4,7 +4,7 @@
 
 ## motivation
 
-hlp is a lightweight javascript utility library that provides essential helpers for everyday coding tasks. it offers intuitive methods for variable existence checks, type validation, string manipulation, date operations, and more. designed with simplicity in mind, hlp eliminates boilerplate code and makes common programming patterns more concise and readable, allowing developers to focus on building features rather than writing repetitive utility code.
+this is a lightweight javascript utility library that provides essential helpers for everyday coding tasks. it offers intuitive methods for variable existence checks, type validation, string manipulation, date operations, and more. designed with simplicity in mind, `hlp` eliminates boilerplate code and makes common programming patterns more concise and readable, allowing developers to focus on building features rather than writing repetitive utility code.
 
 ## installation
 
@@ -41,6 +41,14 @@ hlp.v( vrbl, 'default' )
 // get first variable that exists, otherwise ''
 hlp.v( vrbl1, vrbl2, vrbl3 )
 
+// truthness
+if( hlp.true(vrbl) ) {}
+if( hlp.false(vrbl) ) {}
+
+// be aware, that hlp.true is not always the logic negation of hlp.false
+hlp.true(null) // false
+hlp.false(null) // false
+
 // loop over arrays/objects only if possible
 hlp.loop(['foo','bar','baz'], (vrbl__value) => {});
 hlp.loop(['foo','bar','baz'], (vrbl__value, vrbl__key) => {});
@@ -49,6 +57,19 @@ hlp.loop([], (vrbl__value, vrbl__key) => { }) // does nothing
 hlp.loop({}, (vrbl__value, vrbl__key) => { }) // does nothing
 hlp.loop(null, (vrbl__value, vrbl__key) => { }) // does nothing
 
+// if you are unsure, if a variable is even set before checking its existence,
+// simply put it inside this helper function
+// that works because javascript only evaluates the content
+// of the inner callback (or closure) when it is actually executed.
+if( hlp.x(() => vrbl) )
+if( hlp.nx(() => vrbl)  )
+if( hlp.true(() => vrbl) )
+if( hlp.false(() => vrbl)  )
+if( hlp.v(() => vrbl) === 'foo' )
+if( hlp.v(() => vrbl) == 1337 )
+hlp.v(() => vrbl)
+hlp.loop((() => vrbl), (vrbl__value, vrbl__key) => { })
+
 // capitalize
 hlp.capitalize('foo') // Foo
 
@@ -598,20 +619,43 @@ hlp.animate(
 ).then(() => { console.log('done'); });
 ```
 
-## notes
+## php implementation
+
+there is also a php implemenation [stringhelper](https://github.com/vielhuber/stringhelper) with similiar functions available.
+
+## testing
+
+`npm run js:tests`
+
+## recommendations
+
+### existence
+
+```js
+if (foo) {} // ⚠️ be aware of: '0'/[]/{}
+if (foo?.prop) {}
+if (foo?.someFun1()?.someFun2()?.getName()) {}
+```
+
+### truthness
+
+```js
+if (foo === true) {}
+if (foo?.prop === true) {}
+if (foo?.someFun1()?.someFun2()?.getName() === true) {}
+```
 
-### alternative safe patterns
+### comparison
 
 ```js
-if( Object.keys(obj).length === 0 && obj.constructor === Object ) {}
-if (typeof arr !== 'undefined' && arr.length > 0) {}
-for(const [obj__key, obj__value] of Object.entries(obj)) {}
+if (foo === 'foo') {}
+if (foo?.prop === 'foo') {}
+if (foo?.someFun1()?.someFun2()?.getName() === 'foo') {}
 ```
 
-### equality
+these recommendations ground on the fact, that js has a lot of pitfalls, when comparing loosely:
 
 ```js
-// js has a lot of pitfalls, when comparing loosely
 if( '' == [] ) // true
 if( '' == [''] ) // true
 if( '' == 0 ) // true
@@ -625,56 +669,25 @@ if( 0 == [] ) // true
 if( 0 == [''] ) // true
 if( [0] == false ) // true
 if( [0] == 0 ) // true
+```
+
+also don't forget those delicacies:
 
-// also don't forget those delicacies
+```js
 0 === -0 // true
 NaN === NaN // false
 (![]+[])[+[]]+(![]+[])[+!+[]]+([![]]+[][[]])[+!+[]+[+[]]]+(![]+[])[!+[]+!+[]] === 'fail' // true
+```
 
-// this non-strict equality is symmetric, but not transitive
+this non-strict equality is symmetric, but not transitive:
+
+```js
 a = ''; b = 0; c = [0];
 a == b; // true
 b == c; // true
 c == a; // false
-
-// to overcome this issue, we...
-
-// ...use strict comparison when possible
-if( vrbl === 'foo' ) {}
-
-// ...use loose comparison when appropriate
-if( hlp.getParam('number') == 1337 ) {}
-
-// ...check for truthness / falsiness with these helper methods
-if( hlp.true(vrbl) ) {}
-
-if( hlp.false(vrbl) ) {}
-
-// be aware, that hlp.true is not always the logic negation of hlp.false
-hlp.true(null) // false
-hlp.false(null) // false
-```
-
-### try
-
-```js
-// if you are unsure, if a variable is even set before checking its existence,
-// simply put it inside this helper function
-if( hlp.x(() => vrbl) )
-if( hlp.nx(() => vrbl)  )
-if( hlp.true(() => vrbl) )
-if( hlp.false(() => vrbl)  )
-if( hlp.v(() => vrbl) === 'foo' )
-if( hlp.v(() => vrbl) == 1337 )
-echo hlp.v(() => vrbl)
-// that works because javascript only evaluates the content of the inner callback (or closure) when it is actually executed.
-hlp.loop((() => vrbl), (vrbl__value, vrbl__key) => { })
 ```
 
-## php implementation
-
-there is also a php implemenation [stringhelper](https://github.com/vielhuber/stringhelper) with similiar functions available.
-
 ## appendix
 
 ### existence matrix

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "hlp",
-    "version": "3.6.3",
+    "version": "3.6.5",
     "main": "_js/_build/script.js",
     "files": [
         "_js/_build/*.js",