@omnisass/library 0.2.0 → 0.3.0

package/modules/utilities/validators/number/_is-number-unitless.scss

@@ -1,5 +1,6 @@
 @use 'sass:math';
-@use '../type-of/is-number' as type-of;
+@use '../type-of/is-number' as *;
+@use '../../loggers/log-invalid-type' as *;
 
 /// Проверяет, является ли число безразмерным.
 ///
@@ -63,13 +64,13 @@
 /// 	@debug is-number-unitless(-0);           // true (отрицательный ноль)
 /// 	@debug is-number-unitless(+0);           // true (положительный ноль)
 /// 	@debug is-number-unitless(calc(10 + 5)); // true
-/// @example scss - Нечисловые значения (всегда false)
-/// 	@debug is-number-unitless("16");       // false
-/// 	@debug is-number-unitless(#ff0000);    // false
-/// 	@debug is-number-unitless(true);       // false
-/// 	@debug is-number-unitless(null);       // false
-/// 	@debug is-number-unitless(auto);       // false
-/// 	@debug is-number-unitless((16, "px")); // false
+/// @example scss - Нечисловые значения (всегда Error)
+/// 	@debug is-number-unitless("16");       // Error: "⛔ Параметр «$value» функции «is-number-unitless» получил неожиданный тип «string», хотя ожидается «number»"
+/// 	@debug is-number-unitless(#ff0000);    // Error: "⛔ Параметр «$value» функции «is-number-unitless» получил неожиданный тип «color», хотя ожидается «number»"
+/// 	@debug is-number-unitless(true);       // Error: "⛔ Параметр «$value» функции «is-number-unitless» получил неожиданный тип «bool», хотя ожидается «number»"
+/// 	@debug is-number-unitless(null);       // Error: "⛔ Параметр «$value» функции «is-number-unitless» получил неожиданный тип «null», хотя ожидается «number»"
+/// 	@debug is-number-unitless(auto);       // Error: "⛔ Параметр «$value» функции «is-number-unitless» получил неожиданный тип «string», хотя ожидается «number»"
+/// 	@debug is-number-unitless((16, "px")); // Error: "⛔ Параметр «$value» функции «is-number-unitless» получил неожиданный тип «list», хотя ожидается «number»"
 /// @param {*} $value - Значение для проверки. Может быть
 /// 	любого типа, но функция вернет `true` только для
 /// 	чисел, которые не имеют единиц измерения. Любые
@@ -80,9 +81,49 @@
 /// 	`math.unit($value)` является пустой строкой).
 /// 	Возвращает `false` для чисел с единицами измерения и всех
 /// 	нечисловых значений.
-/// @throws {Error} - Не выбрасывает ошибков, безопасно
-/// 	обрабатывает значения любого типа. Функция `math.unit()`
-/// 	безопасно работает с любыми значениями.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-number-unitless($value) {
-	@return type-of.is-number($value) and math.unit($value) == '';
+
+	// Проверка типа входного параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'is-number-unitless',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Основная логика выполняется только если $value является
+	// корректным числом.
+	@else {
+
+		// Логика проверки, является ли число безразмерным:
+		// Условие состоит из двух частей, соединенных оператором and:
+		// 1. ($value) - проверка на истинность значения
+		//    В Sass любое не-null значение считается истинным,
+		//    но это условие может быть избыточным после проверки is-number()
+		// 2. math.unit($value) == '' - проверяет, что строка единиц измерения
+		//    пустая. Функция math.unit() возвращает единицу измерения
+		//    числа как строку. Для безразмерных чисел возвращает пустую строку.
+		//
+		// Возвращаемое значение:
+		// - true: если значение является числом И имеет пустую единицу измерения
+		// - false: если значение не является числом ИЛИ имеет непустую единицу измерения
+		//
+		// Ключевая особенность: функция возвращает булево значение (true/false),
+		// которое можно использовать в условных конструкциях @if/@else.
+		@return ($value) and math.unit($value) == '';
+
+	}
+
 }

package/modules/utilities/validators/number/_is-number-zero.scss

@@ -1,4 +1,5 @@
-@use '../type-of/is-number' as type-of;
+@use '../type-of/is-number' as *;
+@use '../../loggers/log-invalid-type' as *;
 
 /// Проверяет, является ли значение нулем (числовым нулем).
 ///
