Filter expressions and legacy conditions

5.x only

This page applies to the 5.x line only (npm 5.1.x, branch 5.x). From 6.0, @ahoo-wang/fetcher-wow lives in the Wow repository (typescript/) and is documented at wow.ahoo.me; its successor @ahoo-wang/wow-client is on npm from Wow 9.2.0 (9.2.1 or later accepts fetcher 6).

Use filter.* to construct the discriminated FilterExpression wire format (op). Legacy root functions such as eq and and construct deprecated Condition objects (operator, value, children, options). They remain public for existing servers and Viewer integration. Do not rename keys or mix the two trees.

New builder family	Input / wire meaning
matchAll(), matchNone()	Explicit all / none; no arguments.
id/aggregateId/tenantId/ownerId/spaceId(value)	String metadata values; ids/aggregateIds accept nonempty readonly string arrays.
and/or/nor(operands)	Nonempty array, copied to operands; no legacy variadic syntax or empty-all normalization.
eq/ne(field, value)	JSON scalar including null; numbers must be finite.
gt/gte/lt/lte(field, value)	Non-null comparable scalar.
contains/startsWith/endsWith(field, text, comparison?)	Default CASE_SENSITIVE; use StringComparison.CASE_INSENSITIVE explicitly.
isIn/notIn/containsAll(field, values)	Nonempty array of non-null comparable scalars; copied.
between(field, lowerBound, upperBound)	Validates scalar bounds, not their order or common semantic type.
isEmpty/isEmptyString/isNotEmptyString/isNull/isNotNull/exists/notExists(field)	Distinct presence/empty operations; no value argument.
deletion(state)	DeletionState.ACTIVE/DELETED/ALL, validated.
elementMatch(field, predicate)	Element-relative expression, recursively excludes root metadata/deletion/search.
search(query, options?)	Nonblank string, fields defaults [], mode defaults SearchMode.TERMS; PHRASE is explicit.
today/tomorrow/yesterday/thisWeek/nextWeek/lastWeek/thisMonth/nextMonth/lastMonth/thisYear/nextYear/lastYear(field, options?)	Relative calendar filters, resolved by the server.
beforeToday(field, time, options?)	Local time HH:mm with optional seconds and up to nine fractional digits.
recentDays/earlierDays(field, days, options?)	Positive JVM Int, maximum 2147483647.

QueryField/LogicalField are string type aliases. Builders additionally reject invalid logical paths: segments start with a letter/underscore (optionally @), continue with letters/digits/underscore/hyphen, and allow numeric segments after a dot. RelativeTimeFilterOptions defaults timeUnit to MILLISECONDS, leaves zoneId/datePattern absent; it validates explicit offset zones and Java date-pattern syntax, but does not prove an arbitrary named zone exists on the server. No clock calculation is done in the browser. Invalid values/options throw TypeError before a request. Literal object creation can bypass these runtime builder checks; TypeScript alone is not validation.

Legacy compatibility

Condition's fields are optional and value is any. isValidateCondition is a truthiness check. and(...conditions) removes absent/all children and flattens nested AND; no conditions produces all(). or drops absent entries and returns all() for no valid entries; nor returns all() for an empty argument list and otherwise preserves its children. They are not interchangeable with filter.or/filter.nor. Legacy isIn(field, ...values) is variadic, while ids(values) accepts a string array. active() is the legacy deletion selector; new code uses filter.deletion(DeletionState.ACTIVE). ignoreCaseOptions and dateOptions return undefined when no options were supplied. raw and match are backend-specific legacy escape hatches; no new raw filter builder exists. Operator, LOGICAL_OPERATORS, EMPTY_VALUE_OPERATORS and OperatorLocale serve the legacy UI contract. All builders only produce data; server schema, authorization and storage semantics remain server responsibilities.

Complete example

import {
  filter,
  StringComparison,
  DeletionState,
} from '@ahoo-wang/fetcher-wow';
export const activeUsers = filter.and([
  filter.deletion(DeletionState.ACTIVE),
  filter.contains('state.name', 'ada', StringComparison.CASE_INSENSITIVE),
  filter.between('state.age', 18, 65),
  filter.elementMatch('state.roles', filter.eq('name', 'editor')),
]);
console.assert(activeUsers.operands.length === 4);
let rejected = false;
try {
  filter.isIn('state.role', []);
} catch {
  rejected = true;
}
console.assert(rejected);

Public signatures and types

These signatures follow declarations reachable from the current root entry. ? marks optional input; generics/interfaces only constrain compile-time types. Locate inherited and related types through the symbol index. Runtime defaults and failure behavior are described above.

FilterExpression builders and types

filter

Expand all fields and members

