@aidc-toolkit/core 1.0.41 → 1.0.43-beta

package/dist/index.d.ts

@@ -1,761 +1,30 @@
-import { ISettingsParam, Logger } from 'tslog';
-import { Resource, i18n } from 'i18next';
-
-/**
- * Typed function, applicable to any function, stricter than {@linkcode Function}.
- *
- * @template TFunction
- * Function type.
- */
-type TypedFunction<TFunction extends (...args: Parameters<TFunction>) => ReturnType<TFunction>> = (...args: Parameters<TFunction>) => ReturnType<TFunction>;
-/**
- * Typed synchronous function, applicable to any function that doesn't return a {@linkcode Promise}.
- *
- * @template TFunction
- * Function type.
- */
-type TypedSyncFunction<TFunction extends TypedFunction<TFunction>> = [ReturnType<TFunction>] extends [PromiseLike<unknown>] ? never : TypedFunction<TFunction>;
-/**
- * Arbitrary constructor. An arbitrary constructor doesn't have to be an exact match to a constructor; the only
- * requirements are that `TConstructorParameters` have compatible types (exact or wider types of the actual constructor
- * parameters) and that `TConstructorInstance` be a compatible type (exact or narrower type of the actual constructor
- * instance).
- *
- * @template TConstructorParameters
- * Constructor parameters types.
- *
- * @template TConstructorInstance
- * Constructor instance type.
- */
-type Constructor<TConstructorParameters extends unknown[], TConstructorInstance> = new (...args: TConstructorParameters) => TConstructorInstance;
-/**
- * Arbitrary abstract constructor. Abstract version of {@linkcode Constructor}.
- *
- * @template TConstructorParameters
- * Constructor parameters types.
- *
- * @template TConstructorInstance
- * Constructor instance type.
- */
-type AbstractConstructor<TConstructorParameters extends unknown[], TConstructorInstance> = abstract new (...args: TConstructorParameters) => TConstructorInstance;
-/**
- * Typed constructor, applicable to any constructor.
- *
- * @template TConstructor
- * Constructor type.
- */
-type TypedConstructor<TConstructor extends abstract new (...args: ConstructorParameters<TConstructor>) => InstanceType<TConstructor>> = Constructor<ConstructorParameters<TConstructor>, InstanceType<TConstructor>>;
-/**
- * Typed abstract constructor, applicable to any constructor.
- *
- * @template TConstructor
- * Constructor type.
- */
-type TypedAbstractConstructor<TConstructor extends abstract new (...args: ConstructorParameters<TConstructor>) => InstanceType<TConstructor>> = AbstractConstructor<ConstructorParameters<TConstructor>, InstanceType<TConstructor>>;
-/**
- * Promisable type. Extends a type by allowing a {@linkcode Promise} of the same type. Typically used in abstract method
- * declarations where the implementing class may or may not implement the method as asynchronous.
- */
-type Promisable<T> = T | Promise<T>;
-/**
- * Determine the fundamental promised type. This is stricter than `Awaited<Type>` in that it requires a {@linkcode
- * Promise}.
- *
- * @template T
- * Promised type.
- */
-type PromisedType<T> = [T] extends [PromiseLike<infer TPromised>] ? TPromised : never;
-/**
- * Typed asynchronous function, applicable to any function that returns a {@linkcode Promise}.
- *
- * @template TFunction
- * Function type.
- */
-type TypedAsyncFunction<TMethod extends (...args: Parameters<TMethod>) => PromiseLike<PromisedType<ReturnType<TMethod>>>> = (...args: Parameters<TMethod>) => Promise<PromisedType<ReturnType<TMethod>>>;
-/**
- * Nullishable type. Extends a type by allowing `null` and `undefined`.
- *
- * @template T
- * Type.
- */
-type Nullishable<T> = T | null | undefined;
-/**
- * Non-nullishable type. If T is an object type, it is spread and attributes within it are made non-nullishable.
- * Equivalent to a deep `Required<T>` for an object and `NonNullable<T>` for any other type.
- *
- * @template T
- * Type.
- */
-type NonNullishable<T> = T extends object ? {
-    [P in keyof T]-?: NonNullishable<T[P]>;
-} : NonNullable<T>;
-/**
- * Make some keys within a type optional.
- *
- * @template T
- * Object type.
- *
- * @template K
- * Object key type.
- */
-type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-/**
- * Type to restrict property keys to those that are strings and that support a specified type.
- *
- * @template T
- * Object type.
- *
- * @template P
- * Object property type.
- */
-type PropertyKeys<T, P> = {
-    [K in keyof T]: K extends string ? T[K] extends P ? K : never : never;
-}[keyof T];
-
-/**
- * Create an object with omitted entries.
- *
- * @template T
- * Object type.
- *
- * @template K
- * Object key type.
- *
- * @param o
- * Object.
- *
- * @param keys
- * Keys to omit.
- *
- * @returns
- * Edited object.
- */
-declare function omit<T extends object, K extends keyof T>(o: T, ...keys: K[]): Omit<T, K>;
-/**
- * Create an object with picked entries.
- *
- * @template T
- * Object type.
- *
- * @template K
- * Object key type.
- *
- * @param o
- * Object.
- *
- * @param keys
- * Keys to pick.
- *
- * @returns
- * Edited object.
- */
-declare function pick<T extends object, K extends keyof T>(o: T, ...keys: K[]): Pick<T, K>;
-/**
- * Create an object from a wide object without entries matching those from a narrow object.
- *
- * @template TWide
- * Wide object type.
- *
- * @template TNarrow
- * Narrow object type.
- *
- * @template K
- * Narrow object key type, subset of wide object key type.
- *
- * @param wide
- * Wide object.
- *
- * @param narrow
- * Narrow object.
- *
- * @returns
- * Edited object.
- */
-declare function exclude<TWide extends TNarrow, TNarrow extends object, K extends keyof TNarrow>(wide: TWide, narrow: TNarrow): Omit<TWide, K>;
-/**
- * Create an object from a wide object with entries matching those from a narrow object.
- *
- * @template TWide
- * Wide object type.
- *
- * @template TNarrow
- * Narrow object type.
- *
- * @template K
- * Narrow object key type, subset of wide object key type.
- *
- * @param wide
- * Wide object.
- *
- * @param narrow
- * Narrow object.
- *
- * @returns
- * Edited object.
- */
-declare function include<TWide extends TNarrow, TNarrow extends object, K extends keyof TNarrow>(wide: TWide, narrow: TNarrow): Pick<TWide, K>;
-/**
- * Cast a property as a more narrow type.
- *
- * @template T
- * Object type.
- *
- * @template K
- * Object key type.
- *
- * @template TAsType
- * Desired type.
- *
- * @param o
- * Object.
- *
- * @param key
- * Key of property to cast.
- *
- * @returns
- * Single-key object with property cast as desired type.
- */
-declare function propertyAs<T extends object, K extends keyof T, TAsType extends T[K]>(o: T, key: K): Readonly<Omit<T, K> extends T ? Partial<Record<K, TAsType>> : Record<K, TAsType>>;
-/**
- * Determine if argument is nullish. Application extension may pass `null` or `undefined` to missing parameters.
- *
- * @param argument
- * Argument.
- *
- * @returns
- * True if argument is undefined or null.
- */
-declare function isNullish(argument: unknown): argument is null | undefined;
-
-/**
- * Log levels.
- */
-declare const LogLevels: {
-    readonly Silly: 0;
-    readonly Trace: 1;
-    readonly Debug: 2;
-    readonly Info: 3;
-    readonly Warn: 4;
-    readonly Error: 5;
-    readonly Fatal: 6;
-};
-/**
- * Log level key.
- */
-type LogLevelKey = keyof typeof LogLevels;
-/**
- * Log level.
- */
-type LogLevel = typeof LogLevels[LogLevelKey];
-/**
- * Get the log level enumeration value corresponding to a string or number.
- *
- * @param untypedLogLevel
- * Untyped log level.
- *
- * @returns
- * Typed log level or default `LogLevels.Info` if untyped log level not provided..
- */
-declare function logLevelOf(untypedLogLevel?: string | number): LogLevel;
-/**
- * Get a logger with an optional log level. The underlying implementation is
- * [`tslog`](https://tslog.js.org/).
- *
- * @param logLevel
- * Log level as enumeration value or string. Mapped to `minLevel` and sets `hideLogPositionForProduction` to true in
- * settings if at {@linkcode LogLevels.Info} or higher. Default is {@linkcode LogLevels.Info}.
- *
- * @param settings
- * Detailed settings. See [`tslog`](https://tslog.js.org/#/?id=settings) documentation for details. The `minLevel` is
- * ignored in favour of `logLevel` but `hideLogPositionForProduction` will override the default logic.
- *
- * @param logObj
- * Default log object. See [`tslog`](https://tslog.js.org/#/?id=defining-and-accessing-logobj) documentation for
- * details.
- *
- * @returns
- * Logger.
- *
- * @template T
- * Log object type.
- */
-declare function getLogger<T extends object = object>(logLevel?: string | number, settings?: ISettingsParam<T>, logObj?: T): Logger<T>;
-/**
- * Get a loggable representation of a value. Values are returned unmodified, except as follows:
- *
- * - Big integers are converted to whole numbers where possible, otherwise as their decimal string representations.
- * - Arrays are limited to a maximum of ten elements. Any array longer than ten elements is replaced with the first four
- * elements, a string of three dots, and the last four elements. This may still create large results for
- * multidimensional arrays.
- * - Errors are converted to objects with `name`, `message`, and `stack` properties.
- * - Symbols are converted to their string representations.
- * - Functions are converted to strings of the form `Function(name)`.
- *
- * @param value
- * Value.
- *
- * @returns
- * Loggable value.
- */
-declare function loggableValue(value: unknown): unknown;
-/**
- * Logger transport that stores messages in memory.
- */
-declare class MemoryTransport<T extends object> {
-    #private;
-    /**
-     * Constructor.
-     *
-     * @param logger
-     * Logger.
-     *
-     * @param maximumLength
-     * Maximum length of messages array.
-     *
-     * @param truncateLength
-     * Length to which messages array is truncated when maximum is reached. Default is 50% of `maximumLength`, maximum
-     * is 80% of `maximumLength`.
-     */
-    constructor(logger: Logger<T>, maximumLength: number, truncateLength?: number);
-    /**
-     * Get the messages.
-     */
-    get messages(): string[];
-    /**
-     * Get the maximum length of messages array.
-     */
-    get maximumLength(): number;
-    /**
-     * Get the length to which messages array is truncated when maximum is reached.
-     */
-    get truncateLength(): number;
-    /**
-     * Add a notification callback. If one already exists under the current name, do nothing.
-     *
-     * @param name
-     * Callback name.
-     *
-     * @param notificationCallback
-     * Callback.
-     *
-     * @returns
-     * True if successfully added.
-     */
-    addNotificationCallback(name: string, notificationCallback: (message: string | undefined, messages: readonly string[]) => void): boolean;
-    /**
-     * Remove a notification callback.
-     *
-     * @param name
-     * Callback name.
-     */
-    removeNotificationCallback(name: string): void;
-    /**
-     * Resize the messages array.
-     *
-     * @param maximumLength
-     * Maximum length of messages array.
-     *
-     * @param truncateLength
-     * Length to which messages array is truncated when maximum is reached. Default is 50% of `maximumLength`, maximum
-     * is 80% of `maximumLength`.
-     */
-    resize(maximumLength: number, truncateLength?: number): void;
-}
-
-/**
- * Parsed version.
- */
-interface ParsedVersion {
-    /**
-     * Major version.
-     */
-    readonly majorVersion: number;
-    /**
-     * Minor version.
-     */
-    readonly minorVersion: number;
-    /**
-     * Patch version.
-     */
-    readonly patchVersion: number;
-    /**
-     * Pre-release identifier.
-     */
-    readonly preReleaseIdentifier: string | undefined;
-    /**
-     * Date/time included with pre-release identifier.
-     */
-    readonly dateTime: string | undefined;
-}
-/**
- * Parse version.
- *
- * @param version
- * Version, typically from package.json.
- *
- * @returns
- * Parsed version.
- */
-declare function parseVersion(version: string): ParsedVersion;
-
-/**
- * Alpha URL. Reads from local application storage, path "config", key "resources.local", if present, otherwise defaults
- * to Vite development server URL.
- */
-declare const ALPHA_URL: Promise<string>;
-/**
- * AIDC Toolkit website base URL.
- */
-declare const WEBSITE_BASE_URL = "https://aidc-toolkit.com";
-/**
- * Determine the website URL based on the package version.
- *
- * @param version
- * Package version.
- *
- * @param includeVersionInProduction
- * If true, the version is included in the URL in production.
- *
- * @param alphaURL
- * URL if pre-release identifier is "alpha".
- *
- * @param nonAlphaRelativeURL
- * Non-alpha URL, relative to website base URL plus pre-release identifier (optional) and version.
- *
- * @returns
- * Fully-formed website URL based on the package version.
- */
-declare function websiteURL(version: string, includeVersionInProduction: boolean, alphaURL: string, nonAlphaRelativeURL?: string): string;
-
-/**
- * Application data.
- */
-type AppData = string | number | boolean | 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;
-
-/**
- * Generic read-only application data storage.
- */
-declare abstract class ReadOnlyAppDataStorage<SupportsBinary extends boolean> {
-    #private;
-    /**
-     * Extension to identify binary data.
-     */
-    protected static readonly BINARY_EXTENSION = ".bin";
-    /**
-     * Extension to identify JSON data.
-     */
-    protected static readonly JSON_EXTENSION = ".json";
-    /**
-     * Constructor.
-     *
-     * @param supportsBinary
-     * True if binary data is supported.
-     *
-     * @param path
-     * Storage path prepended to each key along with '/' if defined, empty string if not.
-     */
-    protected constructor(supportsBinary: SupportsBinary, path?: string);
-    /**
-     * Determine if binary data is supported.
-     */
-    get supportsBinary(): SupportsBinary;
-    /**
-     * Get the storage path, prepended to each key.
-     */
-    get path(): string;
-    /**
-     * Build the full storage key.
-     *
-     * @param pathKey
-     * Key relative to path.
-     *
-     * @param isBinary
-     * True if key is to binary data, false or undefined if to string data. Ignored if binary data is not supported.
-     *
-     * @returns
-     * Full storage key.
-     */
-    protected fullKey(pathKey: string, isBinary: boolean): string;
-    /**
-     * Read a string or binary data from persistent storage.
-     *
-     * @param key
-     * Storage key (file path in Node.js, key in localStorage).
-     *
-     * @param asBinary
-     * True if binary data is requested, false or undefined if string data is requested. Ignored if binary data is not
-     * supported.
-     *
-     * @returns
-     * String or binary data or undefined if not found.
-     */
-    protected abstract doRead(key: string, asBinary: boolean | undefined): Promisable<(SupportsBinary extends true ? string | Uint8Array : string) | undefined>;
-    /**
-     * Read application data from storage.
-     *
-     * @param pathKey
-     * Key relative to path.
-     *
-     * @param asBinary
-     * True if binary data is requested, false or undefined if string data is requested. Ignored if binary data is not
-     * supported.
-     *
-     * @returns
-     * Application data or undefined if not found.
-     */
-    read(pathKey: string, asBinary?: boolean): Promise<AppData | undefined>;
-}
-/**
- * Generic read/write application data storage.
- */
-declare abstract class AppDataStorage<SupportsBinary extends boolean> extends ReadOnlyAppDataStorage<SupportsBinary> {
-    /**
-     * Write a string or binary data in persistent storage.
-     *
-     * @param key
-     * Storage key (file path in Node.js, key in localStorage).
-     *
-     * @param data
-     * String or binary data.
-     */
-    protected abstract doWrite(key: string, data: SupportsBinary extends true ? string | Uint8Array : string): Promisable<void>;
-    /**
-     * Write application data to storage.
-     *
-     * @param pathKey
-     * Key relative to path.
-     *
-     * @param appData
-     * Application data to write.
-     */
-    write(pathKey: string, appData: AppData): Promise<void>;
-    /**
-     * Delete from persistent storage.
-     *
-     * @param key
-     * Storage key (file path in Node.js, key in localStorage).
-     */
-    protected abstract doDelete(key: string): Promisable<void>;
-    /**
-     * Delete application data from persistent storage.
-     *
-     * @param pathKey
-     * Key relative to path.
-     *
-     * @param asBinary
-     * True if key is to binary data, false or undefined if to string data. Ignored if binary data is not supported.
-     */
-    delete(pathKey: string, asBinary?: boolean): Promise<void>;
-}
-
-/**
- * Local application data storage class for the current environment. This is a variable representing a `Promise` as the
- * implementing class is loaded dynamically to prevent the inclusion of unnecessary node dependencies in a browser
- * environment.
- */
-declare const LocalAppDataStorage: Promise<new (path?: string) => AppDataStorage<boolean>>;
-
-/**
- * Remote application data storage using HTTP. The `store()` and `delete()` methods are not supported.
- */
-declare class RemoteAppDataStorage extends ReadOnlyAppDataStorage<true> {
-    /**
-     * Constructor.
-     *
-     * @param baseURL
-     * Base URL. The URL must not end with a slash.
-     */
-    constructor(baseURL: string);
-    /**
-     * @inheritDoc
-     */
-    protected doRead(key: string, asBinary: boolean | undefined): Promise<string | Uint8Array | undefined>;
-}
-
-/**
- * Generic cache. Typically used to manage a local copy of remote data that is not refreshed regularly.
- *
- * @template TCache
- * Type of cached data.
- *
- * @template TSource
- * Type of source data. The type may be different from the cached data type if a transformation is required.
- */
-declare abstract class Cache<TCache, TSource = TCache> {
-    /**
-     * Get the date/time at or after which the source should be checked for updates. If the value is undefined, this is
-     * the first usage.
-     */
-    abstract get nextCheckDateTime(): Promisable<Date | undefined>;
-    /**
-     * Get the date/time at which the cache was last updated. This may more accurately reflect the date/time at which
-     * the last source retrieved was updated. If the value is undefined, there is no data in the cache.
-     */
-    abstract get cacheDateTime(): Promisable<Date | undefined>;
-    /**
-     * Get the cache data. This should only ever be called if the cache date/time is defined.
-     */
-    abstract get cacheData(): Promisable<TCache>;
-    /**
-     * Get the date/time at which the source was last updated. This should not be called unless the next check date/time
-     * has passed, as it may trigger an expensive remote retrieval.
-     */
-    abstract get sourceDateTime(): Promisable<Date>;
-    /**
-     * Get the source data. This should not be called unless the next check date/time has passed, as it may trigger an
-     * expensive remote retrieval.
-     */
-    abstract get sourceData(): Promisable<TSource>;
-    /**
-     * Update the cache with only the next check date/time. The cache date/time and cache data must not be modified.
-     * This is typically called when the cache is up to date with the source or source retrieval has failed.
-     *
-     * @param nextCheckDateTime
-     * Next check date/time.
-     */
-    abstract update(nextCheckDateTime: Date): Promisable<void>;
-    /**
-     * Update all cache parameters. This is typically called when the cache is updated from the source.
-     *
-     * @param nextCheckDateTime
-     * Next check date/time.
-     *
-     * @param cacheDateTime
-     * Cache date/time.
-     *
-     * @param cacheData
-     * Cache data.
-     */
-    abstract update(nextCheckDateTime: Date, cacheDateTime: Date, cacheData: TCache): Promisable<void>;
-}
-
-/**
- * Hyperlink.
- */
-interface Hyperlink {
-    /**
-     * Reference, relative or absolute depending on the application.
-     */
-    readonly reference: string;
-    /**
-     * Human-readable text.
-     */
-    readonly text?: string | undefined;
-    /**
-     * Additional details.
-     */
-    readonly details?: string | undefined;
-}
-
-declare const _default: {
-    Logger: {
-        unknownLogLevel: string;
-    };
-    RemoteAppDataStorage: {
-        httpError: string;
-    };
-};
-
-/**
- * Locale strings type for generic manipulation.
- */
-interface LocaleResources {
-    [key: string]: LocaleResources | string;
-}
-/**
- * Internationalization operating environments.
- */
-declare const I18nEnvironments: {
-    /**
-     * Command-line interface (e.g., unit tests).
-     */
-    readonly CLI: 0;
-    /**
-     * Web server.
-     */
-    readonly Server: 1;
-    /**
-     * Web browser.
-     */
-    readonly Browser: 2;
-};
-/**
- * Internationalization operating environment key.
- */
-type I18nEnvironmentKey = keyof typeof I18nEnvironments;
-/**
- * Internationalization operating environment.
- */
-type I18nEnvironment = typeof I18nEnvironments[I18nEnvironmentKey];
-declare const coreNS = "aidct_core";
-/**
- * Locale resources type is extracted from the English locale resources object.
- */
-type CoreLocaleResources = typeof _default;
-/**
- * Core resource bundle.
- */
-declare const coreResourceBundle: Resource;
-declare const i18nextCore: i18n;
-/**
- * Initialize internationalization.
- *
- * @param i18next
- * Internationalization object. As multiple objects exist, this parameter represents the one for the module for which
- * internationalization is being initialized.
- *
- * @param environment
- * Environment in which the application is running.
- *
- * @param debug
- * Debug setting.
- *
- * @param defaultNS
- * Default namespace.
- *
- * @param defaultResourceBundle
- * Default resource bundle.
- *
- * @param i18nDependencyInits
- * Dependency internationalization initialization functions.
- *
- * @returns
- * Default resource bundle.
- */
-declare function i18nInit(i18next: i18n, environment: I18nEnvironment, debug: boolean, defaultNS: string, defaultResourceBundle: Resource, ...i18nDependencyInits: Array<(environment: I18nEnvironment, debug: boolean) => Promise<Resource>>): Promise<Resource>;
-/**
- * Initialize internationalization.
- *
- * @param environment
- * Environment in which the application is running.
- *
- * @param debug
- * Debug setting.
- *
- * @returns
- * Core resource bundle.
- */
-declare function i18nCoreInit(environment: I18nEnvironment, debug?: boolean): Promise<Resource>;
-
-export { ALPHA_URL, type AbstractConstructor, type AppData, AppDataStorage, Cache, type Constructor, type CoreLocaleResources, type Hyperlink, type I18nEnvironment, type I18nEnvironmentKey, I18nEnvironments, LocalAppDataStorage, type LocaleResources, type LogLevel, type LogLevelKey, LogLevels, MemoryTransport, type NonNullishable, type Nullishable, type Optional, type ParsedVersion, type Promisable, type PromisedType, type PropertyKeys, ReadOnlyAppDataStorage, RemoteAppDataStorage, type TypedAbstractConstructor, type TypedAsyncFunction, type TypedConstructor, type TypedFunction, type TypedSyncFunction, WEBSITE_BASE_URL, coreNS, coreResourceBundle, decodeAppData, encodeAppData, exclude, getLogger, i18nCoreInit, i18nInit, i18nextCore, include, isNullish, logLevelOf, loggableValue, omit, parseVersion, pick, propertyAs, websiteURL };
+/*!
+ * Copyright © 2024-2026 Dolphin Data Development Ltd. and AIDC Toolkit
+ * contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export type * from "./type.js";
+export * from "./type-helper.js";
+export * from "./logger.js";
+export * from "./parse-version.js";
+export * from "./website-url.js";
+export * from "./app-data.js";
+export * from "./app-data-storage.js";
+export * from "./local-app-data-storage.js";
+export * from "./http-fetch.js";
+export * from "./remote-app-data-storage.js";
+export * from "./cache.js";
+export type * from "./hyperlink.js";
+export * from "./locale/i18n.js";
+//# sourceMappingURL=index.d.ts.map