@bunyad/orm 0.1.0-alpha.0

package/dist/model-strictness.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Laravel Eloquent strictness + touching guards.
+ * @see Illuminate\Database\Eloquent\Model::preventLazyLoading
+ * @see Model::preventSilentlyDiscardingAttributes
+ * @see Model::preventAccessingMissingAttributes
+ * @see Model::shouldBeStrict
+ * @see Model::withoutTouching
+ */
+export declare function enterEagerLoad(): void;
+export declare function leaveEagerLoad(): void;
+export declare function isInsideEagerLoad(): boolean;
+export declare class LazyLoadingViolationException extends Error {
+    constructor(model: string, relation: string);
+}
+export declare class MassAssignmentException extends Error {
+    constructor(message: string);
+}
+export declare class MissingAttributeException extends Error {
+    constructor(model: string, key: string);
+}
+export declare function modelsShouldPreventLazyLoading(): boolean;
+export declare function modelsShouldPreventSilentlyDiscardingAttributes(): boolean;
+export declare function modelsShouldPreventAccessingMissingAttributes(): boolean;
+export declare function preventLazyLoading(prevent?: boolean): void;
+export declare function preventSilentlyDiscardingAttributes(prevent?: boolean): void;
+export declare function preventAccessingMissingAttributes(prevent?: boolean): void;
+export declare function shouldBeStrict(should?: boolean): void;
+/** Test helper — reset all strictness / touch flags. */
+export declare function resetModelStrictnessForTests(): void;
+export declare function isIgnoringTouch(modelClass?: object): boolean;
+/**
+ * Run without touching parent timestamps (Laravel `Model::withoutTouching`).
+ * Pass model classes to limit the ignore set; omit to ignore all models.
+ */
+export declare function withoutTouching<T>(modelsOrCallback: object[] | (() => T | Promise<T>), callback?: () => T | Promise<T>): Promise<T>;

package/dist/model-strictness.js

@@ -0,0 +1,114 @@
+/**
+ * Laravel Eloquent strictness + touching guards.
+ * @see Illuminate\Database\Eloquent\Model::preventLazyLoading
+ * @see Model::preventSilentlyDiscardingAttributes
+ * @see Model::preventAccessingMissingAttributes
+ * @see Model::shouldBeStrict
+ * @see Model::withoutTouching
+ */
+/** Depth of active eager-load work — `related()` must not trip lazy-load prevention. */
+let eagerLoadDepth = 0;
+export function enterEagerLoad() {
+    eagerLoadDepth += 1;
+}
+export function leaveEagerLoad() {
+    eagerLoadDepth = Math.max(0, eagerLoadDepth - 1);
+}
+export function isInsideEagerLoad() {
+    return eagerLoadDepth > 0;
+}
+let preventsLazyLoading = false;
+let preventsSilentlyDiscardingAttributes = false;
+let preventsAccessingMissingAttributes = false;
+/** Classes currently ignoring touch (empty set = ignore all when flag set). */
+let ignoringTouch = false;
+let ignoringTouchModels = null;
+export class LazyLoadingViolationException extends Error {
+    constructor(model, relation) {
+        super(`Attempted to lazy load [${relation}] on model [${model}] but lazy loading is disabled.`);
+        this.name = "LazyLoadingViolationException";
+    }
+}
+export class MassAssignmentException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MassAssignmentException";
+    }
+}
+export class MissingAttributeException extends Error {
+    constructor(model, key) {
+        super(`The attribute [${key}] either does not exist or was not retrieved for model [${model}].`);
+        this.name = "MissingAttributeException";
+    }
+}
+export function modelsShouldPreventLazyLoading() {
+    return preventsLazyLoading;
+}
+export function modelsShouldPreventSilentlyDiscardingAttributes() {
+    return preventsSilentlyDiscardingAttributes;
+}
+export function modelsShouldPreventAccessingMissingAttributes() {
+    return preventsAccessingMissingAttributes;
+}
+export function preventLazyLoading(prevent = true) {
+    preventsLazyLoading = prevent;
+}
+export function preventSilentlyDiscardingAttributes(prevent = true) {
+    preventsSilentlyDiscardingAttributes = prevent;
+}
+export function preventAccessingMissingAttributes(prevent = true) {
+    preventsAccessingMissingAttributes = prevent;
+}
+export function shouldBeStrict(should = true) {
+    preventLazyLoading(should);
+    preventSilentlyDiscardingAttributes(should);
+    preventAccessingMissingAttributes(should);
+}
+/** Test helper — reset all strictness / touch flags. */
+export function resetModelStrictnessForTests() {
+    preventsLazyLoading = false;
+    preventsSilentlyDiscardingAttributes = false;
+    preventsAccessingMissingAttributes = false;
+    eagerLoadDepth = 0;
+    ignoringTouch = false;
+    ignoringTouchModels = null;
+}
+export function isIgnoringTouch(modelClass) {
+    if (!ignoringTouch)
+        return false;
+    if (!ignoringTouchModels || ignoringTouchModels.size === 0)
+        return true;
+    if (!modelClass)
+        return true;
+    return ignoringTouchModels.has(modelClass);
+}
+/**
+ * Run without touching parent timestamps (Laravel `Model::withoutTouching`).
+ * Pass model classes to limit the ignore set; omit to ignore all models.
+ */
+export async function withoutTouching(modelsOrCallback, callback) {
+    let models = null;
+    let cb;
+    if (typeof modelsOrCallback === "function") {
+        cb = modelsOrCallback;
+    }
+    else {
+        models = modelsOrCallback;
+        if (!callback) {
+            throw new Error("withoutTouching requires a callback.");
+        }
+        cb = callback;
+    }
+    const prevIgnoring = ignoringTouch;
+    const prevModels = ignoringTouchModels;
+    ignoringTouch = true;
+    ignoringTouchModels =
+        models && models.length > 0 ? new Set(models) : null;
+    try {
+        return await cb();
+    }
+    finally {
+        ignoringTouch = prevIgnoring;
+        ignoringTouchModels = prevModels;
+    }
+}

