@relq/orm 0.1.0

package/dist/esm/utils/fk-resolver.js

@@ -0,0 +1,178 @@
+export class ForeignKeyResolutionError extends Error {
+    fromTable;
+    toTable;
+    constructor(fromTable, toTable, message) {
+        super(message || `No foreign key relationship found between "${fromTable}" and "${toTable}"`);
+        this.fromTable = fromTable;
+        this.toTable = toTable;
+        this.name = 'ForeignKeyResolutionError';
+    }
+}
+function isArrayFormat(tableRelations) {
+    return Array.isArray(tableRelations);
+}
+function* iterateForeignKeys(tableRelations) {
+    if (!tableRelations)
+        return;
+    if (isArrayFormat(tableRelations)) {
+        for (const relationDef of tableRelations) {
+            if (relationDef.$type === 'foreignKey' && relationDef.$columns?.length > 0) {
+                const columnKey = relationDef.$columns[0].column;
+                yield [columnKey, relationDef];
+            }
+        }
+    }
+    else {
+        for (const [columnKey, relationDef] of Object.entries(tableRelations)) {
+            yield [columnKey, relationDef];
+        }
+    }
+}
+export function resolveForeignKey(relations, schema, fromTableKey, toTableKey) {
+    if (!relations) {
+        return null;
+    }
+    const fromTableDef = schema[fromTableKey];
+    const toTableDef = schema[toTableKey];
+    if (!fromTableDef || !toTableDef) {
+        return null;
+    }
+    const fromTableName = fromTableDef.$name || fromTableKey;
+    const toTableName = toTableDef.$name || toTableKey;
+    const fromTableRelations = relations[fromTableKey];
+    if (fromTableRelations) {
+        for (const [columnKey, relationDef] of Object.entries(fromTableRelations)) {
+            if (relationDef.$type === 'foreignKey' && relationDef.$targetTable === toTableName) {
+                const fromColumn = getSourceColumnName(fromTableDef, columnKey, relationDef);
+                const toColumn = getTargetColumnName(relationDef, toTableDef);
+                return {
+                    fromTable: fromTableName,
+                    fromColumn,
+                    toTable: toTableName,
+                    toColumn,
+                    direction: 'forward'
+                };
+            }
+        }
+    }
+    const toTableRelations = relations[toTableKey];
+    if (toTableRelations) {
+        for (const [columnKey, relationDef] of Object.entries(toTableRelations)) {
+            if (relationDef.$type === 'foreignKey' && relationDef.$targetTable === fromTableName) {
+                const toColumn = getSourceColumnName(toTableDef, columnKey, relationDef);
+                const fromColumn = getTargetColumnName(relationDef, fromTableDef);
+                return {
+                    fromTable: fromTableName,
+                    fromColumn,
+                    toTable: toTableName,
+                    toColumn,
+                    direction: 'reverse'
+                };
+            }
+        }
+    }
+    return null;
+}
+export function resolveForeignKeyOrThrow(relations, schema, fromTableKey, toTableKey) {
+    const result = resolveForeignKey(relations, schema, fromTableKey, toTableKey);
+    if (!result) {
+        const availableRelations = getAvailableRelations(relations, fromTableKey);
+        let message = `No foreign key relationship found between "${fromTableKey}" and "${toTableKey}".`;
+        if (availableRelations.length > 0) {
+            message += ` Available relations from "${fromTableKey}": ${availableRelations.join(', ')}.`;
+        }
+        else {
+            message += ` No relations defined for "${fromTableKey}".`;
+        }
+        message += ' Use an explicit join condition instead.';
+        throw new ForeignKeyResolutionError(fromTableKey, toTableKey, message);
+    }
+    return result;
+}
+export function getAvailableRelations(relations, tableKey) {
+    if (!relations) {
+        return [];
+    }
+    const tableRelations = relations[tableKey];
+    if (!tableRelations) {
+        return [];
+    }
+    return Object.entries(tableRelations)
+        .filter(([_, def]) => def.$type === 'foreignKey')
+        .map(([key, def]) => `${key} → ${def.$targetTable}`);
+}
+export function getAllForeignKeys(relations, schema, tableKey) {
+    if (!relations) {
+        return [];
+    }
+    const results = [];
+    const tableDef = schema[tableKey];
+    if (!tableDef) {
+        return [];
+    }
+    const tableName = tableDef.$name || tableKey;
+    const tableRelations = relations[tableKey];
+    if (tableRelations) {
+        for (const [columnKey, relationDef] of Object.entries(tableRelations)) {
+            if (relationDef.$type === 'foreignKey') {
+                const targetTableKey = findTableKeyByName(schema, relationDef.$targetTable);
+                const targetTableDef = targetTableKey ? schema[targetTableKey] : null;
+                results.push({
+                    fromTable: tableName,
+                    fromColumn: getSourceColumnName(tableDef, columnKey, relationDef),
+                    toTable: relationDef.$targetTable,
+                    toColumn: getTargetColumnName(relationDef, targetTableDef),
+                    direction: 'forward'
+                });
+            }
+        }
+    }
+    for (const [otherTableKey, otherRelations] of Object.entries(relations)) {
+        if (otherTableKey === tableKey)
+            continue;
+        for (const [columnKey, relationDef] of Object.entries(otherRelations)) {
+            if (relationDef.$type === 'foreignKey' && relationDef.$targetTable === tableName) {
+                const otherTableDef = schema[otherTableKey];
+                results.push({
+                    fromTable: tableName,
+                    fromColumn: getTargetColumnName(relationDef, tableDef),
+                    toTable: otherTableDef?.$name || otherTableKey,
+                    toColumn: getSourceColumnName(otherTableDef, columnKey, relationDef),
+                    direction: 'reverse'
+                });
+            }
+        }
+    }
+    return results;
+}
+function getSourceColumnName(tableDef, columnKey, relationDef) {
+    const colKey = (relationDef.$columns && relationDef.$columns.length > 0)
+        ? relationDef.$columns[0].column
+        : columnKey;
+    if (tableDef && tableDef.$columns && tableDef.$columns[colKey]) {
+        const colDef = tableDef.$columns[colKey];
+        return colDef.$columnName || colKey;
+    }
+    return camelToSnake(colKey);
+}
+function getTargetColumnName(relationDef, targetTableDef) {
+    const colKey = (relationDef.$references && relationDef.$references.length > 0)
+        ? relationDef.$references[0].column
+        : 'id';
+    if (targetTableDef && targetTableDef.$columns && targetTableDef.$columns[colKey]) {
+        const colDef = targetTableDef.$columns[colKey];
+        return colDef.$columnName || colKey;
+    }
+    return colKey;
+}
+function findTableKeyByName(schema, tableName) {
+    for (const [key, def] of Object.entries(schema)) {
+        if (def.$name === tableName || key === tableName) {
+            return key;
+        }
+    }
+    return null;
+}
+function camelToSnake(str) {
+    return str.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+}

