arkormx 2.7.0 → 2.8.0

package/dist/{index-C77nMASp.d.mts → index-4mi5sLRA.d.cts}

@@ -1,7 +1,7 @@
-import { Collection } from "@h3ravel/collect.js";
 import { Kysely, Transaction } from "kysely";
-import { Command } from "@h3ravel/musket";
 import { PrismaClient } from "@prisma/client";
+import { Collection } from "@h3ravel/collect.js";
+import { Command } from "@h3ravel/musket";
 
 //#region src/types/migrations.d.ts
 type SchemaColumnType = 'id' | 'uuid' | 'enum' | 'string' | 'text' | 'integer' | 'bigInteger' | 'float' | 'boolean' | 'json' | 'date' | 'timestamp';
@@ -2083,7 +2083,19 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
   protected readonly attributes: Record<string, unknown>;
   protected original: Record<string, unknown>;
   protected changes: Record<string, unknown>;
+  protected previous: Record<string, unknown>;
   protected readonly touchedAttributes: Set<string>;
+  /**
+   * Indicates whether the model corresponds to a row that exists in the
+   * database. Hydrated and freshly inserted models are marked as existing;
+   * models built with `new Model(...)` are not until they are saved.
+   */
+  exists: boolean;
+  /**
+   * Indicates whether the model was inserted during the current lifecycle
+   * (i.e. the last successful save performed a create rather than an update).
+   */
+  wasRecentlyCreated: boolean;
   constructor(attributes?: Record<string, unknown>);
   private static emitDeprecationWarning;
   /**
@@ -2239,6 +2251,48 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   static scope<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, name: string, ...args: unknown[]): QueryBuilder<TModel, TDelegate>;
+  /**
+   * Start a query constrained by the given where clause.
+   *
+   * @param this
+   * @param where
+   * @returns
+   */
+  static where<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, where: QuerySchemaWhere<TDelegate>): QueryBuilder<TModel, TDelegate>;
+  /**
+   * Retrieve all records for the model.
+   *
+   * @param this
+   * @returns
+   */
+  static all<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis): Promise<ArkormCollection<TModel>>;
+  /**
+   * Create and persist a new record, returning the hydrated model instance.
+   *
+   * @param this
+   * @param data
+   * @returns
+   */
+  static create<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, data: ModelCreateData<TModel, TDelegate>): Promise<TModel>;
+  /**
+   * Insert new records or update existing records by one or more unique keys.
+   *
+   * @param this
+   * @param values
+   * @param uniqueBy
+   * @param update
+   * @returns
+   */
+  static upsert<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, values: Array<Record<string, unknown>>, uniqueBy: string | string[], update?: string[] | null): Promise<number>;
+  /**
+   * Delete records by their primary key(s), dispatching model events for each
+   * matched record. Returns the number of records deleted.
+   *
+   * @param this
+   * @param ids
+   * @returns
+   */
+  static destroy<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, ids: string | number | Array<string | number>): Promise<number>;
   /**
    * Get the soft delete configuration for the model, including whether
    * soft deletes are enabled and the name of the deleted at column.
@@ -2297,6 +2351,15 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    */
   update(attributes: Partial<TAttributes>): Promise<boolean>;
   update(attributes: Record<string, unknown>): Promise<boolean>;
+  /**
+   * Update the model and persist it within a transaction, rethrowing on
+   * failure. Unlike update(), errors are not swallowed.
+   *
+   * @param attributes
+   * @returns
+   */
+  updateOrFail(attributes: Partial<TAttributes>): Promise<this>;
+  updateOrFail(attributes: Record<string, unknown>): Promise<this>;
   /**
    * Get the value of an attribute, applying any get mutators or casts if defined.
    *
@@ -2316,8 +2379,10 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
   setAttribute(key: string, value: unknown): this;
   /**
    * Save the model to the database.
-   * If the model has an identifier (id), it will perform an update.
-   * Otherwise, it will perform a create.
+   * If the model already exists in the database it performs an update;
+   * otherwise it performs an insert. Existence is tracked through the
+   * `exists` flag rather than the presence of a primary-key value, so a model
+   * built with an explicit primary key still inserts on its first save.
    *
    * @returns
    */
