@typescript-package/data/types/typescript-package-data.d.ts

A lightweight TypeScript library for basic data management.

import { DataShape, AsyncReturn, IterValue, DataAdapter } from '@typedly/data';

/**
 * @description Manages the immutability states of `this` current instance.
 * @export
 * @abstract
 * @class Immutability
 */
declare abstract class Immutability {
    #private;
    /**
     * @description
     * @template Type
     * @param {Type} object
     * @returns {Readonly<Type>}
     */
    static deepFreeze<Type>(object: Type): Readonly<Type>;
    /**
     * @description
     * @public
     * @readonly
     * @type {boolean}
     */
    get frozen(): boolean;
    /**
     * @description
     * @public
     * @readonly
     * @type {boolean}
     */
    get locked(): boolean;
    /**
     * @description
     * @public
     * @readonly
     * @type {boolean}
     */
    get mutable(): boolean;
    /**
     * @description
     * @public
     * @readonly
     * @type {boolean}
     */
    get sealed(): boolean;
    /**
     * @description Deeply freezes current `this` instance.
     * @public
     * @returns {this} Returns current instance.
     */
    deepFreeze(): this;
    /**
     * @description "Prevents the modification of existing property attributes and values, and prevents the addition of new properties."
     * @public
     * @returns {this} Returns current instance.
     */
    freeze(): this;
    /**
     * @description Checks whether `this` current instance is frozen.
     * @public
     * @returns {boolean}
     */
    isFrozen(): boolean;
    /**
     * @description Checks whether the current instance is locked.
     * @public
     * @returns {boolean} Returns a `boolean` indicating whether current instance is locked.
     */
    isLocked(): boolean;
    /**
     * @description Checks whether the object is mutable.
     * @public
     * @returns {boolean} True if the object is mutable, otherwise `false`.
     */
    isMutable(): boolean;
    /**
     * @description Checks whether `this` current instance is sealed.
     * @public
     * @returns {boolean} Returns a `boolean` indicating whether current instance is sealed.
     */
    isSealed(): boolean;
    /**
     * @description Locks the object, means deeply freezes and blocks the `set()`, ensuring deep immutability.
     * It combines the features of `Object.freeze`, but extends immutability to nested structures (deep immutability).
     * @public
     * @returns {this} Returns current instance.
     */
    lock(): this;
    /**
     * @description "Prevents the modification of attributes of existing properties, and prevents the addition of new properties."
     * @public
     * @returns {this} Returns current instance.
     */
    seal(): this;
    /**
     * @description Validates the ability to set the value.
     * @protected
     * @returns {this} Returns current instance.
     */
    protected validate(): this;
}

/**
 * @description The core abstraction with immutability for handling data-related classes.
 * @export
 * @abstract
 * @class DataCore
 * @template T Represents the type of data value.
 * @template Async Indicates whether the operations are asynchronous.
 * @extends {Immutability}
 * @implements {DataShape<T>}
 */
