@mittwald/api-models 0.0.0-development-04b7288-20240610

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mittwald CM Service GmbH & Co. KG and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,397 @@
+# mittwald API models
+
+This package contains a collection of domain models for coherent interaction
+with the mittwald API.
+
+## License
+
+Copyright (c) 2023 Mittwald CM Service GmbH & Co. KG and contributors
+
+This project (and all NPM packages) therein is licensed under the MIT License;
+see the [LICENSE](../../LICENSE) file for details.
+
+## Installing
+
+You can install this package from the regular NPM registry:
+
+```shell
+yarn add @mittwald/api-models
+```
+
+## Setup
+
+You will need to initialize an API client in order to operate with the models
+provided by this package. Use the `api` global instance for initialization with
+some methods.
+
+```typescript
+import { api } from "@mittwald/api-models";
+
+api.setupWithApiToken(process.env.MW_API_TOKEN);
+```
+
+## Examples
+
+- A **`Reference`** or `ReferenceModel` represents a certain model just by its
+  ID.
+- A **`DetailedModel`** contains all the data of the resource.
+
+For a more detailed description refer to the section
+[Type of models](#Type-of-models)
+
+```typescript
+// Get a detailed project
+const detailedProject = await Project.get("p-vka9t3");
+
+// Create a project reference
+const projectRef = Project.ofId("p-vka9t3");
+
+// Get the detailed project from the reference
+const anotherDetailedProject = await projectRef.getDetailed();
+
+// Update project description
+await detailedProject.updateDescription("My new description!");
+
+// This method just needs the ID and a description and
+// thus is also available on the reference
+await projectRef.updateDescription("My new description!");
+
+// Accessing the projects server reference
+const server = project.server;
+
+// List all projects of this server
+const serversProjects = await server.listProjects();
+
+// List all projects
+const allProjects = await Project.list();
+
+// Iterate over project List Models
+for (const project of serversProjects) {
+  await project.leave();
+}
+```
+
+## Usage in React
+
+This package also provides methods aligned to be used in React components. It
+uses
+[@mittwald/react-use-promise](https://www.npmjs.com/package/@mittwald/react-use-promise)
+to encapsulate all asynchronous functions into AsyncResources. More details
+about how to use AsyncResources see the package documentation.
+
+### Installation
+
+To use the React client you have to install the additional
+`@mittwald/react-use-promise` package:
+
+```shell
+yarn add @mittwald/react-use-promise
+```
+
+All asynchronous methods provide a `use`-method property. This method uses
+[@mittwald/react-use-promise](https://www.npmjs.com/package/@mittwald/react-use-promise)
+under the hood to "resolve" the promise in the "React way".
+
+```typescript
+const detailedProject = Project.get.use("p-vka9t3");
+
+// Create a project reference
+const projectRef = Project.ofId("p-vka9t3");
+
+// Get the detailed project from the reference
+const anotherDetailedProject = projectRef.getDetailed.use();
+
+// Accessing the projects server reference
+const server = project.server;
+
+// List all projects of this server
+const serversProjects = server.listProjects.use();
+
+// List all projects
+const allProjects = Project.list.use();
+```
+
+## Immutability and state updates
+
+Most of all models provided by this package represent an associated counter-part
+in the backend. When a model is loaded from the backend, the current state is
+incorporated into the model instance. To keep it simple and predictable this
+**state is immutable and does not change under any circumstances**. As a result
+you must create a new instance to get an updated model and propagate it
+throughout the runtime code.
+
+This also applies for operations initiated at client-side. For example when the
+`updateDescription` method is called on a project, the project instance will
+still have the old description.
+
+"Watching for changes" is not scope of this package and will be implemented in
+future releases or other packages™️.
+
+## Contribute
+
+**As a general advice when contributing, be sure to look at the existing source
+code and use it as a template!**
+
+Please consider the following conventions when adding or modifying models.
+
+### File structure
+
+Structure the models in meaningful directories.
+
+### Use the base classes
+
+Models should extend (or inherit) the correct base class. You can find the base
+classes in `src/base`. The following classes are available.
+
+#### `DataModel`
+
+The DataModel is the foundation of all model classes that contain a set of
+immutable generic data.
+
+#### `ReferenceModel`
+
+A ReferenceModel represents a certain model just by its ID. As the most basic
+model operations often just need the ID and some input data (deleting, renaming,
+...), Reference Models can avoid unnecessary API round trips.
+
+### Stick to the ubiquitous language
+
+When adding models or methods pay close attention to the (maybe existing)
+language used in the respective domain. Talk to the responsible team if you are
+uncertain.
+
+### Models as abstraction layer
+
+Models should cover the following aspects:
+
+- Coherent representation of the business logic
+- Simple loading of models and their linked entities
+- Methods to interact with the model in an intuitive way
+- Preprocessing of the models raw data to increase DX
+- Consistent API
+
+### Type of models
+
+#### Detailed vs. List Models
+
+The response type for some models often differs when loading single items or
+lists. To reduce the amount of data, the list response type is usually a subset
+of the comprehensive model. Add separate classes for the Detailed Model (name it
+`[Model]Detailed`) and the List Model (name it `[Model]ListItem`).
+
+If both model share a common code base, you should add a Common Model (name it
+`[Model]Common`).
+
+#### Reference Models
+
+A Reference Model represents a certain model just by its ID. As the most basic
+model operations often just need the ID and some input data (deleting, renaming,
+...), Reference Models can avoid unnecessary API round trips. These classes
+should be used as a return type for newly created models or for linked models.
+
+To get the actual Detailed Model, Reference Models _must_ have a
+`function getDetailed(): Promise<ModelDetailed>` method.
+
+Consider extending the Reference Model when implementing the Entry-Point Model.
+
+#### Implementation details
+
+When implementing shared functionality, like in the Common Models, you can use
+the [`polytype`](https://www.npmjs.com/package/polytype) library to realize
+dynamic multiple inheritance. Be sure to look at the existing source code for
+implementation examples.
+
+#### Entry-Point Model
+
+Provide a single model (name it `[Model]`) as an entry point for all different
+model types (detailed, list, ...). As a convention provide a default export for
+this model.
+
+### Use the correct verbs
+
+#### `find`
+
+Entry-Point models should have a static `find` method. The find method returns
+the detailed model or may return `undefined` if the model can not be found.
+
+#### `get`
+
+In addition to the `find` method Entry-Point models should have a static `get`
+method. The get method should return the desired object or throw an
+`ObjectNotFoundError`. You can use the `find` method and assert the existence
+with the `assertObjectFound` function.
+
+#### `list`
+
+When a list of objects should be loaded use a `list` method. It may support a
+`query` parameter to filter the result by given criteria.
+
+#### `create`
+
+When a model should be created use a static `create` method. This method should
+return a reference of the created resource.
+
+### Accessing "linked" models
+
+Most of the models are part of a larger model tree. Models should provide
+methods to get the parent and child models, like `project.getServer()`,
+`server.listProjects()` or `server.getCustomer()`. Use `get`, `list` or `find`
+prefixes as described above.
+
+#### Use Reference Models resp. Entry-Point Models when possible!
+
+If a linked model provides a Reference Model or Entry-point Model, create it in
+the model constructor, to avoid unnecessary API round trips.
+
+### Abstraction of model behaviors
+
+Models are usually backed by a set of behaviors, defining the basic model
+interactions. In order to actually "use" the model, it must be initialized with
+a concrete behavior implementation. This layer of abstraction removes
+implementation specific code from the model, and also makes behaviors
+exchangeable without any impact on the model itself - for example inside unit
+tests.
+
+Consider using behaviors for:
+
+- API interactions
+- Storing and loading local data
+- Complex computations or logic (maybe supported by an external library)
+
+#### Encapsulate API interaction inside behaviors
+
+Encapsulate any API interaction inside the model behaviors to prevent strong
+coupling of model and API-specific implementation.
+
+##### Don't 🥴
+
+```typescript
+class ProjectDetailed {
+  public static async find(
+    id: string,
+  ): Promise<ProjProjectDetailed | undefined> {
+    const response = await client.project.getProject({
+      id,
+    });
+
+    if (response.status === 200) {
+      return new Project(response.data.id, response.data);
+    }
+    assertStatus(response, 403);
+  }
+}
+```
+
+##### Do 😃
+
+```typescript
+class ProjectDetailed {
+  public static async find(id: string): Promise<ProjectDetailed | undefined> {
+    const data = await config.project.behaviors.find(id);
+    if (data !== undefined) {
+      return new Project(data.id, data);
+    }
+  }
+}
+```
+
+#### How-to implement behaviors
+
+Place a `behaviors` folder inside the model that should look like this:
+
+```
+Project/
+├─ behaviors/
+│  ├─ index.ts
+│  ├─ types.ts (behavior interface)
+│  ├─ api.ts   (behavior implementation)
+│  ├─ inmem.ts (behavior implementation)
+
+```
+
+##### Define `types.ts` first
+
+It is a good starting point to first implement the interface for the behavior.
+The interface usually just defines methods used in the behavior. Like
+
+```ts
+export interface ProjectBehaviors {
+  find: (id: string) => Promise<ProjectData | undefined>;
+  updateDescription: (projectId: string, description: string) => Promise<void>;
+}
+```
+
+Then register the behavior in the global behavior configuration
+`packages/models/src/config/config.ts`.
+
+##### Use the behaviors in the model
+
+If the behavior interface is defined, you can start implementing the model. You
+can also first implement the concrete API behavior, to "proof" the behavior is
+"working" with the real API.
+
+```ts
+import { config } from "../../config/config.js";
+
+class ProjectDetailed {
+  public static async find(id: string): Promise<ProjectDetailed | undefined> {
+    const data = await config.project.behaviors.find(id);
+    if (data !== undefined) {
+      return new Project(data.id, data);
+    }
+  }
+}
+```
+
+##### Implement the API behavior
+
+The API behavior depends on an API client. You can implement the behavior as an
+object factory, or a simple class implementing the interface. When using the
+object factory, you do not have to redeclare the method parameter types.
+
+Do the implementation specific stuff, thus preparing and executing the request,
+and finally processing the response.
+
+```ts
+import { ProjectBehaviors } from "./types.js";
+import { assertStatus, MittwaldAPIV2Client } from "@mittwald/api-client";
+
+export const apiProjectBehaviors = (
+  client: MittwaldAPIV2Client,
+): ProjectBehaviors => ({
+  find: async (id) => {
+    const response = await client.project.getProject({
+      projectId: id,
+    });
+
+    if (response.status === 200) {
+      return response.data;
+    }
+    assertStatus(response, 403);
+  },
+});
+```
+
+### Prepare for React
+
+All asynchronous methods should provide a `use`-method property. This method
+uses
+[@mittwald/react-use-promise](https://www.npmjs.com/package/@mittwald/react-use-promise)
+under the hood to "resolve" the promise in the "React way".
+
+To provide this feature to your _async_ model methods, wrap the actual method
+with the `provideReact` enhancer.
+
+```ts
+class ProjectDetailed {
+  public static find = provideReact(
+    async (id: string): Promise<ProjectDetailed | undefined> => {
+      const data = await config.behaviors.project.find(id);
+
+      if (data !== undefined) {
+        return new ProjectDetailed(data);
+      }
+    },
+  );
+}
+```

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@mittwald/api-models",
+  "version": "0.0.0-development-04b7288-20240610",
+  "author": "Mittwald CM Service GmbH & Co. KG <opensource@mittwald.de>",
+  "type": "module",
+  "description": "Collection of domain models for coherent interaction with the API",
+  "keywords": [
+    "api",
+    "client",
+    "mittwald",
+    "rest",
+    "sdk"
+  ],
+  "homepage": "https://developer.mittwald.de",
+  "repository": "github:mittwald/api-client-js",
+  "bugs": {
+    "url": "https://github.com/mittwald/api-client-js/issues"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./react": {
+      "types": "./dist/types/react.d.ts",
+      "import": "./dist/esm/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "run build:clean && run tsc",
+    "build:clean": "rimraf dist",
+    "lint": "run eslint .",
+    "test": "node --experimental-vm-modules $(yarn bin jest)"
+  },
+  "dependencies": {
+    "@mittwald/api-client": "^0.0.0-development-04b7288-20240610",
+    "another-deep-freeze": "^1.0.0",
+    "polytype": "^0.17.0",
+    "type-fest": "^4.12.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@mittwald/react-use-promise": "^2.3.12",
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.2.64",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-json": "^3.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.5",
+    "react": "^18.2.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.2"
+  },
+  "peerDependencies": {
+    "@mittwald/react-use-promise": "^2.3.12"
+  },
+  "peerDependenciesMeta": {
+    "@mittwald/react-use-promise": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "gitHead": "97660b1fee614cc23b778573ba3e8ae75a961517"
+}