@decaf-ts/core 0.18.0 → 0.19.0

package/lib/types/persistence/Sequence.d.mts

@@ -0,0 +1,126 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import { SequenceOptions, SequenceOptionsType } from "../interfaces/SequenceOptions.js";
+import { Constructor } from "@decaf-ts/decoration";
+import { ContextualizedArgs, ContextualLoggedClass, MaybeContextualArg, MethodOrOperation } from "../utils/ContextualLoggedClass.js";
+import { Adapter } from "./Adapter.js";
+import { Repo } from "../repository/Repository.js";
+import { SequenceModel } from "../model/SequenceModel.js";
+import { Context } from "./Context.js";
+import { MultiLock } from "@decaf-ts/transactional-decorators";
+import type { ContextOf, FlagsOf } from "./types.js";
+/**
+ * @description Abstract base class for sequence generation
+ * @summary Provides a framework for generating sequential values (like primary keys) in the persistence layer.
+ * Implementations of this class handle the specifics of how sequences are stored and incremented in different
+ * database systems.
+ * @param {SequenceOptions} options - Configuration options for the sequence generator
+ * @class Sequence
+ * @example
+ * ```typescript
+ * // Example implementation for a specific database
+ * class PostgresSequence extends Sequence {
+ *   constructor(options: SequenceOptions) {
+ *     super(options);
+ *   }
+ *
+ *   async next(): Promise<number> {
+ *     // Implementation to get next value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT nextval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].nextval);
+ *   }
+ *
+ *   async current(): Promise<number> {
+ *     // Implementation to get current value from PostgreSQL sequence
+ *     const result = await this.options.executor.raw(`SELECT currval('${this.options.name}')`);
+ *     return parseInt(result.rows[0].currval);
+ *   }
+ *
+ *   async range(count: number): Promise<number[]> {
+ *     // Implementation to get a range of values
+ *     const values: number[] = [];
+ *     for (let i = 0; i < count; i++) {
+ *       values.push(await this.next());
+ *     }
+ *     return values;
+ *   }
+ * }
+ *
+ * // Usage
+ * const sequence = new PostgresSequence({
+ *   name: 'user_id_seq',
+ *   executor: dbExecutor
+ * });
+ *
+ * const nextId = await sequence.next();
+ * ```
+ */
+export declare class Sequence<A extends Adapter<any, any, any, any> = Adapter<any, any, any, any>> extends ContextualLoggedClass<any> {
+    protected readonly options: SequenceOptions;
+    protected readonly adapter: A;
+    protected repo: Repo<SequenceModel>;
+    protected static readonly lock: MultiLock;
+    /**
+     * @description Creates a new sequence instance
+     * @summary Protected constructor that initializes the sequence with the provided options
+     */
+    constructor(options: SequenceOptions, adapter: A, overrides?: Partial<FlagsOf<A>>);
+    /**
+     * @description Retrieves the current value of the sequence
+     * @summary Gets the current value of the sequence from storage. If the sequence
+     * doesn't exist yet, it returns the configured starting value.
+     * @return A promise that resolves to the current sequence value
+     */
+    current(...args: MaybeContextualArg<any>): Promise<string | number | bigint>;
+    /**
+     * @description Increments the sequence value
+     * @summary Increases the current sequence value by the specified amount and persists
+     * the new value to storage. This method handles both numeric and BigInt sequence types.
+     * @param {string | number | bigint} current - The current value of the sequence
+     * @param {number} [count] - Optional amount to increment by, defaults to the sequence's incrementBy value
+     * @return A promise that resolves to the new sequence value after incrementing
+     */
+    protected increment(count: number | undefined, context: Context<any>): Promise<string | number | bigint>;
+    /**
+     * @description Gets the next value in the sequence
+     * @summary Retrieves the current value of the sequence and increments it by the
+     * configured increment amount. This is the main method used to get a new sequential value.
+     * @return A promise that resolves to the next value in the sequence
+     */
+    next(...argz: MaybeContextualArg<any>): Promise<number | string | bigint>;
+    /**
+     * @description Generates a range of sequential values
+     * @summary Retrieves a specified number of sequential values from the sequence.
+     * This is useful when you need to allocate multiple IDs at once.
+     * The method increments the sequence by the total amount needed and returns all values in the range.
+     * @param {number} count - The number of sequential values to generate
+     * @return A promise that resolves to an array of sequential values
+     */
+    range(count: number, ...argz: MaybeContextualArg<any>): Promise<(number | string | bigint)[]>;
+    /**
+     * @description Ensures the sequence exists and is at least a given value
+     * @summary Upserts the sequence record to the provided value when missing, and optionally only when the
+     * provided value is greater than the persisted one. This is used by decorators that want to "seed" a
+     * sequence based on an existing model value (for example when overriding/bootstrapping sequences).
+     */
+    ensureAtLeast(value: string | number | bigint, ...argz: MaybeContextualArg<any>): Promise<string | number | bigint>;
+    protected parse(value: string | number | bigint): string | number | bigint;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<typeof this.adapter>, ARGS>, operation: METHOD): ContextualizedArgs<ContextOf<typeof this.adapter>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<typeof this.adapter>, ARGS>, operation: METHOD, allowCreate: false): ContextualizedArgs<ContextOf<typeof this.adapter>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<typeof this.adapter>, ARGS>, operation: METHOD, allowCreate: true): Promise<ContextualizedArgs<ContextOf<typeof this.adapter>, ARGS, METHOD extends string ? true : false>>;
+    /**
+     * @description Gets the primary key sequence name for a model
+     * @summary Utility method that returns the standardized sequence name for a model's primary key
+     * @template M - The model type
+     * @param {M|Constructor<M>} model - The model instance or constructor
+     * @return {string} The sequence name for the model's primary key
+     */
+    static pk<M extends Model>(model: M | Constructor<M>): string;
+    /**
+     * @description Parses a sequence value to the appropriate type
+     * @summary Converts a sequence value to the specified type (Number or BigInt)
+     * @param {"Number"|"BigInt"|undefined} type - The target type to convert to
+     * @param {string|number|bigint} value - The value to convert
+     * @return {string|number|bigint} The converted value
+     */
+    static parseValue(type: SequenceOptionsType, value: string | number | bigint): string | number | bigint;
+}

