arkormx 0.2.11 → 1.0.0

package/dist/index.d.mts

@@ -570,10 +570,6 @@ declare class InlineFactory<TModel, TAttributes extends FactoryAttributes> exten
 declare const defineFactory: <TModel, TAttributes extends FactoryAttributes = Partial<ModelAttributes<TModel>>>(model: FactoryModelConstructor<TModel>, definition: FactoryDefinition<TAttributes>) => ModelFactory<TModel, TAttributes>;
 //#endregion
 //#region src/Model.d.ts
-type RelatedModelClass<TInstance = unknown> = (abstract new (attributes?: Record<string, unknown>) => TInstance) & RelationshipModelStatic;
-type GlobalScope = (query: QueryBuilder<any, any>) => QueryBuilder<any, any> | void;
-type ModelEventName = 'saving' | 'saved' | 'creating' | 'created' | 'updating' | 'updated' | 'deleting' | 'deleted' | 'restoring' | 'restored' | 'forceDeleting' | 'forceDeleted';
-type ModelEventListener<TModel extends Model = Model> = (model: TModel) => void | Promise<void>;
 /**
  * Base model class that all models should extend.
  *
@@ -583,6 +579,8 @@ type ModelEventListener<TModel extends Model = Model> = (model: TModel) => void
  * @since 0.1.0
  */
 declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string, unknown> | string = Record<string, any>, TAttributes extends Record<string, unknown> = ModelAttributesOf<TSchema>> {
+  private static readonly lifecycleStates;
+  private static eventsSuppressed;
   protected static factoryClass?: new () => ModelFactory<any, any>;
   protected static client: Record<string, unknown>;
   protected static delegate: string;
@@ -590,6 +588,7 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
   protected static deletedAtColumn: string;
   protected static globalScopes: Record<string, GlobalScope>;
   protected static eventListeners: Partial<Record<ModelEventName, ModelEventListener<any>[]>>;
+  protected static dispatchesEvents: Partial<Record<ModelEventName, ModelEventDispatcher<any> | ModelEventDispatcher<any>[]>>;
   protected casts: CastMap;
   protected hidden: string[];
   protected visible: string[];
@@ -611,6 +610,13 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @param scope
    */
   static addGlobalScope(name: string, scope: GlobalScope): void;
+  /**
+   * Execute a callback without applying global scopes for the current model class.
+   *
+   * @param callback
+   * @returns
+   */
+  static withoutGlobalScopes<T>(callback: () => T | Promise<T>): Promise<Awaited<T>>;
   /**
    * Remove a global scope by name.
    *
@@ -628,6 +634,26 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @param listener
    */
   static on<TModel extends Model = Model>(event: ModelEventName, listener: ModelEventListener<TModel>): void;
+  /**
+   * Register a model lifecycle callback listener.
+   *
+   * @param event
+   * @param listener
+   */
+  static event<TModel extends Model = Model>(event: ModelEventName, listener: ModelEventListener<TModel>): void;
+  static retrieved<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static saving<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static saved<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static creating<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static created<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static updating<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static updated<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static deleting<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static deleted<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static restoring<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static restored<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static forceDeleting<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
+  static forceDeleted<TModel extends Model = Model>(listener: ModelEventListener<TModel>): void;
   /**
    * Remove listeners for an event. If listener is omitted, all listeners for that event are removed.
    *
@@ -639,6 +665,22 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * Clears all event listeners for the model.
    */
   static clearEventListeners(): void;
+  /**
+   * Execute a callback while suppressing lifecycle events for all models.
+   *
+   * @param callback
+   * @returns
+   */
+  static withoutEvents<T>(callback: () => T | Promise<T>): Promise<Awaited<T>>;
+  /**
+   * Execute a callback within a transaction scope.
+   * Nested calls reuse the active transaction client.
+   *
+   * @param callback
+   * @param options
+   * @returns
+   */
+  static transaction<T>(callback: (client: PrismaClientLike) => T | Promise<T>, options?: PrismaTransactionOptions): Promise<Awaited<T>>;
   /**
    * Get the Prisma delegate for the model.
    * If a delegate name is provided, it will attempt to resolve that delegate.
@@ -656,6 +698,14 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @returns
    */
   static query<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any>, TModel extends InstanceType<TThis> = InstanceType<TThis>, TDelegate extends PrismaDelegateLike = DelegateForModelSchema<TModel extends Model<infer TSchema> ? TSchema : Record<string, any>>>(this: TThis): QueryBuilder<TModel, TDelegate>;
+  /**
+   * Boot hook for subclasses to register scopes or perform one-time setup.
+   */
+  protected static boot(): void;
+  /**
+   * Booted hook for subclasses to register callbacks after boot logic runs.
+   */
+  protected static booted(): void;
   /**
    * Get a query builder instance that includes soft-deleted records.
    *
@@ -704,6 +754,22 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @returns
    */
   static hydrateMany<TModel>(this: new (attributes: Record<string, unknown>) => TModel, attributes: Record<string, unknown>[]): TModel[];
+  /**
+   * Hydrate a model instance and dispatch the retrieved lifecycle event.
+   *
+   * @param this
+   * @param attributes
+   * @returns
+   */
+  static hydrateRetrieved<TModel>(this: ModelStatic<TModel, PrismaDelegateLike>, attributes: Record<string, unknown>): Promise<TModel>;
+  /**
+   * Hydrate multiple model instances and dispatch the retrieved lifecycle event for each.
+   *
+   * @param this
+   * @param attributes
+   * @returns
+   */
+  static hydrateManyRetrieved<TModel>(this: ModelStatic<TModel, PrismaDelegateLike>, attributes: Record<string, unknown>[]): Promise<TModel[]>;
   /**
    * Fill the model's attributes from a plain object, using the
    * setAttribute method to ensure that mutators and casts are applied.
@@ -738,6 +804,12 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @returns
    */
   save(): Promise<this>;
+  /**
+   * Save the model without dispatching lifecycle events.
+   *
+   * @returns
+   */
+  saveQuietly(): Promise<this>;
   /**
    * Delete the model from the database.
    * If soft deletes are enabled, it will perform a soft delete by
@@ -747,6 +819,12 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @returns
    */
   delete(): Promise<this>;
+  /**
+   * Delete the model without dispatching lifecycle events.
+   *
+   * @returns
+   */
+  deleteQuietly(): Promise<this>;
   /**
    * Permanently delete the model from the database, regardless of whether soft
    * deletes are enabled.
@@ -754,12 +832,24 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @returns
    */
   forceDelete(): Promise<this>;
+  /**
+   * Force delete the model without dispatching lifecycle events.
+   *
+   * @returns
+   */
+  forceDeleteQuietly(): Promise<this>;
   /**
    * Restore a soft-deleted model by setting the deleted at column to null.
    *
    * @returns
    */
   restore(): Promise<this>;
+  /**
+   * Restore the model without dispatching lifecycle events.
+   *
+   * @returns
+   */
+  restoreQuietly(): Promise<this>;
   /**
    * Load related models onto the current model instance.
    *
@@ -786,6 +876,34 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * @returns
    */
   toJSON(): Serializable;
+  /**
+   * Determine if another model represents the same persisted record.
+   *
+   * @param model
+   * @returns
+   */
+  is(model: unknown): boolean;
+  /**
+   * Determine if another model does not represent the same persisted record.
+   *
+   * @param model
+   * @returns
+   */
+  isNot(model: unknown): boolean;
+  /**
+   * Determine if another model is the same in-memory instance.
+   *
+   * @param model
+   * @returns
+   */
+  isSame(model: unknown): boolean;
+  /**
+   * Determine if another model is not the same in-memory instance.
+   *
+   * @param model
+   * @returns
+   */
+  isNotSame(model: unknown): boolean;
   /**
    * Define a has one relationship.
    *
@@ -908,6 +1026,42 @@ declare abstract class Model<TSchema extends PrismaDelegateLike | Record<string,
    * Ensures event listeners are own properties on subclass constructors.
    */
   private static ensureOwnEventListeners;
+  /**
+   * Resolve lifecycle state for the provided model class.
+   *
+   * @param modelClass
+   * @returns
+   */
+  private static getLifecycleState;
+  /**
+   * Ensure the target model class has executed its boot lifecycle.
+   *
+   * @param modelClass
+   */
+  private static ensureModelBooted;
+  /**
+   * Determine if global scopes are currently suppressed for the model class.
+   *
+   * @param modelClass
+   * @returns
+   */
+  private static areGlobalScopesSuppressed;
+  /**
+   * Resolve configured class-based event handlers for a lifecycle event.
+   *
+   * @param modelClass
+   * @param event
+   * @returns
+   */
+  private static resolveDispatchedEventListeners;
+  /**
+   * Determine whether a lifecycle event has any registered listeners.
+   *
+   * @param modelClass
+   * @param event
+   * @returns
+   */
+  private static hasEventListeners;
   /**
    * Dispatches lifecycle events to registered listeners.
    *
@@ -934,6 +1088,15 @@ type DelegateFromPrismaClient<TKey extends string> = LowercaseString<TKey> exten
 type DelegateForModelSchema<TSchema extends PrismaDelegateLike | Record<string, unknown> | string> = TSchema extends PrismaDelegateLike ? TSchema : TSchema extends string ? DelegateFromPrismaClient<TSchema> extends PrismaDelegateLike ? DelegateFromPrismaClient<TSchema> : PrismaDelegateLike : PrismaDelegateLike;
 type ModelAttributesOf<TSchema extends PrismaDelegateLike | Record<string, unknown> | string> = TSchema extends PrismaDelegateLike ? DelegateRow<TSchema> extends Record<string, unknown> ? DelegateRow<TSchema> : Record<string, any> : TSchema extends string ? DelegateFromPrismaClient<TSchema> extends PrismaDelegateLike ? DelegateRow<DelegateFromPrismaClient<TSchema>> extends Record<string, unknown> ? DelegateRow<DelegateFromPrismaClient<TSchema>> : Record<string, any> : Record<string, any> : TSchema extends Record<string, unknown> ? TSchema : Record<string, any>;
 type ModelAttributes<TModel> = TModel extends Model<infer TSchema> ? ModelAttributesOf<TSchema> : Record<string, any>;
+type RelatedModelClass<TInstance = unknown> = (abstract new (attributes?: Record<string, unknown>) => TInstance) & RelationshipModelStatic;
+type GlobalScope = (query: QueryBuilder<any, any>) => QueryBuilder<any, any> | void;
+type ModelEventName = 'retrieved' | 'saving' | 'saved' | 'creating' | 'created' | 'updating' | 'updated' | 'deleting' | 'deleted' | 'restoring' | 'restored' | 'forceDeleting' | 'forceDeleted';
+type ModelEventListener<TModel extends Model = Model> = (model: TModel) => void | Promise<void>;
+type ModelEventHandler<TModel extends Model = Model> = {
+  handle: (model: TModel) => void | Promise<void>;
+};
+type ModelEventHandlerConstructor<TModel extends Model = Model> = new () => ModelEventHandler<TModel>;
+type ModelEventDispatcher<TModel extends Model = Model> = ModelEventHandler<TModel> | ModelEventHandlerConstructor<TModel>;
 //#endregion
 //#region src/Paginator.d.ts
 /**
@@ -1772,6 +1935,8 @@ interface ModelStatic<TModel, TDelegate extends PrismaDelegateLike = PrismaDeleg
   query: () => QueryBuilder<TModel, TDelegate>;
   hydrate: (attributes: DelegateRow<TDelegate> extends Record<string, unknown> ? DelegateRow<TDelegate> : Record<string, unknown>) => TModel;
   hydrateMany: (attributes: (DelegateRow<TDelegate> extends Record<string, unknown> ? DelegateRow<TDelegate> : Record<string, unknown>)[]) => TModel[];
+  hydrateRetrieved: (attributes: DelegateRow<TDelegate> extends Record<string, unknown> ? DelegateRow<TDelegate> : Record<string, unknown>) => Promise<TModel>;
+  hydrateManyRetrieved: (attributes: (DelegateRow<TDelegate> extends Record<string, unknown> ? DelegateRow<TDelegate> : Record<string, unknown>)[]) => Promise<TModel[]>;
   getDelegate: (delegate?: string) => TDelegate;
   getSoftDeleteConfig: () => SoftDeleteConfig;
 }
@@ -1789,6 +1954,15 @@ interface CastHandler<T = unknown> {
 type CastDefinition = CastType | CastHandler;
 type CastMap = Record<string, CastDefinition>;
 type PrismaClientLike = PrismaClient | Record<string, unknown>;
+interface PrismaTransactionOptions {
+  maxWait?: number;
+  timeout?: number;
+  isolationLevel?: string;
+}
+type PrismaTransactionCallback<TResult = unknown> = (client: PrismaClientLike) => TResult | Promise<TResult>;
+interface PrismaTransactionCapableClient {
+  $transaction: <TResult>(callback: PrismaTransactionCallback<TResult>, options?: PrismaTransactionOptions) => Promise<TResult>;
+}
 type ClientResolver = PrismaClientLike | (() => PrismaClientLike);
 interface ArkormConfig {
   /**
@@ -2791,8 +2965,34 @@ declare abstract class Seeder {
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
+interface ArkormErrorContext {
+  code?: string;
+  operation?: string;
+  model?: string;
+  delegate?: string;
+  relation?: string;
+  scope?: string;
+  meta?: Record<string, unknown>;
+  cause?: unknown;
+}
 declare class ArkormException extends Error {
-  constructor(message: string);
+  readonly code?: string;
+  readonly operation?: string;
+  readonly model?: string;
+  readonly delegate?: string;
+  readonly relation?: string;
+  readonly scope?: string;
+  readonly meta?: Record<string, unknown>;
+  constructor(message: string, context?: ArkormErrorContext);
+  getContext(): Omit<ArkormErrorContext, 'cause'> & {
+    cause?: unknown;
+  };
+  toJSON(): Record<string, unknown>;
+}
+//#endregion
+//#region src/Exceptions/MissingDelegateException.d.ts
+declare class MissingDelegateException extends ArkormException {
+  constructor(message: string, context?: ArkormErrorContext);
 }
 //#endregion
 //#region src/Exceptions/ModelNotFoundException.d.ts
@@ -2805,10 +3005,35 @@ declare class ArkormException extends Error {
  */
 declare class ModelNotFoundException extends ArkormException {
   private modelName;
-  constructor(modelName: string, message?: string);
+  constructor(modelName: string, message?: string, context?: ArkormErrorContext);
   getModelName(): string;
 }
 //#endregion
+//#region src/Exceptions/QueryConstraintException.d.ts
+declare class QueryConstraintException extends ArkormException {
+  constructor(message: string, context?: ArkormErrorContext);
+}
+//#endregion
+//#region src/Exceptions/RelationResolutionException.d.ts
+declare class RelationResolutionException extends ArkormException {
+  constructor(message: string, context?: ArkormErrorContext);
+}
+//#endregion
+//#region src/Exceptions/ScopeNotDefinedException.d.ts
+declare class ScopeNotDefinedException extends ArkormException {
+  constructor(message: string, context?: ArkormErrorContext);
+}
+//#endregion
+//#region src/Exceptions/UniqueConstraintResolutionException.d.ts
+declare class UniqueConstraintResolutionException extends ArkormException {
+  constructor(message: string, context?: ArkormErrorContext);
+}
+//#endregion
+//#region src/Exceptions/UnsupportedAdapterFeatureException.d.ts
+declare class UnsupportedAdapterFeatureException extends ArkormException {
+  constructor(message: string, context?: ArkormErrorContext);
+}
+//#endregion
 //#region src/helpers/migration-history.d.ts
 declare const resolveMigrationStateFilePath: (cwd: string, configuredPath?: string) => string;
 declare const buildMigrationIdentity: (filePath: string, className: string) => string;
@@ -3125,6 +3350,9 @@ declare const getDefaultStubsPath: () => string;
  * @returns
  */
 declare const getRuntimePrismaClient: () => PrismaClientLike | undefined;
+declare const getActiveTransactionClient: () => PrismaClientLike | undefined;
+declare const isTransactionCapableClient: (value: unknown) => value is PrismaTransactionCapableClient;
+declare const runArkormTransaction: <TResult>(callback: PrismaTransactionCallback<TResult>, options?: PrismaTransactionOptions) => Promise<TResult>;
 /**
  * Get the configured pagination URL driver factory from runtime config.
  *
@@ -3191,4 +3419,4 @@ declare class URLDriver {
   url(page: number): string;
 }
 //#endregion
-export { ArkormCollection, ArkormException, Attribute, AttributeOptions, CliApp, ForeignKeyBuilder, InitCommand, InlineFactory, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, MigrateRollbackCommand, Migration, MigrationHistoryCommand, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_MODEL_REGEX, Paginator, PrismaDelegateMap, QueryBuilder, SEEDER_BRAND, SchemaBuilder, SeedCommand, Seeder, SeederCallArgument, SeederConstructor, SeederInput, TableBuilder, URLDriver, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationRollbackToPrismaSchema, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationIdentity, buildMigrationRunId, buildMigrationSource, buildModelBlock, buildRelationLine, computeMigrationChecksum, configureArkormRuntime, createMigrationTimestamp, createPrismaAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationFieldName, ensureArkormConfigLoading, escapeRegex, findAppliedMigration, findModelBlock, formatDefaultValue, formatRelationAction, generateMigrationFile, getDefaultStubsPath, getLastMigrationRun, getLatestAppliedMigrations, getMigrationPlan, getRuntimePaginationCurrentPageResolver, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, isMigrationApplied, loadArkormConfig, markMigrationApplied, markMigrationRun, pad, readAppliedMigrationsState, removeAppliedMigration, resetArkormRuntimeForTests, resolveCast, resolveMigrationClassName, resolveMigrationStateFilePath, resolvePrismaType, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName, writeAppliedMigrationsState };
+export { ArkormCollection, ArkormErrorContext, ArkormException, Attribute, AttributeOptions, CliApp, ForeignKeyBuilder, InitCommand, InlineFactory, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, MigrateRollbackCommand, Migration, MigrationHistoryCommand, MissingDelegateException, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_MODEL_REGEX, Paginator, PrismaDelegateMap, QueryBuilder, QueryConstraintException, RelationResolutionException, SEEDER_BRAND, SchemaBuilder, ScopeNotDefinedException, SeedCommand, Seeder, SeederCallArgument, SeederConstructor, SeederInput, TableBuilder, URLDriver, UniqueConstraintResolutionException, UnsupportedAdapterFeatureException, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationRollbackToPrismaSchema, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationIdentity, buildMigrationRunId, buildMigrationSource, buildModelBlock, buildRelationLine, computeMigrationChecksum, configureArkormRuntime, createMigrationTimestamp, createPrismaAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationFieldName, ensureArkormConfigLoading, escapeRegex, findAppliedMigration, findModelBlock, formatDefaultValue, formatRelationAction, generateMigrationFile, getActiveTransactionClient, getDefaultStubsPath, getLastMigrationRun, getLatestAppliedMigrations, getMigrationPlan, getRuntimePaginationCurrentPageResolver, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, isMigrationApplied, isTransactionCapableClient, loadArkormConfig, markMigrationApplied, markMigrationRun, pad, readAppliedMigrationsState, removeAppliedMigration, resetArkormRuntimeForTests, resolveCast, resolveMigrationClassName, resolveMigrationStateFilePath, resolvePrismaType, runArkormTransaction, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName, writeAppliedMigrationsState };