@@ -2328,6 +2393,13 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   saveQuietly(): Promise<this>;
+  /**
+   * Save the model within a transaction, rolling back and rethrowing if the
+   * operation fails. Unlike update(), this never swallows errors.
+   *
+   * @returns
+   */
+  saveOrFail(): Promise<this>;
   /**
    * Delete the model from the database.
    * If soft deletes are enabled, it will perform a soft delete by
@@ -2343,6 +2415,13 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   deleteQuietly(): Promise<this>;
+  /**
+   * Delete the model within a transaction, rolling back and rethrowing if the
+   * operation fails.
+   *
+   * @returns
+   */
+  deleteOrFail(): Promise<this>;
   /**
    * Permanently delete the model from the database, regardless of whether soft
    * deletes are enabled.
@@ -2443,6 +2522,24 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   wasChanged(keys?: string | string[]): boolean;
+  /**
+   * Get the attributes that were changed during the last successful
+   * persistence operation.
+   *
+   * @returns
+   */
+  getChanges(): Partial<TAttributes>;
+  /**
+   * Get the attribute snapshot that was persisted before the last successful
+   * persistence operation.
+   *
+   * @returns
+   */
+  getPrevious(): Partial<TAttributes>;
+  /**
+   * @param key The attribute key to retrieve the previous value for.
+   */
+  getPrevious<TKey extends keyof TAttributes & string>(key: TKey): TAttributes[TKey] | undefined;
   /**
    * Convert the model instance to a plain object, applying visibility
    * rules, appends, and mutators.
@@ -2676,6 +2773,13 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @param previousOriginal
    */
   private syncChanges;
+  /**
+   * Capture the attribute snapshot that was persisted before the most recent
+   * save so it can be read back via getPrevious().
+   *
+   * @param previousOriginal
+   */
+  private syncPrevious;
   /**
    * Resolve lifecycle state for the provided model class.
    *
@@ -3799,6 +3903,35 @@ declare class QueryBuilder<TModel, TDelegate extends ModelQuerySchemaLike = Mode
    * @returns
    */
   firstOrFail(): Promise<TModel>;
+  /**
+   * Returns the first record matching the given attributes or instantiates a
+   * new, unpersisted model populated with the merged attributes and values.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  firstOrNew(attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<TModel>;
+  /**
+   * Returns the first record matching the given attributes or creates and
+   * persists a new record populated with the merged attributes and values.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  firstOrCreate(attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<TModel>;
+  /**
+   * Returns the first record matching the query, or the result of the
+   * fallback callback when no record exists. An optional column list narrows
+   * the selected columns before the lookup.
+   *
+   * @param columnsOrCallback
+   * @param maybeCallback
+   * @returns
+   */
+  firstOr<TResult>(callback: () => TResult | Promise<TResult>): Promise<TModel | TResult>;
+  firstOr<TResult>(columns: string[], callback: () => TResult | Promise<TResult>): Promise<TModel | TResult>;
   /**
    * Finds a record by a specific key and value.
    * This is a convenience method that is equivalent to
@@ -3925,6 +4058,15 @@ declare class QueryBuilder<TModel, TDelegate extends ModelQuerySchemaLike = Mode
    * @returns
    */
   updateOrInsert(attributes: Record<string, unknown>, values?: Record<string, unknown> | ((exists: boolean) => Record<string, unknown> | Promise<Record<string, unknown>>)): Promise<boolean>;
+  /**
+   * Update the first record matching the given attributes, or create a new
+   * record populated with the merged attributes and values when none exists.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  updateOrCreate(attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<TModel>;
   private shouldFallbackUpdateOrInsertUpsert;
   /**
    * Insert new records or update existing records by one or more unique keys.
@@ -3942,6 +4084,14 @@ declare class QueryBuilder<TModel, TDelegate extends ModelQuerySchemaLike = Mode
    * @returns
    */
   delete(): Promise<TModel | null>;
