@bunyad/orm 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/model.js

@@ -1,12 +1,12 @@
 import { DatabaseManager as Db, setDefaultConnection, connections, LengthAwarePaginator, CursorPaginator, Paginator, dateTimeForStorage, withoutQueryWriteHook, wrapSqlName, } from "@bunyad/database";
-import { Collection } from "@bunyad/common";
+import { Collection, LazyCollection } from "@bunyad/common";
 import { OrmCollection } from "./orm-collection.js";
-import { Attribute, castFromStorage, castToStorage, hashCastValue, isAlreadyHashed, enumFromStorage, enumToStorage, isAttribute, isCastType, isEnumCast, } from "./casts.js";
+import { Attribute, castFromStorage, castToStorage, hashCastValue, isAlreadyHashed, enumFromStorage, enumToStorage, isAttribute, isCastType, parseCast, formatPhpDate, isEnumCast, } from "./casts.js";
 import { bootIfNotBooted, fireModelEvent, hasAnyModelEventListeners, hasModelEventListeners, observeModel, registerModelEvent, withoutModelEvents, } from "./model-events.js";
 import { resolveModelBuilder } from "./decorators.js";
 import { addGlobalScope as registerGlobalScope, getGlobalScopes, hasGlobalScopes, installLocalScopeCallStatic, removeGlobalScope as unregisterGlobalScope, } from "./scopes.js";
 import { deletedAtColumn, normalizeWithRelations, nowForConnection, parseRelationAlias, singular, usesSoftDeletes, } from "./model-helpers.js";
-import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, aggregateRelation, clearMorphMap, morphMap, morphTypeFor, } from "./relations.js";
+import { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, MorphedByMany, aggregateRelation, clearMorphMap, getMorphedModel, enforceMorphMap, morphMap, registerMorphClass, requireMorphMap, morphTypeFor, } from "./relations.js";
 import { eagerLoadAggregates, eagerLoadModels, } from "./eager.js";
 import { ModelQuery, MODEL_QUERY_TARGET } from "./model-query.js";
 import { LazyLoadingViolationException, MassAssignmentException, MissingAttributeException, isIgnoringTouch, isInsideEagerLoad, modelsShouldPreventAccessingMissingAttributes, modelsShouldPreventLazyLoading, modelsShouldPreventSilentlyDiscardingAttributes, preventAccessingMissingAttributes as setPreventAccessingMissingAttributes, preventLazyLoading as setPreventLazyLoading, preventSilentlyDiscardingAttributes as setPreventSilentlyDiscardingAttributes, shouldBeStrict as setShouldBeStrict, withoutTouching as runWithoutTouching, } from "./model-strictness.js";
@@ -69,7 +69,23 @@ function cachedSyncInsertColumns(ctor) {
     });
     return cols;
 }