package/lib/types/persistence/constants.d.cts

@@ -0,0 +1,74 @@
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { AdapterFlags, ContextFlags } from "./types.cjs";
+import { PreparedStatementKeys } from "../query/constants.cjs";
+/**
+ * @description Persistence-related constant keys
+ * @summary Enum containing string constants used throughout the persistence layer for metadata, relations, and other persistence-related operations
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
+export declare enum PersistenceKeys {
+    PERSISTENCE = "persistence",
+    /** @description Key for index metadata */
+    INDEX = "index",
+    /** @description Key for sequence metadata */
+    SEQUENCE = "sequence",
+    /** @description Key for unique constraint metadata */
+    UNIQUE = "unique",
+    /** @description Key for adapter metadata */
+    ADAPTER = "adapter",
+    /** @description Template for injectable adapter names */
+    INJECTABLE = "decaf_{0}_adapter_for_{1}",
+    SERVICE = "service",
+    /** @description Key for table name metadata */
+    TABLE = "table",
+    /** @description Key for column name metadata */
+    COLUMN = "column",
+    /** @description Key for general metadata storage */
+    METADATA = "__metadata",
+    /** @description Key for created-by ownership metadata */
+    OWNERSHIP = "ownership",
+    /** @description Key for created-by ownership metadata */
+    CREATED_BY = "ownership.created-by",
+    /** @description Key for updated-by ownership metadata */
+    UPDATED_BY = "ownership.updated-by",
+    /** @description Key for relations metadata storage */
+    RELATIONS = "__relations",
+    /** @description Key for relations metadata storage */
+    RELATION = "relation",
+    /** @description Key for one-to-one relation metadata */
+    ONE_TO_ONE = "relation.one-to-one",
+    /** @description Key for one-to-many relation metadata */
+    ONE_TO_MANY = "relation.one-to-many",
+    /** @description Key for many-to-one relation metadata */
+    MANY_TO_ONE = "relation.many-to-one",
+    /** @description Key for many-to-one relation metadata */
+    MANY_TO_MANY = "relation.many-to-many",
+    /** @description Key for populate metadata */
+    POPULATE = "populate",
+    /** @description Key for populate metadata */
+    NO_VALIDATE = "no-validate",
+    /** @description Key for migration classes */
+    MIGRATION = "migration",
+    STATEMENT = "statement",
+    QUERY = "query",
+    UUID = "uuid",
+    TAG_FOR_DELETION = "tag_for_deletion",
+    INITIALIZATION = "initialization",
+    SHUTDOWN = "shutdown",
+    BY_KEY = "by-key",
+    AUTH = "auth",
+    AUTH_ROLE = "auth-role",
+    DECAF_ROUTE = "DecafRoute",
+    THROTTLE = "throttle",
+    PERSISTENT_VERSION = "persistent-version",
+    DEFAULT_QUERY_ATTR = "default-query-attr"
+}
+export declare const DefaultContextFlags: ContextFlags<any>;
+export declare const DefaultAdapterFlags: AdapterFlags;
+export declare const TransactionOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const NonTransactionOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const SelectOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const MultipleSelectOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const PaginationOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];

