native-document 1.0.165 → 1.0.168

package/docs/filters.md

@@ -1,1216 +1,247 @@
-# Filters
-
-NativeDocument provides a comprehensive set of filter helpers for creating reactive, type-safe data filtering with Observable arrays. These filters work seamlessly with the `where()`, `whereSome()`, and `whereEvery()` methods.
+---
+title: Filters
+description: Composable, reactive filter helpers for ObservableArray.where() - comparison, string, date, array, and logical operators
+---
 
-## Overview
+# Filters
 
-Filter helpers enable:
-- **Reactive filtering** - Filters update automatically when observables change
-- **Type-safe comparisons** - Validate data types and formats
-- **Composable logic** - Combine filters with `and`, `or`, `not`
-- **Date/Time handling** - Specialized filters for temporal data
-- **Custom filters** - Create your own filter logic
+Filter helpers enable reactive, composable filtering on `ObservableArray` via `.where()`, `.whereSome()`, and `.whereEvery()`. Filters update automatically when observable values change.
 
-## Import
 ```javascript
-import { filters } from 'native-document/utils';
-const { equals, greaterThan, between, includes, and, or, not } = filters;
-
-// Or destructure directly
-import { filters: { equals, greaterThan, between, includes } } from 'native-document/utils';
-```
+import { utils } from 'native-document';
+const { filters } = utils;
 
-## Basic Filters
-
-### Comparison Filters
-```javascript
+// Or
 import { filters } from 'native-document/utils';
-const { equals, notEquals, greaterThan, lessThan } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { id: 1, name: 'Phone', price: 599, stock: 10 },
-    { id: 2, name: 'Laptop', price: 999, stock: 5 },
-    { id: 3, name: 'Tablet', price: 399, stock: 0 },
-    { id: 4, name: 'Watch', price: 299, stock: 15 }
-]);
 
-// Filter by exact value
-const expensive = products.where({
-    price: equals(999)
-});
-// Result: [{ id: 2, name: 'Laptop', price: 999, stock: 5 }]
-
-// Filter by inequality
-const notTablet = products.where({
-    name: notEquals('Tablet')
-});
-// Result: All except Tablet
-
-// Greater than
-const expensiveProducts = products.where({
-    price: greaterThan(500)
-});
-// Result: Phone and Laptop
-
-// Less than
-const affordable = products.where({
-    price: lessThan(400)
-});
-// Result: Watch and Tablet
+// Or named imports
+import { equals, greaterThan, between, match, and, or, not } from 'native-document/filters';
 ```
 
-### Shortcuts
-```javascript
-import { filters } from 'native-document/utils';
-const { eq, neq, gt, gte, lt, lte } = filters;
+> All filters are for **`ObservableArray` only** - see [Observables](./observables.md) for `.where()` usage.
 
-const products = Observable.array([...]);
+---
 
-// Short aliases
-const expensive = products.where({ price: gt(500) });
-const affordable = products.where({ price: lte(400) });
-const notPhone = products.where({ name: neq('Phone') });
-```
+## Comparison
 
-### greaterThanOrEqual() / lessThanOrEqual()
 ```javascript
-import { filters } from 'native-document/utils';
-const { greaterThanOrEqual, lessThanOrEqual } = filters;
-import { Observable } from 'native-document';
-
 const products = Observable.array([
-    { name: 'Budget', price: 100 },
-    { name: 'Standard', price: 500 },
-    { name: 'Premium', price: 1000 }
+    { name: 'Phone',  price: 599, stock: 10 },
+    { name: 'Laptop', price: 999, stock: 0  },
+    { name: 'Tablet', price: 399, stock: 5  },
 ]);
 
-// Greater than or equal to
-const standardOrBetter = products.where({
-    price: greaterThanOrEqual(500)
-});
-// Result: Standard, Premium
-
-// Less than or equal to
-const budgetFriendly = products.where({
-    price: lessThanOrEqual(500)
-});
-// Result: Budget, Standard
+products.where({ price: equals(599) })              // Phone
+products.where({ name:  notEquals('Phone') })       // Laptop, Tablet
+products.where({ price: greaterThan(500) })         // Phone, Laptop
+products.where({ price: greaterThanOrEqual(399) })  // all
+products.where({ price: lessThan(600) })            // Tablet
+products.where({ price: lessThanOrEqual(399) })     // Tablet
+products.where({ price: between(400, 700) })        // Phone
+products.where({ stock: equals(0) })                // Laptop
 ```
 
-## Range Filters
+All accept observables as arguments - filters update automatically when they change:
 
-### between()
 ```javascript
-import { filters } from 'native-document/utils';
-const { between } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { name: 'Budget Phone', price: 199 },
-    { name: 'Mid Phone', price: 499 },
-    { name: 'Premium Phone', price: 999 },
-    { name: 'Luxury Phone', price: 1499 }
-]);
-
-// Static range
-const midRange = products.where({
-    price: between(400, 800)
-});
-// Result: [{ name: 'Mid Phone', price: 499 }]
-
-// Reactive range with observables
-const minPrice = Observable(200);
-const maxPrice = Observable(1000);
+const minPrice = Observable(300);
+const maxPrice = Observable(800);
 
 const filtered = products.where({
     price: between(minPrice, maxPrice)
 });
 
-// Updates automatically when bounds change
-minPrice.set(500);  // Now shows only Premium Phone
-maxPrice.set(600);  // Now shows nothing
+minPrice.set(500); // filtered updates automatically
 ```
 
