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

package/src/locale/i18n.ts

@@ -1,6 +1,6 @@
-import { type I18nEnvironment, i18nFinalizeInit } from "@aidc-toolkit/core";
-import { gs1Resources, i18nGS1Init } from "@aidc-toolkit/gs1";
-import { i18nUtilityInit, utilityResources } from "@aidc-toolkit/utility";
+import { i18nCoreInit, type I18nEnvironment, i18nInit } from "@aidc-toolkit/core";
+import { i18nGS1Init } from "@aidc-toolkit/gs1";
+import { i18nUtilityInit } from "@aidc-toolkit/utility";
 import i18next, { type i18n, type Resource } from "i18next";
 import enLocaleResources from "./en/locale-resources.js";
 import frLocaleResources from "./fr/locale-resources.js";
@@ -13,9 +13,9 @@ export const appExtensionNS = "aidct_app_extension";
 export type AppExtensionLocaleResources = typeof enLocaleResources;
 
 /**
- * App extension resources.
+ * App extension resource bundle.
  */
-export const appExtensionResources: Resource = {
+export const appExtensionResourceBundle: Resource = {
     en: {
         aidct_app_extension: enLocaleResources
     },
@@ -35,9 +35,10 @@ export const i18nextAppExtension: i18n = i18next.createInstance();
  *
  * @param debug
  * Debug setting.
+ *
+ * @returns
+ * App extension resource bundle.
  */
-export async function i18nAppExtensionInit(environment: I18nEnvironment, debug = false): Promise<void> {
-    await i18nUtilityInit(environment, debug);
-    await i18nGS1Init(environment, debug);
-    await i18nFinalizeInit(i18nextAppExtension, environment, debug, appExtensionNS, utilityResources, gs1Resources, appExtensionResources);
+export async function i18nAppExtensionInit(environment: I18nEnvironment, debug = false): Promise<Resource> {
+    return i18nInit(i18nextAppExtension, environment, debug, appExtensionNS, appExtensionResourceBundle, i18nCoreInit, i18nUtilityInit, i18nGS1Init);
 }

package/src/locale/i18next.d.ts

@@ -1,3 +1,4 @@
+import type { CoreLocaleResources } from "@aidc-toolkit/core";
 import type { GS1LocaleResources } from "@aidc-toolkit/gs1";
 import type { UtilityLocaleResources } from "@aidc-toolkit/utility";
 import type { AppExtensionLocaleResources } from "./i18n.js";
@@ -12,6 +13,7 @@ declare module "i18next" {
     interface CustomTypeOptions {
         defaultNS: "aidct_app_extension";
         resources: {
+            aidct_core: CoreLocaleResources;
             aidct_utility: UtilityLocaleResources;
             aidct_gs1: GS1LocaleResources;
             aidct_app_extension: AppExtensionLocaleResources;

package/src/proxy.ts

@@ -7,12 +7,13 @@ import {
 } from "@aidc-toolkit/core";
 import type { Logger } from "tslog";
 import type { AppExtension } from "./app-extension.js";
-import type {
-    ClassDescriptor,
-    ExtendsParameterDescriptor,
-    MethodDescriptor,
-    ParameterDescriptor,
-    ReplacementParameterDescriptor
+import {
+    type ClassDescriptor,
+    type ExtendsParameterDescriptor,
+    type MethodDescriptor,
+    Multiplicities,
+    type ParameterDescriptor,
+    type ReplacementParameterDescriptor
 } from "./descriptor.js";
 import { LibProxy } from "./lib-proxy.js";
 import type { ErrorExtends } from "./type.js";
@@ -94,8 +95,9 @@ interface DecoratorMethodDescriptor extends Omit<InterimMethodDescriptor, "name"
 /**
  * Subset of class descriptor used during decoration process.
  */
-type InterimClassDescriptor =
-    Omit<ClassDescriptor, "name" | "namespaceClassName" | "objectName" | "methodDescriptors">;
+interface InterimClassDescriptor extends Omit<ClassDescriptor, "name" | "category" | "namespaceClassName" | "objectName" | "methodDescriptors"> {
+    readonly category?: string;
+}
 
 /**
  * Subset of class descriptor used in call to decorator.
@@ -168,15 +170,20 @@ interface TargetLogger {
  */
 export class Proxy {
     /**
-     * Abstract class descriptors map, keyed on declaration class name. Abstract classes are not used directly by target
+     * Abstract class descriptors map, keyed on declaration class. Abstract classes are not used directly by target
      * applications.
      */
-    readonly #abstractClassDescriptorsMap = new Map<string, ClassDescriptor>();
+    readonly #abstractClassDescriptorsMap = new Map<typeof LibProxy, ClassDescriptor>();
 
     /**
-     * Concrete class descriptors map, keyed on declaration class name.
+     * Concrete class descriptors map, keyed on declaration class.
      */
-    readonly #concreteClassDescriptorsMap = new Map<string, ClassDescriptor>();
+    readonly #concreteClassDescriptorsMap = new Map<typeof LibProxy, ClassDescriptor>();
+
+    /**
+     * Namespace class names set for duplicate detection.
+     */
+    readonly #namespaceClassNamesSet = new Set<string>();
 
     /**
      * Interim object.
@@ -232,42 +239,39 @@ export class Proxy {
         this.#interim = interim;
 
         return (Target: TProxyClassConstructor, context: ClassDecoratorContext<TProxyClassConstructor>) => {
-            const name = context.name;
+            const className = context.name;
 
             // Validate that class descriptor is applied within an appropriate class.
-            if (typeof name !== "string") {
-                throw new Error(`${String(name)} has an invalid name`);
+            if (className === undefined) {
+                throw new Error("Class has no name");
             }
 
-            const namespacePrefix = decoratorClassDescriptor.namespace === undefined ? "" : `${decoratorClassDescriptor.namespace}.`;
-            const namespaceClassName = `${namespacePrefix}${name}`;
-
             const abstractClassDescriptorsMap = this.#abstractClassDescriptorsMap;
             const concreteClassDescriptorsMap = this.#concreteClassDescriptorsMap;
 
-            if (abstractClassDescriptorsMap.has(namespaceClassName) || concreteClassDescriptorsMap.has(namespaceClassName)) {
-                throw new Error(`Duplicate class ${namespaceClassName}`);
-            }
-
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Class hierarchy is known.
-            let baseClassType: typeof LibProxy = Target as unknown as typeof LibProxy;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Target is known to be of type LibProxy.
+            const targetClassType = Target as unknown as typeof LibProxy;
+            let baseClassType = targetClassType;
             let baseClassDescriptor: ClassDescriptor | undefined;
 
             do {
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Class hierarchy is known.
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Class hierarchy is known to stop at LibProxy.
                 baseClassType = Object.getPrototypeOf(baseClassType) as typeof LibProxy;
 
-                const namespaceBaseClassName = `${namespacePrefix}${baseClassType.name}`;
-
-                // Look first within the namespace and then in no namespace, in both abstract class descriptors map and concrete class descriptors map.
-                baseClassDescriptor =
-                    abstractClassDescriptorsMap.get(namespaceBaseClassName) ?? abstractClassDescriptorsMap.get(baseClassType.name) ??
-                    concreteClassDescriptorsMap.get(namespaceBaseClassName) ?? concreteClassDescriptorsMap.get(baseClassType.name);
+                // Look in both abstract class descriptors map and concrete class descriptors map.
+                baseClassDescriptor = abstractClassDescriptorsMap.get(baseClassType) ?? concreteClassDescriptorsMap.get(baseClassType);
             } while (baseClassType !== LibProxy && baseClassDescriptor === undefined);
 
+            let namespace = interimClassDescriptor.namespace;
+            let category = interimClassDescriptor.category;
+
             let interimMethodDescriptors: InterimMethodDescriptor[];
 
             if (baseClassDescriptor !== undefined) {
+                // Inherit namespace and category from base class if not explicitly defined.
+                namespace ??= baseClassDescriptor.namespace;
+                category ??= baseClassDescriptor.category;
+
                 const baseClassMethodDescriptors = baseClassDescriptor.methodDescriptors;
                 const replaceParameterDescriptors = decoratorClassDescriptor.replacementParameterDescriptors;
 
@@ -286,6 +290,19 @@ export class Proxy {
                 interimMethodDescriptors = [];
             }
 
+            const namespacePrefix = namespace === undefined ? "" : `${namespace}.`;
+            const namespaceClassName = `${namespacePrefix}${className}`;
+
+            if (this.#namespaceClassNamesSet.has(namespaceClassName)) {
+                throw new Error(`Duplicate class ${namespaceClassName}`);
+            }
+
+            if (category === undefined) {
+                throw new Error(`Missing category for ${namespaceClassName}`);
+            }
+
+            this.#namespaceClassNamesSet.add(namespaceClassName);
+
             // Replace base class method descriptors with matching names or append new method descriptor.
             for (const classInterimMethodDescriptor of interim.methodDescriptors) {
                 const existingIndex = interimMethodDescriptors.findIndex(interimMethodDescriptor => interimMethodDescriptor.name === classInterimMethodDescriptor.name);
@@ -353,14 +370,16 @@ export class Proxy {
             }
 
             const classDescriptor: ClassDescriptor = {
-                name,
                 ...interimClassDescriptor,
+                name: className,
+                namespace,
+                category,
                 namespaceClassName,
                 objectName: `${objectNameGroups["namespaceFirstWord"].toLowerCase()}${objectNameGroups["namespaceRemaining"]}${objectNameGroups["className"]}`,
                 methodDescriptors
             };
 
-            (isAbstract ? abstractClassDescriptorsMap : concreteClassDescriptorsMap).set(namespaceClassName, classDescriptor);
+            (isAbstract ? abstractClassDescriptorsMap : concreteClassDescriptorsMap).set(targetClassType, classDescriptor);
 
             const methodDescriptorsMap = new Map<string, MethodDescriptor>();
 
@@ -388,8 +407,8 @@ export class Proxy {
                         const methodDescriptor = methodDescriptorsMap.get(methodName)!;
 
                         return {
-                            namespace: decoratorClassDescriptor.namespace,
-                            className: name,
+                            namespace,
+                            className,
                             methodName,
                             functionName: methodDescriptor.functionName,
                             parameters: methodDescriptor.parameterDescriptors.map((parameterDescriptor, index) => ({
@@ -435,19 +454,24 @@ export class Proxy {
             // Expand all parameter descriptors.
             const parameterDescriptors = decoratorMethodDescriptor.parameterDescriptors.map((decoratorParameterDescriptor) => {
                 const parameterDescriptor = expandParameterDescriptor(decoratorParameterDescriptor);
+                const parameterName = parameterDescriptor.name;
 
                 if (!parameterDescriptor.isRequired) {
                     anyOptional = true;
                 } else if (anyOptional) {
-                    throw new Error(`Parameter ${parameterDescriptor.name} descriptor of method ${name} is required but prior parameter descriptor is optional`);
+                    throw new Error(`Parameter ${parameterName} descriptor of method ${name} is required but prior parameter descriptor is optional`);
+                }
+
+                if ((parameterDescriptor.multiplicity === Multiplicities.Array || parameterDescriptor.multiplicity === Multiplicities.Matrix) && decoratorMethodDescriptor.multiplicity !== Multiplicities.Matrix) {
+                    throw new Error(`Parameter ${parameterName} descriptor of method ${name} is array or matrix but method descriptor is not matrix`);
                 }
 
                 return parameterDescriptor;
             });
 
             this.#interim.methodDescriptors.push({
-                name,
                 ...decoratorMethodDescriptor,
+                name,
                 parameterDescriptors
             });
 
@@ -489,10 +513,10 @@ export class Proxy {
     }
 
     /**
-     * Get the class descriptors map.
+     * Get the class descriptors.
      */
-    get classDescriptorsMap(): Map<string, ClassDescriptor> {
-        return this.#concreteClassDescriptorsMap;
+    get classDescriptors(): MapIterator<ClassDescriptor> {
+        return this.#concreteClassDescriptorsMap.values();
     }
 }
 

package/src/utility/character-set-descriptor.ts

@@ -1,9 +1,9 @@
-import { type ExtendsParameterDescriptor, type ParameterDescriptor, Types } from "../descriptor.js";
+import { type ExtendsParameterDescriptor, Multiplicities, type ParameterDescriptor, Types } from "../descriptor.js";
 
 const exclusionParameterDescriptor: ParameterDescriptor = {
     name: "exclusion",
     type: Types.Number,
-    isMatrix: false,
+    multiplicity: Multiplicities.Singleton,
     isRequired: false
 };
 

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

@@ -11,7 +11,7 @@ import {
     Sequence
 } from "@aidc-toolkit/utility";
 import type { AppExtension } from "../app-extension.js";
-import { type ExtendsParameterDescriptor, type ParameterDescriptor, Types } from "../descriptor.js";
+import { type ExtendsParameterDescriptor, Multiplicities, type ParameterDescriptor, Types } from "../descriptor.js";
 import { expandParameterDescriptor, proxy } from "../proxy.js";
 import type { ErrorExtends, Matrix, MatrixResult } from "../type.js";
 import {
@@ -31,7 +31,7 @@ import {
 const lengthParameterDescriptor: ParameterDescriptor = {
     name: "length",
     type: Types.Number,
-    isMatrix: false,
+    multiplicity: Multiplicities.Singleton,
     isRequired: true
 };
 
@@ -52,7 +52,7 @@ export abstract class CharacterSetValidatorProxy<ThrowError extends boolean, TEr
 
     @proxy.describeMethod({
         type: Types.String,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [validateSParameterDescriptor, exclusionNoneParameterDescriptor]
     })
     validate(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>): Matrix<string> {
@@ -63,7 +63,7 @@ export abstract class CharacterSetValidatorProxy<ThrowError extends boolean, TEr
 
     @proxy.describeMethod({
         type: Types.Boolean,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [validateSParameterDescriptor, exclusionNoneParameterDescriptor]
     })
     isValid(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>): Matrix<boolean> {
@@ -83,7 +83,7 @@ export abstract class CharacterSetCreatorProxy<ThrowError extends boolean, TErro
 
     @proxy.describeMethod({
         type: Types.String,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [lengthParameterDescriptor, valueParameterDescriptor, exclusionNoneParameterDescriptor, tweakParameterDescriptor]
     })
     create(length: number, matrixValues: Matrix<number | bigint>, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<string, ThrowError, TError> {
@@ -98,7 +98,7 @@ export abstract class CharacterSetCreatorProxy<ThrowError extends boolean, TErro
     @proxy.describeMethod({
         infixBefore: "Sequence",
         type: Types.String,
-        isMatrix: true,
+        multiplicity: Multiplicities.Array,
         parameterDescriptors: [lengthParameterDescriptor, startValueParameterDescriptor, countParameterDescriptor, exclusionNoneParameterDescriptor, tweakParameterDescriptor]
     })
     createSequence(length: number, startValue: number, count: number, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<string, ThrowError, TError> {
@@ -114,7 +114,7 @@ export abstract class CharacterSetCreatorProxy<ThrowError extends boolean, TErro
 
     @proxy.describeMethod({
         type: Types.Number,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [valueForSParameterDescriptor, exclusionNoneParameterDescriptor, tweakParameterDescriptor]
     })
     valueFor(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<TBigInt, ThrowError, TError> {

package/src/utility/reg-exp-proxy.ts

@@ -1,6 +1,6 @@
 import type { Nullishable } from "@aidc-toolkit/core";
 import { RegExpValidator } from "@aidc-toolkit/utility";
-import { type ParameterDescriptor, Types } from "../descriptor.js";
+import { Multiplicities, type ParameterDescriptor, Types } from "../descriptor.js";
 import { proxy } from "../proxy.js";
 import type { ErrorExtends, Matrix } from "../type.js";
 import { validateSParameterDescriptor } from "./string-descriptor.js";
@@ -9,14 +9,14 @@ import { StringProxy } from "./string-proxy.js";
 const regExpParameterDescriptor: ParameterDescriptor = {
     name: "regExp",
     type: Types.String,
-    isMatrix: false,
+    multiplicity: Multiplicities.Singleton,
     isRequired: true
 };
 
 const errorMessageParameterDescriptor: ParameterDescriptor = {
     name: "errorMessage",
     type: Types.String,
-    isMatrix: false,
+    multiplicity: Multiplicities.Singleton,
     isRequired: false
 };
 
@@ -26,7 +26,7 @@ const errorMessageParameterDescriptor: ParameterDescriptor = {
 export class RegExpProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends StringProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     @proxy.describeMethod({
         type: Types.String,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [regExpParameterDescriptor, validateSParameterDescriptor, errorMessageParameterDescriptor]
     })
     validate(regExp: string, matrixSs: Matrix<string>, errorMessage: Nullishable<string>): Matrix<string> {
@@ -40,7 +40,7 @@ export class RegExpProxy<ThrowError extends boolean, TError extends ErrorExtends
 
     @proxy.describeMethod({
         type: Types.Boolean,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [regExpParameterDescriptor, validateSParameterDescriptor]
     })
     isValid(regExp: string, matrixSs: Matrix<string>): Matrix<boolean> {

package/src/utility/string-descriptor.ts

@@ -1,9 +1,9 @@
-import { type ExtendsParameterDescriptor, type ParameterDescriptor, Types } from "../descriptor.js";
+import { type ExtendsParameterDescriptor, Multiplicities, type ParameterDescriptor, Types } from "../descriptor.js";
 
 export const sParameterDescriptor: ParameterDescriptor = {
     name: "s",
     type: Types.String,
-    isMatrix: true,
+    multiplicity: Multiplicities.Matrix,
     isRequired: true
 };
 

package/src/utility/string-proxy.ts

@@ -1,7 +1,11 @@
 import type { StringValidation, StringValidator } from "@aidc-toolkit/utility";
 import { LibProxy } from "../lib-proxy.js";
+import { proxy } from "../proxy.js";
 import type { ErrorExtends, Matrix } from "../type.js";
 
+@proxy.describeClass(true, {
+    category: "string"
+})
 export abstract class StringProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     protected validateString<TStringValidation extends StringValidation>(validator: StringValidator<TStringValidation>, matrixSs: Matrix<string>, validation?: TStringValidation): Matrix<string> {
         return this.matrixErrorResult(matrixSs, (s) => {

package/src/utility/transformer-descriptor.ts

@@ -1,27 +1,27 @@
-import { type ExtendsParameterDescriptor, type ParameterDescriptor, Types } from "../descriptor.js";
+import { type ExtendsParameterDescriptor, Multiplicities, type ParameterDescriptor, Types } from "../descriptor.js";
 
 export const valueParameterDescriptor: ParameterDescriptor = {
     name: "value",
     type: Types.Number,
-    isMatrix: true,
+    multiplicity: Multiplicities.Matrix,
     isRequired: true
 };
 
 export const startValueParameterDescriptor: ExtendsParameterDescriptor = {
     extendsDescriptor: valueParameterDescriptor,
     name: "startValue",
-    isMatrix: false
+    multiplicity: Multiplicities.Singleton
 };
 
 export const countParameterDescriptor: ExtendsParameterDescriptor = {
     extendsDescriptor: valueParameterDescriptor,
     name: "count",
-    isMatrix: false
+    multiplicity: Multiplicities.Singleton
 };
 
 export const tweakParameterDescriptor: ParameterDescriptor = {
     name: "tweak",
     type: Types.Number,
-    isMatrix: false,
+    multiplicity: Multiplicities.Singleton,
     isRequired: false
 };

package/src/utility/transformer-proxy.ts

@@ -1,6 +1,6 @@
 import type { Nullishable } from "@aidc-toolkit/core";
 import { mapIterable, Sequence, Transformer } from "@aidc-toolkit/utility";
-import { type ExtendsParameterDescriptor, type ParameterDescriptor, Types } from "../descriptor.js";
+import { type ExtendsParameterDescriptor, Multiplicities, 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";
@@ -14,7 +14,7 @@ import {
 const domainParameterDescriptor: ParameterDescriptor = {
     name: "domain",
     type: Types.Number,
-    isMatrix: false,
+    multiplicity: Multiplicities.Singleton,
     isRequired: true
 };
 
@@ -24,12 +24,13 @@ const transformedValueParameterDescriptor: ExtendsParameterDescriptor = {
 };
 
 @proxy.describeClass(false, {
+    category: "transformation",
     methodInfix: "Transform"
 })
 export class TransformerProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     @proxy.describeMethod({
         type: Types.Number,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [domainParameterDescriptor, valueParameterDescriptor, tweakParameterDescriptor]
     })
     forward(domain: number | bigint, matrixValues: Matrix<number | bigint>, tweak: Nullishable<number | bigint>): MatrixResult<TBigInt, ThrowError, TError> {
@@ -43,7 +44,7 @@ export class TransformerProxy<ThrowError extends boolean, TError extends ErrorEx
     @proxy.describeMethod({
         infixBefore: "Sequence",
         type: Types.Number,
-        isMatrix: true,
+        multiplicity: Multiplicities.Array,
         parameterDescriptors: [domainParameterDescriptor, startValueParameterDescriptor, countParameterDescriptor, tweakParameterDescriptor]
     })
     forwardSequence(domain: number | bigint, startValue: number, count: number, tweak: Nullishable<number | bigint>): MatrixResult<TBigInt, ThrowError, TError> {
@@ -56,7 +57,7 @@ export class TransformerProxy<ThrowError extends boolean, TError extends ErrorEx
 
     @proxy.describeMethod({
         type: Types.Number,
-        isMatrix: true,
+        multiplicity: Multiplicities.Matrix,
         parameterDescriptors: [domainParameterDescriptor, transformedValueParameterDescriptor, tweakParameterDescriptor]
     })
     reverse(domain: number | bigint, matrixTransformedValues: Matrix<number | bigint>, tweak: Nullishable<number | bigint>): MatrixResult<TBigInt, ThrowError, TError> {