@nu-art/thunderstorm-frontend 0.400.5

package/utils/EditableItem.d.ts

@@ -0,0 +1,240 @@
+import { ArrayType, AssetValueType, AwaitedDebounceInstance, DBProto, InvalidResult, Logger, RecursiveReadonly, ResolvableContent, SubsetKeys } from '@nu-art/ts-common';
+import { ModuleFE_BaseApi } from '../modules/db-api-gen/ModuleFE_BaseApi.js';
+export type UIProps_EditableItem<EnclosingItem, K extends keyof EnclosingItem, ItemType, Prop extends AssetValueType<EnclosingItem, K, ItemType> = AssetValueType<EnclosingItem, K, ItemType>> = {
+    editable: EditableItem<EnclosingItem>;
+    prop: Prop;
+    ignoreError?: boolean;
+};
+type ValidationErrors<T> = {
+    autoSave: boolean;
+    editing: boolean;
+    results: InvalidResult<T>;
+};
+export type Editable_OnError<T> = (item: Partial<T>, err: Error) => any | Promise<any>;
+export type Editable_SaveAction<T> = (item: T) => Promise<T>;
+export type Editable_PreSaveAction<T> = (item: T) => void;
+export type Editable_DeleteAction<T> = (item: T) => Promise<void>;
+export type Editable_OnChange<T> = (editable: EditableItem<T>) => Promise<void>;
+export declare const EditableItemStatus_Saving = "saving";
+export declare const EditableItemStatus_SavedWithErrors = "saved-with-errors";
+export declare const EditableItemStatus_FailedValidation = "failed-validation";
+export declare const EditableItemStatus_ErrorSaving = "error-saving";
+export declare const EditableItemStatus_UnsavedChanges = "unsaved-changes";
+export declare const EditableItemStatus_Creating = "creating";
+export declare const EditableItemStatus_Saved = "saved";
+export declare const EditableItemStatus_Unknown = "unknown";
+declare const EditableItemStatuses: string[];
+export type EditableItem_Status = typeof EditableItemStatuses[number];
+export interface EditableItemStatusListener {
+    onEditableItemStatusChanged(newStatus: EditableItem_Status, prevStatus: EditableItem_Status, editableItem: EditableItem<any>): any | Promise<any>;
+}
+/**
+ * A utility class for editing any item of type T.
+ * It encapsulates an item along with functions to save and delete the item.
+ * This class can be used with any type of item that can be modified, saved, and deleted.
+ *
+ * @template T The type of the item.
+ */
+export declare class EditableItem<T> extends Logger {
+    static AUTO_SAVE: boolean;
+    protected readonly internalSaveAction: Editable_SaveAction<T>;
+    private status;
+    private statusListener;
+    readonly item: Partial<T>;
+    protected originalItem: Partial<T>;
+    protected validationResults?: ValidationErrors<T>;
+    protected conflictingItem?: T;
+    protected _autoSave: boolean;
+    protected _isSaving: boolean;
+    protected saveError?: Error;
+    protected onSaveCompleted?: (item: T) => any;
+    protected onChanged?: Editable_OnChange<T>;
+    protected preSaveAction?: Editable_PreSaveAction<T>;
+    private deleteAction;
+    private saveAction;
+    private onError?;
+    /**
+     * Constructs an EditableItem instance.
+     *
+     * @param item The item to be edited.
+     * @param saveAction The function to be called when saving the item.
+     * @param deleteAction The function to be called when deleting the item.
+     */
+    constructor(item: Partial<T>);
+    private updateItemImpl;
+    setOnError(onError: Editable_OnError<T>): this;
+    setOnChanged(onChanged?: Editable_OnChange<T>): this;
+    protected handleValidationError(err: Error): void;
+    setSaveAction(saveAction: Editable_SaveAction<T>): this;
+    setDeleteAction(deleteAction: Editable_DeleteAction<T>): this;
+    setPreSaveAction(preSaveAction: Editable_PreSaveAction<T>): this;
+    setOnDelete(onDelete: (item: T) => Promise<any>): this;
+    setOnSaveCompleted(onSaved?: (item: T) => any): this;
+    setConflictingItem(conflictingItem?: T): void;
+    protected hasConflicts(conflictingItem: T): boolean;
+    hasChanges(): boolean;
+    addStatusListener(listener: EditableItemStatusListener): void;
+    removeStatusListener(listener: EditableItemStatusListener): void;
+    protected calculateState(): void;
+    protected setStatus(newStatus: EditableItem_Status): void;
+    getStatus(): string;
+    /**
+     * Set the auto-save mode.Page_ItemsEditor
+     *
+     * @param mode The auto-save mode.
+     * @returns The instance itself for method chaining.
+     */
+    setAutoSave(mode: boolean): this;
+    /**
+     * Get the saving status of the current editable instance
+     * @returns The saving status as boolean
+     */
+    isSaving(): boolean;
+    /**
+     * Set the value of a specific property in the item.
+     *
+     * @template K The type of the key.
+     * @param key The key of the property.
+     * @param value The new value of the property.
+     * @returns A boolean indicating whether the value has been set.
+     */
+    set<K extends keyof T>(key: K, value: ResolvableContent<T[K] | undefined>): boolean;
+    /**
+     * Updates the item with the given values and performs auto-save if enabled.
+     * This method allows partial updates, only the properties provided in the values object will be updated.
+     *
+     * @param values An object with partial properties of T.
+     * @returns A promise representing the auto-save operation if changes were made and auto-save is enabled.
+     */
+    updateObj(values: Partial<{
+        [K in keyof T]: ResolvableContent<T[K] | undefined, [T[K] | undefined]>;
+    }>): Promise<void>;
+    /**
+     * Equivalent to array.push
+     * @param value
+     * @param index
+     */
+    updateArrayAt(value: ArrayType<T>, index?: number): Promise<void>;
+    removeArrayItem(index: number): Promise<void>;
+    /**
+     * Update the value of a specific property in the item and perform auto-save if enabled.
+     *
+     * @template K The type of the key.
+     * @param key The key of the property.
+     * @param value The new value of the property.
+     * @returns A promise representing the auto-save operation if enabled, undefined otherwise.
+     */
+    update<K extends keyof T>(key: K, value: ((item?: T[K]) => T[K]) | T[K] | undefined): Promise<void>;
+    /**
+     * Get a value of a specific property
+     *
+     * @template K The type of the key.
+     * @param key The key of the property.
+     * @param fallbackValue
+     * @returns Readonly type of the value in T[K].
+     */
+    get<K extends keyof T>(key: K, fallbackValue?: T[K]): RecursiveReadonly<T[K]>;
+    hasError<K extends keyof T>(key?: K): (Readonly<InvalidResult<T[K]>> | Readonly<string>) | undefined;
+    hasErrors: () => boolean;
+    hasValidationError: () => boolean;
+    protected setValidationResults(ValidationResults?: ValidationErrors<T>): this;
+    /**
+     * If auto save in the editable item is true, preform the save action
+     * Can be overridden in deriving classes
+     * @protected
+     */
+    protected autoSaveImpl(): Promise<void>;
+    protected processResponse(dbItem: T): T;
+    private autoSave;
+    /**
+     * Save the item by calling the saveAction function.
+     *
+     * @returns The promise returned by the saveAction function.
+     */
+    save(consumeError?: boolean): Promise<T>;
+    /**
+     * Delete the item by calling the deleteAction function.
+     *
+     * @template K The type of the key.
+     * @returns A promise representing the delete operation.
+     */
+    delete<K extends keyof T>(): Promise<void>;
+    /**
+     * Return a new EditableItem that represents a property of the current item.
+     *
+     * @template K The type of the key.
+     * @param key The key of the property.
+     * @param defaultValue The default value of the property.
+     * @returns The new EditableItem.
+     */
+    editProp<K extends keyof T>(key: K, defaultValue: ResolvableContent<Partial<NonNullable<T[K]>>>): EditableItem<NonNullable<T[K]>>;
+    /**
+     * Return a new EditableItem for the DB Entity described by the reference id associated with the provided key and module.
+     *
+     * @template K The type of the key.
+     * @param key The key of the reference id.
+     * @param module The module associated with the reference id.
+     * @param initialValue An initial value to use in case there is no reference id.
+     *
+     * @returns The new EditableItem.
+     */
+    editRefV3<Proto extends DBProto<any>, K extends SubsetKeys<keyof T, T, string>>(key: K, module: ModuleFE_BaseApi<Proto>, initialValue: Partial<Proto['uiType']>): EditableDBItemV3<Proto>;
+    /**
+     * Implement in children! validate the item using custom logic
+     * @protected
+     */
+    validate(): void;
+    /**
+     * Trigger on change with all necessary actions for the editable instance
+     * @protected
+     */
+    protected callOnChange(): void;
+    /**
+     * handle item update from a different source out of the editable item
+     * @param newItem The item passed to the instance from the third party
+     */
+    updateItem(newItem: T): void;
+}
+/**
+ * A utility class for editing any item of type T that can be stored in a database.
+ * This class extends EditableItem and adds functionality related to database operations.
+ *
+ * @template T The type of the item that extends DB_Object.
+ * @template Ks The keys of the T type. Default is '_id'.
+ */
+export declare class EditableDBItemV3<Proto extends DBProto<any>> extends EditableItem<Proto['uiType']> {
+    private readonly module;
+    private debounceInstance;
+    private debounceTimeout;
+    /**
+     * Constructs an EditableDBItemV3 instance.
+     *
+     * @param item The item to be edited.
+     * @param module The module for database operations.
+     * @param onCompleted The function to be called when the operation is completed.
+     * @param debounceInstance Debounce instance from previous editable item
+     */
+    constructor(item: Partial<Proto['uiType']>, module: ModuleFE_BaseApi<Proto>, debounceInstance?: AwaitedDebounceInstance<any, any>);
+    save(consumeError?: boolean): Promise<Proto['dbType']>;
+    protected processResponse(dbItem: Proto['dbType']): Proto['dbType'];
+    /**
+     * Preform auto save in editable db item will be in debounce
+     * @protected
+     */
+    protected autoSaveImpl(): Promise<void>;
+    setDebounceTimeout: (timeout: number) => EditableDBItemV3<Proto>;
+    protected hasConflicts(_conflictingItem: Proto['dbType']): boolean;
+    protected calculateState(): void;
+    /**
+     * Use the db module provided to validate and update the validation results accordingly
+     * @return preDB item if validation succeeded otherwise returns void
+     */
+    validate(): Proto["preDbType"] | undefined;
+    /**
+     * Update db item from a source out of the save action merged with the current UI item in the instance
+     * @param newItem The item passed to the instance from the third party
+     */
+    updateItem(newItem: Proto['uiType']): void;
+    protected handleValidationError(e: Error): void;
+}
+export {};