breeze-client 2.2.2 → 3.0.0

package/core/core.d.ts

@@ -0,0 +1,285 @@
+/** The success callback accepted by the deprecated callback form of the async methods.
+@deprecated Await the returned promise instead of passing callbacks. */
+export interface Callback {
+    (data: any): void;
+}
+type Predicate<T> = (i: T) => boolean;
+declare function objectForEach(obj: Object, kvFn: (key: string, val: any) => any): void;
+declare function objectMap(obj: Object, kvFn?: (key: string, val: any) => any): any[];
+declare function objectFirst(obj: Object, kvPredicate: (key: string, val: any) => boolean): {
+    /** The property's name. */
+    key: string;
+    /** The property's value. */
+    value: any;
+} | null;
+declare function isSettable(obj: Object, propertyName: string): boolean;
+declare function getPropDescriptor(obj: Object, propertyName: string): PropertyDescriptor | undefined;
+/** can be used like: persons.filter(propEq("firstName", "John")) */
+declare function propEq(propertyName: string, value: any): (obj: Object) => boolean;
+/** can be used like: persons.filter(propEq("firstName", "FirstName", "John")) */
+declare function propsEq(property1Name: string, property2Name: string, value: any): (obj: Object) => boolean;
+/** can be used like persons.map(pluck("firstName")) */
+declare function pluck(propertyName: any): (obj: Object) => any;
+/** Return an array of property values from source */
+declare function getOwnPropertyValues(source: Object): any[];
+/** Copy properties from source to target. Returns target. */
+declare function extend(target: Object, source?: Object, propNames?: string[]): Object;
+/** Copy properties from defaults iff undefined on target.  Returns target. */
+declare function updateWithDefaults(target: Object, defaults: Object): any;
+/** Set ctor.defaultInstance to an instance of ctor with properties from target.
+    We want to insure that the object returned by ctor.defaultInstance is always immutable
+    Use 'target' as the primary template for the ctor.defaultInstance;
+    Use current 'ctor.defaultInstance' as the template for any missing properties
+    creates a new instance for ctor.defaultInstance
+    returns target unchanged */
+declare function setAsDefault(target: Object, ctor: {
+    new (...args: any[]): any;
+    defaultInstance?: any;
+}): any;
+/**
+    'source' is an object that will be transformed into another
+    'template' is a map where the
+       keys: are the keys to return
+         if a key contains ','s then the key is treated as a delimited string with first of the
+         keys being the key to return and the others all valid aliases for this key
+       'values' are either
+           1) the 'default' value of the key
+           2) a function that takes in the source value and should return the value to set
+         The value from the source is then set on the target,
+         after first passing thru the fn, if provided, UNLESS:
+           1) it is the default value
+           2) it is undefined ( nulls WILL be set)
+    'target' is optional
+       - if it exists then properties of the target will be set ( overwritten if the exist)
+       - if it does not exist then a new object will be created as filled.
+    'target is returned.
+*/
+declare function toJson(source: Object, template: Object, target?: Object): Object;
+/** Replacer function for toJSONSafe, when serializing entities.  Excludes entityAspect and other internal properties. */
+declare function toJSONSafeReplacer(prop: string, val: any): any;
+/** Safely perform toJSON logic on objects with cycles. */
+declare function toJSONSafe(obj: any, replacer?: (prop: string, value: any) => any): any;
+/** Resolves the values of a list of properties by checking each property in multiple sources until a value is found. */
+declare function resolveProperties(sources: Object[], propertyNames: string[]): any;
+declare function toArray(item: any): any[];
+/** a version of Array.map that doesn't require an array, i.e. works on arrays and scalars. */
+declare function map<T>(items: T | T[], fn: (v: T, ix?: number) => any, includeNull?: boolean): any | any[];
+/** Return first element matching predicate */
+declare function arrayFirst<T>(array: T[], predicate: Predicate<any>): T;
+/** Return index of first element matching predicate */
+declare function arrayIndexOf<T>(array: T[], predicate: Predicate<any>): number;
+/** Add item if not already in array */
+declare function arrayAddItemUnique<T>(array: T[], item: T): void;
+/** Remove items from the array
+ * @param array
+ * @param predicateOrItem - item to remove, or function to determine matching item
+ * @param shouldRemoveMultiple - true to keep removing after first match, false otherwise
+ */
+declare function arrayRemoveItem<T>(array: T[], predicateOrItem: T | Predicate<T>, shouldRemoveMultiple?: boolean): boolean;
+/** Combine array elements using the callback.  Returns array with length == min(a1.length, a2.length) */
+declare function arrayZip(a1: any[], a2: any[], callback: (x1: any, x2: any) => any): any[];
+declare function arrayEquals(a1: any[], a2: any[], equalsFn?: (x1: any, x2: any) => boolean): boolean;
+/** Returns the array stored under key, creating it if absent. */
+declare function getMapArray<K, V>(map: Map<K, V[]>, key: K): V[];
+/** Execute fn while obj has tempValue for property */
+declare function using(obj: Object, property: string, tempValue: any, fn: () => any): any;
+/** Call state = startFn(), call fn(), call endFn(state) */
+declare function wrapExecution(startFn: () => any, endFn: (state: any) => any, fn: () => any): any;
+/** Remember & return the value of fn() when it was called with its current args */
+declare function memoize(fn: any): any;
+declare function durationToSeconds(duration: string): number;
+declare function noop(): void;
+declare function identity(x: any): any;
+declare function isDate(o: any): boolean;
+declare function isDateString(s: string): boolean;
+declare function isFunction(o: any): boolean;
+declare function isGuid(value: any): boolean;
+declare function isDuration(value: any): boolean;
+declare function isEmpty(obj: any): boolean;
+/**
+ * Replaces `%1`, `%2`, ... in `str` with the arguments that follow it.
+ *
+ *     formatString("a %1 and a %2", "cat", "dog")   // "a cat and a dog"
+ *
+ * It declared rest parameters and then read `arguments` anyway, and compiled a fresh `RegExp`
+ * on every call to bound the placeholder to the number of arguments given - so `%3` with two
+ * arguments was left in place rather than replaced. One shared pattern does the same thing:
+ * a placeholder with no argument for it is left alone here too.
+ * @hidden
+ */
+export declare function formatString(str: string, ...params: any[]): string;
+/** @hidden */
+export declare function arrayFlatMap<T, U>(arr: T[], mapFn: (arg: T) => U[]): U[];
+/**
+ * A version 4 UUID.
+ *
+ * `crypto.randomUUID()` where it exists, which is everywhere Breeze supports except a browser
+ * outside a secure context - it is unavailable over plain HTTP. It is both properly random and
+ * about 30x faster than building one out of `Math.random()`, which matters because this is what
+ * names a new entity with a Guid key.
+ *
+ * The fallback is the old implementation. `Math.random()` is not a cryptographic source, so the
+ * values it produces are unique enough for a client-side temporary key and should not be relied
+ * on for anything else.
+ * @hidden
+ */
+export declare function getUuid(): string;
+/** @hidden */
+export declare function stringStartsWith(str: string, prefix: string): boolean;
+/** @hidden */
+export declare function stringEndsWith(str: string, suffix: string): boolean;
+/** Utility functions that Breeze 2.x exposed as `breeze.core`, kept for code written against 2.x.
+    Several now just call a JavaScript built-in; those are marked deprecated and name it. */
+export declare const core: {
+    /** @deprecated Use `Object.hasOwn(obj, key)`, which this now calls. */
+    hasOwnProperty: (obj: Object, key: string) => boolean;
+    /** The values of an object's own enumerable properties. `Object.values(obj)`, except that null
+        or undefined gives `[]`. */
+    getOwnPropertyValues: typeof getOwnPropertyValues;
+    /** The descriptor of `propertyName` on `obj` or, failing that, on the nearest prototype that
+        has it; `undefined` if none does. Unlike `Object.getOwnPropertyDescriptor`, it searches the
+        prototype chain. */
+    getPropertyDescriptor: typeof getPropDescriptor;
+    /** Calls `kvFn(key, value)` for each of an object's own enumerable properties. Does nothing for
+        null or undefined. */
+    objectForEach: typeof objectForEach;
+    /** The first of an object's own enumerable properties for which `kvPredicate(key, value)` is
+        true, as `{ key, value }`; `null` if there is none. */
+    objectFirst: typeof objectFirst;
+    /** Calls `kvFn(key, value)` for each of an object's own enumerable properties and returns the
+        results, leaving out any that are `undefined`. Without `kvFn`, returns the values. */
+    objectMap: typeof objectMap;
+    /** Copies properties from `source` onto `target` and returns `target`: all of `source`'s own
+        enumerable properties, or only `propNames` when given. A shallow copy, like `Object.assign`. */
+    extend: typeof extend;
+    /** A predicate that is true for an object whose `propertyName` is `=== value`:
+        `people.filter(core.propEq('firstName', 'John'))`. */
+    propEq: typeof propEq;
+    /** A predicate that is true for an object whose `property1Name` or `property2Name` is
+        `=== value`. */
+    propsEq: typeof propsEq;
+    /** A function that returns an object's `propertyName`: `people.map(core.pluck('firstName'))`. */
+    pluck: typeof pluck;
+    /** `Array.prototype.map` that also takes a single value, which it passes to `fn` and returns
+        the result of. Null or undefined is returned as is. With `includeNull` false, an element
+        whose result is null or undefined is left as a hole in the returned array. */
+    map: typeof map;
+    /** An object with each of `propertyNames` taken from the first of `sources` in which it is not
+        `undefined`. Breeze uses it to combine a query's settings with its manager's and the
+        defaults, in {@link QueryOptions.resolve} and {@link DataService.resolve}. */
+    resolveProperties: typeof resolveProperties;
+    /** Creates an instance of `ctor` from `target`, fills in whatever it leaves unset from the
+        current `ctor.defaultInstance`, and makes that the new `ctor.defaultInstance`. Returns
+        `target`. The `setAsDefault()` methods of {@link QueryOptions}, {@link SaveOptions},
+        {@link NamingConvention} and {@link LocalQueryComparisonOptions} are built on it. */
+    setAsDefault: typeof setAsDefault;
+    /** Copies each property of `defaults` onto `target` where `target`'s is `undefined`, and
+        returns `target`. */
+    updateWithDefaults: typeof updateWithDefaults;
+    /** The array stored in `map` under `key`, after storing an empty one there if there was none. */
+    getMapArray: typeof getMapArray;
+    /** `[]` for null or undefined, the array itself for an array, and `[item]` for anything else. */
+    toArray: typeof toArray;
+    /** Whether two arrays have the same length and equal elements, compared with `===` or with
+        `equalsFn` if given. An element that is itself an array is compared element by element, with
+        `===`. False if either array is null or undefined. */
+    arrayEquals: typeof arrayEquals;
+    /** @deprecated Use `arr.slice(start, end)`, or `Array.prototype.slice.call(arrayLike)` for
+        an arguments object. That is what this now does. */
+    arraySlice: (ar: any[], start?: number, end?: number) => any[];
+    /** The first element for which `predicate` is true, or `null`. Like `Array.prototype.find`,
+        except for returning `null` rather than `undefined`. */
+    arrayFirst: typeof arrayFirst;
+    /** The index of the first element for which `predicate` is true, or -1. The same as
+        `Array.prototype.findIndex`. */
+    arrayIndexOf: typeof arrayIndexOf;
+    /** Removes from `array`, in place, either `predicateOrItem` itself or the elements that
+        `predicateOrItem`, a function, matches. Removes only the last match unless
+        `shouldRemoveMultiple` is true. Returns whether anything was removed. */
+    arrayRemoveItem: typeof arrayRemoveItem;
+    /** Combines the elements of two arrays pairwise with `callback`. The result is as long as the
+        shorter array. */
+    arrayZip: typeof arrayZip;
+    /** Pushes `item` onto `array` unless the array already holds it. */
+    arrayAddItemUnique: typeof arrayAddItemUnique;
+    /** @deprecated Use `arr.flatMap(fn)`, which this now calls. */
+    arrayFlatMap: typeof arrayFlatMap;
+    /** Sets `obj[property]` to `tempValue`, calls `fn`, then restores the original value, deleting
+        the property if it had none, whether or not `fn` throws. Returns what `fn` returns. */
+    using: typeof using;
+    /** Calls `startFn()`, then `fn()`, then `endFn(state)` with what `startFn` returned, whether or
+        not `fn` throws. If it throws and the state is an object, the error is set on `state.error`
+        first. Returns what `fn` returns. */
+    wrapExecution: typeof wrapExecution;
+    /** Wraps `fn` so that it runs once for each distinct set of arguments and afterwards returns
+        the stored result. Arguments are keyed by value, objects by their `JSON.stringify`. The
+        results are stored on `fn` itself and never released. */
+    memoize: typeof memoize;
+    /** @deprecated Use `crypto.randomUUID()`. This calls it where it exists and falls back to a
+        `Math.random()` implementation in a browser outside a secure context, where it does not. */
+    getUuid: typeof getUuid;
+    /** Converts an ISO 8601 duration such as `PT1H30M` to seconds, counting a year as 360 days and
+        a month as 30. Throws for a string that is not a duration. */
+    durationToSeconds: typeof durationToSeconds;
+    /** Whether `obj[propertyName]` can be assigned: true if no object on the prototype chain
+        defines it, or if its descriptor is writable or has a setter. */
+    isSettable: typeof isSettable;
+    /** Whether `o` is a `Date` holding a valid time - not an Invalid Date. */
+    isDate: typeof isDate;
+    /** Whether `s` is an ISO 8601 date-time with a time zone, such as `2024-05-01T10:30:00Z` or
+        `2024-05-01T10:30:00.5+02:00`. A string with no time zone, or a date with no time, is not. */
+    isDateString: typeof isDateString;
+    /** Whether `value` is a string in GUID form: 8-4-4-4-12 hexadecimal digits. */
+    isGuid: typeof isGuid;
+    /** Whether `value` is a string that looks like an ISO 8601 duration, such as `PT1H`. A quick
+        check of its shape, not a full parse - see {@link core.durationToSeconds}. */
+    isDuration: typeof isDuration;
+    /** Whether `o` is an ordinary function. False for async and generator functions: it checks
+        `Object.prototype.toString`, which names those differently. */
+    isFunction: typeof isFunction;
+    /** Whether `obj` is null, undefined, or has no own enumerable properties. */
+    isEmpty: typeof isEmpty;
+    /** Returns its argument. */
+    identity: typeof identity;
+    /** Does nothing. */
+    noop: typeof noop;
+    /** @deprecated Use `str.startsWith(prefix)`. Not quite the same: this answers `false` for a
+        null string and `true` for a null prefix, where the built-in throws and compares against
+        the text "null" respectively. Guard the null yourself. */
+    stringStartsWith: typeof stringStartsWith;
+    /** @deprecated Use `str.endsWith(suffix)`, with the same caveat about nulls as
+        {@link core.stringStartsWith}. */
+    stringEndsWith: typeof stringEndsWith;
+    /** Replaces `%1`, `%2`, ... in `str` with the arguments that follow it:
+        `formatString('a %1 and a %2', 'cat', 'dog')` is `'a cat and a dog'`. */
+    formatString: typeof formatString;
+    /** Copies properties of `source` to `target`, a new object by default, as `template` directs,
+        and returns `target`. Each key of `template` names a property to copy; a key such as `'a,b'`
+        also accepts `b` as another name for `a`. The template's value is the property's default: a
+        property equal to it (by `==`), `undefined`, or an empty array is left out. If the
+        template's value is a function, it converts the property's value instead, and a
+        {@link BreezeEnum} is written as its name. Breeze's metadata classes build their `toJSON`
+        output with it. */
+    toJson: typeof toJson;
+    /** A copy of `obj` that `JSON.stringify` can serialize even when the object graph has cycles: a
+        reference back to an object already being copied is left out. Uses an object's own `toJSON`
+        when it has one, leaves out functions, and passes each property through `replacer` when
+        given, leaving out any it returns `undefined` for. */
+    toJSONSafe: typeof toJSONSafe;
+    /** A `replacer` for {@link core.toJSONSafe} that leaves out an entity's Breeze members -
+        `entityAspect`, `complexAspect`, `entityType`, `complexType`, `getProperty`, `setProperty`
+        and `constructor` - and any property whose name starts with `_` or `$`. Breeze serializes
+        unmapped property values with it. */
+    toJSONSafeReplacer: typeof toJSONSafeReplacer;
+    /** Text that Breeze uses in its error messages. */
+    strings: {
+        /** Advice appended to errors about a query whose entity type Breeze cannot determine. */
+        TO_TYPE: string;
+    };
+};
+/** The failure callback accepted by the deprecated callback form of the async methods.
+@deprecated Await the returned promise instead of passing callbacks. */
+export interface ErrorCallback {
+    (error: any): void;
+}
+export {};