@gzl10/ts-helpers 4.2.1

package/dist/types/validators.d.ts

@@ -0,0 +1,216 @@
+/**
+ * File and security validators
+ *
+ * This module provides validation functions for file operations and content security.
+ * Functions implement basic security checks to prevent common attack vectors:
+ * - Path traversal attacks (../, ..\)
+ * - XSS injection (script tags, javascript: URLs)
+ * - File size limits
+ *
+ * ⚠️ WARNING: These are basic validations. For production systems, consider:
+ * - Additional OS-specific path validation
+ * - Symbolic link resolution checking
+ * - Comprehensive XSS prevention libraries (e.g., DOMPurify)
+ * - Content-Type validation
+ * - Virus scanning for uploaded files
+ */
+/**
+ * Validates file path for security vulnerabilities
+ *
+ * Protects against common path traversal attacks by checking for:
+ * - Parent directory references (../, ..\)
+ * - Mixed path separators (//\, \\)
+ * - Excessive path length (>1000 chars)
+ * - Empty or null paths
+ *
+ * ⚠️ SECURITY NOTE: This is basic validation. For production use, consider:
+ * - Validating against an allowed directory whitelist
+ * - Resolving symbolic links
+ * - OS-specific path rules (Windows vs Unix)
+ * - Canonicalization before validation
+ *
+ * @param filePath - File path string to validate
+ * @returns True if path appears safe, false if potentially dangerous
+ *
+ * @example
+ * ```typescript
+ * // Safe paths - Allowed
+ * isValidFilePath('./data/users.json')        // true
+ * isValidFilePath('data/users.json')          // true
+ * isValidFilePath('/absolute/path/file.txt')  // true
+ * isValidFilePath('C:\\Users\\data\\file.txt') // true
+ *
+ * // Dangerous paths - Path traversal attacks
+ * isValidFilePath('../../../etc/passwd')      // false
+ * isValidFilePath('data/../../../etc/passwd') // false
+ * isValidFilePath('..\\..\\..\\windows\\system32\\config') // false
+ * isValidFilePath('data//\\..//config')       // false
+ *
+ * // Invalid paths - Malformed
+ * isValidFilePath('')                         // false
+ * isValidFilePath(null as any)                // false
+ * isValidFilePath(undefined as any)           // false
+ * isValidFilePath('x'.repeat(1001))          // false (too long)
+ *
+ * // Real-world usage in file operations
+ * async function readUserFile(userPath: string) {
+ *   if (!isValidFilePath(userPath)) {
+ *     throw new Error('Invalid or unsafe file path detected')
+ *   }
+ *
+ *   // Additional check: ensure path is within allowed directory
+ *   const allowedDir = '/var/app/uploads'
+ *   const fullPath = path.join(allowedDir, userPath)
+ *
+ *   return fs.readFile(fullPath, 'utf-8')
+ * }
+ * ```
+ *
+ * @see {@link isValidTextContent} for content security validation
+ * @see {@link isValidFileSize} for file size validation
+ */
+declare function isValidFilePath(filePath: string): boolean;
+/**
+ * Validates file size against a maximum limit
+ *
+ * Checks if a file size is valid (non-negative) and within acceptable limits.
+ * Used to prevent:
+ * - Denial of Service (DoS) attacks via large file uploads
+ * - Disk space exhaustion
+ * - Memory overflow during file processing
+ *
+ * @param size - File size in bytes to validate
+ * @param maxSize - Maximum allowed size in bytes
+ * @returns True if size is valid and within limit, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Common size limits
+ * const KB = 1024
+ * const MB = 1024 * KB
+ * const GB = 1024 * MB
+ *
+ * // Image upload validation (5 MB limit)
+ * const imageSize = 4 * MB
+ * isValidFileSize(imageSize, 5 * MB)  // true
+ *
+ * // Document upload validation (10 MB limit)
+ * const docSize = 12 * MB
+ * isValidFileSize(docSize, 10 * MB)  // false (exceeds limit)
+ *
+ * // Video upload validation (1 GB limit)
+ * const videoSize = 500 * MB
+ * isValidFileSize(videoSize, 1 * GB)  // true
+ *
+ * // Invalid sizes
+ * isValidFileSize(-100, 1 * MB)      // false (negative size)
+ * isValidFileSize(NaN, 1 * MB)       // false (invalid number)
+ * isValidFileSize('1000' as any, 1 * MB) // false (not a number)
+ *
+ * // Real-world usage in file upload handler
+ * app.post('/upload', (req, res) => {
+ *   const file = req.files.document
+ *   const maxSize = 10 * 1024 * 1024 // 10 MB
+ *
+ *   if (!isValidFileSize(file.size, maxSize)) {
+ *     return res.status(413).json({
+ *       error: 'File too large',
+ *       maxSize: '10 MB',
+ *       received: `${(file.size / (1024 * 1024)).toFixed(2)} MB`
+ *     })
+ *   }
+ *
+ *   // Process file...
+ * })
+ * ```
+ *
+ * @see {@link isValidFilePath} for path security validation
+ */
+declare function isValidFileSize(size: number, maxSize: number): boolean;
+/**
+ * Validates text content for security vulnerabilities and size limits
+ *
+ * Performs basic security checks on text content to detect common XSS attack vectors:
+ * - Script tags (<script>)
+ * - JavaScript URLs (javascript:)
+ * - Data URLs with HTML (data:text/html)
+ * - VBScript URLs (vbscript:)
+ *
+ * Also enforces maximum content length to prevent DoS attacks.
+ *
+ * ⚠️ WARNING: This is basic XSS detection. For production systems:
+ * - Use dedicated sanitization libraries (DOMPurify, sanitize-html)
+ * - Implement Content Security Policy (CSP)
+ * - Apply output encoding based on context (HTML, JS, URL)
+ * - Validate against allowlists, not just blocklists
+ *
+ * @param content - Text content to validate
+ * @param options - Validation options
+ * @param options.maxLength - Maximum content length in characters (default: 1,000,000)
+ * @returns True if content appears safe, false if dangerous patterns detected
+ *
+ * @example
+ * ```typescript
+ * // Safe content - Allowed
+ * isValidTextContent('Hello, world!')           // true
+ * isValidTextContent('User input: <b>bold</b>') // true
+ * isValidTextContent('Email: user@example.com') // true
+ *
+ * // Dangerous content - XSS vectors detected
+ * isValidTextContent('<script>alert("XSS")</script>')     // false
+ * isValidTextContent('<img src=x onerror="alert(1)">')    // false (contains 'script' in onerror)
+ * isValidTextContent('<a href="javascript:void(0)">')     // false
+ * isValidTextContent('<iframe src="data:text/html,..."') // false
+ * isValidTextContent('vbscript:msgbox("XSS")')           // false
+ *
+ * // Size limit validation
+ * isValidTextContent('x'.repeat(999_999))              // true (under default 1M limit)
+ * isValidTextContent('x'.repeat(1_000_001))            // false (exceeds default limit)
+ * isValidTextContent('x'.repeat(5000), { maxLength: 1000 }) // false (custom limit)
+ *
+ * // Edge cases
+ * isValidTextContent('')                     // true (empty is valid)
+ * isValidTextContent(null as any)            // false (not a string)
+ * isValidTextContent(undefined as any)       // false (not a string)
+ * isValidTextContent(123 as any)             // false (not a string)
+ *
+ * // Real-world usage in comment system
+ * app.post('/api/comments', (req, res) => {
+ *   const { content } = req.body
+ *
+ *   if (!isValidTextContent(content, { maxLength: 5000 })) {
+ *     return res.status(400).json({
+ *       error: 'Invalid comment content',
+ *       details: 'Content contains dangerous patterns or exceeds 5000 characters'
+ *     })
+ *   }
+ *
+ *   // Additional sanitization recommended
+ *   const sanitized = DOMPurify.sanitize(content)
+ *
+ *   // Save to database...
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Form validation with custom limits
+ * function validateUserBio(bio: string): { valid: boolean; error?: string } {
+ *   if (!isValidTextContent(bio, { maxLength: 500 })) {
+ *     return {
+ *       valid: false,
+ *       error: 'Bio must be less than 500 characters and cannot contain scripts'
+ *     }
+ *   }
+ *   return { valid: true }
+ * }
+ * ```
+ *
+ * @see {@link isValidFilePath} for file path validation
+ * @see sanitizeHtml from validation module for HTML sanitization
+ */
+declare function isValidTextContent(content: string, options?: {
+    maxLength?: number;
+}): boolean;
+
+export { isValidFilePath, isValidFileSize, isValidTextContent };

