metal-orm 1.0.43 → 1.0.44

package/src/core/ddl/schema-diff.ts

@@ -6,6 +6,7 @@ import { deriveIndexName } from './naming-strategy.js';
 import { generateCreateTableSql, renderColumnDefinition } from './schema-generator.js';
 import { ColumnDiff, DatabaseColumn, DatabaseSchema, DatabaseTable } from './schema-types.js';
 
+/** The kind of schema change. */
 export type SchemaChangeKind =
   | 'createTable'
   | 'dropTable'
@@ -15,6 +16,7 @@ export type SchemaChangeKind =
   | 'addIndex'
   | 'dropIndex';
 
+/** Represents a single schema change. */
 export interface SchemaChange {
   kind: SchemaChangeKind;
   table: string;
@@ -23,11 +25,13 @@ export interface SchemaChange {
   safe: boolean;
 }
 
+/** Represents a plan of schema changes. */
 export interface SchemaPlan {
   changes: SchemaChange[];
   warnings: string[];
 }
 
+/** Options for schema diffing. */
 export interface SchemaDiffOptions {
   /** Allow destructive operations (drops) */
   allowDestructive?: boolean;
@@ -69,6 +73,14 @@ const diffColumn = (expected: ColumnDef, actual: DatabaseColumn, dialect: Schema
   };
 };
 
+/**
+ * Computes the differences between expected and actual database schemas.
+ * @param expectedTables - The expected table definitions.
+ * @param actualSchema - The actual database schema.
+ * @param dialect - The schema dialect.
+ * @param options - Options for the diff.
+ * @returns The schema plan with changes and warnings.
+ */
 export const diffSchema = (
   expectedTables: TableDef[],
   actualSchema: DatabaseSchema,
@@ -191,10 +203,20 @@ export const diffSchema = (
   return plan;
 };
 
+/** Options for schema synchronization. */
 export interface SynchronizeOptions extends SchemaDiffOptions {
   dryRun?: boolean;
 }
 
+/**
+ * Synchronizes the database schema with the expected tables.
+ * @param expectedTables - The expected table definitions.
+ * @param actualSchema - The actual database schema.
+ * @param dialect - The schema dialect.
+ * @param executor - The database executor.
+ * @param options - Options for synchronization.
+ * @returns The schema plan with changes and warnings.
+ */
 export const synchronizeSchema = async (
   expectedTables: TableDef[],
   actualSchema: DatabaseSchema,

package/src/core/ddl/schema-generator.ts

@@ -4,15 +4,25 @@ import type { SchemaDialect } from './schema-dialect.js';
 import { resolvePrimaryKey } from './sql-writing.js';
 import { DialectName } from './schema-dialect.js';
 
+/** Result of generating schema SQL. */
 export interface SchemaGenerateResult {
   tableSql: string;
   indexSql: string[];
 }
 
+/** Options for rendering column definitions. */
 export interface RenderColumnOptions {
   includePrimary?: boolean;
 }
 
+/**
+ * Renders a column definition for SQL.
+ * @param table - The table definition.
+ * @param col - The column definition.
+ * @param dialect - The schema dialect.
+ * @param options - Options for rendering.
+ * @returns The rendered SQL and whether primary key is inline.
+ */
 export const renderColumnDefinition = (
   table: TableDef,
   col: ColumnDef,
@@ -44,6 +54,12 @@ export const renderColumnDefinition = (
   return { sql: parts.join(' '), inlinePrimary: !!(options.includePrimary && col.primary) };
 };
 
+/**
+ * Generates SQL to create a table.
+ * @param table - The table definition.
+ * @param dialect - The schema dialect.
+ * @returns The table SQL and index SQL.
+ */
 export const generateCreateTableSql = (
   table: TableDef,
   dialect: SchemaDialect
@@ -91,6 +107,12 @@ export const generateCreateTableSql = (
   return { tableSql, indexSql };
 };
 
+/**
+ * Generates SQL for creating multiple tables.
+ * @param tables - The table definitions.
+ * @param dialect - The schema dialect.
+ * @returns The SQL statements.
+ */
 export const generateSchemaSql = (
   tables: TableDef[],
   dialect: SchemaDialect

package/src/core/ddl/schema-plan-executor.ts

@@ -1,6 +1,12 @@
 import { DbExecutor } from '../execution/db-executor.js';
 import type { SchemaPlan, SynchronizeOptions } from './schema-diff.js';
 
+/**
+ * Executes a schema plan by running the SQL statements.
+ * @param plan - The schema plan to execute.
+ * @param executor - The database executor.
+ * @param options - Options for synchronization.
+ */
 export const executeSchemaPlan = async (
   plan: SchemaPlan,
   executor: DbExecutor,

package/src/core/ddl/schema-types.ts

@@ -1,6 +1,7 @@
 import { ForeignKeyReference } from '../../schema/column.js';
 import { IndexColumn } from '../../schema/table.js';
 
+/** Represents the differences detected in a database column's properties. */
 export interface ColumnDiff {
   typeChanged?: boolean;
   nullabilityChanged?: boolean;
@@ -8,6 +9,7 @@ export interface ColumnDiff {
   autoIncrementChanged?: boolean;
 }
 
+/** Represents a column in the database schema. */
 export interface DatabaseColumn {
   name: string;
   type: string;
@@ -20,6 +22,7 @@ export interface DatabaseColumn {
   check?: string;
 }
 
+/** Represents an index in the database schema. */
 export interface DatabaseIndex {
   name: string;
   columns: IndexColumn[];
@@ -27,11 +30,13 @@ export interface DatabaseIndex {
   where?: string;
 }
 
+/** Represents a check constraint in the database schema. */
 export interface DatabaseCheck {
   name?: string;
   expression: string;
 }
 
+/** Represents a table in the database schema. */
 export interface DatabaseTable {
   name: string;
   schema?: string;
@@ -41,6 +46,7 @@ export interface DatabaseTable {
   checks?: DatabaseCheck[];
 }
 
+/** Represents the overall database schema. */
 export interface DatabaseSchema {
   tables: DatabaseTable[];
 }

package/src/core/dialect/abstract.ts

@@ -379,8 +379,8 @@ export abstract class Dialect
     if (isOperandNode(term)) {
       return this.compileOperand(term, ctx);
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const expr = this.compileExpression(term as any, ctx);
+    // At this point, term must be an ExpressionNode
+    const expr = this.compileExpression(term as ExpressionNode, ctx);
     return `(${expr})`;
   }
 

package/src/core/execution/pooling/pool.ts

@@ -1,5 +1,12 @@
 import type { PoolAdapter, PoolLease, PoolOptions } from './pool-types.js';
 
+/**
+ * Node.js Timer with optional unref method (for preventing event loop from staying alive)
+ */
+type NodeTimer = ReturnType<typeof setInterval> & {
+    unref?: () => void;
+};
+
 type Deferred<T> = {
     promise: Promise<T>;
     resolve: (value: T) => void;
@@ -49,8 +56,7 @@ export class Pool<TResource> {
             }, interval);
 
             // Best-effort: avoid keeping the event loop alive.
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (this.reapTimer as any).unref?.();
+            (this.reapTimer as NodeTimer).unref?.();
         }
 
         // Best-effort warmup.
@@ -93,16 +99,16 @@ export class Pool<TResource> {
         this.waiters.push(waiter);
 
         const timeout = this.options.acquireTimeoutMillis;
-        let timer: ReturnType<typeof setTimeout> | null = null;
+        let timer: NodeTimer | null = null;
         if (timeout && timeout > 0) {
             timer = setTimeout(() => {
                 // Remove from queue if still waiting.
                 const idx = this.waiters.indexOf(waiter);
                 if (idx >= 0) this.waiters.splice(idx, 1);
                 waiter.reject(new Error('Pool acquire timeout'));
-            }, timeout);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (timer as any).unref?.();
+            }, timeout) as NodeTimer;
+            // Best-effort: avoid keeping the event loop alive.
+            timer.unref?.();
         }
 
         try {
@@ -267,4 +273,3 @@ export class Pool<TResource> {
         }
     }
 }
-

package/src/core/functions/datetime.ts

@@ -26,108 +26,132 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
 // ----------------------
 
 /**
- * Helper: NOW() - Returns the current local date and time
+ * Returns the current local date and time.
+ * @returns A FunctionNode representing the NOW() SQL function.
  */
 export const now = (): FunctionNode => fn('NOW', []);
 
 /**
- * Helper: CURRENT_DATE - Returns only the current date (no time)
+ * Returns the current date without time.
+ * @returns A FunctionNode representing the CURRENT_DATE SQL function.
  */
 export const currentDate = (): FunctionNode => fn('CURRENT_DATE', []);
 
 /**
- * Helper: CURRENT_TIME - Returns only the current time
+ * Returns the current time without date.
+ * @returns A FunctionNode representing the CURRENT_TIME SQL function.
  */
 export const currentTime = (): FunctionNode => fn('CURRENT_TIME', []);
 
 /**
- * Helper: UTC_NOW() - Returns current UTC/GMT date and time
+ * Returns the current UTC date and time.
+ * @returns A FunctionNode representing the UTC_NOW() SQL function.
  */
 export const utcNow = (): FunctionNode => fn('UTC_NOW', []);
 
 /**
- * Helper: EXTRACT(part FROM date) - Extracts a part (year, month, day, hour, etc.) from a date
- * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY', 'HOUR', 'MINUTE', 'SECOND')
- * @param date - The date/datetime value
+ * 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.
  */
 export const extract = (part: OperandInput, date: OperandInput): FunctionNode => fn('EXTRACT', [part, date]);
 
 /**
- * Helper: YEAR(date) - Extracts the year from a 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.
  */
 export const year = (date: OperandInput): FunctionNode => fn('YEAR', [date]);
 
 /**
- * Helper: MONTH(date) - Extracts the month from a 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.
  */
 export const month = (date: OperandInput): FunctionNode => fn('MONTH', [date]);
 
 /**
- * Helper: DAY(date) - Extracts the day from a 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.
  */
 export const day = (date: OperandInput): FunctionNode => fn('DAY', [date]);
 
 /**
- * Helper: DATE_ADD(date, interval, unit) - Adds a specific time interval to a date
- * @param date - The date/datetime value
- * @param interval - The number of units to add
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND')
+ * 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.
  */
 export const dateAdd = (date: OperandInput, interval: OperandInput, unit: OperandInput): FunctionNode =>
     fn('DATE_ADD', [date, interval, unit]);
 
 /**
- * Helper: DATE_SUB(date, interval, unit) - Subtracts a specific time interval from a date
- * @param date - The date/datetime value
- * @param interval - The number of units to subtract
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND')
+ * 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.
  */
 export const dateSub = (date: OperandInput, interval: OperandInput, unit: OperandInput): FunctionNode =>
     fn('DATE_SUB', [date, interval, unit]);
 
 /**
- * Helper: DATE_DIFF(date1, date2) - Returns the difference between two dates in days
- * @param date1 - The end date
- * @param date2 - The start date
+ * 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.
  */
 export const dateDiff = (date1: OperandInput, date2: OperandInput): FunctionNode => fn('DATE_DIFF', [date1, date2]);
 
 /**
- * Helper: DATE_FORMAT(date, format) - Converts a date to a formatted string
- * @param date - The date/datetime value
- * @param format - The format string (dialect-specific)
+ * 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.
  */
 export const dateFormat = (date: OperandInput, format: OperandInput): FunctionNode => fn('DATE_FORMAT', [date, format]);
 
 /**
- * Helper: UNIX_TIMESTAMP() - Returns the current Unix epoch (seconds since 1970)
+ * Returns the current Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).
+ * @returns A FunctionNode representing the UNIX_TIMESTAMP SQL function.
  */
 export const unixTimestamp = (): FunctionNode => fn('UNIX_TIMESTAMP', []);
 
 /**
- * Helper: FROM_UNIXTIME(timestamp) - Converts Unix epoch seconds to a date
- * @param timestamp - Unix timestamp in seconds
+ * 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.
  */
 export const fromUnixTime = (timestamp: OperandInput): FunctionNode => fn('FROM_UNIXTIME', [timestamp]);
 
 /**
- * Helper: END_OF_MONTH(date) - Returns the last day of the month for a given date
+ * 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.
  */
 export const endOfMonth = (date: OperandInput): FunctionNode => fn('END_OF_MONTH', [date]);
 
 /**
- * Helper: DAY_OF_WEEK(date) - Returns the index of the weekday
+ * 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.
  */
 export const dayOfWeek = (date: OperandInput): FunctionNode => fn('DAY_OF_WEEK', [date]);
 
 /**
- * Helper: WEEK_OF_YEAR(date) - Returns the week number of the year
+ * 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.
  */
 export const weekOfYear = (date: OperandInput): FunctionNode => fn('WEEK_OF_YEAR', [date]);
 
 /**
- * Helper: DATE_TRUNC(part, date) - Resets date precision (e.g., first day of the month/year)
- * @param part - The truncation precision (e.g., 'YEAR', 'MONTH', 'DAY')
- * @param date - The date/datetime value
+ * 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.
  */
 export const dateTrunc = (part: OperandInput, date: OperandInput): FunctionNode => fn('DATE_TRUNC', [part, date]);

package/src/core/functions/numeric.ts

@@ -27,154 +27,219 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
 // ----------------------
 
 /**
- * Helper: ABS(x) - Returns the absolute value of a number
+ * Returns the absolute value of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the ABS SQL function.
  */
 export const abs = (value: OperandInput): FunctionNode => fn('ABS', [value]);
 
 /**
- * Helper: ACOS(x) - Returns the arccosine (inverse cosine)
+ * Returns the arccosine (inverse cosine) of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the ACOS SQL function.
  */
 export const acos = (value: OperandInput): FunctionNode => fn('ACOS', [value]);
 
 /**
- * Helper: ASIN(x) - Returns the arcsine (inverse sine)
+ * Returns the arcsine (inverse sine) of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the ASIN SQL function.
  */
 export const asin = (value: OperandInput): FunctionNode => fn('ASIN', [value]);
 
 /**
- * Helper: ATAN(x) - Returns the arctangent (inverse tangent)
+ * Returns the arctangent (inverse tangent) of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the ATAN SQL function.
  */
 export const atan = (value: OperandInput): FunctionNode => fn('ATAN', [value]);
 
 /**
- * Helper: ATAN2(y, x) - Returns the arctangent of the two arguments
+ * Returns the arctangent of the two arguments.
+ * @param y - The y-coordinate.
+ * @param x - The x-coordinate.
+ * @returns A FunctionNode representing the ATAN2 SQL function.
  */
 export const atan2 = (y: OperandInput, x: OperandInput): FunctionNode => fn('ATAN2', [y, x]);
 
 /**
- * Helper: CEIL(x) / CEILING(x) - Returns the smallest integer >= x
+ * Returns the smallest integer greater than or equal to a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the CEIL SQL function.
  */
 export const ceil = (value: OperandInput): FunctionNode => fn('CEIL', [value]);
 
 /**
- * Helper: CEILING(x) - Alias for CEIL
+ * Alias for ceil. Returns the smallest integer greater than or equal to a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the CEILING SQL function.
  */
 export const ceiling = (value: OperandInput): FunctionNode => fn('CEILING', [value]);
 
 /**
- * Helper: COS(x) - Returns the cosine of a number (in radians)
+ * Returns the cosine of a number (in radians).
+ * @param value - The numeric value in radians.
+ * @returns A FunctionNode representing the COS SQL function.
  */
 export const cos = (value: OperandInput): FunctionNode => fn('COS', [value]);
 
 /**
- * Helper: COT(x) - Returns the cotangent of a number
+ * Returns the cotangent of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the COT SQL function.
  */
 export const cot = (value: OperandInput): FunctionNode => fn('COT', [value]);
 
 /**
- * Helper: DEGREES(x) - Converts radians to degrees
+ * Converts radians to degrees.
+ * @param value - The angle in radians.
+ * @returns A FunctionNode representing the DEGREES SQL function.
  */
 export const degrees = (value: OperandInput): FunctionNode => fn('DEGREES', [value]);
 
 /**
- * Helper: EXP(x) - Returns e raised to the power of the argument
+ * Returns e raised to the power of the argument.
+ * @param value - The exponent.
+ * @returns A FunctionNode representing the EXP SQL function.
  */
 export const exp = (value: OperandInput): FunctionNode => fn('EXP', [value]);
 
 /**
- * Helper: FLOOR(x) - Returns the largest integer <= x
+ * Returns the largest integer less than or equal to a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the FLOOR SQL function.
  */
 export const floor = (value: OperandInput): FunctionNode => fn('FLOOR', [value]);
 
 /**
- * Helper: LN(x) - Returns the natural logarithm (base e)
+ * Returns the natural logarithm (base e) of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the LN SQL function.
  */
 export const ln = (value: OperandInput): FunctionNode => fn('LN', [value]);
 
 /**
- * Helper: LOG(x) - Returns the base-10 logarithm
+ * Returns the base-10 logarithm of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the LOG SQL function.
  */
 export const log = (value: OperandInput): FunctionNode => fn('LOG', [value]);
 
 /**
- * Helper: LOG10(x) - Returns the base-10 logarithm
+ * Returns the base-10 logarithm of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the LOG10 SQL function.
  */
 export const log10 = (value: OperandInput): FunctionNode => fn('LOG10', [value]);
 
 /**
- * Helper: LOG(base, x) - Returns the logarithm of x for a specific base
+ * Returns the logarithm of a number for a specific base.
+ * @param base - The base of the logarithm.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the LOG_BASE SQL function.
  */
 export const logBase = (base: OperandInput, value: OperandInput): FunctionNode => fn('LOG_BASE', [base, value]);
 
 /**
- * Helper: MOD(x, y) - Returns the remainder of x/y
+ * Returns the remainder of dividing x by y.
+ * @param x - The dividend.
+ * @param y - The divisor.
+ * @returns A FunctionNode representing the MOD SQL function.
  */
 export const mod = (x: OperandInput, y: OperandInput): FunctionNode => fn('MOD', [x, y]);
 
 /**
- * Helper: PI() - Returns the value of PI (approx. 3.14159...)
+ * Returns the value of PI (approximately 3.14159...).
+ * @returns A FunctionNode representing the PI SQL function.
  */
 export const pi = (): FunctionNode => fn('PI', []);
 
 /**
- * Helper: POWER(x, y) - Returns x raised to the power of y
+ * Returns x raised to the power of y.
+ * @param x - The base.
+ * @param y - The exponent.
+ * @returns A FunctionNode representing the POWER SQL function.
  */
 export const power = (x: OperandInput, y: OperandInput): FunctionNode => fn('POWER', [x, y]);
 
 /**
- * Helper: POW(x, y) - Alias for POWER
+ * Alias for power. Returns x raised to the power of y.
+ * @param x - The base.
+ * @param y - The exponent.
+ * @returns A FunctionNode representing the POW SQL function.
  */
 export const pow = (x: OperandInput, y: OperandInput): FunctionNode => fn('POW', [x, y]);
 
 /**
- * Helper: RADIANS(x) - Converts degrees to radians
+ * Converts degrees to radians.
+ * @param value - The angle in degrees.
+ * @returns A FunctionNode representing the RADIANS SQL function.
  */
 export const radians = (value: OperandInput): FunctionNode => fn('RADIANS', [value]);
 
 /**
- * Helper: RAND() / RANDOM() - Returns a random number
+ * Returns a random number between 0 and 1.
+ * @returns A FunctionNode representing the RANDOM SQL function.
  */
 export const random = (): FunctionNode => fn('RANDOM', []);
 
 /**
- * Helper: RAND() - Alias for RANDOM (returns float 0-1)
+ * Alias for random. Returns a random number between 0 and 1.
+ * @returns A FunctionNode representing the RAND SQL function.
  */
 export const rand = (): FunctionNode => fn('RAND', []);
 
 /**
- * Helper: ROUND(x[, decimals]) - Rounds a number to specified decimal places
+ * Rounds a number to a specified number of decimal places.
+ * @param value - The numeric value to round.
+ * @param decimals - The number of decimal places (optional).
+ * @returns A FunctionNode representing the ROUND SQL function.
  */
 export const round = (value: OperandInput, decimals?: OperandInput): FunctionNode =>
     decimals === undefined ? fn('ROUND', [value]) : fn('ROUND', [value, decimals]);
 
 /**
- * Helper: SIGN(x) - Returns the sign of a number (-1, 0, 1)
+ * Returns the sign of a number (-1 for negative, 0 for zero, 1 for positive).
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the SIGN SQL function.
  */
 export const sign = (value: OperandInput): FunctionNode => fn('SIGN', [value]);
 
 /**
- * Helper: SIN(x) - Returns the sine of a number (in radians)
+ * Returns the sine of a number (in radians).
+ * @param value - The numeric value in radians.
+ * @returns A FunctionNode representing the SIN SQL function.
  */
 export const sin = (value: OperandInput): FunctionNode => fn('SIN', [value]);
 
 /**
- * Helper: SQRT(x) - Returns the square root of a number
+ * Returns the square root of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the SQRT SQL function.
  */
 export const sqrt = (value: OperandInput): FunctionNode => fn('SQRT', [value]);
 
 /**
- * Helper: TAN(x) - Returns the tangent of a number (in radians)
+ * Returns the tangent of a number (in radians).
+ * @param value - The numeric value in radians.
+ * @returns A FunctionNode representing the TAN SQL function.
  */
 export const tan = (value: OperandInput): FunctionNode => fn('TAN', [value]);
 
 /**
- * Helper: TRUNC(x[, decimals]) / TRUNCATE(x, decimals) - Truncates a number without rounding
+ * Truncates a number to a specified number of decimal places without rounding.
+ * @param value - The numeric value to truncate.
+ * @param decimals - The number of decimal places (optional).
+ * @returns A FunctionNode representing the TRUNC SQL function.
  */
 export const trunc = (value: OperandInput, decimals?: OperandInput): FunctionNode =>
     decimals === undefined ? fn('TRUNC', [value]) : fn('TRUNC', [value, decimals]);
 
 /**
- * Helper: TRUNCATE(x, decimals) - Alias for TRUNC
+ * Alias for trunc. Truncates a number to a specified number of decimal places without rounding.
+ * @param value - The numeric value to truncate.
+ * @param decimals - The number of decimal places.
+ * @returns A FunctionNode representing the TRUNCATE SQL function.
  */
 export const truncate = (value: OperandInput, decimals: OperandInput): FunctionNode =>
     fn('TRUNCATE', [value, decimals]);