form0-core 0.0.0 → 0.1.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 paqu.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# form0-core
+
+[![NPM Version](https://img.shields.io/npm/v/form0-core)](https://www.npmjs.com/package/form0-core)
+[![NPM Downloads](https://img.shields.io/npm/dt/form0-core)](https://www.npmjs.com/package/form0-core)
+[![License](https://img.shields.io/npm/l/form0-core)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-docs.form0.dev-2563eb)](https://docs.form0.dev)
+[![Website](https://img.shields.io/badge/site-form0.dev-0f172a)](https://form0.dev)
+
+> [!WARNING]
+> form0 is in active, very early development. Do not use in production. Expect breaking
+> changes and unstable behavior.
+
+form0-core is the schema-driven engine that powers form0 ecosystem. It is framework-agnostic and runs in any JavaScript runtime (Node.js, browsers, React Native, etc.)
+
+## 🚀 Start with the CLI (recommended)
+
+The entry point for most users is form0-cli. Follow the quickstart to create a project and preview
+your schema:
+- https://docs.form0.dev/getting-started/quickstart
+
+## 🗂️ Documentation
+
+- Docs home: https://docs.form0.dev
+- form0-core overview: https://docs.form0.dev/core/overview
+- form0-core concepts: https://docs.form0.dev/core/concepts
+- Main site: https://form0.dev
+
+## Direct usage (advanced)
+
+If you are integrating the engine directly:
+
+```bash
+npm install form0-core
+```
+
+## Security
+
+See `SECURITY.md` for security modes and configuration.

package/SECURITY.md

@@ -0,0 +1,179 @@
+# Security Features
+
+form0-core provides configurable security options for expression evaluation to balance flexibility and safety.
+
+## Security Modes
+
+### TRUSTED (Default)
+
+- **Full JavaScript access** - Current behavior maintained
+- **No restrictions** - All expressions execute as-is
+- **Use case**: Internal tools, trusted developers, client-side only
+
+```javascript
+import { createFormEngine } from 'form0-core';
+
+// Default behavior - no security parameter needed
+const engine = createFormEngine({ schema });
+
+// Or explicitly set trusted mode
+const engine = createFormEngine({
+  schema,
+  security: { mode: 'trusted' },
+});
+```
+
+### SAFE
+
+- **Restricted context** - Only whitelisted globals available
+- **Pattern blocking** - Dangerous patterns are blocked
+- **Use case**: User-generated expressions, safer environments
+
+```javascript
+import { createFormEngine, SECURITY_MODES, SAFE_SECURITY_CONFIG } from 'form0-core';
+
+// Simple safe mode
+const engine = createFormEngine({
+  schema,
+  security: { mode: SECURITY_MODES.SAFE },
+});
+
+// Or use predefined safe config
+const engine = createFormEngine({
+  schema,
+  security: SAFE_SECURITY_CONFIG,
+});
+```
+
+### CUSTOM
+
+- **User-defined rules** - Configure your own security settings
+- **Flexible restrictions** - Mix and match security features
+- **Use case**: Specific security requirements
+
+```javascript
+const engine = createFormEngine({
+  schema,
+  security: {
+    mode: SECURITY_MODES.CUSTOM,
+    maxExecutionTime: 1000,
+    allowedGlobals: ['Math', 'Date', 'Number'],
+    blockedPatterns: [/\bwindow\b/, /\bdocument\b/, /\bfetch\b/],
+  },
+});
+```
+
+## Security Configuration Options
+
+```javascript
+// TRUSTED mode (default) - no additional config needed
+const trustedConfig = {
+  mode: 'trusted', // Full JavaScript access
+};
+
+// SAFE mode - uses predefined safe settings
+const safeConfig = {
+  mode: 'safe', // Automatically applies safe defaults
+};
+
+// CUSTOM mode - define your own rules
+const customConfig = {
+  mode: 'custom',
+  maxExecutionTime: 1000, // Milliseconds (future feature)
+  maxCallStackDepth: 100, // Maximum recursion depth (future feature)
+  allowedGlobals: ['Math', 'Date', 'JSON'], // Whitelisted global objects
+  blockedPatterns: [/\beval\b/, /\bwindow\b/], // Regex patterns to block
+};
+```
+
+## Default Blocked Patterns (Safe Mode)
+
+The following patterns are blocked by default in safe mode:
+
+- `eval`, `Function` - Code execution
+- `window`, `document` - Browser globals
+- `process`, `require` - Node.js globals
+- `fetch`, `XMLHttpRequest` - Network requests
+- `localStorage`, `sessionStorage` - Storage APIs
+- `__proto__`, `constructor`, `prototype` - Prototype pollution
+
+## Migration Guide
+
+### No Changes Needed
+
+Existing code continues to work unchanged:
+
+```javascript
+// This still works exactly as before
+const engine = createFormEngine({ schema, initialValues });
+```
+
+### Adding Security
+
+To add security, simply include the security parameter:
+
+```javascript
+// Add safe mode
+const engine = createFormEngine({
+  schema,
+  initialValues,
+  security: { mode: 'safe' },
+});
+```
+
+## Examples
+
+### Safe Mathematical Calculations
+
+```javascript
+const schema = {
+  form: {
+    elements: [
+      {
+        type: 'CalculatedField',
+        data_name: 'result',
+        calculate: 'Math.max($value1, $value2) * 1.1', // ✅ Works in safe mode
+      },
+    ],
+  },
+};
+```
+
+### Blocked Dangerous Expressions
+
+```javascript
+const schema = {
+  form: {
+    elements: [
+      {
+        type: 'CalculatedField',
+        data_name: 'result',
+        calculate: 'window.alert("hello")', // ❌ Blocked in safe mode
+      },
+    ],
+  },
+};
+```
+
+### Custom Security Rules
+
+```javascript
+const engine = createFormEngine({
+  schema,
+  security: {
+    mode: 'custom',
+    allowedGlobals: ['Math'], // Only Math allowed
+    blockedPatterns: [/\bDate\b/], // Block Date usage
+  },
+});
+```
+
+## Testing Security
+
+Use the included test file to verify security behavior:
+
+```bash
+node test/security-test.js
+```
+
+This will show how different expressions behave under different security modes.

package/package.json

@@ -1,12 +1,54 @@
 {
   "name": "form0-core",
-  "version": "0.0.0",
-  "main": "index.js",
+  "version": "0.1.0-beta.2",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Schema-driven engine that powers form0 ecosystem.",
+  "main": "src/index.js",
+  "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node tests/form0-core.test.js && node tests/security-test.js",
+    "postinstall": "node scripts/postinstall.cjs",
+    "format": "prettier --write \"**/*.{js,jsx,json,ts,tsx,md}\"",
+    "format:check": "prettier --check \"**/*.{js,jsx,json,ts,tsx,md}\""
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paqu-io/form0-core.git"
+  },
+  "keywords": [
+    "form",
+    "form-builder",
+    "form-generator",
+    "form-engine",
+    "schema",
+    "json-schema",
+    "react",
+    "react-native",
+    "dynamic-forms"
+  ],
+  "author": "paqu.io <hello@paqu.io> (https://paqu.io/)",
+  "contributors": [
+    {
+      "name": "aragornii"
+    }
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/paqu-io/form0-core/issues"
+  },
+  "homepage": "https://form0.dev/",
+  "engines": {
+    "node": ">=18.0.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": ""
+  "devDependencies": {
+    "ignore": "^7.0.5",
+    "prettier": "^3.5.3"
+  }
 }

package/scripts/postinstall.cjs

@@ -0,0 +1,38 @@
+const PACKAGE_NAME = 'form0-core';
+
+const npmUserAgent = process.env.npm_config_user_agent || '';
+const npmArgv = process.env.npm_config_argv;
+
+const isSupportedManager = /(npm|pnpm|yarn|bun)\//.test(npmUserAgent);
+
+const parseNpmArgv = (raw) => {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+
+const includesExplicitPackage = (argv) => {
+  if (!argv) return false;
+  const args = Array.isArray(argv.original) ? argv.original : argv.cooked || [];
+  return args.some(
+    (arg) => arg === PACKAGE_NAME || arg.startsWith(`${PACKAGE_NAME}@`),
+  );
+};
+
+if (isSupportedManager && includesExplicitPackage(parseNpmArgv(npmArgv))) {
+  // Keep message short to avoid noisy installs.
+  console.warn(
+    [
+      '',
+      'form0-core is the engine only.',
+      'For the full form0 ecosystem, install the CLI:',
+      '  npm install -g form0-cli',
+      'Docs: https://docs.form0.dev/getting-started/quickstart',
+      'If you are integrating the engine directly, you can ignore this warning.',
+      '',
+    ].join('\n'),
+  );
+}

package/src/builtins/choice/choicelabel.js

@@ -0,0 +1,43 @@
+/**
+ * @builtin CHOICELABEL
+ * @description Retrieves the currently selected choice field label, preserving the type (if the label is a number preserves the number type, otherwise string). If no selection it returns null.
+ * @param {Object} choiceField - The choice field object with choice and other arrays
+ * @returns {*} The selected choice label with preserved type, or null if no selection
+ * @example
+ * // Get the selected city label
+ * CHOICELABEL($city)
+ * @example
+ * // Use in display logic
+ * "You selected: " + CHOICELABEL($city)
+ */
+export const CHOICELABEL = (choiceField) => {
+  // Handle null/undefined input
+  if (!choiceField || typeof choiceField !== 'object') {
+    return null;
+  }
+
+  // Validate structure
+  if (!Array.isArray(choiceField.choice)) {
+    return null;
+  }
+
+  // Get the selected choice (single selection)
+  if (choiceField.choice.length > 0) {
+    const selectedChoice = choiceField.choice[0];
+    if (selectedChoice && selectedChoice.label !== undefined) {
+      // Preserve type - if it's a number, keep it as number
+      const label = selectedChoice.label;
+
+      // Try to parse as number if it's a string that represents a number
+      if (typeof label === 'string' && !isNaN(label) && !isNaN(parseFloat(label))) {
+        // Check if it's an integer or float
+        const numLabel = parseFloat(label);
+        return Number.isInteger(numLabel) ? parseInt(label, 10) : numLabel;
+      }
+
+      return label;
+    }
+  }
+
+  return null;
+};

package/src/builtins/choice/choicelabels.js

@@ -0,0 +1,43 @@
+/**
+ * @builtin CHOICELABELS
+ * @description Retrieves an array of all selected choice field labels from a MultiChoiceField, preserving the type of each label. Returns an empty array if no selections.
+ * @param {Object} multiChoiceField - The multi choice field object with choices and other arrays
+ * @returns {Array} Array of selected choice labels with preserved types
+ * @example
+ * // Get all selected color labels
+ * CHOICELABELS($colors)
+ * @example
+ * // Display selected colors
+ * "Selected colors: " + CHOICELABELS($colors).join(", ")
+ */
+export const CHOICELABELS = (multiChoiceField) => {
+  // Handle null/undefined input
+  if (!multiChoiceField || typeof multiChoiceField !== 'object') {
+    return [];
+  }
+
+  // Validate structure
+  if (!Array.isArray(multiChoiceField.choices)) {
+    return [];
+  }
+
+  // Get all selected choices
+  const labels = [];
+  for (const choice of multiChoiceField.choices) {
+    if (choice && choice.label !== undefined) {
+      // Preserve type - if it's a number, keep it as number
+      const label = choice.label;
+
+      // Try to parse as number if it's a string that represents a number
+      if (typeof label === 'string' && !isNaN(label) && !isNaN(parseFloat(label))) {
+        // Check if it's an integer or float
+        const numLabel = parseFloat(label);
+        labels.push(Number.isInteger(numLabel) ? parseInt(label, 10) : numLabel);
+      } else {
+        labels.push(label);
+      }
+    }
+  }
+
+  return labels;
+};

package/src/builtins/choice/choicevalue.js

@@ -0,0 +1,43 @@
+/**
+ * @builtin CHOICEVALUE
+ * @description Retrieves the currently selected choice field value, preserving the type (if the value is a number preserves the number type, otherwise string). If no selection it returns null.
+ * @param {Object} choiceField - The choice field object with choice and other arrays
+ * @returns {*} The selected choice value with preserved type, or null if no selection
+ * @example
+ * // Get the selected city value
+ * CHOICEVALUE($city)
+ * @example
+ * // Use in conditional logic
+ * IF(CHOICEVALUE($city) === "bogota", "Welcome to Bogotá!", "Welcome!")
+ */
+export const CHOICEVALUE = (choiceField) => {
+  // Handle null/undefined input
+  if (!choiceField || typeof choiceField !== 'object') {
+    return null;
+  }
+
+  // Validate structure
+  if (!Array.isArray(choiceField.choice)) {
+    return null;
+  }
+
+  // Get the selected choice (single selection)
+  if (choiceField.choice.length > 0) {
+    const selectedChoice = choiceField.choice[0];
+    if (selectedChoice && selectedChoice.value !== undefined) {
+      // Preserve type - if it's a number, keep it as number
+      const value = selectedChoice.value;
+
+      // Try to parse as number if it's a string that represents a number
+      if (typeof value === 'string' && !isNaN(value) && !isNaN(parseFloat(value))) {
+        // Check if it's an integer or float
+        const numValue = parseFloat(value);
+        return Number.isInteger(numValue) ? parseInt(value, 10) : numValue;
+      }
+
+      return value;
+    }
+  }
+
+  return null;
+};

package/src/builtins/choice/choicevalues.js

@@ -0,0 +1,43 @@
+/**
+ * @builtin CHOICEVALUES
+ * @description Retrieves an array of all selected choice field values from a MultiChoiceField, preserving the type of each value. Returns an empty array if no selections.
+ * @param {Object} multiChoiceField - The multi choice field object with choices and other arrays
+ * @returns {Array} Array of selected choice values with preserved types
+ * @example
+ * // Get all selected color values
+ * CHOICEVALUES($colors)
+ * @example
+ * // Check if "red" is selected
+ * CHOICEVALUES($colors).includes("red")
+ */
+export const CHOICEVALUES = (multiChoiceField) => {
+  // Handle null/undefined input
+  if (!multiChoiceField || typeof multiChoiceField !== 'object') {
+    return [];
+  }
+
+  // Validate structure
+  if (!Array.isArray(multiChoiceField.choices)) {
+    return [];
+  }
+
+  // Get all selected choices
+  const values = [];
+  for (const choice of multiChoiceField.choices) {
+    if (choice && choice.value !== undefined) {
+      // Preserve type - if it's a number, keep it as number
+      const value = choice.value;
+
+      // Try to parse as number if it's a string that represents a number
+      if (typeof value === 'string' && !isNaN(value) && !isNaN(parseFloat(value))) {
+        // Check if it's an integer or float
+        const numValue = parseFloat(value);
+        values.push(Number.isInteger(numValue) ? parseInt(value, 10) : numValue);
+      } else {
+        values.push(value);
+      }
+    }
+  }
+
+  return values;
+};

package/src/builtins/choice/hasother.js

@@ -0,0 +1,37 @@
+/**
+ * @builtin HASOTHER
+ * @description Returns true if user entered an other option, false otherwise. Works with both SingleChoiceField and MultiChoiceField.
+ * @param {Object} choiceField - The choice field object (SingleChoiceField with choice array or MultiChoiceField with choices array) and other array
+ * @returns {boolean} True if user entered an other option, false otherwise
+ * @example
+ * // Check if user entered other option in single choice field
+ * HASOTHER($city)
+ * @example
+ * // Check if user entered other option in multi choice field
+ * HASOTHER($colors)
+ * @example
+ * // Use in conditional logic
+ * IF(HASOTHER($city), "Custom city: " + OTHER($city), "Selected city: " + CHOICELABEL($city))
+ */
+export const HASOTHER = (choiceField) => {
+  // Handle null/undefined input
+  if (!choiceField || typeof choiceField !== 'object') {
+    return false;
+  }
+
+  // Validate structure - must have either choice array (SingleChoiceField) or choices array (MultiChoiceField)
+  const hasChoiceArray = Array.isArray(choiceField.choice);
+  const hasChoicesArray = Array.isArray(choiceField.choices);
+
+  if (!hasChoiceArray && !hasChoicesArray) {
+    return false;
+  }
+
+  // Validate other array structure
+  if (!Array.isArray(choiceField.other)) {
+    return false;
+  }
+
+  // Check if there are any other entries
+  return choiceField.other.length > 0;
+};

package/src/builtins/choice/other.js

@@ -0,0 +1,44 @@
+/**
+ * @builtin OTHER
+ * @description Retrieves the other label if user entered the other option, otherwise null. Works with both SingleChoiceField and MultiChoiceField.
+ * @param {Object} choiceField - The choice field object (SingleChoiceField with choice array or MultiChoiceField with choices array) and other array
+ * @returns {string|null} The other label if user entered an other option, null otherwise
+ * @example
+ * // Get the other value from single choice field
+ * OTHER($city)
+ * @example
+ * // Get the other value from multi choice field
+ * OTHER($colors)
+ * @example
+ * // Use in conditional logic
+ * IF(HASOTHER($city), "Custom city: " + OTHER($city), "No custom city entered")
+ */
+export const OTHER = (choiceField) => {
+  // Handle null/undefined input
+  if (!choiceField || typeof choiceField !== 'object') {
+    return null;
+  }
+
+  // Validate structure - must have either choice array (SingleChoiceField) or choices array (MultiChoiceField)
+  const hasChoiceArray = Array.isArray(choiceField.choice);
+  const hasChoicesArray = Array.isArray(choiceField.choices);
+
+  if (!hasChoiceArray && !hasChoicesArray) {
+    return null;
+  }
+
+  // Validate other array structure
+  if (!Array.isArray(choiceField.other)) {
+    return null;
+  }
+
+  // Get the other entry (single selection - user can only add 1 other option)
+  if (choiceField.other.length > 0) {
+    const otherEntry = choiceField.other[0];
+    if (otherEntry && otherEntry.label !== undefined) {
+      return otherEntry.label;
+    }
+  }
+
+  return null;
+};