survey engine v2.0.0

docs/example-usage.md

@@ -0,0 +1,114 @@
+# Survey Editor Event Listener Example
+
+The SurveyEditor now supports a simple event-driven architecture with a single `survey-changed` event.
+
+## Basic Usage
+
+```typescript
+import { SurveyEditor } from '../src/survey-editor';
+
+// Create editor instance
+const editor = new SurveyEditor(survey);
+
+// Listen for any survey changes (both uncommitted changes and commits)
+editor.on('survey-changed', (data) => {
+  if (data.isCommit) {
+    console.log('Changes committed:', data.description);
+    // Save to persistent storage
+    saveToDatabase(editor.toJson());
+  } else {
+    console.log('Survey modified (uncommitted)');
+    // Auto-save to session storage for recovery
+    updateSessionData(editor.toJson());
+  }
+
+  console.log('Has uncommitted changes:', data.hasUncommittedChanges);
+});
+```
+
+## Session Data Auto-Save Example
+
+```typescript
+class EditorSession {
+  private editor: SurveyEditor;
+  private sessionKey: string;
+
+  constructor(editor: SurveyEditor, sessionKey: string) {
+    this.editor = editor;
+    this.sessionKey = sessionKey;
+
+    // Set up auto-save on any change
+    this.editor.on('survey-changed', this.handleSurveyChanged.bind(this));
+  }
+
+  private handleSurveyChanged(data: { hasUncommittedChanges: boolean; isCommit: boolean; description?: string }) {
+    if (data.isCommit) {
+      // Save committed state to persistent storage
+      localStorage.setItem(
+        this.sessionKey,
+        JSON.stringify(this.editor.toJson())
+      );
+
+      // Clear draft since it's now committed
+      sessionStorage.removeItem(`${this.sessionKey}_draft`);
+    } else if (data.hasUncommittedChanges) {
+      // Save to session storage for recovery
+      sessionStorage.setItem(
+        `${this.sessionKey}_draft`,
+        JSON.stringify(this.editor.toJson())
+      );
+    }
+  }
+
+  cleanup() {
+    this.editor.clearAllListeners();
+  }
+}
+```
+
+## Analytics Example
+
+```typescript
+class EditorAnalytics {
+  constructor(editor: SurveyEditor) {
+    // Track all survey changes
+    editor.on('survey-changed', (data) => {
+      if (data.isCommit) {
+        this.trackEvent('survey_changes_committed', {
+          description: data.description,
+          hasUncommittedChanges: data.hasUncommittedChanges
+        });
+      } else {
+        this.trackEvent('survey_modified', {
+          hasUncommittedChanges: data.hasUncommittedChanges
+        });
+      }
+    });
+  }
+
+  private trackEvent(eventName: string, properties?: any) {
+    // Send to your analytics service
+    analytics.track(eventName, properties);
+  }
+}
+```
+
+## Available Events
+
+| Event Type | Data | Description |
+|------------|------|-------------|
+| `survey-changed` | `{ hasUncommittedChanges: boolean; isCommit: boolean; description?: string }` | Fired when survey content changes or is committed |
+
+### Event Data Properties
+
+- `hasUncommittedChanges`: Whether the editor has uncommitted changes
+- `isCommit`: `true` if this event was triggered by a commit, `false` if by a modification
+- `description`: Only present when `isCommit` is `true`, contains the commit description
+
+## Best Practices
+
+1. **Remove listeners**: Always call `editor.off()` or `editor.clearAllListeners()` when cleaning up
+2. **Error handling**: Event listeners are wrapped in try-catch, but handle errors gracefully
+3. **Performance**: Be mindful of heavy operations in the `survey-changed` event as it fires on every modification
+4. **Memory leaks**: Remove listeners when components unmount to prevent memory leaks
+5. **Check event type**: Use the `isCommit` flag to differentiate between modifications and commits

docs/survey-structure.md

@@ -1,8 +1,10 @@
+TODO: update this file with the new structure
+
 # Survey Definition Structure
 
 ## Overview
 
-Usually a survey is described as a set of (ordered) questions. 
+Usually a survey is described as a set of (ordered) questions.
 
 In this engine a survey is a hierarchical structure composed by 2 kind of elements:
 
@@ -33,49 +35,50 @@ SurveyGroupItem(intake):
 
 ### Path into the survey tree and key rules for SurveyItem
 
-** Survey Engine Rule **
+**Survey Engine Rule**
 
 These rules are mandatory to allow the survey engine to work correctly.
 
-Each `SurveyItem` has a key, uniquely identify the item inside the survey. 
+Each `SurveyItem` has a key, uniquely identify the item inside the survey.
 They keys of SurveyItem elements (`SurveySingleItem` and `SurveyGroupItem`) must follow these rules:
 
 - The key is composed by a set of segments separated by a dot (.), root element has only one segment
-- The key segments are set of characters WITHOUT dot 
+- The key segments are set of characters WITHOUT dot
 - The key of one SurveyItem must be prefixed by the key of it parents.
-- All keys must uniquely identify one item 
+- All keys must uniquely identify one item
 
-The key with several segments separated by dots represent the path to this item from the root item. In other words, the key of each item must be the path (dot separated) to this item from the root item. Each dot represent the walk through the lower level. 
+The key with several segments separated by dots represent the path to this item from the root item. In other words, the key of each item must be the path (dot separated) to this item from the root item. Each dot represent the walk through the lower level.
 
 Examples:
