@relq/orm 0.1.3 → 0.1.4

package/dist/esm/mysql/helpers/MysqlPaginateBuilder.js

@@ -0,0 +1,182 @@
+import { MysqlCountBuilder } from "../count/count-builder.js";
+import { MysqlSelectBuilder } from "../select/select-builder.js";
+import { INTERNAL } from "../../core/helpers/methods.js";
+import { RelqBuilderError } from "../../shared/errors/relq-errors.js";
+export class MysqlPaginateBuilder {
+    relq;
+    tableName;
+    columns;
+    whereClause;
+    orderByClause;
+    constructor(relq, tableName, columns, whereClause, orderByClause) {
+        this.relq = relq;
+        this.tableName = tableName;
+        this.columns = columns;
+        this.whereClause = whereClause;
+        this.orderByClause = orderByClause;
+    }
+    async paging(options) {
+        const page = options.page ?? 1;
+        const perPage = options.perPage;
+        const shouldCount = options.count ?? true;
+        if (page < 1) {
+            throw new RelqBuilderError('page must be >= 1', { builder: 'paginate', hint: 'Page numbers are 1-indexed, starting from 1' });
+        }
+        if (perPage < 1) {
+            throw new RelqBuilderError('perPage must be >= 1', { builder: 'paginate', hint: 'Set perPage to the number of items you want per page (e.g. 20)' });
+        }
+        const columnsToSelect = this.columns && this.columns.length > 0 ? this.columns : ['*'];
+        const orderByArr = this.orderByClause
+            ? (Array.isArray(this.orderByClause[0]) ? this.orderByClause : [this.orderByClause])
+            : [];
+        const selectBuilder = new MysqlSelectBuilder(this.tableName, columnsToSelect);
+        if (this.whereClause) {
+            selectBuilder.where(this.whereClause);
+        }
+        for (const [column, direction] of orderByArr) {
+            const dbColumn = this.relq[INTERNAL].transformToDbColumns(this.tableName, { [column]: true });
+            selectBuilder.orderBy(Object.keys(dbColumn)[0] || column, direction);
+        }
+        let total = 0;
+        if (shouldCount) {
+            const countBuilder = new MysqlCountBuilder(this.tableName);
+            if (this.whereClause) {
+                countBuilder.where(this.whereClause);
+            }
+            const countResult = await this.relq[INTERNAL].executeCount(countBuilder.toString());
+            total = countResult.count;
+        }
+        const offset = (page - 1) * perPage;
+        selectBuilder.limit(perPage);
+        selectBuilder.offset(offset);
+        const result = await this.relq[INTERNAL].executeSelect(selectBuilder.toString(), this.tableName);
+        const totalPages = Math.ceil(total / perPage);
+        const hasNext = page < totalPages;
+        const hasPrev = page > 1;
+        const pagination = {
+            page,
+            perPage,
+            total,
+            totalPages,
+        };
+        if (hasNext) {
+            pagination.hasNext = true;
+            pagination.nextPage = page + 1;
+            Object.defineProperty(pagination, 'loadNext', {
+                value: () => this.paging({ ...options, page: page + 1 }),
+                enumerable: false,
+            });
+        }
+        else {
+            pagination.hasNext = false;
+        }
+        if (hasPrev) {
+            pagination.hasPrev = true;
+            pagination.prevPage = page - 1;
+            Object.defineProperty(pagination, 'loadPrev', {
+                value: () => this.paging({ ...options, page: page - 1 }),
+                enumerable: false,
+            });
+        }
+        else {
+            pagination.hasPrev = false;
+        }
+        Object.defineProperty(pagination, 'toJSON', {
+            value: () => ({
+                page, perPage, total, totalPages,
+                hasNext: pagination.hasNext, hasPrev: pagination.hasPrev,
+                nextPage: pagination.nextPage, prevPage: pagination.prevPage,
+            }),
+            enumerable: false,
+        });
+        return { data: result.data, pagination };
+    }
+    async offset(options) {
+        const position = options.position ?? 0;
+        const shouldCount = options.count ?? false;
+        if (position < 0) {
+            throw new RelqBuilderError('position must be >= 0', { builder: 'paginate', hint: 'Position is 0-indexed; use 0 for the first row' });
+        }
+        let limit;
+        if (options.shuffleLimit) {
+            const [min, max] = options.shuffleLimit;
+            if (min < 1 || max < 1) {
+                throw new RelqBuilderError('shuffleLimit values must be >= 1', { builder: 'paginate', hint: 'Both min and max in shuffleLimit must be positive integers' });
+            }
+            if (min > max) {
+                throw new RelqBuilderError('shuffleLimit[0] must be <= shuffleLimit[1]', { builder: 'paginate', hint: 'The first value (min) must be less than or equal to the second value (max)' });
+            }
+            limit = Math.floor(Math.random() * (max - min + 1)) + min;
+        }
+        else {
+            const limitValue = options.limit;
+            if (limitValue !== undefined && limitValue < 1) {
+                throw new RelqBuilderError('limit must be >= 1', { builder: 'paginate', hint: 'Set limit to a positive integer for the number of rows to fetch' });
+            }
+            limit = limitValue ?? 50;
+        }
+        const columnsToSelect = this.columns && this.columns.length > 0 ? this.columns : ['*'];
+        const orderByArr = this.orderByClause
+            ? (Array.isArray(this.orderByClause[0]) ? this.orderByClause : [this.orderByClause])
+            : [];
+        const selectBuilder = new MysqlSelectBuilder(this.tableName, columnsToSelect);
+        if (this.whereClause) {
+            selectBuilder.where(this.whereClause);
+        }
+        for (const [column, direction] of orderByArr) {
+            const dbColumn = this.relq[INTERNAL].transformToDbColumns(this.tableName, { [column]: true });
+            selectBuilder.orderBy(Object.keys(dbColumn)[0] || column, direction);
+        }
+        let total = 0;
+        if (shouldCount) {
+            const countBuilder = new MysqlCountBuilder(this.tableName);
+            if (this.whereClause) {
+                countBuilder.where(this.whereClause);
+            }
+            const countResult = await this.relq[INTERNAL].executeCount(countBuilder.toString());
+            total = countResult.count;
+        }
+        selectBuilder.limit(limit + 1);
+        selectBuilder.offset(position);
+        const result = await this.relq[INTERNAL].executeSelect(selectBuilder.toString(), this.tableName);
+        const hasMore = result.data.length > limit;
+        const data = hasMore ? result.data.slice(0, limit) : result.data;
+        const hasPrev = position > 0;
+        const pagination = {
+            position,
+            limit,
+            total,
+        };
+        if (hasMore) {
+            pagination.hasMore = true;
+            pagination.nextPos = position + limit;
+            Object.defineProperty(pagination, 'loadNext', {
+                value: () => this.offset({ ...options, position: position + limit }),
+                enumerable: false,
+            });
+        }
+        else {
+            pagination.hasMore = false;
+        }
+        if (hasPrev) {
+            pagination.hasPrev = true;
+            pagination.prevPos = Math.max(0, position - limit);
+            Object.defineProperty(pagination, 'loadPrev', {
+                value: () => this.offset({ ...options, position: Math.max(0, position - limit) }),
+                enumerable: false,
+            });
+        }
+        else {
+            pagination.hasPrev = false;
+        }
+        Object.defineProperty(pagination, 'toJSON', {
+            value: () => ({
+                position, limit, total,
+                hasMore: pagination.hasMore, hasPrev: pagination.hasPrev,
+                nextPos: pagination.nextPos, prevPos: pagination.prevPos,
+            }),
+            enumerable: false,
+        });
+        return { data, pagination };
+    }
+}

