natural-time-js 2.1.0 → 3.0.0

package/dist/utils/validators.js

@@ -1,231 +0,0 @@
-/**
- * @module natural-time-js/validators
- * @description Validation utilities for natural time calculations.
- * This module provides functions to validate inputs for natural time operations,
- * ensuring that values are within acceptable ranges and of the correct types.
- */
-import { NaturalDate } from '../core/NaturalDate.js';
-/**
- * Valid range for latitude values in degrees
- */
-const LATITUDE_RANGE = {
-    MIN: -90,
-    MAX: 90
-};
-/**
- * Valid range for longitude values in degrees
- */
-const LONGITUDE_RANGE = {
-    MIN: -180,
-    MAX: 180
-};
-/**
- * Valid range for angle values in degrees
- */
-const ANGLE_RANGE = {
-    MIN: 0,
-    MAX: 360
-};
-/**
- * Valid ranges for natural date components
- */
-const NATURAL_DATE_RANGES = {
-    /** Moon (month) number range (1-14) */
-    MOON: { MIN: 1, MAX: 14 },
-    /** Week of year range (1-53) */
-    WEEK: { MIN: 1, MAX: 53 },
-    /** Week within moon range (1-4) */
-    WEEK_OF_MOON: { MIN: 1, MAX: 4 },
-    /** Day of moon range (1-28) */
-    DAY_OF_MOON: { MIN: 1, MAX: 28 },
-    /** Day of week range (1-7) */
-    DAY_OF_WEEK: { MIN: 1, MAX: 7 }
-};
-/**
- * Validates if a value is a finite number.
- *
- * This is a utility function that checks if a value is a valid number
- * (not NaN, not Infinity, and actually a number type).
- *
- * @param value - Value to validate
- * @returns True if value is a valid number
- *
- * @example
- * isValidNumber(42); // true
- * isValidNumber('42'); // false (string, not number)
- * isValidNumber(NaN); // false
- * isValidNumber(Infinity); // false
- */
-export const isValidNumber = (value) => {
-    return typeof value === 'number' && Number.isFinite(value) && !Number.isNaN(value);
-};
-/**
- * Validates if a latitude value is within the valid range.
- *
- * Latitude must be a number between -90° (South Pole) and 90° (North Pole).
- *
- * @param latitude - Latitude in degrees to validate
- * @returns True if latitude is valid
- *
- * @example
- * isValidLatitude(45.5); // true
- * isValidLatitude(-90); // true (South Pole)
- * isValidLatitude(90); // true (North Pole)
- * isValidLatitude(91); // false (out of range)
- */
-export const isValidLatitude = (latitude) => {
-    return isValidNumber(latitude) &&
-        latitude >= LATITUDE_RANGE.MIN &&
-        latitude <= LATITUDE_RANGE.MAX;
-};
-/**
- * Validates if a longitude value is within the valid range.
- *
- * Longitude must be a number between -180° and 180°, where:
- * - 0° is the Prime Meridian (Greenwich)
- * - Positive values are East longitude
- * - Negative values are West longitude
- *
- * @param longitude - Longitude in degrees to validate
- * @returns True if longitude is valid
- *
- * @example
- * isValidLongitude(0); // true (Prime Meridian)
- * isValidLongitude(180); // true (International Date Line)
- * isValidLongitude(-180); // true (International Date Line)
- * isValidLongitude(181); // false (out of range)
- */
-export const isValidLongitude = (longitude) => {
-    return isValidNumber(longitude) &&
-        longitude >= LONGITUDE_RANGE.MIN &&
-        longitude <= LONGITUDE_RANGE.MAX;
-};
-/**
- * Validates if an angle value is within the valid range.
- *
- * Angles in natural time are measured in degrees from 0° to 360°,
- * representing a full circle. This is used for time of day and
- * celestial positions.
- *
- * @param angle - Angle in degrees to validate
- * @returns True if angle is valid
- *
- * @example
- * isValidAngle(180); // true (half circle)
- * isValidAngle(360); // true (full circle)
- * isValidAngle(0); // true (beginning of circle)
- * isValidAngle(361); // false (out of range)
- * isValidAngle(-1); // false (out of range)
- */
-export const isValidAngle = (angle) => {
-    return isValidNumber(angle) &&
-        angle >= ANGLE_RANGE.MIN &&
-        angle <= ANGLE_RANGE.MAX;
-};
-/**
- * Validates if a timestamp is a valid Unix time.
- *
- * Unix timestamps represent the number of milliseconds since
- * January 1, 1970, 00:00:00 UTC (the Unix epoch).
- * Valid timestamps must be positive numbers.
- *
- * @param timestamp - Unix timestamp in milliseconds
- * @returns True if timestamp is valid
- *
- * @example
- * isValidTimestamp(Date.now()); // true
- * isValidTimestamp(0); // false (Unix epoch exactly)
- * isValidTimestamp(-1); // false (before Unix epoch)
- */
-export const isValidTimestamp = (timestamp) => {
-    return isValidNumber(timestamp) && timestamp > 0;
-};
-/**
- * Validates if an object is a properly initialized NaturalDate instance.
- *
- * This function performs a comprehensive check of a NaturalDate object,
- * verifying that all properties are present and within valid ranges.
- * It's used to ensure that only valid NaturalDate objects are used in calculations.
- *
- * @param date - Value to validate
- * @returns True if value is a valid NaturalDate instance
- *
- * @example
- * const naturalDate = new NaturalDate(new Date(), 0);
- * isValidNaturalDate(naturalDate); // true
- *
- * isValidNaturalDate({}); // false (not a NaturalDate instance)
- * isValidNaturalDate(null); // false
- */
-export const isValidNaturalDate = (date) => {
-    if (!(date instanceof NaturalDate)) {
-        return false;
-    }
-    // Basic property validations
-    if (!isValidTimestamp(date.unixTime) ||
-        !isValidLongitude(date.longitude) ||
-        !isValidNumber(date.year)) {
-        return false;
-    }
-    // Natural calendar validations
-    return (isValidNumber(date.moon) &&
-        date.moon >= NATURAL_DATE_RANGES.MOON.MIN &&
-        date.moon <= NATURAL_DATE_RANGES.MOON.MAX &&
-        isValidNumber(date.week) &&
-        date.week >= NATURAL_DATE_RANGES.WEEK.MIN &&
-        date.week <= NATURAL_DATE_RANGES.WEEK.MAX &&
-        isValidNumber(date.weekOfMoon) &&
-        date.weekOfMoon >= NATURAL_DATE_RANGES.WEEK_OF_MOON.MIN &&
-        date.weekOfMoon <= NATURAL_DATE_RANGES.WEEK_OF_MOON.MAX &&
-        isValidNumber(date.dayOfMoon) &&
-        date.dayOfMoon >= NATURAL_DATE_RANGES.DAY_OF_MOON.MIN &&
-        date.dayOfMoon <= NATURAL_DATE_RANGES.DAY_OF_MOON.MAX &&
-        isValidNumber(date.dayOfWeek) &&
-        date.dayOfWeek >= NATURAL_DATE_RANGES.DAY_OF_WEEK.MIN &&
-        date.dayOfWeek <= NATURAL_DATE_RANGES.DAY_OF_WEEK.MAX &&
-        isValidNumber(date.dayOfYear) &&
-        date.dayOfYear >= 1 &&
-        date.dayOfYear <= date.yearDuration &&
-        typeof date.isRainbowDay === 'boolean' &&
-        isValidAngle(date.time) &&
-        isValidTimestamp(date.yearStart) &&
-        isValidNumber(date.yearDuration) &&
-        isValidTimestamp(date.nadir));
-};
-/**
- * Validates if a string is a valid cache key.
- *
- * Cache keys are used for storing and retrieving calculated values
- * to improve performance. Valid keys must be non-empty strings.
- *
- * @param key - Cache key to validate
- * @returns True if key is valid
- *
- * @example
- * isValidCacheKey('SUN_2023_45.5_0'); // true
- * isValidCacheKey(''); // false (empty string)
- * isValidCacheKey(123); // false (not a string)
- */
-export const isValidCacheKey = (key) => {
-    return typeof key === 'string' && key.length > 0;
-};
-/**
- * Throws a formatted error for invalid parameters.
- *
- * This utility function creates consistent error messages for validation failures,
- * making it easier to identify and fix issues with invalid inputs.
- *
- * @param paramName - Name of the invalid parameter
- * @param value - Invalid value
- * @param expectedType - Description of expected type/format
- * @throws {Error} Formatted validation error
- *
- * @example
- * // If latitude is invalid:
- * throwValidationError('latitude', 95, 'number between -90 and 90');
- * // Throws: "Error: Invalid latitude: 95. Expected number between -90 and 90"
- */
-export const throwValidationError = (paramName, value, expectedType) => {
-    throw new Error(`Invalid ${paramName}: ${value}. Expected ${expectedType}`);
-};
-//# sourceMappingURL=validators.js.map

package/dist/utils/validators.js.map

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