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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@aidc-toolkit/app-extension",
-  "version": "1.0.31-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,21 +19,20 @@
     "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": "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.31-beta"
+    "@aidc-toolkit/dev": "1.0.33-beta"
   },
   "dependencies": {
-    "@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"
+    "@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,15 @@
-import type { TypedAsyncFunction, TypedFunction, TypedSyncFunction } from "@aidc-toolkit/core";
+import {
+    type AppDataStorage,
+    getLogger,
+    type Hyperlink,
+    LogLevels,
+    MemoryTransport,
+    type Promisable
+} from "@aidc-toolkit/core";
+import type { Logger } from "tslog";
 import { i18nextAppExtension } from "./locale/i18n.js";
-import type { ErrorExtends, ResultError, SheetAddress, SheetRange } from "./type.js";
+import type { StreamingCancelledCallback, StreamingConsumerCallback } from "./streaming.js";
+import type { ErrorExtends, MatrixResult, SheetAddress, SheetRange, SingletonResult } from "./type.js";
 
 /**
  * Application extension.
@@ -14,10 +23,33 @@ import type { ErrorExtends, ResultError, SheetAddress, SheetRange } from "./type
  * @template TInvocationContext
  * Application-specific invocation context type.
  *
+ * @template TStreamingInvocationContext
+ * Application-specific streaming 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> {
+export abstract class AppExtension<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    /**
+     * Application name.
+     */
+    static readonly APPLICATION_NAME = "AIDCToolkit";
+
+    /**
+     * Version property name.
+     */
+    static readonly VERSION_NAME = `${AppExtension.APPLICATION_NAME}.version`;
+
+    /**
+     * Maximum logger messages length.
+     */
+    static readonly #MAXIMUM_LOGGER_MESSAGES_LENGTH = 120;
+
+    /**
+     * Truncate logger messages length.
+     */
+    static readonly #TRUNCATE_LOGGER_MESSAGES_LENGTH = 100;
+
     /**
      * Application version.
      */
@@ -34,14 +66,14 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
     readonly #throwError: ThrowError;
 
     /**
-     * Maximum width supported by application.
+     * Logger.
      */
-    #maximumWidth?: number;
+    readonly #logger: Logger<object>;
 
     /**
-     * Maximum height supported by application.
+     * Logger memory transport.
      */
-    #maximumHeight?: number;
+    readonly #memoryTransport: MemoryTransport<object>;
 
     /**
      * Constructor.
@@ -55,10 +87,30 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @param throwError
      * If true, errors are reported through the throw/catch mechanism.
      */
-    constructor(version: string, maximumSequenceCount: number, throwError: ThrowError) {
+    protected constructor(version: string, maximumSequenceCount: number, throwError: ThrowError) {
         this.#version = version;
         this.#maximumSequenceCount = maximumSequenceCount;
         this.#throwError = throwError;
+
+        // Running in production if version doesn't include a pre-release identifier.
+        const isProduction = !version.includes("-");
+
+        this.#logger = getLogger(isProduction ? LogLevels.Info : LogLevels.Debug, {
+            type: isProduction ? "hidden" : "pretty"
+        });
+
+        this.#memoryTransport = new MemoryTransport(this.#logger, AppExtension.#MAXIMUM_LOGGER_MESSAGES_LENGTH, AppExtension.#TRUNCATE_LOGGER_MESSAGES_LENGTH);
+    }
+
+    /**
+     * Initialize the application extension.
+     */
+    async initialize(): Promise<void> {
+        const fileVersion = await this.getDocumentProperty(AppExtension.VERSION_NAME);
+
+        if (fileVersion !== this.#version) {
+            await this.setDocumentProperty(AppExtension.VERSION_NAME, this.#version);
+        }
     }
 
     /**
@@ -79,44 +131,28 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
     }
 
     /**
-     * Get the maximum width supported by the application.
-     *
-     * @returns
-     * Maximum width supported by the application.
+     * Get the logger.
      */
-    async maximumWidth(): Promise<number> {
-        this.#maximumWidth ??= await this.getMaximumWidth();
-
-        return this.#maximumWidth;
+    get logger(): Logger<object> {
+        return this.#logger;
     }
 
     /**
-     * Get the maximum width supported by the application.
-     *
-     * @returns
-     * Maximum width supported by the application.
+     * Get the logger memory transport.
      */
-    protected abstract getMaximumWidth(): number | Promise<number>;
+    get memoryTransport(): MemoryTransport<object> {
+        return this.#memoryTransport;
+    }
 
     /**
-     * Get the maximum height supported by the application.
-     *
-     * @returns
-     * Maximum height supported by the application.
+     * Get the maximum width supported by the application.
      */
-    async maximumHeight(): Promise<number> {
-        this.#maximumHeight ??= await this.getMaximumHeight();
-
-        return this.#maximumHeight;
-    }
+    abstract get maximumWidth(): number;
 
     /**
      * Get the maximum height supported by the application.
-     *
-     * @returns
-     * Maximum height supported by the application.
      */
-    protected abstract getMaximumHeight(): number | Promise<number>;
+    abstract get maximumHeight(): number;
 
     /**
      * Get the sheet address from an invocation context.
@@ -127,7 +163,7 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @returns
      * Sheet address.
      */
-    abstract getSheetAddress(invocationContext: TInvocationContext): SheetAddress | Promise<SheetAddress>;
+    abstract getSheetAddress(invocationContext: TInvocationContext): Promisable<SheetAddress>;
 
     /**
      * Get a parameter range from an invocation context.
@@ -141,7 +177,61 @@ 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): SheetRange | null | Promise<SheetRange | null>;
+    abstract getParameterSheetRange(invocationContext: TInvocationContext, parameterNumber: number): Promisable<SheetRange | null>;
+
+    /**
+     * Set up streaming for a streaming function.
+     *
+     * @param streamingInvocationContext
+     * Streaming invocation context.
+     *
+     * @param streamingCancelledCallback
+     * Streaming cancelled callback, called when streaming is cancelled.
+     *
+     * @returns
+     * Streaming consumer callback, called when stream contents updated.
+     */
+    abstract setUpStreaming<TResult>(streamingInvocationContext: TStreamingInvocationContext, streamingCancelledCallback: StreamingCancelledCallback): StreamingConsumerCallback<TResult, ThrowError, TError>;
+
+    /**
+     * Get a property stored within the active document.
+     *
+     * @param name
+     * Property name.
+     *
+     * @returns
+     * Property value or undefined if no value is stored under the given name.
+     */
+    abstract getDocumentProperty(name: string): Promisable<string | undefined>;
+
+    /**
+     * Set a property to be stored within the active document.
+     *
+     * @param name
+     * Property name.
+     *
+     * @param value
+     * Property value.
+     */
+    abstract setDocumentProperty(name: string, value: string): Promisable<void>;
+
+    /**
+     * Delete a property from the active document.
+     *
+     * @param name
+     * Property name.
+     */
+    abstract deleteDocumentProperty(name: string): Promisable<void>;
+
+    /**
+     * Get application data storage for the current document.
+     */
+    abstract get documentAppDataStorage(): AppDataStorage<boolean>;
+
+    /**
+     * Get application data storage shared across multiple documents.
+     */
+    abstract get sharedAppDataStorage(): AppDataStorage<boolean>;
 
     /**
      * Validate a sequence count against the maximum supported by application.
@@ -169,7 +259,21 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * @returns
      * Mapped big integer value.
      */
-    abstract mapBigInt(value: bigint): ResultError<TBigInt, ThrowError, TError>;
+    abstract mapBigInt(value: bigint): SingletonResult<TBigInt, ThrowError, TError>;
+
+    /**
+     * Map hyperlink results to a form suitable for the application.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @param matrixHyperlinkResults
+     * Matrix of hyperlink results from function call.
+     *
+     * @returns
+     * Matrix of results in a form suitable for the application.
+     */
+    abstract mapHyperlinkResults(invocationContext: TInvocationContext, matrixHyperlinkResults: MatrixResult<Hyperlink, ThrowError, TError>): Promisable<MatrixResult<unknown, ThrowError, TError>>;
 
     /**
      * Map a range error (thrown by the library) to an application-specific error. If errors are reported through the
@@ -187,60 +291,4 @@ export abstract class AppExtension<ThrowError extends boolean, TError extends Er
      * Message to include in the error.
      */
     abstract handleError(message: string): never;
-
-    /**
-     * 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.
-     *
-     * @param method
-     * Method to call.
-     *
-     * @returns
-     * Function wrapped around the method.
-     */
-    bindSync<TMethod extends TypedSyncFunction<TMethod>>(thisArg: ThisParameterType<TMethod>, method: TMethod): TypedFunction<TMethod> {
-        const boundMethod = method.bind(thisArg);
-
-        return (...args: Parameters<TMethod>): ReturnType<TMethod> => {
-            try {
-                return boundMethod(...args);
-            } catch (e: unknown) {
-                // eslint-disable-next-line no-console -- Necessary for diagnostics.
-                console.error(e);
-
-                this.handleError(e instanceof Error ? e.message : String(e));
-            }
-        };
-    }
-
-    /**
-     * 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.
-     *
-     * @param method
-     * Method to call.
-     *
-     * @returns
-     * Function wrapped around the method.
-     */
-    bindAsync<TMethod extends TypedAsyncFunction<TMethod>>(thisArg: ThisParameterType<TMethod>, method: TMethod): TypedAsyncFunction<TMethod> {
-        const boundMethod = method.bind(thisArg);
-
-        return async (...args: Parameters<TMethod>) => await boundMethod(...args).catch((e: unknown) => {
-            // eslint-disable-next-line no-console -- Necessary for diagnostics.
-            console.error(e);
-
-            this.handleError(e instanceof Error ? e.message : String(e));
-        });
-    }
 }

package/src/app-helper-proxy.ts

@@ -0,0 +1,326 @@
+import { isNullish, type LogLevel, logLevelOf, type NonNullishable, type Nullishable } from "@aidc-toolkit/core";
+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 spillArrayParameterDescriptor: ParameterDescriptor = {
+    name: "spillArray",
+    type: Types.Any,
+    multiplicity: Multiplicities.Array,
+    isRequired: true
+};
+
+const spillMaximumParameterDescriptor: ParameterDescriptor = {
+    name: "spillMaximum",
+    type: Types.Number,
+    multiplicity: Multiplicities.Singleton,
+    isRequired: false
+};
+
+const spillMaximumWidthParameterDescriptor: ExtendsParameterDescriptor = {
+    extendsDescriptor: spillMaximumParameterDescriptor,
+    sortOrder: 0,
+    name: "spillMaximumWidth"
+};
+
+const spillMaximumHeightParameterDescriptor: ExtendsParameterDescriptor = {
+    extendsDescriptor: spillMaximumParameterDescriptor,
+    sortOrder: 1,
+    name: "spillMaximumHeight"
+};
+
+/**
+ * Maximum dimensions.
+ */
+interface MaximumDimensions {
+    /**
+     * Optional maximum width.
+     */
+    width: Nullishable<number>;
+
+    /**
+     * Optional maximum height.
+     */
+    height: Nullishable<number>;
+}
+
+/**
+ * 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 TStreamingInvocationContext
+ * Application-specific streaming invocation context type.
+ * 
+ * @template TBigInt
+ * Type to which big integer is mapped.
+ */
+@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.
+     *
+     * @returns
+     * Version.
+     */
+    @proxy.describeMethod({
+        type: Types.String,
+        multiplicity: Multiplicities.Singleton,
+        parameterDescriptors: []
+    })
+    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.
+     */
+    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 ?? this.appExtension.maximumWidth - sheetAddress.columnIndex;
+            definedMaximumHeight = maximumHeight ?? this.appExtension.maximumHeight - sheetAddress.rowIndex;
+        } else {
+            definedMaximumWidth = maximumWidth;
+            definedMaximumHeight = maximumHeight;
+        }
+
+        return {
+            width: definedMaximumWidth,
+            height: definedMaximumHeight
+        };
+    }
+
+    /**
+     * Spill a one-dimensional matrix to fit a rectangle within a given maximum height and width.
+     *
+     * @param arrayValues
+     * Matrix values. Matrix is length 1 or 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.
+     */
+    @proxy.describeMethod({
+        requiresContext: true,
+        type: Types.Any,
+        multiplicity: Multiplicities.Matrix,
+        parameterDescriptors: [spillArrayParameterDescriptor, spillMaximumHeightParameterDescriptor, spillMaximumWidthParameterDescriptor]
+    })
+    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 = arrayValues.length;
+        const width = height !== 0 ? arrayValues[0].length : 0;
+
+        const isArrayOrError = this.singletonResult(() => {
+            if (height > 1 && width > 1) {
+                throw new RangeError(i18nextAppExtension.t("Proxy.matrixMustBeArray"));
+            }
+
+            return true;
+        });
+
+        if (isArrayOrError === true) {
+            const maximumDimensions = await this.#defaultMaximums({
+                width: maximumWidth,
+                height: maximumHeight
+            }, invocationContext);
+
+            const isHorizontal = height === 1;
+            const length = isHorizontal ? width : height;
+            const maximumParallel = isHorizontal ? maximumDimensions.width : maximumDimensions.height;
+            const maximumPerpendicular = isHorizontal ? maximumDimensions.height : maximumDimensions.width;
+            const maximumArea = maximumParallel * maximumPerpendicular;
+
+            // Lengths 0 and 1 are valid and require no special processing.
+            if (length > 1 && length <= maximumArea) {
+                const lengthSquareRoot = Math.sqrt(length);
+
+                let spillParallel: number | undefined = undefined;
+
+                // Array that has a length of a power of 10 is treated specially.
+                if (Number.isInteger(Math.log10(length))) {
+                    // Try spill that is a power of 10, favouring the parallel direction.
+                    let spillParallel10 = 10 ** Math.ceil(Math.log10(lengthSquareRoot));
+
+                    // Favour the perpendicular direction if not enough parallel space.
+                    if (spillParallel10 > maximumParallel) {
+                        spillParallel10 /= 10;
+                    }
+
+                    // Take result as the spill parallel if it fits.
+                    if (spillParallel10 <= maximumParallel && length / spillParallel10 <= maximumPerpendicular) {
+                        spillParallel = spillParallel10;
+                    }
+                }
+
+                // Make spill as square as possible, favouring the parallel direction.
+                spillParallel ??= Math.max(Math.min(Math.ceil(lengthSquareRoot), maximumParallel), Math.floor(length / maximumPerpendicular));
+
+                const spillPerpendicular = Math.ceil(length / spillParallel);
+
+                result = [];
+
+                if (isHorizontal) {
+                    let startIndex = 0;
+
+                    do {
+                        const endIndex = startIndex + spillParallel;
+
+                        // Each row is a slice of the original single row.
+                        const row = arrayValues[0].slice(startIndex, endIndex);
+
+                        // Row length will be anywhere from 1 to spillParallel.
+                        if (row.length < spillParallel) {
+                            const rowLength = row.length;
+
+                            row.length = spillParallel;
+
+                            // Fill empty cells with empty string.
+                            row.fill("", rowLength, spillParallel);
+                        }
+
+                        result.push(row);
+
+                        startIndex = endIndex;
+                    } while (startIndex < length);
+                } else {
+                    for (let rowIndex = 0; rowIndex < spillParallel; rowIndex++) {
+                        const row: unknown[] = [];
+
+                        // Each column is a slice of the original single column.
+                        for (let valueIndex = rowIndex; valueIndex < length; valueIndex += spillParallel) {
+                            row.push(arrayValues[valueIndex][0]);
+                        }
+
+                        // Row length will always be spillPerpendicular or spillPerpendicular - 1.
+                        if (row.length < spillPerpendicular) {
+                            row[spillPerpendicular - 1] = "";
+                        }
+
+                        result.push(row);
+                    }
+                }
+            } else {
+                // Return matrix unmodified and let application handle spill error if any.
+                result = arrayValues;
+            }
+        } else {
+            // Return error as only element in matrix.
+            result = [[isArrayOrError]];
+        }
+
+        return result;
+    }
+
+    /**
+     * Get the logger messages as a stream.
+     *
+     * @param logLevelString
+     * Log level as string.
+     *
+     * @param streamingInvocationContext
+     * Streaming invocation context.
+     */
+    @proxy.describeMethod({
+        type: Types.String,
+        isHidden: true,
+        isStream: true,
+        multiplicity: Multiplicities.Array,
+        parameterDescriptors: [{
+            name: "logLevel",
+            type: Types.String,
+            multiplicity: Multiplicities.Singleton,
+            isRequired: false
+        }]
+    })
+    loggerMessages(logLevelString: Nullishable<string>, streamingInvocationContext: Nullishable<TStreamingInvocationContext>): void {
+        if (isNullish(streamingInvocationContext)) {
+            // Application error; no localization necessary.
+            throw new Error("Streaming invocation context not provided by application");
+        }
+
+        const appExtension = this.appExtension;
+
+        let notificationCallbackAdded = false;
+        let previousLogLevel: number | undefined = undefined;
+
+        const streamingConsumerCallback = appExtension.setUpStreaming<string>(streamingInvocationContext, () => {
+            if (notificationCallbackAdded) {
+                appExtension.memoryTransport.removeNotificationCallback("loggerMessages");
+            }
+
+            if (previousLogLevel !== undefined) {
+                appExtension.logger.settings.minLevel = previousLogLevel;
+            }
+        });
+
+        if (appExtension.memoryTransport.addNotificationCallback("loggerMessages", (_message, messages) => {
+            streamingConsumerCallback(this.iterableResult(() => messages));
+        })) {
+            notificationCallbackAdded = true;
+
+            let logLevel: LogLevel | undefined = undefined;
+
+            if (!isNullish(logLevelString)) {
+                try {
+                    logLevel = logLevelOf(logLevelString);
+                } catch {
+                    // Ignore error.
+                }
+            }
+
+            // Set log level if required.
+            if (logLevel !== undefined) {
+                previousLogLevel = appExtension.logger.settings.minLevel;
+                appExtension.logger.settings.minLevel = logLevel;
+            }
+        } else {
+            // Diagnostic tool; localization not required.
+            streamingConsumerCallback([["Only one logger messages call allowable per workbook"]]);
+        }
+    }
+}