@spudlabs/guardis 0.4.0

package/script/src/modules/strings.branded.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * This module provides type guards for common string patterns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCommaDelimitedNumbers = exports.isCommaDelimitedIntegers = exports.isPeriodDelimited = exports.isCommaDelimited = exports.isUUIDv7 = exports.isUUIDv4 = exports.isPhoneNumber = exports.isUSPhone = exports.isInternationalPhone = exports.isEmail = void 0;
+const strings_js_1 = require("./strings.js");
+/**
+ * Type guard for validating whether a given value is a valid email string. Uses a
+ * branded type to ensure type safety and distinguish it from other strings.
+ *
+ * Uses the `EMAIL_REGEX` to test if the input is a string that matches the email format.
+ *
+ * @param t - The value to test for email validity.
+ * @returns Boolean indicating whether the input is a valid email.
+ */
+exports.isEmail = strings_js_1.isEmail;
+/**
+ * Type guard for validating whether a given value is a valid international phone number string.
+ * Uses a branded type to ensure type safety and distinguish it from other strings.
+ *
+ * Uses the `INT_PHONE_REGEX` to test if the input is a string that matches the international phone number format.
+ *
+ * @param t - The value to test for international phone number validity.
+ * @returns Boolean indicating whether the input is a valid international phone number.
+ */
+exports.isInternationalPhone = strings_js_1.isInternationalPhone;
+/**
+ * Type guard for validating whether a given value is a valid US phone number string.
+ * Uses a branded type to ensure type safety and distinguish it from other strings.
+ *
+ * Uses the `US_PHONE_REGEX` to test if the input is a string that matches the US phone number format.
+ *
+ * @param t - The value to test for US phone number validity.
+ * @returns Boolean indicating whether the input is a valid US phone number.
+ */
+exports.isUSPhone = strings_js_1.isUSPhone;
+/**
+ * Type guard for validating whether a given value is a valid phone number string,
+ * either in international or US format. Uses a branded type to ensure type safety
+ * and distinguish it from other strings.
+ *
+ * Uses both `INT_PHONE_REGEX` and `US_PHONE_REGEX` to test if the input is a string
+ * that matches either format.
+ *
+ * @param t - The value to test for phone number validity.
+ * @returns Boolean indicating whether the input is a valid phone number.
+ */
+exports.isPhoneNumber = strings_js_1.isPhoneNumber;
+/**
+ * Type guard for validating whether a given value is a valid UUIDv4 string.
+ * Uses a branded type to ensure type safety and distinguish it from other strings.
+ *
+ * Uses a regex pattern to test if the input is a string that matches the UUIDv4 format.
+ *
+ * @param t - The value to test for UUIDv4 validity.
+ * @returns Boolean indicating whether the input is a valid UUIDv4.
+ */
+exports.isUUIDv4 = strings_js_1.isUUIDv4;
+/**
+ * Type guard for validating whether a given value is a valid UUIDv7 string.
+ * Uses a branded type to ensure type safety and distinguish it from other strings.
+ *
+ * Uses a regex pattern to test if the input is a string that matches the UUIDv7 format.
+ *
+ * @param t - The value to test for UUIDv7 validity.
+ * @returns Boolean indicating whether the input is a valid UUIDv7.
+ */
+exports.isUUIDv7 = strings_js_1.isUUIDv7;
+/**
+ * Type guard for validating whether a given value is a valid comma-delimited string.
+ * Uses a branded type to ensure type safety and distinguish it from other strings.
+ *
+ * Uses a regex pattern to test if the input is a string that matches the comma-delimited format.
+ *
+ * @param t - The value to test for comma-delimited string validity.
+ * @returns Boolean indicating whether the input is a valid comma-delimited string.
+ */
+exports.isCommaDelimited = strings_js_1.isCommaDelimited;
+/**
+ * Type guard for validating whether a given value is a valid period-delimited string.
+ * Uses a branded type to ensure type safety and distinguish it from other strings.
+ *
+ * Uses a regex pattern to test if the input is a string that matches the period-delimited format.
+ *
+ * @param t - The value to test for period-delimited string validity.
+ * @returns Boolean indicating whether the input is a valid period-delimited string.
+ */
+exports.isPeriodDelimited = strings_js_1.isPeriodDelimited;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited
+ * string of integers.
+ *
+ * - Matches one or more integers (positive or negative) separated by commas.
+ * - Does not allow empty values between commas.
+ * - Does not allow any whitespace (between digits or after commas).
+ * - Does not match empty strings.
+ *
+ * @param t - The value to test for comma-delimited integers validity.
+ * @returns Boolean indicating whether the input is a valid comma-delimited string of integers.
+ *
+ * @example
+ * - Valid: "1,2,3", "123,456,789", "-1,2,-3"
+ * - Invalid: "1,,3", "1, 2, 3", "1 2,3", "", "1.5,2"
+ */
+exports.isCommaDelimitedIntegers = strings_js_1.isCommaDelimitedIntegers;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited
+ * string of numbers.
+ *
+ * - Matches one or more numbers (integers, floats, decimals, or percentages) separated by commas.
+ * - Supports positive and negative numbers.
+ * - Supports decimal values (e.g., "1.5", "3.14159").
+ * - Supports percentage values (e.g., "50%", "12.5%").
+ * - Does not allow empty values between commas.
+ * - Does not allow any whitespace (between digits or after commas).
+ * - Does not match empty strings.
+ *
+ * @param t - The value to test for comma-delimited numbers validity.
+ * @returns Boolean indicating whether the input is a valid comma-delimited string of numbers.
+ *
+ * @example
+ * - Valid: "1,2,3", "1.5,2.5,3.5", "-1.5,2,3.14", "50%,75%,100%", "1.5%,2,3%"
+ * - Invalid: "1,,3", "1, 2, 3", "1 2,3", "", "1..5,2", "1.5.5,2"
+ */
+exports.isCommaDelimitedNumbers = strings_js_1.isCommaDelimitedNumbers;

