relq 1.0.42 → 1.0.44

package/dist/cjs/core/relq-client.cjs

@@ -43,6 +43,7 @@ const pool_defaults_1 = require("../utils/pool-defaults.cjs");
 const relq_errors_1 = require("../errors/relq-errors.cjs");
 const type_coercion_1 = require("../utils/type-coercion.cjs");
 const helpers_1 = require("./helpers/index.cjs");
+const scalar_select_builder_1 = require("../select/scalar-select-builder.cjs");
 let PgPool = null;
 let PgClient = null;
 const activeRelqInstances = new Set();
@@ -720,6 +721,14 @@ class Relq {
         }
         return result.result.rows.map((r) => r['QUERY PLAN'] || Object.values(r)[0]).join('\n');
     }
+    scalar(scalars) {
+        const schema = this._getSchema();
+        return new scalar_select_builder_1.ConnectedScalarSelectBuilder(scalars, schema, {
+            executeSelectOne: this[helpers_1.INTERNAL].executeSelect.bind(this),
+            hasColumnMapping: this._hasColumnMapping.bind(this),
+            transformToDbColumns: this._transformToDbColumns.bind(this)
+        });
+    }
 }
 exports.Relq = Relq;
 exports.default = Relq;

package/dist/cjs/select/scalar-query-builder.cjs

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScalarQueryBuilderImpl = void 0;
+exports.createScalarTableAccessor = createScalarTableAccessor;
+const pg_format_1 = __importDefault(require("../addon/pg-format/index.cjs"));
+const condition_collector_1 = require("../condition/condition-collector.cjs");
+class ScalarResultImpl {
+    sql;
+    params;
+    $scalar = true;
+    $type;
+    constructor(sql, params = []) {
+        this.sql = sql;
+        this.params = params;
+    }
+    toSQL() {
+        return this.sql;
+    }
+    getParams() {
+        return this.params;
+    }
+}
+class ScalarQueryBuilderImpl {
+    tableName;
+    tableSchema;
+    columnResolver;
+    whereConditions = [];
+    constructor(tableName, tableSchema, columnResolver) {
+        this.tableName = tableName;
+        this.tableSchema = tableSchema;
+        this.columnResolver = columnResolver;
+    }
+    where(callback) {
+        const conditionBuilder = new condition_collector_1.ConditionCollector();
+        callback(conditionBuilder);
+        this.whereConditions.push(...conditionBuilder.getConditions());
+        return this;
+    }
+    count() {
+        const sql = this.buildSQL('COUNT(*)');
+        return new ScalarResultImpl(sql);
+    }
+    sum(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`COALESCE(SUM(${pg_format_1.default.ident(sqlColumn)}), 0)`);
+        return new ScalarResultImpl(sql);
+    }
+    avg(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`COALESCE(AVG(${pg_format_1.default.ident(sqlColumn)}), 0)`);
+        return new ScalarResultImpl(sql);
+    }
+    min(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`MIN(${pg_format_1.default.ident(sqlColumn)})`);
+        return new ScalarResultImpl(sql);
+    }
+    max(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`MAX(${pg_format_1.default.ident(sqlColumn)})`);
+        return new ScalarResultImpl(sql);
+    }
+    pick(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(pg_format_1.default.ident(sqlColumn), true);
+        return new ScalarResultImpl(sql);
+    }
+    exists() {
+        const whereClause = this.buildWhereClause();
+        const sql = `(EXISTS(SELECT 1 FROM ${pg_format_1.default.ident(this.tableName)}${whereClause}))`;
+        return new ScalarResultImpl(sql);
+    }
+    resolveColumn(column) {
+        if (this.columnResolver) {
+            return this.columnResolver(column);
+        }
+        const columns = this.tableSchema?.$columns || this.tableSchema;
+        const columnDef = columns?.[column];
+        if (columnDef?.$columnName) {
+            return columnDef.$columnName;
+        }
+        return column.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+    }
+    transformConditions(conditions) {
+        if (!this.columnResolver && !this.tableSchema) {
+            return conditions;
+        }
+        return conditions.map(cond => {
+            if (!cond.column || cond.method === 'raw') {
+                return cond;
+            }
+            if (cond.method === 'or' || cond.method === 'and') {
+                return {
+                    ...cond,
+                    values: this.transformConditions(cond.values)
+                };
+            }
+            return {
+                ...cond,
+                column: this.resolveColumn(cond.column)
+            };
+        });
+    }
+    buildWhereClause() {
+        if (this.whereConditions.length === 0) {
+            return '';
+        }
+        const transformed = this.transformConditions(this.whereConditions);
+        return ` WHERE ${(0, condition_collector_1.buildConditionsSQL)(transformed)}`;
+    }
+    buildSQL(selectExpr, withLimit = false) {
+        const whereClause = this.buildWhereClause();
+        const limitClause = withLimit ? ' LIMIT 1' : '';
+        return `(SELECT ${selectExpr} FROM ${pg_format_1.default.ident(this.tableName)}${whereClause}${limitClause})`;
+    }
+}
+exports.ScalarQueryBuilderImpl = ScalarQueryBuilderImpl;
+function createScalarTableAccessor(schema, getColumnResolver) {
+    return new Proxy({}, {
+        get(_, prop) {
+            if (typeof prop === 'symbol') {
+                return undefined;
+            }
+            const tables = schema?.tables || schema;
+            const tableDef = tables?.[prop];
+            const sqlTableName = tableDef?.$name || prop;
+            const columnResolver = getColumnResolver?.(sqlTableName);
+            return new ScalarQueryBuilderImpl(sqlTableName, tableDef, columnResolver);
+        }
+    });
+}

