feat: make invoke generic

.changeset/sour-islands-move.md

@@ -0,0 +1,5 @@
+---
+"alcaeus": minor
+---
+
+Added generic type argument to operation `invoke` methods

docs/latest/representations/affordances/invoking-operations.md

@@ -37,6 +37,9 @@ await operation.invoke(JSON.stringify(newComment))
 
 </run-kit>
 
+> [!TIP]
+> TypeScript users can add a generic type argument to the method invocation to have the return type of the operation strongly typed to a resource model. For example `operation.invoke<Person>()` call.
+
 > [!WARNING]
 > Note that the `invoke` method does not accept objects. If the client operates on JSON-LD objects, the body must be stringified beforehand.
 

src/Resources/Operation.ts

@@ -1,12 +1,15 @@
 import type { Constructor, RdfResource } from '@tpluscode/rdfine'
+import type { RdfResourceCore } from '@tpluscode/rdfine/RdfResource'
+import type { DatasetCore } from '@rdfjs/types'
+import type { Resource } from '@rdfine/hydra'
 import type { HydraClient, HydraResponse } from '../alcaeus'
 import type * as Supported from './Mixins/Operation'
 
 export interface RuntimeOperation extends Supported.Operation {
     /**
      * Gets the title of the operation
      */
-    invoke(body?: BodyInit, headers?: HeadersInit): Promise<HydraResponse>
+    invoke<T extends RdfResourceCore = Resource>(body?: BodyInit, headers?: HeadersInit): Promise<HydraResponse<DatasetCore, T>>
 
     /**
      * Gets the resource on which the operation will be invoked
@@ -21,12 +24,12 @@ export function createMixin(client: HydraClient, target: RdfResource) {
                 return target
             }
 
-            public invoke(body?: BodyInit, headers?: HeadersInit): Promise<HydraResponse> {
+            public invoke<T extends RdfResourceCore<any> = Resource<DatasetCore>>(body?: BodyInit, headers?: HeadersInit): Promise<HydraResponse<DatasetCore, T>> {
                 if (body !== null && typeof body !== 'undefined' && headers !== null && typeof headers !== 'undefined') {
-                    return client.invokeOperation(this, headers, body)
+                    return client.invokeOperation<T>(this, headers, body)
                 }
 
-                return client.invokeOperation(this)
+                return client.invokeOperation<T>(this)
             }
         }
     }

src/alcaeus.ts

@@ -40,7 +40,7 @@ export interface HydraClient<D extends DatasetIndexed = DatasetIndexed> {
     parsers: SinkMap<EventEmitter, Stream>
     loadResource<T extends RdfResourceCore<any> = Resource<D>>(uri: string | NamedNode, headers?: HeadersInit): Promise<HydraResponse<D, T>>
     loadDocumentation(uri: string | NamedNode, headers?: HeadersInit): Promise<ApiDocumentation<D> | null>
-    invokeOperation(operation: InvokedOperation, headers?: HeadersInit, body?: BodyInit): Promise<HydraResponse<D>>
+    invokeOperation<T extends RdfResourceCore<any> = Resource<D>>(operation: InvokedOperation, headers?: HeadersInit, body?: BodyInit): Promise<HydraResponse<D, T>>
     defaultHeaders: HeadersInit | ((params: { uri: string }) => HeadersInit | Promise<HeadersInit>)
     resources: ResourceStore<D>
     apiDocumentations: ResourceRepresentation<D, ApiDocumentation<D>>[]
@@ -163,7 +163,7 @@ export class Alcaeus<D extends DatasetIndexed> implements HydraClient<D> {
         return null
     }
 
-    public async invokeOperation(operation: InvokedOperation, headers: HeadersInit, body?: BodyInit): Promise<HydraResponse<D>> {
+    public async invokeOperation<T extends RdfResourceCore<any> = Resource<D>>(operation: InvokedOperation, headers: HeadersInit, body?: BodyInit): Promise<HydraResponse<D, T>> {
         const uri = getAbsoluteUri(operation.target.id.value, this.baseUri)
         const mergedHeaders = await this.__mergeHeaders(new this._headers(headers), { uri })
 
@@ -194,7 +194,7 @@ export class Alcaeus<D extends DatasetIndexed> implements HydraClient<D> {
                 response,
             })
 
-            return resources.get(namedNode(response.resourceUri))!
+            return resources.get<T>(namedNode(response.resourceUri))!
         }
 
         return {