@tstdl/base 0.92.123 → 0.92.124

package/orm/server/database.js

@@ -4,12 +4,22 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+/**
+ * @module
+ * Provides the core database connection and migration functionality using Drizzle ORM and node-postgres.
+ * It sets up the dependency injection for the database instance.
+ */
 import { drizzle, NodePgDatabase } from 'drizzle-orm/node-postgres';
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
-import pg from 'pg';
+import { Pool } from 'pg';
 import { inject, Injector, ReplaceClass } from '../../injector/index.js';
 import { isUndefined } from '../../utils/type-guards.js';
 import { DatabaseConfig } from './module.js';
+/**
+ * Represents the application's database connection.
+ * Extends Drizzle's `NodePgDatabase` and integrates with the dependency injection system.
+ * Can be resolved using a `PoolConfig` argument.
+ */
 let Database = class Database extends NodePgDatabase {
 };
 Database = __decorate([
@@ -22,9 +32,13 @@ Injector.registerSingleton(Database, {
         if (isUndefined(connection)) {
             throw new Error('Missing postgres connection. Provide it either via injection argument or a provider for DatabaseConfig.');
         }
-        const pool = new pg.Pool(connection);
+        const pool = new Pool(connection);
         context.addDisposeHandler(async () => pool.end());
         return drizzle(pool);
-    }
+    },
 });
+/**
+ * Re-exports the `migrate` function from `drizzle-orm/node-postgres/migrator`
+ * for running database migrations.
+ */
 export { migrate };

package/orm/server/drizzle/schema-converter.js

@@ -19,12 +19,17 @@ import { NumericDateSchema } from '../../schemas/numeric-date.js';
 import { TimestampSchema } from '../../schemas/timestamp.js';
 import { UuidSchema } from '../../schemas/uuid.js';
 import { decryptBytes, encryptBytes } from '../encryption.js';
+import { convertQuery } from '../query-converter.js';
 const getDbSchema = memoizeSingle(pgSchema);
 export const getDrizzleTableFromType = memoize(_getDrizzleTableFromType);
 const columnDefinitionsSymbol = Symbol('columnDefinitions');
+const columnDefinitionsMapSymbol = Symbol('columnDefinitionsMap');
 export function getColumnDefinitions(table) {
     return table[columnDefinitionsSymbol];
 }
+export function getColumnDefinitionsMap(table) {
+    return table[columnDefinitionsMapSymbol];
+}
 export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     const metadata = reflectionRegistry.getMetadata(type);
     assertDefined(metadata, `Type ${type.name} does not have reflection metadata.`);
@@ -41,6 +46,7 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
     const tableName = tableReflectionData?.name ?? getDefaultTableName(type);
     const dbSchema = getDbSchema(schema);
     const columnDefinitions = getPostgresColumnEntries(type, dbSchema, tableName);
+    const columnDefinitionsMap = new Map(columnDefinitions.map((column) => [column.objectPath.path, column]));
     function getColumn(table, propertyName) {
         return assertDefinedPass(table[propertyName], `Property "${propertyName}" does not exist on ${type.name}`);
     }
@@ -60,7 +66,11 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
             return column;
         });
         const indexFn = (data.options?.unique == true) ? uniqueIndex : index;
-        return indexFn(data.name ?? getIndexName(tableName, columns, { naming: data.options?.naming })).using(data.options?.using ?? 'btree', ...columns);
+        let builder = indexFn(data.name ?? getIndexName(tableName, columns, { naming: data.options?.naming })).using(data.options?.using ?? 'btree', ...columns);
+        if (isDefined(data.options?.where)) {
+            builder = builder.where(convertQuery(data.options.where(table), table, columnDefinitionsMap));
+        }
+        return builder;
     }
     function buildPrimaryKey(table) {
         const columns = primaryKeyColumnDefinitions.map((columnDefinition) => getColumn(table, columnDefinition.name));
@@ -95,6 +105,7 @@ export function _getDrizzleTableFromType(type, fallbackSchemaName) {
         ...tableReflectionDatas.flatMap((tableReflectionData) => tableReflectionData.checks).filter(isDefined).map((data) => check(data.name, data.builder(table)))
     ]);
     drizzleSchema[columnDefinitionsSymbol] = columnDefinitions;
