@aidc-toolkit/app-extension 0.9.19-beta

package/dist/utility/transformer-descriptor.js

@@ -0,0 +1,24 @@
+import { Type } from "../descriptor.js";
+export const valueParameterDescriptor = {
+    name: "value",
+    type: Type.Number,
+    isMatrix: true,
+    isRequired: true
+};
+export const startValueParameterDescriptor = {
+    extendsDescriptor: valueParameterDescriptor,
+    name: "startValue",
+    isMatrix: false
+};
+export const countParameterDescriptor = {
+    extendsDescriptor: valueParameterDescriptor,
+    name: "count",
+    isMatrix: false
+};
+export const tweakParameterDescriptor = {
+    name: "tweak",
+    type: Type.Number,
+    isMatrix: false,
+    isRequired: false
+};
+//# sourceMappingURL=transformer-descriptor.js.map

package/dist/utility/transformer-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer-descriptor.js","sourceRoot":"","sources":["../../src/utility/transformer-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAElE,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IACzD,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,IAAI,CAAC,MAAM;IACjB,QAAQ,EAAE,IAAI;IACd,UAAU,EAAE,IAAI;CACnB,CAAC;AAEF,MAAM,CAAC,MAAM,6BAA6B,GAAwB;IAC9D,iBAAiB,EAAE,wBAAwB;IAC3C,IAAI,EAAE,YAAY;IAClB,QAAQ,EAAE,KAAK;CAClB,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IACzD,iBAAiB,EAAE,wBAAwB;IAC3C,IAAI,EAAE,OAAO;IACb,QAAQ,EAAE,KAAK;CAClB,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IACzD,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,IAAI,CAAC,MAAM;IACjB,QAAQ,EAAE,KAAK;IACf,UAAU,EAAE,KAAK;CACpB,CAAC"}

package/dist/utility/transformer-proxy.d.ts

@@ -0,0 +1,8 @@
+import { LibProxy } from "../lib-proxy.js";
+import type { ErrorExtends, Matrix, MatrixResultError, Nullishable, ResultError } from "../types.js";
+export declare class TransformerProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    forward(domain: number | bigint, matrixValues: Matrix<number | bigint>, tweak: Nullishable<number | bigint>): MatrixResultError<ResultError<TBigInt, ThrowError, TError>, ThrowError, TError>;
+    forwardSequence(domain: number | bigint, startValue: number, count: number, tweak: Nullishable<number | bigint>): Matrix<ResultError<TBigInt, ThrowError, TError>>;
+    reverse(domain: number | bigint, matrixTransformedValues: Matrix<number | bigint>, tweak: Nullishable<number | bigint>): MatrixResultError<ResultError<TBigInt, ThrowError, TError>, ThrowError, TError>;
+}
+//# sourceMappingURL=transformer-proxy.d.ts.map

package/dist/utility/transformer-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer-proxy.d.ts","sourceRoot":"","sources":["../../src/utility/transformer-proxy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAqBrG,qBAGa,gBAAgB,CAAC,UAAU,SAAS,OAAO,EAAE,MAAM,SAAS,YAAY,CAAC,UAAU,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAE,SAAQ,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE,OAAO,CAAC;IAK7L,OAAO,CACwC,MAAM,EAAE,MAAM,GAAG,MAAM,EACxB,YAAY,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,EACrC,KAAK,EAAE,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC,GAC9E,iBAAiB,CAAC,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC;IAWlF,eAAe,CACgC,MAAM,EAAE,MAAM,GAAG,MAAM,EACnB,UAAU,EAAE,MAAM,EACvB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC,GAC9E,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAUnD,OAAO,CACwC,MAAM,EAAE,MAAM,GAAG,MAAM,EACb,uBAAuB,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,EAC3D,KAAK,EAAE,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC,GAC9E,iBAAiB,CAAC,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC;CAKrF"}

package/dist/utility/transformer-proxy.js