package/dist/cjs/select/scalar-select-builder.cjs

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectedScalarSelectBuilder = exports.ScalarSelectBuilder = void 0;
+const pg_format_1 = __importDefault(require("../addon/pg-format/index.cjs"));
+const scalar_query_builder_1 = require("./scalar-query-builder.cjs");
+class ScalarSelectBuilder {
+    executeQuery;
+    scalarResults;
+    constructor(scalars, schema, executeQuery, getColumnResolver) {
+        this.executeQuery = executeQuery;
+        const tableAccessor = (0, scalar_query_builder_1.createScalarTableAccessor)(schema, getColumnResolver);
+        this.scalarResults = {};
+        for (const [key, callback] of Object.entries(scalars)) {
+            this.scalarResults[key] = callback(tableAccessor);
+        }
+    }
+    toString() {
+        const columns = Object.entries(this.scalarResults)
+            .map(([alias, scalar]) => `${scalar.toSQL()} AS ${pg_format_1.default.ident(alias)}`)
+            .join(', ');
+        return `SELECT ${columns}`;
+    }
+    async get(withMetadata) {
+        const sql = this.toString();
+        const { data, metadata } = await this.executeQuery(sql);
+        const row = Array.isArray(data) ? data[0] : data;
+        const result = this.transformResult(row);
+        if (withMetadata) {
+            return { data: result, metadata };
+        }
+        return result;
+    }
+    transformResult(row) {
+        if (!row) {
+            const result = {};
+            for (const key of Object.keys(this.scalarResults)) {
+                result[key] = null;
+            }
+            return result;
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(row)) {
+            if (typeof value === 'string' && /^\d+$/.test(value)) {
+                result[key] = parseInt(value, 10);
+            }
+            else if (typeof value === 'string' && /^\d+\.\d+$/.test(value)) {
+                result[key] = parseFloat(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+}
+exports.ScalarSelectBuilder = ScalarSelectBuilder;
+class ConnectedScalarSelectBuilder extends ScalarSelectBuilder {
+    constructor(scalars, schema, internal) {
+        const executeQuery = async (sql) => {
+            return internal.executeSelectOne(sql);
+        };
+        const getColumnResolver = (tableName) => {
+            if (internal.hasColumnMapping()) {
+                return (column) => {
+                    const transformed = internal.transformToDbColumns(tableName, { [column]: null });
+                    const keys = Object.keys(transformed);
+                    return keys.length > 0 ? keys[0] : column;
+                };
+            }
+            return undefined;
+        };
+        super(scalars, schema, executeQuery, getColumnResolver);
+    }
+}
+exports.ConnectedScalarSelectBuilder = ConnectedScalarSelectBuilder;

package/dist/cjs/types/scalar-types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/utils/fk-resolver.cjs

@@ -16,6 +16,26 @@ class ForeignKeyResolutionError extends Error {
     }
 }
 exports.ForeignKeyResolutionError = 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];
+        }
+    }
+}
 function resolveForeignKey(relations, schema, fromTableKey, toTableKey) {
     if (!relations) {
         return null;

package/dist/esm/core/relq-client.js

@@ -7,6 +7,7 @@ import { validatePoolConfig, formatPoolConfig, getSmartPoolDefaults } from "../u
 import { RelqEnvironmentError, RelqConfigError, RelqQueryError, RelqConnectionError, parsePostgresError } from "../errors/relq-errors.js";
 import { deserializeValue, serializeValue } from "../utils/type-coercion.js";
 import { ConnectedCTEBuilder, ConnectedQueryBuilder, ConnectedRawQueryBuilder, ConnectedTransactionBuilder, INTERNAL, debugLog } from "./helpers/index.js";
+import { ConnectedScalarSelectBuilder } from "../select/scalar-select-builder.js";
 let PgPool = null;
 let PgClient = null;
 const activeRelqInstances = new Set();
@@ -684,5 +685,13 @@ export class Relq {
         }
         return result.result.rows.map((r) => r['QUERY PLAN'] || Object.values(r)[0]).join('\n');
     }
+    scalar(scalars) {
+        const schema = this._getSchema();
+        return new ConnectedScalarSelectBuilder(scalars, schema, {
+            executeSelectOne: this[INTERNAL].executeSelect.bind(this),
+            hasColumnMapping: this._hasColumnMapping.bind(this),
+            transformToDbColumns: this._transformToDbColumns.bind(this)
+        });
+    }
 }
 export default Relq;

