metal-orm 1.0.62 → 1.0.64

package/src/core/functions/text.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,246 +22,313 @@ const fn = (key: string, args: OperandInput[]): FunctionNode => ({
   args: args.map(toOperand)
 });
 
+const sfn = (key: string, args: OperandInput[]): TypedExpression<string> => asType<string>(fn(key, args));
+const nfn = (key: string, args: OperandInput[]): TypedExpression<number> => asType<number>(fn(key, args));
+
 /**
  * Converts a string to lowercase.
- * @param value - The string value.
- * @returns A FunctionNode representing the LOWER SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `LOWER` SQL function.
+ * 
+ * @example
+ * lower(users.email);
  */
-export const lower = (value: OperandInput): FunctionNode => fn('LOWER', [value]);
+export const lower = (value: OperandInput): TypedExpression<string> => sfn('LOWER', [value]);
 
 /**
  * Converts a string to uppercase.
- * @param value - The string value.
- * @returns A FunctionNode representing the UPPER SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `UPPER` SQL function.
+ * 
+ * @example
+ * upper(users.firstName);
  */
-export const upper = (value: OperandInput): FunctionNode => fn('UPPER', [value]);
+export const upper = (value: OperandInput): TypedExpression<string> => sfn('UPPER', [value]);
 
 /**
  * Returns the ASCII code of the first character of a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the ASCII SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<number>` representing the `ASCII` SQL function.
+ * 
+ * @example
+ * ascii(users.initial);
  */
-export const ascii = (value: OperandInput): FunctionNode => fn('ASCII', [value]);
+export const ascii = (value: OperandInput): TypedExpression<number> => nfn('ASCII', [value]);
 
 /**
  * Returns a string from one or more ASCII codes.
- * @param codes - The ASCII codes.
- * @returns A FunctionNode representing the CHAR SQL function.
+ * 
+ * @param codes - One or more ASCII codes.
+ * @returns A `TypedExpression<string>` representing the `CHAR` SQL function.
+ * 
+ * @example
+ * char(65, 66, 67); // 'ABC'
  */
