@decaf-ts/db-decorators/lib/esm/model/decorators.js

Agnostic database decorators and repository

import { DBKeys, DefaultSeparator } from "./constants.js";
import { apply } from "@decaf-ts/reflection";
import { Decoration, Hashing, propMetadata, type, } from "@decaf-ts/decorator-validation";
import { onCreate, onCreateUpdate, onUpdate } from "./../operations/decorators.js";
import { InternalError } from "./../repository/errors.js";
import { Repository } from "./../repository/Repository.js";
import { OperationKeys } from "./../operations/index.js";
/**
 * @description Hashes a property value during create or update operations
 * @summary Callback function used by the hash decorator to apply hashing to a property value
 * @template M - Type extending Model
 * @template R - Type extending IRepository
 * @template V - Type for metadata
 * @template F - Type extending RepositoryFlags
 * @template C - Type extending Context
 * @param {C} context - The operation context
 * @param {V} data - Metadata for the operation
 * @param key - The property key to hash
 * @param {M} model - The model being processed
 * @param {M} [oldModel] - The previous model state (for updates)
 * @return {void}
 * @function hashOnCreateUpdate
 * @memberOf module:db-decorators
 */
export function hashOnCreateUpdate(context, data, key, model, oldModel) {
    if (typeof model[key] === "undefined")
        return;
    const hash = Hashing.hash(model[key]);
    if (oldModel && model[key] === hash)
        return;
    model[key] = hash;
}
/**
 * @description Creates a decorator that hashes a property value
 * @summary Decorator that automatically hashes a property value during create and update operations
 * @return {PropertyDecorator} A decorator that can be applied to class properties
 * @function hash
 * @category Property Decorators
 */
export function hash() {
    return apply(onCreateUpdate(hashOnCreateUpdate), propMetadata(Repository.key(DBKeys.HASH), {}));
}
/**
 * @description Composes a property value from other properties during create or update operations
 * @summary Callback function used by composed decorators to generate a property value from other properties
 * @template M - Type extending Model
 * @template R - Type extending IRepository
 * @template V - Type extending ComposedFromMetadata
 * @template F - Type extending RepositoryFlags
 * @template C - Type extending Context
 * @param {C} context - The operation context
 * @param {V} data - Metadata for the composition
 * @param key - The property key to set the composed value on
 * @param {M} model - The model being processed
 * @return {void}
 * @function composedFromCreateUpdate
 * @memberOf module:db-decorators
 */
export function composedFromCreateUpdate(context, data, key, model) {
    try {
        const { args, type, prefix, suffix, separator } = data;
        const composed = args.map((arg) => {
            if (!(arg in model))
                throw new InternalError(`Property ${arg} not found to compose from`);
            if (type === "keys")
                return arg;
            if (typeof model[arg] === "undefined")
                throw new InternalError(`Property ${args} does not contain a value to compose from`);
            return model[arg].toString();
        });
        if (prefix)
            composed.unshift(prefix);
        if (suffix)
            composed.push(suffix);
        model[key] = composed.join(separator);
    }
    catch (e) {
        throw new InternalError(`Failed to compose value: ${e}`);
    }
}
/**
 * @description Creates a decorator that composes a property value from other properties
 * @summary Base function for creating property composition decorators
 * @param {string[]} args - Property names to compose from
 * @param {boolean} [hashResult=false] - Whether to hash the composed result
 * @param {string} [separator=DefaultSeparator] - Character used to join the composed values
 * @param {"keys"|"values"} [type="values"] - Whether to use property keys or values
 * @param {string} [prefix=""] - Optional prefix to add to the composed value
 * @param {string} [suffix=""] - Optional suffix to add to the composed value
 * @param {GroupSort} groupsort - GroupSort configuration
 * @return {PropertyDecorator} A decorator that can be applied to class properties
 * @function composedFrom
 * @category PropertyDecorators
 */
function composedFrom(args, hashResult = false, separator = DefaultSeparator, type = "values", prefix = "", suffix = "", groupsort = { priority: 55 }) {
    const data = {
        args: args,
        hashResult: hashResult,
        separator: separator,
        type: type,
        prefix: prefix,
        suffix: suffix,
    };
    const decorators = [
        onCreateUpdate(composedFromCreateUpdate, data, groupsort),
        propMetadata(Repository.key(DBKeys.COMPOSED), data),
    ];
    if (hashResult)
        decorators.push(hash());
    return apply(...decorators);
}
/**
 * @description Creates a decorator that composes a property value from property keys
 * @summary Decorator that generates a property value by joining the names of other properties
 * @param {string[]} args - Property names to compose from
 * @param {string} [separator=DefaultSeparator] - Character used to join the property names
 * @param {boolean} [hash=false] - Whether to hash the composed result
 * @param {string} [prefix=""] - Optional prefix to add to the composed value
 * @param {string} [suffix=""] - Optional suffix to add to the composed value
 * @param {GroupSort} groupsort - GroupSort configuration
 * @return {PropertyDecorator} A decorator that can be applied to class properties
 * @function composedFromKeys
 * @category PropertyDecorators
 */
