itlab-internal-services 2.15.7 → 2.16.0

package/dist/modules/services/services.module.js

@@ -0,0 +1,63 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServicesModule = void 0;
+const common_1 = require("@nestjs/common");
+const providers_1 = require("./providers");
+const newsroom_service_1 = require("./providers/newsroom.service");
+const services_module_definition_1 = require("./services.module-definition");
+const serviceProviders = [
+    // Apps
+    newsroom_service_1.NewsroomService,
+    providers_1.EventsService,
+    providers_1.HackschoolService,
+    providers_1.DemoHiveService,
+    providers_1.TechRadarService,
+    providers_1.PodcastsService,
+    providers_1.BooksService,
+    providers_1.TeamService,
+    providers_1.NewsletterService,
+    providers_1.IdeasService,
+    providers_1.LunchRouletteService,
+    // Utils
+    providers_1.AccountsService,
+    providers_1.CommentsService,
+    providers_1.NotificationService,
+    providers_1.MailService,
+    providers_1.SearchService,
+    providers_1.ChangelogService,
+    providers_1.PassService,
+    providers_1.ContentService,
+];
+/**
+ * ServicesModule
+ */
+let ServicesModule = class ServicesModule extends services_module_definition_1.ServicesModuleClass {
+    /**
+     * Synchronously configures the ServicesModule with provided options.
+     *
+     * Extends the base ServicesModuleClass `forRoot` method by exporting the options token.
+     *
+     * @param {ServicesModuleOptions} options - Configuration options for ServicesModule setup.
+     * @returns {DynamicModule} Configured dynamic module.
+     */
+    static forRoot(options) {
+        const moduleDefinition = super.forRoot(options || {});
+        return Object.assign(Object.assign({}, moduleDefinition), { exports: [
+                ...(moduleDefinition.exports || []),
+                {
+                    provide: services_module_definition_1.SERVICES_MODULE_OPTIONS_TOKEN,
+                    useValue: options,
+                },
+            ] });
+    }
+};
+exports.ServicesModule = ServicesModule;
+exports.ServicesModule = ServicesModule = __decorate([
+    (0, common_1.Module)({ providers: serviceProviders, exports: serviceProviders })
+], ServicesModule);

package/dist/pipes/index.d.ts

@@ -1,3 +1,2 @@
-export * from './hub-id.pipe';
-export * from './hub-resource.pipe';
-export * from './mongo-id.pipe';
+export * from './params';
+export * from './queries';

package/dist/pipes/index.js

@@ -14,6 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./hub-id.pipe"), exports);
-__exportStar(require("./hub-resource.pipe"), exports);
-__exportStar(require("./mongo-id.pipe"), exports);
+__exportStar(require("./params"), exports);
+__exportStar(require("./queries"), exports);

package/dist/pipes/params/hub-id.pipe.d.ts

@@ -0,0 +1,22 @@
+import { ValidationOptions } from 'class-validator';
+/**
+ * Parameter decorator that validates a route parameter as a HubId.
+ *
+ * @param {string} parameterName - The name of the route parameter
+ * @returns {ParameterDecorator}
+ */
+export declare function HubIdParam(parameterName: string): ParameterDecorator;
+/**
+ * Decorator to add Swagger metadata and error response for HubId parameters.
+ *
+ * @param {string} parameterName - The route parameter name
+ * @returns {MethodDecorator & ClassDecorator}
+ */
+export declare function ApiHubIdParam(parameterName: string): MethodDecorator & ClassDecorator;
+/**
+ * Decorator to validate DTO properties as HubId using class-validator.
+ *
+ * @param {ValidationOptions} options - Optional validation options
+ * @returns {PropertyDecorator}
+ */
+export declare function IsHubId(options?: ValidationOptions): PropertyDecorator;

package/dist/pipes/{hub-id.pipe.js → params/hub-id.pipe.js}

@@ -1,18 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HubIdParam = HubIdParam;
-exports.ApiHubId = ApiHubId;
+exports.ApiHubIdParam = ApiHubIdParam;
 exports.IsHubId = IsHubId;
 const common_1 = require("@nestjs/common");
 const swagger_1 = require("@nestjs/swagger");
 const class_validator_1 = require("class-validator");
 const itlab_functions_1 = require("itlab-functions");
