@amekusa/util.js 1.2.1 → 2.1.0

package/README.md

@@ -10,30 +10,47 @@ npm i @amekusa/util.js
 
 ### ES
 ```js
-// A) import functions
-import {
-	arr,
-	isEmpty,
-	clean,
-	merge,
-} from '@amekusa/util.js';
-
-// B) import as an object
-import util from '@amekusa/util.js';
+// Import functions
+import {merge, arr, isEmpty} from '@amekusa/util.js';
+
+// Import categories
+import {gen, time, web, io, sh} from '@amekusa/util.js';
+
+// Import only browser-compatible categories
+import {gen, time, web} from '@amekusa/util.js/browser';
 ```
 
 ### CJS
 ```js
-// A) import functions
-const {
-	arr,
-	isEmpty,
-	clean,
-	merge,
-} = require('@amekusa/util.js');
-
-// B) import as an object
-const util = require('@amekusa/util.js');
+// Import functions
+const {merge, arr, isEmpty} = require('@amekusa/util.js');
+
+// Import categories
+const {gen, time, web, io, sh} = require('@amekusa/util.js');
+
+// Import only browser-compatible categories
+const {gen, time, web} = require('@amekusa/util.js/browser');
+```
+
+### Browser
+```html
+<script src="amekusa.util.br.js"></script>
+<script src="your-script.js"></script>
+```
+
+```js
+// your-script.js
+const {gen, time, web} = amekusa.util;
+```
+
+### Browser with module loading
+```html
+<script type="module" src="your-script.js"></script>
+```
+
+```js
+// your-script.js
+import {gen, time, web} from './amekusa.util.br.es.js';
 ```
 
 ## LICENSE

package/dist/{import/bundle.js → amekusa.util.br.es.js}

