metal-orm 1.0.33 → 1.0.35

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,45 +22,47 @@ 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;
-
-/**
- * Infers a row shape from a table definition
- */
-export type InferRow<TTable extends TableDef> = {
-  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
-};
-
+  T['tsType'] extends undefined
+    ? 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
+ */
+export type InferRow<TTable extends TableDef> = {
+  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
+};
+
 type RelationResult<T extends RelationDef> =
   T extends HasManyRelation<infer TTarget>        ? InferRow<TTarget>[] :
   T extends HasOneRelation<infer TTarget>         ? InferRow<TTarget> | null :
   T extends BelongsToRelation<infer TTarget>      ? InferRow<TTarget> | null :
   T extends BelongsToManyRelation<infer TTarget>  ? (InferRow<TTarget> & { _pivot?: any })[] :
   never;
-
-/**
- * Maps relation names to the expected row results
- */
-export type RelationMap<TTable extends TableDef> = {
-  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
-};
-
-export interface HasManyCollection<TChild> {
-  load(): Promise<TChild[]>;
-  getItems(): TChild[];
-  add(data: Partial<TChild>): TChild;
-  attach(entity: TChild): void;
-  remove(entity: TChild): void;
-  clear(): void;
-}
-
+
+/**
+ * Maps relation names to the expected row results
+ */
+export type RelationMap<TTable extends TableDef> = {
+  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
+};
+
+export interface HasManyCollection<TChild> {
+  load(): Promise<TChild[]>;
+  getItems(): TChild[];
+  add(data: Partial<TChild>): TChild;
+  attach(entity: TChild): void;
+  remove(entity: TChild): void;
+  clear(): void;
+}
+
 export interface BelongsToReference<TParent> {
   load(): Promise<TParent | null>;
   get(): TParent | null;
@@ -72,28 +74,28 @@ export interface HasOneReference<TChild> {
   get(): TChild | null;
   set(data: Partial<TChild> | TChild | null): TChild | null;
 }
-
-export interface ManyToManyCollection<TTarget> {
-  load(): Promise<TTarget[]>;
-  getItems(): TTarget[];
-  attach(target: TTarget | number | string): void;
-  detach(target: TTarget | number | string): void;
-  syncByIds(ids: (number | string)[]): Promise<void>;
-}
-
-export type Entity<
+
+export interface ManyToManyCollection<TTarget> {
+  load(): Promise<TTarget[]>;
+  getItems(): TTarget[];
+  attach(target: TTarget | number | string): void;
+  detach(target: TTarget | number | string): void;
+  syncByIds(ids: (number | string)[]): Promise<void>;
+}
+
+export type EntityInstance<
   TTable extends TableDef,
   TRow = InferRow<TTable>
 > = TRow & {
   [K in keyof RelationMap<TTable>]:
     TTable['relations'][K] extends HasManyRelation<infer TTarget>
-      ? HasManyCollection<Entity<TTarget>>
+      ? HasManyCollection<EntityInstance<TTarget>>
       : TTable['relations'][K] extends HasOneRelation<infer TTarget>
-        ? HasOneReference<Entity<TTarget>>
+        ? HasOneReference<EntityInstance<TTarget>>
         : TTable['relations'][K] extends BelongsToManyRelation<infer TTarget>
-          ? ManyToManyCollection<Entity<TTarget>>
+          ? ManyToManyCollection<EntityInstance<TTarget>>
           : TTable['relations'][K] extends BelongsToRelation<infer TTarget>
-            ? BelongsToReference<Entity<TTarget>>
+            ? BelongsToReference<EntityInstance<TTarget>>
             : never;
 } & {
   $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;