@opencrvs/toolkit 1.9.8-rc.34c53bf → 1.9.8-rc.48851c5

package/dist/conditionals/index.js

@@ -36,6 +36,7 @@ __export(conditionals_exports, {
   defineConditional: () => defineConditional,
   defineFormConditional: () => defineFormConditional,
   flag: () => flag,
+  isCodeToEvaluate: () => isCodeToEvaluate,
   isFieldReference: () => isFieldReference,
   never: () => never,
   not: () => not,
@@ -249,6 +250,9 @@ var user = Object.assign(userSerializer, {
 function isFieldReference(value) {
   return typeof value === "object" && value !== null && "$$field" in value;
 }
+function isCodeToEvaluate(value) {
+  return typeof value === "object" && value !== null && "$$code" in value;
+}
 function getDateRangeToFieldReference(field, comparedField, clause) {
   return {
     type: "object",
@@ -685,6 +689,112 @@ function createFieldConditionals(fieldId) {
         required: [fieldId]
       });
     },
+    /**
+     * Executes a custom validation function defined by country configuration.
+     * 
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     * 
+     * The function is serialized via toString() and transmitted as part of the JSON Schema.
+     * It is deserialized just-in-time during validation on the client.
+     * 
+     * @param fn - Validation function that receives the field value and form context.
+     *             Must return true if valid, false if invalid.
+     * 
+     * @returns JSONSchema conditional for AJV validation
+     * 
+     * @example
+     * // Simple age validation
+     * field('age').customClientValidator((value, ctx) => {
+     *   return value >= 18
+     * })
+     * 
+     * @example
+     * // Cross-field validation: child DOB must be after mother DOB
+     * field('child.dob').customClientValidator((value, ctx) => {
+     *   const motherDob = ctx.$form['mother.dob']
+     *   if (!motherDob || !value) return false
+     *   return new Date(value) > new Date(motherDob)
+     * })
+     * 
+     * @example
+     * // Two number fields validated together
+     * field('fieldA').customClientValidator((value, ctx) => {
+     *   const fieldB = ctx.$form['fieldB']
+     *   if (!fieldB) return false
+     *   return value + fieldB > 100
+     * })
+     * 
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend validation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Must return boolean: true = valid, false = invalid
+     * 
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientValidator(fn) {
+      const serializedFn = fn.toString();
+      return defineFormConditional({
+        type: "object",
+        properties: {
+          [fieldId]: wrapToPath(
+            {
+              customClientValidator: serializedFn
+            },
+            this.$$subfield
+          )
+        },
+        required: [fieldId]
+      });
+    },
+    /**
+     * Defines a client-side computation function for dynamic field values.
+     * 
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     * 
+     * The function is serialized via toString() and transmitted to the client,
+     * where it is deserialized and executed to compute field values dynamically.
+     * 
+     * @param fn - Computation function that receives the field value and form context.
+     *             Returns the computed value (any type).
+     * 
+     * @returns CodeToEvaluate object for client-side execution
+     * 
+     * @example
+     * // Concatenate first and last name
+     * field('fullName').customClientEvaluation((value, ctx) => {
+     *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+     * })
+     * 
+     * @example
+     * // Calculate age from date of birth
+     * field('childAge').customClientEvaluation((value, ctx) => {
+     *   const dob = ctx.$form['child.dob']
+     *   if (!dob) return undefined
+     *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+     *   return age
+     * })
+     * 
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend computation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Should return the computed value (any type)
+     * 
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientEvaluation(fn) {
+      const serializedFn = fn.toString();
+      return {
+        $$code: serializedFn
+      };
+    },
     getId: () => ({ fieldId }),
     /**
      * @deprecated

package/dist/events/index.js

@@ -71,6 +71,7 @@ __export(events_exports, {
   CheckboxFieldValue: () => CheckboxFieldValue,
   Clause: () => Clause,
   ClientSpecificAction: () => ClientSpecificAction,
+  CodeToEvaluate: () => CodeToEvaluate,
   Conditional: () => Conditional,
   ConditionalType: () => ConditionalType,
   ConfirmableActions: () => ConfirmableActions,
@@ -322,6 +323,7 @@ __export(events_exports, {
   isBulletListFieldType: () => isBulletListFieldType,
   isButtonFieldType: () => isButtonFieldType,
   isCheckboxFieldType: () => isCheckboxFieldType,
+  isCodeToEvaluate: () => isCodeToEvaluate,
   isConditionMet: () => isConditionMet,
   isCountryFieldType: () => isCountryFieldType,
   isCustomFieldType: () => isCustomFieldType,
@@ -2036,6 +2038,11 @@ var FieldReference = z17.object({
     'If the FieldValue is an object, subfield can be used to refer to e.g. `["foo", "bar"]` in `{ foo: { bar: 3 } }`'
   )
 }).describe("Reference to a field by its ID");
+var CodeToEvaluate = z17.object({
+  $$code: z17.string().describe(
+    "Serialized function string that will be evaluated at runtime with the field value and context"
+  )
+}).describe("Custom evaluation function for computed field values");
 var ValidationConfig = z17.object({
   validator: Conditional,
   message: TranslationConfig
@@ -2068,7 +2075,7 @@ var BaseField = z17.object({
   uncorrectable: z17.boolean().default(false).optional().describe(
     "Indicates whether the field can be modified during record correction."
   ),
-  value: FieldReference.or(z17.array(FieldReference)).optional().describe(
+  value: FieldReference.or(CodeToEvaluate).or(z17.array(FieldReference.or(CodeToEvaluate))).optional().describe(
     "Reference to the source field or fields. When a value is defined, it is copied from the parent field when changed. If multiple references are provided, the first truthy value is used."
   ),
   analytics: z17.boolean().default(false).optional().describe(
@@ -2410,7 +2417,7 @@ var Address = BaseField.extend({
 var StaticDataEntry = z17.object({
   id: z17.string().describe("ID for the data entry."),
   label: TranslationConfig,
-  value: TranslationConfig.or(z17.string()).or(FieldReference)
+  value: TranslationConfig.or(z17.string()).or(FieldReference).or(CodeToEvaluate)
 }).describe("Static data entry");
 var DataEntry = z17.union([StaticDataEntry, z17.object({ fieldId: z17.string() })]).describe(
   "Data entry can be either a static data entry, or a reference to another field in the current form or the declaration."
@@ -2452,7 +2459,7 @@ var HttpField = BaseField.extend({
     headers: z17.record(z17.string(), z17.string()).optional(),
     body: z17.record(z17.string(), z17.any()).optional(),
     errorValue: z17.any().optional().describe("Value to set if the request fails"),
-    params: z17.record(z17.string(), z17.union([z17.string(), FieldReference])).optional(),
+    params: z17.record(z17.string(), z17.union([z17.string(), FieldReference, CodeToEvaluate])).optional(),
     timeout: z17.number().default(15e3).describe("Request timeout in milliseconds")
   })
 }).describe("HTTP request function triggered by a button click or other event");
@@ -3594,31 +3601,57 @@ ajv.addKeyword({
     return locations.some((location) => location.id === locationIdInput);
   }
 });
+ajv.addKeyword({
+  keyword: "customClientValidator",
+  type: ["string", "number", "boolean", "object", "array", "null"],
+  schemaType: "string",
+  $data: false,
+  errors: false,
+  validate(schema, data, _, dataContext) {
+    if (!schema || typeof schema !== "string") {
+      return true;
+    }
+    if (typeof window === "undefined") {
+      return true;
+    }
+    try {
+      const validatorFn = new Function(
+        "value",
+        "context",
+        `return (${schema})(value, context)`
+      );
+      const context = dataContext?.rootData || {};
+      const result = validatorFn(data, context);
+      return Boolean(result);
+    } catch (error) {
+      return false;
+    }
+  }
+});
+function isAgeValue(value) {
+  return typeof value === "object" && value !== null && "age" in value && typeof value.age === "number";
+}
 function validate(schema, data) {
   const validator = ajv.getSchema(schema.$id) || ajv.compile(schema);
   if ("$form" in data) {
-    data.$form = Object.fromEntries(
-      Object.entries(data.$form).map(([key, value]) => {
-        const maybeAgeValue = AgeValue.safeParse(value);
-        if (maybeAgeValue.success) {
-          const age = maybeAgeValue.data.age;
-          const maybeAsOfDate = DateValue.safeParse(
-            data.$form[maybeAgeValue.data.asOfDateRef]
-          );
-          return [
-            key,
-            {
-              age,
-              dob: ageToDate(
-                age,
-                maybeAsOfDate.success ? maybeAsOfDate.data : data.$now
-              )
-            }
-          ];
-        }
+    const entries = Object.entries(data.$form).map(([key, value]) => {
+      if (!isAgeValue(value)) {
         return [key, value];
-      })
-    );
+      }
+      const age = value.age;
+      const maybeAsOfDate = DateValue.safeParse(data.$form[value.asOfDateRef]);
+      return [
+        key,
+        {
+          age,
+          dob: ageToDate(
+            age,
+            maybeAsOfDate.success ? maybeAsOfDate.data : data.$now
+          )
+        }
+      ];
+    });
+    data.$form = Object.fromEntries(entries);
   }
   const result = validator(data);
   return result;
@@ -4629,6 +4662,9 @@ var user = Object.assign(userSerializer, {
 function isFieldReference(value) {
   return typeof value === "object" && value !== null && "$$field" in value;
 }
+function isCodeToEvaluate(value) {
+  return typeof value === "object" && value !== null && "$$code" in value;
+}
 function getDateRangeToFieldReference(field3, comparedField, clause) {
   return {
     type: "object",
@@ -5065,6 +5101,112 @@ function createFieldConditionals(fieldId) {
         required: [fieldId]
       });
     },
+    /**
+     * Executes a custom validation function defined by country configuration.
+     * 
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     * 
+     * The function is serialized via toString() and transmitted as part of the JSON Schema.
+     * It is deserialized just-in-time during validation on the client.
+     * 
+     * @param fn - Validation function that receives the field value and form context.
+     *             Must return true if valid, false if invalid.
+     * 
+     * @returns JSONSchema conditional for AJV validation
+     * 
+     * @example
+     * // Simple age validation
+     * field('age').customClientValidator((value, ctx) => {
+     *   return value >= 18
+     * })
+     * 
+     * @example
+     * // Cross-field validation: child DOB must be after mother DOB
+     * field('child.dob').customClientValidator((value, ctx) => {
+     *   const motherDob = ctx.$form['mother.dob']
+     *   if (!motherDob || !value) return false
+     *   return new Date(value) > new Date(motherDob)
+     * })
+     * 
+     * @example
+     * // Two number fields validated together
+     * field('fieldA').customClientValidator((value, ctx) => {
+     *   const fieldB = ctx.$form['fieldB']
+     *   if (!fieldB) return false
+     *   return value + fieldB > 100
+     * })
+     * 
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend validation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Must return boolean: true = valid, false = invalid
+     * 
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientValidator(fn) {
+      const serializedFn = fn.toString();
+      return defineFormConditional({
+        type: "object",
+        properties: {
+          [fieldId]: wrapToPath(
+            {
+              customClientValidator: serializedFn
+            },
+            this.$$subfield
+          )
+        },
+        required: [fieldId]
+      });
+    },
+    /**
+     * Defines a client-side computation function for dynamic field values.
+     * 
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     * 
+     * The function is serialized via toString() and transmitted to the client,
+     * where it is deserialized and executed to compute field values dynamically.
+     * 
+     * @param fn - Computation function that receives the field value and form context.
+     *             Returns the computed value (any type).
+     * 
+     * @returns CodeToEvaluate object for client-side execution
+     * 
+     * @example
+     * // Concatenate first and last name
+     * field('fullName').customClientEvaluation((value, ctx) => {
+     *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+     * })
+     * 
+     * @example
+     * // Calculate age from date of birth
+     * field('childAge').customClientEvaluation((value, ctx) => {
+     *   const dob = ctx.$form['child.dob']
+     *   if (!dob) return undefined
+     *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+     *   return age
+     * })
+     * 
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend computation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Should return the computed value (any type)
+     * 
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientEvaluation(fn) {
+      const serializedFn = fn.toString();
+      return {
+        $$code: serializedFn
+      };
+    },
     getId: () => ({ fieldId }),
     /**
      * @deprecated

package/dist/notification/index.js

@@ -1532,6 +1532,11 @@ var FieldReference = z17.object({
     'If the FieldValue is an object, subfield can be used to refer to e.g. `["foo", "bar"]` in `{ foo: { bar: 3 } }`'
   )
 }).describe("Reference to a field by its ID");
+var CodeToEvaluate = z17.object({
+  $$code: z17.string().describe(
+    "Serialized function string that will be evaluated at runtime with the field value and context"
+  )
+}).describe("Custom evaluation function for computed field values");
 var ValidationConfig = z17.object({
   validator: Conditional,
   message: TranslationConfig
@@ -1564,7 +1569,7 @@ var BaseField = z17.object({
   uncorrectable: z17.boolean().default(false).optional().describe(
     "Indicates whether the field can be modified during record correction."
   ),
-  value: FieldReference.or(z17.array(FieldReference)).optional().describe(
+  value: FieldReference.or(CodeToEvaluate).or(z17.array(FieldReference.or(CodeToEvaluate))).optional().describe(
     "Reference to the source field or fields. When a value is defined, it is copied from the parent field when changed. If multiple references are provided, the first truthy value is used."
   ),
   analytics: z17.boolean().default(false).optional().describe(
@@ -1906,7 +1911,7 @@ var Address = BaseField.extend({
 var StaticDataEntry = z17.object({
   id: z17.string().describe("ID for the data entry."),
   label: TranslationConfig,
-  value: TranslationConfig.or(z17.string()).or(FieldReference)
+  value: TranslationConfig.or(z17.string()).or(FieldReference).or(CodeToEvaluate)
 }).describe("Static data entry");
 var DataEntry = z17.union([StaticDataEntry, z17.object({ fieldId: z17.string() })]).describe(
   "Data entry can be either a static data entry, or a reference to another field in the current form or the declaration."
@@ -1948,7 +1953,7 @@ var HttpField = BaseField.extend({
     headers: z17.record(z17.string(), z17.string()).optional(),
     body: z17.record(z17.string(), z17.any()).optional(),
     errorValue: z17.any().optional().describe("Value to set if the request fails"),
-    params: z17.record(z17.string(), z17.union([z17.string(), FieldReference])).optional(),
+    params: z17.record(z17.string(), z17.union([z17.string(), FieldReference, CodeToEvaluate])).optional(),
     timeout: z17.number().default(15e3).describe("Request timeout in milliseconds")
   })
 }).describe("HTTP request function triggered by a button click or other event");
@@ -2780,6 +2785,33 @@ ajv.addKeyword({
     return locations.some((location) => location.id === locationIdInput);
   }
 });
+ajv.addKeyword({
+  keyword: "customClientValidator",
+  type: ["string", "number", "boolean", "object", "array", "null"],
+  schemaType: "string",
+  $data: false,
+  errors: false,
+  validate(schema, data, _, dataContext) {
+    if (!schema || typeof schema !== "string") {
+      return true;
+    }
+    if (typeof window === "undefined") {
+      return true;
+    }
+    try {
+      const validatorFn = new Function(
+        "value",
+        "context",
+        `return (${schema})(value, context)`
+      );
+      const context = dataContext?.rootData || {};
+      const result = validatorFn(data, context);
+      return Boolean(result);
+    } catch (error) {
+      return false;
+    }
+  }
+});
 
 // ../commons/src/utils.ts
 var z29 = __toESM(require("zod/v4"));
@@ -3535,6 +3567,112 @@ function createFieldConditionals(fieldId) {
         required: [fieldId]
       });
     },
+    /**
+     * Executes a custom validation function defined by country configuration.
+     * 
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     * 
+     * The function is serialized via toString() and transmitted as part of the JSON Schema.
+     * It is deserialized just-in-time during validation on the client.
+     * 
+     * @param fn - Validation function that receives the field value and form context.
+     *             Must return true if valid, false if invalid.
+     * 
+     * @returns JSONSchema conditional for AJV validation
+     * 
+     * @example
+     * // Simple age validation
+     * field('age').customClientValidator((value, ctx) => {
+     *   return value >= 18
+     * })
+     * 
+     * @example
+     * // Cross-field validation: child DOB must be after mother DOB
+     * field('child.dob').customClientValidator((value, ctx) => {
+     *   const motherDob = ctx.$form['mother.dob']
+     *   if (!motherDob || !value) return false
+     *   return new Date(value) > new Date(motherDob)
+     * })
+     * 
+     * @example
+     * // Two number fields validated together
+     * field('fieldA').customClientValidator((value, ctx) => {
+     *   const fieldB = ctx.$form['fieldB']
+     *   if (!fieldB) return false
+     *   return value + fieldB > 100
+     * })
+     * 
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend validation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Must return boolean: true = valid, false = invalid
+     * 
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientValidator(fn) {
+      const serializedFn = fn.toString();
+      return defineFormConditional({
+        type: "object",
+        properties: {
+          [fieldId]: wrapToPath(
+            {
+              customClientValidator: serializedFn
+            },
+            this.$$subfield
+          )
+        },
+        required: [fieldId]
+      });
+    },
+    /**
+     * Defines a client-side computation function for dynamic field values.
+     * 
+     * **Use this as a last resort when predefined toolkit methods are insufficient.**
+     * 
+     * The function is serialized via toString() and transmitted to the client,
+     * where it is deserialized and executed to compute field values dynamically.
+     * 
+     * @param fn - Computation function that receives the field value and form context.
+     *             Returns the computed value (any type).
+     * 
+     * @returns CodeToEvaluate object for client-side execution
+     * 
+     * @example
+     * // Concatenate first and last name
+     * field('fullName').customClientEvaluation((value, ctx) => {
+     *   return `${ctx.$form.firstName} ${ctx.$form.lastName}`
+     * })
+     * 
+     * @example
+     * // Calculate age from date of birth
+     * field('childAge').customClientEvaluation((value, ctx) => {
+     *   const dob = ctx.$form['child.dob']
+     *   if (!dob) return undefined
+     *   const age = Math.floor((new Date(ctx.$now) - new Date(dob)) / (365.25 * 24 * 60 * 60 * 1000))
+     *   return age
+     * })
+     * 
+     * @remarks
+     * Limitations:
+     * - Client-side only. For backend computation, use country config event triggers.
+     * - Cannot reference external libraries (lodash, etc.)
+     * - Function must be pure — no side effects, no closures over external state
+     * - Function must be serialisable via toString()
+     * - Receives (value, context) parameters where context contains $form, $now, $online, etc.
+     * - Should return the computed value (any type)
+     * 
+     * @see https://github.com/opencrvs/opencrvs-core/issues/11653
+     */
+    customClientEvaluation(fn) {
+      const serializedFn = fn.toString();
+      return {
+        $$code: serializedFn
+      };
+    },
     getId: () => ({ fieldId }),
     /**
      * @deprecated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencrvs/toolkit",
-  "version": "1.9.8-rc.34c53bf",
+  "version": "1.9.8-rc.48851c5",
   "description": "OpenCRVS toolkit for building country configurations",
   "license": "MPL-2.0",
   "exports": {