@flusys/nestjs-shared 9.1.1 → 9.2.0

package/README.md

@@ -164,8 +164,28 @@ Generated POST-only endpoints: `/insert`, `/insert-many`, `/get-all`, `/get/:id`
 
 Security levels: `'public'` (no auth), `'jwt'` (token only), `'permission'` (token + action check).
 
+An endpoint left out of a per-endpoint `security` map is never public: `insertMany` / `updateMany` take
+the security of `insert` / `update`, `getByIds` / `getByFilter` that of `getById` (else `getAll`), and
+`bulkUpsert` requires both `insert` and `update` (their permissions combined with AND). Anything still
+unset - including a controller with no `security` option at all - requires a JWT. List an endpoint as
+`'public'` explicitly to open it.
+
+`PermissionGuard` fails closed on an empty requirement: `@RequirePermission()` with no codes, `''`, `[]`
+or `{ permissions: [] }` is a 403 for every user (and a 401 without one), never a pass.
+
+`IdempotencyInterceptor` (on `insert` / `insert-many`) replays the stored response for a repeated
+`X-Idempotency-Key` only to the same tenant, user and endpoint, and releases the key when the request
+fails, so a retry after an error is processed again rather than answered with 409.
+
 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.
 
+### Company scoping
+
+`applyCompanyFilter(query, { isCompanyFeatureEnabled, entityAlias }, user)`, `buildCompanyWhereCondition(where, enabled, user)`
+and `validateCompanyOwnership(entity, user, enabled, name)` (`@flusys/nestjs-shared/utils`) keep a user to their own company
+when the company feature is on. A logged-in user without a `companyId` matches nothing (and may not use another company's
+row) - never every company's data. Passing no user at all (`null` / `undefined`) is a system call and is left unscoped.
+
 ### Savepoints in a shared transaction
 
 `withSavepoint(queryRunner, fn)` (`@flusys/nestjs-shared/utils`) runs `fn` inside a savepoint of an
