@aidc-toolkit/app-extension 1.0.49 → 1.0.50

package/dist/{character-set-proxy-BOW94WCe.d.cts → character-set-proxy-CQCOcqR3.d.cts}

@@ -3,13 +3,57 @@ import { StringValidation, StringValidator, CharacterSetValidator, Exclusion, Ch
 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
+ * 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 ErrorExtends<ThrowError extends boolean> = ThrowError extends true ? Error : object;
+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.
  */
@@ -69,14 +113,8 @@ type Matrix<T> = T[][];
  *
  * @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;
+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;
@@ -84,19 +122,13 @@ type SingletonResult<TResult, ThrowError extends boolean, TError extends ErrorEx
  *
  * @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>>;
+type MatrixResult<TResult> = Matrix<SingletonResult<TResult>>;
 
 /**
  * Streaming consumer callback, returned by application extension implementation.
  */
-type StreamingConsumerCallback<TResult, ThrowError extends boolean, TError extends ErrorExtends<ThrowError>> = (result: MatrixResult<TResult, ThrowError, TError>) => void;
+type StreamingConsumerCallback<TResult> = (result: MatrixResult<TResult>) => void;
 /**
  * Streaming cancelled callback, passed to application extension implementation.
  */
@@ -104,23 +136,8 @@ 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> {
+declare abstract class LibProxy {
     #private;
     /**
      * Constructor.
@@ -128,11 +145,11 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @param appExtension
      * Application extension.
      */
-    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>);
+    constructor(appExtension: AppExtension);
     /**
      * Get the application extension.
      */
-    get appExtension(): AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>;
+    get appExtension(): AppExtension;
     /**
      * Map big integer to another type if necessary.
      *
@@ -142,7 +159,7 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @returns
      * Mapped big integer value.
      */
-    mapBigInt(value: bigint): SingletonResult<TBigInt, ThrowError, TError>;
+    mapBigInt(value: bigint): SingletonResult<BigInteger>;
     /**
      * Call a singleton result function with error handling.
      *
@@ -152,7 +169,7 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @returns
      * Callback return or error if errors are not thrown.
      */
-    singletonResult<TResult>(callback: () => SingletonResult<TResult, ThrowError, TError>): SingletonResult<TResult, ThrowError, TError>;
+    singletonResult<TResult>(callback: () => SingletonResult<TResult>): SingletonResult<TResult>;
     /**
      * Call a matrix result function with error handling.
      *
@@ -165,7 +182,7 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @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>;
+    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.
@@ -176,7 +193,7 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @returns
      * Matrix of boolean values, true if corresponding string is empty.
      */
-    protected isValidString(matrixValidateResults: MatrixResult<string, ThrowError, TError>): Matrix<boolean>;
+    protected isValidString(matrixValidateResults: MatrixResult<string>): Matrix<boolean>;
     /**
      * Set up a mapping and call a matrix result function with error handling.
      *
@@ -192,7 +209,7 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @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>;
+    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.
      *
@@ -205,7 +222,7 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @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>;
+    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.
@@ -232,28 +249,13 @@ declare abstract class LibProxy<ThrowError extends boolean, TError extends Error
      * @returns
      * Matrix of callback results.
      */
-    protected iterableResult<TResult>(iterableCallback: () => Iterable<SingletonResult<TResult, ThrowError, TError>>): MatrixResult<TResult, ThrowError, TError>;
+    protected iterableResult<TResult>(iterableCallback: () => Iterable<SingletonResult<TResult>>): MatrixResult<TResult>;
 }
 
 /**
  * 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> {
+declare abstract class AppExtension {
     #private;
     /**
      * Application name.
@@ -317,7 +319,7 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      * @returns
      * Proxy instance.
      */
-    getProxy<T extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>>(ProxyConstructor: new (appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>) => T): T;
+    getProxy<T extends LibProxy>(ProxyConstructor: new (appExtension: AppExtension) => T): T;
     /**
      * Get the sheet address from an invocation context.
      *
@@ -327,7 +329,7 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      * @returns
      * Sheet address.
      */
-    abstract getSheetAddress(invocationContext: TInvocationContext): Promisable<SheetAddress>;
+    abstract getSheetAddress(invocationContext: InvocationContext): Promisable<SheetAddress>;
     /**
      * Get a parameter range from an invocation context.
      *
@@ -340,12 +342,12 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      * @returns
      * Sheet range or null if parameter is not a range.
      */
-    abstract getParameterSheetRange(invocationContext: TInvocationContext, parameterNumber: number): Promisable<SheetRange | null>;
+    abstract getParameterSheetRange(invocationContext: InvocationContext, parameterNumber: number): Promisable<SheetRange | null>;
     /**
-     * Set up streaming for a streaming function.
+     * Install a streaming function.
      *
-     * @param streamingInvocationContext
-     * Streaming invocation context.
+     * @param streamingContext
+     * Streaming context.
      *
      * @param streamingCancelledCallback
      * Streaming cancelled callback, called when streaming is cancelled.
@@ -353,7 +355,7 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      * @returns
      * Streaming consumer callback, called when stream contents updated.
      */
-    abstract setUpStreaming<TResult>(streamingInvocationContext: TStreamingInvocationContext, streamingCancelledCallback: StreamingCancelledCallback): StreamingConsumerCallback<TResult, ThrowError, TError>;
+    abstract installStreaming<TResult>(streamingContext: StreamingContext, streamingCancelledCallback: StreamingCancelledCallback): StreamingConsumerCallback<TResult>;
     /**
      * Get a property stored within the active document.
      *
@@ -401,7 +403,7 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      */
     validateSequenceCount(sequenceCount: number): void;
     /**
-     * Map big integer to another type if necessary.
+     * Map a big integer to its representation type.
      *
      * @param value
      * Big integer value to map.
@@ -409,27 +411,25 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      * @returns
      * Mapped big integer value.
      */
-    abstract mapBigInt(value: bigint): SingletonResult<TBigInt, ThrowError, TError>;
+    abstract mapBigInt(value: bigint): SingletonResult<BigInteger>;
     /**
      * 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>>;
+    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): TError;
+    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.
@@ -440,34 +440,34 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
     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> {
+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<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends StringProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+declare abstract class CharacterSetValidatorProxy extends StringProxy {
     #private;
-    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>, characterSetValidator: CharacterSetValidator);
+    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<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends CharacterSetValidatorProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+declare abstract class CharacterSetCreatorProxy extends CharacterSetValidatorProxy {
     #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>;
+    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<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 NumericProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
 }
-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 HexadecimalProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
 }
-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 AlphabeticProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
 }
-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>);
+declare class AlphanumericProxy extends CharacterSetCreatorProxy {
+    constructor(appExtension: AppExtension);
 }
 
-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 };
+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 };