-## String Filters
-
-### includes() / contains()
-```javascript
-import { filters } from 'native-document/utils';
-const { includes, contains } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { name: 'iPhone 15 Pro' },
-    { name: 'Samsung Galaxy' },
-    { name: 'Google Pixel' },
-    { name: 'OnePlus Phone' }
-]);
+---
 
-// Case-insensitive by default
-const phones = products.where({
-    name: includes('phone')
-});
-// Result: iPhone 15 Pro, OnePlus Phone
-
-// Reactive search
-const searchTerm = Observable('galaxy');
-const results = products.where({
-    name: includes(searchTerm)
-});
-// Result: Samsung Galaxy
-
-searchTerm.set('pixel');
-// Result: Google Pixel
-
-// contains is an alias
-const sameResults = products.where({
-    name: contains('phone')
-});
-```
+## String
 
-### startsWith()
 ```javascript
-import { filters } from 'native-document/utils';
-const { startsWith } = filters;
-import { Observable } from 'native-document';
-
 const users = Observable.array([
     { name: 'Alice Johnson' },
     { name: 'Bob Smith' },
-    { name: 'Alice Brown' },
     { name: 'Charlie Wilson' }
 ]);
 
-// Case-insensitive by default
-const alices = users.where({
-    name: startsWith('alice')
-});
-// Result: Alice Johnson, Alice Brown
-
-// Case-sensitive (second parameter)
-const caseSensitive = users.where({
-    name: startsWith('Alice', true)
-});
-// Result: Alice Johnson, Alice Brown
+users.where({ name: includes('alice') })      // Alice Johnson (case-insensitive)
+users.where({ name: includes('smith', true) }) // Bob Smith (case-sensitive)
+users.where({ name: startsWith('A') })         // Alice Johnson
+users.where({ name: endsWith('son') })         // Alice Johnson, Charlie Wilson
+users.where({ name: match(/^[A-C]/) })         // Alice, Bob, Charlie (regex)
+users.where({ name: match('bob', false) })     // Bob Smith (plain text)
 ```
 
-### endsWith()
-```javascript
-import { filters } from 'native-document/utils';
-const { endsWith } = filters;
-import { Observable } from 'native-document';
-
-const files = Observable.array([
-    { name: 'document.pdf' },
-    { name: 'image.jpg' },
-    { name: 'report.pdf' },
-    { name: 'photo.png' }
-]);
+Reactive search:
 
-// Case-insensitive by default
-const pdfs = files.where({
-    name: endsWith('.pdf')
-});
-// Result: document.pdf, report.pdf
-
-// Case-sensitive
-const pdfsCaseSensitive = files.where({
-    name: endsWith('.PDF', true)
-});
-// Result: [] (none match uppercase)
-```
-
-### match()
 ```javascript
-import { filters } from 'native-document/utils';
-const { match } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { sku: 'ABC-123' },
-    { sku: 'DEF-456' },
-    { sku: 'GHI-789' },
-    { sku: 'INVALID' }
-]);
+const search = Observable('');
+const results = users.where({ name: includes(search) });
 
-// Regex pattern
-const validSKUs = products.where({
-    sku: match(/^[A-Z]{3}-\d{3}$/, true)
-});
-// Result: ABC-123, DEF-456, GHI-789
-
-// Simple text match (no regex)
-const containsABC = products.where({
-    sku: match('ABC', false)
-});
-// Result: ABC-123
-
-// With flags
-const caseInsensitive = products.where({
-    sku: match(/abc/, true, 'i')
-});
-// Result: ABC-123
+search.set('ali'); // Alice Johnson
+search.set('');    // all users
 ```
 
-## Array Filters
+---
 
-### inArray()
-```javascript
-import { filters } from 'native-document/utils';
-const { inArray } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { id: 1, category: 'electronics' },
-    { id: 2, category: 'books' },
-    { id: 3, category: 'clothing' },
-    { id: 4, category: 'electronics' }
-]);
-
-// Static array
-const allowed = products.where({
-    category: inArray(['electronics', 'books'])
-});
-// Result: items 1, 2, 4
-
-// Reactive array
-const allowedCategories = Observable.array(['electronics']);
-const filtered = products.where({
-    category: inArray(allowedCategories)
-});
-
-// Updates when array changes
-allowedCategories.push('books');
-// Now includes books too
-```
+## Array membership
 
-### notIn()
 ```javascript
-import { filters } from 'native-document/utils';
-const { notIn } = filters;
-import { Observable } from 'native-document';
-
-const users = Observable.array([
-    { id: 1, status: 'active' },
-    { id: 2, status: 'banned' },
-    { id: 3, status: 'inactive' },
-    { id: 4, status: 'active' }
-]);
+const allowed = Observable.array(['electronics', 'books']);
 
-const validUsers = users.where({
-    status: notIn(['banned', 'deleted'])
-});
-// Result: items 1, 3, 4
+products.where({ category: inArray(allowed) })       // reactive
+products.where({ category: inArray(['books']) })     // static
+products.where({ status:   notIn(['banned', 'deleted']) })
 ```
 
-## Empty/Existence Filters
+---
 
