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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidc-toolkit/app-extension",
-  "version": "1.0.28-beta",
+  "version": "1.0.32-beta",
   "description": "Application extension framework for AIDC Toolkit",
   "type": "module",
   "main": "dist/index.js",
@@ -19,21 +19,20 @@
     "url": "https://www.linkedin.com/in/kdean"
   },
   "scripts": {
-    "locale-resources-generator": "tsx src/generator/locale-resources-generator.ts",
+    "generate-locale-resources": "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:dev": "npm run tsc:core -- --noEmit && tsup --define.mode=dev",
     "build:release": "npm run tsc:core -- --noEmit && tsup",
     "build:doc": "npm run build:dev"
   },
   "devDependencies": {
-    "@aidc-toolkit/dev": "1.0.28-beta"
+    "@aidc-toolkit/dev": "1.0.32-beta"
   },
   "dependencies": {
-    "@aidc-toolkit/core": "1.0.28-beta",
-    "@aidc-toolkit/gs1": "1.0.28-beta",
-    "@aidc-toolkit/utility": "1.0.28-beta",
-    "i18next": "^25.7.2"
+    "@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"
   }
 }

package/src/app-data.ts

@@ -0,0 +1,94 @@
+import { fromByteArray, toByteArray } from "base64-js";
+
+/**
+ * Application data.
+ */
+export type AppData = string | number | boolean | Date | Uint8Array | object;
+
+/**
+ * Decode application data from an encoded string.
+ *
+ * @param stringData
+ * String data.
+ *
+ * @returns
+ * Decoded application data.
+ */
+export function decodeAppData(stringData: string): AppData | undefined {
+    let decodedAppData: AppData | undefined;
+
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Mapping is expected to be correct.
+        decodedAppData = JSON.parse(stringData, (_key, value: unknown) => {
+            let replacementValue = value;
+
+            // Decode string representing date/time and binary array and pass through other values unmodified.
+            if (typeof value === "string") {
+                // First capture group is type, second is data; simple split at ':' character.
+                const stringDataGroups = /^(?<type>\w+):(?<data>.*)$/u.exec(value)?.groups;
+
+                if (stringDataGroups !== undefined) {
+                    const type = stringDataGroups["type"];
+                    const data = stringDataGroups["data"];
+
+                    switch (type) {
+                        case "dateTime":
+                            replacementValue = new Date(data);
+                            break;
+
+                        case "binary":
+                            replacementValue = toByteArray(data);
+                            break;
+                    }
+                }
+            }
+
+            return replacementValue;
+        }) as AppData;
+    } catch {
+        // String data is not valid JSON; discard it.
+        decodedAppData = undefined;
+    }
+
+    return decodedAppData;
+}
+
+/**
+ * Encode an object to a format suitable for storage.
+ *
+ * @param data
+ * Object.
+ *
+ * @returns
+ * Object suitable for storage with date/time and binary types encoded as strings.
+ */
+function encodeObject(data: object): object | string {
+    let mappedData: object | string;
+
+    if (data instanceof Date) {
+        mappedData = `dateTime:${data.toISOString()}`;
+    } else if (data instanceof Uint8Array) {
+        mappedData = `binary:${fromByteArray(data)}`;
+    } else {
+        mappedData = Object.fromEntries(Object.entries(data).map(([key, value]: [string, unknown]) =>
+            // Encode date/time and binary array as string and pass through other values unmodified.
+            [key, typeof value === "object" && value !== null ? encodeObject(value) : value]
+        ));
+    }
+
+    return mappedData;
+}
+
+/**
+ * Encode application data as a string for storage. Encoded string is in JSON format with date/time and binary data
+ * converted to identifiable strings for decoding.
+ *
+ * @param appData
+ * Application data.
+ *
+ * @returns
+ * Encoded application data.
+ */
+export function encodeAppData(appData: AppData): string {
+    return JSON.stringify(typeof appData !== "object" ? appData : encodeObject(appData));
+}

package/src/app-extension.ts

@@ -1,6 +1,9 @@
-import type { TypedAsyncFunction, TypedFunction, TypedSyncFunction } from "@aidc-toolkit/core";
+import { 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 { 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 +17,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 prefix for properties and application data.
+     */
+    static readonly APPLICATION_NAME_PREFIX = "AIDCToolkit.";
+
+    /**
+     * Version property name.
+     */
+    static readonly VERSION_NAME = `${AppExtension.APPLICATION_NAME_PREFIX}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 +60,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 +81,31 @@ 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",
+            hideLogPositionForProduction: isProduction
+        });
+
+        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.getFileProperty(AppExtension.VERSION_NAME);
+
+        if (fileVersion !== this.#version) {
+            await this.setFileProperty(AppExtension.VERSION_NAME, this.#version);
+        }
     }
 
     /**
@@ -79,44 +126,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 +158,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 +172,87 @@ 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 file.
+     *
+     * @param name
+     * Property name.
+     *
+     * @returns
+     * Property value or undefined if no value is stored under the given name.
+     */
+    abstract getFileProperty(name: string): Promisable<string | undefined>;
+
+    /**
+     * Set a property to be stored within the active file.
+     *
+     * @param name
+     * Property name.
+     *
+     * @param value
+     * Property value or null to remove.
+     */
+    abstract setFileProperty(name: string, value: string | null): Promisable<void>;
+
+    /**
+     * Get application data stored within the active file.
+     *
+     * @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.
+     */
+    abstract setFileData(name: string, appData: AppData | null): 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.
+     */
+    abstract getSharedData(name: string): Promisable<AppData | undefined>;
+
+    /**
+     * 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.
+     */
+    abstract setSharedData(name: string, appData: AppData | null): Promisable<void>;
 
     /**
      * Validate a sequence count against the maximum supported by application.
@@ -169,7 +280,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 +312,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));
-        });
-    }
 }