@aidc-toolkit/app-extension 1.0.48-beta → 1.0.49

package/dist/character-set-proxy-BOW94WCe.d.ts

@@ -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';
+
+/**
+ * Type that error type is expected to extend. If the application framework reports errors through the throw/catch
+ * mechanism, the error type is expected to extend {@linkcode Error}. Otherwise, it may extend any object type.
+ *
+ * @template ThrowError
+ * If true, errors are reported through the throw/catch mechanism.
+ */
+type ErrorExtends<ThrowError extends boolean> = ThrowError extends true ? Error : object;
+/**
+ * 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.
+ *
+ * @template ThrowError
+ * If true, errors are reported through the throw/catch mechanism.
+ *
+ * @template TError
+ * Error type.
+ */
+type SingletonResult<TResult, ThrowError extends boolean, TError extends ErrorExtends<ThrowError>> = ThrowError extends false ? TResult | TError : TResult;
+/**
+ * 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.
+ *
+ * @template ThrowError
+ * If true, errors are reported through the throw/catch mechanism.
+ *
+ * @template TError
+ * Error type.
+ */
+type MatrixResult<TResult, ThrowError extends boolean, TError extends ErrorExtends<ThrowError>> = Matrix<SingletonResult<TResult, ThrowError, TError>>;
+
+/**
+ * Streaming consumer callback, returned by application extension implementation.
+ */
+type StreamingConsumerCallback<TResult, ThrowError extends boolean, TError extends ErrorExtends<ThrowError>> = (result: MatrixResult<TResult, ThrowError, TError>) => void;
+/**
+ * Streaming cancelled callback, passed to application extension implementation.
+ */
+type StreamingCancelledCallback = () => void;
+
+/**
+ * Library proxy.
+ *
+ * @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.
+ */
+declare abstract class LibProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    #private;
+    /**
+     * Constructor.
+     *
+     * @param appExtension
+     * Application extension.
+     */
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>);
+    /**
+     * Get the application extension.
+     */
+    get appExtension(): AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>;
+    /**
+     * Map big integer to another type if necessary.
+     *
+     * @param value
+     * Big integer value to map.
+     *
+     * @returns
+     * Mapped big integer value.
+     */
+    mapBigInt(value: bigint): SingletonResult<TBigInt, ThrowError, TError>;
+    /**
+     * 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, ThrowError, TError>): SingletonResult<TResult, ThrowError, TError>;
+    /**
+     * 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, ThrowError, TError>): MatrixResult<TResult, ThrowError, TError>;
+    /**
+     * 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, ThrowError, TError>): 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, ThrowError, TError>): MatrixResult<TResult, ThrowError, TError>;
+    /**
+     * 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, ThrowError, TError>>): MatrixResult<TResult, ThrowError, TError>;
+    /**
+     * 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, ThrowError, TError>>): MatrixResult<TResult, ThrowError, TError>;
+}
+
+/**
+ * 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.
+ */
+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 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<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>>(ProxyConstructor: new (appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>) => T): T;
+    /**
+     * 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>;
+    /**
+     * 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 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;
+}
+
+declare abstract class StringProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    protected validateString<TStringValidation extends StringValidation>(validator: StringValidator<TStringValidation>, matrixSs: Matrix<string>, validation?: TStringValidation): Matrix<string>;
+}
+
+declare abstract class CharacterSetValidatorProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends StringProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    #private;
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>, characterSetValidator: CharacterSetValidator);
+    validate(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>): Matrix<string>;
+    isValid(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>): Matrix<boolean>;
+}
+declare abstract class CharacterSetCreatorProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends CharacterSetValidatorProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    #private;
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>, characterSetCreator: CharacterSetCreator);
+    create(length: number, matrixValues: Matrix<number | bigint>, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<string, ThrowError, TError>;
+    createSequence(length: number, startValue: number, count: number, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<string, ThrowError, TError>;
+    valueFor(matrixSs: Matrix<string>, exclusion: Nullishable<Exclusion>, tweak: Nullishable<number | bigint>): MatrixResult<TBigInt, ThrowError, TError>;
+}
+declare class NumericProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends CharacterSetCreatorProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>);
+}
+declare class HexadecimalProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends CharacterSetCreatorProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>);
+}
+declare class AlphabeticProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends CharacterSetCreatorProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>);
+}
+declare class AlphanumericProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends CharacterSetCreatorProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>);
+}
+
+export { type Address as A, CharacterSetValidatorProxy as C, type ErrorExtends as E, HexadecimalProxy as H, LibProxy as L, type Matrix as M, NumericProxy as N, type Range as R, StringProxy as S, type MatrixResult as a, type Sheet as b, type SheetAddress as c, type SheetRange as d, type SingletonResult as e, type StreamingConsumerCallback as f, type StreamingCancelledCallback as g, AppExtension as h, CharacterSetCreatorProxy as i, AlphabeticProxy as j, AlphanumericProxy as k };