-### isEmpty()
-```javascript
-import { filters } from 'native-document/utils';
-const { isEmpty } = filters;
-import { Observable } from 'native-document';
-
-const tasks = Observable.array([
-    { title: 'Task 1', description: '' },
-    { title: 'Task 2', description: 'Details' },
-    { title: 'Task 3', description: null },
-    { title: 'Task 4', tags: [] }
-]);
+## Logical operators
 
-// Empty string or null
-const noDescription = tasks.where({
-    description: isEmpty()
-});
-// Result: Task 1, Task 3
+`and`, `or`, `not` operate **within a single field**. For cross-field logic use the `_` key:
 
-// Empty arrays
-const noTags = tasks.where({
-    tags: isEmpty()
-});
-// Result: Task 4
-
-// Conditional empty
-const shouldBeEmpty = Observable(true);
-const filtered = tasks.where({
-    description: isEmpty(shouldBeEmpty)
-});
-
-shouldBeEmpty.set(false);
-// Now returns items with non-empty descriptions
-```
-
-### isNotEmpty()
 ```javascript
-import { filters } from 'native-document/utils';
-const { isNotEmpty } = filters;
-import { Observable } from 'native-document';
+// and - field must pass ALL conditions
+products.where({ price: and(greaterThan(100), lessThan(800)) })
 
-const tasks = Observable.array([
-    { title: 'Task 1', description: '' },
-    { title: 'Task 2', description: 'Details' },
-    { title: 'Task 3', description: null }
-]);
+// or - field must pass AT LEAST ONE
+products.where({ category: or(equals('electronics'), equals('books')) })
 
-const withDescription = tasks.where({
-    description: isNotEmpty()
-});
-// Result: Task 2
+// not - inverts
+products.where({ status: not(equals('banned')) })
 
-// Conditional
-const shouldHaveContent = Observable(true);
-const filtered = tasks.where({
-    description: isNotEmpty(shouldHaveContent)
-});
+// cross-field - plain function with _ key
+products.where({
+    _: item => item.stock > 0 && item.price < 500
+})
 ```
 
-## Date and Time Filters
+`all` is an alias for `and`, `any` is an alias for `or`.
 
-All date and time filters automatically convert values to Date objects using the internal `toDate()` helper. You can pass Date objects, timestamps, or date strings - they will be converted automatically.
-
-### Date Comparison
-```javascript
-import { filters } from 'native-document/utils';
-const { dateEquals, dateBefore, dateAfter, dateBetween } = filters;
-import { Observable } from 'native-document';
-
-const events = Observable.array([
-    { name: 'Meeting', date: '2024-01-15' },
-    { name: 'Conference', date: '2024-06-20' },
-    { name: 'Workshop', date: '2024-09-10' },
-    { name: 'Seminar', date: '2024-12-05' }
-]);
-
-// Specific date (string automatically converted to Date)
-const januaryEvents = events.where({
-    date: dateEquals('2024-01-15')
-});
-// Result: Meeting
-
-// Or with Date object
-const januaryEvents2 = events.where({
-    date: dateEquals(new Date('2024-01-15'))
-});
-// Result: Meeting
-
-// Before a date
-const firstHalf = events.where({
-    date: dateBefore('2024-07-01')
-});
-// Result: Meeting, Conference
-
-// After a date
-const secondHalf = events.where({
-    date: dateAfter('2024-07-01')
-});
-// Result: Workshop, Seminar
-
-// Date range
-const summerEvents = events.where({
-    date: dateBetween('2024-06-01', '2024-08-31')
-});
-// Result: Conference
+---
 
-// Reactive date filtering with observables
-const startDate = Observable('2024-01-01');
-const endDate = Observable('2024-06-30');
+## Custom filter
 
-const filtered = events.where({
-    date: dateBetween(startDate, endDate)
-});
-
-// Updates when dates change
-endDate.set('2024-12-31');
-// Now includes all events
-
-// Works with timestamps too
-const timestamp = Date.now();
-const recentEvents = events.where({
-    date: dateAfter(timestamp)
-});
-```
-
-### Time Comparison (Ignores Date)
-
-Time filters extract and compare only the time portion (hours, minutes, seconds), ignoring the date.
 ```javascript
-import { filters } from 'native-document/utils';
-const { timeEquals, timeBefore, timeAfter, timeBetween } = filters;
-import { Observable } from 'native-document';
-
-const appointments = Observable.array([
-    { name: 'Breakfast', time: '2024-01-15 08:00:00' },
-    { name: 'Meeting', time: '2024-01-15 14:00:00' },
-    { name: 'Dinner', time: '2024-01-15 19:00:00' }
-]);
-
-// Specific time (date is ignored, only time matters)
-const lunchTime = appointments.where({
-    time: timeEquals('2024-01-01 14:00:00')
-});
-// Result: Meeting (date doesn't need to match)
-
-// Before a time
-const morning = appointments.where({
-    time: timeBefore('12:00:00')
-});
-// Result: Breakfast
+const minRating = Observable(4);
 
-// After a time
-const evening = appointments.where({
-    time: timeAfter('18:00:00')
-});
-// Result: Dinner
-
-// Time range (9 AM to 5 PM)
-const businessHours = appointments.where({
-    time: timeBetween('09:00:00', '17:00:00')
-});
-// Result: Meeting
-
-// Works with any date - only time is compared
-const businessHours2 = appointments.where({
-    time: timeBetween('2025-12-25 09:00:00', '2025-12-25 17:00:00')
-});
-// Result: Meeting (same result, date is ignored)
+products.where({
+    _: custom((item, min) => {
+        return item.rating >= min && item.reviews > 10;
+    }, minRating) // observables as extra dependencies
+})
 ```
 
