arkormx 2.3.0 → 2.4.0

package/dist/{relationship-CRlJHS90.cjs → relationship-Cku0y1Mt.cjs}

@@ -3362,9 +3362,34 @@ var Relation = class {
 	getRelatedModel() {
 		return this.related;
 	}
+	getRelatedModelConstructor() {
+		return this.related;
+	}
 	createRelationTableLoader() {
 		return new RelationTableLoader(this.getRelationAdapter());
 	}
+	getCreationAttributes() {
+		return {};
+	}
+	mergeCreationAttributes(attributes = {}) {
+		return {
+			...attributes,
+			...this.getCreationAttributes()
+		};
+	}
+	applyCreationAttributesToModel(model) {
+		const attributes = this.getCreationAttributes();
+		const fillable = model;
+		if (Object.keys(attributes).length === 0) return model;
+		if (typeof fillable.fill === "function") {
+			fillable.fill(attributes);
+			return model;
+		}
+		if (typeof fillable.setAttribute === "function") Object.entries(attributes).forEach(([key, value]) => {
+			fillable.setAttribute?.(key, value);
+		});
+		return model;
+	}
 	/**
 	* Apply a constraint to the relationship query.
 	* 
@@ -3560,6 +3585,30 @@ var Relation = class {
 		return results;
 	}
 	/**
+	* Execute the relationship query and return the first related model or throw an error if not found.
+	* 
+	* @returns 
+	*/
+	async firstOrFail() {
+		return (await this.getQuery()).firstOrFail();
+	}
+	/**
+	* Execute the relationship query and return the first related model or the result of 
+	* the callback if not found.
+	* 
+	* @param callback 
+	* @returns 
+	*/
+	async firstOr(callback) {
+		const result = await this.first();
+		if (result) return result;
+		return callback();
+	}
+	async firstWhere(key, operatorOrValue, maybeValue) {
+		const query = await this.getQuery();
+		return maybeValue === void 0 ? query.firstWhere(key, operatorOrValue) : query.firstWhere(key, operatorOrValue, maybeValue);
+	}
+	/**
 	* Count records that match the relationship query.
 	*
 	* @returns
@@ -3583,6 +3632,207 @@ var Relation = class {
 	async doesntExist() {
 		return !await this.exists();
 	}
+	/**
+	* Create a new instance of the related model with the given attributes and 
+	* relationship creation attributes applied, but do not save it.
+	* 
+	* @param attributes 
+	* @returns 
+	*/
+	make(attributes = {}) {
+		return this.getRelatedModelConstructor().hydrate(this.mergeCreationAttributes(attributes));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and relationship 
+	* creation attributes applied, but do not save them.
+	* 
+	* @param attributes 
+	* @returns 
+	*/
+	makeMany(attributes = []) {
+		return attributes.map((item) => this.make(item));
+	}
+	/**
+	* Create a new instance of the related model with the given attributes and relationship 
+	* creation attributes applied, and save it to the database.
+	* 
+	* @param attributes 
+	* @returns 
+	*/
+	async create(attributes = {}) {
+		return await this.getRelatedModelConstructor().query().create(this.mergeCreationAttributes(attributes));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and relationship 
+	* creation attributes applied, and save them to the database.
+	* 
+	* @param values 
+	* @returns 
+	*/
+	async createMany(values = []) {
+		if (values.length === 0) return [];
+		return await Promise.all(values.map(async (value) => await this.create(value)));
+	}
+	/**
+	* Save the given model instance by applying relationship creation attributes and calling save() on it.
+	* 
+	* @param model 
+	* @returns 
+	*/
+	async save(model) {
+		const saveable = this.applyCreationAttributesToModel(model);
+		if (typeof saveable.save !== "function") throw new UnsupportedAdapterFeatureException("Related model does not support save().", { operation: "relation.save" });
+		try {
+			return await saveable.save();
+		} catch (error) {
+			if (!this.shouldCreateAfterSaveMiss(error)) throw error;
+			const attributes = typeof saveable.getRawAttributes === "function" ? saveable.getRawAttributes() : {};
+			return await this.create(attributes);
+		}
+	}
+	/**
+	* Save the given model instance by applying relationship creation attributes and 
+	* calling saveQuietly() on it if supported, otherwise falling back to save().
+	* 
+	* @param model 
+	* @returns 
+	*/
+	async saveQuietly(model) {
+		const saveable = this.applyCreationAttributesToModel(model);
+		if (typeof saveable.saveQuietly === "function") try {
+			return await saveable.saveQuietly();
+		} catch (error) {
+			if (!this.shouldCreateAfterSaveMiss(error)) throw error;
+			const attributes = typeof saveable.getRawAttributes === "function" ? saveable.getRawAttributes() : {};
+			return await this.create(attributes);
+		}
+		if (typeof saveable.save === "function") return await saveable.save();
+		throw new UnsupportedAdapterFeatureException("Related model does not support saveQuietly().", { operation: "relation.saveQuietly" });
+	}
+	shouldCreateAfterSaveMiss(error) {
+		return error instanceof Error && (error.name === "ModelNotFoundException" || error.message.includes("Record not found"));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and 
+	* relationship * creation attributes applied, and save them to the database.
+	* 
+	* @param models 
+	* @returns 
+	*/
+	async saveMany(models = []) {
+		return await Promise.all(models.map(async (model) => await this.save(model)));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and relationship 
+	* creation attributes applied, and save them to the database.
+	* 
+	* @param models 
+	* @returns 
+	*/
+	async saveManyQuietly(models = []) {
+		return await Promise.all(models.map(async (model) => await this.saveQuietly(model)));
+	}
+	async find(value, key) {
+		return (await this.getQuery()).find(value, key);
+	}
+	async findMany(values, key) {
+		const related = this.getRelatedModelConstructor();
+		const resolvedKey = key ?? related.getPrimaryKey();
+		return (await this.getQuery()).where({ [resolvedKey]: { in: values } }).get();
+	}
+	async findOr(value, keyOrCallback, maybeCallback) {
+		const query = await this.getQuery();
+		return typeof keyOrCallback === "function" ? query.findOr(value, keyOrCallback) : query.findOr(value, keyOrCallback, maybeCallback);
+	}
+	async findOrFail(value, key) {
+		const found = await this.find(value, key);
+		if (found) return found;
+		return (await this.getQuery()).where({ [key ?? this.getRelatedModelConstructor().getPrimaryKey()]: value }).firstOrFail();
+	}
+	/**
+	* Find the first related model by a specific key and value, or create a new instance if not found.
+	* 
+	* @param attributes 
+	* @param values 
+	* @returns 
+	*/
+	async firstOrNew(attributes, values = {}) {
+		const found = await (await this.getQuery()).clone().where(attributes).first();
+		if (found) return found;
+		return this.make({
+			...attributes,
+			...values
+		});
+	}
+	/**
+	* Find the first related model by a specific key and value, or create and save a new instance 
+	* if not found.
+	* 
+	* @param attributes 
+	* @param values 
+	* @returns 
+	*/
+	async firstOrCreate(attributes, values = {}) {
+		const found = await (await this.getQuery()).clone().where(attributes).first();
+		if (found) return found;
+		return await this.create({
+			...attributes,
+			...values
+		});
+	}
+	/**
+	* Find the first related model by a specific key and value, update the first matching record with 
+	* the given values, or create and save a new instance if no matching record is found.
+	* 
+	* @param attributes 
+	* @param values 
+	* @returns 
+	*/
+	async updateOrCreate(attributes, values = {}) {
+		const query = await this.getQuery();
+		const found = await query.clone().where(attributes).first();
+		if (!found) return await this.create({
+			...attributes,
+			...values
+		});
+		const updatable = found;
+		if (typeof updatable.fill === "function" && typeof updatable.save === "function") return await updatable.fill(values).save();
+		return await query.clone().where(attributes).update(values);
+	}
+	/**
+	* Find related models by specific attributes, update matching records with the given values, or 
+	* create and save new instances if no matching records are found.
+	* 
+	* @param values 
+	* @param uniqueBy 
+	* @param update 
+	* @returns 
+	*/
+	async upsert(values, uniqueBy, update = null) {
+		return await (await this.getQuery()).upsert(values.map((value) => this.mergeCreationAttributes(value)), uniqueBy, update);
+	}
+	/**
+	* Paginate the relationship query results.
+	* 
+	* @param perPage 
+	* @param page 
+	* @param options 
+	* @returns 
+	*/
+	async paginate(perPage = 15, page, options = {}) {
+		return (await this.getQuery()).paginate(perPage, page, options);
+	}
+	/**
+	* Paginate the relationship query results without total count optimization.
+	* 
+	* @param perPage 
+	* @param page 
+	* @param options 
+	* @returns 
+	*/
+	async simplePaginate(perPage = 15, page, options = {}) {
+		return (await this.getQuery()).simplePaginate(perPage, page, options);
+	}
 };
 
 //#endregion
@@ -3771,9 +4021,14 @@ var BelongsToManyRelation = class BelongsToManyRelation extends Relation {
 		};
 	}
 	buildPivotTarget() {
+		const metadata = getPersistedTableMetadata(this.throughTable, {
+			features: resolvePersistedMetadataFeatures(getUserConfig("features")),
+			strict: true
+		});
 		return {
 			table: this.throughTable,
-			primaryKey: this.relatedPivotKey
+			primaryKey: this.relatedPivotKey,
+			columns: metadata.columns
 		};
 	}
 	buildRelatedPivotCondition(relatedValues) {
@@ -4269,6 +4524,9 @@ var HasManyRelation = class extends Relation {
 		const localValue = this.parent.getAttribute(this.localKey);
 		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
 	}
+	getCreationAttributes() {
+		return { [this.foreignKey]: this.parent.getAttribute(this.localKey) };
+	}
 	getMetadata() {
 		return {
 			type: "hasMany",
@@ -4372,6 +4630,9 @@ var HasOneRelation = class extends SingleResultRelation {
 		const localValue = this.parent.getAttribute(this.localKey);
 		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
 	}
+	getCreationAttributes() {
+		return { [this.foreignKey]: this.parent.getAttribute(this.localKey) };
+	}
 	getMetadata() {
 		return {
 			type: "hasOne",
@@ -4480,6 +4741,12 @@ var MorphManyRelation = class extends Relation {
 			[`${this.morphName}Type`]: type
 		}));
 	}
+	getCreationAttributes() {
+		return {
+			[`${this.morphName}Id`]: this.parent.getAttribute(this.localKey),
+			[`${this.morphName}Type`]: this.parent.constructor.name
+		};
+	}
 	getMetadata() {
 		return {
 			type: "morphMany",
@@ -4527,6 +4794,12 @@ var MorphOneRelation = class extends SingleResultRelation {
 			[`${this.morphName}Type`]: type
 		}));
 	}
+	getCreationAttributes() {
+		return {
+			[`${this.morphName}Id`]: this.parent.getAttribute(this.localKey),
+			[`${this.morphName}Type`]: this.parent.constructor.name
+		};
+	}
 	getMetadata() {
 		return {
 			type: "morphOne",

package/dist/{relationship-CJaPnw92.mjs → relationship-DcvK5Xn-.mjs}

@@ -3334,9 +3334,34 @@ var Relation = class {
 	getRelatedModel() {
 		return this.related;
 	}
+	getRelatedModelConstructor() {
+		return this.related;
+	}
 	createRelationTableLoader() {
 		return new RelationTableLoader(this.getRelationAdapter());
 	}
+	getCreationAttributes() {
+		return {};
+	}
+	mergeCreationAttributes(attributes = {}) {
+		return {
+			...attributes,
+			...this.getCreationAttributes()
+		};
+	}
+	applyCreationAttributesToModel(model) {
+		const attributes = this.getCreationAttributes();
+		const fillable = model;
+		if (Object.keys(attributes).length === 0) return model;
+		if (typeof fillable.fill === "function") {
+			fillable.fill(attributes);
+			return model;
+		}
+		if (typeof fillable.setAttribute === "function") Object.entries(attributes).forEach(([key, value]) => {
+			fillable.setAttribute?.(key, value);
+		});
+		return model;
+	}
 	/**
 	* Apply a constraint to the relationship query.
 	* 
@@ -3532,6 +3557,30 @@ var Relation = class {
 		return results;
 	}
 	/**
+	* Execute the relationship query and return the first related model or throw an error if not found.
+	* 
+	* @returns 
+	*/
+	async firstOrFail() {
+		return (await this.getQuery()).firstOrFail();
+	}
+	/**
+	* Execute the relationship query and return the first related model or the result of 
+	* the callback if not found.
+	* 
+	* @param callback 
+	* @returns 
+	*/
+	async firstOr(callback) {
+		const result = await this.first();
+		if (result) return result;
+		return callback();
+	}
+	async firstWhere(key, operatorOrValue, maybeValue) {
+		const query = await this.getQuery();
+		return maybeValue === void 0 ? query.firstWhere(key, operatorOrValue) : query.firstWhere(key, operatorOrValue, maybeValue);
+	}
+	/**
 	* Count records that match the relationship query.
 	*
 	* @returns
@@ -3555,6 +3604,207 @@ var Relation = class {
 	async doesntExist() {
 		return !await this.exists();
 	}
+	/**
+	* Create a new instance of the related model with the given attributes and 
+	* relationship creation attributes applied, but do not save it.
+	* 
+	* @param attributes 
+	* @returns 
+	*/
+	make(attributes = {}) {
+		return this.getRelatedModelConstructor().hydrate(this.mergeCreationAttributes(attributes));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and relationship 
+	* creation attributes applied, but do not save them.
+	* 
+	* @param attributes 
+	* @returns 
+	*/
+	makeMany(attributes = []) {
+		return attributes.map((item) => this.make(item));
+	}
+	/**
+	* Create a new instance of the related model with the given attributes and relationship 
+	* creation attributes applied, and save it to the database.
+	* 
+	* @param attributes 
+	* @returns 
+	*/
+	async create(attributes = {}) {
+		return await this.getRelatedModelConstructor().query().create(this.mergeCreationAttributes(attributes));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and relationship 
+	* creation attributes applied, and save them to the database.
+	* 
+	* @param values 
+	* @returns 
+	*/
+	async createMany(values = []) {
+		if (values.length === 0) return [];
+		return await Promise.all(values.map(async (value) => await this.create(value)));
+	}
+	/**
+	* Save the given model instance by applying relationship creation attributes and calling save() on it.
+	* 
+	* @param model 
+	* @returns 
+	*/
+	async save(model) {
+		const saveable = this.applyCreationAttributesToModel(model);
+		if (typeof saveable.save !== "function") throw new UnsupportedAdapterFeatureException("Related model does not support save().", { operation: "relation.save" });
+		try {
+			return await saveable.save();
+		} catch (error) {
+			if (!this.shouldCreateAfterSaveMiss(error)) throw error;
+			const attributes = typeof saveable.getRawAttributes === "function" ? saveable.getRawAttributes() : {};
+			return await this.create(attributes);
+		}
+	}
+	/**
+	* Save the given model instance by applying relationship creation attributes and 
+	* calling saveQuietly() on it if supported, otherwise falling back to save().
+	* 
+	* @param model 
+	* @returns 
+	*/
+	async saveQuietly(model) {
+		const saveable = this.applyCreationAttributesToModel(model);
+		if (typeof saveable.saveQuietly === "function") try {
+			return await saveable.saveQuietly();
+		} catch (error) {
+			if (!this.shouldCreateAfterSaveMiss(error)) throw error;
+			const attributes = typeof saveable.getRawAttributes === "function" ? saveable.getRawAttributes() : {};
+			return await this.create(attributes);
+		}
+		if (typeof saveable.save === "function") return await saveable.save();
+		throw new UnsupportedAdapterFeatureException("Related model does not support saveQuietly().", { operation: "relation.saveQuietly" });
+	}
+	shouldCreateAfterSaveMiss(error) {
+		return error instanceof Error && (error.name === "ModelNotFoundException" || error.message.includes("Record not found"));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and 
+	* relationship * creation attributes applied, and save them to the database.
+	* 
+	* @param models 
+	* @returns 
+	*/
+	async saveMany(models = []) {
+		return await Promise.all(models.map(async (model) => await this.save(model)));
+	}
+	/**
+	* Create new instances of the related model with the given attributes and relationship 
+	* creation attributes applied, and save them to the database.
+	* 
+	* @param models 
+	* @returns 
+	*/
+	async saveManyQuietly(models = []) {
+		return await Promise.all(models.map(async (model) => await this.saveQuietly(model)));
+	}
+	async find(value, key) {
+		return (await this.getQuery()).find(value, key);
+	}
+	async findMany(values, key) {
+		const related = this.getRelatedModelConstructor();
+		const resolvedKey = key ?? related.getPrimaryKey();
+		return (await this.getQuery()).where({ [resolvedKey]: { in: values } }).get();
+	}
+	async findOr(value, keyOrCallback, maybeCallback) {
+		const query = await this.getQuery();
+		return typeof keyOrCallback === "function" ? query.findOr(value, keyOrCallback) : query.findOr(value, keyOrCallback, maybeCallback);
+	}
+	async findOrFail(value, key) {
+		const found = await this.find(value, key);
+		if (found) return found;
+		return (await this.getQuery()).where({ [key ?? this.getRelatedModelConstructor().getPrimaryKey()]: value }).firstOrFail();
+	}
+	/**
+	* Find the first related model by a specific key and value, or create a new instance if not found.
+	* 
+	* @param attributes 
+	* @param values 
+	* @returns 
+	*/
+	async firstOrNew(attributes, values = {}) {
+		const found = await (await this.getQuery()).clone().where(attributes).first();
+		if (found) return found;
+		return this.make({
+			...attributes,
+			...values
+		});
+	}
+	/**
+	* Find the first related model by a specific key and value, or create and save a new instance 
+	* if not found.
+	* 
+	* @param attributes 
+	* @param values 
+	* @returns 
+	*/
+	async firstOrCreate(attributes, values = {}) {
+		const found = await (await this.getQuery()).clone().where(attributes).first();
+		if (found) return found;
+		return await this.create({
+			...attributes,
+			...values
+		});
+	}
+	/**
+	* Find the first related model by a specific key and value, update the first matching record with 
+	* the given values, or create and save a new instance if no matching record is found.
+	* 
+	* @param attributes 
+	* @param values 
+	* @returns 
+	*/
+	async updateOrCreate(attributes, values = {}) {
+		const query = await this.getQuery();
+		const found = await query.clone().where(attributes).first();
+		if (!found) return await this.create({
+			...attributes,
+			...values
+		});
+		const updatable = found;
+		if (typeof updatable.fill === "function" && typeof updatable.save === "function") return await updatable.fill(values).save();
+		return await query.clone().where(attributes).update(values);
+	}
+	/**
+	* Find related models by specific attributes, update matching records with the given values, or 
+	* create and save new instances if no matching records are found.
+	* 
+	* @param values 
+	* @param uniqueBy 
+	* @param update 
+	* @returns 
+	*/
+	async upsert(values, uniqueBy, update = null) {
+		return await (await this.getQuery()).upsert(values.map((value) => this.mergeCreationAttributes(value)), uniqueBy, update);
+	}
+	/**
+	* Paginate the relationship query results.
+	* 
+	* @param perPage 
+	* @param page 
+	* @param options 
+	* @returns 
+	*/
+	async paginate(perPage = 15, page, options = {}) {
+		return (await this.getQuery()).paginate(perPage, page, options);
+	}
+	/**
+	* Paginate the relationship query results without total count optimization.
+	* 
+	* @param perPage 
+	* @param page 
+	* @param options 
+	* @returns 
+	*/
+	async simplePaginate(perPage = 15, page, options = {}) {
+		return (await this.getQuery()).simplePaginate(perPage, page, options);
+	}
 };
 
 //#endregion
@@ -3743,9 +3993,14 @@ var BelongsToManyRelation = class BelongsToManyRelation extends Relation {
 		};
 	}
 	buildPivotTarget() {
+		const metadata = getPersistedTableMetadata(this.throughTable, {
+			features: resolvePersistedMetadataFeatures(getUserConfig("features")),
+			strict: true
+		});
 		return {
 			table: this.throughTable,
-			primaryKey: this.relatedPivotKey
+			primaryKey: this.relatedPivotKey,
+			columns: metadata.columns
 		};
 	}
 	buildRelatedPivotCondition(relatedValues) {
@@ -4241,6 +4496,9 @@ var HasManyRelation = class extends Relation {
 		const localValue = this.parent.getAttribute(this.localKey);
 		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
 	}
+	getCreationAttributes() {
+		return { [this.foreignKey]: this.parent.getAttribute(this.localKey) };
+	}
 	getMetadata() {
 		return {
 			type: "hasMany",
@@ -4344,6 +4602,9 @@ var HasOneRelation = class extends SingleResultRelation {
 		const localValue = this.parent.getAttribute(this.localKey);
 		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
 	}
+	getCreationAttributes() {
+		return { [this.foreignKey]: this.parent.getAttribute(this.localKey) };
+	}
 	getMetadata() {
 		return {
 			type: "hasOne",
@@ -4452,6 +4713,12 @@ var MorphManyRelation = class extends Relation {
 			[`${this.morphName}Type`]: type
 		}));
 	}
+	getCreationAttributes() {
+		return {
+			[`${this.morphName}Id`]: this.parent.getAttribute(this.localKey),
+			[`${this.morphName}Type`]: this.parent.constructor.name
+		};
+	}
 	getMetadata() {
 		return {
 			type: "morphMany",
@@ -4499,6 +4766,12 @@ var MorphOneRelation = class extends SingleResultRelation {
 			[`${this.morphName}Type`]: type
 		}));
 	}
+	getCreationAttributes() {
+		return {
+			[`${this.morphName}Id`]: this.parent.getAttribute(this.localKey),
+			[`${this.morphName}Type`]: this.parent.constructor.name
+		};
+	}
 	getMetadata() {
 		return {
 			type: "morphOne",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkormx",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Modern TypeScript-first ORM for Node.js.",
   "keywords": [
     "orm",