@aidc-toolkit/app-extension 1.0.52-beta → 1.0.52

package/dist/character-set-proxy-CQCOcqR3.d.cts

@@ -0,0 +1,473 @@
+import { MemoryTransport, Promisable, AppDataStorage, HTTPFetch, Hyperlink, Nullishable } from '@aidc-toolkit/core';
+import { StringValidation, StringValidator, CharacterSetValidator, Exclusion, CharacterSetCreator } from '@aidc-toolkit/utility';
+import { Logger } from 'tslog';
+
+/**
+ * Application extension options. Never instantiated; used only as extension point for custom application extension
+ * options to define types.
+ */
+interface AppExtensionOptions {
+    /**
+     * If true, errors are reported through the throw/catch mechanism.
+     */
+    ThrowError: boolean;
+    /**
+     * Application error.
+     */
+    ApplicationError: object;
+    /**
+     * Invocation context.
+     */
+    InvocationContext: unknown;
+    /**
+     * Streaming context.
+     */
+    StreamingContext: unknown;
+    /**
+     * Big integer representation.
+     */
+    BigInteger: number | bigint;
+}
+/**
+ * Custom application extension options.
+ */
+interface CustomAppExtensionOptions extends AppExtensionOptions {
+}
+/**
+ * If true, errors are reported through the throw/catch mechanism.
+ */
+type ThrowError = CustomAppExtensionOptions["ThrowError"];
+/**
+ * Application error type.
+ */
+type ApplicationError = CustomAppExtensionOptions["ApplicationError"];
+/**
+ * Invocation context type.
+ */
+type InvocationContext = CustomAppExtensionOptions["InvocationContext"];
+/**
+ * Streaming context type.
+ */
+type StreamingContext = CustomAppExtensionOptions["StreamingContext"];
+/**
+ * Big integer representation type.
+ */
+type BigInteger = CustomAppExtensionOptions["BigInteger"];
+
+/**
+ * Sheet.
+ */
+interface Sheet {
+    /**
+     * Sheet name.
+     */
+    readonly name: string;
+}
+/**
+ * Single cell address.
+ */
+interface Address {
+    /**
+     * Zero-indexed row.
+     */
+    readonly rowIndex: number;
+    /**
+     * Zero-indexed column.
+     */
+    readonly columnIndex: number;
+}
+/**
+ * Sheet address.
+ */
+interface SheetAddress extends Sheet, Address {
+}
+/**
+ * Range of cells.
+ */
+interface Range {
+    /**
+     * Start address, inclusive.
+     */
+    readonly startAddress: Address;
+    /**
+     * End address, exclusive.
+     */
+    readonly endAddress: Address;
+}
+/**
+ * Sheet range.
+ */
+interface SheetRange extends Sheet, Range {
+}
+/**
+ * Matrix type; shorthand for defining a two-dimensional matrix (array of array) of a type.
+ *
+ * @template T
+ * Type.
+ */
+type Matrix<T> = T[][];
+/**
+ * Function singleton return, possibly including an error return. If the application extension reports errors through
+ * the return value, the result is the union of the return type and the error type; otherwise, it's just the return
+ * type.
+ *
+ * @template TResult
+ * Result type.
+ */
+type SingletonResult<TResult> = ThrowError extends true ? TResult : TResult | ApplicationError;
+/**
+ * Function matrix return, possibly including an error return in each element. If the application extension reports
+ * errors through the return value, the individual element result is the union of the return type and the error type;
+ * otherwise, it's just the return type.
+ *
+ * @template TResult
+ * Result type.
+ */
+type MatrixResult<TResult> = Matrix<SingletonResult<TResult>>;
+
+/**
+ * Streaming consumer callback, returned by application extension implementation.
+ */
+type StreamingConsumerCallback<TResult> = (result: MatrixResult<TResult>) => void;
+/**
+ * Streaming cancelled callback, passed to application extension implementation.
+ */
+type StreamingCancelledCallback = () => void;
+
+/**
+ * Library proxy.
+ */
+declare abstract class LibProxy {
+    #private;
+    /**
+     * Constructor.
+     *
+     * @param appExtension
+     * Application extension.
+     */
+    constructor(appExtension: AppExtension);
+    /**
+     * Get the application extension.
+     */
+    get appExtension(): AppExtension;
+    /**
+     * Map big integer to another type if necessary.
+     *
+     * @param value
+     * Big integer value to map.
+     *
+     * @returns
+     * Mapped big integer value.
+     */
+    mapBigInt(value: bigint): SingletonResult<BigInteger>;
+    /**
+     * Call a singleton result function with error handling.
+     *
+     * @param callback
+     * Callback.
+     *
+     * @returns
+     * Callback return or error if errors are not thrown.
+     */
+    singletonResult<TResult>(callback: () => SingletonResult<TResult>): SingletonResult<TResult>;
+    /**
+     * Call a matrix result function with error handling.
+     *
+     * @param matrixValues
+     * Matrix of values.
+     *
+     * @param valueCallback
+     * Callback to process value.
+     *
+     * @returns
+     * Matrix of callback results and errors if errors are not thrown.
+     */
+    protected matrixResult<TValue, TResult>(matrixValues: Matrix<TValue>, valueCallback: (value: TValue) => SingletonResult<TResult>): MatrixResult<TResult>;
+    /**
+     * Map a matrix of validate string results to boolean. If the string is empty, the result is true, indicating that
+     * there is no error.
+     *
+     * @param matrixValidateResults
+     * Matrix of results from a call to a validate function.
+     *
+     * @returns
+     * Matrix of boolean values, true if corresponding string is empty.
+     */
+    protected isValidString(matrixValidateResults: MatrixResult<string>): Matrix<boolean>;
+    /**
+     * Set up a mapping and call a matrix result function with error handling.
+     *
+     * @param setUpCallback
+     * Callback to set up the mapping.
+     *
+     * @param matrixValues
+     * Matrix of values.
+     *
+     * @param valueCallback
+     * Callback to process value.
+     *
+     * @returns
+     * Matrix of callback results and errors if errors are not thrown.
+     */
+    protected setUpMatrixResult<TSetup, TValue, TResult>(setUpCallback: () => TSetup, matrixValues: Matrix<TValue>, valueCallback: (setup: TSetup, value: TValue) => SingletonResult<TResult>): MatrixResult<TResult>;
+    /**
+     * Call an array result function with error handling and map to a matrix.
+     *
+     * @param matrixValues
+     * Matrix of values.
+     *
+     * @param callback
+     * Callback.
+     *
+     * @returns
+     * Matrix of callback results and errors if errors are not thrown.
+     */
+    protected arrayResult<TValue, TResult>(matrixValues: Matrix<TValue>, callback: (value: TValue) => Array<SingletonResult<TResult>>): MatrixResult<TResult>;
+    /**
+     * Call a matrix result function with error handling and map a non-error result to an empty string and {@linkcode
+     * RangeError} to the string error message.
+     *
+     * @param matrixValues
+     * Matrix of values.
+     *
+     * @param callback
+     * Callback that either returns or throws an exception.
+     *
+     * @returns
+     * Matrix of strings.
+     */
+    protected matrixErrorResult<TValue>(matrixValues: Matrix<TValue>, callback: (value: TValue) => void): Matrix<string>;
+    /**
+     * Call an iterable result function with error handling and map to a matrix. Although the natural approach would be
+     * to map to a single-element array containing an array of *N* results (i.e., [[r0, r1, r2, ..., r*N*]]), this is
+     * rendered visually as a single row. The more readable approach is as a single column, so the mapping is to an
+     * *N*-element array of single-element result arrays (i.e., [[r0], [r1], [r2], ..., [r*N*]]).
+     *
+     * @param iterableCallback
+     * Iterable callback.
+     *
+     * @returns
+     * Matrix of callback results.
+     */
+    protected iterableResult<TResult>(iterableCallback: () => Iterable<SingletonResult<TResult>>): MatrixResult<TResult>;
+}
+
+/**
+ * Application extension.
+ */
+declare abstract class AppExtension {
+    #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 a proxy instance. The use of a weak map ensures that proxies are loaded only as needed and may be garbage
+     * collected if required.
+     *
+     * @param ProxyConstructor
+     * Proxy constructor.
+     *
+     * @returns
+     * Proxy instance.
+     */
+    getProxy<T extends LibProxy>(ProxyConstructor: new (appExtension: AppExtension) => T): T;
+    /**
+     * Get the sheet address from an invocation context.
+     *
+     * @param invocationContext
+     * Invocation context.
+     *
+     * @returns
+     * Sheet address.
+     */
+    abstract getSheetAddress(invocationContext: InvocationContext): 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: InvocationContext, parameterNumber: number): Promisable<SheetRange | null>;
+    /**
+     * Install a streaming function.
+     *
+     * @param streamingContext
+     * Streaming context.
+     *
+     * @param streamingCancelledCallback
+     * Streaming cancelled callback, called when streaming is cancelled.
+     *
+     * @returns
+     * Streaming consumer callback, called when stream contents updated.
+     */
+    abstract installStreaming<TResult>(streamingContext: StreamingContext, streamingCancelledCallback: StreamingCancelledCallback): StreamingConsumerCallback<TResult>;
+    /**
+     * 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>;
+    /**
+     * Get HTTP fetch function.
+     */
+    abstract get httpFetch(): HTTPFetch;
+    /**
+     * Validate a sequence count against the maximum supported by application.
+     *
+     * @param sequenceCount
+     * Sequence count.
+     */
+    validateSequenceCount(sequenceCount: number): void;
+    /**
+     * Map a big integer to its representation type.
+     *
+     * @param value
+     * Big integer value to map.
+     *
+     * @returns
+     * Mapped big integer value.
+     */
+    abstract mapBigInt(value: bigint): SingletonResult<BigInteger>;
+    /**
+     * Map hyperlink results to a form suitable for the application.
+     *
+     * @param matrixHyperlinkResults
+     * Matrix of hyperlink results from function call.
+     *
+     * @returns
+     * Matrix of results in a form suitable for the application.
+     */
+    abstract mapHyperlinkResults(matrixHyperlinkResults: MatrixResult<Hyperlink>): Promisable<MatrixResult<unknown>>;
+    /**
+     * 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
+     * Range error.
+     */
+    abstract mapRangeError(rangeError: RangeError): ApplicationError;
+    /**
+     * 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;
+}
+
+declare abstract class StringProxy extends LibProxy {
+    protected validateString<TStringValidation extends StringValidation>(validator: StringValidator<TStringValidation>, matrixSs: Matrix<string>, validation?: TStringValidation): Matrix<string>;
+}
+
+declare abstract class CharacterSetValidatorProxy extends StringProxy {
+    #private;
+    constructor(appExtension: AppExtension, characterSetValidator: CharacterSetValidator);
+    validate(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>): Matrix<string>;
+    isValid(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>): Matrix<boolean>;
+}
+declare abstract class CharacterSetCreatorProxy extends CharacterSetValidatorProxy {
+    #private;
+    constructor(appExtension: AppExtension, characterSetCreator: CharacterSetCreator);
+    create(length: number, matrixValues: Matrix<number | bigint>, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<string>;
+    createSequence(length: number, startValue: number, count: number, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<string>;
+    valueFor(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<BigInteger>;
+}
+declare class NumericProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
+}
+declare class HexadecimalProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
+}
+declare class AlphabeticProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
+}
+declare class AlphanumericProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
+}
+
+export { type Address as A, type BigInteger as B, CharacterSetCreatorProxy as C, HexadecimalProxy as H, type InvocationContext as I, LibProxy as L, type Matrix as M, NumericProxy as N, type Range as R, type StreamingContext as S, type ThrowError as T, type MatrixResult as a, StringProxy as b, AlphabeticProxy as c, AlphanumericProxy as d, AppExtension as e, type AppExtensionOptions as f, type ApplicationError as g, CharacterSetValidatorProxy as h, type CustomAppExtensionOptions as i, type Sheet as j, type SheetAddress as k, type SheetRange as l, type SingletonResult as m, type StreamingCancelledCallback as n, type StreamingConsumerCallback as o };