relq 1.0.0

package/dist/esm/errors/relq-errors.js

@@ -0,0 +1,310 @@
+export function setupErrorHandler() {
+    if (typeof process === 'undefined' || !process.on)
+        return;
+    process.on('uncaughtException', (error) => {
+        if (error instanceof RelqError) {
+            const inspect = error[Symbol.for('nodejs.util.inspect.custom')];
+            if (typeof inspect === 'function') {
+                console.error(inspect.call(error, 0, {}));
+            }
+            else {
+                console.error(`${error.name}: ${error.message}`);
+            }
+        }
+        else {
+            console.error(`${error.name || 'Error'}: ${error.message}`);
+            if (error.stack) {
+                const stackLines = error.stack.split('\n').filter(line => line.trim().startsWith('at '));
+                console.error(stackLines.slice(0, 5).join('\n'));
+            }
+        }
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        if (reason instanceof RelqError) {
+            const inspect = reason[Symbol.for('nodejs.util.inspect.custom')];
+            if (typeof inspect === 'function') {
+                console.error(inspect.call(reason, 0, {}));
+            }
+            else {
+                console.error(`${reason.name}: ${reason.message}`);
+            }
+        }
+        else if (reason instanceof Error) {
+            console.error(`${reason.name || 'Error'}: ${reason.message}`);
+            if (reason.stack) {
+                const stackLines = reason.stack.split('\n').filter(line => line.trim().startsWith('at '));
+                console.error(stackLines.slice(0, 5).join('\n'));
+            }
+        }
+        else {
+            console.error('Unhandled rejection:', reason);
+        }
+        process.exit(1);
+    });
+}
+export class RelqError extends Error {
+    name;
+    cause;
+    timestamp;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'RelqError';
+        this.cause = cause;
+        this.timestamp = new Date();
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    [Symbol.for('nodejs.util.inspect.custom')](_depth, _options) {
+        const lines = [
+            `${this.name}: ${this.message}`,
+            ` timestamp: ${this.timestamp.toISOString()}`
+        ];
+        const props = this._getInspectProps();
+        for (const [key, value] of Object.entries(props)) {
+            const strVal = value === undefined ? 'undefined' : JSON.stringify(value);
+            lines.push(`${key.padStart(10)}: ${strVal}`);
+        }
+        if (this.stack) {
+            const stackLines = this.stack.split('\n').filter(line => line.trim().startsWith('at ') || line.includes(this.name));
+            lines.push('');
+            lines.push(...stackLines.slice(1, 6));
+        }
+        return lines.join('\n');
+    }
+    _getInspectProps() {
+        return {};
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            cause: this.cause?.message,
+            timestamp: this.timestamp.toISOString(),
+            stack: this.stack
+        };
+    }
+}
+export class RelqConnectionError extends RelqError {
+    name = 'RelqConnectionError';
+    code;
+    host;
+    port;
+    constructor(message, options) {
+        super(message, options?.cause);
+        this.code = options?.code;
+        this.host = options?.host;
+        this.port = options?.port;
+    }
+    _getInspectProps() {
+        return { code: this.code, host: this.host, port: this.port };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            code: this.code,
+            host: this.host,
+            port: this.port
+        };
+    }
+}
+export class RelqQueryError extends RelqError {
+    name = 'RelqQueryError';
+    sql;
+    code;
+    detail;
+    hint;
+    constructor(message, options) {
+        super(message, options?.cause);
+        this.sql = options?.sql;
+        this.code = options?.code;
+        this.detail = options?.detail;
+        this.hint = options?.hint;
+    }
+    _getInspectProps() {
+        return { sql: this.sql, detail: this.detail, hint: this.hint, code: this.code };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            sql: this.sql,
+            code: this.code,
+            detail: this.detail,
+            hint: this.hint
+        };
+    }
+}
+export class RelqTransactionError extends RelqError {
+    name = 'RelqTransactionError';
+    operation;
+    transactionState;
+    constructor(message, operation, options) {
+        super(message, options?.cause);
+        this.operation = operation;
+        this.transactionState = options?.transactionState;
+    }
+    _getInspectProps() {
+        return { operation: this.operation, transactionState: this.transactionState };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            operation: this.operation,
+            transactionState: this.transactionState
+        };
+    }
+}
+export class RelqConfigError extends RelqError {
+    name = 'RelqConfigError';
+    field;
+    value;
+    constructor(message, options) {
+        super(message);
+        this.field = options?.field;
+        this.value = options?.value;
+    }
+    _getInspectProps() {
+        return { field: this.field, value: this.value };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            field: this.field,
+            value: this.value
+        };
+    }
+}
+export class RelqTimeoutError extends RelqError {
+    name = 'RelqTimeoutError';
+    timeout;
+    operation;
+    constructor(message, timeout, operation, cause) {
+        super(message, cause);
+        this.timeout = timeout;
+        this.operation = operation;
+    }
+    _getInspectProps() {
+        return { timeout: this.timeout, operation: this.operation };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            timeout: this.timeout,
+            operation: this.operation
+        };
+    }
+}
+export class RelqPoolError extends RelqError {
+    name = 'RelqPoolError';
+    poolSize;
+    activeConnections;
+    waitingClients;
+    constructor(message, options) {
+        super(message, options?.cause);
+        this.poolSize = options?.poolSize;
+        this.activeConnections = options?.activeConnections;
+        this.waitingClients = options?.waitingClients;
+    }
+    _getInspectProps() {
+        return { poolSize: this.poolSize, activeConnections: this.activeConnections, waitingClients: this.waitingClients };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            poolSize: this.poolSize,
+            activeConnections: this.activeConnections,
+            waitingClients: this.waitingClients
+        };
+    }
+}
+export class RelqEnvironmentError extends RelqError {
+    name = 'RelqEnvironmentError';
+    environment;
+    reason;
+    constructor(message, environment, reason) {
+        super(message);
+        this.environment = environment;
+        this.reason = reason;
+    }
+    _getInspectProps() {
+        return { environment: this.environment, reason: this.reason };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            environment: this.environment,
+            reason: this.reason
+        };
+    }
+}
+export class RelqBuilderError extends RelqError {
+    name = 'RelqBuilderError';
+    builder;
+    missing;
+    hint;
+    constructor(message, options) {
+        super(message);
+        this.builder = options?.builder;
+        this.missing = options?.missing;
+        this.hint = options?.hint;
+    }
+    _getInspectProps() {
+        return { builder: this.builder, missing: this.missing, hint: this.hint };
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            builder: this.builder,
+            missing: this.missing,
+            hint: this.hint
+        };
+    }
+}
+export function isRelqError(error) {
+    return error instanceof RelqError;
+}
+export function isRelqConnectionError(error) {
+    return error instanceof RelqConnectionError;
+}
+export function isRelqQueryError(error) {
+    return error instanceof RelqQueryError;
+}
+export function isRelqBuilderError(error) {
+    return error instanceof RelqBuilderError;
+}
+export function wrapError(error, context) {
+    if (isRelqError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        const message = context ? `${context}: ${error.message}` : error.message;
+        return new RelqError(message, error);
+    }
+    const message = context
+        ? `${context}: ${String(error)}`
+        : String(error);
+    return new RelqError(message);
+}
+export function parsePostgresError(error, sql) {
+    const message = error.message || 'Database error';
+    const code = error.code;
+    if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT') {
+        return new RelqConnectionError(message, {
+            cause: error,
+            code,
+            host: error.hostname,
+            port: error.port
+        });
+    }
+    if (code === '57014') {
+        return new RelqTimeoutError('Query execution timed out', error.timeout || 0, 'query', error);
+    }
+    return new RelqQueryError(message, {
+        cause: error,
+        sql,
+        code,
+        detail: error.detail,
+        hint: error.hint
+    });
+}

