Improved return type definitions

Author: bastianeicher

endpoints/Endpoint.ts

@@ -226,7 +226,7 @@ export class Endpoint {
      * Shows whether the server has indicated that a specific HTTP method is currently allowed.
      * Uses cached data from last response.
      * @param method The HTTP methods (e.g. GET, POST, ...) to check.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
     protected isMethodAllowed(method: HttpMethod): boolean | undefined {
         if (this.allowedMethods.length === 0)

endpoints/EntryEndpoint.ts

@@ -41,7 +41,5 @@ export class EntryEndpoint extends Endpoint {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async readMeta(): Promise<void> {
-        await this.send(HttpMethod.Get);
-    }
+    async readMeta() { await this.send(HttpMethod.Get); }
 }

endpoints/generic/CollectionEndpoint.ts

@@ -22,35 +22,31 @@ export class CollectionEndpoint<TEntity> extends GenericCollectionEndpoint<TEnti
      * @throws {@link AuthorizationError}: {@link HttpStatusCode.Forbidden}
      * @throws {@link HttpError}: Other non-success status code
      */
-    contains(element: (TEntity | string)): Promise<boolean> {
-        return this.get(element).exists();
-    }
+    contains(element: (TEntity | string)) { return this.get(element).exists(); }
 
     /**
      * Sets/replaces an existing element in the collection.
      * @param element The new state of the element.
+     * @returns The `TEntity` as returned by the server, possibly with additional fields set. undefined if the server does not respond with a result entity.
      * @throws {@link BadRequestError}: {@link HttpStatusCode.BadRequest}
      * @throws {@link AuthenticationError}: {@link HttpStatusCode.Unauthorized}
      * @throws {@link AuthorizationError}: {@link HttpStatusCode.Forbidden}
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    set(element: TEntity): Promise<void | TEntity> {
-        return this.get(element).set(element);
-    }
+    set(element: TEntity) { return this.get(element).set(element); }
 
     /**
      * Modifies an existing element in the collection by merging changes on the server-side.
      * @param element The `TEntity` data to merge with the existing element.
+     * @returns The `TEntity` as returned by the server, possibly with additional fields set. undefined if the server does not respond with a result entity.
      * @throws {@link BadRequestError}: {@link HttpStatusCode.BadRequest}
      * @throws {@link AuthenticationError}: {@link HttpStatusCode.Unauthorized}
      * @throws {@link AuthorizationError}: {@link HttpStatusCode.Forbidden}
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    merge(element: TEntity): Promise<void | TEntity> {
-        return this.get(element).merge(element);
-    }
+    merge(element: TEntity) { return this.get(element).merge(element); }
 
     /**
      * Deletes an existing element from the collection.
@@ -60,7 +56,5 @@ export class CollectionEndpoint<TEntity> extends GenericCollectionEndpoint<TEnti
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    delete(element: (TEntity | string)): Promise<void> {
-        return this.get(element).delete();
-    }
+    delete(element: (TEntity | string)) { return this.get(element).delete(); }
 }

endpoints/generic/ElementEndpoint.ts

@@ -33,17 +33,15 @@ export class ElementEndpoint<TEntity> extends ETagEndpointBase {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async read(): Promise<TEntity> {
-        return this.serializer.deserialize<TEntity>(await this.getContent());
-    }
+    async read() { return this.serializer.deserialize<TEntity>(await this.getContent()); }
 
     /**
      * Determines whether the element currently exists.
      * @throws {@link AuthenticationError}: {@link HttpStatusCode.Unauthorized}
      * @throws {@link AuthorizationError}: {@link HttpStatusCode.Forbidden}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async exists(): Promise<boolean> {
+    async exists() {
         const response = await this.httpClient.send(this.uri, HttpMethod.Head);
         if (response.ok) return true;
         if (response.status === HttpStatusCode.NotFound || response.status === HttpStatusCode.Gone) return false;
@@ -55,15 +53,14 @@ export class ElementEndpoint<TEntity> extends ETagEndpointBase {
     /**
      * Shows whether the server has indicated that {@link set} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get setAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Put);
-    }
+    get setAllowed() { return this.isMethodAllowed(HttpMethod.Put); }
 
     /**
      * Sets/replaces the `TEntity`.
      * @param entity The new `TEntity`.
+     * @returns The `TEntity` as returned by the server, possibly with additional fields set. undefined if the server does not respond with a result entity.
      * @throws {@link ConcurrencyError}: The entity has changed since it was last retrieved with {@link read}. Your changes were rejected to prevent a lost update.
      * @throws {@link BadRequestError}: {@link HttpStatusCode.BadRequest}
      * @throws {@link AuthenticationError}: {@link HttpStatusCode.Unauthorized}
@@ -82,15 +79,14 @@ export class ElementEndpoint<TEntity> extends ETagEndpointBase {
     /**
      * Shows whether the server has indicated that {@link merge} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get mergeAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Patch);
-    }
+    get mergeAllowed() { return this.isMethodAllowed(HttpMethod.Patch); }
 
     /**
      * Modifies an existing `TEntity` by merging changes on the server-side.
      * @param entity The `TEntity` data to merge with the existing element.
+     * @returns The `TEntity` as returned by the server, possibly with additional fields set. undefined if the server does not respond with a result entity.
      * @throws {@link ConcurrencyError}: The entity has changed since it was last retrieved with {@link read}. Your changes were rejected to prevent a lost update.
      * @throws {@link BadRequestError}: {@link HttpStatusCode.BadRequest}
      * @throws {@link AuthenticationError}: {@link HttpStatusCode.Unauthorized}
@@ -114,6 +110,7 @@ export class ElementEndpoint<TEntity> extends ETagEndpointBase {
      * Reads the current state of the entity, applies a change to it and stores the result. Applies optimistic concurrency using automatic retries.
      * @param updateAction A callback that takes the current state of the entity and applies the desired modifications.
      * @param maxRetries The maximum number of retries to perform for optimistic concurrency before giving up.
+     * @returns The `TEntity` as returned by the server, possibly with additional fields set. undefined if the server does not respond with a result entity.
      * @throws {@link ConcurrencyError}: The maximum number of retries to perform for optimistic concurrency before giving up.
      * @throws {@link BadRequestError}: {@link HttpStatusCode.BadRequest}
      * @throws {@link AuthenticationError}: {@link HttpStatusCode.Unauthorized}
@@ -138,11 +135,9 @@ export class ElementEndpoint<TEntity> extends ETagEndpointBase {
     /**
      * Shows whether the server has indicated that {@link delete} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get deleteAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Delete);
-    }
+    get deleteAllowed() { return this.isMethodAllowed(HttpMethod.Delete); }
 
     /**
      * Deletes the element.
@@ -152,7 +147,5 @@ export class ElementEndpoint<TEntity> extends ETagEndpointBase {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async delete(): Promise<void> {
-        await this.deleteContent();
-    }
+    async delete() { await this.deleteContent(); }
 }

endpoints/generic/GenericCollectionEndpoint.ts

@@ -39,28 +39,23 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Endpoin
     /**
      * Shows whether the server has indicated that {@link readAll} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get readAllAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Get);
-    }
+    get readAllAllowed() { return this.isMethodAllowed(HttpMethod.Get); }
 
-    async readAll(): Promise<TEntity[]> {
-        return this.serializer.deserialize<TEntity[]>(await this.getContent());
-    }
+    async readAll() { return this.serializer.deserialize<TEntity[]>(await this.getContent()); }
 
     /**
      * Shows whether the server has indicated that {@link create} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get createAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Post);
-    }
+    get createAllowed() { return this.isMethodAllowed(HttpMethod.Post); }
 
     /**
      * Adds a `TEntity` as a new element to the collection.
      * @param entity The new `TEntity`.
+     * @returns The `TEntity` as returned by the server, possibly with additional fields set. undefined if the server does not respond with a result entity.
      * @throws {@link BadRequestError}: {@link HttpStatusCode.BadRequest}
      * @throws {@link AuthenticationError}: {@link HttpStatusCode.Unauthorized}
      * @throws {@link AuthorizationError}: {@link HttpStatusCode.Forbidden}
@@ -83,11 +78,9 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Endpoin
     /**
      * Shows whether the server has indicated that {@link createAll} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get createAllAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Patch);
-    }
+    get createAllAllowed() { return this.isMethodAllowed(HttpMethod.Patch); }
 
     /**
      * Adds (or updates) multiple `TEntity`s as elements in the collection.
@@ -98,7 +91,7 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Endpoin
      * @throws {@link ConflictError}: {@link HttpStatusCode.Conflict}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async createAll(entities: TEntity[]): Promise<void> {
+    async createAll(entities: TEntity[]) {
         await this.send(HttpMethod.Patch, {
             [HttpHeader.ContentType]: this.serializer.supportedMediaTypes[0]
         }, this.serializer.serialize(entities));
@@ -107,11 +100,9 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Endpoin
     /**
      * Shows whether the server has indicated that {@link setAll} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get setAllAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Put);
-    }
+    get setAllAllowed() { return this.isMethodAllowed(HttpMethod.Put); }
 
     /**
      *  Replaces the entire content of the collection with new `TEntity`s.
@@ -122,7 +113,5 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Endpoin
      * @throws {@link ConflictError}: {@link HttpStatusCode.Conflict}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async setAll(entities: TEntity[]): Promise<void> {
-        await this.putContent(entities);
-    }
+    async setAll(entities: TEntity[]) { await this.putContent(entities); }
 }

endpoints/raw/BlobEndpoint.ts

@@ -18,18 +18,14 @@ export class BlobEndpoint extends Endpoint {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async probe(): Promise<void> {
-        await this.send(HttpMethod.Options);
-    }
+    async probe() { await this.send(HttpMethod.Options); }
 
     /**
      * Shows whether the server has indicated that {@link download} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get downloadAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Get);
-    }
+    get downloadAllowed() { return this.isMethodAllowed(HttpMethod.Get); }
 
     /**
      * Downloads the blob's content.
@@ -47,11 +43,9 @@ export class BlobEndpoint extends Endpoint {
     /**
      * Shows whether the server has indicated that {@link upload} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get uploadAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Put);
-    }
+    get uploadAllowed() { return this.isMethodAllowed(HttpMethod.Put); }
 
     /**
      * Uploads data as the blob's content.
@@ -61,18 +55,14 @@ export class BlobEndpoint extends Endpoint {
      * @throws {@link AuthorizationError}: {@link HttpStatusCode.Forbidden}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async upload(blob: Blob): Promise<void> {
-        await this.send(HttpMethod.Put, { [HttpHeader.ContentType]: blob.type }, blob);
-    }
+    async upload(blob: Blob) { await this.send(HttpMethod.Put, { [HttpHeader.ContentType]: blob.type }, blob); }
 
     /**
      * Shows whether the server has indicated that {@link delete} is currently allowed.
      * Uses cached data from last response.
-     * @returns An indicator whether the method is allowed. If no request has been sent yet or the server did not specify allowed methods `undefined` is returned.
+     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` If no request has been sent yet or the server did not specify allowed methods.
      */
-    get deleteAllowed(): boolean | undefined {
-        return this.isMethodAllowed(HttpMethod.Delete);
-    }
+    get deleteAllowed() { return this.isMethodAllowed(HttpMethod.Delete); }
 
     /**
      * Deletes the blob from the server.
@@ -82,7 +72,5 @@ export class BlobEndpoint extends Endpoint {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async delete(): Promise<void> {
-        await this.send(HttpMethod.Delete);
-    }
+    async delete() { await this.send(HttpMethod.Delete); }
 }

endpoints/raw/UploadEndpoint.ts

@@ -23,7 +23,7 @@ export class UploadEndpoint extends Endpoint {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async upload(blob: Blob, fileName?: string): Promise<void> {
+    async upload(blob: Blob, fileName?: string) {
         if (this.formField) {
             const formData = new FormData();
             formData.set(this.formField, blob, fileName);

endpoints/rpc/ActionEndpoint.ts

@@ -22,7 +22,5 @@ export class ActionEndpoint extends RpcEndpointBase {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async invoke(): Promise<void> {
-        await this.send(HttpMethod.Post);
-    }
+    async invoke() { await this.send(HttpMethod.Post); }
 }

endpoints/rpc/ConsumerEndpoint.ts

@@ -24,7 +24,7 @@ export class ConsumerEndpoint<TEntity> extends RpcEndpointBase {
      * @throws {@link NotFoundError}: {@link HttpStatusCode.NotFound} or {@link HttpStatusCode.Gone}
      * @throws {@link HttpError}: Other non-success status code
      */
-    async invoke(entity: TEntity): Promise<void> {
+    async invoke(entity: TEntity) {
         await this.send(HttpMethod.Post, {
             [HttpHeader.ContentType]: this.serializer.supportedMediaTypes[0]
         }, this.serializer.serialize(entity));