@aidc-toolkit/app-extension 1.0.31-beta → 1.0.32-beta

package/src/gs1/service-proxy.ts

@@ -0,0 +1,56 @@
+import { isNullish, type Nullishable } from "@aidc-toolkit/core";
+import { verifiedByGS1 } from "@aidc-toolkit/gs1";
+import { type ExtendsParameterDescriptor, type ParameterDescriptor, Types } from "../descriptor.js";
+import { LibProxy } from "../lib-proxy.js";
+import { proxy } from "../proxy.js";
+import type { ErrorExtends, Matrix, MatrixResult } from "../type.js";
+import { identifierParameterDescriptor, identifierTypeParameterDescriptor } from "./identifier-descriptor.js";
+import { validateIdentifierType } from "./identifier-type.js";
+
+const hyperlinkIdentifierParameterDescriptor: ExtendsParameterDescriptor = {
+    extendsDescriptor: identifierParameterDescriptor,
+    name: "hyperlinkIdentifier"
+};
+
+const hyperlinkTextParameterDescriptor: ParameterDescriptor = {
+    name: "hyperlinkText",
+    type: Types.String,
+    isMatrix: false,
+    isRequired: false
+};
+
+const hyperlinkDetailsParameterDescriptor: ParameterDescriptor = {
+    name: "hyperlinkDetails",
+    type: Types.String,
+    isMatrix: false,
+    isRequired: false
+};
+
+@proxy.describeClass(false, {
+    namespace: "GS1"
+})
+export class ServiceProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    @proxy.describeMethod({
+        type: Types.Any,
+        isMatrix: true,
+        requiresContext: true,
+        parameterDescriptors: [
+            identifierTypeParameterDescriptor,
+            hyperlinkIdentifierParameterDescriptor,
+            hyperlinkTextParameterDescriptor,
+            hyperlinkDetailsParameterDescriptor
+        ]
+    })
+    async verifiedByGS1(identifierType: string, matrixIdentifiers: Matrix<string>, text: Nullishable<string>, details: Nullishable<string>, invocationContext: Nullishable<TInvocationContext>): Promise<MatrixResult<unknown, ThrowError, TError>> {
+        if (isNullish(invocationContext)) {
+            // Application error; no localization necessary.
+            throw new Error("Invocation context not provided by application");
+        }
+
+        return this.appExtension.mapHyperlinkResults(invocationContext, this.setUpMatrixResult(() =>
+            validateIdentifierType(identifierType),
+        matrixIdentifiers, (validatedIdentifierType, identifier) =>
+            verifiedByGS1(validatedIdentifierType, identifier, text ?? undefined, details ?? undefined)
+        ));
+    }
+}

package/src/gs1/variable-measure-proxy.ts