export function composedFromKeys(args, separator = DefaultSeparator, hash = false, prefix = "", suffix = "", groupsort = { priority: 55 }) {
    return composedFrom(args, hash, separator, "keys", prefix, suffix, groupsort);
}
/**
 * @description Creates a decorator that composes a property value from property values
 * @summary Decorator that generates a property value by joining the values of other properties
 * @param {string[]} args - Property names whose values will be composed
 * @param {string} [separator=DefaultSeparator] - Character used to join the property values
 * @param {boolean} [hash=false] - Whether to hash the composed result
 * @param {string} [prefix=""] - Optional prefix to add to the composed value
 * @param {string} [suffix=""] - Optional suffix to add to the composed value
 * @param {GroupSort} groupsort - GroupSort configuration
 * @return {PropertyDecorator} A decorator that can be applied to class properties
 * @function composed
 * @category PropertyDecorators
 */
export function composed(args, separator = DefaultSeparator, hash = false, prefix = "", suffix = "", groupsort = { priority: 55 }) {
    return composedFrom(args, hash, separator, "values", prefix, suffix, groupsort);
}
/**
 * @description Creates a function that updates a version property during operations
 * @summary Factory function that generates a callback for incrementing version numbers
 * @param {CrudOperations} operation - The type of operation (CREATE or UPDATE)
 * @return {Function} A callback function that updates the version property
 * @template M - Type extending Model
 * @template R - Type extending IRepository
 * @template V - Type for metadata
 * @template F - Type extending RepositoryFlags
 * @template C - Type extending Context
 * @function versionCreateUpdate
 * @memberOf module:db-decorators
 * @mermaid
 * sequenceDiagram
 *   participant Caller
 *   participant versionCreateUpdate
 *
 *   Caller->>versionCreateUpdate: operation
 *   versionCreateUpdate-->>Caller: callback function
 *   Note over Caller,versionCreateUpdate: When callback is executed:
 *   Caller->>versionCreateUpdate: context, data, key, model
 *   alt operation is CREATE
 *     versionCreateUpdate->>versionCreateUpdate: set version to 1
 *   else operation is UPDATE
 *     versionCreateUpdate->>versionCreateUpdate: increment version
 *   else invalid operation
 *     versionCreateUpdate->>versionCreateUpdate: throw error
 *   end
 *   versionCreateUpdate-->>Caller: void
 */
export function versionCreateUpdate(operation) {
    return function versionCreateUpdate(context, data, key, model) {
        try {
            switch (operation) {
                case OperationKeys.CREATE:
                    model[key] = 1;
                    break;
                case OperationKeys.UPDATE:
                    model[key]++;
                    break;
                default:
                    throw new InternalError(`Invalid operation: ${operation}`);
            }
        }
        catch (e) {
            throw new InternalError(`Failed to update version: ${e}`);
        }
    };
}
/**
 * @description Creates a decorator for versioning a property in a model
 * @summary This decorator applies multiple sub-decorators to handle version management during create and update operations
 * @return {PropertyDecorator} A composite decorator that sets the type to Number, manages version updates, and adds versioning metadata
 * @function version
 * @category PropertyDecorators
 */
export function version() {
    const key = Repository.key(DBKeys.VERSION);
    return Decoration.for(key)
        .define(type(Number.name), onCreate(versionCreateUpdate(OperationKeys.CREATE)), onUpdate(versionCreateUpdate(OperationKeys.UPDATE)), propMetadata(key, true))
        .apply();
}
/**
 * @description Creates a decorator that marks a property as transient
 * @summary Decorator that indicates a property should not be persisted to the database
 * @return {PropertyDecorator} A decorator that can be applied to class properties
 * @function transient
 * @category PropertyDecorators
 */
export function transient() {
    const key = Repository.key(DBKeys.TRANSIENT);
    return Decoration.for(key)
        .define(function transient(model, attribute) {
        propMetadata(Repository.key(DBKeys.TRANSIENT), true)(model, attribute);
        propMetadata(Repository.key(DBKeys.TRANSIENT), true)(model.constructor);
    })
        .apply();
}
//# sourceMappingURL=decorators.js.map