@pawells/typescript-common 1.0.1 → 1.1.0

package/build/string/assert.js

@@ -0,0 +1,185 @@
+import { SetExceptionClass, SetExceptionMessage, ThrowException } from '../asserts/utils.js';
+/**
+ * Cache for compiled regex patterns to improve performance when the same patterns are used repeatedly.
+ * Maps regex source + flags to the compiled RegExp object for efficient reuse.
+ *
+ * @internal
+ */
+const REGEX_PATTERN_CACHE = new Map();
+/**
+ * Maximum number of cached regex patterns to prevent unbounded memory growth.
+ * When this limit is reached, the cache will be cleared to maintain memory efficiency.
+ *
+ * @internal
+ */
+const MAX_CACHE_SIZE = 100;
+/**
+ * Number of oldest cache entries to evict in one batch when the cache is full.
+ *
+ * @internal
+ */
+const CACHE_EVICTION_BATCH_SIZE = 20;
+/**
+ * Gets a cached regex pattern or creates and caches a new one.
+ * This optimization improves performance when the same regex patterns are used repeatedly.
+ *
+ * @param source - The regex pattern source string
+ * @param flags - The regex flags string
+ * @returns The compiled RegExp object
+ * @internal
+ */
+function getCachedRegex(source, flags = '') {
+    const cacheKey = `${source}:::${flags}`;
+    let regex = REGEX_PATTERN_CACHE.get(cacheKey);
+    if (!regex) {
+        // Use LRU eviction: delete oldest entries when cache reaches limit
+        if (REGEX_PATTERN_CACHE.size >= MAX_CACHE_SIZE) {
+            const keysToDelete = Array.from(REGEX_PATTERN_CACHE.keys()).slice(0, CACHE_EVICTION_BATCH_SIZE);
+            keysToDelete.forEach(key => REGEX_PATTERN_CACHE.delete(key));
+        }
+        regex = new RegExp(source, flags);
+        REGEX_PATTERN_CACHE.set(cacheKey, regex);
+    }
+    return regex;
+}
+/**
+ * Error thrown when a value is not a valid string or fails a string assertion.
+ *
+ * @example
+ * throw new StringError('Value is not a valid string');
+ */
+export class StringError extends Error {
+    constructor(message) {
+        super(message ?? 'String Assertion Failed');
+        this.name = 'StringError';
+        Object.setPrototypeOf(this, StringError.prototype);
+    }
+}
+/**
+ * Asserts that a value is a string primitive type.
+ *
+ * This method validates that the provided value is of type 'string'. It accepts
+ * any string including empty strings. This is a strict type check that will
+ * reject string objects created with new String().
+ *
+ * @template TError - Custom error type to throw on failure
+ * @param value - The value to validate as a string
+ * @param exception - Optional exception configuration for custom error handling
+ * @throws {StringError} When value is not a string primitive
+ *
+ * @example
+ * ```typescript
+ * AssertString("hello");             // ✓ Valid
+ * AssertString("");                  // ✓ Valid (empty string is still a string)
+ * AssertString("123");               // ✓ Valid (numeric string)
+ * AssertString(123);                 // ✗ Throws StringError (number)
+ * AssertString(null);                // ✗ Throws StringError
+ * AssertString(new String("hello")); // ✗ Throws StringError (String object)
+ * ```
+ */
+export function AssertString(value, exception = {}) {
+    SetExceptionClass(exception, StringError);
+    if (typeof value !== 'string') {
+        SetExceptionMessage(exception, `Expected string but received ${typeof value}: ${String(value)}`);
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that a value is a non-empty string (after trimming whitespace).
+ *
+ * This method validates that the provided value is a string and contains at least
+ * one non-whitespace character after trimming. This is useful for validating user
+ * inputs, form fields, and API parameters where empty or whitespace-only strings
+ * are not acceptable.
+ *
+ * @template TError - Custom error type to throw on failure
+ * @param value - The value to validate as a non-empty string
+ * @param exception - Optional exception configuration for custom error handling
+ * @throws {StringError} When value is not a string or is empty/whitespace-only
+ *
+ * @example
+ * ```typescript
+ * AssertStringNotEmpty("hello");         // ✓ Valid
+ * AssertStringNotEmpty("  a  ");         // ✓ Valid (has non-whitespace content)
+ * AssertStringNotEmpty("x");             // ✓ Valid (single character)
+ * AssertStringNotEmpty("");              // ✗ Throws StringError (empty)
+ * AssertStringNotEmpty("   ");           // ✗ Throws StringError (whitespace only)
+ * AssertStringNotEmpty("\t\n  ");        // ✗ Throws StringError (whitespace only)
+ * AssertStringNotEmpty(123);             // ✗ Throws StringError (not a string)
+ * ```
+ */
+export function AssertStringNotEmpty(value, exception = {}) {
+    SetExceptionClass(exception, StringError);
+    if (typeof value !== 'string') {
+        SetExceptionMessage(exception, `Expected non-empty string but received ${typeof value}: ${String(value)}`);
+        ThrowException(exception);
+    }
+    const str = value;
+    if (str === '') {
+        SetExceptionMessage(exception, 'Expected non-empty string but received empty string');
+        ThrowException(exception);
+    }
+    if (str.trim() === '') {
+        SetExceptionMessage(exception, 'Expected non-empty string but received whitespace-only string');
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that a string matches a regular expression pattern.
+ *
+ * This method validates that the provided string matches the specified regular
+ * expression pattern. The string must be a valid string type (use AssertString first
+ * if needed). Useful for validating formats like emails, phone numbers, IDs, and
+ * other structured text data.
+ *
+ * For performance optimization, regex patterns are cached when possible to avoid
+ * recompilation of the same patterns. This provides significant performance benefits
+ * when validating many values against the same pattern.
+ *
+ * @template TError - Custom error type to throw on failure
+ * @param value - The string to test against the pattern
+ * @param regex - The regular expression pattern to match against
+ * @param exception - Optional exception configuration for custom error handling
+ * @throws {StringError} When string does not match the pattern
+ *
+ * @example
+ * ```typescript
+ * // Email validation
+ * AssertStringMatches("hello@example.com", /^[^\s@]+@[^\s@]+\.[^\s@]+$/);  // ✓ Valid
+ *
+ * // Digits only validation
+ * AssertStringMatches("123", /^\d+$/);                                     // ✓ Valid
+ * AssertStringMatches("12a", /^\d+$/);                                     // ✗ Throws StringError
+ *
+ * // Phone number format
+ * AssertStringMatches("(555) 123-4567", /^\(\d{3}\) \d{3}-\d{4}$/);       // ✓ Valid
+ *
+ * // Alphanumeric with length constraint
+ * AssertStringMatches("abc123", /^[a-zA-Z0-9]{3,10}$/);                   // ✓ Valid
+ * AssertStringMatches("ab", /^[a-zA-Z0-9]{3,10}$/);                       // ✗ Throws (too short)
+ *
+ * // Performance benefit with repeated pattern usage
+ * const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+ * AssertStringMatches("user1@example.com", emailPattern); // Cached for future use
+ * AssertStringMatches("user2@example.com", emailPattern); // Uses cached pattern
+ * ```
+ */
+export function AssertStringMatches(value, regex, exception = {}) {
+    SetExceptionClass(exception, StringError);
+    AssertString(value, exception); // Ensure value is a string before matching
+    // Use cached regex for better performance when possible
+    // If the regex has a source and flags, we can cache it for reuse
+    let testRegex;
+    if (regex.source && regex.flags !== undefined) {
+        testRegex = getCachedRegex(regex.source, regex.flags);
+    }
+    else {
+        // Fallback to original regex if caching is not possible
+        testRegex = regex;
+    }
+    if (!testRegex.test(value)) {
+        SetExceptionMessage(exception, `String does not match the required pattern: ${regex.toString()}`);
+        ThrowException(exception);
+    }
+}
+//# sourceMappingURL=assert.js.map

package/build/string/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../src/string/assert.ts"],"names":[],"mappings":"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"}

package/build/string/index.d.ts

@@ -12,4 +12,5 @@ export * from './validation.js';
 export * from './formatting.js';
 export * from './transformation.js';
 export type { TStringValidator, TStringFormatter, TStringTransformer, TCaseConverter, TStringPredicate, TFormatValue, TFormatParams, TFormatArgs } from './types.js';
+export * from './assert.js';
 //# sourceMappingURL=index.d.ts.map

package/build/string/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AAEpC,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AAEpC,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrK,cAAc,aAAa,CAAC"}

package/build/string/index.js

@@ -11,4 +11,5 @@ export * from './case-conversion.js';
 export * from './validation.js';
 export * from './formatting.js';
 export * from './transformation.js';
+export * from './assert.js';
 //# sourceMappingURL=index.js.map

package/build/string/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/string/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,aAAa,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pawells/typescript-common",
 	"displayName": "TypeScript Common Utilities",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"description": "Shared TypeScript utility library — array, object, string, time, and enum helpers. ESM-only, no runtime dependencies.",
 	"type": "module",
 	"main": "./build/index.js",