package/script/src/modules/strings.d.ts

@@ -0,0 +1,109 @@
+import type { TypeGuard } from "../types.js";
+/**
+ * Type guard that checks if the provided value is a valid email string.
+ *
+ * Uses the `EMAIL_REGEX` to test if the input is a string matching the email format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid email.
+ */
+export declare const isEmail: TypeGuard<string>;
+/**
+ * Type guard that checks if the provided value is a valid international phone number.
+ *
+ * Uses the `INT_PHONE_REGEX` to test if the input is a string matching the international phone number format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid international phone number.
+ */
+export declare const isInternationalPhone: TypeGuard<string>;
+/**
+ * Type guard that checks if the provided value is a valid US phone number.
+ *
+ * Uses the `US_PHONE_REGEX` to test if the input is a string matching the US phone number format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid US phone number.
+ */
+export declare const isUSPhone: TypeGuard<string>;
+/**
+ * Type guard that checks if the provided value is a valid phone number, either international or US format.
+ *
+ * Uses both `INT_PHONE_REGEX` and `US_PHONE_REGEX` to test if the input is a string matching either format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid phone number.
+ */
+export declare const isPhoneNumber: TypeGuard<string>;
+/**
+ * A type guard function that checks if a given value is a valid UUID version 4 string.
+ *
+ * @param t - The value to be checked.
+ * @returns  Boolean indicating whether the input is a valid UUID v4 string.
+ */
+export declare const isUUIDv4: TypeGuard<string>;
+/**
+ * A type guard function that checks if a given value is a valid UUID version 7 string.
+ *
+ * @param t - The value to be checked.
+ * @returns  Boolean indicating whether the input is a valid UUID v7 string.
+ */
+export declare const isUUIDv7: TypeGuard<string>;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited string.
+ *
+ * This function extends the `isString` type guard and applies an additional validation
+ * using the `COMMA_DELIMITED_REGEX` regular expression. If the string matches the pattern,
+ * it is returned; otherwise, `null` is returned.
+ *
+ * @param t - The input value to be checked.
+ * @returns  Boolean indicating whether the input is a valid comma-delimited string.
+ */
+export declare const isCommaDelimited: TypeGuard<string>;
+/**
+ * Checks if a given string matches the period-delimited format.
+ * This function extends the `isString` type guard to validate
+ * whether the input string conforms to the `PERIOD_DELIMITED_REGEX`.
+ *
+ * @param t - The string to be validated.
+ * @returns  Boolean indicating whether the input is a valid period-delimited string.
+ */
+export declare const isPeriodDelimited: TypeGuard<string>;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited
+ * string of integers.
+ *
+ * - Matches one or more integers (positive or negative) separated by commas.
+ * - Does not allow empty values between commas.
+ * - Does not allow any whitespace (between digits or after commas).
+ * - Does not match empty strings.
+ *
+ * @param t - The value to test for comma-delimited integers validity.
+ * @returns Boolean indicating whether the input is a valid comma-delimited string of integers.
+ *
+ * @example
+ * - Valid: "1,2,3", "123,456,789", "-1,2,-3"
+ * - Invalid: "1,,3", "1, 2, 3", "1 2,3", "", "1.5,2"
+ */
+export declare const isCommaDelimitedIntegers: TypeGuard<string>;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited
+ * string of numbers.
+ *
+ * - Matches one or more numbers (integers, floats, decimals, or percentages) separated by commas.
+ * - Supports positive and negative numbers.
+ * - Supports decimal values (e.g., "1.5", "3.14159").
+ * - Supports percentage values (e.g., "50%", "12.5%").
+ * - Does not allow empty values between commas.
+ * - Does not allow any whitespace (between digits or after commas).
+ * - Does not match empty strings.
+ *
+ * @param t - The value to test for comma-delimited numbers validity.
+ * @returns Boolean indicating whether the input is a valid comma-delimited string of numbers.
+ *
+ * @example
+ * - Valid: "1,2,3", "1.5,2.5,3.5", "-1.5,2,3.14", "50%,75%,100%", "1.5%,2,3%"
+ * - Invalid: "1,,3", "1, 2, 3", "1 2,3", "", "1..5,2", "1.5.5,2"
+ */
+export declare const isCommaDelimitedNumbers: TypeGuard<string>;
+//# sourceMappingURL=strings.d.ts.map

