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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/app-extension",
-  "version": "1.0.27-beta",
+  "version": "1.0.31-beta",
   "description": "Application extension framework for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -28,12 +28,12 @@
     "build:doc": "npm run build:dev"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "1.0.27-beta"
+    "@aidc-toolkit/dev": "1.0.31-beta"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "1.0.27-beta",
-    "@aidc-toolkit/gs1": "1.0.27-beta",
-    "@aidc-toolkit/utility": "1.0.27-beta",
+    "@aidc-toolkit/core": "1.0.31-beta",
+    "@aidc-toolkit/gs1": "1.0.31-beta",
+    "@aidc-toolkit/utility": "1.0.31-beta",
     "i18next": "^25.7.2"
   }
 }

package/src/app-extension.ts

@@ -55,7 +55,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @param throwError
      * If true, errors are reported through the throw/catch mechanism.
      */
-    protected constructor(version: string, maximumSequenceCount: number, throwError: ThrowError) {
+    constructor(version: string, maximumSequenceCount: number, throwError: ThrowError) {
         this.#version = version;
         this.#maximumSequenceCount = maximumSequenceCount;
         this.#throwError = throwError;
@@ -96,7 +96,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @returns
      * Maximum width supported by the application.
      */
-    protected abstract getMaximumWidth(): Promise<number>;
+    protected abstract getMaximumWidth(): number | Promise<number>;
 
     /**
      * Get the maximum height supported by the application.
@@ -116,7 +116,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @returns
      * Maximum height supported by the application.
      */
-    protected abstract getMaximumHeight(): Promise<number>;
+    protected abstract getMaximumHeight(): number | Promise<number>;
 
     /**
      * Get the sheet address from an invocation context.
@@ -127,7 +127,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @returns
      * Sheet address.
      */
-    abstract getSheetAddress(invocationContext: TInvocationContext): Promise<SheetAddress>;
+    abstract getSheetAddress(invocationContext: TInvocationContext): SheetAddress | Promise<SheetAddress>;
 
     /**
      * Get a parameter range from an invocation context.
@@ -141,7 +141,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @returns
      * Sheet range or null if parameter is not a range.
      */
-    abstract getParameterSheetRange(invocationContext: TInvocationContext, parameterNumber: number): Promise<SheetRange | null>;
+    abstract getParameterSheetRange(invocationContext: TInvocationContext, parameterNumber: number): SheetRange | null | Promise<SheetRange | null>;
 
     /**
      * Validate a sequence count against the maximum supported by application.

package/src/app-utility-proxy.ts

@@ -1,7 +1,8 @@
 import { isNullish, type NonNullishable, type Nullishable } from "@aidc-toolkit/core";
-import { type ParameterDescriptor, ProxyClass, ProxyMethod, ProxyParameter, Types } from "./descriptor.js";
+import { type ExtendsParameterDescriptor, type ParameterDescriptor, Types } from "./descriptor.js";
 import { LibProxy } from "./lib-proxy.js";
 import { i18nextAppExtension } from "./locale/i18n.js";
+import { proxy } from "./proxy.js";
 import type { ErrorExtends, Matrix } from "./type.js";
 
 const spillMatrix: ParameterDescriptor = {
@@ -18,13 +19,13 @@ const spillMaximumParameterDescriptor: ParameterDescriptor = {
     isRequired: false
 };
 
-const spillMaximumWidthParameterDescriptor: ParameterDescriptor = {
+const spillMaximumWidthParameterDescriptor: ExtendsParameterDescriptor = {
     extendsDescriptor: spillMaximumParameterDescriptor,
     sortOrder: 0,
     name: "spillMaximumWidth"
 };
 
-const spillMaximumHeightParameterDescriptor: ParameterDescriptor = {
+const spillMaximumHeightParameterDescriptor: ExtendsParameterDescriptor = {
     extendsDescriptor: spillMaximumParameterDescriptor,
     sortOrder: 1,
     name: "spillMaximumHeight"
@@ -60,7 +61,7 @@ interface MaximumDimensions {
  * @template TBigInt
  * Type to which big integer is mapped.
  */
-@ProxyClass()
+@proxy.describeClass(false)
 export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt> {
     /**
      * Get the version.
@@ -68,9 +69,10 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
      * @returns
      * Version.
      */
-    @ProxyMethod({
+    @proxy.describeMethod({
         type: Types.String,
-        isMatrix: false
+        isMatrix: false,
+        parameterDescriptors: []
     })
     version(): string {
         return this.appExtension.version;
@@ -135,17 +137,13 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
      * @returns
      * Matrix spilled within maximum width and maximum height.
      */
-    @ProxyMethod({
+    @proxy.describeMethod({
         requiresContext: true,
         type: Types.Any,
-        isMatrix: true
+        isMatrix: true,
+        parameterDescriptors: [spillMatrix, spillMaximumWidthParameterDescriptor, spillMaximumHeightParameterDescriptor]
     })
-    async vSpill(
-        @ProxyParameter(spillMatrix) hMatrixValues: Matrix<unknown>,
-        @ProxyParameter(spillMaximumWidthParameterDescriptor) maximumWidth: Nullishable<number>,
-        @ProxyParameter(spillMaximumHeightParameterDescriptor) maximumHeight: Nullishable<number>,
-        invocationContext: Nullishable<TInvocationContext>
-    ): Promise<Matrix<unknown>> {
+    async vSpill(hMatrixValues: Matrix<unknown>, maximumWidth: Nullishable<number>, maximumHeight: Nullishable<number>, invocationContext: Nullishable<TInvocationContext>): Promise<Matrix<unknown>> {
         let result: Matrix<unknown>;
 
         if (hMatrixValues.length !== 1) {
@@ -169,7 +167,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
             // 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)));
+                const spillWidth10 = 10 ** Math.floor(Math.log10(spillWidth));
 
                 // Keep default if not enough space for power of 10 matrix.
                 if (hLength / spillWidth10 <= maximumDimensions.height) {
@@ -214,17 +212,13 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
      * @returns
      * Matrix spilled within maximum height and maximum width.
      */
-    @ProxyMethod({
+    @proxy.describeMethod({
         requiresContext: true,
         type: Types.Any,
-        isMatrix: true
+        isMatrix: true,
+        parameterDescriptors: [spillMatrix, spillMaximumHeightParameterDescriptor, spillMaximumWidthParameterDescriptor]
     })
-    async hSpill(
-        @ProxyParameter(spillMatrix) vMatrixValues: Matrix<unknown>,
-        @ProxyParameter(spillMaximumHeightParameterDescriptor) maximumHeight: Nullishable<number>,
-        @ProxyParameter(spillMaximumWidthParameterDescriptor) maximumWidth: Nullishable<number>,
-        invocationContext: Nullishable<TInvocationContext>
-    ): Promise<Matrix<unknown>> {
+    async hSpill(vMatrixValues: Matrix<unknown>, maximumHeight: Nullishable<number>, maximumWidth: Nullishable<number>, invocationContext: Nullishable<TInvocationContext>): Promise<Matrix<unknown>> {
         let result: Matrix<unknown>;
 
         for (const hArrayValues of vMatrixValues) {
@@ -250,7 +244,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
             // 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)));
+                const spillHeight10 = 10 ** Math.floor(Math.log10(spillHeight));
 
                 // Keep default if not enough space for power of 10 matrix.
                 if (vLength / spillHeight10 <= maximumDimensions.width) {

package/src/descriptor.ts

@@ -1,8 +1,3 @@
-import type { TypedFunction } from "@aidc-toolkit/core";
-import type { AppExtension } from "./app-extension.js";
-import { LibProxy } from "./lib-proxy.js";
-import type { ErrorExtends } from "./type.js";
-
 /**
  * Core descriptor.
  */
@@ -64,9 +59,9 @@ interface TypeDescriptor extends Descriptor {
 }
 
 /**
- * Base parameter descriptor; all attributes required.
+ * Parameter descriptor.
  */
-export interface BaseParameterDescriptor extends TypeDescriptor {
+export interface ParameterDescriptor extends TypeDescriptor {
     /**
      * True if required.
      */
@@ -74,43 +69,20 @@ export interface BaseParameterDescriptor extends TypeDescriptor {
 }
 
 /**
- * Extends parameter descriptor; extends a parameter descriptor and overrides select attributes.
+ * Extends parameter descriptor.
  */
-export interface ExtendsParameterDescriptor extends Partial<BaseParameterDescriptor> {
+export interface ExtendsParameterDescriptor extends Partial<ParameterDescriptor> {
     /**
-     * Base parameter descriptor that this one extends.
+     * Parameter descriptor that this one extends.
      */
-    readonly extendsDescriptor: ParameterDescriptor;
+    readonly extendsDescriptor: ParameterDescriptor | ExtendsParameterDescriptor;
 
     /**
-     * Sort order within base parameter descriptor if applicable.
+     * Sort order within extended parameter descriptor.
      */
     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.
  */
@@ -135,6 +107,16 @@ export interface MethodDescriptor extends TypeDescriptor {
      * Parameter descriptors.
      */
     readonly parameterDescriptors: readonly ParameterDescriptor[];
+
+    /**
+     * Function name with optional infix.
+     */
+    readonly functionName: string;
+
+    /**
+     * Function name in optional namespace with optional infix.
+     */
+    readonly namespaceFunctionName: string;
 }
 
 /**
@@ -144,12 +126,12 @@ export interface ClassDescriptor extends Descriptor {
     /**
      * Class namespace. If not provided, class is at the top level.
      */
-    readonly namespace?: string;
+    readonly namespace?: string | undefined;
 
     /**
      * Method infix. If undefined, method name is generated verbatim.
      */
-    readonly methodInfix?: string;
+    readonly methodInfix?: string | undefined;
 
     /**
      * Replace parameter descriptors for class hierarchies where enumeration parameter descriptors can change.
@@ -160,229 +142,17 @@ export interface ClassDescriptor extends Descriptor {
     }>;
 
     /**
-     * Method descriptors.
+     * Class name in optional namespace.
      */
-    readonly methodDescriptors: readonly MethodDescriptor[];
-}
-
-/**
- * Proxy class type with fixed constructor.
- *
- * @template ThrowError
- * If true, errors are reported through the throw/catch mechanism.
- *
- * @template TError
- * Error type.
- *
- * @template TInvocationContext
- * Application-specific invocation context type.
- *
- * @template TBigInt
- * Type to which big integer is mapped.
- *
- * @template T
- * Proxy type.
- */
-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 map, keyed on declaration class name and method name.
- */
-const classMethodsDescriptorsMap = new Map<string, MethodDescriptor[]>();
-
-/**
- * Class descriptors map, keyed on declaration class name.
- */
-const classDescriptorsMap = new Map<string, ClassDescriptor>();
-
-/**
- * Proxy parameter decorator.
- *
- * @template ThrowError
- * If true, errors are reported through the throw/catch mechanism.
- *
- * @template TError
- * Error type.
- *
- * @template TInvocationContext
- * Application-specific invocation context type.
- *
- * @template TBigInt
- * Type to which big integer is mapped.
- *
- * @template T
- * Proxy type.
- *
- * @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;
-    };
-}
+    readonly namespaceClassName: string;
 
-/**
- * Proxy method decorator.
- *
- * @template ThrowError
- * If true, errors are reported through the throw/catch mechanism.
- *
- * @template TError
- * Error type.
- *
- * @template TInvocationContext
- * Application-specific invocation context type.
- *
- * @template TBigInt
- * Type to which big integer is mapped.
- *
- * @template T
- * Proxy type.
- *
- * @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.
- *
- * @template ThrowError
- * If true, errors are reported through the throw/catch mechanism.
- *
- * @template TError
- * Error type.
- *
- * @template TInvocationContext
- * Application-specific invocation context type.
- *
- * @template TBigInt
- * Type to which big integer is mapped.
- *
- * @template T
- * Proxy type.
- *
- * @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
-        });
-    };
-}
+    /**
+     * Object name.
+     */
+    readonly objectName: string;
 
-/**
- * Get class descriptors map.
- *
- * @returns
- * Class descriptors map.
- */
-export function getClassDescriptorsMap(): ReadonlyMap<string, ClassDescriptor> {
-    return classDescriptorsMap;
+    /**
+     * Method descriptors.
+     */
+    readonly methodDescriptors: readonly MethodDescriptor[];
 }