@flusys/nestjs-shared 8.1.5 → 9.1.0

package/README.md

@@ -164,6 +164,23 @@ Generated POST-only endpoints: `/insert`, `/insert-many`, `/get-all`, `/get/:id`
 
 Security levels: `'public'` (no auth), `'jwt'` (token only), `'permission'` (token + action check).
 
+Bodies of `insert` / `insert-many` / `update` / `update-many` / `bulk-upsert` are validated against the concrete Create/Update DTO by `DtoBodyValidationPipe` (`@flusys/nestjs-shared/pipes`, same `DEFAULT_VALIDATION_OPTIONS` as the global pipe: whitelist + forbidNonWhitelisted, no implicit conversion), because a generic `@Body() dto: T` reflects as `Object` and the global pipe skips it. Audit fields are never taken from the client: `SetCreatedByOnBody` / `SetUpdateByOnBody` / `SetDeletedByOnBody` drop any client-sent `createdById` / `updatedById` / `deletedById` and stamp the authenticated user's id (nothing without a user), and the pipe keeps only the audit key the endpoint's interceptor stamps. A `slug` the DTO does not declare is the `Slug` interceptor's and is kept.
+
+### Savepoints in a shared transaction
+
+`withSavepoint(queryRunner, fn)` (`@flusys/nestjs-shared/utils`) runs `fn` inside a savepoint of an
+already-open transaction: a failure rolls back only what `fn` did and is rethrown, so the caller can
+swallow it and keep using the transaction. Use it for any step that may fail without failing the whole
+unit of work - PostgreSQL aborts the entire transaction after one failed statement otherwise.
+
+```typescript
+try {
+  await withSavepoint(queryRunner, () => service.insert(dto, user, { queryRunner }));
+} catch {
+  // skipped; the transaction is still usable
+}
+```
+
 ## 4. Guards and Decorators
 
 ```typescript
@@ -190,6 +207,8 @@ async publicList() { }
 
 `ILoggedUserInfo` fields: `id`, `email`, `name?`, `phone?`, `profilePictureId?`, `companyId?`, `branchId?`.
 
+`matchesPermission(granted, required)` (`@flusys/nestjs-shared/utils`) is the one wildcard matcher (`*`, `prefix.*`) behind `PermissionGuard` and `SharedPermissionCacheService.matchPermission`. For a check inside a handler, `SharedPermissionCacheService.assertPermission(user, code)` throws `InsufficientPermissionsException` (403) unless the user holds the code in their company/branch scope, and `PermissionSystemUnavailableException` when no cache is wired up - never re-implement that check. `PERMISSION_RESOLVER` / `IPermissionResolver` (`@flusys/nestjs-shared/interfaces`) is the provider interface for reading a user's codes in any company/branch scope, including one not loaded into the cache yet; nestjs-iam implements it, feature packages inject it `@Optional()`.
+
 ## 5. Response DTOs
 
 All controllers return one of these shapes:
@@ -232,6 +251,8 @@ throw new ValidationException([{ field: 'email', message: 'Invalid format' }]);
 
 All exceptions produce: `{ success: false, message, messageKey,messageVariables:{} code, _meta }`.
 
+**Keyed diagnostics** - when a service returns a list of problems (plan warnings, validation findings) instead of throwing, each item is a translatable reference, not text. `IMessageRef` (`@flusys/nestjs-shared/interfaces`) is `{ messageKey, messageVariables? }`, built with `messageRef(key, variables?)` (`@flusys/nestjs-shared/utils`). A variable may itself be an `IMessageRef` (the frontend translates it first). `IValidationError` (`errors[]` of an exception) may carry `messageKey`/`messageVariables` instead of `message`.
+
 ## 7. Hybrid Cache
 
 ```typescript