@@ -259,33 +279,88 @@ All exceptions produce: `{ success: false, message, messageKey,messageVariables:
 
 ## 7. Hybrid Cache
 
-```typescript
-import { HybridCache } from '@flusys/nestjs-shared/classes';
+`CacheModule.forRoot(isGlobal = true, memoryTtl = 60_000, memorySize = 5000)` provides one `HybridCache` under `CACHE_INSTANCE`. The store is chosen by `USE_CACHE_LABEL`:
+
+| `USE_CACHE_LABEL`  | Data store                                 | Stamps / claims             | Use when                                   |
+| ------------------ | ------------------------------------------ | --------------------------- | ------------------------------------------ |
+| `memory` (default) | in-process LRU                             | in-process                  | **one instance only** - nothing is shared  |
+| `redis`            | Redis (`REDIS_URL`)                        | Redis (`SET NX`)            | several instances                          |
+| `hybrid`           | in-process L1 + Redis L2                   | Redis (`SET NX`)            | several instances, hot immutable reads     |
+
+`memory` mode is single-instance only: invalidations, claims and one-time values live in the process, so a second instance never sees them. Run more than one instance with `redis` or `hybrid`.
+
+### API
+
+| Method                                  | Meaning                                                                                                     |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `get(key, { skipMemory? })`             | Read; L1 first in `hybrid` unless `skipMemory`. Only `undefined` is a miss.                                 |
+| `set(key, value, ttl?, { skipMemory? })`| Write with `ttl` ms, else the default (`memoryTtl`) - on every layer, Redis included, so nothing lives forever. |
+| `del(key)`                              | Delete from every layer (other instances' L1 copies are **not** reached).                                  |
+| `getStamp(name)` / `bumpStamp(name)`    | Version stamp: created at random when absent, moved by `bumpStamp` atomically for every instance.           |
+| `claim(name, ttl)` / `releaseClaim(name)` | Atomic first-wins lock (Redis `SET NX PX`); `true` only for the first caller while it lives.              |
+| `take(key, ttl)`                        | Atomic read-and-delete of a one-time value: exactly one caller across all instances receives it.           |
 
+### Rules
+
+1. **L1 values must be immutable for their key.** In `hybrid` mode the in-process layer of other instances is never invalidated, so `del` or an overwrite does not reach them. A key whose value changes in place - sessions, revocation markers, one-time state, counters, flags - must use `{ skipMemory: true }` on **both** `get` and `set`.
+2. **One-time values use `take`**, never `get` + `del` (two concurrent requests would both read the value). The claim behind `take` is per value, so a fresh value stored under the same key (a resent code) can be taken again.
+3. **Locks and de-duplication use `claim`** and release it when done; the ttl bounds how long a crashed instance holds it.
+4. **Invalidate by stamp, after commit.** Embed `getStamp()` in data keys and `bumpStamp()` to invalidate - never track key lists. Bump **after** the transaction commits: a bump inside it lets a concurrent reader re-cache old rows under the new stamp.
+
+```typescript
 @Injectable()
 export class MyService {
-  constructor(@Inject('CACHE_INSTANCE') private cache: HybridCache) {}
-
-  async getData(key: string) {
-    const cached = await this.cache.get(key);
-    if (cached) return cached;
-    const data = await this.fetchFromDb();
-    await this.cache.set(key, data, 3600); // TTL in seconds
-    return data;
-  }
+  constructor(@Inject(CACHE_INSTANCE) private readonly cache: HybridCache) {}
 
-  async invalidate(key: string) {
-    await this.cache.delete(key);
+  async consumeResetToken(tokenHash: string) {
+    return this.cache.take<IResetState>(`reset:${tokenHash}`, 15 * 60_000);
   }
-  async invalidatePrefix(prefix: string) {
-    await this.cache.deleteByPrefix(prefix);
+
+  async runOnce(jobId: string, work: () => Promise<void>) {
+    if (!(await this.cache.claim(`job:${jobId}`, 60_000))) return;
+    try {
+      await work();
+    } finally {
+      await this.cache.releaseClaim(`job:${jobId}`);
+    }
   }
 }
 ```
 
-`CacheModule.forRoot(true)` connects to Redis automatically when `REDIS_URL` is set; otherwise uses in-memory only.
+### ApiService caching
 
-**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`.
+With `isCacheable = true`, `findById` and `getAll` are cached under `[tenant_<id>_]entity_<name>_<id_x|all>_<stamp>_<sha256(query)>`:
+
+- The stamp (one per entity in `cacheDependencies()`, joined) is read **before** the query, so a write that commits mid-read moves the stamp and the stale result lands under a key no later read asks for.
+- Cache failures on the read path (stamp, get, set) are logged and the read goes to the database.
+- `insert` / `insertMany` / `update` / `updateMany` / `bulkUpsert` / `delete` call `invalidateCache()` after commit - whether the service is cacheable or not, because another service may cache the same entity. A failed invalidation is logged, never fails the committed write.
+- `after*Operation` hooks run **before** commit - never invalidate in them.
+
+```typescript
+// A cached read that joins or embeds another entity must depend on it
+protected override cacheDependencies(): string[] {
+  return [this.entityName, TASK_MANAGER_EVENT_ENTITIES.TASK];
+}
+
+// A service that writes another entity directly (repository, query runner, cascade) bumps it after commit
+await this.utilsService.clearCache(OTHER_ENTITY_NAME, this.cacheManager, this.cacheTenant());
+```
+
+`UtilsService`: `getCacheStamp(cache, entityNames, tenantId?)`, `getCacheKey(entityName, params, entityId, tenantId, stamp)`, `clearCache(entityName, cache, tenantId?)` (bumps the stamp; logs instead of throwing).
+
+A cached result must depend only on the SQL it ran: anything else (current time, config, the user beyond what the query filters on, feature flags) belongs in the key or the read must not be cached.
+
+**Multi-tenant keys:** one cache serves every tenant, so `ApiService` prefixes its keys and stamps 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 calls `UtilsService` itself must pass the same tenant: `cacheTenantId(dataSourceProvider)` from `@flusys/nestjs-shared/utils`, or `this.cacheTenant()` inside an `ApiService`.
+
+### Permission cache
+
+A user's codes are cached under `[tenant:<id>:]<format>:v:<user stamp>` - the scope key from `buildPermissionCacheKey` (user, or company + branch with `enableCompanyFeature`) plus one stamp per user. `resolvePermissionCacheKey(cache, options, config)` gives the key (resolve it before reading grants from the database, write under that same key); `invalidatePermissionCache(cache, userId, config)` bumps the stamp and drops every company / branch scope of the user on every instance. The tenant prefix is added only when `config.multiTenant` is set - a single database ignores a tenant header.
+
+`SharedPermissionCacheService.getPermissions` reads that key and, on a miss (first request, expiry, invalidation), falls back to `PERMISSION_RESOLVER` when it is provided (nestjs-iam); without one, a miss is "no permissions". `setPermissions` writes the current key; `clearPermissions` bumps the user stamp.
+
+### Idempotency
+
+`IdempotencyInterceptor` keys `X-Idempotency-Key` by tenant, user and endpoint. A stored response is replayed (read with `skipMemory`); otherwise the request `claim`s the key (409 `system.duplicate.request` while another request holds it), stores its response for 24 h with `skipMemory`, and releases the claim on success and on error so a failed request can be retried.
 
 ## 8. Hybrid Event Bus
 
@@ -412,7 +487,8 @@ so `enabled: false` silences the module everywhere. `delete` and `restore` carry
 there is no row left to attach.
 
 Payloads are walked before they leave the process: credential-like fields become
-`[REDACTED]`, a relation that loops back becomes `[CIRCULAR]`, anything past 8 levels deep
+`[REDACTED]` (matched case and separator blind - `apiKey`, `api_key`, `X-API-KEY`,
+`private-key` alike; `@LogAction({ includeParams: true })` uses the same redaction), a relation that loops back becomes `[CIRCULAR]`, anything past 8 levels deep
 becomes `[TRUNCATED]`, and a Buffer becomes `[BINARY]`. Saved TypeORM rows with
 bidirectional relations are therefore safe to publish. The `config` blob on a
 `storageConfig` or `emailConfig` row is redacted whole - S3, Azure, SFTP and SMTP
@@ -807,6 +883,31 @@ async listForCurrentBranch(query: SelectQueryBuilder<Invoice>, user: ILoggedUser
 }
 ```
 
+## 10. Expressions
+
+A JSON expression tree any package can store and evaluate (`@flusys/nestjs-shared/interfaces` for the types, `/utils` for the engine). Pure functions, no Nest dependencies; every slot that takes a value takes another expression.
+
+| `type` | Shape | Result |
+| --- | --- | --- |
+| `literal` | `{ value }` | the value |
+| `field_ref` | `{ ref }` | `ctx.resolveRef(ref)` |
+| `arithmetic` | `{ op, operands[] }` | `sum`, `subtract`, `multiply`, `divide`, `modulo`, `power`, `average`, `min`, `max`; blank operands count as 0 |
+| `concat` | `{ parts[], separator? }` | joined text; with a separator, blank parts are skipped |
+| `template` | `{ template }` | `"{{ ref }}"` placeholders filled through `resolveRef` |
+| `function` | `{ name, args[] }` | see `EXPRESSION_FUNCTIONS`: text (incl. `REGEX_EXTRACT` / `REGEX_REPLACE` / `REGEX_TEST`), number, date (UTC) and `COALESCE` |
+| `if` | `{ condition, whenTrue, whenFalse? }` | `condition` is an AND / OR group of `{ left, comparison, right? }`, groups nest |
+
+```typescript
+import { evaluateExpression, assertValidExpression, isExpressionError } from '@flusys/nestjs-shared/utils';
+
+assertValidExpression(expr, { isKnownRef: (ref) => fieldIds.has(ref) }); // on save
+const value = evaluateExpression(expr, { resolveRef: (ref) => data[ref] });
+```
+
+- Errors are `ExpressionError { code, variables }` (plain, not HTTP) - map `code` to your own message key; check with `isExpressionError()`, not `instanceof`.
+- Limits (`EXPRESSION_LIMITS`): depth 16, 500 nodes, 4000-char templates, 100k-char text results.
+- Regex runs on RE2 via `safeRegexProblem()` / `compileSafeRegex()` (`SAFE_REGEX_LIMITS`): linear time, pattern length / counted-repeat caps. Never `new RegExp` on author input.
+
 ## License
 
 MIT © FLUSYS

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

@@ -25,6 +25,7 @@ export declare function createApiController<CreateDtoT extends object, UpdateDto
     readonly enabledEndpoints: ApiEndpoint[] | "all";
     service: ServiceT;
     isEnabled(endpoint: ApiEndpoint): boolean;
+    assertEnabled(endpoint: ApiEndpoint): void;
     insert(addDto: CreateDtoT, user: ILoggedUserInfo | null): Promise<SingleResponseDto<ResponseDtoT>>;
     insertMany(addDto: CreateDtoT[], user: ILoggedUserInfo | null): Promise<BulkResponseDto<ResponseDtoT>>;
     getById(id: string, body: GetByIdBodyDto, user: ILoggedUserInfo | null): Promise<SingleResponseDto<ResponseDtoT>>;

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

@@ -23,9 +23,16 @@ export declare abstract class ApiService<CreateDtoT extends object, UpdateDtoT e
     private repositoryInitialized;
     private readonly _entity;
     private readonly _dataSourceProvider;
+    private readonly logger;
     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 cacheDependencies(): string[];
+    protected bypassListCache(_filterAndPaginationDto: FilterAndPaginationDto): boolean;
+    invalidateCache(): Promise<void>;
+    private readCacheStamp;
+    private readCached;
+    private writeCached;
     protected ensureDataSourceRepository(): Promise<void>;
     protected resolveRepositories(entities: EntityTarget<any>[]): Promise<Repository<any>[]>;
     insert(dto: CreateDtoT, user: ILoggedUserInfo | null): Promise<InterfaceT>;
@@ -42,8 +49,6 @@ export declare abstract class ApiService<CreateDtoT extends object, UpdateDtoT e
     delete(option: DeleteDto, user: ILoggedUserInfo | null): Promise<null>;
     protected publishLifecycleEvents(groups: IEventGroup<EntityT>[], user: ILoggedUserInfo | null): Promise<void>;
     protected publishDomainAction(action: string, input?: Omit<IPublishDomainEventInput, 'module' | 'entity' | 'action'>): Promise<void>;
-    clearCacheForAll(): Promise<void>;
-    clearCacheForId(entities: EntityT[]): Promise<void>;
     private handleError;
     private ensureArray;
     private executeInTransaction;

package/classes/hybrid-cache.class.d.ts

@@ -1,10 +1,23 @@
+export type CacheMode = 'memory' | 'redis' | 'hybrid';
+export interface ICacheAccessOptions {
+    skipMemory?: boolean;
+}
 export declare class HybridCache {
+    private readonly mode;
+    private readonly defaultTtl;
     private memory?;
     private redis?;
+    private redisStore?;
+    private localAtomic?;
     constructor(memoryTtl?: number, memorySize?: number);
-    get<T>(key: string): Promise<T | undefined>;
-    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    getMode(): CacheMode;
+    get<T>(key: string, options?: ICacheAccessOptions): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttl?: number, options?: ICacheAccessOptions): Promise<void>;
     del(key: string): Promise<void>;
-    reset(): Promise<void>;
-    resetL2(): Promise<void>;
+    getStamp(name: string): Promise<string>;
+    bumpStamp(name: string): Promise<void>;
+    claim(name: string, ttl: number): Promise<boolean>;
+    releaseClaim(name: string): Promise<void>;
+    take<T>(key: string, ttl: number): Promise<T | undefined>;
+    private rawKey;
 }

