native-document 1.0.164 → 1.0.166

package/src/core/utils/filters/standard.js

@@ -1,47 +1,116 @@
-import Validator from "../../utils/validator";
-import { createFilter, createMultiSourceFilter } from "./utils";
-import DebugManager from "../debug-manager";
-
+import Validator from '../../utils/validator';
+import { createFilter, createMultiSourceFilter } from './utils';
+import DebugManager from '../debug-manager';
 
+/**
+ * Creates a filter that passes values strictly equal to the target.
+ *
+ * @param {*|ObservableItem} observableOrValue - Static value or observable to compare against
+ * @returns {FilterResult}
+ * @example
+ * const statusFilter = equals('active');
+ * users.where({ status: statusFilter });
+ */
 export function equals(observableOrValue){
     return createFilter(observableOrValue, (value, target) => value === target);
 }
 
+/**
+ * Creates a filter that passes values not strictly equal to the target.
+ *
+ * @param {*|ObservableItem} observableOrValue - Static value or observable
+ * @returns {FilterResult}
+ */
 export function notEquals(observableOrValue){
     return createFilter(observableOrValue, (value, target) => value !== target);
 }
 
+/**
+ * Creates a filter that passes values greater than the target.
+ *
+ * @param {number|ObservableItem<number>} observableOrValue - Threshold value or observable
+ * @returns {FilterResult}
+ */
 export function greaterThan(observableOrValue){
     return createFilter(observableOrValue, (value, target) => value > target);
 }
 
+/**
+ * Creates a filter that passes values greater than or equal to the target.
+ *
+ * @param {number|ObservableItem<number>} observableOrValue - Threshold value or observable
+ * @returns {FilterResult}
+ */
 export function greaterThanOrEqual(observableOrValue){
     return createFilter(observableOrValue, (value, target) => value >= target);
 }
 
+/**
+ * Creates a filter that passes values less than the target.
+ *
+ * @param {number|ObservableItem<number>} observableOrValue - Threshold value or observable
+ * @returns {FilterResult}
+ */
 export function lessThan(observableOrValue){
     return createFilter(observableOrValue, (value, target) => value < target);
 }
 
+/**
+ * Creates a filter that passes values less than or equal to the target.
+ *
+ * @param {number|ObservableItem<number>} observableOrValue - Threshold value or observable
+ * @returns {FilterResult}
+ */
 export function lessThanOrEqual(observableOrValue){
     return createFilter(observableOrValue, (value, target) => value <= target);
 }
 
+/**
+ * Creates a filter that passes values between min and max (inclusive).
+ * Both min and max can be static values or observables.
+ *
+ * @param {number|ObservableItem<number>} minObservableOrValue - Lower bound
+ * @param {number|ObservableItem<number>} maxObservableOrValue - Upper bound
+ * @returns {FilterResult}
+ * @example
+ * items.where({ age: between(18, 65) });
+ */
 export function between(minObservableOrValue, maxObservableOrValue){
     return createMultiSourceFilter(
         [minObservableOrValue, maxObservableOrValue],
-        (value, [min, max]) => value >= min && value <= max
+        (value, [min, max]) => value >= min && value <= max,
     );
 }
 
+/**
+ * Creates a filter that passes values included in the given array.
+ *
+ * @param {Array|ObservableItem<Array>} observableOrArray - Array to check membership in
+ * @returns {FilterResult}
+ * @example
+ * items.where({ role: inArray(['admin', 'editor']) });
+ */
 export function inArray(observableOrArray){
     return createFilter(observableOrArray, (value, arr) => arr.includes(value));
 }
 
+/**
+ * Creates a filter that passes values not included in the given array.
+ *
+ * @param {Array|ObservableItem<Array>} observableOrArray - Array to check exclusion from
+ * @returns {FilterResult}
+ */
 export function notIn(observableOrArray){
     return createFilter(observableOrArray, (value, arr) => !arr.includes(value));
 }
 