declare abstract class DataCore<T, Async extends boolean = false> extends Immutability implements DataShape<T, Async> {
    /**
     * @description Symbol key for accessing the value of the data instance.
     * @public
     * @static
     * @type {*}
     */
    static valueSymbol: symbol;
    /**
     * @description The `string` tag representation of the `DataCore` class when used in `Object.prototype.toString.call(instance)`.
     * @public
     * @static
     * @type {string}
     */
    static toStringTag: string;
    /**
     * @description Checks whether the provided value implements the iterable interface.
     * @param {unknown} value The value to inspect.
     * @returns {value is Iterable<unknown>} True when value exposes an iterator function.
     */
    static isIterable(value: unknown): value is Iterable<unknown>;
    /**
     * @description Returns the `string` tag representation of the `DataCore` class when used in `Object.prototype.toString.call(instance)`.
     * @public
     * @readonly
     * @type {string}
     */
    get [Symbol.toStringTag](): string;
    /**
     * @description Returns the string tag of the current instance defined by the `Symbol.toStringTag`.
     * @public
     * @returns {string | undefined} The extracted class name, such as `'DataCore'`, or `undefined` if extraction fails.
     */
    get tag(): string | undefined;
    /**
     * @description Returns the value of generic type variable `T`.
     * @public
     * @abstract
     * @readonly
     * @type {T}
     */
    abstract get value(): T;
    /**
     * @description Clears the value by setting to `undefined` or `null`.
     * @public
     * @abstract
     * @returns {this} Returns `this` current instance.
     */
    abstract clear(): AsyncReturn<Async, this>;
    /**
     * @description Abstract method to clear or remove the stored data value.
     * @public
     * @abstract
     * @returns {this} Returns `this` current instance.
     */
    abstract destroy(): AsyncReturn<Async, this>;
    /**
     * @description Gets the value either asynchronously or synchronously based on the `Async` generic type variable.
     * @public
     * @abstract
     * @returns {AsyncReturn<Async, T>}
     */
    abstract getValue(): AsyncReturn<Async, T>;
    /**
     * @inheritdoc
     * @public
     * @returns {this}
     */
    lock(): this;
    /**
     * @description Sets the value of `T` in arbitrary parameter array.
     * @public
     * @abstract
     * @template {unknown[]} V The type of the values array.
     * @param {...V} values The arbitrary values array of type `V`.
     * @returns {this}
     */
    abstract setValue<V extends unknown[]>(...values: V): AsyncReturn<Async, this>;
    /**
     * @description Sets the value of `T` in arbitrary parameter.
     * @public
     * @abstract
     * @param {...T[]} value Arbitrary number of values of type `T`.
     * @returns {this}
     */
    abstract setValue(...value: T[]): AsyncReturn<Async, this>;
    /**
     * @description Sets the data value. Ensure `super.validate()` is called before invoking this method.
     * @public
     * @abstract
     * @param {T} value The data value of `T` to set.
     * @returns {this} Returns `this` current instance.
     */
    abstract setValue(value: T): AsyncReturn<Async, this>;
    /**
     * @description Returns an iterator for the data value.
     * @public
     * @returns {IterableIterator<T>}
     */
    [Symbol.iterator](): IterableIterator<IterValue<T>>;
}

/**
 * @description The abstract `AdapterData` class extends `DataCore` adding functionality for managing data value by adapter with arguments.
 * Designed to create data containers of `T` type managed by adapters that require constructor arguments.
 * @export
 * @abstract
 * @class AdapterData
 * @template T
 * @template {unknown[]} [G=unknown[]] Arguments type for the adapter constructor.
 * @template {boolean} [R=false] Indicates if the adapter operations are asynchronous.
 * @template {DataAdapter<T, R> | undefined} [A=DataAdapter<T, R>] The adapter type.
 * @extends {DataCore<T, R>}
 */
declare abstract class AdapterData<T, G extends unknown[] = unknown[], R extends boolean = false, A extends DataAdapter<T, R> | undefined = DataAdapter<T, R>> extends DataCore<T, R> {
    #private;
    /**
     * @description Returns the `string` tag representation of the `BaseData` class when used in `Object.prototype.toString.call(instance)`.
     * @public
     * @readonly
     * @type {string}
     */
    get [Symbol.toStringTag](): string;
    /**
     * @description The underlying adapter to handle the data value.
     * @public
     * @readonly
     * @type {(A | undefined)}
     */
    get adapter(): A | undefined;
    /**
     * @description Indicates if the adapter operations are asynchronous.
     * @public
     * @readonly
     * @type {R}
     */
    get async(): R;
    /**
     * @description Returns the privately stored value of generic type variable `T`.
     * @public
     * @readonly
     * @type {T}
     */
    get value(): T;
    /**
     * Creates an instance of `AdapterData`.
     * @constructor
     * @param {R} async Async switch for the adapter operations.
     * @param {?{new (...args: G): A}} [adapter] The adapter constructor.
     * @param {...G} args The arguments passed to the adapter constructor.
     */
    constructor(async: R, adapter?: {
        new (...args: G): A;
    }, ...args: G);
    /**
     * @description Clears the value to `undefined`.
     * @public
     * @returns {AsyncReturn<R, this>} The `this` current instance.
     */
    clear(): AsyncReturn<R, this>;
    /**
     * @description Destroys the value by setting it to `null`.
     * @public
     * @returns {AsyncReturn<R, this>} The `this` current instance.
     */
    destroy(): AsyncReturn<R, this>;
    /**
     * @description Gets the value either asynchronously or synchronously based on the `R` generic type variable.
     * @public
     * @returns {AsyncReturn<R, T>}
     */
    getValue(): AsyncReturn<R, T>;
    /**
     * @description Sets the data value.
     * @public
     * @param {T} value The data value of `T` to set.
     * @returns {AsyncReturn<R, this>} The `this` current instance.
     */
    setValue(value: T): AsyncReturn<R, this>;
    /**
     * @description The helper method to return conditional `this` based on async type `R`, and returned `result` of adapter.
     * @param {AsyncReturn<R, A> | this} result The result of the adapter operation if provided, or `this`.
     * @returns {AsyncReturn<R, this>} The `this` current instance.
     */
    protected returnThis(result: AsyncReturn<R, A> | this): AsyncReturn<R, this>;
}