@@ -260,6 +281,8 @@ export class MyService {
 
 `CacheModule.forRoot(true)` connects to Redis automatically when `REDIS_URL` is set; otherwise uses in-memory only.
 
+**Multi-tenant keys:** one cache serves every tenant, so `ApiService` prefixes its keys with the current tenant (`cacheTenant()`), taken from a tenant-aware DataSource provider (`isMultiTenant()` / `getCurrentTenantId()`, which `MultiTenantDataSourceService` implements). A single database is never prefixed. Code that clears or reads these keys through `UtilsService` itself must pass the same tenant: `cacheTenantId(dataSourceProvider)` from `@flusys/nestjs-shared/utils`, or `this.cacheTenant()` inside an `ApiService`.
+
 ## 8. Hybrid Event Bus
 
 The event counterpart of the hybrid cache: one wrapper, transport chosen by configuration.
@@ -603,7 +626,6 @@ import { NOTIFICATION_EVENT_ACTIONS } from '@flusys/nestjs-notification/config';
 NotificationModule.forRoot({
   config: {
     ...dbConfig,
-    enableRealtime: true,
     events: {
       enabled: true,
       actions: [
@@ -713,7 +735,31 @@ export class AuditConsumer {
 actions, so one type fits every handler. `*` matches exactly one segment; `**` (or `#`)
 matches the rest. Handlers are discovered at bootstrap on any singleton provider or
 controller registered with Nest - a REQUEST-scoped provider has no instance at that point,
-so put consumers on singletons. Injecting `EVENT_BUS_INSTANCE` gives direct
+so put consumers on singletons.
+
+**Database work in a handler.** Every handler runs inside the request context of the event's
+actor - tenant, company, user and request id restored from `event.actor`. When
+`MultiTenantDataSourceService` has no HTTP request, it takes the tenant from that context, so a
+handler reaches the right tenant database by resolving any request-scoped service through
+`ModuleRef` - no tenant plumbing:
+
+```typescript
+@Injectable()
+export class InvoiceConsumer {
+  constructor(@Inject(ModuleRef) private readonly moduleRef: ModuleRef) {}
+
+  @OnDomainEvent('form-builder.form_result.submitted')
+  async handle(event: DomainEvent) {
+    const results = await this.moduleRef.resolve(FormResultService, ContextIdFactory.create(), { strict: false });
+    // ...any read or write here hits event.actor.tenantId's database
+  }
+}
+```
+
+Events a handler publishes carry the same actor, so a chain of handlers stays on one tenant.
+The same fallback serves any service resolved through `ModuleRef` during an HTTP request.
+
+Injecting `EVENT_BUS_INSTANCE` gives direct
 `publish` / `subscribe` access - mark it `@Optional()`, so the service still resolves in an
 app that never registers `EventBusModule`.
 

package/classes/api-service.class.d.ts

@@ -25,6 +25,7 @@ export declare abstract class ApiService<CreateDtoT extends object, UpdateDtoT e
     private readonly _dataSourceProvider;
     constructor(entityName: string, cacheManager: HybridCache, utilsService: UtilsService, _loggerName: string, isCacheable: boolean | undefined, moduleName: string, dataSourceProvider: IDataSourceProvider, entity: EntityTarget<EntityT>);
     protected getDataSourceProvider(): IDataSourceProvider;
+    protected cacheTenant(): string | undefined;
     protected ensureDataSourceRepository(): Promise<void>;
     protected resolveRepositories(entities: EntityTarget<any>[]): Promise<Repository<any>[]>;
     insert(dto: CreateDtoT, user: ILoggedUserInfo | null): Promise<InterfaceT>;
@@ -46,6 +47,8 @@ export declare abstract class ApiService<CreateDtoT extends object, UpdateDtoT e
     private handleError;
     private ensureArray;
     private executeInTransaction;
+    protected assertColumnProperty(key: string): void;
+    protected applyEqualsFilter(query: SelectQueryBuilder<EntityT>, key: string, value: unknown): void;
     protected beforeInsertOperation(_dto: CreateDtoT | Array<CreateDtoT>, _user: ILoggedUserInfo | null, _queryRunner: QueryRunner): Promise<void>;
     protected afterInsertOperation(_entity: EntityT[], _dto: CreateDtoT | Array<CreateDtoT>, _user: ILoggedUserInfo | null, _queryRunner: QueryRunner): Promise<void>;
     protected beforeUpdateOperation(_dto: UpdateDtoT | Array<UpdateDtoT>, _user: ILoggedUserInfo | null, _queryRunner: QueryRunner): Promise<void>;

package/constants/permissions.d.ts

@@ -97,6 +97,30 @@ export declare const FORM_RESULT_PERMISSIONS: {
     readonly UPDATE: "form-result.update";
     readonly DELETE: "form-result.delete";
 };
+export declare const ENTITY_DEFINITION_PERMISSIONS: {
+    readonly CREATE: "entity_builder.entity_definition.create";
+    readonly READ: "entity_builder.entity_definition.read";
+    readonly UPDATE: "entity_builder.entity_definition.update";
+    readonly DELETE: "entity_builder.entity_definition.delete";
+};
+export declare const FIELD_DEFINITION_PERMISSIONS: {
+    readonly READ: "entity_builder.field_definition.read";
+    readonly UPDATE: "entity_builder.field_definition.update";
+};
+export declare const FLOW_DEFINITION_PERMISSIONS: {
+    readonly CREATE: "entity_builder.flow_definition.create";
+    readonly READ: "entity_builder.flow_definition.read";
+    readonly UPDATE: "entity_builder.flow_definition.update";
+    readonly DELETE: "entity_builder.flow_definition.delete";
+    readonly TEST: "entity_builder.flow_definition.test";
+    readonly SYSTEM: "entity_builder.flow_definition.system";
+    readonly CODE: "entity_builder.flow_definition.code";
+};
+export declare const ENTITY_BUILDER_ALL_DYNAMIC: {
+    readonly ALL: "entity_builder.entity.*";
+};
+export declare const dynamicEntityPermissionParent: (entityCode: string) => string;
+export declare const dynamicEntityPermission: (entityCode: string, action: "create" | "read" | "update" | "delete") => string;
 export declare const EVENT_PERMISSIONS: {
     readonly CREATE: "event.create";
     readonly READ: "event.read";
@@ -259,6 +283,28 @@ export declare const PERMISSIONS: {
         readonly UPDATE: "form-result.update";
         readonly DELETE: "form-result.delete";
     };
+    readonly ENTITY_DEFINITION: {
+        readonly CREATE: "entity_builder.entity_definition.create";
+        readonly READ: "entity_builder.entity_definition.read";
+        readonly UPDATE: "entity_builder.entity_definition.update";
+        readonly DELETE: "entity_builder.entity_definition.delete";
+    };
+    readonly FIELD_DEFINITION: {
+        readonly READ: "entity_builder.field_definition.read";
+        readonly UPDATE: "entity_builder.field_definition.update";
+    };
+    readonly FLOW_DEFINITION: {
+        readonly CREATE: "entity_builder.flow_definition.create";
+        readonly READ: "entity_builder.flow_definition.read";
+        readonly UPDATE: "entity_builder.flow_definition.update";
+        readonly DELETE: "entity_builder.flow_definition.delete";
+        readonly TEST: "entity_builder.flow_definition.test";
+        readonly SYSTEM: "entity_builder.flow_definition.system";
+        readonly CODE: "entity_builder.flow_definition.code";
+    };
+    readonly ENTITY_BUILDER_ALL_DYNAMIC: {
+        readonly ALL: "entity_builder.entity.*";
+    };
     readonly EVENT: {
         readonly CREATE: "event.create";
         readonly READ: "event.read";

package/exceptions/base-app.exception.d.ts

@@ -1,7 +1,8 @@
 import { HttpException, HttpStatus } from '@nestjs/common';
-export interface IValidationError {
+import { type IMessageRef } from '../interfaces/message-ref.interface.js';
+export interface IValidationError extends Partial<IMessageRef> {
     field: string;
-    message: string;
+    message?: string;
 }
 export interface IBaseAppExceptionOptions {
     message: string;

package/fesm/{509.js → 183.js}

@@ -1,10 +1,10 @@
-import { IsArray, IsBoolean, IsIn, IsNotEmpty, IsNumber, IsObject, IsOptional, IsString, IsUUID, Matches, MaxLength, ValidateNested } from "class-validator";
 import * as __rspack_external__nestjs_swagger_7cd450b5 from "@nestjs/swagger";
 import * as __rspack_external_class_transformer_c5a479fb from "class-transformer";
-export const __rspack_esm_id = 509;
-export const __rspack_esm_ids = [509];
+import * as __rspack_external_class_validator_7b99ef4d from "class-validator";
+export const __rspack_esm_id = 183;
+export const __rspack_esm_ids = [183];
 export const __webpack_modules__ = {
-980(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+746(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 
 // EXPORTS
 __webpack_require__.d(__webpack_exports__, {
@@ -25,8 +25,8 @@ __webpack_require__.d(__webpack_exports__, {
 
 // EXTERNAL MODULE: external "@nestjs/swagger"
 var swagger_ = __webpack_require__(176);
-;// CONCATENATED MODULE: external "class-validator"
-
+// EXTERNAL MODULE: external "class-validator"
+var external_class_validator_ = __webpack_require__(421);
 ;// CONCATENATED MODULE: ./projects/nestjs-shared/src/dtos/delete.dto.ts
 function _ts_decorate(decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -74,7 +74,7 @@ _ts_decorate([
             }
         ]
     }),
-    IsNotEmpty(),
+    (0,external_class_validator_.IsNotEmpty)(),
     _ts_metadata("design:type", Object)
 ], DeleteDto.prototype, "id", void 0);
 _ts_decorate([
@@ -87,8 +87,8 @@ _ts_decorate([
         ],
         example: 'delete'
     }),
-    IsNotEmpty(),
-    IsIn([
+    (0,external_class_validator_.IsNotEmpty)(),
+    (0,external_class_validator_.IsIn)([
         'delete',
         'restore',
         'permanent'
@@ -100,8 +100,8 @@ _ts_decorate([
         description: 'User ID who initiated the deletion (auto-set by interceptor)',
         example: 'f2e9c8d0-7a2a-11eb-9439-0242ac130002'
     }),
-    IsOptional(),
-    IsUUID(),
+    (0,external_class_validator_.IsOptional)(),
+    (0,external_class_validator_.IsUUID)(),
     _ts_metadata("design:type", String)
 ], DeleteDto.prototype, "deletedById", void 0);
 
@@ -138,12 +138,12 @@ pagination_dto_ts_decorate([
         description: 'Number of items per page (default: 10)',
         example: 10
     }),
-    IsOptional(),
+    (0,external_class_validator_.IsOptional)(),
     (0,external_class_transformer_.Transform)(({ value })=>{
         const n = Number(value);
         return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 10;
     }),
-    IsNumber(),
+    (0,external_class_validator_.IsNumber)(),
     pagination_dto_ts_metadata("design:type", Number)
 ], PaginationDto.prototype, "pageSize", void 0);
 pagination_dto_ts_decorate([
@@ -151,12 +151,12 @@ pagination_dto_ts_decorate([
         description: 'Zero-based page index (default: 0)',
         example: 0
     }),
-    IsOptional(),
+    (0,external_class_validator_.IsOptional)(),
     (0,external_class_transformer_.Transform)(({ value })=>{
         const n = Number(value);
         return Number.isFinite(n) && n >= 0 ? Math.trunc(n) : 0;
     }),
-    IsNumber(),
+    (0,external_class_validator_.IsNumber)(),
     pagination_dto_ts_metadata("design:type", Number)
 ], PaginationDto.prototype, "currentPage", void 0);
 
@@ -199,8 +199,8 @@ filter_and_pagination_dto_ts_decorate([
             category: 'electronics'
         }
     }),
-    IsOptional(),
-    IsObject(),
+    (0,external_class_validator_.IsOptional)(),
+    (0,external_class_validator_.IsObject)(),
     filter_and_pagination_dto_ts_metadata("design:type", typeof Record === "undefined" ? Object : Record)
 ], FilterAndPaginationDto.prototype, "filter", void 0);
 filter_and_pagination_dto_ts_decorate([
@@ -212,8 +212,8 @@ filter_and_pagination_dto_ts_decorate([
             pageSize: 10
         }
     }),
-    IsOptional(),
-    ValidateNested(),
+    (0,external_class_validator_.IsOptional)(),
+    (0,external_class_validator_.ValidateNested)(),
     (0,external_class_transformer_.Type)(()=>PaginationDto),
     filter_and_pagination_dto_ts_metadata("design:type", typeof PaginationDto === "undefined" ? Object : PaginationDto)
 ], FilterAndPaginationDto.prototype, "pagination", void 0);
@@ -226,8 +226,8 @@ filter_and_pagination_dto_ts_decorate([
             name: 'ASC'
         }
     }),
-    IsOptional(),
-    IsObject(),
+    (0,external_class_validator_.IsOptional)(),
+    (0,external_class_validator_.IsObject)(),
     filter_and_pagination_dto_ts_metadata("design:type", typeof Record === "undefined" ? Object : Record)
 ], FilterAndPaginationDto.prototype, "sort", void 0);
 filter_and_pagination_dto_ts_decorate([
@@ -243,16 +243,16 @@ filter_and_pagination_dto_ts_decorate([
             'createdAt'
         ]
     }),
-    IsOptional(),
-    IsArray(),
-    IsString({
+    (0,external_class_validator_.IsOptional)(),
+    (0,external_class_validator_.IsArray)(),
+    (0,external_class_validator_.IsString)({
         each: true
     }),
-    Matches(/^[a-zA-Z_][a-zA-Z0-9_]*$/, {
+    (0,external_class_validator_.Matches)(/^[a-zA-Z_][a-zA-Z0-9_]*$/, {
         each: true,
         message: 'Select fields must be valid identifiers (alphanumeric and underscores only)'
     }),
-    MaxLength(64, {
+    (0,external_class_validator_.MaxLength)(64, {
         each: true,
         message: 'Field names must be 64 characters or less'
     }),
@@ -264,8 +264,8 @@ filter_and_pagination_dto_ts_decorate([
         example: false,
         default: false
     }),
-    IsOptional(),
-    IsBoolean(),
+    (0,external_class_validator_.IsOptional)(),
+    (0,external_class_validator_.IsBoolean)(),
     filter_and_pagination_dto_ts_metadata("design:type", Boolean)
 ], FilterAndPaginationDto.prototype, "withDeleted", void 0);
 /**
@@ -286,16 +286,16 @@ filter_and_pagination_dto_ts_decorate([
             'createdAt'
         ]
     }),
-    IsOptional(),
-    IsArray(),
-    IsString({
+    (0,external_class_validator_.IsOptional)(),
+    (0,external_class_validator_.IsArray)(),
+    (0,external_class_validator_.IsString)({
         each: true
     }),
-    Matches(/^[a-zA-Z_][a-zA-Z0-9_]*$/, {
+    (0,external_class_validator_.Matches)(/^[a-zA-Z_][a-zA-Z0-9_]*$/, {
         each: true,
         message: 'Select fields must be valid identifiers (alphanumeric and underscores only)'
     }),
-    MaxLength(64, {
+    (0,external_class_validator_.MaxLength)(64, {
         each: true,
         message: 'Field names must be 64 characters or less'
     }),
@@ -338,9 +338,9 @@ get_by_ids_dto_ts_decorate([
             'uuid-2'
         ]
     }),
-    IsNotEmpty(),
-    IsArray(),
-    IsUUID('all', {
+    (0,external_class_validator_.IsNotEmpty)(),
+    (0,external_class_validator_.IsArray)(),
+    (0,external_class_validator_.IsUUID)('all', {
         each: true
     }),
     get_by_ids_dto_ts_metadata("design:type", Array)
@@ -349,7 +349,7 @@ get_by_ids_dto_ts_decorate([
     (0,swagger_.ApiPropertyOptional)({
         description: 'Select specific fields to return (comma-separated or array)'
     }),
-    IsOptional(),
+    (0,external_class_validator_.IsOptional)(),
     get_by_ids_dto_ts_metadata("design:type", Object)
 ], GetByIdsDto.prototype, "select", void 0);
 
@@ -788,6 +788,12 @@ module.exports = __rspack_external__nestjs_swagger_7cd450b5;
 module.exports = __rspack_external_class_transformer_c5a479fb;
 
 
+},
+421(module) {
+
+module.exports = __rspack_external_class_validator_7b99ef4d;
+
+
 },
 
 };