@equinor/fusion-framework-module-services 7.2.1 → 8.0.0

package/src/types.ts

@@ -6,22 +6,29 @@ import type {
 } from '@equinor/fusion-framework-module-http/client';
 
 /**
- * A factory function that creates an instance of an HTTP client.
+ * Factory function that creates a named HTTP client instance.
  *
- * @param name - The name of the HTTP client to create.
- * @returns A Promise that resolves to an instance of the HTTP client.
+ * Used by {@link ApiProvider} to resolve service-specific HTTP clients
+ * (for example, `'bookmarks'`, `'context'`, `'notification'`, `'people'`).
+ * The factory first checks registered HTTP clients, then falls back to
+ * service discovery.
+ *
+ * @template TClient - The HTTP client type to create.
+ * @param name - Logical service name used to look up or create the HTTP client.
+ * @returns A Promise that resolves to a configured HTTP client instance.
  */
 export type ApiClientFactory<TClient extends IHttpClient = IHttpClient> = (
   name: string,
 ) => Promise<TClient>;
 
 /**
- * Represents the arguments for an API client function.
+ * Tuple type representing the positional arguments passed to an HTTP client method.
+ *
+ * Used internally by endpoint generators to build the `[path, init]` pair
+ * that the HTTP client's `json()` or `json$()` method expects.
  *
- * @template TClient - The type of the HTTP client used by the API client.
- * @template TResult - The type of the result returned by the API client.
- * @param path - The path of the API endpoint.
- * @param init - Optional initialization options for the API client request.
+ * @template TClient - The HTTP client type that will execute the request.
+ * @template TResult - The expected response body type.
  */
 export type ApiClientArguments<TClient extends IHttpClient, TResult = unknown> = [
   path: string,
@@ -29,24 +36,42 @@ export type ApiClientArguments<TClient extends IHttpClient, TResult = unknown> =
 ];
 
 /**
- * Execute methods on the IHttpClient
+ * Maps HTTP client execution methods to their return types.
+ *
+ * - `json` — returns a `Promise` that resolves with the parsed JSON body.
+ * - `json$` — returns an RxJS-style `StreamResponse` observable.
+ *
+ * All versioned API client methods are generic over `ClientMethod`,
+ * allowing callers to choose between promise-based and observable-based
+ * consumption.
+ *
+ * @template T - The expected deserialized response body type.
  */
 export type ClientMethod<T = unknown> = {
-  /**
-   * Fetch JSON data from a service
-   */
+  /** Fetch JSON data from a service as a promise. */
   json: Promise<T>;
-  /**
-   * Fetch JSON data from a service as observable
-   */
+  /** Fetch JSON data from a service as an observable stream. */
   json$: StreamResponse<T>;
 };
 
+/**
+ * Maps HTTP client binary-data execution methods to their return types.
+ *
+ * - `blob` — returns a `Promise` that resolves with the binary blob result.
+ * - `blob$` — returns an RxJS-style `StreamResponse` observable for the blob.
+ *
+ * Used by endpoints that return non-JSON data such as profile photos.
+ *
+ * @template T - The blob result type, defaults to `BlobResult`.
+ */
 export type ClientDataMethod<T extends BlobResult = BlobResult> = {
+  /** Fetch binary data from a service as a promise. */
   blob: Promise<T>;
+  /** Fetch binary data from a service as an observable stream. */
   blob$: StreamResponse<T>;
 };
 
+/** Union of available client method names (`'json' | 'json$'`). */
 export type ClientMethodType = keyof ClientMethod;
 
 /**

package/src/utils.ts

@@ -9,12 +9,7 @@ import {
 import type { ExtractApiVersion } from './types';
 
 /**
- * Extracts the correct API version from the provided `apiVersions` object based on the given `version` parameter.
- *
- * @param apiVersions - An object mapping API version strings to their corresponding versions.
- * @param version - The version string to extract.
- * @returns The extracted API version, or throws an error if the version is not supported.
- */
+ * Resolves an API version string from a named key or raw version value.\n *\n * Looks up `version` as a key in `apiVersions` first; if not found,\n * searches the object values for a direct match. Throws when neither\n * lookup succeeds.\n *\n * @template TApiVersions - Record mapping version names to version strings.\n * @template TAllowedApiVersion - Allowed version constraint.\n * @template TVersion - The version string provided by the caller.\n * @param apiVersions - Map of version names to version strings.\n * @param version - Version key or raw version string to resolve.\n * @returns The resolved API version string.\n * @throws {Error} When the version is not found in `apiVersions`.\n *\n * @example\n * ```ts\n * enum ApiVersions { v1 = '1.0', v2 = '2.0' }\n * extractVersion(ApiVersions, 'v1'); // '1.0'\n * extractVersion(ApiVersions, '1.0'); // '1.0'\n * ```\n */
 export const extractVersion = <
   TApiVersions extends Record<string, string>,
   TAllowedApiVersion extends string,
@@ -34,11 +29,7 @@ export const extractVersion = <
 };
 
 /**
- * Creates a response selector that parses the response body using the provided Zod schema.
- *
- * @param schema - The Zod schema to use for parsing the response body.
- * @returns A response selector function that parses the response body using the provided schema.
- */
+ * Creates a response selector that parses the HTTP response body with a Zod schema.\n *\n * Combines the built-in `jsonSelector` with Zod validation, ensuring the\n * response body matches the expected shape at runtime.\n *\n * @template Output - The validated output type produced by the schema.\n * @param schema - The Zod schema used to parse and validate the response body.\n * @returns A `ResponseSelector` that extracts JSON and runs it through `schema.parse`.\n *\n * @example\n * ```ts\n * import { z } from 'zod';\n * const UserSchema = z.object({ id: z.string(), name: z.string() });\n * const selector = schemaSelector(UserSchema);\n * ```\n */
 export const schemaSelector =
   <Output>(schema: z.ZodSchema<Output>): ResponseSelector<Output> =>
   async (response: FetchResponse<unknown>) =>

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '7.2.1';
+export const version = '8.0.0';