@futdevpro/fsm-dynamo 1.20.88 → 1.20.93

package/build-esm/_models/control-models/data-model-params.control-model.js

@@ -0,0 +1,259 @@
+import { DyFM_Log } from '../../_collections/utils/log.util';
+import { DyFM_Object } from '../../_collections/utils/object.util';
+import { DyFM_getConstructionStackLocation } from '../../_collections/utils/stack.util';
+import { DyFM_getBasicPropertyType } from '../../_collections/utils/utilities.util';
+import { DyFM_BasicProperty_Type } from '../../_enums/basic-property-type.enum';
+import { DyFM_DataModel_Type } from '../../_enums/data-model-type.enum';
+import { DyFM_DataProperty_Params, } from './data-property-params.control-model';
+import { DyFM_Error } from './error.control-model';
+import { DyFM_DataModel_Settings } from './data-model-settings.control-model';
+/**
+ * Resolve a {@link DyFM_RetentionSettings} to a positive integer TTL in seconds, or `undefined`
+ * when no valid retention is configured (→ no TTL index is installed). `ttlSeconds` wins over
+ * `retentionDays`; non-finite or ≤ 0 values are rejected. Pure + side-effect-free (unit-tested).
+ */
+export function DyFM_resolveRetentionTtlSeconds(retention) {
+    if (!retention) {
+        return undefined;
+    }
+    const raw = retention.ttlSeconds !== undefined ? retention.ttlSeconds
+        : retention.retentionDays !== undefined ? retention.retentionDays * 86400
+            : undefined;
+    if (raw === undefined || !Number.isFinite(raw) || raw <= 0) {
+        return undefined;
+    }
+    return Math.floor(raw);
+}
+/**
+ * Resolve the declared indexes of a model to the VALID ones, or `undefined` when there is nothing
+ * to install. An entry is dropped when it has no usable `name` or no key at all — an index without
+ * keys is not installable, and a nameless one could not be reconciled on the next startup.
+ * Pure + side-effect-free (unit-tested).
+ */
+export function DyFM_resolveDeclaredIndexes(indexes) {
+    if (!indexes?.length) {
+        return undefined;
+    }
+    const valid = indexes.filter((entry) => !!entry && typeof entry.name === 'string' && !!entry.name.trim()
+        && !!entry.keys && Object.keys(entry.keys).length > 0);
+    return valid.length ? valid : undefined;
+}
+/* export type DyFM_Data_P<T extends DyFM_Metadata> = DyFM_DataModel_Params<T>;
+ *
+ * @example
+ * ```ts
+ * const params: DyFM_DataModel_Params<DyFM_Metadata> = new DyFM_DataModel_Params({
+ *   dataName: 'User',
+ *   properties: {
+ *     name: { type: DyFM_BasicProperty_Type.string },
+ *     age: { type: DyFM_BasicProperty_Type.number },
+ *   },
+ * });
+ */
+export class DyFM_DataModelParams_ControlModel extends DyFM_DataModel_Settings {
+    static {
+        Object.defineProperty(this, 'name', { value: 'DyFM_DataModel_Params' });
+    }
+    /* override properties?: DyFM_DataProperties<T>; */
+    stackLocation;
+    constructor(set) {
+        super(set);
+        try {
+            if (set) {
+                Object.assign(this, set);
+            }
+            this.stackLocation = DyFM_getConstructionStackLocation();
+            if (!this.properties || typeof this.properties !== 'object') {
+                DyFM_Log.error('DyFM_DataModel_Params.constructor: ' +
+                    `Properties are missing in "${this.dataName}" model.` +
+                    `\nstackLocation: ${this.stackLocation}\n`);
+                this.properties = {};
+            }
+            const keys = Object.keys(this.properties);
+            keys.forEach((key) => {
+                if (!key) {
+                    DyFM_Log.error('DyFM_DataModel_Params.constructor: ' +
+                        `A property key is missing in "${this.dataName}" model.` +
+                        `\nstackLocation: ${this.stackLocation}\n`);
+                }
+                const propertyParams = new DyFM_DataProperty_Params({
+                    ...this.properties[key],
+                    key: key,
+                }, this);
+                const basicType = DyFM_getBasicPropertyType(propertyParams.type);
+                if (basicType !== propertyParams.type) {
+                    propertyParams.nonBasicType = propertyParams.type;
+                    propertyParams.type = basicType;
+                }
+                this.properties[key] = propertyParams;
+                if (propertyParams.subObjectParams) {
+                    this.setKeysForSubObjectParams(propertyParams);
+                }
+            });
+            keys.forEach((key) => {
+                const property = this.properties[key];
+                /* if (property.vectorizeTo) {
+                  if (!this.properties[property.vectorizeTo]) {
+                    throw new Error(
+                      `Vectorize to property "${property.vectorizeTo}" is not found in ` +
+                      `"${this.dataName}" model.`
+                    );
+                  }
+          
+                  this.properties[property.vectorizeTo].vectorizeFrom ??= key;
+                } */
+                if (property.vectorizedFrom) {
+                    property.vectorizedFrom.forEach((fromKey) => {
+                        if (!this.properties[fromKey]) {
+                            DyFM_Log.error(`Vectorized from property "${fromKey}" is not found in ` +
+                                `"${this.dataName}" model.` +
+                                `\nstackLocation: ${this.stackLocation}\n`);
+                        }
+                        /* if (!this.properties[fromKey].vectorizeUseIndex) {
+                          DyFM_Log.error(
+                            `Vectorized from property "${fromKey}" has no vectorizeUseIndex in ` +
+                            `"${this.dataName}" model.` +
+                            `\nstackLocation: ${this.stackLocation}\n`
+                          );
+                        } */
+                        /* if (
+                          (this.properties[fromKey] as DyFM_DataProperty_Params<any>)?.type !== DyFM_BasicProperty_Type.string
+                        ) {
+                          DyFM_Log.error(
+                            `Vectorized from property "${property.vectorizedFrom}" is not a string property in ` +
+                            `"${this.dataName}" model.` +
+                            `\nstackLocation: ${this.stackLocation}\n`
+                          );
+                        } */
+                    });
+                    /* this.properties[property.vectorizedFrom].vectorizeTo ??= key; */
+                    if (property.type !== DyFM_BasicProperty_Type.array) {
+                        DyFM_Log.error(`Vectorized from property "${property.vectorizedFrom}" is not a number[] property in ` +
+                            `"${this.dataName}" model.` +
+                            `\nstackLocation: ${this.stackLocation}\n`);
+                    }
+                    if (property.nonBasicType !== 'number[]') {
+                        DyFM_Log.error(`Vectorized from property "${property.vectorizedFrom}" is not a number[] property in ` +
+                            `"${this.dataName}" model.` +
+                            `\nstackLocation: ${this.stackLocation}\n`);
+                    }
+                    if (!property.vectorizeUseIndex) {
+                        DyFM_Log.error('vectorizeUseIndex is required if vectorizedFrom is set. ' +
+                            `"${this.dataName}" model.` +
+                            `\nstackLocation: ${this.stackLocation}\n`);
+                    }
+                    if (property.index) {
+                        /** {@link DyFM_DataProperty_Params.vectorizeUseIndex} */
+                        DyFM_Log.warn(`index is not recommended to be set for vectorized properties in ` +
+                            `"${this.dataName}" model. ` +
+                            `\n(you should set it in the Atlas and vectorizeUseIndex, ` +
+                            `more info at DyFM_DataProperty_Params.vectorizeUseIndex))` +
+                            `\nstackLocation: ${this.stackLocation}\n`);
+                    }
+                    /* if (!this.properties[property.vectorizeUseIndex]) {
+                      throw new Error(
+                        `vectorizeUseIndex property "${property.vectorizeUseIndex}" is not found in ` +
+                        `"${this.dataName}" model.` +
+                        `\nstackLocation: ${this.stackLocation}\n`
+                      );
+                    }
+            
+                    if (!(this.properties[property.vectorizeUseIndex] as DyFM_DataProperty_Params<any>).index) {
+                      throw new Error(
+                        `vectorizeUseIndex property "${property.vectorizeUseIndex}" is not an ` +
+                        `index property in "${this.dataName}" model.` +
+                        `\nstackLocation: ${this.stackLocation}`
+                      );
+                    } */
+                }
+            });
+            if (!this?.modelType || this?.modelType == DyFM_DataModel_Type.data) {
+                this.modelType = DyFM_DataModel_Type.data;
+            }
+            /* if (!this.dbName && this?.modelType == DyFM_DataModel_Type.data) {
+              // upper case first letter
+              this.dbName = this.dataName.charAt(0).toUpperCase() + this.dataName.slice(1);
+              
+              this.dbName.split('').forEach((char: string, index: number): void => {
+                if (
+                  index > 0 &&
+                  this.dbName[index - 1] === '_' &&
+                  char === char.toUpperCase()
+                ) {
+                  this.dbName = this.dbName.slice(0, index) +
+                                char.toLowerCase() +
+                                this.dbName.slice(index + 1);
+                }
+              });
+            } */
+            if (!this.dataName) {
+                DyFM_Log.error('DyFM_DataModel_Params.constructor: ' +
+                    `dataName is missing in "${this.dataName}" model.` +
+                    `\nstackLocation: ${this.stackLocation}\n`);
+                this.dataName = 'UNNAMED_MODEL';
+            }
+            // check for any Uppercase letters in dbName (not needed cos can be DyNAny_something_like_this)
+            /* if (RegExp(/[A-Z]/).exec(this.dataName)) {
+              DyFM_Log.warn(
+                'DyFM_DataModel_Params.constructor: ' +
+                `dbName should be in snake_case in "${this.dataName}" model.` +
+                'For future compatibility.' +
+                `\nstackLocation: ${this.stackLocation}\n`
+              );
+            } */
+            if (this.dataName.includes('-')) {
+                DyFM_Log.warn('DyFM_DataModel_Params.constructor: ' +
+                    `dataName should be in snake_case in "${this.dataName}" model.` +
+                    'For future compatibility.' +
+                    `\nstackLocation: ${this.stackLocation}\n`);
+            }
+            DyFM_Object.cleanObject(this);
+        }
+        catch (error) {
+            DyFM_Error.logSimple('DyFM_DataModel_Params.constructor error:', error);
+            DyFM_Log.warn('Due to the error, the Params contruction failed, therefore the model is not constructed properly. ' +
+                `("${this.dataName}" model)` +
+                `\nstackLocation: ${this.stackLocation}`);
+            /* DyFM_Log.error(
+              'DyFM_DataModel_Params.constructor: ' +
+              `An error occurred while constructing the "${this.dataName}" model.` +
+              `\nstackLocation: ${this.stackLocation}\n`
+            ); */
+        }
+    }
+    constructed() {
+        return true;
+    }
+    /**
+     * BFR-ORGANIZER-001/002 kísérő (generikus): egy property deklarált default-értéke
+     * (`properties[key].default`) — hogy a defaultok EGYETLEN forrásból (a dataParams-ból)
+     * jöjjenek a fogyasztó create-útjain is (pl. `params.priority ?? dataParams.getDefaultValue('priority')`),
+     * ne duplikálódjanak literálként a service-kódban. `undefined`, ha nincs deklarált default.
+     */
+    getDefaultValue(key) {
+        return this.properties?.[key]?.default;
+    }
+    setKeysForSubObjectParams(property) {
+        if (property.subObjectParams) {
+            Object.keys(property.subObjectParams).forEach((key) => {
+                if (!key) {
+                    DyFM_Log.error('DyFM_DataModel_Params.setKeysForSubObjectParams: ' +
+                        `A subObjectParams key is missing in "${this.dataName}" model.` +
+                        `\nstackLocation: ${this.stackLocation}\n`);
+                }
+                const subObjectPropertyParams = property.subObjectParams[key];
+                subObjectPropertyParams.key = key;
+                const basicType = DyFM_getBasicPropertyType(subObjectPropertyParams.type);
+                if (basicType !== subObjectPropertyParams.type) {
+                    subObjectPropertyParams.nonBasicType = subObjectPropertyParams.type;
+                    subObjectPropertyParams.type = basicType;
+                }
+                if (subObjectPropertyParams.subObjectParams) {
+                    this.setKeysForSubObjectParams(subObjectPropertyParams);
+                }
+            });
+        }
+    }
+}
+/** @deprecated Use DyFM_DataModelParams_ControlModel. Same constructor; no API removal. */
+export { DyFM_DataModelParams_ControlModel as DyFM_DataModel_Params };