@@ -0,0 +1,74 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Sequence, Transformer, mapIterable } from "@aidc-toolkit/utility";
+import { ProxyClass, ProxyMethod, ProxyParameter, Type } from "../descriptor.js";
+import { LibProxy } from "../lib-proxy.js";
+import { countParameterDescriptor, startValueParameterDescriptor, tweakParameterDescriptor, valueParameterDescriptor } from "./transformer-descriptor.js";
+const domainParameterDescriptor = {
+    name: "domain",
+    type: Type.Number,
+    isMatrix: false,
+    isRequired: true
+};
+// eslint-disable-next-line no-useless-assignment -- ESLint bug.
+const transformedValueParameterDescriptor = {
+    extendsDescriptor: valueParameterDescriptor,
+    name: "transformedValue"
+};
+let TransformerProxy = class TransformerProxy extends LibProxy {
+    forward(domain, matrixValues, tweak) {
+        const transformer = Transformer.get(domain, tweak ?? undefined);
+        return this.mapMatrix(matrixValues, value => this.mapBigInt(transformer.forward(value)));
+    }
+    forwardSequence(domain, startValue, count, tweak) {
+        this.appExtension.validateSequenceCount(count);
+        return LibProxy.matrixResult(mapIterable(Transformer.get(domain, tweak ?? undefined).forward(new Sequence(startValue, count)), value => this.mapBigInt(value)));
+    }
+    reverse(domain, matrixTransformedValues, tweak) {
+        const transformer = Transformer.get(domain, tweak ?? undefined);
+        return this.mapMatrix(matrixTransformedValues, transformedValue => this.mapBigInt(transformer.reverse(transformedValue)));
+    }
+};
+__decorate([
+    ProxyMethod({
+        type: Type.Number,
+        isMatrix: true
+    }),
+    __param(0, ProxyParameter(domainParameterDescriptor)),
+    __param(1, ProxyParameter(valueParameterDescriptor)),
+    __param(2, ProxyParameter(tweakParameterDescriptor))
+], TransformerProxy.prototype, "forward", null);
+__decorate([
+    ProxyMethod({
+        infixBefore: "Sequence",
+        type: Type.Number,
+        isMatrix: true
+    }),
+    __param(0, ProxyParameter(domainParameterDescriptor)),
+    __param(1, ProxyParameter(startValueParameterDescriptor)),
+    __param(2, ProxyParameter(countParameterDescriptor)),
+    __param(3, ProxyParameter(tweakParameterDescriptor))
+], TransformerProxy.prototype, "forwardSequence", null);
+__decorate([
+    ProxyMethod({
+        type: Type.Number,
+        isMatrix: true
+    }),
+    __param(0, ProxyParameter(domainParameterDescriptor)),
+    __param(1, ProxyParameter(transformedValueParameterDescriptor)),
+    __param(2, ProxyParameter(tweakParameterDescriptor))
+], TransformerProxy.prototype, "reverse", null);
+TransformerProxy = __decorate([
+    ProxyClass({
+        methodInfix: "Transform"
+    })
+], TransformerProxy);
+export { TransformerProxy };
+//# sourceMappingURL=transformer-proxy.js.map

package/dist/utility/transformer-proxy.js.map

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

package/eslint.config.ts

@@ -0,0 +1,21 @@
+import { esLintConfigAIDCToolkit } from "@aidc-toolkit/dev";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+    ...esLintConfigAIDCToolkit,
+    {
+        files: [
+            "src/*/**/*-proxy.ts"
+        ],
+        rules: {
+            // Same rule minus ClassDeclaration, ClassProperty, and MethodDefinition contexts.
+            "jsdoc/require-description": ["warn", {
+                contexts: ["FunctionDeclaration", "TSEnumDeclaration", "TSInterfaceDeclaration", "TSModuleDeclaration", "TSTypeAliasDeclaration"]
+            }],
+            // Same rule minus ClassDeclaration, ClassProperty, and MethodDefinition contexts.
+            "jsdoc/require-jsdoc": ["warn", {
+                contexts: ["FunctionDeclaration", "TSEnumDeclaration", "TSInterfaceDeclaration", "TSModuleDeclaration", "TSTypeAliasDeclaration"]
+            }]
+        }
+    }
+]);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@aidc-toolkit/app-extension",
+  "version": "0.9.19-beta",
+  "description": "Application extension framework for AIDC Toolkit",
+  "type": "module",
+  "main": "dist/index.js",
+  "homepage": "https://aidc-toolkit.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidc-toolkit/app-extension.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aidc-toolkit/app-extension/issues"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Kevin Dean",
+    "email": "Kevin.Dean@datadevelopment.com",
+    "url": "https://www.linkedin.com/in/kdean"
+  },
+  "scripts": {
+    "lint": "eslint",
+    "build:core": "rimraf dist && tsc --project",
+    "build:dev": "npm run build:core -- node_modules/@aidc-toolkit/dev/tsconfig-build-dev.json",
+    "build:release": "npm run build:core -- node_modules/@aidc-toolkit/dev/tsconfig-build.json",
+    "build:doc": "npm run build:dev"
+  },
+  "devDependencies": {
+    "@aidc-toolkit/dev": "beta"
+  },
+  "dependencies": {
+    "@aidc-toolkit/core": "beta",
+    "@aidc-toolkit/gs1": "beta",
+    "@aidc-toolkit/utility": "beta",
+    "i18next": "^25.6.3"
+  }
+}