declare const filter: {
  matchAll(): MatchFilter;
  matchNone(): MatchFilter;
  id(value: string): MetadataValueFilter;
  ids(values: readonly string[]): MetadataValuesFilter;
  aggregateId(value: string): MetadataValueFilter;
  aggregateIds(values: readonly string[]): MetadataValuesFilter;
  tenantId(value: string): MetadataValueFilter;
  ownerId(value: string): MetadataValueFilter;
  spaceId(value: string): MetadataValueFilter;
  and: {
    <FIELDS extends string>(
      operands: readonly ElementFilterExpression<FIELDS>[],
    ): ElementLogicalFilter<FIELDS>;
    <FIELDS extends string>(
      operands: readonly FilterExpression<FIELDS>[],
    ): LogicalFilter<FIELDS>;
  };
  or: {
    <FIELDS extends string>(
      operands: readonly ElementFilterExpression<FIELDS>[],
    ): ElementLogicalFilter<FIELDS>;
    <FIELDS extends string>(
      operands: readonly FilterExpression<FIELDS>[],
    ): LogicalFilter<FIELDS>;
  };
  nor: {
    <FIELDS extends string>(
      operands: readonly ElementFilterExpression<FIELDS>[],
    ): ElementLogicalFilter<FIELDS>;
    <FIELDS extends string>(
      operands: readonly FilterExpression<FIELDS>[],
    ): LogicalFilter<FIELDS>;
  };
  eq<FIELDS extends string>(
    field: FIELDS,
    value: EqualityFilterValue,
  ): EqualityFilter<FIELDS>;
  ne<FIELDS extends string>(
    field: FIELDS,
    value: EqualityFilterValue,
  ): EqualityFilter<FIELDS>;
  gt<FIELDS extends string>(
    field: FIELDS,
    value: ComparableFilterLiteral,
  ): ComparisonFilter<FIELDS>;
  gte<FIELDS extends string>(
    field: FIELDS,
    value: ComparableFilterLiteral,
  ): ComparisonFilter<FIELDS>;
  lt<FIELDS extends string>(
    field: FIELDS,
    value: ComparableFilterLiteral,
  ): ComparisonFilter<FIELDS>;
  lte<FIELDS extends string>(
    field: FIELDS,
    value: ComparableFilterLiteral,
  ): ComparisonFilter<FIELDS>;
  contains<FIELDS extends string>(
    field: FIELDS,
    value: string,
    stringComparison?: StringComparison,
  ): StringFilter<FIELDS>;
  startsWith<FIELDS extends string>(
    field: FIELDS,
    value: string,
    stringComparison?: StringComparison,
  ): StringFilter<FIELDS>;
  endsWith<FIELDS extends string>(
    field: FIELDS,
    value: string,
    stringComparison?: StringComparison,
  ): StringFilter<FIELDS>;
  isIn<FIELDS extends string>(
    field: FIELDS,
    values: readonly ComparableFilterLiteral[],
  ): CollectionFilter<FIELDS>;
  notIn<FIELDS extends string>(
    field: FIELDS,
    values: readonly ComparableFilterLiteral[],
  ): CollectionFilter<FIELDS>;
  containsAll<FIELDS extends string>(
    field: FIELDS,
    values: readonly ComparableFilterLiteral[],
  ): CollectionFilter<FIELDS>;
  between<FIELDS extends string>(
    field: FIELDS,
    lowerBound: ComparableFilterLiteral,
    upperBound: ComparableFilterLiteral,
  ): BetweenFilter<FIELDS>;
  isEmpty<FIELDS extends string>(field: FIELDS): FieldPresenceFilter<FIELDS>;
  isEmptyString<FIELDS extends string>(
    field: FIELDS,
  ): FieldPresenceFilter<FIELDS>;
  isNotEmptyString<FIELDS extends string>(
    field: FIELDS,
  ): FieldPresenceFilter<FIELDS>;
  isNull<FIELDS extends string>(field: FIELDS): FieldPresenceFilter<FIELDS>;
  isNotNull<FIELDS extends string>(field: FIELDS): FieldPresenceFilter<FIELDS>;
  exists<FIELDS extends string>(field: FIELDS): FieldPresenceFilter<FIELDS>;
  notExists<FIELDS extends string>(field: FIELDS): FieldPresenceFilter<FIELDS>;
  deletion(state: DeletionState): DeletionFilter;
  elementMatch<FIELDS extends string, ELEMENT_FIELDS extends string>(
    field: FIELDS,
    predicate: ElementFilterExpression<ELEMENT_FIELDS>,
  ): ElementMatchFilter<FIELDS, ELEMENT_FIELDS>;
  search<FIELDS extends string>(
    query: string,
    options?: SearchFilterOptions<FIELDS>,
  ): SearchFilter<FIELDS>;
  today<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  beforeToday<FIELDS extends string>(
    field: FIELDS,
    time: string,
    options?: RelativeTimeFilterOptions,
  ): BeforeTodayFilter<FIELDS>;
  tomorrow<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  thisWeek<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  nextWeek<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  lastWeek<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  thisMonth<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  lastMonth<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  yesterday<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  nextMonth<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  lastYear<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  thisYear<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  nextYear<FIELDS extends string>(
    field: FIELDS,
    options?: RelativeTimeFilterOptions,
  ): CalendarFilter<FIELDS>;
  recentDays<FIELDS extends string>(
    field: FIELDS,
    days: number,
    options?: RelativeTimeFilterOptions,
  ): DaysFilter<FIELDS>;
  earlierDays<FIELDS extends string>(
    field: FIELDS,
    days: number,
    options?: RelativeTimeFilterOptions,
  ): DaysFilter<FIELDS>;
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174

packages/wow/src/query/filter.ts:580