package/dist/esm/mysql/helpers/MysqlReturningExecutor.js

@@ -0,0 +1,65 @@
+import { MysqlInsertBuilder } from "../insert/insert-builder.js";
+import { INTERNAL } from "../../core/helpers/methods.js";
+import { requireCapability } from "../../core/helpers/capability-guard.js";
+export class MysqlReturningExecutor {
+    builder;
+    relq;
+    tableName;
+    schemaKey;
+    columnMapping;
+    constructor(builder, relq, tableName, schemaKey) {
+        this.builder = builder;
+        this.relq = relq;
+        this.tableName = tableName;
+        this.schemaKey = schemaKey;
+        requireCapability(relq, 'returning', 'RETURNING clause (MariaDB 10.5+ only)');
+        this.setupColumnMapping();
+    }
+    setupColumnMapping() {
+        if (!this.tableName && !this.schemaKey) {
+            return;
+        }
+        const internal = this.relq[INTERNAL];
+        const tableDef = internal.getTableDef(this.schemaKey || this.tableName);
+        if (!tableDef) {
+            return;
+        }
+        const tableColumns = tableDef.$columns || tableDef;
+        this.columnMapping = new Map();
+        for (const [propName, columnDef] of Object.entries(tableColumns)) {
+            if (columnDef && typeof columnDef === 'object') {
+                const sqlName = columnDef.$columnName || propName;
+                this.columnMapping.set(sqlName, propName);
+            }
+        }
+    }
+    transformRow(row) {
+        if (!this.columnMapping) {
+            return row;
+        }
+        const transformed = {};
+        for (const [sqlKey, value] of Object.entries(row)) {
+            const propName = this.columnMapping.get(sqlKey) || sqlKey;
+            transformed[propName] = value;
+        }
+        return transformed;
+    }
+    toString() {
+        return this.builder.toString();
+    }
+    async run(withMetadata) {
+        const internal = this.relq[INTERNAL];
+        if (this.builder instanceof MysqlInsertBuilder) {
+            for (const row of this.builder.insertData) {
+                internal.validateData(this.builder.tableName, row, 'insert');
+            }
+        }
+        const sql = this.builder.toString();
+        const result = await internal.executeSelect(sql);
+        const transformedData = result.data.map(row => this.transformRow(row));
+        if (withMetadata) {
+            return { ...result, data: transformedData };
+        }
+        return transformedData;
+    }
+}