package/build-esm/_models/control-models/data-model-settings.control-model.js

@@ -0,0 +1,63 @@
+import { DyFM_Metadata } from '../data-models/metadata.data-model';
+/**
+ * Declarative data-model settings used by the database and service layers.
+ * Historical boolean names remain the serialized keys; their `is...` aliases
+ * expose the current naming contract without rewriting stored configuration.
+ */
+export class DyFM_DataModelSettings_ControlModel extends DyFM_Metadata {
+    static {
+        Object.defineProperty(this, 'name', { value: 'DyFM_DataModel_Settings' });
+    }
+    /** Database table name in snake_case; also used by logs and errors. */
+    dataName;
+    modelType;
+    /** @deprecated Use isArchiveAdded; addArchive remains the serialized compatibility key. */
+    addArchive;
+    /** @deprecated Use isModifyForbidden; forbidModify remains the serialized compatibility key. */
+    forbidModify;
+    /** @deprecated Use isDeleteForbidden; forbidDelete remains the serialized compatibility key. */
+    forbidDelete;
+    /** Declarative automatic-retention settings for the model. */
+    retention;
+    /**
+     * Declarative COMPOUND / PARTIAL indexes installed at startup (FR-BFR-041 / SR-3).
+     *
+     * Use this when the property-level `index` / `unique` flags cannot express the rule — a key that
+     * spans SEVERAL fields, or a uniqueness rule that must apply only where a field EXISTS.
+     */
+    indexes;
+    /** Property declarations used to configure persistence behavior. */
+    properties;
+}
+Object.defineProperty(DyFM_DataModelSettings_ControlModel.prototype, 'isArchiveAdded', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.addArchive;
+    },
+    set: function (isValue) {
+        this.addArchive = isValue;
+    },
+});
+Object.defineProperty(DyFM_DataModelSettings_ControlModel.prototype, 'isModifyForbidden', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.forbidModify;
+    },
+    set: function (isValue) {
+        this.forbidModify = isValue;
+    },
+});
+Object.defineProperty(DyFM_DataModelSettings_ControlModel.prototype, 'isDeleteForbidden', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.forbidDelete;
+    },
+    set: function (isValue) {
+        this.forbidDelete = isValue;
+    },
+});
+/** @deprecated Use DyFM_DataModelSettings_ControlModel. Same constructor; no API removal. */
+export { DyFM_DataModelSettings_ControlModel as DyFM_DataModel_Settings };

