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

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@aidc-toolkit/app-extension",
-  "version": "1.0.25-beta",
+  "version": "1.0.27-beta",
   "description": "Application extension framework for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
   "homepage": "https://aidc-toolkit.com/",
-  "repository": "aidc-toolkit/app-extension",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidc-toolkit/app-extension.git"
+  },
   "bugs": {
     "url": "https://github.com/aidc-toolkit/app-extension/issues"
   },
@@ -16,19 +19,21 @@
     "url": "https://www.linkedin.com/in/kdean"
   },
   "scripts": {
+    "locale-resources-generator": "tsx src/generator/locale-resources-generator.ts",
     "lint": "eslint",
+    "tsc:core": "tsc --project tsconfig-src.json",
+    "build:devx": "rimraf dist && npm run tsc:core -- --declarationMap --sourceMap",
     "build:dev": "tsup --define.mode=dev",
-    "build:release": "tsup",
+    "build:release": "npm run tsc:core -- --noEmit && tsup",
     "build:doc": "npm run build:dev"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "1.0.25-beta",
-    "@types/node": "^24.10.1"
+    "@aidc-toolkit/dev": "1.0.27-beta"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "1.0.25-beta",
-    "@aidc-toolkit/gs1": "1.0.25-beta",
-    "@aidc-toolkit/utility": "1.0.25-beta",
-    "i18next": "^25.7.1"
+    "@aidc-toolkit/core": "1.0.27-beta",
+    "@aidc-toolkit/gs1": "1.0.27-beta",
+    "@aidc-toolkit/utility": "1.0.27-beta",
+    "i18next": "^25.7.2"
   }
 }

package/src/app-extension.ts

@@ -1,44 +1,47 @@
 import type { TypedAsyncFunction, TypedFunction, TypedSyncFunction } from "@aidc-toolkit/core";
-import { i18nextAppExtension } from "./locale/i18n";
-import type { ErrorExtends, ResultError, SheetAddress, SheetRange } from "./type";
+import { i18nextAppExtension } from "./locale/i18n.js";
+import type { ErrorExtends, ResultError, SheetAddress, SheetRange } from "./type.js";
 
 /**
  * Application extension.
  *
- * @template TBigInt
- * Type to which big integer is mapped.
- *
  * @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.
  */
 export abstract class AppExtension<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> {
     /**
      * Application version.
      */
-    private readonly _version: string;
+    readonly #version: string;
 
     /**
      * Maximum sequence count supported by application.
      */
-    private readonly _maximumSequenceCount: number;
+    readonly #maximumSequenceCount: number;
 
     /**
      * If true, errors are reported through the throw/catch mechanism.
      */
-    private readonly _throwError: ThrowError;
+    readonly #throwError: ThrowError;
 
     /**
      * Maximum width supported by application.
      */
-    private _maximumWidth?: number;
+    #maximumWidth?: number;
 
     /**
      * Maximum height supported by application.
      */
-    private _maximumHeight?: number;
+    #maximumHeight?: number;
 
     /**
      * Constructor.
@@ -53,9 +56,9 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * If true, errors are reported through the throw/catch mechanism.
      */
     protected constructor(version: string, maximumSequenceCount: number, throwError: ThrowError) {
-        this._version = version;
-        this._maximumSequenceCount = maximumSequenceCount;
-        this._throwError = throwError;
+        this.#version = version;
+        this.#maximumSequenceCount = maximumSequenceCount;
+        this.#throwError = throwError;
     }
 
     /**
@@ -65,14 +68,14 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * Version.
      */
     get version(): string {
-        return this._version;
+        return this.#version;
     }
 
     /**
      * Determine if errors are reported through the throw/catch mechanism.
      */
     get throwError(): ThrowError {
-        return this._throwError;
+        return this.#throwError;
     }
 
     /**
@@ -82,9 +85,9 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * Maximum width supported by the application.
      */
     async maximumWidth(): Promise<number> {
-        this._maximumWidth ??= await this.getMaximumWidth();
+        this.#maximumWidth ??= await this.getMaximumWidth();
 
-        return this._maximumWidth;
+        return this.#maximumWidth;
     }
 
     /**
@@ -102,9 +105,9 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * Maximum height supported by the application.
      */
     async maximumHeight(): Promise<number> {
-        this._maximumHeight ??= await this.getMaximumHeight();
+        this.#maximumHeight ??= await this.getMaximumHeight();
 
-        return this._maximumHeight;
+        return this.#maximumHeight;
     }
 
     /**
@@ -149,10 +152,10 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
     validateSequenceCount(sequenceCount: number): void {
         const absoluteSequenceCount = Math.abs(sequenceCount);
 
-        if (absoluteSequenceCount > this._maximumSequenceCount) {
+        if (absoluteSequenceCount > this.#maximumSequenceCount) {
             throw new RangeError(i18nextAppExtension.t("AppExtension.sequenceCountMustBeLessThanOrEqualTo", {
                 sequenceCount: absoluteSequenceCount,
-                maximumSequenceCount: this._maximumSequenceCount
+                maximumSequenceCount: this.#maximumSequenceCount
             }));
         }
     }
@@ -188,6 +191,9 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
     /**
      * Bind a synchronous method and wrap it in a try/catch for comprehensive error handling.
      *
+     * @template TMethod
+     * Method type.
+     *
      * @param thisArg
      * The value to be passed as the `this` parameter to the method.
      *
@@ -215,6 +221,9 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
     /**
      * Bind an asynchronous method and wrap it in a try/catch for comprehensive error handling.
      *
+     * @template TMethod
+     * Method type.
+     *
      * @param thisArg
      * The value to be passed as the `this` parameter to the method.
      *

package/src/app-utility-proxy.ts

@@ -1,8 +1,8 @@
 import { isNullish, type NonNullishable, type Nullishable } from "@aidc-toolkit/core";
-import { type ParameterDescriptor, ProxyClass, ProxyMethod, ProxyParameter, Types } from "./descriptor";
-import { LibProxy } from "./lib-proxy";
-import { i18nextAppExtension } from "./locale/i18n";
-import type { ErrorExtends, Matrix } from "./type";
+import { type ParameterDescriptor, ProxyClass, ProxyMethod, ProxyParameter, Types } from "./descriptor.js";
+import { LibProxy } from "./lib-proxy.js";
+import { i18nextAppExtension } from "./locale/i18n.js";
+import type { ErrorExtends, Matrix } from "./type.js";
 
 const spillMatrix: ParameterDescriptor = {
     name: "spillMatrix",
@@ -47,6 +47,18 @@ interface MaximumDimensions {
 
 /**
  * Application utilities.
+ *
+ *@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.
  */
 @ProxyClass()
 export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt> {
@@ -76,7 +88,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
      * @returns
      * Array of maximum width and maximum height.
      */
-    private async defaultMaximums(maximumDimensions: MaximumDimensions, invocationContext: Nullishable<TInvocationContext>): Promise<NonNullishable<MaximumDimensions>> {
+    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");
@@ -140,7 +152,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
             throw new RangeError(i18nextAppExtension.t("Proxy.vSpillMustBeHorizontalArray"));
         }
 
-        const maximumDimensions = await this.defaultMaximums({
+        const maximumDimensions = await this.#defaultMaximums({
             width: maximumWidth,
             height: maximumHeight
         }, invocationContext);
@@ -222,7 +234,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
             }
         }
 
