@tstdl/base 0.92.123 → 0.92.125

package/orm/server/transaction.d.ts

@@ -1,7 +1,8 @@
+import type { PgTransaction as DrizzlePgTransaction, PgQueryResultHKT, PgTransactionConfig } from 'drizzle-orm/pg-core';
 import { DeferredPromise } from '../../promise/deferred-promise.js';
-import type { PgTransaction as DrizzlePgTransaction, PgTransactionConfig } from 'drizzle-orm/pg-core';
+import type { Record } from '../../types.js';
 import type { Database } from './database.js';
-type PgTransaction = DrizzlePgTransaction<any, any, any>;
+export type PgTransaction = DrizzlePgTransaction<PgQueryResultHKT, Record, Record>;
 export type TransactionConfig = PgTransactionConfig;
 export declare abstract class Transaction {
     #private;
@@ -18,12 +19,11 @@ export declare abstract class Transaction {
     protected abstract _rollback(): void;
 }
 export declare class DrizzleTransaction extends Transaction {
-    readonly transaction: PgTransaction;
+    readonly pgTransaction: PgTransaction;
     readonly deferPromise: DeferredPromise<void>;
     readonly pgTransactionPromise: Promise<void>;
-    constructor(transaction: PgTransaction, pgTransactionPromise: Promise<void>);
+    constructor(pgTransaction: PgTransaction, pgTransactionPromise: Promise<void>);
     static create(session: Database | PgTransaction, config?: TransactionConfig): Promise<DrizzleTransaction>;
     protected _commit(): Promise<void>;
     protected _rollback(): void;
 }
-export {};

package/orm/server/transaction.js

@@ -1,5 +1,5 @@
-import { DeferredPromise } from '../../promise/deferred-promise.js';
 import { Subject } from 'rxjs';
+import { DeferredPromise } from '../../promise/deferred-promise.js';
 export class Transaction {
     #afterCommitSubject = new Subject();
     #useCounter = 0;
@@ -36,12 +36,12 @@ export class Transaction {
     }
 }
 export class DrizzleTransaction extends Transaction {
-    transaction;
+    pgTransaction;
     deferPromise = new DeferredPromise();
     pgTransactionPromise;
-    constructor(transaction, pgTransactionPromise) {
+    constructor(pgTransaction, pgTransactionPromise) {
         super();
-        this.transaction = transaction;
+        this.pgTransaction = pgTransaction;
         this.pgTransactionPromise = pgTransactionPromise;
     }
     static async create(session, config) {
@@ -64,7 +64,7 @@ export class DrizzleTransaction extends Transaction {
     }
     _rollback() {
         try {
-            this.transaction.rollback();
+            this.pgTransaction.rollback();
         }
         catch (error) {
             this.deferPromise.reject(error);

package/orm/server/transactional.d.ts

@@ -0,0 +1,75 @@
+import { Database } from './database.js';
+import { type PgTransaction, type Transaction, type TransactionConfig } from './transaction.js';
+export type TransactionInitOptions = TransactionConfig & {
+    /**
+     * Indicates that an existing transaction should be used if available instead of creating a new one.
+     * @default true
+     */
+    useExisting?: boolean;
+};
+export type TransactionHandler<R> = (transaction: Transaction) => Promise<R>;
+type TransactionalContext<ContextData = unknown> = {
+    session: Database | PgTransaction;
+    cache: WeakMap<Database | PgTransaction, any>;
+    data: ContextData;
+};
+declare const getCurrentTransactionalContext: {
+    (required: true, debugFn: import("../../types.js").Function): TransactionalContext<unknown>;
+    (required?: false, debugFn?: import("../../types.js").Function): TransactionalContext<unknown> | null;
+    (required: boolean, debugFn: import("../../types.js").Function): TransactionalContext<unknown> | null;
+}, runInTransactionalContext: <ReturnT>(context: TransactionalContext<unknown>, fn: () => ReturnT) => ReturnT, isInTransactionalContext: () => boolean;
+export { getCurrentTransactionalContext, isInTransactionalContext, runInTransactionalContext };
+export declare abstract class Transactional<ContextData = unknown> {
+    #private;
+    readonly session: PgTransaction | Database;
+    readonly isInTransaction: boolean;
+    constructor();
+    /**
+     * Starts a new database transaction.
+     * @param config Optional transaction configuration.
+     * @returns A promise that resolves to the new Transaction instance.
+     */
+    startTransaction(config?: TransactionInitOptions): Promise<Transaction>;
+    /**
+     * Returns a new instance of the repository bound to the provided session.
+     * Useful for performing multiple operations within a single database session.
+     * @param session The session to bind to.
+     * @returns A new repository instance bound to the session.
+     */
+    withSession(session: Database | PgTransaction): this;
+    /**
+       * Returns a new instance of the repository bound to the provided transaction, if a transaction is provided.
+       * Otherwise, returns the current instance.
+       * @param transaction The transaction to bind to (optional).
+       * @returns A repository instance bound to the transaction or the current instance.
+       */
+    withOptionalTransaction(transaction: Transaction | undefined): this;
+    /**
+     * Returns a new instance of the repository bound to the provided transaction.
+     * Useful for performing multiple operations within a single database transaction.
+     * @param transaction The transaction to bind to.
+     * @returns A new repository instance bound to the transaction.
+     */
+    withTransaction(transaction: Transaction): this;
+    /**
+     * Executes a handler function within the provided transaction. If no transaction is provided,
+     * it starts a new transaction, executes the handler, and commits or rolls back based on the outcome.
+     * @template R The return type of the handler.
+     * @param existingTransaction The transaction to use (optional). Creates a new one otherwise.
+     * @param handler The function to execute within the transaction.
+     * @returns A promise that resolves to the result of the handler function.
+     */
+    useTransaction<R>(existingTransaction: Transaction | undefined, handler: TransactionHandler<R>): Promise<R>;
+    /**
+     * Starts a new transaction, executes the provided handler function within it,
+     * and automatically commits the transaction if the handler succeeds or rolls it back if it throws an error.
+     * @template R The return type of the handler.
+     * @param handler The function to execute within the transaction.
+     * @param config Optional transaction configuration.
+     * @returns A promise that resolves to the result of the handler function.
+     */
+    transaction<R>(handler: TransactionHandler<R>, config?: TransactionInitOptions): Promise<R>;
+    protected getTransactionalContextData(): ContextData;
+}
+export declare function tryGetTransactionalContextData<T>(_instance?: Transactional<T>): T | undefined;
+export declare function getTransactionalContextData<T>(_instance?: Transactional<T>): T;

package/orm/server/transactional.js

@@ -0,0 +1,134 @@
+import { PgTransaction as DrizzlePgTransaction } from 'drizzle-orm/pg-core';
+import { createContextProvider } from '../../context/context.js';
+import { Injector } from '../../injector/index.js';
+import { inject, runInInjectionContext } from '../../injector/inject.js';
+import { isDefined, isUndefined } from '../../utils/type-guards.js';
+import { Database } from './database.js';
+import { DrizzleTransaction } from './transaction.js';
+const transactionCache = new WeakMap();
+const { getCurrentTransactionalContext, runInTransactionalContext, isInTransactionalContext } = createContextProvider('Transactional');
+export { getCurrentTransactionalContext, isInTransactionalContext, runInTransactionalContext };
+function transactionalContextDataGuardFunction() {
+    throw new Error('function getTransactionalContextData must be implemented to use transactional context data.');
+}
+const transactionalContextDataGuard = new Proxy({}, {
+    apply: transactionalContextDataGuardFunction,
+    construct: transactionalContextDataGuardFunction,
+    defineProperty: transactionalContextDataGuardFunction,
+    deleteProperty: transactionalContextDataGuardFunction,
+    get: transactionalContextDataGuardFunction,
+    getOwnPropertyDescriptor: transactionalContextDataGuardFunction,
+    getPrototypeOf: transactionalContextDataGuardFunction,
+    has: transactionalContextDataGuardFunction,
+    isExtensible: transactionalContextDataGuardFunction,
+    ownKeys: transactionalContextDataGuardFunction,
+    preventExtensions: transactionalContextDataGuardFunction,
+    set: transactionalContextDataGuardFunction,
+    setPrototypeOf: transactionalContextDataGuardFunction,
+});
+export class Transactional {
+    #injector = inject(Injector);
+    #classConstructor;
+    #instanceCache = getCurrentTransactionalContext()?.cache ?? new WeakMap();
+    #context = getCurrentTransactionalContext() ?? {};
+    session = this.#context.session ?? inject(Database);
+    isInTransaction = this.session instanceof DrizzlePgTransaction;
+    constructor() {
+        this.#classConstructor = new.target;
+    }
+    /**
+     * Starts a new database transaction.
+     * @param config Optional transaction configuration.
+     * @returns A promise that resolves to the new Transaction instance.
+     */
+    async startTransaction(config) {
+        if ((config?.useExisting != false) && this.isInTransaction) {
+            const existing = transactionCache.get(this.session);
+            if (isDefined(existing)) {
+                return existing;
+            }
+        }
+        const transaction = await DrizzleTransaction.create(this.session, config);
+        transactionCache.set(transaction.pgTransaction, transaction);
+        return transaction;
+    }
+    /**
+     * Returns a new instance of the repository bound to the provided session.
+     * Useful for performing multiple operations within a single database session.
+     * @param session The session to bind to.
+     * @returns A new repository instance bound to the session.
+     */
+    withSession(session) {
+        if (this.#instanceCache.has(session)) {
+            return this.#instanceCache.get(session);
+        }
+        if (session == this.session) {
+            this.#instanceCache.set(session, this);
+            return this;
+        }
+        const context = {
+            session: session,
+            cache: this.#instanceCache,
+            data: this.getTransactionalContextData(),
+        };
+        const repositoryWithSession = runInInjectionContext(this.#injector, () => runInTransactionalContext(context, () => new this.#classConstructor()));
+        this.#instanceCache.set(session, repositoryWithSession);
+        return repositoryWithSession;
+    }
+    /**
+       * Returns a new instance of the repository bound to the provided transaction, if a transaction is provided.
+       * Otherwise, returns the current instance.
+       * @param transaction The transaction to bind to (optional).
+       * @returns A repository instance bound to the transaction or the current instance.
+       */
+    withOptionalTransaction(transaction) {
+        if (isUndefined(transaction)) {
+            return this;
+        }
+        return this.withTransaction(transaction);
+    }
+    /**
+     * Returns a new instance of the repository bound to the provided transaction.
+     * Useful for performing multiple operations within a single database transaction.
+     * @param transaction The transaction to bind to.
+     * @returns A new repository instance bound to the transaction.
+     */
+    withTransaction(transaction) {
+        return this.withSession(transaction.pgTransaction);
+    }
+    /**
+     * Executes a handler function within the provided transaction. If no transaction is provided,
+     * it starts a new transaction, executes the handler, and commits or rolls back based on the outcome.
+     * @template R The return type of the handler.
+     * @param existingTransaction The transaction to use (optional). Creates a new one otherwise.
+     * @param handler The function to execute within the transaction.
+     * @returns A promise that resolves to the result of the handler function.
+     */
+    async useTransaction(existingTransaction, handler) {
+        if (isUndefined(existingTransaction)) {
+            return this.transaction(handler);
+        }
+        return existingTransaction.use(async () => handler(existingTransaction));
+    }
+    /**
+     * Starts a new transaction, executes the provided handler function within it,
+     * and automatically commits the transaction if the handler succeeds or rolls it back if it throws an error.
+     * @template R The return type of the handler.
+     * @param handler The function to execute within the transaction.
+     * @param config Optional transaction configuration.
+     * @returns A promise that resolves to the result of the handler function.
+     */
+    async transaction(handler, config) {
+        const transaction = await this.startTransaction(config);
+        return transaction.use(async () => handler(transaction));
+    }
+    getTransactionalContextData() {
+        return transactionalContextDataGuard; // eslint-disable-line @typescript-eslint/no-unsafe-return
+    }
+}
+export function tryGetTransactionalContextData(_instance) {
+    return getCurrentTransactionalContext()?.data;
+}
+export function getTransactionalContextData(_instance) {
+    return getCurrentTransactionalContext(true, getTransactionalContextData).data;
+}

package/orm/server/types.d.ts

@@ -20,6 +20,7 @@ export type ColumnDefinition = {
     toDatabase: (value: unknown, context: TransformContext) => any;
     fromDatabase: (value: unknown, context: TransformContext) => any;
 };
+export type ColumnDefinitionsMap = Map<string, ColumnDefinition>;
 export type TransformContext = {
     encryptionKey?: CryptoKey;
 };

package/orm/sqls.d.ts

@@ -1,16 +1,71 @@
+/**
+ * @module
+ * Provides utility SQL functions and constants for use with Drizzle ORM,
+ * simplifying common SQL operations like generating UUIDs, working with intervals,
+ * and aggregating data.
+ */
 import { type Column, type SQL } from 'drizzle-orm';
 import type { GetSelectTableSelection, SelectResultField, TableLike } from 'drizzle-orm/query-builders/select.types';
 import type { Uuid } from './types.js';
+/** Drizzle SQL helper for getting the current transaction's timestamp. Returns a Date object. */
 export declare const TRANSACTION_TIMESTAMP: SQL<Date>;
+/** Drizzle SQL helper for generating a random UUID (v4). Returns a Uuid string. */
 export declare const RANDOM_UUID: SQL<Uuid>;
+/** Represents valid units for PostgreSQL interval values. */
 export type IntervalUnit = 'millennium' | 'millenniums' | 'millennia' | 'century' | 'centuries' | 'decade' | 'decades' | 'year' | 'years' | 'day' | 'days' | 'hour' | 'hours' | 'minute' | 'minutes' | 'second' | 'seconds' | 'millisecond' | 'milliseconds' | 'microsecond' | 'microseconds';
+/**
+ * Creates a Drizzle SQL interval expression.
+ * @param value - The numeric value of the interval.
+ * @param unit - The unit of the interval (e.g., 'day', 'hour').
+ * @returns A Drizzle SQL object representing the interval.
+ */
 export declare function interval(value: number, unit: IntervalUnit): SQL;
+/**
+ * Creates a Drizzle SQL `array_agg` aggregate function call.
+ * Aggregates values from a column into a PostgreSQL array.
+ * @template T - The Drizzle column type.
+ * @param column - The column to aggregate.
+ * @returns A Drizzle SQL object representing the aggregated array.
+ */
 export declare function arrayAgg<T extends Column>(column: T): SQL<SelectResultField<T>[]>;
+/**
+ * Creates a Drizzle SQL `json_agg` aggregate function call.
+ * Aggregates rows or column values into a JSON array.
+ * @template T - The Drizzle table or column type.
+ * @param tableOrColumn - The table or column to aggregate into JSON.
+ * @returns A Drizzle SQL object representing the JSON aggregated array.
+ */
 export declare function jsonAgg<T extends TableLike>(tableOrColumn: T): SQL<SelectResultField<GetSelectTableSelection<T>>[]>;
 export declare namespace jsonAgg {
     var withNull: <T extends TableLike>(tableOrColumn: T) => SQL<(SelectResultField<GetSelectTableSelection<T>> | null)[]>;
 }
+/**
+ * Creates a Drizzle SQL `coalesce` function call.
+ * Returns the first non-null value from the provided list of columns or SQL expressions.
+ * @template T - An array type of Drizzle Columns or SQL expressions.
+ * @param columns - The columns or SQL expressions to check.
+ * @returns A Drizzle SQL object representing the coalesced value.
+ */
 export declare function coalesce<T extends (Column | SQL)[]>(...columns: T): SQL<SelectResultField<T>[number]>;
+/**
+ * Creates a Drizzle SQL `to_jsonb` function call.
+ * Converts the input column or SQL expression to a JSONB value.
+ * @template T - The Drizzle column or SQL expression type.
+ * @param column - The column or SQL expression to convert.
+ * @returns A Drizzle SQL object representing the value as JSONB.
+ */
 export declare function toJsonb<T extends (Column | SQL)>(column: T): SQL<SelectResultField<T>>;
+/**
+ * Creates a Drizzle SQL `num_nulls` function call.
+ * Counts the number of null arguments.
+ * @param columns - The columns to check for nulls.
+ * @returns A Drizzle SQL object representing the count of nulls.
+ */
 export declare function numNulls(...columns: Column[]): SQL<number>;
+/**
+ * Creates a Drizzle SQL `num_nonnulls` function call.
+ * Counts the number of non-null arguments.
+ * @param columns - The columns to check for non-nulls.
+ * @returns A Drizzle SQL object representing the count of non-nulls.
+ */
 export declare function numNonNulls(...columns: Column[]): SQL<number>;

package/orm/sqls.js

@@ -1,25 +1,85 @@
+/**
+ * @module
+ * Provides utility SQL functions and constants for use with Drizzle ORM,
+ * simplifying common SQL operations like generating UUIDs, working with intervals,
+ * and aggregating data.
+ */
 import { sql } from 'drizzle-orm';
+/** Drizzle SQL helper for getting the current transaction's timestamp. Returns a Date object. */
 export const TRANSACTION_TIMESTAMP = sql `transaction_timestamp()`;
+/** Drizzle SQL helper for generating a random UUID (v4). Returns a Uuid string. */
 export const RANDOM_UUID = sql `gen_random_uuid()`;
+/**
+ * Creates a Drizzle SQL interval expression.
+ * @param value - The numeric value of the interval.
+ * @param unit - The unit of the interval (e.g., 'day', 'hour').
+ * @returns A Drizzle SQL object representing the interval.
+ */
 export function interval(value, unit) {
     return sql `(${value} ||' ${sql.raw(unit)}')::interval`;
 }
+/**
+ * Creates a Drizzle SQL `array_agg` aggregate function call.
+ * Aggregates values from a column into a PostgreSQL array.
+ * @template T - The Drizzle column type.
+ * @param column - The column to aggregate.
+ * @returns A Drizzle SQL object representing the aggregated array.
+ */
 export function arrayAgg(column) {
     return sql `array_agg(${column})`;
 }
+/**
+ * Creates a Drizzle SQL `json_agg` aggregate function call.
+ * Aggregates rows or column values into a JSON array.
+ * @template T - The Drizzle table or column type.
+ * @param tableOrColumn - The table or column to aggregate into JSON.
+ * @returns A Drizzle SQL object representing the JSON aggregated array.
+ */
 export function jsonAgg(tableOrColumn) {
     return sql `json_agg(${tableOrColumn})`;
 }
+/**
+ * Variant of `jsonAgg` that includes null values in the resulting JSON array.
+ * @template T - The Drizzle table or column type.
+ * @param tableOrColumn - The table or column to aggregate into JSON.
+ * @returns A Drizzle SQL object representing the JSON aggregated array, potentially containing nulls.
+ */
 jsonAgg.withNull = jsonAgg;
+/**
+ * Creates a Drizzle SQL `coalesce` function call.
+ * Returns the first non-null value from the provided list of columns or SQL expressions.
+ * @template T - An array type of Drizzle Columns or SQL expressions.
+ * @param columns - The columns or SQL expressions to check.
+ * @returns A Drizzle SQL object representing the coalesced value.
+ */
 export function coalesce(...columns) {
     return sql `coalesce(${sql.join(columns, sql.raw(', '))})`;
 }
+/**
+ * Creates a Drizzle SQL `to_jsonb` function call.
+ * Converts the input column or SQL expression to a JSONB value.
+ * @template T - The Drizzle column or SQL expression type.
+ * @param column - The column or SQL expression to convert.
+ * @returns A Drizzle SQL object representing the value as JSONB.
+ */
 export function toJsonb(column) {
     return sql `to_jsonb(${column})`;
 }
+/**
+ * Creates a Drizzle SQL `num_nulls` function call.
+ * Counts the number of null arguments.
+ * @param columns - The columns to check for nulls.
+ * @returns A Drizzle SQL object representing the count of nulls.
+ */
 export function numNulls(...columns) {
     return sql `num_nulls(${sql.join(columns, sql.raw(', '))})`;
 }
+/**
+ * Creates a Drizzle SQL `num_nonnulls` function call.
+ * Counts the number of non-null arguments.
+ * @param columns - The columns to check for non-nulls.
+ * @returns A Drizzle SQL object representing the count of non-nulls.
+ */
 export function numNonNulls(...columns) {
     return sql `num_nonnulls(${sql.join(columns, sql.raw(', '))})`;
 }

package/orm/types.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @module
+ * Defines core ORM types, including tagged types for representing database column types
+ * (like Uuid, Timestamp, Json, etc.) and helper types for working with Drizzle ORM features
+ * like primary keys and default values. It also re-exports common decorators and schemas.
+ */
 import type { $Type, HasDefault as DrizzleHasDefault, IsPrimaryKey as DrizzleIsPrimaryKey } from 'drizzle-orm';
 import type { boolean, doublePrecision, integer, jsonb, PgColumnBuilder, PgColumnBuilderBase, PgEnumColumnBuilderInitial, text, uuid } from 'drizzle-orm/pg-core';
 import { Array, Integer } from '../schema/index.js';
@@ -6,25 +12,82 @@ import type { GetTagMetadata, HasTag, Tagged, UnwrapTagged } from '../types/inde
 import type { bytea, numericDate, timestamp } from './data-types/index.js';
 import { Check, Column, Embedded, Encrypted, Index, PrimaryKey, References, Table, Unique } from './decorators.js';
 import { Json, NumericDate, Timestamp, Uuid } from './schemas/index.js';
+/** Tag identifier for column type information. */
 export type ColumnTypeTag = 'column';
+/** Tag identifier for embedded type configuration. */
 export type EmbeddedConfigTag = 'embedded';
+/**
+ * Helper type to tag a column type as being a primary key.
+ * It wraps the original type `T` and associates Drizzle's `IsPrimaryKey` marker
+ * with the underlying Drizzle column builder type stored in the tag metadata.
+ * @template T - The original column type (e.g., Uuid, Integer).
+ */
 export type IsPrimaryKey<T> = T extends Tagged<unknown, ColumnTypeTag, PgColumnBuilderBase> ? Tagged<UnwrapTagged<T>, ColumnTypeTag, DrizzleIsPrimaryKey<GetTagMetadata<T, ColumnTypeTag>>> : Tagged<T, ColumnTypeTag, DrizzleIsPrimaryKey<ColumnBuilder<T>>>;
+/**
+ * Helper type to tag a column type as having a default value.
+ * It wraps the original type `T` and associates Drizzle's `HasDefault` marker
+ * with the underlying Drizzle column builder type stored in the tag metadata.
+ * @template T - The original column type (e.g., Uuid, Timestamp).
+ */
 export type HasDefault<T> = T extends Tagged<unknown, ColumnTypeTag, PgColumnBuilderBase> ? Tagged<UnwrapTagged<T>, ColumnTypeTag, DrizzleHasDefault<GetTagMetadata<T, ColumnTypeTag>>> : Tagged<T, ColumnTypeTag, DrizzleHasDefault<ColumnBuilder<T>>>;
-type EnumColumn<T extends EnumerationObject, ColumnName extends string = ''> = PgEnumColumnBuilderInitial<ColumnName, UnionToTuple<`${EnumerationValue<T>}`> extends [string, ...string[]] ? UnionToTuple<`${EnumerationValue<T>}`> : ['NO_VALUES_PROVIDED']>;
-export type ColumnBuilder<T, ColumnName extends string = never> = HasTag<T> extends true ? T extends Tagged<T, ColumnTypeTag, any> ? GetTagMetadata<T, ColumnTypeTag> : never : T extends string ? string extends ColumnName ? ReturnType<typeof text<ColumnName, string, [string, ...string[]]>> : ReturnType<typeof text<string, [string, ...string[]]>> : T extends number ? string extends ColumnName ? ReturnType<typeof doublePrecision<ColumnName>> : ReturnType<typeof doublePrecision> : T extends boolean ? string extends ColumnName ? ReturnType<typeof boolean<ColumnName>> : ReturnType<typeof boolean> : T extends Uint8Array ? string extends ColumnName ? ReturnType<typeof bytea<ColumnName>> : ReturnType<typeof bytea> : T extends EnumerationObject ? string extends ColumnName ? EnumColumn<T, ColumnName> : EnumColumn<T> : T extends (infer U)[] ? string extends ColumnName ? ReturnType<ColumnBuilder<U, ColumnName>['array']> : ReturnType<ColumnBuilder<U>['array']> : never;
+type EnumColumn<T extends string | number, ColumnName extends string = ''> = PgEnumColumnBuilderInitial<ColumnName, UnionToTuple<`${T}`> extends [string, ...string[]] ? UnionToTuple<`${T}`> : ['NO_VALUES_PROVIDED']>;
+type TextTuple<T extends string> = UnionToTuple<`${T}`> extends [string, ...string[]] ? UnionToTuple<`${T}`> : [string];
+type HandledColumnName<T extends string = never> = [T] extends [never] ? '' : T;
+/**
+ * Utility type to infer the Drizzle column builder type based on a TypeScript type `T`.
+ * Handles primitive types (string, number, boolean), arrays, enums, Uint8Array,
+ * and existing tagged column types.
+ * @template T - The TypeScript type to map to a column builder.
+ * @template ColumnName - Optional column name for context.
+ */
+export type ColumnBuilder<T, ColumnName extends string = never> = HasTag<T> extends true ? T extends Tagged<unknown, ColumnTypeTag, any> ? GetTagMetadata<T, ColumnTypeTag> : never : T extends string ? ReturnType<typeof text<HandledColumnName<ColumnName>, string, TextTuple<T>>> : T extends number ? ReturnType<typeof doublePrecision<HandledColumnName<ColumnName>>> : T extends boolean ? ReturnType<typeof boolean<HandledColumnName<ColumnName>>> : T extends Uint8Array ? ReturnType<typeof bytea<HandledColumnName<ColumnName>>> : T extends EnumerationObject ? EnumColumn<EnumerationValue<T>, HandledColumnName<ColumnName>> : T extends (infer U)[] ? ReturnType<ColumnBuilder<U, HandledColumnName<ColumnName>>['array']> : never;
+/**
+ * Tagged type representing an embedded class configuration.
+ * Stores the embedded type `T` and an optional column name prefix `P`.
+ * @template T - The constructor of the class being embedded.
+ * @template P - An optional prefix for the column names generated from the embedded class properties.
+ */
 export type Embedded<T = AbstractConstructor, P extends string = ''> = Tagged<T, EmbeddedConfigTag, {
     prefix: P;
 }>;
+/**
+ * Tagged type representing a PostgreSQL array column.
+ * Wraps an existing tagged column type `T` and derives the Drizzle array column builder.
+ * @template T - The tagged type of the array elements.
+ */
 export type Array<T extends Tagged<ObjectLiteral, ColumnTypeTag, PgColumnBuilder<any>>> = Tagged<UnwrapTagged<T>[], ColumnTypeTag, ReturnType<GetTagMetadata<T, ColumnTypeTag>['array']>>;
+/**
+ * Tagged type representing a JSONB column.
+ * Stores the TypeScript type `T` that the JSONB data represents.
+ * @template T - The TypeScript type of the data stored in the JSONB column.
+ */
 export type Json<T> = Tagged<T, ColumnTypeTag, $Type<ReturnType<typeof jsonb>, T>>;
-export type Enum<T extends EnumerationObject> = Tagged<EnumerationValue<T>, ColumnTypeTag, EnumColumn<T>>;
-export type Text = Tagged<string, ColumnTypeTag, ReturnType<typeof text<string, [string, ...string[]]>>>;
+/**
+ * Tagged type representing a PostgreSQL enum column.
+ * Derives the enum values and the Drizzle enum column builder from the provided enum object `T`.
+ * @template T - The enumeration object type.
+ */
+export type Enum<T extends string | number> = Tagged<T, ColumnTypeTag, EnumColumn<T>>;
+/** Tagged type representing a `text` column. */
+export type Text<T extends string = string> = Tagged<string, ColumnTypeTag, ReturnType<typeof text<string, TextTuple<T>>>>;
+/** Tagged type representing a `uuid` column. Stores the UUID as a string. */
 export type Uuid = Tagged<string, ColumnTypeTag, ReturnType<typeof uuid>>;
+/** Tagged type representing an `integer` column. */
 export type Integer = Tagged<number, ColumnTypeTag, ReturnType<typeof integer>>;
+/** Tagged type representing a `double precision` column. */
 export type DoublePrecision = Tagged<number, ColumnTypeTag, ReturnType<typeof doublePrecision>>;
+/** Tagged type representing a `boolean` column. */
 export type Boolean = Tagged<number, ColumnTypeTag, ReturnType<typeof boolean>>;
+/** Tagged type representing a custom `numericDate` column (stores date as number YYYYMMDD). */
 export type NumericDate = Tagged<number, ColumnTypeTag, ReturnType<typeof numericDate>>;
+/** Tagged type representing a `timestamp` column (stores timestamp as number - milliseconds since epoch). */
 export type Timestamp = Tagged<number, ColumnTypeTag, ReturnType<typeof timestamp>>;
+/** Tagged type representing a `bytea` (byte array) column. */
 export type Bytea = Tagged<Uint8Array, ColumnTypeTag, ReturnType<typeof bytea>>;
+/**
+ * Tagged type representing an encrypted column.
+ * Stores the original TypeScript type `T`, but the underlying database type is `bytea`.
+ * @template T - The original (unencrypted) type of the data.
+ */
 export type Encrypted<T> = Tagged<T, ColumnTypeTag, ReturnType<typeof bytea>>;
 export { Array, Check, Column, Embedded, Encrypted, Index, Integer, Json, NumericDate, PrimaryKey, References, Table, Timestamp, Unique, Uuid };

package/orm/utils.d.ts

@@ -1,3 +1,19 @@
-import type { Entity } from './entity.js';
-export declare function getEntityMap<T extends Entity>(entities: T[]): Map<string, T>;
-export declare function getEntityIds<T extends Entity>(entities: T[]): string[];
+/**
+ * @module
+ * Provides utility functions for working with ORM entities.
+ */
+import type { Entity, EntityWithoutMetadata } from './entity.js';
+/**
+ * Converts an array of entities into a Map keyed by entity ID.
+ * @template T - The entity type, must extend `Entity` (i.e., have an `id` property).
+ * @param entities - An array of entities.
+ * @returns A Map where keys are entity IDs and values are the corresponding entities.
+ */
+export declare function getEntityMap<T extends Entity | EntityWithoutMetadata>(entities: T[]): Map<string, T>;
+/**
+ * Extracts the IDs from an array of entities.
+ * @template T - The entity type, must extend `Entity` (i.e., have an `id` property).
+ * @param entities - An array of entities.
+ * @returns An array containing the IDs of the entities.
+ */
+export declare function getEntityIds(entities: (Entity | EntityWithoutMetadata)[]): string[];

package/orm/utils.js

@@ -1,6 +1,18 @@
+/**
+ * Converts an array of entities into a Map keyed by entity ID.
+ * @template T - The entity type, must extend `Entity` (i.e., have an `id` property).
+ * @param entities - An array of entities.
+ * @returns A Map where keys are entity IDs and values are the corresponding entities.
+ */
 export function getEntityMap(entities) {
     return new Map(entities.map((entity) => [entity.id, entity]));
 }
+/**
+ * Extracts the IDs from an array of entities.
+ * @template T - The entity type, must extend `Entity` (i.e., have an `id` property).
+ * @param entities - An array of entities.
+ * @returns An array containing the IDs of the entities.
+ */
 export function getEntityIds(entities) {
     return entities.map((entity) => entity.id);
 }