-### DateTime Comparison (Date + Time)
+---
 
-DateTime filters compare both date and time together for exact timestamp matching.
-```javascript
-import { filters } from 'native-document/utils';
-const { dateTimeEquals, dateTimeBefore, dateTimeAfter, dateTimeBetween } = filters;
-import { Observable } from 'native-document';
+## Date and time filters
 
-const logs = Observable.array([
-    { message: 'Start', timestamp: '2024-01-15 08:30:00' },
-    { message: 'Process', timestamp: '2024-01-15 14:45:00' },
-    { message: 'End', timestamp: '2024-01-15 18:20:00' }
-]);
+All date/time values are automatically converted to `Date` objects.
 
-// Exact timestamp (both date and time must match)
-const exactLog = logs.where({
-    timestamp: dateTimeEquals('2024-01-15 14:45:00')
-});
-// Result: Process
-
-// Before timestamp
-const earlyLogs = logs.where({
-    timestamp: dateTimeBefore('2024-01-15 15:00:00')
-});
-// Result: Start, Process
-
-// After timestamp
-const lateLogs = logs.where({
-    timestamp: dateTimeAfter('2024-01-15 15:00:00')
-});
-// Result: End
-
-// Timestamp range (work hours: 9 AM to 5 PM)
-const workHours = logs.where({
-    timestamp: dateTimeBetween(
-        '2024-01-15 09:00:00',
-        '2024-01-15 17:00:00'
-    )
-});
-// Result: Process
-
-// Reactive datetime filtering
-const startTime = Observable('2024-01-15 08:00:00');
-const endTime = Observable('2024-01-15 16:00:00');
-
-const filtered = logs.where({
-    timestamp: dateTimeBetween(startTime, endTime)
-});
-
-// Updates when times change
-endTime.set('2024-01-15 20:00:00');
-// Now includes all logs
-```
-
-### Date Format Examples
-
-All date/time filters accept multiple formats:
-```javascript
-import { filters } from 'native-document/utils';
-const { dateEquals, timeEquals, dateTimeEquals } = filters;
-
-const events = Observable.array([...]);
-
-// ISO 8601 string
-events.where({ date: dateEquals('2024-01-15') });
-
-// Date object
-events.where({ date: dateEquals(new Date('2024-01-15')) });
-
-// Timestamp (milliseconds)
-events.where({ date: dateEquals(1705276800000) });
-
-// Full datetime string
-events.where({ timestamp: dateTimeEquals('2024-01-15T14:30:00') });
-
-// Time only (date portion ignored)
-events.where({ time: timeEquals('14:30:00') });
-
-// Observable with any format
-const targetDate = Observable('2024-01-15');
-events.where({ date: dateEquals(targetDate) });
-```
+### Date (ignores time)
 
-### Working with Different Timezones
 ```javascript
-import { filters } from 'native-document/utils';
-const { dateTimeBetween } = filters;
-import { Observable } from 'native-document';
+import { dateEquals, dateBefore, dateAfter, dateBetween } from 'native-document/filters';
 
-const events = Observable.array([
-    { name: 'Meeting', time: '2024-01-15T14:00:00Z' },      // UTC
-    { name: 'Call', time: '2024-01-15T09:00:00-05:00' },    // EST
-    { name: 'Workshop', time: '2024-01-15T16:00:00+01:00' } // CET
-]);
+const today = Observable(new Date());
 
-// All dates are converted to Date objects internally
-// Local timezone is used for comparison
-const todayEvents = events.where({
-    time: dateTimeBetween(
-        '2024-01-15T00:00:00',
-        '2024-01-15T23:59:59'
-    )
-});
+events.where({ date: dateEquals('2024-03-15') })
+events.where({ date: dateAfter(new Date()) })
+events.where({ date: dateBefore(today) })
+events.where({ date: dateBetween('2024-06-01', '2024-08-31') })
 ```
 
-### Practical Date/Time Examples
+### Time (ignores date)
 
-#### Filter Events by Today/This Week
 ```javascript
-import { filters } from 'native-document/utils';
-const { dateEquals, dateBetween } = filters;
-import { Observable } from 'native-document';
-
-const events = Observable.array([...]);
+import { timeBefore, timeAfter, timeBetween } from 'native-document/filters';
 
-// Today's events
-const today = new Date().toISOString().split('T')[0]; // "2024-01-15"
-const todayEvents = events.where({
-    date: dateEquals(today)
-});
-
-// This week's events
-const startOfWeek = new Date();
-startOfWeek.setDate(startOfWeek.getDate() - startOfWeek.getDay());
-
-const endOfWeek = new Date(startOfWeek);
-endOfWeek.setDate(endOfWeek.getDate() + 6);
-
-const thisWeekEvents = events.where({
-    date: dateBetween(
-        startOfWeek.toISOString().split('T')[0],
-        endOfWeek.toISOString().split('T')[0]
-    )
-});
+// Only the time portion is compared - date is ignored
+calls.where({ time: timeBetween('09:00:00', '17:00:00') }) // business hours
+calls.where({ time: timeAfter('18:00:00') })                // evening
 ```
 