package/dist/esm/select/scalar-query-builder.js

@@ -0,0 +1,126 @@
+import format from "../addon/pg-format/index.js";
+import { ConditionCollector, buildConditionsSQL } from "../condition/condition-collector.js";
+class ScalarResultImpl {
+    sql;
+    params;
+    $scalar = true;
+    $type;
+    constructor(sql, params = []) {
+        this.sql = sql;
+        this.params = params;
+    }
+    toSQL() {
+        return this.sql;
+    }
+    getParams() {
+        return this.params;
+    }
+}
+export class ScalarQueryBuilderImpl {
+    tableName;
+    tableSchema;
+    columnResolver;
+    whereConditions = [];
+    constructor(tableName, tableSchema, columnResolver) {
+        this.tableName = tableName;
+        this.tableSchema = tableSchema;
+        this.columnResolver = columnResolver;
+    }
+    where(callback) {
+        const conditionBuilder = new ConditionCollector();
+        callback(conditionBuilder);
+        this.whereConditions.push(...conditionBuilder.getConditions());
+        return this;
+    }
+    count() {
+        const sql = this.buildSQL('COUNT(*)');
+        return new ScalarResultImpl(sql);
+    }
+    sum(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`COALESCE(SUM(${format.ident(sqlColumn)}), 0)`);
+        return new ScalarResultImpl(sql);
+    }
+    avg(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`COALESCE(AVG(${format.ident(sqlColumn)}), 0)`);
+        return new ScalarResultImpl(sql);
+    }
+    min(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`MIN(${format.ident(sqlColumn)})`);
+        return new ScalarResultImpl(sql);
+    }
+    max(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(`MAX(${format.ident(sqlColumn)})`);
+        return new ScalarResultImpl(sql);
+    }
+    pick(column) {
+        const sqlColumn = this.resolveColumn(column);
+        const sql = this.buildSQL(format.ident(sqlColumn), true);
+        return new ScalarResultImpl(sql);
+    }
+    exists() {
+        const whereClause = this.buildWhereClause();
+        const sql = `(EXISTS(SELECT 1 FROM ${format.ident(this.tableName)}${whereClause}))`;
+        return new ScalarResultImpl(sql);
+    }
+    resolveColumn(column) {
+        if (this.columnResolver) {
+            return this.columnResolver(column);
+        }
+        const columns = this.tableSchema?.$columns || this.tableSchema;
+        const columnDef = columns?.[column];
+        if (columnDef?.$columnName) {
+            return columnDef.$columnName;
+        }
+        return column.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+    }
+    transformConditions(conditions) {
+        if (!this.columnResolver && !this.tableSchema) {
+            return conditions;
+        }
+        return conditions.map(cond => {
+            if (!cond.column || cond.method === 'raw') {
+                return cond;
+            }
+            if (cond.method === 'or' || cond.method === 'and') {
+                return {
+                    ...cond,
+                    values: this.transformConditions(cond.values)
+                };
+            }
+            return {
+                ...cond,
+                column: this.resolveColumn(cond.column)
+            };
+        });
+    }
+    buildWhereClause() {
+        if (this.whereConditions.length === 0) {
+            return '';
+        }
+        const transformed = this.transformConditions(this.whereConditions);
+        return ` WHERE ${buildConditionsSQL(transformed)}`;
+    }
+    buildSQL(selectExpr, withLimit = false) {
+        const whereClause = this.buildWhereClause();
+        const limitClause = withLimit ? ' LIMIT 1' : '';
+        return `(SELECT ${selectExpr} FROM ${format.ident(this.tableName)}${whereClause}${limitClause})`;
+    }
+}
+export function createScalarTableAccessor(schema, getColumnResolver) {
+    return new Proxy({}, {
+        get(_, prop) {
+            if (typeof prop === 'symbol') {
+                return undefined;
+            }
+            const tables = schema?.tables || schema;
+            const tableDef = tables?.[prop];
+            const sqlTableName = tableDef?.$name || prop;
+            const columnResolver = getColumnResolver?.(sqlTableName);
+            return new ScalarQueryBuilderImpl(sqlTableName, tableDef, columnResolver);
+        }
+    });
+}

