@tstdl/base 0.92.123 → 0.92.125

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.d.ts

@@ -1,12 +1,32 @@
+/**
+ * @module
+ * Provides configuration options and setup for the ORM module.
+ * Allows configuring database connection, repository settings, and encryption secrets
+ * via dependency injection.
+ */
 import type { PoolConfig } from 'pg';
 import { EntityRepositoryConfig } from './repository.js';
+/**
+ * Configuration class for the database connection.
+ * Holds the `pg.PoolConfig`.
+ */
 export declare class DatabaseConfig {
+    /** Optional PostgreSQL pool configuration. */
     connection?: PoolConfig;
 }
+/**
+ * Options for configuring the ORM module using `configureOrm`.
+ */
 export type OrmModuleOptions = {
+    /** Optional PostgreSQL pool configuration. */
     connection?: PoolConfig;
+    /** Optional configuration for entity repositories. */
     repositoryConfig?: EntityRepositoryConfig;
 };
+/**
+ * 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 declare function configureOrm(options: OrmModuleOptions & {
     encryptionSecret?: Uint8Array;
 }): void;

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.d.ts

@@ -1,4 +1,21 @@
+/**
+ * @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 { SQL } from 'drizzle-orm';
 import type { Query } from '../query.js';
 import type { ColumnDefinition, PgTableFromType } from './types.js';
+/**
+ * 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 declare function convertQuery(query: Query, table: PgTableFromType, columnDefinitionsMap: Map<string, ColumnDefinition>): SQL;

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}".`);
 }