-#### Filter by Business Hours
-```javascript
-import { filters } from 'native-document/utils';
-const { timeBetween } = filters;
-import { Observable } from 'native-document';
-
-const calls = Observable.array([
-    { caller: 'Alice', time: '2024-01-15 08:30:00' },
-    { caller: 'Bob', time: '2024-01-15 14:30:00' },
-    { caller: 'Charlie', time: '2024-01-15 20:00:00' }
-]);
+### DateTime (date + time)
 
-// Business hours: 9 AM - 6 PM
-const businessHoursCalls = calls.where({
-    time: timeBetween('09:00:00', '18:00:00')
-});
-// Result: Bob (14:30 is within business hours)
-```
-
-#### Filter Recent Activity
 ```javascript
-import { filters } from 'native-document/utils';
-const { dateTimeAfter } = filters;
-import { Observable } from 'native-document';
-
-const activities = Observable.array([...]);
-
-// Last 24 hours
-const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
-const recentActivity = activities.where({
-    timestamp: dateTimeAfter(oneDayAgo)
-});
+import { dateTimeAfter, dateTimeBetween } from 'native-document/filters';
 
-// Last hour
-const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
-const veryRecentActivity = activities.where({
-    timestamp: dateTimeAfter(oneHourAgo)
-});
-```
-
-### Time Comparison (Ignores Date)
-```javascript
-import { filters } from 'native-document/utils';
-const { timeEquals, timeBefore, timeAfter, timeBetween } = filters;
-import { Observable } from 'native-document';
-
-const appointments = Observable.array([
-    { name: 'Breakfast', time: new Date('2024-01-15 08:00:00') },
-    { name: 'Meeting', time: new Date('2024-01-15 14:00:00') },
-    { name: 'Dinner', time: new Date('2024-01-15 19:00:00') }
-]);
-
-// Specific time (ignores date)
-const lunchTime = appointments.where({
-    time: timeEquals(new Date('2024-01-01 14:00:00'))
-});
-// Result: Meeting (even though date is different)
-
-// Before a time
-const morning = appointments.where({
-    time: timeBefore(new Date('2024-01-01 12:00:00'))
-});
-// Result: Breakfast
-
-// After a time
-const evening = appointments.where({
-    time: timeAfter(new Date('2024-01-01 18:00:00'))
-});
-// Result: Dinner
-
-// Time range
-const businessHours = appointments.where({
-    time: timeBetween(
-        new Date('2024-01-01 09:00:00'),
-        new Date('2024-01-01 17:00:00')
-    )
-});
-// Result: Meeting
-```
-
-### DateTime Comparison (Date + Time)
-```javascript
-import { filters } from 'native-document/utils';
-const { dateTimeEquals, dateTimeBefore, dateTimeAfter, dateTimeBetween } = filters;
-import { Observable } from 'native-document';
-
-const logs = Observable.array([
-    { message: 'Start', timestamp: new Date('2024-01-15 08:30:00') },
-    { message: 'Process', timestamp: new Date('2024-01-15 14:45:00') },
-    { message: 'End', timestamp: new Date('2024-01-15 18:20:00') }
-]);
-
-// Exact timestamp
-const exactLog = logs.where({
-    timestamp: dateTimeEquals(new Date('2024-01-15 14:45:00'))
-});
-// Result: Process
-
-// Before timestamp
-const earlyLogs = logs.where({
-    timestamp: dateTimeBefore(new Date('2024-01-15 15:00:00'))
-});
-// Result: Start, Process
-
-// After timestamp
-const lateLogs = logs.where({
-    timestamp: dateTimeAfter(new Date('2024-01-15 15:00:00'))
-});
-// Result: End
-
-// Timestamp range
-const workHours = logs.where({
-    timestamp: dateTimeBetween(
-        new Date('2024-01-15 09:00:00'),
-        new Date('2024-01-15 17:00:00')
-    )
-});
-// Result: Process
-```
-
-## Logical Operators
-
-### and() / all()
-```javascript
-import { filters } from 'native-document/utils';
-const { and, all, greaterThan, lessThan } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { name: 'Phone', price: 599, stock: 10 },
-    { name: 'Laptop', price: 999, stock: 5 },
-    { name: 'Tablet', price: 399, stock: 0 },
-    { name: 'Watch', price: 299, stock: 15 }
-]);
-
-// Combine multiple conditions
-const midRangeInStock = products.where({
-    price: and(
-        greaterThan(300),
-        lessThan(700)
-    ),
-    stock: greaterThan(0)
-});
-// Result: Phone
-
-// 'all' is an alias for 'and'
-const sameResult = products.where({
-    price: all(
-        greaterThan(300),
-        lessThan(700)
-    )
-});
-```
-
-### or() / any()
-```javascript
-import { filters } from 'native-document/utils';
-const { or, any, lessThan, greaterThan } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { name: 'Budget Phone', price: 199 },
-    { name: 'Mid Phone', price: 499 },
-    { name: 'Premium Phone', price: 999 }
-]);
-
-// Either cheap OR expensive
-const dealsOrPremium = products.where({
-    price: or(
-        lessThan(300),
-        greaterThan(800)
-    )
-});
-// Result: Budget Phone, Premium Phone
-
-// 'any' is an alias for 'or'
-const sameResult = products.where({
-    price: any(
-        lessThan(300),
-        greaterThan(800)
-    )
-});
-```
-
-### not()
-```javascript
-import { filters } from 'native-document/utils';
-const { not, equals } = filters;
-import { Observable } from 'native-document';
-
-const users = Observable.array([
-    { name: 'Alice', status: 'active' },
-    { name: 'Bob', status: 'inactive' },
-    { name: 'Charlie', status: 'active' }
-]);
-
-// Invert condition
-const notActive = users.where({
-    status: not(equals('active'))
-});
-// Result: Bob
-
-// Can combine with other filters
-const notActiveOrBanned = users.where({
-    status: not(inArray(['active', 'banned']))
-});
-```
-
-## Complex Filtering
-
-### Nested Conditions
-```javascript
-import { filters } from 'native-document/utils';
-const { and, or, greaterThan, lessThan, equals } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { name: 'Phone', price: 599, category: 'electronics', stock: 10 },
-    { name: 'Book', price: 29, category: 'books', stock: 50 },
-    { name: 'Laptop', price: 999, category: 'electronics', stock: 5 },
-    { name: 'Magazine', price: 9, category: 'books', stock: 100 }
-]);
-
-// (electronics AND expensive) OR (books AND cheap)
-const filtered = products.where({
-    _: or(
-        and(
-            (item) => item.category === 'electronics',
-            (item) => item.price > 500
-        ),
-        and(
-            (item) => item.category === 'books',
-            (item) => item.price < 20
-        )
-    )
-});
-// Result: Phone, Laptop, Magazine
-```
-
-### Multiple Property Filters
-```javascript
-import { filters } from 'native-document/utils';
-const { greaterThan, includes, equals } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { name: 'Gaming Phone', price: 799, category: 'electronics', tags: ['gaming', 'mobile'] },
-    { name: 'Office Laptop', price: 1299, category: 'electronics', tags: ['work', 'productivity'] },
-    { name: 'Budget Tablet', price: 299, category: 'electronics', tags: ['entertainment'] }
-]);
-
-// Filter on multiple properties
-const filtered = products.where({
-    price: greaterThan(500),
-    category: equals('electronics'),
-    name: includes('gaming')
-});
-// Result: Gaming Phone
-```
-
-### Reactive Multi-Condition Filters
-```javascript
-import { filters } from 'native-document/utils';
-const { and, greaterThan, lessThan, includes, custom } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([...]);
-
-// Reactive filter values
-const searchTerm = Observable('');
-const minPrice = Observable(0);
-const maxPrice = Observable(10000);
-const showInStockOnly = Observable(false);
-
-const filtered = products.where({
-    name: includes(searchTerm),
-    price: and(
-        greaterThan(minPrice),
-        lessThan(maxPrice)
-    ),
-    stock: custom((value, showInStock) => {
-        return !showInStock || value > 0;
-    }, showInStockOnly)
-});
-
-// Updates automatically when any filter changes
-searchTerm.set('phone');
-minPrice.set(500);
-maxPrice.set(1000);
-showInStockOnly.set(true);
+logs.where({ timestamp: dateTimeAfter(new Date(Date.now() - 86400000)) }) // last 24h
+logs.where({ timestamp: dateTimeBetween(start, end) })
 ```
 