package/dist/esm/select/scalar-select-builder.js

@@ -0,0 +1,70 @@
+import format from "../addon/pg-format/index.js";
+import { createScalarTableAccessor } from "./scalar-query-builder.js";
+export class ScalarSelectBuilder {
+    executeQuery;
+    scalarResults;
+    constructor(scalars, schema, executeQuery, getColumnResolver) {
+        this.executeQuery = executeQuery;
+        const tableAccessor = createScalarTableAccessor(schema, getColumnResolver);
+        this.scalarResults = {};
+        for (const [key, callback] of Object.entries(scalars)) {
+            this.scalarResults[key] = callback(tableAccessor);
+        }
+    }
+    toString() {
+        const columns = Object.entries(this.scalarResults)
+            .map(([alias, scalar]) => `${scalar.toSQL()} AS ${format.ident(alias)}`)
+            .join(', ');
+        return `SELECT ${columns}`;
+    }
+    async get(withMetadata) {
+        const sql = this.toString();
+        const { data, metadata } = await this.executeQuery(sql);
+        const row = Array.isArray(data) ? data[0] : data;
+        const result = this.transformResult(row);
+        if (withMetadata) {
+            return { data: result, metadata };
+        }
+        return result;
+    }
+    transformResult(row) {
+        if (!row) {
+            const result = {};
+            for (const key of Object.keys(this.scalarResults)) {
+                result[key] = null;
+            }
+            return result;
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(row)) {
+            if (typeof value === 'string' && /^\d+$/.test(value)) {
+                result[key] = parseInt(value, 10);
+            }
+            else if (typeof value === 'string' && /^\d+\.\d+$/.test(value)) {
+                result[key] = parseFloat(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+}
+export class ConnectedScalarSelectBuilder extends ScalarSelectBuilder {
+    constructor(scalars, schema, internal) {
+        const executeQuery = async (sql) => {
+            return internal.executeSelectOne(sql);
+        };
+        const getColumnResolver = (tableName) => {
+            if (internal.hasColumnMapping()) {
+                return (column) => {
+                    const transformed = internal.transformToDbColumns(tableName, { [column]: null });
+                    const keys = Object.keys(transformed);
+                    return keys.length > 0 ? keys[0] : column;
+                };
+            }
+            return undefined;
+        };
+        super(scalars, schema, executeQuery, getColumnResolver);
+    }
+}

package/dist/esm/types/scalar-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -8,6 +8,26 @@ export class ForeignKeyResolutionError extends Error {
         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;

package/dist/index.d.ts

@@ -5424,8 +5424,12 @@ export interface ForeignKeyRelationDef {
 }
 /** Relation definition type */
 export type RelationDef = ForeignKeyRelationDef;
+/** Table's relations - NEW: array of FK definitions */
+export type TableRelationsArray = ForeignKeyRelationDef[];
 /** Table's relations map (legacy format) */
 export type TableRelations = Record<string, RelationDef>;
+/** All relations for a schema - NEW: array per table */
+export type SchemaRelationsArray = Record<string, TableRelationsArray>;
 /** All relations for a schema (legacy) */
 export type SchemaRelations = Record<string, TableRelations>;
 /**
@@ -5735,7 +5739,7 @@ export interface RelqConfig {
 	 *   )
 	 * ```
 	 */
-	relations?: SchemaRelations;
+	relations?: SchemaRelations | SchemaRelationsArray;
 }
 /**
  * Unsubscribe function returned by `db.subscribe()`
@@ -7127,7 +7131,7 @@ export interface RelqInternal {
 	/** Get the schema object for type-safe joins */
 	getSchema(): Record<string, any> | undefined;
 	/** Get the relations object for FK auto-resolution */
-	getRelations(): SchemaRelations | undefined;
+	getRelations(): SchemaRelations | SchemaRelationsArray | undefined;
 	/** Get table definition by schema key */
 	getTableDef(tableKey: string): TableDefinition<any> | undefined;
 }
@@ -7780,6 +7784,156 @@ declare class ConnectedRawQueryBuilder {
 	count(): Promise<RelqCount>;
 }
 declare const INTERNAL: unique symbol;
+/**
+ * Marker interface for scalar subquery results.
+ * Contains type information and SQL generation capability.
+ */
+export interface ScalarResult<T> {
+	/** Marker to identify scalar results */
+	readonly $scalar: true;
+	/** Type marker for TypeScript inference (not used at runtime) */
+	readonly $type: T;
+	/** Generate SQL for this scalar subquery */
+	toSQL(): string;
+	/** Get bound parameters for this subquery */
+	getParams(): unknown[];
+}
+/**
+ * ScalarQueryBuilder interface for building scalar subqueries.
+ * Provides filtering and terminal aggregate methods.
+ */
+export interface ScalarQueryBuilder<TTable> {
+	/**
+	 * Add WHERE conditions to the scalar subquery
+	 */
+	where(callback: (q: TypedWhereCondition<TTable>) => any): this;
+	/**
+	 * Count rows matching the conditions
+	 * @returns ScalarResult<number>
+	 */
+	count(): ScalarResult<number>;
+	/**
+	 * Sum a numeric column
+	 * @param column - Column to sum (must be numeric)
+	 * @returns ScalarResult<number>
+	 */
+	sum<K extends ColumnName<TTable>>(column: K): ScalarResult<number>;
+	/**
+	 * Average of a numeric column
+	 * @param column - Column to average (must be numeric)
+	 * @returns ScalarResult<number>
+	 */
+	avg<K extends ColumnName<TTable>>(column: K): ScalarResult<number>;
+	/**
+	 * Minimum value of a column
+	 * @param column - Column to get minimum
+	 * @returns ScalarResult of the column's type
+	 */
+	min<K extends ColumnName<TTable>>(column: K): ScalarResult<TTable extends {
+		$inferSelect: infer S;
+	} ? K extends keyof S ? S[K] : any : any>;
+	/**
+	 * Maximum value of a column
+	 * @param column - Column to get maximum
+	 * @returns ScalarResult of the column's type
+	 */
+	max<K extends ColumnName<TTable>>(column: K): ScalarResult<TTable extends {
+		$inferSelect: infer S;
+	} ? K extends keyof S ? S[K] : any : any>;
+	/**
+	 * Pick a single value from the first row
+	 * @param column - Column to pick
+	 * @returns ScalarResult of the column's type (nullable)
+	 */
+	pick<K extends ColumnName<TTable>>(column: K): ScalarResult<(TTable extends {
+		$inferSelect: infer S;
+	} ? K extends keyof S ? S[K] : any : any) | null>;
+	/**
+	 * Check if any rows exist
+	 * @returns ScalarResult<boolean>
+	 */
+	exists(): ScalarResult<boolean>;
+}
+/**
+ * ScalarTableAccessor provides access to tables for scalar subqueries.
+ * Each property is a ScalarQueryBuilder for that table.
+ *
+ * @example
+ * ```typescript
+ * // In scalar callback:
+ * q => q.orders.where(w => w.equal('status', 'active')).count()
+ * //     ^^^^^^
+ * //     This is ScalarTableAccessor providing .orders
+ * ```
+ */
+export type ScalarTableAccessor<TSchema> = {
+	readonly [K in keyof TSchema & string]: ScalarQueryBuilder<TSchema[K]>;
+};
+/**
+ * Callback function type for scalar definitions.
+ * Takes a table accessor and returns a ScalarResult.
+ */
+export type ScalarCallback<TSchema, TResult> = (tables: ScalarTableAccessor<TSchema>) => ScalarResult<TResult>;
+/**
+ * Infer result type from an object of scalar callbacks.
+ *
+ * @example
+ * ```typescript
+ * type Input = {
+ *   count: (q: ScalarTableAccessor<Schema>) => ScalarResult<number>;
+ *   name: (q: ScalarTableAccessor<Schema>) => ScalarResult<string | null>;
+ * };
+ * type Result = InferScalars<Input>;
+ * // { count: number; name: string | null }
+ * ```
+ */
+export type InferScalars<T extends Record<string, ScalarCallback<any, any>>> = Prettify<{
+	[K in keyof T]: T[K] extends ScalarCallback<any, infer R> ? R : never;
+}>;
+/**
+ * Type for the scalar definitions object passed to db.scalar()
+ */
+export type ScalarDefinitions<TSchema> = Record<string, ScalarCallback<TSchema, any>>;
+/**
+ * Executor function type for running queries
+ */
+export type QueryExecutor = (sql: string) => Promise<{
+	data: any;
+	metadata: RelqMetadata;
+}>;
+/**
+ * Column resolver getter type
+ */
+export type ColumnResolverGetter = (tableName: string) => ((column: string) => string) | undefined;
+declare class ScalarSelectBuilder<TSchema, TScalars extends Record<string, ScalarCallback<TSchema, any>>> {
+	private readonly executeQuery;
+	private readonly scalarResults;
+	constructor(scalars: TScalars, schema: TSchema, executeQuery: QueryExecutor, getColumnResolver?: ColumnResolverGetter);
+	/**
+	 * Generate the SQL for this scalar select
+	 */
+	toString(): string;
+	/**
+	 * Execute the query and return the result
+	 * @param withMetadata - If true, returns { data, metadata } instead of just data
+	 */
+	get(withMetadata?: false): Promise<InferScalars<TScalars>>;
+	get(withMetadata: true): Promise<RelqResult<InferScalars<TScalars>>>;
+	/**
+	 * Transform result values to correct types
+	 */
+	private transformResult;
+}
+declare class ConnectedScalarSelectBuilder<TSchema, TScalars extends Record<string, ScalarCallback<TSchema, any>>> extends ScalarSelectBuilder<TSchema, TScalars> {
+	constructor(scalars: TScalars, schema: TSchema, internal: {
+		executeSelectOne: (sql: string) => Promise<{
+			data: any;
+			metadata: RelqMetadata;
+		}>;
+		hasColumnMapping: () => boolean;
+		transformToDbColumns: (tableName: string, data: Record<string, any>) => Record<string, any>;
+	});
+}
 /**
  * Main Relq client class with connection management
  * Supports both pooled and single connection modes
@@ -8174,6 +8328,26 @@ export declare class Relq<TSchema = any> {
 		verbose?: boolean;
 		format?: "text" | "json" | "xml" | "yaml";
 	}): Promise<string | object[]>;
+	/**
+	 * Execute multiple scalar subqueries in a single SELECT statement
+	 *
+	 * Use this for aggregating values from multiple tables without a base table.
+	 * Each callback receives a table accessor and must return a scalar result
+	 * (count, sum, avg, min, max, pick, or exists).
+	 *
+	 * @example
+	 * ```typescript
+	 * const stats = await db.scalar({
+	 *   licenseCount: q => q.licenses.where(w => w.equal('productId', id)).count(),
+	 *   totalSpent: q => q.orders.where(w => w.equal('customerId', id)).sum('amount'),
+	 *   lastOrder: q => q.orders.where(w => w.equal('customerId', id)).max('createdAt'),
+	 *   hasSubscription: q => q.subscriptions.where(w => w.equal('userId', id)).exists(),
+	 * }).get();
+	 *
+	 * // Type: { licenseCount: number, totalSpent: number, lastOrder: Date, hasSubscription: boolean }
+	 * ```
+	 */
+	scalar<T extends Record<string, ScalarCallback<TSchema, any>>>(scalars: T): ConnectedScalarSelectBuilder<TSchema, T>;
 }
 /**
  * Type inference for aggregate functions, COUNT queries, and GROUP BY operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relq",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "description": "The Fully-Typed PostgreSQL ORM for TypeScript",
   "author": "Olajide Mathew O. <olajide.mathew@yuniq.solutions>",
   "license": "MIT",