@decaf-ts/db-decorators 0.11.0 → 0.13.0

package/lib/types/overrides/Model.d.cts

@@ -0,0 +1,84 @@
+import { Constructor } from "@decaf-ts/decoration";
+import "@decaf-ts/decorator-validation";
+import { ComposedFromMetadata } from "../model/index.cjs";
+import { Context } from "../repository/index.cjs";
+declare module "@decaf-ts/decorator-validation" {
+    interface Model {
+        isTransient(): boolean;
+        segregate<M extends Model<boolean>>(this: M): {
+            model: M;
+            transient?: Record<keyof M, M[keyof M]>;
+        };
+    }
+    namespace Model {
+        /**
+         * @description Retrieves primary key information for a model
+         * @summary Retrieves primary key information or it's value for a model from it's metadata.
+         *
+         * @template model - The model type extending from Model
+         * @param {M | Constructor<M>} model - The model class or it's constructor
+         * @param {boolean} keyValue - Optional keyValue flag, to return the value of the id instead of the property. Does not work with constructor.
+         * @return {any} The property of the id of the model, or it's value
+         *
+         * @example
+         * class User extends Model {
+         *
+         *       const idProp = Model.pk(newModel);
+         *       const id = Model.pk(newModel, true);
+         */
+        function pk<M extends Model<boolean>>(model: M | Constructor<M>): keyof M;
+        function pk<M extends Model<boolean>>(model: M, keyValue: boolean): M[keyof M];
+        function pk<M extends Model<boolean>>(model: M | Constructor<M>, keyValue?: boolean): keyof M | M[keyof M];
+        function pkProps<M extends Model<boolean>>(model: Constructor<M>): any;
+        function isTransient<M extends Model<boolean>>(model: M | Constructor<M>): boolean;
+        /**
+         * @description Separates transient properties from a model
+         * @summary Extracts properties marked as transient into a separate object
+         * @template M - Type extending Model
+         * @param {M} model - The model instance to process
+         * @return {Object} Object containing the model without transient properties and a separate transient object
+         * @property {M} model - The model with transient properties removed
+         * @property {Record<string, any>} [transient] - Object containing the transient properties
+         * @function segregate
+         * @mermaid
+         * sequenceDiagram
+         *   participant Caller
+         *   participant modelToTransient
+         *   participant isTransient
+         *   participant Metadata.validatableProperties
+         *
+         *   Caller->>modelToTransient: model
+         *   modelToTransient->>isTransient: check if model is transient
+         *   isTransient-->>modelToTransient: transient status
+         *   alt model is not transient
+         *     modelToTransient-->>Caller: {model}
+         *   else model is transient
+         *     modelToTransient->>Metadata.validatableProperties: get decorated properties, combine with model props
+         *     modelToTransient->>get transient properties from Metadata
+         *     modelToTransient->>modelToTransient: separate properties
+         *     modelToTransient->>Model.build: rebuild model without transient props
+         *     modelToTransient-->>Caller: {model, transient}
+         *   end
+         */
+        function segregate<M extends Model<boolean>>(model: M): {
+            model: M;
+            transient?: Record<keyof M, M[keyof M]>;
+        };
+        /**
+         * @description Merges two model instances into a new instance.
+         * @summary Creates a new model instance by combining properties from an old model and a new model.
+         * Properties from the new model override properties from the old model if they are defined.
+         * @param {M} oldModel - The original model instance
+         * @param {M} model - The new model instance with updated properties
+         * @return {M} A new model instance with merged properties
+         */
+        function merge<M extends Model<boolean>>(oldModel: M, newModel: M, constructor?: Constructor<M>): M;
+        function composed<M extends Model<boolean>>(model: Constructor<M>): boolean;
+        function composed<M extends Model<boolean>>(model: Constructor<M> | M, prop: keyof M): ComposedFromMetadata | undefined;
+        function composed<M extends Model<boolean>>(model: Constructor<M> | M, prop?: keyof M): boolean | ComposedFromMetadata | undefined;
+        function generated<M extends Model>(model: M | Constructor<M>, prop: keyof M): boolean | string;
+        function shouldGenerate<M extends Model>(model: M, prop: keyof M, ctx: Context<any>): boolean;
+        function versionProp<M extends Model<boolean>>(model: M): keyof M;
+        function versionOf<M extends Model<boolean>>(model: M): number;
+    }
+}

