@apisr/drizzle-model 2.0.2 → 2.0.4

package/dist/core/result.mjs

@@ -0,0 +1,215 @@
+//#region src/core/result.ts
+/**
+* A lazy result that implements `PromiseLike` so it can be `await`-ed.
+*
+* Execution is deferred until `.then()` is called, allowing the caller
+* to chain modifiers (`.select()`, `.with()`, …) before the query runs.
+*
+* When `_safe` is `true`, execution errors are caught and the result
+* is wrapped in a {@link SafeResult} discriminated union.
+*
+* @typeParam T - The resolved result type.
+*/
+var ThenableResult = class {
+	/** The deferred execution function. */
+	_execute;
+	/** When `true`, wraps the result in `{ data, error }`. */
+	_safe;
+	constructor(execute, safe = false) {
+		this._execute = execute;
+		this._safe = safe;
+	}
+	/**
+	* Implements the `PromiseLike` interface.
+	*
+	* Triggers the deferred execution and forwards to the native
+	* `Promise.then()`. When `_safe` is enabled, catches errors and
+	* resolves to `{ data, error }` instead of rejecting.
+	*/
+	then(onfulfilled, onrejected) {
+		if (!this._safe) return this._execute().then(onfulfilled, onrejected);
+		return this._execute().then((data) => ({
+			data,
+			error: void 0
+		})).catch((error) => ({
+			data: void 0,
+			error
+		})).then(onfulfilled, onrejected);
+	}
+};
+/**
+* A thenable query result that supports chaining query modifiers.
+*
+* Each modifier returns a **new** `QueryResult` with the updated state,
+* keeping the original immutable.
+*
+* @typeParam T - The resolved result type.
+*/
+var QueryResult = class QueryResult extends ThenableResult {
+	/** The current accumulated query state. */
+	state;
+	/** The runner function that executes the query with the given state. */
+	runner;
+	constructor(state, runner) {
+		super(() => runner(state), state.safe);
+		this.state = state;
+		this.runner = runner;
+	}
+	/**
+	* Includes related entities via LEFT JOINs.
+	*
+	* @param value - A relation selection map (e.g. `{ posts: true }`).
+	* @returns A new `QueryResult` with the `.with()` state applied.
+	*/
+	with(value) {
+		return new QueryResult({
+			...this.state,
+			with: value
+		}, this.runner);
+	}
+	/**
+	* Controls which columns appear in the SQL SELECT clause (whitelist).
+	*
+	* This affects the query itself, not just the result.
+	* Equivalent to `db.select({ col: table.col }).from(table)`.
+	*
+	* @param value - A map of `{ columnName: true }`.
+	* @returns A new `QueryResult` with the `.select()` state applied.
+	*/
+	select(value) {
+		return new QueryResult({
+			...this.state,
+			select: value
+		}, this.runner);
+	}
+	/**
+	* Controls which columns are excluded from the SQL SELECT clause (blacklist).
+	*
+	* This affects the query itself, not just the result.
+	* All columns except the listed ones will be fetched.
+	*
+	* @param value - A map of `{ columnName: true }`.
+	* @returns A new `QueryResult` with the `.exclude()` state applied.
+	*/
+	exclude(value) {
+		return new QueryResult({
+			...this.state,
+			exclude: value
+		}, this.runner);
+	}
+	/**
+	* Disables format transformations for this query.
+	*
+	* @returns A new `QueryResult` with `raw` set to `true`.
+	*/
+	raw() {
+		return new QueryResult({
+			...this.state,
+			raw: true
+		}, this.runner);
+	}
+	/**
+	* Wraps the result in a `{ data, error }` discriminated union.
+	*
+	* When the query succeeds, resolves to `{ data: T, error: undefined }`.
+	* When it fails, resolves to `{ data: undefined, error: unknown }`
+	* instead of rejecting.
+	*
+	* @returns A new `QueryResult` with safe error handling enabled.
+	*/
+	safe() {
+		return new QueryResult({
+			...this.state,
+			safe: true
+		}, this.runner);
+	}
+	/**
+	* Returns the current query state for debugging purposes.
+	*
+	* @returns The accumulated {@link QueryState}.
+	*/
+	debug() {
+		return this.state;
+	}
+};
+/**
+* A thenable mutation result that supports chaining mutation modifiers.
+*
+* Each modifier returns a **new** `MutateResult` with the updated state,
+* keeping the original immutable.
+*
+* @typeParam T - The resolved result type.
+*/
+var MutateResult = class MutateResult extends ThenableResult {
+	/** The current accumulated mutation state. */
+	state;
+	/** The runner function that executes the mutation with the given state. */
+	runner;
+	constructor(state, runner) {
+		super(() => runner(state), state.safe);
+		this.state = state;
+		this.runner = runner;
+	}
+	/**
+	* Specifies which columns to return from the mutation (as an array).
+	*
+	* @param value - Optional column selection map for `.returning()`.
+	* @returns A new `MutateResult` with the return selection applied.
+	*/
+	return(value) {
+		return new MutateResult({
+			...this.state,
+			returnSelect: value,
+			hasReturn: true
+		}, this.runner);
+	}
+	/**
+	* Specifies which columns to return, resolving to only the **first** row.
+	*
+	* Behaves like `.return()` but unwraps the array to a single object.
+	*
+	* @param value - Optional column selection map for `.returning()`.
+	* @returns A new `MutateResult` with `returnFirst` enabled.
+	*/
+	returnFirst(value) {
+		return new MutateResult({
+			...this.state,
+			returnSelect: value,
+			returnFirst: true,
+			hasReturn: true
+		}, this.runner);
+	}
+	/**
+	* Excludes specific fields from the mutation result **after** execution.
+	*
+	* Unlike `.exclude()` on queries (which affects the SQL projection),
+	* `.omit()` removes keys from the result objects in-memory.
+	*
+	* @param value - A map of `{ fieldName: true }` for fields to remove.
+	* @returns A new `MutateResult` with the omit map applied.
+	*/
+	omit(value) {
+		return new MutateResult({
+			...this.state,
+			omit: value
+		}, this.runner);
+	}
+	/**
+	* Wraps the result in a `{ data, error }` discriminated union.
+	*
+	* When the mutation succeeds, resolves to `{ data: T, error: undefined }`.
+	* When it fails, resolves to `{ data: undefined, error: unknown }`
+	* instead of rejecting.
+	*
+	* @returns A new `MutateResult` with safe error handling enabled.
+	*/
+	safe() {
+		return new MutateResult({
+			...this.state,
+			safe: true
+		}, this.runner);
+	}
+};
+
+//#endregion
+export { MutateResult, QueryResult };

