@tridion-sites/models 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @tridion-sites/models
 
+## 0.1.4
+
+### Patch Changes
+
+-   54439b54a7: removed links to internal systems, added readme files
+-   Updated dependencies [54439b54a7]
+    -   @tridion-sites/open-api-client@1.0.6
+
 ## 0.1.3
 
 ### Patch Changes

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": "0.1.4",
   "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": "1.0.6",
     "immer": "9.0.16"
   },
   "devDependencies": {