-## Custom Filters
-
-### createFilter()
-```javascript
-import { filters } from 'native-document/utils';
-const { createFilter } = filters;
-import { Observable } from 'native-document';
-
-// Create email validator
-const isValidEmail = createFilter(
-    true, // static value or observable
-    (value, shouldBeValid) => {
-        const isValid = /\S+@\S+\.\S+/.test(value);
-        return shouldBeValid ? isValid : !isValid;
-    }
-);
-
-const users = Observable.array([
-    { email: 'alice@example.com' },
-    { email: 'invalid-email' },
-    { email: 'bob@example.com' }
-]);
-
-const validUsers = users.where({
-    email: isValidEmail
-});
-// Result: alice@example.com, bob@example.com
-
-// Reactive validation
-const shouldValidate = Observable(true);
-const emailFilter = createFilter(
-    shouldValidate,
-    (value, validate) => {
-        if (!validate) return true; // Skip validation
-        return /\S+@\S+\.\S+/.test(value);
-    }
-);
-
-const filtered = users.where({
-    email: emailFilter
-});
-
-shouldValidate.set(false);
-// Now returns all users (validation disabled)
-```
-
-### createMultiSourceFilter()
-```javascript
-import { filters } from 'native-document/utils';
-const { createMultiSourceFilter } = filters;
-import { Observable } from 'native-document';
-
-const minValue = Observable(0);
-const maxValue = Observable(100);
-const multiplier = Observable(1);
-
-// Filter using multiple observables
-const complexFilter = createMultiSourceFilter(
-    [minValue, maxValue, multiplier],
-    (value, [min, max, mult]) => {
-        const adjusted = value * mult;
-        return adjusted >= min && adjusted <= max;
-    }
-);
-
-const numbers = Observable.array([
-    { value: 10 },
-    { value: 50 },
-    { value: 150 }
-]);
-
-const filtered = numbers.where({
-    value: complexFilter
-});
-
-// All observables update the filter
-multiplier.set(2);  // Now filters based on value * 2
-minValue.set(50);   // Now requires value * 2 >= 50
-```
-
-### custom()
-```javascript
-import { filters } from 'native-document/utils';
-const { custom } = filters;
-import { Observable } from 'native-document';
-
-const products = Observable.array([
-    { name: 'Phone', price: 599, discount: 0.1 },
-    { name: 'Laptop', price: 999, discount: 0.15 },
-    { name: 'Tablet', price: 399, discount: 0.05 }
-]);
-
-const maxBudget = Observable(600);
-
-// Custom filter with observable dependency
-const withinBudget = products.where({
-    _: custom((product, budget) => {
-        const finalPrice = product.price * (1 - product.discount);
-        return finalPrice <= budget;
-    }, maxBudget)
-});
-// Result: Phone, Tablet
-
-// Updates when budget changes
-maxBudget.set(400);
-// Result: Tablet only
-```
+---
 
 ## Filter Reference
 