package/package.json

@@ -0,0 +1,253 @@
+{
+  "name": "@gzl10/ts-helpers",
+  "version": "4.2.1",
+  "description": "Librería de utilidades TypeScript con herramientas especializadas para desarrollo web, validación española, manejo de datos y operaciones asíncronas.",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=8.0.0"
+  },
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./dist/types/index.d.ts",
+        "import": "./dist/node-esm/index.js",
+        "require": "./dist/node/index.js"
+      },
+      "browser": {
+        "types": "./dist/types/index.d.ts",
+        "import": "./dist/browser/index.js"
+      },
+      "default": {
+        "types": "./dist/types/index.d.ts",
+        "import": "./dist/esm/index.js",
+        "require": "./dist/cjs/index.js"
+      }
+    },
+    "./node": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/node-esm/index.js",
+      "require": "./dist/node/index.js"
+    },
+    "./browser": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/browser/index.js"
+    },
+    "./universal": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./validation": {
+      "node": {
+        "types": "./dist/types/validation.d.ts",
+        "import": "./dist/node-esm/validation.js",
+        "require": "./dist/node/validation.js"
+      },
+      "browser": {
+        "types": "./dist/types/validation.d.ts",
+        "import": "./dist/browser/validation-core.js"
+      },
+      "default": {
+        "types": "./dist/types/validation.d.ts",
+        "import": "./dist/esm/validation.js",
+        "require": "./dist/cjs/validation.js"
+      }
+    },
+    "./validation-core": {
+      "types": "./dist/types/validation.d.ts",
+      "import": "./dist/esm/validation.js",
+      "require": "./dist/cjs/validation.js"
+    },
+    "./validation-crypto": {
+      "node": {
+        "types": "./dist/types/validation-crypto-node.d.ts",
+        "import": "./dist/node-esm/validation-crypto.js",
+        "require": "./dist/node/validation-crypto.js"
+      },
+      "browser": {
+        "types": "./dist/types/validation-crypto-browser.d.ts",
+        "import": "./dist/browser/validation-crypto.js"
+      },
+      "default": {
+        "types": "./dist/types/validation-crypto-browser.d.ts",
+        "import": "./dist/browser/validation-crypto.js"
+      }
+    },
+    "./environment-detection": {
+      "types": "./dist/types/environment-detection.d.ts",
+      "import": "./dist/esm/environment-detection.js",
+      "require": "./dist/cjs/environment-detection.js"
+    },
+    "./strings": {
+      "types": "./dist/types/strings.d.ts",
+      "import": "./dist/esm/strings.js",
+      "require": "./dist/cjs/strings.js"
+    },
+    "./objects": {
+      "types": "./dist/types/objects.d.ts",
+      "import": "./dist/esm/objects.js",
+      "require": "./dist/cjs/objects.js"
+    },
+    "./dates": {
+      "types": "./dist/types/dates.d.ts",
+      "import": "./dist/esm/dates.js",
+      "require": "./dist/cjs/dates.js"
+    },
+    "./math": {
+      "types": "./dist/types/math.d.ts",
+      "import": "./dist/esm/math.js",
+      "require": "./dist/cjs/math.js"
+    },
+    "./async": {
+      "types": "./dist/types/async.d.ts",
+      "import": "./dist/esm/async.js",
+      "require": "./dist/cjs/async.js"
+    },
+    "./data": {
+      "types": "./dist/types/data.d.ts",
+      "import": "./dist/node-esm/data.js",
+      "require": "./dist/node/data.js"
+    },
+    "./environment": {
+      "types": "./dist/types/environment.d.ts",
+      "import": "./dist/esm/environment.js",
+      "require": "./dist/cjs/environment.js"
+    },
+    "./errors": {
+      "types": "./dist/types/errors.d.ts",
+      "import": "./dist/esm/errors.js",
+      "require": "./dist/cjs/errors.js"
+    },
+    "./csv": {
+      "types": "./dist/types/csv.d.ts",
+      "import": "./dist/node-esm/csv.js",
+      "require": "./dist/node/csv.js"
+    },
+    "./json": {
+      "types": "./dist/types/json.d.ts",
+      "import": "./dist/node-esm/json.js",
+      "require": "./dist/node/json.js"
+    },
+    "./tree": {
+      "types": "./dist/types/tree.d.ts",
+      "import": "./dist/node-esm/tree.js",
+      "require": "./dist/node/tree.js"
+    },
+    "./validators": {
+      "types": "./dist/types/validators.d.ts",
+      "import": "./dist/node-esm/validators.js",
+      "require": "./dist/node/validators.js"
+    },
+    "./number": {
+      "types": "./dist/types/number.d.ts",
+      "import": "./dist/esm/number.js",
+      "require": "./dist/cjs/number.js"
+    },
+    "./package.json": "./package.json",
+    "./dist/*": "./dist/*"
+  },
+  "author": "Gonzalo Díez<gonzalo@gzl10.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.gzl10.com/oss/ts-helpers.git"
+  },
+  "homepage": "https://gitlab.gzl10.com/oss/ts-helpers",
+  "bugs": {
+    "url": "https://gitlab.gzl10.com/oss/ts-helpers/-/issues"
+  },
+  "license": "MIT",
+  "files": [
+    "dist/**/*.d.ts",
+    "dist/**/*.js",
+    "dist/**/*.map",
+    "README.md",
+    "USAGE-GUIDE.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "crc": "^4.3.2",
+    "dayjs": "^1.11.13",
+    "fast-deep-equal": "^3.1.3",
+    "iso-datestring-validator": "^2.2.2",
+    "lodash": "^4.17.21",
+    "numeral": "^2.0.6",
+    "papaparse": "^5.5.3",
+    "qs": "^6.14.0",
+    "tslib": "^2.8.1",
+    "validator": "^13.15.15"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@types/lodash": "^4.17.20",
+    "@types/node": "^20.19.13",
+    "@types/numeral": "^2.0.5",
+    "@types/papaparse": "^5.3.16",
+    "@types/qs": "^6.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.44.0",
+    "@typescript-eslint/parser": "^8.44.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.34.0",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-compat": "^6.0.2",
+    "eslint-plugin-prettier": "^5.5.4",
+    "globals": "^16.3.0",
+    "jsdom": "^27.0.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.44.0",
+    "vitest": "^3.2.4"
+  },
+  "browserslist": [
+    "Chrome >= 58"
+  ],
+  "keywords": [
+    "typescript",
+    "utilities",
+    "helpers",
+    "spanish",
+    "tools",
+    "utils",
+    "dates",
+    "numbers",
+    "format",
+    "validation",
+    "web-development",
+    "async",
+    "data-import",
+    "data-export"
+  ],
+  "scripts": {
+    "clean": "rimraf dist package-lock.json node_modules test-results",
+    "build": "tsup",
+    "build:cjs": "tsup --config tsup.config.ts --format cjs",
+    "build:esm": "tsup --config tsup.config.ts --format esm",
+    "build:types": "tsup --config tsup.config.ts --dts-only",
+    "build:watch": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.{ts,js,mjs}' 'tests/**/*.{ts,js}' --fix",
+    "lint:check": "eslint 'src/**/*.{ts,js,mjs}' 'tests/**/*.{ts,js}'",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:report": "vitest run --reporter=html --reporter=junit && echo 'HTML report generated at test-results/index.html'",
+    "test:report:open": "vitest run --reporter=html --reporter=junit && open test-results/index.html",
+    "test:docs": "vitest run --reporter=verbose --reporter=html --reporter=junit",
+    "test:ci": "vitest run --reporter=junit --reporter=html --coverage",
+    "dev": "npm run build:watch",
+    "release:prepare": "changeset",
+    "release:version": "changeset version",
+    "release:publish": "changeset publish",
+    "release": "pnpm release:version && pnpm release:publish",
+    "quality": "pnpm run format && pnpm run lint && pnpm run test && pnpm run build",
+    "quality:check": "pnpm run lint:check && pnpm run format:check && pnpm run test && pnpm run build"
+  }
+}