native-document 1.0.15 → 1.0.16-8.2

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

@@ -0,0 +1,178 @@
+import {createFilter, createMultiSourceFilter, getSecondsOfDay, isSameDay, toDate} from './utils';
+
+/**
+ * Creates a filter that passes when the date value is on the same day as the target date.
+ * Accepts Date objects, timestamps, or ISO strings.
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target date to compare against
+ * @returns {FilterResult}
+ * @example
+ * const today = new Date();
+ * events.where({ date: dateEquals(today) });
+ */
+export const dateEquals = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return isSameDay(value, target);
+    });
+};
+
+/**
+ * Creates a filter that passes when the date value is strictly before the target date (day comparison).
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target date
+ * @returns {FilterResult}
+ */
+export const dateBefore = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return toDate(value) < toDate(target);
+    });
+};
+
+/**
+ * Creates a filter that passes when the date value is strictly after the target date (day comparison).
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target date
+ * @returns {FilterResult}
+ */
+export const dateAfter = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return toDate(value) > toDate(target);
+    });
+};
+
+/**
+ * Creates a filter that passes when the date value falls within the given date range (inclusive, day comparison).
+ *
+ * @param {Date|number|string|ObservableItem} startObservableOrValue - Start of the range
+ * @param {Date|number|string|ObservableItem} endObservableOrValue - End of the range
+ * @returns {FilterResult}
+ * @example
+ * events.where({ date: dateBetween(startDate, endDate) });
+ */
+export const dateBetween = (startObservableOrValue, endObservableOrValue) => {
+    return createMultiSourceFilter(
+        [startObservableOrValue, endObservableOrValue],
+        (value, [start, end]) => {
+            if (!value || !start || !end) return false;
+            const date = toDate(value);
+            return date >= toDate(start) && date <= toDate(end);
+        },
+    );
+};
+
+/**
+ * Creates a filter that passes when the time component (HH:MM:SS) equals the target time.
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target time
+ * @returns {FilterResult}
+ */
+export const timeEquals = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        const d1 = toDate(value);
+        const d2 = toDate(target);
+        return d1.getHours() === d2.getHours() &&
+            d1.getMinutes() === d2.getMinutes() &&
+            d1.getSeconds() === d2.getSeconds();
+    });
+};
+
+/**
+ * Creates a filter that passes when the time component is strictly after the target time.
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target time
+ * @returns {FilterResult}
+ */
+export const timeAfter = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return getSecondsOfDay(value) > getSecondsOfDay(target);
+    });
+};
+
+/**
+ * Creates a filter that passes when the time component is strictly before the target time.
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target time
+ * @returns {FilterResult}
+ */
+export const timeBefore = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return getSecondsOfDay(value) < getSecondsOfDay(target);
+    });
+};
+
+/**
+ * Creates a filter that passes when the time component falls within the given time range (inclusive).
+ *
+ * @param {Date|number|string|ObservableItem} startObservableOrValue - Start time
+ * @param {Date|number|string|ObservableItem} endObservableOrValue - End time
+ * @returns {FilterResult}
+ */
+export const timeBetween = (startObservableOrValue, endObservableOrValue) => {
+    return createMultiSourceFilter([startObservableOrValue, endObservableOrValue],
+        (value, [start, end]) => {
+            if (!value || !start || !end) return false;
+            const date = getSecondsOfDay(value);
+            return date >= getSecondsOfDay(start) && date <= getSecondsOfDay(end);
+        },
+    );
+};
+
+/**
+ * Creates a filter that passes when the full datetime (date + time) equals the target exactly.
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target datetime
+ * @returns {FilterResult}
+ */
+export const dateTimeEquals = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return toDate(value).getTime() === toDate(target).getTime();
+    });
+};
+
+/**
+ * Creates a filter that passes when the full datetime is strictly after the target.
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target datetime
+ * @returns {FilterResult}
+ */
+export const dateTimeAfter = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return toDate(value) > toDate(target);
+    });
+};
+
+/**
+ * Creates a filter that passes when the full datetime is strictly before the target.
+ *
+ * @param {Date|number|string|ObservableItem} observableOrValue - Target datetime
+ * @returns {FilterResult}
+ */
+export const dateTimeBefore = (observableOrValue) => {
+    return createFilter(observableOrValue, (value, target) => {
+        if (!value || !target) return false;
+        return toDate(value) < toDate(target);
+    });
+};
+
+/**
+ * Creates a filter that passes when the full datetime falls within the given range (inclusive).
+ *
+ * @param {Date|number|string|ObservableItem} startObservableOrValue - Start of the range
+ * @param {Date|number|string|ObservableItem} endObservableOrValue - End of the range
+ * @returns {FilterResult}
+ */
+export const dateTimeBetween = (startObservableOrValue, endObservableOrValue) => {
+    return createMultiSourceFilter([startObservableOrValue, endObservableOrValue], (value, [start, end]) => {
+        if (!value || !start || !end) return false;
+        const date = toDate(value);
+        return date >= toDate(start) && date <= toDate(end);
+    });
+};

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

@@ -0,0 +1,4 @@
+export * from './utils';
+export * from './standard';
+export * from './date';
+export * from './strings';

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