package/build-esm/_models/control-models/data-property-params.control-model.js

@@ -0,0 +1,101 @@
+import { DyFM_Log } from '../../_collections/utils/log.util';
+import { DyFM_getConstructionStackLocation } from '../../_collections/utils/stack.util';
+import { DyFM_BasicProperty_Type } from '../../_enums/basic-property-type.enum';
+import { DyFM_DataProperty_Settings } from './data-property-settings.control-model';
+/* export type DyFM_DataPropertySettings<T = any> = DyFM_DataProperty_Settings<T>; */
+/* export type DyFM_DataPropertyParams<T> = DyFM_DataProperty_Params<T>;
+export type DyFM_DPropPs<T> = DyFM_DataProperty_Params<T>; */
+/**
+ * This will be used for setting up db.
+ * DataServices also uses this to prehook tools, as db service and dependency db service.
+ *
+ * @example
+ * ```ts
+ * const params: DyFM_DataProperty_Params<string, any> = new DyFM_DataProperty_Params({
+ *   key: 'name',
+ *   type: DyFM_BasicProperty_Type.string,
+ * });
+ * ```
+ */
+export class DyFM_DataPropertyParams_ControlModel extends DyFM_DataProperty_Settings {
+    static {
+        Object.defineProperty(this, 'name', { value: 'DyFM_DataProperty_Params' });
+    }
+    /* override subObjectParams?: DyFM_DataProperty_Params<>[] = []; */
+    /* override subObjectParams?: DyFM_Data_Params<T> = {}; */
+    additionalValidators = [];
+    constructor(set, parentDataParams) {
+        super();
+        if (set) {
+            if (!set.type && !set.forbidden) {
+                DyFM_Log.error('DYNAMO ERROR: ', `\n type is missing from DynamoNTSDataPropertyParams at "${set.key}" in ` +
+                    `"${parentDataParams?.dataName}" model.` +
+                    `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);
+            }
+            if (set.dependencyDataName) {
+                if (set.required === false) {
+                    DyFM_Log.warn('DYNAMO WARNING: ', `\n required is not recommended to be false if dependency is set at "${set.key}" in ` +
+                        `"${parentDataParams?.dataName}" model.` +
+                        `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);
+                }
+                else if (set.required === undefined) {
+                    DyFM_Log.warn('DYNAMO WARNING: ', `\n required is recommended to be set if dependency is set at "${set.key}" in ` +
+                        `"${parentDataParams?.dataName}" model.` +
+                        `\n   (it is required or it is not a dependency)` +
+                        `\n It will be set to true by while you are not setting it. ` +
+                        `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);
+                    set.required = true;
+                }
+            }
+            if (set.vectorizedFrom) {
+                if (set.index) {
+                    DyFM_Log.warn('DYNAMO WARNING: ', `\n vectorizedFrom and index are not recommended to be set at the same time at "${set.key}" in ` +
+                        `"${parentDataParams?.dataName}" model.` +
+                        `\n It will be set to false by while you are not setting it. ` +
+                        `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);
+                    set.index = false;
+                }
+                if (!set.vectorizeUseIndex) {
+                    DyFM_Log.S_warn('DYNAMO WARNING: ', `\n vectorizeUseIndex is required if vectorizedFrom is set at "${set.key}" in ` +
+                        `"${parentDataParams?.dataName}" model. (It will be set to "${set.key}" by default)` +
+                        `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);
+                    set.vectorizeUseIndex = set.key;
+                }
+            }
+            Object.assign(this, set);
+        }
+        else {
+            DyFM_Log.error('DYNAMO ERROR: ', `\nMISSING DynamoNTSDataPropertyParams constructor input at "${this.key}"!` +
+                `\n stackLocation: ${DyFM_getConstructionStackLocation(2)}`);
+        }
+    }
+    constructed() {
+        return true;
+    }
+    // tslint:disable-next-line: ban-types
+    getBEType() {
+        switch (this.type) {
+            case DyFM_BasicProperty_Type.string:
+                return String;
+            case DyFM_BasicProperty_Type.number:
+                return Number;
+            case DyFM_BasicProperty_Type.boolean:
+                return Boolean;
+            case DyFM_BasicProperty_Type.date:
+                return Date;
+            case DyFM_BasicProperty_Type.object:
+            default:
+                if (this.type?.includes('[]')) {
+                    return Array;
+                }
+                else if (this.type?.includes('=>') || this.type?.includes('function')) {
+                    return Function;
+                }
+                else {
+                    return Object;
+                }
+        }
+    }
+}
+/** @deprecated Use DyFM_DataPropertyParams_ControlModel. Same constructor; no API removal. */
+export { DyFM_DataPropertyParams_ControlModel as DyFM_DataProperty_Params };

package/build-esm/_models/control-models/data-property-settings.control-model.js

@@ -0,0 +1,61 @@
+/** Settings shared by persisted data-property declarations. */
+export class DyFM_DataPropertySettings_ControlModel {
+    static {
+        Object.defineProperty(this, 'name', { value: 'DyFM_DataProperty_Settings' });
+    }
+    key;
+    type;
+    nonBasicType;
+    default;
+    /** @deprecated Use isUnique; unique remains the serialized compatibility key. */
+    unique;
+    /** @deprecated Use isReadonly; readonly remains the serialized compatibility key. */
+    readonly;
+    /** @deprecated Use isRequired; required remains the serialized compatibility key. */
+    required;
+    /** @deprecated Use isIndexed; index remains the serialized compatibility key. */
+    index;
+    /** @deprecated Use isForbidden; forbidden remains the serialized compatibility key. */
+    forbidden;
+    /** @deprecated Use isEncrypted; encrypt remains the serialized compatibility key. */
+    encrypt;
+    dependencyDataName;
+    /** @deprecated Use isArchiveable; archiveable remains the serialized compatibility key. */
+    archiveable;
+    archiveListAfter;
+    vectorizedFrom;
+    embeddingModel;
+    /** @deprecated Use isAlwaysVectorized; vectorizeAlways remains the serialized compatibility key. */
+    vectorizeAlways;
+    vectorizeUseIndex;
+    minlength;
+    maxlength;
+    subObjectParams;
+    additionalValidators;
+}
+const booleanAliases = [
+    ['unique', 'isUnique'],
+    ['readonly', 'isReadonly'],
+    ['required', 'isRequired'],
+    ['index', 'isIndexed'],
+    ['forbidden', 'isForbidden'],
+    ['encrypt', 'isEncrypted'],
+    ['archiveable', 'isArchiveable'],
+    ['vectorizeAlways', 'isAlwaysVectorized'],
+];
+booleanAliases.forEach((booleanAlias) => {
+    const legacyName = booleanAlias[0];
+    const canonicalName = booleanAlias[1];
+    Object.defineProperty(DyFM_DataPropertySettings_ControlModel.prototype, canonicalName, {
+        configurable: true,
+        enumerable: false,
+        get: function () {
+            return this[legacyName];
+        },
+        set: function (isValue) {
+            this[legacyName] = isValue;
+        },
+    });
+});
+/** @deprecated Use DyFM_DataPropertySettings_ControlModel. Same constructor; no API removal. */
+export { DyFM_DataPropertySettings_ControlModel as DyFM_DataProperty_Settings };