+/**
+ * Creates a filter that passes when the value is empty (null, undefined, empty string, or empty array).
+ * Pass false as the argument to filter for non-empty values instead.
+ *
+ * @param {boolean|ObservableItem<boolean>} [observableOrValue=true] - If true, filters empty values; if false, filters non-empty
+ * @returns {FilterResult}
+ */
 export function isEmpty(observableOrValue = true){
     return createFilter(observableOrValue, (value, shouldBeEmpty) => {
         const isActuallyEmpty = !value || value === '' ||
@@ -51,6 +120,13 @@ export function isEmpty(observableOrValue = true){
     });
 }
 
+/**
+ * Creates a filter that passes when the value is not empty.
+ * Pass false as the argument to filter for empty values instead.
+ *
+ * @param {boolean|ObservableItem<boolean>} [observableOrValue=true] - If true, filters non-empty values
+ * @returns {FilterResult}
+ */
 export function isNotEmpty(observableOrValue = true){
     return createFilter(observableOrValue, (value, shouldBeNotEmpty) => {
         const isActuallyNotEmpty = !!value && value !== '' &&
@@ -60,6 +136,18 @@ export function isNotEmpty(observableOrValue = true){
     });
 }
 
+/**
+ * Creates a filter that tests the value against a pattern (string or regex).
+ *
+ * @param {string|RegExp|ObservableItem} patternObservableOrValue - Pattern to match against
+ * @param {boolean|ObservableItem<boolean>} [asRegexObservableOrValue=true] - If true, treat pattern as a regex; if false, use case-insensitive substring match
+ * @param {string|ObservableItem<string>} [flagsObservableOrValue=''] - Regex flags (e.g. 'i', 'g')
+ * @returns {FilterResult}
+ * @example
+ * const search = Observable('john');
+ * users.where({ name: match(search) }); // regex match, reactive
+ * users.where({ name: match('john', false) }); // case-insensitive substring
+ */
 export function match(patternObservableOrValue, asRegexObservableOrValue = true, flagsObservableOrValue = ''){
     return createMultiSourceFilter(
         [patternObservableOrValue, asRegexObservableOrValue, flagsObservableOrValue],
@@ -80,10 +168,19 @@ export function match(patternObservableOrValue, asRegexObservableOrValue = true,
                 return String(value).toLowerCase().includes(String(pattern).toLowerCase());
             }
             return String(value).includes(String(pattern));
-        }
+        },
     );
 }
 