package/script/src/modules/strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../../src/src/modules/strings.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,EAAE,SAAS,CAAC,MAAM,CAGrC,CAAC;AAOF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,CAAC,MAAM,CAGlD,CAAC;AAOF;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,MAAM,CAGvC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,MAAM,CAQ3C,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,CAAC,MAAM,CAGtC,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,CAAC,MAAM,CAGtC,CAAC;AAiBF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,CAAC,MAAM,CAG9C,CAAC;AAKF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC,MAAM,CAG/C,CAAC;AAIF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,CAAC,MAAM,CAGtD,CAAC;AAIF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,CAAC,MAAM,CAGrD,CAAC"}

package/script/src/modules/strings.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCommaDelimitedNumbers = exports.isCommaDelimitedIntegers = exports.isPeriodDelimited = exports.isCommaDelimited = exports.isUUIDv7 = exports.isUUIDv4 = exports.isPhoneNumber = exports.isUSPhone = exports.isInternationalPhone = exports.isEmail = void 0;
+/**
+ * Type guards for common string formats such as email, phone numbers, and UUIDs.
+ * These guards extend the basic string type guard to include regex-based validation.
+ */
+const guard_js_1 = require("../guard.js");
+/** A regex statement to detect _most_ email formats. */
+const EMAIL_REGEX = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/;
+/**
+ * Type guard that checks if the provided value is a valid email string.
+ *
+ * Uses the `EMAIL_REGEX` to test if the input is a string matching the email format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid email.
+ */
+exports.isEmail = guard_js_1.isString.extend("email", (t) => EMAIL_REGEX.test(t) ? t : null);
+/** Regex for validating international phone numbers. See
+ * https://blog.stevenlevithan.com/archives/validate-phone-number#r4-3 for more
+ * information. */
+const INT_PHONE_REGEX = /^\+(?:[0-9] ?){6,14}[0-9]$/;
+/**
+ * Type guard that checks if the provided value is a valid international phone number.
+ *
+ * Uses the `INT_PHONE_REGEX` to test if the input is a string matching the international phone number format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid international phone number.
+ */
+exports.isInternationalPhone = guard_js_1.isString.extend("international phone number", (t) => INT_PHONE_REGEX.test(t) ? t : null);
+/** Regex for validating US phone numbers. See
+ * https://blog.stevenlevithan.com/archives/validate-phone-number#r4-3 for more
+ * information. */
+const US_PHONE_REGEX = /^(?:\+?1[-. ]?)?\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/;
+/**
+ * Type guard that checks if the provided value is a valid US phone number.
+ *
+ * Uses the `US_PHONE_REGEX` to test if the input is a string matching the US phone number format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid US phone number.
+ */
+exports.isUSPhone = guard_js_1.isString.extend("US phone number", (t) => US_PHONE_REGEX.test(t) ? t : null);
+/**
+ * Type guard that checks if the provided value is a valid phone number, either international or US format.
+ *
+ * Uses both `INT_PHONE_REGEX` and `US_PHONE_REGEX` to test if the input is a string matching either format.
+ *
+ * @param t - The value to check.
+ * @returns Boolean indicating whether the input is a valid phone number.
+ */
+exports.isPhoneNumber = guard_js_1.isString.extend("phone number", (t) => {
+    if (INT_PHONE_REGEX.test(t) || US_PHONE_REGEX.test(t)) {
+        return t;
+    }
+    return null;
+});
+/** Regex for validating UUID v4 strings. */
+const UUID_4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * A type guard function that checks if a given value is a valid UUID version 4 string.
+ *
+ * @param t - The value to be checked.
+ * @returns  Boolean indicating whether the input is a valid UUID v4 string.
+ */
+exports.isUUIDv4 = guard_js_1.isString.extend("UUIDv4", (t) => UUID_4_REGEX.test(t) ? t : null);
+/** Regex for validating UUID v7 strings. */
+const UUID_7_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * A type guard function that checks if a given value is a valid UUID version 7 string.
+ *
+ * @param t - The value to be checked.
+ * @returns  Boolean indicating whether the input is a valid UUID v7 string.
+ */
+exports.isUUIDv7 = guard_js_1.isString.extend("UUIDv7", (t) => UUID_7_REGEX.test(t) ? t : null);
+/**
+ * A regular expression used to validate comma-delimited strings.
+ *
+ * - Matches strings enclosed in double quotes, allowing for escaped characters within the quotes.
+ * - Matches unquoted segments that do not contain commas, double quotes, or backslashes.
+ * - Useful for parsing CSV-like strings where fields may be quoted or unquoted.
+ * - Validates the entire string structure, allowing empty strings, single values, or comma-separated values.
+ *
+ * Example:
+ * Input: `"value1","value2,with,commas",unquotedValue`
+ * Matches: entire string as valid comma-delimited format
+ */
+const COMMA_DELIMITED_REGEX = /^(?:(?:"(?:[^"\\]|\\.)*"|[^,"\\]+)(?:,(?:"(?:[^"\\]|\\.)*"|[^,"\\]+))*)?$/;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited string.
+ *
+ * This function extends the `isString` type guard and applies an additional validation
+ * using the `COMMA_DELIMITED_REGEX` regular expression. If the string matches the pattern,
+ * it is returned; otherwise, `null` is returned.
+ *
+ * @param t - The input value to be checked.
+ * @returns  Boolean indicating whether the input is a valid comma-delimited string.
+ */
+exports.isCommaDelimited = guard_js_1.isString.extend("comma-delimited string", (t) => COMMA_DELIMITED_REGEX.test(t) ? t : null);
+const PERIOD_DELIMITED_REGEX = /^(?:(?:"(?:[^"\\]|\\.)*"|[^."\\""]+)(?:.(?:"(?:[^"\\]|\\.)*"|[^."\\""]+))*)?$/;
+/**
+ * Checks if a given string matches the period-delimited format.
+ * This function extends the `isString` type guard to validate
+ * whether the input string conforms to the `PERIOD_DELIMITED_REGEX`.
+ *
+ * @param t - The string to be validated.
+ * @returns  Boolean indicating whether the input is a valid period-delimited string.
+ */
+exports.isPeriodDelimited = guard_js_1.isString.extend("period-delimited string", (t) => PERIOD_DELIMITED_REGEX.test(t) ? t : null);
+const COMMA_DELIMITED_INTEGERS_REGEX = /^-?\d+(?:,-?\d+)*$/;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited
+ * string of integers.
+ *
+ * - Matches one or more integers (positive or negative) separated by commas.
+ * - Does not allow empty values between commas.
+ * - Does not allow any whitespace (between digits or after commas).
+ * - Does not match empty strings.
+ *
+ * @param t - The value to test for comma-delimited integers validity.
+ * @returns Boolean indicating whether the input is a valid comma-delimited string of integers.
+ *
+ * @example
+ * - Valid: "1,2,3", "123,456,789", "-1,2,-3"
+ * - Invalid: "1,,3", "1, 2, 3", "1 2,3", "", "1.5,2"
+ */
+exports.isCommaDelimitedIntegers = guard_js_1.isString.extend("comma-delimited integers", (t) => COMMA_DELIMITED_INTEGERS_REGEX.test(t) ? t : null);
+const COMMA_DELIMITED_NUMBERS_REGEX = /^-?\d+(?:\.\d+)?%?(?:,-?\d+(?:\.\d+)?%?)*$/;
+/**
+ * A type guard function that checks if a given string matches the pattern of a comma-delimited
+ * string of numbers.
+ *
+ * - Matches one or more numbers (integers, floats, decimals, or percentages) separated by commas.
+ * - Supports positive and negative numbers.
+ * - Supports decimal values (e.g., "1.5", "3.14159").
+ * - Supports percentage values (e.g., "50%", "12.5%").
+ * - Does not allow empty values between commas.
+ * - Does not allow any whitespace (between digits or after commas).
+ * - Does not match empty strings.
+ *
+ * @param t - The value to test for comma-delimited numbers validity.
+ * @returns Boolean indicating whether the input is a valid comma-delimited string of numbers.
+ *
+ * @example
+ * - Valid: "1,2,3", "1.5,2.5,3.5", "-1.5,2,3.14", "50%,75%,100%", "1.5%,2,3%"
+ * - Invalid: "1,,3", "1, 2, 3", "1 2,3", "", "1..5,2", "1.5.5,2"
+ */
+exports.isCommaDelimitedNumbers = guard_js_1.isString.extend("comma-delimited numbers", (t) => COMMA_DELIMITED_NUMBERS_REGEX.test(t) ? t : null);