@object-ui/core 17.6.0 → 17.7.0

package/dist/utils/filter-converter.d.ts

@@ -23,6 +23,34 @@ export type FilterNode = [string, string, any] | [string, ...FilterNode[]];
  * @param operator - MongoDB-style operator (e.g., '$gte', '$in')
  * @returns ObjectStack operator or null if not recognized
  */
+/**
+ * What the refusal is ABOUT, as structured data rather than as prose to scrape.
+ *
+ * `message` already names both, but a renderer that wants to say "the
+ * $icontains condition cannot be applied" must not recover the token with a
+ * regular expression over an English paragraph that every one of these
+ * refusals deliberately writes differently. objectui#9050's step 2 requires the
+ * render-time diagnostic to NAME the operator, so the name travels as a field.
+ *
+ * `operator` is the spelling the AUTHOR wrote — `$startswith` for a retired
+ * alias, `icontains` for a view rule — never a canonical form substituted for
+ * it, for the reason the view-rule arm's own tail already gives: prescribing a
+ * spelling the author's vocabulary does not have sends them looking for a key
+ * their metadata cannot contain.
+ *
+ * It is OPTIONAL because some refusals are not about an operator at all: the
+ * bare-array and exotic-comparand arms judge a COMPARAND written in the
+ * implicit-equality position, and the empty-operator-map arm judges a field
+ * that names NO operator (`{ a: {} }`, objectui#9164). In each, no operator was
+ * spelled and `field` is the only handle the author can act on. A renderer
+ * reads {@link filterRefusalSubject} rather than choosing between them itself.
+ */
+export interface FilterRefusalSubject {
+    /** The operator spelling the author wrote, when the refusal is about one. */
+    operator?: string;
+    /** The field the refused condition is on, when the refusal is about one. */
+    field?: string;
+}
 /**
  * A filter operator this layer will not translate.
  *
@@ -34,8 +62,22 @@ export type FilterNode = [string, string, any] | [string, ...FilterNode[]];
 export declare class FilterOperatorError extends Error {
     readonly code = "INVALID_FILTER";
     readonly httpStatus = 400;
-    constructor(message: string);
+    /** @see FilterRefusalSubject */
+    readonly operator: string | undefined;
+    /** @see FilterRefusalSubject */
+    readonly field: string | undefined;
+    constructor(message: string, subject?: FilterRefusalSubject);
 }
+/**
+ * The one token a "this view's filter is malformed" state names.
+ *
+ * Operator first, because that is what the ruling asks the state to name and
+ * what an author can act on — `$regex` is not supported, `$startswith` is
+ * retired. Field second, for the refusals that have no operator to name — the
+ * two comparand arms and the empty operator map. `undefined` for neither, which no arm produces today and which a
+ * renderer must still handle rather than print "undefined" at a user.
+ */
+export declare function filterRefusalSubject(error: FilterOperatorError): string | undefined;
 export declare function convertOperatorToAST(operator: string): string | null;
 /**
  * Convert object-based filters to ObjectStack FilterNode AST format.
@@ -59,9 +101,67 @@ export declare function convertOperatorToAST(operator: string): string | null;
  * convertFiltersToAST({ age: { $gte: 18, $lte: 65 }, status: 'active' })
  * // => ['and', ['age', '>=', 18], ['age', '<=', 65], ['status', '=', 'active']]
  *
- * @throws {Error} If an unknown operator is encountered
+ * @example
+ * // Logical combinators (objectui#6948) — children lower recursively
+ * convertFiltersToAST({ $or: [{ status: 'open' }, { status: 'blocked' }] })
+ * // => ['or', ['status', '=', 'open'], ['status', '=', 'blocked']]
+ *
+ * @example
+ * // A Date is a comparand, not an operator map (objectui#8555). It lowers as
+ * // the Date INSTANCE — the spec accepts one, and the operator form already
+ * // emits one.
+ * convertFiltersToAST({ created: new Date('2026-01-01') })
+ * // => ['created', '=', Date(2026-01-01)]
+ *
+ * @throws {FilterOperatorError} If an unknown operator is encountered, if
+ * `$not` is used — see the `$not` arm for why the AST cannot carry it — if a
+ * field's value is a bare ARRAY (`{ tags: ['a', 'b'] }`) — see the array arm for
+ * why that is refused rather than read as `$in` — or if a field's value is an
+ * EXOTIC object the spec does not accept as a comparand (`{ name: /abc/ }`,
+ * a `Set`, a `Map`): see the exotic-comparand arm for why that is refused
+ * rather than dropped (objectui#8567), or if an `$icontains` comparand is not a
+ * NON-EMPTY STRING (`{ name: { $icontains: '' } }`, `{ name: { $icontains: 42 } }`)
+ * — two shapes `@objectstack/spec`'s `FILTER_TEXT_CASES` declares REFUSED and
+ * `ValueDataSource` has refused since objectui#8748; see
+ * {@link refuseTextComparand} (objectui#9001), or if a field is an EMPTY
+ * operator map (`{ a: {} }`) — alone (objectui#9164) or
+ * beside a key that lowers (objectui#10788): see {@link refuseEmptyOperatorMap},
+ * or if a `$empty` flag is not a boolean (`{ a: { $empty: 'yes' } }`,
+ * objectui#11094).
+ *
+ * @example
+ * // A field with NO operator (objectui#9164)
+ * convertFiltersToAST({ a: {} })
+ * // => throws FilterOperatorError (INVALID_FILTER / 400), field 'a'
+ *
+ * @example
+ * // … and beside a key that lowers, where it used to vanish and widen the
+ * // result to `['status', '=', 'a']` (objectui#10788)
+ * convertFiltersToAST({ status: 'a', created: {} })
+ * // => throws FilterOperatorError (INVALID_FILTER / 400), field 'created'
+ *
+ * @example
+ * // A filter that is NOTHING BUT combinators reducing to the TRUE identity
+ * // constrains nothing, and says so (objectui#8770). Callers skip the slot.
+ * convertFiltersToAST({ $and: [] })
+ * // => undefined
+ *
+ * @example
+ * // A filter whose EVERY key is skipped for a null/undefined value also
+ * // constrains nothing — the same answer this function already gives that key
+ * // when a sibling survives (objectui#9020). Callers skip the slot.
+ * convertFiltersToAST({ a: null })
+ * // => undefined
+ *
+ * @example
+ * // … and a filter that MIXES the two constrains nothing either, because the
+ * // identity fold counts only the keys the loop actually PROCESSED
+ * // (objectui#9030). A skipped key used to be counted against that fold, so a
+ * // filter whose every key folds alone did not fold together.
+ * convertFiltersToAST({ $and: [], b: undefined })
+ * // => undefined
  */