+  /**
+   * Hydrate a row that was just deleted, marking the resulting model as no
+   * longer existing in the database.
+   *
+   * @param attributes
+   * @returns
+   */
+  private hydrateDeleted;
   /**
    * Deletes the first record matching the current query constraints and throws
    * when no record matches.

package/dist/{index-Dnn0lsDy.d.cts → index-De8zXqTD.d.mts}

@@ -1,7 +1,7 @@
-import { Kysely, Transaction } from "kysely";
-import { PrismaClient } from "@prisma/client";
 import { Collection } from "@h3ravel/collect.js";
+import { Kysely, Transaction } from "kysely";
 import { Command } from "@h3ravel/musket";
+import { PrismaClient } from "@prisma/client";
 
 //#region src/types/migrations.d.ts
 type SchemaColumnType = 'id' | 'uuid' | 'enum' | 'string' | 'text' | 'integer' | 'bigInteger' | 'float' | 'boolean' | 'json' | 'date' | 'timestamp';
@@ -2083,7 +2083,19 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
   protected readonly attributes: Record<string, unknown>;
   protected original: Record<string, unknown>;
   protected changes: Record<string, unknown>;
+  protected previous: Record<string, unknown>;
   protected readonly touchedAttributes: Set<string>;
+  /**
+   * Indicates whether the model corresponds to a row that exists in the
+   * database. Hydrated and freshly inserted models are marked as existing;
+   * models built with `new Model(...)` are not until they are saved.
+   */
+  exists: boolean;
+  /**
+   * Indicates whether the model was inserted during the current lifecycle
+   * (i.e. the last successful save performed a create rather than an update).
+   */
+  wasRecentlyCreated: boolean;
   constructor(attributes?: Record<string, unknown>);
   private static emitDeprecationWarning;
   /**
@@ -2239,6 +2251,48 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   static scope<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, name: string, ...args: unknown[]): QueryBuilder<TModel, TDelegate>;
+  /**
+   * Start a query constrained by the given where clause.
+   *
+   * @param this
+   * @param where
+   * @returns
+   */
+  static where<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, where: QuerySchemaWhere<TDelegate>): QueryBuilder<TModel, TDelegate>;
+  /**
+   * Retrieve all records for the model.
+   *
+   * @param this
+   * @returns
+   */
+  static all<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis): Promise<ArkormCollection<TModel>>;
+  /**
+   * Create and persist a new record, returning the hydrated model instance.
+   *
+   * @param this
+   * @param data
+   * @returns
+   */
+  static create<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, data: ModelCreateData<TModel, TDelegate>): Promise<TModel>;
+  /**
+   * Insert new records or update existing records by one or more unique keys.
+   *
+   * @param this
+   * @param values
+   * @param uniqueBy
+   * @param update
+   * @returns
+   */
+  static upsert<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, values: Array<Record<string, unknown>>, uniqueBy: string | string[], update?: string[] | null): Promise<number>;
+  /**
+   * Delete records by their primary key(s), dispatching model events for each
+   * matched record. Returns the number of records deleted.
+   *
+   * @param this
+   * @param ids
+   * @returns
+   */
+  static destroy<TThis extends abstract new (attributes?: Record<string, unknown>) => Model<any, any>, TModel extends Model<any, any> = InstanceType<TThis>, TDelegate extends ModelQuerySchemaLike = QuerySchemaForModel<TModel extends Model<infer TSchema, any> ? TSchema : Record<string, any>, TModel extends Model<any, infer TAttributes> ? TAttributes : Record<string, any>>>(this: TThis, ids: string | number | Array<string | number>): Promise<number>;
   /**
    * Get the soft delete configuration for the model, including whether
    * soft deletes are enabled and the name of the deleted at column.
@@ -2297,6 +2351,15 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    */
   update(attributes: Partial<TAttributes>): Promise<boolean>;
   update(attributes: Record<string, unknown>): Promise<boolean>;
+  /**
+   * Update the model and persist it within a transaction, rethrowing on
+   * failure. Unlike update(), errors are not swallowed.
+   *
+   * @param attributes
+   * @returns
+   */
+  updateOrFail(attributes: Partial<TAttributes>): Promise<this>;
+  updateOrFail(attributes: Record<string, unknown>): Promise<this>;
   /**
    * Get the value of an attribute, applying any get mutators or casts if defined.
    *
@@ -2316,8 +2379,10 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
   setAttribute(key: string, value: unknown): this;
   /**
    * Save the model to the database.
-   * If the model has an identifier (id), it will perform an update.
-   * Otherwise, it will perform a create.
+   * If the model already exists in the database it performs an update;
+   * otherwise it performs an insert. Existence is tracked through the
+   * `exists` flag rather than the presence of a primary-key value, so a model
+   * built with an explicit primary key still inserts on its first save.
    *
    * @returns
    */