@@ -0,0 +1,263 @@
+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,
+    );
+}
+
+/**
+ * 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 === '' ||
+            (Array.isArray(value) && value.length === 0);
+
+        return shouldBeEmpty ? isActuallyEmpty : !isActuallyEmpty;
+    });
+}
+
+/**
+ * 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 !== '' &&
+            (!Array.isArray(value) || value.length > 0);
+
+        return shouldBeNotEmpty ? isActuallyNotEmpty : !isActuallyNotEmpty;
+    });
+}
+
+/**
+ * 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],
+        (value, [pattern, asRegex, flags]) => {
+            if (!pattern) return true;
+
+            if (asRegex){
+                try {
+                    const regex = new RegExp(pattern, flags);
+                    return regex.test(String(value));
+                } catch (error){
+                    DebugManager.warn('Invalid regex pattern:', pattern, error);
+                    return false;
+                }
+            }
+
+            if (!flags || flags === ''){
+                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]) : [])
+        .filter(Validator.isObservable);
+
+    return {
+        dependencies: dependencies.length > 0 ? dependencies : null,
+        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]) : [])
+        .filter(Validator.isObservable);
+
+    return {
+        dependencies: dependencies.length > 0 ? dependencies : null,
+        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),
+    };
+}
+
+/**
+ * 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);
+
+    return {
+        dependencies: dependencies.length > 0 ? dependencies : null,
+        callback: (value) => {
+            const values = observables.map(o =>
+                Validator.isObservable(o) ? o.val() : o,
+            );
+            return callbackFn(value, ...values);
+        },
+    };
+}
+
+export const gt = greaterThan;
+export const gte = greaterThanOrEqual;
+export const lt = lessThan;
+export const lte = lessThanOrEqual;
+export const eq = equals;
+export const neq = notEquals;
+export const all = and;
+export const any = or;
+

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

@@ -0,0 +1,67 @@
+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;
+        if (!query) return true;
+        if (!caseSensitive){
+            return String(value).toLowerCase().includes(String(query).toLowerCase());
+        }
+        return String(value).includes(String(query));
+    });
+}
+
+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;
+        if (!caseSensitive){
+            return String(value).toLowerCase().startsWith(String(query).toLowerCase());
+        }
+        return String(value).startsWith(String(query));
+    });
+}
+
+/**
+ * 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;
+        if (!caseSensitive){
+            return String(value).toLowerCase().endsWith(String(query).toLowerCase());
+        }
+        return String(value).endsWith(String(query));
+    });
+}

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

@@ -0,0 +1,77 @@
+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);
+    return d1.getFullYear() === d2.getFullYear() &&
+        d1.getMonth() === d2.getMonth() &&
+        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),
+    };
+}
+
+/**
+ * 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,
+    );
+
+    return {
+        dependencies: observables.length > 0 ? observables : null,
+        callback: (value) => callbackFn(value, getValues()),
+    };
+}

package/src/core/utils/formatters.js

@@ -0,0 +1,90 @@
+const $parseDateParts = (value, locale) => {
+    const d = new Date(value);
+    return {
+        d,
+        parts: new Intl.DateTimeFormat(locale, {
+            year:   'numeric',
+            month:  'long',
+            day:    '2-digit',
+            hour:   '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        }).formatToParts(d).reduce((acc, { type, value }) => {
+            acc[type] = value;
+            return acc;
+        }, {}),
+    };
+};
+
+const $applyDatePattern = (pattern, d, parts) => {
+    const pad = n => String(n).padStart(2, '0');
+    return pattern
+        .replace('YYYY', parts.year)
+        .replace('YY',   parts.year.slice(-2))
+        .replace('MMMM', parts.month)
+        .replace('MMM',  parts.month.slice(0, 3))
+        .replace('MM',   pad(d.getMonth() + 1))
+        .replace('DD',   pad(d.getDate()))
+        .replace('D',    d.getDate())
+        .replace('HH',   parts.hour)
+        .replace('mm',   parts.minute)
+        .replace('ss',   parts.second);
+};
+
+export const Formatters = {
+    currency: (value, locale, { currency = 'XOF', notation, minimumFractionDigits, maximumFractionDigits } = {}) =>
+        new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency,
+            notation,
+            minimumFractionDigits,
+            maximumFractionDigits,
+        }).format(value),
+
+    number: (value, locale, { notation, minimumFractionDigits, maximumFractionDigits } = {}) =>
+        new Intl.NumberFormat(locale, {
+            notation,
+            minimumFractionDigits,
+            maximumFractionDigits,
+        }).format(value),
+
+    percent: (value, locale, { decimals = 1 } = {}) =>
+        new Intl.NumberFormat(locale, {
+            style:                'percent',
+            maximumFractionDigits: decimals,
+        }).format(value),
+
+    date: (value, locale, { format, dateStyle = 'long' } = {}) => {
+        if (format) {
+            const { d, parts } = $parseDateParts(value, locale);
+            return $applyDatePattern(format, d, parts);
+        }
+        return new Intl.DateTimeFormat(locale, { dateStyle }).format(new Date(value));
+    },
+
+    time: (value, locale, { format, hour = '2-digit', minute = '2-digit', second } = {}) => {
+        if (format) {
+            const { d, parts } = $parseDateParts(value, locale);
+            return $applyDatePattern(format, d, parts);
+        }
+        return new Intl.DateTimeFormat(locale, { hour, minute, second }).format(new Date(value));
+    },
+
+    datetime: (value, locale, { format, dateStyle = 'long', hour = '2-digit', minute = '2-digit', second } = {}) => {
+        if (format) {
+            const { d, parts } = $parseDateParts(value, locale);
+            return $applyDatePattern(format, d, parts);
+        }
+        return new Intl.DateTimeFormat(locale, { dateStyle, hour, minute, second }).format(new Date(value));
+    },
+
+    relative: (value, locale, { unit = 'day', numeric = 'auto' } = {}) => {
+        const diff = Math.round((value - Date.now()) / (1000 * 60 * 60 * 24));
+        return new Intl.RelativeTimeFormat(locale, { numeric }).format(diff, unit);
+    },
+
+    plural: (value, locale, { singular, plural } = {}) => {
+        const rule = new Intl.PluralRules(locale).select(value);
+        return `${value} ${rule === 'one' ? singular : plural}`;
+    },
+};