package/lib/types/overrides/Model.d.mts

@@ -0,0 +1,84 @@
+import { Constructor } from "@decaf-ts/decoration";
+import "@decaf-ts/decorator-validation";
+import { ComposedFromMetadata } from "../model/index.js";
+import { Context } from "../repository/index.js";
+declare module "@decaf-ts/decorator-validation" {
+    interface Model {
+        isTransient(): boolean;
+        segregate<M extends Model<boolean>>(this: M): {
+            model: M;
+            transient?: Record<keyof M, M[keyof M]>;
+        };
+    }
+    namespace Model {
+        /**
+         * @description Retrieves primary key information for a model
+         * @summary Retrieves primary key information or it's value for a model from it's metadata.
+         *
+         * @template model - The model type extending from Model
+         * @param {M | Constructor<M>} model - The model class or it's constructor
+         * @param {boolean} keyValue - Optional keyValue flag, to return the value of the id instead of the property. Does not work with constructor.
+         * @return {any} The property of the id of the model, or it's value
+         *
+         * @example
+         * class User extends Model {
+         *
+         *       const idProp = Model.pk(newModel);
+         *       const id = Model.pk(newModel, true);
+         */
+        function pk<M extends Model<boolean>>(model: M | Constructor<M>): keyof M;
+        function pk<M extends Model<boolean>>(model: M, keyValue: boolean): M[keyof M];
+        function pk<M extends Model<boolean>>(model: M | Constructor<M>, keyValue?: boolean): keyof M | M[keyof M];
+        function pkProps<M extends Model<boolean>>(model: Constructor<M>): any;
+        function isTransient<M extends Model<boolean>>(model: M | Constructor<M>): boolean;
+        /**
+         * @description Separates transient properties from a model
+         * @summary Extracts properties marked as transient into a separate object
+         * @template M - Type extending Model
+         * @param {M} model - The model instance to process
+         * @return {Object} Object containing the model without transient properties and a separate transient object
+         * @property {M} model - The model with transient properties removed
+         * @property {Record<string, any>} [transient] - Object containing the transient properties
+         * @function segregate
+         * @mermaid
+         * sequenceDiagram
+         *   participant Caller
+         *   participant modelToTransient
+         *   participant isTransient
+         *   participant Metadata.validatableProperties
+         *
+         *   Caller->>modelToTransient: model
+         *   modelToTransient->>isTransient: check if model is transient
+         *   isTransient-->>modelToTransient: transient status
+         *   alt model is not transient
+         *     modelToTransient-->>Caller: {model}
+         *   else model is transient
+         *     modelToTransient->>Metadata.validatableProperties: get decorated properties, combine with model props
+         *     modelToTransient->>get transient properties from Metadata
+         *     modelToTransient->>modelToTransient: separate properties
+         *     modelToTransient->>Model.build: rebuild model without transient props
+         *     modelToTransient-->>Caller: {model, transient}
+         *   end
+         */
+        function segregate<M extends Model<boolean>>(model: M): {
+            model: M;
+            transient?: Record<keyof M, M[keyof M]>;
+        };
+        /**
+         * @description Merges two model instances into a new instance.
+         * @summary Creates a new model instance by combining properties from an old model and a new model.
+         * Properties from the new model override properties from the old model if they are defined.
+         * @param {M} oldModel - The original model instance
+         * @param {M} model - The new model instance with updated properties
+         * @return {M} A new model instance with merged properties
+         */
+        function merge<M extends Model<boolean>>(oldModel: M, newModel: M, constructor?: Constructor<M>): M;
+        function composed<M extends Model<boolean>>(model: Constructor<M>): boolean;
+        function composed<M extends Model<boolean>>(model: Constructor<M> | M, prop: keyof M): ComposedFromMetadata | undefined;
+        function composed<M extends Model<boolean>>(model: Constructor<M> | M, prop?: keyof M): boolean | ComposedFromMetadata | undefined;
+        function generated<M extends Model>(model: M | Constructor<M>, prop: keyof M): boolean | string;
+        function shouldGenerate<M extends Model>(model: M, prop: keyof M, ctx: Context<any>): boolean;
+        function versionProp<M extends Model<boolean>>(model: M): keyof M;
+        function versionOf<M extends Model<boolean>>(model: M): number;
+    }
+}