package/dist/esm/examples/fulltext-search-test.js

@@ -0,0 +1,117 @@
+import relq from "../index.js";
+const alterTableSQL = relq('results')
+    .alterTable()
+    .addColumn('search_vector', {
+    type: 'tsvector',
+    generated: {
+        always: true,
+        expression: `
+                setweight(to_tsvector('english', coalesce(email, '')), 'A') ||
+                setweight(to_tsvector('english', coalesce(ip_address, '')), 'B') ||
+                setweight(to_tsvector('english', coalesce(country, '')), 'C') ||
+                setweight(to_tsvector('english', coalesce(city, '')), 'C') ||
+                setweight(to_tsvector('english', coalesce(device, '')), 'D') ||
+                setweight(to_tsvector('english', coalesce(browser, '')), 'D')
+            `.trim()
+    }
+}, true)
+    .toString();
+console.log('=== ALTER TABLE ===');
+console.log(alterTableSQL);
+console.log('');
+const createIndexSQL = relq('results')
+    .createIndex('idx_results_search_gin')
+    .gin(['search_vector'], 'tsvector_ops')
+    .where("user_id IS NOT NULL AND is_deleted = FALSE")
+    .ifNotExists()
+    .toString();
+console.log('=== CREATE INDEX ===');
+console.log(createIndexSQL);
+console.log('');
+const searchQuery = relq('results')
+    .select([
+    'id',
+    'email',
+    'ip_address',
+    'country',
+    'city',
+    'device',
+    'browser',
+    'is_pinned',
+    'updated_at'
+])
+    .where(q => q
+    .equal('user_id', 'abc')
+    .equal('is_deleted', false)
+    .fulltext.search('search_vector', 'john@gmail'))
+    .orderBy('is_pinned', 'DESC')
+    .orderBy('updated_at', 'DESC')
+    .toString();
+console.log('=== SELECT QUERY ===');
+console.log(searchQuery);
+console.log('');
+console.log('=== ADDITIONAL EXAMPLES ===\n');
+const sortIndexSQL = relq('results')
+    .createIndex('idx_results_sort')
+    .btree([
+    { column: 'is_pinned', order: 'DESC' },
+    { column: 'updated_at', order: 'DESC' }
+])
+    .where("is_deleted = FALSE")
+    .ifNotExists()
+    .toString();
+console.log('1. Multi-column sort index:');
+console.log(sortIndexSQL);
+console.log('');
+const userIndexSQL = relq('results')
+    .createIndex('idx_results_user_deleted')
+    .btree(['user_id', 'is_deleted'])
+    .ifNotExists()
+    .toString();
+console.log('2. User + deleted filter index:');
+console.log(userIndexSQL);
+console.log('');
+const rankedSearchQuery = relq('results')
+    .select(['id', 'email', 'country'])
+    .where(q => q
+    .equal('user_id', 'abc')
+    .equal('is_deleted', false)
+    .fulltext.rank('search_vector', 'california', 0.1))
+    .toString();
+console.log('3. Search with minimum rank threshold:');
+console.log(rankedSearchQuery);
+console.log('');
+const alterWithIdentitySQL = relq('users')
+    .alterTable()
+    .addColumn('sequence_id', {
+    type: 'integer',
+    generated: {
+        always: false,
+        expression: 'nextval(\'user_seq\'::regclass)'
+    }
+})
+    .toString();
+console.log('4. Generated column with BY DEFAULT:');
+console.log(alterWithIdentitySQL);
+console.log('');
+const multipleActionsSQL = relq('results')
+    .alterTable()
+    .addColumn('search_vector', {
+    type: 'tsvector',
+    generated: {
+        always: true,
+        expression: `to_tsvector('english', coalesce(email, ''))`
+    }
+})
+    .addColumn('full_name', {
+    type: 'text',
+    generated: {
+        always: true,
+        expression: `coalesce(first_name, '') || ' ' || coalesce(last_name, '')`
+    }
+})
+    .toString();
+console.log('5. Multiple generated columns:');
+console.log(multipleActionsSQL);
+console.log('');
+console.log('✅ All examples generated successfully!');