-        const maximumDimensions = await this.defaultMaximums({
+        const maximumDimensions = await this.#defaultMaximums({
             width: maximumWidth,
             height: maximumHeight
         }, invocationContext);

package/src/descriptor.ts

@@ -1,7 +1,7 @@
 import type { TypedFunction } from "@aidc-toolkit/core";
-import type { AppExtension } from "./app-extension";
-import { LibProxy } from "./lib-proxy";
-import type { ErrorExtends } from "./type";
+import type { AppExtension } from "./app-extension.js";
+import { LibProxy } from "./lib-proxy.js";
+import type { ErrorExtends } from "./type.js";
 
 /**
  * Core descriptor.
@@ -167,8 +167,23 @@ export interface ClassDescriptor extends Descriptor {
 
 /**
  * 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;
+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.
@@ -188,6 +203,21 @@ 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.
  *
@@ -203,6 +233,21 @@ export function ProxyParameter<ThrowError extends boolean, TError extends ErrorE
 /**
  * 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.
  *
@@ -258,6 +303,21 @@ export function ProxyMethod<ThrowError extends boolean, TError extends ErrorExte
 /**
  * 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.
  *

package/src/generator/descriptor.ts

@@ -1,4 +1,4 @@
-import type { BaseParameterDescriptor, ClassDescriptor, MethodDescriptor } from "../descriptor";
+import type { BaseParameterDescriptor, ClassDescriptor, MethodDescriptor } from "../descriptor.js";
 
 /**
  * Localization.
@@ -33,12 +33,15 @@ export interface ParameterLocalization extends Localization {
 
 /**
  * Localization descriptor.
+ *
+ * @param TLocalization
+ * Localization type.
  */
