breeze-client 2.2.2 → 3.0.0

package/manager/entity-manager.d.ts

@@ -0,0 +1,801 @@
+import { DataServiceAdapter } from '../config/interface-registry.js';
+import { Callback, ErrorCallback } from '../core/core.js';
+import { BreezeEvent } from '../core/event.js';
+import { Entity, ComplexObject, StructuralObject, PropertyChangedEventArgs } from '../entity/entity-aspect.js';
+import type { RelationArray } from '../entity/relation-array.js';
+import { MetadataStore, EntityType, DataProperty } from '../metadata/entity-metadata.js';
+import { EntityKey } from '../entity/entity-key.js';
+import { EntityAction } from '../entity/entity-action.js';
+import { EntityState } from '../entity/entity-state.js';
+import { DataService } from '../metadata/data-service.js';
+import { ValidationError } from '../validation/validate.js';
+import { ValidationOptions } from '../validation/validation-options.js';
+import { QueryOptions, MergeStrategy } from '../query/query-options.js';
+import { SaveOptions } from './save-options.js';
+import { KeyGenerator } from '../entity/key-generator.js';
+import { EntityQuery } from '../query/entity-query.js';
+import type { KeyValues } from '../query/property-path.js';
+/** The response to one HTTP request Breeze made, as its data service adapter received it. Found on
+{@link ServerError.httpResponse}, {@link QueryResult.httpResponse} and {@link SaveResult.httpResponse}. */
+export interface HttpResponse {
+    /** The request that was sent: its {@link AjaxConfig} without the callbacks - `url`, `type` (the
+    HTTP method), `params`, `data`, `headers` and so on. */
+    config: any;
+    /** The response body: the parsed JSON of a successful response, or the text of a failed one.
+    Null when the request failed before any response arrived, or its body could not be read. */
+    data: any;
+    /** Set only when the request failed: the error the transport threw if the request could not be
+    completed or its body could not be read, otherwise the status text. */
+    error?: any;
+    /** Set by Breeze on the response to a save request, where it is used to turn the server's
+    per-entity errors into {@link EntityError}s. Undefined for queries and metadata requests.
+    Applications do not normally need it. */
+    saveContext?: any;
+    /** The HTTP status code. `0` when the request failed before any response arrived: offline, DNS,
+    CORS, a server that is down, or an aborted request. */
+    status: number;
+    /** The HTTP status text, such as "Not Found". Empty when the server sent none (HTTP/2 never does), and set to
+    the transport's error message when the request failed before any response arrived. May be absent with a custom ajax adapter. */
+    statusText?: string;
+    /** Returns the value of the named response header, or `null` if the response did not include it.
+    Called with an empty name, returns an object holding every header, keyed by lower-case name.
+    When no response arrived, returns `""` for a name and `{}` without one. */
+    getHeaders(headerName: string): string;
+}
+/** What {@link EntityManager.importEntities} returns. */
+export interface ImportResult {
+    /** The entities in the bundle as they now are in this manager: the ones newly attached, and the
+    cached ones they were merged into - including any the {@link ImportConfig.mergeStrategy} left
+    unchanged. */
+    entities: Entity[];
+    /** The temporary keys in the bundle, each mapped to the temporary key its entity has in this
+    manager. See {@link ITempKeyMap}. */
+    tempKeyMapping: ITempKeyMap;
+}
+/** Base shape of any errors returned from the server. */
+export interface ServerError extends Error {
+    /** The failed response, for anything the other members do not cover. */
+    httpResponse: HttpResponse;
+    /** The HTTP status code - see {@link HttpResponse.status}. `0` when the request failed before any
+    response arrived. */
+    status: number;
+    /** The best description Breeze could find: the message in the response body (a .NET exception's
+    message, or the `message`, `detail` or `title` of a JSON error), otherwise the transport's error
+    text. When the status is `0`, it also says the server was probably not reached. */
+    message: string;
+    /** The status text of the failed response - see {@link HttpResponse.statusText}. */
+    statusText?: string;
+    /** The body of the failed response, as the adapter received it (`httpResponse.data`); null if there was none. */
+    body?: any;
+    /** The URL the request was sent to (`httpResponse.config.url`). Query parameters added with
+    `EntityQuery.withParameters` are not included. */
+    url?: string;
+    /** The RFC 9457 `type` member of the problem document, when the server sent one: a URI naming
+    what kind of problem this is.
+  
+    Read it rather than the message when the recovery depends on the kind of failure. The status
+    code is often not enough on its own - an optimistic concurrency conflict and a duplicate key are
+    both `409`, and they are recovered from differently - and message text is not something to match
+    on, since it varies by ORM, database and server version.
+  
+    Undefined when the server sent no `type`, which is every pre-3.0 Breeze server and most
+    non-Breeze ones. See {@link ProblemTypes} and {@link isConcurrencyError}. */
+    problemType?: string;
+}
+/** The RFC 9457 `type` URIs a Breeze server sends on {@link ServerError.problemType}.
+
+A problem type is a stable identifier for a *kind* of failure, which is what a status code often
+is not: `409` covers both a concurrency conflict and a duplicate key, and the two call for
+different recovery. */
+export declare const ProblemTypes: {
+    /** A row was changed or deleted by someone else after this client read it. */
+    readonly concurrencyConflict: "https://breeze.github.io/problems/concurrency-conflict";
+    /** The save was rejected by validation; see `entityErrors`. */
+    readonly entityErrors: "https://breeze.github.io/problems/entity-errors";
+    /** An unhandled exception on the server. */
+    readonly serverError: "https://breeze.github.io/problems/server-error";
+};
+/** Whether an error is an optimistic concurrency conflict - a row changed or deleted by someone
+else after this client read it.
+
+```ts
+try {
+  await em.saveChanges();
+} catch (e) {
+  if (isConcurrencyError(e)) {
+    // re-read and let the user decide; retrying the same save would fail the same way
+  }
+}
+```
+
+This is exact rather than approximate: it is true only when the server said so with
+{@link ProblemTypes.concurrencyConflict}, never inferred from the status code or the message. A
+`409` from a duplicate key is not a concurrency conflict, and matching on message text breaks
+when the ORM, database or server version changes.
+
+A Breeze .NET server sends this for EF Core's `DbUpdateConcurrencyException` and NHibernate's
+`StaleObjectStateException`. A server that does not send a `type` - any pre-3.0 Breeze server, and
+most non-Breeze ones - returns false here, and there is nothing reliable to use instead.
+
+When the conflict names the rows involved, they are on `entityErrors` with the entities attached:
+
+```ts
+const stale = (e.entityErrors ?? [])
+  .filter(ee => ee.errorName === "ConcurrencyError")
+  .map(ee => ee.entity);
+```
+@param error The rejection value from a Breeze call - typically a {@link SaveError}.
+@returns true if the server identified this as a concurrency conflict. */
+export declare function isConcurrencyError(error: any): boolean;
+/** Shape of a save error when returned to the client. */
+export interface SaveError extends ServerError {
+    /** The errors the server reported on particular entities. Undefined when it named none - after a
+    network failure or a server exception, say - which is how to tell a rejected save from those.
+    Breeze also adds each one to its entity's validation errors.
+  
+    When client-side validation stops a save before it is sent, the rejection is a plain `Error` with
+    `entityErrors` built from the entities' validation errors, and no HTTP members. */
+    entityErrors?: EntityError[];
+}
+/** Shape of an error on a specific entity.  Part of a {@link SaveError} */
+export interface EntityError {
+    /** The entity the error is about. `null` when the server named an entity that is not in this
+    manager's cache. */
+    entity: Entity | null;
+    /** What kind of error this is. From the server, the name it gave the error, such as
+    `"ConcurrencyError"`; from client-side validation, the validator's name, or the error's key if it
+    was added without a validator. */
+    errorName: string;
+    /** The error message. */
+    errorMessage: string;
+    /** The client-side name of the property the error is about; empty or null when it is about the
+    whole entity. */
+    propertyName: string;
+    /** `true` for an error the server reported, `false` for one from client-side validation. */
+    isServerError: boolean;
+    /** Whatever extra information the server attached to the error. Undefined for client-side
+    errors. */
+    custom?: any;
+}
+/**
+ * Anything the type-taking APIs accept in place of an {@link EntityType}: the type itself, its
+ * name, or a constructor registered for it with {@link MetadataStore.registerEntityTypeCtor}.
+ */
+export type EntityTypeArg = EntityType | string | (new () => Entity);
+/** What {@link EntityManager.exportEntities} exports: particular entities, or every entity of the
+given types - as registered classes, {@link EntityType}s or type names. */
+export type ExportEntitiesArg = Entity[] | (new () => Entity)[] | EntityType[] | string[];
+/**
+The values {@link EntityManager.createEntity} can be given for an entity of class `T`: any of its
+data and navigation properties, each optional.
+
+- A collection navigation property takes a plain array of entities, and a complex property a plain
+  object of its own values - both are what `createEntity` accepts at runtime.
+- The members every entity has - `entityAspect`, `entityType`, `getProperty`, `setProperty` - are
+  not initial values, and passing one fails inside Breeze. Methods are left out too.
+
+A property the class does not declare is a compile error, which is the point: at runtime
+`createEntity` ignores it without a word, so a misspelt or server-cased name (`ShipName` for
+`shipName`) would otherwise create the entity without it.
+
+Only the constructor overload is checked. Pass the type's name or its `EntityType` to create one
+from values the compiler cannot see.
+*/
+export type InitialValues<T> = {
+    [K in keyof T as K extends keyof Entity | keyof ComplexObject ? never : T[K] extends Function ? never : K]?: T[K] extends RelationArray<infer U> ? U[] | T[K] : T[K] extends ReadonlyArray<infer U> ? (U extends ComplexObject ? InitialValues<U> | U : U)[] | T[K] : T[K] extends ComplexObject ? InitialValues<T[K]> | T[K] : T[K];
+};
+/** What an {@link EntityManager.executeQuery} call resolves with - as do `EntityQuery.execute` and
+`RelationArray.load`. `T` is what the query was built for: `EntityQuery.from(Customer)` gives a
+`QueryResult<Customer>`, whose `results` is `Customer[]`. It defaults to `any`. */
+export interface QueryResult<T = any> {
+    /** Top level entities returned.  Excludes entities that are Deleted. */
+    results: T[];
+    /** Query that was executed */
+    query: EntityQuery | string;
+    /** EntityManager that executed the query */
+    entityManager?: EntityManager;
+    /** Total number of results available on the server */
+    inlineCount?: number;
+    /** All entities returned by the query.  Differs from `results` when an expand is used.  Includes entities that are Deleted. */
+    retrievedEntities?: Entity[];
+    /** Raw response from the server */
+    httpResponse?: HttpResponse;
+}
+/** The success callback accepted by the deprecated callback form of {@link EntityManager.executeQuery}.
+@deprecated Await the returned promise instead of passing callbacks. */
+export interface QuerySuccessCallback {
+    (data: QueryResult): void;
+}
+/** The failure callback accepted by the deprecated callback form of {@link EntityManager.executeQuery}.
+@deprecated Await the returned promise instead of passing callbacks. */
+export interface QueryErrorCallback {
+    (error: {
+        query: EntityQuery;
+        httpResponse: HttpResponse;
+        entityManager: EntityManager;
+        message?: string;
+        stack?: string;
+    }): void;
+}
+/** Key mapping information returned as part of an {@link SaveResult}. */
+export interface KeyMapping {
+    /** The qualified name of the entity's type, such as `"Order:#Northwind.Models"`. */
+    entityTypeName: string;
+    /** The temporary key value the entity had on the client. */
+    tempValue: any;
+    /** The permanent key value the server assigned. */
+    realValue: any;
+}
+/** Maps each temporary key in a bundle imported by {@link EntityManager.importEntities} to the
+temporary key its entity was given in the importing manager. Returned as
+{@link ImportResult.tempKeyMapping}.
+
+Each property name is an old key in its {@link EntityKey.toString} form - the entity type's
+qualified name, a hyphen and the key value, such as `"Order:#Northwind.Models--1"` for the key
+`-1` - and its value is the new {@link EntityKey}. Both are temporary: the entity is still unsaved,
+and gets its permanent key when it is saved. The new key keeps the old value unless this manager's
+{@link KeyGenerator} has already handed that value out.
+
+With {@link ImportConfig.mergeAdds} set, imported entities keep their old keys and this map does not
+describe them. */
+export interface ITempKeyMap {
+    [index: string]: EntityKey;
+}
+/** Configuration info to be passed to the {@link EntityManager.importEntities} method */
+export interface ImportConfig {
+    /** If true, merge Added entities (with temp keys) as well.  This can be dangerous. */
+    mergeAdds?: boolean;
+    /** How to merge an imported entity into one with the same key already in this manager. Defaults
+    to the manager's `queryOptions.mergeStrategy`. With {@link MergeStrategy.Disallowed} the import
+    throws on such an entity. Added entities with temporary keys are never merged unless `mergeAdds`
+    is set. */
+    mergeStrategy?: MergeStrategy;
+    /** Called before anything is imported when the bundle was exported without metadata, with the
+    `MetadataStore.metadataVersion` of the Breeze that exported it and the name of the exporting
+    manager's `MetadataStore`. Throw from it to stop the import if the bundle does not match this
+    manager's metadata. Not called when the bundle includes metadata. */
+    metadataVersionFn?: (arg: {
+        metadataVersion: any;
+        metadataStoreName: any;
+    }) => void;
+}
+/** The shape of the Promise returned by an {@link EntityManager.saveChanges} call. */
+export interface SaveResult {
+    /** The entities the server returned for the save, as merged into this manager's cache. Empty
+    when there was nothing to save. */
+    entities: Entity[];
+    /** For each entity saved with a temporary key, the permanent key the server assigned. Breeze has
+    already applied them - to the entities and to the foreign keys that pointed at them - by the time
+    the save resolves. */
+    keyMappings: KeyMapping[];
+    /** The entities the server reports it deleted during the save, by type name and key values. This
+    can include entities the client did not send, such as ones deleted by server-side logic. Breeze
+    detaches any of them that are in the cache. */
+    deletedKeys?: {
+        /** The name of the deleted entity's type, as the server sent it. */
+        entityTypeName: string;
+        /** The deleted entity's key values, one per key property. */
+        keyValues: any[];
+    }[];
+    /** The raw response to the save request. Undefined when there was nothing to save, and so no
+    request. */
+    httpResponse?: HttpResponse;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link DataServiceAdapter} implementation.
+@adapter (see {@link DataServiceAdapter})
+@hidden
+*/
+export interface SaveContext {
+    entityManager: EntityManager;
+    dataService: DataService;
+    processSavedEntities: (saveResult: SaveResult) => Entity[];
+    resourceName: string;
+    adapter?: DataServiceAdapter;
+    routePrefix?: string;
+}
+/** For use by breeze plugin authors only. The class is for use in building a {@link DataServiceAdapter} implementation.
+@adapter (see {@link DataServiceAdapter})
+@hidden
+*/
+export interface SaveBundle {
+    entities: Entity[];
+    saveOptions: SaveOptions;
+}
+/** Configuration info to be passed to the {@link EntityManager} constructor */
+export interface EntityManagerConfig {
+    /** The service name associated with this EntityManager.  */
+    serviceName?: string;
+    /** The DataService associated with this EntityManager. */
+    dataService?: DataService;
+    /** The {@link QueryOptions} associated with this EntityManager.  */
+    queryOptions?: QueryOptions;
+    /** The {@link SaveOptions} associated with this EntityManager. */
+    saveOptions?: SaveOptions;
+    /** The {@link ValidationOptions} associated with this EntityManager.  */
+    validationOptions?: ValidationOptions;
+    /** The {@link KeyGenerator} constructor associated with this EntityManager. The manager creates its own
+    instance, and a new one whenever it is cleared, so a generator cannot be passed in as an instance. */
+    keyGeneratorCtor?: {
+        new (): KeyGenerator;
+    };
+    /** The {@link MetadataStore} associated with this EntityManager. */
+    metadataStore?: MetadataStore;
+}
+/** The shape returned by callbacks registered with {@link EntityManager.entityChanged} event */
+export interface EntityChangedEventArgs {
+    /** What happened - see {@link EntityAction}. */
+    entityAction: EntityAction;
+    /** The entity the action happened to. Undefined for {@link EntityAction.Clear}, which affects every
+    entity in the manager. */
+    entity?: Entity;
+    /** Set only for {@link EntityAction.PropertyChange}: the same {@link PropertyChangedEventArgs} the
+    entity's `propertyChanged` event receives. Undefined for every other action. */
+    args?: PropertyChangedEventArgs;
+}
+/** The argument to the `validationErrorsChanged` event of an {@link EntityManager} and of an
+{@link EntityAspect}. Raised once per operation - a validation, or a call that adds, removes or
+clears errors - that added or removed at least one error. */
+export interface ValidationErrorsChangedEventArgs {
+    /** The entity whose validation errors changed. */
+    entity: Entity;
+    /** The errors the operation added. An error found again when the entity is re-validated appears
+    here again, replacing the one with the same key. */
+    added: ValidationError[];
+    /** The errors the operation removed: ones that no longer fail validation, and ones removed with
+    {@link EntityAspect.removeValidationError} or {@link EntityAspect.clearValidationErrors}. */
+    removed: ValidationError[];
+}
+/** The argument to the {@link EntityManager.hasChangesChanged} event. */
+export interface HasChangesChangedEventArgs {
+    /** The manager whose `hasChanges` state changed. */
+    entityManager: EntityManager;
+    /** Whether the manager now has changes - see {@link EntityManager.hasChanges}. */
+    hasChanges: boolean;
+}
+/**
+Instances of the EntityManager contain and manage collections of entities, either retrieved from a backend datastore or created on the client.
+*/
+export declare class EntityManager {
+    /** The service name associated with this EntityManager. __Read Only__ */
+    serviceName: string;
+    /** The DataService associated with this EntityManager. __Read Only__ */
+    dataService: DataService;
+    /** The {@link QueryOptions} associated with this EntityManager. __Read Only__ */
+    queryOptions: QueryOptions;
+    /** The {@link SaveOptions} associated with this EntityManager. __Read Only__ */
+    saveOptions: SaveOptions;
+    /** The {@link ValidationOptions} associated with this EntityManager. __Read Only__ */
+    validationOptions: ValidationOptions;
+    /** The {@link KeyGenerator} associated with this EntityManager. __Read Only__ */
+    keyGenerator: KeyGenerator;
+    /** The {@link KeyGenerator} constructor associated with this EntityManager. __Read Only__ */
+    keyGeneratorCtor: {
+        new (): KeyGenerator;
+    };
+    /** The {@link MetadataStore} associated with this EntityManager. __Read Only__ */
+    metadataStore: MetadataStore;
+    /** True while Breeze is loading entities into this manager - merging query or save results, or
+    attaching or creating entities. While it is set, property changes do not mark entities Modified,
+    are not validated, and raise no property-change events. Used by Breeze; applications do not
+    normally need it. */
+    isLoading: boolean;
+    /** True while {@link EntityAspect.rejectChanges} restores an entity's original values, so that
+    restoring them raises no property-change events. Used by Breeze; applications do not normally need
+    it. */
+    isRejectingChanges: boolean;
+    /**
+    A {@link BreezeEvent} that fires whenever a change to any entity in this EntityManager occurs. __Read Only__
+  
+    @eventArgs -
+    - entityAction - The {@link EntityAction} that occured.
+    - entity - The entity that changed. Undefined for {@link EntityAction.Clear}, which affects every entity in the manager.
+    - args - Additional information about this event. This will differ based on the entityAction.
+  
+    ```ts
+    const em = new EntityManager({ serviceName: "breeze/NorthwindIBModel" });
+    em.entityChanged.subscribe(changeArgs => {
+        // This code will be executed any time any entity within the entityManager
+        // is added, modified, deleted or detached for any reason.
+        const action = changeArgs.entityAction;
+        const entity = changeArgs.entity;
+        // .. do something to this entity when it is changed.
+    });
+    ```
+    @event
+    */
+    entityChanged: BreezeEvent<EntityChangedEventArgs>;
+    /**
+    An {@link BreezeEvent} that fires whenever validationErrors change for any entity in this EntityManager. __Read Only__
+    @eventArgs -
+      - entity - The entity on which the validation errors have been added or removed.
+      - added - An array containing any newly added {@link ValidationError}s
+      - removed - An array containing any newly removed {@link ValidationError}s. This is those errors that have been 'fixed'
+  
+    ```ts
+    const em = new EntityManager({ serviceName: "breeze/NorthwindIBModel" });
+    em.validationErrorsChanged.subscribe(changeArgs => {
+        // This code will be executed any time any entity within the entityManager
+        // experiences a change to its validationErrors collection.
+        const entity = changeArgs.entity;
+        const errorsAdded = changeArgs.added;
+        const errorsCleared = changeArgs.removed;
+        // ... do something interesting with the entity.
+    });
+    ```
+    @event
+    */
+    validationErrorsChanged: BreezeEvent<ValidationErrorsChangedEventArgs>;
+    /**
+    A {@link BreezeEvent} that fires whenever an EntityManager transitions to or from having changes. __Read Only__
+    @eventArgs -
+      - entityManager - The EntityManager whose 'hasChanges' status has changed.
+      - hasChanges - Whether or not this EntityManager has changes.
+  
+    ```ts
+    const em = new EntityManager({ serviceName: "breeze/NorthwindIBModel" });
+    em.hasChangesChanged.subscribe(args => {
+        const hasChanges = args.hasChanges;
+        const entityManager = args.entityManager;
+    });
+    ```
+    @event
+    */
+    hasChangesChanged: BreezeEvent<HasChangesChangedEventArgs>;
+    /** Functions a {@link DataServiceAdapter} uses to build the save request: `unwrapInstance` turns an
+    entity or complex object into a plain object with server property names, `unwrapOriginalValues`
+    does the same for its original values, and `unwrapChangedValues` for the current values of its
+    changed properties. For adapter authors; applications do not normally need it. */
+    helper: {
+        /** Turns an entity or complex object into a plain object keyed by server property names. */
+        unwrapInstance: typeof unwrapInstance;
+        /** The same, for the original values of an entity's changed properties. */
+        unwrapOriginalValues: typeof unwrapOriginalValues;
+        /** The same, for the current values of an entity's changed properties. */
+        unwrapChangedValues: typeof unwrapChangedValues;
+    };
+    /**
+    EntityManager constructor.
+  
+    At its most basic an EntityManager can be constructed with just a service name
+    ```ts
+    const entityManager = new EntityManager("breeze/NorthwindIBModel");
+    ```
+  
+    This is the same as calling it with the following configuration object
+    ```ts
+    const entityManager = new EntityManager({ serviceName: "breeze/NorthwindIBModel" });
+    ```
+  
+    Usually however, configuration objects will contain more than just the 'serviceName';
+    ```ts
+    const metadataStore = new MetadataStore();
+    const entityManager = new EntityManager({
+      serviceName: "breeze/NorthwindIBModel",
+      metadataStore: metadataStore
+    });
+    ```
+  
+    or
+    ```ts
+    const queryOptions = new QueryOptions({
+        mergeStrategy: MergeStrategy.OverwriteChanges,
+        fetchStrategy: FetchStrategy.FromServer
+    });
+    const validationOptions = new ValidationOptions({
+        validateOnAttach: true,
+        validateOnSave: true,
+        validateOnQuery: false
+    });
+    const entityManager = new EntityManager({
+        serviceName: "breeze/NorthwindIBModel",
+        queryOptions: queryOptions,
+        validationOptions: validationOptions
+    });
+    ```
+    @param emConfig - Configuration settings or a service name.
+    */
+    constructor(emConfig?: EntityManagerConfig | string);
+    /**
+    General purpose property set method.  Any of the properties in the {@link EntityManagerConfig}
+    may be set.
+    ```ts
+    // assume em1 is a previously created EntityManager
+    // where we want to change some of its settings.
+    em1.setProperties( {
+        serviceName: "breeze/foo"
+    });
+    ```
+    @param config - An object containing the selected properties and values to set.
+    */
+    setProperties(config: EntityManagerConfig): void;
+    createEntity<T extends Entity>(entityCtor: new () => T, initialValues?: InitialValues<T>, entityState?: EntityState, mergeStrategy?: MergeStrategy): T;
+    createEntity(typeName: string, initialValues?: Object, entityState?: EntityState, mergeStrategy?: MergeStrategy): Entity;
+    createEntity(entityType: EntityType, initialValues?: Object, entityState?: EntityState, mergeStrategy?: MergeStrategy): Entity;
+    static importEntities(exportedString: string, config?: ImportConfig): EntityManager;
+    static importEntities(exportedData: Object, config?: ImportConfig): EntityManager;
+    /**
+    Calls {@link EntityAspect.acceptChanges} on every changed entity in this EntityManager.
+    */
+    acceptChanges(): void;
+    exportEntities(entities?: ExportEntitiesArg, exportConfig?: {
+        asString?: true;
+        includeMetadata?: boolean;
+    } | boolean): string;
+    exportEntities(entities: ExportEntitiesArg | undefined, exportConfig: {
+        asString: false;
+        includeMetadata?: boolean;
+    }): Object;
+    exportEntities(entities?: ExportEntitiesArg, exportConfig?: {
+        asString?: boolean;
+        includeMetadata?: boolean;
+    } | boolean): string | Object;
+    importEntities(exportedString: string, config?: ImportConfig): ImportResult;
+    importEntities(exportedData: Object, config?: ImportConfig): ImportResult;
+    /**
+    Clears this EntityManager's cache but keeps all other settings. Note that this
+    method is not as fast as creating a new EntityManager via 'new EntityManager'.
+    This is because clear actually detaches all of the entities from the EntityManager.
+    ```ts
+    // assume em1 is an EntityManager containing a number of existing entities.
+    em1.clear();
+    // em1 is will now contain no entities, but all other setting will be maintained.
+    ```
+    */
+    clear(): void;
+    /**
+    Creates an empty copy of this EntityManager but with the same DataService, MetadataStore, QueryOptions, SaveOptions, ValidationOptions, etc.
+    ```ts
+    // assume em1 is an EntityManager containing a number of existing entities.
+    const em2 = em1.createEmptyCopy();
+    // em2 is a new EntityManager with all of em1's settings
+    // but no entities.
+    ```
+    @returns A new EntityManager.
+    */
+    createEmptyCopy(): EntityManager;
+    /**
+    Attaches an entity to this EntityManager with an  {@link EntityState} of 'Added'.
+    ```ts
+    // assume em1 is an EntityManager containing a number of existing entities.
+    const cust1 = em1.createEntity(Customer, { companyName: "Acme" }, EntityState.Detached);
+    em1.addEntity(cust1);     // returns cust1, a Customer
+    ```
+  
+    Note that this is the same as using 'attachEntity' with an {@link EntityState} of 'Added'.
+  
+    ```ts
+    // assume em1 is an EntityManager containing a number of existing entities.
+    const cust1 = em1.createEntity(Customer, { companyName: "Acme" }, EntityState.Detached);
+    em1.attachEntity(cust1, EntityState.Added);
+    ```
+    @param entity - The entity to add.
+    @returns The added entity.
+    */
+    addEntity<T extends Entity>(entity: T): T;
+    /**
+    Attaches an entity to this EntityManager with a specified {@link EntityState}.
+    ```ts
+    // assume em1 is an EntityManager containing a number of existing entities.
+    const cust1 = em1.createEntity(Customer, { companyName: "Acme" }, EntityState.Detached);
+    em1.attachEntity(cust1, EntityState.Added);     // returns cust1, a Customer
+    ```
+    @param entity - The entity to add.
+    @param entityState - (default=EntityState.Unchanged) The EntityState of the newly attached entity. If omitted this defaults to EntityState.Unchanged.
+    @param mergeStrategy - (default = MergeStrategy.Disallowed) How the specified entity should be merged into the EntityManager if this EntityManager already contains an entity with the same key.
+    @returns The attached entity.
+    */
+    attachEntity<T extends Entity>(entity: T, entityState?: EntityState, mergeStrategy?: MergeStrategy): T;
+    /**
+    Detaches an entity from this EntityManager.
+    ```ts
+    // assume em1 is an EntityManager containing a number of existing entities.
+    // assume cust1 is a customer Entity previously attached to em1
+    em1.detachEntity(cust1);
+    // em1 will now no longer contain cust1 and cust1 will have an
+    // entityAspect.entityState of EntityState.Detached
+    ```
+    @param entity - The entity to detach.
+    @returns Whether the entity could be detached. This will return false if the entity is already detached or was never attached.
+    */
+    detachEntity(entity: Entity): any;
+    fetchMetadata(dataService?: DataService): Promise<any>;
+    /** @deprecated Await the returned promise instead of passing callbacks. */
+    fetchMetadata(dataService: DataService | undefined, callback?: Callback, errorCallback?: ErrorCallback): Promise<any>;
+    executeQuery<T>(query: EntityQuery<T>): Promise<QueryResult<T>>;
+    executeQuery(query: string): Promise<QueryResult>;
+    /** @deprecated Await the returned promise instead of passing callbacks. */
+    executeQuery<T>(query: EntityQuery<T>, callback?: QuerySuccessCallback, errorCallback?: QueryErrorCallback): Promise<QueryResult<T>>;
+    /** @deprecated Await the returned promise instead of passing callbacks. */
+    executeQuery(query: string, callback?: QuerySuccessCallback, errorCallback?: QueryErrorCallback): Promise<QueryResult>;
+    /**
+    Executes the specified query against this EntityManager's local cache.
+  
+    Because this method is executed immediately there is no need for a promise or a callback
+    ```ts
+    const em = new EntityManager(serviceName);
+    const query = EntityQuery.from(Order);
+    const orders = em.executeQueryLocally(query);   // Order[]
+    ```
+  
+    Note that this can also be accomplished using the 'executeQuery' method with
+    a FetchStrategy of FromLocalCache and making use of the Promise or callback
+    ```ts
+    const em = new EntityManager(serviceName);
+    const query = EntityQuery.from(Order).using(FetchStrategy.FromLocalCache);
+    const data = await em.executeQuery(query);
+    const orders = data.results;   // Order[]
+    ```
+    @param query - The {@link EntityQuery} to execute.
+    @returns  {Array of Entity}  Array of entities from cache that satisfy the query
+    */
+    executeQueryLocally<T>(query: EntityQuery<T>): T[];
+    saveChanges(entities?: Entity[] | null, saveOptions?: SaveOptions): Promise<SaveResult>;
+    /** @deprecated Await the returned promise instead of passing callbacks. */
+    saveChanges(entities: Entity[] | null | undefined, saveOptions: SaveOptions | undefined, callback?: Function, errorCallback?: Function): Promise<SaveResult>;
+    /**
+    Run the "saveChanges" pre-save client validation logic.
+    
+    This is NOT a general purpose validation method.
+    It is intended for utilities that must know if saveChanges
+    would reject the save due to client validation errors.
+    
+    It only validates entities if the EntityManager's
+    {@link ValidationOptions}.validateOnSave is true.
+    
+    @param entitiesToSave {Array of Entity} The list of entities to save (to validate).
+    @returns {Error} Validation error or null if no error
+    */
+    saveChangesValidateOnClient(entitiesToSave: Entity[]): Error | null;
+    /**
+    The check {@link EntityManager.saveChangesValidateOnClient} makes, with async validators run too:
+    each entity is validated with {@link EntityAspect.validateEntityAsync}. `saveChanges` uses this
+    in its place when any of the entities it saves has an async validator.
+    @param entitiesToSave - The entities to validate.
+    @returns A promise of the error `saveChanges` would reject with, or null.
+    */
+    saveChangesValidateOnClientAsync(entitiesToSave: Entity[]): Promise<Error | null>;
+    /**
+    Returns the entity in this manager's cache with this key, or `null` if there is none. It does
+    not query the server; see {@link EntityManager.fetchEntityByKey} for that. Given the constructor of a class registered with the
+    {@link MetadataStore}, the result has that class's type.
+    ```ts
+    // assume em1 is an EntityManager containing a number of preexisting entities,
+    // and that Employee is registered with its MetadataStore.
+    const employee = em1.getEntityByKey(Employee, 1);   // Employee | null
+    ```
+    A key of more than one property is clearest given by name - see {@link KeyValues}:
+    ```ts
+    const detail = em1.getEntityByKey(OrderDetail, { orderID: 10248, productID: 11 });
+    ```
+    */
+    getEntityByKey<T extends Entity>(entityCtor: new () => T, keyValues: KeyValues<T> | KeyValue | any[]): T | null;
+    /**
+    Returns the entity in this manager's cache with this key, or `null` if there is none. It does
+    not query the server; see {@link EntityManager.fetchEntityByKey} for that.
+    ```ts
+    // assume em1 is an EntityManager containing a number of preexisting entities.
+    const employeeType = em1.metadataStore.getAsEntityType("Employee");
+    const employeeKey = new EntityKey(employeeType, 1);
+    const employee = em1.getEntityByKey(employeeKey);
+    // employee will either be an entity or null.
+    ```
+    */
+    getEntityByKey(entityKey: EntityKey): Entity | null;
+    /**
+    Returns the entity in this manager's cache with this key, or `null` if there is none. It does
+    not query the server; see {@link EntityManager.fetchEntityByKey} for that.
+    ```ts
+    // assume em1 is an EntityManager containing a number of preexisting entities.
+    const employee = em1.getEntityByKey("Employee", 1);
+    // employee will either be an entity or null.
+    ```
+    */
+    getEntityByKey(typeName: string, keyValues: any | any[]): Entity | null;
+    /**
+    Returns the entity in this manager's cache with this key, or `null` if there is none. It does
+    not query the server; see {@link EntityManager.fetchEntityByKey} for that.
+    ```ts
+    // assume em1 is an EntityManager containing a number of preexisting entities.
+    const employeeType = em1.metadataStore.getAsEntityType("Employee");
+    const employee = em1.getEntityByKey(employeeType, 1);
+    // employee will either be an entity or null.
+    ```
+    */
+    getEntityByKey(type: EntityType, keyValues: any | any[]): Entity | null;
+    fetchEntityByKey<T extends Entity>(entityCtor: new () => T, keyValues: KeyValues<T> | KeyValue | any[], checkLocalCacheFirst?: boolean): Promise<EntityByKeyResult<T>>;
+    fetchEntityByKey(typeName: string, keyValues: any | any[], checkLocalCacheFirst?: boolean): Promise<IEntityByKeyResult>;
+    fetchEntityByKey(entityType: EntityType, keyValues: any | any[], checkLocalCacheFirst?: boolean): Promise<IEntityByKeyResult>;
+    fetchEntityByKey(entityKey: EntityKey, checkLocalCacheFirst?: boolean): Promise<IEntityByKeyResult>;
+    /**
+    [Deprecated] - Attempts to locate an entity within this EntityManager by its  {@link EntityKey}.
+    ```ts
+    // assume em1 is an EntityManager containing a number of preexisting entities.
+    const employeeType = em1.metadataStore.getAsEntityType("Employee");
+    const employeeKey = new EntityKey(employeeType, 1);
+    const employee = em1.findEntityByKey(employeeKey);
+    // employee will either be an entity or null.
+    ```
+    @deprecated    Use getEntityByKey instead
+    @param entityKey - The  {@link EntityKey} of the Entity to be located.
+    @returns An Entity or null;
+    */
+    findEntityByKey(entityKey: EntityKey): Entity | null;
+    /**
+    Generates a temporary key for the specified entity.  This is used to insure that newly
+    created entities have unique keys and to register that these keys are temporary and
+    need to be automatically replaced with 'real' key values once these entities are saved.
+    
+    The {@link EntityManager.keyGeneratorCtor} property is used internally by this method to actually generate
+    the keys - See the  KeyGenerator interface interface description to see
+    how a custom key generator can be plugged in.
+    ```ts
+    // assume em1 is an EntityManager containing a number of preexisting entities.
+    const customer = em1.createEntity(Customer, { companyName: "Acme" }, EntityState.Detached);
+    const customerId = em1.generateTempKeyValue(customer);
+    // customer.customerID is now set to a newly generated unique id value.
+    // This property will change again after a successful save of the customer.
+    em1.addEntity(customer);
+    await em1.saveChanges();
+    // customer.customerID !== customerId, because the server will have generated
+    // a new id and the client will have been updated with this new id.
+    ```
+    @param entity - The Entity to generate a key for.
+    @returns The new key value
+    */
+    generateTempKeyValue(entity: Entity): any;
+    hasChanges<T extends Entity>(entityCtor: new () => T): boolean;
+    hasChanges(entityCtors: (new () => Entity)[]): boolean;
+    hasChanges(): boolean;
+    hasChanges(entityTypeNames: string | string[]): boolean;
+    hasChanges(entityTypes: EntityType | EntityType[]): boolean;
+    getChanges<T extends Entity>(entityCtor: new () => T): T[];
+    /** Several types at once: `getChanges([Customer, Order])` is `(Customer | Order)[]`. */
+    getChanges<C extends (new () => Entity)[]>(entityCtors: [...C]): InstanceType<C[number]>[];
+    getChanges(): Entity[];
+    getChanges(entityTypeNames: string | string[]): Entity[];
+    getChanges(entityTypes: EntityType | EntityType[]): Entity[];
+    /**
+    Rejects (reverses the effects) all of the additions, modifications and deletes from this EntityManager.
+    Calls {@link EntityAspect.rejectChanges} on every changed entity in this EntityManager.
+    ```ts
+    // assume em1 is an EntityManager containing a number of preexisting entities.
+    const entities = em1.rejectChanges();
+    ```
+    @returns The entities whose changes were rejected. These entities will all have EntityStates of
+    either 'Unchanged' or 'Detached'
+    */
+    rejectChanges(): Entity[];
+    getEntities<T extends Entity>(entityCtor: new () => T, entityStates?: EntityState | EntityState[]): T[];
+    /** Several types at once: `getEntities([Customer, Order])` is `(Customer | Order)[]`. */
+    getEntities<C extends (new () => Entity)[]>(entityCtors: [...C], entityStates?: EntityState | EntityState[]): InstanceType<C[number]>[];
+    getEntities(entityTypeNames?: string | string[], entityStates?: EntityState | EntityState[]): Entity[];
+    getEntities(entityTypes?: EntityType | EntityType[], entityStates?: EntityState | EntityState[]): Entity[];
+}
+/** What an {@link EntityManager.fetchEntityByKey} call resolves with. */
+export interface IEntityByKeyResult {
+    /** The entity, or `null` if there is none.
+  
+    `null` rather than `undefined`, because that is what absence means everywhere else in Breeze:
+    a scalar navigation property with nothing cached is `null`, a nullable data property is `null`,
+    and {@link EntityManager.getEntityByKey} returns `null`. Before 3.0 this one property was the
+    exception. See UPGRADE.md. */
+    entity: Entity | null;
+    /** The key that was looked up. */
+    entityKey: EntityKey;
+    /** True if the answer came from the local cache, which is only checked when `checkLocalCacheFirst`
+    is true; false if the server was queried. It can be true with a null `entity`: the cached entity is
+    Deleted, and the manager's `queryOptions` exclude deleted entities and do not use
+    {@link MergeStrategy.OverwriteChanges}. */
+    fromCache: boolean;
+}
+/** {@link IEntityByKeyResult} for a known entity type - what the constructor overload of
+{@link EntityManager.fetchEntityByKey} returns. */
+export interface EntityByKeyResult<T extends Entity> extends IEntityByKeyResult {
+    entity: T | null;
+}
+/** A single key value: what a one-property key's value can be. */
+type KeyValue = string | number | boolean | Date;
+declare function unwrapInstance(structObj: StructuralObject, transformFn?: (dp: DataProperty, val: any) => any): any;
+declare function unwrapOriginalValues(target: StructuralObject, metadataStore: MetadataStore, transformFn?: (dp: DataProperty, val: any) => any): Record<string, any>;
+declare function unwrapChangedValues(entity: Entity, metadataStore: MetadataStore, transformFn: (dp: DataProperty, val: any) => any): Record<string, any>;
+export {};