package/lib/types/overrides/ModelBuilderExtensions.d.cts

@@ -0,0 +1,15 @@
+import "@decaf-ts/decorator-validation";
+declare module "@decaf-ts/decorator-validation" {
+    interface ModelBuilder<M> {
+        generated<N extends keyof M>(attr: N, type?: string): ModelBuilder<M>;
+        hash<N extends keyof M>(attr: N): ModelBuilder<M>;
+        composedFromKeys<N extends keyof M>(attr: N, args: string[], separator?: string, filterEmpty?: boolean | string[], hash?: boolean, prefix?: string, suffix?: string, groupsort?: {
+            priority: number;
+        }): ModelBuilder<M>;
+        composed<N extends keyof M>(attr: N, args: string[], separator?: string, filterEmpty?: boolean | string[], hash?: boolean, prefix?: string, suffix?: string, groupsort?: {
+            priority: number;
+        }): ModelBuilder<M>;
+        version<N extends keyof M>(attr: N): ModelBuilder<M>;
+        transient<N extends keyof M>(attr: N): ModelBuilder<M>;
+    }
+}

package/lib/types/overrides/ModelBuilderExtensions.d.mts

@@ -0,0 +1,15 @@
+import "@decaf-ts/decorator-validation";
+declare module "@decaf-ts/decorator-validation" {
+    interface ModelBuilder<M> {
+        generated<N extends keyof M>(attr: N, type?: string): ModelBuilder<M>;
+        hash<N extends keyof M>(attr: N): ModelBuilder<M>;
+        composedFromKeys<N extends keyof M>(attr: N, args: string[], separator?: string, filterEmpty?: boolean | string[], hash?: boolean, prefix?: string, suffix?: string, groupsort?: {
+            priority: number;
+        }): ModelBuilder<M>;
+        composed<N extends keyof M>(attr: N, args: string[], separator?: string, filterEmpty?: boolean | string[], hash?: boolean, prefix?: string, suffix?: string, groupsort?: {
+            priority: number;
+        }): ModelBuilder<M>;
+        version<N extends keyof M>(attr: N): ModelBuilder<M>;
+        transient<N extends keyof M>(attr: N): ModelBuilder<M>;
+    }
+}

package/lib/types/overrides/index.d.cts

@@ -0,0 +1,10 @@
+/**
+ * @description Exports for the overrides module.
+ * @summary This file exports all the necessary components for the overrides functionality, including Model, overrides, and Metadata.
+ * @module db-decorators/overrides
+ */
+import "./overrides";
+export * from "./Model.cjs";
+export * from "./overrides.cjs";
+export * from "./Metadata.cjs";
+export * from "./ModelBuilderExtensions.cjs";

package/lib/types/overrides/index.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @description Exports for the overrides module.
+ * @summary This file exports all the necessary components for the overrides functionality, including Model, overrides, and Metadata.
+ * @module db-decorators/overrides
+ */
+import "./overrides";
+export * from "./Model.js";
+export * from "./overrides.js";
+export * from "./Metadata.js";
+export * from "./ModelBuilderExtensions.js";

package/lib/types/overrides/overrides.d.cts

@@ -0,0 +1 @@
+export {};

package/lib/types/overrides/overrides.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/repository/Context.d.cts

