breeze-client 2.2.2 → 3.0.0

package/metadata/data-service.js

@@ -0,0 +1,246 @@
+import { assertConfig } from '../core/assert-param.js';
+import { config } from '../config/config.js';
+import { core, stringEndsWith } from '../core/core.js';
+/**
+A DataService instance is used to encapsulate the details of a single 'service'; this includes a serviceName, a dataService adapterInstance,
+and whether the service has server side metadata.
+
+You can construct an EntityManager with either a serviceName or a DataService instance, if you use a serviceName then a DataService
+is constructed for you.  (It can also be set via the EntityManager.setProperties method).
+
+The same applies to the MetadataStore.fetchMetadata method, i.e. it takes either a serviceName or a DataService instance.
+
+Each metadataStore contains a list of DataServices, each accessible via its ‘serviceName’.
+( see MetadataStore.getDataService and MetadataStore.addDataService).  The ‘addDataService’ method is called internally
+anytime a MetadataStore.fetchMetadata call occurs with a new dataService ( or service name).
+
+*/
+export class DataService {
+    /**   DataService constructor
+    ```ts
+    var dataService = new DataService({
+        serviceName: altServiceName,
+        hasServerMetadata: false
+    });
+    ```
+  
+    ```ts
+    var metadataStore = new MetadataStore({
+        namingConvention: NamingConvention.camelCase
+    });
+    ```
+  
+    ```ts
+    return new EntityManager({
+        dataService: dataService,
+        metadataStore: metadataStore
+    });
+    ```
+    @param config - A configuration object.
+    */
+    constructor(config) {
+        updateWithConfig(this, config);
+    }
+    /**
+    Returns a copy of this DataService with the specified properties applied.
+    @param config - The configuration object to apply to create a new DataService.
+    */
+    using(config) {
+        if (!config)
+            return this;
+        let result = new DataService(this);
+        return updateWithConfig(result, config);
+    }
+    /**
+    Combines several DataServices into one, taking each property from the first of them that has it
+    set, and filling in the adapters: the named ones, or the defaults. Breeze uses it to combine a
+    query's or save's own DataService with the EntityManager's before each request; applications do
+    not normally need it.
+    @param dataServices - The DataServices to combine, most specific first. Entries may be null or
+    undefined. The array is modified.
+    @throws if none of them has a `serviceName`.
+    */
+    static resolve(dataServices) {
+        // final defaults
+        // Deliberate use of 'as any' below.
+        dataServices.push({
+            hasServerMetadata: true,
+            useJsonp: false
+        });
+        let ds = new DataService(core.resolveProperties(dataServices, ["serviceName", "adapterName", "uriBuilderName", "hasServerMetadata", "jsonResultsAdapter", "useJsonp"]));
+        if (!ds.serviceName) {
+            throw new Error("Unable to resolve a 'serviceName' for this dataService");
+        }
+        ds.adapterInstance = ds.adapterInstance || config.getAdapterInstance("dataService", ds.adapterName);
+        ds.jsonResultsAdapter = ds.jsonResultsAdapter || ds.adapterInstance.jsonResultsAdapter;
+        ds.uriBuilder = ds.uriBuilder || config.getAdapterInstance("uriBuilder", ds.uriBuilderName);
+        return ds;
+    }
+    /** @hidden @internal */
+    static _normalizeServiceName(serviceName) {
+        serviceName = serviceName.trim();
+        if (serviceName.substr(-1) !== "/") {
+            return serviceName + '/';
+        }
+        else {
+            return serviceName;
+        }
+    }
+    /**
+    Returns the serializable form of this DataService: `serviceName`, `adapterName`,
+    `uriBuilderName`, `hasServerMetadata`, `useJsonp` and the `name` of its `jsonResultsAdapter`,
+    leaving out any that are not set. `JSON.stringify` calls it when `MetadataStore.exportMetadata`
+    and `EntityManager.exportEntities` serialize their DataServices; {@link DataService.fromJSON}
+    reads it back.
+    */
+    toJSON() {
+        // don't use default value here - because we want to be able to distinguish undefined props for inheritence purposes.
+        return core.toJson(this, {
+            serviceName: null,
+            adapterName: null,
+            uriBuilderName: null,
+            hasServerMetadata: null,
+            jsonResultsAdapter: function (v) {
+                return v && v.name;
+            },
+            useJsonp: null
+        });
+    }
+    /**
+    Creates a DataService from the output of {@link DataService.toJSON}. Used when importing metadata
+    and exported entities. The `jsonResultsAdapter` name is looked up among the
+    {@link JsonResultsAdapter}s created so far, so create a custom one before importing.
+    @param json - A serialized DataService. Its `jsonResultsAdapter` property is replaced.
+    @throws if the named `jsonResultsAdapter` does not exist.
+    */
+    static fromJSON(json) {
+        json.jsonResultsAdapter = config._fetchObject(JsonResultsAdapter, json.jsonResultsAdapter);
+        return new DataService(json);
+    }
+    /**
+     Returns a url for this dataService with the specified suffix. This method handles dataService names either
+     with or without trailing '/'s.  If the suffix starts with "http" then it will be returned as-is.
+     @param suffix {String} The resulting url.
+     @returns {a Url string}
+     */
+    qualifyUrl(suffix) {
+        if (suffix && suffix.startsWith("http")) {
+            return suffix;
+        }
+        let url = this.serviceName;
+        // remove any trailing "/"
+        if (stringEndsWith(url, "/")) {
+            url = url.substr(0, url.length - 1);
+        }
+        // ensure that it ends with "/" + suffix
+        suffix = "/" + suffix;
+        if (!stringEndsWith(url, suffix)) {
+            url = url + suffix;
+        }
+        return url;
+    }
+}
+DataService.prototype._$typeName = "DataService";
+function updateWithConfig(obj, dsConfig) {
+    if (dsConfig) {
+        assertConfig(dsConfig)
+            .whereParam("serviceName").isOptional()
+            .whereParam("adapterName").isString().isOptional()
+            .whereParam("uriBuilderName").isString().isOptional()
+            .whereParam("hasServerMetadata").isBoolean().isOptional()
+            .whereParam("jsonResultsAdapter").isInstanceOf(JsonResultsAdapter).isOptional()
+            .whereParam("useJsonp").isBoolean().isOptional()
+            .applyAll(obj);
+        obj.serviceName = obj.serviceName && DataService._normalizeServiceName(obj.serviceName);
+        obj.adapterInstance = obj.adapterName ? config.getAdapterInstance("dataService", obj.adapterName) : undefined;
+        obj.uriBuilder = obj.uriBuilderName ? config.getAdapterInstance("uriBuilder", obj.uriBuilderName) : undefined;
+    }
+    return obj;
+}
+/**
+A JsonResultsAdapter instance is used to provide custom extraction and parsing logic on the json results returned by any web service.
+This facility makes it possible for breeze to talk to virtually any web service and return objects that will be first class 'breeze' citizens.
+*/
+export class JsonResultsAdapter {
+    /** The name of this adapter.  This name is used to uniquely identify and locate this instance when an 'exported' JsonResultsAdapter is later imported. */
+    name;
+    /** A Function that is called once per query operation to extract the 'payload' from any json received over the wire.
+    This method has a default implementation which simply returns the "results" property from any json returned as a result of executing the query. */
+    extractResults; // TODO - refine
+    /** A function that is called once per save operation to extract the entities from any json received over the wire.  Must return an array.
+    This method has a default implementation which simply returns the "entities" property from any json returned as a result of executing the save. */
+    extractSaveResults;
+    /** A function that is called once per save operation to extract the key mappings from any json received over the wire.  Must return an array.
+  This method has a default implementation which simply returns the "keyMappings" property from any json returned as a result of executing the save. */
+    extractKeyMappings;
+    /** A function that is called once per save operation to extract any deleted keys from any json received over the wire.  Must return an array.
+    This method has a default implementation which is to simply returns the "deletedKeys" property from any json returned as a result of executing the save. */
+    extractDeletedKeys; // TODO: refine
+    /** A visitor method that will be called on each node of the returned payload. */
+    visitNode;
+    /**
+    JsonResultsAdapter constructor
+  
+    @example
+        //
+        var jsonResultsAdapter = new JsonResultsAdapter({
+            name: "test1e",
+            extractResults: function(json) {
+                return json.results;
+            },
+            visitNode: function(node, mappingContext, nodeContext) {
+                var entityType = normalizeTypeName(node.$type);
+                var propertyName = nodeContext.propertyName;
+                var ignore = propertyName && propertyName.substr(0, 1) === "$";
+  
+                return {
+                    entityType: entityType,
+                    nodeId: node.$id,
+                    nodeRefId: node.$ref,
+                    ignore: ignore,
+                    passThru: false // default
+                };
+            }
+        });
+  
+        var dataService = new DataService( {
+                serviceName: "breeze/foo",
+                jsonResultsAdapter: jsonResultsAdapter
+        });
+  
+        var entityManager = new EntityManager( {
+            dataService: dataService
+        });
+  
+    @param jsConfig - A configuration object.
+  
+    */
+    constructor(jsConfig) {
+        if (arguments.length !== 1) {
+            throw new Error("The JsonResultsAdapter ctor should be called with a single argument that is a configuration object.");
+        }
+        assertConfig(jsConfig)
+            .whereParam("name").isNonEmptyString()
+            .whereParam("extractResults").isFunction().isOptional().withDefault(extractResultsDefault)
+            .whereParam("extractSaveResults").isFunction().isOptional().withDefault(extractSaveResultsDefault)
+            .whereParam("extractKeyMappings").isFunction().isOptional().withDefault(extractKeyMappingsDefault)
+            .whereParam("extractDeletedKeys").isFunction().isOptional().withDefault(extractDeletedKeysDefault)
+            .whereParam("visitNode").isFunction()
+            .applyAll(this);
+        config._storeObject(this, "JsonResultsAdapter", this.name);
+    }
+}
+JsonResultsAdapter.prototype._$typeName = "JsonResultsAdapter";
+function extractResultsDefault(data) {
+    return data.results;
+}
+function extractSaveResultsDefault(data) {
+    return data.entities || data.Entities || [];
+}
+function extractKeyMappingsDefault(data) {
+    return data.keyMappings || data.KeyMappings || [];
+}
+function extractDeletedKeysDefault(data) {
+    return data.deletedKeys || data.DeletedKeys || [];
+}
+//# sourceMappingURL=data-service.js.map

