@api-client/core 0.11.2 → 0.11.4

package/data/models/petstore.json

@@ -4447,6 +4447,11 @@
 {
 "@id": "#547"
 }
+],
+"sourcemaps:sources": [
+{
+"@id": "#546/source-map"
+}
 ]
 },
 {
@@ -5259,6 +5264,9 @@
 ],
 "sourcemaps:lexical": [
 {
+"@id": "#295/source-map/lexical/element_1"
+},
+{
 "@id": "#295/source-map/lexical/element_0"
 }
 ]
@@ -5442,6 +5450,9 @@
 ],
 "sourcemaps:lexical": [
 {
+"@id": "#319/source-map/lexical/element_1"
+},
+{
 "@id": "#319/source-map/lexical/element_0"
 }
 ]
@@ -5623,6 +5634,9 @@
 ],
 "sourcemaps:lexical": [
 {
+"@id": "#337/source-map/lexical/element_1"
+},
+{
 "@id": "#337/source-map/lexical/element_0"
 }
 ]
@@ -5948,13 +5962,16 @@
 ],
 "sourcemaps:lexical": [
 {
-"@id": "#351/source-map/lexical/element_2"
+"@id": "#351/source-map/lexical/element_3"
+},
+{
+"@id": "#351/source-map/lexical/element_1"
 },
 {
 "@id": "#351/source-map/lexical/element_0"
 },
 {
-"@id": "#351/source-map/lexical/element_1"
+"@id": "#351/source-map/lexical/element_2"
 }
 ]
 },
@@ -6104,10 +6121,13 @@
 ],
 "sourcemaps:lexical": [
 {
-"@id": "#378/source-map/lexical/element_1"
+"@id": "#378/source-map/lexical/element_2"
 },
 {
 "@id": "#378/source-map/lexical/element_0"
+},
+{
+"@id": "#378/source-map/lexical/element_1"
 }
 ]
 },
@@ -6921,6 +6941,9 @@
 ],
 "sourcemaps:lexical": [
 {
+"@id": "#456/source-map/lexical/element_1"
+},
+{
 "@id": "#456/source-map/lexical/element_0"
 }
 ]
@@ -7108,6 +7131,9 @@
 ],
 "sourcemaps:lexical": [
 {
+"@id": "#466/source-map/lexical/element_1"
+},
+{
 "@id": "#466/source-map/lexical/element_0"
 }
 ]
@@ -7655,6 +7681,9 @@
 ],
 "sourcemaps:lexical": [
 {
+"@id": "#509/source-map/lexical/element_1"
+},
+{
 "@id": "#509/source-map/lexical/element_0"
 }
 ]
@@ -8243,6 +8272,17 @@
 ]
 },
 {
+"@id": "#546/source-map",
+"@type": [
+"sourcemaps:SourceMap"
+],
+"sourcemaps:lexical": [
+{
+"@id": "#546/source-map/lexical/element_0"
+}
+]
+},
+{
 "@id": "#544/source-map",
 "@type": [
 "sourcemaps:SourceMap"
@@ -9027,6 +9067,11 @@
 ]
 },
 {
+"@id": "#295/source-map/lexical/element_1",
+"sourcemaps:element": "amf://id#295",
+"sourcemaps:value": "[(121,6)-(135,0)]"
+},
+{
 "@id": "#295/source-map/lexical/element_0",
 "sourcemaps:element": "apiContract:parameter",
 "sourcemaps:value": "[(121,6)-(135,0)]"
@@ -9234,6 +9279,11 @@
 ]
 },
 {
+"@id": "#319/source-map/lexical/element_1",
+"sourcemaps:element": "amf://id#319",
+"sourcemaps:value": "[(164,6)-(174,0)]"
+},
+{
 "@id": "#319/source-map/lexical/element_0",
 "sourcemaps:element": "apiContract:parameter",
 "sourcemaps:value": "[(164,6)-(174,0)]"
@@ -9444,6 +9494,11 @@
 ]
 },
 {
+"@id": "#337/source-map/lexical/element_1",
+"sourcemaps:element": "amf://id#337",
+"sourcemaps:value": "[(201,6)-(209,0)]"
+},
+{
 "@id": "#337/source-map/lexical/element_0",
 "sourcemaps:element": "apiContract:uriParameter",
 "sourcemaps:value": "[(201,6)-(209,0)]"
@@ -9901,18 +9956,23 @@
 ]
 },
 {
-"@id": "#351/source-map/lexical/element_2",
+"@id": "#351/source-map/lexical/element_3",
 "sourcemaps:element": "apiContract:uriParameter",
 "sourcemaps:value": "[(234,6)-(275,0)]"
 },
 {
+"@id": "#351/source-map/lexical/element_1",
+"sourcemaps:element": "apiContract:parameter",
+"sourcemaps:value": "[(234,6)-(275,0)]"
+},
+{
 "@id": "#351/source-map/lexical/element_0",
 "sourcemaps:element": "apiContract:cookieParameter",
 "sourcemaps:value": "[(234,6)-(275,0)]"
 },
 {
-"@id": "#351/source-map/lexical/element_1",
-"sourcemaps:element": "apiContract:parameter",
+"@id": "#351/source-map/lexical/element_2",
+"sourcemaps:element": "amf://id#351",
 "sourcemaps:value": "[(234,6)-(275,0)]"
 },
 {
@@ -10087,7 +10147,7 @@
 ]
 },
 {
-"@id": "#378/source-map/lexical/element_1",
+"@id": "#378/source-map/lexical/element_2",
 "sourcemaps:element": "apiContract:uriParameter",
 "sourcemaps:value": "[(288,6)-(302,0)]"
 },