@@ -0,0 +1,112 @@
+import { ContextArgs } from "./utils.cjs";
+import { Contextual, FlagsOf } from "../interfaces/Contextual.cjs";
+import { OperationKeys } from "../operations/constants.cjs";
+import { Model } from "@decaf-ts/decorator-validation";
+import { ObjectAccumulator } from "typed-object-accumulator";
+import { ContextFlags, FlagsOfContext, LoggerOfFlags, RepositoryFlags } from "./types.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Factory type for creating context instances.
+ * @summary Defines a function type that creates context instances with specific repository flags.
+ * @template F - The repository flags type extending RepositoryFlags
+ * @typedef {Function} ContextFactory
+ * @memberOf module:db-decorators
+ */
+export type ContextFactory<C extends Context<any>> = (arg: Partial<Omit<FlagsOf<C>, "timestamp">>) => C;
+/**
+ * @description Default factory for creating context instances.
+ * @summary A factory function that creates new Context instances with the provided repository flags.
+ * It automatically adds a timestamp to the context and returns a properly typed context instance.
+ * @const DefaultContextFactory
+ * @memberOf module:db-decorators
+ */
+export declare const DefaultContextFactory: ContextFactory<any>;
+/**
+ * @description A context management class for handling repository operations.
+ * @summary The Context class provides a mechanism for managing repository operations with flags,
+ * parent-child relationships, and state accumulation. It allows for hierarchical context chains
+ * and maintains operation-specific configurations while supporting type safety through generics.
+ *
+ * @template F - Type extending RepositoryFlags that defines the context configuration
+ *
+ * @param {ObjectAccumulator<F>} cache - The internal cache storing accumulated values
+ *
+ * @class
+ *
+ * @example
+ * ```typescript
+ * // Creating a new context with repository flags
+ * const context = new Context<RepositoryFlags>();
+ *
+ * // Accumulating values
+ * const enrichedContext = context.accumulate({
+ *   writeOperation: true,
+ *   affectedTables: ['users'],
+ *   operation: OperationKeys.CREATE
+ * });
+ *
+ * // Accessing values
+ * const isWrite = enrichedContext.get('writeOperation'); // true
+ * const tables = enrichedContext.get('affectedTables'); // ['users']
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant Ctx as Context
+ *   participant Cache as ObjectAccumulator
+ *
+ *   C->>Ctx: new Context()
+ *   Ctx->>Cache: create cache
+ *
+ *   C->>Ctx: accumulate(value)
+ *   Ctx->>Cache: accumulate(value)
+ *   Cache-->>Ctx: updated cache
+ *   Ctx-->>C: updated context
+ *
+ *   C->>Ctx: get(key)
+ *   Ctx->>Cache: get(key)
+ *   alt Key exists in cache
+ *     Cache-->>Ctx: value
+ *   else Key not found
+ *     Ctx->>Ctx: check parent context
+ *     alt Parent exists
+ *       Ctx->>Parent: get(key)
+ *       Parent-->>Ctx: value
+ *     else No parent
+ *       Ctx-->>C: throw error
+ *     end
+ *   end
+ *   Ctx-->>C: requested value
+ */
+export declare class Context<F extends ContextFlags<any> = RepositoryFlags<any>> {
+    constructor(ctx?: Context<F>);
+    static factory: ContextFactory<any>;
+    readonly cache: RepositoryFlags<any> & ObjectAccumulator<any>;
+    /**
+     * @description Accumulates new values into the context.
+     * @summary Merges the provided value object with the existing context state,
+     * creating a new immutable cache state.
+     */
+    accumulate<V extends object>(value: V): Context<F & V>;
+    get logger(): LoggerOfFlags<F>;
+    get timestamp(): F["timestamp"];
+    /**
+     * @description Retrieves a value from the context by key.
+     * @param {string} key
+     * @return {any}
+     */
+    get<K extends keyof F>(key: K): F[K];
+    /**
+     * @description Creates a child context from another context
+     */
+    static childFrom<C extends Context<any>>(context: C, overrides?: Partial<FlagsOf<C>>): C;
+    /**
+     * @description Creates a new context from operation parameters
+     */
+    static from<M extends Model, C extends Context<any>>(operation: OperationKeys.CREATE | OperationKeys.READ | OperationKeys.UPDATE | OperationKeys.DELETE | string, overrides: Partial<FlagsOfContext<C>>, model: Constructor<M>, ...args: any[]): Promise<C>;
+    /**
+     * @description Prepares arguments for context operations
+     */
+    static args<M extends Model<any>, C extends Context<any>>(operation: OperationKeys.CREATE | OperationKeys.READ | OperationKeys.UPDATE | OperationKeys.DELETE | string, model: Constructor<M>, args: any[], contextual?: Contextual<C>, overrides?: Partial<FlagsOf<C>>): Promise<ContextArgs<C>>;
+}

package/lib/types/repository/Context.d.mts

