@naturalcycles/js-lib 14.270.0 → 14.271.0

package/dist/string/url.util.d.ts

@@ -13,3 +13,10 @@ import type { StringMap } from '../types';
  * Goal of this function is to produce exactly same output as URLSearchParams would.
  */
 export declare function _parseQueryString(search: string): StringMap;
+/**
+ * A wrapper around `new URL(href)`, but it returns `null` instead of throwing an error.
+ * While `URL.parse` exists, and behaves similarly, it's not widely supported.
+ *
+ * `null` was chosen instead of `undefined` in the return type union to make it easier to move to `URL.parse` if it ever becomes widely supported.
+ */
+export declare function _toUrlOrNull(url: string | undefined, base?: string): URL | null;

package/dist/string/url.util.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._parseQueryString = _parseQueryString;
+exports._toUrlOrNull = _toUrlOrNull;
 /**
  * Parses `location.search` string (e.g `?a=1&b=2`) into a StringMap, e.g:
  * `{ a: '1', b: '2' }`
@@ -27,3 +28,19 @@ function _parseQueryString(search) {
     });
     return qs;
 }
+/**
+ * A wrapper around `new URL(href)`, but it returns `null` instead of throwing an error.
+ * While `URL.parse` exists, and behaves similarly, it's not widely supported.
+ *
+ * `null` was chosen instead of `undefined` in the return type union to make it easier to move to `URL.parse` if it ever becomes widely supported.
+ */
+function _toUrlOrNull(url, base) {
+    if (typeof url !== 'string')
+        return null;
+    try {
+        return new URL(url, base || undefined);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/types.d.ts

@@ -196,6 +196,13 @@ export type IsoDateTime = Branded<string, 'IsoDateTime'>;
  * @example '2023-09'
  */
 export type MonthId = string;
+/**
+ * Identifies IANA timezone name.
+ * Branded type.
+ *
+ * @example 'America/New_York'
+ */
+export type IanaTimezone = Branded<string, 'IanaTimezone'>;
 /**
  * Branded UnixTimestamp in seconds.
  * Extends (compatible with) `number`.

package/dist-esm/string/url.util.js

@@ -24,3 +24,19 @@ export function _parseQueryString(search) {
     });
     return qs;
 }
+/**
+ * A wrapper around `new URL(href)`, but it returns `null` instead of throwing an error.
+ * While `URL.parse` exists, and behaves similarly, it's not widely supported.
+ *
+ * `null` was chosen instead of `undefined` in the return type union to make it easier to move to `URL.parse` if it ever becomes widely supported.
+ */
+export function _toUrlOrNull(url, base) {
+    if (typeof url !== 'string')
+        return null;
+    try {
+        return new URL(url, base || undefined);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.270.0",
+  "version": "14.271.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/string/url.util.ts

@@ -25,3 +25,19 @@ export function _parseQueryString(search: string): StringMap {
     })
   return qs
 }
+
+/**
+ * A wrapper around `new URL(href)`, but it returns `null` instead of throwing an error.
+ * While `URL.parse` exists, and behaves similarly, it's not widely supported.
+ *
+ * `null` was chosen instead of `undefined` in the return type union to make it easier to move to `URL.parse` if it ever becomes widely supported.
+ */
+export function _toUrlOrNull(url: string | undefined, base?: string): URL | null {
+  if (typeof url !== 'string') return null
+
+  try {
+    return new URL(url, base || undefined)
+  } catch {
+    return null
+  }
+}

package/src/types.ts

@@ -254,6 +254,14 @@ export type IsoDateTime = Branded<string, 'IsoDateTime'>
  */
 export type MonthId = string
 
+/**
+ * Identifies IANA timezone name.
+ * Branded type.
+ *
+ * @example 'America/New_York'
+ */
+export type IanaTimezone = Branded<string, 'IanaTimezone'>
+
 /**
  * Branded UnixTimestamp in seconds.
  * Extends (compatible with) `number`.