package/dist/esm/utils/index.js

@@ -0,0 +1,4 @@
+export { convertCase } from "./case-converter.js";
+export { default as format } from "../shared/pg-format.js";
+export { resolveForeignKey, resolveForeignKeyOrThrow, getAvailableRelations, getAllForeignKeys, ForeignKeyResolutionError } from "./fk-resolver.js";
+export { loadEnvFile, resolvePgEnv, resolveAwsEnv, hasPgEnvConfig, hasAwsEnvConfig, validateEnvConfig, mergeWithPgEnv, mergeWithAwsEnv } from "./env-resolver.js";

package/dist/esm/utils/pool-defaults.js

@@ -0,0 +1,85 @@
+import { detectEnvironment } from "./environment-detection.js";
+export function getSmartPoolDefaults() {
+    const env = detectEnvironment();
+    const baseConfig = {
+        min: 0,
+        idleTimeoutMillis: 10000,
+        connectionTimeoutMillis: 10000,
+    };
+    if (env.type === 'serverless' || env.type === 'edge') {
+        return {
+            ...baseConfig,
+            max: 1,
+            idleTimeoutMillis: 1000,
+            recommendation: `${env.type === 'serverless' ? 'Serverless' : 'Edge'} environment detected (${env.provider}).\n` +
+                '   Pool: min: 0, max: 1 (single lazy connection per invocation)'
+        };
+    }
+    return {
+        ...baseConfig,
+        max: 10,
+        idleTimeoutMillis: 30000,
+        recommendation: 'Traditional server environment.\n' +
+            '   Pool: min: 0, max: 10 (connections created on demand, scale under load)'
+    };
+}
+export function validatePoolConfig(config, env) {
+    const warnings = [];
+    const errors = [];
+    const min = config.min ?? 0;
+    const max = config.max ?? 10;
+    if (env.type === 'edge' && max > 1) {
+        warnings.push(`⚠️  Running in ${env.provider} (edge) with pool max: ${max}.\n` +
+            '   Edge runtimes have short-lived connections.\n' +
+            '   \n' +
+            '   Recommended: pool: { min: 0, max: 1 }');
+    }
+    if (min > max) {
+        warnings.push(`⚠️  Pool min (${min}) is greater than max (${max}).\n` +
+            `   This is invalid. Min will be clamped to max (${max}).`);
+    }
+    if (env.type === 'serverless' && max > 1) {
+        warnings.push(`⚠️  Running in ${env.provider} with pool max: ${max}.\n` +
+            '   Each serverless function will create up to ' + max + ' connections.\n' +
+            '   With many concurrent functions, this can exhaust PostgreSQL connections.\n' +
+            '   \n' +
+            '   Recommended: pool: { min: 0, max: 1 }\n' +
+            '   \n' +
+            '   If you need connection pooling in serverless:\n' +
+            '   - Use PgBouncer or connection pooler\n' +
+            '   - Use Supabase (built-in pooling)\n' +
+            '   - Use Neon serverless driver');
+    }
+    if (env.type === 'traditional' && min > 5) {
+        warnings.push(`⚠️  Pool min set to ${min}. This keeps ${min} connections always open.\n` +
+            '   High min values waste resources when traffic is low.\n' +
+            '   \n' +
+            '   Recommended: min: 0 (connections created on demand)\n' +
+            '   Pool will scale up to max: ' + max + ' under load automatically.');
+    }
+    if (max > 20) {
+        warnings.push(`⚠️  Pool max set to ${max}. This is very high.\n` +
+            '   PostgreSQL connection limit is typically 100-200.\n' +
+            '   Multiple app instances × max connections can exhaust the database.\n' +
+            '   \n' +
+            '   Recommended: max: 10-20 per app instance');
+    }
+    return {
+        valid: errors.length === 0,
+        warnings,
+        errors
+    };
+}
+export function mergeWithDefaults(userConfig) {
+    const defaults = getSmartPoolDefaults();
+    return {
+        min: userConfig?.min ?? defaults.min,
+        max: userConfig?.max ?? defaults.max,
+        idleTimeoutMillis: userConfig?.idleTimeoutMillis ?? defaults.idleTimeoutMillis,
+        connectionTimeoutMillis: userConfig?.connectionTimeoutMillis ?? defaults.connectionTimeoutMillis,
+        recommendation: defaults.recommendation
+    };
+}
+export function formatPoolConfig(config) {
+    return `{ min: ${config.min}, max: ${config.max}, idleTimeout: ${config.idleTimeoutMillis}ms }`;
+}

