@aidc-toolkit/app-extension 0.9.19-beta

package/src/app-utility-proxy.ts

@@ -0,0 +1,266 @@
+import { type ParameterDescriptor, ProxyClass, ProxyMethod, ProxyParameter, Type } from "./descriptor.js";
+import { LibProxy } from "./lib-proxy.js";
+import { i18nextAppExtension } from "./locale/i18n.js";
+import { type ErrorExtends, isNullish, type Matrix, type NonNullishable, type Nullishable } from "./types.js";
+
+const spillMatrix: ParameterDescriptor = {
+    name: "spillMatrix",
+    type: Type.Any,
+    isMatrix: true,
+    isRequired: true
+};
+
+const spillMaximumParameterDescriptor: ParameterDescriptor = {
+    name: "spillMaximum",
+    type: Type.Number,
+    isMatrix: false,
+    isRequired: false
+};
+
+const spillMaximumWidthParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: spillMaximumParameterDescriptor,
+    sortOrder: 0,
+    name: "spillMaximumWidth"
+};
+
+const spillMaximumHeightParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: spillMaximumParameterDescriptor,
+    sortOrder: 1,
+    name: "spillMaximumHeight"
+};
+
+/**
+ * Maximum dimensions.
+ */
+interface MaximumDimensions {
+    /**
+     * Optional maximum width.
+     */
+    width: Nullishable<number>;
+
+    /**
+     * Optional maximum height.
+     */
+    height: Nullishable<number>;
+}
+
+/**
+ * Application utilities.
+ */
+@ProxyClass()
+export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    /**
+     * Get the version.
+     *
+     * @returns
+     * Version.
+     */
+    @ProxyMethod({
+        type: Type.String,
+        isMatrix: false
+    })
+    version(): string {
+        return this.appExtension.version;
+    }
+
+    /**
+     * Provide default values for maximum width and height if required.
+     *
+     * @param maximumDimensions
+     * Maximum dimensions provided to function.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @returns
+     * Array of maximum width and maximum height.
+     */
+    private async defaultMaximums(maximumDimensions: MaximumDimensions, invocationContext: Nullishable<TInvocationContext>): Promise<NonNullishable<MaximumDimensions>> {
+        if (isNullish(invocationContext)) {
+            // Application error; no localization necessary.
+            throw new Error("Invocation context not provided by application");
+        }
+
+        const maximumWidth = maximumDimensions.width;
+        const maximumHeight = maximumDimensions.height;
+
+        let definedMaximumWidth: number;
+        let definedMaximumHeight: number;
+
+        // Skip any extra work if both values are provided.
+        if (isNullish(maximumWidth) || isNullish(maximumHeight)) {
+            const sheetAddress = await this.appExtension.getSheetAddress(invocationContext);
+
+            definedMaximumWidth = maximumWidth ?? await this.appExtension.maximumWidth() - sheetAddress.columnIndex;
+            definedMaximumHeight = maximumHeight ?? await this.appExtension.maximumHeight() - sheetAddress.rowIndex;
+        } else {
+            definedMaximumWidth = maximumWidth;
+            definedMaximumHeight = maximumHeight;
+        }
+
+        return {
+            width: definedMaximumWidth,
+            height: definedMaximumHeight
+        };
+    }
+
+    /**
+     * Spill a horizontal matrix vertically to fit within a maximum width and height.
+     *
+     * @param hMatrixValues
+     * Horizontal matrix values. Matrix has length 1 and contains a single array with the values.
+     *
+     * @param maximumWidth
+     * Maximum width.
+     *
+     * @param maximumHeight
+     * Maximum height.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @returns
+     * Matrix spilled within maximum width and maximum height.
+     */
+    @ProxyMethod({
+        requiresContext: true,
+        type: Type.Any,
+        isMatrix: true
+    })
+    async vSpill(
+        @ProxyParameter(spillMatrix) hMatrixValues: Matrix<unknown>,
+        @ProxyParameter(spillMaximumWidthParameterDescriptor) maximumWidth: Nullishable<number>,
+        @ProxyParameter(spillMaximumHeightParameterDescriptor) maximumHeight: Nullishable<number>,
+        invocationContext: Nullishable<TInvocationContext>
+    ): Promise<Matrix<unknown>> {
+        let result: Matrix<unknown>;
+
+        if (hMatrixValues.length !== 1) {
+            throw new RangeError(i18nextAppExtension.t("Proxy.vSpillMustBeHorizontalArray"));
+        }
+
+        const maximumDimensions = await this.defaultMaximums({
+            width: maximumWidth,
+            height: maximumHeight
+        }, invocationContext);
+
+        const hArrayValues = hMatrixValues[0];
+        const hLength = hArrayValues.length;
+        const maximumArea = maximumDimensions.width * maximumDimensions.height;
+
+        // Lengths 0 and 1 are valid and require no special processing.
+        if (hLength > 1 && hLength <= maximumArea) {
+            // Make spill as square as possible.
+            let spillWidth = Math.min(Math.ceil(Math.sqrt(maximumArea)), maximumDimensions.width);
+
+            // Array that has a length of a power of 10 is treated specially.
+            if (Number.isInteger(Math.log10(hLength))) {
+                // Try spill width that is a power of 10.
+                const spillWidth10 = Math.pow(10, Math.floor(Math.log10(spillWidth)));
+
+                // Keep default if not enough space for power of 10 matrix.
+                if (hLength / spillWidth10 <= maximumDimensions.height) {
+                    spillWidth = spillWidth10;
+                }
+            }
+
+            result = [];
+
+            let hStartIndex = 0;
+
+            do {
+                const hEndIndex = hStartIndex + spillWidth;
+
+                result.push(hArrayValues.slice(hStartIndex, hEndIndex));
+
+                hStartIndex = hEndIndex;
+            } while (hStartIndex < hLength);
+        } else {
+            // Return matrix unmodified and let application handle spill error if any.
+            result = hMatrixValues;
+        }
+
+        return result;
+    }
+
+    /**
+     * Spill a vertical matrix horizontally to fit within a maximum width and height.
+     *
+     * @param vMatrixValues
+     * Vertical matrix values. Matrix contains arrays of length 1 with the values.
+     *
+     * @param maximumHeight
+     * Maximum height.
+     *
+     * @param maximumWidth
+     * Maximum width.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @returns
+     * Matrix spilled within maximum height and maximum width.
+     */
+    @ProxyMethod({
+        requiresContext: true,
+        type: Type.Any,
+        isMatrix: true
+    })
+    async hSpill(
+        @ProxyParameter(spillMatrix) vMatrixValues: Matrix<unknown>,
+        @ProxyParameter(spillMaximumHeightParameterDescriptor) maximumHeight: Nullishable<number>,
+        @ProxyParameter(spillMaximumWidthParameterDescriptor) maximumWidth: Nullishable<number>,
+        invocationContext: Nullishable<TInvocationContext>
+    ): Promise<Matrix<unknown>> {
+        let result: Matrix<unknown>;
+
+        for (const hArrayValues of vMatrixValues) {
+            // This test should be necessary only once but account for zero-size matrix and misuse of method.
+            if (hArrayValues.length !== 1) {
+                throw new RangeError(i18nextAppExtension.t("Proxy.hSpillMustBeVerticalArray"));
+            }
+        }
+
+        const maximumDimensions = await this.defaultMaximums({
+            width: maximumWidth,
+            height: maximumHeight
+        }, invocationContext);
+
+        const vLength = vMatrixValues.length;
+        const maximumArea = maximumDimensions.width * maximumDimensions.height;
+
+        // Lengths 0 and 1 are valid and require no special processing.
+        if (vLength > 1 && vLength <= maximumArea) {
+            // Make spill as square as possible.
+            let spillHeight = Math.min(Math.ceil(Math.sqrt(maximumArea)), maximumDimensions.height);
+
+            // Array that has a length of a power of 10 is treated specially.
+            if (Number.isInteger(Math.log10(vLength))) {
+                // Try spill height that is a power of 10.
+                const spillHeight10 = Math.pow(10, Math.floor(Math.log10(spillHeight)));
+
+                // Keep default if not enough space for power of 10 matrix.
+                if (vLength / spillHeight10 <= maximumDimensions.width) {
+                    spillHeight = spillHeight10;
+                }
+            }
+
+            result = [];
+
+            for (let rowIndex = 0; rowIndex < spillHeight; rowIndex++) {
+                const row = new Array<unknown>();
+
+                for (let cellIndex = rowIndex; cellIndex < vLength; cellIndex++) {
+                    row.push(vMatrixValues[cellIndex][0]);
+                }
+
+                result.push(row);
+            }
+        } else {
+            // Return matrix unmodified and let application handle spill error if any.
+            result = vMatrixValues;
+        }
+
+        return result;
+    }
+}

