@aidc-toolkit/app-extension 1.0.45 → 1.0.46-beta

package/dist/app-extension.d.ts

@@ -0,0 +1,194 @@
+import { type AppDataStorage, type Hyperlink, MemoryTransport, type Promisable } from "@aidc-toolkit/core";
+import type { Logger } from "tslog";
+import type { StreamingCancelledCallback, StreamingConsumerCallback } from "./streaming.js";
+import type { ErrorExtends, MatrixResult, SheetAddress, SheetRange, SingletonResult } from "./type.js";
+/**
+ * Application extension.
+ *
+ * @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.
+ */
+export declare abstract class AppExtension<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    #private;
+    /**
+     * Application name.
+     */
+    static readonly APPLICATION_NAME = "AIDCToolkit";
+    /**
+     * Version property name.
+     */
+    static readonly VERSION_NAME: string;
+    /**
+     * Constructor.
+     *
+     * @param version
+     * Application version.
+     *
+     * @param maximumSequenceCount
+     * Maximum sequence count supported by application.
+     *
+     * @param throwError
+     * If true, errors are reported through the throw/catch mechanism.
+     */
+    protected constructor(version: string, maximumSequenceCount: number, throwError: ThrowError);
+    /**
+     * Initialize the application extension.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the version.
+     *
+     * @returns
+     * Version.
+     */
+    get version(): string;
+    /**
+     * Determine if errors are reported through the throw/catch mechanism.
+     */
+    get throwError(): ThrowError;
+    /**
+     * Get the logger.
+     */
+    get logger(): Logger<object>;
+    /**
+     * Get the logger memory transport.
+     */
+    get memoryTransport(): MemoryTransport<object>;
+    /**
+     * Get the maximum width supported by the application.
+     */
+    abstract get maximumWidth(): number;
+    /**
+     * Get the maximum height supported by the application.
+     */
+    abstract get maximumHeight(): number;
+    /**
+     * Get the sheet address from an invocation context.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @returns
+     * Sheet address.
+     */
+    abstract getSheetAddress(invocationContext: TInvocationContext): Promisable<SheetAddress>;
+    /**
+     * Get a parameter range from an invocation context.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @param parameterNumber
+     * Parameter number.
+     *
+     * @returns
+     * Sheet range or null if parameter is not a range.
+     */
+    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.
+     *
+     * @param sequenceCount
+     * Sequence count.
+     */
+    validateSequenceCount(sequenceCount: number): void;
+    /**
+     * Map big integer to another type if necessary.
+     *
+     * @param value
+     * Big integer value to map.
+     *
+     * @returns
+     * Mapped big integer value.
+     */
+    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
+     * throw/catch mechanism, the implementation may return the range error unmodified if that is supported.
+     *
+     * @param rangeError
+     */
+    abstract mapRangeError(rangeError: RangeError): TError;
+    /**
+     * Handle an error with a message; called when an exception occurs outside the control of the AIDC Toolkit library.
+     * Implementation must not return, most likely by throwing the message wrapped in an error type.
+     *
+     * @param message
+     * Message to include in the error.
+     */
+    abstract handleError(message: string): never;
+}
+//# sourceMappingURL=app-extension.d.ts.map

package/dist/app-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-extension.d.ts","sourceRoot":"","sources":["../src/app-extension.ts"],"names":[],"mappings":"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"}

package/dist/app-extension.js