-### Comparison Filters
-
-| Filter | Alias | Description | Example |
-|--------|-------|-------------|---------|
-| `equals(value)` | `eq(value)` | Exact match | `equals(10)` |
-| `notEquals(value)` | `neq(value)` | Not equal | `notEquals('test')` |
-| `greaterThan(value)` | `gt(value)` | Greater than | `gt(100)` |
-| `greaterThanOrEqual(value)` | `gte(value)` | Greater or equal | `gte(50)` |
-| `lessThan(value)` | `lt(value)` | Less than | `lt(1000)` |
-| `lessThanOrEqual(value)` | `lte(value)` | Less or equal | `lte(500)` |
-
-### Range Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `between(min, max)` | Value within range (inclusive) | `between(10, 100)` |
-
-### String Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `includes(text, caseSensitive?)` | Contains substring | `includes('hello')` |
-| `contains(text, caseSensitive?)` | Alias for includes | `contains('world')` |
-| `startsWith(text, caseSensitive?)` | Starts with prefix | `startsWith('Mr')` |
-| `endsWith(text, caseSensitive?)` | Ends with suffix | `endsWith('.pdf')` |
-| `match(pattern, asRegex?, flags?)` | Pattern matching | `match(/\d+/, true)` |
-
-### Array Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `inArray(array)` | Value in array | `inArray(['a', 'b'])` |
-| `notIn(array)` | Value not in array | `notIn(['banned'])` |
-
-### Empty Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `isEmpty(shouldBeEmpty?)` | Value is empty/null | `isEmpty()` |
-| `isNotEmpty(shouldBeNotEmpty?)` | Value is not empty | `isNotEmpty()` |
-
-### Date Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `dateEquals(date)` | Same date (ignores time) | `dateEquals(new Date())` |
-| `dateBefore(date)` | Before date | `dateBefore(new Date())` |
-| `dateAfter(date)` | After date | `dateAfter(new Date())` |
-| `dateBetween(start, end)` | Date range | `dateBetween(start, end)` |
-
-### Time Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `timeEquals(time)` | Same time (ignores date) | `timeEquals(new Date())` |
-| `timeBefore(time)` | Before time | `timeBefore(new Date())` |
-| `timeAfter(time)` | After time | `timeAfter(new Date())` |
-| `timeBetween(start, end)` | Time range | `timeBetween(start, end)` |
-
-### DateTime Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `dateTimeEquals(datetime)` | Exact timestamp | `dateTimeEquals(new Date())` |
-| `dateTimeBefore(datetime)` | Before timestamp | `dateTimeBefore(new Date())` |
-| `dateTimeAfter(datetime)` | After timestamp | `dateTimeAfter(new Date())` |
-| `dateTimeBetween(start, end)` | Timestamp range | `dateTimeBetween(start, end)` |
-
-### Logical Operators
-
-| Filter | Alias | Description | Example |
-|--------|-------|-------------|---------|
-| `and(...filters)` | `all(...filters)` | All conditions must match | `and(gt(10), lt(100))` |
-| `or(...filters)` | `any(...filters)` | Any condition must match | `or(eq('a'), eq('b'))` |
-| `not(filter)` | - | Invert condition | `not(equals('test'))` |
-
-### Custom Filters
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `createFilter(value, callback)` | Single source custom filter | See above |
-| `createMultiSourceFilter(sources, callback)` | Multi-source custom filter | See above |
-| `custom(callback, ...observables)` | Custom logic with dependencies | See above |
+### Comparison
+| Filter | Alias | Description |
+|---|---|---|
+| `equals(value)` | `eq` | Exact match |
+| `notEquals(value)` | `neq` | Not equal |
+| `greaterThan(value)` | `gt` | > value |
+| `greaterThanOrEqual(value)` | `gte` | >= value |
+| `lessThan(value)` | `lt` | < value |
+| `lessThanOrEqual(value)` | `lte` | <= value |
+| `between(min, max)` | - | min <= value <= max |
+
+### String
+| Filter | Description |
+|---|---|
+| `includes(text, caseSensitive?)` | Contains substring |
+| `startsWith(text, caseSensitive?)` | Starts with |
+| `endsWith(text, caseSensitive?)` | Ends with |
+| `match(pattern, asRegex?, flags?)` | Regex or plain text match |
+
+### Array
+| Filter | Description |
+|---|---|
+| `inArray(array)` | Value is in array (observable-aware) |
+| `notIn(array)` | Value is not in array |
+
+### Logical
+| Filter | Alias | Description |
+|---|---|---|
+| `and(...filters)` | `all` | All conditions pass |
+| `or(...filters)` | `any` | At least one passes |
+| `not(filter)` | - | Inverts the filter |
+
+### Custom
+| Filter | Description |
+|---|---|
+| `custom(fn, ...observables)` | Custom logic with reactive dependencies |
+
+### Date
+| Filter | Description |
+|---|---|
+| `dateEquals(date)` | Same date (ignores time) |
+| `dateBefore(date)` | Before date |
+| `dateAfter(date)` | After date |
+| `dateBetween(start, end)` | Date range |
+| `timeEquals(time)` | Same time (ignores date) |
+| `timeBefore(time)` | Before time |
+| `timeAfter(time)` | After time |
+| `timeBetween(start, end)` | Time range |
+| `dateTimeEquals(dt)` | Exact timestamp |
+| `dateTimeBefore(dt)` | Before timestamp |
+| `dateTimeAfter(dt)` | After timestamp |
+| `dateTimeBetween(start, end)` | Timestamp range |
+
+---
 
 ## Best Practices
 
