@veap/database 0.0.0-stage → 0.1.1

package/dist/model.d.ts

@@ -0,0 +1,379 @@
+import { type CastType } from "./casts.js";
+import { ModelQueryBuilder } from "./query-builder.js";
+import { BelongsTo, BelongsToMany, HasMany, HasOne, MorphedByMany, MorphMany, MorphOne, MorphTo, MorphToMany } from "./relations/index.js";
+import type { GlobalScope } from "./scopes.js";
+export declare abstract class Model<Attributes extends Record<string, any> = Record<string, any>> {
+    [key: string]: any;
+    /**
+     * Database table name.
+     */
+    static table: string;
+    /**
+     * Optional polymorphic morph alias (e.g. 'post', 'category', 'user').
+     */
+    static morphAlias?: string;
+    /**
+     * Primary key column name.
+     */
+    static primaryKey: string;
+    /**
+     * Whether to automatically generate UUID v4 for the primary key on creation.
+     */
+    static autoUuid: boolean;
+    /**
+     * Whether the table has timestamp columns.
+     * Can be true (both created_at and updated_at), false (none),
+     * or an array of specific timestamp columns like ["created_at"].
+     */
+    static timestamps: boolean | string[];
+    /**
+     * Attribute type casts dictionary.
+     */
+    static casts: Record<string, CastType>;
+    /**
+     * Whether this model uses soft deletes.
+     */
+    static softDeletes: boolean;
+    /**
+     * Column name used for soft deletes.
+     */
+    static deletedAtColumn: string;
+    /**
+     * Hidden attributes that should not be included in toJSON serialization.
+     */
+    static hidden: string[];
+    /**
+     * Attributes that are mass assignable.
+     * If not empty, only attributes in this array can be mass-assigned.
+     */
+    static fillable: string[];
+    /**
+     * Attributes that are guarded from mass assignment.
+     * If '*' or non-empty, attributes in this array cannot be mass-assigned.
+     */
+    static guarded: string[];
+    /**
+     * Registered global scopes dictionary.
+     */
+    static globalScopes: Record<string, GlobalScope>;
+    /**
+     * Registers a new global scope on this model.
+     */
+    static addGlobalScope(name: string, scope: GlobalScope): void;
+    /**
+     * Checks if a global scope is registered on this model.
+     */
+    static hasGlobalScope(name: string): boolean;
+    /**
+     * Model attributes stored in state.
+     */
+    protected _attributes: Record<string, any>;
+    /**
+     * Original attributes as loaded from database (for dirty tracking).
+     */
+    protected _original: Record<string, any>;
+    /**
+     * Eager-loaded relations.
+     */
+    protected _relations: Record<string, any>;
+    /**
+     * Indicates if the model exists in the database.
+     */
+    isNew: boolean;
+    constructor(attributes?: Partial<Attributes>, isNew?: boolean);
+    get id(): any;
+    set id(value: any);
+    /**
+     * Static Query Builder entrypoint.
+     */
+    static query<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }): ModelQueryBuilder<M>;
+    /**
+     * Starts a query builder including soft-deleted models.
+     */
+    static withTrashed<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }): ModelQueryBuilder<M>;
+    /**
+     * Starts a query builder restricting to only soft-deleted models.
+     */
+    static onlyTrashed<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }): ModelQueryBuilder<M>;
+    /**
+     * Finds a model by primary key.
+     */
+    static find<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, id: any): Promise<M | null>;
+    /**
+     * Finds a model by primary key or throws.
+     */
+    static findOrFail<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, id: any): Promise<M>;
+    /**
+     * Gets all records from table.
+     */
+    static all<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }): Promise<M[]>;
+    /**
+     * Counts rows in table.
+     */
+    static count<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, column?: string): Promise<number>;
+    /**
+     * Starts a WHERE query.
+     */
+    static where<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, column: string | Record<string, any>, operator?: any, value?: any): ModelQueryBuilder<M>;
+    /**
+     * Creates and saves a new model instance.
+     */
+    static create<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, attributes: Record<string, any>): Promise<M>;
+    /**
+     * Creates and saves a new model instance without mass assignment restrictions.
+     */
+    static forceCreate<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, attributes: Record<string, any>): Promise<M>;
+    /**
+     * Finds the first record matching attributes or creates and saves a new instance.
+     */
+    static firstOrCreate<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, attributes: Record<string, any>, values?: Record<string, any>): Promise<M>;
+    /**
+     * Finds the first record matching attributes or instantiates a new instance (unsaved).
+     */
+    static firstOrNew<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, attributes: Record<string, any>, values?: Record<string, any>): Promise<M>;
+    /**
+     * Creates or updates a record matching attributes, filling it with values.
+     */
+    static updateOrCreate<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, attributes: Record<string, any>, values?: Record<string, any>): Promise<M>;
+    /**
+     * Begins querying a relation existence on the model.
+     */
+    static has<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, relation: string, operator?: string, count?: number): ModelQueryBuilder<M>;
+    /**
+     * Begins querying a relation with a callback on the model.
+     */
+    static whereHas<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, relation: string, callback?: (query: ModelQueryBuilder) => void): ModelQueryBuilder<M>;
+    /**
+     * Begins querying a relation absence on the model.
+     */
+    static whereDoesntHave<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, relation: string, callback?: (query: ModelQueryBuilder) => void): ModelQueryBuilder<M>;
+    /**
+     * Begins querying with related models count.
+     */
+    static withCount<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, ...relations: any[]): ModelQueryBuilder<M>;
+    /**
+     * Executes a database transaction.
+     */
+    static transaction<T>(callback: (trx: any) => Promise<T>): Promise<T>;
+    /**
+     * Applies a local scope by name on a new query builder.
+     */
+    static scope<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, name: string, ...args: any[]): ModelQueryBuilder<M>;
+    /**
+     * Excludes a specific global scope on a new query builder.
+     */
+    static withoutGlobalScope<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, scope: string): ModelQueryBuilder<M>;
+    /**
+     * Excludes multiple or all global scopes on a new query builder.
+     */
+    static withoutGlobalScopes<M extends Model>(this: {
+        new (...args: any[]): M;
+        table: string;
+    }, scopes?: string[]): ModelQueryBuilder<M>;
+    /**
+     * Starts a new Factory for this model.
+     * Uses static newFactory() method on the model class.
+     */
+    static factory<F = any>(this: any, count?: number): F;
+    /**
+     * Deletes a model by primary key (soft-deletes if softDeletes is enabled).
+     */
+    static destroy(this: typeof Model, id: any): Promise<boolean>;
+    /**
+     * Permanently deletes a model by primary key regardless of softDeletes setting.
+     */
+    static forceDestroy(this: typeof Model, id: any): Promise<boolean>;
+    /**
+     * Restores a soft-deleted model by primary key.
+     */
+    static restore(this: typeof Model, id: any): Promise<boolean>;
+    /**
+     * Determines if the given attribute may be mass assigned.
+     */
+    isFillable(key: string): boolean;
+    /**
+     * Fills model with mass-assignable attributes.
+     */
+    fill(attributes: Partial<Attributes>): this;
+    /**
+     * Force fills model with attributes, bypassing fillable/guarded protection.
+     */
+    forceFill(attributes: Partial<Attributes>): this;
+    /**
+     * Fires a model lifecycle event.
+     * Calls instance hook methods (e.g. beforeSave/saving) and publishes to eventBus.
+     * If any handler returns false, the operation is canceled.
+     */
+    protected fireModelEvent(event: string): Promise<boolean>;
+    /**
+     * Hydrates attributes from raw database row, applying casts.
+     */
+    hydrate(rawRow: Record<string, any>): this;
+    getAttribute(key: string): any;
+    setAttribute(key: string, value: any): this;
+    isDirty(key?: string): boolean;
+    getRelation<R = any>(name: string): R | undefined;
+    setRelation(name: string, value: any): this;
+    /**
+     * Invokes and returns the Relation instance for a given relation name,
+     * bypassing any cached/loaded relation data in `_relations`.
+     */
+    getRelationDefinition(name: string): any;
+    /**
+     * Saves model to database (INSERT if isNew, UPDATE if exists).
+     */
+    save(): Promise<this>;
+    /**
+     * Updates attributes and saves immediately.
+     */
+    update(attributes: Partial<Attributes>): Promise<this>;
+    /**
+     * Deletes model from database (soft-deletes if softDeletes is enabled).
+     */
+    delete(): Promise<boolean>;
+    /**
+     * Permanently deletes model from database, bypassing soft delete.
+     */
+    forceDelete(): Promise<boolean>;
+    /**
+     * Restores a soft-deleted model.
+     */
+    restore(): Promise<boolean>;
+    /**
+     * Checks if the model has been soft-deleted.
+     */
+    trashed(): boolean;
+    /**
+     * Alias for trashed().
+     */
+    isTrashed(): boolean;
+    /**
+     * Refreshes model attributes from database.
+     */
+    refresh(): Promise<this>;
+    /**
+     * Converts model to JSON object including loaded relations.
+     * Provides both original and camelCase aliases for seamless frontend DX.
+     */
+    toJSON(): Record<string, any>;
+    hasOne<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+    }, foreignKey?: string, localKey?: string): HasOne<this, R>;
+    hasMany<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+    }, foreignKey?: string, localKey?: string): HasMany<this, R>;
+    belongsTo<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+        primaryKey?: string;
+        name?: string;
+    }, foreignKey?: string, ownerKey?: string): BelongsTo<this, R>;
+    belongsToMany<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+        primaryKey?: string;
+        name?: string;
+    }, pivotTable: string, foreignPivotKey?: string, relatedPivotKey?: string, localKey?: string, relatedKey?: string): BelongsToMany<this, R>;
+    /**
+     * Defines a polymorphic, inverse one-to-one or one-to-many relation.
+     * E.g. comment.morphTo('commentable') -> resolves type from commentable_type and id from commentable_id
+     */
+    morphTo<R extends Model = any>(name?: string, type?: string, id?: string): MorphTo<this, R>;
+    /**
+     * Defines a polymorphic one-to-one relation.
+     * E.g. user.morphOne(Image, 'imageable')
+     */
+    morphOne<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+        primaryKey?: string;
+    }, name: string, type?: string, id?: string, localKey?: string): MorphOne<this, R>;
+    /**
+     * Defines a polymorphic one-to-many relation.
+     * E.g. post.morphMany(Comment, 'commentable')
+     */
+    morphMany<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+        primaryKey?: string;
+    }, name: string, type?: string, id?: string, localKey?: string): MorphMany<this, R>;
+    /**
+     * Defines a polymorphic many-to-many relation where the parent is the polymorphic entity.
+     * E.g. post.morphToMany(Tag, 'taggable', 'taggables')
+     */
+    morphToMany<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+        primaryKey?: string;
+        name?: string;
+    }, name: string, pivotTable?: string, foreignPivotKey?: string, relatedPivotKey?: string, parentKey?: string, relatedKey?: string): MorphToMany<this, R>;
+    /**
+     * Defines the inverse of a polymorphic many-to-many relation.
+     * E.g. tag.morphedByMany(BlogPost, 'taggable', 'taggables')
+     */
+    morphedByMany<R extends Model>(related: {
+        new (...args: any[]): R;
+        table: string;
+        primaryKey?: string;
+        name?: string;
+    }, name: string, pivotTable?: string, foreignPivotKey?: string, relatedPivotKey?: string, parentKey?: string, relatedKey?: string): MorphedByMany<this, R>;
+}