package/constants/index.d.ts

@@ -8,6 +8,7 @@ export declare const EVENT_BUS_MODULE_OPTIONS = "EVENT_BUS_MODULE_OPTIONS";
 export declare const IDEMPOTENCY_KEY_HEADER = "x-idempotency-key";
 export declare const REQUEST_ID_HEADER = "x-request-id";
 export declare const CLIENT_TYPE_HEADER = "x-client-type";
+export declare const TENANT_ID_PATTERN: RegExp;
 export declare const PERMISSIONS_CACHE_PREFIX = "my-permissions";
 export declare const IDEMPOTENCY_CACHE_PREFIX = "idempotency";
 export declare const DEFAULT_EVENT_EXCHANGE = "flusys.events";

package/constants/permissions.d.ts

@@ -51,6 +51,9 @@ export declare const COMPANY_ACTION_PERMISSIONS: {
     readonly READ: "company-action.read";
     readonly ASSIGN: "company-action.assign";
 };
+export declare const CROSS_COMPANY_PERMISSIONS: {
+    readonly ASSIGN: "cross-company.assign";
+};
 export declare const FILE_PERMISSIONS: {
     readonly CREATE: "file.create";
     readonly READ: "file.read";
@@ -239,6 +242,9 @@ export declare const PERMISSIONS: {
         readonly READ: "company-action.read";
         readonly ASSIGN: "company-action.assign";
     };
+    readonly CROSS_COMPANY: {
+        readonly ASSIGN: "cross-company.assign";
+    };
     readonly FILE: {
         readonly CREATE: "file.create";
         readonly READ: "file.read";
@@ -258,6 +264,9 @@ export declare const PERMISSIONS: {
         readonly UPDATE: "storage-config.update";
         readonly DELETE: "storage-config.delete";
     };
+    readonly UPLOAD_CONFIG: {
+        readonly DELETE: "upload-config.delete";
+    };
     readonly EMAIL_CONFIG: {
         readonly CREATE: "email-config.create";
         readonly READ: "email-config.read";

package/fesm/183.js

@@ -4,7 +4,7 @@ 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__ = {
-746(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
+3746(__unused_rspack_module, __webpack_exports__, __webpack_require__) {
 
 // EXPORTS
 __webpack_require__.d(__webpack_exports__, {
@@ -24,9 +24,9 @@ __webpack_require__.d(__webpack_exports__, {
 });
 
 // EXTERNAL MODULE: external "@nestjs/swagger"
-var swagger_ = __webpack_require__(176);
+var swagger_ = __webpack_require__(6176);
 // EXTERNAL MODULE: external "class-validator"
-var external_class_validator_ = __webpack_require__(421);
+var external_class_validator_ = __webpack_require__(5421);
 ;// 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;
@@ -106,7 +106,7 @@ _ts_decorate([
 ], DeleteDto.prototype, "deletedById", void 0);
 
 // EXTERNAL MODULE: external "class-transformer"
-var external_class_transformer_ = __webpack_require__(812);
+var external_class_transformer_ = __webpack_require__(5812);
 ;// CONCATENATED MODULE: ./projects/nestjs-shared/src/dtos/pagination.dto.ts
 function pagination_dto_ts_decorate(decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -777,19 +777,19 @@ MessageResponseDto = response_payload_dto_ts_decorate([
 
 
 },
-176(module) {
+6176(module) {
 
 module.exports = __rspack_external__nestjs_swagger_7cd450b5;
 
 
 },
-812(module) {
+5812(module) {
 
 module.exports = __rspack_external_class_transformer_c5a479fb;
 
 
 },
-421(module) {
+5421(module) {
 
 module.exports = __rspack_external_class_validator_7b99ef4d;