package/src/descriptor.ts

@@ -0,0 +1,314 @@
+import type { AppExtension } from "./app-extension.js";
+import { LibProxy } from "./lib-proxy.js";
+import type { ErrorExtends, TypedFunction } from "./types.js";
+
+/**
+ * Core descriptor.
+ */
+interface Descriptor {
+    readonly name: string;
+}
+
+/**
+ * Types supported by proxy methods.
+ */
+export enum Type {
+    /**
+     * String.
+     */
+    String,
+
+    /**
+     * Number or enumeration.
+     */
+    Number,
+
+    /**
+     * Boolean.
+     */
+    Boolean,
+
+    /**
+     * Any.
+     */
+    Any
+}
+
+/**
+ * Type descriptor.
+ */
+interface TypeDescriptor extends Descriptor {
+    /**
+     * Type.
+     */
+    readonly type: Type;
+
+    /**
+     * True if type is a matrix (method accepts or returns a two-dimensional array).
+     */
+    readonly isMatrix: boolean;
+}
+
+/**
+ * Base parameter descriptor; all attributes required.
+ */
+export interface BaseParameterDescriptor extends TypeDescriptor {
+    /**
+     * True if required.
+     */
+    readonly isRequired: boolean;
+}
+
+/**
+ * Extends parameter descriptor; extends a parameter descriptor and overrides select attributes.
+ */
+export interface ExtendsParameterDescriptor extends Partial<BaseParameterDescriptor> {
+    /**
+     * Base parameter descriptor that this one extends.
+     */
+    readonly extendsDescriptor: ParameterDescriptor;
+
+    /**
+     * Sort order within base parameter descriptor if applicable.
+     */
+    readonly sortOrder?: number;
+}
+
+/**
+ * Parameter descriptor, either base or extends.
+ */
+export type ParameterDescriptor = BaseParameterDescriptor | ExtendsParameterDescriptor;
+
+/**
+ * Expand a parameter descriptor to its full form with all required attributes.
+ *
+ * @param parameterDescriptor
+ * Parameter descriptor.
+ *
+ * @returns
+ * Parameter descriptor in its full form.
+ */
+export function expandParameterDescriptor(parameterDescriptor: ParameterDescriptor): BaseParameterDescriptor {
+    return !("extendsDescriptor" in parameterDescriptor) ?
+        parameterDescriptor :
+        {
+            ...expandParameterDescriptor(parameterDescriptor.extendsDescriptor),
+            ...parameterDescriptor
+        };
+}
+
+/**
+ * Method descriptor.
+ */
+export interface MethodDescriptor extends TypeDescriptor {
+    /**
+     * If true, application-specific invocation context is required.
+     */
+    readonly requiresContext?: boolean;
+
+    /**
+     * If true, method infix is ignored.
+     */
+    readonly ignoreInfix?: boolean;
+
+    /**
+     * String before which method infix appears. If undefined, infix is appended to the method name. Ignored if
+     * `ignoreInfix` is true.
+     */
+    readonly infixBefore?: string;
+
+    /**
+     * Parameter descriptors.
+     */
+    readonly parameterDescriptors: readonly ParameterDescriptor[];
+}
+
+/**
+ * Class descriptor.
+ */
+export interface ClassDescriptor extends Descriptor {
+    /**
+     * Class namespace. If not provided, class is at the top level.
+     */
+    readonly namespace?: string;
+
+    /**
+     * Method infix. If undefined, method name is generated verbatim.
+     */
+    readonly methodInfix?: string;
+
+    /**
+     * Replace parameter descriptors for class hierarchies where enumeration parameter descriptors can change.
+     */
+    readonly replaceParameterDescriptors?: ReadonlyArray<{
+        readonly name: string;
+        readonly replacement: ParameterDescriptor;
+    }>;
+
+    /**
+     * Method descriptors.
+     */
+    readonly methodDescriptors: readonly MethodDescriptor[];
+}
+
+/**
+ * Proxy class type with fixed constructor.
+ */
+type ProxyClassType<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt, T extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt>> = (new(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) => T) & typeof LibProxy;
+
+/**
+ * Pending parameter descriptors, consumed and reset when method is described.
+ */
+let pendingParameterDescriptors: ParameterDescriptor[] = [];
+
+/**
+ * Class method descriptors, keyed on declaration class name and method name.
+ */
+const classMethodsDescriptorsMap = new Map<string, MethodDescriptor[]>();
+
+/**
+ * Class descriptors, keyed on declaration class name.
+ */
+const classDescriptorsMap = new Map<string, ClassDescriptor>();
+
+/**
+ * Proxy parameter decorator.
+ *
+ * @param parameterDescriptor
+ * Parameter descriptor.
+ *
+ * @returns
+ * Function defining metadata for the parameter.
+ */
+export function ProxyParameter<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt, T extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt>>(parameterDescriptor: ParameterDescriptor): ((target: T, propertyKey: string, parameterIndex: number) => void) {
+    return (_target: T, _propertyKey: string, parameterIndex: number) => {
+        pendingParameterDescriptors[parameterIndex] = parameterDescriptor;
+    };
+}
+
+/**
+ * Proxy method decorator.
+ *
+ * @param methodDescriptor
+ * Method descriptor.
+ *
+ * @returns
+ * Function defining metadata for the method.
+ */
+export function ProxyMethod<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt, T extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt>>(methodDescriptor: Omit<MethodDescriptor, "name" | "parameterDescriptors">): ((target: T, propertyKey: string, propertyDescriptor: PropertyDescriptor) => void) {
+    return (target: T, propertyKey: string, propertyDescriptor: PropertyDescriptor) => {
+        const declarationClassName = target.constructor.name;
+
+        // Validate that method descriptor is applied to a function.
+        if (typeof propertyDescriptor.value !== "function") {
+            throw new Error(`${declarationClassName}.${propertyKey} is not a method`);
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Known to be a method.
+        const parameterCount = (propertyDescriptor.value as TypedFunction<(...args: unknown[]) => unknown>).length - (!(methodDescriptor.requiresContext ?? false) ? 0 : 1);
+
+        let anyOptional = false;
+
+        // Validate that all parameters have descriptors.
+        for (let index = 0; index < parameterCount; index++) {
+            const parameterDescriptor = expandParameterDescriptor(pendingParameterDescriptors[index]);
+
+            if (typeof parameterDescriptor === "undefined") {
+                throw new Error(`Missing parameter descriptor at index ${index} of ${declarationClassName}.${propertyKey}`);
+            }
+
+            if (!parameterDescriptor.isRequired) {
+                anyOptional = true;
+            } else if (anyOptional) {
+                throw new Error(`Parameter descriptor ${parameterDescriptor.name} at index ${index} of ${declarationClassName}.${propertyKey} is required but prior parameter descriptor ${pendingParameterDescriptors[index - 1].name} is optional`);
+            }
+        }
+
+        let methodDescriptors = classMethodsDescriptorsMap.get(declarationClassName);
+        if (methodDescriptors === undefined) {
+            methodDescriptors = [];
+            classMethodsDescriptorsMap.set(declarationClassName, methodDescriptors);
+        }
+
+        // Method descriptors array is constructed in reverse order so that final result is in the correct order.
+        methodDescriptors.push({
+            name: propertyKey,
+            ...methodDescriptor,
+            parameterDescriptors: pendingParameterDescriptors
+        });
+
+        pendingParameterDescriptors = [];
+    };
+}
+
+/**
+ * Proxy class decorator.
+ *
+ * @param classDescriptor
+ * Class descriptor.
+ *
+ * @returns
+ * Function defining metadata for the class.
+ */
+export function ProxyClass<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt, T extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt>>(classDescriptor: Omit<ClassDescriptor, "name" | "methodDescriptors"> = {}): ((classType: ProxyClassType<ThrowError, TError, TInvocationContext, TBigInt, T>) => void) {
+    return (classType: ProxyClassType<ThrowError, TError, TInvocationContext, TBigInt, T>) => {
+        const methodDescriptorsMap = new Map<string, MethodDescriptor>();
+
+        /**
+         * Build method descriptors map from every class in hierarchy until LibProxy class is reached.
+         *
+         * @param classType
+         * Class type.
+         */
+        function buildMethodDescriptorsMap(classType: typeof LibProxy): void {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Class hierarchy is known.
+            const baseClassType = Object.getPrototypeOf(classType) as typeof LibProxy;
+
+            // Start with class furthest up the hierarchy.
+            if (baseClassType !== LibProxy) {
+                buildMethodDescriptorsMap(baseClassType);
+            }
+
+            const classMethodDescriptors = classMethodsDescriptorsMap.get(classType.name);
+
+            if (classMethodDescriptors !== undefined) {
+                for (const classMethodDescriptor of classMethodDescriptors) {
+                    // If any class overrides a base class method, it will appear in the same position as the base class method.
+                    methodDescriptorsMap.set(classMethodDescriptor.name, classMethodDescriptor);
+                }
+            }
+        }
+
+        buildMethodDescriptorsMap(classType);
+
+        let methodDescriptors: MethodDescriptor[];
+
+        if (classDescriptor.replaceParameterDescriptors !== undefined) {
+            const replacementParameterDescriptorsMap = new Map(classDescriptor.replaceParameterDescriptors.map(replaceParameterDescriptor => [replaceParameterDescriptor.name, replaceParameterDescriptor.replacement]));
+
+            // Method descriptors for class have to be built as copies due to possible mutation of parameter descriptors.
+            methodDescriptors = Array.from(methodDescriptorsMap.values()).map(methodDescriptor => ({
+                ...methodDescriptor,
+                parameterDescriptors: methodDescriptor.parameterDescriptors.map(parameterDescriptor => replacementParameterDescriptorsMap.get(expandParameterDescriptor(parameterDescriptor).name) ?? parameterDescriptor)
+            }));
+        } else {
+            methodDescriptors = Array.from(methodDescriptorsMap.values());
+        }
+
+        classDescriptorsMap.set(classType.name, {
+            name: classType.name,
+            ...classDescriptor,
+            methodDescriptors
+        });
+    };
+}
+
+/**
+ * Get class descriptors.
+ *
+ * @returns
+ * Class descriptors.
+ */
+export function getClassDescriptors(): ReadonlyMap<string, ClassDescriptor> {
+    return classDescriptorsMap;
+}

package/src/gs1/character-set-proxy.ts

@@ -0,0 +1,41 @@
+import { AI39_CREATOR, AI82_CREATOR } from "@aidc-toolkit/gs1";
+import type { AppExtension } from "../app-extension.js";
+import { expandParameterDescriptor, ProxyClass } from "../descriptor.js";
+import type { ErrorExtends } from "../types.js";
+import {
+    exclusionAllNumericParameterDescriptor,
+    exclusionNoneParameterDescriptor
+} from "../utility/character-set-descriptor.js";
+import { CharacterSetProxy } from "../utility/character-set-proxy.js";
+
+@ProxyClass({
+    namespace: "GS1",
+    methodInfix: "AI82",
+    replaceParameterDescriptors: [
+        {
+            name: expandParameterDescriptor(exclusionNoneParameterDescriptor).name,
+            replacement: exclusionAllNumericParameterDescriptor
+        }
+    ]
+})
+export class AI82Proxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends CharacterSetProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) {
+        super(appExtension, AI82_CREATOR);
+    }
+}
+
+@ProxyClass({
+    namespace: "GS1",
+    methodInfix: "AI39",
+    replaceParameterDescriptors: [
+        {
+            name: expandParameterDescriptor(exclusionNoneParameterDescriptor).name,
+            replacement: exclusionAllNumericParameterDescriptor
+        }
+    ]
+})
+export class AI39Proxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends CharacterSetProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) {
+        super(appExtension, AI39_CREATOR);
+    }
+}