ts-forge 1.0.0 → 1.0.1-beta.0

package/CHANGELOG.md

@@ -1,4 +1,11 @@
+## v1.0.1-beta.0
+
+- README.md: documentation finished
+- Updated dev dependencies
+- Improved type definitions for getDefinitionsForClass function
+
 ## v1.0.0
 
 - `@Resolver()` and `@ResolverFn()` decorators were created
 - Created `getDefinitionsForClass()` function which handles resolver functions definition
+- Unit testing for decorators and utils

package/README.md

@@ -1,5 +1,67 @@
 **Warning:** The first version of this library is ready, however documentation is still in progress
 
+This library allows you to define resolvers for your Atlassian Forge addon using decorators. It uses the `@forge/resolver` library under the hood to define resolvers, but it provides a more convenient way to define them using decorators.
+
+## Table of contents
+
+- [Introduction](#introduction)
+- [Table of Contents](#table-of-contents)
+- [Installation](#installation)
+- [@Resolver](#resolver)
+- [@ResolverFn](#resolverfn)
+- [getDefinitionsForClass](#getdefinitionsforclass)
+- [Middlewares](#middlewares)
+- [Error handler](#error-handler)
+
+[![npm version](https://badge.fury.io/js/ts-forge.svg)](https://badge.fury.io/js/ts-forge)
+[![npm downloads](https://img.shields.io/npm/dm/ts-forge.svg)](https://www.npmjs.com/package/ts-forge)
+
+## Introduction
+
+This library is designed to make it easier to define resolvers in your Atlassian Forge addon using TypeScript decorators. It allows you to define resolvers, middlewares, and error handlers in a more structured and readable way, while still leveraging the power of the `@forge/resolver` library.
+
+It provides two main decorators: `@Resolver` and `@ResolverFn`, which can be used to define resolvers and their configurations. Additionally, it provides a function `getDefinitionsForClass` to get the definitions of the resolvers you created.
+
+When you create a resolver, you typically would do something like this:
+
+```ts
+import Resolver "@forge/resolver";
+
+const resolver = new Resolver();
+
+resolver.define("hello", async (req) => {
+  try {
+    return { message: "Hello world!" };
+  } catch(error)  {
+    console.error("An error occurred:", error);
+
+    return { status: "error", message: "An error occurred" };
+  }
+});
+
+resolver.define("update-user", async (req) => {
+  try {
+    // Update user logic...
+
+    return { status: "success", message: "User updated successfully" };
+  } catch(error) {
+    console.error("An error occurred:", error);
+
+    return { status: "error", message: "An error occurred" };
+  }
+});
+
+export const definitions = resolver.getDefinitions();
+```
+
+## Installation
+
+This is a Node.js module available on npm. Make sure you have `@forge/resolver` installed as well, since this library uses it under the hood. The minimum version of `@forge/resolver` required is `^1.6.0`.
+
+```bash
+npm install ts-forge
+```
+
 ## @Resolver
 
 ```ts
@@ -225,4 +287,99 @@ const definitions = getDefinitionsForClass({
 
 ## Error handler
 
-An error handler is a function that is called when an error is thrown in a resolver function
+An error handler is a function that allows you to handle errors thrown in your resolver functions or middlewares. It can be defined in `@ResolverFn()`, `@Resolver()` and `getDefinitionsForClass()`.
+
+When an error is thrown, the error handler will be called with the error and the request object, allowing you to handle the error and return a response to the frontend.
+
+When an error is thrown, the error handler will be called in the following order:
+
+1. If an error handler is defined in the `@ResolverFn()` decorator, it will be called
+2. Error handler defined in `@Resolver()`, will be called when an error handler was not defined in `@ResolverFn()`
+3. If no error handler was defined in `@ResolverFn()` and `@Resolver()`, the error handler defined in `getDefinitionsForClass()` will be called
+4. If no error handler was defined in any of the above, the error will be logged to the console and will be returned to the frontend
+
+#### Usage
+
+This is an example of an error handler function
+
+```ts
+import { Request } from "@forge/resolver";
+
+function myErrorHandler(error: any, request: Request): any | Promise<any> {
+  // Handle the error and return a response
+  console.error("An error occurred:", error);
+
+  return { status: "error", message: "An error occurred" };
+}
+```
+
+Then you can use this error handler in `@ResolverFn()`, `@Resolver()` or `getDefinitionsForClass()`
+In the following example the `myErrorHandler` error handler is used in `@ResolverFn()`. This is useful when you want certain error handler to be called for some resolver functions
+
+```ts
+@Resolver()
+class HelloWorldResolver {
+  @ResolverFn({
+    key: "hello-world",
+    errorHandler: myErrorHandler
+  })
+  async helloWorld() {
+    // Do whatever this resolver should do
+  }
+
+  // myErrorHandler won't be called when an error is thrown in this resolver function
+  @ResolverFn("get-current-user")
+  async getCurrentUser() {
+    // Return current user
+  }
+}
+```
+
+In this example the `myErrorHandler` error handler is used in `@Resolver()`. Error handlers defined in this decorator will be called for all resolver functions defined in the class.
+
+```ts
+@Resolver({
+  // Error handler defined in this function will be called if an error is thrown in any of the resolver functions defined in this class
+  errorHandler: myErrorHandler
+})
+class HelloWorldResolver {
+  // There's no need to add the same error handler in @ResolverFn()
+  @ResolverFn("hello-world")
+  async helloWorld() {
+    // Do whatever this resolver should do
+  }
+
+  // myErrorHandler will also be called if an error is thrown in this resolver function
+  @ResolverFn("get-current-user")
+  async getCurrentUser() {
+    // Return current user
+  }
+}
+```
+
+Last but not least, you can define an error handler in the `getDefinitionsForClass` function. Error handlers defined here will be called if an error is thrown in any of the resolvers that you pass to the `resolvers` array.
+
+```ts
+@Resolver()
+class HelloWorldResolver {
+  @ResolverFn("hello-world")
+  helloWorld(request: Request) {
+    return { message: "Hello world!" };
+  }
+}
+
+@Resolver()
+class UserResolver {
+  @ResolverFn("get-user")
+  getUser(request: Request) {
+    return {...};
+  }
+}
+
+const definitions = getDefinitionsForClass({
+  errorHandler: myErrorHandler,
+  // Error handler will be called if an error is thrown in any of the resolver functions
+  // You don't need to add the myErrorHandler error handler in @Resolver or @ResolverFn decorators
+  resolvers: [HelloWorldResolver, UserResolver]
+});
+```

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "ts-forge",
-  "version": "1.0.0",
+  "version": "1.0.1-beta.0",
   "main": "dist/index.js",
   "scripts": {
-    "test": "vitest --run",
-    "test:ui": "vitest --ui",
-    "test:watch": "vitest",
-    "test:coverage": "vitest --run --coverage",
+    "test": "vitest --run --coverage",
+    "test:ui": "vitest --ui --coverage",
     "dev": "tsc -p ./tsconfig.json --watch",
     "build": "eval $(rm -r dist) && tsc -p ./tsconfig.json",
     "prepublish": "npm run build"
@@ -27,9 +25,9 @@
     "@forge/resolver": ">=1.6.0 <2.0.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "3.1.4",
-    "jsdom": "^26.1.0",
-    "typescript": "5.8.3",
-    "vitest": "^3.1.4"
+    "@vitest/coverage-v8": "4.0.8",
+    "jsdom": "^27.1.0",
+    "typescript": "5.9.3",
+    "vitest": "^4.0.8"
   }
 }