@koine/utils 1.0.74 → 1.0.77

package/capitalize.d.ts

@@ -4,5 +4,5 @@
  * @category text
  * @see https://stackoverflow.com/a/11409944/1938970
  */
-export declare function capitalize<T extends string>(text?: null | T): "" | Capitalize<T>;
+export declare function capitalize<T extends string>(string: null | T): Capitalize<T>;
 export default capitalize;

package/capitalize.js

@@ -4,9 +4,9 @@
  * @category text
  * @see https://stackoverflow.com/a/11409944/1938970
  */
-export function capitalize(text) {
-    return text
-        ? (text.charAt(0).toUpperCase() + text.slice(1))
-        : "";
+export function capitalize(string) {
+    var ensuredString = string || "";
+    return (ensuredString.charAt(0).toUpperCase() +
+        ensuredString.slice(1));
 }
 export default capitalize;

package/getParamAsInt.d.ts

@@ -6,7 +6,7 @@
  * @category location
  *
  * @param {string} [raw] - The _raw_ query parameter
- * @param {number} [fallback=1] - Fallback value, `1` by default
+ * @param {number} [fallback] - Fallback number, we return `null` if not provided
  */
-export declare function getParamAsInt(raw?: string | string[], fallback?: number): number;
+export declare function getParamAsInt<TFallback extends number | null | undefined>(raw?: string | string[], fallback?: TFallback): number | TFallback;
 export default getParamAsInt;

package/getParamAsInt.js

@@ -7,10 +7,14 @@ import getParamAsString from "./getParamAsString";
  * @category location
  *
  * @param {string} [raw] - The _raw_ query parameter
- * @param {number} [fallback=1] - Fallback value, `1` by default
+ * @param {number} [fallback] - Fallback number, we return `null` if not provided
  */
 export function getParamAsInt(raw, fallback) {
-    if (fallback === void 0) { fallback = 1; }
-    return parseInt(getParamAsString(raw) || String(fallback), 10);
+    if (fallback === void 0) { fallback = null; }
+    var string = getParamAsString(raw);
+    if (string) {
+        return parseInt(string, 10);
+    }
+    return fallback;
 }
 export default getParamAsInt;

package/getUrlHashParams.d.ts

@@ -1,8 +1,8 @@
 import { type AnyQueryParams } from "./location";
 /**
  * It returns the "query params" as an object extracting it from the given `hash`
- *string or, if not provided, failling back reading the `location.hash`
-
+ * string or, if not provided, failling back reading the `location.hash`
+ *
  * @category location
  */
 export declare function getUrlHashParams<T extends NonNullable<AnyQueryParams>>(hash?: string): T;

package/getUrlHashParams.js

@@ -1,7 +1,7 @@
 /**
  * It returns the "query params" as an object extracting it from the given `hash`
- *string or, if not provided, failling back reading the `location.hash`
-
+ * string or, if not provided, failling back reading the `location.hash`
+ *
  * @category location
  */
 export function getUrlHashParams(hash) {

package/getUrlHashPathname.d.ts

@@ -1,6 +1,6 @@
 /**
  * It returns the "pathname" cleaned up from the `#` and the initial slashes
- *  extracting it from the given `hash` string or, if not provided, failling
+ * extracting it from the given `hash` string or, if not provided, failling
  * back reading the `location.hash`
  *
  * @category location

package/getUrlHashPathname.js

@@ -1,6 +1,6 @@
 /**
  * It returns the "pathname" cleaned up from the `#` and the initial slashes
- *  extracting it from the given `hash` string or, if not provided, failling
+ * extracting it from the given `hash` string or, if not provided, failling
  * back reading the `location.hash`
  *
  * @category location

package/getZonedDate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * It returns a `Date` object from a date `string` adjusted on the user timeZone,
+ * if a timeZone is not provided we try getting it from the `Intl` browwser native
+ * API. It gracefully falls back returning a _non-timezone-based_ `Date`.
+ *
+ * @category date
+ *
+ * @resources
+ * - to get the timeZone client side see [this article](https://attacomsian.com/blog/javascript-current-timezone)
+ * - for converting the date based on the time zone [date-fns docs](https://date-fns.org/v2.27.0/docs/Time-Zones) and [date-fns-tz docs](https://github.com/marnusw/date-fns-tz)
+ *
+ * @param dateString A parseable date as string, `Z` is automatically suffixed if not present to correctly get time zone based time from a UTC date.
+ * @param timeZone Optionally pass a timeZone (e.g. from user preference or from the server), it falls back trying to read it from the `Intl` browwser native API.
+ */
+export declare function getZonedDate(dateString?: string, timeZone?: string): Date;
+export default getZonedDate;

package/getZonedDate.js

@@ -0,0 +1,37 @@
+import utcToZonedTime from "date-fns-tz/esm/utcToZonedTime";
+import isBrowser from "./isBrowser";
+/**
+ * It returns a `Date` object from a date `string` adjusted on the user timeZone,
+ * if a timeZone is not provided we try getting it from the `Intl` browwser native
+ * API. It gracefully falls back returning a _non-timezone-based_ `Date`.
+ *
+ * @category date
+ *
+ * @resources
+ * - to get the timeZone client side see [this article](https://attacomsian.com/blog/javascript-current-timezone)
+ * - for converting the date based on the time zone [date-fns docs](https://date-fns.org/v2.27.0/docs/Time-Zones) and [date-fns-tz docs](https://github.com/marnusw/date-fns-tz)
+ *
+ * @param dateString A parseable date as string, `Z` is automatically suffixed if not present to correctly get time zone based time from a UTC date.
+ * @param timeZone Optionally pass a timeZone (e.g. from user preference or from the server), it falls back trying to read it from the `Intl` browwser native API.
+ */
+export function getZonedDate(dateString, timeZone) {
+    if (dateString === void 0) { dateString = ""; }
+    if (!dateString.endsWith("Z"))
+        dateString += "Z";
+    if (!timeZone && isBrowser) {
+        try {
+            timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        }
+        catch (e) {
+            if (process.env["NODE_ENV"] !== "production") {
+                console.warn("[@koine/utils:getZonedDate] failed reading timeZone, error", e);
+            }
+            // no need to do anything here, it just means `Intl` failed, probably
+            // because the browser does not support it
+        }
+    }
+    return timeZone
+        ? utcToZonedTime(new Date(dateString), timeZone)
+        : new Date(dateString);
+}
+export default getZonedDate;

package/index.d.ts

@@ -28,6 +28,7 @@ export * from "./getUrlHashParams";
 export * from "./getUrlHashPathname";
 export * from "./getUrlPathnameParts";
 export * from "./getUrlQueryParams";
+export * from "./getZonedDate";
 export * from "./imgEmptyPixel";
 export * from "./isAnyObject";
 export * from "./isArray";

package/index.js

@@ -29,6 +29,7 @@ export * from "./getUrlHashParams";
 export * from "./getUrlHashPathname";
 export * from "./getUrlPathnameParts";
 export * from "./getUrlQueryParams";
+export * from "./getZonedDate";
 export * from "./imgEmptyPixel";
 export * from "./isAnyObject";
 export * from "./isArray";

package/node/capitalize.js

@@ -7,10 +7,10 @@ exports.capitalize = void 0;
  * @category text
  * @see https://stackoverflow.com/a/11409944/1938970
  */
-function capitalize(text) {
-    return text
-        ? (text.charAt(0).toUpperCase() + text.slice(1))
-        : "";
+function capitalize(string) {
+    var ensuredString = string || "";
+    return (ensuredString.charAt(0).toUpperCase() +
+        ensuredString.slice(1));
 }
 exports.capitalize = capitalize;
 exports.default = capitalize;

package/node/getParamAsInt.js

@@ -10,11 +10,15 @@ var getParamAsString_1 = require("./getParamAsString");
  * @category location
  *
  * @param {string} [raw] - The _raw_ query parameter
- * @param {number} [fallback=1] - Fallback value, `1` by default
+ * @param {number} [fallback] - Fallback number, we return `null` if not provided
  */
 function getParamAsInt(raw, fallback) {
-    if (fallback === void 0) { fallback = 1; }
-    return parseInt((0, getParamAsString_1.default)(raw) || String(fallback), 10);
+    if (fallback === void 0) { fallback = null; }
+    var string = (0, getParamAsString_1.default)(raw);
+    if (string) {
+        return parseInt(string, 10);
+    }
+    return fallback;
 }
 exports.getParamAsInt = getParamAsInt;
 exports.default = getParamAsInt;

package/node/getUrlHashParams.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUrlHashParams = void 0;
 /**
  * It returns the "query params" as an object extracting it from the given `hash`
- *string or, if not provided, failling back reading the `location.hash`
-
+ * string or, if not provided, failling back reading the `location.hash`
+ *
  * @category location
  */
 function getUrlHashParams(hash) {

package/node/getUrlHashPathname.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUrlHashPathname = void 0;
 /**
  * It returns the "pathname" cleaned up from the `#` and the initial slashes
- *  extracting it from the given `hash` string or, if not provided, failling
+ * extracting it from the given `hash` string or, if not provided, failling
  * back reading the `location.hash`
  *
  * @category location

package/node/getZonedDate.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getZonedDate = void 0;
+var utcToZonedTime_1 = require("date-fns-tz/esm/utcToZonedTime");
+var isBrowser_1 = require("./isBrowser");
+/**
+ * It returns a `Date` object from a date `string` adjusted on the user timeZone,
+ * if a timeZone is not provided we try getting it from the `Intl` browwser native
+ * API. It gracefully falls back returning a _non-timezone-based_ `Date`.
+ *
+ * @category date
+ *
+ * @resources
+ * - to get the timeZone client side see [this article](https://attacomsian.com/blog/javascript-current-timezone)
+ * - for converting the date based on the time zone [date-fns docs](https://date-fns.org/v2.27.0/docs/Time-Zones) and [date-fns-tz docs](https://github.com/marnusw/date-fns-tz)
+ *
+ * @param dateString A parseable date as string, `Z` is automatically suffixed if not present to correctly get time zone based time from a UTC date.
+ * @param timeZone Optionally pass a timeZone (e.g. from user preference or from the server), it falls back trying to read it from the `Intl` browwser native API.
+ */
+function getZonedDate(dateString, timeZone) {
+    if (dateString === void 0) { dateString = ""; }
+    if (!dateString.endsWith("Z"))
+        dateString += "Z";
+    if (!timeZone && isBrowser_1.default) {
+        try {
+            timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        }
+        catch (e) {
+            if (process.env["NODE_ENV"] !== "production") {
+                console.warn("[@koine/utils:getZonedDate] failed reading timeZone, error", e);
+            }
+            // no need to do anything here, it just means `Intl` failed, probably
+            // because the browser does not support it
+        }
+    }
+    return timeZone
+        ? (0, utcToZonedTime_1.default)(new Date(dateString), timeZone)
+        : new Date(dateString);
+}
+exports.getZonedDate = getZonedDate;
+exports.default = getZonedDate;

package/node/index.js

@@ -32,6 +32,7 @@ tslib_1.__exportStar(require("./getUrlHashParams"), exports);
 tslib_1.__exportStar(require("./getUrlHashPathname"), exports);
 tslib_1.__exportStar(require("./getUrlPathnameParts"), exports);
 tslib_1.__exportStar(require("./getUrlQueryParams"), exports);
+tslib_1.__exportStar(require("./getZonedDate"), exports);
 tslib_1.__exportStar(require("./imgEmptyPixel"), exports);
 tslib_1.__exportStar(require("./isAnyObject"), exports);
 tslib_1.__exportStar(require("./isArray"), exports);

package/node/readCookie.js

@@ -10,7 +10,7 @@ function converterRead(value) {
 function readCookie(name) {
     if (typeof document === "undefined") {
         if (process.env["NODE_ENV"] !== "production") {
-            console.warn("[@koine/utils] readCookie: document is undefined");
+            console.warn("[@koine/utils:readCookie] document is undefined");
         }
         return name ? "" : {};
     }
@@ -28,7 +28,7 @@ function readCookie(name) {
         }
         catch (e) {
             if (process.env["NODE_ENV"] !== "production") {
-                console.warn("[@koine/utils] readCookie: failed to decode", value);
+                console.warn("[@koine/utils:readCookie] failed to decode", value);
             }
         }
     }

package/node/setCookie.js

@@ -4,6 +4,7 @@ exports.setCookie = void 0;
 var tslib_1 = require("tslib");
 var cookie_1 = require("./cookie");
 var isNumber_1 = require("./isNumber");
+var isUndefined_1 = require("./isUndefined");
 function converterWrite(value) {
     return encodeURIComponent(value).replace(/%(2[346BF]|3[AC-F]|40|5[BDE]|60|7[BCD])/g, decodeURIComponent);
 }
@@ -19,9 +20,9 @@ function setCookie(name, value, attributes) {
     // eslint-disable-next-line prefer-const
     var expires = attributes.expires, restAttrs = tslib_1.__rest(attributes, ["expires"]);
     var cleanedAttrs = tslib_1.__assign(tslib_1.__assign({ expires: "" }, cookie_1.defaultAttributesClient), restAttrs);
-    if (typeof document === "undefined") {
+    if ((0, isUndefined_1.default)(document)) {
         if (process.env["NODE_ENV"] !== "production") {
-            console.warn("[@koine/utils] cookie setCookie: document is undefined");
+            console.warn("[@koine/utils:setCookie] document is undefined");
         }
         return undefined;
     }

package/package.json

@@ -5,9 +5,10 @@
   "typings": "./index.d.ts",
   "dependencies": {},
   "peerDependencies": {
+    "date-fns-tz": "^1.3.7",
     "tslib": "^2.4.0"
   },
-  "version": "1.0.74",
+  "version": "1.0.77",
   "module": "./index.js",
   "types": "./index.d.ts"
 }

package/readCookie.js

@@ -7,7 +7,7 @@ function converterRead(value) {
 export function readCookie(name) {
     if (typeof document === "undefined") {
         if (process.env["NODE_ENV"] !== "production") {
-            console.warn("[@koine/utils] readCookie: document is undefined");
+            console.warn("[@koine/utils:readCookie] document is undefined");
         }
         return name ? "" : {};
     }
@@ -25,7 +25,7 @@ export function readCookie(name) {
         }
         catch (e) {
             if (process.env["NODE_ENV"] !== "production") {
-                console.warn("[@koine/utils] readCookie: failed to decode", value);
+                console.warn("[@koine/utils:readCookie] failed to decode", value);
             }
         }
     }

package/setCookie.js

@@ -1,6 +1,7 @@
 import { __assign, __rest } from "tslib";
 import { defaultAttributesClient } from "./cookie";
 import isNumber from "./isNumber";
+import isUndefined from "./isUndefined";
 function converterWrite(value) {
     return encodeURIComponent(value).replace(/%(2[346BF]|3[AC-F]|40|5[BDE]|60|7[BCD])/g, decodeURIComponent);
 }
@@ -16,9 +17,9 @@ export function setCookie(name, value, attributes) {
     // eslint-disable-next-line prefer-const
     var expires = attributes.expires, restAttrs = __rest(attributes, ["expires"]);
     var cleanedAttrs = __assign(__assign({ expires: "" }, defaultAttributesClient), restAttrs);
-    if (typeof document === "undefined") {
+    if (isUndefined(document)) {
         if (process.env["NODE_ENV"] !== "production") {
-            console.warn("[@koine/utils] cookie setCookie: document is undefined");
+            console.warn("[@koine/utils:setCookie] document is undefined");
         }
         return undefined;
     }