@clipboard-health/phone-number 0.2.1 → 0.3.0

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@clipboard-health/phone-number",
   "description": "Phone number utility functions.",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
-    "@clipboard-health/util-ts": "3.12.1",
+    "@clipboard-health/util-ts": "3.12.2",
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@clipboard-health/testing-core": "0.21.1",
-    "libphonenumber-js": "1.12.15"
+    "@clipboard-health/testing-core": "0.21.2",
+    "libphonenumber-js": "1.12.23"
   },
   "keywords": [],
   "license": "MIT",

package/src/index.d.ts

@@ -1 +1,2 @@
 export * from "./lib/formatPhoneNumber";
+export * from "./lib/isValidPhoneNumber";

package/src/index.js

@@ -2,4 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./lib/formatPhoneNumber"), exports);
+tslib_1.__exportStar(require("./lib/isValidPhoneNumber"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/phone-number/src/index.ts"],"names":[],"mappings":";;;AAAA,kEAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/phone-number/src/index.ts"],"names":[],"mappings":";;;AAAA,kEAAwC;AACxC,mEAAyC"}

package/src/lib/formatPhoneNumber.d.ts

@@ -1,5 +1,46 @@
 import { type ServiceResult } from "@clipboard-health/util-ts";
-export declare function formatPhoneNumber(params: {
-    phoneNumber: string;
+import { type WithPhoneNumber } from "./types";
+export interface FormatPhoneNumberParams extends WithPhoneNumber {
     format: "E.164" | "humanReadable";
-}): ServiceResult<string>;
+}
+/**
+ * Formats a phone number to the specified format.
+ *
+ * @param params - The formatting parameters
+ * @param params.phoneNumber - The phone number to format
+ * @param params.format - The desired output format ("E.164" for international format or "humanReadable" for national format)
+ * @returns A ServiceResult containing the formatted phone number or an error
+ *
+ * @example
+ * ```ts
+ * const result = formatPhoneNumber({ phoneNumber: "(555) 123-4567", format: "E.164" });
+ * if (isSuccess(result)) {
+ *   console.log(result.value); // "+15551234567"
+ * }
+ * ```
+ */
+export declare function formatPhoneNumber(params: FormatPhoneNumberParams): ServiceResult<string>;
+/**
+ * Formats a phone number to the specified format, throwing an error if formatting fails.
+ *
+ * This is a convenience function that wraps `formatPhoneNumber` and throws an error
+ * instead of returning a ServiceResult. Use this when you want to handle errors via
+ * exception handling rather than explicit error checking.
+ *
+ * @param params - The formatting parameters
+ * @param params.phoneNumber - The phone number to format
+ * @param params.format - The desired output format ("E.164" for international format or "humanReadable" for national format)
+ * @returns The formatted phone number
+ * @throws Error when the phone number cannot be formatted (invalid format, missing country code, etc.)
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const formatted = formatPhoneNumberOrThrow({ phoneNumber: "(555) 123-4567", format: "E.164" });
+ *   console.log(formatted); // "+15551234567"
+ * } catch (error) {
+ *   console.error("Invalid phone number:", error.message);
+ * }
+ * ```
+ */
+export declare function formatPhoneNumberOrThrow(params: FormatPhoneNumberParams): string;

package/src/lib/formatPhoneNumber.js

@@ -1,8 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatPhoneNumber = formatPhoneNumber;
+exports.formatPhoneNumberOrThrow = formatPhoneNumberOrThrow;
 const util_ts_1 = require("@clipboard-health/util-ts");
 const libphonenumber_js_1 = require("libphonenumber-js");
+/**
+ * Formats a phone number to the specified format.
+ *
+ * @param params - The formatting parameters
+ * @param params.phoneNumber - The phone number to format
+ * @param params.format - The desired output format ("E.164" for international format or "humanReadable" for national format)
+ * @returns A ServiceResult containing the formatted phone number or an error
+ *
+ * @example
+ * ```ts
+ * const result = formatPhoneNumber({ phoneNumber: "(555) 123-4567", format: "E.164" });
+ * if (isSuccess(result)) {
+ *   console.log(result.value); // "+15551234567"
+ * }
+ * ```
+ */
 function formatPhoneNumber(params) {
     const { phoneNumber, format } = params;
     try {
@@ -11,8 +28,38 @@ function formatPhoneNumber(params) {
         });
         return (0, util_ts_1.success)(parsedPhoneNumber.format(format === "E.164" ? "E.164" : "NATIONAL"));
     }
-    catch {
-        return (0, util_ts_1.failure)({ issues: [{ message: "Invalid phone number", code: "INVALID_PHONE_NUMBER" }] });
+    catch (error) {
+        return (0, util_ts_1.failure)({ issues: [{ message: (0, util_ts_1.toError)(error).message, code: "INVALID_PHONE_NUMBER" }] });
     }
 }
+/**
+ * Formats a phone number to the specified format, throwing an error if formatting fails.
+ *
+ * This is a convenience function that wraps `formatPhoneNumber` and throws an error
+ * instead of returning a ServiceResult. Use this when you want to handle errors via
+ * exception handling rather than explicit error checking.
+ *
+ * @param params - The formatting parameters
+ * @param params.phoneNumber - The phone number to format
+ * @param params.format - The desired output format ("E.164" for international format or "humanReadable" for national format)
+ * @returns The formatted phone number
+ * @throws Error when the phone number cannot be formatted (invalid format, missing country code, etc.)
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const formatted = formatPhoneNumberOrThrow({ phoneNumber: "(555) 123-4567", format: "E.164" });
+ *   console.log(formatted); // "+15551234567"
+ * } catch (error) {
+ *   console.error("Invalid phone number:", error.message);
+ * }
+ * ```
+ */
+function formatPhoneNumberOrThrow(params) {
+    const result = formatPhoneNumber(params);
+    if ((0, util_ts_1.isFailure)(result)) {
+        throw result.error;
+    }
+    return result.value;
+}
 //# sourceMappingURL=formatPhoneNumber.js.map

package/src/lib/formatPhoneNumber.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatPhoneNumber.js","sourceRoot":"","sources":["../../../../../packages/phone-number/src/lib/formatPhoneNumber.ts"],"names":[],"mappings":";;AAGA,8CAcC;AAjBD,uDAAiF;AACjF,yDAA8D;AAE9D,SAAgB,iBAAiB,CAAC,MAGjC;IACC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAEvC,IAAI,CAAC;QACH,MAAM,iBAAiB,GAAG,IAAA,6CAAyB,EAAC,WAAW,CAAC,IAAI,EAAE,EAAE;YACtE,cAAc,EAAE,IAAI;SACrB,CAAC,CAAC;QACH,OAAO,IAAA,iBAAO,EAAC,iBAAiB,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAA,iBAAO,EAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,sBAAsB,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;AACH,CAAC"}
+{"version":3,"file":"formatPhoneNumber.js","sourceRoot":"","sources":["../../../../../packages/phone-number/src/lib/formatPhoneNumber.ts"],"names":[],"mappings":";;AA+BA,8CAWC;AAyBD,4DAOC;AA1ED,uDAMmC;AACnC,yDAA8D;AAQ9D;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,iBAAiB,CAAC,MAA+B;IAC/D,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAEvC,IAAI,CAAC;QACH,MAAM,iBAAiB,GAAG,IAAA,6CAAyB,EAAC,WAAW,CAAC,IAAI,EAAE,EAAE;YACtE,cAAc,EAAE,IAAI;SACrB,CAAC,CAAC;QACH,OAAO,IAAA,iBAAO,EAAC,iBAAiB,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACtF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,IAAA,iBAAO,EAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,IAAA,iBAAO,EAAC,KAAK,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,wBAAwB,CAAC,MAA+B;IACtE,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,IAAA,mBAAS,EAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,MAAM,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC"}

package/src/lib/isValidPhoneNumber.d.ts

@@ -0,0 +1,3 @@
+import { type WithPhoneNumber } from "./types";
+export type IsValidPhoneNumberParams = WithPhoneNumber;
+export declare function isValidPhoneNumber(params: IsValidPhoneNumberParams): boolean;

package/src/lib/isValidPhoneNumber.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidPhoneNumber = isValidPhoneNumber;
+const libphonenumber_js_1 = require("libphonenumber-js");
+function isValidPhoneNumber(params) {
+    const { phoneNumber } = params;
+    return (0, libphonenumber_js_1.isValidPhoneNumber)(phoneNumber.trim(), {
+        defaultCountry: "US",
+    });
+}
+//# sourceMappingURL=isValidPhoneNumber.js.map

package/src/lib/isValidPhoneNumber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isValidPhoneNumber.js","sourceRoot":"","sources":["../../../../../packages/phone-number/src/lib/isValidPhoneNumber.ts"],"names":[],"mappings":";;AAMA,gDAMC;AAZD,yDAA8E;AAM9E,SAAgB,kBAAkB,CAAC,MAAgC;IACjE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAE/B,OAAO,IAAA,sCAAmB,EAAC,WAAW,CAAC,IAAI,EAAE,EAAE;QAC7C,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;AACL,CAAC"}

package/src/lib/types.d.ts

@@ -0,0 +1,3 @@
+export interface WithPhoneNumber {
+    phoneNumber: string;
+}

package/src/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/phone-number/src/lib/types.ts"],"names":[],"mappings":""}