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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@aidc-toolkit/app-extension",
-  "version": "1.0.32-beta",
+  "version": "1.0.33-beta",
   "description": "Application extension framework for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
-  "homepage": "https://aidc-toolkit.com/",
+  "homepage": "https://aidc-toolkit.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aidc-toolkit/app-extension.git"
@@ -19,20 +19,20 @@
     "url": "https://www.linkedin.com/in/kdean"
   },
   "scripts": {
-    "generate-locale-resources": "tsx src/generator/locale-resources-generator.ts",
     "lint": "eslint",
-    "tsc:core": "tsc --project tsconfig-src.json",
-    "build:dev": "npm run tsc:core -- --noEmit && tsup --define.mode=dev",
-    "build:release": "npm run tsc:core -- --noEmit && tsup",
-    "build:doc": "npm run build:dev"
+    "build:base": "tsc --project tsconfig-src.json --noEmit && tsup",
+    "build:alpha": "npm run build:base -- --define.mode=alpha",
+    "build:beta": "npm run build:base -- --define.mode=beta",
+    "build:prod": "npm run build:base",
+    "build:doc": "npm run build:alpha",
+    "generate-locale-resources": "tsx src/generator/locale-resources-generator.ts"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "1.0.32-beta"
+    "@aidc-toolkit/dev": "1.0.33-beta"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "1.0.32-beta",
-    "@aidc-toolkit/gs1": "1.0.32-beta",
-    "@aidc-toolkit/utility": "1.0.32-beta",
-    "base64-js": "^1.5.1"
+    "@aidc-toolkit/core": "1.0.33-beta",
+    "@aidc-toolkit/gs1": "1.0.33-beta",
+    "@aidc-toolkit/utility": "1.0.33-beta"
   }
 }

package/src/app-extension.ts

@@ -1,6 +1,12 @@
-import { getLogger, type Hyperlink, LogLevels, MemoryTransport, type Promisable } from "@aidc-toolkit/core";
+import {
+    type AppDataStorage,
+    getLogger,
+    type Hyperlink,
+    LogLevels,
+    MemoryTransport,
+    type Promisable
+} from "@aidc-toolkit/core";
 import type { Logger } from "tslog";
-import type { AppData } from "./app-data.js";
 import { i18nextAppExtension } from "./locale/i18n.js";
 import type { StreamingCancelledCallback, StreamingConsumerCallback } from "./streaming.js";
 import type { ErrorExtends, MatrixResult, SheetAddress, SheetRange, SingletonResult } from "./type.js";