package/dist/esm/mysql/helpers/index.js

@@ -0,0 +1,15 @@
+export { MysqlConnectedRawQueryBuilder } from "./MysqlConnectedRawQueryBuilder.js";
+export { MysqlConnectedCountBuilder } from "./MysqlConnectedCountBuilder.js";
+export { MysqlTransactionClient, executeMysqlTransaction } from "./MysqlConnectedTransactionBuilder.js";
+export { MysqlConnectedDeleteBuilder } from "./MysqlConnectedDeleteBuilder.js";
+export { MysqlConnectedUpdateBuilder } from "./MysqlConnectedUpdateBuilder.js";
+export { MysqlConnectedInsertBuilder } from "./MysqlConnectedInsertBuilder.js";
+export { MysqlConnectedAggregateBuilder } from "./MysqlConnectedAggregateBuilder.js";
+export { NativeCTEBuilder } from "../../core/cte/native-cte-builder.js";
+export { MysqlConnectedInsertFromSelectBuilder } from "./MysqlConnectedInsertFromSelectBuilder.js";
+export { MysqlConnectedSelectBuilder } from "./MysqlConnectedSelectBuilder.js";
+export { MysqlConnectedQueryBuilder } from "./MysqlConnectedQueryBuilder.js";
+export { MysqlPaginateBuilder } from "./MysqlPaginateBuilder.js";
+export { executeMysqlTypeSafeJoin, executeMysqlCorrelatedSubqueryJoin, executeMysqlJoinManyThrough } from "./select-joins.js";
+export { executeMysqlCursorEach, executeMysqlPagination } from "./select-pagination.js";
+export { executeMysqlFindById, executeMysqlFindOne, executeMysqlFindMany, executeMysqlExists, executeMysqlUpsert, executeMysqlCreateWith, executeMysqlSoftDelete, executeMysqlRestore, getMysqlPrimaryKeyColumn } from "./query-convenience.js";

package/dist/esm/mysql/helpers/query-convenience.js

