@api-client/core 0.11.11 → 0.12.0

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

@@ -0,0 +1,383 @@
+import type { DataDomain } from './DataDomain.js';
+import { DomainEntityKind } from '../models/kinds.js';
+import { DomainElement, type DomainElementSchema } from './DomainElement.js';
+import { type IThing, Thing } from '../models/Thing.js';
+import type { IShapeUnion } from '../amf/definitions/Shapes.js';
+import { DomainProperty, type DomainPropertySchema } from './DomainProperty.js';
+import { DomainAssociation, DomainAssociationSchema } from './DomainAssociation.js';
+import type { AssociationAddOptions } from './types.js';
+import type { FileBreadcrumb } from '../models/store/File.js';
+import type { DomainModel } from './DomainModel.js';
+import type { IShapeRenderOptions } from '../amf/shape/ShapeBase.js';
+export interface EntityOrderedItem {
+    /**
+     * The type of the ordered item.
+     */
+    type: 'property' | 'association';
+    /**
+     * The key of the ordered item.
+     */
+    key: string;
+}
+export interface DomainEntitySchema extends DomainElementSchema {
+    kind: typeof DomainEntityKind;
+    /**
+     * The domain entity description.
+     */
+    info: IThing;
+    /**
+     * Optional general purpose tags for the UI.
+     */
+    tags?: string[];
+    /**
+     * For future use.
+     *
+     * The keys of the taxonomy items associated with the entity.
+     */
+    taxonomy?: string[];
+    /**
+     * The ordered list of fields (properties and associations) in the schema.
+     * These only keep references to the properties and associations.
+     * The order of the fields is important as it defines the order of the
+     * properties in the schema.
+     */
+    fields?: EntityOrderedItem[];
+    /**
+     * Whether this entity is deprecated.
+     */
+    deprecated?: boolean;
+}
+/**
+ * Represents an entity within a data domain model.
+ *
+ * A `DomainEntity` defines a structured data type,
+ * containing properties and associations. It's a
+ * fundamental building block for modeling complex data
+ * structures.
+ *
+ * **Key Features:**
+ *
+ * - **Properties:** Defines the data elements (fields) within the entity.
+ * - **Associations:** Defines relationships to other entities.
+ * - **Inheritance:** Supports inheriting properties and associations from parent entities.
+ * - **Metadata:** Supports tags, taxonomy, and deprecation status.
+ * - **AMF Shape Generation:** Can be serialized to an AMF (API Modeling Framework) shape.
+ * - **Example Generation:** Can generate example databased on its schema.
+ *
+ * **Usage:**
+ *
+ * The preferred way to create a `DomainEntity` is through
+ * the `DomainModel.addEntity()` method.
+ *
+ * **Example:**
+ *
+ * ```typescript
+ * const dataDomain = new DataDomain();
+ * const userModel = dataDomain.addModel({ key: 'userModel' });
+ * const userEntity = userModel.addEntity({ key: 'user' });
+ * ```
+ */
+export declare class DomainEntity extends DomainElement {
+    /**
+     * The kind of the domain element.
+     */
+    kind: typeof DomainEntityKind;
+    /**
+     * The description of the domain entity.
+     */
+    accessor info: Thing;
+    /**
+     * Optional general purpose tags for the UI.
+     */
+    accessor tags: string[];
+    /**
+     * Reserved for future use.
+     *
+     * The keys of the taxonomy items associated with the entity.
+     */
+    accessor taxonomy: string[];
+    /**
+     * The ordered list of fields (properties and associations) in the schema.
+     * These only keep references to the properties and associations.
+     * The order of the fields is important as it defines the order of the
+     * properties in the schema.
+     */
+    accessor fields: EntityOrderedItem[];
+    /**
+     * Whether this entity is deprecated.
+     */
+    accessor deprecated: boolean | undefined;
+    /**
+     * Creates a full data entity schema with defaults.
+     *
+     * @param input The partial data entity schema.
+     * @returns The data entity schema.
+     */
+    static createSchema(input?: Partial<DomainEntitySchema>): DomainEntitySchema;
+    /**
+     * Creates a new domain entity instance.
+     *
+     * You probably want to use the `DomainModel.addEntity()`
+     * method instead.
+     *
+     * @param root A reference to the root DataDomain instance.
+     * @param input The partial domain entity schema.
+     */
+    constructor(root: DataDomain, input?: Partial<DomainEntitySchema>);
+    /**
+     * Generates a JSON representation of the entity.
+     *
+     * @returns A plain object representation of the `DomainEntity`.
+     */
+    toJSON(): DomainEntitySchema;
+    /**
+     * Returns a parent data entity where this data property
+     * exist.
+     *
+     * @returns The parent `DomainModel` or undefined if not found.
+     * @example
+     * ```typescript
+     * const parent = entity.getParentInstance();
+     * if (parent) {
+     *   console.log(parent.key);
+     * }
+     * ```
+     */
+    getParentInstance(): DomainModel | undefined;
+    /**
+     * Adds a property to this entity.
+     *
+     * @param property The partial property schema.
+     * @returns The created `DomainProperty` instance.
+     * @example
+     * ```typescript
+     * const property = entity.addProperty({
+     *   key: 'name',
+     *   type: 'string',
+     *   required: true,
+     * })
+     * ```
+     */
+    addProperty(property?: Partial<DomainPropertySchema>): DomainProperty;
+    /**
+     * Removes a property from this entity.
+     *
+     * @param key The key of the property to remove.
+     * @throws {RemovePropertyException} When the property does not exist.
+     * @example
+     * ```typescript
+     * entity.removeProperty('name')
+     * ```
+     */
+    removeProperty(key: string): void;
+    /**
+     * Lists all properties of this entity.
+     *
+     * Note, it accounts for the order of the properties as
+     * defined in the `fields` array.
+     *
+     * @returns A generator that yields each `DomainProperty`.
+     * @example
+     * ```typescript
+     * for (const property of entity.listProperties()) {
+     *   console.log(property.key);
+     * }
+     * ```
+     */
+    listProperties(): Generator<DomainProperty>;
+    /**
+     * Checks if this entity has any properties.
+     *
+     * @returns True if the entity has properties.
+     * @example
+     * ```typescript
+     * if (entity.hasProperties()) {
+     *   // ...
+     * }
+     * ```
+     */
+    hasProperties(): boolean;
+    /**
+     * Lists all parent entities of this entity.
+     *
+     * @returns A generator that yields each parent `DomainEntity`.
+     * @example
+     * ```typescript
+     * for (const parent of entity.listParents()) {
+     *   console.log(parent.key);
+     * }
+     * ```
+     */
+    listParents(): Generator<DomainEntity>;
+    /**
+     * Adds a parent to this entity.
+     *
+     * @param key The key of the parent entity.
+     * @param domain The key of the foreign domain the parent belongs to.
+     * @returns `this` for chaining.
+     * @throws ValidationError When the parent does not exist or a circular dependency is detected.
+     * @example
+     * ```typescript
+     * entity.addParent('baseEntity');
+     * ```
+     */
+    addParent(key: string, domain?: string): this;
+    /**
+     * Removes a parent from this entity.
+     *
+     * @param key The key of the parent entity to remove.
+     * @returns `this` for chaining.
+     * @throws Error When the parent does not exist.
+     * @example
+     * ```typescript
+     * entity.removeParent('baseEntity');
+     * ```
+     */
+    removeParent(key: string): this;
+    /**
+     * Checks if this entity has any parents.
+     *
+     * @returns True if the entity has parents.
+     * @example
+     * ```typescript
+     * if (entity.hasParents()) {
+     *   // ...
+     * }
+     * ```
+     */
+    hasParents(): boolean;
+    /**
+     * Checks if the passed entity has a circular parent
+     * relationship when attempting to add a new parent.
+     *
+     * @param key The key of the parent being added.
+     * @returns True if adding this parent would create a
+     *   circular relationship.
+     */
+    hasCircularParent(key: string): boolean;
+    /**
+     * Creates breadcrumbs from this entity to the root
+     * namespace.
+     *
+     * @returns An array of `FileBreadcrumb` instances.
+     * @example
+     * ```typescript
+     * const breadcrumbs = entity.breadcrumbs();
+     * console.log(breadcrumbs);
+     * ```
+     */
+    breadcrumbs(): FileBreadcrumb[];
+    /**
+     * Adds an association to this entity.
+     *
+     * @param init The association options.
+     * @param input The partial association schema.
+     * @returns The created `DomainAssociation` instance.
+     * @throws Error When the target entity does not exist.
+     * @example
+     * ```typescript
+     * const association = entity.addAssociation({
+     *   key: 'address',
+     * });
+     * ```
+     */
+    addAssociation(init?: AssociationAddOptions, input?: Partial<DomainAssociationSchema>): DomainAssociation;
+    /**
+     * Removes an association from this entity.
+     *
+     * @param key The key of the association to remove.
+     * @throws Error When the association does not exist.
+     * @example
+     * ```typescript
+     * entity.removeAssociation('address');
+     * ```
+     */
+    removeAssociation(key: string): void;
+    /**
+     * Lists all associations of this entity.
+     *
+     * The order of the associations is defined in the `fields` array.
+     *
+     * @returns A generator that yields each
+     *   `DomainAssociation`.
+     * @example
+     * ```typescript
+     * for (const association of entity.listAssociations()) {
+     *   console.log(association.key);
+     * }
+     * ```
+     */
+    listAssociations(): Generator<DomainAssociation>;
+    /**
+     * Checks if this entity has any associations.
+     *
+     * @returns True if the entity has associations.
+     * @example
+     * ```typescript
+     * if (entity.hasAssociations()) {
+     *   // ...
+     * }
+     * ```
+     */
+    hasAssociations(): boolean;
+    /**
+     * Lists all fields (properties and associations) of this entity.
+     *
+     * @returns A generator that yields each `DomainAssociation` or `DomainProperty`.
+     * @example
+     * ```typescript
+     * for (const field of entity.listFields()) {
+     *   console.log(field.key);
+     * }
+     * ```
+     */
+    listFields(): Generator<DomainAssociation | DomainProperty>;
+    /**
+     * Checks if this entity has any fields (properties or associations).
+     *
+     * @returns True if the entity has fields.
+     * @example
+     * ```typescript
+     * if (entity.hasFields()) {
+     *   // ...
+     * }
+     * ```
+     */
+    hasFields(): boolean;
+    private removeField;
+    /**
+     * Creates an AMF's data Shape.
+     *
+     * 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(): IShapeUnion;
+    /**
+     * Reads the schema of the Entity and generates an example for it.
+     *
+     * @param mime The mime type of the example.
+     * @param opts The example generation options.
+     * @returns The generated example.
+     * @example
+     * ```typescript
+     * const example = entity.toExample('application/json');
+     * console.log(example);
+     * ```
+     */
+    toExample(mime: string, opts?: IShapeRenderOptions): string | number | boolean | null | undefined;
+    /**
+     * Checks whether the entity is a child of the given namespace or data model.
+     * The relationship doesn't have to be direct, as long as the entity
+     * is in the hierarchy it will return true.
+     *
+     * @param key The key of the parent to check.
+     * @returns True if this entity is a child of the given namespace or data model.
+     */
+    isChildOf(key: string): boolean;
+}
+//# sourceMappingURL=DomainEntity.d.ts.map

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

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