metal-orm 1.0.62 → 1.0.64

package/src/core/ast/expression.ts

@@ -2,6 +2,8 @@
  * Expression AST nodes and builders.
  * Re-exports components for building and visiting SQL expression trees.
  */
+import type { CaseExpressionNode, FunctionNode, WindowFunctionNode } from './expression-nodes.js';
+
 export * from './expression-nodes.js';
 export * from './expression-builders.js';
 export * from './window-functions.js';
@@ -9,3 +11,10 @@ export * from './aggregate-functions.js';
 export * from './expression-visitor.js';
 export type { ColumnRef, TableRef as AstTableRef } from './types.js';
 export * from './adapters.js';
+
+export type TypedExpression<T> =
+  (FunctionNode | CaseExpressionNode | WindowFunctionNode) & { __tsType: T };
+
+export const asType = <T>(
+  expr: FunctionNode | CaseExpressionNode | WindowFunctionNode
+): TypedExpression<T> => expr as TypedExpression<T>;

package/src/core/ast/window-functions.ts

@@ -3,13 +3,14 @@ import { columnOperand } from './expression-builders.js';
 import { OrderDirection } from '../sql/sql.js';
 import { OrderByNode } from './query.js';
 import { ColumnRef } from './types.js';
+import { TypedExpression, asType } from './expression.js';
 
