@tstdl/base 0.93.86 → 0.93.89

package/orm/server/transaction.d.ts

@@ -7,7 +7,9 @@ export type TransactionConfig = PgTransactionConfig;
 export declare abstract class Transaction implements AsyncDisposable {
     #private;
     readonly afterCommit: import("../../utils/async-hook/index.js").AsyncHook<never, never, unknown>;
+    readonly parent?: Transaction;
     manualCommit: boolean;
+    constructor(parent?: Transaction);
     [Symbol.asyncDispose](): Promise<void>;
     withManualCommit(): void;
     /**
@@ -23,8 +25,8 @@ export declare abstract class Transaction implements AsyncDisposable {
 export declare class DrizzleTransaction extends Transaction {
     #private;
     readonly pgTransaction: PgTransaction;
-    constructor(pgTransaction: PgTransaction);
-    static create(session: Database | PgTransaction, config?: TransactionConfig): Promise<DrizzleTransaction>;
+    constructor(pgTransaction: PgTransaction, parent?: Transaction);
+    static create(session: Database | PgTransaction, config?: TransactionConfig, parent?: Transaction): Promise<DrizzleTransaction>;
     protected _commit(): Promise<void>;
     protected _rollback(): Promise<void>;
     private setTransactionResultPromise;

package/orm/server/transaction.js

@@ -6,7 +6,11 @@ export class Transaction {
     #useCounter = 0;
     #done = false;
     afterCommit = asyncHook();
+    parent;
     manualCommit = false;
+    constructor(parent) {
+        this.parent = parent;
+    }
     async [Symbol.asyncDispose]() {
         if (!this.#done) {
             await this.rollback();
@@ -49,7 +53,12 @@ export class Transaction {
         }
         this.#done = true;
         await this._commit();
-        await this.afterCommit.trigger();
+        if (this.parent) {
+            this.parent.afterCommit.register(async () => await this.afterCommit.trigger());
+        }
+        else {
+            await this.afterCommit.trigger();
+        }
     }
     async rollback() {
         if (this.#done) {
@@ -63,14 +72,14 @@ export class DrizzleTransaction extends Transaction {
     #deferPromise = new DeferredPromise();
     pgTransaction;
     #pgTransactionResultPromise;
-    constructor(pgTransaction) {
-        super();
+    constructor(pgTransaction, parent) {
+        super(parent);
         this.pgTransaction = pgTransaction;
     }
-    static async create(session, config) {
+    static async create(session, config, parent) {
         const instancePromise = new DeferredPromise();
         const pgTransactionResultPromise = session.transaction(async (tx) => {
-            const transaction = new DrizzleTransaction(tx);
+            const transaction = new DrizzleTransaction(tx, parent);
             instancePromise.resolve(transaction);
             await transaction.#deferPromise;
         }, config);

package/orm/server/transactional.d.ts

@@ -1,4 +1,5 @@
 import { type InjectionToken, type ResolveArgument } from '../../injector/index.js';
+import type { Type } from '../../types/index.js';
 import { Database } from './database.js';
 import { Transaction, type PgTransaction, type TransactionConfig } from './transaction.js';
 export type TransactionInitOptions = TransactionConfig & {
@@ -11,7 +12,7 @@ export type TransactionInitOptions = TransactionConfig & {
 export type TransactionHandler<R> = (transaction: Transaction) => Promise<R>;
 type TransactionalContext<ContextData = unknown> = {
     session: Database | PgTransaction;
-    cache: WeakMap<Database | PgTransaction, any>;
+    instances: WeakMap<Type, WeakMap<Database | PgTransaction, any>>;
     data: ContextData;
 };
 declare const getCurrentTransactionalContext: {
@@ -22,7 +23,7 @@ declare const getCurrentTransactionalContext: {
 export { getCurrentTransactionalContext, isInTransactionalContext, runInTransactionalContext };
 export declare abstract class Transactional<ContextData = unknown> {
     #private;
-    readonly session: PgTransaction | Database;
+    readonly session: Database | PgTransaction;
     readonly isInTransaction: boolean;
     constructor();
     /**
@@ -64,6 +65,9 @@ export declare abstract class Transactional<ContextData = unknown> {
     /**
      * 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.
+     *
+     * If called within an existing transaction, it reuses the existing transaction unless specified otherwise in the config.
+     *
      * @template R The return type of the handler.
      * @param handler The function to execute within the transaction.
      * @param config Optional transaction configuration.

package/orm/server/transactional.js

@@ -30,7 +30,15 @@ export class Transactional {
     #injector = inject(Injector);
     #classConstructor;
     #context = getCurrentTransactionalContext() ?? {};
-    #instanceCache = this.#context.cache ?? new WeakMap();
+    #instances = this.#context.instances ?? new WeakMap();
+    get #instanceCache() {
+        let cache = this.#instances.get(this.#classConstructor);
+        if (isUndefined(cache)) {
+            cache = new WeakMap();
+            this.#instances.set(this.#classConstructor, cache);
+        }
+        return cache;
+    }
     session = this.#context.session ?? inject(Database);
     isInTransaction = this.session instanceof DrizzlePgTransaction;
     constructor() {
@@ -42,13 +50,14 @@ export class Transactional {
      * @returns A promise that resolves to the new Transaction instance.
      */
     async startTransaction(config) {
-        if ((config?.useExisting != false) && this.isInTransaction) {
+        if ((config?.useExisting == true) && this.isInTransaction) {
             const existing = transactionCache.get(this.session);
             if (isDefined(existing)) {
                 return existing;
             }
         }
-        const transaction = await DrizzleTransaction.create(this.session, config);
+        const parentTransaction = tryGetTstdlTransaction(this.session);
+        const transaction = await DrizzleTransaction.create(this.session, config, parentTransaction);
         transactionCache.set(transaction.pgTransaction, transaction);
         return transaction;
     }
@@ -68,7 +77,7 @@ export class Transactional {
         }
         const context = {
             session: session,
-            cache: this.#instanceCache,
+            instances: this.#instances,
             data: this.getTransactionalContextData(),
         };
         const repositoryWithSession = runInInjectionContext(this.#injector, () => runInTransactionalContext(context, () => new this.#classConstructor()));
@@ -108,11 +117,19 @@ export class Transactional {
         if (isUndefined(existingTransaction)) {
             return await this.transaction(handler);
         }
-        return await existingTransaction.use(async () => await handler(existingTransaction));
+        const context = {
+            session: existingTransaction.pgTransaction,
+            instances: this.#instances,
+            data: this.getTransactionalContextData(),
+        };
+        return await existingTransaction.use(async () => await runInTransactionalContext(context, async () => await 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.
+     *
+     * If called within an existing transaction, it reuses the existing transaction unless specified otherwise in the config.
+     *
      * @template R The return type of the handler.
      * @param handler The function to execute within the transaction.
      * @param config Optional transaction configuration.
@@ -120,17 +137,30 @@ export class Transactional {
      */
     async transaction(handler, config) {
         const transaction = await this.startTransaction(config);
-        return await transaction.use(async () => await handler(transaction));
+        const context = {
+            session: transaction.pgTransaction,
+            instances: this.#instances,
+            data: this.getTransactionalContextData(),
+        };
+        return await transaction.use(async () => await runInTransactionalContext(context, async () => await handler(transaction)));
     }
     getTransactionalContextData() {
-        return transactionalContextDataGuard; // eslint-disable-line @typescript-eslint/no-unsafe-return
+        return transactionalContextDataGuard;
     }
 }
 export function tryGetTransactionalContextData(_instance) {
-    return getCurrentTransactionalContext()?.data;
+    const data = getCurrentTransactionalContext()?.data;
+    if (data == transactionalContextDataGuard) {
+        return undefined;
+    }
+    return data;
 }
 export function getTransactionalContextData(_instance) {
-    return getCurrentTransactionalContext(true, getTransactionalContextData).data;
+    const data = getCurrentTransactionalContext(true, getTransactionalContextData).data;
+    if (data == transactionalContextDataGuard) {
+        throw new Error('function getTransactionalContextData must be implemented to use transactional context data.');
+    }
+    return data;
 }
 export function tryGetTstdlTransaction(transactionOrSession) {
     if (isUndefined(transactionOrSession)) {

package/orm/server/types.d.ts

@@ -14,6 +14,8 @@ export type ColumnDefinition = {
     name: string;
     objectPath: JsonPath;
     reflectionData: OrmColumnReflectionData | undefined;
+    inherited: boolean;
+    table: PgTableFromType | ExtraConfigColumnsFromType;
     buildType: (options: BuildTypeOptions) => PgColumnBuilder<any, any, any, any>;
     dereferenceObjectPath: (obj: Record) => any;
     toDatabase: (value: unknown, context: TransformContext) => any;

package/orm/sqls/case-when.d.ts

@@ -0,0 +1,25 @@
+import { type SQL, type SQLWrapper } from 'drizzle-orm';
+export declare class CaseBuilder<TReturn = never> {
+    readonly cases: SQL[];
+    caseExpression?: SQL | SQLWrapper;
+    constructor(expression?: SQL | SQLWrapper);
+    /** Adds a WHEN clause. */
+    when<TValue>(pattern: SQL | SQLWrapper | string | number | boolean | undefined, result: SQL<TValue> | TValue | SQLWrapper): CaseBuilder<TReturn | TValue>;
+    /**
+     * Adds an ELSE clause and finishes the statement.
+     * If no WHEN clauses were added, it returns the value directly.
+     */
+    else<TElse>(value: TElse | SQL | SQLWrapper): SQL<TReturn | TElse>;
+    /**
+     * Finishes the statement without an ELSE (defaults to NULL).
+     * If no WHEN clauses were added, it returns NULL directly.
+     */
+    end(): SQL<TReturn | null>;
+    private finalize;
+}
+/**
+ * Creates a "Searched Case" builder.
+ * Syntax: CASE WHEN condition THEN result ...
+ */
+export declare function caseWhen(caseExpression: SQL | SQLWrapper): CaseBuilder;
+export declare function caseWhen<TValue>(condition: SQL | SQLWrapper | string | number | boolean | undefined, value: SQL<TValue> | TValue | SQLWrapper): CaseBuilder<TValue>;

package/orm/sqls/case-when.js

@@ -0,0 +1,54 @@
+import { isDefined } from '../../utils/type-guards.js';
+import { sql } from 'drizzle-orm';
+export class CaseBuilder {
+    cases = [];
+    caseExpression;
+    constructor(expression) {
+        this.caseExpression = expression;
+    }
+    /** Adds a WHEN clause. */
+    when(pattern, result) {
+        if (isDefined(pattern)) {
+            this.cases.push(sql `WHEN ${pattern} THEN ${result}`);
+        }
+        return this;
+    }
+    /**
+     * Adds an ELSE clause and finishes the statement.
+     * If no WHEN clauses were added, it returns the value directly.
+     */
+    else(value) {
+        if (this.cases.length == 0) {
+            return sql `${value}`;
+        }
+        return this.finalize(value);
+    }
+    /**
+     * Finishes the statement without an ELSE (defaults to NULL).
+     * If no WHEN clauses were added, it returns NULL directly.
+     */
+    end() {
+        if (this.cases.length == 0) {
+            return sql `NULL`;
+        }
+        return this.finalize();
+    }
+    finalize(elseValue) {
+        const chunks = [sql `CASE`];
+        if (isDefined(this.caseExpression)) {
+            chunks.push(sql `${this.caseExpression}`);
+        }
+        chunks.push(sql.join(this.cases, sql ` `));
+        const endChunk = isDefined(elseValue)
+            ? sql `ELSE ${elseValue} END`
+            : sql `END`;
+        chunks.push(endChunk);
+        return sql.join(chunks, sql ` `);
+    }
+}
+export function caseWhen(condition, value) {
+    if (isDefined(value)) {
+        return new CaseBuilder().when(condition, value);
+    }
+    return new CaseBuilder(condition);
+}

package/orm/sqls/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sqls.js';
+export * from './case-when.js';

package/orm/sqls/index.js

@@ -0,0 +1,2 @@
+export * from './sqls.js';
+export * from './case-when.js';

package/orm/{sqls.d.ts → sqls/sqls.d.ts}

@@ -6,18 +6,14 @@
  */
 import { Column, type AnyColumn, type SQL, type SQLChunk } from 'drizzle-orm';
 import type { GetSelectTableSelection, SelectResultField, TableLike } from 'drizzle-orm/query-builders/select.types';
-import type { EnumerationObject, EnumerationValue } from '../types/types.js';
-import { type PgEnumFromEnumeration } from './enums.js';
-import type { TsVectorWeight } from './query/index.js';
-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_V4: SQL<Uuid>;
-/** Drizzle SQL helper for generating a random UUID (v7). Returns a Uuid string. */
-export declare const RANDOM_UUID_V7: SQL<Uuid>;
+import type { EnumerationObject, EnumerationValue, Record } from '../../types/types.js';
+import { type PgEnumFromEnumeration } from '../enums.js';
+import type { TsVectorWeight } from '../query/index.js';
+import type { Uuid } from '../types.js';
 /** 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';
+export type ExclusiveColumnCondition = Column | boolean | SQL;
+export declare const simpleJsonKeyPattern: RegExp;
 export type TsHeadlineOptions = {
     /**
      * The longest headline to output.
@@ -60,14 +56,41 @@ export type TsHeadlineOptions = {
      */
     fragmentDelimiter?: string;
 };
+/** 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_V4: SQL<Uuid>;
+/** Drizzle SQL helper for generating a random UUID (v7). Returns a Uuid string. */
+export declare const RANDOM_UUID_V7: SQL<Uuid>;
+export declare const SQL_TRUE: SQL<boolean>;
+export declare const SQL_FALSE: SQL<boolean>;
 export declare function enumValue<T extends EnumerationObject>(enumeration: T, dbEnum: PgEnumFromEnumeration<T> | string | null, value: EnumerationValue<T>): SQL<string>;
 /**
- * Generates a SQL condition that ensures exactly one of the specified columns is non-null and optional custom conditions.
- * @param enumeration The enumeration object
- * @param discriminator The column used to discriminate between different enumeration values
- * @param conditionMapping An object mapping enumeration values to columns and conditions
+ * Generates a SQL `CASE` expression to enforce strict, mutually exclusive column usage based on a discriminator value.
+ *
+ * This function is useful for "Table per Hierarchy" inheritance patterns or polymorphic associations where specific columns should only be present when a discriminator holds a specific value.
+ * Particularly in conjunction with check constraints, it ensures data integrity by enforcing that only the relevant columns for a given discriminator value are populated.
+ *
+ * The logic ensures that for a specific enum value:
+ * 1. Columns explicitly mapped to that value are enforced as **IS NOT NULL**.
+ * 2. Columns mapped to *other* enum values (but not the current one) are enforced as **IS NULL**.
+ * 3. Any custom SQL conditions provided are combined via `AND`.
+ *
+ * @remarks
+ * The function collects all columns defined across the entire `conditionMapping`. If a column appears anywhere in the mapping but is not associated with the current discriminator value being evaluated, it is automatically asserted as `NULL`.
+ *
+ * @param enumeration - The source enumeration object containing the valid discriminator values.
+ * @param discriminator - The database column acting as the type discriminator.
+ * @param conditionMapping - A configuration object where keys are enum values and values are:
+ * - A `Column` (enforced as NOT NULL).
+ * - A `SQL` condition (passed through).
+ * - A boolean (converted to SQL TRUE/FALSE).
+ * - An array containing a mix of the above.
+ * - `null` (implies this enum value is invalid or should result in `FALSE`).
+ *
+ * @returns A SQL object representing the complete `CASE discriminator WHEN ... THEN ... ELSE FALSE` statement.
  */
-export declare function exclusiveReference<T extends EnumerationObject>(enumeration: T, discriminator: Column, conditionMapping: Record<EnumerationValue<T>, Column | [Column, condition: boolean | SQL] | null>): SQL;
+export declare function exclusiveColumn<T extends EnumerationObject>(enumeration: T, discriminator: Column, conditionMapping: Record<EnumerationValue<T>, ExclusiveColumnCondition | [ExclusiveColumnCondition, ...ExclusiveColumnCondition[]] | null>): SQL;
 export declare function exclusiveNotNull(...columns: Column[]): SQL;
 /**
  * Generates a SQL `CASE ... WHEN ... END` statement for dynamic condition mapping based on an enumeration.
@@ -92,8 +115,7 @@ export declare function exclusiveNotNull(...columns: Column[]): SQL;
  *   By default, it generates an `IS NOT NULL` check.
  */
 export declare function enumerationCaseWhen<T extends EnumerationObject>(enumeration: T, discriminator: Column, conditionMapping: Record<EnumerationValue<T>, Column | [Column, ...Column[]] | boolean | SQL>, defaultColumnCondition?: (column: [Column, ...Column[]]) => SQL<unknown> | undefined): SQL;
-export declare function array<T>(values: SQL<T>[]): SQL<T[]>;
-export declare function array<T = unknown>(values: SQLChunk[]): SQL<T[]>;
+export declare function array<T>(values: readonly (SQL<T> | SQLChunk | T)[]): SQL<T[]>;
 export declare function autoAlias<T>(column: AnyColumn<{
     data: T;
 }>): SQL.Aliased<T>;
@@ -161,7 +183,28 @@ export declare function greatest<T extends (Column | SQL | number)[]>(...values:
     [P in keyof T]: T[P] extends number ? Exclude<T[P], number> | SQL<number> : T[P];
 }[number]>>;
 export declare function greatest<T>(...values: T[]): SQL<SelectResultField<T>>;
-export declare function unnest<T>(array: SQL<readonly T[]>): SQL<T>;
+export declare function unnest<T>(array: SQL<readonly T[]> | SQL.Aliased<readonly T[]> | Column): SQL<T>;
+/**
+ * Creates a PostgreSQL array contains operator expression (@>).
+ * @param left - The array column or expression.
+ * @param right - The array value or expression to check for containment.
+ * @returns A Drizzle SQL object representing the array contains operation.
+ */
+export declare function arrayContains<T>(left: Column | SQL<readonly T[]>, right: readonly T[] | Column | SQL<readonly T[]>): SQL<boolean>;
+/**
+ * Creates a PostgreSQL array is contained by operator expression (<@).
+ * @param left - The array value or expression to check.
+ * @param right - The array column or expression to check against.
+ * @returns A Drizzle SQL object representing the array is contained by operation.
+ */
+export declare function arrayIsContainedBy<T>(left: readonly T[] | Column | SQL<readonly T[]>, right: Column | SQL<readonly T[]>): SQL<boolean>;
+/**
+ * Creates a PostgreSQL array overlaps operator expression (&&).
+ * @param left - The first array column or expression.
+ * @param right - The second array value or expression.
+ * @returns A Drizzle SQL object representing the array overlaps operation.
+ */
+export declare function arrayOverlaps<T>(left: Column | SQL<readonly T[]>, right: readonly T[] | Column | SQL<readonly T[]>): SQL<boolean>;
 export declare function toTsVector(language: string | SQLChunk, text: string | SQLChunk): SQL<string>;
 export declare function tsvectorToArray(tsvector: SQL): SQL<string[]>;
 /**
@@ -261,4 +304,9 @@ export declare function isStrictWordSimilar(left: string | SQLChunk, right: stri
 export declare function distance(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
 export declare function wordDistance(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
 export declare function strictWordDistance(left: string | SQLChunk, right: string | SQLChunk): SQL<number>;
-export declare function jsonbBuildObject(properties: Record<string, any> | [string, any][]): SQL;
+export declare function jsonbBuildObject(properties: Record<string, unknown> | readonly [string, unknown][]): SQL;
+/**
+ * A recursive utility to build PostgreSQL JSONB from TS structures.
+ * Supports: Nested Objects, Arrays, Drizzle Columns, and Raw SQL.
+ */
+export declare function buildJsonb(value: any): SQL;

package/orm/{sqls.js → sqls/sqls.js}

@@ -4,17 +4,22 @@
  * simplifying common SQL operations like generating UUIDs, working with intervals,
  * and aggregating data.
  */
-import { and, Column, eq, sql, isNotNull as sqlIsNotNull, Table } from 'drizzle-orm';
+import { and, Column, eq, isSQLWrapper, sql, isNotNull as sqlIsNotNull, isNull as sqlIsNull, Table } from 'drizzle-orm';
 import { match, P } from 'ts-pattern';
-import { mapObjectValues, objectEntries, objectValues } from '../utils/object/object.js';
-import { assertDefined, isArray, isDefined, isInstanceOf, isNotNull, isNull, isNumber, isString } from '../utils/type-guards.js';
-import { getEnumName } from './enums.js';
+import { distinct, toArray } from '../../utils/array/array.js';
+import { objectEntries, objectValues } from '../../utils/object/object.js';
+import { assertDefined, isArray, isBoolean, isDefined, isInstanceOf, isNotNull, isNull, isNumber, isObject, isString } from '../../utils/type-guards.js';
+import { getEnumName } from '../enums.js';
+import { caseWhen } from './case-when.js';
+export const simpleJsonKeyPattern = /^[a-zA-Z0-9_-]+$/u;
 /** 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_V4 = sql `gen_random_uuid()`;
 /** Drizzle SQL helper for generating a random UUID (v7). Returns a Uuid string. */
 export const RANDOM_UUID_V7 = sql `uuidv7()`;
+export const SQL_TRUE = sql `TRUE`;
+export const SQL_FALSE = sql `FALSE`;
 export function enumValue(enumeration, dbEnum, value) {
     if (isNull(dbEnum)) {
         const enumName = getEnumName(enumeration);
@@ -25,23 +30,50 @@ export function enumValue(enumeration, dbEnum, value) {
     return sql `'${sql.raw(String(value))}'::${enumType}`;
 }
 /**
- * Generates a SQL condition that ensures exactly one of the specified columns is non-null and optional custom conditions.
- * @param enumeration The enumeration object
- * @param discriminator The column used to discriminate between different enumeration values
- * @param conditionMapping An object mapping enumeration values to columns and conditions
+ * Generates a SQL `CASE` expression to enforce strict, mutually exclusive column usage based on a discriminator value.
+ *
+ * This function is useful for "Table per Hierarchy" inheritance patterns or polymorphic associations where specific columns should only be present when a discriminator holds a specific value.
+ * Particularly in conjunction with check constraints, it ensures data integrity by enforcing that only the relevant columns for a given discriminator value are populated.
+ *
+ * The logic ensures that for a specific enum value:
+ * 1. Columns explicitly mapped to that value are enforced as **IS NOT NULL**.
+ * 2. Columns mapped to *other* enum values (but not the current one) are enforced as **IS NULL**.
+ * 3. Any custom SQL conditions provided are combined via `AND`.
+ *
+ * @remarks
+ * The function collects all columns defined across the entire `conditionMapping`. If a column appears anywhere in the mapping but is not associated with the current discriminator value being evaluated, it is automatically asserted as `NULL`.
+ *
+ * @param enumeration - The source enumeration object containing the valid discriminator values.
+ * @param discriminator - The database column acting as the type discriminator.
+ * @param conditionMapping - A configuration object where keys are enum values and values are:
+ * - A `Column` (enforced as NOT NULL).
+ * - A `SQL` condition (passed through).
+ * - A boolean (converted to SQL TRUE/FALSE).
+ * - An array containing a mix of the above.
+ * - `null` (implies this enum value is invalid or should result in `FALSE`).
+ *
+ * @returns A SQL object representing the complete `CASE discriminator WHEN ... THEN ... ELSE FALSE` statement.
  */
-export function exclusiveReference(enumeration, discriminator, conditionMapping) {
-    const columns = objectValues(conditionMapping).filter(isNotNull).map((value) => isInstanceOf(value, Column) ? value : value[0]);
-    const mapping = mapObjectValues(conditionMapping, (value) => {
-        if (isInstanceOf(value, Column)) {
-            return value;
-        }
+export function exclusiveColumn(enumeration, discriminator, conditionMapping) {
+    const allColumns = objectValues(conditionMapping)
+        .filter(isNotNull)
+        .flatMap((value) => toArray(value).filter((value) => isInstanceOf(value, Column)));
+    const participatingColumns = distinct(allColumns);
+    const mapping = objectEntries(conditionMapping).map(([key, value]) => {
         if (isNull(value)) {
-            return sql `FALSE`;
+            return [key, SQL_FALSE];
         }
-        return value[1];
+        const requiredColumns = toArray(value).filter((value) => isInstanceOf(value, Column));
+        const nullColumns = participatingColumns.filter((column) => !requiredColumns.includes(column));
+        const customConditions = toArray(value).filter((val) => !isInstanceOf(val, Column)).map((condition) => isBoolean(condition) ? (condition ? SQL_TRUE : SQL_FALSE) : condition);
+        const condition = and(...requiredColumns.map((col) => sqlIsNotNull(col)), ...nullColumns.map((col) => sqlIsNull(col)), ...customConditions);
+        return [key, condition];
     });
-    return and(exclusiveNotNull(...columns), enumerationCaseWhen(enumeration, discriminator, mapping));
+    const kaseWhen = caseWhen(discriminator);
+    for (const [key, condition] of mapping) {
+        kaseWhen.when(enumValue(enumeration, null, key), condition);
+    }
+    return kaseWhen.else(SQL_FALSE);
 }
 export function exclusiveNotNull(...columns) {
     return eq(numNonNulls(...columns), sql.raw('1'));
@@ -72,7 +104,7 @@ export function enumerationCaseWhen(enumeration, discriminator, conditionMapping
     const whens = [];
     for (const [key, value] of objectEntries(conditionMapping)) {
         const condition = match(value)
-            .with(P.boolean, (bool) => bool ? sql `TRUE` : sql `FALSE`)
+            .with(P.boolean, (bool) => bool ? SQL_TRUE : SQL_FALSE)
             .when((value) => isInstanceOf(value, Column), (col) => defaultColumnCondition(col))
             .otherwise((rawSql) => rawSql);
         whens.push(sql `    WHEN ${enumValue(enumeration, null, key)} THEN ${condition}`);
@@ -84,7 +116,8 @@ ${sql.join(whens, sql `\n`)}
   END`;
 }
 export function array(values) {
-    const valueString = sql.join(values, sql.raw(', '));
+    const chunks = values.map((value) => isSQLWrapper(value) ? value : sql `${value}`);
+    const valueString = sql.join(chunks, sql.raw(', '));
     return sql `ARRAY[${valueString}]`;
 }
 export function autoAlias(column) {
@@ -175,6 +208,36 @@ export function greatest(...values) {
 export function unnest(array) {
     return sql `unnest(${array})`;
 }
+/**
+ * Creates a PostgreSQL array contains operator expression (@>).
+ * @param left - The array column or expression.
+ * @param right - The array value or expression to check for containment.
+ * @returns A Drizzle SQL object representing the array contains operation.
+ */
+export function arrayContains(left, right) {
+    const rightSql = isArray(right) ? array(right) : right;
+    return sql `(${left} @> ${rightSql})`;
+}
+/**
+ * Creates a PostgreSQL array is contained by operator expression (<@).
+ * @param left - The array value or expression to check.
+ * @param right - The array column or expression to check against.
+ * @returns A Drizzle SQL object representing the array is contained by operation.
+ */
+export function arrayIsContainedBy(left, right) {
+    const leftSql = isArray(left) ? array(left) : left;
+    return sql `(${leftSql} <@ ${right})`;
+}
+/**
+ * Creates a PostgreSQL array overlaps operator expression (&&).
+ * @param left - The first array column or expression.
+ * @param right - The second array value or expression.
+ * @returns A Drizzle SQL object representing the array overlaps operation.
+ */
+export function arrayOverlaps(left, right) {
+    const rightSql = isArray(right) ? array(right) : right;
+    return sql `(${left} && ${rightSql})`;
+}
 export function toTsVector(language, text) {
     return sql `to_tsvector(${language}, ${text})`;
 }
@@ -323,8 +386,39 @@ export function strictWordDistance(left, right) {
 }
 export function jsonbBuildObject(properties) {
     const entries = isArray(properties) ? properties : objectEntries(properties);
-    const chunks = entries
-        .filter(([_, propValue]) => isDefined(propValue))
-        .map(([propKey, propValue]) => sql `'${sql.raw(propKey)}', ${propValue}`);
+    const chunks = [];
+    for (const [key, value] of entries) {
+        if (isDefined(value)) {
+            const isSimpleKey = simpleJsonKeyPattern.test(key);
+            const sqlKey = isSimpleKey ? sql.raw(`'${key}'`) : sql `${key}`;
+            chunks.push(sqlKey, buildJsonb(value));
+        }
+    }
+    if (chunks.length == 0) {
+        return sql `'{}'::jsonb`;
+    }
     return sql `jsonb_build_object(${sql.join(chunks, sql `, `)})`;
 }
+/**
+ * A recursive utility to build PostgreSQL JSONB from TS structures.
+ * Supports: Nested Objects, Arrays, Drizzle Columns, and Raw SQL.
+ */
+export function buildJsonb(value) {
+    if (isSQLWrapper(value)) {
+        return sql `${value}`;
+    }
+    if (isNull(value)) {
+        return sql `null`;
+    }
+    if (isArray(value)) {
+        if (value.length == 0) {
+            return sql `'[]'::jsonb`;
+        }
+        const elements = value.map((inner) => buildJsonb(inner));
+        return sql `jsonb_build_array(${sql.join(elements, sql `, `)})`;
+    }
+    if (isObject(value)) {
+        return jsonbBuildObject(value);
+    }
+    return sql `${value}`;
+}

package/orm/tests/data-types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/orm/tests/data-types.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'vitest';
+import { dateToNumericDate, numericDateToDateObject } from '../../utils/date-time.js';
+describe('ORM Data Types - numericDate Logic', () => {
+    test('dateToNumericDate should return days since epoch', () => {
+        const date = new Date(Date.UTC(2024, 0, 1));
+        expect(dateToNumericDate(date)).toBe(19723);
+    });
+    test('numericDateToDateObject should convert days since epoch to date components', () => {
+        const { year, month, day } = numericDateToDateObject(19723);
+        expect(year).toBe(2024);
+        expect(month).toBe(1);
+        expect(day).toBe(1);
+    });
+    test('leap year handling (2024-02-29)', () => {
+        const leapDate = new Date(Date.UTC(2024, 1, 29));
+        const numeric = dateToNumericDate(leapDate);
+        expect(numeric).toBe(19782);
+        const { year, month, day } = numericDateToDateObject(19782);
+        expect(year).toBe(2024);
+        expect(month).toBe(2);
+        expect(day).toBe(29);
+    });
+    test('epoch start (1970-01-01)', () => {
+        const epoch = new Date(Date.UTC(1970, 0, 1));
+        expect(dateToNumericDate(epoch)).toBe(0);
+        const { year, month, day } = numericDateToDateObject(0);
+        expect(year).toBe(1970);
+        expect(month).toBe(1);
+        expect(day).toBe(1);
+    });
+    test('before epoch (1969-12-31)', () => {
+        const beforeEpoch = new Date(Date.UTC(1969, 11, 31));
+        expect(dateToNumericDate(beforeEpoch)).toBe(-1);
+        const { year, month, day } = numericDateToDateObject(-1);
+        expect(year).toBe(1969);
+        expect(month).toBe(12);
+        expect(day).toBe(31);
+    });
+});