hysteria-orm 10.8.2 → 10.8.3

package/lib/index.d.cts

@@ -5068,18 +5068,17 @@ declare class ModelManager<T extends Model> {
      */
     private executeMssqlMerge;
     /**
-     * @description Updates a record, returns the updated record
-     * @description Model is retrieved from the database using the primary key regardless of any model hooks
+     * @description Updates a record. When returning is provided, re-fetches and returns the updated record; otherwise returns void.
      * @description Can only be used if the model has a primary key, use a massive update if the model has no primary key
      */
-    updateRecord(model: Partial<T>, options?: {
+    updateRecord(pk: string | number, data: Partial<T>, options?: {
         returning?: ModelKey<T>[];
-    }): Promise<ModelWithoutRelations<T>>;
+    }): Promise<ModelWithoutRelations<T> | void>;
     /**
      * @description Deletes a record
      * @description Can only be used if the model has a primary key, use a massive delete if the model has no primary key
      */
-    deleteRecord(model: T): Promise<void>;
+    deleteRecord(pk: string | number): Promise<void>;
     /**
      * @description Returns a query builder instance
      */
@@ -5687,23 +5686,24 @@ type ModelWithoutRelations<T extends Model> = Pick<Omit<T, "*">, ExcludeRelation
  * This type is used as the return type for:
  * - Static find methods: find, findOne, findOneOrFail, findBy, findOneBy, findOneByPrimaryKey
  * - Static retrieval methods: all, first
- * - Static mutation methods: insert, insertMany, upsert, upsertMany, updateRecord, softDelete
+ * - Static mutation methods: insert, insertMany, upsert, upsertMany, updateRecord, softDelete, save
  * - Static refresh method: refresh
  *
  * @example
  * ```typescript
- * // All these methods return ModelQueryResult<User> (or arrays/nullables thereof)
+ * // Find methods return ModelQueryResult<User> (or arrays/nullables thereof)
  * const user1 = await User.findOne({ where: { id: 1 } });
- * const user2 = await User.findOneOrFail({ where: { id: 1 } });
  * const users = await User.find({});
- * const allUsers = await User.all();
- * const newUser = await User.insert({ name: "John" });
  *
- * // Results are plain data objects - use static methods for operations
+ * // Mutation methods return void by default; use returning for data
+ * await User.insert({ name: "John" }); // void
+ * const newUser = await User.insert({ name: "John" }, { returning: ["*"] }); // User
+ *
  * if (user1) {
- *   await User.updateRecord(user1, { name: "Jane" });
- *   await User.refresh(user1);
- *   await User.deleteRecord(user1);
+ *   await User.updateRecord(user1.id, { name: "Jane" }); // void
+ *   const updated = await User.updateRecord(user1.id, { name: "Jane" }, { returning: ["*"] }); // User
+ *   const refreshed = await User.refresh(user1.id);
+ *   await User.deleteRecord(user1.id);
  * }
  * ```
  */
@@ -6240,9 +6240,12 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
      */
     static findOneByPrimaryKey<T extends Model, S extends ModelKey<T>[] = never[], R extends ModelRelation<T>[] = never[]>(this: new () => T | typeof Model, value: string | number, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<FindReturnType<T, S, R> | null>;
     /**
-     * @description Refreshes a model from the database, the model must have a primary key defined
+     * @description Retrieves a fresh copy of a record from the database by primary key
+     * @param pk The primary key value of the record to refresh
+     * @param options Optional transaction/connection options
+     * @returns The refreshed model data or null if not found
      */
-    static refresh<T extends Model>(this: new () => T | typeof Model, model: T, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
+    static refresh<T extends Model>(this: new () => T | typeof Model, pk: string | number, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T> | null>;
     /**
      * @description Saves a new record to the database
      * @warning If not using postgres and the model has no primary key, the model will be saved, but it won't be possible to retrieve it so at that point it will be returned as null, this is not typed as Model | null for type safety reasons
@@ -6286,12 +6289,17 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
         caseConvention?: CaseConvention;
     }): Promise<void>;
     /**
-     * @description Updates a record, returns the updated record
-     * @description Model is retrieved from the database using the primary key regardless of any model hooks
+     * @description Updates a record by primary key. By default returns void; when returning is provided, re-fetches and returns the specified columns.
      * @description Can only be used if the model has a primary key, use a massive update if the model has no primary key
+     * @param pk The primary key value of the record to update
+     * @param updatePayload The partial data to update
+     * @param options Optional transaction/connection options and returning columns
+     * @typeParam R - The returning columns (literal tuple for type inference). Defaults to void.
      * @throws {HysteriaError} If the model has no primary key
      */
-    static updateRecord<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: Partial<T>, updatePayload?: Partial<ModelWithoutRelations<T>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T>>;
+    static updateRecord<T extends Model, const R extends ReturningColumns<T> = undefined>(this: new () => T | typeof Model, pk: string | number, updatePayload: Partial<ModelWithoutRelations<T>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<T, R>>;
     /**
      * @description Finds the first record or creates a new one if it doesn't exist
      */
@@ -6317,28 +6325,39 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
         returning?: R;
     }): Promise<WriteReturnType<T, R>[]>;
     /**
-     * @description Deletes a record to the database
+     * @description Deletes a record from the database by primary key
+     * @param pk The primary key value of the record to delete
+     * @param options Optional transaction/connection options
+     * @throws {HysteriaError} If the model has no primary key
      */
-    static deleteRecord<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: T, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
+    static deleteRecord<T extends Model>(this: new () => T | typeof Model, pk: string | number, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
     /**
-     * @description Saves (inserts or updates) a model instance to the database
-     * @description If the primary key is not set, performs an insert. If set, performs an update.
-     * @description After saving, the instance is updated with the result from the database
-     * @param modelSqlInstance The model instance to save
-     * @param options Optional transaction, connection, or ignoreHooks options
+     * @description Saves (inserts or updates) model data to the database. By default returns void; when returning is provided, returns the specified columns.
+     * @description If the primary key is present in the data, performs an update. If not, performs an insert.
+     * @param modelData The data to save
+     * @param options Optional transaction, connection options and returning columns
+     * @typeParam R - The returning columns (literal tuple for type inference). Defaults to void.
      * @throws {HysteriaError} If the model has no primary key defined
      */
-    static save<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: Partial<T>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T>>;
+    static save<T extends Model, const R extends ReturningColumns<T> = undefined>(this: new () => T | typeof Model, modelData: Partial<ModelWithoutRelations<T>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<T, R>>;
     /**
-     * @description Soft Deletes a record to the database
+     * @description Soft Deletes a record by primary key. By default returns void; when returning is provided, returns the specified columns.
      * @description default column: deletedAt
      * @description default value: The current date and time in UTC timezone in the format "YYYY-MM-DD HH:mm:ss"
      * @description You can override the column and value by providing the column and value on the static properties of the model `softDeleteColumn` and `softDeleteValue`
+     * @param pk The primary key value of the record to soft delete
+     * @param softDeleteOptions Optional column and value overrides
+     * @param options Optional transaction/connection options and returning columns
+     * @typeParam R - The returning columns (literal tuple for type inference). Defaults to void.
      */
-    static softDelete<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: T, softDeleteOptions?: {
+    static softDelete<T extends Model, const R extends ReturningColumns<T> = undefined>(this: new () => T | typeof Model, pk: string | number, softDeleteOptions?: {
         column?: ModelKey<T>;
         value?: string | number | boolean | Date;
-    }, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T>>;
+    }, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<T, R>>;
     /**
      * @description Truncates the table for the given model
      */
@@ -6535,8 +6554,17 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
  */
 interface ColumnDef<T = unknown> {
     readonly _phantom: T;
+    readonly _isPrimary?: boolean;
     readonly _apply: (target: Object, propertyKey: string) => void;
 }
+/**
+ * A column descriptor marked as a primary key.
+ * Used by `col.primary()`, `col.increment()`, and `col.bigIncrement()` to
+ * carry PK type information for `defineModel` type inference.
+ */
+interface PrimaryColumnDef<T = unknown> extends ColumnDef<T> {
+    readonly _isPrimary: true;
+}
 /**
  * Phantom-typed descriptor for a model relation.
  * `T` carries the TypeScript type the relation resolves to at the instance level.
@@ -6624,7 +6652,7 @@ interface ColNamespace {
      * col.primary<number>({ nullable: false })
      * ```
      */
-    primary<T = string | number>(options?: ColPrimaryOptions & TypedSerialize<T> & TypedPrepare<T>): ColumnDef<T>;
+    primary<T = string | number>(options?: ColPrimaryOptions & TypedSerialize<T> & TypedPrepare<T>): PrimaryColumnDef<T>;
     /**
      * VARCHAR column. Accepts an optional `length` option.
      * Type: `string` (nullable-aware).
@@ -6668,12 +6696,12 @@ interface ColNamespace {
      * Auto-incrementing integer primary key. Always non-nullable.
      * Type: `number`. Only `prepare` is exposed.
      */
-    increment(options?: ColIncrementOptions & TypedPrepare<number>): ColumnDef<number>;
+    increment(options?: ColIncrementOptions & TypedPrepare<number>): PrimaryColumnDef<number>;
     /**
      * Auto-incrementing bigint primary key. Always non-nullable.
      * Type: `number`. Only `prepare` is exposed.
      */
-    bigIncrement(options?: ColBigIncrementOptions & TypedPrepare<number>): ColumnDef<number>;
+    bigIncrement(options?: ColBigIncrementOptions & TypedPrepare<number>): PrimaryColumnDef<number>;
     /**
      * Boolean column.
      * Type: `boolean` (nullable-aware). No `serialize` or `prepare` exposed.
@@ -6949,6 +6977,17 @@ type DefineModelOptions<K extends string = string> = {
     softDeleteColumn?: K;
     softDeleteValue?: boolean | string;
 };
+/**
+ * Extracts the primary key column type from a columns definition.
+ * Looks for columns defined with `PrimaryColumnDef` (col.primary, col.increment, col.bigIncrement).
+ * Falls back to `string | number` if no PK column is found.
+ */
+type ExtractPKType<C extends Record<string, ColumnDef>> = {
+    [K in keyof C]: C[K] extends PrimaryColumnDef<infer T> ? T : never;
+}[keyof C];
+type InferPK<C extends Record<string, ColumnDef>> = [
+    ExtractPKType<C>
+] extends [never] ? string | number : ExtractPKType<C>;
 type InferColumns<C extends Record<string, ColumnDef>> = {
     [K in keyof C]: C[K] extends ColumnDef<infer T> ? T : never;
 };
@@ -6982,6 +7021,11 @@ type ModelDefinition<C extends Record<string, ColumnDef> = Record<string, Column
 type ConcreteModelStatics = {
     [K in keyof typeof Model]: (typeof Model)[K];
 };
+/**
+ * Static methods that may have narrowed PK types in DefinedModel.
+ * Excluded from structural checks in AnyModelConstructor.
+ */
+type PKNarrowedMethods = "updateRecord" | "deleteRecord" | "softDelete" | "save" | "refresh";
 /**
  * Union type that accepts both decorator-based model classes (`typeof Model`
  * subclasses) and programmatic models created via `defineModel`.
@@ -6989,7 +7033,7 @@ type ConcreteModelStatics = {
  * Use this instead of `typeof Model` in any user-facing API that should
  * accept either kind of model.
  */
-type AnyModelConstructor = typeof Model | (ConcreteModelStatics & (new (...args: any[]) => Model));
+type AnyModelConstructor = typeof Model | (Omit<ConcreteModelStatics, PKNarrowedMethods> & (new (...args: any[]) => Model));
 /**
  * The return type of `defineModel` – a concrete Model constructor whose
  * instances carry the inferred column + relation properties.
@@ -6997,7 +7041,27 @@ type AnyModelConstructor = typeof Model | (ConcreteModelStatics & (new (...args:
  * Uses a mapped type over `typeof Model` so the abstract flag is stripped,
  * making the result instantiable while keeping all public static members.
  */
-type DefinedModel<C extends Record<string, ColumnDef>, R extends Record<string, RelationDef>> = ConcreteModelStatics & {
+/**
+ * Overrides for static methods that accept a primary key parameter.
+ * Narrows the PK type from `string | number` to the actual inferred PK type.
+ */
+type DefinedModelPKOverrides<C extends Record<string, ColumnDef>, M extends Model> = {
+    updateRecord<const R extends ReturningColumns<M> = undefined>(pk: InferPK<C>, updatePayload: Partial<ModelWithoutRelations<M>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<M, R>>;
+    deleteRecord(pk: InferPK<C>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
+    softDelete<const R extends ReturningColumns<M> = undefined>(pk: InferPK<C>, softDeleteOptions?: {
+        column?: ModelKey<M>;
+        value?: string | number | boolean | Date;
+    }, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<M, R>>;
+    save<const R extends ReturningColumns<M> = undefined>(modelData: Partial<ModelWithoutRelations<M>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<M, R>>;
+    refresh(pk: InferPK<C>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<M> | null>;
+};
+type DefinedModel<C extends Record<string, ColumnDef>, R extends Record<string, RelationDef>> = Omit<ConcreteModelStatics, PKNarrowedMethods> & DefinedModelPKOverrides<C, InferModel<C, R> & Model> & {
     new (): InferModel<C, R> & Model;
 };
 
@@ -8497,4 +8561,4 @@ declare const generateOpenApiModelWithMetadata: <T extends new () => Model>(mode
     $id?: string;
 }>;
 
-export { type AbstractConstructor, type AdminJsActionOptions, type AdminJsAssets, type AdminJsBranding, type AdminJsInstance, type AdminJsLocale, type AdminJsOptions, type AdminJsPage, type AdminJsPropertyOptions, type AdminJsResourceOptions, type AdminJsSettings, type AnyConstructor, type AnyModelConstructor, type AsymmetricEncryptionOptions, type BaseModelMethodOptions, type BaseModelRelationType, BaseSeeder, type BigIntFields, type BuildSelectType, type BuildSingleSelectType, type CacheAdapter, type CacheKeys, type CheckType, ClientMigrator, Collection, type ColumnDataTypeOption, type ColumnDataTypeOptionSimple, type ColumnDataTypeOptionWithBinary, type ColumnDataTypeOptionWithDatePrecision, type ColumnDataTypeOptionWithEnum, type ColumnDataTypeOptionWithLength, type ColumnDataTypeOptionWithPrecision, type ColumnDataTypeOptionWithScaleAndPrecision, type ColumnDataTypeOptionWithText, type ColumnDef, type ColumnOptions, type ColumnType, type CommonDataSourceInput, type ComposeBuildSelect, type ComposeSelect, type ConnectionPolicies, type Constructor, type CustomLogger, type DataSourceInput, type DataSourceType, type DateColumnOptions, type DatetimeColumnOptions, type DefinedModel, type ExcludeMethods, type ExtractColumnName, type ExtractSourceColumn, type FetchHooks, type FindReturnType, type GetColumnType, type GetConnectionReturnType, HysteriaError, InMemoryAdapter, type IncrementFields, type IndexType, type LazyRelationType, type LoggerConfig, type ManyOptions, type ManyToManyOptions, type ManyToManyStringOptions, Migration, type MigrationConfig, type MigrationConfigBase, type MixinColumns, MixinFactory, Model, type ModelDataProperties, type ModelInstanceType, type ModelKey, ModelQueryBuilder, type ModelQueryResult, type ModelRelation, type ModelSelectTuple, type ModelSelectableInput, type ModelWithoutRelations, MongoDataSource, type MongoDataSourceInput$1 as MongoDataSourceInput, type MssqlConnectionInstance, type MssqlDataSourceInput, type MssqlPoolInstance, type MysqlConnectionInstance, type MysqlSqlDataSourceInput, type NotNullableMysqlSqlDataSourceInput, type NotNullableOracleDBDataSourceInput, type NotNullableOracleMssqlDataSourceInput, type NotNullablePostgresSqlDataSourceInput, type NotNullableSqliteDataSourceInput, type NullableColumn, type NumberModelKey, type OneOptions, type OracleDBDataSourceInput, type OracleDBPoolInstance, type PgPoolClientInstance, type PostgresSqlDataSourceInput, QueryBuilder, type RawModelOptions, RawNode, type RawQueryOptions, RedisCacheAdapter, type RedisFetchable, type RedisStorable, type RelModelCallback, type RelatedInstance, type RelationDef, type RelationNullableOption, type RelationQueryBuilderType, type ReplicationType, type ReturningColumns, type ReturningKey, Schema, SchemaBuilder, type SeederConfig, type SelectBrand, type SelectableColumn, type SelectedModel, type SlaveAlgorithm, type SlaveContext, type SqlCloneOptions, SqlDataSource, type SqlDataSourceInput, type SqlDataSourceModel, type SqlDataSourceType, type SqlDriverSpecificOptions, type SqlPoolType, type Sqlite3ConnectionOptions, type SqliteConnectionInstance, type SqliteDataSourceInput, type StartTransactionOptions, type SymmetricEncryptionOptions, type TableFormat, type ThroughModel, type TimestampFields, Transaction, type TransactionExecutionOptions, type TypedPrepare, type TypedPropertyDecorator, type TypedSerialize, type UlidFields, UlidMixin, type UniqueType, type UseCacheReturnType, type UseConnectionInput, type UuidFields, UuidMixin, WriteOperation, type WriteReturnType, belongsTo, bigIntMixin, check, col, column, createMixin, createModelFactory, defineMigrator, defineModel, generateOpenApiModel, generateOpenApiModelSchema, generateOpenApiModelWithMetadata, getChecks, getCollectionProperties, getIndexes, getModelColumns, type getPoolReturnType, getPrimaryKey, getRelations, getRelationsMetadata, getUniques, hasMany, hasOne, incrementMixin, index, HysteriaLogger as logger, manyToMany, property, RedisDataSource as redis, rel, timestampMixin, ulidMixin, unique, uuidMixin, view, withPerformance };
+export { type AbstractConstructor, type AdminJsActionOptions, type AdminJsAssets, type AdminJsBranding, type AdminJsInstance, type AdminJsLocale, type AdminJsOptions, type AdminJsPage, type AdminJsPropertyOptions, type AdminJsResourceOptions, type AdminJsSettings, type AnyConstructor, type AnyModelConstructor, type AsymmetricEncryptionOptions, type BaseModelMethodOptions, type BaseModelRelationType, BaseSeeder, type BigIntFields, type BuildSelectType, type BuildSingleSelectType, type CacheAdapter, type CacheKeys, type CheckType, ClientMigrator, Collection, type ColumnDataTypeOption, type ColumnDataTypeOptionSimple, type ColumnDataTypeOptionWithBinary, type ColumnDataTypeOptionWithDatePrecision, type ColumnDataTypeOptionWithEnum, type ColumnDataTypeOptionWithLength, type ColumnDataTypeOptionWithPrecision, type ColumnDataTypeOptionWithScaleAndPrecision, type ColumnDataTypeOptionWithText, type ColumnDef, type ColumnOptions, type ColumnType, type CommonDataSourceInput, type ComposeBuildSelect, type ComposeSelect, type ConnectionPolicies, type Constructor, type CustomLogger, type DataSourceInput, type DataSourceType, type DateColumnOptions, type DatetimeColumnOptions, type DefinedModel, type ExcludeMethods, type ExtractColumnName, type ExtractSourceColumn, type FetchHooks, type FindReturnType, type GetColumnType, type GetConnectionReturnType, HysteriaError, InMemoryAdapter, type IncrementFields, type IndexType, type InferPK, type LazyRelationType, type LoggerConfig, type ManyOptions, type ManyToManyOptions, type ManyToManyStringOptions, Migration, type MigrationConfig, type MigrationConfigBase, type MixinColumns, MixinFactory, Model, type ModelDataProperties, type ModelInstanceType, type ModelKey, ModelQueryBuilder, type ModelQueryResult, type ModelRelation, type ModelSelectTuple, type ModelSelectableInput, type ModelWithoutRelations, MongoDataSource, type MongoDataSourceInput$1 as MongoDataSourceInput, type MssqlConnectionInstance, type MssqlDataSourceInput, type MssqlPoolInstance, type MysqlConnectionInstance, type MysqlSqlDataSourceInput, type NotNullableMysqlSqlDataSourceInput, type NotNullableOracleDBDataSourceInput, type NotNullableOracleMssqlDataSourceInput, type NotNullablePostgresSqlDataSourceInput, type NotNullableSqliteDataSourceInput, type NullableColumn, type NumberModelKey, type OneOptions, type OracleDBDataSourceInput, type OracleDBPoolInstance, type PgPoolClientInstance, type PostgresSqlDataSourceInput, type PrimaryColumnDef, QueryBuilder, type RawModelOptions, RawNode, type RawQueryOptions, RedisCacheAdapter, type RedisFetchable, type RedisStorable, type RelModelCallback, type RelatedInstance, type RelationDef, type RelationNullableOption, type RelationQueryBuilderType, type ReplicationType, type ReturningColumns, type ReturningKey, Schema, SchemaBuilder, type SeederConfig, type SelectBrand, type SelectableColumn, type SelectedModel, type SlaveAlgorithm, type SlaveContext, type SqlCloneOptions, SqlDataSource, type SqlDataSourceInput, type SqlDataSourceModel, type SqlDataSourceType, type SqlDriverSpecificOptions, type SqlPoolType, type Sqlite3ConnectionOptions, type SqliteConnectionInstance, type SqliteDataSourceInput, type StartTransactionOptions, type SymmetricEncryptionOptions, type TableFormat, type ThroughModel, type TimestampFields, Transaction, type TransactionExecutionOptions, type TypedPrepare, type TypedPropertyDecorator, type TypedSerialize, type UlidFields, UlidMixin, type UniqueType, type UseCacheReturnType, type UseConnectionInput, type UuidFields, UuidMixin, WriteOperation, type WriteReturnType, belongsTo, bigIntMixin, check, col, column, createMixin, createModelFactory, defineMigrator, defineModel, generateOpenApiModel, generateOpenApiModelSchema, generateOpenApiModelWithMetadata, getChecks, getCollectionProperties, getIndexes, getModelColumns, type getPoolReturnType, getPrimaryKey, getRelations, getRelationsMetadata, getUniques, hasMany, hasOne, incrementMixin, index, HysteriaLogger as logger, manyToMany, property, RedisDataSource as redis, rel, timestampMixin, ulidMixin, unique, uuidMixin, view, withPerformance };

package/lib/index.d.ts

@@ -5068,18 +5068,17 @@ declare class ModelManager<T extends Model> {
      */
     private executeMssqlMerge;
     /**
-     * @description Updates a record, returns the updated record
-     * @description Model is retrieved from the database using the primary key regardless of any model hooks
+     * @description Updates a record. When returning is provided, re-fetches and returns the updated record; otherwise returns void.
      * @description Can only be used if the model has a primary key, use a massive update if the model has no primary key
      */
-    updateRecord(model: Partial<T>, options?: {
+    updateRecord(pk: string | number, data: Partial<T>, options?: {
         returning?: ModelKey<T>[];
-    }): Promise<ModelWithoutRelations<T>>;
+    }): Promise<ModelWithoutRelations<T> | void>;
     /**
      * @description Deletes a record
      * @description Can only be used if the model has a primary key, use a massive delete if the model has no primary key
      */
-    deleteRecord(model: T): Promise<void>;
+    deleteRecord(pk: string | number): Promise<void>;
     /**
      * @description Returns a query builder instance
      */
@@ -5687,23 +5686,24 @@ type ModelWithoutRelations<T extends Model> = Pick<Omit<T, "*">, ExcludeRelation
  * This type is used as the return type for:
  * - Static find methods: find, findOne, findOneOrFail, findBy, findOneBy, findOneByPrimaryKey
  * - Static retrieval methods: all, first
- * - Static mutation methods: insert, insertMany, upsert, upsertMany, updateRecord, softDelete
+ * - Static mutation methods: insert, insertMany, upsert, upsertMany, updateRecord, softDelete, save
  * - Static refresh method: refresh
  *
  * @example
  * ```typescript
- * // All these methods return ModelQueryResult<User> (or arrays/nullables thereof)
+ * // Find methods return ModelQueryResult<User> (or arrays/nullables thereof)
  * const user1 = await User.findOne({ where: { id: 1 } });
- * const user2 = await User.findOneOrFail({ where: { id: 1 } });
  * const users = await User.find({});
- * const allUsers = await User.all();
- * const newUser = await User.insert({ name: "John" });
  *
- * // Results are plain data objects - use static methods for operations
+ * // Mutation methods return void by default; use returning for data
+ * await User.insert({ name: "John" }); // void
+ * const newUser = await User.insert({ name: "John" }, { returning: ["*"] }); // User
+ *
  * if (user1) {
- *   await User.updateRecord(user1, { name: "Jane" });
- *   await User.refresh(user1);
- *   await User.deleteRecord(user1);
+ *   await User.updateRecord(user1.id, { name: "Jane" }); // void
+ *   const updated = await User.updateRecord(user1.id, { name: "Jane" }, { returning: ["*"] }); // User
+ *   const refreshed = await User.refresh(user1.id);
+ *   await User.deleteRecord(user1.id);
  * }
  * ```
  */
@@ -6240,9 +6240,12 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
      */
     static findOneByPrimaryKey<T extends Model, S extends ModelKey<T>[] = never[], R extends ModelRelation<T>[] = never[]>(this: new () => T | typeof Model, value: string | number, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<FindReturnType<T, S, R> | null>;
     /**
-     * @description Refreshes a model from the database, the model must have a primary key defined
+     * @description Retrieves a fresh copy of a record from the database by primary key
+     * @param pk The primary key value of the record to refresh
+     * @param options Optional transaction/connection options
+     * @returns The refreshed model data or null if not found
      */
-    static refresh<T extends Model>(this: new () => T | typeof Model, model: T, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
+    static refresh<T extends Model>(this: new () => T | typeof Model, pk: string | number, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T> | null>;
     /**
      * @description Saves a new record to the database
      * @warning If not using postgres and the model has no primary key, the model will be saved, but it won't be possible to retrieve it so at that point it will be returned as null, this is not typed as Model | null for type safety reasons
@@ -6286,12 +6289,17 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
         caseConvention?: CaseConvention;
     }): Promise<void>;
     /**
-     * @description Updates a record, returns the updated record
-     * @description Model is retrieved from the database using the primary key regardless of any model hooks
+     * @description Updates a record by primary key. By default returns void; when returning is provided, re-fetches and returns the specified columns.
      * @description Can only be used if the model has a primary key, use a massive update if the model has no primary key
+     * @param pk The primary key value of the record to update
+     * @param updatePayload The partial data to update
+     * @param options Optional transaction/connection options and returning columns
+     * @typeParam R - The returning columns (literal tuple for type inference). Defaults to void.
      * @throws {HysteriaError} If the model has no primary key
      */
-    static updateRecord<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: Partial<T>, updatePayload?: Partial<ModelWithoutRelations<T>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T>>;
+    static updateRecord<T extends Model, const R extends ReturningColumns<T> = undefined>(this: new () => T | typeof Model, pk: string | number, updatePayload: Partial<ModelWithoutRelations<T>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<T, R>>;
     /**
      * @description Finds the first record or creates a new one if it doesn't exist
      */
@@ -6317,28 +6325,39 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
         returning?: R;
     }): Promise<WriteReturnType<T, R>[]>;
     /**
-     * @description Deletes a record to the database
+     * @description Deletes a record from the database by primary key
+     * @param pk The primary key value of the record to delete
+     * @param options Optional transaction/connection options
+     * @throws {HysteriaError} If the model has no primary key
      */
-    static deleteRecord<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: T, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
+    static deleteRecord<T extends Model>(this: new () => T | typeof Model, pk: string | number, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
     /**
-     * @description Saves (inserts or updates) a model instance to the database
-     * @description If the primary key is not set, performs an insert. If set, performs an update.
-     * @description After saving, the instance is updated with the result from the database
-     * @param modelSqlInstance The model instance to save
-     * @param options Optional transaction, connection, or ignoreHooks options
+     * @description Saves (inserts or updates) model data to the database. By default returns void; when returning is provided, returns the specified columns.
+     * @description If the primary key is present in the data, performs an update. If not, performs an insert.
+     * @param modelData The data to save
+     * @param options Optional transaction, connection options and returning columns
+     * @typeParam R - The returning columns (literal tuple for type inference). Defaults to void.
      * @throws {HysteriaError} If the model has no primary key defined
      */
-    static save<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: Partial<T>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T>>;
+    static save<T extends Model, const R extends ReturningColumns<T> = undefined>(this: new () => T | typeof Model, modelData: Partial<ModelWithoutRelations<T>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<T, R>>;
     /**
-     * @description Soft Deletes a record to the database
+     * @description Soft Deletes a record by primary key. By default returns void; when returning is provided, returns the specified columns.
      * @description default column: deletedAt
      * @description default value: The current date and time in UTC timezone in the format "YYYY-MM-DD HH:mm:ss"
      * @description You can override the column and value by providing the column and value on the static properties of the model `softDeleteColumn` and `softDeleteValue`
+     * @param pk The primary key value of the record to soft delete
+     * @param softDeleteOptions Optional column and value overrides
+     * @param options Optional transaction/connection options and returning columns
+     * @typeParam R - The returning columns (literal tuple for type inference). Defaults to void.
      */
-    static softDelete<T extends Model>(this: new () => T | typeof Model, modelSqlInstance: T, softDeleteOptions?: {
+    static softDelete<T extends Model, const R extends ReturningColumns<T> = undefined>(this: new () => T | typeof Model, pk: string | number, softDeleteOptions?: {
         column?: ModelKey<T>;
         value?: string | number | boolean | Date;
-    }, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<T>>;
+    }, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<T, R>>;
     /**
      * @description Truncates the table for the given model
      */
@@ -6535,8 +6554,17 @@ declare abstract class Model<T extends Model<T> = any> extends Entity {
  */
 interface ColumnDef<T = unknown> {
     readonly _phantom: T;
+    readonly _isPrimary?: boolean;
     readonly _apply: (target: Object, propertyKey: string) => void;
 }
+/**
+ * A column descriptor marked as a primary key.
+ * Used by `col.primary()`, `col.increment()`, and `col.bigIncrement()` to
+ * carry PK type information for `defineModel` type inference.
+ */
+interface PrimaryColumnDef<T = unknown> extends ColumnDef<T> {
+    readonly _isPrimary: true;
+}
 /**
  * Phantom-typed descriptor for a model relation.
  * `T` carries the TypeScript type the relation resolves to at the instance level.
@@ -6624,7 +6652,7 @@ interface ColNamespace {
      * col.primary<number>({ nullable: false })
      * ```
      */
-    primary<T = string | number>(options?: ColPrimaryOptions & TypedSerialize<T> & TypedPrepare<T>): ColumnDef<T>;
+    primary<T = string | number>(options?: ColPrimaryOptions & TypedSerialize<T> & TypedPrepare<T>): PrimaryColumnDef<T>;
     /**
      * VARCHAR column. Accepts an optional `length` option.
      * Type: `string` (nullable-aware).
@@ -6668,12 +6696,12 @@ interface ColNamespace {
      * Auto-incrementing integer primary key. Always non-nullable.
      * Type: `number`. Only `prepare` is exposed.
      */
-    increment(options?: ColIncrementOptions & TypedPrepare<number>): ColumnDef<number>;
+    increment(options?: ColIncrementOptions & TypedPrepare<number>): PrimaryColumnDef<number>;
     /**
      * Auto-incrementing bigint primary key. Always non-nullable.
      * Type: `number`. Only `prepare` is exposed.
      */
-    bigIncrement(options?: ColBigIncrementOptions & TypedPrepare<number>): ColumnDef<number>;
+    bigIncrement(options?: ColBigIncrementOptions & TypedPrepare<number>): PrimaryColumnDef<number>;
     /**
      * Boolean column.
      * Type: `boolean` (nullable-aware). No `serialize` or `prepare` exposed.
@@ -6949,6 +6977,17 @@ type DefineModelOptions<K extends string = string> = {
     softDeleteColumn?: K;
     softDeleteValue?: boolean | string;
 };
+/**
+ * Extracts the primary key column type from a columns definition.
+ * Looks for columns defined with `PrimaryColumnDef` (col.primary, col.increment, col.bigIncrement).
+ * Falls back to `string | number` if no PK column is found.
+ */
+type ExtractPKType<C extends Record<string, ColumnDef>> = {
+    [K in keyof C]: C[K] extends PrimaryColumnDef<infer T> ? T : never;
+}[keyof C];
+type InferPK<C extends Record<string, ColumnDef>> = [
+    ExtractPKType<C>
+] extends [never] ? string | number : ExtractPKType<C>;
 type InferColumns<C extends Record<string, ColumnDef>> = {
     [K in keyof C]: C[K] extends ColumnDef<infer T> ? T : never;
 };
@@ -6982,6 +7021,11 @@ type ModelDefinition<C extends Record<string, ColumnDef> = Record<string, Column
 type ConcreteModelStatics = {
     [K in keyof typeof Model]: (typeof Model)[K];
 };
+/**
+ * Static methods that may have narrowed PK types in DefinedModel.
+ * Excluded from structural checks in AnyModelConstructor.
+ */
+type PKNarrowedMethods = "updateRecord" | "deleteRecord" | "softDelete" | "save" | "refresh";
 /**
  * Union type that accepts both decorator-based model classes (`typeof Model`
  * subclasses) and programmatic models created via `defineModel`.
@@ -6989,7 +7033,7 @@ type ConcreteModelStatics = {
  * Use this instead of `typeof Model` in any user-facing API that should
  * accept either kind of model.
  */
-type AnyModelConstructor = typeof Model | (ConcreteModelStatics & (new (...args: any[]) => Model));
+type AnyModelConstructor = typeof Model | (Omit<ConcreteModelStatics, PKNarrowedMethods> & (new (...args: any[]) => Model));
 /**
  * The return type of `defineModel` – a concrete Model constructor whose
  * instances carry the inferred column + relation properties.
@@ -6997,7 +7041,27 @@ type AnyModelConstructor = typeof Model | (ConcreteModelStatics & (new (...args:
  * Uses a mapped type over `typeof Model` so the abstract flag is stripped,
  * making the result instantiable while keeping all public static members.
  */
-type DefinedModel<C extends Record<string, ColumnDef>, R extends Record<string, RelationDef>> = ConcreteModelStatics & {
+/**
+ * Overrides for static methods that accept a primary key parameter.
+ * Narrows the PK type from `string | number` to the actual inferred PK type.
+ */
+type DefinedModelPKOverrides<C extends Record<string, ColumnDef>, M extends Model> = {
+    updateRecord<const R extends ReturningColumns<M> = undefined>(pk: InferPK<C>, updatePayload: Partial<ModelWithoutRelations<M>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<M, R>>;
+    deleteRecord(pk: InferPK<C>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<void>;
+    softDelete<const R extends ReturningColumns<M> = undefined>(pk: InferPK<C>, softDeleteOptions?: {
+        column?: ModelKey<M>;
+        value?: string | number | boolean | Date;
+    }, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<M, R>>;
+    save<const R extends ReturningColumns<M> = undefined>(modelData: Partial<ModelWithoutRelations<M>>, options?: Omit<BaseModelMethodOptions, "ignoreHooks"> & {
+        returning?: R;
+    }): Promise<WriteReturnType<M, R>>;
+    refresh(pk: InferPK<C>, options?: Omit<BaseModelMethodOptions, "ignoreHooks">): Promise<ModelQueryResult<M> | null>;
+};
+type DefinedModel<C extends Record<string, ColumnDef>, R extends Record<string, RelationDef>> = Omit<ConcreteModelStatics, PKNarrowedMethods> & DefinedModelPKOverrides<C, InferModel<C, R> & Model> & {
     new (): InferModel<C, R> & Model;
 };
 
@@ -8497,4 +8561,4 @@ declare const generateOpenApiModelWithMetadata: <T extends new () => Model>(mode
     $id?: string;
 }>;
 
-export { type AbstractConstructor, type AdminJsActionOptions, type AdminJsAssets, type AdminJsBranding, type AdminJsInstance, type AdminJsLocale, type AdminJsOptions, type AdminJsPage, type AdminJsPropertyOptions, type AdminJsResourceOptions, type AdminJsSettings, type AnyConstructor, type AnyModelConstructor, type AsymmetricEncryptionOptions, type BaseModelMethodOptions, type BaseModelRelationType, BaseSeeder, type BigIntFields, type BuildSelectType, type BuildSingleSelectType, type CacheAdapter, type CacheKeys, type CheckType, ClientMigrator, Collection, type ColumnDataTypeOption, type ColumnDataTypeOptionSimple, type ColumnDataTypeOptionWithBinary, type ColumnDataTypeOptionWithDatePrecision, type ColumnDataTypeOptionWithEnum, type ColumnDataTypeOptionWithLength, type ColumnDataTypeOptionWithPrecision, type ColumnDataTypeOptionWithScaleAndPrecision, type ColumnDataTypeOptionWithText, type ColumnDef, type ColumnOptions, type ColumnType, type CommonDataSourceInput, type ComposeBuildSelect, type ComposeSelect, type ConnectionPolicies, type Constructor, type CustomLogger, type DataSourceInput, type DataSourceType, type DateColumnOptions, type DatetimeColumnOptions, type DefinedModel, type ExcludeMethods, type ExtractColumnName, type ExtractSourceColumn, type FetchHooks, type FindReturnType, type GetColumnType, type GetConnectionReturnType, HysteriaError, InMemoryAdapter, type IncrementFields, type IndexType, type LazyRelationType, type LoggerConfig, type ManyOptions, type ManyToManyOptions, type ManyToManyStringOptions, Migration, type MigrationConfig, type MigrationConfigBase, type MixinColumns, MixinFactory, Model, type ModelDataProperties, type ModelInstanceType, type ModelKey, ModelQueryBuilder, type ModelQueryResult, type ModelRelation, type ModelSelectTuple, type ModelSelectableInput, type ModelWithoutRelations, MongoDataSource, type MongoDataSourceInput$1 as MongoDataSourceInput, type MssqlConnectionInstance, type MssqlDataSourceInput, type MssqlPoolInstance, type MysqlConnectionInstance, type MysqlSqlDataSourceInput, type NotNullableMysqlSqlDataSourceInput, type NotNullableOracleDBDataSourceInput, type NotNullableOracleMssqlDataSourceInput, type NotNullablePostgresSqlDataSourceInput, type NotNullableSqliteDataSourceInput, type NullableColumn, type NumberModelKey, type OneOptions, type OracleDBDataSourceInput, type OracleDBPoolInstance, type PgPoolClientInstance, type PostgresSqlDataSourceInput, QueryBuilder, type RawModelOptions, RawNode, type RawQueryOptions, RedisCacheAdapter, type RedisFetchable, type RedisStorable, type RelModelCallback, type RelatedInstance, type RelationDef, type RelationNullableOption, type RelationQueryBuilderType, type ReplicationType, type ReturningColumns, type ReturningKey, Schema, SchemaBuilder, type SeederConfig, type SelectBrand, type SelectableColumn, type SelectedModel, type SlaveAlgorithm, type SlaveContext, type SqlCloneOptions, SqlDataSource, type SqlDataSourceInput, type SqlDataSourceModel, type SqlDataSourceType, type SqlDriverSpecificOptions, type SqlPoolType, type Sqlite3ConnectionOptions, type SqliteConnectionInstance, type SqliteDataSourceInput, type StartTransactionOptions, type SymmetricEncryptionOptions, type TableFormat, type ThroughModel, type TimestampFields, Transaction, type TransactionExecutionOptions, type TypedPrepare, type TypedPropertyDecorator, type TypedSerialize, type UlidFields, UlidMixin, type UniqueType, type UseCacheReturnType, type UseConnectionInput, type UuidFields, UuidMixin, WriteOperation, type WriteReturnType, belongsTo, bigIntMixin, check, col, column, createMixin, createModelFactory, defineMigrator, defineModel, generateOpenApiModel, generateOpenApiModelSchema, generateOpenApiModelWithMetadata, getChecks, getCollectionProperties, getIndexes, getModelColumns, type getPoolReturnType, getPrimaryKey, getRelations, getRelationsMetadata, getUniques, hasMany, hasOne, incrementMixin, index, HysteriaLogger as logger, manyToMany, property, RedisDataSource as redis, rel, timestampMixin, ulidMixin, unique, uuidMixin, view, withPerformance };
+export { type AbstractConstructor, type AdminJsActionOptions, type AdminJsAssets, type AdminJsBranding, type AdminJsInstance, type AdminJsLocale, type AdminJsOptions, type AdminJsPage, type AdminJsPropertyOptions, type AdminJsResourceOptions, type AdminJsSettings, type AnyConstructor, type AnyModelConstructor, type AsymmetricEncryptionOptions, type BaseModelMethodOptions, type BaseModelRelationType, BaseSeeder, type BigIntFields, type BuildSelectType, type BuildSingleSelectType, type CacheAdapter, type CacheKeys, type CheckType, ClientMigrator, Collection, type ColumnDataTypeOption, type ColumnDataTypeOptionSimple, type ColumnDataTypeOptionWithBinary, type ColumnDataTypeOptionWithDatePrecision, type ColumnDataTypeOptionWithEnum, type ColumnDataTypeOptionWithLength, type ColumnDataTypeOptionWithPrecision, type ColumnDataTypeOptionWithScaleAndPrecision, type ColumnDataTypeOptionWithText, type ColumnDef, type ColumnOptions, type ColumnType, type CommonDataSourceInput, type ComposeBuildSelect, type ComposeSelect, type ConnectionPolicies, type Constructor, type CustomLogger, type DataSourceInput, type DataSourceType, type DateColumnOptions, type DatetimeColumnOptions, type DefinedModel, type ExcludeMethods, type ExtractColumnName, type ExtractSourceColumn, type FetchHooks, type FindReturnType, type GetColumnType, type GetConnectionReturnType, HysteriaError, InMemoryAdapter, type IncrementFields, type IndexType, type InferPK, type LazyRelationType, type LoggerConfig, type ManyOptions, type ManyToManyOptions, type ManyToManyStringOptions, Migration, type MigrationConfig, type MigrationConfigBase, type MixinColumns, MixinFactory, Model, type ModelDataProperties, type ModelInstanceType, type ModelKey, ModelQueryBuilder, type ModelQueryResult, type ModelRelation, type ModelSelectTuple, type ModelSelectableInput, type ModelWithoutRelations, MongoDataSource, type MongoDataSourceInput$1 as MongoDataSourceInput, type MssqlConnectionInstance, type MssqlDataSourceInput, type MssqlPoolInstance, type MysqlConnectionInstance, type MysqlSqlDataSourceInput, type NotNullableMysqlSqlDataSourceInput, type NotNullableOracleDBDataSourceInput, type NotNullableOracleMssqlDataSourceInput, type NotNullablePostgresSqlDataSourceInput, type NotNullableSqliteDataSourceInput, type NullableColumn, type NumberModelKey, type OneOptions, type OracleDBDataSourceInput, type OracleDBPoolInstance, type PgPoolClientInstance, type PostgresSqlDataSourceInput, type PrimaryColumnDef, QueryBuilder, type RawModelOptions, RawNode, type RawQueryOptions, RedisCacheAdapter, type RedisFetchable, type RedisStorable, type RelModelCallback, type RelatedInstance, type RelationDef, type RelationNullableOption, type RelationQueryBuilderType, type ReplicationType, type ReturningColumns, type ReturningKey, Schema, SchemaBuilder, type SeederConfig, type SelectBrand, type SelectableColumn, type SelectedModel, type SlaveAlgorithm, type SlaveContext, type SqlCloneOptions, SqlDataSource, type SqlDataSourceInput, type SqlDataSourceModel, type SqlDataSourceType, type SqlDriverSpecificOptions, type SqlPoolType, type Sqlite3ConnectionOptions, type SqliteConnectionInstance, type SqliteDataSourceInput, type StartTransactionOptions, type SymmetricEncryptionOptions, type TableFormat, type ThroughModel, type TimestampFields, Transaction, type TransactionExecutionOptions, type TypedPrepare, type TypedPropertyDecorator, type TypedSerialize, type UlidFields, UlidMixin, type UniqueType, type UseCacheReturnType, type UseConnectionInput, type UuidFields, UuidMixin, WriteOperation, type WriteReturnType, belongsTo, bigIntMixin, check, col, column, createMixin, createModelFactory, defineMigrator, defineModel, generateOpenApiModel, generateOpenApiModelSchema, generateOpenApiModelWithMetadata, getChecks, getCollectionProperties, getIndexes, getModelColumns, type getPoolReturnType, getPrimaryKey, getRelations, getRelationsMetadata, getUniques, hasMany, hasOne, incrementMixin, index, HysteriaLogger as logger, manyToMany, property, RedisDataSource as redis, rel, timestampMixin, ulidMixin, unique, uuidMixin, view, withPerformance };