@decaf-ts/db-decorators/lib/esm/repository/Context.d.ts

Agnostic database decorators and repository

import { ContextArgs } from "./utils";
import { Contextual, FlagsOf } from "../interfaces/Contextual";
import { OperationKeys } from "../operations/constants";
import { Model } from "@decaf-ts/decorator-validation";
import { ObjectAccumulator } from "typed-object-accumulator";
import { ContextFlags, FlagsOfContext, LoggerOfFlags, RepositoryFlags } from "./types";
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>>;
}