@api-client/core 0.11.11 → 0.12.1

package/build/src/modeling/DomainAssociation.d.ts

@@ -0,0 +1,281 @@
+import type { DataDomain } from './DataDomain.js';
+import { DomainAssociationKind } from '../models/kinds.js';
+import { DomainElement, type DomainElementSchema } from './DomainElement.js';
+import { type IThing, Thing } from '../models/Thing.js';
+import type { DomainEntity } from './DomainEntity.js';
+import type { IApiAssociationShape, IApiPropertyShape } from '../amf/definitions/Shapes.js';
+import type { AssociationBinding, AssociationBindings, AssociationWebBindings } from './Bindings.js';
+import { DomainAttributeAttribute } from './DataFormat.js';
+import type { AssociationTarget } from './types.js';
+export interface DomainAssociationSchema extends DomainElementSchema {
+    kind: typeof DomainAssociationKind;
+    /**
+     * The data association description.
+     */
+    info: IThing;
+    /**
+     * Wether the data association is required.
+     */
+    required?: boolean;
+    /**
+     * Whether the data association allows multiple items.
+     */
+    multiple?: boolean;
+    /**
+     * The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
+     *
+     * When this is defined then it is used as the schema. When this is not defined it uses
+     * referenced entities schemas. Note, changes in the referenced entities may not be propagated
+     * to schemas altered by the user.
+     */
+    schema?: IApiAssociationShape;
+    /**
+     * The list of bindings for this property.
+     *
+     * A binding defines a translation from a data model to a specific format.
+     * For example allows to define properties required to generate AMF shape and therefore RAML/OAS shapes for web APIs
+     * or a protocol buffer schema.
+     */
+    bindings?: AssociationBinding[];
+    /**
+     * 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.
+     * When multiple associations are set then we are dealing with an union.
+     */
+    targets?: AssociationTarget[];
+}
+/**
+ * Represents an association between entities in a data domain.
+ *
+ * A `DomainAssociation` defines a relationship between a
+ * `DomainEntity` and one or more other entities. It specifies
+ * how entities are connected and can represent various types
+ * of relationships, such as one-to-one, one-to-many, or
+ * many-to-many.
+ *
+ * **Key Features:**
+ *
+ * -   **Target Entities:** Specifies the entities that are
+ *     the target of the association.
+ * -   **Cardinality:** Defines whether the association is
+ *     single-valued or multi-valued (e.g., one-to-one vs.
+ *     one-to-many).
+ * -   **Required Status:** Indicates whether the association
+ *     is mandatory or optional.
+ * -   **Schema Customization:** Allows defining a custom
+ *     schema for the association, overriding the default
+ *     schema derived from the target entities.
+ * -   **Bindings:** Supports defining how the association is
+ *     represented in different formats (e.g., web APIs,
+ *     protocol buffers).
+ * -   **Foreign Namespaces:** Can target entities in other
+ *     namespaces, enabling cross-namespace relationships.
+ *
+ * **Usage:**
+ *
+ * The preferred way to create a `DomainAssociation` is
+ * through the `DomainEntity.addAssociation()` method.
+ *
+ * **Example:**
+ *
+ * ```typescript
+ * const dataDomain = new DataDomain();
+ * const userModel = dataDomain.addModel({ key: 'userModel' });
+ * const userEntity = userModel.addEntity({ key: 'user' });
+ * const addressEntity = userModel.addEntity({ key: 'address' });
+ * // Add an association from User to Address
+ * const addressAssociation = userEntity.addAssociation();
+ * addressAssociation.addTarget(addressEntity);
+ * ```
+ */
+export declare class DomainAssociation extends DomainElement {
+    /**
+     * The kind of the domain element.
+     */
+    kind: typeof DomainAssociationKind;
+    /**
+     * The description of the association namespace.
+     */
+    accessor info: Thing;
+    /**
+     * Wether the data association is required.
+     */
+    accessor required: boolean | undefined;
+    /**
+     * Whether the data association allows multiple items.
+     */
+    accessor multiple: boolean | undefined;
+    /**
+     * The schema allowing to translate the model into a
+     * specific format (like JSON, RAML, XML, etc.)
+     */
+    accessor schema: IApiAssociationShape | undefined;
+    /**
+     * The list of bindings for this property.
+     *
+     * A binding defines a translation from a data model to a specific format.
+     * For example allows to define properties required to generate AMF shape and therefore RAML/OAS shapes for web APIs
+     * or a protocol buffer schema.
+     */
+    accessor bindings: AssociationBinding[];
+    /**
+     * The key of the parent entity.
+     */
+    protected parent: string;
+    /**
+     * 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.
+     * When multiple associations are set then we are dealing with an union.
+     */
+    accessor targets: AssociationTarget[];
+    /**
+     * Creates a full data association schema with defaults.
+     *
+     * @param input The partial data association schema.
+     * @returns The data association schema.
+     */
+    static createSchema(input?: Partial<DomainAssociationSchema>): DomainAssociationSchema;
+    /**
+     * Creates a new data association instance.
+     *
+     * You probably want to use the `DomainEntity.addAssociation()` method instead.
+     *
+     * @param root A reference to the root DataDomain instance.
+     * @param parent The key of the parent entity.
+     * @param input The partial data association schema.
+     */
+    constructor(root: DataDomain, parent: string, input?: Partial<DomainAssociationSchema>);
+    /**
+     * Generates a JSON representation of the association.
+     *
+     * @returns A plain object representation of the `DomainAssociation`.
+     */
+    toJSON(): DomainAssociationSchema;
+    /**
+     * Returns a parent data entity where this data property exist.
+     *
+     * @returns The parent `DomainEntity` or undefined if not found.
+     */
+    getParentInstance(): DomainEntity | undefined;
+    /**
+     * Removes this property from the parent entity.
+     *
+     * This method removes the association from the parent
+     * entity's list of associations.
+     *
+     * @example
+     * ```typescript
+     * association.remove();
+     * ```
+     */
+    remove(): void;
+    /**
+     * Creates the `schema` object if missing and returns it.
+     *
+     * @returns The schema object.
+     * @example
+     * ```typescript
+     * const schema = association.ensureSchema();
+     * ```
+     */
+    ensureSchema(): IApiAssociationShape;
+    /**
+     * Checks whether the passed value is one of the supported
+     * data property attributes.
+     *
+     * @param value The value to test
+     * @returns True when the passed value is one of the
+     *   supported data property attributes.
+     */
+    static isValidAttribute(value: unknown): value is DomainAttributeAttribute;
+    /**
+     * Creates if not existing and returns web bindings
+     * definition.
+     *
+     * @returns The web binding definition
+     * @example
+     * ```typescript
+     * const webBindings = association.getWebBinding();
+     * webBindings.hidden = true;
+     * ```
+     */
+    getWebBinding(): AssociationWebBindings;
+    /**
+     * Returns the schema value of the binding, if any was
+     * created.
+     *
+     * @param type The type of the binding to read.
+     * @returns The binding schema, if any
+     * @example
+     * ```typescript
+     * const webBindings = association.readBinding('web');
+     * if (webBindings) {
+     *   // ...
+     * }
+     * ```
+     */
+    readBinding(type: 'web' | 'protobuf'): AssociationBindings | undefined;
+    /**
+     * Adds a target entity to the association.
+     *
+     * If the entity comes from another namespace then it is
+     * set as a foreign entity.
+     *
+     * @param entity - The `DomainEntity` instance to add.
+     * @example
+     * ```typescript
+     * association.addTarget(addressEntity);
+     * ```
+     */
+    addTarget(entity: DomainEntity): void;
+    /**
+     * Adds a target entity to the association.
+     *
+     * @param entity - The `DomainEntity` definition or just
+     *   its key.
+     * @param namespace - The key of the foreign namespace this
+     *   entity belongs to. Do not set this value for local
+     *   entities.
+     * @example
+     * ```typescript
+     * association.addTarget('address', 'foreignNamespace');
+     * ```
+     */
+    addTarget(entity: string, namespace?: string): void;
+    /**
+     * Removes a target entity from the targets list.
+     *
+     * @param init The key of an entity, its instance, or
+     *   schema.
+     * @example
+     * ```typescript
+     * association.removeTarget(addressEntity);
+     * ```
+     */
+    removeTarget(init: string | DomainEntity): void;
+    /**
+     * Lists all target entities of this association.
+     *
+     * @returns A generator that yields each target
+     *   `DomainEntity`.
+     * @example
+     * ```typescript
+     * for (const target of association.listTargets()) {
+     *   console.log(target.key);
+     * }
+     * ```
+     */
+    listTargets(): Generator<DomainEntity>;
+    /**
+     * Creates a Property Shape of AMF.
+     * The property itself is auto-generated. If the `schema` is defined then it is used
+     * as the `range` of the property. Otherwise basic shape is generated for the range.
+     *
+     * This is a preferred way of reading the AMF shape as this synchronizes changed
+     * data properties with the shape definition.
+     *
+     * @returns AMF property shape definition.
+     */
+    toApiShape(): IApiPropertyShape;
+}
+//# sourceMappingURL=DomainAssociation.d.ts.map

package/build/src/modeling/DomainAssociation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DomainAssociation.d.ts","sourceRoot":"","sources":["../../../src/modeling/DomainAssociation.ts"],"names":[],"mappings":"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"}