package/dist/esm/explain/explain-builder.js

@@ -0,0 +1,95 @@
+export class ExplainBuilder {
+    query;
+    options;
+    constructor(query, options = {}) {
+        this.query = query;
+        this.options = options;
+    }
+    analyze(enable = true) {
+        this.options.analyze = enable;
+        return this;
+    }
+    verbose(enable = true) {
+        this.options.verbose = enable;
+        return this;
+    }
+    costs(enable = true) {
+        this.options.costs = enable;
+        return this;
+    }
+    settings(enable = true) {
+        this.options.settings = enable;
+        return this;
+    }
+    buffers(enable = true) {
+        this.options.buffers = enable;
+        if (enable) {
+            this.options.analyze = true;
+        }
+        return this;
+    }
+    timing(enable = true) {
+        this.options.timing = enable;
+        if (enable) {
+            this.options.analyze = true;
+        }
+        return this;
+    }
+    summary(enable = true) {
+        this.options.summary = enable;
+        return this;
+    }
+    wal(enable = true) {
+        this.options.wal = enable;
+        if (enable) {
+            this.options.analyze = true;
+        }
+        return this;
+    }
+    format(format) {
+        this.options.format = format;
+        return this;
+    }
+    toString() {
+        const options = [];
+        if (this.options.analyze) {
+            options.push('ANALYZE');
+        }
+        if (this.options.verbose) {
+            options.push('VERBOSE');
+        }
+        if (this.options.costs === false) {
+            options.push('COSTS FALSE');
+        }
+        else if (this.options.costs === true) {
+            options.push('COSTS TRUE');
+        }
+        if (this.options.settings) {
+            options.push('SETTINGS');
+        }
+        if (this.options.buffers) {
+            options.push('BUFFERS');
+        }
+        if (this.options.timing === false) {
+            options.push('TIMING FALSE');
+        }
+        else if (this.options.timing === true) {
+            options.push('TIMING TRUE');
+        }
+        if (this.options.summary) {
+            options.push('SUMMARY');
+        }
+        if (this.options.wal) {
+            options.push('WAL');
+        }
+        if (this.options.format) {
+            options.push(`FORMAT ${this.options.format}`);
+        }
+        let sql = 'EXPLAIN';
+        if (options.length > 0) {
+            sql += ` (${options.join(', ')})`;
+        }
+        sql += ' ' + this.query;
+        return sql;
+    }
+}