@@ -1,4 +1,202 @@
 /*!
+ * === @amekusa/util.js/gen === *
+ * MIT License
+ *
+ * Copyright (c) 2024 Satoshi Soma
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Coerces the given value into an array.
+ * @param {any} x
+ * @return {any[]}
+ */
+function arr(x) {
+	return Array.isArray(x) ? x : [x];
+}
+
+/**
+ * Checks the type of the given value matches with one of the given types.
+ * If a constructor is given to `types`, it checks if `x` is `instanceof` the constructor.
+ * @param {any} x
+ * @param {...string|function} types - Type or Constructor
+ * @return {boolean}
+ */
+function is(x, ...types) {
+	let t = typeof x;
+	for (let i = 0; i < types.length; i++) {
+		let v = types[i];
+		if (typeof v == 'string') {
+			if (v == 'array') {
+				if (Array.isArray(x)) return true;
+			} else if (t == v) return true;
+		} else if (x instanceof v) return true;
+	}
+	return false;
+}
+
+/**
+ * Returns whether the given value can be considered as "empty".
+ * @param {any} x
+ * @return {boolean}
+ */
+function isEmpty(x) {
+	if (Array.isArray(x)) return x.length == 0;
+	switch (typeof x) {
+	case 'string':
+		return !x;
+	case 'object':
+		for (let _ in x) return false;
+		return true;
+	case 'undefined':
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Returns whether the given value can be considered as "empty" or "falsy".
+ * Faster than {@link isEmpty}.
+ * @param {any} x
+ * @return {boolean}
+ */
+function isEmptyOrFalsy(x) {
+	if (!x) return true;
+	if (Array.isArray(x)) return x.length == 0;
+	if (typeof x == 'object') {
+		for (let _ in x) return false;
+	}
+	return false;
+}
+
+/**
+ * @function isEmptyOrFalsey
+ * Alias of {@link isEmptyOrFalsy}.
+ */
+const isEmptyOrFalsey = isEmptyOrFalsy;
+
+/**
+ * Removes "empty" values from the given object or array.
+ * @param {object|any[]} x
+ * @param {number} recurse - Recursion limit
+ * @return {object|any[]} modified `x`
+ */
+function clean(x, recurse = 8) {
+	if (recurse) {
+		if (Array.isArray(x)) {
+			let r = [];
+			for (let i = 0; i < x.length; i++) {
+				let v = clean(x[i], recurse - 1);
+				if (!isEmpty(v)) r.push(v);
+			}
+			return r;
+		}
+		if (typeof x == 'object') {
+			let r = {};
+			for (let k in x) {
+				let v = clean(x[k], recurse - 1);
+				if (!isEmpty(v)) r[k] = v;
+			}
+			return r;
+		}
+	}
+	return x;
+}
+
+/**
+ * Merges the 2nd object into the 1st object recursively (deep-merge). The 1st object will be modified.
+ * @param {object} x - The 1st object
+ * @param {object} y - The 2nd object
+ * @param {object} [opts] - Options
+ * @param {number} opts.recurse=8 - Recurstion limit. Negative number means unlimited
+ * @param {boolean|string} opts.mergeArrays - How to merge arrays
+ * - `true`: merge x with y
+ * - 'push': push y elements to x
+ * - 'concat': concat x and y
+ * - other: replace x with y
+ * @return {object} The 1st object
+ */
+function merge(x, y, opts = {}) {
+	if (!('recurse' in opts)) opts.recurse = 8;
+	switch (Array.isArray(x) + Array.isArray(y)) {
+	case 0: // no array
+		if (opts.recurse && x && y && typeof x == 'object' && typeof y == 'object') {
+			opts.recurse--;
+			for (let k in y) x[k] = merge(x[k], y[k], opts);
+			opts.recurse++;
+			return x;
+		}
+	case 1: // 1 array
+		return y;
+	}
+	// 2 arrays
+	switch (opts.mergeArrays) {
+	case true:
+		for (let i = 0; i < y.length; i++) {
+			if (!x.includes(y[i])) x.push(y[i]);
+		}
+		return x;
+	case 'push':
+		x.push(...y);
+		return x;
+	case 'concat':
+		return x.concat(y);
+	}
+	return y;
+}
+
+/**
+ * Gets a property from the given object by the given string path.
+ * @param {object} obj - Object to traverse
+ * @param {string} path - Property names separated with '.'
+ * @return {any} value of the found property, or undefined if it's not found
+ */
+function dig(obj, path) {
+	path = path.split('.');
+	for (let i = 0; i < path.length; i++) {
+		let p = path[i];
+		if (typeof obj == 'object' && p in obj) obj = obj[p];
+		else return undefined;
+	}
+	return obj;
+}
+
+/**
+ * Substitutes the properties of the given data for the references in the given string.
+ * @param {string} str - String that contains references to the properties
+ * @param {object} data - Object that contains properties to replace the references
+ * @param {object} [opts] - Options
+ * @return {string} a modified `str`
+ */
+function subst(str, data, opts = {}) {
+	let {
+		modifier = null,
+		start = '{{',
+		end   = '}}',
+	} = opts;
+	let ref = new RegExp(start + '\\s*([-.\\w]+)\\s*' + end, 'g');
+	return str.replaceAll(ref, modifier
+		? (_, m1) => (modifier(dig(data, m1), m1, data) || '')
+		: (_, m1) => (dig(data, m1) || '')
+	);
+}var gen=/*#__PURE__*/Object.freeze({__proto__:null,arr:arr,clean:clean,dig:dig,is:is,isEmpty:isEmpty,isEmptyOrFalsey:isEmptyOrFalsey,isEmptyOrFalsy:isEmptyOrFalsy,merge:merge,subst:subst});/*!
  * === @amekusa/util.js/web === *
  * MIT License
  *
@@ -47,15 +245,7 @@ const escHTML_find = new RegExp(`["'<>]|(&(?!${Object.values(escHTML_map).join('
 	// - This avoids double-escaping '&' symbols
 	// - Regex negative match: (?!word)
 
-const escHTML_replace = found => `&${escHTML_map[found]};`;
-
-var web = /*#__PURE__*/Object.freeze({
-__proto__: null,
-escHTML: escHTML,
-escHtml: escHtml
-});
-
-/*!
+const escHTML_replace = found => `&${escHTML_map[found]};`;var web=/*#__PURE__*/Object.freeze({__proto__:null,escHTML:escHTML,escHtml:escHtml});/*!
  * === @amekusa/util.js/time === *
  * MIT License
  *
@@ -225,171 +415,4 @@ function hms(d, format = null) {
  */
 function iso9075(d) {
 	return ymd(d, '-') + ' ' + hms(d, ':');
-}
-
-var time = /*#__PURE__*/Object.freeze({
-__proto__: null,
-addTime: addTime,
-ceil: ceil,
-date: date,
-floor: floor,
-hms: hms,
-iso9075: iso9075,
-localize: localize,
-ms: ms,
-quantize: quantize,
-round: round,
-ymd: ymd
-});
-
-/*!
- * === @amekusa/util.js === *
- * MIT License
- *
- * Copyright (c) 2024 Satoshi Soma
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
-/**
- * Coerces the given value into an array.
- * @param {any} x
- * @return {any[]}
- */
-function arr(x) {
-	return Array.isArray(x) ? x : [x];
-}
-
-/**
- * Alias of `Array.isArray`.
- * @return {boolean}
- */
-const isArray = Array.isArray;
-
-/**
- * Returns whether the given value is a number or a string.
- * @param {any} x
- * @return {boolean}
- */
-function isNumOrStr(x) {
-	switch (typeof x) {
-	case 'number':
-	case 'string':
-		return true;
-	}
-	return false;
-}
-
-/**
- * Returns whether the given value can be considered as "empty".
- * @param {any} x
- * @return {boolean}
- */
-function isEmpty(x) {
-	if (Array.isArray(x)) return x.length == 0;
-	switch (typeof x) {
-	case 'string':
-		return !x;
-	case 'object':
-		if (x === null) return true;
-		for (let i in x) return false;
-	case 'undefined':
-		return true;
-	}
-	return false;
-}
-
-/**
- * Removes "empty" values from the given object or array.
- * @param {object|any[]} x
- * @param {number} recurse - Recursion limit
- * @return {object|any[]} modified `x`
- */
-function clean(x, recurse = 8) {
-	if (recurse) {
-		if (Array.isArray(x)) {
-			let r = [];
-			for (let i = 0; i < x.length; i++) {
-				let I = clean(x[i], recurse - 1);
-				if (!isEmpty(I)) r.push(I);
-			}
-			return r;
-		}
-		if (typeof x == 'object') {
-			let r = {};
-			for (let k in x) {
-				let v = clean(x[k], recurse - 1);
-				if (!isEmpty(v)) r[k] = v;
-			}
-			return r;
-		}
-	}
-	return x;
-}
-
-/**
- * Merges the 2nd object into the 1st object recursively (deep-merge). The 1st object will be modified.
- * @param {object} x - The 1st object
- * @param {object} y - The 2nd object
- * @param {object} [opts] - Options
- * @param {number} opts.recurse=8 - Recurstion limit. Negative number means unlimited
- * @param {boolean|string} opts.mergeArrays - How to merge arrays
- * - `true`: merge x with y
- * - 'push': push y elements to x
- * - 'concat': concat x and y
- * - other: replace x with y
- * @return {object} The 1st object
- */
-function merge(x, y, opts = {}) {
-	if (!('recurse' in opts)) opts.recurse = 8;
-	switch (Array.isArray(x) + Array.isArray(y)) {
-	case 0: // no array
-		if (opts.recurse && x && y && typeof x == 'object' && typeof y == 'object') {
-			opts.recurse--;
-			for (let k in y) x[k] = merge(x[k], y[k], opts);
-			opts.recurse++;
-			return x;
-		}
-	case 1: // 1 array
-		return y;
-	}
-	// 2 arrays
-	switch (opts.mergeArrays) {
-	case true:
-		for (let i = 0; i < y.length; i++) {
-			if (!x.includes(y[i])) x.push(y[i]);
-		}
-		return x;
-	case 'push':
-		x.push(...y);
-		return x;
-	case 'concat':
-		return x.concat(y);
-	}
-	return y;
-}
-
-var main = {
-	arr,
-	isEmpty,
-	clean,
-	merge,
-};
-
-export { arr, clean, main as default, isArray, isEmpty, isNumOrStr, merge, time, web };
+}var time=/*#__PURE__*/Object.freeze({__proto__:null,addTime:addTime,ceil:ceil,date:date,floor:floor,hms:hms,iso9075:iso9075,localize:localize,ms:ms,quantize:quantize,round:round,ymd:ymd});export{arr,clean,dig,gen,is,isEmpty,isEmptyOrFalsey,isEmptyOrFalsy,merge,subst,time,web};

package/dist/amekusa.util.br.es.min.js

@@ -0,0 +1,73 @@
+/*!
+ * === @amekusa/util.js/gen === *
+ * MIT License
+ *
+ * Copyright (c) 2024 Satoshi Soma
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+function e(e){return Array.isArray(e)?e:[e]}function t(e,...t){let r=typeof e;for(let n=0;n<t.length;n++){let i=t[n];if("string"==typeof i){if("array"==i){if(Array.isArray(e))return!0}else if(r==i)return!0}else if(e instanceof i)return!0}return!1}function r(e){if(Array.isArray(e))return 0==e.length;switch(typeof e){case"string":return!e;case"object":for(let t in e)return!1;return!0;case"undefined":return!0}return!1}function n(e){if(!e)return!0;if(Array.isArray(e))return 0==e.length;if("object"==typeof e)for(let t in e)return!1;return!1}const i=n;function u(e,t=8){if(t){if(Array.isArray(e)){let n=[];for(let i=0;i<e.length;i++){let o=u(e[i],t-1);r(o)||n.push(o)}return n}if("object"==typeof e){let n={};for(let i in e){let o=u(e[i],t-1);r(o)||(n[i]=o)}return n}}return e}function o(e,t,r={}){switch("recurse"in r||(r.recurse=8),Array.isArray(e)+Array.isArray(t)){case 0:if(r.recurse&&e&&t&&"object"==typeof e&&"object"==typeof t){r.recurse--;for(let n in t)e[n]=o(e[n],t[n],r);return r.recurse++,e}case 1:return t}switch(r.mergeArrays){case!0:for(let r=0;r<t.length;r++)e.includes(t[r])||e.push(t[r]);return e;case"push":return e.push(...t),e;case"concat":return e.concat(t)}return t}function a(e,t){t=t.split(".");for(let r=0;r<t.length;r++){let n=t[r];if("object"!=typeof e||!(n in e))return;e=e[n]}return e}function c(e,t,r={}){let{modifier:n=null,start:i="{{",end:u="}}"}=r,o=new RegExp(i+"\\s*([-.\\w]+)\\s*"+u,"g");return e.replaceAll(o,n?(e,r)=>n(a(t,r),r,t)||"":(e,r)=>a(t,r)||"")}var s=Object.freeze({__proto__:null,arr:e,clean:u,dig:a,is:t,isEmpty:r,isEmptyOrFalsey:i,isEmptyOrFalsy:n,merge:o,subst:c});
+/*!
+ * === @amekusa/util.js/web === *
+ * MIT License
+ *
+ * Copyright (c) 2024 Satoshi Soma
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */function f(e){return`${e}`.replace(p,y)}const l=f,g={"&":"amp",'"':"quot","'":"apos","<":"lt",">":"gt"},p=new RegExp(`["'<>]|(&(?!${Object.values(g).join("|")};))`,"g"),y=e=>`&${g[e]};`;var d=Object.freeze({__proto__:null,escHTML:f,escHtml:l});
+/*!
+ * === @amekusa/util.js/time === *
+ * MIT License
+ *
+ * Copyright (c) 2024 Satoshi Soma
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */function h(e,t,r="round"){return e.setTime(Math[r](e.getTime()/t)*t),e}function m(e,t=null){let r=[e.getFullYear().toString(),(e.getMonth()+1).toString().padStart(2,"0"),e.getDate().toString().padStart(2,"0")];switch(typeof t){case"string":return r.join(t);case"object":return t?(t.Y=r[0],t.M=r[1],t.D=r[2],t):r;default:if(!t)return r;throw"invalid type"}}function A(e,t=null){let r=[e.getHours().toString().padStart(2,"0"),e.getMinutes().toString().padStart(2,"0"),e.getSeconds().toString().padStart(2,"0")];switch(typeof t){case"string":return r.join(t);case"object":return t?(t.h=r[0],t.m=r[1],t.s=r[2],t):r;default:if(!t)return r;throw"invalid type"}}var j=Object.freeze({__proto__:null,addTime:function(e,t){return e.setTime(e.getTime()+t),e},ceil:function(e,t){return h(e,t,"ceil")},date:function(...e){return e.length&&e[0]?e[0]instanceof Date?e[0]:new Date(...e):new Date},floor:function(e,t){return h(e,t,"floor")},hms:A,iso9075:function(e){return m(e,"-")+" "+A(e,":")},localize:function(e){return e.setTime(e.getTime()-6e4*e.getTimezoneOffset()),e},ms:function(...e){if(!e.length||!e[0])return Date.now();let t=e[0];return"number"==typeof t?t:t instanceof Date?t.getTime():new Date(...e).getTime()},quantize:h,round:function(e,t){return h(e,t,"round")},ymd:m});export{e as arr,u as clean,a as dig,s as gen,t as is,r as isEmpty,i as isEmptyOrFalsey,n as isEmptyOrFalsy,o as merge,c as subst,j as time,d as web};