- - A survey named weekly, with an item Q1:
-   - The root item is is keyed 'weekly', 
-   - the item is keyed 'weekly.Q1'
- - A survey named weekly with a group of question 'G1', this group containing two questions (SingleItem) Q1 and Q2:
-   -  the root item's key is 'weekly'
-   -  the group's key is 'weekly.G1'
-   -  the item inside the groups have keys respectively 'weekly.G1.Q1', 'weekly.G1.Q2'
 
-** General best practices **
+- A survey named weekly, with an item Q1:
+  - The root item is is keyed 'weekly',
+  - the item is keyed 'weekly.Q1'
+- A survey named weekly with a group of question 'G1', this group containing two questions (SingleItem) Q1 and Q2:
+  - the root item's key is 'weekly'
+  - the group's key is 'weekly.G1'
+  - the item inside the groups have keys respectively 'weekly.G1.Q1', 'weekly.G1.Q2'
+
+**General best practices**
 
 - Key segments should be alphanumerical words, including underscores
 - As meaningful as possible
 - If a word separator is chosen (dash or underscore) it should be the same everywhere
 
-** Best practices for InfluenzaNet **
+**Best practices for InfluenzaNet**
 
 Besides the previous naming rules, there are some naming convention, inherited from past platform of Influenzanet
 
 - [should] Items are named with a 'Q' followed by a question identifier (in use Q[nn] and Qcov[nn])
-- [must] Last segment of each key must be unique for all the survey. e.g. 'weekly.Q1' must be unique but also 'Q1' in the survey. You must not have another item with a key finishing by 'Q1', even if in another group. This rule because the last segment is used a the key for data export. 
-- [must] Question keys are arbitrary but the common questions must have the assigned key in the survey standard definition 
-- [should] Non common question, should have a prefix to clearly identify them as non standard question (like a namespace), for example 
+- [must] Last segment of each key must be unique for all the survey. e.g. 'weekly.Q1' must be unique but also 'Q1' in the survey. You must not have another item with a key finishing by 'Q1', even if in another group. This rule because the last segment is used a the key for data export.
+- [must] Question keys are arbitrary but the common questions must have the assigned key in the survey standard definition
+- [should] Non common question, should have a prefix to clearly identify them as non standard question (like a namespace), for example
 
 ## Survey Item Components
 
-Components describe the properties of a SurveySingleItem (e.g. a question). 
+Components describe the properties of a SurveySingleItem (e.g. a question).
 
-Every elements of a question is a component with a specific role. For example the label, the input widget or an option is a component. 
+Every elements of a question is a component with a specific role. For example the label, the input widget or an option is a component.
 
 Several kind of components are proposed :
 
@@ -88,12 +91,14 @@ Components can also be described as a tree, nodes as Group components, and leaf
 Each component has a 'role' field, giving the purpose of the component and how the survey engine will handle it.
 
 Common roles:
+
 - 'root' : the group component of a survey item, containing all the components of a Survey item.
 - 'responseGroup' : a response group component
 - 'helpGroup'
 - 'text' : a component describing text to show (for example the label of the question)
 
 Response dedicated roles:
+
 - 'singleChoiceGroup'
 - dropDownGroup
 - multipleChoiceGroup
@@ -111,6 +116,7 @@ common Fields :
 - `disabled` : rules for disabling component
 
 For group component only
+
 - `order` : order of components (for Group component)
 
 Most of fields are represented as structure called `Expression`. They can be evaluated to a value (boolean, string, value) at runtime allowing to define complex rules to dynamically determine a field value.
@@ -126,6 +132,7 @@ Keys are mandatory for Response component
 **Expression** are tree structures to represent operation to be evaluated at runtime and can produce a value. They provides dynamic property evaluation for the survey logic.
 
 An **Expression** is a simple structure that can be either:
+
 - A typed literal value (numerical, string)
 - A call, with a `name` and a field `data` set of parameters with a list of `Expression`
 

eslint.config.js

@@ -0,0 +1,36 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      // Rule to detect unused imports and variables
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+      // Additional TypeScript-specific rules
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+  {
+    files: ['**/*.test.ts', '**/*.spec.ts'],
+    rules: {
+      // Allow unused variables in tests (common for setup/teardown)
+      '@typescript-eslint/no-unused-vars': 'off',
+    },
+  }
+);

jestconfig.json

@@ -14,4 +14,4 @@
     "json",
     "node"
   ]
-}
+}

package.json

@@ -1,11 +1,14 @@
 {
   "name": "survey-engine",
-  "version": "1.3.2",
+  "version": "2.0.0-dev",
   "description": "Implementation of the survey engine to use in typescript/javascript projects.",
   "main": "index.js",
+  "type": "module",
   "scripts": {
     "test": "jest --config jestconfig.json",
-    "build": "rollup -c"
+    "build": "tsdown",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix"
   },
   "keywords": [
     "survey engine"
@@ -17,20 +20,15 @@
   },
   "homepage": "https://github.com/influenzanet/survey-engine.ts#readme",
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^21.0.1",
-    "@rollup/plugin-node-resolve": "^13.0.6",
-    "@types/jest": "^29.2.0",
-    "jest": "^29.2.1",
-    "rollup": "^2.61.1",
-    "rollup-plugin-copy": "^3.4.0",
-    "rollup-plugin-delete": "^2.0.0",
-    "rollup-plugin-multi-input": "^1.3.1",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "rollup-plugin-typescript2": "^0.31.1",
-    "ts-jest": "^29.0.3",
-    "typescript": "^4.5.3"
+    "@types/jest": "^30.0.0",
+    "eslint": "^9.29.0",
+    "jest": "^30.0.2",
+    "ts-jest": "^29.4.0",
+    "tsdown": "^0.12.8",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.0"
   },
   "dependencies": {
-    "date-fns": "^2.29.3"
+    "date-fns": "^4.1.0"
   }
 }