package/dist/esm/explain/index.js

@@ -0,0 +1 @@
+export { ExplainBuilder } from "./explain-builder.js";

package/dist/esm/function/create-function-builder.js

@@ -0,0 +1,188 @@
+import format from "../../addons/pg-format.js";
+import { RelqBuilderError } from "../errors/relq-errors.js";
+export class CreateFunctionBuilder {
+    functionName;
+    __parameters = [];
+    returnType;
+    __returnsTable;
+    __returnsSetOf;
+    __language = 'plpgsql';
+    functionBody;
+    volatility = 'VOLATILE';
+    security = 'INVOKER';
+    __parallel = 'UNSAFE';
+    costValue;
+    rowsValue;
+    strictFlag = false;
+    leakproofFlag = false;
+    orReplaceFlag = false;
+    constructor(functionName) {
+        this.functionName = functionName;
+    }
+    parameter(name, type, defaultValue, mode = 'IN') {
+        this.__parameters.push({ name, type, default: defaultValue, mode });
+        return this;
+    }
+    parameters(params) {
+        Object.entries(params).forEach(([name, type]) => {
+            this.__parameters.push({ name, type });
+        });
+        return this;
+    }
+    returns(type) {
+        this.returnType = type;
+        return this;
+    }
+    returnsTable(columns) {
+        this.__returnsTable = columns;
+        return this;
+    }
+    returnsSetOf(type) {
+        this.__returnsSetOf = type;
+        return this;
+    }
+    language(lang) {
+        this.__language = lang;
+        return this;
+    }
+    body(sql) {
+        this.functionBody = sql.trim();
+        return this;
+    }
+    immutable() {
+        this.volatility = 'IMMUTABLE';
+        return this;
+    }
+    stable() {
+        this.volatility = 'STABLE';
+        return this;
+    }
+    volatile() {
+        this.volatility = 'VOLATILE';
+        return this;
+    }
+    securityDefiner() {
+        this.security = 'DEFINER';
+        return this;
+    }
+    securityInvoker() {
+        this.security = 'INVOKER';
+        return this;
+    }
+    parallel(safety) {
+        this.__parallel = safety;
+        return this;
+    }
+    strict() {
+        this.strictFlag = true;
+        return this;
+    }
+    leakproof() {
+        this.leakproofFlag = true;
+        return this;
+    }
+    cost(estimatedCost) {
+        this.costValue = estimatedCost;
+        return this;
+    }
+    rows(estimatedRows) {
+        this.rowsValue = estimatedRows;
+        return this;
+    }
+    orReplace() {
+        this.orReplaceFlag = true;
+        return this;
+    }
+    toString() {
+        if (!this.returnType && !this.__returnsTable && !this.__returnsSetOf) {
+            throw new RelqBuilderError('Return type is required', { builder: 'CreateFunctionBuilder', missing: 'returnType', hint: 'Use .returns(), .returnsTable(), or .returnsSetOf()' });
+        }
+        if (!this.functionBody) {
+            throw new RelqBuilderError('Function body is required', { builder: 'CreateFunctionBuilder', missing: 'body', hint: 'Use .body()' });
+        }
+        let sql = 'CREATE';
+        if (this.orReplaceFlag) {
+            sql += ' OR REPLACE';
+        }
+        sql += ` FUNCTION ${format.ident(this.functionName)}`;
+        if (this.__parameters.length > 0) {
+            const params = this.__parameters.map(p => {
+                let paramSQL = '';
+                if (p.mode && p.mode !== 'IN') {
+                    paramSQL += `${p.mode} `;
+                }
+                paramSQL += `${format.ident(p.name)} ${p.type}`;
+                if (p.default !== undefined) {
+                    paramSQL += ` DEFAULT ${format('%L', p.default)}`;
+                }
+                return paramSQL;
+            });
+            sql += `(${params.join(', ')})`;
+        }
+        else {
+            sql += '()';
+        }
+        if (this.__returnsTable) {
+            const tableCols = Object.entries(this.__returnsTable)
+                .map(([name, type]) => `${format.ident(name)} ${type}`)
+                .join(', ');
+            sql += ` RETURNS TABLE(${tableCols})`;
+        }
+        else if (this.__returnsSetOf) {
+            sql += ` RETURNS SETOF ${this.__returnsSetOf}`;
+        }
+        else {
+            sql += ` RETURNS ${this.returnType}`;
+        }
+        sql += ` LANGUAGE ${this.language}`;
+        sql += ` ${this.volatility}`;
+        if (this.strictFlag) {
+            sql += ' STRICT';
+        }
+        sql += ` SECURITY ${this.security}`;
+        sql += ` PARALLEL ${this.__parallel}`;
+        if (this.leakproofFlag) {
+            sql += ' LEAKPROOF';
+        }
+        if (this.costValue !== undefined) {
+            sql += ` COST ${this.costValue}`;
+        }
+        if (this.rowsValue !== undefined) {
+            sql += ` ROWS ${this.rowsValue}`;
+        }
+        sql += ` AS $$${this.functionBody}$$`;
+        return sql;
+    }
+}
+export class DropFunctionBuilder {
+    functionName;
+    parameterTypes;
+    ifExistsFlag = false;
+    cascadeFlag = false;
+    constructor(functionName, parameterTypes) {
+        this.functionName = functionName;
+        this.parameterTypes = parameterTypes;
+    }
+    ifExists() {
+        this.ifExistsFlag = true;
+        return this;
+    }
+    cascade() {
+        this.cascadeFlag = true;
+        return this;
+    }
+    toString() {
+        let sql = 'DROP FUNCTION';
+        if (this.ifExistsFlag) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${format.ident(this.functionName)}`;
+        if (this.parameterTypes && this.parameterTypes.length > 0) {
+            sql += `(${this.parameterTypes.join(', ')})`;
+        }
+        if (this.cascadeFlag) {
+            sql += ' CASCADE';
+        }
+        return sql;
+    }
+}

package/dist/esm/function/index.js

@@ -0,0 +1 @@
+export { CreateFunctionBuilder, DropFunctionBuilder } from "./create-function-builder.js";