@@ -0,0 +1,133 @@
+import { getLogger, LogLevels, MemoryTransport } from "@aidc-toolkit/core";
+import { i18nextAppExtension } from "./locale/i18n.js";
+/**
+ * Application extension.
+ *
+ * @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.
+ */
+export class AppExtension {
+    /**
+     * Application name.
+     */
+    static APPLICATION_NAME = "AIDCToolkit";
+    /**
+     * Version property name.
+     */
+    static VERSION_NAME = `${AppExtension.APPLICATION_NAME}.version`;
+    /**
+     * Maximum logger messages length.
+     */
+    static #MAXIMUM_LOGGER_MESSAGES_LENGTH = 120;
+    /**
+     * Truncate logger messages length.
+     */
+    static #TRUNCATE_LOGGER_MESSAGES_LENGTH = 100;
+    /**
+     * Application version.
+     */
+    #version;
+    /**
+     * Maximum sequence count supported by application.
+     */
+    #maximumSequenceCount;
+    /**
+     * If true, errors are reported through the throw/catch mechanism.
+     */
+    #throwError;
+    /**
+     * Logger.
+     */
+    #logger;
+    /**
+     * Logger memory transport.
+     */
+    #memoryTransport;
+    /**
+     * Constructor.
+     *
+     * @param version
+     * Application version.
+     *
+     * @param maximumSequenceCount
+     * Maximum sequence count supported by application.
+     *
+     * @param throwError
+     * If true, errors are reported through the throw/catch mechanism.
+     */
+    constructor(version, maximumSequenceCount, 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() {
+        const fileVersion = await this.getDocumentProperty(AppExtension.VERSION_NAME);
+        if (fileVersion !== this.#version) {
+            await this.setDocumentProperty(AppExtension.VERSION_NAME, this.#version);
+        }
+    }
+    /**
+     * Get the version.
+     *
+     * @returns
+     * Version.
+     */
+    get version() {
+        return this.#version;
+    }
+    /**
+     * Determine if errors are reported through the throw/catch mechanism.
+     */
+    get throwError() {
+        return this.#throwError;
+    }
+    /**
+     * Get the logger.
+     */
+    get logger() {
+        return this.#logger;
+    }
+    /**
+     * Get the logger memory transport.
+     */
+    get memoryTransport() {
+        return this.#memoryTransport;
+    }
+    /**
+     * Validate a sequence count against the maximum supported by application.
+     *
+     * @param sequenceCount
+     * Sequence count.
+     */
+    validateSequenceCount(sequenceCount) {
+        const absoluteSequenceCount = Math.abs(sequenceCount);
+        if (absoluteSequenceCount > this.#maximumSequenceCount) {
+            throw new RangeError(i18nextAppExtension.t("AppExtension.sequenceCountMustBeLessThanOrEqualTo", {
+                sequenceCount: absoluteSequenceCount,
+                maximumSequenceCount: this.#maximumSequenceCount
+            }));
+        }
+    }
+}
+//# sourceMappingURL=app-extension.js.map

package/dist/app-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-extension.js","sourceRoot":"","sources":["../src/app-extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,SAAS,EAET,SAAS,EACT,eAAe,EAElB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAgB,YAAY;IAC9B;;OAEG;IACH,MAAM,CAAU,gBAAgB,GAAG,aAAa,CAAC;IAEjD;;OAEG;IACH,MAAM,CAAU,YAAY,GAAG,GAAG,YAAY,CAAC,gBAAgB,UAAU,CAAC;IAE1E;;OAEG;IACH,MAAM,CAAU,+BAA+B,GAAG,GAAG,CAAC;IAEtD;;OAEG;IACH,MAAM,CAAU,gCAAgC,GAAG,GAAG,CAAC;IAEvD;;OAEG;IACM,QAAQ,CAAS;IAE1B;;OAEG;IACM,qBAAqB,CAAS;IAEvC;;OAEG;IACM,WAAW,CAAa;IAEjC;;OAEG;IACM,OAAO,CAAiB;IAEjC;;OAEG;IACM,gBAAgB,CAA0B;IAEnD;;;;;;;;;;;OAWG;IACH,YAAsB,OAAe,EAAE,oBAA4B,EAAE,UAAsB;QACvF,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,qBAAqB,GAAG,oBAAoB,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAE9B,6EAA6E;QAC7E,MAAM,YAAY,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAE5C,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE;YACtE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;SAC3C,CAAC,CAAC;QAEH,IAAI,CAAC,gBAAgB,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,+BAA+B,EAAE,YAAY,CAAC,gCAAgC,CAAC,CAAC;IAC3J,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU;QACZ,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QAE9E,IAAI,WAAW,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,MAAM,IAAI,CAAC,mBAAmB,CAAC,YAAY,CAAC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7E,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,IAAI,OAAO;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,IAAI,eAAe;QACf,OAAO,IAAI,CAAC,gBAAgB,CAAC;IACjC,CAAC;IA2FD;;;;;OAKG;IACH,qBAAqB,CAAC,aAAqB;QACvC,MAAM,qBAAqB,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAEtD,IAAI,qBAAqB,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;YACrD,MAAM,IAAI,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,mDAAmD,EAAE;gBAC5F,aAAa,EAAE,qBAAqB;gBACpC,oBAAoB,EAAE,IAAI,CAAC,qBAAqB;aACnD,CAAC,CAAC,CAAC;QACR,CAAC;IACL,CAAC"}

package/dist/app-helper-proxy.d.ts

@@ -0,0 +1,61 @@
+import { type Nullishable } from "@aidc-toolkit/core";
+import { LibProxy } from "./lib-proxy.js";
+import type { ErrorExtends, Matrix, MatrixResult } from "./type.js";
+/**
+ * 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.
+ */
+export declare class AppHelperProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    #private;
+    /**
+     * Get the version.
+     *
+     * @returns
+     * Version.
+     */
+    version(): string;
+    /**
+     * 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.
+     */
+    spill(arrayValues: Matrix<unknown>, maximumHeight: Nullishable<number>, maximumWidth: Nullishable<number>, invocationContext: Nullishable<TInvocationContext>): Promise<MatrixResult<unknown, ThrowError, TError>>;
+    /**
+     * Get the logger messages as a stream.
+     *
+     * @param logLevelString
+     * Log level as string.
+     *
+     * @param streamingInvocationContext
+     * Streaming invocation context.
+     */
+    loggerMessages(logLevelString: Nullishable<string>, streamingInvocationContext: Nullishable<TStreamingInvocationContext>): void;
+}
+//# sourceMappingURL=app-helper-proxy.d.ts.map

package/dist/app-helper-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-helper-proxy.d.ts","sourceRoot":"","sources":["../src/app-helper-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6D,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AA2CpE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAGa,cAAc,CAAC,UAAU,SAAS,OAAO,EAAE,MAAM,SAAS,YAAY,CAAC,UAAU,CAAC,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,OAAO,CAAE,SAAQ,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,OAAO,CAAC;;IACrP;;;;;OAKG;IAMH,OAAO,IAAI,MAAM;IA6CjB;;;;;;;;;;;;;;;;;OAiBG;IAQG,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,iBAAiB,EAAE,WAAW,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IA4GxN;;;;;;;;OAQG;IAaH,cAAc,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,0BAA0B,EAAE,WAAW,CAAC,2BAA2B,CAAC,GAAG,IAAI;CA8ClI"}