breeze-client 2.2.2 → 3.0.0

package/query/predicate.d.ts

@@ -0,0 +1,394 @@
+import { EntityType, StructuralType } from '../metadata/entity-metadata.js';
+import { QueryOp } from './entity-query.js';
+import type { FilterQueryOp, RecursiveArray } from './entity-query.js';
+import { DataType } from '../metadata/data-type.js';
+import { Entity } from '../entity/entity-aspect.js';
+import type { CollectionElement, CollectionPath, FilterOpFor, FilterValueFor, FunctionExpressionPath, NoInferFrom, PropertyPath, PropertyValue, QuantifierOp, WhereObject } from './property-path.js';
+export interface Op {
+    key: string;
+    aliases?: string[];
+    isFunction?: boolean;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export interface Visitor {
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export interface VisitContext {
+    entityType?: EntityType;
+    toNameOnServer?: boolean;
+    useExplicitDataType?: boolean;
+    visitor?: Visitor;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export interface ExpressionContext {
+    entityType?: EntityType;
+    usesNameOnServer?: boolean;
+    dataType?: DataType | string;
+    isRHS?: boolean;
+    isFnArg?: boolean;
+}
+/**
+Builds {@link Predicate}s checked against one entity type - what {@link Predicate.for} returns.
+
+Each Predicate it produces is a `Predicate<T>`, so combining them with `and`, `or` and `not` is
+checked too, and an {@link EntityQuery} for another type will not accept them.
+*/
+export interface TypedPredicateFactory<T> {
+    /** A path only known at run time, or a query function, neither of which can be checked.
+    ```ts
+    const p = Predicate.for(Customer);
+    const byColumn = p(userChosenColumn, "eq", value);          // userChosenColumn: string
+    const byFunction = p("toLower(companyName)", "startsWith", "c");
+    ```
+    */
+    <P extends string>(property: P extends FunctionExpressionPath ? P : (string extends P ? P : never), operator: string | FilterQueryOp, value: any): Predicate<T>;
+    <P extends string>(collection: string extends P ? P : never, quantifier: string | FilterQueryOp, property: string, operator: string | FilterQueryOp, value: any): Predicate<T>;
+    /** A property, an operator that suits its type, and a matching value.
+    ```ts
+    const p = Predicate.for(Order);
+    const pred = p("freight", "gt", 100);
+    const viaNavigation = p("customer.companyName", "startsWith", "A");
+    ```
+    */
+    <P extends PropertyPath<T>, O extends FilterOpFor<PropertyValue<T, P>>>(property: P, operator: O, value: FilterValueFor<T, PropertyValue<T, P>, O>): Predicate<T>;
+    /** `any` or `all` over a collection, filtered by a Predicate built for the element type.
+    ```ts
+    const pd = Predicate.for(OrderDetail);
+    const pred = Predicate.for(Order)("orderDetails", "any", pd("unitPrice", ">", 20));
+    ```
+    */
+    <P extends CollectionPath<T>>(collection: P, quantifier: QuantifierOp | FilterQueryOp, predicate: Predicate<CollectionElement<T, P>>): Predicate<T>;
+    /** `any` or `all` over a collection, then a filter on the element type.
+    ```ts
+    const p = Predicate.for(Customer);
+    const pred = p("orders", "all", "freight", "lt", 100);
+    ```
+    */
+    <P extends CollectionPath<T>, P2 extends PropertyPath<CollectionElement<T, P>>, O2 extends FilterOpFor<PropertyValue<CollectionElement<T, P>, P2>>>(collection: P, quantifier: QuantifierOp, property: P2, operator: O2, value: FilterValueFor<CollectionElement<T, P>, PropertyValue<CollectionElement<T, P>, P2>, O2>): Predicate<T>;
+    /** The object form, checked in full.
+    ```ts
+    const p = Predicate.for(Customer);
+    const pred = p({ city: "London", companyName: { startsWith: "A" } });
+    ```
+    */
+    (predicate: WhereObject<T>): Predicate<T>;
+}
+/**
+Used to define a 'where' predicate for an {@link EntityQuery}. Predicates are immutable, which means that any
+method that would modify a Predicate actually returns a new Predicate.
+```ts
+const p = Predicate.for(Order);
+const p1 = p("freight", ">", 100);
+const p2 = p1.and(p("shipCity", "startsWith", "C"));
+const query = EntityQuery.from(Order).where(p2);
+```
+*/
+export declare class Predicate<T = any> {
+    /**
+    Never set: it is here only so that a `Predicate<Order>` and a `Predicate<Customer>` are different
+    types. It is public because a private member reaches the published .d.ts without its type, which
+    would lose the distinction.
+    @hidden
+    */
+    readonly _$predicateFor?: T;
+    /** The operator of this predicate. Its `key` is, for example, `eq` or `gt` for a comparison, `and` or `or` for a composite, `not`, or `any` or `all`. `undefined` for a pass-through predicate made from a raw filter string. __Read Only__ */
+    op: Op;
+    /** The name of the visitor method that handles this kind of predicate, such as `binaryPredicate` or `andOrPredicate`. Used by Breeze when it serializes or evaluates a predicate; applications do not normally need it. __Read Only__ */
+    visitorMethodName: string;
+    /**
+    Predicate constructor. The compiler checks nothing it is given; for that, build the Predicate with
+    {@link Predicate.for} or {@link Predicate.create} and a type argument instead.
+    ```ts
+    const p1 = new Predicate("companyName", "startsWith", "B");
+    const query = EntityQuery.from(Customer).where(p1);
+    ```
+  
+    or
+    ```ts
+    const p2 = new Predicate("region", FilterQueryOp.Equals, null);
+    const query = EntityQuery.from(Customer).where(p2);
+    ```
+    @param args - `property, operator, value`, in that order:
+    - **property**: A property name, a nested property name or an expression involving a property name.
+    - **operator**: the filter query operator.
+    - **value**: This will be treated as either a property expression or a literal depending on context.  In general,
+    if the value can be interpreted as a property expression it will be, otherwise it will be treated as a literal.
+    In most cases this works well, but you can also force the interpretation by making the value argument itself an object with a 'value'
+    property and an 'isLiteral' property set to either true or false.  Breeze also tries to infer the dataType of any
+    literal based on context, if this fails you can force this inference by making the value argument an object with a
+    'value' property and a 'dataType' property set to one of the breeze.DataType enumeration instances.
+    */
+    constructor(...args: any[]);
+    static create<T = any>(predicate: Predicate<T>): Predicate<T>;
+    static create(rawFilterString: string): Predicate;
+    static create(anArray: RecursiveArray<string | number | FilterQueryOp | Predicate>): Predicate;
+    static create<P extends string>(property: P extends FunctionExpressionPath ? P : (string extends P ? P : never), operator: string | FilterQueryOp, value: any): Predicate;
+    static create<P extends string>(collection: string extends P ? P : never, quantifier: string | FilterQueryOp, property: string, operator: string | FilterQueryOp, value: any): Predicate;
+    static create(property: string, filterop: string, property2: string, filterop2: string, property3: string, filterop3: string, value: any): Predicate;
+    /** Checks the property path against `T`. The operator and the value are not tied to that
+    property: supplying `T` stops TypeScript inferring the rest from the path. Use the object form,
+    or {@link Predicate.for}, to have them checked too.
+    ```ts
+    const p = Predicate.create<Customer>("companyName", "startsWith", "C");
+    ```
+    */
+    static create<T = any>(property: PropertyPath<NoInferFrom<T>> | FunctionExpressionPath, operator: string | FilterQueryOp, value: any): Predicate<T>;
+    /** `any` or `all` over a collection, filtered by a Predicate built for the element type.
+    ```ts
+    const pd = Predicate.for(OrderDetail);
+    const p = Predicate.create<Order>("orderDetails", "any", pd("unitPrice", ">", 20));
+    ```
+    */
+    static create<T = any>(collection: CollectionPath<NoInferFrom<T>>, quantifier: QuantifierOp | FilterQueryOp, predicate: Predicate): Predicate<T>;
+    /** Checks the collection path against `T`.
+    ```ts
+    const p = Predicate.create<Customer>("orders", "any", "freight", ">", 100);
+    ```
+    */
+    static create<T = any>(collection: CollectionPath<NoInferFrom<T>>, quantifier: QuantifierOp | FilterQueryOp, property: string, operator: string | FilterQueryOp, value: any): Predicate<T>;
+    /** The object form, checked in full against `T`.
+    ```ts
+    const p = Predicate.create<Order>({ freight: { gt: 100 }, shipCity: { startsWith: "C" } });
+    ```
+    */
+    static create<T = any>(predicate: WhereObject<NoInferFrom<T>>): Predicate<T>;
+    /**
+    Creates a 'composite' Predicate by 'and'ing a set of specified Predicates together.
+    ```ts
+    const p = Predicate.for(Order);
+    const dt = new Date(1988, 9, 12);
+    const p1 = p("orderDate", "ne", dt);
+    const p2 = p("shipCity", "startsWith", "C");
+    const p3 = p("freight", ">", 100);
+    const newPred = Predicate.and(p1, p2, p3);
+    ```
+  
+    or
+    ```ts
+    const preds = [p1, p2, p3];
+    const newPred = Predicate.and(preds);
+    ```
+    @param predicates - multiple Predicates or an array of Predicates.
+    Any null or undefined values passed in will be automatically filtered out before constructing the composite predicate.
+    */
+    static and<T = any>(...predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    static and<T = any>(predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    /**
+    Creates a 'composite' Predicate by 'or'ing a set of specified Predicates together.
+    ```ts
+    const p = Predicate.for(Order);
+    const dt = new Date(1988, 9, 12);
+    const p1 = p("orderDate", "ne", dt);
+    const p2 = p("shipCity", "startsWith", "C");
+    const p3 = p("freight", ">", 100);
+    const newPred = Predicate.or(p1, p2, p3);
+    ```
+  
+    or
+    ```ts
+    const preds = [p1, p2, p3];
+    const newPred = Predicate.or(preds);
+    ```
+    @param predicates - multiple Predicates or an array of Predicates.
+    Any null or undefined values passed in will be automatically filtered out before constructing the composite predicate.
+    */
+    static or<T = any>(...predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    static or<T = any>(predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    /**
+    Creates a 'composite' Predicate by 'negating' a specified predicate.
+    ```ts
+    const p1 = Predicate.create<Order>({ freight: { gt: 100 } });
+    const not_p1 = Predicate.not(p1);
+    ```
+  
+    This can also be accomplished using the 'instance' version of the 'not' method
+    ```ts
+    const not_p1 = p1.not();
+    ```
+  
+    Both of which would be the same as
+    ```ts
+    const not_p1 = Predicate.create<Order>({ freight: { le: 100 } });
+    ```
+    */
+    static not<T = any>(pred: Predicate<T>): Predicate<T>;
+    /**
+    Builds Predicates checked against one entity type.
+    ```ts
+    const p = Predicate.for(Customer);
+    const pred = p("companyName", "startsWith", "C").and(p("city", "eq", "Vienna"));
+    ```
+  
+    A standalone Predicate has no query to take an entity type from, so on its own
+    {@link Predicate.create} cannot check anything. Naming the type supplies what is missing, the
+    same way {@link EntityQuery.from} does for a query - and from a constructor rather than a type
+    argument, so the type is written once.
+  
+    The constructor is read for its type only; nothing about it is kept. The predicates are ordinary
+    Predicates at run time, typed `Predicate<U>`, so that what they are combined with, and the query
+    they are used in, is checked too. The constructor does not have to be registered with a MetadataStore for this - though
+    if it is not, nothing validates the path against the metadata either, exactly as before.
+    @param ctor - The entity class to check property paths against.
+    @returns A factory that builds Predicates for that type.
+    */
+    static for<U extends Entity>(ctor: new () => U): TypedPredicateFactory<U>;
+    /**
+    Adds functions that predicates can call, such as `toupper` in `Predicate.create<Customer>("toupper(companyName)", "==", "ACME")`,
+    or replaces existing ones. Each entry maps a function name to `fn`, which evaluates it in local
+    queries, and the {@link DataType} it returns. A server query sends the call by name, so the
+    server must support the function too.
+    ```ts
+    Predicate.extendFuncMap({
+      initial: { fn: (s: string) => s.charAt(0), dataType: DataType.String }
+    });
+    ```
+    @param funcMap - The functions to add, keyed by name. Write names in lower case: Breeze lower-cases a
+    function name when it parses a predicate.
+    */
+    static extendFuncMap(funcMap: {
+        [key: string]: {
+            fn: (...args: any[]) => any;
+            dataType: DataType;
+        };
+    }): void;
+    and(...predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    and(predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    and(predicate: WhereObject<T>): Predicate<T>;
+    and<O extends string>(property: PropertyPath<T>, operator: string extends O ? O : never, value: any): Predicate<T>;
+    and<P extends string>(property: P extends FunctionExpressionPath ? P : (string extends P ? P : never), operator: string | FilterQueryOp, value: any): Predicate<T>;
+    and<P extends string>(collection: string extends P ? P : never, quantifier: string | FilterQueryOp, property: string, operator: string | FilterQueryOp, value: any): Predicate<T>;
+    and<P extends CollectionPath<T>>(collection: P, quantifier: QuantifierOp | FilterQueryOp, predicate: Predicate<CollectionElement<T, P>>): Predicate<T>;
+    and<P extends PropertyPath<T>, O extends FilterOpFor<PropertyValue<T, P>>>(property: P, operator: O, value: FilterValueFor<T, PropertyValue<T, P>, O>): Predicate<T>;
+    and<P extends CollectionPath<T>, P2 extends PropertyPath<CollectionElement<T, P>>, O2 extends FilterOpFor<PropertyValue<CollectionElement<T, P>, P2>>>(collection: P, quantifier: QuantifierOp, property: P2, operator: O2, value: FilterValueFor<CollectionElement<T, P>, PropertyValue<CollectionElement<T, P>, P2>, O2>): Predicate<T>;
+    or(...predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    or(predicates: (Predicate<T> | null | undefined)[]): Predicate<T>;
+    or(predicate: WhereObject<T>): Predicate<T>;
+    or<O extends string>(property: PropertyPath<T>, operator: string extends O ? O : never, value: any): Predicate<T>;
+    or<P extends string>(property: P extends FunctionExpressionPath ? P : (string extends P ? P : never), operator: string | FilterQueryOp, value: any): Predicate<T>;
+    or<P extends string>(collection: string extends P ? P : never, quantifier: string | FilterQueryOp, property: string, operator: string | FilterQueryOp, value: any): Predicate<T>;
+    or<P extends CollectionPath<T>>(collection: P, quantifier: QuantifierOp | FilterQueryOp, predicate: Predicate<CollectionElement<T, P>>): Predicate<T>;
+    or<P extends PropertyPath<T>, O extends FilterOpFor<PropertyValue<T, P>>>(property: P, operator: O, value: FilterValueFor<T, PropertyValue<T, P>, O>): Predicate<T>;
+    or<P extends CollectionPath<T>, P2 extends PropertyPath<CollectionElement<T, P>>, O2 extends FilterOpFor<PropertyValue<CollectionElement<T, P>, P2>>>(collection: P, quantifier: QuantifierOp, property: P2, operator: O2, value: FilterValueFor<CollectionElement<T, P>, PropertyValue<CollectionElement<T, P>, P2>, O2>): Predicate<T>;
+    /**
+    Returns the 'negated' version of this Predicate
+    ```ts
+    const p1 = Predicate.create<Order>({ freight: { gt: 100 } });
+    const not_p1 = p1.not();
+    ```
+  
+    This can also be accomplished using the 'static' version of the 'not' method
+    ```ts
+    const not_p1 = Predicate.not(p1);
+    ```
+  
+    which would be the same as
+    ```ts
+    const not_p1 = Predicate.create<Order>({ freight: { le: 100 } });
+    ```
+    */
+    not(): Predicate<T>;
+    /**
+    Returns this predicate in Breeze's JSON query syntax, with property paths as written - the object
+    form that {@link Predicate.create} and {@link EntityQuery.where} also accept, such as
+    `{ freight: { gt: 100 } }`. `JSON.stringify` calls it.
+    */
+    toJSON(): any;
+    /** Returns this predicate as a JSON string: `JSON.stringify` of {@link Predicate.toJSON}. Useful for logging and debugging. */
+    toString(): string;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export declare class UnaryPredicate extends Predicate {
+    pred: Predicate;
+    constructor(op: string | QueryOp, ...args: any[]);
+    _validate(entityType: EntityType, usesNameOnServer?: boolean): void;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export declare class BinaryPredicate extends Predicate {
+    expr1Source: any;
+    expr2Source: any;
+    expr1?: PredicateExpression;
+    expr2?: PredicateExpression;
+    constructor(op: string | QueryOp, expr1: any, expr2: any);
+    _validate(entityType: EntityType, usesNameOnServer?: boolean): void;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export declare class AndOrPredicate extends Predicate {
+    preds: Predicate[];
+    constructor(op: string | QueryOp, preds: any[]);
+    _validate(entityType: EntityType, usesNameOnServer?: boolean): void;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export declare class AnyAllPredicate extends Predicate {
+    exprSource: string;
+    pred: Predicate;
+    constructor(op: string | QueryOp, expr: string, pred: any);
+    _validate(entityType: EntityType, usesNameOnServer: boolean): void;
+}
+/** @hidden */
+export declare class PredicateExpression {
+    visitorMethodName: string;
+    visit: Function;
+    dataType?: DataType | StructuralType;
+    constructor(visitorMethodName: string);
+    _validate(entityType: EntityType | undefined, usesNameOnServer?: boolean): void;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export declare class LitExpr extends PredicateExpression {
+    value: any;
+    /** Narrows the optional dataType on PredicateExpression: a LitExpr always has one,
+        because the constructor falls back to DataType.fromValue when none is supplied. */
+    dataType: DataType;
+    hasExplicitDataType: boolean;
+    constructor(value: any, dataType: string | DataType | undefined, hasExplicitDataType?: boolean);
+    toString(): string;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export declare class PropExpr extends PredicateExpression {
+    propertyPath: string;
+    constructor(propertyPath: string);
+    toString(): string;
+    _validate(entityType: EntityType | undefined, usesNameOnServer?: boolean): void;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link UriBuilderAdapter} implementation.
+@adapter (see {@link UriBuilderAdapter})
+@hidden
+*/
+export declare class FnExpr extends PredicateExpression {
+    fnName: string;
+    exprs: PredicateExpression[];
+    localFn: any;
+    constructor(fnName: string, exprs: PredicateExpression[]);
+    toString(): string;
+    _validate(entityType: EntityType | undefined, usesNameOnServer?: boolean): void;
+    static _funcMap: Map<string, {
+        fn: (...args: any[]) => any;
+        dataType: DataType;
+    }>;
+}