package/dist/esm/utils/type-coercion.js

@@ -0,0 +1,112 @@
+const BIGINT_TYPES = new Set(['BIGINT', 'INT8', 'BIGSERIAL', 'SERIAL8']);
+const DATE_TYPES = new Set(['TIMESTAMP', 'TIMESTAMPTZ', 'DATE', 'TIME', 'TIMETZ']);
+const JSON_TYPES = new Set(['JSON', 'JSONB']);
+export function deserializeValue(value, pgType) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const upperType = pgType.toUpperCase();
+    if (BIGINT_TYPES.has(upperType)) {
+        if (typeof value === 'string') {
+            return BigInt(value);
+        }
+        if (typeof value === 'number') {
+            return BigInt(value);
+        }
+        return value;
+    }
+    if (DATE_TYPES.has(upperType) || upperType.startsWith('TIMESTAMP')) {
+        if (value instanceof Date) {
+            return value;
+        }
+        if (typeof value === 'string' || typeof value === 'number') {
+            return new Date(value);
+        }
+        return value;
+    }
+    if (JSON_TYPES.has(upperType)) {
+        if (typeof value === 'string') {
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
+        }
+        return value;
+    }
+    if (upperType === 'BOOLEAN' || upperType === 'BOOL') {
+        if (typeof value === 'string') {
+            return value.toLowerCase() === 'true' || value === 't' || value === '1';
+        }
+        return Boolean(value);
+    }
+    return value;
+}
+export function deserializeRow(row, schema) {
+    const result = {};
+    const columnMap = new Map();
+    for (const [key, config] of Object.entries(schema)) {
+        const dbColumnName = config.$columnName || key;
+        const sqlType = config.$sqlType || (typeof config.$type === 'string' ? config.$type : 'TEXT');
+        columnMap.set(dbColumnName, { key, type: sqlType });
+    }
+    for (const [dbColumn, value] of Object.entries(row)) {
+        const mapping = columnMap.get(dbColumn);
+        if (mapping) {
+            result[mapping.key] = deserializeValue(value, mapping.type);
+        }
+        else {
+            result[dbColumn] = value;
+        }
+    }
+    return result;
+}
+export function deserializeRows(rows, schema) {
+    return rows.map(row => deserializeRow(row, schema));
+}
+export function serializeValue(value, pgType) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const upperType = pgType.toUpperCase();
+    if (BIGINT_TYPES.has(upperType)) {
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        return value;
+    }
+    if (DATE_TYPES.has(upperType) || upperType.startsWith('TIMESTAMP')) {
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        return value;
+    }
+    if (JSON_TYPES.has(upperType)) {
+        if (typeof value === 'object' && value !== null) {
+            return JSON.stringify(value);
+        }
+        return value;
+    }
+    return value;
+}
+export function serializeRow(row, schema) {
+    const result = {};
+    for (const [key, value] of Object.entries(row)) {
+        const config = schema[key];
+        if (config) {
+            const sqlType = config.$sqlType || (typeof config.$type === 'string' ? config.$type : 'TEXT');
+            result[key] = serializeValue(value, sqlType);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function extractSchemaColumns(tableDefinition) {
+    if (tableDefinition && tableDefinition.$columns) {
+        return tableDefinition.$columns;
+    }
+    return null;
+}

package/dist/esm/window/index.js

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

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

@@ -0,0 +1,73 @@
+import format from "../shared/pg-format.js";
+export class WindowBuilder {
+    partitionColumns = [];
+    orderColumns = [];
+    frameStart;
+    frameEnd;
+    frameMode;
+    partitionBy(...columns) {
+        this.partitionColumns.push(...columns);
+        return this;
+    }
+    orderBy(column, direction = 'ASC') {
+        this.orderColumns.push({ column, direction });
+        return this;
+    }
+    rows(start, end) {
+        this.frameMode = 'ROWS';
+        this.frameStart = typeof start === 'number' ? `${start} PRECEDING` : start;
+        this.frameEnd = end ? (typeof end === 'number' ? `${end} FOLLOWING` : end) : 'CURRENT ROW';
+        return this;
+    }
+    range(start, end) {
+        this.frameMode = 'RANGE';
+        this.frameStart = typeof start === 'number' ? `${start} PRECEDING` : start;
+        this.frameEnd = end ? (typeof end === 'number' ? `${end} FOLLOWING` : end) : 'CURRENT ROW';
+        return this;
+    }
+    groups(start, end) {
+        this.frameMode = 'GROUPS';
+        this.frameStart = typeof start === 'number' ? `${start} PRECEDING` : start;
+        this.frameEnd = end ? (typeof end === 'number' ? `${end} FOLLOWING` : end) : 'CURRENT ROW';
+        return this;
+    }
+    toString() {
+        const parts = [];
+        if (this.partitionColumns.length > 0) {
+            parts.push(`PARTITION BY ${this.partitionColumns.map(c => format.ident(c)).join(', ')}`);
+        }
+        if (this.orderColumns.length > 0) {
+            parts.push(`ORDER BY ${this.orderColumns.map(o => `${format.ident(o.column)} ${o.direction}`).join(', ')}`);
+        }
+        if (this.frameMode && this.frameStart) {
+            parts.push(`${this.frameMode} BETWEEN ${this.frameStart} AND ${this.frameEnd}`);
+        }
+        return parts.join(' ');
+    }
+    rowNumber() {
+        return `ROW_NUMBER() OVER (${this.toString()})`;
+    }
+    rank() {
+        return `RANK() OVER (${this.toString()})`;
+    }
+    denseRank() {
+        return `DENSE_RANK() OVER (${this.toString()})`;
+    }
+    lag(column, offset = 1, defaultValue) {
+        const def = defaultValue !== undefined ? `, ${format('%L', defaultValue)}` : '';
+        return `LAG(${format.ident(column)}, ${offset}${def}) OVER (${this.toString()})`;
+    }
+    lead(column, offset = 1, defaultValue) {
+        const def = defaultValue !== undefined ? `, ${format('%L', defaultValue)}` : '';
+        return `LEAD(${format.ident(column)}, ${offset}${def}) OVER (${this.toString()})`;
+    }
+    firstValue(column) {
+        return `FIRST_VALUE(${format.ident(column)}) OVER (${this.toString()})`;
+    }
+    lastValue(column) {
+        return `LAST_VALUE(${format.ident(column)}) OVER (${this.toString()})`;
+    }
+    nthValue(column, n) {
+        return `NTH_VALUE(${format.ident(column)}, ${n}) OVER (${this.toString()})`;
+    }
+}

package/dist/index.cjs

@@ -0,0 +1 @@
+module.exports = require('./cjs/index.cjs');