@@ -25,14 +31,14 @@ import type { ErrorExtends, MatrixResult, SheetAddress, SheetRange, SingletonRes
  */
 export abstract class AppExtension<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     /**
-     * Application name prefix for properties and application data.
+     * Application name.
      */
-    static readonly APPLICATION_NAME_PREFIX = "AIDCToolkit.";
+    static readonly APPLICATION_NAME = "AIDCToolkit";
 
     /**
      * Version property name.
      */
-    static readonly VERSION_NAME = `${AppExtension.APPLICATION_NAME_PREFIX}version`;
+    static readonly VERSION_NAME = `${AppExtension.APPLICATION_NAME}.version`;
 
     /**
      * Maximum logger messages length.
@@ -90,8 +96,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
         const isProduction = !version.includes("-");
 
         this.#logger = getLogger(isProduction ? LogLevels.Info : LogLevels.Debug, {
-            type: isProduction ? "hidden" : "pretty",
-            hideLogPositionForProduction: isProduction
+            type: isProduction ? "hidden" : "pretty"
         });
 
         this.#memoryTransport = new MemoryTransport(this.#logger, AppExtension.#MAXIMUM_LOGGER_MESSAGES_LENGTH, AppExtension.#TRUNCATE_LOGGER_MESSAGES_LENGTH);
@@ -101,10 +106,10 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * Initialize the application extension.
      */
     async initialize(): Promise<void> {
-        const fileVersion = await this.getFileProperty(AppExtension.VERSION_NAME);
+        const fileVersion = await this.getDocumentProperty(AppExtension.VERSION_NAME);
 
         if (fileVersion !== this.#version) {
-            await this.setFileProperty(AppExtension.VERSION_NAME, this.#version);
+            await this.setDocumentProperty(AppExtension.VERSION_NAME, this.#version);
         }
     }
 
@@ -189,7 +194,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
     abstract setUpStreaming<TResult>(streamingInvocationContext: TStreamingInvocationContext, streamingCancelledCallback: StreamingCancelledCallback): StreamingConsumerCallback<TResult, ThrowError, TError>;
 
     /**
-     * Get a property stored within the active file.
+     * Get a property stored within the active document.
      *
      * @param name
      * Property name.
@@ -197,62 +202,36 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @returns
      * Property value or undefined if no value is stored under the given name.
      */
-    abstract getFileProperty(name: string): Promisable<string | undefined>;
+    abstract getDocumentProperty(name: string): Promisable<string | undefined>;
 
     /**
-     * Set a property to be stored within the active file.
+     * Set a property to be stored within the active document.
      *
      * @param name
      * Property name.
      *
      * @param value
-     * Property value or null to remove.
+     * Property value.
      */
-    abstract setFileProperty(name: string, value: string | null): Promisable<void>;
+    abstract setDocumentProperty(name: string, value: string): Promisable<void>;
 
     /**
-     * Get application data stored within the active file.
+     * Delete a property from the active document.
      *
      * @param name
-     * Name under which data is stored.
-     *
-     * @returns
-     * Application data or undefined if no data is stored under the given name.
-     */
-    abstract getFileData(name: string): Promisable<AppData | undefined>;
-
-    /**
-     * Set application data to be stored within the active file.
-     *
-     * @param name
-     * Name under which to store data.
-     *
-     * @param appData
-     * Application data or null to remove.
+     * Property name.
      */
-    abstract setFileData(name: string, appData: AppData | null): Promisable<void>;
+    abstract deleteDocumentProperty(name: string): Promisable<void>;
 
     /**
-     * Get application data stored and shared across multiple files.
-     *
-     * @param name
-     * Name under which data is stored.
-     *
-     * @returns
-     * Application ata or undefined if no data is stored under the given name.
+     * Get application data storage for the current document.
      */
-    abstract getSharedData(name: string): Promisable<AppData | undefined>;
+    abstract get documentAppDataStorage(): AppDataStorage<boolean>;
 
     /**
-     * Set application data to be stored and shared across multiple files.
-     *
-     * @param name
-     * Name under which to store data.
-     *
-     * @param appData
-     * Application data or null to remove.
+     * Get application data storage shared across multiple documents.
      */
-    abstract setSharedData(name: string, appData: AppData | null): Promisable<void>;
+    abstract get sharedAppDataStorage(): AppDataStorage<boolean>;
 
     /**
      * Validate a sequence count against the maximum supported by application.

package/src/{app-utility-proxy.ts → app-helper-proxy.ts}

@@ -1,21 +1,21 @@
 import { isNullish, type LogLevel, logLevelOf, type NonNullishable, type Nullishable } from "@aidc-toolkit/core";
-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 { i18nextAppExtension } from "./locale/i18n.js";
 import { proxy } from "./proxy.js";
 import type { ErrorExtends, Matrix, MatrixResult } from "./type.js";
 
-const spillMatrixParameterDescriptor: ParameterDescriptor = {
-    name: "spillMatrix",
+const spillArrayParameterDescriptor: ParameterDescriptor = {
+    name: "spillArray",
     type: Types.Any,
-    isMatrix: true,
+    multiplicity: Multiplicities.Array,
     isRequired: true
 };
 
 const spillMaximumParameterDescriptor: ParameterDescriptor = {
     name: "spillMaximum",
     type: Types.Number,
-    isMatrix: false,
+    multiplicity: Multiplicities.Singleton,
     isRequired: false
 };
 
@@ -64,8 +64,10 @@ interface MaximumDimensions {
  * @template TBigInt
  * Type to which big integer is mapped.
  */
-@proxy.describeClass(false)
-export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+@proxy.describeClass(false, {
+    category: "helper"
+})
+export class AppHelperProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     /**
      * Get the version.
      *
@@ -74,7 +76,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
      */
     @proxy.describeMethod({
         type: Types.String,
-        isMatrix: false,
+        multiplicity: Multiplicities.Singleton,
         parameterDescriptors: []
     })
     version(): string {
@@ -125,7 +127,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
     /**
      * Spill a one-dimensional matrix to fit a rectangle within a given maximum height and width.
      *
-     * @param matrixValues
+     * @param arrayValues
      * Matrix values. Matrix is length 1 or contains arrays of length 1 with the values.
      *
      * @param maximumHeight
@@ -143,15 +145,15 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
     @proxy.describeMethod({
         requiresContext: true,
         type: Types.Any,
-        isMatrix: true,
-        parameterDescriptors: [spillMatrixParameterDescriptor, spillMaximumHeightParameterDescriptor, spillMaximumWidthParameterDescriptor]
+        multiplicity: Multiplicities.Matrix,
+        parameterDescriptors: [spillArrayParameterDescriptor, spillMaximumHeightParameterDescriptor, spillMaximumWidthParameterDescriptor]
     })
-    async spill(matrixValues: Matrix<unknown>, maximumHeight: Nullishable<number>, maximumWidth: Nullishable<number>, invocationContext: Nullishable<TInvocationContext>): Promise<MatrixResult<unknown, ThrowError, TError>> {
+    async spill(arrayValues: Matrix<unknown>, maximumHeight: Nullishable<number>, maximumWidth: Nullishable<number>, invocationContext: Nullishable<TInvocationContext>): Promise<MatrixResult<unknown, ThrowError, TError>> {
         let result: MatrixResult<unknown, ThrowError, TError>;
 
         // Assume matrix is uniformly two-dimensional.
-        const height = matrixValues.length;
-        const width = height !== 0 ? matrixValues[0].length : 0;
+        const height = arrayValues.length;
+        const width = height !== 0 ? arrayValues[0].length : 0;
 
         const isArrayOrError = this.singletonResult(() => {
             if (height > 1 && width > 1) {
@@ -209,7 +211,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
                         const endIndex = startIndex + spillParallel;
 
                         // Each row is a slice of the original single row.
-                        const row = matrixValues[0].slice(startIndex, endIndex);
+                        const row = arrayValues[0].slice(startIndex, endIndex);
 
                         // Row length will be anywhere from 1 to spillParallel.
                         if (row.length < spillParallel) {
@@ -231,7 +233,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
 
                         // Each column is a slice of the original single column.
                         for (let valueIndex = rowIndex; valueIndex < length; valueIndex += spillParallel) {
-                            row.push(matrixValues[valueIndex][0]);
+                            row.push(arrayValues[valueIndex][0]);
                         }
 
                         // Row length will always be spillPerpendicular or spillPerpendicular - 1.
@@ -244,7 +246,7 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
                 }
             } else {
                 // Return matrix unmodified and let application handle spill error if any.
-                result = matrixValues;
+                result = arrayValues;
             }
         } else {
             // Return error as only element in matrix.
@@ -267,11 +269,11 @@ export class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExt
         type: Types.String,
         isHidden: true,
         isStream: true,
-        isMatrix: true,
+        multiplicity: Multiplicities.Array,
         parameterDescriptors: [{
             name: "logLevel",
             type: Types.String,
-            isMatrix: false,
+            multiplicity: Multiplicities.Singleton,
             isRequired: false
         }]
     })

package/src/descriptor.ts

@@ -43,6 +43,42 @@ export type TypeKey = keyof typeof Types;
  */
 export type Type = typeof Types[TypeKey];
 
+/**
+ * Multiplicities supported by proxy methods.
+ */
+export const Multiplicities = {
+    /**
+     * Parameter or return value is a singleton.
+     */
+    Singleton: 0,
+
+    /**
+     * Parameter or return value is a singleton or an array.
+     */
+    Array: 1,
+
+    /**
+     * Parameter or return value is a singleton, an array, or a matrix.
+     */
+    Matrix: 2,
+
+    /**
+     * Parameter value is a singleton or array but is treated as a singleton internally and doesn't drive multiplicity
+     * of the return value. Return value is an array for use as a singleton array parameter.
+     */
+    SingletonArray: 3
+} as const;
+
+/**
+ * Multiplicity key.
+ */
+export type MultiplicityKey = keyof typeof Multiplicities;
+
+/**
+ * Multiplicity.
+ */
+export type Multiplicity = typeof Multiplicities[MultiplicityKey];
+
 /**
  * Type descriptor.
  */
@@ -53,9 +89,9 @@ interface TypeDescriptor extends Descriptor {
     readonly type: Type;
 
     /**
-     * True if type is a matrix (method accepts or returns, or parameter is, a two-dimensional array).
+     * Multiplicity.
      */
-    readonly isMatrix: boolean;
+    readonly multiplicity: Multiplicity;
 }
 
 /**
@@ -158,6 +194,11 @@ export interface ClassDescriptor extends Descriptor {
      */
     readonly namespace?: string | undefined;
 
+    /**
+     * Category.
+     */
+    readonly category: string;
+
     /**
      * Method infix. If undefined, method name is generated verbatim.
      */