Merge pull request #6 from feat/optional-return-payload

Make return values of Graphic methods optionally be undefined

Author: nytamin

CHANGELOG.md

@@ -17,3 +17,5 @@ The log below details the changes during development of this version:
 * 2025-05-16: Add `renderRequirements` property to Graphics manifest
 * 2025-05-16: Add `data` argument to the `load` method.
   Before, the `data`-payload was only sent using the `updateData()` method. Now it must be sent on `load()` as well.
+* 2025-05-16: Change return values of Graphic methods to optionally be `undefined`.
+  (An `undefined` value should be treated as `{ code: 200 }`)

v1-draft-0/specification/docs/Specification.md

@@ -175,10 +175,11 @@ Depending on the rendering capabilities (defined in the Manifest file), a Graphi
 To describe the functions in this document, the Typescript interface notation is used. For simplicity, we omit the indication
 that vendor-specific fields can be included in both request and response payloads.
 For the 'action' methods (`playAction()`, `stopAction()`, `updateAction()` and `customAction()`), a Promise MUST be returned that
-resolves to an `ReturnPayload` object containing the following fields:
+resolves to `undefined` or to an `ReturnPayload` object containing the following fields:
 * `code`: a number that corresponds to an HTTP status code (2xx indicates a successful result, 4xx and 5xx indicate an error).
 * `message`: an optional human-readable message that corresponds to the `code`.
 * `result`: an optional Graphics-specific response object.
+If the returned Promise resolves to `undefined`, it should be treated as a `{ code: 200 }`.
 
 Similarly, for simplicity reasons, we omit these three fields in the description of the functions below.
 In [Typescript interface](#typescript-interface-for-graphic), the full interface is provided.

v1-draft-0/typescript-definitions/src/apis/graphicsAPI.ts

@@ -37,7 +37,7 @@ export interface Graphic {
       /** A set of characteristics / capabilities of the Renderer, that affects how the Graphic will be rendered. */
       renderCharacteristics: RenderCharacteristics;
     } & VendorExtend
-  ) => Promise<ReturnPayload>;
+  ) => Promise<ReturnPayload | undefined>;
 
   /**
    * Called by the Renderer to force the Graphic to terminate/dispose/clear any loaded resources.
@@ -51,7 +51,7 @@ export interface Graphic {
       /** The data send here is defined in the manifest "schema". Note: This data MUST HAVE the same type as the `data` argument in the load method.  */
       data: unknown;
     } & VendorExtend
-  ) => Promise<ReturnPayload>;
+  ) => Promise<ReturnPayload | undefined>;
 
   /** This is called when user calls the "play" action. */
   playAction: (
@@ -68,21 +68,23 @@ export interface Graphic {
   /** This is called when user calls the "stop" action. */
   stopAction: (
     params: { skipAnimation: boolean } & VendorExtend
-  ) => Promise<ReturnPayload>;
+  ) => Promise<ReturnPayload | undefined>;
 
   /**
    * Called by the Renderer to invoke an Action on the Graphic
    * @returns The return value of the invoked method (vendor-specific)
    */
-  customAction: (params: ActionInvokeParams) => Promise<ReturnPayload>;
+  customAction: (
+    params: ActionInvokeParams
+  ) => Promise<ReturnPayload | undefined>;
 
   /**
    * If the Graphic supports non-realtime rendering, this is called to make the graphic jump to a certain point in time.
    * @returns A Promise that resolves when the Graphic has finished rendering the requested frame.
    */
   goToTime: (
     params: { timestamp: number } & VendorExtend
-  ) => Promise<ReturnPayload>;
+  ) => Promise<ReturnPayload | undefined>;
 
   /**
    * If the Graphic supports non-realtime rendering, this is called to schedule actions to be invoked at a certain point in time.
@@ -116,6 +118,5 @@ export interface Graphic {
             } & VendorExtend);
       }[];
     } & VendorExtend
-  ) => Promise<EmptyPayload>;
+  ) => Promise<EmptyPayload | undefined>;
 }
-

v1-draft-0/typescript-definitions/src/definitions/types.ts

@@ -42,7 +42,7 @@ export type ActionInvokeParams = {
   payload: unknown;
 } & VendorExtend;
 
-export type PlayActionReturnPayload = ReturnPayload & {
+export type PlayActionReturnPayload = (ReturnPayload | {}) & {
   /** The resulting step from a PlayAction */
-  currentStep: number
-}
+  currentStep: number;
+};