@@ -54,12 +55,12 @@
 /// 	@debug is-number-zero(0.0000001);   // false (очень малое, но не ноль)
 /// 	@debug is-number-zero(1e-10);       // false (научная нотация, не ноль)
 /// @example scss - Нечисловые значения
-/// 	@debug is-number-zero("0");         // false
-/// 	@debug is-number-zero("zero");      // false
-/// 	@debug is-number-zero(null);        // false
-/// 	@debug is-number-zero(false);       // false
-/// 	@debug is-number-zero((0, 0, 0));   // false (список нулей)
-/// 	@debug is-number-zero(none);        // false
+/// 	@debug is-number-zero("0");         // Error: "⛔ Параметр «$value» функции «is-number-zero» получил неожиданный тип «string», хотя ожидается «number»"
+/// 	@debug is-number-zero("zero");      // Error: "⛔ Параметр «$value» функции «is-number-zero» получил неожиданный тип «string», хотя ожидается «number»"
+/// 	@debug is-number-zero(null);        // Error: "⛔ Параметр «$value» функции «is-number-zero» получил неожиданный тип «null», хотя ожидается «number»"
+/// 	@debug is-number-zero(false);       // Error: "⛔ Параметр «$value» функции «is-number-zero» получил неожиданный тип «bool», хотя ожидается «number»"
+/// 	@debug is-number-zero((0, 0, 0));   // Error: "⛔ Параметр «$value» функции «is-number-zero» получил неожиданный тип «list», хотя ожидается «number»"
+/// 	@debug is-number-zero(none);        // Error: "⛔ Параметр «$value» функции «is-number-zero» получил неожиданный тип «string», хотя ожидается «number»"
 /// @param {*} $value - Значение для проверки. Может быть
 /// 	любого типа, но функция вернет `true` только для
 /// 	чисел равных нулю, включая ноль с единицами
@@ -68,8 +69,51 @@
 /// 	является числом и строго равно нулю. Во всех
 /// 	остальных случаях возвращает `false`, включая
 /// 	ненулевые числа и значения других типов.
-/// @throws {Error} - Не выбрасывает ошибков, безопасно
-/// 	обрабатывает значения любого типа.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-number-zero($value) {
-	@return type-of.is-number($value) and $value == 0;
+
+	// Проверка типа входного параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'is-number-zero',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Основная логика выполняется только если $value является
+	// корректным числом.
+	@else {
+
+		// Логика проверки, является ли число нулем:
+		// Условие состоит из двух частей, соединенных оператором and:
+		// 1. is-number($value) - повторная проверка, что значение является числом
+		//    (хотя эта проверка уже была выполнена выше, она добавляет
+		//    дополнительную безопасность для внутренней логики)
+		// 2. $value == 0 - проверяет, равно ли значение нулю
+		//    Оператор == сравнивает числовые значения, учитывая единицы измерения
+		//    (например, 0px == 0 вернет true, 0rem == 0px вернет true)
+		//
+		// Возвращаемое значение:
+		// - true: если значение является числом И равно нулю
+		// - false: если значение не является числом ИЛИ не равно нулю
+		//
+		// Ключевая особенность: функция корректно работает с числами
+		// с разными единицами измерения (0px, 0rem, 0em и т.д.),
+		// так как Sass считает все нулевые значения равными,
+		// независимо от единиц измерения.
+		@return is-number($value) and $value == 0;
+
+	}
+
 }

package/modules/utilities/validators/string/_is-string-contained.scss

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../type-of/is-string' as *;
+@use '../../loggers/log-invalid-type' as *;
 
 /// Проверяет, содержится ли подстрока в указанной строке.
 ///
@@ -100,9 +102,62 @@
 /// 	и `false` в противном случае. Возвращаемые значения:
 /// - `true`: подстрока существует в строке (хотя бы одно вхождение)
 /// - `false`: подстрока не найдена или является пустой строкой