package/dist/core/runtime.mjs

@@ -0,0 +1,393 @@
+import { DialectHelper } from "./dialect.mjs";
+import { ProjectionBuilder } from "./query/projection.mjs";
+import { WhereCompiler } from "./query/where.mjs";
+import { JoinExecutor } from "./query/joins.mjs";
+import { MutateResult, QueryResult } from "./result.mjs";
+import { ResultTransformer } from "./transform.mjs";
+
+//#region src/core/runtime.ts
+/**
+* The runtime implementation behind every model instance.
+*
+* Exposes query methods (`findMany`, `findFirst`), mutation methods
+* (`insert`, `update`, `delete`, `upsert`), and lifecycle helpers
+* (`where`, `extend`, `db`, `include`).
+*
+* Internally delegates to specialised helpers:
+* - {@link WhereCompiler} — compiles where clauses.
+* - {@link ProjectionBuilder} — builds column projections.
+* - {@link JoinExecutor} — executes relation joins.
+* - {@link ResultTransformer} — applies post-query transforms.
+*
+* Each call to `.where()` returns a **new** runtime with the additional
+* filter applied, keeping the original immutable.
+*/
+var ModelRuntime = class ModelRuntime {
+	/** Static configuration for this model. */
+	config;
+	/** The current where filter applied via `.where()`. */
+	currentWhere;
+	whereCompiler;
+	projection;
+	joinExecutor;
+	transformer;
+	dialectHelper;
+	constructor(config, currentWhere) {
+		this.config = config;
+		this.currentWhere = currentWhere;
+		this.dialectHelper = new DialectHelper(config.dialect);
+		this.whereCompiler = new WhereCompiler();
+		this.projection = new ProjectionBuilder();
+		this.joinExecutor = new JoinExecutor(this.dialectHelper);
+		this.transformer = new ResultTransformer();
+	}
+	/** Model discriminator tag. */
+	get $model() {
+		return "model";
+	}
+	/** The name of the table this model is bound to. */
+	get $modelName() {
+		return this.config.tableName;
+	}
+	/** The user-defined format function, if any. */
+	get $format() {
+		return this.config.options.format;
+	}
+	/** The current where clause, exposed for relation descriptors. */
+	get $where() {
+		return this.currentWhere;
+	}
+	/** The table name this model is bound to, exposed for relation descriptors. */
+	get $tableName() {
+		return this.config.tableName;
+	}
+	/**
+	* Returns a new runtime with an additional where filter.
+	*
+	* The new filter is AND-ed with any existing model-level where clause
+	* at execution time.
+	*
+	* @param value - A where clause (object, SQL, or model reference).
+	* @returns A new {@link ModelRuntime} with the filter applied.
+	*/
+	where(value) {
+		return new ModelRuntime(this.config, value);
+	}
+	/**
+	* Returns a relation descriptor carrying the model's where clause
+	* and the nested relation includes.
+	*
+	* Used in `.with()` to filter a relation and load nested relations:
+	* ```ts
+	* userModel.findMany().with({
+	*   posts: postModel.where({ ... }).include({ comments: true }),
+	* });
+	* ```
+	*
+	* @param value - The nested relation include descriptor.
+	* @returns A model relation descriptor consumed by the join executor.
+	*/
+	include(value) {
+		return {
+			__modelRelation: true,
+			whereValue: this.currentWhere,
+			tableName: this.config.tableName,
+			with: value
+		};
+	}
+	/**
+	* Creates a new runtime with merged options.
+	*
+	* Useful for extending a base model with additional format functions,
+	* methods, or default where clauses.
+	*
+	* @param nextOptions - Partial options to merge.
+	* @returns A new {@link ModelRuntime} with the merged configuration.
+	*/
+	extend(nextOptions) {
+		return new ModelRuntime({
+			...this.config,
+			options: {
+				...this.config.options,
+				...nextOptions,
+				methods: {
+					...this.config.options.methods ?? {},
+					...nextOptions.methods ?? {}
+				},
+				format: nextOptions.format ?? this.config.options.format
+			}
+		});
+	}
+	/**
+	* Creates a new runtime bound to a different database instance.
+	*
+	* @param db - The new Drizzle database instance.
+	* @returns A new {@link ModelRuntime} using the given database.
+	*/
+	db(db) {
+		return new ModelRuntime({
+			...this.config,
+			db
+		});
+	}
+	/**
+	* Returns a thenable that resolves to an array of matching rows.
+	*
+	* Supports chaining: `.select()`, `.exclude()` (SQL SELECT),
+	* `.with()` (relations), `.raw()`, `.safe()`.
+	*
+	* @returns A {@link QueryResult} that can be awaited or further chained.
+	*/
+	findMany() {
+		const runner = async (qState) => {
+			const table = this.getTable();
+			const whereSql = this.buildEffectiveWhere(table);
+			let result;
+			if (qState.with) result = await this.joinExecutor.execute({
+				db: this.config.db,
+				schema: this.config.schema,
+				relations: this.config.relations,
+				baseTableName: this.config.tableName,
+				baseTable: table,
+				whereSql,
+				withValue: qState.with,
+				select: qState.select,
+				exclude: qState.exclude,
+				limitOne: false
+			});
+			else {
+				const { selectMap } = this.projection.build(table, qState.select, qState.exclude);
+				let query = this.config.db.select(selectMap);
+				query = query.from(table);
+				if (whereSql) query = query.where(whereSql);
+				result = await query;
+			}
+			return this.applyPostQueryTransforms(result, qState);
+		};
+		return new QueryResult({}, runner);
+	}
+	/**
+	* Returns a thenable that resolves to the first matching row (or `undefined`).
+	*
+	* Supports chaining: `.select()`, `.exclude()` (SQL SELECT),
+	* `.with()` (relations), `.raw()`, `.safe()`.
+	*
+	* @returns A {@link QueryResult} that can be awaited or further chained.
+	*/
+	findFirst() {
+		const runner = async (qState) => {
+			const table = this.getTable();
+			const whereSql = this.buildEffectiveWhere(table);
+			let result;
+			if (qState.with) result = await this.joinExecutor.execute({
+				db: this.config.db,
+				schema: this.config.schema,
+				relations: this.config.relations,
+				baseTableName: this.config.tableName,
+				baseTable: table,
+				whereSql,
+				withValue: qState.with,
+				select: qState.select,
+				exclude: qState.exclude,
+				limitOne: true
+			});
+			else {
+				const { selectMap } = this.projection.build(table, qState.select, qState.exclude);
+				let query = this.config.db.select(selectMap);
+				query = query.from(table);
+				if (whereSql) query = query.where(whereSql);
+				query = query.limit(1);
+				result = (await query)[0];
+			}
+			return this.applyPostQueryTransforms(result, qState);
+		};
+		return new QueryResult({}, runner);
+	}
+	/**
+	* Returns a promise that resolves to the number of matching rows.
+	*
+	* Respects the effective where clause (model-level + `.where()`).
+	*
+	* @returns A `Promise<number>` with the row count.
+	*/
+	async count() {
+		const table = this.getTable();
+		const whereSql = this.buildEffectiveWhere(table);
+		const db = this.config.db;
+		const { count: countFn } = await import("drizzle-orm");
+		let query = db.select({ count: countFn() });
+		query = query.from(table);
+		if (whereSql) query = query.where(whereSql);
+		return (await query)[0]?.count ?? 0;
+	}
+	/**
+	* Inserts one or more rows into the table.
+	*
+	* @param value - The row(s) to insert.
+	* @returns A {@link MutateResult} that can be awaited or chained with `.return()`.
+	*/
+	insert(value) {
+		const runner = async (mState) => {
+			const table = this.getTable();
+			const withValues = this.config.db.insert(table).values(mState.value);
+			let result = await this.execReturning(withValues, mState);
+			if (!(mState.hasReturn || Array.isArray(mState.value)) && Array.isArray(result)) result = result[0];
+			return this.applyPostMutateTransforms(result, mState);
+		};
+		return new MutateResult({
+			kind: "insert",
+			value
+		}, runner);
+	}
+	/**
+	* Updates rows matching the current where clause.
+	*
+	* @param value - The partial row data to set.
+	* @returns A {@link MutateResult} that can be awaited or chained with `.return()`.
+	*/
+	update(value) {
+		const runner = async (mState) => {
+			const table = this.getTable();
+			const whereSql = this.buildEffectiveWhere(table);
+			let query = this.config.db.update(table);
+			query = query.set(mState.value);
+			if (whereSql) query = query.where(whereSql);
+			const result = await this.execReturning(query, mState);
+			return this.applyPostMutateTransforms(result, mState);
+		};
+		return new MutateResult({
+			kind: "update",
+			value
+		}, runner);
+	}
+	/**
+	* Deletes rows matching the current where clause.
+	*
+	* @returns A {@link MutateResult} that can be awaited or chained with `.return()`.
+	*/
+	delete() {
+		const runner = async (mState) => {
+			const table = this.getTable();
+			const whereSql = this.buildEffectiveWhere(table);
+			let query = this.config.db.delete(table);
+			if (whereSql) query = query.where(whereSql);
+			const result = await this.execReturning(query, mState);
+			return this.applyPostMutateTransforms(result, mState);
+		};
+		return new MutateResult({ kind: "delete" }, runner);
+	}
+	/**
+	* Inserts a row, or updates it when a conflict is detected.
+	*
+	* The `value` must contain `insert`, `update`, and optionally `target`.
+	*
+	* @param value - The upsert descriptor.
+	* @returns A {@link MutateResult} that can be awaited or chained with `.return()`.
+	*/
+	upsert(value) {
+		const runner = async (mState) => {
+			const table = this.getTable();
+			const upsertValue = mState.value;
+			const insertValues = upsertValue.insert;
+			const updateCfg = upsertValue.update;
+			const target = this.normalizeUpsertTarget(table, upsertValue.target);
+			let updateSet = updateCfg;
+			if (typeof updateCfg === "function") updateSet = updateCfg({
+				excluded: (field) => table[field],
+				inserted: (field) => table[field]
+			});
+			let query = this.config.db.insert(table);
+			query = query.values(insertValues);
+			const queryRecord = query;
+			if (typeof queryRecord.onConflictDoUpdate === "function") query = queryRecord.onConflictDoUpdate({
+				target,
+				set: updateSet
+			});
+			const result = await this.execReturning(query, mState);
+			return this.applyPostMutateTransforms(result, mState);
+		};
+		return new MutateResult({
+			kind: "upsert",
+			value
+		}, runner);
+	}
+	/**
+	* Attaches user-defined methods from the model options to a target object.
+	*
+	* Each method is bound to `target` so that `this` inside the method
+	* refers to the model-like object.
+	*
+	* @param target - The object to attach methods to.
+	*/
+	attachMethods(target) {
+		const methods = this.config.options.methods;
+		if (!methods) return;
+		for (const [key, fn] of Object.entries(methods)) if (typeof fn === "function") target[key] = fn.bind(target);
+	}
+	/**
+	* Applies `returnFirst` and `omit` transforms to a mutation result.
+	*/
+	applyPostMutateTransforms(result, mState) {
+		let out = result;
+		if (mState.returnFirst && Array.isArray(out)) out = out[0];
+		if (mState.omit) out = this.transformer.applyExclude(out, mState.omit);
+		return out;
+	}
+	/**
+	* Retrieves the Drizzle table object for the configured table name.
+	*/
+	getTable() {
+		return this.config.schema[this.config.tableName];
+	}
+	/**
+	* Builds the effective where clause by merging the model-level where
+	* (from options) with the call-level where (from `.where()`).
+	*/
+	buildEffectiveWhere(table) {
+		return this.whereCompiler.compileEffective(table, this.config.options.where, this.currentWhere);
+	}
+	/**
+	* Applies post-query transforms to the query result.
+	*
+	* Note: `.select()` and `.exclude()` are handled at the SQL level
+	* (via {@link ProjectionBuilder}) and are NOT applied here.
+	* Only format transforms are applied post-query.
+	*/
+	applyPostQueryTransforms(result, qState) {
+		let out = result;
+		if (!qState.raw) out = this.transformer.applyFormat(out, this.config.options.format);
+		return out;
+	}
+	/**
+	* Executes the returning clause for a mutation query.
+	*
+	* Handles the dialect-specific differences:
+	* - Standard `.returning()` (PostgreSQL, SQLite).
+	* - `.$returningId()` (MySQL, SingleStore, CockroachDB).
+	*
+	* @param query  - The built mutation query.
+	* @param mState - The mutation state (may contain `returnSelect`).
+	* @returns The mutation result.
+	*/
+	async execReturning(query, mState) {
+		const queryRecord = query;
+		if (typeof queryRecord.returning === "function") return mState.returnSelect ? await queryRecord.returning(mState.returnSelect) : await queryRecord.returning();
+		if (this.dialectHelper.isReturningIdOnly() && typeof queryRecord.$returningId === "function") return await queryRecord.$returningId();
+		return await query;
+	}
+	/**
+	* Normalizes the upsert conflict target.
+	*
+	* Converts string column names to their Drizzle column references,
+	* handling both single values and arrays.
+	*/
+	normalizeUpsertTarget(table, target) {
+		if (!target) return target;
+		if (typeof target === "string") return table[target] ?? target;
+		if (Array.isArray(target)) return target.map((t) => typeof t === "string" ? table[t] ?? t : t);
+		return target;
+	}
+};
+
+//#endregion
+export { ModelRuntime };

