@tstdl/base 0.93.85 → 0.93.87

package/authentication/client/authentication.service.d.ts

@@ -84,10 +84,10 @@ export declare class AuthenticationClientService<AdditionalTokenPayload extends
      */
     get definedTenantId(): string;
     /**
-     * Get current subject or throw if not available
+     * Get current subjectId or throw if not available
      * @throws Will throw if subject is not available
      */
-    get definedSubject(): string;
+    get definedSubjectId(): string;
     /** Whether a valid token is available (not undefined and not expired) */
     get hasValidToken(): boolean;
     constructor();

package/authentication/client/authentication.service.js

@@ -140,10 +140,10 @@ let AuthenticationClientService = class AuthenticationClientService {
         return this.definedToken.tenant;
     }
     /**
-     * Get current subject or throw if not available
+     * Get current subjectId or throw if not available
      * @throws Will throw if subject is not available
      */
-    get definedSubject() {
+    get definedSubjectId() {
         return this.definedToken.subject;
     }
     /** Whether a valid token is available (not undefined and not expired) */

package/authentication/models/authentication-credentials.model.d.ts

@@ -1,13 +1,10 @@
 import { TenantEntity, type Uuid } from '../../orm/index.js';
 export declare class AuthenticationCredentials extends TenantEntity {
     subjectId: Uuid;
+    /** The version of the hash algorithm used. */
     hashVersion: number;
-    /**
-     * The salt used to hash the secret.
-     */
+    /** The salt used to hash the secret. */
     salt: Uint8Array<ArrayBuffer>;
-    /**
-     * The hashed secret.
-     */
+    /** The hashed secret. */
     hash: Uint8Array<ArrayBuffer>;
 }

package/authentication/models/authentication-credentials.model.js

@@ -12,14 +12,11 @@ import { Integer, Uint8ArrayProperty } from '../../schema/index.js';
 import { Subject } from './subject.model.js';
 let AuthenticationCredentials = class AuthenticationCredentials extends TenantEntity {
     subjectId;
+    /** The version of the hash algorithm used. */
     hashVersion;
-    /**
-     * The salt used to hash the secret.
-     */
+    /** The salt used to hash the secret. */
     salt;
-    /**
-     * The hashed secret.
-     */
+    /** The hashed secret. */
     hash;
 };
 __decorate([

package/authentication/models/authentication-session.model.d.ts

@@ -4,13 +4,10 @@ export declare class AuthenticationSession extends TenantEntity {
     subjectId: Uuid;
     begin: Timestamp;
     end: Timestamp;
+    /** The version of the hash algorithm used. */
     refreshTokenHashVersion: number;
-    /**
-     * The salt used to hash the refresh token.
-     */
+    /** The salt used to hash the refresh token. */
     refreshTokenSalt: Uint8Array<ArrayBuffer>;
-    /**
-     * The hashed refresh token.
-     */
+    /** The hashed refresh token. */
     refreshTokenHash: Uint8Array<ArrayBuffer>;
 }

package/authentication/models/authentication-session.model.js

@@ -14,14 +14,11 @@ let AuthenticationSession = class AuthenticationSession extends TenantEntity {
     subjectId;
     begin;
     end;
+    /** The version of the hash algorithm used. */
     refreshTokenHashVersion;
-    /**
-     * The salt used to hash the refresh token.
-     */
+    /** The salt used to hash the refresh token. */
     refreshTokenSalt;
-    /**
-     * The hashed refresh token.
-     */
+    /** The hashed refresh token. */
     refreshTokenHash;
 };
 __decorate([

package/authentication/models/token.model.d.ts

@@ -2,9 +2,7 @@ import type { Record } from '../../types/index.js';
 import type { JwtToken, JwtTokenHeader } from '../../utils/jwt.js';
 import type { TokenPayloadBase } from './token-payload-base.model.js';
 export type TokenHeader = {
-    /**
-     * Token version.
-     */
+    /** Token version. */
     v: number;
 };
 /**
@@ -18,42 +16,26 @@ export type Token<AdditionalTokenPayload extends Record = Record<never>> = JwtTo
  */
 export type TokenPayload<T extends Record = Record<never>> = T & TokenPayloadBase;
 export type RefreshToken = JwtToken<{
-    /**
-     * Expiration timestamp in seconds.
-     */
+    /** Expiration timestamp in seconds. */
     exp: number;
-    /**
-     * The tenant id.
-     */
+    /** The tenant id. */
     tenant: string;
-    /**
-     * The subject of the token.
-     */
+    /** The subject of the token. */
     subject: string;
-    /**
-     * The subject of the impersonator, if any.
-     */
+    /** The subject of the impersonator, if any. */
     impersonator?: string;
-    /**
-     * The id of the session.
-     */
+    /** The id of the session. */
     session: string;
-    /**
-     * The secret to use for refreshing the token.
-     */
+    /** The secret to use for refreshing the token. */
     secret: string;
 }>;
 export type SecretResetToken = JwtToken<{
-    /**
-     * Expiration timestamp in seconds.
-     */
+    /** Issued at timestamp in seconds. */
+    iat: number;
+    /** Expiration timestamp in seconds. */
     exp: number;
-    /**
-     * The tenant id.
-     */
+    /** The tenant id. */
     tenant: string;
-    /**
-     * The subject for which to reset the secret.
-     */
+    /** The subject for which to reset the secret. */
     subject: string;
 }>;

package/authentication/server/authentication.audit.d.ts

@@ -15,6 +15,7 @@ export type AuthenticationAuditEvents = {
     };
     'refresh-failure': {
         reason: string;
+        sessionId: string | null;
     };
     'impersonate-success': {
         impersonatedSubjectId: string;

package/authentication/server/authentication.service.js

@@ -25,7 +25,7 @@ import { currentTimestamp, timestampToTimestampSeconds } from '../../utils/date-
 import { timingSafeBinaryEquals } from '../../utils/equals.js';
 import { createJwtTokenString } from '../../utils/jwt.js';
 import { getRandomBytes, getRandomString } from '../../utils/random.js';
-import { assertDefinedPass, isBinaryData, isString, isUndefined } from '../../utils/type-guards.js';
+import { isBinaryData, isDefined, isString, isUndefined } from '../../utils/type-guards.js';
 import { millisecondsPerDay, millisecondsPerMinute } from '../../utils/units.js';
 import { AuthenticationCredentials, AuthenticationSession, Subject, User } from '../models/index.js';
 import { AuthenticationAncillaryService, GetTokenPayloadContextAction } from './authentication-ancillary.service.js';
@@ -63,6 +63,13 @@ export class AuthenticationServiceOptions {
      */
     secretResetTokenTimeToLive;
 }
+const HASH_ITERATIONS = 250000;
+const HASH_LENGTH_BITS = 512;
+const HASH_LENGTH_BYTES = HASH_LENGTH_BITS / 8;
+const JWT_ID_LENGTH = 24;
+const REFRESH_TOKEN_SECRET_LENGTH = 64;
+const SALT_LENGTH = 32;
+const SIGNING_SECRETS_DERIVATION_ITERATIONS = 500000;
 const SIGNING_SECRETS_LENGTH = 64;
 /**
  * Handles authentication on server side.
@@ -136,7 +143,7 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
         if (options?.skipValidation != true) {
             await this.#authenticationSecretRequirementsValidator.validateSecretRequirements(secret);
         }
-        const salt = getRandomBytes(32);
+        const salt = getRandomBytes(SALT_LENGTH);
         const hash = await this.getHash(secret, salt);
         await this.#credentialsRepository.transaction(async (tx) => {
             await this.#credentialsRepository.withTransaction(tx).upsert(['tenantId', 'subjectId'], {
@@ -159,15 +166,18 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
      */
     async authenticate(subject, secret) {
         const actualSubject = await this.tryResolveSubject(subject);
-        // Always try to load credentials, even if the subject is not resolved, to reduce information leakage.
-        // If the subject is not resolved, we will create a new credentials entry with an empty salt and hash.
-        // This way, we do not leak if the subject exists or not via timing attacks.
-        const credentials = await this.#credentialsRepository.tryLoadByQuery({ tenantId: actualSubject?.tenantId ?? NIL_UUID, subjectId: actualSubject?.id ?? NIL_UUID })
-            ?? { subjectId: actualSubject, salt: new Uint8Array(), hash: new Uint8Array() };
+        // we use a random uuid instead of null here to reduce timing attack surface by DB optimiziations
+        const queryTenantId = actualSubject?.tenantId ?? crypto.randomUUID();
+        const querySubjectId = actualSubject?.id ?? crypto.randomUUID();
+        const loadedCredentials = await this.#credentialsRepository.tryLoadByQuery({
+            tenantId: queryTenantId,
+            subjectId: querySubjectId,
+        });
+        const credentials = loadedCredentials ?? { salt: new Uint8Array(SALT_LENGTH), hash: new Uint8Array(HASH_LENGTH_BYTES) };
         const hash = await this.getHash(secret, credentials.salt);
         const valid = timingSafeBinaryEquals(hash, credentials.hash);
-        if (valid) {
-            return { success: true, subject: assertDefinedPass(actualSubject, 'Subject should be defined if authentication is valid but it is not.') };
+        if (valid && isDefined(actualSubject) && isDefined(loadedCredentials)) {
+            return { success: true, subject: actualSubject };
         }
         return { success: false };
     }
@@ -282,6 +292,12 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
                 throw new InvalidTokenError('Session is expired.');
             }
             if (!timingSafeBinaryEquals(hash, session.refreshTokenHash)) {
+                await this.endSession(sessionId, auditor);
+                await authAuditor.warn('refresh-failure', {
+                    targetId: session.tenantId,
+                    targetType: 'User',
+                    details: { sessionId, reason: 'Token reuse detected. Session revoked.' },
+                });
                 throw new InvalidTokenError('Invalid refresh token.');
             }
             const now = currentTimestamp();
@@ -311,7 +327,7 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
             await authAuditor.warn('refresh-failure', {
                 targetId: NIL_UUID,
                 targetType: 'User',
-                details: { reason: error.message },
+                details: { sessionId: null, reason: error.message },
             });
             throw error;
         }
@@ -458,6 +474,21 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
         const authAuditor = auditor.fork(AuthenticationService_1.name);
         try {
             const token = await this.validateSecretResetToken(tokenString);
+            const credentials = await this.#credentialsRepository.tryLoadByQuery({
+                tenantId: token.payload.tenant,
+                subjectId: token.payload.subject,
+            });
+            if (isDefined(credentials)) {
+                const lastUpdateSeconds = timestampToTimestampSeconds(credentials.metadata.revisionTimestamp);
+                if (token.payload.iat < lastUpdateSeconds) {
+                    await authAuditor.info('reset-secret-failure', {
+                        targetId: token.payload.subject,
+                        targetType: 'User',
+                        details: { reason: 'Token is invalid (credentials have already been changed).' },
+                    });
+                    throw new InvalidTokenError();
+                }
+            }
             const subject = await this.#subjectRepository.loadByQuery({ tenantId: token.payload.tenant, id: token.payload.subject });
             await this.setCredentials(subject, newSecret);
             await authAuditor.info('reset-secret-success', {
@@ -580,7 +611,7 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
             typ: 'JWT',
         };
         const payload = {
-            jti: jwtId ?? getRandomString(24, Alphabet.LowerUpperCaseNumbers),
+            jti: jwtId ?? getRandomString(JWT_ID_LENGTH, Alphabet.LowerUpperCaseNumbers),
             iat: issuedAt ?? timestampToTimestampSeconds(timestamp),
             exp: expiration ?? timestampToTimestampSeconds(timestamp + this.tokenTimeToLive),
             refreshTokenExp: timestampToTimestampSeconds(refreshTokenExpiration),
@@ -607,8 +638,8 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
      * @returns The created refresh token.
      */
     async createRefreshToken(subject, sessionId, expirationTimestamp, options) {
-        const secret = getRandomString(64, Alphabet.LowerUpperCaseNumbers);
-        const salt = getRandomBytes(32);
+        const secret = getRandomString(REFRESH_TOKEN_SECRET_LENGTH, Alphabet.LowerUpperCaseNumbers);
+        const salt = getRandomBytes(SALT_LENGTH);
         const hash = await this.getHash(secret, salt);
         const jsonToken = {
             header: {
@@ -647,12 +678,14 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
         return subjects[0];
     }
     async createSecretResetToken(subject, expirationTimestamp) {
+        const iat = timestampToTimestampSeconds(currentTimestamp());
         const jsonToken = {
             header: {
                 alg: 'HS256',
                 typ: 'JWT',
             },
             payload: {
+                iat,
                 exp: timestampToTimestampSeconds(expirationTimestamp),
                 subject: subject.id,
                 tenant: subject.tenantId,
@@ -663,9 +696,9 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
     }
     async deriveSigningSecrets(secret) {
         const key = await importPbkdf2Key(secret);
-        const saltBase64 = await this.#keyValueStore.getOrSet('derivationSalt', encodeBase64(getRandomBytes(32)));
+        const saltBase64 = await this.#keyValueStore.getOrSet('derivationSalt', encodeBase64(getRandomBytes(SALT_LENGTH)));
         const salt = decodeBase64(saltBase64);
-        const algorithm = { name: 'PBKDF2', hash: 'SHA-512', iterations: 500000, salt };
+        const algorithm = { name: 'PBKDF2', hash: 'SHA-512', iterations: SIGNING_SECRETS_DERIVATION_ITERATIONS, salt };
         const [derivedTokenSigningSecret, derivedRefreshTokenSigningSecret, derivedSecretResetTokenSigningSecret] = await deriveBytesMultiple(algorithm, key, 3, SIGNING_SECRETS_LENGTH);
         this.derivedTokenSigningSecret = derivedTokenSigningSecret;
         this.derivedRefreshTokenSigningSecret = derivedRefreshTokenSigningSecret;
@@ -673,7 +706,7 @@ let AuthenticationService = AuthenticationService_1 = class AuthenticationServic
     }
     async getHash(secret, salt) {
         const key = await importPbkdf2Key(secret);
-        const hash = await globalThis.crypto.subtle.deriveBits({ name: 'PBKDF2', hash: 'SHA-512', iterations: 250000, salt }, key, 512);
+        const hash = await globalThis.crypto.subtle.deriveBits({ name: 'PBKDF2', hash: 'SHA-512', iterations: HASH_ITERATIONS, salt }, key, HASH_LENGTH_BITS);
         return new Uint8Array(hash);
     }
 };

package/examples/document-management/main.js

@@ -28,6 +28,7 @@ import { configurePostgresQueue, migratePostgresQueueSchema } from '../../queue/
 import { configureDefaultSignalsImplementation } from '../../signals/implementation/configure.js';
 import { boolean, positiveInteger, string } from '../../utils/config-parser.js';
 import { TstdlCategoryParents, TstdlDocumentCategoryLabels, TstdlDocumentPropertyConfiguration, TstdlDocumentTypeCategories, TstdlDocumentTypeLabels, TstdlDocumentTypeProperties } from './categories-and-types.js';
+import { configurePostgresCircuitBreaker, migratePostgresCircuitBreaker } from '../../circuit-breaker/postgres/module.js';
 const config = {
     database: {
         host: string('DATABASE_HOST', '127.0.0.1'),
@@ -87,6 +88,7 @@ async function bootstrap() {
     const injector = inject(Injector);
     configureNodeHttpServer();
     configurePostgresQueue();
+    configurePostgresCircuitBreaker();
     configureLocalMessageBus();
     configureDefaultSignalsImplementation();
     configureGenkit({
@@ -134,8 +136,9 @@ async function bootstrap() {
         apiKey: config.ai.apiKey,
         keyFile: config.ai.keyFile,
     });
-    await runInInjectionContext(injector, async () => await migrateDocumentManagementSchema());
-    await runInInjectionContext(injector, async () => await migratePostgresQueueSchema());
+    await runInInjectionContext(injector, migrateDocumentManagementSchema);
+    await runInInjectionContext(injector, migratePostgresCircuitBreaker);
+    await runInInjectionContext(injector, migratePostgresQueueSchema);
 }
 async function main() {
     const tenantId = '00000000-0000-0000-0000-000000000000';

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.
@@ -91,7 +113,7 @@ export declare function exclusiveNotNull(...columns: Column[]): SQL;
  *   that defines the default condition to apply when a `Column` is provided in `conditionMapping`.
  *   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 | boolean | SQL>, defaultColumnCondition?: (column: Column) => SQL<unknown>): SQL;
+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 autoAlias<T>(column: AnyColumn<{

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'));
@@ -68,11 +99,11 @@ export function exclusiveNotNull(...columns) {
  *   that defines the default condition to apply when a `Column` is provided in `conditionMapping`.
  *   By default, it generates an `IS NOT NULL` check.
  */
-export function enumerationCaseWhen(enumeration, discriminator, conditionMapping, defaultColumnCondition = (column) => sqlIsNotNull(column)) {
+export function enumerationCaseWhen(enumeration, discriminator, conditionMapping, defaultColumnCondition = (column) => isArray(column) ? and(...column.map((col) => sqlIsNotNull(col))) : sqlIsNotNull(column)) {
     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.85",
+  "version": "0.93.87",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -145,7 +145,7 @@
   "peerDependencies": {
     "@genkit-ai/google-genai": "^1.27",
     "@google-cloud/storage": "^7.18",
-    "@google/genai": "^1.34",
+    "@google/genai": "^1.35",
     "@toon-format/toon": "^2.1.0",
     "@tstdl/angular": "^0.93",
     "@zxcvbn-ts/core": "^3.0",
@@ -174,7 +174,7 @@
     }
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "5.6",
+    "@stylistic/eslint-plugin": "5.7",
     "@types/koa__router": "12.0",
     "@types/luxon": "3.7",
     "@types/mjml": "4.7",