Documentation / zerotal / auth / UserModel

Interface: UserModel

Defined in: packages/auth/src/facades/Auth.ts:215

Augmentable interface for the application's concrete user model.

By default it is identical to AuthUser. Apps extend it once to make Auth.user() return the fully-typed model:

Example

// bootstrap/app.ts (or any file imported at boot)
import type { User } from '../app/models/User.ts';

declare module '@zerotal/auth' {
  interface UserModel extends User {}
}

Extends

AuthUser

Attributes & mass assignment

id

id: number

Defined in: packages/orm/src/model/BaseModel.ts:819

Primary-key value. Populated after save inserts a new row, or when the instance is hydrated from the database.

Inherited from

AuthUser.id

fill()

fill(data): this

Defined in: packages/orm/src/model/BaseModel.ts:1235

Mass-assign fields, respecting fillable / guarded protection. Call this instead of Object.assign when data comes from user input.

Guarded by default: a model that declares neither fillable nor guarded (and is not unguarded) rejects every attribute with a MassAssignmentError, so a stray key from a request body can never reach the database. Declare fillable to allow specific columns, or use forceFill for trusted, framework-internal writes.

Accepts UpdatePayload<this> — a partial of the model's writable, non-relation, non-auto-managed columns. Passing id, createdAt, relations, or methods is a compile-time error.

Parameters

data

UpdatePayload<this>

Returns

this

Example

post.fill(ctx.body<UpdatePayload<Post>>());

Throws

when data contains a key not permitted by this model's fillable / guarded configuration.

Inherited from

AuthUser.fill

forceFill()

forceFill(data): this

Defined in: packages/orm/src/model/BaseModel.ts:1277

Mass-assign fields bypassing fillable / guarded protection. Use only for trusted data you construct yourself (framework-internal writes, factories, seeders) — never for request input.

Parameters

data

Record<string, unknown>

Returns

this

Example

// Trusted, non-user data:
role.forceFill({ name, guard });

Inherited from

AuthUser.forceFill

isDirty()

isDirty(column?): boolean

Defined in: packages/orm/src/model/BaseModel.ts:2167

True when the model (or a specific column) has unsaved changes since it was loaded or last saved.

Parameters

column?

string

Returns

boolean

Inherited from

AuthUser.isDirty

$dirty()

$dirty(): Record<string, unknown>

Defined in: packages/orm/src/model/BaseModel.ts:2182

Return a map of changed columns to their current values — the set that a subsequent save would write.

Returns

Record<string, unknown>

Inherited from

AuthUser.$dirty

markDirty()

markDirty(property): this

Defined in: packages/orm/src/model/BaseModel.ts:2202

Force a property to be treated as dirty so it is included in the next save, even if its value is reference-equal to the loaded snapshot (e.g. an in-place mutation of a JSON column).

Parameters

property

keyof UserModel

Returns

this

Inherited from

AuthUser.markDirty

Comparison

is()

is(other): boolean

Defined in: packages/orm/src/model/BaseModel.ts:1900

True when other is the same model class with the same primary key.

Parameters

other

BaseModel | null | undefined

Returns

boolean

Inherited from

AuthUser.is

isNot()

isNot(other): boolean

Defined in: packages/orm/src/model/BaseModel.ts:1915

Inverse of is.

Parameters

other

BaseModel | null | undefined

Returns

boolean

Inherited from

AuthUser.isNot

Other

getAuthId()

getAuthId(): number

Defined in: packages/auth/src/Authenticatable.ts:49

The value stored in the session to identify this user.

Returns

number

Inherited from

AuthUser.getAuthId

getAuthPassword()

getAuthPassword(): string | null

Defined in: packages/auth/src/Authenticatable.ts:54

The hashed password. Returns null when the model uses passwordless auth.

Returns

string | null

Inherited from

AuthUser.getAuthPassword

getRememberToken()

getRememberToken(): string | null

Defined in: packages/auth/src/Authenticatable.ts:59

The hashed "remember me" token, or null when none is set.

Returns

string | null

Inherited from

AuthUser.getRememberToken

setRememberToken()

setRememberToken(value): void

Defined in: packages/auth/src/Authenticatable.ts:66

Set (or clear, with null) the hashed "remember me" token.

Parameters

value

string | null

Returns

void

Inherited from

AuthUser.setRememberToken

getRememberTokenName()

getRememberTokenName(): string

Defined in: packages/auth/src/Authenticatable.ts:71

Database column name backing the remember token.

Returns

string

Inherited from

AuthUser.getRememberTokenName

__isZerotalModel

readonly __isZerotalModel: true

Defined in: packages/orm/src/model/BaseModel.ts:561

Phantom nominal brand, used ONLY at the type level to detect relation properties (see ColumnKeys in payload.ts). Detecting relations by this one marker — rather than structurally via extends BaseModel — avoids forcing TS to re-resolve a related model's fill(data: UpdatePayload<this>) signature, which is itself defined in terms of ColumnKeys. That structural feedback loop is what makes mutually-referential models (A.b: B, B.a: A) trip TS2615 ("circularly references itself in mapped type").

declare => purely type-level, no runtime field is emitted and instances never carry it. The leading underscore keeps it out of column/serialization key sets automatically.

Inherited from

AuthUser.__isZerotalModel

Persistence

save()

save(): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1594

Persist this instance: INSERT when new, or UPDATE of only the dirty columns when it already exists. Applies casts, hashes hashable fields, maintains timestamps, and runs the save/create/update lifecycle hooks. On insert the new primary key (and full row) are read back onto the instance. Returns this.

Returns

Promise<UserModel>

Example

