metal-orm 1.0.34 → 1.0.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/src/decorators/bootstrap.ts

@@ -119,16 +119,16 @@ export const bootstrapEntities = (): TableDef[] => {
   return metas.map(meta => meta.table!) as TableDef[];
 };
 
-export const getTableDefFromEntity = (ctor: EntityConstructor): TableDef | undefined => {
+export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor: EntityConstructor): TTable | undefined => {
   const meta = getEntityMetadata(ctor);
   if (!meta) return undefined;
   if (!meta.table) {
     bootstrapEntities();
   }
-  return meta.table;
+  return meta.table as TTable;
 };
 
-export const selectFromEntity = <TTable extends TableDef>(
+export const selectFromEntity = <TTable extends TableDef = TableDef>(
   ctor: EntityConstructor
 ): SelectQueryBuilder<any, TTable> => {
   const table = getTableDefFromEntity(ctor);

package/src/decorators/column.ts

@@ -18,9 +18,10 @@ export interface ColumnOptions {
   args?: ColumnDef['args'];
   notNull?: boolean;
   primary?: boolean;
+  tsType?: ColumnDef['tsType'];
 }
 
-export type ColumnInput = ColumnOptions | ColumnDef;
+export type ColumnInput = ColumnOptions | ColumnDef<any, any>;
 
 const normalizeColumnInput = (input: ColumnInput): ColumnDefLike => {
   const asOptions = input as ColumnOptions;
@@ -30,6 +31,7 @@ const normalizeColumnInput = (input: ColumnInput): ColumnDefLike => {
     args: asOptions.args ?? asDefinition.args,
     notNull: asOptions.notNull ?? asDefinition.notNull,
     primary: asOptions.primary ?? asDefinition.primary,
+    tsType: asDefinition.tsType ?? asOptions.tsType,
     unique: asDefinition.unique,
     default: asDefinition.default,
     autoIncrement: asDefinition.autoIncrement,

package/src/orm/entity-metadata.ts

@@ -6,7 +6,14 @@ export type EntityConstructor = new (...args: any[]) => any;
 export type EntityOrTableTarget = EntityConstructor | TableDef;
 export type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
 
-export type ColumnDefLike = Omit<ColumnDef, 'name' | 'table'>;
+export type ColumnDefLike<T extends ColumnDef = ColumnDef> = Omit<T, 'name' | 'table'>;
+
+type MaterializeColumns<TColumns extends Record<string, ColumnDefLike>> = {
+  [K in keyof TColumns]: ColumnDef<TColumns[K]['type'], TColumns[K]['tsType']> & Omit<
+    TColumns[K],
+    'name' | 'table' | 'type' | 'tsType'
+  > & { name: string; table: string };
+};
 
 interface BaseRelationMetadata {
   propertyKey: string;
@@ -49,13 +56,13 @@ export type RelationMetadata =
   | BelongsToRelationMetadata
   | BelongsToManyRelationMetadata;
 
-export interface EntityMetadata {
+export interface EntityMetadata<TColumns extends Record<string, ColumnDefLike> = Record<string, ColumnDefLike>> {
   target: EntityConstructor;
   tableName: string;
-  columns: Record<string, ColumnDefLike>;
+  columns: TColumns;
   relations: Record<string, RelationMetadata>;
   hooks?: TableHooks;
-  table?: TableDef;
+  table?: TableDef<MaterializeColumns<TColumns>>;
 }
 
 const metadataMap = new Map<EntityConstructor, EntityMetadata>();
@@ -96,7 +103,7 @@ export const addColumnMetadata = (
   column: ColumnDefLike
 ): void => {
   const meta = ensureEntityMetadata(target);
-  meta.columns[propertyKey] = { ...column };
+  (meta.columns as Record<string, ColumnDefLike>)[propertyKey] = { ...column };
 };
 
 export const addRelationMetadata = (
@@ -122,19 +129,19 @@ export const setEntityTableName = (
   }
 };
 
-export const buildTableDef = (meta: EntityMetadata): TableDef => {
+export const buildTableDef = <TColumns extends Record<string, ColumnDefLike>>(meta: EntityMetadata<TColumns>): TableDef<MaterializeColumns<TColumns>> => {
   if (meta.table) {
     return meta.table;
   }
 
-  const columns = Object.entries(meta.columns).reduce<Record<string, ColumnDef>>((acc, [key, def]) => {
-    acc[key] = {
+  const columns = Object.entries(meta.columns).reduce<MaterializeColumns<TColumns>>((acc, [key, def]) => {
+    (acc as any)[key] = {
       ...def,
       name: key,
       table: meta.tableName
     };
     return acc;
-  }, {});
+  }, {} as MaterializeColumns<TColumns>);
 
   const table = defineTable(meta.tableName, columns, {}, meta.hooks);
   meta.table = table;

package/src/orm/entity.ts

@@ -104,17 +104,20 @@ export const createEntityProxy = <
   return proxy;
 };
 
-export const createEntityFromRow = <TTable extends TableDef>(
+export const createEntityFromRow = <
+  TTable extends TableDef,
+  TResult extends EntityInstance<TTable> = EntityInstance<TTable>
+>(
   ctx: EntityContext,
   table: TTable,
   row: Record<string, any>,
   lazyRelations: (keyof RelationMap<TTable>)[] = []
-): EntityInstance<TTable> => {
+): TResult => {
   const pkName = findPrimaryKey(table);
   const pkValue = row[pkName];
   if (pkValue !== undefined && pkValue !== null) {
     const tracked = ctx.getEntity(table, pkValue);
-    if (tracked) return tracked;
+    if (tracked) return tracked as TResult;
   }
 
   const entity = createEntityProxy(ctx, table, row, lazyRelations);
@@ -124,7 +127,7 @@ export const createEntityFromRow = <TTable extends TableDef>(
     ctx.trackNew(table, entity);
   }
 
-  return entity;
+  return entity as TResult;
 };
 
 const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));

package/src/schema/column.ts

@@ -1,6 +1,6 @@
-/**
- * Supported column data types for database schema definitions
- */
+/**
+ * Supported column data types for database schema definitions
+ */
 export type ColumnType =
   | 'INT'
   | 'INTEGER'
@@ -42,110 +42,112 @@ export type ColumnType =
   | 'timestamp'
   | 'timestamptz'
   | 'boolean';
-
-export type ReferentialAction =
-  | 'NO ACTION'
-  | 'RESTRICT'
-  | 'CASCADE'
-  | 'SET NULL'
-  | 'SET DEFAULT';
-
-export interface RawDefaultValue {
-  raw: string;
-}
-
-export type DefaultValue = unknown | RawDefaultValue;
-
-export interface ForeignKeyReference {
-  /** Target table name */
-  table: string;
-  /** Target column name */
-  column: string;
-  /** Optional constraint name */
-  name?: string;
-  /** ON DELETE action */
-  onDelete?: ReferentialAction;
-  /** ON UPDATE action */
-  onUpdate?: ReferentialAction;
-  /** Whether the constraint is deferrable (Postgres) */
-  deferrable?: boolean;
-}
-
-/**
- * Definition of a database column
- */
-export interface ColumnDef<T extends ColumnType = ColumnType> {
-  /** Column name (filled at runtime by defineTable) */
-  name: string;
-  /** Data type of the column */
-  type: T;
-  /** Whether this column is a primary key */
-  primary?: boolean;
-  /** Whether this column cannot be null */
-  notNull?: boolean;
-  /** Whether this column must be unique (or name of the unique constraint) */
-  unique?: boolean | string;
-  /** Default value for the column */
-  default?: DefaultValue;
-  /** Whether the column auto-increments / identity */
-  autoIncrement?: boolean;
-  /** Identity strategy where supported */
-  generated?: 'always' | 'byDefault';
-  /** Inline check constraint expression */
-  check?: string;
-  /** Foreign key reference */
-  references?: ForeignKeyReference;
-  /** Column comment/description */
-  comment?: string;
-  /** Additional arguments for the column type (e.g., VARCHAR length) */
-  args?: any[];
-  /** Table name this column belongs to (filled at runtime by defineTable) */
-  table?: string;
-}
-
-/**
- * Factory for creating column definitions with common data types
- */
-export const col = {
-  /**
-   * Creates an integer column definition
-   * @returns ColumnDef with INT type
-   */
-  int: (): ColumnDef<'INT'> => ({ name: '', type: 'INT' }),
-
-  /**
-   * Creates a big integer column definition
-   */
-  bigint: (): ColumnDef<'BIGINT'> => ({ name: '', type: 'BIGINT' }),
-
-  /**
-   * Creates a variable character column definition
-   * @param length - Maximum length of the string
-   * @returns ColumnDef with VARCHAR type
-   */
-  varchar: (length: number): ColumnDef<'VARCHAR'> => ({ name: '', type: 'VARCHAR', args: [length] }),
-
-  /**
-   * Creates a fixed precision decimal column definition
-   */
-  decimal: (precision: number, scale = 0): ColumnDef<'DECIMAL'> => ({
-    name: '',
-    type: 'DECIMAL',
-    args: [precision, scale]
-  }),
-
-  /**
-   * Creates a floating point column definition
-   */
-  float: (precision?: number): ColumnDef<'FLOAT'> => ({
-    name: '',
-    type: 'FLOAT',
-    args: precision !== undefined ? [precision] : undefined
-  }),
-
-  /**
-   * Creates a UUID column definition
-   */
+
+export type ReferentialAction =
+  | 'NO ACTION'
+  | 'RESTRICT'
+  | 'CASCADE'
+  | 'SET NULL'
+  | 'SET DEFAULT';
+
+export interface RawDefaultValue {
+  raw: string;
+}
+
+export type DefaultValue = unknown | RawDefaultValue;
+
+export interface ForeignKeyReference {
+  /** Target table name */
+  table: string;
+  /** Target column name */
+  column: string;
+  /** Optional constraint name */
+  name?: string;
+  /** ON DELETE action */
+  onDelete?: ReferentialAction;
+  /** ON UPDATE action */
+  onUpdate?: ReferentialAction;
+  /** Whether the constraint is deferrable (Postgres) */
+  deferrable?: boolean;
+}
+
+/**
+ * Definition of a database column
+ */
+export interface ColumnDef<T extends ColumnType = ColumnType, TRuntime = unknown> {
+  /** Column name (filled at runtime by defineTable) */
+  name: string;
+  /** Data type of the column */
+  type: T;
+  /** Optional override for the inferred TypeScript type */
+  tsType?: TRuntime;
+  /** Whether this column is a primary key */
+  primary?: boolean;
+  /** Whether this column cannot be null */
+  notNull?: boolean;
+  /** Whether this column must be unique (or name of the unique constraint) */
+  unique?: boolean | string;
+  /** Default value for the column */
+  default?: DefaultValue;
+  /** Whether the column auto-increments / identity */
+  autoIncrement?: boolean;
+  /** Identity strategy where supported */
+  generated?: 'always' | 'byDefault';
+  /** Inline check constraint expression */
+  check?: string;
+  /** Foreign key reference */
+  references?: ForeignKeyReference;
+  /** Column comment/description */
+  comment?: string;
+  /** Additional arguments for the column type (e.g., VARCHAR length) */
+  args?: any[];
+  /** Table name this column belongs to (filled at runtime by defineTable) */
+  table?: string;
+}
+
+/**
+ * Factory for creating column definitions with common data types
+ */
+export const col = {
+  /**
+   * Creates an integer column definition
+   * @returns ColumnDef with INT type
+   */
+  int: (): ColumnDef<'INT'> => ({ name: '', type: 'INT' }),
+
+  /**
+   * Creates a big integer column definition
+   */
+  bigint: (): ColumnDef<'BIGINT'> => ({ name: '', type: 'BIGINT' }),
+
+  /**
+   * Creates a variable character column definition
+   * @param length - Maximum length of the string
+   * @returns ColumnDef with VARCHAR type
+   */
+  varchar: (length: number): ColumnDef<'VARCHAR'> => ({ name: '', type: 'VARCHAR', args: [length] }),
+
+  /**
+   * Creates a fixed precision decimal column definition
+   */
+  decimal: (precision: number, scale = 0): ColumnDef<'DECIMAL'> => ({
+    name: '',
+    type: 'DECIMAL',
+    args: [precision, scale]
+  }),
+
+  /**
+   * Creates a floating point column definition
+   */
+  float: (precision?: number): ColumnDef<'FLOAT'> => ({
+    name: '',
+    type: 'FLOAT',
+    args: precision !== undefined ? [precision] : undefined
+  }),
+
+  /**
+   * Creates a UUID column definition
+   */
   uuid: (): ColumnDef<'UUID'> => ({ name: '', type: 'UUID' }),
 
   /**
@@ -179,110 +181,110 @@ export const col = {
   /**
    * Creates a timestamp column definition
    */
-  timestamp: (): ColumnDef<'TIMESTAMP'> => ({ name: '', type: 'TIMESTAMP' }),
-
-  /**
-   * Creates a timestamptz column definition
-   */
-  timestamptz: (): ColumnDef<'TIMESTAMPTZ'> => ({ name: '', type: 'TIMESTAMPTZ' }),
-
-  /**
-   * Creates a date column definition
-   */
-  date: (): ColumnDef<'DATE'> => ({ name: '', type: 'DATE' }),
-
-  /**
-   * Creates a datetime column definition
-   */
-  datetime: (): ColumnDef<'DATETIME'> => ({ name: '', type: 'DATETIME' }),
-
-  /**
-   * Creates a JSON column definition
-   * @returns ColumnDef with JSON type
-   */
-  json: (): ColumnDef<'JSON'> => ({ name: '', type: 'JSON' }),
-
-  /**
-   * Creates a boolean column definition
-   * @returns ColumnDef with BOOLEAN type
-   */
-  boolean: (): ColumnDef<'BOOLEAN'> => ({ name: '', type: 'BOOLEAN' }),
-
-  /**
-   * Creates an enum column definition
-   * @param values - Enum values
-   */
-  enum: (values: string[]): ColumnDef<'ENUM'> => ({ name: '', type: 'ENUM', args: values }),
-
-  /**
-   * Marks a column definition as a primary key
-   * @param def - Column definition to modify
-   * @returns Modified ColumnDef with primary: true
-   */
-  primaryKey: <T extends ColumnType>(def: ColumnDef<T>): ColumnDef<T> =>
-    ({ ...def, primary: true }),
-
-  /**
-   * Marks a column as NOT NULL
-   */
-  notNull: <T extends ColumnType>(def: ColumnDef<T>): ColumnDef<T> =>
-    ({ ...def, notNull: true }),
-
-  /**
-   * Marks a column as UNIQUE
-   */
-  unique: <T extends ColumnType>(def: ColumnDef<T>, name?: string): ColumnDef<T> =>
-    ({
-      ...def,
-      unique: name ?? true
-    }),
-
-  /**
-   * Sets a default value for the column
-   */
-  default: <T extends ColumnType>(def: ColumnDef<T>, value: unknown): ColumnDef<T> =>
-    ({
-      ...def,
-      default: value
-    }),
-
-  /**
-   * Sets a raw SQL default value for the column
-   */
-  defaultRaw: <T extends ColumnType>(def: ColumnDef<T>, expression: string): ColumnDef<T> =>
-    ({
-      ...def,
-      default: { raw: expression }
-    }),
-
-  /**
-   * Marks a column as auto-increment / identity
-   */
-  autoIncrement: <T extends ColumnType>(
-    def: ColumnDef<T>,
-    strategy: ColumnDef['generated'] = 'byDefault'
-  ): ColumnDef<T> =>
-    ({
-      ...def,
-      autoIncrement: true,
-      generated: strategy
-    }),
-
-  /**
-   * Adds a foreign key reference
-   */
-  references: <T extends ColumnType>(def: ColumnDef<T>, ref: ForeignKeyReference): ColumnDef<T> =>
-    ({
-      ...def,
-      references: ref
-    }),
-
-  /**
-   * Adds a check constraint to the column
-   */
-  check: <T extends ColumnType>(def: ColumnDef<T>, expression: string): ColumnDef<T> =>
-    ({
-      ...def,
-      check: expression
-    })
-};
+  timestamp: <TRuntime = string>(): ColumnDef<'TIMESTAMP', TRuntime> => ({ name: '', type: 'TIMESTAMP' }),
+
+  /**
+   * Creates a timestamptz column definition
+   */
+  timestamptz: <TRuntime = string>(): ColumnDef<'TIMESTAMPTZ', TRuntime> => ({ name: '', type: 'TIMESTAMPTZ' }),
+
+  /**
+   * Creates a date column definition
+   */
+  date: <TRuntime = string>(): ColumnDef<'DATE', TRuntime> => ({ name: '', type: 'DATE' }),
+
+  /**
+   * Creates a datetime column definition
+   */
+  datetime: <TRuntime = string>(): ColumnDef<'DATETIME', TRuntime> => ({ name: '', type: 'DATETIME' }),
+
+  /**
+   * Creates a JSON column definition
+   * @returns ColumnDef with JSON type
+   */
+  json: (): ColumnDef<'JSON'> => ({ name: '', type: 'JSON' }),
+
+  /**
+   * Creates a boolean column definition
+   * @returns ColumnDef with BOOLEAN type
+   */
+  boolean: (): ColumnDef<'BOOLEAN'> => ({ name: '', type: 'BOOLEAN' }),
+
+  /**
+   * Creates an enum column definition
+   * @param values - Enum values
+   */
+  enum: (values: string[]): ColumnDef<'ENUM'> => ({ name: '', type: 'ENUM', args: values }),
+
+  /**
+   * Marks a column definition as a primary key
+   * @param def - Column definition to modify
+   * @returns Modified ColumnDef with primary: true
+   */
+  primaryKey: <T extends ColumnType>(def: ColumnDef<T>): ColumnDef<T> =>
+    ({ ...def, primary: true }),
+
+  /**
+   * Marks a column as NOT NULL
+   */
+  notNull: <T extends ColumnType>(def: ColumnDef<T>): ColumnDef<T> =>
+    ({ ...def, notNull: true }),
+
+  /**
+   * Marks a column as UNIQUE
+   */
+  unique: <T extends ColumnType>(def: ColumnDef<T>, name?: string): ColumnDef<T> =>
+    ({
+      ...def,
+      unique: name ?? true
+    }),
+
+  /**
+   * Sets a default value for the column
+   */
+  default: <T extends ColumnType>(def: ColumnDef<T>, value: unknown): ColumnDef<T> =>
+    ({
+      ...def,
+      default: value
+    }),
+
+  /**
+   * Sets a raw SQL default value for the column
+   */
+  defaultRaw: <T extends ColumnType>(def: ColumnDef<T>, expression: string): ColumnDef<T> =>
+    ({
+      ...def,
+      default: { raw: expression }
+    }),
+
+  /**
+   * Marks a column as auto-increment / identity
+   */
+  autoIncrement: <T extends ColumnType>(
+    def: ColumnDef<T>,
+    strategy: ColumnDef['generated'] = 'byDefault'
+  ): ColumnDef<T> =>
+    ({
+      ...def,
+      autoIncrement: true,
+      generated: strategy
+    }),
+
+  /**
+   * Adds a foreign key reference
+   */
+  references: <T extends ColumnType>(def: ColumnDef<T>, ref: ForeignKeyReference): ColumnDef<T> =>
+    ({
+      ...def,
+      references: ref
+    }),
+
+  /**
+   * Adds a check constraint to the column
+   */
+  check: <T extends ColumnType>(def: ColumnDef<T>, expression: string): ColumnDef<T> =>
+    ({
+      ...def,
+      check: expression
+    })
+};

package/src/schema/types.ts

@@ -22,14 +22,16 @@ export type RelationTargetTable<TRel extends RelationDef> =
  * Maps a ColumnDef to its TypeScript type representation
  */
 export type ColumnToTs<T extends ColumnDef> =
-  T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number :
-  T['type'] extends 'BIGINT' | 'bigint' ? number | bigint :
-  T['type'] extends 'DECIMAL' | 'decimal' | 'FLOAT' | 'float' | 'DOUBLE' | 'double' ? number :
-  T['type'] extends 'BOOLEAN' | 'boolean' ? boolean :
-  T['type'] extends 'JSON' | 'json' ? unknown :
-  T['type'] extends 'BLOB' | 'blob' | 'BINARY' | 'binary' | 'VARBINARY' | 'varbinary' | 'BYTEA' | 'bytea' ? Buffer :
-  T['type'] extends 'DATE' | 'date' | 'DATETIME' | 'datetime' | 'TIMESTAMP' | 'timestamp' | 'TIMESTAMPTZ' | 'timestamptz' ? string :
-  string;
+  [unknown] extends [T['tsType']]
+    ? T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number :
+      T['type'] extends 'BIGINT' | 'bigint' ? number | bigint :
+      T['type'] extends 'DECIMAL' | 'decimal' | 'FLOAT' | 'float' | 'DOUBLE' | 'double' ? number :
+      T['type'] extends 'BOOLEAN' | 'boolean' ? boolean :
+      T['type'] extends 'JSON' | 'json' ? unknown :
+      T['type'] extends 'BLOB' | 'blob' | 'BINARY' | 'binary' | 'VARBINARY' | 'varbinary' | 'BYTEA' | 'bytea' ? Buffer :
+      T['type'] extends 'DATE' | 'date' | 'DATETIME' | 'datetime' | 'TIMESTAMP' | 'timestamp' | 'TIMESTAMPTZ' | 'timestamptz' ? string :
+      string
+    : Exclude<T['tsType'], undefined>;
 
 /**
  * Infers a row shape from a table definition