+/**
+ * Combines multiple filters with AND logic — all filters must pass.
+ * Merges dependencies from all child filters automatically.
+ *
+ * @param {...FilterResult} filters - Filters to combine
+ * @returns {FilterResult}
+ * @example
+ * items.where({ _: and(greaterThan(18), lessThan(65)) });
+ */
 export function and(...filters){
     const dependencies = filters
         .flatMap(f => f.dependencies ? (Array.isArray(f.dependencies) ? f.dependencies : [f.dependencies]) : [])
@@ -91,10 +188,19 @@ export function and(...filters){
 
     return {
         dependencies: dependencies.length > 0 ? dependencies : null,
-        callback: (value) => filters.every(f => f.callback(value))
+        callback: (value) => filters.every(f => f.callback(value)),
     };
 }
 
+/**
+ * Combines multiple filters with OR logic — at least one filter must pass.
+ * Merges dependencies from all child filters automatically.
+ *
+ * @param {...FilterResult} filters - Filters to combine
+ * @returns {FilterResult}
+ * @example
+ * items.where({ _: or(equals('admin'), equals('editor')) });
+ */
 export function or(...filters){
     const dependencies = filters
         .flatMap(f => f.dependencies ? (Array.isArray(f.dependencies) ? f.dependencies : [f.dependencies]) : [])
@@ -102,17 +208,36 @@ export function or(...filters){
 
     return {
         dependencies: dependencies.length > 0 ? dependencies : null,
-        callback: (value) => filters.some(f => f.callback(value))
+        callback: (value) => filters.some(f => f.callback(value)),
     };
 }
 
+/**
+ * Negates a filter — passes when the given filter does not pass.
+ *
+ * @param {FilterResult} filter - Filter to negate
+ * @returns {FilterResult}
+ * @example
+ * items.where({ status: not(equals('deleted')) });
+ */
 export function not(filter){
     return {
         dependencies: filter.dependencies,
-        callback: (value) => !filter.callback(value)
+        callback: (value) => !filter.callback(value),
     };
 }
 
+/**
+ * Creates a custom filter from a callback and a list of observable dependencies.
+ * The callback receives the item value followed by the current values of all observables.
+ *
+ * @param {(value: *, ...depValues: any[]) => boolean} callbackFn - Filter function
+ * @param {...ObservableItem} observables - Observable dependencies passed as extra arguments to callback
+ * @returns {FilterResult}
+ * @example
+ * const minAge = Observable(18);
+ * items.where({ age: custom((age, min) => age >= min, minAge) });
+ */
 export function custom(callbackFn, ...observables){
     const dependencies = observables.filter(Validator.isObservable);
 
@@ -120,10 +245,10 @@ export function custom(callbackFn, ...observables){
         dependencies: dependencies.length > 0 ? dependencies : null,
         callback: (value) => {
             const values = observables.map(o =>
-                Validator.isObservable(o) ? o.val() : o
+                Validator.isObservable(o) ? o.val() : o,
             );
             return callbackFn(value, ...values);
-        }
+        },
     };
 }
 

package/src/core/utils/filters/strings.js

@@ -1,6 +1,18 @@
-import { createFilter, createMultiSourceFilter } from "./utils";
-
+import { createFilter, createMultiSourceFilter } from './utils';
 
+/**
+ * Creates a filter that passes when the value includes the given query string.
+ * Case-insensitive by default.
+ * Alias: contains
+ *
+ * @param {string|ObservableItem<string>} observableOrValue - Substring to search for
+ * @param {boolean} [caseSensitive=false] - If true, comparison is case-sensitive
+ * @returns {FilterResult}
+ * @example
+ * const search = Observable('john');
+ * users.where({ name: includes(search) }); // reactive, case-insensitive
+ * users.where({ name: includes('John', true) }); // case-sensitive
+ */
 export function includes(observableOrValue, caseSensitive = false){
     return createFilter(observableOrValue, (value, query) => {
         if (!value) return false;
@@ -14,6 +26,16 @@ export function includes(observableOrValue, caseSensitive = false){
 
 export const contains = includes;
 
+/**
+ * Creates a filter that passes when the value starts with the given query string.
+ * Case-insensitive by default.
+ *
+ * @param {string|ObservableItem<string>} observableOrValue - Prefix to search for
+ * @param {boolean} [caseSensitive=false] - If true, comparison is case-sensitive
+ * @returns {FilterResult}
+ * @example
+ * users.where({ name: startsWith('Jo') });
+ */
 export function startsWith(observableOrValue, caseSensitive = false){
     return createFilter(observableOrValue, (value, query) => {
         if (!query) return true;
@@ -24,6 +46,16 @@ export function startsWith(observableOrValue, caseSensitive = false){
     });
 }
 
+/**
+ * Creates a filter that passes when the value ends with the given query string.
+ * Case-insensitive by default.
+ *
+ * @param {string|ObservableItem<string>} observableOrValue - Suffix to search for
+ * @param {boolean} [caseSensitive=false] - If true, comparison is case-sensitive
+ * @returns {FilterResult}
+ * @example
+ * files.where({ name: endsWith('.js') });
+ */
 export function endsWith(observableOrValue, caseSensitive = false){
     return createFilter(observableOrValue, (value, query) => {
         if (!query) return true;

package/src/core/utils/filters/utils.js

@@ -1,10 +1,23 @@
-import Validator from "../../utils/validator";
+import Validator from '../../utils/validator';
 
+/**
+ * Converts a value to a Date object. Returns the value as-is if it's already a Date.
+ *
+ * @param {Date|number|string} value - Value to convert
+ * @returns {Date}
+ */
 export function toDate(value) {
     if (value instanceof Date) return value;
     return new Date(value);
 }
 
+/**
+ * Returns true if two date values fall on the same calendar day (year, month, day).
+ *
+ * @param {Date|number|string} date1 - First date
+ * @param {Date|number|string} date2 - Second date
+ * @returns {boolean}
+ */
 export function isSameDay(date1, date2) {
     const d1 = toDate(date1);
     const d2 = toDate(date2);
@@ -13,29 +26,52 @@ export function isSameDay(date1, date2) {
         d1.getDate() === d2.getDate();
 }
 
+/**
+ * Returns the total number of seconds elapsed since midnight for the given date's time component.
+ * Used internally for time range comparisons.
+ *
+ * @param {Date|number|string} date - Date value to extract time from
+ * @returns {number} Seconds since midnight (0–86399)
+ */
 export function getSecondsOfDay(date) {
     const d = toDate(date);
     return (d.getHours() * 3600) + (d.getMinutes() * 60) + d.getSeconds();
 }
 
+/**
+ * Creates a FilterResult from a single observable or static value and a comparison callback.
+ * If the value is an observable, it is registered as a dependency so the filter reacts to changes.
+ *
+ * @param {*|ObservableItem} observableOrValue - Observable or static value used as the comparison target
+ * @param {(value: *, target: *) => boolean} callbackFn - Filter function receiving (item value, target value)
+ * @returns {{ dependencies: ObservableItem|null, callback: (value: *) => boolean }} FilterResult
+ */
 export function createFilter(observableOrValue, callbackFn){
     const isObservable = Validator.isObservable(observableOrValue);
 
     return {
         dependencies: isObservable ? observableOrValue : null,
-        callback: (value) => callbackFn(value, isObservable ? observableOrValue.val() : observableOrValue)
+        callback: (value) => callbackFn(value, isObservable ? observableOrValue.val() : observableOrValue),
     };
 }
 
+/**
+ * Creates a FilterResult from multiple observable or static sources and a multi-value comparison callback.
+ * All observable sources are registered as dependencies.
+ *
+ * @param {Array<*|ObservableItem>} sources - Array of observables or static values
+ * @param {(value: *, targets: any[]) => boolean} callbackFn - Filter function receiving (item value, array of resolved source values)
+ * @returns {{ dependencies: ObservableItem[]|null, callback: (value: *) => boolean }} FilterResult
+ */
 export function createMultiSourceFilter(sources, callbackFn){
     const observables = sources.filter(Validator.isObservable);
 
     const getValues = () => sources.map(src =>
-        Validator.isObservable(src) ? src.val() : src
+        Validator.isObservable(src) ? src.val() : src,
     );
 
     return {
         dependencies: observables.length > 0 ? observables : null,
-        callback: (value) => callbackFn(value, getValues())
+        callback: (value) => callbackFn(value, getValues()),
     };
 }

package/src/core/utils/formatters.js

@@ -12,7 +12,7 @@ const $parseDateParts = (value, locale) => {
         }).formatToParts(d).reduce((acc, { type, value }) => {
             acc[type] = value;
             return acc;
-        }, {})
+        }, {}),
     };
 };
 
@@ -38,20 +38,20 @@ export const Formatters = {
             currency,
             notation,
             minimumFractionDigits,
-            maximumFractionDigits
+            maximumFractionDigits,
         }).format(value),
 
     number: (value, locale, { notation, minimumFractionDigits, maximumFractionDigits } = {}) =>
         new Intl.NumberFormat(locale, {
             notation,
             minimumFractionDigits,
-            maximumFractionDigits
+            maximumFractionDigits,
         }).format(value),
 
     percent: (value, locale, { decimals = 1 } = {}) =>
         new Intl.NumberFormat(locale, {
             style:                'percent',
-            maximumFractionDigits: decimals
+            maximumFractionDigits: decimals,
         }).format(value),
 
     date: (value, locale, { format, dateStyle = 'long' } = {}) => {

package/src/core/utils/helpers.js

@@ -1,5 +1,13 @@
-import Validator from "./validator";
+import Validator from './validator';
 
+/**
+ * Calls a function with the given arguments and optional context.
+ *
+ * @internal
+ * @param {Function} fn - Function to invoke
+ * @param {Array} args - Arguments to pass
+ * @param {Object|null} [context] - `this` context, or null to call without binding
+ */
 const invoke = function(fn, args, context) {
     if(context) {
         fn.apply(context, args);
@@ -32,7 +40,7 @@ export const debounce = function(fn, delay, options = {}) {
         // debounce mode: reset the timer for each call
         clearTimeout(timer);
         timer = setTimeout(() => invoke(fn, lastArgs, context), delay);
-    }
+    };
 };
 
 export const nextTick = function(fn) {
@@ -48,12 +56,18 @@ export const nextTick = function(fn) {
     };
 };
 
+
 /**
+ * Returns the unique key for a given item, used by ForEach and ForEachArray for DOM diffing.
+ * Resolution order:
+ * 1. If key is a function: calls key(item, defaultKey)
+ * 2. If key is a string: reads item[key] (unwrapping observables)
+ * 3. Otherwise: returns item value or defaultKey
  *
- * @param {*} item
- * @param {string|null} defaultKey
- * @param {?Function} key
- * @returns {*}
+ * @param {*} item - The item to extract a key from
+ * @param {string|number} defaultKey - Fallback key (usually the array index)
+ * @param {string|Function|null} key - Key property name or custom key function
+ * @returns {string|number} The resolved unique key
  */
 export const getKey = (item, defaultKey, key) => {
     if (Validator.isString(key)) {
@@ -70,10 +84,28 @@ export const getKey = (item, defaultKey, key) => {
     return val ?? defaultKey;
 };
 
+/**
+ * Trims all leading and trailing occurrences of char from str.
+ *
+ * @param {string} str - String to trim
+ * @param {string} char - Character to remove from both ends
+ * @returns {string} Trimmed string
+ * @example
+ * trim('/foo/bar/', '/'); // 'foo/bar'
+ */
 export const trim = function(str, char) {
     return str.replace(new RegExp(`^[${char}]+|[${char}]+$`, 'g'), '');
-}
+};
 
+/**
+ * Deep clones a value. Uses structuredClone when available.
+ * Handles: primitives, Dates, Arrays, plain Objects.
+ * Observables are kept by reference (not cloned); onObservableFound is called for each.
+ *
+ * @param {*} value - Value to clone
+ * @param {((observable: ObservableItem) => void)?} [onObservableFound] - Called for each observable encountered
+ * @returns {*} Deep clone of the value
+ */
 export const deepClone = (value, onObservableFound) => {
     try {
         if(window.structuredClone !== undefined) {

package/src/core/utils/localstorage.js

@@ -1,8 +1,8 @@
-import NativeDocumentError from "../errors/NativeDocumentError";
+import NativeDocumentError from '../errors/NativeDocumentError';
 
 export const LocalStorage = {
     getJson(key) {
-        let value = localStorage.getItem(key);
+        const value = localStorage.getItem(key);
         try {
             return JSON.parse(value);
         } catch (e) {
@@ -33,25 +33,25 @@ export const LocalStorage = {
     },
     has(key) {
         return localStorage.getItem(key) != null;
-    }
-}
+    },
+};
 
 export const $getFromStorage = (key, value) => {
     if(!LocalStorage.has(key)) {
         return value;
     }
     switch (typeof value) {
-        case 'object': return LocalStorage.getJson(key) ?? value;
-        case 'boolean': return LocalStorage.getBool(key) ?? value;
-        case 'number': return LocalStorage.getNumber(key) ?? value;
-        default: return LocalStorage.get(key, value) ?? value;
+    case 'object': return LocalStorage.getJson(key) ?? value;
+    case 'boolean': return LocalStorage.getBool(key) ?? value;
+    case 'number': return LocalStorage.getNumber(key) ?? value;
+    default: return LocalStorage.get(key, value) ?? value;
     }
 };
 
 export const $saveToStorage = (value) => {
     switch (typeof value) {
-        case 'object': return LocalStorage.setJson;
-        case 'boolean': return LocalStorage.setBool;
-        default: return LocalStorage.set;
+    case 'object': return LocalStorage.setJson;
+    case 'boolean': return LocalStorage.setBool;
+    default: return LocalStorage.set;
     }
 };

package/src/core/utils/memoize.js

@@ -1,5 +1,17 @@
 
 
+/**
+ * Wraps a function so it executes at most once.
+ * Later calls return the cached result without re-executing the function.
+ *
+ * @template T
+ * @param {(...args: any[]) => T} fn - Function to wrap
+ * @returns {(...args: any[]) => T} Memoized function
+ * @example
+ * const init = once(() => expensiveSetup());
+ * init(); // runs setup
+ * init(); // returns cached result
+ */
 export const once = (fn) => {
     let result = null;
     return (...args) => {
@@ -11,6 +23,18 @@ export const once = (fn) => {
     };
 };
 
+/**
+ * Creates a lazy proxy that calls fn() once on first property access,
+ * then returns properties from the cached result for all later accesses.
+ *
+ * @template T
+ * @param {() => T} fn - Factory function to call once
+ * @returns {T} Proxy to the lazily created object
+ * @example
+ * const store = autoOnce(() => createExpensiveStore());
+ * store.count; // triggers createExpensiveStore() on first access
+ * store.name; // uses a cached result
+ */
 export const autoOnce = (fn) => {
     let target = null;
     return new Proxy({}, {
@@ -20,10 +44,22 @@ export const autoOnce = (fn) => {
             }
             target = fn();
             return target[key];
-        }
+        },
     });
 };
 
+/**
+ * Wraps a function with key-based memoization.
+ * The first argument is used as the cache key; later arguments are passed to fn.
+ *
+ * @template T
+ * @param {(...args: any[]) => T} fn - Function to memoize
+ * @returns {(key: any, ...args: any[]) => T} Memoized function
+ * @example
+ * const getUser = memoize((id) => fetchUser(id));
+ * getUser('user-1', 1); // fetches
+ * getUser('user-1', 1); // returns cached
+ */
 export const memoize = (fn) => {
     const cache = new Map();
     return (...args) => {
@@ -38,6 +74,23 @@ export const memoize = (fn) => {
     };
 };
 
+/**
+ * Creates a proxy where each property access memorizes the result of calling fn with the property key.
+ * If fn accepts arguments (fn.length > 0), the proxy returns a memoized function instead.
+ *
+ * @template T
+ * @param {((key: string|symbol, ...args?: any[]) => T)} fn - Factory function
+ * @returns {Record<string|symbol, T>} Proxy with per-key memoized results
+ * @example
+ * // fn with no args — result memoized by key
+ * const icons = autoMemoize((name) => loadIcon(name));
+ * icons.home; // calls loadIcon('home'), caches result
+ * icons.home; // returns cached
+ *
+ * // fn with args — returns a memoized function per key
+ * const formatters = autoMemoize((locale, value) => format(value, locale));
+ * formatters.fr('hello'); // calls format('hello', 'fr'), caches under 'fr'
+ */
 export const autoMemoize = (fn) => {
     const cache = new Map();
     return new Proxy({}, {
@@ -52,11 +105,11 @@ export const autoMemoize = (fn) => {
                     const result = fn(...args, key);
                     cache.set(key, result);
                     return result;
-                }
+                };
             }
             const result = fn(key);
             cache.set(key, result);
             return result;
-        }
+        },
     });
 };

package/src/core/utils/plugins-manager.js

@@ -1,4 +1,4 @@
-import DebugManager from "./debug-manager";
+import DebugManager from './debug-manager';
 
 let PluginsManager = null;
 
@@ -18,7 +18,7 @@ if(process.env.NODE_ENV === 'development') {
                 }
                 name = name || plugin.name;
                 if (!name || typeof name !== 'string') {
-                    throw new Error(`Please, provide a valid plugin name`);
+                    throw new Error('Please, provide a valid plugin name');
                 }
                 if($plugins.has(name)) {
                     return;
@@ -73,7 +73,7 @@ if(process.env.NODE_ENV === 'development') {
                         }
                     }
                 }
-            }
+            },
         };
     }());
 }