@@ -0,0 +1,61 @@
+import { VariableMeasure } from "@aidc-toolkit/gs1";
+import { type ParameterDescriptor, Types } from "../descriptor.js";
+import { LibProxy } from "../lib-proxy.js";
+import { proxy } from "../proxy.js";
+import type { ErrorExtends, Matrix, MatrixResult } from "../type.js";
+
+const rcnFormatParameterDescriptor: ParameterDescriptor = {
+    name: "rcnFormat",
+    type: Types.String,
+    isMatrix: false,
+    isRequired: true
+};
+
+const rcnParameterDescriptor: ParameterDescriptor = {
+    name: "rcn",
+    type: Types.String,
+    isMatrix: true,
+    isRequired: true
+};
+
+const rcnItemReferenceParameterDescriptor: ParameterDescriptor = {
+    name: "rcnItemReference",
+    type: Types.Number,
+    isMatrix: false,
+    isRequired: true
+};
+
+const rcnPriceOrWeightParameterDescriptor: ParameterDescriptor = {
+    name: "rcnPriceOrWeight",
+    type: Types.Number,
+    isMatrix: true,
+    isRequired: true
+};
+
+@proxy.describeClass(false, {
+    namespace: "GS1"
+})
+export class VariableMeasureProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    @proxy.describeMethod({
+        type: Types.Number,
+        isMatrix: true,
+        parameterDescriptors: [rcnFormatParameterDescriptor, rcnParameterDescriptor]
+    })
+    parseVariableMeasureRCN(format: string, matrixRCNs: Matrix<string>): MatrixResult<number, ThrowError, TError> {
+        return this.arrayResult(matrixRCNs, (rcn) => {
+            const rcnReference = VariableMeasure.parseRCN(format, rcn);
+
+            return [rcnReference.itemReference, rcnReference.priceOrWeight];
+        });
+    }
+
+    @proxy.describeMethod({
+        type: Types.String,
+        isMatrix: true,
+        ignoreInfix: true,
+        parameterDescriptors: [rcnFormatParameterDescriptor, rcnItemReferenceParameterDescriptor, rcnPriceOrWeightParameterDescriptor]
+    })
+    createVariableMeasureRCN(format: string, itemReference: number, matrixPricesOrWeights: Matrix<number>): MatrixResult<string, ThrowError, TError> {
+        return this.matrixResult(matrixPricesOrWeights, priceOrWeight => VariableMeasure.createRCN(format, itemReference, priceOrWeight));
+    }
+}

package/src/index.ts

@@ -15,12 +15,18 @@
  * limitations under the License.
  */
 export * from "./locale/i18n.js";
+
 export type * from "./type.js";
+export * from "./app-data.js";
+
+export type * from "./streaming.js";
 export * from "./app-extension.js";
 export * from "./lib-proxy.js";
+
 export * from "./descriptor.js";
 export * from "./app-utility-proxy.js";
 export * from "./utility/index.js";
 export * as GS1 from "./gs1/index.js";
+
 export * from "./generator/index.js";
 export { expandParameterDescriptor } from "./proxy.js";

package/src/lib-proxy.ts

@@ -1,7 +1,7 @@
 import { mapIterable } from "@aidc-toolkit/utility";
 import type { AppExtension } from "./app-extension.js";
 import { i18nextAppExtension } from "./locale/i18n.js";
-import type { ErrorExtends, Matrix, MatrixResultError, ResultError } from "./type.js";
+import type { ErrorExtends, Matrix, MatrixResult, SingletonResult } from "./type.js";
 
 /**
  * Library proxy.
@@ -15,14 +15,17 @@ import type { ErrorExtends, Matrix, MatrixResultError, ResultError } from "./typ
  * @template TInvocationContext
  * Application-specific invocation context type.
  *
+ * @template TStreamingInvocationContext
+ * Application-specific streaming invocation context type.
+ * 
  * @template TBigInt
  * Type to which big integer is mapped.
  */
-export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> {
+export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     /**
      * Application extension.
      */
-    readonly #appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>;
+    readonly #appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>;
 
     /**
      * Constructor.
@@ -30,14 +33,14 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
      * @param appExtension
      * Application extension.
      */
-    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>) {
         this.#appExtension = appExtension;
     }
 
     /**
      * Get the application extension.
      */
-    get appExtension(): AppExtension<ThrowError, TError, TInvocationContext, TBigInt> {
+    get appExtension(): AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
         return this.#appExtension;
     }
 
@@ -50,12 +53,13 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
      * @returns
      * Mapped big integer value.
      */
