@inweb/client 25.8.16 → 25.8.19

package/src/Api/Assembly.ts

@@ -23,14 +23,15 @@
 
 import { IHttpClient } from "./IHttpClient";
 import { FetchError } from "./FetchError";
-import { IAssociatedFileData, IAssemblyVersionInfo } from "./IAssembly";
+import { IAssociatedFileData, IAssemblyVersionInfo, IModelTransformMatrix } from "./IAssembly";
 import { IShortUserDescription } from "./IUser";
 import { Model } from "./Model";
 import { ClashTest } from "./ClashTest";
 import { waitFor, userFullName, userInitials } from "./Utils";
 
 /**
- * The class representing a `assembly` entity.
+ * Provides properties and methods for obtaining information about an assembly on the server
+ * and managing its data.
  */
 export class Assembly {
   private _data: any;
@@ -39,8 +40,8 @@ export class Assembly {
   public path: string;
 
   /**
-   * @param data - An object that implements assembly data storage.
-   * @param httpClient - Http client.
+   * @param data - Raw assembly data received from the server.
+   * @param httpClient - HTTP client instance used to send REST API requests to the server.
    */
   constructor(data: any, httpClient: IHttpClient) {
     this.path = `/assemblies/${data.id}`;
@@ -130,9 +131,9 @@ export class Assembly {
   /**
    * Assembly geometry data type:
    *
-   * - `vsfx` - VSFX, assembly can be opened in `VisualizeJS` viewer.
+   * - `vsfx` - `VSFX` format, assembly can be opened in `VisualizeJS` viewer.
    *
-   * Returns an empty string if geometry data has not yet been extracted.
+   * Returns an empty string if the geometry data is not yet ready.
    */
   get geometryType(): string {
     return this.status === "done" ? "vsfx" : "";
@@ -227,7 +228,7 @@ export class Assembly {
   }
 
   /**
-   * Refresh assembly data.
+   * Reloads assembly data from the server.
    */
   async checkout(): Promise<this> {
     const response = await this.internalGet("");
@@ -247,7 +248,7 @@ export class Assembly {
   }
 
   /**
-   * Delete the assembly from the server.
+   * Deletes an assembly from the server.
    *
    * @returns Returns the raw data of a deleted assembly.
    */
@@ -256,8 +257,8 @@ export class Assembly {
   }
 
   /**
-   * Save assembly data changes to the server. Call this method to update assembly data on the
-   * server after any changes.
+   * Saves assembly properties changes to the server. Call this method to update assembly data
+   * on the server after any property changes.
    */
   save(): Promise<this> {
     return this.update(this.data);
@@ -284,39 +285,22 @@ export class Assembly {
       .then((array) => array.map((data: any) => new Model(data, this)));
   }
 
-  /**
-   * Transformation matrix.
-   *
-   * @typedef {any} Transform
-   * @property {any} translate - Translation part, move along the X, Y, Z axes.
-   * @property {number} translate.x - The value for substruct for X axes.
-   * @property {number} translate.y - The value for substruct for Y axes.
-   * @property {number} translate.z - The value for substruct for Z axes.
-   * @property {any} rotation - Rotation part, rotate by the specified angle, around the
-   *   specified vector.
-   * @property {number} rotation.x - X coordinate of the rotation vector.
-   * @property {number} rotation.y - Y coordinate of the rotation vector.
-   * @property {number} rotation.z - Z coordinate of the rotation vector.
-   * @property {number} rotation.angle - The angle of rotation.
-   * @property {number} scale - Scaling part, scale with multiplier, from center of extends.
-   */
-
   /**
    * Returns a model transformation.
    *
-   * @param handle - Model handle.
+   * @param handle - Model original handle.
    */
-  getModelTransformMatrix(handle: string): any {
+  getModelTransformMatrix(handle: string): IModelTransformMatrix {
     return this.data.transform[handle];
   }
 
   /**
-   * Set or delete a model transformation.
+   * Sets or removes a model transformation.
    *
-   * @param handle - Model handle.
-   * @param transform - Transformation matrix. To delete transformation provide this to `undefined`.
+   * @param handle - Model original handle.
+   * @param transform - Transformation matrix. Specify `undefined` to remove transformation.
    */
-  setModelTransformMatrix(handle: string, transform: any): Promise<this> {
+  setModelTransformMatrix(handle: string, transform: IModelTransformMatrix): Promise<this> {
     const obj = { ...this.data.transform };
     obj[handle] = transform;
     return this.update({ transform: obj });
@@ -325,8 +309,8 @@ export class Assembly {
   /**
    * Returns the properties for an objects in the assembly.
    *
-   * @param handles - Object original handle or handles array. Leave this parameter undefined
-   *   to get properties for all objects in the assembly.
+   * @param handles - Object original handle or handles array. Specify `undefined` to get
+   *   properties for all objects in the assembly.
    * @returns {Promise<any>}
    */
   getProperties(handles?: string | string[]): Promise<any[]> {
@@ -364,7 +348,7 @@ export class Assembly {
   }
 
   /**
-   * Returns the cda.json for an assembly.
+   * Returns the CDA tree for an assembly.
    */
   getCdaTree(): Promise<any[]> {
     return this.internalGet(`/properties/tree`).then((response) => response.json());
@@ -380,7 +364,7 @@ export class Assembly {
   }
 
   /**
-   * Add new assembly viewpoint. To create a viewpoint use `Viewer.createViewpoint()`.
+   * Adds a new viewpoint to the assembly. To create a viewpoint use `Viewer.createViewpoint()`.
    *
    * @param viewpoint - Viewpoint.
    */
@@ -389,7 +373,7 @@ export class Assembly {
   }
 
   /**
-   * Delete assembly viewpoint.
+   * Deletes the specified assembly viewpoint.
    *
    * @param guid - Viewpoint GUID.
    * @returns Returns the raw data of a deleted viewpoint.
@@ -419,7 +403,7 @@ export class Assembly {
   }
 
   /**
-   * Download assembly resource file. Resource files are files that contain model scene
+   * Downloads an assembly resource file. Resource files are files that contain model scene
    * descriptions, or geometry data.
    *
    * @param dataId - Resource file name.
@@ -440,7 +424,7 @@ export class Assembly {
   }
 
   /**
-   * Download a part of assembly resource file. Resource files are files that contain model
+   * Downloads a part of assembly resource file. Resource files are files that contain model
    * scene descriptions, or geometry data.
    *
    * @param dataId - Resource file name.
@@ -500,7 +484,7 @@ export class Assembly {
   }
 
   /**
-   * Wait for assembly to be created. Assembly is created when it changes to `done` or `failed` status.
+   * Waits for assembly to be created. Assembly is created when it changes to `done` or `failed` status.
    *
    * @param params - An object containing waiting parameters.
    * @param params.timeout - The time, in milliseconds that the function should wait assembly.
@@ -531,15 +515,13 @@ export class Assembly {
   /**
    * Returns a list of assembly clash tests.
    *
-   * @param {number} start - The starting index in the test list. Used for paging.
-   * @param {number} limit - The maximum number of tests that should be returned per request.
-   *   Used for paging.
-   * @param {string} name - Filter the tests by part of the name.
-   * @param {string | string[]} ids - List of tests IDs to return. You can specify multiple IDs
-   *   on one `string` by separating them with a "|".
-   * @param {bool} sortByDesc - Allows to specify the descending order of the result. By
-   *   default tests are sorted by name in ascending order.
-   * @param {string} sortField - Allows to specify sort field.
+   * @param start - The starting index in the test list. Used for paging.
+   * @param limit - The maximum number of tests that should be returned per request. Used for paging.
+   * @param name - Filter the tests by part of the name. Case sensitive.
+   * @param ids - List of tests IDs to return.
+   * @param sortByDesc - Allows to specify the descending order of the result. By default tests
+   *   are sorted by name in ascending order.
+   * @param sortField - Allows to specify sort field.
    */
   getClashTests(
     start?: number,
@@ -575,7 +557,7 @@ export class Assembly {
   }
 
   /**
-   * Returns the assembly clash test information.
+   * Returns information about the specified assembly clash test.
    *
    * @param testId - Test ID.
    */
@@ -586,20 +568,39 @@ export class Assembly {
   }
 
   /**
-   * Create assembly clash test. Assembly must be in a `done` state, otherwise the test will fail.
+   * Creates an assembly clash test. Assembly must be in a `done` state, otherwise the test will fail.
    *
    * @param name - Test name.
-   * @param selectionTypeA - The type of first selection set for clash detection. Can be `all`,
-   *   `handles`, `models` or `searchquery`.
-   * @param selectionTypeB - The type of second selection set for clash detection. Can be
-   *   `all`, `handles`, `models` or `searchquery`.
-   * @param selectionSetA - First selection set for clash detection.
-   * @param selectionSetB - Second selection set for clash detection.
+   * @param selectionTypeA - The type of first selection set for clash detection. Can be one of:
+   *
+   *   - `all` - All file/assembly objects.
+   *   - `handle` - Objects with original handles specified in the `selectionSetA`.
+   *   - `models` - All objects of the models with original handles specified in the `selectionSetA`.
+   *   - `searchquery` - Objects retrieved by the search queries specified in `selectionSetA`.
+   *
+   * @param selectionTypeB - The type of second selection set for clash detection. Can be one of:
+   *
+   *   - `all` - All file/assembly objects.
+   *   - `handle` - Objects with original handles specified in the `selectionSetB`.
+   *   - `models` - All objects of the models with original handles specified in the `selectionSetB`.
+   *   - `searchquery` - Objects retrieved by the search queries specified in `selectionSetB`.
+   *
+   * @param selectionSetA - First selection set for clash detection. Objects from
+   *   `selectionSetA` will be tested against each others by objects from the `selectionSetB`
+   *   during the test.
+   * @param selectionSetB - Second selection set for clash detection. Objects from
+   *   `selectionSetB` will be tested against each others by objects from the `selectionSetA`
+   *   during the test.
    * @param params - An object containing test parameters.
-   * @param params.tolerance - The distance of separation between entities at which test begins
+   * @param params.tolerance - The distance of separation between objects at which test begins
    *   detecting clashes.
-   * @param params.clearance - The type of the clashes that the test detects: `true` for
-   *   `Сlearance clash` or `false` for `Hard clash`.
+   * @param params.clearance - The type of the clashes that the test detects:
+   *
+   *   - `true` - Сlearance clash. A clash in which the object A may or may not intersect with
+   *       object B, but comes within a distance of less than the `tolerance`.
+   *   - `false` - Hard clash. A clash in which the object A intersects with object B by a distance
+   *       of more than the `tolerance`.
+   *
    * @param params.waitForDone - Wait for test to complete.
    * @param params.timeout - The time, in milliseconds that the function should wait test. If
    *   test is not complete during this time, the `TimeoutError` exception will be thrown.
@@ -643,7 +644,7 @@ export class Assembly {
   }
 
   /**
-   * Delete assembly clash test.
+   * Deletes the specified assembly clash test.
    *
    * @param testId - Test ID.
    * @returns Returns the raw data of a deleted test.

package/src/Api/ClashTest.ts

@@ -26,7 +26,7 @@ import { IShortUserDescription } from "./IUser";
 import { waitFor, userFullName, userInitials } from "./Utils";
 
 /**
- * The base class provides information about the file/assembly clash detection test and test results.
+ * Provides properties and methods for obtaining information about a file/assembly clash detection test.
  */
 export class ClashTest {
   private _data: any;
@@ -34,9 +34,9 @@ export class ClashTest {
   public httpClient: IHttpClient;
 
   /**
-   * @param data - Raw test data.
-   * @param basePath - Clash tests API base path for the owner file/assembly.
-   * @param httpClient - Http client.
+   * @param data - Raw test data received from the server.
+   * @param basePath - The clash test API base path of the file/assembly that owns the test.
+   * @param httpClient - HTTP client instance used to send REST API requests to the server.
    */
   constructor(data: any, basePath: string, httpClient: IHttpClient) {
     this.httpClient = httpClient;
@@ -59,10 +59,10 @@ export class ClashTest {
   /**
    * The type of the clashes that the test detects:
    *
-   * - `Сlearance clash` (true) - a clash in which the entity A may or may not intersect with
-   *   entity B, but comes within a distance of less than the `tolerance`.
-   * - `Hard clash` (false) - a clash in which the entity A intersects with entity B by a
-   *   distance of more than the `tolerance`.
+   * - `true` - Сlearance clash. A clash in which the object A may or may not intersect with
+   *   object B, but comes within a distance of less than the {@link tolerance}.
+   * - `false` - Hard clash. A clash in which the object A intersects with object B by a distance
+   *   of more than the {@link tolerance}.
    *
    * @readonly
    */
@@ -144,8 +144,8 @@ export class ClashTest {
   }
 
   /**
-   * First selection set for clash detection. Entities from `selectionSetA` will be tested
-   * against each others by entities from the `selectionSetB` during the test.
+   * First selection set for clash detection. Objects from `selectionSetA` will be tested
+   * against each others by objects from the `selectionSetB` during the test.
    *
    * @readonly
    */
@@ -156,10 +156,10 @@ export class ClashTest {
   /**
    * The type of first selection set for clash detection. Can be one of:
    *
-   * - `all` - All file/assembly entities.
-   * - `handle` - Entities with handles specified in the `selectionSetA`.
-   * - `models` - Entities of file/assembly models specified in `selectionSetA`.
-   * - `searchquery` - Entities retrieved by the search queries specified in `selectionSetA`.
+   * - `all` - All file/assembly objects.
+   * - `handle` - Objects with original handles specified in the `selectionSetA`.
+   * - `models` - All objects of the models with original handles specified in the `selectionSetA`.
+   * - `searchquery` - Objects retrieved by the search queries specified in `selectionSetA`.
    *
    * @readonly
    */
@@ -168,8 +168,8 @@ export class ClashTest {
   }
 
   /**
-   * Second selection set for clash detection. Entities from `selectionSetB` will be tested
-   * against each others by entities from the `selectionSetA` during the test.
+   * Second selection set for clash detection. Objects from `selectionSetB` will be tested
+   * against each others by objects from the `selectionSetA` during the test.
    *
    * @readonly
    */
@@ -180,10 +180,10 @@ export class ClashTest {
   /**
    * The type of second selection set for clash detection. Can be one of:
    *
-   * - `all` - All file/assembly entities.
-   * - `handle` - Entities with handles specified in the `selectionSetB`.
-   * - `models` - Entities of file/assembly models specified in `selectionSetB`.
-   * - `searchquery` - Entities retrieved by the search queries specified in `selectionSetB`.
+   * - `all` - All file/assembly objects.
+   * - `handle` - Objects with original handles specified in the `selectionSetB`.
+   * - `models` - All objects of the models with original handles specified in the `selectionSetB`.
+   * - `searchquery` - Objects retrieved by the search queries specified in `selectionSetB`.
    *
    * @readonly
    */
@@ -201,7 +201,7 @@ export class ClashTest {
   }
 
   /**
-   * The distance of separation between entities at which test begins detecting clashes.
+   * The distance of separation between objects at which test begins detecting clashes.
    *
    * @readonly
    */
@@ -210,7 +210,7 @@ export class ClashTest {
   }
 
   /**
-   * Refresh test data.
+   * Reloads test data from the server.
    */
   async checkout(): Promise<this> {
     const response = await this.internalGet("");
@@ -219,7 +219,7 @@ export class ClashTest {
   }
 
   /**
-   * Update test data on the server.
+   * Updates test data on the server.
    *
    * @param data - Raw test data.
    */
@@ -230,7 +230,7 @@ export class ClashTest {
   }
 
   /**
-   * Remove a test from a file.
+   * Deletes a test and its results report from the server.
    *
    * @returns Returns the raw data of a deleted test.
    */
@@ -239,15 +239,15 @@ export class ClashTest {
   }
 
   /**
-   * Save test data changes to the server. Call this method to update test data on the server
-   * after any changes.
+   * Saves test properties changes to the server. Call this method to update test data on the
+   * server after any property changes.
    */
   save(): Promise<this> {
     return this.update(this.data);
   }
 
   /**
-   * Wait for test to complete. Test is done when it changes to `done` or `failed` status.
+   * Waits for test to complete. Test is done when it changes to `done` or `failed` status.
    *
    * @param params - An object containing waiting parameters.
    * @param params.timeout - The time, in milliseconds that the function should wait test. If
@@ -257,9 +257,20 @@ export class ClashTest {
    * @param params.signal - An
    *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController}
    *   signal, which can be used to abort waiting as desired.
+   * @param params.onCheckout - Waiting progress callback. Return `true` to cancel waiting.
    */
-  waitForDone(params?: { timeout?: number; interval?: number; signal?: AbortSignal }): Promise<this> {
-    const checkDone = () => this.checkout().then((test) => ["done", "failed"].includes(test.status));
+  waitForDone(params?: {
+    timeout?: number;
+    interval?: number;
+    signal?: AbortSignal;
+    onCheckout?: (test: ClashTest, ready: boolean) => boolean;
+  }): Promise<this> {
+    const checkDone = () =>
+      this.checkout().then((test) => {
+        const ready = ["done", "failed"].includes(test.status);
+        const cancel = params?.onCheckout?.(test, ready);
+        return cancel || ready;
+      });
     return waitFor(checkDone, params).then(() => this);
   }