@flusys/nestjs-shared 9.1.0 → 9.1.2

package/README.md

@@ -209,6 +209,10 @@ async publicList() { }
 
 `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()`.
 
+`evaluatePermissionLogic(logic, granted)` evaluates an AND / OR `ILogicNode` tree with the same matcher and returns `{ passed, missingPermissions, operator }` (a group without children fails closed); `permissionLogicCodes(logic)` lists the codes a tree names. `PermissionGuard` uses it for `@RequirePermissionLogic`, and `SharedPermissionCacheService.assertPermissionLogic(user, logic)` is the throwing form for code outside a guard (403 naming what is missing, 500 when no cache is wired up) - used by `nestjs-entity-builder` for flow URLs with a permission rule.
+
+`permissionLogicProblem(value)` validates a stored rule (`'invalid' | 'empty' | 'too_many' | null`; at most `MAX_PERMISSION_LOGIC_DEPTH` (5) group levels and `MAX_PERMISSION_LOGIC_CODES` (50) codes) - use it for any DTO or config that accepts an `ILogicNode`. `loadPermissionCodes(scope, { resolver, cache })` reads a user's codes from `PERMISSION_RESOLVER` when wired, else from a configured `SharedPermissionCacheService`, else throws `PermissionSystemUnavailableException` - never re-implement that fallback.
+
 ## 5. Response DTOs
 
 All controllers return one of these shapes:
@@ -763,6 +767,71 @@ Injecting `EVENT_BUS_INSTANCE` gives direct
 `publish` / `subscribe` access - mark it `@Optional()`, so the service still resolves in an
 app that never registers `EventBusModule`.
 
+## 9. Branch Hierarchy
+
+Branches nest through `CompanyBranch.parentId` (always inside one company). Two layers, so any package can use them without importing nestjs-auth:
+
+**Pure helpers** (`@flusys/nestjs-shared/utils`) on a flat `{ id, parentId }` list. They tolerate bad data: repeated ids keep their first entry, empty ids are ignored, a branch that is its own parent is a root, and parent cycles never loop.
+
+| Function | Returns |
+| --- | --- |
+| `collectBranchDescendantIds(nodes, ids, { includeSelf?, maxDepth? })` | every branch under `ids`, level by level; with `includeSelf` the given ids come first |
+| `collectBranchAncestorIds(nodes, id, { includeSelf?, maxDepth? })` | the parent chain, nearest parent first, stopping at a parent not in `nodes` |
+| `isBranchWithin(nodes, id, ancestorId)` | `id` is `ancestorId` or anywhere under it |
+| `getBranchPath(nodes, id)` | the nodes from the top-most known ancestor down to `id` |
+| `normalizeBranchIds(ids)` | each id once, in order, without empty values |
+| `applyBranchFilter(query, { entityAlias, columnName?, includeUnassigned? }, ids)` | adds `alias.branchId IN (:...ids)`; `includeUnassigned` also keeps rows with no branch; no ids matches nothing (or only unassigned rows) |
+
+`maxDepth: 1` limits a walk to direct children or the direct parent.
+
+**`BRANCH_HIERARCHY_RESOLVER`** (`@flusys/nestjs-shared/interfaces`), implemented by nestjs-auth's `BranchHierarchyResolverAdapter` when the company feature is on. Inject it `@Optional()`:
+
+| Method | Use it for |
+| --- | --- |
+| `getDescendantIds(ids, { includeSelf? })` | structure only (every sub-branch, grants ignored) - e.g. admin screens; never to scope a user's data |
+| `getAncestorIds(id, { includeSelf? })` | breadcrumbs, inherited settings |
+| `isWithinBranch(id, ancestorId)` | "does this record's branch sit under mine?" |
+| `getGrantedBranchIds(userId, companyId?)` | the branches the user is granted - exactly what company select offers |
+| `getGrantedDescendantIds(userId, ids, { includeSelf? })` | the current branch sees its granted sub-branches' data; a branch dropdown filter that also matches granted sub-branches |
+| `hasBranchAccess(userId, branchId)` | the user is granted that branch itself (a parent grant does not count) |
+
+Results only hold existing, not soft-deleted branches (inactive ones are included), and empty, malformed or unknown ids match nothing. A soft-deleted branch cuts the chain, so what sits below it is no longer under its old ancestors. A user's granted branches are exactly what company select offers (`COMPANY_ACCESS_RESOLVER`, whose `getUserAccess(userId)` lists each as `{ id, companyId, parentId, name }`). Grants are explicit: a grant on a parent never reaches a child that is not granted itself, in either direction - with Parent and Level 2 granted but not Level 1, `getGrantedDescendantIds(userId, parent, { includeSelf: true })` is `[parent, level2]`.
+
+```typescript
+constructor(@Optional() @Inject(BRANCH_HIERARCHY_RESOLVER) private readonly branches?: IBranchHierarchyResolver) {}
+
+async listForCurrentBranch(query: SelectQueryBuilder<Invoice>, user: ILoggedUserInfo) {
+  if (!this.branches || !user.branchId) return query;
+  const ids = await this.branches.getGrantedDescendantIds(user.id, user.branchId, { includeSelf: true });
+  return applyBranchFilter(query, { entityAlias: 'invoice', columnName: 'branch_id' }, ids);
+}
+```
+
+## 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/constants/permissions.d.ts

@@ -113,7 +113,6 @@ export declare const FLOW_DEFINITION_PERMISSIONS: {
     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: {
@@ -299,7 +298,6 @@ export declare const PERMISSIONS: {
         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: {