-    mapBigInt(value: bigint): ResultError<TBigInt, ThrowError, TError> {
+    mapBigInt(value: bigint): SingletonResult<TBigInt, ThrowError, TError> {
         return this.#appExtension.mapBigInt(value);
     }
 
     /**
-     * Handle an error thrown by a function call.
+     * Handle an error thrown by a function call. Return type is {@linkcode SingletonResult} to ensure assignment
+     * compatibility.
      *
      * @param e
      * Error.
@@ -63,8 +67,8 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
      * @returns
      * Error if errors are not thrown.
      */
-    #handleError<TResult>(e: unknown): ResultError<TResult, ThrowError, TError> {
-        let result: ResultError<TResult, ThrowError, TError>;
+    #handleError<TResult>(e: unknown): SingletonResult<TResult, ThrowError, TError> {
+        let result: SingletonResult<TResult, ThrowError, TError>;
 
         if (e instanceof RangeError) {
             const error = this.#appExtension.mapRangeError(e);
@@ -74,34 +78,30 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
                 throw error as Error;
             }
 
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type determination is handled above.
-            result = error as ResultError<TResult, ThrowError, TError>;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Won't get here if ThrowError is false so result is TError.
+            result = error as SingletonResult<TResult, ThrowError, TError>;
         } else {
-            // Unknown error; pass up the stack.
-            // eslint-disable-next-line @typescript-eslint/only-throw-error -- Error is being passed on from elsewhere.
-            throw e;
+            // Unknown error; pass on to application extension.
+            result = this.appExtension.handleError(e instanceof Error ? e.message : String(e));
         }
 
         return result;
     }
 
     /**
-     * Do the callback for a simple return.
-     *
-     * @param value
-     * Value.
+     * Call a singleton result function with error handling.
      *
      * @param callback
      * Callback.
      *
      * @returns
-     * Callback result or error if errors are not thrown.
+     * Callback return or error if errors are not thrown.
      */
-    #doCallback<TValue, TResult>(value: TValue, callback: (value: TValue) => TResult): ResultError<TResult, ThrowError, TError> {
-        let result: ResultError<TResult, ThrowError, TError>;
+    singletonResult<TResult>(callback: () => SingletonResult<TResult, ThrowError, TError>): SingletonResult<TResult, ThrowError, TError> {
+        let result: SingletonResult<TResult, ThrowError, TError>;
 
         try {
-            result = callback(value);
+            result = callback();
         } catch (e: unknown) {
             result = this.#handleError(e);
         }
@@ -110,19 +110,60 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
     }
 
     /**
-     * Map a matrix of values using a callback.
+     * Call a matrix result function with error handling.
      *
      * @param matrixValues
      * Matrix of values.
      *
-     * @param callback
-     * Callback.
+     * @param valueCallback
+     * Callback to process value.
      *
      * @returns
      * Matrix of callback results and errors if errors are not thrown.
      */