package/dist/model.d.ts

@@ -0,0 +1,490 @@
+import type { Connection, DatabaseManager, DateInput } from "@bunyad/database";
+import { LengthAwarePaginator, CursorPaginator } from "@bunyad/database";
+import { Collection } from "@bunyad/common";
+import { OrmCollection } from "./orm-collection.js";
+import { type CastDefinition } from "./casts.js";
+import { type ModelEventListener, type ModelEventName, type ModelObserver } from "./model-events.js";
+import { type GlobalScopeCallback } from "./scopes.js";
+import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, type MorphToManyOptions } from "./relations.js";
+import { ModelQuery } from "./model-query.js";
+export type { CastType, CastDefinition, EnumCast } from "./casts.js";
+export { Attribute, AsCollection, AsFluent, AsEnumCollection, } from "./casts.js";
+export type { ModelEventName, ModelEventListener, ModelObserver, } from "./model-events.js";
+export { resetModelEventsForTests } from "./model-events.js";
+/** Thrown when a model query returns no results. */
+export declare class ModelNotFoundException extends Error {
+    constructor(message?: string);
+}
+/**
+ * Relation factory on `static relations`.
+ * Parameter is bivariant so subclasses may type `(m: Contact) => …`
+ * without breaking `typeof Contact` assignability to `typeof Model`.
+ */
+export type RelationFactory = {
+    bivarianceHack(model: Model): unknown;
+}["bivarianceHack"];
+export type RelationsMap = Record<string, RelationFactory> | (() => Record<string, RelationFactory>);
+export type ModelClass = typeof Model & {
+    table: string;
+    primaryKey: string;
+    softDeletes?: boolean;
+    deletedAt?: string;
+    /** Property or method (`casts()`). */
+    casts?: Record<string, CastDefinition> | (() => Record<string, CastDefinition>);
+    /** Relation factories (`static relations = { posts: (m) => m.hasMany(Post) }`). */
+    relations?: RelationsMap;
+    hidden?: string[];
+    appends?: string[];
+    fillable?: readonly string[] | string[];
+    guarded?: readonly string[] | string[];
+};
+export type ModelQueryOptions = {
+    withTrashed?: boolean;
+    onlyTrashed?: boolean;
+    eagerLoad?: import("./model-helpers.js").NormalizedEagerRelation[];
+    withoutGlobalScopes?: true | string[];
+    /** Named connection (`User.on('secondary')`) or a Connection handle. */
+    connection?: string | Connection;
+    /**
+     * Nested `where(callback)` group — BelongsTo whereHas must use IN/EXISTS,
+     * not JOIN (nested builders only emit WHERE SQL).
+     */
+    nestedWhereGroup?: boolean;
+};
+/** Resolve a connection name or handle to a live Connection. */
+export declare function resolveConnection(connection?: string | Connection | null): Connection;
+export declare function filterFillable(model: ModelClass, attributes: Record<string, unknown>): Record<string, unknown>;
+/** True when hydrating this row must run cast getters (partial selects often do not). */
+export declare function attributesNeedModelCasts(ctor: ModelClass, attributes: Record<string, unknown>): boolean;
+export declare function canFastFind(ctor: ModelClass): boolean;
+/**
+ * Active Record model — familiar query/relation APIs for app code.
+ */
+export declare class Model {
+    #private;
+    static table: string;
+    static primaryKey: string;
+    /**
+     * `$incrementing` — false for UUID / ULID / assigned keys.
+     * When false, `save()` inserts the primary key instead of `insertGetId`.
+     */
+    static incrementing: boolean;
+    /** `$keyType` (`int` | `string`). */
+    static keyType: "int" | "string";
+    /** Connection name (`"secondary"`) or Connection handle. */
+    static connection?: string | Connection;
+    /** SoftDeletes stand-in (`@SoftDeletes()` sets this). */
+    static softDeletes: boolean;
+    static deletedAt: string;
+    /** Set by `@HasFactory(...)` — call `Model.factory().create()`. */
+    static factory?: () => import("./factory.js").Factory<any>;
+    /** When false, `save()` skips `created_at` / `updated_at`. */
+    static timestamps: boolean;
+    /**
+     * Laravel `$casts` property — prefer `static casts()` when adding enums / Attribute.
+     * May be a plain object or a method returning the map.
+     */
+    static casts: Record<string, CastDefinition> | (() => Record<string, CastDefinition>);
+    /**
+     * Relation definitions. Prefer this over instance methods so you can
+     * `declare product: Product | null` and use `model.product` after eager load,
+     * with `model.related('product')` for the relation query.
+     */
+    static relations: RelationsMap;
+    /**
+     * Laravel `$touches` — relation names whose related models get `touch()` after
+     * this model is saved (or soft-deleted). Honor `withoutTouching`.
+     */
+    static touches: string[];
+    /** Laravel `$hidden`. */
+    static hidden: string[];
+    /** Laravel `$visible` allow-list (empty = all non-hidden). */
+    static visible: string[];
+    /** Laravel `$appends` — accessors included in `toArray()`. */
+    static appends: string[];
+    /** Laravel `$fillable`. */
+    static fillable: readonly string[] | string[];
+    /** Laravel `$guarded` — default guard all until fillable is set. */
+    static guarded: readonly string[] | string[];
+    id: string | number;
+    /** Laravel `$exists` — true after retrieve / successful insert. */
+    get exists(): boolean;
+    set exists(value: boolean);
+    constructor(attributes?: Record<string, unknown>);
+    /**
+     * `newFromBuilder` — hydrate a persisted row (sets `$exists`).
+     * Used by ModelQuery list/find paths.
+     */
+    static newFromBuilder<T extends typeof Model>(this: T, attributes: Record<string, unknown>): InstanceType<T>;
+    /** Snapshot current attributes as the original set. */
+    syncOriginal(): this;
+    /** Current attribute bag (non-function own properties). */
+    getAttributes(): Record<string, unknown>;
+    /**
+     * Laravel `getAttribute` — throws when `preventAccessingMissingAttributes` is on
+     * and the key was not retrieved / does not exist (relations exempt).
+     */
+    getAttribute(key: string): unknown;
+    /** Laravel `isDirty`. */
+    isDirty(...attributes: string[]): boolean;
+    /** Laravel `isClean`. */
+    isClean(...attributes: string[]): boolean;
+    /** Laravel `getDirty`. */
+    getDirty(): Record<string, unknown>;
+    /** Laravel `getOriginal`. */
+    getOriginal(): Record<string, unknown>;
+    getOriginal(key: string): unknown;
+    /** Laravel `getChanges` — attributes changed by the last save. */
+    getChanges(): Record<string, unknown>;
+    /** Laravel `wasChanged`. */
+    wasChanged(...attributes: string[]): boolean;
+    /** Laravel `wasRecentlyCreated`. */
+    wasRecentlyCreated(): boolean;
+    /** Laravel `append`. */
+    append(...attributes: string[]): this;
+    /** Laravel `setAppends`. */
+    setAppends(attributes: string[]): this;
+    /** Laravel `getAppends`. */
+    getAppends(): string[];
+    /** Laravel `getHidden`. */
+    getHidden(): string[];
+    /** Laravel `getVisible`. */
+    getVisible(): string[];
+    /** Laravel `setHidden`. */
+    setHidden(attributes: string[]): this;
+    /** Laravel `setVisible`. */
+    setVisible(attributes: string[]): this;
+    /** Laravel `makeVisible` — show attributes for this instance. */
+    makeVisible(...attributes: string[]): this;
+    /** Laravel `makeHidden` — hide attributes for this instance. */
+    makeHidden(...attributes: string[]): this;
+    /**
+     * Run a callback without touching timestamps (Laravel `Model::withoutTimestamps`).
+     */
+    static withoutTimestamps<T>(this: typeof Model, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Laravel `Model::withoutTouching` — skip parent `touch()` while callback runs.
+     * Pass model classes to limit which models ignore touch; omit for all.
+     */
+    static withoutTouching<T>(this: typeof Model, callback: () => T | Promise<T>): Promise<T>;
+    static withoutTouching<T>(this: typeof Model, models: Array<typeof Model>, callback: () => T | Promise<T>): Promise<T>;
+    /** Whether touch is currently suppressed for this model class. */
+    static isIgnoringTouch(this: typeof Model): boolean;
+    /** Laravel `Model::preventLazyLoading`. */
+    static preventLazyLoading(prevent?: boolean): void;
+    /** Laravel `Model::preventSilentlyDiscardingAttributes`. */
+    static preventSilentlyDiscardingAttributes(prevent?: boolean): void;
+    /** Laravel `Model::preventAccessingMissingAttributes`. */
+    static preventAccessingMissingAttributes(prevent?: boolean): void;
+    /** Laravel `Model::shouldBeStrict` — enable/disable the strictness trio. */
+    static shouldBeStrict(should?: boolean): void;
+    /** Laravel `Model::addGlobalScope`. */
+    static addGlobalScope(this: typeof Model, nameOrScope: string | GlobalScopeCallback, scope?: GlobalScopeCallback): void;
+    /** Laravel `Model::addGlobalScope` removal helper. */
+    static removeGlobalScope(this: typeof Model, name: string): void;
+    /**
+     * Laravel `boot` — runs once per model class before first use.
+     * Prefer registering listeners in `booted()`.
+     */
+    static boot(): void;
+    /**
+     * Laravel `booted` — runs once after `boot`. Typical place for `static::created(...)`.
+     */
+    static booted(): void;
+    /** Ensure this model class has been booted. */
+    static bootIfNotBooted(): void;
+    /** Laravel `Model::observe`. */
+    static observe<T extends Model>(this: abstract new (...args: never[]) => T, observer: ModelObserver<T> | (new () => ModelObserver<T>) | Array<ModelObserver<T> | (new () => ModelObserver<T>)>): void;
+    /** Laravel `Model::withoutEvents`. */
+    static withoutEvents<T>(this: typeof Model, callback: () => T | Promise<T>): T | Promise<T>;
+    static retrieved(callback: ModelEventListener): void;
+    static creating(callback: ModelEventListener): void;
+    static created(callback: ModelEventListener): void;
+    static updating(callback: ModelEventListener): void;
+    static updated(callback: ModelEventListener): void;
+    static saving(callback: ModelEventListener): void;
+    static saved(callback: ModelEventListener): void;
+    static deleting(callback: ModelEventListener): void;
+    static deleted(callback: ModelEventListener): void;
+    static trashed(callback: ModelEventListener): void;
+    static forceDeleting(callback: ModelEventListener): void;
+    static forceDeleted(callback: ModelEventListener): void;
+    static restoring(callback: ModelEventListener): void;
+    static restored(callback: ModelEventListener): void;
+    static replicating(callback: ModelEventListener): void;
+    /** Fire a lifecycle event on this instance. */
+    fireModelEvent(event: ModelEventName): boolean | Promise<boolean>;
+    /** Resolve casts from `casts()` method or `$casts` property. */
+    static getCasts(): Record<string, CastDefinition>;
+    static castAttributes(attributes: Record<string, unknown>, direction: "get" | "set"): Record<string, unknown>;
+    static setConnection(connection: Connection): void;
+    static getConnection(): Connection;
+    /** Laravel `$model->setConnection($name)`. */
+    setConnection(connection: string | Connection): this;
+    /** Active connection for this instance (instance override → model → default). */
+    getConnection(): Connection;
+    static db(): DatabaseManager;
+    /**
+     * Laravel `Model::on($connection)` — same model, different named connection.
+     */
+    static on<T extends typeof Model>(this: T, connection: string): ModelQuery<InstanceType<T>>;
+    /**
+     * Create a model query (honors `@UseBuilder` when present).
+     * Local scopes (`scopeActive` → `.active()`) are available via proxy.
+     */
+    static newQuery<T extends typeof Model>(this: T, options?: ModelQueryOptions): ModelQuery<InstanceType<T>>;
+    /** Laravel `withoutGlobalScopes()`. */
+    static withoutGlobalScopes<T extends typeof Model>(this: T, names?: string[]): ModelQuery<InstanceType<T>>;
+    /** Laravel `withoutGlobalScope($name)`. */
+    static withoutGlobalScope<T extends typeof Model>(this: T, name: string): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::query()` — scoped `ModelQuery` (not a raw table builder). */
+    static query<T extends typeof Model>(this: T, options?: ModelQueryOptions): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::find`. */
+    static find<T extends typeof Model>(this: T, id: string | number): InstanceType<T> | null | Promise<InstanceType<T> | null>;
+    /** Laravel `getRouteKeyName()` — column used for implicit route binding. */
+    static getRouteKeyName(): string;
+    /**
+     * Laravel `resolveRouteBinding` — find by PK or custom `{param:column}` field.
+     */
+    static resolveRouteBinding<T extends typeof Model>(this: T, value: string | number, field?: string): InstanceType<T> | null | Promise<InstanceType<T> | null>;
+    /**
+     * Laravel SoftDeletes `resolveSoftDeletableRouteBinding` — same as
+     * `resolveRouteBinding` but includes soft-deleted rows (`withTrashed()`).
+     * Used by the router when the route opts in via `withTrashed()`.
+     */
+    static resolveSoftDeletableRouteBinding<T extends typeof Model>(this: T, value: string | number, field?: string): InstanceType<T> | null | Promise<InstanceType<T> | null>;
+    /** Laravel `Model::findOrFail`. */
+    static findOrFail<T extends typeof Model>(this: T, id: string | number): Promise<InstanceType<T>>;
+    /** Laravel `Model::all`. */
+    static all<T extends typeof Model>(this: T): Promise<OrmCollection<InstanceType<T>>>;
+    /**
+     * Laravel `Model::get` — same as `query().get()` / `all()`.
+     * Typed helper for autocomplete; Proxy also forwards other terminals.
+     */
+    static get<T extends typeof Model>(this: T): OrmCollection<InstanceType<T>> | Promise<OrmCollection<InstanceType<T>>>;
+    /**
+     * Laravel `Model::pluck($column, $key = null)`.
+     * One column → list Collection; with `key` → keyed Record (see Collection.pluck).
+     */
+    static pluck<T extends typeof Model>(this: T, column: string): Promise<Collection<unknown>>;
+    static pluck<T extends typeof Model>(this: T, column: string, key: string): Promise<Record<string, unknown>>;
+    /** SQLite-only sync `all()` — see `ModelQuery.getSync`. */
+    static allSync<T extends typeof Model>(this: T): OrmCollection<InstanceType<T>>;
+    /** SQLite-only sync `find` — see `ModelQuery.firstSync`. */
+    static findSync<T extends typeof Model>(this: T, id: string | number): InstanceType<T> | null;
+    /** Laravel `Model::where`. */
+    static where<T extends typeof Model>(this: T, callback: (query: ModelQuery<InstanceType<T>>) => void): ModelQuery<InstanceType<T>>;
+    static where<T extends typeof Model>(this: T, column: string, value: unknown): ModelQuery<InstanceType<T>>;
+    static where<T extends typeof Model>(this: T, column: string, op: string, value: unknown): ModelQuery<InstanceType<T>>;
+    /** Karobar-style multi-column LIKE search. */
+    static search<T extends typeof Model>(this: T, columns: string[], term: string): ModelQuery<InstanceType<T>>;
+    /** Start a new query and forward common builder methods (Laravel `__callStatic`). */
+    static orWhere<T extends typeof Model>(this: T, column: string, value: unknown): ModelQuery<InstanceType<T>>;
+    static orWhere<T extends typeof Model>(this: T, column: string, op: string, value: unknown): ModelQuery<InstanceType<T>>;
+    static whereIn<T extends typeof Model>(this: T, column: string, values: unknown[]): ModelQuery<InstanceType<T>>;
+    static whereNull<T extends typeof Model>(this: T, column: string): ModelQuery<InstanceType<T>>;
+    static whereNotNull<T extends typeof Model>(this: T, column: string): ModelQuery<InstanceType<T>>;
+    static orderBy<T extends typeof Model>(this: T, column: string, direction?: "asc" | "desc"): ModelQuery<InstanceType<T>>;
+    static orderByDesc<T extends typeof Model>(this: T, column: string): ModelQuery<InstanceType<T>>;
+    static orderByRaw<T extends typeof Model>(this: T, sql: string): ModelQuery<InstanceType<T>>;
+    /** Karobar alias for `orderByRaw`. */
+    static orderBySql<T extends typeof Model>(this: T, sql: string): ModelQuery<InstanceType<T>>;
+    static latest<T extends typeof Model>(this: T, column?: string): ModelQuery<InstanceType<T>>;
+    static oldest<T extends typeof Model>(this: T, column?: string): ModelQuery<InstanceType<T>>;
+    static limit<T extends typeof Model>(this: T, value: number): ModelQuery<InstanceType<T>>;
+    static take<T extends typeof Model>(this: T, value: number): ModelQuery<InstanceType<T>>;
+    static select<T extends typeof Model>(this: T, ...columns: string[]): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::whereDate`. */
+    static whereDate<T extends typeof Model>(this: T, column: string, value: DateInput): ModelQuery<InstanceType<T>>;
+    static whereDate<T extends typeof Model>(this: T, column: string, op: string, value: DateInput): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::whereNot(closure)`. */
+    static whereNot<T extends typeof Model>(this: T, callback: (query: ModelQuery<InstanceType<T>>) => void): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::orWhereNot(closure)`. */
+    static orWhereNot<T extends typeof Model>(this: T, callback: (query: ModelQuery<InstanceType<T>>) => void): ModelQuery<InstanceType<T>>;
+    /** Laravel `withTrashed()`. */
+    static withTrashed<T extends typeof Model>(this: T): ModelQuery<InstanceType<T>>;
+    /** Laravel `onlyTrashed()`. */
+    static onlyTrashed<T extends typeof Model>(this: T): ModelQuery<InstanceType<T>>;
+    /** Laravel `withoutTrashed()`. */
+    static withoutTrashed<T extends typeof Model>(this: T): ModelQuery<InstanceType<T>>;
+    /** `get()` returns plain row objects. Models are not built. */
+    static rows<T extends typeof Model>(this: T): ModelQuery<InstanceType<T>, "row">;
+    /** Eager-load relations (`with('posts')`, `with({ posts: (q) => q.where(…) })`). */
+    static with<T extends typeof Model>(this: T, ...relations: Array<string | string[] | Record<string, unknown>>): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::whereHas`. */
+    static whereHas<T extends typeof Model>(this: T, relation: string, callback?: (query: ModelQuery) => void): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::whereDoesntHave`. */
+    static whereDoesntHave<T extends typeof Model>(this: T, relation: string, callback?: (query: ModelQuery) => void): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::orWhereHas`. */
+    static orWhereHas<T extends typeof Model>(this: T, relation: string, callback?: (query: ModelQuery) => void): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::whereRelation`. */
+    static whereRelation<T extends typeof Model>(this: T, relation: string, column: string, opOrValue: unknown, value?: unknown): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::orWhereRelation`. */
+    static orWhereRelation<T extends typeof Model>(this: T, relation: string, column: string, opOrValue: unknown, value?: unknown): ModelQuery<InstanceType<T>>;
+    /** `withCount` — `'posts'`, `'posts as post_total'`, a string list, or `{ products: { as: 'productsCount' } }`. */
+    static withCount<T extends typeof Model>(this: T, ...relations: Array<string | string[] | Record<string, unknown>>): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::withSum`. */
+    static withSum<T extends typeof Model>(this: T, relation: string, column: string): ModelQuery<InstanceType<T>>;
+    static withAvg<T extends typeof Model>(this: T, relation: string, column: string): ModelQuery<InstanceType<T>>;
+    static withMin<T extends typeof Model>(this: T, relation: string, column: string): ModelQuery<InstanceType<T>>;
+    static withMax<T extends typeof Model>(this: T, relation: string, column: string): ModelQuery<InstanceType<T>>;
+    static withExists<T extends typeof Model>(this: T, ...relations: string[]): ModelQuery<InstanceType<T>>;
+    static withWhereHas<T extends typeof Model>(this: T, relation: string, callback?: (query: ModelQuery) => void): ModelQuery<InstanceType<T>>;
+    static whereBelongsTo<T extends typeof Model>(this: T, related: Model, relationName?: string): ModelQuery<InstanceType<T>>;
+    static whereAny<T extends typeof Model>(this: T, columns: string[], opOrValue: unknown, value?: unknown): ModelQuery<InstanceType<T>>;
+    static whereAll<T extends typeof Model>(this: T, columns: string[], opOrValue: unknown, value?: unknown): ModelQuery<InstanceType<T>>;
+    static whereNone<T extends typeof Model>(this: T, columns: string[], opOrValue: unknown, value?: unknown): ModelQuery<InstanceType<T>>;
+    static whereKey<T extends typeof Model>(this: T, id: string | number | Array<string | number>): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::whereUuid`. */
+    static whereUuid<T extends typeof Model>(this: T, column: string, value: string): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::whereUlid`. */
+    static whereUlid<T extends typeof Model>(this: T, column: string, value: string): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::join`. */
+    static join<T extends typeof Model>(this: T, table: string, first: string, op: string, second: string): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::leftJoin`. */
+    static leftJoin<T extends typeof Model>(this: T, table: string, first: string, op: string, second: string): ModelQuery<InstanceType<T>>;
+    /** Laravel `Model::paginate`. */
+    static paginate<T extends typeof Model>(this: T, perPage?: number, page?: number, options?: {
+        path?: string;
+        pageName?: string;
+    }): Promise<LengthAwarePaginator<InstanceType<T>>>;
+    /** Laravel `Model::cursorPaginate`. */
+    static cursorPaginate<T extends typeof Model>(this: T, perPage?: number, cursor?: string | null, options?: {
+        path?: string;
+        cursorName?: string;
+    }): Promise<CursorPaginator<InstanceType<T>>>;
+    /** Laravel `Model::create` (respects `$fillable` / `$guarded`). */
+    static create<T extends typeof Model>(this: T, attributes: Record<string, unknown>): InstanceType<T> | Promise<InstanceType<T>>;
+    /** Laravel `Model::forceCreate` — insert every given attribute, ignoring `$fillable`. */
+    static forceCreate<T extends typeof Model>(this: T, useAttrs: Record<string, unknown>): InstanceType<T> | Promise<InstanceType<T>>;
+    /** Laravel `firstOrNew`. */
+    static firstOrNew<T extends typeof Model>(this: T, attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<InstanceType<T>>;
+    /** Laravel `firstOrCreate`. */
+    static firstOrCreate<T extends typeof Model>(this: T, attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<InstanceType<T>>;
+    /** Laravel `updateOrCreate`. */
+    static updateOrCreate<T extends typeof Model>(this: T, attributes: Record<string, unknown>, values?: Record<string, unknown>): Promise<InstanceType<T>>;
+    /**
+     * Bulk insert. Delegates to `ModelQuery.insert` (timestamps stamped when enabled).
+     * Does not fire creating/created events — set tenant/client ids on the rows.
+     */
+    static insert<T extends typeof Model>(this: T, values: Record<string, unknown> | Record<string, unknown>[]): Promise<boolean>;
+    /**
+     * Laravel `Model::upsert` — bulk insert-or-update on unique conflict.
+     * Delegates to `ModelQuery.upsert` (timestamps stamped when enabled).
+     */
+    static upsert<T extends typeof Model>(this: T, values: Record<string, unknown> | Record<string, unknown>[], uniqueBy: string | string[], update?: string[] | null): Promise<number>;
+    /** Laravel `$model->fill($attributes)`. */
+    fill(attributes: Record<string, unknown>): this;
+    /** Laravel `$model->update($attributes)`. */
+    update(attributes: Record<string, unknown>): Promise<this>;
+    save(): this | Promise<this>;
+    /** Laravel `$model->saveQuietly()`. */
+    saveQuietly(): Promise<this>;
+    /** Laravel `$model->refresh()`. */
+    refresh(): Promise<this>;
+    /**
+     * Laravel-style refresh under row lock (`lockForUpdate`).
+     * Reloads this instance from a locked select of the same primary key.
+     */
+    refreshForUpdate(): Promise<this>;
+    /** Laravel `$model->fresh()`. */
+    fresh(): Promise<this | null>;
+    /** Eager-load relations onto this model (`load('posts')` / constrained maps). */
+    load(...relations: Array<string | Record<string, unknown>>): Promise<this>;
+    /** Load only relations that are not already present. */
+    loadMissing(...relations: Array<string | Record<string, unknown>>): Promise<this>;
+    /** Laravel `$model->relationLoaded($key)`. */
+    relationLoaded(key: string): boolean;
+    /**
+     * Laravel `$model->touches($relation)` — whether `$touches` lists this relation.
+     */
+    touches(relation: string): boolean;
+    /**
+     * Laravel `$model->touchOwners()` — touch each relation in `$touches`.
+     * Uses `relation.touch()` when available (BelongsTo / HasOne / HasMany);
+     * otherwise loads the related model and calls `touch()` on it.
+     */
+    touchOwners(): Promise<void>;
+    /**
+     * Laravel `$model->touch()` — bump `updated_at` (no-op while `withoutTouching`).
+     * Saving also runs `$touches` / `touchOwners()` for listed relations.
+     */
+    touch(): Promise<boolean>;
+    /**
+     * Relation query builder (`$model->product()` in Laravel).
+     *
+     * Define relations on `static relations` and declare the loaded property:
+     * `declare product: Product | null` — then use `model.product` after `with('product')`,
+     * and `model.related('product')` when you need the relation query.
+     *
+     * Legacy instance methods named `product()` remain supported via the prototype.
+     */
+    related(name: string): unknown;
+    /** Laravel `$model->replicate()`. */
+    replicate(except?: string[]): this;
+    delete(): Promise<void>;
+    restore(): Promise<void>;
+    forceDelete(): Promise<void>;
+    /** Laravel `$model->deleteQuietly()`. */
+    deleteQuietly(): Promise<void>;
+    trashed(): boolean;
+    /** Laravel `$model->toArray()`. */
+    toArray(): Record<string, unknown>;
+    /** Laravel `$model->loadCount(...$relations)`. */
+    loadCount(...relations: string[]): Promise<this>;
+    /** Laravel `$model->loadSum($relation, $column)`. */
+    loadSum(relation: string, column: string): Promise<this>;
+    loadAvg(relation: string, column: string): Promise<this>;
+    loadMin(relation: string, column: string): Promise<this>;
+    loadMax(relation: string, column: string): Promise<this>;
+    /** Laravel `$model->loadExists(...$relations)`. */
+    loadExists(...relations: string[]): Promise<this>;
+    toJSON(): Record<string, unknown>;
+    /** Alias of {@link toJSON}. */
+    toJson(): Record<string, unknown>;
+    /** Laravel `$model->increment($column, $amount)`. */
+    increment(column: string, amount?: number): Promise<this>;
+    /** Laravel `$model->decrement($column, $amount)`. */
+    decrement(column: string, amount?: number): Promise<this>;
+    /** Laravel `Model::destroy($ids)`. */
+    static destroy<T extends typeof Model>(this: T, ids: Array<string | number> | string | number): Promise<number>;
+    /**
+     * Laravel `Model::forceDestroy($ids)` — permanent delete by key(s).
+     * Soft-delete models are found via `withTrashed()` so trashed rows are included.
+     */
+    static forceDestroy<T extends typeof Model>(this: T, ids: Array<string | number> | string | number): Promise<number>;
+    /** Laravel `$this->hasMany(Related::class)`. */
+    hasMany<R extends ModelClass>(related: R, foreignKey?: string, localKey?: string): HasMany<InstanceType<R>>;
+    /** Laravel `$this->hasOne(Related::class)`. */
+    hasOne<R extends ModelClass>(related: R, foreignKey?: string, localKey?: string): HasOne<InstanceType<R>>;
+    /**
+     * Laravel `$this->hasManyThrough(Related::class, Through::class)`.
+     * Parent → Through (firstKey) → Related (secondKey).
+     */
+    hasManyThrough<R extends ModelClass, TThrough extends ModelClass>(related: R, through: TThrough, firstKey?: string, secondKey?: string, localKey?: string, secondLocalKey?: string): HasManyThrough<InstanceType<R>>;
+    /**
+     * Laravel `$this->hasOneThrough(Related::class, Through::class)`.
+     */
+    hasOneThrough<R extends ModelClass, TThrough extends ModelClass>(related: R, through: TThrough, firstKey?: string, secondKey?: string, localKey?: string, secondLocalKey?: string): HasOneThrough<InstanceType<R>>;
+    /** Laravel `$this->belongsTo(Related::class)`. */
+    belongsTo<R extends ModelClass>(related: R, foreignKey?: string, ownerKey?: string): BelongsTo<InstanceType<R>>;
+    /** Laravel `$this->belongsToMany(Related::class, pivot)`. */
+    belongsToMany<R extends ModelClass>(related: R, table?: string, foreignPivotKey?: string, relatedPivotKey?: string): BelongsToMany<InstanceType<R>>;
+    /**
+     * Polymorphic many-to-many (`model_has_roles`-style pivots).
+     * Third argument may be the pivot table name or an options bag (tenant/legacy morph types).
+     */
+    morphToMany<R extends ModelClass>(related: R, name: string, tableOrOptions?: string | MorphToManyOptions, foreignPivotKey?: string, relatedPivotKey?: string): MorphToMany<InstanceType<R>>;
+    /** Laravel `$this->morphMany(Related::class, name)`. */
+    morphMany<R extends ModelClass>(related: R, name: string, type?: string, id?: string, localKey?: string): MorphMany<InstanceType<R>>;
+    /** Laravel `$this->morphOne(Related::class, name)`. */
+    morphOne<R extends ModelClass>(related: R, name: string, type?: string, id?: string, localKey?: string): MorphOne<InstanceType<R>>;
+    /** Laravel `$this->morphTo($name)`. */
+    morphTo(name: string, type?: string, id?: string, ownerKey?: string): MorphTo;
+}
+/** True when `value` is a Model subclass constructor (O(1) prototype check). */
+export declare function isModelCtor(value: unknown): value is ModelClass;
+export { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, clearMorphMap, morphMap, type MorphToManyOptions, } from "./relations.js";
+export { eagerLoadAggregates, eagerLoadModels, type EagerAggregateSpec, } from "./eager.js";
+export { ModelQuery } from "./model-query.js";
+export { LazyLoadingViolationException, MassAssignmentException, MissingAttributeException, resetModelStrictnessForTests, } from "./model-strictness.js";