@@ -10097,6 +10157,11 @@
 "sourcemaps:value": "[(288,6)-(302,0)]"
 },
 {
+"@id": "#378/source-map/lexical/element_1",
+"sourcemaps:element": "amf://id#378",
+"sourcemaps:value": "[(288,6)-(302,0)]"
+},
+{
 "@id": "#377/source-map/lexical/element_2",
 "sourcemaps:element": "core:name",
 "sourcemaps:value": "[(303,8)-(303,13)]"
@@ -10901,6 +10966,11 @@
 ]
 },
 {
+"@id": "#456/source-map/lexical/element_1",
+"sourcemaps:element": "amf://id#456",
+"sourcemaps:value": "[(443,6)-(451,0)]"
+},
+{
 "@id": "#456/source-map/lexical/element_0",
 "sourcemaps:element": "apiContract:uriParameter",
 "sourcemaps:value": "[(443,6)-(451,0)]"
@@ -11069,6 +11139,11 @@
 ]
 },
 {
+"@id": "#466/source-map/lexical/element_1",
+"sourcemaps:element": "amf://id#466",
+"sourcemaps:value": "[(474,6)-(482,0)]"
+},
+{
 "@id": "#466/source-map/lexical/element_0",
 "sourcemaps:element": "apiContract:uriParameter",
 "sourcemaps:value": "[(474,6)-(482,0)]"
@@ -11641,6 +11716,11 @@
 ]
 },
 {
+"@id": "#509/source-map/lexical/element_1",
+"sourcemaps:element": "amf://id#509",
+"sourcemaps:value": "[(564,6)-(577,0)]"
+},
+{
 "@id": "#509/source-map/lexical/element_0",
 "sourcemaps:element": "apiContract:parameter",
 "sourcemaps:value": "[(564,6)-(577,0)]"
@@ -12256,6 +12336,11 @@
 ]
 },
 {
+"@id": "#546/source-map/lexical/element_0",
+"sourcemaps:element": "amf://id#546",
+"sourcemaps:value": "[(678,6)-(685,0)]"
+},
+{
 "@id": "#544/source-map/lexical/element_2",
 "sourcemaps:element": "core:name",
 "sourcemaps:value": "[(686,8)-(686,13)]"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/DataAssociation.ts

@@ -388,6 +388,8 @@ export class DataAssociation {
 
   /**
    * @param init The key of an entity, its instance, or schema.
+   * @param namespace - The key of the foreign namespace this entity belongs to.
+   *      Do not set this value for local entities.
    */
   addTarget(init: string | DataEntity | IDataEntity, namespace?: string): void {
     let key: string
@@ -415,21 +417,6 @@ export class DataAssociation {
     this.targets.push(info)
   }
 
-  /**
-   * Removes a target entity from the association.
-   *
-   * @param entity - The `DataEntity` or `IDataEntity` instance to remove.
-   */
-  removeTarget(entity: DataEntity | IDataEntity): void
-
-  /**
-   * Removes a target entity from the association.
-   *
-   * @param key - The key of the target entity to remove.
-   */
-  // eslint-disable-next-line @typescript-eslint/unified-signatures
-  removeTarget(key: string): void
-
   /**
    * Removes a target entity from the targets list.
    *

package/src/modeling/DataModel.ts

@@ -1,7 +1,7 @@
 import { IThing, Thing } from '../models/Thing.js'
 import v4 from '../lib/uuid.js'
 import { DataEntity, IDataEntity } from './DataEntity.js'
-import { DataNamespace } from './DataNamespace.js'
+import type { DataItemAdaptingOptions, DataNamespace } from './DataNamespace.js'
 import { FileBreadcrumb } from '../models/store/File.js'
 import { DataModelKind } from '../models/kinds.js'
 
@@ -149,6 +149,45 @@ export class DataModel {
     }
   }
 
+  /**
+   * Adapts an entity to this data model.
+   * The entity must already be added to another data model within this namespace for it to be
+   * adapted to this data model.
+   * This method is used to change the data model of an entity.
+   * It will remove the entity from the previous data model and add it to this one.
+   * @param entity The entity to adapt.
+   */
+  adaptEntity(entity: DataEntity, opts: DataItemAdaptingOptions = {}): void {
+    if (opts.index !== undefined) {
+      if (opts.index < 0) {
+        throw new Error(`The index ${opts.index} cannot be below 0.`)
+      }
+      if (opts.index >= this.entities.length) {
+        throw new Error(`The index ${opts.index} is not valid.`)
+      }
+    }
+    if (entity.root !== this.root) {
+      throw new Error(`The entity ${entity.key} is not in the same namespace as this data model.`)
+    }
+    if (entity.getParent() === this) {
+      throw new Error(`The entity ${entity.key} is already adapted by this data model.`)
+    }
+    const parent = entity.getParent()
+    if (!parent) {
+      throw new Error(`The entity ${entity.key} has no parent.`)
+    }
+    const index = parent.entities.findIndex((i) => i.key === entity.key)
+    if (index < 0) {
+      throw new Error(`The entity ${entity.key} is not in the parent data model.`)
+    }
+    parent.entities.splice(index, 1)
+    if (opts.index !== undefined) {
+      this.entities.splice(opts.index, 0, entity)
+    } else {
+      this.entities.push(entity)
+    }
+  }
+
   /**
    * Adds an entity to this data model.
    *

package/src/modeling/DataNamespace.ts

@@ -9,6 +9,13 @@ import v4 from '../lib/uuid.js'
 
 type ItemKind = typeof DataNamespaceKind | typeof DataModelKind
 
+export interface DataItemAdaptingOptions {
+  /**
+   * The index at which to adapt the item.
+   */
+  index?: number
+}
+
 interface IDataDefinitions {
   models?: IDataModel[]
   entities?: IDataEntity[]
@@ -44,7 +51,7 @@ interface DataDefinitions {
 
 /**
  * Data definition for a foreign namespace.
- * Each foreigh namespace is resolved to a specific version.
+ * Each foreign namespace is resolved to a specific version.
  * This makes sure that the local data are always referencing an existing
  * entity as breaking changes should be resolved when upgrading a version.
  */
@@ -435,6 +442,14 @@ export class DataNamespace extends DataNamespaceParent {
     return result
   }
 
+  /**
+   * Checks if this is the root namespace.
+   * @returns True if this is the root namespace.
+   */
+  isRoot(): boolean {
+    return this.root === undefined
+  }
+
   /**
    * Finds a parent namespace for the given namespace.
    * @param key The namespace key to find the parent for.
@@ -486,6 +501,55 @@ export class DataNamespace extends DataNamespaceParent {
     return definition
   }
 
+  /**
+   * Adapts an existing namespace to this namespace.
+   * This will remove the namespace from the parent namespace and add it to this one.
+   *
+   * @param ns The namespace to adapt.
+   * @param opts Adapting options.
+   */
+  adaptNamespace(ns: DataNamespace, opts: DataItemAdaptingOptions = {}): void {
+    if (opts.index !== undefined) {
+      if (opts.index < 0) {
+        throw new Error(`The index ${opts.index} cannot be below 0.`)
+      }
+      if (opts.index >= this.items.length) {
+        throw new Error(`The index ${opts.index} is not valid.`)
+      }
+    }
+    if (ns === this) {
+      throw new Error(`Unable to adapt a namespace that is self.`)
+    }
+    if (ns.root !== this.root) {
+      throw new Error(`The namespace ${ns.key} is not in the same namespace as this data namespace.`)
+    }
+    if (ns.getParent() === this) {
+      throw new Error(`The namespace ${ns.key} is already adapted by this data namespace.`)
+    }
+    // Check for circular dependency
+    let current: DataNamespace | undefined = this
+    while (current) {
+      if (current === ns) {
+        throw new Error(`Unable to adapt namespace ${ns.key} under itself or one of its children.`)
+      }
+      current = current.getParent()
+    }
+    const parent = ns.getParent() || this.root
+    if (!parent) {
+      throw new Error(`The namespace ${ns.key} has no parent.`)
+    }
+    const index = parent.items.findIndex((i) => i.key === ns.key)
+    if (index < 0) {
+      throw new Error(`The namespace ${ns.key} is not in the parent data namespace.`)
+    }
+    const [item] = parent.items.splice(index, 1)
+    if (opts.index !== undefined) {
+      this.items.splice(opts.index, 0, item)
+    } else {
+      this.items.push(item)
+    }
+  }
+
   /**
    * Finds a namespace in the definitions.
    * @param key The key of the namespace to find.
@@ -715,6 +779,29 @@ export class DataNamespace extends DataNamespaceParent {
     return result
   }
 
+  /**
+   * Finds an associated entity in the current or foreign namespace.
+   * This is a helper function to discover entities in the current and foreign namespaces.
+   *
+   * @param key The key of the entity to find.
+   * @param namespace The optional namespace to search in.
+   * If not set, the current namespace is used.
+   * This is used to find entities in foreign namespaces.
+   * @returns The entity or undefined if not found.
+   */
+  findAssociatedEntity(key: string, namespace?: string): DataEntity | undefined {
+    let ns: DataNamespace | undefined
+    if (namespace) {
+      ns = this.foreign.find((i) => i.key === namespace)
+    } else {
+      ns = this
+    }
+    if (!ns) {
+      return undefined
+    }
+    return ns.findEntity(key)
+  }
+
   addForeign(ns: DataNamespace): void {
     const exists = this.foreign.some((i) => i.key === ns.key)
     if (exists) {

package/src/modeling/readme.md

@@ -0,0 +1,134 @@
+# Data Modeling
+
+## Core Concepts
+
+At the heart of this data modeling system are the following fundamental concepts.
+
+### DataNamespace
+
+This is the top-level container, representing a logical grouping of data. Think of it as a "domain" or a "schema" in a database. It can contain:
+
+- `DataModels`: Logical groupings of entities.
+- `DataEntities`: The basic building blocks, representing individual data structures.
+- `DataProperties`: Attributes of entities (e.g., name, age, address).
+- `DataAssociations`: Relationships between entities (e.g., a user has an address).
+- `Sub-namespaces`: Namespaces can be nested within each other, creating a hierarchical structure.
+- `Foreign Namespaces`: References to external namespaces, enabling the use of entities defined elsewhere.
+- `Tags`: Common tags for the entire namespace.
+
+### DataModel
+
+A logical grouping of `DataEntity` instances. It represents a specific data structure, like a "Product" or "User" model. A `DataModel` can contain multiple `DataEntity` instances.
+
+### DataEntity
+
+The fundamental building block of the data model. It represents a specific type of data, like a "User," "Product," or "Address."
+
+- `Properties`: DataProperty instances that describe the attributes of the entity.
+- `Associations`: DataAssociation instances that define relationships to other entities.
+- `Parents`: An entity can inherit from other entities, creating a hierarchy.
+- `Fields`: Ordered list of properties and associations.
+- `Tags`: Optional tags for the UI.
+- `Taxonomy`: Reserved for future use.
+- `Deprecated`: Whether the entity is deprecated.
+- `Schema`: The schema allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
+
+### DataProperty
+
+Represents an attribute of a `DataEntity`. It has a name, a data type (e.g., string, number, boolean), and optional constraints (e.g., required, multiple, min/max values).
+
+- `Type`: The data type of the property.
+- `Schema`: The general schema definition of this property.
+- `Bindings`: The list of bindings for this property.
+- `Tags`: Optional tags for the UI.
+- `Taxonomy`: Reserved for future use.
+- `Deprecated`: Whether the property is deprecated.
+- `Primary`: Whether this property describes a primary key of the entity.
+- `Index`: Whether this property describes an indexed property of the entity.
+- `ReadOnly`: Whether the property is read only in the schema.
+- `WriteOnly`: Whether the property is write only in the schema.
+
+### DataAssociation
+
+Defines a relationship between `DataEntity` instances. It specifies the target entities and the nature of the relationship (e.g., one-to-one, one-to-many).
+
+- `Targets`: The list of target entities.
+- `Multiple`: Whether the association allows multiple target entities.
+- `Required`: Whether the association is required.
+- `Schema`: The definition of the database/API schema
+- `Bindings`: The list of bindings allowing to translate the model into a specific format (like JSON, RAML, XML, etc.)
+- `Hidden`: Defines if this association is a part of the schema or not.
+
+### Bindings
+
+Defines a translation from a data model to a specific format (like JSON, RAML, XML, etc.)
+
+## How a Data Domain is Structured
+
+Here's how these components work together to structure a data domain:
+
+1. **Root Namespace**: You start with a `DataNamespace`, which acts as the root of your data domain. This namespace is the top-level container for all other elements.
+
+1. **Sub-namespaces (Optional)**: You can create sub-namespaces within the root namespace to further organize your data. This is useful for large domains with many entities and relationships.
+
+1. **Data Models**: Within a namespace (or sub-namespace), you define `DataModel` instances. Each `DataModel` represents a specific area of your domain. For example, you might have a "User Management" `DataModel`, a "Product Catalog" `DataModel`, and an "Order Processing" `DataModel`.
+
+1. **Data Entities**: Inside each `DataModel`, you define `DataEntity` instances. These are the core data structures. For example, in the "User Management" `DataModel`, you might have `DataEntity` instances for "User," "Role," and "Permission."
+
+1. **Data Properties**: Each `DataEntity` has `DataProperty` instances that describe its attributes. For example, the "User" `DataEntity` might have `DataProperty` instances for "firstName" (string), "lastName" (string), "email" (string), "age" (number), etc.
+
+1. **Data Associations**: You use `DataAssociation` instances to define relationships between `DataEntity` instances. For example:
+
+   - A "User" has an "Address" (one-to-one).
+   - A "User" has multiple "Roles" (one-to-many).
+   - A "Product" belongs to a "Category" (many-to-one).
+   - An "Order" contains multiple "Order Items" (one-to-many).
+
+1. **Inheritance**: `DataEntity` instances can inherit from other `DataEntity` instances using the parents property. This allows you to create a hierarchy of entities and reuse common properties and associations.
+
+1. **Foreign Namespaces**: You can reference entities from other namespaces using the foreign property of the root namespace. This allows you to reuse data structures defined elsewhere.
+
+1. **Bindings**: You can define bindings for properties and associations to translate the data model into specific formats (e.g., JSON, RAML, XML, Protocol Buffers).
+
+## Example Scenario
+
+Let's imagine a simple e-commerce domain:
+
+- **Root Namespace**: `ECommerce`
+  - **Sub-namespace**: `Catalog`
+    - **Data Model**: `ProductCatalog`
+      - **Data Entity**: `Product`
+        - **Data Properties**: `name` (string), `description` (string), `price` (number), `sku` (string)
+        - **Data Association**: `category` (references `Category` entity)
+      - **Data Entity**: `Category`
+        - **Data Properties**: `name` (string), `description` (string)
+  - **Sub-namespace**: `UserManagement`
+    - **Data Model**: `UserManagement`
+      - **Data Entity**: `User`
+        - **Data Properties**: `firstName` (string), `lastName` (string), `email` (string), `password` (string)
+        - **Data Association**: `address` (references `Address` entity)
+      - **Data Entity**: `Address`
+        - **Data Properties**: `street` (string), `city` (string), `zipCode` (string), `country` (string)
+  - **Foreign Namespace**: `Taxonomy` (defined elsewhere)
+    - **Data Model**: `Taxonomy`
+      - **Data Entity**: `TaxonomyItem`
+
+### Key Relationships
+
+- **Namespace-Model**: A `DataNamespace` contains `DataModel` instances.
+- **Model-Entity**: A `DataModel` contains `DataEntity` instances.
+- **Entity-Property**: A `DataEntity` has `DataProperty` instances.
+- **Entity-Association**: A `DataEntity` has `DataAssociation` instances.
+- **Entity-Parent**: A `DataEntity` can have `DataEntity` instances as parents.
+- **Namespace-Foreign**: A `DataNamespace` can have references to `DataNamespace` instances.
+
+## Summary
+
+This data modeling system provides a flexible and powerful way to define complex data domains. It allows you to:
+
+- **Organize**: Group related data into namespaces and models.
+- **Structure**: Define entities with properties and relationships.
+- **Reuse**: Inherit from other entities and reference foreign namespaces.
+- **Translate**: Define bindings to map the model to different formats.
+- **Validate**: Validate the data model definition.
+- **Generate**: Generate AMF shapes and examples.

package/tests/unit/modeling/data_model.spec.ts

@@ -285,3 +285,57 @@ test.group('breadcrumbs()', (group) => {
     assert.equal(result[3].key, m1.key, 'has self last')
   })
 })
+
+test.group('adaptEntity()', (group) => {
+  let root: DataNamespace
+  let dm1: DataModel
+  let dm2: DataModel
+  let e1: DataEntity
+  let e2: DataEntity
+
+  group.each.setup(() => {
+    root = new DataNamespace()
+    dm1 = root.addNamespace('dm1').addDataModel('Data Model 1')
+    dm2 = root.addNamespace('dm2').addDataModel('Data Model 2')
+    e1 = dm1.addEntity('Entity 1')
+    e2 = dm1.addEntity('Entity 2')
+  })
+
+  test('moves an entity to a new data model', ({ assert }) => {
+    dm2.adaptEntity(e1)
+    assert.deepEqual(dm1.entities, [e2], 'removes from the old data model')
+    assert.deepEqual(dm2.entities, [e1], 'adds to the new data model')
+    assert.deepEqual(root.definitions.entities, [e1, e2], 'keeps the entity in the root definitions')
+  })
+
+  test('moves an entity to a new index', ({ assert }) => {
+    const e3 = dm2.addEntity('Entity 3')
+    dm2.adaptEntity(e1, { index: 0 })
+    assert.deepEqual(dm1.entities, [e2], 'removes from the old data model')
+    assert.deepEqual(dm2.entities, [e1, e3], 'adds to the new data model')
+    assert.deepEqual(root.definitions.entities, [e1, e2, e3], 'keeps the entity in the root definitions')
+  })
+
+  test('throws when adapting an entity from another root', ({ assert }) => {
+    const otherRoot = new DataNamespace()
+    const otherDm = otherRoot.addNamespace('other').addDataModel('Other Data Model')
+    const otherEntity = otherDm.addEntity('Other Entity')
+    assert.throws(
+      () => dm1.adaptEntity(otherEntity),
+      `The entity ${otherEntity.key} is not in the same namespace as this data model.`
+    )
+  })
+
+  test('throws when adapting an entity that is already adapted', ({ assert }) => {
+    dm2.adaptEntity(e1)
+    assert.throws(() => dm2.adaptEntity(e1), `The entity ${e1.key} is already adapted by this data model.`)
+  })
+
+  test('throws when index is out of range (minimum)', ({ assert }) => {
+    assert.throws(() => dm2.adaptEntity(e1, { index: -1 }), `The index -1 cannot be below 0.`)
+  })
+
+  test('throws when index is out of range (maximum)', ({ assert }) => {
+    assert.throws(() => dm2.adaptEntity(e1, { index: 1 }), `The index 1 is not valid.`)
+  })
+})