const user = new User();
user.fill({ name: "Ada", email: "ada@example.com" });
await user.save();

Inherited from

AuthUser.save

delete()

delete(): Promise<void>

Defined in: packages/orm/src/model/BaseModel.ts:1754

Delete this record. For soft-delete models this sets deleted_at (the row stays in the table but is hidden from default queries); otherwise it issues a hard DELETE. Runs the before/after delete lifecycle hooks.

Returns

Promise<void>

Inherited from

AuthUser.delete

fresh()

fresh(): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1834

Re-read this record from the database and return it as a new instance, leaving the current one untouched. Use refresh to mutate in place.

Returns

Promise<UserModel>

Throws

when the row no longer exists.

Inherited from

AuthUser.fresh

refresh()

refresh(): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1852

Reload this instance's attributes from the database, mutating it in place. Unlike fresh() (which returns a new instance) this updates this.

Returns

Promise<UserModel>

Throws

when the row no longer exists.

Inherited from

AuthUser.refresh

replicate()

replicate(except?): this

Defined in: packages/orm/src/model/BaseModel.ts:1870

Copy this model into a new unsaved instance. The primary key and timestamps are not copied; pass except to omit additional columns.

Parameters

except?

string[]

Returns

this

Inherited from

AuthUser.replicate

increment()

increment(column, amount?): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1924

Atomically increment a column in the DB and on this instance.

Parameters

column

amount?

number = 1

Returns

Promise<UserModel>

Inherited from

AuthUser.increment

decrement()

decrement(column, amount?): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1933

Atomically decrement a column in the DB and on this instance.

Parameters

column

amount?

number = 1

Returns

Promise<UserModel>

Inherited from

AuthUser.decrement

Relationships

load()

load(relations): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1793

Eager-load the given relations onto this already-fetched model instance. If a relation is already loaded, it is reloaded.

Parameters

relations

string[]

Returns

Promise<UserModel>

Example

const post = await Post.find(1);
await post.load(['comments', 'tags']);
// post.comments is now populated

Inherited from

AuthUser.load

loadMissing()

loadMissing(relations): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1815

Like load(), but skips relations that are already loaded on this instance.

Parameters

relations

string[]

Returns

Promise<UserModel>

Example

await post.loadMissing(['comments']); // no-op if comments already loaded

Inherited from

AuthUser.loadMissing

loadCount()

loadCount(relations): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:1962

Load relation COUNT(s) onto this instance (sets <rel>Count).

Parameters

relations

string | string[]

Returns

Promise<UserModel>

Inherited from

AuthUser.loadCount

loadSum()

loadSum(relation, column): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:2044

Load SUM(column) over a relation onto this instance (sets <rel>Sum<Column>).

Parameters

relation

string

column

string

Returns

Promise<UserModel>

Inherited from

AuthUser.loadSum

loadAvg()

loadAvg(relation, column): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:2052

Load AVG(column) over a relation onto this instance (sets <rel>Avg<Column>).

Parameters

relation

string

column

string

Returns

Promise<UserModel>

Inherited from

AuthUser.loadAvg

loadMin()

loadMin(relation, column): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:2060

Load MIN(column) over a relation onto this instance (sets <rel>Min<Column>).

Parameters

relation

string

column

string

Returns

Promise<UserModel>

Inherited from

AuthUser.loadMin

loadMax()

loadMax(relation, column): Promise<UserModel>

Defined in: packages/orm/src/model/BaseModel.ts:2068

Load MAX(column) over a relation onto this instance (sets <rel>Max<Column>).

Parameters

relation

string

column

string

Returns

Promise<UserModel>

Inherited from

AuthUser.loadMax

associate()

associate(relation, model): this

Defined in: packages/orm/src/model/BaseModel.ts:2116

Set this model's belongsTo foreign key to model and cache the relation. Does not persist — call save() afterwards.

Parameters

relation

string

model

BaseModel

Returns

this

Example

comment.associate('post', post);
await comment.save();

Throws

when relation is not a belongsTo relation on this model.

Inherited from

AuthUser.associate

dissociate()

dissociate(relation): this

Defined in: packages/orm/src/model/BaseModel.ts:2143

Clear this model's belongsTo foreign key and cached relation.

Parameters

relation

string

Returns

this

Throws

when relation is not a belongsTo relation on this model.

Inherited from

AuthUser.dissociate

Serialization

makeHidden()

makeHidden(...keys): this

Defined in: packages/orm/src/model/BaseModel.ts:2077

Hide additional keys from toJSON() for this instance only.

Parameters

keys

...string[]

Returns

this

Inherited from

AuthUser.makeHidden

makeVisible()

makeVisible(...keys): this

Defined in: packages/orm/src/model/BaseModel.ts:2088

Reveal keys that are hidden by the class hidden list, for this instance only.

Parameters

keys

...string[]

Returns

this

Inherited from

AuthUser.makeVisible

append()

append(...keys): this

Defined in: packages/orm/src/model/BaseModel.ts:2099

Add computed accessor name(s) to this instance's toJSON() output.

Parameters

keys

...string[]

Returns

this

Inherited from

AuthUser.append

toJSON()

toJSON(): Record<string, unknown>

Defined in: packages/orm/src/model/BaseModel.ts:2220

Called automatically by JSON.stringify — returns a plain object containing only user-facing data:

• All column values and loaded relation instances (enumerable own props) • Excludes internal ORM state: _original, _exists, _forcedDirty, zerotal* • Excludes any remaining getter guards (unloaded relation lazy-load traps)

Nested model instances (e.g. post.author) also have toJSON(), so JSON.stringify recurses correctly through the full object graph.