package/lib/types/persistence/constants.d.mts

@@ -0,0 +1,74 @@
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import { AdapterFlags, ContextFlags } from "./types.js";
+import { PreparedStatementKeys } from "../query/constants.js";
+/**
+ * @description Persistence-related constant keys
+ * @summary Enum containing string constants used throughout the persistence layer for metadata, relations, and other persistence-related operations
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
+export declare enum PersistenceKeys {
+    PERSISTENCE = "persistence",
+    /** @description Key for index metadata */
+    INDEX = "index",
+    /** @description Key for sequence metadata */
+    SEQUENCE = "sequence",
+    /** @description Key for unique constraint metadata */
+    UNIQUE = "unique",
+    /** @description Key for adapter metadata */
+    ADAPTER = "adapter",
+    /** @description Template for injectable adapter names */
+    INJECTABLE = "decaf_{0}_adapter_for_{1}",
+    SERVICE = "service",
+    /** @description Key for table name metadata */
+    TABLE = "table",
+    /** @description Key for column name metadata */
+    COLUMN = "column",
+    /** @description Key for general metadata storage */
+    METADATA = "__metadata",
+    /** @description Key for created-by ownership metadata */
+    OWNERSHIP = "ownership",
+    /** @description Key for created-by ownership metadata */
+    CREATED_BY = "ownership.created-by",
+    /** @description Key for updated-by ownership metadata */
+    UPDATED_BY = "ownership.updated-by",
+    /** @description Key for relations metadata storage */
+    RELATIONS = "__relations",
+    /** @description Key for relations metadata storage */
+    RELATION = "relation",
+    /** @description Key for one-to-one relation metadata */
+    ONE_TO_ONE = "relation.one-to-one",
+    /** @description Key for one-to-many relation metadata */
+    ONE_TO_MANY = "relation.one-to-many",
+    /** @description Key for many-to-one relation metadata */
+    MANY_TO_ONE = "relation.many-to-one",
+    /** @description Key for many-to-one relation metadata */
+    MANY_TO_MANY = "relation.many-to-many",
+    /** @description Key for populate metadata */
+    POPULATE = "populate",
+    /** @description Key for populate metadata */
+    NO_VALIDATE = "no-validate",
+    /** @description Key for migration classes */
+    MIGRATION = "migration",
+    STATEMENT = "statement",
+    QUERY = "query",
+    UUID = "uuid",
+    TAG_FOR_DELETION = "tag_for_deletion",
+    INITIALIZATION = "initialization",
+    SHUTDOWN = "shutdown",
+    BY_KEY = "by-key",
+    AUTH = "auth",
+    AUTH_ROLE = "auth-role",
+    DECAF_ROUTE = "DecafRoute",
+    THROTTLE = "throttle",
+    PERSISTENT_VERSION = "persistent-version",
+    DEFAULT_QUERY_ATTR = "default-query-attr"
+}
+export declare const DefaultContextFlags: ContextFlags<any>;
+export declare const DefaultAdapterFlags: AdapterFlags;
+export declare const TransactionOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const NonTransactionOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const SelectOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const MultipleSelectOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];
+export declare const PaginationOperationKeys: (string | OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys)[];

package/lib/types/persistence/decorators.d.cts

@@ -0,0 +1,28 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import { ContextOf } from "./types.cjs";
+import { Repo } from "../repository/Repository.cjs";
+import { ContextualArgs } from "../utils/ContextualLoggedClass.cjs";
+/**
+ * @description Handler function that sets a timestamp property to the current timestamp.
+ * @summary Updates a model property with the current timestamp from the repository context.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context containing the current timestamp
+ * @param {V} data - The data being processed
+ * @param key - The property key to update
+ * @param {M} model - The model instance being updated
+ * @return {Promise<void>} A promise that resolves when the timestamp has been set
+ * @function uuidCreateUpdateHandler
+ */
+export declare function uuidCreateUpdateHandler<M extends Model<boolean>, R extends Repo<M>>(this: R, context: ContextOf<R>, data: UUIDMetadata, key: keyof M, model: M): Promise<void>;
+export type UUIDMetadata = {
+    update: boolean;
+    seed?: string | (<M extends Model>(model: M, ...args: ContextualArgs<any>) => string);
+    args?: any[];
+};
+export declare function uuid(...args: any[]): (target: any, propertyKey?: any) => void;
+export declare function uuid(update: boolean, ...args: any[]): (target: any, propertyKey?: any) => void;
+export declare function uuid(seed: string | (<M extends Model>(model: M, ...args: ContextualArgs<any>) => string), ...args: any[]): (target: any, propertyKey?: any) => void;

package/lib/types/persistence/decorators.d.mts

@@ -0,0 +1,28 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import { ContextOf } from "./types.js";
+import { Repo } from "../repository/Repository.js";
+import { ContextualArgs } from "../utils/ContextualLoggedClass.js";
+/**
+ * @description Handler function that sets a timestamp property to the current timestamp.
+ * @summary Updates a model property with the current timestamp from the repository context.
+ * @template M - The model type extending Model
+ * @template R - The repository type extending IRepository
+ * @template V - The data type for the operation
+ * @template F - The repository flags type
+ * @template C - The context type
+ * @param {C} context - The repository context containing the current timestamp
+ * @param {V} data - The data being processed
+ * @param key - The property key to update
+ * @param {M} model - The model instance being updated
+ * @return {Promise<void>} A promise that resolves when the timestamp has been set
+ * @function uuidCreateUpdateHandler
+ */
+export declare function uuidCreateUpdateHandler<M extends Model<boolean>, R extends Repo<M>>(this: R, context: ContextOf<R>, data: UUIDMetadata, key: keyof M, model: M): Promise<void>;
+export type UUIDMetadata = {
+    update: boolean;
+    seed?: string | (<M extends Model>(model: M, ...args: ContextualArgs<any>) => string);
+    args?: any[];
+};
+export declare function uuid(...args: any[]): (target: any, propertyKey?: any) => void;
+export declare function uuid(update: boolean, ...args: any[]): (target: any, propertyKey?: any) => void;
+export declare function uuid(seed: string | (<M extends Model>(model: M, ...args: ContextualArgs<any>) => string), ...args: any[]): (target: any, propertyKey?: any) => void;

package/lib/types/persistence/errors.d.cts

@@ -0,0 +1,33 @@
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * @description Error thrown when an unsupported operation is attempted
+ * @summary This error is thrown when an operation is requested that is not supported by the current
+ * persistence adapter or configuration. It extends the BaseError class and sets a 500 status code.
+ * @param {string|Error} msg - The error message or an Error object to wrap
+ * @class UnsupportedError
+ * @example
+ * ```typescript
+ * // Throwing an UnsupportedError
+ * if (!adapter.supportsTransactions()) {
+ *   throw new UnsupportedError('Transactions are not supported by this adapter');
+ * }
+ *
+ * // Catching an UnsupportedError
+ * try {
+ *   await adapter.beginTransaction();
+ * } catch (error) {
+ *   if (error instanceof UnsupportedError) {
+ *     console.error('Operation not supported:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class UnsupportedError extends InternalError {
+    constructor(msg: string | Error | unknown);
+}
+export declare class MigrationError extends InternalError {
+    constructor(msg: string | Error | unknown, name?: string);
+}
+export declare class MigrationRuleError extends MigrationError {
+    constructor(msg: string | Error | unknown);
+}

package/lib/types/persistence/errors.d.mts

@@ -0,0 +1,33 @@
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * @description Error thrown when an unsupported operation is attempted
+ * @summary This error is thrown when an operation is requested that is not supported by the current
+ * persistence adapter or configuration. It extends the BaseError class and sets a 500 status code.
+ * @param {string|Error} msg - The error message or an Error object to wrap
+ * @class UnsupportedError
+ * @example
+ * ```typescript
+ * // Throwing an UnsupportedError
+ * if (!adapter.supportsTransactions()) {
+ *   throw new UnsupportedError('Transactions are not supported by this adapter');
+ * }
+ *
+ * // Catching an UnsupportedError
+ * try {
+ *   await adapter.beginTransaction();
+ * } catch (error) {
+ *   if (error instanceof UnsupportedError) {
+ *     console.error('Operation not supported:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class UnsupportedError extends InternalError {
+    constructor(msg: string | Error | unknown);
+}
+export declare class MigrationError extends InternalError {
+    constructor(msg: string | Error | unknown, name?: string);
+}
+export declare class MigrationRuleError extends MigrationError {
+    constructor(msg: string | Error | unknown);
+}

package/lib/types/persistence/event-filters.d.cts

@@ -0,0 +1,20 @@
+import { AllOperationKeys, ObserverFilter } from "./types.cjs";
+import { Model, ModelConstructor } from "@decaf-ts/decorator-validation";
+import type { Repo } from "../repository/Repository.cjs";
+export declare function onlyOnCreate(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnUpdate(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnDelete(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnTransactional(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnSingle(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnBulk(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnFilter(clazz: ModelConstructor<any>, ops: AllOperationKeys[]): ObserverFilter;
+export type AvailableFilters = typeof DefaultRepositoryFilters;
+export declare const DefaultRepositoryFilters: {
+    onlyOnCreate: typeof onlyOnCreate;
+    onlyOnUpdate: typeof onlyOnUpdate;
+    onlyOnDelete: typeof onlyOnDelete;
+    onlyOnTransactional: typeof onlyOnTransactional;
+    onlyOnSingle: typeof onlyOnSingle;
+    onlyOnBulk: typeof onlyOnBulk;
+};
+export declare function getFilters<M extends Model>(repo: Repo<M>): Record<keyof typeof DefaultRepositoryFilters, ObserverFilter>;

package/lib/types/persistence/event-filters.d.mts

@@ -0,0 +1,20 @@
+import { AllOperationKeys, ObserverFilter } from "./types.js";
+import { Model, ModelConstructor } from "@decaf-ts/decorator-validation";
+import type { Repo } from "../repository/Repository.js";
+export declare function onlyOnCreate(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnUpdate(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnDelete(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnTransactional(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnSingle(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnBulk(clazz: ModelConstructor<any>): ObserverFilter;
+export declare function onlyOnFilter(clazz: ModelConstructor<any>, ops: AllOperationKeys[]): ObserverFilter;
+export type AvailableFilters = typeof DefaultRepositoryFilters;
+export declare const DefaultRepositoryFilters: {
+    onlyOnCreate: typeof onlyOnCreate;
+    onlyOnUpdate: typeof onlyOnUpdate;
+    onlyOnDelete: typeof onlyOnDelete;
+    onlyOnTransactional: typeof onlyOnTransactional;
+    onlyOnSingle: typeof onlyOnSingle;
+    onlyOnBulk: typeof onlyOnBulk;
+};
+export declare function getFilters<M extends Model>(repo: Repo<M>): Record<keyof typeof DefaultRepositoryFilters, ObserverFilter>;

package/lib/types/persistence/generators.d.cts

@@ -0,0 +1,14 @@
+export interface Generator<OUT extends string | number = string> {
+    generate(prev?: OUT): OUT | Promise<OUT>;
+}
+export declare class UUID implements Generator {
+    private static _instance;
+    generate(prev?: string): string | Promise<string>;
+    static get instance(): UUID;
+}
+export declare class Serial implements Generator {
+    private static _instance;
+    private count;
+    generate(prev?: string): string | Promise<string>;
+    static get instance(): Serial;
+}

package/lib/types/persistence/generators.d.mts

@@ -0,0 +1,14 @@
+export interface Generator<OUT extends string | number = string> {
+    generate(prev?: OUT): OUT | Promise<OUT>;
+}
+export declare class UUID implements Generator {
+    private static _instance;
+    generate(prev?: string): string | Promise<string>;
+    static get instance(): UUID;
+}
+export declare class Serial implements Generator {
+    private static _instance;
+    private count;
+    generate(prev?: string): string | Promise<string>;
+    static get instance(): Serial;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @description Exports for the persistence module.
+ * @summary This file exports all the necessary components for the persistence functionality, including Dispatch, constants, and more.
+ * @module core/persistence
+ */
+export * from "./Dispatch.cjs";
+export * from "./constants.cjs";
+export * from "./Context.cjs";
+export * from "./ContextLock.cjs";
+export * from "./decorators.cjs";
+export * from "./errors.cjs";
+export * from "./generators.cjs";
+export * from "./event-filters.cjs";
+export * from "./ObserverHandler.cjs";
+export * from "./Sequence.cjs";
+export * from "./types.cjs";
+export * from "./transactions.cjs";
+export * from "./Adapter.cjs";

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

@@ -0,0 +1,18 @@
+/**
+ * @description Exports for the persistence module.
+ * @summary This file exports all the necessary components for the persistence functionality, including Dispatch, constants, and more.
+ * @module core/persistence
+ */
+export * from "./Dispatch.js";
+export * from "./constants.js";
+export * from "./Context.js";
+export * from "./ContextLock.js";
+export * from "./decorators.js";
+export * from "./errors.js";
+export * from "./generators.js";
+export * from "./event-filters.js";
+export * from "./ObserverHandler.js";
+export * from "./Sequence.js";
+export * from "./types.js";
+export * from "./transactions.js";
+export * from "./Adapter.js";

package/lib/types/persistence/transactions.d.cts

@@ -0,0 +1,4 @@
+import { Adapter } from "../persistence/Adapter.cjs";
+import { ContextLock } from "../persistence/ContextLock.cjs";
+export declare function getAdapterTransaction(obj: any, ...args: any[]): import(".").AdapterTransaction<Adapter<any, any, any, any>>;
+export declare function getContextLock(obj: any, ...args: any[]): ContextLock;

package/lib/types/persistence/transactions.d.mts

@@ -0,0 +1,4 @@
+import { Adapter } from "../persistence/Adapter.js";
+import { ContextLock } from "../persistence/ContextLock.js";
+export declare function getAdapterTransaction(obj: any, ...args: any[]): import(".").AdapterTransaction<Adapter<any, any, any, any>>;
+export declare function getContextLock(obj: any, ...args: any[]): ContextLock;

package/lib/types/persistence/types.d.cts

@@ -0,0 +1,86 @@
+import { BulkCrudOperationKeys, LoggerOfFlags, OperationKeys, RepositoryFlags, ContextFlags as CtxFlags } from "@decaf-ts/db-decorators";
+import { Adapter } from "./Adapter.cjs";
+import { Observable, type Observer } from "../interfaces/index.cjs";
+import { Logger } from "@decaf-ts/logging";
+import { Constructor } from "@decaf-ts/decoration";
+import { Model } from "@decaf-ts/decorator-validation";
+import { ContextualArgs, ContextualLoggedClass } from "../utils/ContextualLoggedClass.cjs";
+import { Context } from "./Context.cjs";
+import { Repository } from "../repository/Repository.cjs";
+import { PersistenceKeys } from "./constants.cjs";
+import { PreparedStatementKeys } from "../query/constants.cjs";
+import { ContextLock } from "./ContextLock.cjs";
+export type FlagsOfContext<C extends Context<any>> = C extends Context<infer F> ? F : never;
+export type LoggerOfContext<C extends Context<any>> = LoggerOfFlags<FlagsOfContext<C>>;
+export type ContextOfRepository<R extends Repository<any, any>> = R extends Repository<any, infer A> ? ContextOf<A> : never;
+export type FlagsOfRepository<R extends Repository<any, any>> = FlagsOfContext<ContextOfRepository<R>>;
+export type LoggerOfRepository<R extends Repository<any, any>> = LoggerOfContext<ContextOfRepository<R>>;
+export type ContextOf<OBJ extends Repository<any, any> | Adapter<any, any, any, any> | ContextualLoggedClass<any>> = OBJ extends Adapter<any, any, any, infer C> ? C : OBJ extends Repository<any, any> ? ContextOfRepository<OBJ> : OBJ extends ContextualLoggedClass<infer C> ? C : never;
+export type ConfigOf<OBJ extends Adapter<any, any, any, any>> = OBJ extends Adapter<infer C, any, any, any> ? C : never;
+export type LoggerOfAdapter<A extends Adapter<any, any, any, any>> = A extends Adapter<any, any, any, infer C> ? LoggerOfContext<C> : never;
+export type FlagsOfAdapter<A extends Adapter<any, any, any, any>> = A extends Adapter<any, any, any, infer C> ? FlagsOfContext<C> : never;
+export type LoggerOf<OBJ extends AdapterFlags<any> | Context<any> | Adapter<any, any, any> | Repository<any, any>> = OBJ extends AdapterFlags<any> ? LoggerOfFlags<OBJ> : OBJ extends Context<any> ? LoggerOfContext<OBJ> : OBJ extends Repository<any, any> ? LoggerOfRepository<OBJ> : OBJ extends Adapter<any, any, any> ? LoggerOfAdapter<OBJ> : Logger;
+export type ConfOf<A extends Adapter<any, any, any, any>> = A extends Adapter<infer C, any, any> ? C : never;
+export type FlagsOf<OBJ extends Repository<any, any> | Adapter<any, any, any, any> | Context<any>> = OBJ extends Context<any> ? FlagsOfContext<OBJ> : OBJ extends Repository<any, any> ? FlagsOfRepository<OBJ> : OBJ extends Adapter<any, any, any, any> ? FlagsOfAdapter<OBJ> : never;
+export type PersistenceObservable<CONTEXT extends Context<any>> = Observable<[
+    Observer,
+    ObserverFilter?
+], [
+    Constructor | string,
+    OperationKeys | BulkCrudOperationKeys | string,
+    EventIds,
+    ...ContextualArgs<CONTEXT>
+]>;
+export type PersistenceObserver<CONTEXT extends Context<any>> = Observer<[
+    Constructor | string,
+    OperationKeys | BulkCrudOperationKeys | string,
+    EventIds,
+    ...ContextualArgs<CONTEXT>
+]>;
+/**
+ * @description Type representing possible ID formats for database events
+ * @summary A union type that defines the possible formats for event identifiers in the persistence layer.
+ * These can be single values (string, number, bigint) or arrays of these types.
+ * @typedef {(string|number|bigint|string[]|number[]|bigint[])} EventIds
+ * @memberOf module:core
+ */
+export type EventIds = string | number | bigint | string[] | number[] | bigint[];
+export type ObserverFilter = (table: Constructor | string, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<any>) => boolean;
+export type InferredAdapterConfig<A> = A extends Adapter<infer CONF, any, any> ? CONF : never;
+export interface AdapterDispatch<A extends Adapter<any, any, any, any>> extends PersistenceObservable<ContextOf<A>> {
+    close(...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+    updateObservers<M extends Model>(table: Constructor<M> | string, event: OperationKeys | BulkCrudOperationKeys | string, id: EventIds, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+}
+export type RepositoryFor<A extends Adapter<any, any, any, any>> = A extends Adapter<any, any, any, any> ? ReturnType<A["repository"]> : never;
+export type PreparedModel = {
+    record: Record<string, any>;
+    id: string;
+    transient?: Record<string, any>;
+};
+export type ContextFlags<LOG extends Logger> = CtxFlags<LOG> & Pick<RepositoryFlags<LOG>, "operation" | "correlationId" | "ignoreDevSafeGuards" | "parentContext" | "childContexts"> & {
+    pending?: Record<string, string[]>;
+    transactionLock?: ContextLock;
+};
+export type AdapterFlags<LOG extends Logger = Logger> = RepositoryFlags<LOG> & ContextFlags<LOG> & {
+    allowGenerationOverride: boolean;
+    afterQueryHandlers: boolean;
+    enforceUpdateValidation: boolean;
+    allowRawStatements: boolean;
+    forcePrepareSimpleQueries: boolean;
+    forcePrepareComplexQueries: boolean;
+    cacheForPopulate: Record<string, any>;
+    preferFromCache: boolean;
+    noEmit: boolean;
+    noEmitSingle: boolean;
+    noEmitBulk: boolean;
+    breakOnSingleFailureInBulk: boolean;
+    observeFullResult: boolean;
+    paginateByBookmark: boolean;
+    dryRun: boolean;
+    lock?: ContextLock;
+};
+export type RawResult<R, D extends boolean> = D extends true ? R : {
+    data: R;
+    count?: number;
+};
+export type AllOperationKeys = OperationKeys | BulkCrudOperationKeys | PersistenceKeys | PreparedStatementKeys | string;