@decaf-ts/core 0.20.0 → 0.21.0

package/lib/types/interfaces/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @description Exports for the interfaces module.
+ * @summary This file exports all the necessary components for the interfaces functionality, including ErrorParser, Executor, and more.
+ * @module core/interfaces
+ */
+export * from "./ErrorParser";
+export * from "./Executor";
+export * from "./Observable";
+export * from "./Observer";
+export * from "./Queriable";
+export * from "./RawExecutor";
+export * from "./SequenceOptions";

package/lib/types/migrations/Migration.d.ts

@@ -0,0 +1,19 @@
+import { ConnectionForAdapter, Migration } from "./types";
+import { AbsContextual, ContextualArgs } from "../utils/ContextualLoggedClass";
+import { Adapter } from "../persistence/Adapter";
+import { ContextOf } from "../persistence/types";
+export declare abstract class AbsMigration<A extends Adapter<any, any, any, any>, R = void> extends AbsContextual<ContextOf<A>> implements Migration<A, R> {
+    private _reference?;
+    private _precedence?;
+    transaction: boolean;
+    get reference(): string;
+    get precedence(): string | Migration<any, any>;
+    protected constructor();
+    protected get adapter(): A;
+    protected abstract getQueryRunner(conn: ConnectionForAdapter<A>): ConnectionForAdapter<A>;
+    private enforceRules;
+    private prefix;
+    abstract down(qr: ConnectionForAdapter<A>, adapter: A, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+    abstract migrate(qr: ConnectionForAdapter<A>, adapter: A, ...args: ContextualArgs<ContextOf<A>>): Promise<R>;
+    abstract up(qr: ConnectionForAdapter<A>, adapter: A, ctx: ContextOf<A>): Promise<void>;
+}

package/lib/types/migrations/MigrationService.d.ts

@@ -0,0 +1,63 @@
+import { Migration, MigrationConfig, PersistenceMigrationConfig } from "./types";
+import { ClientBasedService } from "../services/services";
+import { Adapter } from "../persistence/Adapter";
+import { ContextOf } from "../persistence/types";
+import { ContextualArgs, MaybeContextualArg } from "../utils/ContextualLoggedClass";
+import { TaskModel } from "../tasks/models/TaskModel";
+import { MigrationVersioning } from "./MigrationVersioning";
+type ResolvedMigration = {
+    migration: Migration<any, any>;
+    flavour: string;
+    reference: string;
+    version: string;
+};
+type VersionTask = {
+    version: string;
+    task: TaskModel;
+};
+export declare class MigrationService<PERSIST extends boolean, A extends Adapter<any, any, any, any> = any, R = void> extends ClientBasedService<PERSIST extends boolean ? A : void, MigrationConfig<PERSIST>> implements Migration<A, R> {
+    protected versioning: MigrationVersioning;
+    protected queuedTaskChain: Array<{
+        id: string;
+        version: string;
+    }>;
+    flavour?: string;
+    readonly reference: string;
+    readonly precedence: Migration<any, any> | Migration<any, any>[] | null;
+    transaction: boolean;
+    constructor();
+    static migrateAdapters<AD extends Adapter<any, any, any, any> = Adapter<any, any, any, any>>(adapters: AD[], cfg?: PersistenceMigrationConfig<AD>, ...args: MaybeContextualArg<ContextOf<AD>>): Promise<MigrationService<true, AD>[]>;
+    initialize(...args: MaybeContextualArg<ContextOf<A>>): Promise<{
+        config: MigrationConfig<PERSIST>;
+        client: PERSIST extends boolean ? A : void;
+    }>;
+    down(qr: any, adapter: any, ...args: ContextualArgs<ContextOf<any>>): Promise<void>;
+    protected normalizeVersion(raw: string, precedenceHint?: string): string;
+    protected extractPrecedenceTokens(migration: Migration<any, any>): string[];
+    protected referencesMigration(candidate: Migration<any, any>, target: ResolvedMigration): boolean;
+    protected precedenceHint(migration: Migration<any, any>): string | undefined;
+    protected compareByPrecedence(migration1: ResolvedMigration, migration2: ResolvedMigration): number;
+    protected sort(migrations: ResolvedMigration[]): ResolvedMigration[];
+    protected resolveMigration(migration: Migration<any, any>): ResolvedMigration;
+    protected shouldIncludeMigration(migration: ResolvedMigration, targetFlavour?: string, includeGeneric?: boolean): boolean;
+    protected collectMigrations(targetFlavour?: string, includeGeneric?: boolean): ResolvedMigration[];
+    protected buildExecutionPlan(options?: {
+        fromVersion?: string;
+        toVersion?: string;
+        targetFlavour?: string;
+        includeGeneric?: boolean;
+    }): ResolvedMigration[];
+    protected executeMigration(migration: ResolvedMigration, ...args: ContextualArgs<ContextOf<any>>): Promise<void>;
+    protected buildMigrationTaskForPlan(plan: ResolvedMigration[], ...args: ContextualArgs<ContextOf<any>>): TaskModel;
+    protected buildMigrationTasksForPlan(plan: ResolvedMigration[], ...args: ContextualArgs<ContextOf<any>>): VersionTask[];
+    createMigrationTask(targetVersion?: string, fromVersion?: string, ...args: ContextualArgs<ContextOf<any>>): TaskModel;
+    createMigrationTasks(targetVersion?: string, fromVersion?: string, ...args: ContextualArgs<ContextOf<any>>): VersionTask[];
+    protected migrationTaskIdsFromContext(taskKey: string, args: ContextualArgs<ContextOf<any>>): string[];
+    migrate(qr?: any, adapter?: any, ...args: MaybeContextualArg<ContextOf<any>>): Promise<R>;
+    migrateNormally(qr?: any, adapter?: any, ...args: MaybeContextualArg<ContextOf<any>>): Promise<R>;
+    migrateViaTasks(qr?: any, adapter?: any, ...args: MaybeContextualArg<ContextOf<any>>): Promise<R>;
+    track(taskIds?: string[] | string, ...args: MaybeContextualArg<ContextOf<any>>): Promise<void>;
+    retry(taskIds?: string[] | string, ...args: MaybeContextualArg<ContextOf<any>>): Promise<void>;
+    up(qr: any, adapter: any, ...args: ContextualArgs<ContextOf<any>>): Promise<void>;
+}
+export {};

package/lib/types/migrations/MigrationTaskBuilder.d.ts

@@ -0,0 +1,10 @@
+import { CompositeTaskBuilder } from "../tasks/builder";
+import { TaskModel } from "../tasks/models/TaskModel";
+import { MigrationStepInput } from "./MigrationTasks";
+export declare class MigrationTaskBuilder {
+    protected readonly builder: CompositeTaskBuilder;
+    constructor(name?: string);
+    addMigrationStep(step: MigrationStepInput): this;
+    addStep(classification: string, input?: any): this;
+    build(): TaskModel;
+}

package/lib/types/migrations/MigrationTasks.d.ts

@@ -0,0 +1,9 @@
+import { TaskHandler } from "../tasks/TaskHandler";
+import { TaskContext } from "../tasks/TaskContext";
+export interface MigrationStepInput {
+    reference: string;
+    args?: any[];
+}
+export declare class MigrationTask extends TaskHandler<MigrationStepInput, void> {
+    run(input: MigrationStepInput, ctx: TaskContext): Promise<void>;
+}

package/lib/types/migrations/MigrationVersioning.d.ts

@@ -0,0 +1,7 @@
+export interface MigrationVersioning {
+    isVersionHint(value: string): boolean;
+    normalize(reference: string, precedenceHint?: string): string;
+    compare(a: string, b: string): number;
+    gt(a: string, b: string): boolean;
+    lte(a: string, b: string): boolean;
+}

package/lib/types/migrations/SemverMigrationVersioning.d.ts

@@ -0,0 +1,10 @@
+import { MigrationVersioning } from "./MigrationVersioning";
+export declare class SemverMigrationVersioning implements MigrationVersioning {
+    private coerce;
+    private slug;
+    isVersionHint(value: string): boolean;
+    normalize(reference: string, precedenceHint?: string): string;
+    compare(a: string, b: string): number;
+    gt(a: string, b: string): boolean;
+    lte(a: string, b: string): boolean;
+}

package/lib/types/migrations/StandardMigrationVersioning.d.ts

@@ -0,0 +1,12 @@
+import { MigrationVersioning } from "./MigrationVersioning";
+/**
+ * Legacy non-semver migration ordering strategy.
+ * Keeps references as-is and compares using lexical order.
+ */
+export declare class StandardMigrationVersioning implements MigrationVersioning {
+    isVersionHint(value: string): boolean;
+    normalize(reference: string, precedenceHint?: string): string;
+    compare(a: string, b: string): number;
+    gt(a: string, b: string): boolean;
+    lte(a: string, b: string): boolean;
+}

package/lib/types/migrations/constants.d.ts

@@ -0,0 +1,2 @@
+import { MigrationConfig } from "./types";
+export declare const DefaultMigrationConfig: MigrationConfig<true>;

package/lib/types/migrations/decorators.d.ts

@@ -0,0 +1,12 @@
+import { Constructor } from "@decaf-ts/decoration";
+import { Migration, MigrationRule } from "./types";
+export declare function migration(reference: string): (target: object) => any;
+export declare function migration(reference: string, precedence: Constructor<Migration<any, any>> | null): (target: object) => any;
+export declare function migration(reference: string, flavour: string, rules?: MigrationRule[]): (target: object) => any;
+export declare function migration(reference: string, precedence: Constructor<Migration<any, any>>, flavour: string): (target: object) => any;
+export declare function migration(reference: string, precedence?: Constructor<Migration<any, any>> | string | null, flavour?: string | MigrationRule[], rules?: MigrationRule[]): (target: object) => any;
+export declare function migration(reference: string, opts?: {
+    precedence?: Constructor<Migration<any, any>> | string | null;
+    flavour?: string;
+    rules?: MigrationRule[];
+}): (target: object) => any;

package/lib/types/migrations/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @description Exports for the migrations module.
+ * @summary This file exports all the necessary components for the migrations functionality, including constants, decorators, and more.
+ * @module core/migrations
+ */
+import "../overrides";
+export * from "./constants";
+export * from "./decorators";
+export * from "./Migration";
+export * from "./MigrationService";
+export * from "./MigrationTaskBuilder";
+export * from "./MigrationTasks";
+export * from "./StandardMigrationVersioning";
+export * from "./MigrationVersioning";
+export * from "./types";

package/lib/types/migrations/types.d.ts

@@ -0,0 +1,46 @@
+import { Adapter } from "../persistence/Adapter";
+import { AdapterFlags, ContextOf } from "../persistence/types";
+import { ContextualArgs } from "../utils/ContextualLoggedClass";
+import { TaskService } from "../tasks/TaskService";
+import type { MigrationVersioning } from "./MigrationVersioning";
+export interface Migration<A extends Adapter<any, any, any, any>, R = void> {
+    flavour?: string;
+    precedence: Migration<any, any> | Migration<any, any>[] | string | null;
+    reference: string;
+    transaction: boolean;
+    up(qr: ConnectionForAdapter<A>, adapter: A, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+    migrate(qr: ConnectionForAdapter<A>, adapter: A, ...args: ContextualArgs<ContextOf<A>>): Promise<R>;
+    down(qr: ConnectionForAdapter<A>, adapter: A, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+}
+export type ConnectionForAdapter<A extends Adapter<any, any, any, any>> = A extends Adapter<any, any, infer CONN, any> ? CONN : never;
+export type MigrationRule<A extends Adapter<any, any, any, any> = any, QUERYRUNNER = ConnectionForAdapter<A>> = (qr: QUERYRUNNER, adapter: A, ctx: ContextOf<A>) => Promise<boolean>;
+export type MigrationMetadata = {
+    precedence?: Migration<any, any> | string;
+    flavour: string;
+    rules?: MigrationRule[];
+};
+export type RetrieveLastVersionHandler<A extends Adapter<any, any, any, any> = Adapter<any, any, any, any>> = (adapter: A, ...args: ContextualArgs<ContextOf<A>>) => Promise<string | undefined | null>;
+export type SetCurrentVersionHandler<A extends Adapter<any, any, any, any> = Adapter<any, any, any, any>> = (version: string, adapter: A, ...args: ContextualArgs<ContextOf<A>>) => Promise<void>;
+export type AdapterMigrationHandlers<AD extends Adapter<any, any, any, any> = Adapter<any, any, any, any>> = {
+    retrieveLastVersion?: RetrieveLastVersionHandler<AD>;
+    setCurrentVersion?: SetCurrentVersionHandler<AD>;
+};
+export type PersistenceMigrationConfig<AD extends Adapter<any, any, any, any> = Adapter<any, any, any, any>> = {
+    toVersion?: string;
+    taskMode?: boolean;
+    dryRun?: boolean;
+    flavours?: string[];
+    taskService?: TaskService<any>;
+    handlers?: Partial<Record<string, AdapterMigrationHandlers<AD>>>;
+};
+export type MigrationConfig<PERSIST extends boolean> = AdapterFlags<any> & {
+    persistMigrationSteps: PERSIST;
+    persistenceFlavour?: string;
+    targetVersion?: string;
+    taskMode?: boolean;
+    includeGenericInTaskMode?: boolean;
+    retrieveLastVersion?: RetrieveLastVersionHandler;
+    setCurrentVersion?: SetCurrentVersionHandler;
+    taskService?: TaskService<any>;
+    versioning?: MigrationVersioning;
+};

package/lib/types/model/BaseModel.d.ts

@@ -0,0 +1,37 @@
+import { ModelArg, Model } from "@decaf-ts/decorator-validation";
+/**
+ * @description Base model class for all domain models
+ * @summary An abstract base class that extends the Model class from decorator-validation and adds timestamp functionality.
+ * All domain models in the application should extend this class to inherit common properties and behaviors.
+ * @param {ModelArg<BaseModel>} arg - Optional initialization data for the model
+ * @class BaseModel
+ * @example
+ * ```typescript
+ * class User extends BaseModel {
+ *   @required()
+ *   username!: string;
+ *
+ *   @email()
+ *   email!: string;
+ *
+ *   constructor(data?: ModelArg<User>) {
+ *     super(data);
+ *   }
+ * }
+ *
+ * const user = new User({ username: 'john', email: 'john@example.com' });
+ * ```
+ */
+export declare abstract class BaseModel extends Model {
+    /**
+     * @description Creation timestamp for the model
+     * @summary Automatically set to the current date and time when the model is created
+     */
+    createdAt: Date;
+    /**
+     * @description Last update timestamp for the model
+     * @summary Automatically updated to the current date and time whenever the model is modified
+     */
+    updatedAt: Date;
+    protected constructor(arg?: ModelArg<BaseModel>);
+}

package/lib/types/model/SequenceModel.d.ts

@@ -0,0 +1,32 @@
+import type { ModelArg } from "@decaf-ts/decorator-validation";
+import { BaseModel } from "./BaseModel";
+/**
+ * @description RAM sequence model for auto-incrementing values
+ * @summary A model class that represents a sequence in the RAM adapter. It stores the current value
+ * of a sequence that can be used for generating sequential identifiers for entities.
+ * The sequence is identified by its ID and maintains the current value.
+ * @param {ModelArg<Sequence>} seq - Initial sequence data
+ * @class Sequence
+ * @category Ram
+ * @example
+ * ```typescript
+ * // Create a new sequence
+ * const orderSequence = new Sequence({ id: 'order_seq', current: 1 });
+ *
+ * // Use the sequence to get the next value
+ * const nextOrderId = parseInt(orderSequence.current.toString()) + 1;
+ * orderSequence.current = nextOrderId;
+ * ```
+ */
+export declare class SequenceModel extends BaseModel {
+    /**
+     * @description Primary key identifier for the sequence
+     */
+    id: string;
+    /**
+     * @description Current value of the sequence
+     * Used to generate the next sequential value
+     */
+    current: string | number;
+    constructor(seq?: ModelArg<SequenceModel>);
+}