arkormx 0.1.11 → 0.2.1

package/dist/index.cjs

@@ -2203,9 +2203,14 @@ const defineFactory = (model, definition) => {
 * @since 0.1.0
 */
 var ModelNotFoundException = class extends ArkormException {
-	constructor(message = "No query results for the given model.") {
+	modelName;
+	constructor(modelName, message = "No query results for the given model.") {
 		super(message);
 		this.name = "ModelNotFoundException";
+		this.modelName = modelName;
+	}
+	getModelName() {
+		return this.modelName;
 	}
 };
 
@@ -3605,7 +3610,7 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async firstOrFail() {
 		const model = await this.first();
-		if (!model) throw new ModelNotFoundException("Record not found.");
+		if (!model) throw new ModelNotFoundException(this.model.name, "Record not found.");
 		return model;
 	}
 	async find(value, key = "id") {
@@ -3638,7 +3643,7 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async valueOrFail(column) {
 		const result = await this.value(column);
-		if (result == null) throw new ModelNotFoundException("Record not found.");
+		if (result == null) throw new ModelNotFoundException(this.model.name, "Record not found.");
 		return result;
 	}
 	/**
@@ -3664,6 +3669,99 @@ var QueryBuilder = class QueryBuilder {
 		return this.model.hydrate(created);
 	}
 	/**
+	* Creates multiple records and returns hydrated model instances.
+	*
+	* @param values
+	* @returns
+	*/
+	async createMany(values) {
+		if (values.length === 0) return [];
+		return await Promise.all(values.map(async (value) => await this.create(value)));
+	}
+	/**
+	* Insert one or more records.
+	*
+	* @param values
+	* @returns
+	*/
+	async insert(values) {
+		const payloads = this.normalizeInsertPayloads(values);
+		if (payloads.length === 0) return true;
+		const delegate = this.delegate;
+		if (typeof delegate.createMany === "function") {
+			await delegate.createMany({ data: payloads });
+			return true;
+		}
+		await Promise.all(payloads.map(async (payload) => {
+			await this.delegate.create({ data: payload });
+		}));
+		return true;
+	}
+	/**
+	* Insert one or more records while ignoring insertion errors.
+	*
+	* @param values
+	* @returns
+	*/
+	async insertOrIgnore(values) {
+		const payloads = this.normalizeInsertPayloads(values);
+		if (payloads.length === 0) return 0;
+		const delegate = this.delegate;
+		if (typeof delegate.createMany === "function") {
+			const result = await delegate.createMany({
+				data: payloads,
+				skipDuplicates: true
+			});
+			return this.resolveAffectedCount(result, payloads.length);
+		}
+		let inserted = 0;
+		for (const payload of payloads) try {
+			await this.delegate.create({ data: payload });
+			inserted += 1;
+		} catch {
+			continue;
+		}
+		return inserted;
+	}
+	/**
+	* Insert a record and return its primary key value.
+	*
+	* @param values
+	* @param sequence
+	* @returns
+	*/
+	async insertGetId(values, sequence) {
+		const created = await this.delegate.create({ data: values });
+		const key = sequence ?? "id";
+		if (!(key in created)) throw new ArkormException(`Inserted record does not contain key [${key}].`);
+		return created[key];
+	}
+	/**
+	* Insert records using values produced by another query/source.
+	*
+	* @param columns
+	* @param query
+	* @returns
+	*/
+	async insertUsing(columns, query) {
+		const rows = await this.resolveInsertUsingRows(columns, query);
+		if (rows.length === 0) return 0;
+		await this.insert(rows);
+		return rows.length;
+	}
+	/**
+	* Insert records using values produced by another query/source while ignoring insertion errors.
+	*
+	* @param columns
+	* @param query
+	* @returns
+	*/
+	async insertOrIgnoreUsing(columns, query) {
+		const rows = await this.resolveInsertUsingRows(columns, query);
+		if (rows.length === 0) return 0;
+		return this.insertOrIgnore(rows);
+	}
+	/**
 	* Updates records matching the current query constraints with the 
 	* specified data and returns the updated record(s) as model instance(s).
 	* 
@@ -3681,6 +3779,71 @@ var QueryBuilder = class QueryBuilder {
 		return this.model.hydrate(updated);
 	}
 	/**
+	* Update records using update-many semantics when available.
+	*
+	* @param data
+	* @returns
+	*/
+	async updateFrom(data) {
+		const where = this.buildWhere();
+		if (!where) throw new ArkormException("Update requires a where clause.");
+		const delegate = this.delegate;
+		if (typeof delegate.updateMany === "function") {
+			const result = await delegate.updateMany({
+				where,
+				data
+			});
+			return this.resolveAffectedCount(result, 0);
+		}
+		await this.update(data);
+		return 1;
+	}
+	/**
+	* Insert a record when no match exists, otherwise update the matching record.
+	*
+	* @param attributes
+	* @param values
+	* @returns
+	*/
+	async updateOrInsert(attributes, values = {}) {
+		const exists = await this.delegate.findFirst({ where: attributes }) != null;
+		const resolvedValues = typeof values === "function" ? await values(exists) : values;
+		if (!exists) {
+			await this.delegate.create({ data: {
+				...attributes,
+				...resolvedValues
+			} });
+			return true;
+		}
+		return await this.clone().where(attributes).update(resolvedValues) != null;
+	}
+	/**
+	* Insert new records or update existing records by one or more unique keys.
+	*
+	* @param values
+	* @param uniqueBy
+	* @param update
+	* @returns
+	*/
+	async upsert(values, uniqueBy, update = null) {
+		if (values.length === 0) return 0;
+		const uniqueKeys = Array.isArray(uniqueBy) ? uniqueBy : [uniqueBy];
+		let affected = 0;
+		for (const row of values) {
+			const attributes = uniqueKeys.reduce((all, key) => {
+				all[key] = row[key];
+				return all;
+			}, {});
+			const updatePayload = (update ?? Object.keys(row).filter((key) => !uniqueKeys.includes(key))).reduce((all, key) => {
+				if (key in row) all[key] = row[key];
+				return all;
+			}, {});
+			await this.updateOrInsert(attributes, updatePayload);
+			affected += 1;
+		}
+		return affected;
+	}
+	/**
 	* Deletes records matching the current query constraints and returns 
 	* the deleted record(s) as model instance(s).
 	* 
@@ -3719,6 +3882,43 @@ var QueryBuilder = class QueryBuilder {
 	async doesntExist() {
 		return !await this.exists();
 	}
+	normalizeInsertPayloads(values) {
+		if (Array.isArray(values)) return values;
+		return [values];
+	}
+	resolveAffectedCount(result, fallback) {
+		if (typeof result === "number") return result;
+		if (result && typeof result === "object" && "count" in result) {
+			const candidate = result.count;
+			if (typeof candidate === "number") return candidate;
+		}
+		return fallback;
+	}
+	async resolveInsertUsingRows(columns, query) {
+		const resolvedQuery = typeof query === "function" ? await query() : query;
+		return (await this.resolveInsertUsingSource(resolvedQuery)).map((row) => {
+			return columns.reduce((record, column) => {
+				record[column] = row[column];
+				return record;
+			}, {});
+		});
+	}
+	async resolveInsertUsingSource(source) {
+		if (source && typeof source === "object") {
+			const asBuilder = source;
+			if (typeof asBuilder.get === "function") {
+				const collection = await asBuilder.get();
+				if (typeof collection.all === "function") return collection.all().map((item) => {
+					const asModel = item;
+					if (typeof asModel.getRawAttributes === "function") return asModel.getRawAttributes();
+					return item;
+				});
+			}
+			if (Array.isArray(source)) return source;
+		}
+		if (Array.isArray(source)) return source;
+		throw new ArkormException("insertUsing expects a query builder, array of records, or async resolver.");
+	}
 	/**
 	* Execute callback when no records exist.
 	*

package/dist/index.d.cts

@@ -1477,6 +1477,51 @@ declare class QueryBuilder<TModel, TDelegate extends PrismaDelegateLike = Prisma
    * @returns
    */
   create(data: DelegateCreateData<TDelegate>): Promise<TModel>;
+  /**
+   * Creates multiple records and returns hydrated model instances.
+   *
+   * @param values
+   * @returns
+   */
+  createMany(values: DelegateCreateData<TDelegate>[]): Promise<TModel[]>;
+  /**
+   * Insert one or more records.
+   *
+   * @param values
+   * @returns
+   */
+  insert(values: DelegateCreateData<TDelegate> | DelegateCreateData<TDelegate>[]): Promise<boolean>;
+  /**
+   * Insert one or more records while ignoring insertion errors.
+   *
+   * @param values
+   * @returns
+   */
+  insertOrIgnore(values: DelegateCreateData<TDelegate> | DelegateCreateData<TDelegate>[]): Promise<number>;
+  /**
+   * Insert a record and return its primary key value.
+   *
+   * @param values
+   * @param sequence
+   * @returns
+   */
+  insertGetId(values: DelegateCreateData<TDelegate>, sequence?: string | null): Promise<unknown>;
+  /**
+   * Insert records using values produced by another query/source.
+   *
+   * @param columns
+   * @param query
+   * @returns
+   */
+  insertUsing(columns: string[], query: unknown): Promise<number>;
+  /**
+   * Insert records using values produced by another query/source while ignoring insertion errors.
+   *
+   * @param columns
+   * @param query
+   * @returns
+   */
+  insertOrIgnoreUsing(columns: string[], query: unknown): Promise<number>;
   /**
    * Updates records matching the current query constraints with the
    * specified data and returns the updated record(s) as model instance(s).
@@ -1485,6 +1530,30 @@ declare class QueryBuilder<TModel, TDelegate extends PrismaDelegateLike = Prisma
    * @returns
    */
   update(data: DelegateUpdateData<TDelegate>): Promise<TModel>;
+  /**
+   * Update records using update-many semantics when available.
+   *
+   * @param data
+   * @returns
+   */
+  updateFrom(data: DelegateUpdateData<TDelegate>): Promise<number>;
+  /**
+   * Insert a record when no match exists, otherwise update the matching record.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  updateOrInsert(attributes: Record<string, unknown>, values?: Record<string, unknown> | ((exists: boolean) => Record<string, unknown> | Promise<Record<string, unknown>>)): Promise<boolean>;
+  /**
+   * Insert new records or update existing records by one or more unique keys.
+   *
+   * @param values
+   * @param uniqueBy
+   * @param update
+   * @returns
+   */
+  upsert(values: Array<Record<string, unknown>>, uniqueBy: string | string[], update?: string[] | null): Promise<number>;
   /**
    * Deletes records matching the current query constraints and returns
    * the deleted record(s) as model instance(s).
@@ -1510,6 +1579,10 @@ declare class QueryBuilder<TModel, TDelegate extends PrismaDelegateLike = Prisma
    * @returns
    */
   doesntExist(): Promise<boolean>;
+  private normalizeInsertPayloads;
+  private resolveAffectedCount;
+  private resolveInsertUsingRows;
+  private resolveInsertUsingSource;
   /**
    * Execute callback when no records exist.
    *
@@ -2557,7 +2630,9 @@ declare class ArkormException extends Error {
  * @since 0.1.0
  */
 declare class ModelNotFoundException extends ArkormException {
-  constructor(message?: string);
+  private modelName;
+  constructor(modelName: string, message?: string);
+  getModelName(): string;
 }
 //#endregion
 //#region src/helpers/migrations.d.ts

package/dist/index.d.mts

@@ -1477,6 +1477,51 @@ declare class QueryBuilder<TModel, TDelegate extends PrismaDelegateLike = Prisma
    * @returns
    */
   create(data: DelegateCreateData<TDelegate>): Promise<TModel>;
+  /**
+   * Creates multiple records and returns hydrated model instances.
+   *
+   * @param values
+   * @returns
+   */
+  createMany(values: DelegateCreateData<TDelegate>[]): Promise<TModel[]>;
+  /**
+   * Insert one or more records.
+   *
+   * @param values
+   * @returns
+   */
+  insert(values: DelegateCreateData<TDelegate> | DelegateCreateData<TDelegate>[]): Promise<boolean>;
+  /**
+   * Insert one or more records while ignoring insertion errors.
+   *
+   * @param values
+   * @returns
+   */
+  insertOrIgnore(values: DelegateCreateData<TDelegate> | DelegateCreateData<TDelegate>[]): Promise<number>;
+  /**
+   * Insert a record and return its primary key value.
+   *
+   * @param values
+   * @param sequence
+   * @returns
+   */
+  insertGetId(values: DelegateCreateData<TDelegate>, sequence?: string | null): Promise<unknown>;
+  /**
+   * Insert records using values produced by another query/source.
+   *
+   * @param columns
+   * @param query
+   * @returns
+   */
+  insertUsing(columns: string[], query: unknown): Promise<number>;
+  /**
+   * Insert records using values produced by another query/source while ignoring insertion errors.
+   *
+   * @param columns
+   * @param query
+   * @returns
+   */
+  insertOrIgnoreUsing(columns: string[], query: unknown): Promise<number>;
   /**
    * Updates records matching the current query constraints with the
    * specified data and returns the updated record(s) as model instance(s).
@@ -1485,6 +1530,30 @@ declare class QueryBuilder<TModel, TDelegate extends PrismaDelegateLike = Prisma
    * @returns
    */
   update(data: DelegateUpdateData<TDelegate>): Promise<TModel>;
+  /**
+   * Update records using update-many semantics when available.
+   *
+   * @param data
+   * @returns
+   */
+  updateFrom(data: DelegateUpdateData<TDelegate>): Promise<number>;
+  /**
+   * Insert a record when no match exists, otherwise update the matching record.
+   *
+   * @param attributes
+   * @param values
+   * @returns
+   */
+  updateOrInsert(attributes: Record<string, unknown>, values?: Record<string, unknown> | ((exists: boolean) => Record<string, unknown> | Promise<Record<string, unknown>>)): Promise<boolean>;
+  /**
+   * Insert new records or update existing records by one or more unique keys.
+   *
+   * @param values
+   * @param uniqueBy
+   * @param update
+   * @returns
+   */
+  upsert(values: Array<Record<string, unknown>>, uniqueBy: string | string[], update?: string[] | null): Promise<number>;
   /**
    * Deletes records matching the current query constraints and returns
    * the deleted record(s) as model instance(s).
@@ -1510,6 +1579,10 @@ declare class QueryBuilder<TModel, TDelegate extends PrismaDelegateLike = Prisma
    * @returns
    */
   doesntExist(): Promise<boolean>;
+  private normalizeInsertPayloads;
+  private resolveAffectedCount;
+  private resolveInsertUsingRows;
+  private resolveInsertUsingSource;
   /**
    * Execute callback when no records exist.
    *
@@ -2557,7 +2630,9 @@ declare class ArkormException extends Error {
  * @since 0.1.0
  */
 declare class ModelNotFoundException extends ArkormException {
-  constructor(message?: string);
+  private modelName;
+  constructor(modelName: string, message?: string);
+  getModelName(): string;
 }
 //#endregion
 //#region src/helpers/migrations.d.ts

package/dist/index.mjs

@@ -2174,9 +2174,14 @@ const defineFactory = (model, definition) => {
 * @since 0.1.0
 */
 var ModelNotFoundException = class extends ArkormException {
-	constructor(message = "No query results for the given model.") {
+	modelName;
+	constructor(modelName, message = "No query results for the given model.") {
 		super(message);
 		this.name = "ModelNotFoundException";
+		this.modelName = modelName;
+	}
+	getModelName() {
+		return this.modelName;
 	}
 };
 
@@ -3576,7 +3581,7 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async firstOrFail() {
 		const model = await this.first();
-		if (!model) throw new ModelNotFoundException("Record not found.");
+		if (!model) throw new ModelNotFoundException(this.model.name, "Record not found.");
 		return model;
 	}
 	async find(value, key = "id") {
@@ -3609,7 +3614,7 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async valueOrFail(column) {
 		const result = await this.value(column);
-		if (result == null) throw new ModelNotFoundException("Record not found.");
+		if (result == null) throw new ModelNotFoundException(this.model.name, "Record not found.");
 		return result;
 	}
 	/**
@@ -3635,6 +3640,99 @@ var QueryBuilder = class QueryBuilder {
 		return this.model.hydrate(created);
 	}
 	/**
+	* Creates multiple records and returns hydrated model instances.
+	*
+	* @param values
+	* @returns
+	*/
+	async createMany(values) {
+		if (values.length === 0) return [];
+		return await Promise.all(values.map(async (value) => await this.create(value)));
+	}
+	/**
+	* Insert one or more records.
+	*
+	* @param values
+	* @returns
+	*/
+	async insert(values) {
+		const payloads = this.normalizeInsertPayloads(values);
+		if (payloads.length === 0) return true;
+		const delegate = this.delegate;
+		if (typeof delegate.createMany === "function") {
+			await delegate.createMany({ data: payloads });
+			return true;
+		}
+		await Promise.all(payloads.map(async (payload) => {
+			await this.delegate.create({ data: payload });
+		}));
+		return true;
+	}
+	/**
+	* Insert one or more records while ignoring insertion errors.
+	*
+	* @param values
+	* @returns
+	*/
+	async insertOrIgnore(values) {
+		const payloads = this.normalizeInsertPayloads(values);
+		if (payloads.length === 0) return 0;
+		const delegate = this.delegate;
+		if (typeof delegate.createMany === "function") {
+			const result = await delegate.createMany({
+				data: payloads,
+				skipDuplicates: true
+			});
+			return this.resolveAffectedCount(result, payloads.length);
+		}
+		let inserted = 0;
+		for (const payload of payloads) try {
+			await this.delegate.create({ data: payload });
+			inserted += 1;
+		} catch {
+			continue;
+		}
+		return inserted;
+	}
+	/**
+	* Insert a record and return its primary key value.
+	*
+	* @param values
+	* @param sequence
+	* @returns
+	*/
+	async insertGetId(values, sequence) {
+		const created = await this.delegate.create({ data: values });
+		const key = sequence ?? "id";
+		if (!(key in created)) throw new ArkormException(`Inserted record does not contain key [${key}].`);
+		return created[key];
+	}
+	/**
+	* Insert records using values produced by another query/source.
+	*
+	* @param columns
+	* @param query
+	* @returns
+	*/
+	async insertUsing(columns, query) {
+		const rows = await this.resolveInsertUsingRows(columns, query);
+		if (rows.length === 0) return 0;
+		await this.insert(rows);
+		return rows.length;
+	}
+	/**
+	* Insert records using values produced by another query/source while ignoring insertion errors.
+	*
+	* @param columns
+	* @param query
+	* @returns
+	*/
+	async insertOrIgnoreUsing(columns, query) {
+		const rows = await this.resolveInsertUsingRows(columns, query);
+		if (rows.length === 0) return 0;
+		return this.insertOrIgnore(rows);
+	}
+	/**
 	* Updates records matching the current query constraints with the 
 	* specified data and returns the updated record(s) as model instance(s).
 	* 
@@ -3652,6 +3750,71 @@ var QueryBuilder = class QueryBuilder {
 		return this.model.hydrate(updated);
 	}
 	/**
+	* Update records using update-many semantics when available.
+	*
+	* @param data
+	* @returns
+	*/
+	async updateFrom(data) {
+		const where = this.buildWhere();
+		if (!where) throw new ArkormException("Update requires a where clause.");
+		const delegate = this.delegate;
+		if (typeof delegate.updateMany === "function") {
+			const result = await delegate.updateMany({
+				where,
+				data
+			});
+			return this.resolveAffectedCount(result, 0);
+		}
+		await this.update(data);
+		return 1;
+	}
+	/**
+	* Insert a record when no match exists, otherwise update the matching record.
+	*
+	* @param attributes
+	* @param values
+	* @returns
+	*/
+	async updateOrInsert(attributes, values = {}) {
+		const exists = await this.delegate.findFirst({ where: attributes }) != null;
+		const resolvedValues = typeof values === "function" ? await values(exists) : values;
+		if (!exists) {
+			await this.delegate.create({ data: {
+				...attributes,
+				...resolvedValues
+			} });
+			return true;
+		}
+		return await this.clone().where(attributes).update(resolvedValues) != null;
+	}
+	/**
+	* Insert new records or update existing records by one or more unique keys.
+	*
+	* @param values
+	* @param uniqueBy
+	* @param update
+	* @returns
+	*/
+	async upsert(values, uniqueBy, update = null) {
+		if (values.length === 0) return 0;
+		const uniqueKeys = Array.isArray(uniqueBy) ? uniqueBy : [uniqueBy];
+		let affected = 0;
+		for (const row of values) {
+			const attributes = uniqueKeys.reduce((all, key) => {
+				all[key] = row[key];
+				return all;
+			}, {});
+			const updatePayload = (update ?? Object.keys(row).filter((key) => !uniqueKeys.includes(key))).reduce((all, key) => {
+				if (key in row) all[key] = row[key];
+				return all;
+			}, {});
+			await this.updateOrInsert(attributes, updatePayload);
+			affected += 1;
+		}
+		return affected;
+	}
+	/**
 	* Deletes records matching the current query constraints and returns 
 	* the deleted record(s) as model instance(s).
 	* 
@@ -3690,6 +3853,43 @@ var QueryBuilder = class QueryBuilder {
 	async doesntExist() {
 		return !await this.exists();
 	}
+	normalizeInsertPayloads(values) {
+		if (Array.isArray(values)) return values;
+		return [values];
+	}
+	resolveAffectedCount(result, fallback) {
+		if (typeof result === "number") return result;
+		if (result && typeof result === "object" && "count" in result) {
+			const candidate = result.count;
+			if (typeof candidate === "number") return candidate;
+		}
+		return fallback;
+	}
+	async resolveInsertUsingRows(columns, query) {
+		const resolvedQuery = typeof query === "function" ? await query() : query;
+		return (await this.resolveInsertUsingSource(resolvedQuery)).map((row) => {
+			return columns.reduce((record, column) => {
+				record[column] = row[column];
+				return record;
+			}, {});
+		});
+	}
+	async resolveInsertUsingSource(source) {
+		if (source && typeof source === "object") {
+			const asBuilder = source;
+			if (typeof asBuilder.get === "function") {
+				const collection = await asBuilder.get();
+				if (typeof collection.all === "function") return collection.all().map((item) => {
+					const asModel = item;
+					if (typeof asModel.getRawAttributes === "function") return asModel.getRawAttributes();
+					return item;
+				});
+			}
+			if (Array.isArray(source)) return source;
+		}
+		if (Array.isArray(source)) return source;
+		throw new ArkormException("insertUsing expects a query builder, array of records, or async resolver.");
+	}
 	/**
 	* Execute callback when no records exist.
 	*

package/package.json

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