-### 1. Use Specific Filters
-```javascript
-import { filters } from 'native-document/utils';
-const { equals, greaterThan } = filters;
-
-// ✅ Good: Specific property filters
-const filtered = products.where({
-    price: greaterThan(100),
-    category: equals('electronics')
-});
-
-// ❌ Less efficient: Generic filter
-const filtered = products.where({
-    _: (product) => product.price > 100 && product.category === 'electronics'
-});
-```
-
-### 2. Reuse Observable Filters
-```javascript
-import { filters } from 'native-document/utils';
-const { between } = filters;
-import { Observable } from 'native-document';
-
-// ✅ Good: Reuse observables
-const minPrice = Observable(0);
-const maxPrice = Observable(1000);
-
-const products1Filtered = products1.where({ price: between(minPrice, maxPrice) });
-const products2Filtered = products2.where({ price: between(minPrice, maxPrice) });
-
-// Both update when observables change
-minPrice.set(500);
-```
-
-### 3. Combine Related Filters
-```javascript
-import { filters } from 'native-document/utils';
-const { and, greaterThan, lessThan } = filters;
-
-// ✅ Good: Use 'and' for multiple conditions
-const filtered = products.where({
-    price: and(greaterThan(100), lessThan(500))
-});
-
-// ❌ Bad: Multiple where() calls
-const filtered = products
-    .where({ price: greaterThan(100) })
-    .where({ price: lessThan(500) });
-```
-
-### 4. Document Complex Filters
-```javascript
-import { filters } from 'native-document/utils';
-const { and, or, greaterThan, equals } = filters;
-
-/**
- * Filters products for flash sale eligibility:
- * - In stock OR coming soon
- * - Price between $50-$500
- * - High rating (4+ stars)
- */
-const flashSaleProducts = products.where({
-    stock: or(greaterThan(0), equals('coming-soon')),
-    price: and(greaterThan(50), lessThan(500)),
-    rating: greaterThan(4)
-});
-```
-
-### 5. Avoid Over-Filtering
-```javascript
-import { filters } from 'native-document/utils';
-const { equals, greaterThan } = filters;
-
-// ❌ Bad: Too many where() calls
-const filtered = products
-    .where({ category: equals('electronics') })
-    .where({ price: greaterThan(100) })
-    .where({ stock: greaterThan(0) })
-    .where({ rating: greaterThan(4) });
-
-// ✅ Good: Combine into single where
-const filtered = products.where({
-    category: equals('electronics'),
-    price: greaterThan(100),
-    stock: greaterThan(0),
-    rating: greaterThan(4)
-});
-```
-
-## Next Steps
+1. Prefer property-specific filters over `_` + plain function when possible - they are more efficient
+2. Combine multiple field conditions in a single `.where()` call - not chained `.where()` calls
+3. Reuse observable filter values across multiple arrays - they all update together
+4. Use `custom()` for complex logic that involves external observables
 
-Explore related utilities and concepts:
+---
 
 ## Next Steps
 
-- **[Getting Started](getting-started.md)** - Installation and first steps
-- **[Core Concepts](core-concepts.md)** - Understanding the fundamentals
-- **[Observables](observables.md)** - Reactive state management
-- **[Elements](elements.md)** - Creating and composing UI
-- **[Conditional Rendering](conditional-rendering.md)** - Dynamic content
-- **[List Rendering](list-rendering.md)** - (ForEach | ForEachArray) and dynamic lists
-- **[Routing](routing.md)** - Navigation and URL management
-- **[State Management](state-management.md)** - Global state patterns
-- **[NDElement](native-document-element.md)** - Native Document Element
-- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
-- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
-- **[Args Validation](validation.md)** - Function Argument Validation
-- **[Memory Management](memory-management.md)** - Memory management
-
-## Utilities
-
-- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
-- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
-- **[Filters](docs/utils/filters.md)** - Data filtering helpers
+- **[Observables](./observables.md)** - Full `.where()`, `.whereSome()`, `.whereEvery()` reference
+- **[List Rendering](./list-rendering.md)** - ForEach with filtered arrays
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors