@kosdev-code/kos-dispense-sdk 2.0.2

package/models/utils/extension-utils.d.ts

@@ -0,0 +1,265 @@
+import { SelectedPourable } from '../models/nozzle/types';
+import { BeverageResponse } from '../models/nozzle/services';
+import { IngredientResponse } from '../models/ingredient/services';
+import { HolderModel } from '../models/holder/types';
+import { HolderResponse } from '../models/holder/services';
+import { AssemblyTypes } from '../models';
+import { CoreExtensionManager, DataLoader, DataMapper, IndexExtension, PropertyMapper } from '@kosdev-code/kos-ui-sdk';
+
+export type IngredientDataMapper<AdditionalData extends object = Record<string, any>> = DataMapper<IngredientResponse, AdditionalData, any>;
+/**
+ * Mapping function that maps an ingredient response into the type property of
+ * the {@link IngredientModel}.
+ */
+export type IngredientTypeMapper<T extends IngredientResponse = IngredientResponse> = PropertyMapper<T, string>;
+/**
+ * Mapping function that maps additional data from holder service response
+ * into the {@link HolderModel} data.
+ */
+export type HolderTypeMapper<T extends HolderResponse = HolderResponse> = PropertyMapper<T, string>;
+/**
+ * Mapping function that maps additional data from holder service response
+ * into the {@link HolderModel} data.
+ */
+export type HolderDataMapper<AdditionalData extends object = Record<string, any>, HolderData extends HolderResponse = HolderResponse> = DataMapper<HolderData, AdditionalData, any>;
+export type GroupBeverageResponse = BeverageResponse & {
+    groupId: string;
+};
+export type AvailabilityDataMapper<AdditionalData extends object = Record<string, any>, AvailabilityData extends GroupBeverageResponse = GroupBeverageResponse> = DataMapper<AvailabilityData, AdditionalData, any>;
+export type SelectedPourableMapper = DataMapper<SelectedPourable, any>;
+export type BoardDataMapper<AdditionalData extends object = Record<string, any>, BoardData extends AssemblyTypes.AssemblyBoard<any> = AssemblyTypes.AssemblyBoard<any>> = DataMapper<BoardData, AdditionalData, any>;
+export type AssemblyMapper<AdditionalData extends object = Record<string, any>, AssemblyResponseData extends AssemblyTypes.AssemblyResponse<any> = AssemblyTypes.AssemblyResponse<any>> = DataMapper<AssemblyResponseData, AdditionalData, any>;
+/**
+ * The DispenseExtensionManager is responsible for managing the extension points that are specific to the Dispense application.
+ */
+export declare class DispenseExtensionManager {
+    core: CoreExtensionManager;
+    /**
+     * Maps data into the {@link IngredientModel}
+     *
+     * It is common for the ingredient data provided by the ingredient service to be augmented with additional properties that are
+     * not provided by the base kOS Ingredient model. The {@link IngredientMapper} extension point allows for the data to be mapped
+     * into the {@link IngredientModel} and the {@link IngredientModel.data} property to be augmented with additional properties.
+     *
+     * @example
+     * The following example shows how to map the data from the service response into the {@link IngredientModel}.
+     * The context is provided by the {@link IngredientLoader} extension point with its data being used to optionally augment the
+     * ingredient data.
+     *
+     * The result of the mapping will be available in the `data` property of the {@link IngredientModel}.
+     *
+     * In this case the `IngedientReponseData` interface represents the data being returned by the ingredient service and the
+     * `IngredientData` interface represents the data that will be available in the {@link IngredientModel.data} property.  The `ingredientDataMapper`
+     * is responsible for mapping from one format to the other.
+     *
+     * ```typescript
+     *
+     * interface IngredientResponseData extends NozzleServices.IngredientResponse {
+     *   chilled: boolean;
+     *   carbonated: boolean;
+     *   highYield: boolean;
+     * }
+     *
+     * interface IngredientData {
+     *   chilled: boolean;
+     *   carbonated: boolean;
+     *   highYield: boolean;
+     * }
+     *
+     * export const ingredientDataMapper = async (
+     * data: IngredientResponseData,
+     * context: IngredientContext
+     * ): Promise<IngredientData> => {
+     *  return {
+     *    chilled: data.chilled,
+     *    carbonated: data.carbonated,
+     *    highYield: data.highYield,
+     *  }
+     * }
+     * ```
+     * */
+    registerIngredientDataMapper(ingredientDataMapper: IngredientDataMapper): this;
+    /**
+     * Loads data that will be provided as context into the {@link IngredientMapper}
+     *
+     * @example
+     * The following example shows how to load the brandset data, normalize it into a map and then provide it back to the framework
+     * where it can be used by the other extension points.
+     *
+     * In the ingredient container model, the data is provided to the {@link IngredientMapper} extension point in order to augment ingredient data
+     * and also loaded into the ingredient container model context in order to make the data available throughout the code.
+     *
+     * ```typescript
+     *  export const ingredientContextLoader = async (): Promise<BeverageContext> => {
+     *  const response = await kosFetch('kos:/system/some/ingredient/endpoint.json');
+     *
+     *   if (response.status !== 200) {
+     *     KosLog.error('Failed to load ingredient data');
+     *       return {};
+     *   }
+     *  const json = await response.json();
+     *  return json;
+     *  };
+     * ```
+     * */
+    registerIngredientLoader(ingredientLoader: DataLoader): this;
+    registerIngredientIndex(ingredientIndex: IndexExtension): this;
+    /**
+     * Registers a data mapper for the {@link IngredientModel}
+     * */
+    registerIngredientTypeMapper(ingredientTypeMapper: IngredientTypeMapper): this;
+    /**
+     * Registers a data mapper for the {@link HolderModel} model.
+     * @param holderDataMapper - Mapping function that maps additional data from holder service response
+     * @returns
+     */
+    registerHolderDataMapper(holderDataMapper: HolderDataMapper): this;
+    registerHolderTypeMapper(holderTypeMapper: HolderTypeMapper): this;
+    /**
+     * Maps the ingredientId property of the holder into the {@link HolderModel}.
+     * If not provided, the ingredientId will assume that the value is mapped from the
+     * ingredientId property of the service response.
+     * */
+    registerHolderIngredientMapper(holderTypeMapper: HolderTypeMapper): this;
+    registerHolderIndex<T extends HolderModel = HolderModel>(holderIndex: IndexExtension<T>): this;
+    /**
+     * Maps data into the {@link AvailabilityModel}
+     *
+     * @example
+     * The following example shows how to map the data from the service response into the {@link AvailabilityModel}.
+     * The context is provided by the {@link AvailabilityLoader} extension point with its data being used to augment the
+     * availability data.
+     *
+     * The result of the mapping will be available in the `data` property of the {@link AvailabilityModel}.
+     *
+     * ```typescript
+     * export const beverageDataMapper = async (
+     * data: NozzleServices.BeverageResponse,
+     * context: BeverageContext
+     * ): Promise<BeverageData> => {
+     *  const id = data.altId;
+     *  const iconUrl = encodeURI(
+     *    `http://localhost:8081/system/brandset/${context?.[id]?.icon}`
+     *  );
+     *  const cuiColorCode = context?.[id]?.cuiColorCode
+     *    ? context?.[id]?.cuiColorCode
+     *    : '';
+     *  return { iconUrl, cuiColorCode };
+     * };
+     * ```
+     * */
+    registerAvailabilityDataMapper(availabilityMapper: AvailabilityDataMapper): this;
+    /**
+     * Loads data that will be provided as context into the {@link AvailabilityMapper}
+     *
+     * @example
+     * A common use case is to load brandset data that is UI specific and not provided directly by the Java service.
+     *
+     * The following example shows how to load the brandset data, normalize it into a map and then provide it back to the framework
+     * where it can be used by the other extension points.
+     *
+     * In the nozzle model, the data is provided to the {@link AvailabilityMapper} extension point in order to augment availability data
+     * and also loaded into the nozzle model context in order to make the data available throughout the code.
+     *
+     * ```typescript
+     *  export const beverageContextLoader = async (): Promise<BeverageContext> => {
+     *  const response = await kosFetch('kos:/system/brandset/brandset.json');
+     *
+     *   if (response.status !== 200) {
+     *     KosLog.error('Failed to load beverage data');
+     *       return {};
+     *   }
+     *   const json: BrandsetResponse | null = await response.json();
+     *   const initialBeverages: Record<string, BrandsetIngredient> = {};
+     *   const beverages = json?.ingredients?.reduce((acc, beverage) => {
+     *     acc[beverage.ingredientId] = beverage;
+     *     return acc;
+     *   }, initialBeverages);
+     *  return beverages;
+     *  };
+     * ```
+     * */
+    registerAvailabilityLoader(availabilityLoader: DataLoader): this;
+    /**
+     * Maps the abstract {@link SelectedPourable} data into a format that is specific to the nozzle.
+     * */
+    registerSelectedPourableDataMapper(selectedPourableMapper: SelectedPourableMapper): this;
+    /**
+     * Maps data into the {@link AssemblyModel} data.
+     * Used in cases where the base assembly has been extended with additional properties in the backend.  This extension
+     * point allows for the data to be mapped into the {@link AssemblyModel} and augmented with additional properties.
+     *
+     * @example
+     *
+     * In this example of an implementation of a {@link AssemblyMapper}, the {@link AssemblyResponse} data is mapped into
+     * a {@link FreestyleAssembly} object.
+     *
+     * The {@link FreestyleAssemblyResponse} interface represents the additional data being returned by the assembly service and is
+     * merged into the {@link AssemblyResponse} interface.
+     *
+     * The {@link FreestyleAssembly} interface represents the additional data, beyond the base data set, that will be merged into the {@link AssemblyModel}.
+     *
+     * The mapper is responsible for mapping from the {@link FreestyleAssemblyResponse} format to the {@link FreestyleAssembly} format.
+     * ```typescript
+     *  import { AssemblyTypes } from "@kosdev-code/kos-dispense-sdk";
+     *  import { DataMapper } from "@kosdev-code/kos-ui-sdk";
+     *
+     *  // define the additional data being returned by the assembly service
+     *  export interface FreestyleAssemblyResponse {
+     *    iceAgitator?: {
+     *      name: "iceAgitator";
+     *      path: string;
+     *    };
+     *  }
+     *
+     *  // define the additional data structure that will be merged into the assembly model
+     *  export interface FreestyleAssembly {
+     *    iceAgitator: {
+     *      path: string;
+     *    };
+     *    carbAgitator: {
+     *      path: string;
+     *    };
+     *  }
+     *
+     *
+     *  // define the mapper that will map the data from the service response into the additional data structure
+     *  // that will be merged into the assembly model.
+     *  // In this case the mapper is responsible for mapping from the {@link FreestyleAssemblyResponse} format to the {@link FreestyleAssembly} format.
+     *  export const assemblyDataMapper: DataMapper<
+     *    AssemblyTypes.AssemblyResponse<FreestyleAssemblyResponse>,
+     *    FreestyleAssembly
+     *    > = async (data) => {
+     *    const response = data.assemblies.reduce((acc, assembly) => {
+     *      const agitatorKeys = ["iceAgitator", "carbAgitator"];
+     *      agitatorKeys.forEach((key) => {
+     *        const agitator = assembly[key];
+     *        if (agitator) {
+     *          acc[key] = agitator;
+     *        }
+     *      });
+     *
+     *      return acc;
+     *    }, {} as FreestyleAssembly);
+     *    return response;
+     *  };
+     *```
+     */
+    registerAssemblyDataMapper(assemblyDataMapper: AssemblyMapper): this;
+    registerBoardIndex(boardIndex: IndexExtension): this;
+    registerBoardDataMapper(boardDataMapper: BoardDataMapper<any, any>): this;
+}
+/**
+ * The KosExtensionManager provides access to the extension points that are provided in the SDK for Dispense applications.
+ *
+ * The extension points are divided into two categories:
+ *
+ * @param core - The core extension {@link CoreExtensionManager}  points are used to extend the base models that are provided by the SDK.
+ * @param dispense -  The dispense extension {@link DispenseExtensionManager} points are used to extend the models that are specific to the Dispense SDK.
+ */
+export declare class KosExtensionManager {
+    dispense: DispenseExtensionManager;
+    core: CoreExtensionManager;
+    constructor();
+}
+//# sourceMappingURL=extension-utils.d.ts.map

package/models/utils/extension-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-utils.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-dispense-sdk/src/models/utils/extension-utils.ts"],"names":[],"mappings":"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"}