/**
 * @description The `BaseData` is an abstract class that extends core features, adding functionality for managing the data value directly or through the adapter.
 * @export
 * @abstract
 * @class BaseData
 * @template T Type of the data value.
 * @template {unknown[]} [G=unknown[]] The arguments parameter type.
 * @template {boolean} [R=false] Indicates if the data operations are asynchronous.
 * @template {DataAdapter<T, R> | undefined} [A=undefined] Adapter type extending `DataAdapter` for handling the data value with it.
 * @extends {AdapterData<T, G, R, A>}
 */
declare abstract class BaseData<T, G extends unknown[] = unknown[], R extends boolean = false, A extends DataAdapter<T, R> | undefined = undefined> extends AdapterData<T, G, R, A> {
    #private;
    /**
     * @description Returns the `string` tag representation of the `BaseData` class when used in `Object.prototype.toString.call(instance)`.
     * @public
     * @readonly
     * @type {string}
     */
    get [Symbol.toStringTag](): string;
    /**
     * @description Returns the privately stored value of generic type variable `T`.
     * @public
     * @readonly
     * @type {T}
     */
    get value(): T;
    /**
     * Creates an instance of `BaseData`.
     * @constructor
     * @param {R} async Indicates if the data operations are asynchronous.
     * @param {T} value Initial data value of generic type variable `T`.
     * @param {?{new (value: T, ...args: G): A}} [adapter] Optional adapter class constructor for handling the data value.
     * @param {...G} args Arguments passed to the adapter class constructor, after the `value` parameter.
     */
    constructor(async: R, value: T, adapter?: {
        new (value: T, ...args: G): A;
    }, ...args: G);
    /**
     * @description Clears the value to `undefined`.
     * @public
     * @returns {AsyncReturn<R, this>} The `this` current instance.
     */
    clear(): AsyncReturn<R, this>;
    /**
     * @description Destroys the value by setting it to `null`.
     * @public
     * @returns {AsyncReturn<R, this>} The `this` current instance.
     */
    destroy(): AsyncReturn<R, this>;
    /**
     * @description Sets the data value.
     * @public
     * @param {T} value The data value of `T` to set.
     * @returns {AsyncReturn<R, this>} The `this` current instance.
     */
    setValue(value: T): AsyncReturn<R, this>;
}

/**
 * @description The `Data` class is a concrete class that extends the `BaseData` abstract class for instantiate base functionality.
 * @public
 * @export
 * @class Data
 * @template T Type of the data value.
 * @template {unknown[]} [G=unknown[]] Arguments passed to the adapter class constructor, after the `value` parameter.
 * @template {boolean} [R=false] Indicates whether the data operations are asynchronous.
 * @template {DataAdapter<T, R> | undefined} [A=DataAdapter<T, R>] Adapter type extending `DataAdapter` for handling the data value.
 * @extends {BaseData<T, G, R, A>}
 */
declare class Data<T, G extends unknown[] = unknown[], R extends boolean = false, A extends DataAdapter<T, R> | undefined = DataAdapter<T, R>> extends BaseData<T, G, R, A> {
    /**
     * @inheritdoc
     * @public
     * @readonly
     * @type {string}
     */
    static toStringTag: string;
    /**
     * @inheritdoc
     * @public
     * @readonly
     * @type {string}
     */
    get [Symbol.toStringTag](): string;
}

export { AdapterData, BaseData, Data, DataCore, Immutability };