@opencrvs/toolkit 2.0.0-rc.fe94e41 → 2.0.0-rc.fedb8b0

package/dist/commons/conditionals/conditionals.d.ts

@@ -1,12 +1,13 @@
 import { EventDocument } from '../events/EventDocument';
-import { EventState } from '../events/ActionDocument';
+import { ActionUpdate, EventState } from '../events/ActionDocument';
 import { ITokenPayload as TokenPayload } from '../authentication';
 import { PartialSchema as AjvJSONSchemaType } from 'ajv/dist/types/json-schema';
 import { userSerializer } from '../events/serializers/user/serializer';
 import { UUID } from '../uuid';
 import { todayDateTimeValueSerializer } from '../events/serializers/date/serializer';
 import { EventStatus } from '../events/EventMetadata';
-import { FieldReference } from '../events/FieldConfig';
+import { CodeToEvaluate, FieldReference } from '../events/FieldConfig';
+import type { ClientFunctionContext } from './validate';
 /** @knipignore */
 export type JSONSchema = {
     $id: string;
@@ -25,7 +26,7 @@ export type EventConditionalParameters = CommonConditionalParameters & {
     $event: EventDocument;
 };
 export type FormConditionalParameters = CommonConditionalParameters & {
-    $form: EventState | Record<string, unknown>;
+    $form: EventState | ActionUpdate;
     $leafAdminStructureLocationIds?: Array<{
         id: UUID;
     }>;
@@ -107,7 +108,9 @@ export declare const user: typeof userSerializer & {
     };
 };
 export declare function isFieldReference(value: unknown): value is FieldReference;
-export declare function isEventFieldReference(value: unknown): value is FieldReference;
+export declare function isEventFieldReference(value: unknown): value is {
+    $$event: string;
+};
 /** Check if an event flag is present */
 export declare function flag(flagvalue: string): JSONSchema;
 /** Check if an event flag is present */
@@ -202,6 +205,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asDob(): any;
         asAge(): any;
@@ -261,6 +295,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     getByPath(fieldPath: string[]): {
         $$subfield: string[];
@@ -334,6 +399,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         getByPath(fieldPath: string[]): any;
         asDob(): {
@@ -402,6 +498,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asAge(): {
             $$subfield: string[];
@@ -469,6 +596,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         isAfter(): {
             days: (days: number) => {
@@ -526,6 +684,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     asDob(): {
         $$subfield: string[];
@@ -600,6 +789,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asDob(): any;
         asAge(): any;
@@ -659,6 +879,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     asAge(): {
         $$subfield: string[];
@@ -733,6 +984,37 @@ export declare function createFieldConditionals(fieldId: string): {
              * )
              */
             object: (options: Record<string, any>) => JSONSchema;
+            /**
+             * Custom client-side validator. The provided function is serialised and executed
+             * just-in-time on the client only. External references (e.g. lodash) are not
+             * available inside the function body — all logic must be self-contained.
+             *
+             * @example
+             * field('nid').customClientValidator((value) => {
+             *   // LUHN check — all logic must be inline
+             *   const digits = String(value).split('').map(Number)
+             *   // ...
+             *   return isValid
+             * })
+             */
+            customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+            /**
+             * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+             * that can be used as the `value` property or a DATA component entry.
+             * The function receives the referenced field's value as the first argument and
+             * the full form context as the second; its return value replaces the field reference.
+             * The function is serialised and executed just-in-time on the client only.
+             * External references (e.g. lodash) are not available inside the function body.
+             *
+             * For computing a default value without referencing a specific field, use
+             * `evaluate(fn)` in the `defaultValue` property instead.
+             *
+             * @example
+             * field('a').customClientEvaluation((aValue, ctx) =>
+             *   Number(aValue) + Number(ctx.$form.b)
+             * )
+             */
+            customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
         };
         asDob(): any;
         asAge(): any;
@@ -792,6 +1074,37 @@ export declare function createFieldConditionals(fieldId: string): {
          * )
          */
         object: (options: Record<string, any>) => JSONSchema;
+        /**
+         * Custom client-side validator. The provided function is serialised and executed
+         * just-in-time on the client only. External references (e.g. lodash) are not
+         * available inside the function body — all logic must be self-contained.
+         *
+         * @example
+         * field('nid').customClientValidator((value) => {
+         *   // LUHN check — all logic must be inline
+         *   const digits = String(value).split('').map(Number)
+         *   // ...
+         *   return isValid
+         * })
+         */
+        customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+        /**
+         * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+         * that can be used as the `value` property or a DATA component entry.
+         * The function receives the referenced field's value as the first argument and
+         * the full form context as the second; its return value replaces the field reference.
+         * The function is serialised and executed just-in-time on the client only.
+         * External references (e.g. lodash) are not available inside the function body.
+         *
+         * For computing a default value without referencing a specific field, use
+         * `evaluate(fn)` in the `defaultValue` property instead.
+         *
+         * @example
+         * field('a').customClientEvaluation((aValue, ctx) =>
+         *   Number(aValue) + Number(ctx.$form.b)
+         * )
+         */
+        customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
     };
     isAfter(): {
         days: (days: number) => {
@@ -849,6 +1162,37 @@ export declare function createFieldConditionals(fieldId: string): {
      * )
      */
     object: (options: Record<string, any>) => JSONSchema;
+    /**
+     * Custom client-side validator. The provided function is serialised and executed
+     * just-in-time on the client only. External references (e.g. lodash) are not
+     * available inside the function body — all logic must be self-contained.
+     *
+     * @example
+     * field('nid').customClientValidator((value) => {
+     *   // LUHN check — all logic must be inline
+     *   const digits = String(value).split('').map(Number)
+     *   // ...
+     *   return isValid
+     * })
+     */
+    customClientValidator(validationFn: (fieldValue: unknown, context: ClientFunctionContext) => boolean): JSONSchema;
+    /**
+     * Custom client-side evaluation. Returns a {@link FieldReference} descriptor
+     * that can be used as the `value` property or a DATA component entry.
+     * The function receives the referenced field's value as the first argument and
+     * the full form context as the second; its return value replaces the field reference.
+     * The function is serialised and executed just-in-time on the client only.
+     * External references (e.g. lodash) are not available inside the function body.
+     *
+     * For computing a default value without referencing a specific field, use
+     * `evaluate(fn)` in the `defaultValue` property instead.
+     *
+     * @example
+     * field('a').customClientEvaluation((aValue, ctx) =>
+     *   Number(aValue) + Number(ctx.$form.b)
+     * )
+     */
+    customClientEvaluation(computationFn: (fieldValue: unknown, context: ClientFunctionContext) => unknown): CodeToEvaluate;
 };
 export {};
 //# sourceMappingURL=conditionals.d.ts.map

package/dist/commons/conditionals/validate.d.ts

@@ -12,6 +12,54 @@ import { ActionType } from '../events/ActionType';
 import { EventConfig } from '../events/EventConfig';
 import { EventDocument } from '../events/EventDocument';
 import { EventIndex } from '../events/EventIndex';
+import { Location } from '../events/locations';
+import { SystemVariables } from '../events/TemplateConfig';
+/** Returns today's date as an ISO date string (YYYY-MM-DD). */
+export declare function todayISO(): string;
+/**
+ * Context passed to every serialised client-side function ({@link runClientFunction}).
+ *
+ * `$user` (full {@link ITokenPayload}, validator paths) and `user` (a
+ * {@link SystemVariables} subset for template substitution, default-value
+ * path) are distinct sources, not duplicates.
+ */
+export type ClientFunctionContext = {
+    $form: EventState | ActionUpdate;
+    $now: string;
+    $online: boolean;
+    $user?: ITokenPayload;
+    $event?: EventDocument;
+    $leafAdminStructureLocationIds: Array<{
+        id: UUID;
+    }>;
+    user?: SystemVariables['user'];
+    $window?: SystemVariables['$window'];
+    locations?: Location[];
+    adminLevelIds?: string[];
+    $flags?: string[];
+    $status?: string;
+};
+type CompiledClientFunction = (data: FieldValue | undefined, context: ClientFunctionContext) => unknown;
+/**
+ * Deserialises a serialised function string (produced by `.toString()`) into a callable.
+ * Results are cached by code string so each unique function body is compiled at most once.
+ * Runs in a clean scope — no access to outer closures or external imports.
+ */
+export declare function compileClientFunction(code: string): CompiledClientFunction;
+export declare function buildClientFunctionContext(input: {
+    form: EventState | ActionUpdate;
+    validatorContext?: ValidatorContext;
+    systemVariables?: SystemVariables;
+    /**
+     * In real use cases, there can be hundreds of thousands of locations.
+     * Make sure that the context contains only the locations that are needed for validation.
+     * E.g. if the user is a leaf admin, only the leaf locations under their admin structure are needed.
+     * Loading few megabytes of locations to memory just for validation is not efficient and will choke the application.
+     */
+    locations?: Location[];
+    adminLevelIds?: string[];
+}): ClientFunctionContext;
+export declare function runClientFunction(code: string, data: FieldValue | undefined, context: ClientFunctionContext): unknown;
 /**
  * Precompiles action conditional schemas from the event configurations to improve performance of condition validation later on.
  * Best called once on application startup before any condition validation is done.
@@ -20,8 +68,8 @@ export declare function precompileActionSchemas(eventConfigurations: EventConfig
 export declare function validate(schema: JSONSchema, data: ConditionalParameters): boolean;
 export declare function validateValue(schema: JSONSchema, data: unknown): boolean;
 export declare function isOnline(): boolean;
-export declare function isConditionMet(conditional: JSONSchema, values: EventState | ActionUpdate, context: ValidatorContext, eventIndex?: EventIndex): boolean;
-export declare function areConditionsMet(conditions: FieldConditional[], values: Record<string, FieldValue>, context: ValidatorContext, event: EventIndex): boolean;
+export declare function isConditionMet(conditional: JSONSchema, values: EventState | ActionUpdate, context: ValidatorContext): boolean;
+export declare function areConditionsMet(conditions: FieldConditional[], values: Record<string, FieldValue>, context: ValidatorContext, _event: EventIndex): boolean;
 export type ValidatorContext = {
     user?: ITokenPayload;
     leafAdminStructureLocationIds?: Array<{
@@ -113,4 +161,5 @@ export declare function runFieldValidations({ field: config, form, value, contex
 }>>;
 export declare function getValidatorsForField(fieldId: FieldConfig['id'], validations: NonNullable<FieldConfig['validation']>): NonNullable<FieldConfig['validation']>;
 export declare function areCertificateConditionsMet(conditions: FieldConditional[], values: ConditionalParameters): boolean;
+export {};
 //# sourceMappingURL=validate.d.ts.map