-export declare function convertFiltersToAST(filter: Record<string, any>): FilterNode | Record<string, any>;
+export declare function convertFiltersToAST(filter: Record<string, any>): FilterNode | Record<string, any> | undefined;
 /**
  * Normalize ONE filter source into a single filter node.
  *
@@ -108,9 +208,57 @@ export declare function convertFiltersToAST(filter: Record<string, any>): Filter
  * untouched.
  *
  * Returns `undefined` for an absent or empty source, so callers can skip
- * `$filter` rather than sending an empty array.
+ * `$filter` rather than sending an empty array — and, since objectui#8770, for
+ * an object source that is nothing but TRUE-identity combinators
+ * (`{ $and: [] }`), and since objectui#9020 for one whose every key is skipped
+ * for a null/undefined value (`{ a: null }`). Both constrain nothing and so
+ * contribute nothing to the `and` {@link mergeFilterNodes} builds. Those answers
+ * are inherited from {@link convertFiltersToAST}, not decided a second time
+ * here — including the fact that they are two separate decisions there.
  */
 export declare function toFilterNode(source: unknown): FilterNode | Record<string, any> | undefined;
+/**
+ * {@link toFilterNode}'s answer for a caller that has no `catch` above it.
+ *
+ * ## Why this exists (objectui#9050, ruling C′ step 2)
+ *
+ * `toFilterNode` is documented as "the last stop before the wire", and the two
+ * callers that reach the wire — `plugin-list`'s `buildEffectiveFilter` and
+ * `plugin-view`'s `ObjectView` — do have a `catch`: they call it inside a load
+ * `try`, `classifyLoadError` reads this file's `INVALID_FILTER` / 400 envelope,
+ * and the author sees "this filter is malformed". Three OTHER callers reach it
+ * from a RENDER-time `useMemo` (`plugin-detail`'s `RelatedList`,
+ * `plugin-form`'s `LineItemsPanel`, `plugin-grid`'s `ObjectGrid`), where a
+ * throw is a render error and there is no `classifyLoadError` in the path.
+ * A fourth is an ADAPTER rather than a renderer: `ValueDataSource.find` lowers
+ * an array `$filter` through this before matching it in memory
+ * (objectui#10767), and a `find` that never threw on a bad filter must not
+ * start to — it re-seats `refusal` as its own excluded-and-logged refusal.
+ *
+ * ## Why the return type is a UNION and not `node | undefined`
+ *
+ * Because `undefined` is the refused answer. A `try`/`catch` that swallows the
+ * refusal and hands back `undefined` means NO FILTER — every row — which is a
+ * silently unconstrained query on a view whose whole purpose can be to hide
+ * rows, and is the failure objectui#9001 closed. So the refusal is not
+ * representable as a node: `ok: false` carries the error and has no `node` to
+ * read at all, and TypeScript makes a caller narrow before it can build a
+ * query. That is the whole difference between this and a bare `catch`.
+ *
+ * ⚠️ Only a {@link FilterOperatorError} is caught. Anything else is a defect in
+ * this file rather than a statement about the author's filter, and is rethrown
+ * so it keeps reaching whatever boundary would have seen it — a render-time
+ * `TypeError` swallowed into "your filter is malformed" would send the author
+ * to edit a filter that is fine.
+ */
+export type FilterNodeResult = {
+    ok: true;
+    node: FilterNode | Record<string, any> | undefined;
+} | {
+    ok: false;
+    refusal: FilterOperatorError;
+};
+export declare function toFilterNodeSafely(source: unknown): FilterNodeResult;
 /**
  * Combine filter sources under a single `and`, each as its OWN child.
  *