@@ -2328,6 +2393,13 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   saveQuietly(): Promise<this>;
+  /**
+   * Save the model within a transaction, rolling back and rethrowing if the
+   * operation fails. Unlike update(), this never swallows errors.
+   *
+   * @returns
+   */
+  saveOrFail(): Promise<this>;
   /**
    * Delete the model from the database.
    * If soft deletes are enabled, it will perform a soft delete by
@@ -2343,6 +2415,13 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   deleteQuietly(): Promise<this>;
+  /**
+   * Delete the model within a transaction, rolling back and rethrowing if the
+   * operation fails.
+   *
+   * @returns
+   */
+  deleteOrFail(): Promise<this>;
   /**
    * Permanently delete the model from the database, regardless of whether soft
    * deletes are enabled.
@@ -2443,6 +2522,24 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @returns
    */
   wasChanged(keys?: string | string[]): boolean;
+  /**
+   * Get the attributes that were changed during the last successful
+   * persistence operation.
+   *
+   * @returns
+   */
+  getChanges(): Partial<TAttributes>;
+  /**
+   * Get the attribute snapshot that was persisted before the last successful
+   * persistence operation.
+   *
+   * @returns
+   */
+  getPrevious(): Partial<TAttributes>;
+  /**
+   * @param key The attribute key to retrieve the previous value for.
+   */
+  getPrevious<TKey extends keyof TAttributes & string>(key: TKey): TAttributes[TKey] | undefined;
   /**
    * Convert the model instance to a plain object, applying visibility
    * rules, appends, and mutators.
@@ -2676,6 +2773,13 @@ declare abstract class Model<TSchema extends ModelQuerySchemaLike | Record<strin
    * @param previousOriginal
    */
   private syncChanges;
+  /**
+   * Capture the attribute snapshot that was persisted before the most recent
+   * save so it can be read back via getPrevious().
+   *
+   * @param previousOriginal
+   */
+  private syncPrevious;
   /**
    * Resolve lifecycle state for the provided model class.
    *
@@ -3799,6 +3903,35 @@ declare class QueryBuilder<TModel, TDelegate extends ModelQuerySchemaLike = Mode
    * @returns
    */
   firstOrFail(): Promise<TModel>;
+  /**
+   * Returns the first record matching the given attributes or instantiates a
+   * new, unpersisted model populated with the merged attributes and values.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  firstOrNew(attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<TModel>;
+  /**
+   * Returns the first record matching the given attributes or creates and
+   * persists a new record populated with the merged attributes and values.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  firstOrCreate(attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<TModel>;
+  /**
+   * Returns the first record matching the query, or the result of the
+   * fallback callback when no record exists. An optional column list narrows
+   * the selected columns before the lookup.
+   *
+   * @param columnsOrCallback
+   * @param maybeCallback
+   * @returns
+   */
+  firstOr<TResult>(callback: () => TResult | Promise<TResult>): Promise<TModel | TResult>;
+  firstOr<TResult>(columns: string[], callback: () => TResult | Promise<TResult>): Promise<TModel | TResult>;
   /**
    * Finds a record by a specific key and value.
    * This is a convenience method that is equivalent to
@@ -3925,6 +4058,15 @@ declare class QueryBuilder<TModel, TDelegate extends ModelQuerySchemaLike = Mode
    * @returns
    */
   updateOrInsert(attributes: Record<string, unknown>, values?: Record<string, unknown> | ((exists: boolean) => Record<string, unknown> | Promise<Record<string, unknown>>)): Promise<boolean>;
+  /**
+   * Update the first record matching the given attributes, or create a new
+   * record populated with the merged attributes and values when none exists.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  updateOrCreate(attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<TModel>;
   private shouldFallbackUpdateOrInsertUpsert;
   /**
    * Insert new records or update existing records by one or more unique keys.
@@ -3942,6 +4084,14 @@ declare class QueryBuilder<TModel, TDelegate extends ModelQuerySchemaLike = Mode
    * @returns
    */
   delete(): Promise<TModel | null>;
+  /**
+   * Hydrate a row that was just deleted, marking the resulting model as no
+   * longer existing in the database.
+   *
+   * @param attributes
+   * @returns
+   */
+  private hydrateDeleted;
   /**
    * Deletes the first record matching the current query constraints and throws
    * when no record matches.