-const exceptions_1 = require("../exceptions");
+const exceptions_1 = require("../../exceptions");
 /**
- * @class ParseHubIdPipe
- *
  * Pipe that validates and transforms a route parameter into a valid HubId string.
- * Throws a `BadParameterException` if the input does not match the expected ID format.
+ * Throws a `BadParameterException` if the input does not match the expected format.
  */
 class ParseHubIdPipe {
     constructor(parameterName) {
@@ -20,42 +18,41 @@ class ParseHubIdPipe {
     }
     /**
      * @param {unknown} inputValue - Raw route parameter value.
-     * @returns {string} - Validated HubId.
+     * @returns {string} - Validated HubId string.
      * @throws {BadParameterException} - If validation fails.
      */
     transform(inputValue) {
-        if ((0, itlab_functions_1.isHubId)(inputValue)) {
+        if ((0, itlab_functions_1.isHubId)(inputValue))
             return String(inputValue);
-        }
         throw new exceptions_1.BadParameterException(this.parameterName);
     }
 }
 /**
- * Creates a parameter decorator that validates a route parameter as a HubId.
+ * Parameter decorator that validates a route parameter as a HubId.
  *
- * @param {string} parameterName - Name of the parameter to validate.
+ * @param {string} parameterName - The name of the route parameter
  * @returns {ParameterDecorator}
  */
 function HubIdParam(parameterName) {
     return (0, common_1.Param)(parameterName, new ParseHubIdPipe(parameterName));
 }
 /**
- * Combines Swagger metadata and error response for HubId parameters.
+ * Decorator to add Swagger metadata and error response for HubId parameters.
  *
- * @param {string} parameterName - Name of the parameter for docs/errors.
- * @returns {MethodDecorator}
+ * @param {string} parameterName - The route parameter name
+ * @returns {MethodDecorator & ClassDecorator}
  */
-function ApiHubId(parameterName) {
+function ApiHubIdParam(parameterName) {
     return (0, common_1.applyDecorators)((0, swagger_1.ApiParam)({
         name: parameterName,
         example: 'example-hub-id',
-        description: 'A valid HubId string (e.g., kebab-case ID format)',
+        description: 'A valid HubId string (kebab-case ID format).',
     }), (0, exceptions_1.ApiBadParameterResponse)(parameterName));
 }
 /**
- * Decorator for validating DTO properties as HubId using class-validator.
+ * Decorator to validate DTO properties as HubId using class-validator.
  *
- * @param {ValidationOptions} [options] - Optional validation settings.
+ * @param {ValidationOptions} options - Optional validation options
  * @returns {PropertyDecorator}
  */
 function IsHubId(options) {

package/dist/pipes/params/hub-resource.pipe.d.ts

@@ -0,0 +1,22 @@
+import { HubResource } from '../../hub-resource.enum';
+/**
+ * Parameter decorator to validate and transform a route parameter as a HubResource.
+ *
+ * @param {string} parameterName - Route parameter name
+ * @returns {ParameterDecorator}
+ */
+export declare function HubResourceParam(parameterName: string): ParameterDecorator;
+/**
+ * Adds Swagger metadata for HubResource parameters.
+ *
+ * @param {string} parameterName - Parameter name for docs/errors
+ * @returns {MethodDecorator & ClassDecorator}
+ */
+export declare function ApiHubResourceParam(parameterName: string): MethodDecorator & ClassDecorator;
+/**
+ * Type guard to determine if a value is a valid HubResource.
+ *
+ * @param {unknown} value - Value to validate
+ * @returns {boolean} True if the value is a valid HubResource
+ */
+export declare function isHubResource(value: unknown): value is HubResource;

package/dist/pipes/{hub-resource.pipe.js → params/hub-resource.pipe.js}

@@ -1,51 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HubResourceParam = HubResourceParam;
-exports.ApiHubResource = ApiHubResource;
+exports.ApiHubResourceParam = ApiHubResourceParam;
 exports.isHubResource = isHubResource;
 const common_1 = require("@nestjs/common");
 const swagger_1 = require("@nestjs/swagger");
 const class_validator_1 = require("class-validator");
-const exceptions_1 = require("../exceptions");
-const hub_resource_enum_1 = require("../hub-resource.enum");
+const exceptions_1 = require("../../exceptions");
+const hub_resource_enum_1 = require("../../hub-resource.enum");
 /**
- * @class ParseHubResourcePipe
- *
- * Pipe that validates and transforms a route parameter into a valid `HubResource` string.
- * Throws `BadParameterException` for unsupported resource identifiers.
+ * Pipe that validates and transforms a route parameter into a valid HubResource.
+ * Throws BadParameterException for unsupported resource identifiers.
  */
 class ParseHubResourcePipe {
     constructor(parameterName) {
         this.parameterName = parameterName;
     }
     /**
-     * @param {unknown} inputValue - Route parameter to validate.
-     * @returns {string} - Validated HubResource.
-     * @throws {BadParameterException} - If input is invalid.
+     * Transform route parameter into a validated HubResource string.
+     *
+     * @param {unknown} inputValue - Raw route parameter value
+     * @returns {string} Validated HubResource string
+     * @throws {BadParameterException} if input is invalid
      */
     transform(inputValue) {
-        if (isHubResource(inputValue)) {
+        if (isHubResource(inputValue))
             return String(inputValue);
-        }
         throw new exceptions_1.BadParameterException(this.parameterName);
     }
 }
 /**
- * Decorator to validate and transform a route parameter as a HubResource.
+ * Parameter decorator to validate and transform a route parameter as a HubResource.
  *
- * @param {string} parameterName - Name of the parameter to validate.
+ * @param {string} parameterName - Route parameter name
  * @returns {ParameterDecorator}
  */
 function HubResourceParam(parameterName) {
     return (0, common_1.Param)(parameterName, new ParseHubResourcePipe(parameterName));
 }
 /**
- * Adds Swagger metadata and error documentation for HubResource parameters.
+ * Adds Swagger metadata for HubResource parameters.
  *
- * @param {string} parameterName - Parameter name for docs/errors.
+ * @param {string} parameterName - Parameter name for docs/errors
  * @returns {MethodDecorator & ClassDecorator}
  */
-function ApiHubResource(parameterName) {
+function ApiHubResourceParam(parameterName) {
     return (0, common_1.applyDecorators)((0, swagger_1.ApiParam)({
         name: parameterName,
         enum: hub_resource_enum_1.HubResource,
@@ -53,10 +52,10 @@ function ApiHubResource(parameterName) {
     }), (0, exceptions_1.ApiBadParameterResponse)(parameterName));
 }
 /**
- * Determines if a value is a valid HubResource.
+ * Type guard to determine if a value is a valid HubResource.
  *
- * @param {unknown} value - value to validate.
- * @returns {boolean} - True if valid.
+ * @param {unknown} value - Value to validate
+ * @returns {boolean} True if the value is a valid HubResource
  */
 function isHubResource(value) {
     return (0, class_validator_1.isString)(value) && hub_resource_enum_1.HUB_RESOURCES.includes(value);

package/dist/pipes/params/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hub-id.pipe';
+export * from './hub-resource.pipe';
+export * from './mongo-id.pipe';

package/dist/pipes/params/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./hub-id.pipe"), exports);
+__exportStar(require("./hub-resource.pipe"), exports);
+__exportStar(require("./mongo-id.pipe"), exports);

package/dist/pipes/params/mongo-id.pipe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parameter decorator to validate a route parameter as a MongoId.
+ *
+ * @param {string} parameterName - Name of the parameter
+ * @returns {ParameterDecorator}
+ */
+export declare function MongoIdParam(parameterName: string): ParameterDecorator;
+/**
+ * Adds Swagger metadata for MongoId parameters.
+ *
+ * @param {string} parameterName - Parameter name for docs/errors
+ * @param {string} description - Optional custom description
+ * @returns {MethodDecorator & ClassDecorator}
+ */
+export declare function ApiMongoIdParam(parameterName: string, description?: string): MethodDecorator & ClassDecorator;

package/dist/pipes/params/mongo-id.pipe.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoIdParam = MongoIdParam;
+exports.ApiMongoIdParam = ApiMongoIdParam;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+const exceptions_1 = require("../../exceptions");
+/**
+ * Pipe that validates and transforms a route parameter into a MongoDB ObjectId string.
+ * Throws BadParameterException if the input is not a valid ObjectId.
+ */
+class ParseMongoIdPipe {
+    constructor(parameterName) {
+        this.parameterName = parameterName;
+    }
+    /**
+     * Transform route parameter into validated Mongo ObjectId string.
+     *
+     * @param {unknown} inputValue - Route parameter value
+     * @returns {string} Validated Mongo ObjectId string
+     * @throws {BadParameterException} if inputValue is invalid
+     */
+    transform(inputValue) {
+        if ((0, class_validator_1.isMongoId)(inputValue))
+            return String(inputValue);
+        throw new exceptions_1.BadParameterException(this.parameterName);
+    }
+}
+/**
+ * Parameter decorator to validate a route parameter as a MongoId.
+ *
+ * @param {string} parameterName - Name of the parameter
+ * @returns {ParameterDecorator}
+ */
+function MongoIdParam(parameterName) {
+    return (0, common_1.Param)(parameterName, new ParseMongoIdPipe(parameterName));
+}
+/**
+ * Adds Swagger metadata for MongoId parameters.
+ *
+ * @param {string} parameterName - Parameter name for docs/errors
+ * @param {string} description - Optional custom description
+ * @returns {MethodDecorator & ClassDecorator}
+ */
+function ApiMongoIdParam(parameterName, description) {
+    return (0, common_1.applyDecorators)((0, swagger_1.ApiParam)({
+        name: parameterName,
+        example: '507f1f77bcf86cd799439011',
+        description: description || `A valid MongoDB ObjectId for the "${parameterName}" parameter.`,
+    }), (0, exceptions_1.ApiBadParameterResponse)(parameterName));
+}

package/dist/pipes/queries/index.d.ts

@@ -0,0 +1,3 @@
+export * from './mongo-ids.pipe';
+export * from './optional-boolean.pipe';
+export * from './optional-include-drafts.pipe';

package/dist/pipes/queries/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./mongo-ids.pipe"), exports);
+__exportStar(require("./optional-boolean.pipe"), exports);
+__exportStar(require("./optional-include-drafts.pipe"), exports);

package/dist/pipes/queries/mongo-ids.pipe.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MongoIdsQuery
+ *
+ * Creates a NestJS @Query decorator that automatically applies the
+ * ParseMongoIdsPipe. Controller methods will receive an array
+ * of valid MongoDB ID strings, even if the query parameter is omitted.
+ *
+ * @param {string} propertyName - The name of the query parameter to bind.
+ * @returns {ParameterDecorator} - A NestJS parameter decorator for controller methods.
+ */
+export declare function MongoIdsQuery(propertyName: string): ParameterDecorator;
+/**
+ * ApiMongoIdsQuery
+ *
+ * Swagger/OpenAPI documentation decorator for optional Mongo ID query parameters.
+ * Marks the query as optional and documents it with a clear description.
+ *
+ * @param {string} propertyName - The query parameter name to display in Swagger docs.
+ * @param {string} [description] - Optional human-readable explanation for the parameter.
+ * @returns {MethodDecorator & ClassDecorator} - A combined decorator for use on routes or controllers.
+ */
+export declare function ApiMongoIdsQuery(propertyName: string, description?: string): MethodDecorator & ClassDecorator;

package/dist/pipes/queries/mongo-ids.pipe.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoIdsQuery = MongoIdsQuery;
+exports.ApiMongoIdsQuery = ApiMongoIdsQuery;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+/**
+ * ParseMongoIdsPipe
+ *
+ * A NestJS pipe that ensures query parameters expected as MongoDB IDs
+ * are filtered and validated. It safely converts an array of raw query
+ * values into an array of valid MongoDB ID strings.
+ *
+ * This helps controllers avoid manual type-checking and validation,
+ * improving consistency and reducing the chance of runtime errors.
+ */
+class ParseMongoIdsPipe {
+    /**
+     * Converts the raw input value into an array of valid MongoDB ID strings.
+     *
+     * @param {unknown} inputValue - The raw value received from the request query string.
+     * @returns {string[]} - Array of valid MongoDB IDs; returns empty array if input is invalid.
+     */
+    transform(inputValue) {
+        const inputValues = Array.isArray(inputValue) ? inputValue : [inputValue];
+        return inputValues.filter((value) => (0, class_validator_1.isMongoId)(value)).map(String);
+    }
+}
+/**
+ * MongoIdsQuery
+ *
+ * Creates a NestJS @Query decorator that automatically applies the
+ * ParseMongoIdsPipe. Controller methods will receive an array
+ * of valid MongoDB ID strings, even if the query parameter is omitted.
+ *
+ * @param {string} propertyName - The name of the query parameter to bind.
+ * @returns {ParameterDecorator} - A NestJS parameter decorator for controller methods.
+ */
+function MongoIdsQuery(propertyName) {
+    return (0, common_1.Query)(propertyName, new ParseMongoIdsPipe());
+}
+/**
+ * ApiMongoIdsQuery
+ *
+ * Swagger/OpenAPI documentation decorator for optional Mongo ID query parameters.
+ * Marks the query as optional and documents it with a clear description.
+ *
+ * @param {string} propertyName - The query parameter name to display in Swagger docs.
+ * @param {string} [description] - Optional human-readable explanation for the parameter.
+ * @returns {MethodDecorator & ClassDecorator} - A combined decorator for use on routes or controllers.
+ */
+function ApiMongoIdsQuery(propertyName, description) {
+    return (0, common_1.applyDecorators)((0, swagger_1.ApiQuery)({
+        required: true,
+        name: propertyName,
+        description: description || `Array of MongoDB IDs`,
+        default: false,
+    }));
+}

package/dist/pipes/queries/optional-boolean.pipe.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OptionalBooleanQuery
+ *
+ * Factory function that creates a NestJS query decorator for boolean flags.
+ * It automatically applies the `ParseOptionalBooleanPipe`, so controller methods
+ * receive properly typed booleans instead of raw strings.
+ *
+ * This prevents controllers from having to manually parse query string values
+ * and keeps intent clear at the method signature level.
+ *
+ * @param {string} propertyName - The name of the query parameter to bind.
+ * @returns {ParameterDecorator} - A NestJS parameter decorator for controller methods.
+ */
+export declare function OptionalBooleanQuery(propertyName: string): ParameterDecorator;
+/**
+ * ApiOptionalBooleanQuery
+ *
+ * Swagger documentation helper for optional boolean query parameters.
+ * By applying this decorator, the parameter will appear in API documentation
+ * with clear details, marked as optional, and defaulting to `false`.
+ *
+ * This ensures consumers of the API understand that the flag exists,
+ * what it controls, and that its omission is safe.
+ *
+ * @param {string} propertyName - The query parameter name to display in Swagger docs.
+ * @param {string} [description] - Optional human-readable explanation for the parameter.
+ * @returns {MethodDecorator & ClassDecorator} - A combined decorator for use on routes or controllers.
+ */
+export declare function ApiOptionalBooleanQuery(propertyName: string, description?: string): MethodDecorator & ClassDecorator;

package/dist/pipes/queries/optional-boolean.pipe.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OptionalBooleanQuery = OptionalBooleanQuery;
+exports.ApiOptionalBooleanQuery = ApiOptionalBooleanQuery;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+// Standardize boolean input formats (string, number, or boolean)
+const trueValues = [true, 'true', 1, '1', 'yes', 'on'];
+/**
+ * ParseOptionalBooleanPipe
+ *
+ * Custom NestJS pipe that converts a query parameter into a boolean value.
+ * This is particularly useful for endpoints where a query string value
+ * (e.g., "true", "1", "false", "0") should be interpreted as a boolean flag.
+ *
+ * The pipe ensures consistent controller input by avoiding raw strings,
+ * which helps prevent subtle bugs where "true" is treated as truthy but
+ * not equal to `true` (boolean).
+ */
+class ParseOptionalBooleanPipe {
+    /**
+     * Converts the raw input value into a boolean.
+     *
+     * Accepts `true`, `"true"`, `1`, `"1"`, `"yes"` or `"on"` as `true`.
+     * All other values (including `undefined`, `"false"`, `"0"`, or unexpected input) are interpreted as `false`.
+     *
+     * @param {unknown} inputValue - The raw value received from the request query string.
+     * @returns {boolean} - `true` if the input explicitly indicates truth, otherwise `false`.
+     */
+    transform(inputValue) {
+        return trueValues.some((trueValue) => trueValue === inputValue);
+    }
+}
+/**
+ * OptionalBooleanQuery
+ *
+ * Factory function that creates a NestJS query decorator for boolean flags.
+ * It automatically applies the `ParseOptionalBooleanPipe`, so controller methods
+ * receive properly typed booleans instead of raw strings.
+ *
+ * This prevents controllers from having to manually parse query string values
+ * and keeps intent clear at the method signature level.
+ *
+ * @param {string} propertyName - The name of the query parameter to bind.
+ * @returns {ParameterDecorator} - A NestJS parameter decorator for controller methods.
+ */
+function OptionalBooleanQuery(propertyName) {
+    return (0, common_1.Query)(propertyName, new ParseOptionalBooleanPipe());
+}
+/**
+ * ApiOptionalBooleanQuery
+ *
+ * Swagger documentation helper for optional boolean query parameters.
+ * By applying this decorator, the parameter will appear in API documentation
+ * with clear details, marked as optional, and defaulting to `false`.
+ *
+ * This ensures consumers of the API understand that the flag exists,
+ * what it controls, and that its omission is safe.
+ *
+ * @param {string} propertyName - The query parameter name to display in Swagger docs.
+ * @param {string} [description] - Optional human-readable explanation for the parameter.
+ * @returns {MethodDecorator & ClassDecorator} - A combined decorator for use on routes or controllers.
+ */
+function ApiOptionalBooleanQuery(propertyName, description) {
+    return (0, common_1.applyDecorators)((0, swagger_1.ApiQuery)({
+        required: false,
+        default: false,
+        name: propertyName,
+        description: description || `Optional boolean flag`,
+        schema: { type: 'boolean', default: false, nullable: true },
+    }));
+}

package/dist/pipes/queries/optional-include-drafts.pipe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OptionalIncludeDraftsQuery
+ *
+ * NestJS parameter decorator for extracting the `includeDrafts` query parameter
+ * from incoming requests. The decorator applies the `ParseOptionalBooleanPipe`
+ * internally (through `OptionalBooleanQuery`) to ensure the controller receives
+ * a properly typed boolean rather than a raw string.
+ *
+ * This avoids boilerplate parsing logic inside controllers and makes the
+ * method signature self-documenting — any reader can immediately see that
+ * `includeDrafts` is expected as a boolean flag.
+ *
+ * @returns {ParameterDecorator} - A query parameter decorator for use on controller methods.
+ */
+export declare function OptionalIncludeDraftsQuery(): ParameterDecorator;
+/**
+ * ApiOptionalIncludeDraftsQuery
+ *
+ * Swagger documentation decorator for the `includeDrafts` query parameter.
+ * This marks the parameter as optional, provides a clear description, and
+ * specifies a default value of `false`. Adding this ensures that API
+ * consumers can see the parameter in the generated docs and understand
+ * its behavior without digging into code.
+ *
+ * @returns {MethodDecorator & ClassDecorator} - A decorator usable on routes or controllers
+ * to enhance Swagger-generated documentation.
+ */
+export declare function ApiOptionalIncludeDraftsQuery(): MethodDecorator & ClassDecorator;

package/dist/pipes/queries/optional-include-drafts.pipe.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OptionalIncludeDraftsQuery = OptionalIncludeDraftsQuery;
+exports.ApiOptionalIncludeDraftsQuery = ApiOptionalIncludeDraftsQuery;
+const optional_boolean_pipe_1 = require("./optional-boolean.pipe");
+const propertyName = 'includeDrafts';
+/**
+ * OptionalIncludeDraftsQuery
+ *
+ * NestJS parameter decorator for extracting the `includeDrafts` query parameter
+ * from incoming requests. The decorator applies the `ParseOptionalBooleanPipe`
+ * internally (through `OptionalBooleanQuery`) to ensure the controller receives
+ * a properly typed boolean rather than a raw string.
+ *
+ * This avoids boilerplate parsing logic inside controllers and makes the
+ * method signature self-documenting — any reader can immediately see that
+ * `includeDrafts` is expected as a boolean flag.
+ *
+ * @returns {ParameterDecorator} - A query parameter decorator for use on controller methods.
+ */
+function OptionalIncludeDraftsQuery() {
+    return (0, optional_boolean_pipe_1.OptionalBooleanQuery)(propertyName);
+}
+/**
+ * ApiOptionalIncludeDraftsQuery
+ *
+ * Swagger documentation decorator for the `includeDrafts` query parameter.
+ * This marks the parameter as optional, provides a clear description, and
+ * specifies a default value of `false`. Adding this ensures that API
+ * consumers can see the parameter in the generated docs and understand
+ * its behavior without digging into code.
+ *
+ * @returns {MethodDecorator & ClassDecorator} - A decorator usable on routes or controllers
+ * to enhance Swagger-generated documentation.
+ */
+function ApiOptionalIncludeDraftsQuery() {
+    return (0, optional_boolean_pipe_1.ApiOptionalBooleanQuery)(propertyName, 'Boolean flag to indicate whether draft resources should be included in the response.');
+}