@mittwald/api-models - npm Package Compare versions

Comparing version 0.1.0-alpha.1 to 0.1.0-alpha.2

package.json

 {
   "name": "@mittwald/api-models",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "author": "Mittwald CM Service GmbH & Co. KG <[e-mail]>",
@@ -22,11 +22,10 @@ "type": "module",
     ".": {
-      "types": "./dist/index.d.mts",
-      "default": "./dist/index.mjs"
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
     },
     "./react": {
-      "types": "./dist/react.d.mts",
-      "default": "./dist/react.mjs"
+      "types": "./dist/types/react.d.ts",
+      "import": "./dist/esm/react.js"
     }
   },
-  "types": "./dist/index.d.ts",
   "files": [
@@ -36,19 +35,19 @@ "dist"
   "scripts": {
-    "build": "unbuild",
+    "build": "run build:clean && run tsc",
+    "build:clean": "rimraf dist",
     "test": "node --experimental-vm-modules $(yarn bin jest)"
   },
   "dependencies": {
-    "@mittwald/api-client-commons": "^4.2.0",
-    "@mittwald/react-use-promise": "^2.1.2",
+    "@mittwald/api-client": "^3.1.59",
     "another-deep-freeze": "^1.0.0",
     "polytype": "^0.17.0",
-    "type-fest": "^4.9.0"
+    "type-fest": "^4.10.3"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
-    "@mittwald/api-client": "*",
-    "@types/jest": "^29.5.11",
-    "@types/react": "^18.2.47",
-    "@typescript-eslint/eslint-plugin": "^6.18.1",
-    "@typescript-eslint/parser": "^6.18.1",
+    "@mittwald/react-use-promise": "^2.3.12",
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.2.57",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
     "eslint": "^8.56.0",
@@ -59,25 +58,19 @@ "eslint-config-prettier": "^9.1.0",
     "jest": "^29.7.0",
-    "prettier": "^3.1.1",
+    "prettier": "^3.2.5",
     "react": "^18.2.0",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.3.3",
-    "unbuild": "^2.0.0"
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
   },
   "peerDependencies": {
-    "@mittwald/api-client": "*",
-    "react": "^18.2.0"
+    "@mittwald/react-use-promise": "^2.3.12"
   },
   "peerDependenciesMeta": {
+    "@mittwald/react-use-promise": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }
-  },
-  "unbuild": {
-    "declaration": true,
-    "sourcemap": true,
-    "externals": [
-      "react",
-      "axios"
-    ]
   }
-}
+}

README.md

@@ -23,14 +23,10 @@ # mittwald API models
 
-You will need an initialized API client in order to operate with the models
-provided by this package. Provide it to the `setupApiBehaviors` method before
-any model operation is executed.
+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 { setupApiBehaviors } from "@mittwald/api-models";
-import { MittwaldAPIV2Client } from "@mittwald/api-client";
+import { api } from "@mittwald/api-models";
 
-// See the documentation of @mittwald/api-client for alternative methods of
-// client initialization: https://www.npmjs.com/package/@mittwald/api-client
-const client = MittwaldAPIClient.newUnauthenticated();
-setupApiBehaviors(client);
+api.setupWithApiToken(process.env.MW_API_TOKEN);
 ```
@@ -295,3 +291,3 @@
   public static async find(id: string): Promise<ProjectDetailed | undefined> {
-    const data = await Project.behaviors.find(id);
+    const data = await config.project.behaviors.find(id);
     if (data !== undefined) {
@@ -303,1 +299,102 @@ 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);
+      }
+    },
+  );
+}
+```

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Dependency count

5

decreased by-28.57%

Number of package files

126

increased by950%

Number of lines in readme file

398

increased by32.23%

Worsened metrics

Total package byte prevSize

82851

decreased by-95.79%

Lines of code

1536

decreased by-91.55%

Published versions last months

15

decreased by-6.25%

Dependency changes

• + Added@mittwald/api-client@^3.1.59

• + Added@mittwald/api-client@3.1.59(transitive)

• + Addedget-intrinsic@1.3.0(transitive)

• + Addedreact@19.0.0(transitive)

• - Removed@mittwald/api-client-commons@^4.2.0

• - Removed@mittwald/react-use-promise@^2.1.2

• - Removed@mittwald/api-client@4.108.0(transitive)

• - Removedget-intrinsic@1.2.7(transitive)

• - Removedjs-tokens@4.0.0(transitive)

• - Removedloose-envify@1.4.0(transitive)

• - Removedreact@18.3.1(transitive)

• Updatedtype-fest@^4.10.3