-const buildWindowFunction = (
+const buildWindowFunction = <T = any>(
   name: string,
   args: (ColumnNode | LiteralNode | JsonPathNode)[] = [],
   partitionBy?: ColumnNode[],
   orderBy?: OrderByNode[]
-): WindowFunctionNode => {
+): TypedExpression<T> => {
   const node: WindowFunctionNode = {
     type: 'WindowFunction',
     name,
@@ -24,47 +25,52 @@ const buildWindowFunction = (
     node.orderBy = orderBy;
   }
 
-  return node;
+  return asType<T>(node);
 };
 
 /**
- * Creates a ROW_NUMBER window function
- * @returns Window function node for ROW_NUMBER
+ * Creates a ROW_NUMBER window function.
+ * 
+ * @returns A `TypedExpression<number>` representing the `ROW_NUMBER` window function.
  */
-export const rowNumber = (): WindowFunctionNode => buildWindowFunction('ROW_NUMBER');
+export const rowNumber = (): TypedExpression<number> => buildWindowFunction<number>('ROW_NUMBER');
 
 /**
- * Creates a RANK window function
- * @returns Window function node for RANK
+ * Creates a RANK window function.
+ * 
+ * @returns A `TypedExpression<number>` representing the `RANK` window function.
  */
-export const rank = (): WindowFunctionNode => buildWindowFunction('RANK');
+export const rank = (): TypedExpression<number> => buildWindowFunction<number>('RANK');
 
 /**
- * Creates a DENSE_RANK window function
- * @returns Window function node for DENSE_RANK
+ * Creates a DENSE_RANK window function.
+ * 
+ * @returns A `TypedExpression<number>` representing the `DENSE_RANK` window function.
  */
-export const denseRank = (): WindowFunctionNode => buildWindowFunction('DENSE_RANK');
+export const denseRank = (): TypedExpression<number> => buildWindowFunction<number>('DENSE_RANK');
 
 /**
- * Creates an NTILE window function
- * @param n - Number of buckets
- * @returns Window function node for NTILE
+ * Creates an NTILE window function.
+ * 
+ * @param n - Number of buckets.
+ * @returns A `TypedExpression<number>` representing the `NTILE` window function.
  */
-export const ntile = (n: number): WindowFunctionNode =>
-  buildWindowFunction('NTILE', [{ type: 'Literal', value: n }]);
+export const ntile = (n: number): TypedExpression<number> =>
+  buildWindowFunction<number>('NTILE', [{ type: 'Literal', value: n }]);
 
 /**
- * Creates a LAG window function
- * @param col - Column to lag
- * @param offset - Offset (defaults to 1)
- * @param defaultValue - Default value if no row exists
- * @returns Window function node for LAG
+ * Creates a LAG window function.
+ * 
+ * @param col - Column or expression to lag.
+ * @param offset - Optional offset (defaults to 1).
+ * @param defaultValue - Optional default value.
+ * @returns A `TypedExpression<T>` representing the `LAG` window function.
  */
-export const lag = (
+export const lag = <T = any>(
   col: ColumnRef | ColumnNode,
   offset: number = 1,
   defaultValue?: LiteralNode['value']
-): WindowFunctionNode => {
+): TypedExpression<T> => {
   const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
     columnOperand(col),
     { type: 'Literal', value: offset }
@@ -72,21 +78,22 @@ export const lag = (
   if (defaultValue !== undefined) {
     args.push({ type: 'Literal', value: defaultValue });
   }
-  return buildWindowFunction('LAG', args);
+  return buildWindowFunction<T>('LAG', args);
 };
 
 /**
- * Creates a LEAD window function
- * @param col - Column to lead
- * @param offset - Offset (defaults to 1)
- * @param defaultValue - Default value if no row exists
- * @returns Window function node for LEAD
+ * Creates a LEAD window function.
+ * 
+ * @param col - Column or expression to lead.
+ * @param offset - Optional offset (defaults to 1).
+ * @param defaultValue - Optional default value.
+ * @returns A `TypedExpression<T>` representing the `LEAD` window function.
  */
-export const lead = (
+export const lead = <T = any>(
   col: ColumnRef | ColumnNode,
   offset: number = 1,
   defaultValue?: LiteralNode['value']
-): WindowFunctionNode => {
+): TypedExpression<T> => {
   const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
     columnOperand(col),
     { type: 'Literal', value: offset }
@@ -94,39 +101,42 @@ export const lead = (
   if (defaultValue !== undefined) {
     args.push({ type: 'Literal', value: defaultValue });
   }
-  return buildWindowFunction('LEAD', args);
+  return buildWindowFunction<T>('LEAD', args);
 };
 
 /**
- * Creates a FIRST_VALUE window function
- * @param col - Column to get first value from
- * @returns Window function node for FIRST_VALUE
+ * Creates a FIRST_VALUE window function.
+ * 
+ * @param col - Column or expression to get first value from.
+ * @returns A `TypedExpression<T>` representing the `FIRST_VALUE` window function.
  */
-export const firstValue = (col: ColumnRef | ColumnNode): WindowFunctionNode =>
-  buildWindowFunction('FIRST_VALUE', [columnOperand(col)]);
+export const firstValue = <T = any>(col: ColumnRef | ColumnNode): TypedExpression<T> =>
+  buildWindowFunction<T>('FIRST_VALUE', [columnOperand(col)]);
 
 /**
- * Creates a LAST_VALUE window function
- * @param col - Column to get last value from
- * @returns Window function node for LAST_VALUE
+ * Creates a LAST_VALUE window function.
+ * 
+ * @param col - Column or expression to get last value from.
+ * @returns A `TypedExpression<T>` representing the `LAST_VALUE` window function.
  */
-export const lastValue = (col: ColumnRef | ColumnNode): WindowFunctionNode =>
-  buildWindowFunction('LAST_VALUE', [columnOperand(col)]);
+export const lastValue = <T = any>(col: ColumnRef | ColumnNode): TypedExpression<T> =>
+  buildWindowFunction<T>('LAST_VALUE', [columnOperand(col)]);
 
 /**
- * Creates a custom window function
- * @param name - Window function name
- * @param args - Function arguments
- * @param partitionBy - Optional PARTITION BY columns
- * @param orderBy - Optional ORDER BY clauses
- * @returns Window function node
+ * Creates a custom window function.
+ * 
+ * @param name - Window function name.
+ * @param args - Function arguments.
+ * @param partitionBy - Optional PARTITION BY columns.
+ * @param orderBy - Optional ORDER BY clauses.
+ * @returns A `TypedExpression<T>` representing the window function.
  */
-export const windowFunction = (
+export const windowFunction = <T = any>(
   name: string,
   args: (ColumnRef | ColumnNode | LiteralNode | JsonPathNode)[] = [],
   partitionBy?: (ColumnRef | ColumnNode)[],
   orderBy?: { column: ColumnRef | ColumnNode; direction: OrderDirection }[]
-): WindowFunctionNode => {
+): TypedExpression<T> => {
   const nodeArgs = args.map(arg => {
     if (typeof (arg as LiteralNode).value !== 'undefined') {
       return arg as LiteralNode;
@@ -144,5 +154,5 @@ export const windowFunction = (
     direction: o.direction
   }));
 
-  return buildWindowFunction(name, nodeArgs, partitionNodes, orderNodes);
+  return buildWindowFunction<T>(name, nodeArgs, partitionNodes, orderNodes);
 };

package/src/core/functions/array.ts

@@ -2,7 +2,7 @@
 
 import { ColumnDef } from '../../schema/column-types.js';
 import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
-import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
+import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
 
 type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
 
@@ -22,5 +22,14 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
     args: args.map(toOperand)
 });
 
-export const arrayAppend = (array: OperandInput, value: OperandInput): FunctionNode =>
-    fn('ARRAY_APPEND', [array, value]);
+const afn = <T = any[]>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
+
+/**
+ * Appends a value to the end of an array.
+ * 
+ * @param array - Array column or value.
+ * @param value - Value to append.
+ * @returns A `TypedExpression<any[]>` representing the `ARRAY_APPEND` SQL function.
+ */
+export const arrayAppend = (array: OperandInput, value: OperandInput): TypedExpression<any[]> =>
+    afn('ARRAY_APPEND', [array, value]);

package/src/core/functions/control-flow.ts

@@ -2,7 +2,7 @@
 
 import { ColumnDef } from '../../schema/column-types.js';
 import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
-import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
+import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
 
 type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
 
@@ -22,48 +22,58 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
   args: args.map(toOperand)
 });
 
+const afn = <T = any>(key: string, args: OperandInput[]): TypedExpression<T> => asType<T>(fn(key, args));
+
 /**
  * Returns the first non-null value in a list.
- * @param args - The list of values to check.
- * @returns A FunctionNode representing the COALESCE SQL function.
+ * 
+ * @param args - The list of values or columns to check.
+ * @returns A `TypedExpression<T>` representing the `COALESCE` SQL function.
+ * 
+ * @example
+ * coalesce(users.nickname, users.firstName, 'Guest');
  */
-export const coalesce = (...args: OperandInput[]): FunctionNode => {
+export const coalesce = <T = any>(...args: OperandInput[]): TypedExpression<T> => {
   if (args.length < 2) throw new Error('coalesce() expects at least 2 arguments');
-  return fn('COALESCE', args);
+  return afn<T>('COALESCE', args);
 };
 
 /**
  * Returns null if the two arguments are equal, otherwise returns the first argument.
+ * 
  * @param val1 - The first value.
- * @param val2 - The second value.
- * @returns A FunctionNode representing the NULLIF SQL function.
+ * @param val2 - The second value to compare against.
+ * @returns A `TypedExpression<T>` representing the `NULLIF` SQL function.
  */
-export const nullif = (val1: OperandInput, val2: OperandInput): FunctionNode => fn('NULLIF', [val1, val2]);
+export const nullif = <T = any>(val1: OperandInput, val2: OperandInput): TypedExpression<T> => afn<T>('NULLIF', [val1, val2]);
 
 /**
  * Returns the largest value in a list.
- * @param args - The list of values to compare.
- * @returns A FunctionNode representing the GREATEST SQL function.
+ * 
+ * @param args - The list of values or columns to compare.
+ * @returns A `TypedExpression<T>` representing the `GREATEST` SQL function.
  */
-export const greatest = (...args: OperandInput[]): FunctionNode => {
+export const greatest = <T = any>(...args: OperandInput[]): TypedExpression<T> => {
   if (args.length < 2) throw new Error('greatest() expects at least 2 arguments');
-  return fn('GREATEST', args);
+  return afn<T>('GREATEST', args);
 };
 
 /**
  * Returns the smallest value in a list.
- * @param args - The list of values to compare.
- * @returns A FunctionNode representing the LEAST SQL function.
+ * 
+ * @param args - The list of values or columns to compare.
+ * @returns A `TypedExpression<T>` representing the `LEAST` SQL function.
  */
-export const least = (...args: OperandInput[]): FunctionNode => {
+export const least = <T = any>(...args: OperandInput[]): TypedExpression<T> => {
   if (args.length < 2) throw new Error('least() expects at least 2 arguments');
-  return fn('LEAST', args);
+  return afn<T>('LEAST', args);
 };
 
 /**
  * Returns the first argument if it is not null, otherwise returns the second argument.
+ * 
  * @param val - The value to check.
  * @param defaultValue - The default value to return if val is null.
- * @returns A FunctionNode representing the COALESCE SQL function.
+ * @returns A `TypedExpression<T>` representing the `COALESCE` SQL function.
  */
-export const ifNull = (val: OperandInput, defaultValue: OperandInput): FunctionNode => coalesce(val, defaultValue);
+export const ifNull = <T = any>(val: OperandInput, defaultValue: OperandInput): TypedExpression<T> => coalesce<T>(val, defaultValue);

package/src/core/functions/datetime.ts

@@ -2,7 +2,7 @@
 
 import { ColumnDef } from '../../schema/column-types.js';
 import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
-import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
+import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
 
 type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
 
@@ -22,187 +22,216 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
     args: args.map(toOperand)
 });
 
+const dfn = (key: string, args: OperandInput[]): TypedExpression<Date> => asType<Date>(fn(key, args));
+const nfn = (key: string, args: OperandInput[]): TypedExpression<number> => asType<number>(fn(key, args));
+const sfn = (key: string, args: OperandInput[]): TypedExpression<string> => asType<string>(fn(key, args));
+
 // ----------------------
 // Helper Functions
 // ----------------------
 
 /**
  * Returns the current local date and time.
- * @returns A FunctionNode representing the NOW() SQL function.
+ * 
+ * @returns A `TypedExpression<Date>` representing the `NOW()` SQL function.
  */
-export const now = (): FunctionNode => fn('NOW', []);
+export const now = (): TypedExpression<Date> => dfn('NOW', []);
 
 /**
- * Returns the current date without time.
- * @returns A FunctionNode representing the CURRENT_DATE SQL function.
+ * Returns the current date (without time).
+ * 
+ * @returns A `TypedExpression<Date>` representing the `CURRENT_DATE` SQL function.
  */
-export const currentDate = (): FunctionNode => fn('CURRENT_DATE', []);
+export const currentDate = (): TypedExpression<Date> => dfn('CURRENT_DATE', []);
 
 /**
- * Returns the current time without date.
- * @returns A FunctionNode representing the CURRENT_TIME SQL function.
+ * Returns the current time (without date).
+ * 
+ * @returns A `TypedExpression<Date>` representing the `CURRENT_TIME` SQL function.
  */
-export const currentTime = (): FunctionNode => fn('CURRENT_TIME', []);
+export const currentTime = (): TypedExpression<Date> => dfn('CURRENT_TIME', []);
 
 /**
  * Returns the current UTC date and time.
- * @returns A FunctionNode representing the UTC_NOW() SQL function.
+ * 
+ * @returns A `TypedExpression<Date>` representing the `UTC_NOW()` SQL function.
  */
-export const utcNow = (): FunctionNode => fn('UTC_NOW', []);
+export const utcNow = (): TypedExpression<Date> => dfn('UTC_NOW', []);
 
 /**
  * Returns the current local time.
- * @returns A FunctionNode representing the LOCALTIME SQL function.
+ * 
+ * @returns A `TypedExpression<Date>` representing the `LOCALTIME` SQL function.
  */
-export const localTime = (): FunctionNode => fn('LOCALTIME', []);
+export const localTime = (): TypedExpression<Date> => dfn('LOCALTIME', []);
 
 /**
  * Returns the current local timestamp.
- * @returns A FunctionNode representing the LOCALTIMESTAMP SQL function.
+ * 
+ * @returns A `TypedExpression<Date>` representing the `LOCALTIMESTAMP` SQL function.
  */
-export const localTimestamp = (): FunctionNode => fn('LOCALTIMESTAMP', []);
+export const localTimestamp = (): TypedExpression<Date> => dfn('LOCALTIMESTAMP', []);
 
 /**
  * Extracts a specified part from a date or datetime value.
- * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY', 'HOUR', 'MINUTE', 'SECOND').
- * @param date - The date or datetime value to extract from.
- * @returns A FunctionNode representing the EXTRACT SQL function.
+ * 
+ * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY').
+ * @param date - The date/datetime value or column.
+ * @returns A `TypedExpression<number>` representing the `EXTRACT` SQL function.
  */
-export const extract = (part: OperandInput, date: OperandInput): FunctionNode => fn('EXTRACT', [part, date]);
+export const extract = (part: OperandInput, date: OperandInput): TypedExpression<number> => nfn('EXTRACT', [part, date]);
 
 /**
  * Extracts the year from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the YEAR SQL function.
+ * 
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `YEAR` SQL function.
  */
-export const year = (date: OperandInput): FunctionNode => fn('YEAR', [date]);
+export const year = (date: OperandInput): TypedExpression<number> => nfn('YEAR', [date]);
 
 /**
  * Extracts the month from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the MONTH SQL function.
+ * 
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `MONTH` SQL function.
  */
-export const month = (date: OperandInput): FunctionNode => fn('MONTH', [date]);
+export const month = (date: OperandInput): TypedExpression<number> => nfn('MONTH', [date]);
 
 /**
  * Extracts the day of the month from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the DAY SQL function.
+ * 
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `DAY` SQL function.
  */
-export const day = (date: OperandInput): FunctionNode => fn('DAY', [date]);
+export const day = (date: OperandInput): TypedExpression<number> => nfn('DAY', [date]);
 
 /**
  * Adds a specified time interval to a date or datetime value.
- * @param date - The date or datetime value to add to.
- * @param interval - The number of units to add.
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
- * @returns A FunctionNode representing the DATE_ADD SQL function.
+ * 
+ * @param date - The base date.
+ * @param interval - The numeric interval to add.
+ * @param unit - The unit (e.g., 'DAY', 'MONTH').
+ * @returns A `TypedExpression<Date>` representing the `DATE_ADD` SQL function.
  */
-export const dateAdd = (date: OperandInput, interval: OperandInput, unit: OperandInput): FunctionNode =>
-    fn('DATE_ADD', [date, interval, unit]);
+export const dateAdd = (date: OperandInput, interval: OperandInput, unit: OperandInput): TypedExpression<Date> =>
+    dfn('DATE_ADD', [date, interval, unit]);
 
 /**
  * Subtracts a specified time interval from a date or datetime value.
- * @param date - The date or datetime value to subtract from.
- * @param interval - The number of units to subtract.
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
- * @returns A FunctionNode representing the DATE_SUB SQL function.
+ * 
+ * @param date - The base date.
+ * @param interval - The numeric interval to subtract.
+ * @param unit - The unit (e.g., 'DAY', 'MONTH').
+ * @returns A `TypedExpression<Date>` representing the `DATE_SUB` SQL function.
  */
-export const dateSub = (date: OperandInput, interval: OperandInput, unit: OperandInput): FunctionNode =>
-    fn('DATE_SUB', [date, interval, unit]);
+export const dateSub = (date: OperandInput, interval: OperandInput, unit: OperandInput): TypedExpression<Date> =>
+    dfn('DATE_SUB', [date, interval, unit]);
 
 /**
  * Returns the difference between two dates in days.
- * @param date1 - The end date.
- * @param date2 - The start date.
- * @returns A FunctionNode representing the DATE_DIFF SQL function.
+ * 
+ * @param date1 - End date.
+ * @param date2 - Start date.
+ * @returns A `TypedExpression<number>` representing the `DATE_DIFF` SQL function.
  */
-export const dateDiff = (date1: OperandInput, date2: OperandInput): FunctionNode => fn('DATE_DIFF', [date1, date2]);
+export const dateDiff = (date1: OperandInput, date2: OperandInput): TypedExpression<number> => nfn('DATE_DIFF', [date1, date2]);
 
 /**
  * Converts a date or datetime value to a formatted string.
- * @param date - The date or datetime value to format.
- * @param format - The format string (dialect-specific).
- * @returns A FunctionNode representing the DATE_FORMAT SQL function.
+ * 
+ * @param date - The date value.
+ * @param format - Dialect-specific format string.
+ * @returns A `TypedExpression<string>` representing the `DATE_FORMAT` SQL function.
  */
-export const dateFormat = (date: OperandInput, format: OperandInput): FunctionNode => fn('DATE_FORMAT', [date, format]);
+export const dateFormat = (date: OperandInput, format: OperandInput): TypedExpression<string> => sfn('DATE_FORMAT', [date, format]);
 
 /**
- * Returns the current Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).
- * @returns A FunctionNode representing the UNIX_TIMESTAMP SQL function.
+ * Returns the current Unix timestamp (seconds since epoch).
+ * 
+ * @returns A `TypedExpression<number>` representing the `UNIX_TIMESTAMP` SQL function.
  */
-export const unixTimestamp = (): FunctionNode => fn('UNIX_TIMESTAMP', []);
+export const unixTimestamp = (): TypedExpression<number> => nfn('UNIX_TIMESTAMP', []);
 
 /**
- * Converts a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC) to a date.
- * @param timestamp - Unix timestamp in seconds.
- * @returns A FunctionNode representing the FROM_UNIXTIME SQL function.
+ * Converts a Unix timestamp to a Date.
+ * 
+ * @param timestamp - Seconds since epoch.
+ * @returns A `TypedExpression<Date>` representing the `FROM_UNIXTIME` SQL function.
  */
-export const fromUnixTime = (timestamp: OperandInput): FunctionNode => fn('FROM_UNIXTIME', [timestamp]);
+export const fromUnixTime = (timestamp: OperandInput): TypedExpression<Date> => dfn('FROM_UNIXTIME', [timestamp]);
 
 /**
  * Returns the last day of the month for a given date.
+ * 
  * @param date - The date value.
- * @returns A FunctionNode representing the END_OF_MONTH SQL function.
+ * @returns A `TypedExpression<Date>` representing the `END_OF_MONTH` SQL function.
  */
-export const endOfMonth = (date: OperandInput): FunctionNode => fn('END_OF_MONTH', [date]);
+export const endOfMonth = (date: OperandInput): TypedExpression<Date> => dfn('END_OF_MONTH', [date]);
 
 /**
  * Returns the index of the weekday for a given date (1 = Sunday, 2 = Monday, etc.).
+ * 
  * @param date - The date value.
- * @returns A FunctionNode representing the DAY_OF_WEEK SQL function.
+ * @returns A `TypedExpression<number>` representing the `DAY_OF_WEEK` SQL function.
  */
-export const dayOfWeek = (date: OperandInput): FunctionNode => fn('DAY_OF_WEEK', [date]);
+export const dayOfWeek = (date: OperandInput): TypedExpression<number> => nfn('DAY_OF_WEEK', [date]);
 
 /**
  * Returns the week number of the year for a given date.
+ * 
  * @param date - The date value.
- * @returns A FunctionNode representing the WEEK_OF_YEAR SQL function.
+ * @returns A `TypedExpression<number>` representing the `WEEK_OF_YEAR` SQL function.
  */
-export const weekOfYear = (date: OperandInput): FunctionNode => fn('WEEK_OF_YEAR', [date]);
+export const weekOfYear = (date: OperandInput): TypedExpression<number> => nfn('WEEK_OF_YEAR', [date]);
 
 /**
- * Truncates a date or datetime value to a specified precision (e.g., first day of the month/year).
- * @param part - The truncation precision (e.g., 'YEAR', 'MONTH', 'DAY').
- * @param date - The date or datetime value to truncate.
- * @returns A FunctionNode representing the DATE_TRUNC SQL function.
+ * Truncates a date or datetime value to a specified precision.
+ * 
+ * @param part - The precision (e.g., 'YEAR', 'MONTH').
+ * @param date - The date to truncate.
+ * @returns A `TypedExpression<Date>` representing the `DATE_TRUNC` SQL function.
  */
-export const dateTrunc = (part: OperandInput, date: OperandInput): FunctionNode => fn('DATE_TRUNC', [part, date]);
+export const dateTrunc = (part: OperandInput, date: OperandInput): TypedExpression<Date> => dfn('DATE_TRUNC', [part, date]);
 
 /**
- * Returns the difference between two timestamps as an interval.
- * @param timestamp - The end timestamp.
- * @param baseTimestamp - The start timestamp (optional, defaults to current time).
- * @returns A FunctionNode representing the AGE SQL function.
+ * Returns the difference between two timestamps as an interval string.
+ * 
+ * @param timestamp - End timestamp.
+ * @param baseTimestamp - Optional start timestamp.
+ * @returns A `TypedExpression<string>` representing the `AGE` SQL function.
  */
-export const age = (timestamp: OperandInput, baseTimestamp?: OperandInput): FunctionNode =>
-    baseTimestamp === undefined ? fn('AGE', [timestamp]) : fn('AGE', [timestamp, baseTimestamp]);
+export const age = (timestamp: OperandInput, baseTimestamp?: OperandInput): TypedExpression<string> =>
+    baseTimestamp === undefined ? sfn('AGE', [timestamp]) : sfn('AGE', [timestamp, baseTimestamp]);
 
 /**
  * Extracts the hour from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the HOUR SQL function.
+ * 
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `HOUR` SQL function.
  */
-export const hour = (date: OperandInput): FunctionNode => fn('HOUR', [date]);
+export const hour = (date: OperandInput): TypedExpression<number> => nfn('HOUR', [date]);
 
 /**
  * Extracts the minute from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the MINUTE SQL function.
+ * 
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `MINUTE` SQL function.
  */
-export const minute = (date: OperandInput): FunctionNode => fn('MINUTE', [date]);
+export const minute = (date: OperandInput): TypedExpression<number> => nfn('MINUTE', [date]);
 
 /**
  * Extracts the second from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the SECOND SQL function.
+ * 
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `SECOND` SQL function.
  */
-export const second = (date: OperandInput): FunctionNode => fn('SECOND', [date]);
+export const second = (date: OperandInput): TypedExpression<number> => nfn('SECOND', [date]);
 
 /**
  * Extracts the quarter from a date or datetime value (1-4).
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the QUARTER SQL function.
+ * 
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `QUARTER` SQL function.
  */
-export const quarter = (date: OperandInput): FunctionNode => fn('QUARTER', [date]);
+export const quarter = (date: OperandInput): TypedExpression<number> => nfn('QUARTER', [date]);