@@ -0,0 +1,199 @@
+import { MysqlCountBuilder } from "../count/count-builder.js";
+import { MysqlInsertBuilder } from "../insert/insert-builder.js";
+import { MysqlSelectBuilder } from "../select/select-builder.js";
+import { MysqlUpdateBuilder } from "../update/update-builder.js";
+import { resolveMysqlForeignKey } from "../utils/fk-resolver.js";
+import { INTERNAL } from "../../core/helpers/methods.js";
+import { RelqBuilderError } from "../../shared/errors/relq-errors.js";
+export async function executeMysqlFindById(ctx, id, getPrimaryKeyColumn) {
+    const pkColumn = getPrimaryKeyColumn();
+    const dbColumn = ctx.relq[INTERNAL].transformToDbColumns(ctx.tableName, { [pkColumn]: id });
+    const dbColName = Object.keys(dbColumn)[0];
+    const builder = new MysqlSelectBuilder(ctx.tableName, ['*']);
+    builder.where(q => q.equal(dbColName, id));
+    builder.limit(1);
+    const sql = builder.toString();
+    const result = await ctx.relq[INTERNAL].executeSelectOne(sql, ctx.tableName);
+    return result.data;
+}
+export async function executeMysqlFindOne(ctx, filter) {
+    const builder = new MysqlSelectBuilder(ctx.tableName, ['*']);
+    const dbFilter = ctx.relq[INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    builder.limit(1);
+    const sql = builder.toString();
+    const result = await ctx.relq[INTERNAL].executeSelectOne(sql, ctx.tableName);
+    return result.data;
+}
+export async function executeMysqlFindMany(ctx, filter) {
+    const builder = new MysqlSelectBuilder(ctx.tableName, ['*']);
+    const dbFilter = ctx.relq[INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[INTERNAL].executeSelect(sql, ctx.tableName);
+    return result.data;
+}
+export async function executeMysqlExists(ctx, filter) {
+    const builder = new MysqlCountBuilder(ctx.tableName);
+    const dbFilter = ctx.relq[INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[INTERNAL].executeCount(sql);
+    return result.count > 0;
+}
+export async function executeMysqlUpsert(ctx, options) {
+    const internal = ctx.relq[INTERNAL];
+    const dbCreate = internal.transformToDbColumns(ctx.tableName, options.create);
+    const dbUpdate = internal.transformToDbColumns(ctx.tableName, options.update);
+    const dbWhere = internal.transformToDbColumns(ctx.tableName, options.where);
+    const builder = new MysqlInsertBuilder(ctx.tableName, dbCreate);
+    builder.onDuplicateKeyUpdate(dup => {
+        dup.doUpdate(dbUpdate);
+    });
+    const sql = builder.toString();
+    await internal.executeRun(sql);
+    const selectBuilder = new MysqlSelectBuilder(ctx.tableName, ['*']);
+    selectBuilder.where(q => {
+        for (const [col, val] of Object.entries(dbWhere)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    selectBuilder.limit(1);
+    const selectResult = await internal.executeSelectOne(selectBuilder.toString(), ctx.tableName);
+    return selectResult.data;
+}
+export async function executeMysqlSoftDelete(ctx, filter) {
+    const dbFilter = ctx.relq[INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    const builder = new MysqlUpdateBuilder(ctx.tableName);
+    builder.set({ deleted_at: new Date() });
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[INTERNAL].executeRun(sql);
+    return result.metadata.rowCount ?? 0;
+}
+export async function executeMysqlRestore(ctx, filter) {
+    const dbFilter = ctx.relq[INTERNAL].transformToDbColumns(ctx.tableName, filter);
+    const builder = new MysqlUpdateBuilder(ctx.tableName);
+    builder.set({ deleted_at: null });
+    builder.where(q => {
+        for (const [col, val] of Object.entries(dbFilter)) {
+            q.equal(col, val);
+        }
+        return q;
+    });
+    const sql = builder.toString();
+    const result = await ctx.relq[INTERNAL].executeRun(sql);
+    return result.metadata.rowCount ?? 0;
+}
+export async function executeMysqlCreateWith(ctx, parentData, related) {
+    const internal = ctx.relq[INTERNAL];
+    const schema = internal.getSchema();
+    if (!schema) {
+        throw new RelqBuilderError('Cannot use createWith() without schema', { builder: 'createWith', hint: 'Pass schema to your Relq client, or use separate insert calls with a transaction instead' });
+    }
+    const parentSchemaKey = findSchemaKeyByTableName(schema, ctx.tableName) || ctx.tableName;
+    try {
+        await internal.executeRun('START TRANSACTION');
+        const dbParent = internal.transformToDbColumns(ctx.tableName, parentData);
+        const parentBuilder = new MysqlInsertBuilder(ctx.tableName, dbParent);
+        const parentSQL = parentBuilder.toString();
+        await internal.executeRun(parentSQL);
+        const pkColumn = getMysqlPrimaryKeyColumn(ctx.relq, parentSchemaKey);
+        const dbPkColumn = Object.keys(internal.transformToDbColumns(ctx.tableName, { [pkColumn]: true }))[0] || pkColumn;
+        const selectParentSQL = `SELECT * FROM \`${ctx.tableName}\` WHERE \`${dbPkColumn}\` = LAST_INSERT_ID() LIMIT 1`;
+        const parentResult = await internal.executeQuery(selectParentSQL);
+        if (!parentResult.result.rows || parentResult.result.rows.length === 0) {
+            throw new RelqBuilderError('Parent insert returned no rows via LAST_INSERT_ID()', { builder: 'createWith', hint: 'Ensure the table has an AUTO_INCREMENT primary key and the insert data is valid' });
+        }
+        const parentRow = parentResult.result.rows[0];
+        for (const [relationKey, childData] of Object.entries(related)) {
+            const childTableDef = schema[relationKey];
+            if (!childTableDef) {
+                throw new RelqBuilderError(`Unknown table "${relationKey}" in createWith()`, { builder: 'createWith', hint: 'Verify the relation key matches a table name defined in your schema' });
+            }
+            const childTableName = childTableDef.$name || relationKey;
+            const fk = resolveMysqlForeignKey(schema, parentSchemaKey, relationKey);
+            if (!fk) {
+                throw new RelqBuilderError(`No FK relationship between "${parentSchemaKey}" and "${relationKey}"`, { builder: 'createWith', hint: 'Define $foreignKeys on your table definitions, or use separate insert calls with explicit FK values' });
+            }
+            let fkColumn;
+            let fkValue;
+            if (fk.direction === 'reverse') {
+                fkColumn = fk.toColumn;
+                fkValue = parentRow[fk.fromColumn];
+            }
+            else {
+                fkColumn = fk.fromColumn;
+                fkValue = parentRow[fk.toColumn];
+            }
+            const rows = Array.isArray(childData) ? childData : [childData];
+            if (rows.length === 0)
+                continue;
+            const firstChildRow = { ...rows[0], [fkColumn]: fkValue };
+            const dbFirstChild = internal.transformToDbColumns(childTableName, firstChildRow);
+            const childBuilder = new MysqlInsertBuilder(childTableName, dbFirstChild);
+            for (let i = 1; i < rows.length; i++) {
+                const childRow = { ...rows[i], [fkColumn]: fkValue };
+                const dbChild = internal.transformToDbColumns(childTableName, childRow);
+                childBuilder.addRow(dbChild);
+            }
+            const childSQL = childBuilder.toString();
+            await internal.executeRun(childSQL);
+        }
+        await internal.executeRun('COMMIT');
+        const transformed = internal.transformResultsFromDb(ctx.tableName, [parentRow]);
+        return transformed[0];
+    }
+    catch (error) {
+        try {
+            await internal.executeRun('ROLLBACK');
+        }
+        catch {
+        }
+        throw error;
+    }
+}
+function findSchemaKeyByTableName(schema, tableName) {
+    for (const [key, def] of Object.entries(schema)) {
+        if (def?.$name === tableName || key === tableName) {
+            return key;
+        }
+    }
+    return null;
+}
+export function getMysqlPrimaryKeyColumn(relq, tableName) {
+    const schema = relq.schema;
+    if (schema && schema[tableName]) {
+        const tableSchema = schema[tableName];
+        const columns = tableSchema.$columns || tableSchema;
+        for (const [colName, colDef] of Object.entries(columns)) {
+            if (colDef && typeof colDef === 'object' &&
+                ('$primaryKey' in colDef ||
+                    colDef.config?.$primaryKey === true)) {
+                return colName;
+            }
+        }
+    }
+    return 'id';
+}