@aidc-toolkit/app-extension 1.0.32-beta → 1.0.33-beta

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { I18nEnvironment, MemoryTransport, Promisable, Hyperlink, Nullishable } from '@aidc-toolkit/core';
+import { I18nEnvironment, MemoryTransport, Promisable, AppDataStorage, Hyperlink, Nullishable } from '@aidc-toolkit/core';
 import { Resource, i18n } from 'i18next';
 import { Logger } from 'tslog';
 import { StringValidation, StringValidator, CharacterSetValidator, Exclusion, CharacterSetCreator } from '@aidc-toolkit/utility';
@@ -11,6 +11,19 @@ declare const _default: {
     Proxy: {
         matrixMustBeArray: string;
     };
+    Categories: {
+        helper: string;
+        transformation: string;
+        string: string;
+        GS1: {
+            checkCharacter: string;
+            identifierValidation: string;
+            identifierCreation: string;
+            variableMeasure: string;
+            prefix: string;
+            service: string;
+        };
+    };
     IdentifierCreatorProxy: {
         prefixDefinitionMustBeOneDimensional: string;
         prefixDefinitionMustHaveMaximumThreeElements: string;
@@ -23,7 +36,7 @@ declare const _default: {
         invalidIdentifierType: string;
     };
     Parameters: {
-        spillMatrix: {
+        spillArray: {
             name: string;
             description: string;
         };
@@ -748,9 +761,9 @@ declare const appExtensionNS = "aidct_app_extension";
  */
 type AppExtensionLocaleResources = typeof _default;
 /**
- * App extension resources.
+ * App extension resource bundle.
  */
-declare const appExtensionResources: Resource;
+declare const appExtensionResourceBundle: Resource;
 declare const i18nextAppExtension: i18n;
 /**
  * Initialize internationalization.
@@ -760,8 +773,11 @@ declare const i18nextAppExtension: i18n;
  *
  * @param debug
  * Debug setting.
+ *
+ * @returns
+ * App extension resource bundle.
  */
-declare function i18nAppExtensionInit(environment: I18nEnvironment, debug?: boolean): Promise<void>;
+declare function i18nAppExtensionInit(environment: I18nEnvironment, debug?: boolean): Promise<Resource>;
 
 /**
  * Type that error type is expected to extend. If the application framework reports errors through the throw/catch
@@ -854,32 +870,6 @@ type SingletonResult<TResult, ThrowError extends boolean, TError extends ErrorEx
  */
 type MatrixResult<TResult, ThrowError extends boolean, TError extends ErrorExtends<ThrowError>> = Matrix<SingletonResult<TResult, ThrowError, TError>>;
 
-/**
- * Application data.
- */
-type AppData = string | number | boolean | Date | Uint8Array | object;
-/**
- * Decode application data from an encoded string.
- *
- * @param stringData
- * String data.
- *
- * @returns
- * Decoded application data.
- */
-declare function decodeAppData(stringData: string): AppData | undefined;
-/**
- * Encode application data as a string for storage. Encoded string is in JSON format with date/time and binary data
- * converted to identifiable strings for decoding.
- *
- * @param appData
- * Application data.
- *
- * @returns
- * Encoded application data.
- */
-declare function encodeAppData(appData: AppData): string;
-
 /**
  * Streaming consumer callback, returned by application extension implementation.
  */
@@ -910,9 +900,9 @@ type StreamingCancelledCallback = () => void;
 declare abstract class AppExtension<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     #private;
     /**
-     * Application name prefix for properties and application data.
+     * Application name.
      */
-    static readonly APPLICATION_NAME_PREFIX = "AIDCToolkit.";
+    static readonly APPLICATION_NAME = "AIDCToolkit";
     /**
      * Version property name.
      */
@@ -998,7 +988,7 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      */
     abstract setUpStreaming<TResult>(streamingInvocationContext: TStreamingInvocationContext, streamingCancelledCallback: StreamingCancelledCallback): StreamingConsumerCallback<TResult, ThrowError, TError>;
     /**
-     * Get a property stored within the active file.
+     * Get a property stored within the active document.
      *
      * @param name
      * Property name.
@@ -1006,57 +996,32 @@ declare abstract class AppExtension<ThrowError extends boolean, TError extends E
      * @returns
      * Property value or undefined if no value is stored under the given name.
      */
-    abstract getFileProperty(name: string): Promisable<string | undefined>;
+    abstract getDocumentProperty(name: string): Promisable<string | undefined>;
     /**
-     * Set a property to be stored within the active file.
+     * Set a property to be stored within the active document.
      *
      * @param name
      * Property name.
      *
      * @param value
-     * Property value or null to remove.
-     */
-    abstract setFileProperty(name: string, value: string | null): Promisable<void>;
-    /**
-     * Get application data stored within the active file.
-     *
-     * @param name
-     * Name under which data is stored.
-     *
-     * @returns
-     * Application data or undefined if no data is stored under the given name.
+     * Property value.
      */
-    abstract getFileData(name: string): Promisable<AppData | undefined>;
+    abstract setDocumentProperty(name: string, value: string): Promisable<void>;
     /**
-     * Set application data to be stored within the active file.
+     * Delete a property from the active document.
      *
      * @param name
-     * Name under which to store data.
-     *
-     * @param appData
-     * Application data or null to remove.
+     * Property name.
      */
-    abstract setFileData(name: string, appData: AppData | null): Promisable<void>;
+    abstract deleteDocumentProperty(name: string): Promisable<void>;
     /**
-     * Get application data stored and shared across multiple files.
-     *
-     * @param name
-     * Name under which data is stored.
-     *
-     * @returns
-     * Application ata or undefined if no data is stored under the given name.
+     * Get application data storage for the current document.
      */
-    abstract getSharedData(name: string): Promisable<AppData | undefined>;
+    abstract get documentAppDataStorage(): AppDataStorage<boolean>;
     /**
-     * Set application data to be stored and shared across multiple files.
-     *
-     * @param name
-     * Name under which to store data.
-     *
-     * @param appData
-     * Application data or null to remove.
+     * Get application data storage shared across multiple documents.
      */
-    abstract setSharedData(name: string, appData: AppData | null): Promisable<void>;
+    abstract get sharedAppDataStorage(): AppDataStorage<boolean>;
     /**
      * Validate a sequence count against the maximum supported by application.
      *
@@ -1275,6 +1240,36 @@ type TypeKey = keyof typeof Types;
  * Type.
  */
 type Type = typeof Types[TypeKey];
+/**
+ * Multiplicities supported by proxy methods.
+ */
+declare const Multiplicities: {
+    /**
+     * Parameter or return value is a singleton.
+     */
+    readonly Singleton: 0;
+    /**
+     * Parameter or return value is a singleton or an array.
+     */
+    readonly Array: 1;
+    /**
+     * Parameter or return value is a singleton, an array, or a matrix.
+     */
+    readonly Matrix: 2;
+    /**
+     * Parameter value is a singleton or array but is treated as a singleton internally and doesn't drive multiplicity
+     * of the return value. Return value is an array for use as a singleton array parameter.
+     */
+    readonly SingletonArray: 3;
+};
+/**
+ * Multiplicity key.
+ */
+type MultiplicityKey = keyof typeof Multiplicities;
+/**
+ * Multiplicity.
+ */
+type Multiplicity = typeof Multiplicities[MultiplicityKey];
 /**
  * Type descriptor.
  */
@@ -1284,9 +1279,9 @@ interface TypeDescriptor extends Descriptor {
      */
     readonly type: Type;
     /**
-     * True if type is a matrix (method accepts or returns, or parameter is, a two-dimensional array).
+     * Multiplicity.
      */
-    readonly isMatrix: boolean;
+    readonly multiplicity: Multiplicity;
 }
 /**
  * Parameter descriptor.
@@ -1373,6 +1368,10 @@ interface ClassDescriptor extends Descriptor {
      * Class namespace. If not provided, class is at the top level.
      */
     readonly namespace?: string | undefined;
+    /**
+     * Category.
+     */
+    readonly category: string;
     /**
      * Method infix. If undefined, method name is generated verbatim.
      */
@@ -1413,7 +1412,7 @@ interface ClassDescriptor extends Descriptor {
  * @template TBigInt
  * Type to which big integer is mapped.
  */
-declare class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
+declare class AppHelperProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     #private;
     /**
      * Get the version.
@@ -1425,7 +1424,7 @@ declare class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorEx
     /**
      * Spill a one-dimensional matrix to fit a rectangle within a given maximum height and width.
      *
-     * @param matrixValues
+     * @param arrayValues
      * Matrix values. Matrix is length 1 or contains arrays of length 1 with the values.
      *
      * @param maximumHeight
@@ -1440,7 +1439,7 @@ declare class AppUtilityProxy<ThrowError extends boolean, TError extends ErrorEx
      * @returns
      * Matrix spilled within maximum height and maximum width.
      */
-    spill(matrixValues: Matrix<unknown>, maximumHeight: Nullishable<number>, maximumWidth: Nullishable<number>, invocationContext: Nullishable<TInvocationContext>): Promise<MatrixResult<unknown, ThrowError, TError>>;
+    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.
      *
@@ -1592,6 +1591,7 @@ declare class GMNValidatorProxy<ThrowError extends boolean, TError extends Error
 
 declare class PrefixManagerProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TStreamingInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt> {
     #private;
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TStreamingInvocationContext, TBigInt>);
     definePrefix(prefix: string, prefixType: Nullishable<PrefixType>, tweakFactor: Nullishable<number>): Matrix<unknown>;
     gcpLength(identifierType: string, matrixIdentifiers: Matrix<string>): Promise<MatrixResult<number, ThrowError, TError>>;
     gcpLengthDateTime(): Promise<SingletonResult<string, ThrowError, TError>>;
@@ -1747,24 +1747,28 @@ interface Localization {
     /**
      * Name.
      */
-    name: string;
+    readonly name: string;
     /**
      * Description.
      */
-    description: string;
+    readonly description: string;
 }
 /**
  * Function localization.
  */
 interface FunctionLocalization extends Localization {
+    /**
+     * Namespace function name.
+     */
+    readonly namespaceFunctionName: string;
     /**
      * Documentation URL.
      */
-    documentationURL: string;
+    readonly documentationURL: string;
     /**
      * Parameters map.
      */
-    parametersMap: Map<string, Localization>;
+    readonly parametersMap: ReadonlyMap<string, Localization>;
 }
 /**
  * Abstract generator.
@@ -1778,6 +1782,10 @@ declare abstract class Generator {
      * Include localizations if true.
      */
     constructor(includeLocalizations?: boolean);
+    /**
+     * Get the logger.
+     */
+    get logger(): Logger<object>;
     /**
      * Get the locales.
      */
@@ -1787,38 +1795,29 @@ declare abstract class Generator {
      */
     protected get defaultLocale(): string;
     /**
-     * Get function localization.
-     *
-     * @param locale
-     * Locale.
-     *
-     * @param namespaceFunctionName
-     * Namespace function name.
-     *
-     * @returns
-     * Function localization.
+     * Initialize the generation of the output.
      */
-    protected getFunctionLocalization(locale: string, namespaceFunctionName: string): FunctionLocalization;
+    protected abstract initialize(): void;
     /**
-     * Get parameter localization.
+     * Create a namespace.
      *
-     * @param locale
-     * Locale.
+     * @param namespace
+     * Namespace.
+     */
+    protected abstract createNamespace(namespace: string | undefined): void;
+    /**
+     * Create a category.
      *
-     * @param namespaceFunctionName
-     * Namespace function name.
+     * @param namespace
+     * Namespace.
      *
-     * @param parameterName
-     * Parameter name.
+     * @param category
+     * Category.
      *
-     * @returns
-     * Parameter localization.
+     * @param categoryLocalizationsMap
+     * Category localizations map.
      */
-    protected getParameterLocalization(locale: string, namespaceFunctionName: string, parameterName: string): Localization;
-    /**
-     * Initialize the generation of the output.
-     */
-    protected abstract initialize(): void;
+    protected abstract createCategory(namespace: string | undefined, category: string, categoryLocalizationsMap: ReadonlyMap<string, string>): void;
     /**
      * Create a proxy object for a class.
      *
@@ -1836,7 +1835,7 @@ declare abstract class Generator {
      * Method descriptor.
      *
      * @param functionLocalizationsMap
-     * Localizations map.
+     * Function localizations map.
      */
     protected abstract createProxyFunction(classDescriptor: ClassDescriptor, methodDescriptor: MethodDescriptor, functionLocalizationsMap: ReadonlyMap<string, FunctionLocalization>): void;
     /**
@@ -1863,4 +1862,4 @@ declare abstract class Generator {
  */
 declare function expandParameterDescriptor(parameterDescriptor: ParameterDescriptor | ExtendsParameterDescriptor): ParameterDescriptor;
 
-export { type Address, AlphabeticProxy, AlphanumericProxy, type AppData, AppExtension, type AppExtensionLocaleResources, AppUtilityProxy, CharacterSetCreatorProxy, CharacterSetValidatorProxy, type ClassDescriptor, type ErrorExtends, type ExtendsParameterDescriptor, type FunctionLocalization, index as GS1, Generator, HexadecimalProxy, LibProxy, type Localization, type Matrix, type MatrixResult, type MethodDescriptor, NumericProxy, type ParameterDescriptor, type Range, RegExpProxy, type ReplacementParameterDescriptor, type Sheet, type SheetAddress, type SheetRange, type SingletonResult, type StreamingCancelledCallback, type StreamingConsumerCallback, TransformerProxy, type Type, type TypeKey, Types, appExtensionNS, appExtensionResources, decodeAppData, encodeAppData, expandParameterDescriptor, i18nAppExtensionInit, i18nextAppExtension };
+export { type Address, AlphabeticProxy, AlphanumericProxy, AppExtension, type AppExtensionLocaleResources, AppHelperProxy, CharacterSetCreatorProxy, CharacterSetValidatorProxy, type ClassDescriptor, type ErrorExtends, type ExtendsParameterDescriptor, type FunctionLocalization, index as GS1, Generator, HexadecimalProxy, LibProxy, type Localization, type Matrix, type MatrixResult, type MethodDescriptor, Multiplicities, type Multiplicity, type MultiplicityKey, NumericProxy, type ParameterDescriptor, type Range, RegExpProxy, type ReplacementParameterDescriptor, type Sheet, type SheetAddress, type SheetRange, type SingletonResult, type StreamingCancelledCallback, type StreamingConsumerCallback, TransformerProxy, type Type, type TypeKey, Types, appExtensionNS, appExtensionResourceBundle, expandParameterDescriptor, i18nAppExtensionInit, i18nextAppExtension };