@flusys/nestjs-form-builder 4.1.0 → 5.0.0

package/README.md

@@ -1,68 +1,9 @@
 # @flusys/nestjs-form-builder
 
-> Dynamic form management for NestJS — JSON schema definitions, schema versioning, access control (PUBLIC/AUTHENTICATED/ACTION_GROUP), draft submissions, and a server-side computed fields engine.
+Dynamic form management for NestJS — JSON schema storage, schema versioning, access control (PUBLIC / AUTHENTICATED / ACTION_GROUP), draft submissions, and a server-side computed fields engine.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/nestjs-form-builder.svg)](https://www.npmjs.com/package/@flusys/nestjs-form-builder)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Module Registration](#module-registration)
-  - [forRoot (Sync)](#forroot-sync)
-  - [forRootAsync (Factory)](#forrootasync-factory)
-- [Configuration Reference](#configuration-reference)
-- [Feature Toggles](#feature-toggles)
-- [API Endpoints](#api-endpoints)
-- [Entities](#entities)
-- [Access Control](#access-control)
-- [Schema Versioning](#schema-versioning)
-- [Draft Support](#draft-support)
-- [Computed Fields Engine](#computed-fields-engine)
-- [Exported Services](#exported-services)
-- [Programmatic Usage](#programmatic-usage)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/nestjs-form-builder` provides a complete dynamic form system where form structures are stored as JSON in the database. New forms can be created without any code changes. The module handles schema versioning (submissions snapshot the schema they were submitted against), per-form access control, draft submissions, and server-side computed field evaluation.
-
----
-
-## Features
-
-- **Database-driven forms** — JSON schema stored in PostgreSQL; no code changes for new forms
-- **Schema versioning** — Schema version auto-increments on change; each submission captures the version it used
-- **Access types** — `PUBLIC` (no auth), `AUTHENTICATED` (any logged-in user), `ACTION_GROUP` (IAM permission-based)
-- **Draft submissions** — Users can save partial form data and finalize later
-- **Computed fields engine** — Server-side arithmetic computed from submission data using rules and conditions
-- **Slug-based lookup** — Forms accessible by a URL-friendly slug
-- **Company scoping** — Optional `companyId` isolation via `FormWithCompany` entity
-- **Multi-tenant** — Per-tenant DataSource isolation
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| `@flusys/nestjs-core` | `^4.0.0` |
-| `@flusys/nestjs-shared` | `^4.0.0` |
-| `@nestjs/core` | `^11.0.0` |
-| `typeorm` | `^0.3.0` |
-| Node.js | `>= 18.x` |
 
 ---
 
@@ -74,377 +15,139 @@ npm install @flusys/nestjs-form-builder @flusys/nestjs-shared @flusys/nestjs-cor
 
 ---
 
-## Quick Start
+## 1. Module Registration
+
+### forRoot (sync)
 
-### Minimal Setup (Single Database)
+#### Mode 1: Single Database
 
 ```typescript
-import { Module } from '@nestjs/common';
 import { FormBuilderModule } from '@flusys/nestjs-form-builder';
 
-@Module({
-  imports: [
-    FormBuilderModule.forRoot({
-      global: true,
-      includeController: true,
-      bootstrapAppConfig: {
-        databaseMode: 'single',
-        enableCompanyFeature: false,
-      },
-      config: {
-        defaultDatabaseConfig: {
-          type: 'postgres',
-          host: process.env.DB_HOST,
-          port: Number(process.env.DB_PORT ?? 5432),
-          username: process.env.DB_USER,
-          password: process.env.DB_PASSWORD,
-          database: process.env.DB_NAME,
-        },
-      },
-    }),
-  ],
-})
-export class AppModule {}
+FormBuilderModule.forRoot({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: false,
+  },
+  config: {
+    defaultDatabaseConfig: {
+      type: 'mysql',
+      host: process.env.DB_HOST,
+      port: Number(process.env.DB_PORT ?? 3306),
+      username: process.env.DB_USER,
+      password: process.env.DB_PASSWORD,
+      database: process.env.DB_NAME,
+    },
+  },
+});
 ```
 
-After startup, create forms via `POST /form-builder/form/insert` and collect submissions via `POST /form-builder/result/insert`.
-
----
-
-## Module Registration
-
-### forRoot (Sync)
+#### Mode 2: Multi-Tenant
 
 ```typescript
 FormBuilderModule.forRoot({
-  global?: boolean;
-  includeController?: boolean;       // Default: true
-  bootstrapAppConfig?: {
-    databaseMode: 'single' | 'multi-tenant';
-    enableCompanyFeature: boolean;   // true = FormWithCompany entity
-  };
-  config?: IFormBuilderConfig;
-})
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
+  },
+  config: {
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: process.env.TENANT_DB_HOST,
+      port: Number(process.env.TENANT_DB_PORT ?? 3306),
+      username: process.env.TENANT_DB_USER,
+      password: process.env.TENANT_DB_PASSWORD,
+      database: process.env.TENANT_DB_NAME,
+    },
+    tenants: [
+      { id: 'tenant-a', database: 'tenant_a_db' },
+      { id: 'tenant-b', database: 'tenant_b_db' },
+    ],
+  },
+});
 ```
 
-### forRootAsync (Factory)
+### forRootAsync (factory — recommended)
 
 ```typescript
-import { ConfigService } from '@nestjs/config';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { FormBuilderModule, ITenantDatabaseConfig } from '@flusys/nestjs-form-builder';
 
+// Single database
 FormBuilderModule.forRootAsync({
   global: true,
-  includeController: true,
   bootstrapAppConfig: {
     databaseMode: 'single',
     enableCompanyFeature: true,
   },
   imports: [ConfigModule],
-  useFactory: (configService: ConfigService) => ({
+  useFactory: (cfg: ConfigService) => ({
     defaultDatabaseConfig: {
-      type: 'postgres',
-      host: configService.get('DB_HOST'),
-      port: configService.get<number>('DB_PORT'),
-      username: configService.get('DB_USER'),
-      password: configService.get('DB_PASSWORD'),
-      database: configService.get('DB_NAME'),
+      type: 'mysql',
+      host: cfg.get('DB_HOST'),
+      port: cfg.get<number>('DB_PORT'),
+      username: cfg.get('DB_USER'),
+      password: cfg.get('DB_PASSWORD'),
+      database: cfg.get('DB_NAME'),
     },
   }),
   inject: [ConfigService],
-})
-```
-
-**Exported services** (available for injection after registration):
-- `FormBuilderConfigService`
-- `FormBuilderDataSourceProvider`
-- `FormService`
-- `FormResultService`
-
----
-
-## Configuration Reference
+});
 
-```typescript
-interface IFormBuilderConfig extends IDataSourceServiceOptions {
-  // No form-builder-specific runtime config.
-  // IDataSourceServiceOptions provides:
-  //   defaultDatabaseConfig?: IDatabaseConfig
-  //   tenantDefaultDatabaseConfig?: IDatabaseConfig
-  //   tenants?: ITenantDatabaseConfig[]
-}
+// Multi-tenant
+FormBuilderModule.forRootAsync({
+  global: true,
+  bootstrapAppConfig: {
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
+  },
+  imports: [ConfigModule],
+  useFactory: (cfg: ConfigService) => ({
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: cfg.get('TENANT_DB_HOST'),
+      port: cfg.get<number>('TENANT_DB_PORT'),
+      username: cfg.get('TENANT_DB_USER'),
+      password: cfg.get('TENANT_DB_PASSWORD'),
+      database: cfg.get('TENANT_DB_NAME'),
+    },
+    tenants: cfg.get<ITenantDatabaseConfig[]>('TENANTS'),
+  }),
+  inject: [ConfigService],
+});
 ```
 
-Bootstrap configuration:
-
-| Field | Type | Default | Effect |
-|-------|------|---------|--------|
-| `databaseMode` | `'single' \| 'multi-tenant'` | `'single'` | Controls DataSource resolution per request |
-| `enableCompanyFeature` | `boolean` | `false` | Uses `FormWithCompany` entity when `true` |
-
----
-
-## Feature Toggles
-
-| Feature | Config | Default | Effect |
-|---------|--------|---------|--------|
-| Company scoping | `enableCompanyFeature: true` | `false` | All queries filtered by `companyId` from JWT; uses `FormWithCompany` entity |
-| Multi-tenant | `databaseMode: 'multi-tenant'` | `'single'` | Per-tenant DataSource connections |
-
----
-
-## API Endpoints
-
-All endpoints use **POST**. Authentication depends on the form's `accessType`.
-
-### Forms — `POST /form-builder/form/*`
-
-| Endpoint | Auth | Description |
-|----------|------|-------------|
-| `POST /form-builder/form/insert` | `form.create` | Create a new form with JSON schema |
-| `POST /form-builder/form/get-all` | `form.read` | List all forms (admin) |
-| `POST /form-builder/form/get/:id` | `form.read` | Get form by ID |
-| `POST /form-builder/form/get-by-slug/:slug` | Varies* | Get form by URL slug |
-| `POST /form-builder/form/update` | `form.update` | Update form (increments schema version if schema changes) |
-| `POST /form-builder/form/delete` | `form.delete` | Delete form |
-| `POST /form-builder/form/publish` | `form.update` | Publish draft form |
-| `POST /form-builder/form/unpublish` | `form.update` | Unpublish form |
-
-*`get-by-slug` respects the form's `accessType` — PUBLIC forms are accessible without auth.
-
-### Form Results (Submissions) — `POST /form-builder/result/*`
-
-| Endpoint | Auth | Description |
-|----------|------|-------------|
-| `POST /form-builder/result/insert` | Varies* | Submit a form result |
-| `POST /form-builder/result/get-all` | `form-result.read` | List all submissions |
-| `POST /form-builder/result/get/:id` | `form-result.read` | Get submission by ID |
-| `POST /form-builder/result/update` | `form-result.update` | Update a submission |
-| `POST /form-builder/result/delete` | `form-result.delete` | Delete a submission |
-| `POST /form-builder/result/save-draft` | Varies* | Save a partial draft submission |
-| `POST /form-builder/result/finalize` | Varies* | Convert draft to final submission |
-| `POST /form-builder/result/get-my-results` | JWT | Get current user's own submissions |
-
-*Depends on the form's `accessType`.
+**Exported services** (available for injection after registration):
+`FormService`, `FormResultService`, `FormBuilderConfigService`, `FormBuilderDataSourceProvider`
 
 ---
 
-## Entities
-
-### Core Entities (always registered)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `Form` | `form_builder_form` | Form definition with JSON schema, access type, version |
-| `FormResult` | `form_builder_result` | Submission data + schema version snapshot |
-
-### Company Feature Entities (`enableCompanyFeature: true`)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `FormWithCompany` | `form_builder_form` | Same as Form + `companyId` |
+## 2. Entities
 
 ```typescript
-import { FormBuilderModule } from '@flusys/nestjs-form-builder';
+import { getFormBuilderEntitiesByConfig } from '@flusys/nestjs-form-builder/entities';
 
 TypeOrmModule.forRoot({
   entities: [
-    ...FormBuilderModule.getEntities({ enableCompanyFeature: true }),
+    ...getFormBuilderEntitiesByConfig(false), // match enableCompanyFeature in bootstrapAppConfig
   ],
-})
+});
 ```
 
----
-
-## Access Control
-
-Each form has an `accessType` field that controls who can access it:
-
-| Access Type | Description |
-|-------------|-------------|
-| `PUBLIC` | No authentication required. Anyone can view and submit. |
-| `AUTHENTICATED` | Requires valid JWT token. Any logged-in user can submit. |
-| `ACTION_GROUP` | Requires a specific IAM action permission (from `nestjs-iam`). |
+| `enableCompanyFeature` | Entities registered             |
+| ---------------------- | ------------------------------- |
+| `false`                | `Form`, `FormResult`            |
+| `true`                 | `FormWithCompany`, `FormResult` |
 
-**Creating a form with access control:**
-
-```json
-POST /form-builder/form/insert
-{
-  "name": "Employee Survey",
-  "slug": "employee-survey",
-  "accessType": "AUTHENTICATED",
-  "schema": { /* JSON schema */ },
-  "isPublished": true
-}
-```
-
-**ACTION_GROUP form:**
-
-```json
-{
-  "name": "Finance Report",
-  "slug": "finance-report",
-  "accessType": "ACTION_GROUP",
-  "requiredAction": "finance.submit-report",
-  "schema": { /* JSON schema */ }
-}
-```
+The service selects the correct entity automatically at request time — no manual switching needed.
 
 ---
 
-## Schema Versioning
-
-When you update a form's `schema` field, the `schemaVersion` counter is automatically incremented. Every form submission stores the `schemaVersion` at the time of submission.
-
-This allows:
-- Viewing historical submissions against the exact schema that was active
-- Running analytics on form data across schema versions
-- Preventing schema changes from breaking existing submission records
-
-```json
-// Version 1 schema
-{ "fields": [{ "name": "firstName", "type": "text" }] }
-
-// After update (version 2) - new field added
-{ "fields": [{ "name": "firstName", "type": "text" }, { "name": "lastName", "type": "text" }] }
-```
-
-Historical submissions still reference `schemaVersion: 1` so you know they were submitted before the `lastName` field existed.
-
----
-
-## Draft Support
-
-Users can save partial form data as a draft and finalize later:
-
-```json
-// Save draft (no validation on all required fields)
-POST /form-builder/result/save-draft
-{
-  "formId": "uuid",
-  "data": { "firstName": "John" }
-}
-
-// Finalize (validates all required fields)
-POST /form-builder/result/finalize
-{
-  "draftId": "uuid",
-  "data": { "firstName": "John", "lastName": "Doe" }
-}
-```
-
-Draft submissions have `isDraft: true`. Finalized submissions have `isDraft: false`. Users can retrieve their own drafts via `POST /form-builder/result/get-my-results`.
-
----
-
-## Computed Fields Engine
-
-Server-side computed fields are calculated from submission data using declarative rules:
-
-```json
-POST /form-builder/form/insert
-{
-  "name": "Loan Calculator",
-  "schema": {
-    "fields": [
-      { "name": "principal", "type": "number", "label": "Loan Amount" },
-      { "name": "rate", "type": "number", "label": "Interest Rate (%)" },
-      { "name": "years", "type": "number", "label": "Term (Years)" }
-    ],
-    "computedFields": [
-      {
-        "name": "monthlyPayment",
-        "label": "Monthly Payment",
-        "expression": "(principal * (rate / 1200)) / (1 - Math.pow(1 + rate / 1200, -years * 12))",
-        "dependsOn": ["principal", "rate", "years"]
-      },
-      {
-        "name": "totalPayment",
-        "label": "Total Payment",
-        "expression": "monthlyPayment * years * 12",
-        "dependsOn": ["monthlyPayment", "years"]
-      }
-    ]
-  }
-}
-```
-
-Computed values are evaluated server-side at submission time and stored with the result.
-
----
-
-## Exported Services
-
-| Service | Description |
-|---------|-------------|
-| `FormService` | Form CRUD, slug lookup, publish/unpublish |
-| `FormResultService` | Submission CRUD, draft management, computed field evaluation |
-| `FormBuilderConfigService` | Exposes runtime config and feature flags |
-| `FormBuilderDataSourceProvider` | Dynamic DataSource resolution per request |
-
----
-
-## Programmatic Usage
-
-```typescript
-import { FormService, FormResultService } from '@flusys/nestjs-form-builder';
-
-@Injectable()
-export class SurveyService {
-  constructor(
-    @Inject(FormService) private readonly formService: FormService,
-    @Inject(FormResultService) private readonly resultService: FormResultService,
-  ) {}
-
-  async getPublicForm(slug: string) {
-    return this.formService.getBySlug(slug);
-  }
-
-  async submitForm(formId: string, data: Record<string, any>, userId: string) {
-    return this.resultService.submit({ formId, data, userId });
-  }
-
-  async getFormResults(formId: string) {
-    return this.resultService.getAll({ filter: { formId } }, null);
-  }
-}
-```
-
----
-
-## Troubleshooting
-
-**`Form not found` for a public form**
-
-Check that the form is published (`isPublished: true`). Unpublished forms are not returned by the public API.
-
----
-
-**Draft finalization fails validation**
-
-The `finalize` endpoint applies full schema validation. Ensure all required fields in the form schema are present in the submitted data.
-
----
-
-**Computed fields not appearing in submission**
-
-Computed fields are evaluated at submission time. Check that `dependsOn` field names exactly match the form field `name` values (case-sensitive).
-
----
-
-**`No metadata for entity`**
-
-Register entities in your `TypeOrmModule`:
-```typescript
-entities: [...FormBuilderModule.getEntities({ enableCompanyFeature: false })]
-```
-
----
 
 ## License
 
 MIT © FLUSYS
-
----
-
-> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.

package/cjs/config/message-keys.js

@@ -10,9 +10,6 @@ function _export(target, all) {
     });
 }
 _export(exports, {
-    get FORM_BUILDER_MODULE_MESSAGES () {
-        return FORM_BUILDER_MODULE_MESSAGES;
-    },
     get FORM_MESSAGES () {
         return FORM_MESSAGES;
     },
@@ -21,42 +18,21 @@ _export(exports, {
     }
 });
 const FORM_MESSAGES = {
-    CREATE_SUCCESS: 'form.create.success',
-    CREATE_MANY_SUCCESS: 'form.create.many.success',
-    GET_SUCCESS: 'form.get.success',
-    GET_ALL_SUCCESS: 'form.get.all.success',
-    UPDATE_SUCCESS: 'form.update.success',
-    UPDATE_MANY_SUCCESS: 'form.update.many.success',
-    DELETE_SUCCESS: 'form.delete.success',
-    RESTORE_SUCCESS: 'form.restore.success',
     NOT_FOUND: 'form.not.found',
-    SCHEMA_SUCCESS: 'form.schema.success',
-    PUBLISH_SUCCESS: 'form.publish.success',
-    UNPUBLISH_SUCCESS: 'form.unpublish.success',
-    DUPLICATE_SUCCESS: 'form.duplicate.success',
     NOT_PUBLIC: 'form.not.public',
     AUTH_REQUIRED: 'form.auth.required',
     ACCESS_DENIED: 'form.access.denied',
     INVALID_ACCESS_TYPE: 'form.invalid.access.type',
-    PERMISSION_CHECK_FAILED: 'form.permission.check.failed'
+    PERMISSION_CHECK_FAILED: 'form.permission.check.failed',
+    GET_SUCCESS: 'form.get.success',
+    GET_ACCESS_INFO_SUCCESS: 'form.get.access.info.success'
 };
 const FORM_RESULT_MESSAGES = {
-    CREATE_SUCCESS: 'form.result.create.success',
-    CREATE_MANY_SUCCESS: 'form.result.create.many.success',
-    GET_SUCCESS: 'form.result.get.success',
     GET_ALL_SUCCESS: 'form.result.get.all.success',
-    UPDATE_SUCCESS: 'form.result.update.success',
-    UPDATE_MANY_SUCCESS: 'form.result.update.many.success',
-    DELETE_SUCCESS: 'form.result.delete.success',
-    RESTORE_SUCCESS: 'form.result.restore.success',
     NOT_FOUND: 'form.result.not.found',
-    SUBMIT_SUCCESS: 'form.result.submit.success',
-    EXPORT_SUCCESS: 'form.result.export.success',
-    STATS_SUCCESS: 'form.result.stats.success',
     HAS_SUBMITTED_SUCCESS: 'form.result.has.submitted.success',
-    HAS_NOT_SUBMITTED_SUCCESS: 'form.result.has.not.submitted.success'
-};
-const FORM_BUILDER_MODULE_MESSAGES = {
-    FORM: FORM_MESSAGES,
-    FORM_RESULT: FORM_RESULT_MESSAGES
+    HAS_NOT_SUBMITTED_SUCCESS: 'form.result.has.not.submitted.success',
+    SUBMIT_SUCCESS: 'form.result.submit.success',
+    DRAFT_GET_SUCCESS: 'form.result.draft.get.success',
+    DRAFT_UPDATE_SUCCESS: 'form.result.draft.update.success'
 };

package/cjs/controllers/form-result.controller.js

@@ -9,12 +9,12 @@ Object.defineProperty(exports, "FormResultController", {
     }
 });
 const _classes = require("@flusys/nestjs-shared/classes");
-const _config = require("../config");
 const _decorators = require("@flusys/nestjs-shared/decorators");
 const _guards = require("@flusys/nestjs-shared/guards");
 const _interfaces = require("@flusys/nestjs-shared/interfaces");
 const _common = require("@nestjs/common");
 const _swagger = require("@nestjs/swagger");
+const _config = require("../config");
 const _dtos = require("../dtos");
 const _formresultservice = require("../services/form-result.service");
 function _define_property(obj, key, value) {
@@ -45,7 +45,7 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let FormResultController = class FormResultController extends (0, _classes.createApiController)(_dtos.CreateFormResultDto, _dtos.UpdateFormResultDto, _dtos.FormResultResponseDto, {
-    entityName: 'formResult',
+    entityName: 'form.result',
     security: {
         insert: {
             level: 'permission',
@@ -95,24 +95,41 @@ let FormResultController = class FormResultController extends (0, _classes.creat
     /**
    * Submit form with authentication
    */ async submitForm(dto, user) {
-        return this.formResultService.submitForm(dto, user, false);
+        const data = await this.formResultService.submitForm(dto, user, false);
+        return {
+            success: true,
+            message: 'Form submitted successfully',
+            messageKey: _config.FORM_RESULT_MESSAGES.SUBMIT_SUCCESS,
+            data
+        };
     }
-    /**
-   * Submit public form (no authentication required)
-   * Only works for forms with accessType = 'public'
-   */ async submitPublicForm(dto) {
-        return this.formResultService.submitForm(dto, null, true);
+    async submitPublicForm(dto) {
+        const data = await this.formResultService.submitForm(dto, null, true);
+        return {
+            success: true,
+            message: 'Form submitted successfully',
+            messageKey: _config.FORM_RESULT_MESSAGES.SUBMIT_SUCCESS,
+            data
+        };
     }
     // Draft Endpoints
-    /**
-   * Get current user's draft for a form
-   */ async getMyDraft(dto, user) {
-        return this.formResultService.getMyDraft(dto.formId, user);
+    async getMyDraft(dto, user) {
+        const data = await this.formResultService.getMyDraft(dto.formId, user);
+        return {
+            success: true,
+            message: 'Draft retrieved',
+            messageKey: _config.FORM_RESULT_MESSAGES.DRAFT_GET_SUCCESS,
+            data
+        };
     }
-    /**
-   * Update existing draft or convert to final submission
-   */ async updateDraft(dto, user) {
-        return this.formResultService.updateDraft(dto.draftId, dto, user);
+    async updateDraft(dto, user) {
+        const data = await this.formResultService.updateDraft(dto.draftId, dto, user);
+        return {
+            success: true,
+            message: 'Draft updated successfully',
+            messageKey: _config.FORM_RESULT_MESSAGES.DRAFT_UPDATE_SUCCESS,
+            data
+        };
     }
     // Query Endpoints
     /**