+/** `Model::unguard()` — global switch. */
+let massAssignmentUnguarded = false;
+/** Whether `key` may be mass assigned (mirrors {@link filterFillable}'s rules). */
+export function canMassAssign(model, key) {
+    if (massAssignmentUnguarded)
+        return true;
+    const fillables = model.fillable ?? [];
+    if (fillables.length > 0)
+        return fillables.includes(key);
+    const guardeds = model.guarded ?? ["*"];
+    if (!guardeds.includes("*"))
+        return !guardeds.includes(key);
+    return true; // empty fillable + guarded ["*"] → allow all (see filterFillable)
+}
 export function filterFillable(model, attributes) {
+    if (massAssignmentUnguarded)
+        return { ...attributes };
     const fillables = model.fillable ?? [];
     const guardeds = model.guarded ?? ["*"];
     const strictDiscard = modelsShouldPreventSilentlyDiscardingAttributes();
@@ -187,6 +203,32 @@ const noCastsCache = new WeakMap();
 const castsResultCache = new WeakMap();
 const hashedColumnsCache = new WeakMap();
 const castShapeCache = new WeakMap();
+/**
+ * Attributes whose cast value is a mutable object (`json`, `array`, `object`,
+ * `collection`). They are compared by content, so an in-place edit
+ * (`row.meta.theme = "dark"`) is dirty and an identical re-assignment is not.
+ */
+const objectCastKeysCache = new WeakMap();
+function objectCastKeys(ctor) {
+    let keys = objectCastKeysCache.get(ctor);
+    if (!keys) {
+        keys = [];
+        for (const [key, definition] of Object.entries(ctor.getCasts())) {
+            if (typeof definition !== "string")
+                continue;
+            const type = parseCast(definition)?.type;
+            if (type === "json" || type === "array" || type === "collection")
+                keys.push(key);
+        }
+        objectCastKeysCache.set(ctor, keys);
+    }
+    return keys;
+}
+function jsonSnapshot(value) {
+    if (value === undefined)
+        return undefined;
+    return JSON.stringify(value);
+}
 /** Reuse DatabaseManager per Connection — avoids `new Db()` on every list build. */
 const dbManagerByConnection = new WeakMap();
 function classHasNoCasts(ctor) {
@@ -382,8 +424,13 @@ export class Model {
     static guarded = ["*"];
     /** Set in constructor / hydrate — avoid empty `{}` alloc before assign. */
     #original;
+    /** Raw (pre-cast) row this model was hydrated from; lets object casts be compared lazily. */
+    #rawRow;
+    /** JSON snapshots of object-cast attributes taken at the last `syncOriginal()`. */
+    #snapshots;
     /** Lazy: allocated on first mutation tracking. */
     #changes;
+    #previous;
     #wasRecentlyCreated = false;
     /**
      * Whether this instance is persisted (`$exists`).
@@ -418,6 +465,8 @@ export class Model {
         assignOwn(self, casted);
         // Avoid a second own-key scan via syncOriginal()/getAttributes() on hydrate.
         this.#original = { ...casted };
+        if (objectCastKeys(ctor).length > 0)
+            this.#rawRow = attributes;
     }
     /**
      * `newFromBuilder` — hydrate a persisted row (sets `$exists`).
@@ -431,8 +480,54 @@ export class Model {
     /** Snapshot current attributes as the original set. */
     syncOriginal() {
         this.#original = this.getAttributes();
+        this.#rawRow = undefined;
+        const keys = objectCastKeys(this.constructor);
+        if (keys.length > 0) {
+            const snapshots = new Map();
+            for (const key of keys) {
+                if (key in this.#original)
+                    snapshots.set(key, jsonSnapshot(this.#original[key]));
+            }
+            this.#snapshots = snapshots;
+        }
+        else {
+            this.#snapshots = undefined;
+        }
         return this;
     }
+    /** JSON of an object-cast attribute as it was when hydrated / last synced. */
+    #objectSnapshot(key) {
+        if (this.#snapshots?.has(key))
+            return this.#snapshots.get(key);
+        const raw = this.#rawRow;
+        if (raw && key in raw) {
+            const definition = this.constructor.getCasts()[key];
+            const parsed = castFromStorage(raw[key], definition);
+            const snapshot = jsonSnapshot(parsed);
+            (this.#snapshots ??= new Map()).set(key, snapshot);
+            return snapshot;
+        }
+        return jsonSnapshot(this.#original?.[key]);
+    }
+    /** The pristine value of `key` (a fresh copy for object casts, so in-place edits don't leak in). */
+    #originalValue(key) {
+        const original = this.#original ?? {};
+        if (objectCastKeys(this.constructor).includes(key) && key in original) {
+            const snapshot = this.#objectSnapshot(key);
+            return snapshot === undefined ? undefined : JSON.parse(snapshot);
+        }
+        return original[key];
+    }
+    /** `$model->only($keys)` — a subset of the attributes (array or varargs; missing keys are skipped). */
+    only(...keys) {
+        const attributes = this.getAttributes();
+        const out = {};
+        for (const key of keys.flat()) {
+            if (Object.prototype.hasOwnProperty.call(attributes, key))
+                out[key] = attributes[key];
+        }
+        return out;
+    }
     /** Current attribute bag (non-function own properties). */
     getAttributes() {
         const out = {};
@@ -493,22 +588,73 @@ export class Model {
     getDirty() {
         const dirty = {};
         const original = this.#original ?? {};
+        const objectKeys = objectCastKeys(this.constructor);
         for (const [key, value] of Object.entries(this.getAttributes())) {
-            if (!Object.is(value, original[key]))
+            if (objectKeys.length > 0 && objectKeys.includes(key) && key in original) {
+                if (jsonSnapshot(value) !== this.#objectSnapshot(key))
+                    dirty[key] = value;
+                continue;
+            }
+            const before = original[key];
+            // Equal instants are not a change (`row.born = new Date(sameTime)`).
+            if (value instanceof Date && before instanceof Date) {
+                if (value.getTime() !== before.getTime())
+                    dirty[key] = value;
+                continue;
+            }
+            if (!Object.is(value, before))
                 dirty[key] = value;
         }
         return dirty;
     }
     getOriginal(key) {
         const original = this.#original ?? {};
-        if (key === undefined)
-            return { ...original };
-        return original[key];
+        if (key === undefined) {
+            const out = { ...original };
+            for (const objectKey of objectCastKeys(this.constructor)) {
+                if (objectKey in out)
+                    out[objectKey] = this.#originalValue(objectKey);
+            }
+            return out;
+        }
+        return this.#originalValue(key);
     }
     /** `getChanges` — attributes changed by the last save. */
     getChanges() {
         return this.#changes ? { ...this.#changes } : {};
     }
+    getPrevious(key) {
+        const previous = this.#previous ?? {};
+        if (key === undefined)
+            return { ...previous };
+        return previous[key];
+    }
+    /** `getChanges()` / `getPrevious()` for the write that just happened (set before `created` / `updated`). */
+    #recordChanges(dirty, exists, usesTimestamps) {
+        const row = this;
+        this.#changes = { ...dirty };
+        if (usesTimestamps) {
+            if ("updated_at" in row && (!exists || "updated_at" in dirty || Object.keys(dirty).length > 0)) {
+                this.#changes.updated_at = row.updated_at;
+            }
+            if (!exists && "created_at" in row) {
+                this.#changes.created_at = row.created_at;
+            }
+        }
+        this.#capturePrevious(!exists);
+    }
+    #capturePrevious(created = false) {
+        const original = this.#original ?? {};
+        const previous = {};
+        if (!created) {
+            for (const key of Object.keys(this.#changes ?? {})) {
+                if (Object.prototype.hasOwnProperty.call(original, key)) {
+                    previous[key] = this.#originalValue(key);
+                }
+            }
+        }
+        this.#previous = previous;
+    }
     /** `wasChanged`. */
     wasChanged(...attributes) {
         const changes = this.#changes;
@@ -609,6 +755,39 @@ export class Model {
     static preventLazyLoading(prevent = true) {
         setPreventLazyLoading(prevent);
     }
+    /** `Model::unguard()` — disable mass-assignment protection (seeders, imports). */
+    static unguard(state = true) {
+        massAssignmentUnguarded = state;
+    }
+    /** `Model::reguard()`. */
+    static reguard() {
+        massAssignmentUnguarded = false;
+    }
+    /** `Model::isUnguarded()`. */
+    static isUnguarded() {
+        return massAssignmentUnguarded;
+    }
+    /** `Model::unguarded(callback)` — run with protection off, then restore it. */
+    static unguarded(callback) {
+        if (massAssignmentUnguarded)
+            return callback();
+        massAssignmentUnguarded = true;
+        let result;
+        try {
+            result = callback();
+        }
+        catch (error) {
+            massAssignmentUnguarded = false;
+            throw error;
+        }
+        if (result instanceof Promise) {
+            return result.finally(() => {
+                massAssignmentUnguarded = false;
+            });
+        }
+        massAssignmentUnguarded = false;
+        return result;
+    }
     /** `Model::preventSilentlyDiscardingAttributes`. */
     static preventSilentlyDiscardingAttributes(prevent = true) {
         setPreventSilentlyDiscardingAttributes(prevent);
@@ -646,6 +825,7 @@ export class Model {
     static booted() { }
     /** Ensure this model class has been booted. */
     static bootIfNotBooted() {
+        registerMorphClass(this);
         bootIfNotBooted(this);
     }
     /** `Model::observe`. */
@@ -654,7 +834,8 @@ export class Model {
     }
     /** `Model::withoutEvents`. */
     static withoutEvents(callback) {
-        return withoutModelEvents(this, callback);
+        // Called on `Model` itself it mutes every model class.
+        return withoutModelEvents(this, callback, this === Model);
     }
     static retrieved(callback) {
         registerModelEvent(this, "retrieved", callback);
@@ -712,6 +893,13 @@ export class Model {
             return cached;
         const field = this.casts;
         const value = typeof field === "function" ? (field.call(this) ?? {}) : (field ?? {});
+        for (const [key, definition] of Object.entries(value)) {
+            if (typeof definition === "string" && !isCastType(definition)) {
+                throw new Error(`Unknown cast type "${definition}" for ${this.name ?? "Model"}.${key}. ` +
+                    `Supported: boolean, integer, float, decimal[:N], string, bigint, json, array, object, collection, ` +
+                    `date[:FORMAT], datetime[:FORMAT], immutable_date, immutable_datetime, encrypted[:json|:array|:collection], hashed.`);
+            }
+        }
         castsResultCache.set(this, value);
         return value;
     }
@@ -930,11 +1118,387 @@ export class Model {
             return q.where(columnOrCallback, opOrValue);
         return q.where(columnOrCallback, String(opOrValue), value);
     }
-    /** Karobar-style multi-column LIKE search. */
+    /** Multi-column LIKE search. */
     static search(columns, term) {
         this.bootIfNotBooted();
         return this.newQuery().search(columns, term);
     }
+    // Terminal forwarders take `any[]` on purpose: an app may define its own static with the same name
+    // (`static exists(id)`), and a stricter base signature would make `typeof User` stop satisfying `typeof Model`.
+    // ── Query-builder forwarding (`__callStatic`): `User.whereBetween(...)`, `User.has('posts')`, … ──
+    static whereBetween(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereBetween"](...args);
+    }
+    static whereNotBetween(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereNotBetween"](...args);
+    }
+    static whereNotIn(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereNotIn"](...args);
+    }
+    static whereRaw(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereRaw"](...args);
+    }
+    static whereColumn(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereColumn"](...args);
+    }
+    static whereLike(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereLike"](...args);
+    }
+    static whereNotLike(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereNotLike"](...args);
+    }
+    static whereDay(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereDay"](...args);
+    }
+    static whereMonth(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereMonth"](...args);
+    }
+    static whereYear(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereYear"](...args);
+    }
+    static orWhereIn(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereIn"](...args);
+    }
+    static orWhereNotIn(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereNotIn"](...args);
+    }
+    static orWhereNull(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereNull"](...args);
+    }
+    static orWhereNotNull(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereNotNull"](...args);
+    }
+    static orWhereBetween(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereBetween"](...args);
+    }
+    static orWhereNotBetween(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereNotBetween"](...args);
+    }
+    static orWhereColumn(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereColumn"](...args);
+    }
+    static orWhereRaw(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereRaw"](...args);
+    }
+    static orWhereLike(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereLike"](...args);
+    }
+    static orWhereNotLike(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereNotLike"](...args);
+    }
+    static groupBy(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["groupBy"](...args);
+    }
+    static having(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["having"](...args);
+    }
+    static havingRaw(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["havingRaw"](...args);
+    }
+    static selectRaw(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["selectRaw"](...args);
+    }
+    static addSelect(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["addSelect"](...args);
+    }
+    static distinct(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["distinct"](...args);
+    }
+    static inRandomOrder(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["inRandomOrder"](...args);
+    }
+    static reorder(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["reorder"](...args);
+    }
+    static offset(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["offset"](...args);
+    }
+    static skip(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["skip"](...args);
+    }
+    static lockForUpdate(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["lockForUpdate"](...args);
+    }
+    static sharedLock(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["sharedLock"](...args);
+    }
+    static has(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["has"](...args);
+    }
+    static doesntHave(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["doesntHave"](...args);
+    }
+    static orHas(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orHas"](...args);
+    }
+    static orDoesntHave(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orDoesntHave"](...args);
+    }
+    static orWhereDoesntHave(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereDoesntHave"](...args);
+    }
+    static whereHasMorph(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereHasMorph"](...args);
+    }
+    static orWhereHasMorph(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereHasMorph"](...args);
+    }
+    static whereDoesntHaveMorph(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereDoesntHaveMorph"](...args);
+    }
+    static orWhereDoesntHaveMorph(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereDoesntHaveMorph"](...args);
+    }
+    static hasMorph(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["hasMorph"](...args);
+    }
+    static doesntHaveMorph(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["doesntHaveMorph"](...args);
+    }
+    static whereMorphedTo(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereMorphedTo"](...args);
+    }
+    static whereNotMorphedTo(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereNotMorphedTo"](...args);
+    }
+    static orWhereMorphedTo(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereMorphedTo"](...args);
+    }
+    static orWhereNotMorphedTo(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereNotMorphedTo"](...args);
+    }
+    static whereMorphRelation(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereMorphRelation"](...args);
+    }
+    static orWhereMorphRelation(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereMorphRelation"](...args);
+    }
+    static whereKeyNot(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["whereKeyNot"](...args);
+    }
+    static orWhereBelongsTo(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereBelongsTo"](...args);
+    }
+    static orWhereAny(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereAny"](...args);
+    }
+    static orWhereAll(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereAll"](...args);
+    }
+    static orWhereNone(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["orWhereNone"](...args);
+    }
+    static withAggregate(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["withAggregate"](...args);
+    }
+    static withAttributes(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["withAttributes"](...args);
+    }
+    static withCasts(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["withCasts"](...args);
+    }
+    static rightJoin(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["rightJoin"](...args);
+    }
+    static when(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["when"](...args);
+    }
+    static unless(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["unless"](...args);
+    }
+    static tap(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["tap"](...args);
+    }
+    static forPage(...args) {
+        this.bootIfNotBooted();
+        return this.newQuery()["forPage"](...args);
+    }
+    static firstWhere(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["firstWhere"].apply(q, args);
+    }
+    static findMany(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["findMany"].apply(q, args);
+    }
+    static findOr(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["findOr"].apply(q, args);
+    }
+    static findOrNew(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["findOrNew"].apply(q, args);
+    }
+    static firstOr(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["firstOr"].apply(q, args);
+    }
+    static chunk(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["chunk"].apply(q, args);
+    }
+    static chunkById(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["chunkById"].apply(q, args);
+    }
+    static chunkByIdDesc(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["chunkByIdDesc"].apply(q, args);
+    }
+    static dd(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["dd"].apply(q, args);
+    }
+    static dump(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["dump"].apply(q, args);
+    }
+    static toBase(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["toBase"].apply(q, args);
+    }
+    static count(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["count"].apply(q, args);
+    }
+    static sum(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["sum"].apply(q, args);
+    }
+    static avg(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["avg"].apply(q, args);
+    }
+    static min(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["min"].apply(q, args);
+    }
+    static max(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["max"].apply(q, args);
+    }
+    static exists(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["exists"].apply(q, args);
+    }
+    static doesntExist(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["doesntExist"].apply(q, args);
+    }
+    static sole(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["sole"].apply(q, args);
+    }
+    static soleValue(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["soleValue"].apply(q, args);
+    }
+    static valueOrFail(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["valueOrFail"].apply(q, args);
+    }
+    static toSql(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["toSql"].apply(q, args);
+    }
+    static toRawSql(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["toRawSql"].apply(q, args);
+    }
+    static getBindings(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["getBindings"].apply(q, args);
+    }
+    static firstOrFail(...args) {
+        this.bootIfNotBooted();
+        const q = this.newQuery();
+        return q["firstOrFail"].apply(q, args);
+    }
     static orWhere(column, opOrValue, value) {
         this.bootIfNotBooted();
         const q = this.newQuery();
@@ -965,7 +1529,7 @@ export class Model {
         this.bootIfNotBooted();
         return this.newQuery().orderByRaw(sql);
     }
-    /** Karobar alias for `orderByRaw`. */
+    /** Alias for `orderByRaw`. */
     static orderBySql(sql) {
         return this.orderByRaw(sql);
     }
@@ -995,15 +1559,15 @@ export class Model {
             return q.whereDate(column, opOrValue);
         return q.whereDate(column, String(opOrValue), value);
     }
-    /** `Model::whereNot(closure)`. */
-    static whereNot(callback) {
+    static whereNot(...args) {
         this.bootIfNotBooted();
-        return this.newQuery().whereNot(callback);
+        const q = this.newQuery();
+        return q.whereNot(...args);
     }
-    /** `Model::orWhereNot(closure)`. */
-    static orWhereNot(callback) {
+    static orWhereNot(...args) {
         this.bootIfNotBooted();
-        return this.newQuery().orWhereNot(callback);
+        const q = this.newQuery();
+        return q.orWhereNot(...args);
     }
     /** `withTrashed()`. */
     static withTrashed() {
@@ -1138,18 +1702,42 @@ export class Model {
     static async cursorPaginate(perPage = 15, cursor = null, options = {}) {
         return this.newQuery().cursorPaginate(perPage, cursor, options);
     }
+    /** `Model::cursor()`: stream models from a single query. */
+    static cursor(chunkSize) {
+        return this.newQuery().cursor(chunkSize);
+    }
+    /** `Model::lazy()`: chunked iteration, one query per chunk. */
+    static lazy(chunkSize) {
+        return this.newQuery().lazy(chunkSize);
+    }
+    /** `Model::lazyById()`: chunked iteration by primary key (safe while updating). */
+    static lazyById(chunkSize, column) {
+        return this.newQuery().lazyById(chunkSize, column);
+    }
+    /** `Model::lazyByIdDesc()`. */
+    static lazyByIdDesc(chunkSize, column) {
+        return this.newQuery().lazyByIdDesc(chunkSize, column);
+    }
     /** `Model::create` (respects `$fillable` / `$guarded`). */
     static create(attributes) {
         this.bootIfNotBooted();
         return this.forceCreate(filterFillable(this, attributes));
     }
     /** `Model::forceCreate` — insert every given attribute, ignoring `$fillable`. */
-    static forceCreate(useAttrs) {
+    static forceCreate(useAttrs, beforeSave) {
         this.bootIfNotBooted();
         // Assign raw attributes (skip get-casts) so mutators like Attribute.set can run on save.
         const model = classHasNoCasts(this)
             ? new this(useAttrs)
             : Object.assign(new this(), useAttrs);
+        const pre = beforeSave?.(model);
+        if (pre instanceof Promise) {
+            return pre.then(() => this.forceCreateSaved(model));
+        }
+        return this.forceCreateSaved(model);
+    }
+    /** Persist a model built by {@link forceCreate} and re-hydrate get-casts. */
+    static forceCreateSaved(model) {
         const saved = model.save();
         const after = (row) => {
             if (classHasNoCasts(this)) {
@@ -1234,6 +1822,20 @@ export class Model {
         assignOwn(this, ctor.castAttributes(finalAttrs, "get"));
         return this;
     }
+    /** `$model->forceFill($attributes)` — assign without checking `fillable` / `guarded`. */
+    forceFill(attributes) {
+        const ctor = this.constructor;
+        assignOwn(this, ctor.castAttributes({ ...attributes }, "get"));
+        return this;
+    }
+    /** `$model->isFillable($key)`. */
+    isFillable(key) {
+        return canMassAssign(this.constructor, key);
+    }
+    /** `$model->isGuarded($key)`. */
+    isGuarded(key) {
+        return !this.isFillable(key);
+    }
     /** `$model->update($attributes)`. */
     async update(attributes) {
         this.fill(attributes);
@@ -1278,6 +1880,20 @@ export class Model {
         });
         return this.save();
     }
+    /**
+     * Bump `updated_at` only when the model is dirty
+     * and the caller did not set `updated_at` themselves. A no-op `save()` must
+     * not issue an UPDATE.
+     */
+    #stampUpdatedAt(now) {
+        const dirty = this.getDirty();
+        for (const _ in dirty) {
+            if (!("updated_at" in dirty)) {
+                this.updated_at = now;
+            }
+            return;
+        }
+    }
     #persistSync(conn) {
         const ctor = this.constructor;
         const key = ctor.primaryKey;
@@ -1290,16 +1906,39 @@ export class Model {
         const usesTimestamps = ctor.timestamps !== false;
         if (usesTimestamps) {
             const now = nowForConnection(conn);
-            row.updated_at = now;
             if (!exists) {
+                row.updated_at = now;
                 row.created_at = row.created_at ?? now;
             }
+            else {
+                this.#stampUpdatedAt(now);
+            }
         }
         if (!exists) {
             const noCasts = classHasNoCasts(ctor);
-            const cachedCols = noCasts
+            let cachedCols = noCasts
                 ? cachedSyncInsertColumns(ctor)
                 : null;
+            // The cached column list is only valid when the row sets exactly those columns:
+            // an unset fillable column must stay absent (so the DB default applies) and an
+            // attribute outside `fillable` (forceFill, direct assignment) must still be saved.
+            if (cachedCols) {
+                let present = 0;
+                for (let i = 0; i < cachedCols.length; i++) {
+                    if (row[cachedCols[i]] === undefined) {
+                        cachedCols = null;
+                        break;
+                    }
+                    present++;
+                }
+                if (cachedCols) {
+                    let own = 0;
+                    for (const _ in row)
+                        own++;
+                    if (own !== present)
+                        cachedCols = null;
+                }
+            }
             let writeColumns;
             let writeValues;
             if (cachedCols) {
@@ -1364,6 +2003,7 @@ export class Model {
             }
             this.#original = original;
             this.#changes = original;
+            this.#previous = undefined;
             this.#touchOwnersSync();
             return this;
         }
@@ -1379,6 +2019,7 @@ export class Model {
         }
         this.#wasRecentlyCreated = false;
         this.#changes = dirty;
+        this.#capturePrevious();
         this.syncOriginal();
         this.#touchOwnersSync();
         return this;
@@ -1392,19 +2033,19 @@ export class Model {
         if ((await fireModelEvent(this, "saving")) === false)
             return this;
         const usesTimestamps = ctor.timestamps !== false;
-        if (usesTimestamps) {
-            const now = nowForConnection(this.getConnection());
-            row.updated_at = now;
-            if (!exists) {
-                row.created_at = row.created_at ?? now;
-            }
-        }
-        const dirty = this.getDirty();
         const persistCtor = ctor;
         const table = new Db(this.getConnection()).table(ctor.table);
+        // Order: saving → creating/updating → timestamps → write → created/updated → saved.
+        let dirty;
         if (!exists) {
             if ((await fireModelEvent(this, "creating")) === false)
                 return this;
+            if (usesTimestamps) {
+                const now = nowForConnection(this.getConnection());
+                row.updated_at = now;
+                row.created_at = row.created_at ?? now;
+            }
+            dirty = this.getDirty();
             const attributes = persistableAttributes(persistCtor, row, ctor.incrementing !== false || row[key] == null ? key : undefined);
             if (ctor.incrementing !== false) {
                 const newId = await withoutQueryWriteHook(() => table.insertGetId(ctor.castAttributes(attributes, "set")));
@@ -1419,28 +2060,34 @@ export class Model {
             }
             this.#exists = true;
             this.#wasRecentlyCreated = true;
+            this.#recordChanges(dirty, false, usesTimestamps);
             await fireModelEvent(this, "created");
         }
         else {
             if ((await fireModelEvent(this, "updating")) === false)
                 return this;
-            const attributes = persistableAttributes(persistCtor, dirty, key);
-            if (Object.keys(attributes).length > 0) {
-                await withoutQueryWriteHook(() => table.where(key, id).update(ctor.castAttributes(attributes, "set")));
+            if (usesTimestamps)
+                this.#stampUpdatedAt(nowForConnection(this.getConnection()));
+            dirty = this.getDirty();
+            // `updated` fires only when something was written.
+            if (Object.keys(dirty).length > 0) {
+                const attributes = persistableAttributes(persistCtor, dirty, key);
+                if (Object.keys(attributes).length > 0) {
+                    await withoutQueryWriteHook(() => table.where(key, id).update(ctor.castAttributes(attributes, "set")));
+                }
+                this.#wasRecentlyCreated = false;
+                this.#recordChanges(dirty, true, usesTimestamps);
+                await fireModelEvent(this, "updated");
             }
-            this.#wasRecentlyCreated = false;
-            await fireModelEvent(this, "updated");
-        }
-        this.#changes = { ...dirty };
-        if (usesTimestamps) {
-            if ("updated_at" in row)
-                this.#changes.updated_at = row.updated_at;
-            if (!exists && "created_at" in row) {
-                this.#changes.created_at = row.created_at;
+            else {
+                this.#wasRecentlyCreated = false;
+                this.#recordChanges(dirty, true, usesTimestamps);
             }
         }
-        this.syncOriginal();
+        // `saved` fires first, then the original set is synced,
+        // so `isDirty()` / `getOriginal()` still describe the save inside `updated` and `saved`.
         await fireModelEvent(this, "saved");
+        this.syncOriginal();
         // finishSave → touchOwners (Relation.touch honors withoutTouching on related).
         await this.touchOwners();
         return this;
@@ -1459,6 +2106,8 @@ export class Model {
         if (fresh) {
             Object.assign(this, fresh.getAttributes());
             this.#original = { ...fresh.#original };
+            this.#rawRow = fresh.#rawRow;
+            this.#snapshots = fresh.#snapshots;
             this.#exists = true;
         }
         return this;
@@ -1478,6 +2127,8 @@ export class Model {
         if (fresh) {
             Object.assign(this, fresh.getAttributes());
             this.#original = { ...fresh.#original };
+            this.#rawRow = fresh.#rawRow;
+            this.#snapshots = fresh.#snapshots;
             this.#exists = true;
         }
         return this;
@@ -1629,8 +2280,8 @@ export class Model {
             return;
         if (usesSoftDeletes(ctor)) {
             await this.#performSoftDelete();
-            await fireModelEvent(this, "deleted");
             await fireModelEvent(this, "trashed");
+            await fireModelEvent(this, "deleted");
             return;
         }
         // delete(): touchOwners before performDeleteOnModel.
@@ -1660,9 +2311,12 @@ export class Model {
         ctor.bootIfNotBooted();
         if ((await fireModelEvent(this, "forceDeleting")) === false)
             return;
+        if ((await fireModelEvent(this, "deleting")) === false)
+            return;
+        await this.touchOwners();
         await this.#performForceDelete();
-        await fireModelEvent(this, "forceDeleted");
         await fireModelEvent(this, "deleted");
+        await fireModelEvent(this, "forceDeleted");
     }
     /** `$model->deleteQuietly()`. */
     async deleteQuietly() {
@@ -1723,7 +2377,8 @@ export class Model {
                 continue;
             if (visible && !visible.has(key))
                 continue;
-            out[key] = value instanceof Date ? value.toISOString() : value;
+            out[key] =
+                value instanceof Date ? serializeDate(ctor, key, value) : value;
         }
         for (const key of appends) {
             if (hidden.has(key))
@@ -1792,8 +2447,14 @@ export class Model {
         }
         return this;
     }
+    /** `toArray()` with `bigint` values as decimal strings, since JSON has no `bigint`. */
     toJSON() {
-        return this.toArray();
+        const out = this.toArray();
+        for (const key in out) {
+            if (typeof out[key] === "bigint")
+                out[key] = String(out[key]);
+        }
+        return out;
     }
     /** Alias of {@link toJSON}. */
     toJson() {
@@ -1903,6 +2564,14 @@ export class Model {
             : [name, primaryMorph].filter((value, index, all) => all.indexOf(value) === index);
         return new MorphToMany(this, related, table, foreign, relatedKey, morphTypeColumn, morphTypes, options.pivotTenantKey, options.parentTenantKey ?? options.pivotTenantKey);
     }
+    /**
+     * `$this->morphedByMany(Related::class, name)` — inverse of `morphToMany`.
+     * Defaults: pivot `{name}s`, `{name}_id`, `{name}_type`, parent key `{parent}_id`.
+     */
+    morphedByMany(related, name, table, foreignPivotKey, relatedPivotKey) {
+        const parent = this.constructor;
+        return new MorphedByMany(this, related, table ?? `${name}s`, foreignPivotKey ?? `${singular(parent.table)}_id`, relatedPivotKey ?? `${name}_id`, `${name}_type`, morphTypeFor(related));
+    }
     /** `$this->morphMany(Related::class, name)`. */
     morphMany(related, name, type, id, localKey) {
         return new MorphMany(this, related, type ?? `${name}_type`, id ?? `${name}_id`, morphTypeFor(this.constructor), localKey);
@@ -1916,6 +2585,17 @@ export class Model {
         return new MorphTo(this, type ?? `${name}_type`, id ?? `${name}_id`, ownerKey);
     }
 }
+/** ISO by default; `date:Y-m-d` / `datetime:FORMAT` casts format the serialized value. */
+function serializeDate(ctor, key, value) {
+    const definition = ctor.getCasts()[key];
+    if (typeof definition === "string") {
+        const arg = parseCast(definition)?.arg;
+        if (arg !== undefined && definition !== "decimal" && !definition.startsWith("decimal:")) {
+            return formatPhpDate(value, arg);
+        }
+    }
+    return value.toISOString();
+}
 installLocalScopeCallStatic(Model);
 /** True when `value` is a Model subclass constructor (O(1) prototype check). */
 export function isModelCtor(value) {
@@ -1925,7 +2605,7 @@ export function isModelCtor(value) {
         value.prototype instanceof Model);
 }
 // Re-exports — public API stays on ./model.ts for index.ts
-export { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, clearMorphMap, morphMap, } from "./relations.js";
+export { BelongsTo, BelongsToMany, HasMany, HasManyThrough, HasOne, HasOneThrough, MorphMany, MorphOne, MorphTo, MorphToMany, MorphedByMany, clearMorphMap, morphMap, enforceMorphMap, requireMorphMap, getMorphedModel, } from "./relations.js";
 export { eagerLoadAggregates, eagerLoadModels, } from "./eager.js";
 export { ModelQuery } from "./model-query.js";
 export { LazyLoadingViolationException, MassAssignmentException, MissingAttributeException, resetModelStrictnessForTests, } from "./model-strictness.js";