@tstdl/base 0.93.86 → 0.93.87

package/orm/index.d.ts

@@ -8,6 +8,6 @@ export * from './entity.js';
 export * from './query/index.js';
 export * from './repository.types.js';
 export * from './schemas/index.js';
-export * from './sqls.js';
+export * from './sqls/index.js';
 export * from './types.js';
 export * from './utils.js';

package/orm/index.js

@@ -8,6 +8,6 @@ export * from './entity.js';
 export * from './query/index.js';
 export * from './repository.types.js';
 export * from './schemas/index.js';
-export * from './sqls.js';
+export * from './sqls/index.js';
 export * from './types.js';
 export * from './utils.js';

package/orm/repository.types.d.ts

@@ -9,7 +9,7 @@ import type { AnyColumn, SQL, SQLWrapper } from 'drizzle-orm';
 import type { PartialDeep } from 'type-fest';
 import type { BaseEntity, Entity, EntityMetadata } from './entity.js';
 import type { FullTextSearchQuery, Query } from './query/index.js';
-import type { TsHeadlineOptions } from './sqls.js';
+import type { TsHeadlineOptions } from './sqls/index.js';
 type WithSql<T> = {
     [P in keyof T]: T[P] extends Record ? WithSql<T[P]> : (T[P] | SQL);
 };

package/orm/server/query-converter.js

@@ -4,7 +4,7 @@ import { NotSupportedError } from '../../errors/not-supported.error.js';
 import { hasOwnProperty, mapObject, mapObjectKeysToSnakeCase, objectEntries } from '../../utils/object/object.js';
 import { toSnakeCase } from '../../utils/string/index.js';
 import { assert, assertDefinedPass, isArray, isDefined, isPrimitive, isRegExp, isString, isUndefined } from '../../utils/type-guards.js';
-import { array, isSimilar, isStrictWordSimilar, isWordSimilar, jsonbBuildObject, phraseToTsQuery, plainToTsQuery, setweight, similarity, strictWordSimilarity, toTsQuery, toTsVector, websearchToTsQuery, wordSimilarity } from '../sqls.js';
+import { array, isSimilar, isStrictWordSimilar, isWordSimilar, jsonbBuildObject, phraseToTsQuery, plainToTsQuery, setweight, similarity, strictWordSimilarity, toTsQuery, toTsVector, websearchToTsQuery, wordSimilarity } from '../sqls/index.js';
 const sqlTrue = sql `true`;
 /**
  * Resolves a target to a Drizzle PgColumn or SQLWrapper.

package/orm/server/repository.js

@@ -23,7 +23,7 @@ import { assertDefined, assertDefinedPass, isArray, isBoolean, isDefined, isFunc
 import { typeExtends } from '../../utils/type/index.js';
 import { millisecondsPerSecond } from '../../utils/units.js';
 import { Entity } from '../entity.js';
-import { distance, isSimilar, isStrictWordSimilar, isWordSimilar, TRANSACTION_TIMESTAMP, tsHeadline, tsRankCd } from '../sqls.js';
+import { distance, isSimilar, isStrictWordSimilar, isWordSimilar, TRANSACTION_TIMESTAMP, tsHeadline, tsRankCd } from '../sqls/index.js';
 import { getColumnDefinitions, getColumnDefinitionsMap, getDrizzleTableFromType } from './drizzle/schema-converter.js';
 import { convertQuery, getTsQuery, getTsVector, resolveTargetColumn } from './query-converter.js';
 import { ENCRYPTION_SECRET } from './tokens.js';

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: TValue | SQL | 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<TValue>(caseExpression: SQL | SQLWrapper): CaseBuilder<TValue>;
+export declare function caseWhen<TValue>(condition: SQL | SQLWrapper | undefined, value: TValue | SQL | SQLWrapper): CaseBuilder<TValue>;

package/orm/sqls/case-when.js

@@ -0,0 +1,54 @@
+import { isDefined, isUndefined } 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 (isUndefined(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,13 @@
  */
 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 } 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 type TsHeadlineOptions = {
     /**
      * The longest headline to output.
@@ -60,14 +55,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.

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

@@ -4,17 +4,21 @@
  * 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, 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, isString } from '../../utils/type-guards.js';
+import { getEnumName } from '../enums.js';
+import { caseWhen } from './case-when.js';
 /** 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 +29,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 +103,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}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.86",
+  "version": "0.93.87",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"