-    protected mapMatrix<TValue, TResult>(matrixValues: Matrix<TValue>, callback: (value: TValue) => TResult): MatrixResultError<TResult, ThrowError, TError> {
-        return matrixValues.map(rowValues => rowValues.map(value => this.#doCallback(value, callback)));
+    protected matrixResult<TValue, TResult>(matrixValues: Matrix<TValue>, valueCallback: (value: TValue) => SingletonResult<TResult, ThrowError, TError>): MatrixResult<TResult, ThrowError, TError> {
+        return matrixValues.map(rowValues => rowValues.map(value => this.singletonResult(() => valueCallback(value))));
+    }
+
+    /**
+     * Map a matrix of validate string results to boolean. If the string is empty, the result is true, indicating that
+     * there is no error.
+     *
+     * @param matrixValidateResults
+     * Matrix of results from a call to a validate function.
+     *
+     * @returns
+     * Matrix of boolean values, true if corresponding string is empty.
+     */
+    protected isValidString(matrixValidateResults: MatrixResult<string, ThrowError, TError>): Matrix<boolean> {
+        return matrixValidateResults.map(rowValues => rowValues.map(value => (validateResult => validateResult === "")(value)));
+    }
+
+    /**
+     * Set up a mapping and call a matrix result function with error handling.
+     *
+     * @param setUpCallback
+     * Callback to set up the mapping.
+     *
+     * @param matrixValues
+     * Matrix of values.
+     *
+     * @param valueCallback
+     * Callback to process value.
+     *
+     * @returns
+     * Matrix of callback results and errors if errors are not thrown.
+     */
+    protected setUpMatrixResult<TSetup, TValue, TResult>(setUpCallback: () => TSetup, matrixValues: Matrix<TValue>, valueCallback: (setup: TSetup, value: TValue) => SingletonResult<TResult, ThrowError, TError>): MatrixResult<TResult, ThrowError, TError> {
+        let result: MatrixResult<TResult, ThrowError, TError>;
+
+        try {
+            result = matrixValues.map(rowValues => rowValues.map(value => this.singletonResult(() => valueCallback(setUpCallback(), value))));
+        } catch (e: unknown) {
+            result = [[this.#handleError(e)]];
+        }
+
+        return result;
     }
 
     /**
@@ -137,15 +178,15 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
      * @returns
      * Callback result or error as array if errors are not thrown.
      */
-    #doArrayCallback<TValue, TResult>(value: TValue, callback: (value: TValue) => TResult[]): Array<ResultError<TResult, ThrowError, TError>> {
-        const result = this.#doCallback(value, callback);
+    #arrayCallback<TValue, TResult>(value: TValue, callback: (value: TValue) => Array<SingletonResult<TResult, ThrowError, TError>>): Array<SingletonResult<TResult, ThrowError, TError>> {
+        const result = this.singletonResult(() => callback(value));
 
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Type determination is handled.
-        return result instanceof Array ? result : [result as ResultError<TResult, ThrowError, TError>];
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- If result is not an array, it must be an error.
+        return result instanceof Array ? result : [result as SingletonResult<TResult, ThrowError, TError>];
     }
 
     /**
-     * Map a one-dimensional matrix of values using a callback.
+     * Call an array result function with error handling and map to a matrix.
      *
      * @param matrixValues
      * Matrix of values.
@@ -156,65 +197,62 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
      * @returns
      * Matrix of callback results and errors if errors are not thrown.
      */
-    protected mapArray<TValue, TResult>(matrixValues: Matrix<TValue>, callback: (value: TValue) => TResult[]): MatrixResultError<TResult, ThrowError, TError> {
-        let matrixResultError: MatrixResultError<TResult, ThrowError, TError>;
+    protected arrayResult<TValue, TResult>(matrixValues: Matrix<TValue>, callback: (value: TValue) => Array<SingletonResult<TResult, ThrowError, TError>>): MatrixResult<TResult, ThrowError, TError> {
+        let result: MatrixResult<TResult, ThrowError, TError>;
 
         if (matrixValues.length === 0) {
             // Special case; unlikely to occur.
-            matrixResultError = [[]];
+            result = [[]];
         } else if (matrixValues.length === 1) {
-            matrixResultError = [];
+            result = [];
 
             matrixValues[0].forEach((value, columnIndex) => {
-                const arrayResultError = this.#doArrayCallback(value, callback);
+                const arrayResult = this.#arrayCallback(value, callback);
 
-                arrayResultError.forEach((resultError, rowIndex) => {
-                    if (matrixResultError.length <= rowIndex) {
-                        matrixResultError.push([]);
+                arrayResult.forEach((resultError, rowIndex) => {
+                    // Append a row if necessary.
+                    if (result.length <= rowIndex) {
+                        result.push([]);
                     }
 
-                    // Assignment will automatically expand array.
-                    matrixResultError[rowIndex][columnIndex] = resultError;
+                    // Assignment will automatically expand row to the number of columns in the matrix.
+                    result[rowIndex][columnIndex] = resultError;
                 });
             });
         } else {
-            matrixResultError = matrixValues.map((rowValue) => {
-                let arrayResultError: Array<ResultError<TResult, ThrowError, TError>>;
+            result = matrixValues.map((rowValue) => {
+                let arrayResult: Array<SingletonResult<TResult, ThrowError, TError>>;
 
                 if (rowValue.length === 0) {
                     // Special case; unlikely to occur.
-                    arrayResultError = [];
+                    arrayResult = [];
                 } else if (rowValue.length === 1) {
-                    arrayResultError = this.#doArrayCallback(rowValue[0], callback);
+                    arrayResult = this.#arrayCallback(rowValue[0], callback);
                 } else {
-                    arrayResultError = [this.#handleError(new RangeError(i18nextAppExtension.t("Proxy.matrixMustBeArray")))];
+                    arrayResult = [this.#handleError(new RangeError(i18nextAppExtension.t("Proxy.matrixMustBeArray")))];
                 }
 
-                return arrayResultError;
+                return arrayResult;
             });
         }
 
-        return matrixResultError;
+        return result;
     }
 
     /**
-     * Map a matrix of values to a matrix of strings via a callback that either returns or throws a range error. If the
-     * callback returns, the result for that element is the empty string; otherwise, if it's a range error, the result
-     * for that element is the error message.
+     * Call a matrix result function with error handling and map a non-error result to an empty string and {@linkcode
+     * RangeError} to the string error message.
      *
      * @param matrixValues
-     * Matrix to map.
+     * Matrix of values.
      *
      * @param callback
      * Callback that either returns or throws an exception.
      *
      * @returns
      * Matrix of strings.
-     *
-     * @template TValue
-     * Value type.
      */
-    protected static mapMatrixRangeError<TValue>(matrixValues: Matrix<TValue>, callback: (value: TValue) => void): Matrix<string> {
+    protected matrixErrorResult<TValue>(matrixValues: Matrix<TValue>, callback: (value: TValue) => void): Matrix<string> {
         return matrixValues.map(rowValues => rowValues.map((value) => {
             let result: string;
 
@@ -229,11 +267,7 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
                     result = e.message;
                 } else {
                     // Unknown error; pass up the stack.
-                    throw e instanceof Error ?
-                        e :
-                        new Error("Unknown error", {
-                            cause: e
-                        });
+                    throw e;
                 }
             }
 
@@ -242,18 +276,26 @@ export abstract class LibProxy<ThrowError extends boolean, TError extends ErrorE
     }
 
     /**
-     * Convert an iterable result of a callback to a matrix result. Although the natural approach would be to map to a
-     * single-element array containing an array of *N* results (i.e., [[r0, r1, r2, ..., r*N*]]), this is rendered
-     * visually as a single row. The more readable approach is as a single column, so the mapping is to an *N*-element
-     * array of single-element result arrays (i.e., [[r0], [r1], [r2], ..., [r*N*]]).
+     * Call an iterable result function with error handling and map to a matrix. Although the natural approach would be
+     * to map to a single-element array containing an array of *N* results (i.e., [[r0, r1, r2, ..., r*N*]]), this is
+     * rendered visually as a single row. The more readable approach is as a single column, so the mapping is to an
+     * *N*-element array of single-element result arrays (i.e., [[r0], [r1], [r2], ..., [r*N*]]).
      *
-     * @param iterableResult
-     * Iterable result.
+     * @param iterableCallback
+     * Iterable callback.
      *
      * @returns
      * Matrix of callback results.
      */
-    protected static matrixResult<TResult>(iterableResult: Iterable<TResult>): Matrix<TResult> {
-        return Array.from(mapIterable(iterableResult, result => [result]));
+    protected iterableResult<TResult>(iterableCallback: () => Iterable<SingletonResult<TResult, ThrowError, TError>>): MatrixResult<TResult, ThrowError, TError> {
+        let result: MatrixResult<TResult, ThrowError, TError>;
+
+        try {
+            result = Array.from(mapIterable(iterableCallback(), result => [result]));
+        } catch (e: unknown) {
+            result = [[this.#handleError(e)]];
+        }
+
+        return result;
     }
 }