@flusys/nestjs-form-builder 3.0.0-rc → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Form Builder Package Guide
 
 > **Package:** `@flusys/nestjs-form-builder`
+> **Version:** 3.0.0
 > **Type:** Dynamic form management with schema versioning and access control
 
 This guide covers the NestJS form builder package - dynamic form creation, submission storage, and multi-tenant support.
@@ -22,6 +23,9 @@ This guide covers the NestJS form builder package - dynamic form creation, submi
 - [Computed Fields](#computed-fields)
 - [Response Mode](#response-mode)
 - [Best Practices](#best-practices)
+- [Swagger Configuration](#swagger-configuration)
+- [Permission Utilities](#permission-utilities)
+- [Controller Security](#controller-security)
 
 ---
 
@@ -227,39 +231,57 @@ export { Form as FormBase } from './form.entity';
 
 Main form entity with all form fields:
 
-| Column | Type | Description |
-|--------|------|-------------|
-| `name` | `varchar(255)` | Form name |
-| `description` | `varchar(500)` | Optional description |
-| `slug` | `varchar(255)` | URL-friendly identifier (unique) |
-| `schema` | `json` | Form schema (sections, fields, settings) |
-| `schemaVersion` | `int` | Auto-incremented on schema changes |
-| `accessType` | `enum` | `public`, `authenticated`, `action_group` |
-| `actionGroups` | `simple-array` | Permission codes for action_group access |
-| `isActive` | `boolean` | Form availability |
-| `metadata` | `simple-json` | Additional data |
+| Column | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `varchar(255)` | required | Form name |
+| `description` | `varchar(500)` | null | Optional description |
+| `slug` | `varchar(255)` | null | URL-friendly identifier |
+| `schema` | `json` | required | Form schema (sections, fields, settings) |
+| `schemaVersion` | `int` | 1 | Auto-incremented on schema changes |
+| `accessType` | `varchar(50)` | 'AUTHENTICATED' | `public`, `authenticated`, `action_group` |
+| `actionGroups` | `simple-array` | null | Permission codes for action_group access |
+| `isActive` | `boolean` | true | Form availability |
+| `metadata` | `simple-json` | null | Additional data |
+
+**Indexes (Form):**
+- `slug` - Unique index
+- `isActive` - Index for filtering active forms
 
 ### Form vs FormWithCompany
 
 - **Form** - Used when `enableCompanyFeature: false`
 - **FormWithCompany** - Extends Form, adds `companyId` column for tenant isolation
 
+**FormWithCompany Additional Column:**
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `companyId` | `uuid` | Company ID for tenant isolation |
+
+**FormWithCompany Indexes:**
+- `companyId` - Index for company filtering
+- `companyId, slug` - Unique compound index (slugs unique per company)
+- `companyId, isActive` - Compound index for active forms per company
+
 ### FormResult
 
 Stores form submissions:
 
-| Column | Type | Description |
-|--------|------|-------------|
-| `formId` | `uuid` | Reference to form |
-| `schemaVersionSnapshot` | `json` | Full schema copy at submission time |
-| `schemaVersion` | `int` | Schema version at submission |
-| `data` | `json` | Submitted field values |
-| `submittedById` | `uuid` | User who submitted (null for public) |
-| `submittedAt` | `timestamp` | Submission timestamp |
-| `isDraft` | `boolean` | Draft vs final submission |
-| `metadata` | `simple-json` | Additional data |
+| Column | Type | Default | Description |
+|--------|------|---------|-------------|
+| `formId` | `uuid` | required | Reference to form |
+| `schemaVersionSnapshot` | `json` | required | Full schema copy at submission time |
+| `schemaVersion` | `int` | required | Schema version at submission |
+| `data` | `json` | required | Submitted field values |
+| `submittedById` | `uuid` | null | User who submitted (null for public) |
+| `submittedAt` | `timestamp` | required | Submission timestamp |
+| `isDraft` | `boolean` | false | Draft vs final submission |
+| `metadata` | `simple-json` | null | Additional data |
+
+**Indexes:**
+- `formId` - Index for filtering by form
 
-**Note:** FormResult doesn't have `companyId` - company context is derived from the linked Form via `formId`.
+**Note:** FormResult doesn't have `companyId` - company context is derived from the linked Form via `formId`. Company filtering is applied via JOIN in queries.
 
 ---
 
@@ -275,6 +297,31 @@ Stores form submissions:
 | `PublicFormResponseDto` | Limited fields for public access |
 | `FormAccessInfoResponseDto` | Access requirements info |
 
+#### CreateFormDto Fields
+
+```typescript
+class CreateFormDto {
+  name: string;                    // Required, max 255 chars
+  description?: string;            // Optional, max 500 chars
+  slug?: string;                   // Optional, max 255 chars (unique)
+  schema: Record<string, unknown>; // Required - form structure
+  accessType?: FormAccessType;     // Default: AUTHENTICATED
+  actionGroups?: string[];         // For ACTION_GROUP access type
+  companyId?: string;              // When company feature enabled
+  isActive?: boolean;              // Default: true
+  metadata?: Record<string, unknown>;
+}
+```
+
+#### UpdateFormDto Fields
+
+```typescript
+class UpdateFormDto extends PartialType(CreateFormDto) {
+  id: string;                      // Required
+  schemaVersion?: number;          // Auto-incremented on schema change
+}
+```
+
 ### Form Result DTOs
 
 | DTO | Purpose |
@@ -287,6 +334,27 @@ Stores form submissions:
 | `GetResultsByFormDto` | Query results by form ID |
 | `FormResultResponseDto` | Result response |
 
+#### SubmitFormDto Fields
+
+```typescript
+class SubmitFormDto {
+  formId: string;                  // Required
+  data: Record<string, unknown>;   // Required - field values
+  isDraft?: boolean;               // Default: false
+  metadata?: Record<string, unknown>;
+}
+```
+
+#### GetResultsByFormDto Fields
+
+```typescript
+class GetResultsByFormDto {
+  formId: string;                  // Required
+  page?: number;                   // Default: 0
+  pageSize?: number;               // Default: 10
+}
+```
+
 ---
 
 ## Services
@@ -297,12 +365,21 @@ Provides access to module configuration:
 
 ```typescript
 @Injectable()
-export class FormBuilderConfigService {
-  isCompanyFeatureEnabled(): boolean;
-  getDatabaseMode(): string;
+export class FormBuilderConfigService implements IModuleConfigService {
+  // Check if company feature is enabled (supports per-tenant override)
+  isCompanyFeatureEnabled(tenant?: ITenantDatabaseConfig): boolean;
+
+  // Get database mode ('single' | 'multi-tenant')
+  getDatabaseMode(): DatabaseMode;
+
+  // Check if running in multi-tenant mode
   isMultiTenant(): boolean;
+
+  // Get full module options
   getOptions(): FormBuilderModuleOptions;
-  getConfig();
+
+  // Get config section (defaultDatabaseConfig, tenants, etc.)
+  getConfig(): IFormBuilderConfig | undefined;
 }
 ```
 
@@ -311,48 +388,111 @@ export class FormBuilderConfigService {
 Extends `RequestScopedApiService` with form-specific operations:
 
 ```typescript
-// Get form for public submission
-const form = await formService.getPublicForm(formId);
+@Injectable({ scope: Scope.REQUEST })
+export class FormService extends RequestScopedApiService<...> {
+  // === Standard CRUD (inherited) ===
+  // insert(dto, user), update(dto, user), delete(id, user), getAll(filter, user), getById(id, user)
+
+  // === Public Access (no auth required) ===
+
+  // Get form for public submission (accessType must be PUBLIC)
+  async getPublicForm(formId: string): Promise<IPublicForm>;
+
+  // Get public form by slug (no auth required)
+  async getPublicFormBySlug(slug: string): Promise<IPublicForm | null>;
+
+  // Get access info for routing decisions
+  async getFormAccessInfo(formId: string): Promise<FormAccessInfoResponseDto>;
+
+  // === Authenticated Access ===
 
-// Get form for authenticated submission (validates access)
-const form = await formService.getAuthenticatedForm(formId, user);
+  // Get form for authenticated submission (validates access + permissions)
+  async getAuthenticatedForm(formId: string, user: ILoggedUserInfo): Promise<IPublicForm>;
 
-// Get form by slug
-const form = await formService.getBySlug('customer-feedback');
+  // Get form by slug (requires auth)
+  async getBySlug(slug: string): Promise<IForm | null>;
 
-// Get access info (for frontend routing)
-const info = await formService.getFormAccessInfo(formId);
+  // Get form for submission (internal - validates access type)
+  async getFormForSubmission(formId: string, user: ILoggedUserInfo | null): Promise<Form>;
+}
 ```
 
 **Schema Versioning:**
 - `schemaVersion` auto-increments when schema JSON changes
 - Comparison uses `JSON.stringify` for deep equality check
+- Version tracked in FormResult snapshots for historical accuracy
 
 ### FormResultService
 
 Handles form submissions and drafts:
 
 ```typescript
-// Submit form (validates access type)
-const result = await formResultService.submitForm(dto, user, isPublic);
-
-// Get results by form with pagination
-const { data, total } = await formResultService.getByFormId(formId, user, {
-  page: 0,
-  pageSize: 10,
-});
-
-// Draft management
-const draft = await formResultService.getMyDraft(formId, user);
-const updated = await formResultService.updateDraft(draftId, dto, user);
-const hasSubmitted = await formResultService.hasUserSubmitted(formId, user);
+@Injectable({ scope: Scope.REQUEST })
+export class FormResultService extends RequestScopedApiService<...> {
+  // === Standard CRUD (inherited) ===
+  // insert(dto, user), update(dto, user), delete(id, user), getAll(filter, user), getById(id, user)
+
+  // === Form Submission ===
+
+  // Submit form (validates access type, handles drafts)
+  async submitForm(
+    dto: SubmitFormDto,
+    user: ILoggedUserInfo | null,
+    isPublic?: boolean,  // default: false
+  ): Promise<IFormResult>;
+
+  // === Draft Management ===
+
+  // Get user's draft for a specific form
+  async getMyDraft(formId: string, user: ILoggedUserInfo): Promise<IFormResult | null>;
+
+  // Update existing draft (can convert to final submission)
+  async updateDraft(
+    draftId: string,
+    dto: SubmitFormDto,
+    user: ILoggedUserInfo,
+  ): Promise<IFormResult>;
+
+  // === Query Methods ===
+
+  // Get results by form ID with pagination
+  async getByFormId(
+    formId: string,
+    user: ILoggedUserInfo | null,
+    pagination?: { page?: number; pageSize?: number },
+  ): Promise<{ data: IFormResult[]; total: number }>;
+
+  // Check if user has submitted (non-draft) for single response mode
+  async hasUserSubmitted(formId: string, user: ILoggedUserInfo): Promise<boolean>;
+}
 ```
 
 **Key behaviors:**
 - Schema snapshot stored with each submission for historical accuracy
 - Drafts auto-update if user re-submits as draft
-- Final submission deletes existing draft
+- Final submission deletes existing draft (soft delete)
 - Computed fields applied only on final submission (not drafts)
+- Company filtering via JOIN when company feature enabled
+
+### FormBuilderDataSourceProvider
+
+Extends `MultiTenantDataSourceService` for dynamic entity loading:
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class FormBuilderDataSourceProvider extends MultiTenantDataSourceService {
+  // Maintains separate static cache from other modules
+  protected static readonly tenantConnections = new Map<string, DataSource>();
+  protected static singleDataSource: DataSource | null = null;
+
+  // Get entities based on company feature flag
+  async getFormBuilderEntities(enableCompanyFeature?: boolean): Promise<any[]>;
+
+  // Inherited from MultiTenantDataSourceService
+  async getDataSource(): Promise<DataSource>;
+  async getRepository<T>(entity: EntityTarget<T>): Promise<Repository<T>>;
+}
+```
 
 ---
 
@@ -481,16 +621,37 @@ When company feature is enabled:
 ### Module Options
 
 ```typescript
-interface FormBuilderModuleOptions {
-  global?: boolean;              // Make module global
-  includeController?: boolean;   // Include REST controllers
-  bootstrapAppConfig?: {
-    databaseMode?: 'single' | 'multi-tenant';
-    enableCompanyFeature?: boolean;
-  };
-  config?: {
-    defaultDatabaseConfig?: IDatabaseConfig;
-  };
+interface FormBuilderModuleOptions extends IDynamicModuleConfig {
+  global?: boolean;                          // Make module global
+  includeController?: boolean;               // Include REST controllers
+  bootstrapAppConfig?: IBootstrapAppConfig;  // Bootstrap configuration
+  config?: IFormBuilderConfig;               // Form builder configuration
+}
+
+interface IFormBuilderConfig extends IDataSourceServiceOptions {
+  // Currently no form-builder specific runtime config
+  // Add form-builder specific settings here as needed
+  defaultDatabaseConfig?: IDatabaseConfig;
+  tenantDefaultDatabaseConfig?: IDatabaseConfig;
+  tenants?: ITenantDatabaseConfig[];
+}
+```
+
+### Async Options
+
+```typescript
+interface FormBuilderModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+  global?: boolean;
+  includeController?: boolean;
+  bootstrapAppConfig?: IBootstrapAppConfig;
+  useFactory?: (...args: any[]) => Promise<IFormBuilderConfig> | IFormBuilderConfig;
+  inject?: any[];
+  useExisting?: Type<FormBuilderOptionsFactory>;
+  useClass?: Type<FormBuilderOptionsFactory>;
+}
+
+interface FormBuilderOptionsFactory {
+  createFormBuilderOptions(): Promise<IFormBuilderConfig> | IFormBuilderConfig;
 }
 ```
 
@@ -574,28 +735,119 @@ const computedValues = calculateComputedFields(formData, computedFields);
 
 **Note:** Backend interface definitions mirror `@flusys/ng-form-builder` interfaces but are defined separately to avoid cross-package dependencies. Both use compatible JSON structures for serialization. See `computed-field.utils.ts` for implementation.
 
+### Computed Field Interfaces
+
+```typescript
+interface IComputedField {
+  id: string;
+  name: string;
+  key: string;                              // Storage key in _computed
+  valueType: 'string' | 'number';
+  rules: IComputedRule[];
+  defaultValue?: string | number | null;
+  description?: string;
+}
+
+interface IComputedRule {
+  id: string;
+  condition?: IComputedConditionGroup;      // Optional - no condition = always apply
+  computation: IComputation;
+}
+
+interface IComputedConditionGroup {
+  operator: 'AND' | 'OR';
+  conditions: IComputedCondition[];
+}
+
+interface IComputedCondition {
+  fieldId: string;
+  comparison: string;                       // See Condition Operators below
+  value: unknown;
+}
+
+interface IComputation {
+  type: ComputationType;
+  config: IDirectValueConfig | IFieldReferenceConfig | IArithmeticConfig;
+}
+
+type ComputationType = 'direct' | 'field_reference' | 'arithmetic';
+```
+
+### Computation Config Types
+
+```typescript
+// Direct value - set a static value
+interface IDirectValueConfig {
+  type: 'direct';
+  value: string | number;
+}
+
+// Field reference - copy value from another field
+interface IFieldReferenceConfig {
+  type: 'field_reference';
+  fieldId: string;
+}
+
+// Arithmetic - calculate from multiple operands
+interface IArithmeticConfig {
+  type: 'arithmetic';
+  operation: ArithmeticOperation;
+  operands: IArithmeticOperand[];
+}
+
+interface IArithmeticOperand {
+  type: 'field' | 'constant';
+  fieldId?: string;       // When type = 'field'
+  value?: number;         // When type = 'constant'
+}
+```
+
 ### Supported Operations
 
 | Type | Description |
 |------|-------------|
 | `direct` | Set a static value |
 | `field_reference` | Copy value from another field |
-| `arithmetic` | Calculate using sum, subtract, multiply, divide, average, min, max |
+| `arithmetic` | Calculate using arithmetic operations |
+
+### Arithmetic Operations
+
+| Operation | Description |
+|-----------|-------------|
+| `sum` | Add all operand values |
+| `subtract` | Subtract subsequent values from first |
+| `multiply` | Multiply all operand values |
+| `divide` | Divide first value by subsequent values |
+| `average` | Calculate average of all operands |
+| `min` | Get minimum value |
+| `max` | Get maximum value |
+| `increment` | Alias for sum |
+| `decrement` | Alias for subtract |
 
 ### Condition Operators
 
 Computed fields support conditional rules with these comparison operators:
 
-| Operator | Description |
-|----------|-------------|
-| `equals`, `not_equals` | Value equality |
-| `contains`, `not_contains` | String/array contains |
-| `greater_than`, `less_than` | Numeric comparison |
-| `greater_or_equal`, `less_or_equal` | Numeric comparison |
-| `is_empty`, `is_not_empty` | Null/empty check |
-| `is_before`, `is_after` | Date comparison |
-| `is_checked`, `is_not_checked` | Boolean/checkbox |
-| `is_any_of`, `is_none_of` | Array membership |
+| Operator | Aliases | Description |
+|----------|---------|-------------|
+| `equals` | | Value equality (string-safe) |
+| `not_equals` | | Value inequality |
+| `contains` | | String contains substring |
+| `not_contains` | | String does not contain substring |
+| `starts_with` | | String starts with value |
+| `ends_with` | | String ends with value |
+| `greater_than` | | Numeric greater than |
+| `less_than` | | Numeric less than |
+| `greater_or_equal` | | Numeric greater or equal |
+| `less_or_equal` | | Numeric less or equal |
+| `is_empty` | | Null, undefined, empty string, or empty array |
+| `is_not_empty` | | Has a non-empty value |
+| `is_before` | | Date comparison (before) |
+| `is_after` | | Date comparison (after) |
+| `is_checked` | | Boolean true (or 'true', or 1) |
+| `is_not_checked` | | Boolean false (or 'false', 0, falsy) |
+| `is_any_of` | `in` | Value is in array |
+| `is_none_of` | `not_in` | Value is not in array |
 
 ### Data Storage
 
@@ -711,6 +963,96 @@ async hasUserSubmitted(
 
 ---
 
+## Swagger Configuration
+
+The package includes a Swagger configuration helper that adapts documentation based on feature flags:
+
+```typescript
+import { formBuilderSwaggerConfig } from '@flusys/nestjs-form-builder';
+import { setupSwaggerDocs } from '@flusys/nestjs-core/docs';
+
+// In bootstrap
+const bootstrapConfig = { enableCompanyFeature: true };
+setupSwaggerDocs(app, formBuilderSwaggerConfig(bootstrapConfig));
+```
+
+**Features:**
+- Automatically excludes `companyId` fields when company feature is disabled
+- Generates comprehensive API documentation
+- Documents all access types and workflows
+
+### Schema Exclusions
+
+When `enableCompanyFeature: false`, these schemas hide `companyId`:
+- `CreateFormDto`
+- `UpdateFormDto`
+- `FormQueryDto`
+- `FormResponseDto`
+
+---
+
+## Permission Utilities
+
+The package provides permission validation utilities for action group access:
+
+```typescript
+import { validateUserPermissions } from '@flusys/nestjs-form-builder';
+
+// Validate user has at least one of the required permissions
+const hasPermission = await validateUserPermissions(
+  user,                           // ILoggedUserInfo
+  ['hr.survey.submit', 'admin'],  // Required permissions (OR logic)
+  cacheManager,                   // HybridCache instance
+  enableCompanyFeature,           // boolean
+  logger,                         // Logger instance
+  'submitting form',              // Context for audit logging
+  formId,                         // Resource ID for audit logging
+);
+```
+
+**Features:**
+- Reads permissions from cache (same format as PermissionGuard)
+- Fail-closed behavior: cache errors result in access denial
+- Audit logging for permission denials
+
+### Permission Cache Key Format
+
+```typescript
+// With company feature enabled
+`permissions:company:${companyId}:branch:${branchId}:user:${userId}`
+
+// Without company feature
+`permissions:user:${userId}`
+```
+
+---
+
+## Controller Security
+
+Both controllers use `createApiController` with permission-based security:
+
+### Form Permissions
+
+| Operation | Permission |
+|-----------|------------|
+| Create | `FORM_PERMISSIONS.CREATE` |
+| Read | `FORM_PERMISSIONS.READ` |
+| Update | `FORM_PERMISSIONS.UPDATE` |
+| Delete | `FORM_PERMISSIONS.DELETE` |
+
+### Form Result Permissions
+
+| Operation | Permission |
+|-----------|------------|
+| Create | `FORM_RESULT_PERMISSIONS.CREATE` |
+| Read | `FORM_RESULT_PERMISSIONS.READ` |
+| Update | `FORM_RESULT_PERMISSIONS.UPDATE` |
+| Delete | `FORM_RESULT_PERMISSIONS.DELETE` |
+
+**Note:** Submit endpoints (`submit`, `submit-public`) don't require these permissions - they use the form's `accessType` for authorization.
+
+---
+
 ## See Also
 
 - [ng-form-builder Guide](../../FLUSYS_NG/docs/FORM-BUILDER-GUIDE.md) - Frontend components
@@ -719,4 +1061,4 @@ async hasUserSubmitted(
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25

package/cjs/services/form-builder-datasource.provider.js

@@ -92,14 +92,8 @@ let FormBuilderDataSourceProvider = class FormBuilderDataSourceProvider extends
     }
     async getFormBuilderEntities(enableCompanyFeature) {
         const enable = enableCompanyFeature ?? this.configService.isCompanyFeatureEnabled();
-        const { Form, FormResult, FormWithCompany } = await Promise.resolve().then(()=>/*#__PURE__*/ _interop_require_wildcard(require("../entities")));
-        return enable ? [
-            FormWithCompany,
-            FormResult
-        ] : [
-            Form,
-            FormResult
-        ];
+        const { getFormBuilderEntitiesByConfig } = await Promise.resolve().then(()=>/*#__PURE__*/ _interop_require_wildcard(require("../entities")));
+        return getFormBuilderEntitiesByConfig(enable);
     }
     async createDataSourceFromConfig(config) {
         const enableCompanyFeature = this.configService.isCompanyFeatureEnabled(this.getCurrentTenant() ?? undefined);

package/fesm/services/form-builder-datasource.provider.js

@@ -41,14 +41,8 @@ export class FormBuilderDataSourceProvider extends MultiTenantDataSourceService
     }
     async getFormBuilderEntities(enableCompanyFeature) {
         const enable = enableCompanyFeature ?? this.configService.isCompanyFeatureEnabled();
-        const { Form, FormResult, FormWithCompany } = await import('../entities');
-        return enable ? [
-            FormWithCompany,
-            FormResult
-        ] : [
-            Form,
-            FormResult
-        ];
+        const { getFormBuilderEntitiesByConfig } = await import('../entities');
+        return getFormBuilderEntitiesByConfig(enable);
     }
     async createDataSourceFromConfig(config) {
         const enableCompanyFeature = this.configService.isCompanyFeatureEnabled(this.getCurrentTenant() ?? undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-form-builder",
-  "version": "3.0.0-rc",
+  "version": "3.0.0",
   "description": "Dynamic form builder module with schema versioning and access control",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -83,7 +83,7 @@
     "typeorm": "^0.3.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "3.0.0-rc",
-    "@flusys/nestjs-shared": "3.0.0-rc"
+    "@flusys/nestjs-core": "3.0.0",
+    "@flusys/nestjs-shared": "3.0.0"
   }
 }