@api-client/core 0.8.20 → 0.8.22

package/src/models/SerializablePayload.ts

@@ -1,11 +1,30 @@
 import { PayloadSerializer, Payload, DeserializedPayload } from '../lib/transformers/PayloadSerializer.js';
 import { hasBuffer } from '../Platform.js';
 
+export interface SerializablePayloadOptions {
+  /**
+   * The mime type of the payload, if any.
+   * This is a helper information that **should** be put 
+   * while providing the payload. It is the value of the 
+   * `content-type` header to be used with the body if one is missing.
+   * 
+   * Note, this is only used when the headers field does not 
+   * include the `content-type` value.
+   */
+  mime?: string;
+}
+
 export class SerializablePayload {
   /**
    * The serialized payload message.
    */
   payload?: Payload;
+
+  /**
+   * Optional meta of the payload
+   */
+  payloadOptions?: SerializablePayloadOptions;
+
   /**
    * The payload in its original format.
    * May not be populated when the `getPayload()` was not yet read.
@@ -15,10 +34,19 @@ export class SerializablePayload {
   /**
    * Sets the payload on the request.
    * This transforms the source `message` to its serialized form using the `PayloadSerializer`.
+   * 
+   * @param message The payload value
+   * @param mime The payload mime type. This is optional and sets the `payloadOptions.mime` value when set.
    */
-  async writePayload(message: unknown): Promise<void> {
+  async writePayload(message: unknown, mime?: string): Promise<void> {
     this._sourcePayload = message;
     this.payload = await PayloadSerializer.serialize(message as DeserializedPayload);
+    if (mime) {
+      if (!this.payloadOptions) {
+        this.payloadOptions = {};
+      }
+      this.payloadOptions.mime = mime;
+    }
   }
 
   /**

package/src/models/data/DataAssociation.ts

@@ -8,6 +8,23 @@ import { DataNamespace } from './DataNamespace.js';
 
 export const Kind = 'Core#DataAssociation';
 
+/**
+ * Describes association target of an entity
+ */
+export interface AssociationTarget {
+  /**
+   * The key of the associated entity.
+   */
+  key: string;
+  /**
+   * The key of the namespace to look for entities.
+   * By default it is the current (root) namespace. When this is set the program 
+   * will look into `foreign` of the root namespace for the definition 
+   * of the entity.
+   */
+  namespace?: string;
+}
+
 /**
  * Describes an association between entities. An association is another property of an entity. The `name` is the name of the
  * property and the value is the associated target or targets.
@@ -46,7 +63,7 @@ export interface IDataAssociation {
    * The list of keys associated with the entity through this association.
    * An association without a target is considered invalid and discarded when processing the values.
    */
-  targets?: string[];
+  targets?: AssociationTarget[];
   /**
    * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
    * 
@@ -109,7 +126,7 @@ export class DataAssociation {
    * The list of keys associated with the entity through this association.
    * An association without a target is considered invalid and discarded when processing the values.
    */
-  targets: string[] = [];
+  targets: AssociationTarget[] = [];
 
   /**
    * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
@@ -145,10 +162,17 @@ export class DataAssociation {
    * 
    * @param root The namespace root.
    * @param target The target entity key.
+   * @param namespace The optional key of the target association when different to the current one.
    */
-  static fromTarget(root: DataNamespace, target: string): DataAssociation {
+  static fromTarget(root: DataNamespace, target: string, namespace?: string): DataAssociation {
     const assoc = new DataAssociation(root);
-    assoc.targets = [target];
+    const info: AssociationTarget = {
+      key: target,
+    }
+    if (namespace) {
+      info.namespace = namespace;
+    }
+    assoc.targets = [info];
     return assoc;
   }
 
@@ -214,7 +238,7 @@ export class DataAssociation {
       this.required = undefined;
     }
     if (Array.isArray(targets)) {
-      this.targets = [...targets];
+      this.targets = targets.map(i => ({ ...i }));
     } else {
       this.targets = [];
     }
@@ -254,7 +278,7 @@ export class DataAssociation {
       result.required = this.required;
     }
     if (Array.isArray(this.targets) && this.targets.length) {
-      result.targets = [...this.targets];
+      result.targets = this.targets.map(i => ({ ...i }));
     }
     if (typeof this.hidden === 'boolean') {
       result.hidden = this.hidden;
@@ -269,8 +293,8 @@ export class DataAssociation {
    * @returns The list of DataEntity definitions for the current targets.
    */
   getTargets(): DataEntity[] {
-    const { root, targets } = this;
-    return root.definitions.entities.filter(item => targets.some(i => i === item.key));
+    const { targets } = this;
+    return this.root.findAssociatedEntities(targets).filter(i => !!i) as DataEntity[];
   }
 
   /**
@@ -293,24 +317,35 @@ export class DataAssociation {
    * Adds a target to the targets list from an entity.
    * @param entity The instance or schema of an entity.
    */
-  addTarget(entity: DataEntity | IDataEntity): void;
+  addTarget(entity: DataEntity | IDataEntity, namespace?: string): void;
 
   /**
    * Adds the target to the targets list with an entity key..
    * @param key The key of the entity to add.
    */
-  addTarget(key: string): void;
+  addTarget(key: string, namespace?: string): void;
 
   /**
    * @param init The key of an entity, its instance, or schema.
    */
-  addTarget(init: string | DataEntity | IDataEntity): void {
+  addTarget(init: string | DataEntity | IDataEntity, namespace?: string): void {
+    let key: string;
     if (typeof init === 'string') {
-      this.targets.push(init);
+      key = init;
     } else {
-      const { key } = init;
-      this.targets.push(key);
+      key = init.key;
+      const typed = init as DataEntity;
+      if (!namespace && typed.root && typed.root !== this.root) {
+        namespace = typed.key;
+      }
+    }
+    const info: AssociationTarget = {
+      key,
+    }
+    if (namespace) {
+      info.namespace = namespace;
     }
+    this.targets.push(info);
   }
 
   /**
@@ -339,7 +374,7 @@ export class DataAssociation {
     } else {
       key = init.key;
     }
-    const index = this.targets.indexOf(key);
+    const index = this.targets.findIndex(i => i.key === key);
     if (index >= 0) {
       this.targets.splice(index, 1);
     }

package/src/models/data/DataEntity.ts

@@ -334,6 +334,8 @@ export class DataEntity {
   /**
    * Creates an association for a given target, adds it to definitions, and returns it.
    * @param target The target entity key of the association
+   * @param namespace The target entity namespace when different to the current namespace.
+   * @param name Optional name.
    * @returns The created association
    */
   addTargetAssociation(target: string, name?: string): DataAssociation {
@@ -346,6 +348,23 @@ export class DataEntity {
     return result;
   }
 
+  /**
+   * Creates an association for a given target that is in another namespace
+   * @param target The target entity key of the association
+   * @param namespace The target entity namespace when different to the current namespace.
+   * @param name Optional name.
+   * @returns The created association
+   */
+  addForeignAssociation(target: string, namespace: string, name?: string): DataAssociation {
+    const result = DataAssociation.fromTarget(this.root, target, namespace);
+    if (name) {
+      result.info.name = name;
+    }
+    this.root.definitions.associations.push(result);
+    this.associations.push(result);
+    return result;
+  }
+
   /**
    * Removes an association from the entity and namespace definitions.
    * @param key The key of the association to remove.
@@ -395,17 +414,18 @@ export class DataEntity {
    * Computes a list of entities that are associated with the current entity.
    */
   getComputedAssociations(): DataEntity[] {
-    const { root, associations } = this;
-    const { entities } = root.definitions;
+    const { associations } = this;
     const result: DataEntity[] = [];
     associations.forEach((assoc) => {
       if (!assoc.targets.length) {
         return;
       }
-      const entity = entities.find(i => assoc.targets.includes(i.key));
-      if (entity) {
-        result.push(entity);
-      }
+      const entities = this.root.findAssociatedEntities(assoc.targets);
+      entities.forEach((entity) => {
+        if (entity) {
+          result.push(entity);
+        }
+      });
     });
     return result;
   }
@@ -473,7 +493,7 @@ export class DataEntity {
   }
 
   /**
-   * Returns a list of entities that are association with this entity through an association
+   * Returns a list of entities that are associated with this entity through an association
    * that the target property points to this entity.
    * 
    * In other words, if entity `A` has association target with `B`, then asking `B` for related entities will
@@ -489,11 +509,32 @@ export class DataEntity {
    */
   getRelatedEntities(): DataEntity[] {
     const { key, root } = this;
+    const result = DataEntity.getRelatedEntities(root, key);
+    root.foreign.forEach((ns) => {
+      const other = DataEntity.getRelatedEntities(ns, key);
+      other.forEach((entity) => {
+        if (!result.includes(entity)) {
+          result.push(entity);
+        }
+      });
+    });
+    return result;
+    // const inverse = root.definitions.associations.filter(i => i.targets.some(j => j.key === key));
+    // inverse.forEach((assoc) => {
+    //   const entity = root.definitions.entities.find(e => e.associations.includes(assoc));
+    //   if (entity) {
+    //     result.push(entity);
+    //   }
+    // });
+    // return result;
+  }
+
+  static getRelatedEntities(namespace: DataNamespace, entity: string): DataEntity[] {
     const result: DataEntity[] = [];
-    const inverse = root.definitions.associations.filter(i => i.targets.includes(key));
+    const inverse = namespace.definitions.associations.filter(i => i.targets.some(j => j.key === entity));
     inverse.forEach((assoc) => {
-      const entity = root.definitions.entities.find(e => e.associations.includes(assoc));
-      if (entity) {
+      const entity = namespace.definitions.entities.find(e => e.associations.includes(assoc));
+      if (entity && !result.includes(entity)) {
         result.push(entity);
       }
     });

package/src/models/data/DataNamespace.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-this-alias */
 import { IThing, Thing } from "../Thing.js";
-import { IDataAssociation, DataAssociation } from "./DataAssociation.js";
+import { IDataAssociation, DataAssociation, AssociationTarget } from "./DataAssociation.js";
 import { IDataEntity, DataEntity } from "./DataEntity.js";
 import { IDataModel, DataModel, Kind as DataModelKind } from "./DataModel.js";
 import { IDataProperty, DataProperty } from "./DataProperty.js";
@@ -277,6 +277,16 @@ export class DataItem implements IDataItem {
 export class DataNamespace extends DataNamespaceParent {
   definitions: DataDefinitions;
 
+  /**
+   * The list of foreign namespaces.
+   * This is used to find entities from foreign namespaces.
+   * Values here are treated as read only (objects can be frozen).
+   * 
+   * This should be set by the application and the namespace will do
+   * nothing to populate this value.
+   */
+  foreign: DataNamespace[] = [];
+
   /**
    * Creates a new data namespace from a name.
    * @param name The name to set.
@@ -553,7 +563,8 @@ export class DataNamespace extends DataNamespaceParent {
       if (!graph[srcEntity.key]) {
         graph[srcEntity.key] = [];
       }
-      graph[srcEntity.key].splice(0, 0, ...assoc.targets);
+      const targetIds = assoc.targets.map(i => i.key);
+      graph[srcEntity.key].splice(0, 0, ...targetIds);
     }
     return graph;
   }
@@ -588,4 +599,69 @@ export class DataNamespace extends DataNamespaceParent {
       path.pop();
     }
   }
+
+  /**
+   * Scans all associations for foreign namespaces and returns 
+   * the list of all namespaces used in the association graph.
+   * This will never add this namespace's key.
+   * 
+   * This function should be used to read keys for all related 
+   * namespaces through associations.
+   * 
+   * @returns All keys of foreign namespaces.
+   */
+  computeForeignNamespaceKeys(): string[] {
+    const result: string[] = [];
+    const { associations = [] } = this.definitions;
+    associations.forEach((association) => {
+      const { targets = [] } = association;
+      targets.forEach((target) => {
+        const { namespace } = target;
+        if (!namespace || namespace === this.key) {
+          return;
+        }
+        result.push(namespace);
+      });
+    });
+    return result;
+  }
+
+  /**
+   * Finds an entity in this namespace.
+   * @param key The key of the entity to find.
+   */
+  findEntity(key: string): DataEntity | undefined {
+    const { definitions } = this.root || this;
+    return definitions.entities.find(i => i.key === key);
+  }
+
+  /**
+   * Searches for entities for association targets.
+   * This is a helper function to discover entities in the current and foreign namespaces.
+   * 
+   * @param targets The list of targets
+   * @returns A list of entities. An `undefined` is put at the index where an entity cannot be found
+   */
+  findAssociatedEntities(targets: AssociationTarget[]): (DataEntity | undefined)[] {
+    const result: (DataEntity | undefined)[] = [];
+    targets.forEach((target) => {
+      let ns: DataNamespace | undefined;
+      if (target.namespace) {
+        ns = this.foreign.find(i => i.key === target.namespace);
+      } else {
+        ns = this;
+      }
+      if (!ns) {
+        result.push(undefined);
+        return;
+      }
+      const entity = ns.findEntity(target.key);
+      if (entity) {
+        result.push(entity);
+      } else {
+        result.push(undefined);
+      }
+    });
+    return result;
+  }
 }

package/src/runtime/http-engine/CoreEngine.ts

@@ -129,7 +129,7 @@ export class CoreEngine extends HttpEngine {
       payload = undefined;
     }
     const headers = new Headers(this.request.toHeadersString());
-    this.prepareHeaders(headers);
+    this.prepareHeaders(headers, !!payload);
     const auth = this.hasProxy && !this.isProxyTunnel ? this._proxyAuthHeader() : undefined;
     if (auth) {
       headers.set('proxy-authorization', auth);

package/src/runtime/http-engine/HttpEngine.ts

@@ -385,23 +385,30 @@ export abstract class HttpEngine extends EventEmitter {
    * If `defaultHeaders` option is set then it adds `user-agent` and `accept`
    * headers.
    * @param headers Parsed headers
+   * @param withPayload Whether the request should send a body message
    */
-  prepareHeaders(headers: Headers): void {
-    if (!this.opts.defaultHeaders) {
-      return;
-    }
-    if (!headers.has('user-agent')) {
-      if (this.opts.defaultUserAgent) {
-        headers.set('user-agent', this.opts.defaultUserAgent);
-      } else {
-        headers.set('user-agent', 'api client');
+  prepareHeaders(headers: Headers, withPayload = false): void {
+    if (this.opts.defaultHeaders) {
+      if (!headers.has('user-agent')) {
+        if (this.opts.defaultUserAgent) {
+          headers.set('user-agent', this.opts.defaultUserAgent);
+        } else {
+          headers.set('user-agent', 'api client');
+        }
+      }
+      if (!headers.has('accept')) {
+        if (this.opts.defaultAccept) {
+          headers.set('accept', this.opts.defaultAccept);
+        } else {
+          headers.set('accept', '*/*');
+        }
       }
     }
-    if (!headers.has('accept')) {
-      if (this.opts.defaultAccept) {
-        headers.set('accept', this.opts.defaultAccept);
-      } else {
-        headers.set('accept', '*/*');
+    if (withPayload) {
+      if (!headers.has('content-type') && this.request.payloadOptions) {
+        if (this.request.payloadOptions.mime) {
+          headers.set('content-type', this.request.payloadOptions.mime);
+        }
       }
     }
   }