package/src/app-extension.ts

@@ -0,0 +1,244 @@
+import { i18nextAppExtension } from "./locale/i18n.js";
+import type {
+    ErrorExtends,
+    ResultError,
+    SheetAddress,
+    SheetRange,
+    TypedAsyncFunction,
+    TypedFunction,
+    TypedSyncFunction
+} from "./types.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.
+ */
+export abstract class AppExtension<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> {
+    /**
+     * Application version.
+     */
+    private readonly _version: string;
+
+    /**
+     * Maximum sequence count supported by application.
+     */
+    private readonly _maximumSequenceCount: number;
+
+    /**
+     * If true, errors are reported through the throw/catch mechanism.
+     */
+    private readonly _throwError: ThrowError;
+
+    /**
+     * Maximum width supported by application.
+     */
+    private _maximumWidth?: number;
+
+    /**
+     * Maximum height supported by application.
+     */
+    private _maximumHeight?: number;
+
+    /**
+     * 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) {
+        this._version = version;
+        this._maximumSequenceCount = maximumSequenceCount;
+        this._throwError = throwError;
+    }
+
+    /**
+     * Get the version.
+     *
+     * @returns
+     * Version.
+     */
+    get version(): string {
+        return this._version;
+    }
+
+    /**
+     * Determine if errors are reported through the throw/catch mechanism.
+     */
+    get throwError(): ThrowError {
+        return this._throwError;
+    }
+
+    /**
+     * Get the maximum width supported by the application.
+     *
+     * @returns
+     * Maximum width supported by the application.
+     */
+    async maximumWidth(): Promise<number> {
+        this._maximumWidth ??= await this.getMaximumWidth();
+
+        return this._maximumWidth;
+    }
+
+    /**
+     * Get the maximum width supported by the application.
+     *
+     * @returns
+     * Maximum width supported by the application.
+     */
+    protected abstract getMaximumWidth(): Promise<number>;
+
+    /**
+     * Get the maximum height supported by the application.
+     *
+     * @returns
+     * Maximum height supported by the application.
+     */
+    async maximumHeight(): Promise<number> {
+        this._maximumHeight ??= await this.getMaximumHeight();
+
+        return this._maximumHeight;
+    }
+
+    /**
+     * Get the maximum height supported by the application.
+     *
+     * @returns
+     * Maximum height supported by the application.
+     */
+    protected abstract getMaximumHeight(): Promise<number>;
+
+    /**
+     * Get the sheet address from an invocation context.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @returns
+     * Sheet address.
+     */
+    abstract getSheetAddress(invocationContext: TInvocationContext): Promise<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): Promise<SheetRange | null>;
+
+    /**
+     * Validate a sequence count against the maximum supported by application.
+     *
+     * @param sequenceCount
+     * Sequence count.
+     */
+    validateSequenceCount(sequenceCount: number): void {
+        const absoluteSequenceCount = Math.abs(sequenceCount);
+
+        if (absoluteSequenceCount > this._maximumSequenceCount) {
+            throw new RangeError(i18nextAppExtension.t("AppExtension.sequenceCountMustBeLessThanOrEqualTo", {
+                sequenceCount: absoluteSequenceCount,
+                maximumSequenceCount: this._maximumSequenceCount
+            }));
+        }
+    }
+
+    /**
+     * Map big integer to another type if necessary.
+     *
+     * @param value
+     * Big integer value to map.
+     *
+     * @returns
+     * Mapped big integer value.
+     */
+    abstract mapBigInt(value: bigint): ResultError<TBigInt, 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;
+
+    /**
+     * Bind a synchronous method and wrap it in a try/catch for comprehensive error handling.
+     *
+     * @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.
+     *
+     * @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));
+        });
+    }
+}