@@ -0,0 +1,112 @@
+import { ContextArgs } from "./utils.js";
+import { Contextual, FlagsOf } from "../interfaces/Contextual.js";
+import { OperationKeys } from "../operations/constants.js";
+import { Model } from "@decaf-ts/decorator-validation";
+import { ObjectAccumulator } from "typed-object-accumulator";
+import { ContextFlags, FlagsOfContext, LoggerOfFlags, RepositoryFlags } from "./types.js";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Factory type for creating context instances.
+ * @summary Defines a function type that creates context instances with specific repository flags.
+ * @template F - The repository flags type extending RepositoryFlags
+ * @typedef {Function} ContextFactory
+ * @memberOf module:db-decorators
+ */
+export type ContextFactory<C extends Context<any>> = (arg: Partial<Omit<FlagsOf<C>, "timestamp">>) => C;
+/**
+ * @description Default factory for creating context instances.
+ * @summary A factory function that creates new Context instances with the provided repository flags.
+ * It automatically adds a timestamp to the context and returns a properly typed context instance.
+ * @const DefaultContextFactory
+ * @memberOf module:db-decorators
+ */
+export declare const DefaultContextFactory: ContextFactory<any>;
+/**
+ * @description A context management class for handling repository operations.
+ * @summary The Context class provides a mechanism for managing repository operations with flags,
+ * parent-child relationships, and state accumulation. It allows for hierarchical context chains
+ * and maintains operation-specific configurations while supporting type safety through generics.
+ *
+ * @template F - Type extending RepositoryFlags that defines the context configuration
+ *
+ * @param {ObjectAccumulator<F>} cache - The internal cache storing accumulated values
+ *
+ * @class
+ *
+ * @example
+ * ```typescript
+ * // Creating a new context with repository flags
+ * const context = new Context<RepositoryFlags>();
+ *
+ * // Accumulating values
+ * const enrichedContext = context.accumulate({
+ *   writeOperation: true,
+ *   affectedTables: ['users'],
+ *   operation: OperationKeys.CREATE
+ * });
+ *
+ * // Accessing values
+ * const isWrite = enrichedContext.get('writeOperation'); // true
+ * const tables = enrichedContext.get('affectedTables'); // ['users']
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client
+ *   participant Ctx as Context
+ *   participant Cache as ObjectAccumulator
+ *
+ *   C->>Ctx: new Context()
+ *   Ctx->>Cache: create cache
+ *
+ *   C->>Ctx: accumulate(value)
+ *   Ctx->>Cache: accumulate(value)
+ *   Cache-->>Ctx: updated cache
+ *   Ctx-->>C: updated context
+ *
+ *   C->>Ctx: get(key)
+ *   Ctx->>Cache: get(key)
+ *   alt Key exists in cache
+ *     Cache-->>Ctx: value
+ *   else Key not found
+ *     Ctx->>Ctx: check parent context
+ *     alt Parent exists
+ *       Ctx->>Parent: get(key)
+ *       Parent-->>Ctx: value
+ *     else No parent
+ *       Ctx-->>C: throw error
+ *     end
+ *   end
+ *   Ctx-->>C: requested value
+ */
+export declare class Context<F extends ContextFlags<any> = RepositoryFlags<any>> {
+    constructor(ctx?: Context<F>);
+    static factory: ContextFactory<any>;
+    readonly cache: RepositoryFlags<any> & ObjectAccumulator<any>;
+    /**
+     * @description Accumulates new values into the context.
+     * @summary Merges the provided value object with the existing context state,
+     * creating a new immutable cache state.
+     */
+    accumulate<V extends object>(value: V): Context<F & V>;
+    get logger(): LoggerOfFlags<F>;
+    get timestamp(): F["timestamp"];
+    /**
+     * @description Retrieves a value from the context by key.
+     * @param {string} key
+     * @return {any}
+     */
+    get<K extends keyof F>(key: K): F[K];
+    /**
+     * @description Creates a child context from another context
+     */
+    static childFrom<C extends Context<any>>(context: C, overrides?: Partial<FlagsOf<C>>): C;
+    /**
+     * @description Creates a new context from operation parameters
+     */
+    static from<M extends Model, C extends Context<any>>(operation: OperationKeys.CREATE | OperationKeys.READ | OperationKeys.UPDATE | OperationKeys.DELETE | string, overrides: Partial<FlagsOfContext<C>>, model: Constructor<M>, ...args: any[]): Promise<C>;
+    /**
+     * @description Prepares arguments for context operations
+     */
+    static args<M extends Model<any>, C extends Context<any>>(operation: OperationKeys.CREATE | OperationKeys.READ | OperationKeys.UPDATE | OperationKeys.DELETE | string, model: Constructor<M>, args: any[], contextual?: Contextual<C>, overrides?: Partial<FlagsOf<C>>): Promise<ContextArgs<C>>;
+}