package/dist/core/transform.mjs

@@ -0,0 +1,83 @@
+//#region src/core/transform.ts
+/**
+* Applies post-query transformations to result sets.
+*
+* Handles three independent transformations that can be composed:
+* - **select** — whitelist specific fields from the result.
+* - **exclude** — blacklist specific fields from the result.
+* - **format** — run a user-defined formatting function over each row.
+*
+* Each method is safe to call on `null`, `undefined`, arrays, and
+* single objects, and recurses correctly into nested structures.
+*/
+var ResultTransformer = class {
+	/**
+	* Picks only the fields present in the `select` map from each row.
+	*
+	* Supports nested selection: when a select value is an object instead
+	* of `true`, it recurses into that nested structure.
+	*
+	* @param value  - The query result (single row, array, or nullish).
+	* @param select - A map of `{ fieldName: true | nestedSelect }`.
+	* @returns The filtered result with the same shape (single / array).
+	*/
+	applySelect(value, select) {
+		if (value == null) return value;
+		if (Array.isArray(value)) return value.map((item) => this.applySelect(item, select));
+		if (typeof value !== "object") return value;
+		const row = value;
+		const out = {};
+		for (const [key, sel] of Object.entries(select)) {
+			if (sel === true) {
+				out[key] = row[key];
+				continue;
+			}
+			if (sel && typeof sel === "object") out[key] = this.applySelect(row[key], sel);
+		}
+		return out;
+	}
+	/**
+	* Removes the fields present in the `exclude` map from each row.
+	*
+	* Supports nested exclusion: when an exclude value is an object,
+	* it recurses into the nested value instead of removing the key entirely.
+	*
+	* @param value   - The query result (single row, array, or nullish).
+	* @param exclude - A map of `{ fieldName: true | nestedExclude }`.
+	* @returns The result with excluded fields removed.
+	*/
+	applyExclude(value, exclude) {
+		if (value == null) return value;
+		if (Array.isArray(value)) return value.map((item) => this.applyExclude(item, exclude));
+		if (typeof value !== "object") return value;
+		const out = { ...value };
+		for (const [key, ex] of Object.entries(exclude)) {
+			if (ex === true) {
+				delete out[key];
+				continue;
+			}
+			if (ex && typeof ex === "object" && key in out) out[key] = this.applyExclude(out[key], ex);
+		}
+		return out;
+	}
+	/**
+	* Applies a user-defined format function to each row in the result.
+	*
+	* When the format function is `undefined` or `null`, the value is
+	* returned unchanged. Arrays are mapped element-by-element.
+	*
+	* @param value  - The query result (single row, array, or nullish).
+	* @param format - A function that transforms a single row, or `undefined`.
+	* @returns The formatted result.
+	*/
+	applyFormat(value, format) {
+		if (!format) return value;
+		if (value == null) return value;
+		if (Array.isArray(value)) return value.map((item) => this.applyFormat(item, format));
+		if (typeof value !== "object") return value;
+		return format(value);
+	}
+};
+
+//#endregion
+export { ResultTransformer };