-export interface LocalizationDescriptor<T extends Localization> {
+export interface LocalizationDescriptor<TLocalization extends Localization> {
     /**
      * Localizations map by locale.
      */
-    readonly localizationsMap: ReadonlyMap<string, T>;
+    readonly localizationsMap: ReadonlyMap<string, TLocalization>;
 }
 
 /**

package/src/generator/generator.ts

@@ -1,14 +1,28 @@
 import { I18nEnvironments } from "@aidc-toolkit/core";
 import type { ParseKeys } from "i18next";
-import { expandParameterDescriptor, getClassDescriptorsMap } from "../descriptor";
-import { appExtensionResources, i18nAppExtensionInit, i18nextAppExtension } from "../locale/i18n";
+import { AppUtilityProxy } from "../app-utility-proxy.js";
+import { expandParameterDescriptor, getClassDescriptorsMap } from "../descriptor.js";
+import * as GS1 from "../gs1/index.js";
+import { appExtensionResources, i18nAppExtensionInit, i18nextAppExtension } from "../locale/i18n.js";
+import * as Utility from "../utility/index.js";
 import type {
     FunctionLocalization,
     Localization,
     ParameterLocalization,
     ProxyFunctionDescriptor,
     ProxyObjectDescriptor
-} from "./descriptor";
+} from "./descriptor.js";
+
+/**
+ * Dummy method to force proxies to register their decorators.
+ *
+ * @param _proxies
+ * Proxies.
+ */
+function registerProxies(..._proxies: unknown[]): void {
+}
+
+registerProxies(AppUtilityProxy, Utility, GS1);
 
 /**
  * Abstract generator.
@@ -17,32 +31,32 @@ export abstract class Generator {
     /**
      * Documentation base URL.
      */
-    private static readonly DOCUMENTATION_BASE_URL = "https://aidc-toolkit.com/";
+    static readonly #DOCUMENTATION_BASE_URL = "https://aidc-toolkit.com/";
 
     /**
      * Documentation path, optionally preceded by locale.
      */
-    private static readonly DOCUMENTATION_PATH = "app-extension/";
+    static readonly #DOCUMENTATION_PATH = "app-extension/";
 
     /**
      * Locales.
      */
-    private readonly _locales: readonly string[];
+    readonly #locales: readonly string[];
 
     /**
      * Default locale.
      */
-    private readonly _defaultLocale: string;
+    readonly #defaultLocale: string;
 
     /**
      * Map of function localizations maps by namespace function name.
      */
-    private readonly _functionLocalizationsMapsMap = new Map<string, ReadonlyMap<string, FunctionLocalization>>();
+    readonly #functionLocalizationsMapsMap = new Map<string, ReadonlyMap<string, FunctionLocalization>>();
 
     /**
      * Map of parameter localizations maps by namespace function parameter name.
      */
-    private readonly _parameterLocalizationsMapsMap = new Map<string, ReadonlyMap<string, ParameterLocalization>>();
+    readonly #parameterLocalizationsMapsMap = new Map<string, ReadonlyMap<string, ParameterLocalization>>();
 
     /**
      *
@@ -55,22 +69,22 @@ export abstract class Generator {
      * Include localizations if true.
      */
     constructor(includeLocalizations = true) {
-        this._locales = includeLocalizations ? Object.keys(appExtensionResources) : [];
-        this._defaultLocale = this._locales[0] ?? "";
+        this.#locales = includeLocalizations ? Object.keys(appExtensionResources) : [];
+        this.#defaultLocale = this.#locales[0] ?? "";
     }
 
     /**
      * Get the locales.
      */
     protected get locales(): readonly string[] {
-        return this._locales;
+        return this.#locales;
     }
 
     /**
      * Get the default locale.
      */
     protected get defaultLocale(): string {
-        return this._defaultLocale;
+        return this.#defaultLocale;
     }
 
     /**
@@ -86,10 +100,10 @@ export abstract class Generator {
      * Function localization.
      */
     protected getFunctionLocalization(namespaceFunctionName: string, locale: string): FunctionLocalization {
-        const functionLocalization = this._functionLocalizationsMapsMap.get(namespaceFunctionName)?.get(locale);
+        const functionLocalization = this.#functionLocalizationsMapsMap.get(namespaceFunctionName)?.get(locale);
 
         if (functionLocalization === undefined) {
-            throw new Error(`Localization for function "${namespaceFunctionName}", locale "${locale}" not found`);
+            throw new Error(`${locale} localization for function ${namespaceFunctionName} not found`);
         }
 
         return functionLocalization;
@@ -111,10 +125,10 @@ export abstract class Generator {
      * Function localization.
      */
     protected getParameterLocalization(namespaceFunctionName: string, parameterName: string, locale: string): ParameterLocalization {
-        const parameterLocalization = this._parameterLocalizationsMapsMap.get(`${namespaceFunctionName}.${parameterName}`)?.get(locale);
+        const parameterLocalization = this.#parameterLocalizationsMapsMap.get(`${namespaceFunctionName}.${parameterName}`)?.get(locale);
 
         if (parameterLocalization === undefined) {
-            throw new Error(`Localization for function "${namespaceFunctionName}", parameter "${parameterName}", locale "${locale}" not found`);
+            throw new Error(`${locale} localization for function ${namespaceFunctionName} parameter ${parameterName} not found`);
         }
 
         return parameterLocalization;
@@ -152,6 +166,9 @@ export abstract class Generator {
     /**
      * Generate localizations map.
      *
+     * @template TLocalization
+     * Localization type.
+     *
      * @param localizedKeyPrefix
      * Localized key prefix.
      *
@@ -161,8 +178,8 @@ export abstract class Generator {
      * @returns
      * Localization map.
      */
-    private generateLocalizationsMap<T extends Localization>(localizedKeyPrefix: string, localizationCallback: (locale: string, localization: Localization) => T): ReadonlyMap<string, T> {
-        return new Map(this._locales.map((locale) => {
+    #generateLocalizationsMap<TLocalization extends Localization>(localizedKeyPrefix: string, localizationCallback: (locale: string, localization: Localization) => TLocalization): ReadonlyMap<string, TLocalization> {
+        return new Map(this.#locales.map((locale) => {
             const lngOption = {
                 lng: locale
             };
@@ -184,6 +201,10 @@ export abstract class Generator {
 
         await i18nAppExtensionInit(I18nEnvironments.CLI);
 
+        // const LocaleResourcesSource = path.resolve(LocaleResourcesGenerator.IMPORT_PATH, entry.name, "locale-resources.ts");
+        //
+        // await import(LocaleResourcesSource).then((module) => {
+
         this.initialize();
 
         try {
@@ -237,7 +258,7 @@ export abstract class Generator {
                         const insertIndex = methodName.indexOf(infixBefore);
 
                         if (insertIndex === -1) {
-                            throw new Error(`Cannot find "${infixBefore}" in method name ${methodName}`);
+                            throw new Error(`Cannot find "${infixBefore}" in method ${methodName}`);
                         }
 
                         // Other classes in the hierarchy and infix is in the middle of the string.
@@ -246,12 +267,12 @@ export abstract class Generator {
 
                     const namespaceFunctionName = `${namespacePrefix}${functionName}`;
 
-                    const functionLocalizationsMap = this.generateLocalizationsMap<FunctionLocalization>(`Functions.${namespaceFunctionName}.`, (locale, localization) => ({
+                    const functionLocalizationsMap = this.#generateLocalizationsMap<FunctionLocalization>(`Functions.${namespaceFunctionName}.`, (locale, localization) => ({
                         ...localization,
-                        documentationURL: `${Generator.DOCUMENTATION_BASE_URL}${locale === this.defaultLocale ? "" : `${locale}/`}${Generator.DOCUMENTATION_PATH}${namespace === undefined ? "" : `${namespace}/`}${localization.name}.html`
+                        documentationURL: `${Generator.#DOCUMENTATION_BASE_URL}${locale === this.defaultLocale ? "" : `${locale}/`}${Generator.#DOCUMENTATION_PATH}${namespace === undefined ? "" : `${namespace}/`}${localization.name}.html`
                     }));
 
-                    this._functionLocalizationsMapsMap.set(namespaceFunctionName, functionLocalizationsMap);
+                    this.#functionLocalizationsMapsMap.set(namespaceFunctionName, functionLocalizationsMap);
 
                     this.createProxyFunction({
                         ...proxyObjectDescriptor,
@@ -263,9 +284,9 @@ export abstract class Generator {
 
                             const parameterName = expandedParameterDescriptor.name;
 
-                            const parameterLocalizationsMap = this.generateLocalizationsMap(`Parameters.${parameterName}.`, (_locale, localization) => localization);
+                            const parameterLocalizationsMap = this.#generateLocalizationsMap(`Parameters.${parameterName}.`, (_locale, localization) => localization);
 
-                            this._parameterLocalizationsMapsMap.set(`${namespaceFunctionName}.${parameterName}`, parameterLocalizationsMap);
+                            this.#parameterLocalizationsMapsMap.set(`${namespaceFunctionName}.${parameterName}`, parameterLocalizationsMap);
 
                             return {
                                 namespace,

package/src/generator/index.ts

@@ -1,2 +1,2 @@
-export type * from "./descriptor";
-export * from "./generator";
+export type * from "./descriptor.js";
+export * from "./generator.js";