-/// @throws Не выбрасывает ошибок, корректно обрабатывает все
-/// 	строковые значения. Невалидные аргументы приводятся к
-/// 	строковому типу.
+/// @throws {Error} - Выбрасывает ошибку, если параметрам передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-string-contained($string, $substring) {
-	@return string.index($string, $substring) != null;
+
+	// Проверка типа первого параметра: ожидается строка для поиска.
+	// Функция is-string() проверяет, является ли $string строкой.
+	// В этой строке будет осуществляться поиск подстроки.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции поиска с нестроковыми данными.
+		@return log-invalid-type(
+			'is-string-contained',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается искомая подстрока.
+	// $substring определяет строку, которую нужно найти внутри $string.
+	@else if not is-string($substring) {
+
+		// Если $substring не является строкой, возвращаем ошибку.
+		// Проверка выполняется только если $string прошел валидацию.
+		@return log-invalid-type(
+			'is-string-contained',
+			$substring,
+			'$substring',
+			'string'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем поиск подстроки.
+	@else {
+
+		// Логика проверки наличия подстроки в строке:
+		// 1. string.index($string, $substring) - ищет первое вхождение
+		//    подстроки в строке и возвращает ее начальную позицию (индекс)
+		//    Если подстрока не найдена, возвращает null
+		// 2. ... != null - сравнивает результат с null
+		//    - Если результат не равен null → подстрока найдена → true
+		//    - Если результат равен null → подстрока не найдена → false
+		//
+		// Возвращаемое значение:
+		// - true: если подстрока содержится в строке хотя бы один раз
+		// - false: если подстрока не содержится в строке
+		//
+		// Ключевая особенность: функция возвращает булево значение (true/false),
+		// которое можно использовать в условных конструкциях @if/@else.
+		@return string.index($string, $substring) != null;
+
+	}
+
 }

package/modules/utilities/validators/string/_is-string-empty.scss

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../type-of/is-string' as *;
+@use '../../loggers/log-invalid-type' as *;
 
 /// Проверяет, является ли строка пустой.
 ///
@@ -39,18 +41,56 @@
 /// 	@debug is-string-empty('\n\t');     // false (строка с escape-символами)
 /// 	@debug is-string-empty('   ');      // false (строка из нескольких пробелов)
 /// @example scss - Нестроковые значения
-/// 	@debug is-string-empty(null);       // Error: $string: null is not a string.
-/// 	@debug is-string-empty(false);      // Error: $string: false is not a string.
-/// 	@debug is-string-empty(0);          // Error: $string: 0 is not a string.
-/// 	@debug is-string-empty(());         // Error: $string: () is not a string.
-/// 	@debug is-string-empty((0, 0, 0));   // Error: $string: (0, 0, 0) is not a string.
+/// 	@debug is-string-empty(null);       // Error: "⛔ Параметр «$string» функции «is-string-empty» получил неожиданный тип «null», хотя ожидается «string»"
+/// 	@debug is-string-empty(false);      // Error: "⛔ Параметр «$string» функции «is-string-empty» получил неожиданный тип «bool», хотя ожидается «string»"
+/// 	@debug is-string-empty(0);          // Error: "⛔ Параметр «$string» функции «is-string-empty» получил неожиданный тип «number», хотя ожидается «string»"
+/// 	@debug is-string-empty((0, 0, 0));   // Error: "⛔ Параметр «$string» функции «is-string-empty» получил неожиданный тип «list», хотя ожидается «string»"
 /// @param {String} $string - Строка для проверки. Функция
 /// 	ожидает получить строковый тип данных.
 /// @return {Boolean} - Возвращает `true`, если длина строки
 /// 	равна нулю. Возвращает `false` для любой строки
 /// 	ненулевой длины, а также для значений других типов.
-/// @throws {Error} - Функция выдаёт ошибки, если в параметр
-/// 	`$string` передаётся значение, не являющееся строкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-string-empty($string) {
-	@return string.length($string) == 0;
+
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $string строкой
+	// (тип данных string). Строка будет проверена на пустоту.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции проверки с нестроковыми данными.
+		@return log-invalid-type(
+			'is-string-empty',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Основная логика выполняется только если $string является
+	// корректной строкой.
+	@else {
+
+		// Логика проверки, является ли строка пустой:
+		// 1. string.length($string) - возвращает количество символов в строке
+		//    Для пустой строки возвращает 0
+		// 2. ... == 0 - сравнивает длину строки с нулем
+		//
+		// Возвращаемое значение:
+		// - true: если длина строки равна 0 (пустая строка)
+		// - false: если длина строки больше 0 (непустая строка)
+		//
+		// Ключевая особенность: функция корректно обрабатывает строки,
+		// содержащие только пробельные символы (они не считаются пустыми,
+		// так как имеют ненулевую длину). Для проверки строк, состоящих
+		// только из пробелов, может потребоваться дополнительная обработка.
+		@return string.length($string) == 0;
+
+	}
+
 }

package/modules/utilities/validators/string/_is-string-ending-with.scss

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../type-of/is-string' as *;
+@use '../../loggers/log-invalid-type' as *;
 
 /// Проверяет, заканчивается ли строка указанной подстрокой.
 ///
@@ -54,13 +56,70 @@
 /// 	указанной подстрокой. Возвращает `false`, если строка не заканчивается
 /// 	подстрокой, если подстрока длиннее строки, или если регистр
 /// 	символов не совпадает.
-/// @throws {Error} - Не выбрасывает ошибок. Если переданы нестроковые
-/// 	значения, функция может вернуть неожиданный результат или вызвать
-/// 	ошибку выполнения.
+/// @throws {Error} - Выбрасывает ошибку, если параметрам передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-string-ending-with($string, $substring) {
 
-	$-substring-length: string.length($substring);
+	// Проверка типа первого параметра: ожидается строка для проверки.
+	// Функция is-string() проверяет, является ли $string строкой.
+	// Будет проверено, заканчивается ли эта строка указанной подстрокой.
+	@if not is-string($string) {
 
-	@return string.slice($string, -$-substring-length) == $substring;
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции проверки с нестроковыми данными.
+		@return log-invalid-type(
+			'is-string-ending-with',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается искомая подстрока.
+	// $substring определяет строку, которой должна заканчиваться $string.
+	@else if not is-string($substring) {
+
+		// Если $substring не является строкой, возвращаем ошибку.
+		// Проверка выполняется только если $string прошел валидацию.
+		@return log-invalid-type(
+			'is-string-ending-with',
+			$substring,
+			'$substring',
+			'string'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - проверяем окончание строки.
+	@else {
+
+		// Определение длины искомой подстроки.
+		// string.length() возвращает количество символов в подстроке.
+		// Это значение используется для извлечения соответствующей
+		// части из конца основной строки.
+		$-substring-length: string.length($substring);
+
+		// Логика проверки окончания строки:
+		// 1. string.slice($string, -$-substring-length) - извлекает
+		//    подстроку из конца основной строки, длина которой равна
+		//    длине искомой подстроки.
+		//    Отрицательный индекс -$-substring-length означает
+		//    "начинать с конца строки, отступив $-substring-length символов".
+		// 2. ... == $substring - сравнивает извлеченную подстроку
+		//    с искомой подстрокой.
+		//
+		// Возвращаемое значение:
+		// - true: если строка заканчивается указанной подстрокой
+		// - false: если строка не заканчивается указанной подстрокой
+		//
+		// Ключевая особенность: функция корректно работает даже если
+		// основная строка короче искомой подстроки (в этом случае
+		// string.slice() вернет меньше символов, и сравнение даст false).
+		@return string.slice($string, -$-substring-length) == $substring;
+
+	}
 
 }

package/modules/utilities/validators/string/_is-string-starting-with.scss

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../type-of/is-string' as *;
+@use '../../loggers/log-invalid-type' as *;
 
 /// Проверяет, начинается ли строка с указанной подстроки.
 ///
@@ -54,13 +56,63 @@
 /// 	с указанной подстроки. Возвращает `false`, если строка не
 /// 	начинается с подстроки, если подстрока длиннее строки, или
 /// 	если регистр символов не совпадает.
-/// @throws {Error} - Не выбрасывает ошибок. Если переданы
-/// 	нестроковые значения, функция может вернуть неожиданный
-/// 	результат или вызвать ошибку выполнения.
+/// @throws {Error} - Выбрасывает ошибку, если параметрам передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-string-starting-with($string, $substring) {
-	@return string.slice(
-		$string,
-		1,
-		string.length($substring)
-	) == $substring;
+
+	// Проверка типа первого параметра: ожидается строка для проверки.
+	// Функция is-string() проверяет, является ли $string строкой.
+	// Будет проверено, начинается ли эта строка указанной подстрокой.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции проверки с нестроковыми данными.
+		@return log-invalid-type(
+			'is-string-starting-with',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается искомая подстрока.
+	// $substring определяет строку, которой должна начинаться $string.
+	@else if not is-string($substring) {
+
+		// Если $substring не является строкой, возвращаем ошибку.
+		// Проверка выполняется только если $string прошел валидацию.
+		@return log-invalid-type(
+			'is-string-starting-with',
+			$substring,
+			'$substring',
+			'string'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - проверяем начало строки.
+	@else {
+
+		// Логика проверки начала строки:
+		// 1. string.length($substring) - вычисляет длину искомой подстроки
+		// 2. string.slice($string, 1, ...) - извлекает подстроку из
+		//    начала основной строки, начиная с первого символа (позиция 1)
+		//    и заканчивая символом с индексом, равным длине подстроки
+		// 3. ... == $substring - сравнивает извлеченную подстроку
+		//    с искомой подстрокой
+		//
+		// Возвращаемое значение:
+		// - true: если строка начинается с указанной подстроки
+		// - false: если строка не начинается с указанной подстроки
+		//
+		// Ключевая особенность: функция корректно работает даже если
+		// основная строка короче искомой подстроки (в этом случае
+		// string.slice() вернет меньше символов, и сравнение даст false).
+		@return string.slice($string, 1, string.length($substring)) == $substring;
+
+	}
+
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@omnisass/library",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Библиотека функций и миксинов, написанная на языке CSS-препроцессора Sass. Она предназначена для того, чтобы упростить, ускорить и улучшить процесс создания стилей для веб-сайтов.",
 	"main": "index.scss",
 	"scripts": {

package/package.scss

@@ -42,7 +42,7 @@ $title: "OmniSass";
 /// @name description
 /// @access private
 /// @type String
-$description: "Набор утилит, миксинов, расширений на языке препроцессора @sass для помощи в ускорении, упрощении и улучщения процесса написания CSS-стилей.";
+$description:  "Набор утилит, миксинов, расширений на языке препроцессора Sass для помощи в ускорении, упрощении и улучщения процесса написания CSS-стилей.";
 
 /// Текущая версия библиотеки - используется для контроля
 /// версий и отслеживания изменений.
@@ -53,7 +53,7 @@ $description: "Набор утилит, миксинов, расширений
 /// @name version
 /// @access private
 /// @type String | Number
-$version: "0.2.0";
+$version: "0.3.0";
 
 /// Тип лицензии библиотеки - используется для указания
 /// условий использования и распространения.
@@ -79,7 +79,7 @@ $sources: "https://sourcecraft.dev/omnisass/library";
 /// @name author
 /// @access private
 /// @link https://t.me/therteenten Telegram
-/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
 /// @prop {String} author.name [Murad Rustamov (therteenten)] - Автор проекта
 /// @prop {String} author.email [therteenten@ya.ru] - Адрес электронной почты автора проекта
 /// @type Map
@@ -91,12 +91,12 @@ $author: (
 /// Миксин создающий комментарий с основной информацией о
 /// библиотеке в итоговом CSS-файле.
 /// ---
-/// @name genOmniSassFingerprint
+/// @name gen-omnisass-fingerprint
 /// @access public
 /// @example scss - Базовое использование
-/// 	@include genOmniSassFingerprint();
+/// 	@include gen-omnisass-fingerprint();
 /// @example scss - Использование без лога в консоль
-/// 	@include genOmniSassFingerprint(false);
+/// 	@include gen-omnisass-fingerprint(false);
 /// @example css - Примерный итоговый результат
 /// 	/*
 /// 	 * @package:
@@ -125,7 +125,7 @@ $author: (
 /// @require {Variable} $title
 /// @require {Variable} $author
 /// @require {Variable} $license
-@mixin genOmniSassFingerprint($show-console-log: true) {
+@mixin gen-omnisass-fingerprint($show-console-log: true) {
 
 	$-author-name: map.get($author, name);
 	$-author-email: map.get($author, email);
@@ -148,7 +148,8 @@ $author: (
 		*/
 
 		@if ($show-console-log) == true {
-			@debug "#{$title} #{$version} using!";
+			@debug "🎉 Используется #{$title} #{$version}. Спасибо за доверие)";
+			@debug "   #{$title} #{$version} is used. Thank you for your trust)";
 		}
 
 	}