+    drizzleSchema[columnDefinitionsMapSymbol] = columnDefinitionsMap;
     return drizzleSchema;
 }
 function getPostgresColumnEntries(type, dbSchema, tableName, path = new JsonPath({ dollar: false }), prefix = '') {

package/orm/server/encryption.js

@@ -1,30 +1,55 @@
+/**
+ * @module
+ * Provides utility functions for encrypting and decrypting byte arrays using AES-GCM.
+ * It includes versioning to handle potential future changes in the encryption format.
+ */
 import { DetailsError } from '../../errors/index.js';
 import { decrypt, encrypt } from '../../utils/cryptography.js';
 import { getRandomBytes } from '../../utils/random.js';
 import { assert } from '../../utils/type-guards.js';
+/** Current version of the encryption format. */
 const encryptionVersion = 1;
+/** Number of bytes used to store the encryption version. */
 const encryptionVersionBytes = 2;
+/** Number of bytes used for the Initialization Vector (IV). */
 const ivBytes = 12;
+/**
+ * Encrypts a byte array using AES-GCM with the provided key.
+ * Prepends the encryption version and IV to the resulting ciphertext.
+ * @param bytes The byte array to encrypt.
+ * @param key The CryptoKey to use for encryption.
+ * @returns A promise that resolves to the encrypted byte array (version + IV + ciphertext).
+ */
 export async function encryptBytes(bytes, key) {
     const iv = getRandomBytes(ivBytes);
     const encrypted = await encrypt({ name: 'AES-GCM', iv }, key, bytes).toBuffer();
     const result = new Uint8Array(encryptionVersionBytes + ivBytes + encrypted.byteLength);
     const resultView = new DataView(result.buffer);
-    resultView.setUint16(0, encryptionVersion);
-    result.set(iv, encryptionVersionBytes);
-    result.set(new Uint8Array(encrypted), encryptionVersionBytes + ivBytes);
+    resultView.setUint16(0, encryptionVersion); // Prepend version
+    result.set(iv, encryptionVersionBytes); // Prepend IV
+    result.set(new Uint8Array(encrypted), encryptionVersionBytes + ivBytes); // Append ciphertext
     return result;
 }
+/**
+ * Decrypts a byte array encrypted with `encryptBytes`.
+ * Reads the version and IV from the beginning of the array.
+ * @param bytes The byte array to decrypt (must include version and IV).
+ * @param key The CryptoKey to use for decryption.
+ * @returns A promise that resolves to the original decrypted byte array.
+ * @throws {DetailsError} If decryption fails (e.g., wrong key, corrupted data).
+ * @throws {Error} If the encryption version is invalid.
+ */
 export async function decryptBytes(bytes, key) {
     const bytesView = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
     const version = bytesView.getUint16(0);
     const iv = bytes.slice(encryptionVersionBytes, encryptionVersionBytes + ivBytes);
-    assert(version == encryptionVersion, 'Invalid encryption version.');
+    assert(version == encryptionVersion, 'Invalid encryption version.'); // Check version
     try {
         const decrypted = await decrypt({ name: 'AES-GCM', iv }, key, bytes.slice(encryptionVersionBytes + ivBytes)).toBuffer();
         return new Uint8Array(decrypted);
     }
     catch (error) {
+        // Wrap decryption errors for better context
         throw new DetailsError('Decrypt error', error);
     }
 }

package/orm/server/index.js

@@ -1,6 +1,13 @@
+/**
+ * @module
+ * Barrel file exporting core server-side ORM functionalities.
+ * Includes database connection, schema management, repositories, transactions,
+ * and query conversion utilities.
+ */
 export * from './database-schema.js';
 export * from './database.js';
 export * from './module.js';
 export * from './query-converter.js';
 export * from './repository.js';
 export * from './transaction.js';
+export * from './transactional.js';

package/orm/server/module.js

@@ -2,9 +2,18 @@ import { Injector } from '../../injector/injector.js';
 import { isDefined } from '../../utils/type-guards.js';
 import { EntityRepositoryConfig } from './repository.js';
 import { ENCRYPTION_SECRET } from './tokens.js';
+/**
+ * Configuration class for the database connection.
+ * Holds the `pg.PoolConfig`.
+ */
 export class DatabaseConfig {
+    /** Optional PostgreSQL pool configuration. */
     connection;
 }
+/**
+ * Configures the ORM module by registering necessary providers in the dependency injector.
+ * @param options - Configuration options including connection details, repository settings, and the encryption secret.
+ */
 export function configureOrm(options) {
     if (isDefined(options.connection)) {
         Injector.register(DatabaseConfig, { useValue: { connection: options.connection } });

package/orm/server/query-converter.js

@@ -1,118 +1,173 @@
+/**
+ * @module
+ * Converts a generic query object structure into a Drizzle ORM SQL condition.
+ * Supports logical operators ($and, $or, $nor) and various comparison operators
+ * ($eq, $neq, $in, $nin, $lt, $lte, $gt, $gte, $regex).
+ */
 import { and, eq, gt, gte, inArray, isNotNull, isNull, isSQLWrapper, lt, lte, ne, not, notInArray, or, SQL, sql } from 'drizzle-orm';
 import { NotSupportedError } from '../../errors/not-supported.error.js';
 import { hasOwnProperty, objectEntries } from '../../utils/object/object.js';
 import { assertDefinedPass, isPrimitive, isRegExp, isString, isUndefined } from '../../utils/type-guards.js';
+/** SQL fragment representing `true`. */
 const sqlTrue = sql `true`;
+/**
+ * Converts a query object into a Drizzle SQL condition.
+ * Recursively handles nested logical operators and maps property names to database columns.
+ * @param query The query object to convert. Can be a Drizzle SQL object, SQLWrapper, or a custom query object.
+ * @param table The Drizzle table object.
+ * @param columnDefinitionsMap A map from property names to column definitions.
+ * @returns A Drizzle SQL condition representing the query.
+ * @throws {Error} If multiple logical operators are used at the same level.
+ * @throws {Error} If a property cannot be mapped to a column.
+ * @throws {Error} If an unsupported query type is encountered.
+ */
 export function convertQuery(query, table, columnDefinitionsMap) {
+    // If the query is already a Drizzle SQL object, return it directly.
     if (query instanceof SQL) {
         return query;
     }
+    // If the query is a SQLWrapper, convert it to a Drizzle SQL object.
     if (isSQLWrapper(query)) {
         return sql `${query}`;
     }
     const queryEntries = objectEntries(query);
+    // If the query object is empty, return true.
     if (queryEntries.length == 0) {
         return sqlTrue;
     }
     const conditions = [];
     for (const [property, value] of queryEntries) {
+        // Handle logical AND operator
         if (property == '$and') {
             if (queryEntries.length > 1) {
                 throw new Error('only one logical operator per level allowed');
             }
             const andQuery = and(...query.$and.map((item) => convertQuery(item, table, columnDefinitionsMap)));
+            // If $and array is empty or results in no conditions, return true.
             if (isUndefined(andQuery)) {
                 return sqlTrue;
             }
             return andQuery;
         }
+        // Handle logical OR operator
         if (property == '$or') {
             if (queryEntries.length > 1) {
                 throw new Error('only one logical operator per level allowed');
             }
             const orQuery = or(...query.$or.map((item) => convertQuery(item, table, columnDefinitionsMap)));
+            // If $or array is empty or results in no conditions, return true.
             if (isUndefined(orQuery)) {
                 return sqlTrue;
             }
             return orQuery;
         }
+        // Handle logical NOR operator
         if (property == '$nor') {
             if (queryEntries.length > 1) {
                 throw new Error('only one logical operator per level allowed');
             }
             const orQuery = or(...query.$nor.map((item) => convertQuery(item, table, columnDefinitionsMap)));
+            // If $nor array is empty or results in no conditions, return true (NOT false -> true).
             if (isUndefined(orQuery)) {
                 return sqlTrue;
             }
             return not(orQuery);
         }
+        // Map property name to column definition and get the Drizzle column object.
         const columnDef = assertDefinedPass(columnDefinitionsMap.get(property), `Could not map property ${property} to column.`);
         const column = table[columnDef.name];
+        // Get the condition for the current property and value.
         const condition = getCondition(property, value, column);
         conditions.push(condition);
     }
+    // Combine all conditions with AND.
     return and(...conditions);
 }
+/**
+ * Generates a Drizzle SQL condition based on a property, its value, and the corresponding column.
+ * Handles various comparison operators.
+ * @param property The property name (used for error messages).
+ * @param value The value or comparison object for the property.
+ * @param column The Drizzle column object.
+ * @returns A Drizzle SQL condition.
+ * @throws {NotSupportedError} If an unsupported operator like $exists, $text, $geoShape, or $geoDistance is used.
+ * @throws {Error} If the value structure is not a recognized comparison operator.
+ */
 function getCondition(property, value, column) {
     const isPrimitiveValue = isPrimitive(value);
+    // Handle equality ($eq or direct primitive value)
     if (isPrimitiveValue || hasOwnProperty(value, '$eq')) {
         const queryValue = isPrimitiveValue ? value : value.$eq;
         if (queryValue === null) {
-            return isNull(column);
+            return isNull(column); // IS NULL
         }
-        return eq(column, queryValue);
+        return eq(column, queryValue); // = value
     }
+    // Handle inequality ($neq)
     if (hasOwnProperty(value, '$neq')) {
         const queryValue = value.$neq;
         if (queryValue === null) {
-            return isNotNull(column);
+            return isNotNull(column); // IS NOT NULL
         }
-        return ne(column, queryValue);
+        return ne(column, queryValue); // != value
     }
+    // $exists is not supported
     if (hasOwnProperty(value, '$exists')) {
         throw new NotSupportedError('$exists is not supported.');
     }
+    // Handle $in operator
     if (hasOwnProperty(value, '$in')) {
         const queryValue = value.$in;
-        return inArray(column, queryValue);
+        return inArray(column, queryValue); // IN (values)
     }
+    // Handle $nin operator
     if (hasOwnProperty(value, '$nin')) {
         const queryValue = value.$nin;
-        return notInArray(column, queryValue);
+        return notInArray(column, queryValue); // NOT IN (values)
     }
+    // Handle $lt operator
     if (hasOwnProperty(value, '$lt')) {
         const queryValue = value.$lt;
-        return lt(column, queryValue);
+        return lt(column, queryValue); // < value
     }
+    // Handle $lte operator
     if (hasOwnProperty(value, '$lte')) {
         const queryValue = value.$lte;
-        return lte(column, queryValue);
+        return lte(column, queryValue); // <= value
     }
+    // Handle $gt operator
     if (hasOwnProperty(value, '$gt')) {
         const queryValue = value.$gt;
-        return gt(column, queryValue);
+        return gt(column, queryValue); // > value
     }
+    // Handle $gte operator
     if (hasOwnProperty(value, '$gte')) {
         const queryValue = value.$gte;
-        return gte(column, queryValue);
+        return gte(column, queryValue); // >= value
     }
+    // Handle $regex operator (using PostgreSQL regexp_like)
     if (hasOwnProperty(value, '$regex')) {
         const queryValue = value.$regex;
+        // Normalize RegExp or string input
         const regexp = isString(queryValue)
             ? ({ value: queryValue })
             : isRegExp(queryValue)
                 ? ({ flags: queryValue.flags, value: queryValue.source })
                 : ({ flags: queryValue.flags, value: queryValue.pattern });
-        return sql `regexp_like(${column}, ${regexp.value}, ${regexp.flags})`;
+        return sql `regexp_like(${column}, ${regexp.value}, ${regexp.flags})`; // Uses regexp_like function
     }
+    // $text is not supported
     if (hasOwnProperty(value, '$text')) {
         throw new NotSupportedError('$text is not supported.');
     }
+    // $geoShape is not supported
     if (hasOwnProperty(value, '$geoShape')) {
         throw new NotSupportedError('$geoShape is not supported.');
     }
+    // $geoDistance is not supported
     if (hasOwnProperty(value, '$geoDistance')) {
         throw new NotSupportedError('$geoDistance is not supported.');
     }
+    // Throw if the query structure is unrecognized
     throw new Error(`Unsupported query type "${property}".`);
 }