package/metadata/data-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-service.js","sourceRoot":"","sources":["../../src/metadata/data-service.ts"],"names":[],"mappings":"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","sourcesContent":["import { EntityType, NavigationProperty } from './entity-metadata.js';\nimport { DataServiceAdapter, UriBuilderAdapter } from '../config/interface-registry.js';\nimport { KeyMapping } from '../manager/entity-manager.js';\nimport { MappingContext } from '../query/mapping-context.js';\nimport { assertConfig } from '../core/assert-param.js';\nimport { config } from '../config/config.js';\nimport { core, stringEndsWith } from '../core/core.js';\n\n/** Configuration info to be passed to the {@link DataService} constructor */\nexport interface DataServiceConfig {\n  /** The serviceName for this DataService.  */\n  serviceName?: string;\n  /** The adapter name for the {@link DataServiceAdapter} to be used with this service.  */\n  adapterName?: string;\n  /** The adapter name for the {@link UriBuilderAdapter} to be used with this service.  */\n  uriBuilderName?: string;\n  /** Whether the server can provide metadata for this service.  */\n  hasServerMetadata?: boolean;\n  /** The {@link JsonResultsAdapter} used to process the results of any query against this DataService.  */\n  jsonResultsAdapter?: JsonResultsAdapter;\n  /** Whether to use JSONP when performing a 'GET' request against this service.\n  @deprecated No effect on Breeze's own transport, which has no JSONP support. Kept because it is\n  part of a serialized DataService, and because a registered (deprecated) ajax adapter can still\n  act on the dataType and crossDomain settings it produces. */\n  useJsonp?: boolean;\n}\n/**\nA DataService instance is used to encapsulate the details of a single 'service'; this includes a serviceName, a dataService adapterInstance,\nand whether the service has server side metadata.\n\nYou can construct an EntityManager with either a serviceName or a DataService instance, if you use a serviceName then a DataService\nis constructed for you.  (It can also be set via the EntityManager.setProperties method).\n\nThe same applies to the MetadataStore.fetchMetadata method, i.e. it takes either a serviceName or a DataService instance.\n\nEach metadataStore contains a list of DataServices, each accessible via its ‘serviceName’.\n( see MetadataStore.getDataService and MetadataStore.addDataService).  The ‘addDataService’ method is called internally\nanytime a MetadataStore.fetchMetadata call occurs with a new dataService ( or service name).\n\n*/\nexport class DataService {\n  /** @hidden @internal */\n  declare _$typeName: string; // actually put on prototype.\n  /** The serviceName for this DataService. __Read Only__ */\n  declare serviceName: string;\n  /** The adapter name for the {@link DataServiceAdapter} to be used with this service. __Read Only__  */\n  declare adapterName: string;\n  /**  The {@link DataServiceAdapter} implementation instance associated with this EntityManager. __Read Only__  */\n  declare adapterInstance?: DataServiceAdapter;\n  /** The adapter name for the {@link UriBuilderAdapter} to be used with this service. __Read Only__  */\n  declare uriBuilderName: string;\n  /**  The {@link UriBuilderAdapter} implementation instance associated with this EntityManager. __Read Only__  */\n  declare uriBuilder?: UriBuilderAdapter;\n  /** Whether the server can provide metadata for this service. __Read Only__   */\n  declare hasServerMetadata: boolean;\n  /** The {@link JsonResultsAdapter} used to process the results of any query against this DataService. __Read Only__ */\n  declare jsonResultsAdapter: JsonResultsAdapter;\n  /** Whether to use JSONP when performing a 'GET' request against this service. __Read Only__\n  @deprecated No effect on Breeze's own transport, which has no JSONP support. Kept because it is\n  part of a serialized DataService, and because a registered (deprecated) ajax adapter can still\n  act on the dataType and crossDomain settings it produces. */\n  declare useJsonp: boolean;\n\n  /**   DataService constructor\n  ```ts\n  var dataService = new DataService({\n      serviceName: altServiceName,\n      hasServerMetadata: false\n  });\n  ```\n\n  ```ts\n  var metadataStore = new MetadataStore({\n      namingConvention: NamingConvention.camelCase\n  });\n  ```\n\n  ```ts\n  return new EntityManager({\n      dataService: dataService,\n      metadataStore: metadataStore\n  });\n  ```\n  @param config - A configuration object.\n  */\n  constructor(config?: DataServiceConfig) {\n    updateWithConfig(this, config);\n  }\n\n\n  /**\n  Returns a copy of this DataService with the specified properties applied.\n  @param config - The configuration object to apply to create a new DataService.\n  */\n  using(config: DataServiceConfig) {\n    if (!config) return this;\n    let result = new DataService(this);\n    return updateWithConfig(result, config);\n  }\n\n  /**\n  Combines several DataServices into one, taking each property from the first of them that has it\n  set, and filling in the adapters: the named ones, or the defaults. Breeze uses it to combine a\n  query's or save's own DataService with the EntityManager's before each request; applications do\n  not normally need it.\n  @param dataServices - The DataServices to combine, most specific first. Entries may be null or\n  undefined. The array is modified.\n  @throws if none of them has a `serviceName`.\n  */\n  static resolve(dataServices: DataService[]) {\n    // final defaults\n    // Deliberate use of 'as any' below.\n    (dataServices as any).push({\n      hasServerMetadata: true,\n      useJsonp: false\n    });\n    let ds = new DataService(core.resolveProperties(dataServices,\n        [\"serviceName\", \"adapterName\", \"uriBuilderName\", \"hasServerMetadata\", \"jsonResultsAdapter\", \"useJsonp\"]));\n\n    if (!ds.serviceName) {\n      throw new Error(\"Unable to resolve a 'serviceName' for this dataService\");\n    }\n    ds.adapterInstance = ds.adapterInstance || config.getAdapterInstance<DataServiceAdapter>(\"dataService\", ds.adapterName);\n    ds.jsonResultsAdapter = ds.jsonResultsAdapter || ds.adapterInstance!.jsonResultsAdapter;\n    ds.uriBuilder = ds.uriBuilder || config.getAdapterInstance<UriBuilderAdapter>(\"uriBuilder\", ds.uriBuilderName);\n    return ds;\n  }\n\n  /** @hidden @internal */\n  static _normalizeServiceName(serviceName: string) {\n    serviceName = serviceName.trim();\n    if (serviceName.substr(-1) !== \"/\") {\n      return serviceName + '/';\n    } else {\n      return serviceName;\n    }\n  }\n\n  /**\n  Returns the serializable form of this DataService: `serviceName`, `adapterName`,\n  `uriBuilderName`, `hasServerMetadata`, `useJsonp` and the `name` of its `jsonResultsAdapter`,\n  leaving out any that are not set. `JSON.stringify` calls it when `MetadataStore.exportMetadata`\n  and `EntityManager.exportEntities` serialize their DataServices; {@link DataService.fromJSON}\n  reads it back.\n  */\n  toJSON() {\n    // don't use default value here - because we want to be able to distinguish undefined props for inheritence purposes.\n    return core.toJson(this, {\n      serviceName: null,\n      adapterName: null,\n      uriBuilderName: null,\n      hasServerMetadata: null,\n      jsonResultsAdapter: function (v: any) {\n        return v && v.name;\n      },\n      useJsonp: null\n    });\n  }\n\n  /**\n  Creates a DataService from the output of {@link DataService.toJSON}. Used when importing metadata\n  and exported entities. The `jsonResultsAdapter` name is looked up among the\n  {@link JsonResultsAdapter}s created so far, so create a custom one before importing.\n  @param json - A serialized DataService. Its `jsonResultsAdapter` property is replaced.\n  @throws if the named `jsonResultsAdapter` does not exist.\n  */\n  static fromJSON(json: any) {\n    json.jsonResultsAdapter = config._fetchObject(JsonResultsAdapter, json.jsonResultsAdapter);\n    return new DataService(json);\n  }\n\n  /**\n   Returns a url for this dataService with the specified suffix. This method handles dataService names either\n   with or without trailing '/'s.  If the suffix starts with \"http\" then it will be returned as-is.\n   @param suffix {String} The resulting url.\n   @returns {a Url string}\n   */\n  qualifyUrl(suffix: string) {\n    if (suffix && suffix.startsWith(\"http\")) {\n      return suffix;\n    }\n    let url = this.serviceName;\n    // remove any trailing \"/\"\n    if (stringEndsWith(url, \"/\")) {\n      url = url.substr(0, url.length - 1);\n    }\n    // ensure that it ends with \"/\" + suffix\n    suffix = \"/\" + suffix;\n    if (!stringEndsWith(url, suffix)) {\n      url = url + suffix;\n    }\n    return url;\n  }\n\n}\nDataService.prototype._$typeName = \"DataService\";\n\nfunction updateWithConfig(obj: DataService, dsConfig?: DataServiceConfig) {\n  if (dsConfig) {\n    assertConfig(dsConfig)\n        .whereParam(\"serviceName\").isOptional()\n        .whereParam(\"adapterName\").isString().isOptional()\n        .whereParam(\"uriBuilderName\").isString().isOptional()\n        .whereParam(\"hasServerMetadata\").isBoolean().isOptional()\n        .whereParam(\"jsonResultsAdapter\").isInstanceOf(JsonResultsAdapter).isOptional()\n        .whereParam(\"useJsonp\").isBoolean().isOptional()\n        .applyAll(obj);\n    obj.serviceName = obj.serviceName && DataService._normalizeServiceName(obj.serviceName);\n    obj.adapterInstance = obj.adapterName ?  config.getAdapterInstance<DataServiceAdapter>(\"dataService\", obj.adapterName) : undefined;\n    obj.uriBuilder = obj.uriBuilderName ? config.getAdapterInstance<UriBuilderAdapter>(\"uriBuilder\", obj.uriBuilderName) : undefined;\n  }\n  return obj;\n}\n\n/**\nWhat a {@link JsonResultsAdapter}'s `visitNode` returns for one node of a query or save result,\ntelling Breeze how to treat it. Every property is optional; returning `{}` (or nothing) treats the\nnode as plain data.\n*/\nexport interface NodeMeta {\n  /** The type of entity or complex object this node is, or its name. When set, Breeze materializes the node as an entity of that type and merges it into the cache (unless the query is `noTracking`); a complex type is mapped without merging. For a top-level query result with no type, Breeze uses the query's result type. */\n  entityType?: EntityType;\n  /** An id for this node, such as a Json.NET `$id`, that other nodes can refer to with `nodeRefId`. */\n  nodeId?: string;\n  /** The `nodeId` of another node that this node stands for, such as a Json.NET `$ref`. Breeze returns the entity or object read from that node in its place. */\n  nodeRefId?: string;\n  /** Whether to skip this node. A skipped property is left off the object that holds it; a skipped top-level node is dropped from the results (or is `null` there, when the query includes deleted entities). */\n  ignore?: boolean;\n  /** Whether to keep the node exactly as the server sent it, without mapping its property names to the client's or visiting what it contains. Ignored for a top-level node that has an `entityType`, which is merged as an entity. */\n  passThru?: boolean;\n  /** Anything else about the node to keep. Breeze stores it on the entity's `entityAspect.extraMetadata`. */\n  extraMetadata?: any;\n  /** Use this object in place of the node that was visited. */\n  node?: any;\n}\n\n/** Where a node passed to a {@link JsonResultsAdapter}'s `visitNode` sits in the result. */\nexport interface NodeContext {\n  /** `\"root\"` for a top-level result, `\"navProp\"` or `\"navPropItem\"` for the value or an item of a navigation property, and `\"anonProp\"` or `\"anonPropItem\"` for the value or an item of a property of a plain (non-entity) object. */\n  nodeType: string;\n  /** For an `\"anonProp\"` or `\"anonPropItem\"` node, the client name of the property that holds it. */\n  propertyName?: string;\n  /** For a `\"navProp\"` or `\"navPropItem\"` node, the navigation property that holds it. */\n  navigationProperty?: NavigationProperty;\n}\n\n/** Configuration info to be passed to the {@link JsonResultsAdapter} constructor */\nexport interface JsonResultsAdapterConfig {\n  /** The name of this adapter.  This name is used to uniquely identify and locate this instance when an 'exported' JsonResultsAdapter is later imported. */\n  name: string;\n  /** A Function that is called once per query operation to extract the 'payload' from any json received over the wire. \n  This method has a default implementation which to simply return the \"results\" property from any json returned as a result of executing the query. \n  */\n  extractResults?: Function;\n  /** A function that is called once per save operation to extract the entities from any json received over the wire.  Must return an array.\n  This method has a default implementation which simply returns the \"entities\" property from any json returned as a result of executing the save. */\n  extractSaveResults?: Function;\n  /** A function that is called once per save operation to extract the key mappings from any json received over the wire.  Must return an array.\n  This method has a default implementation which simply returns the \"keyMappings\" property from any json returned as a result of executing the save. */\n  extractKeyMappings?: (data: {}) => KeyMapping[];\n  /** A function that is called once per save operation to extract any deleted keys from any json received over the wire.  Must return an array.\n  This method has a default implementation which simply returns an empty array. */\n  extractDeletedKeys?: (data: {}) => any[]; // TODO: refine\n  /** A visitor method that will be called on each node of the returned payload. Required.\n  Breeze always passes all three arguments. Returning nothing is the same as returning `{}`. */\n  visitNode: (node: any, mappingContext: MappingContext, nodeContext: NodeContext) => NodeMeta | null | void;\n\n}\n\n/**\nA JsonResultsAdapter instance is used to provide custom extraction and parsing logic on the json results returned by any web service.\nThis facility makes it possible for breeze to talk to virtually any web service and return objects that will be first class 'breeze' citizens.\n*/\nexport class JsonResultsAdapter {\n  /** @hidden @internal */\n  declare _$typeName: string; // actually put on prototype.\n  /** The name of this adapter.  This name is used to uniquely identify and locate this instance when an 'exported' JsonResultsAdapter is later imported. */\n  name: string;\n  /** A Function that is called once per query operation to extract the 'payload' from any json received over the wire. \n  This method has a default implementation which simply returns the \"results\" property from any json returned as a result of executing the query. */\n  extractResults: Function; // TODO - refine\n  /** A function that is called once per save operation to extract the entities from any json received over the wire.  Must return an array.\n  This method has a default implementation which simply returns the \"entities\" property from any json returned as a result of executing the save. */\n  extractSaveResults: Function;\n    /** A function that is called once per save operation to extract the key mappings from any json received over the wire.  Must return an array.\n  This method has a default implementation which simply returns the \"keyMappings\" property from any json returned as a result of executing the save. */\n  extractKeyMappings:  (data: {}) => KeyMapping[];\n  /** A function that is called once per save operation to extract any deleted keys from any json received over the wire.  Must return an array.\n  This method has a default implementation which is to simply returns the \"deletedKeys\" property from any json returned as a result of executing the save. */\n  extractDeletedKeys?: (data: {}) => any[]; // TODO: refine\n  /** A visitor method that will be called on each node of the returned payload. */\n  visitNode: Function;\n\n  /**\n  JsonResultsAdapter constructor\n\n  @example\n      //\n      var jsonResultsAdapter = new JsonResultsAdapter({\n          name: \"test1e\",\n          extractResults: function(json) {\n              return json.results;\n          },\n          visitNode: function(node, mappingContext, nodeContext) {\n              var entityType = normalizeTypeName(node.$type);\n              var propertyName = nodeContext.propertyName;\n              var ignore = propertyName && propertyName.substr(0, 1) === \"$\";\n\n              return {\n                  entityType: entityType,\n                  nodeId: node.$id,\n                  nodeRefId: node.$ref,\n                  ignore: ignore,\n                  passThru: false // default\n              };\n          }\n      });\n\n      var dataService = new DataService( {\n              serviceName: \"breeze/foo\",\n              jsonResultsAdapter: jsonResultsAdapter\n      });\n\n      var entityManager = new EntityManager( {\n          dataService: dataService\n      });\n\n  @param jsConfig - A configuration object.\n\n  */\n  constructor(jsConfig: JsonResultsAdapterConfig) {\n    if (arguments.length !== 1) {\n      throw new Error(\"The JsonResultsAdapter ctor should be called with a single argument that is a configuration object.\");\n    }\n\n    assertConfig(jsConfig)\n        .whereParam(\"name\").isNonEmptyString()\n        .whereParam(\"extractResults\").isFunction().isOptional().withDefault(extractResultsDefault)\n        .whereParam(\"extractSaveResults\").isFunction().isOptional().withDefault(extractSaveResultsDefault)\n        .whereParam(\"extractKeyMappings\").isFunction().isOptional().withDefault(extractKeyMappingsDefault)\n        .whereParam(\"extractDeletedKeys\").isFunction().isOptional().withDefault(extractDeletedKeysDefault)\n        .whereParam(\"visitNode\").isFunction()\n        .applyAll(this);\n    config._storeObject(this, \"JsonResultsAdapter\", this.name);\n  }\n\n}\nJsonResultsAdapter.prototype._$typeName = \"JsonResultsAdapter\";\n\nfunction extractResultsDefault(data: any) {\n  return data.results;\n}\n\nfunction extractSaveResultsDefault(data: any) {\n  return data.entities || data.Entities || [];\n}\n\nfunction extractKeyMappingsDefault(data: any) {\n  return data.keyMappings || data.KeyMappings || [];\n}\n\nfunction extractDeletedKeysDefault(data: any) {\n  return data.deletedKeys || data.DeletedKeys || [];\n}\n\n"]}

package/metadata/data-type.d.ts

@@ -0,0 +1,122 @@
+import { BreezeEnum } from '../core/enum.js';
+import { Validator } from '../validation/validate.js';
+/**
+DataType is an 'Enum' containing all of the supported data types.
+*/
+export declare class DataType extends BreezeEnum {
+    /** The default value of this DataType. __Read Only__ */
+    defaultValue?: any;
+    /** Whether this is a 'numeric' DataType. __Read Only__ */
+    isNumeric?: boolean;
+    /** Whether this is an 'integer' DataType. __Read Only__ */
+    isInteger?: boolean;
+    /** The constructor function to create a {@link Validator} to be used in validating instances of this DataType. */
+    validatorCtor?(context?: any): Validator;
+    /**
+    Optional function to normalize a data value for comparison, if its value cannot be used directly.
+    Note that this will be called each time a property is changed, so make it fast.
+    @returns value appropriate for this DataType
+    */
+    normalize?(value: any): any;
+    /**
+    Optional function to convert a raw (server) value from string to this DataType.
+    @returns value appropriate for this DataType
+    */
+    parseRawValue?(value: any): any;
+    /**
+    Optional function to convert a value from string to this DataType.  Note that this will be called each time a property is changed, so make it fast.
+    @returns value appropriate for this DataType
+    */
+    parse?(source: any, sourceTypeName: string): any;
+    /**
+    Optional function to get the next value for key generation, if this datatype is used as a key.  Uses an internal table of previous values.
+    @returns value appropriate for this DataType
+    */
+    getNext?(): any;
+    /**
+    Optional function to get the next value when the datatype is used as a concurrency property.
+    @param previousValue
+    @returns the next concurrency value, which may be a function of the previousValue.
+    */
+    getConcurrencyValue?(previousValue?: any): any;
+    /**
+    The function Breeze converts `DateTime` and `DateTimeOffset` values from the server with, when it
+    materializes query and save results. Defaults to {@link DataType.parseDateAsUTC}. Replace it at
+    startup, before the first query, to change how a date-time string with no offset is read - for
+    example with {@link DataType.parseDateAsLocal}. It does not affect saves, which always send UTC.
+    */
+    static parseDateFromServer: (value: any) => any;
+    /** A string (.NET `String`; also `Char`). Default `""`. */
+    static String: DataType;
+    /** A 64-bit integer (.NET `Int64`; also `UInt32` and `UInt64`), held as a JavaScript `number`, so values beyond ±2^53 lose precision. Default `0`. */
+    static Int64: DataType;
+    /** A 32-bit integer (.NET `Int32`; also `UInt16`), held as a `number`. Default `0`. */
+    static Int32: DataType;
+    /** A 16-bit integer (.NET `Int16`; also `SByte`), held as a `number`. Default `0`. */
+    static Int16: DataType;
+    /** An unsigned 8-bit integer, 0 to 255 (.NET `Byte`), held as a `number`. Default `0`. */
+    static Byte: DataType;
+    /** A decimal number (.NET `Decimal`), held as a JavaScript `number` - a double - so digits beyond its precision are lost. Default `0`. */
+    static Decimal: DataType;
+    /** A 64-bit floating-point number (.NET `Double`). Also the type Breeze infers for an unmapped property that holds a number. Default `0`. */
+    static Double: DataType;
+    /** A 32-bit floating-point number (.NET `Single`), held as a `number`. Default `0`. */
+    static Single: DataType;
+    /** A calendar date with no time (.NET `DateOnly`), held as a `Date` at local midnight. Read from the first ten characters (`YYYY-MM-DD`) of the server's value, sent back as `YYYY-MM-DD` from the local date, and compared by date alone. Default 1 January 1900. */
+    static DateOnly: DataType;
+    /** A date and time (.NET `DateTime`), held as a `Date`. Read from the server with {@link DataType.parseDateFromServer} and sent as ISO 8601 in UTC. Also the type Breeze infers for an unmapped property that holds a `Date`. Default 1 January 1900, local midnight. */
+    static DateTime: DataType;
+    /** A date and time with an offset (.NET `DateTimeOffset`), held as a `Date`, which has no offset: it is read with {@link DataType.parseDateFromServer} and sent back in UTC, so the original offset is lost. Default 1 January 1900, local midnight. */
+    static DateTimeOffset: DataType;
+    /** A duration (.NET `TimeSpan`), held as the ISO 8601 duration string the server sends, such as `PT4H30M`. Compared as a number of seconds in local queries. Default `PT0S`. */
+    static Time: DataType;
+    /** A time of day (.NET `TimeOnly`), held as the string the server sends: "14:30:00" or "01:23:45.678". */
+    static TimeOnly: DataType;
+    /** A `true` or `false` value (.NET `Boolean`). Default `false`. */
+    static Boolean: DataType;
+    /** A GUID (.NET `Guid`), held as a lower-case string. Default `"00000000-0000-0000-0000-000000000000"`. */
+    static Guid: DataType;
+    /** Binary data (.NET `byte[]`), such as a SQL `rowversion`, held as the base64 string the server sends. Default `null`. */
+    static Binary: DataType;
+    /** An unknown type: a server type name the client does not recognize (the original is kept in the property's `rawTypeName`), or an unmapped property whose type cannot be inferred. Values are not converted or validated. Default `undefined`. */
+    static Undefined: DataType;
+    /**
+    Returns the function Breeze uses to turn values of a data type into something `===`, `<` and `>`
+    compare correctly, in local queries and when ordering: the data type's `normalize` if it has one,
+    a conversion to seconds for {@link DataType.Time}, and otherwise the value itself. Applications do
+    not normally need it.
+    @param dataType - The data type of the values to compare.
+    */
+    static getComparableFn(dataType?: DataType): (value: any) => any;
+    /**
+    Returns the DataType with the specified name, or undefined if there is none. Also accepts the names the .NET
+    servers use for some types, such as 'TimeSpan' for {@link DataType.Time}.
+    */
+    static fromName(name: string): DataType | undefined;
+    /** Returns the DataType for a specified input. */
+    static fromValue(val: any): DataType;
+    /**
+    Converts a {@link DataType.Time} value from the server. By default it returns the value unchanged:
+    a `Time` is held as the ISO 8601 duration string the server sends, such as `PT4H30M`. Replace it
+    at startup, before the first query, to hold durations some other way - as a number of seconds,
+    say, with {@link core.durationToSeconds}.
+    */
+    static parseTimeFromServer(source: any): any;
+    /**
+    Converts a date-time string from the server to a `Date`. This is the default
+    {@link DataType.parseDateFromServer}.
+    - A string with `Z` or an offset (`2024-03-15T10:30:00Z`, `...10:30:00+02:00`) is read as given.
+    - A string with no offset that ends in fractional seconds, of any length
+      (`2024-03-15T10:30:00.5`, `...00.000`, `...00.1234567`), is read as UTC: Breeze appends `Z`.
+    - Any other string with no offset, such as `2024-03-15T10:30:00`, goes to `Date.parse`
+      unchanged, which reads it as **local** time.
+    @param source - The value from the server.
+    */
+    static parseDateAsUTC(source: any): any;
+    /** Parse as UTC then shift to local time */
+    static parseDateAsLocal(source: string): any;
+    /** if val is a Date, return a date-only string e.g. '2023-12-31' */
+    static toDateOnlyString(val: any): any;
+    /** Returns a raw value converted to the specified DataType */
+    static parseRawValue(val: any, dataType?: DataType): any;
+}