-export const char = (...codes: OperandInput[]): FunctionNode => {
+export const char = (...codes: OperandInput[]): TypedExpression<string> => {
   if (codes.length === 0) throw new Error('char() expects at least 1 argument');
-  return fn('CHAR', codes);
+  return sfn('CHAR', codes);
 };
 
 /**
  * Returns the number of characters in a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the CHAR_LENGTH SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<number>` representing the `CHAR_LENGTH` SQL function.
+ * 
+ * @example
+ * charLength(users.bio);
  */
-export const charLength = (value: OperandInput): FunctionNode => fn('CHAR_LENGTH', [value]);
+export const charLength = (value: OperandInput): TypedExpression<number> => nfn('CHAR_LENGTH', [value]);
 
 /**
  * Returns the length of a string in bytes or characters.
- * @param value - The string value.
- * @returns A FunctionNode representing the LENGTH SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<number>` representing the `LENGTH` SQL function.
+ * 
+ * @example
+ * length(users.password);
  */
-export const length = (value: OperandInput): FunctionNode => fn('LENGTH', [value]);
+export const length = (value: OperandInput): TypedExpression<number> => nfn('LENGTH', [value]);
 
 /**
  * Removes leading and trailing whitespace or specified characters from a string.
- * @param value - The string value.
- * @param chars - The characters to trim (optional).
- * @returns A FunctionNode representing the TRIM SQL function.
+ * 
+ * @param value - The string value or column.
+ * @param chars - Optional characters to trim.
+ * @returns A `TypedExpression<string>` representing the `TRIM` SQL function.
+ * 
+ * @example
+ * trim(users.name);
+ * trim(users.path, '/');
  */
-export const trim = (value: OperandInput, chars?: OperandInput): FunctionNode =>
-  chars === undefined ? fn('TRIM', [value]) : fn('TRIM', [value, chars]);
+export const trim = (value: OperandInput, chars?: OperandInput): TypedExpression<string> =>
+  chars === undefined ? sfn('TRIM', [value]) : sfn('TRIM', [value, chars]);
 
 /**
  * Removes leading whitespace from a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the LTRIM SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `LTRIM` SQL function.
  */
-export const ltrim = (value: OperandInput): FunctionNode => fn('LTRIM', [value]);
+export const ltrim = (value: OperandInput): TypedExpression<string> => sfn('LTRIM', [value]);
 
 /**
  * Removes trailing whitespace from a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the RTRIM SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `RTRIM` SQL function.
  */
-export const rtrim = (value: OperandInput): FunctionNode => fn('RTRIM', [value]);
+export const rtrim = (value: OperandInput): TypedExpression<string> => sfn('RTRIM', [value]);
 
 /**
  * Concatenates two or more strings.
- * @param args - The strings to concatenate.
- * @returns A FunctionNode representing the CONCAT SQL function.
+ * 
+ * @param args - The strings or columns to concatenate.
+ * @returns A `TypedExpression<string>` representing the `CONCAT` SQL function.
+ * 
+ * @example
+ * concat(users.firstName, ' ', users.lastName);
  */
-export const concat = (...args: OperandInput[]): FunctionNode => {
+export const concat = (...args: OperandInput[]): TypedExpression<string> => {
   if (args.length < 2) throw new Error('concat() expects at least 2 arguments');
-  return fn('CONCAT', args);
+  return sfn('CONCAT', args);
 };
 
 /**
  * Concatenates strings with a separator.
+ * 
  * @param separator - The separator string.
- * @param args - The strings to concatenate.
- * @returns A FunctionNode representing the CONCAT_WS SQL function.
+ * @param args - The strings or columns to concatenate.
+ * @returns A `TypedExpression<string>` representing the `CONCAT_WS` SQL function.
+ * 
+ * @example
+ * concatWs(', ', users.lastName, users.firstName);
  */
-export const concatWs = (separator: OperandInput, ...args: OperandInput[]): FunctionNode => {
+export const concatWs = (separator: OperandInput, ...args: OperandInput[]): TypedExpression<string> => {
   if (args.length < 1) throw new Error('concatWs() expects at least 2 arguments including the separator');
-  return fn('CONCAT_WS', [separator, ...args]);
+  return sfn('CONCAT_WS', [separator, ...args]);
 };
 
 /**
  * Extracts a substring from a string.
- * @param value - The string value.
- * @param start - The starting position.
- * @param length - The length of the substring (optional).
- * @returns A FunctionNode representing the SUBSTR SQL function.
+ * 
+ * @param value - The input string or column.
+ * @param start - The starting position (1-indexed).
+ * @param length - Optional length of the substring.
+ * @returns A `TypedExpression<string>` representing the `SUBSTR` SQL function.
+ * 
+ * @example
+ * substr(users.token, 1, 8);
  */
-export const substr = (value: OperandInput, start: OperandInput, length?: OperandInput): FunctionNode =>
-  length === undefined ? fn('SUBSTR', [value, start]) : fn('SUBSTR', [value, start, length]);
+export const substr = (value: OperandInput, start: OperandInput, length?: OperandInput): TypedExpression<string> =>
+  length === undefined ? sfn('SUBSTR', [value, start]) : sfn('SUBSTR', [value, start, length]);
 
 /**
  * Returns the leftmost characters of a string.
- * @param value - The string value.
- * @param len - The number of characters to return.
- * @returns A FunctionNode representing the LEFT SQL function.
+ * 
+ * @param value - The string value or column.
+ * @param len - Number of characters to return.
+ * @returns A `TypedExpression<string>` representing the `LEFT` SQL function.
  */
-export const left = (value: OperandInput, len: OperandInput): FunctionNode => fn('LEFT', [value, len]);
+export const left = (value: OperandInput, len: OperandInput): TypedExpression<string> => sfn('LEFT', [value, len]);
 
 /**
  * Returns the rightmost characters of a string.
- * @param value - The string value.
- * @param len - The number of characters to return.
- * @returns A FunctionNode representing the RIGHT SQL function.
+ * 
+ * @param value - The string value or column.
+ * @param len - Number of characters to return.
+ * @returns A `TypedExpression<string>` representing the `RIGHT` SQL function.
  */
-export const right = (value: OperandInput, len: OperandInput): FunctionNode => fn('RIGHT', [value, len]);
+export const right = (value: OperandInput, len: OperandInput): TypedExpression<string> => sfn('RIGHT', [value, len]);
 
 /**
  * Returns the position of a substring in a string.
+ * 
  * @param substring - The substring to search for.
- * @param value - The string to search in.
- * @returns A FunctionNode representing the POSITION SQL function.
+ * @param value - The string or column to search within.
+ * @returns A `TypedExpression<number>` representing the `POSITION` SQL function.
  */
-export const position = (substring: OperandInput, value: OperandInput): FunctionNode => fn('POSITION', [substring, value]);
+export const position = (substring: OperandInput, value: OperandInput): TypedExpression<number> => nfn('POSITION', [substring, value]);
 
 /**
  * Returns the position of a substring in a string.
- * @param value - The string to search in.
+ * 
+ * @param value - The string or column to search within.
  * @param substring - The substring to search for.
- * @returns A FunctionNode representing the INSTR SQL function.
+ * @returns A `TypedExpression<number>` representing the `INSTR` SQL function.
  */
-export const instr = (value: OperandInput, substring: OperandInput): FunctionNode => fn('INSTR', [value, substring]);
+export const instr = (value: OperandInput, substring: OperandInput): TypedExpression<number> => nfn('INSTR', [value, substring]);
 
 /**
  * Returns the position of a substring in a string, optionally starting from a position.
- * @param substring - The substring to search for.
- * @param value - The string to search in.
- * @param start - The starting position (optional).
- * @returns A FunctionNode representing the LOCATE SQL function.
+ * 
+ * @param substring - Substring to find.
+ * @param value - String/column to search.
+ * @param start - Optional starting position.
+ * @returns A `TypedExpression<number>` representing the `LOCATE` SQL function.
  */
-export const locate = (substring: OperandInput, value: OperandInput, start?: OperandInput): FunctionNode =>
-  start === undefined ? fn('LOCATE', [substring, value]) : fn('LOCATE', [substring, value, start]);
+export const locate = (substring: OperandInput, value: OperandInput, start?: OperandInput): TypedExpression<number> =>
+  start === undefined ? nfn('LOCATE', [substring, value]) : nfn('LOCATE', [substring, value, start]);
 
 /**
  * Replaces occurrences of a substring in a string.
- * @param value - The string to search in.
- * @param search - The substring to replace.
- * @param replacement - The replacement string.
- * @returns A FunctionNode representing the REPLACE SQL function.
+ * 
+ * @param value - The original string or column.
+ * @param search - Substring to search for.
+ * @param replacement - Replacement string.
+ * @returns A `TypedExpression<string>` representing the `REPLACE` SQL function.
+ * 
+ * @example
+ * replace(users.email, 'old.com', 'new.com');
  */
-export const replace = (value: OperandInput, search: OperandInput, replacement: OperandInput): FunctionNode =>
-  fn('REPLACE', [value, search, replacement]);
+export const replace = (value: OperandInput, search: OperandInput, replacement: OperandInput): TypedExpression<string> =>
+  sfn('REPLACE', [value, search, replacement]);
 
 /**
  * Repeats a string a specified number of times.
+ * 
  * @param value - The string to repeat.
- * @param count - The number of times to repeat.
- * @returns A FunctionNode representing the REPEAT SQL function.
+ * @param count - How many times to repeat.
+ * @returns A `TypedExpression<string>` representing the `REPEAT` SQL function.
  */
-export const repeat = (value: OperandInput, count: OperandInput): FunctionNode => fn('REPEAT', [value, count]);
+export const repeat = (value: OperandInput, count: OperandInput): TypedExpression<string> => sfn('REPEAT', [value, count]);
 
 /**
  * Left-pads a string to a certain length with another string.
- * @param value - The string to pad.
- * @param len - The length to pad to.
- * @param pad - The padding string.
- * @returns A FunctionNode representing the LPAD SQL function.
+ * 
+ * @param value - The string/column to pad.
+ * @param len - Target length.
+ * @param pad - Padding string.
+ * @returns A `TypedExpression<string>` representing the `LPAD` SQL function.
  */
-export const lpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
-  fn('LPAD', [value, len, pad]);
+export const lpad = (value: OperandInput, len: OperandInput, pad: OperandInput): TypedExpression<string> =>
+  sfn('LPAD', [value, len, pad]);
 
 /**
  * Right-pads a string to a certain length with another string.
- * @param value - The string to pad.
- * @param len - The length to pad to.
- * @param pad - The padding string.
- * @returns A FunctionNode representing the RPAD SQL function.
+ * 
+ * @param value - The string/column to pad.
+ * @param len - Target length.
+ * @param pad - Padding string.
+ * @returns A `TypedExpression<string>` representing the `RPAD` SQL function.
  */
-export const rpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
-  fn('RPAD', [value, len, pad]);
+export const rpad = (value: OperandInput, len: OperandInput, pad: OperandInput): TypedExpression<string> =>
+  sfn('RPAD', [value, len, pad]);
 
 /**
  * Returns a string consisting of a specified number of spaces.
- * @param count - The number of spaces.
- * @returns A FunctionNode representing the SPACE SQL function.
+ * 
+ * @param count - Number of spaces.
+ * @returns A `TypedExpression<string>` representing the `SPACE` SQL function.
  */
-export const space = (count: OperandInput): FunctionNode => fn('SPACE', [count]);
+export const space = (count: OperandInput): TypedExpression<string> => sfn('SPACE', [count]);
 
 /**
  * Reverses a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the REVERSE SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `REVERSE` SQL function.
  */
-export const reverse = (value: OperandInput): FunctionNode => fn('REVERSE', [value]);
+export const reverse = (value: OperandInput): TypedExpression<string> => sfn('REVERSE', [value]);
 
 /**
  * Capitalizes the first letter of each word in a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the INITCAP SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `INITCAP` SQL function.
  */
-export const initcap = (value: OperandInput): FunctionNode => fn('INITCAP', [value]);
+export const initcap = (value: OperandInput): TypedExpression<string> => sfn('INITCAP', [value]);
 
 /**
  * Returns the MD5 hash of a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the MD5 SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `MD5` SQL function.
  */
-export const md5 = (value: OperandInput): FunctionNode => fn('MD5', [value]);
+export const md5 = (value: OperandInput): TypedExpression<string> => sfn('MD5', [value]);
 
 /**
  * Returns the SHA-1 hash of a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the SHA1 SQL function.
+ * 
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `SHA1` SQL function.
  */
-export const sha1 = (value: OperandInput): FunctionNode => fn('SHA1', [value]);
+export const sha1 = (value: OperandInput): TypedExpression<string> => sfn('SHA1', [value]);
 
 /**
  * Returns the SHA-2 hash of a string with a specified bit length.
- * @param value - The string value.
- * @param bits - The bit length (e.g., 224, 256, 384, 512).
- * @returns A FunctionNode representing the SHA2 SQL function.
+ * 
+ * @param value - The input.
+ * @param bits - Bit length (e.g., 256, 512).
+ * @returns A `TypedExpression<string>` representing the `SHA2` SQL function.
  */
-export const sha2 = (value: OperandInput, bits: OperandInput): FunctionNode => fn('SHA2', [value, bits]);
+export const sha2 = (value: OperandInput, bits: OperandInput): TypedExpression<string> => sfn('SHA2', [value, bits]);
 
 /**
  * Returns the length of a string in bits.
- * @param value - The string value.
- * @returns A FunctionNode representing the BIT_LENGTH SQL function.
+ * 
+ * @param value - String value or column.
+ * @returns A `TypedExpression<number>` representing the `BIT_LENGTH` SQL function.
  */
-export const bitLength = (value: OperandInput): FunctionNode => fn('BIT_LENGTH', [value]);
+export const bitLength = (value: OperandInput): TypedExpression<number> => nfn('BIT_LENGTH', [value]);
 
 /**
  * Returns the length of a string in bytes.
- * @param value - The string value.
- * @returns A FunctionNode representing the OCTET_LENGTH SQL function.
+ * 
+ * @param value - String value or column.
+ * @returns A `TypedExpression<number>` representing the `OCTET_LENGTH` SQL function.
  */
-export const octetLength = (value: OperandInput): FunctionNode => fn('OCTET_LENGTH', [value]);
+export const octetLength = (value: OperandInput): TypedExpression<number> => nfn('OCTET_LENGTH', [value]);
 
 /**
  * Returns a string from an ASCII code.
- * @param code - The ASCII code.
- * @returns A FunctionNode representing the CHR/CHAR SQL function.
+ * 
+ * @param code - ASCII code.
+ * @returns A `TypedExpression<string>` representing the `CHR` SQL function.
  */
-export const chr = (code: OperandInput): FunctionNode => fn('CHR', [code]);
+export const chr = (code: OperandInput): TypedExpression<string> => sfn('CHR', [code]);
 

package/src/decorators/bootstrap.ts

@@ -25,13 +25,14 @@ import {
 
 import { tableRef, type TableRef } from '../schema/table.js';
 import {
-  SelectableKeys,
-  ColumnDef,
-  HasManyCollection,
-  HasOneReference,
-  BelongsToReference,
-  ManyToManyCollection
-} from '../schema/types.js';
+  SelectableKeys,
+  ColumnDef,
+  HasManyCollection,
+  HasOneReference,
+  BelongsToReference,
+  ManyToManyCollection,
+  EntityInstance
+} from '../schema/types.js';
 
 const unwrapTarget = (target: EntityOrTableTargetResolver): EntityOrTableTarget => {
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -196,9 +197,9 @@ type NonFunctionKeys<T> = {
 type RelationKeys<TEntity extends object> =
   Exclude<NonFunctionKeys<TEntity>, SelectableKeys<TEntity>> & string;
 
-type EntityTable<TEntity extends object> =
-  Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
-    relations: {
+type EntityTable<TEntity extends object> =
+  Omit<TableDef<{ [K in SelectableKeys<TEntity>]: ColumnDef }>, 'relations'> & {
+    relations: {
       [K in RelationKeys<TEntity>]:
       NonNullable<TEntity[K]> extends HasManyCollection<infer TChild>
       ? HasManyRelation<EntityTable<NonNullable<TChild> & object>>
@@ -214,15 +215,18 @@ type EntityTable<TEntity extends object> =
       : NonNullable<TEntity[K]> extends object
       ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>>
       : never;
-    };
-  };
-
-export const selectFromEntity = <TEntity extends object>(
-  ctor: EntityConstructor<TEntity>
-): SelectQueryBuilder<TEntity, EntityTable<TEntity>> => {
-  const table = getTableDefFromEntity(ctor);
-  if (!table) {
-    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
+    };
+  };
+
+export type DecoratedEntityInstance<TEntity extends object> =
+  TEntity & EntityInstance<EntityTable<TEntity>>;
+
+export const selectFromEntity = <TEntity extends object>(
+  ctor: EntityConstructor<TEntity>
+): SelectQueryBuilder<DecoratedEntityInstance<TEntity>, EntityTable<TEntity>> => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
   }
   return new SelectQueryBuilder(
     table as unknown as EntityTable<TEntity>,

package/src/query-builder/hydration-planner.ts

@@ -31,22 +31,20 @@ export class HydrationPlanner {
    * @param columns - Columns to capture
    * @returns Updated HydrationPlanner with captured columns
    */
-  captureRootColumns(columns: ProjectionNode[]): HydrationPlanner {
-    const currentPlan = this.getPlanOrDefault();
-    const rootCols = new Set(currentPlan.rootColumns);
-    let changed = false;
-
-    columns.forEach(node => {
-      if (node.type !== 'Column') return;
-      if (node.table !== this.table.name) return;
-
-      const alias = node.alias || node.name;
-      if (isRelationAlias(alias)) return;
-      if (!rootCols.has(alias)) {
-        rootCols.add(alias);
-        changed = true;
-      }
-    });
+  captureRootColumns(columns: ProjectionNode[]): HydrationPlanner {
+    const currentPlan = this.getPlanOrDefault();
+    const rootCols = new Set(currentPlan.rootColumns);
+    let changed = false;
+
+    columns.forEach(node => {
+      const alias = node.type === 'Column' ? (node.alias || node.name) : node.alias;
+      if (!alias || isRelationAlias(alias)) return;
+      if (node.type === 'Column' && node.table !== this.table.name) return;
+      if (!rootCols.has(alias)) {
+        rootCols.add(alias);
+        changed = true;
+      }
+    });
 
     if (!changed) return this;
     return new HydrationPlanner(this.table, {