@tridion-sites/models 0.1.3 → 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# Tridion Sites models for Extensions
+
+This NPM package provides a set of domain models specifically designed for frontend development of Tridion Sites. These models encapsulate domain-specific logic and provide a convenient abstraction for interacting with the backend data.
+
+## Note
+
+Due to reliance on various functionality provided at runtime by Tridion Sites, this package is not suitable for standalone usage and can only be utilized as a part of an extension.
+
+## Features
+
+-   Class-based definitions allow for easy item type checks
+-   Quality of life utilities provided as class instance methods
+-   Handling of TCM / ECL URI formats
+-   Easy conversion from and to `@tridion-sites/open-api-client` objects
+
+## Installation
+
+To install `@tridion-sites/models`, you can use npm or yarn:
+
+```bash
+$ npm install @tridion-sites/models
+# or
+$ yarn add @tridion-sites/models
+```
+
+## Mapping to and from the backend data
+
+### Converting from a `@tridion-sites/open-api-client` response to a model
+
+Primary utility methods for conversion of the backend DTOs to models are:
+
+-   `tryMapToModel<TModel>(backendDto)` - maps provided dto to a model, returns `undefined` on failure.
+    <b>Important</b>: generic argument is provided to simplify usage of the utility. It doesn't check that the provided type actually corresponds with the realtime type after the conversion.
+-   `mapToModel<TModel>(backendDto)` - convenience method that throws an error instead of returning `undefined` if conversion has failed.
+-   `mapToModels<TModel>(backendDto[])` - maps an array of backend DTOs to models, returning only successfully mapped objects.
+
+```typescript
+import type { ActivityInstance, ItemUri } from '@tridion-sites/models';
+import { mapToModel } from '@tridion-sites/models';
+import { ItemsService } from '@tridion-sites/open-api-client';
+
+const getActivityById = async (activityId: ItemUri) => {
+    const activity = await ItemsService.getItem(activityId.asString);
+    return mapToModel<ActivityInstance>(activity);
+};
+```
+
+### Converting from a model to a `@tridion-sites/open-api-client` DTO
+
+Every model contains `.getInternalModel()` method that allows to get the underlying backend DTO.
+
+```typescript
+import { IdentifiableObject } from '@tridion-sites/models';
+import { ItemsService } from '@tridion-sites/open-api-client';
+
+const updateItem = async (item: IdentifiableObject) => {
+    const backendDto = item.getInternalModel();
+    await ItemsService.update(backendDto.Id, backendDto);
+};
+```
+
+## Item URI handling
+
+There are 2 primary methods for parsing string URIs:
+
+-   `tryParseItemUri` - parses a string into an ItemUri object. Returns `undefined` if the conversion has failed
+-   `parseItemUri` - convenience method that throws an error instead of returning `undefined` if conversion has failed.
+
+## API Documentation
+
+Documentation for all available models, their methods and model utilities can be found at
+http://developers.rws.com/tridion-sites-extensions-api-docs/models.html

package/dist/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * This NPM package provides a set of domain models specifically designed for frontend development of Tridion Sites.
+ * These models encapsulate domain-specific logic and provide a convenient abstraction for interacting with the backend data.
+ *
+ * @remarks
+ * Due to reliance on various functionality provided at runtime by Tridion Sites,
+ * this package is not suitable for standalone usage and can only be utilized as a part of an extension.
+ *
+ * @packageDocumentation
+ */
+
 import type { AccessControlEntry as AccessControlEntry_2 } from '@tridion-sites/open-api-client';
 import type { AccessControlList as AccessControlList_2 } from '@tridion-sites/open-api-client';
 import type { AccessToken as AccessToken_2 } from '@tridion-sites/open-api-client';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tridion-sites/models",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "Tridion Sites models",
   "author": "RWS",
   "homepage": "https://www.rws.com",
@@ -9,13 +9,6 @@
   "main": "dist/index.js",
   "module": "dist/index.js",
   "typings": "dist/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "https://stash.sdl.com/scm/tdx/tridion-sites.git"
-  },
-  "bugs": {
-    "url": "https://jira.sdl.com/projects/DXUI/issues/"
-  },
   "files": [
     "dist/**/*"
   ],
@@ -31,7 +24,7 @@
     "test:ci": "jest --verbose --reporters='default' --reporters='jest-junit'"
   },
   "dependencies": {
-    "@tridion-sites/open-api-client": "1.0.5",
+    "@tridion-sites/open-api-client": "2.0.0",
     "immer": "9.0.16"
   },
   "devDependencies": {

package/CHANGELOG.md

@@ -1,60 +0,0 @@
-# @tridion-sites/models
-
-## 0.1.3
-
-### Patch Changes
-
--   be9284a536: rename a property
-
-## 0.1.2
-
-### Patch Changes
-
--   b803ef7b33: Fake models now have special creation functions
--   9b78d6d626: upgrade dependencies
--   31bdf04adf: fixed VersionedItem isNew behavior
-
-## 0.1.1
-
-### Patch Changes
-
--   226cc4cce1: Additional info for Taxonomies model is added
--   1845a12377: use the latest typescript version
--   Updated dependencies [1845a12377]
-    -   @tridion-sites/open-api-client@1.0.5
-
-## 0.1.0
-
-### Minor Changes
-
--   Set of small improvements and fixes to the extensions framework
-
-## 0.0.5
-
-### Patch Changes
-
--   update packages
-
-## 0.0.4
-
-### Patch Changes
-
--   include node_modules into the build
-
-## 0.0.3
-
-### Patch Changes
-
--   include node_modules into the build
-
-## 0.0.2
-
-### Patch Changes
-
--   release new package version for extensions, extensions-cli, models, open-api-client
--   c616d80f3c: fixed circular dependencies in @tridion-sites/models
--   117e9e5f76: Models package became public
--   Updated dependencies
--   Updated dependencies [0738aa9ac3]
--   Updated dependencies [ff20566f80]
-    -   @tridion-sites/open-api-client@1.0.4