@skedulo/mex-types 1.60.0 → 1.61.0

package/dist/page/PageComponentModel.d.ts

@@ -2,7 +2,7 @@ import { ListPageExtraActionType, ButtonGroupItemComponentModel, DataExpressionT
 import { BaseListPageViewComponentModel } from '../view';
 import { BaseComponentModel } from '../common';
 import { FlatPageViewComponentTypes } from '../view';
-import { ValidatorDefinitionModel } from '../validator';
+import { SoftValidatorDefinitionModel, ValidatorDefinitionModel } from '../validator';
 /**
  * @area formProperties
  */
@@ -388,6 +388,13 @@ export interface FlatPageComponentModel extends BasePageComponentModel {
         updateButtonText?: LocalizedKey;
         defaultDataForNewObject?: OneLevelBindingObject;
         validator?: ValidatorDefinitionModel;
+        /**
+         * Advisory validators, run once `validator` passes. Failing one asks the user to submit anyway
+         * or keep editing, instead of blocking the save.
+         * @label Soft validator
+         * @version 2.5.x
+         */
+        softValidator?: SoftValidatorDefinitionModel;
         /**
          * @label Read Only condition
          */

package/dist/validator/ValidatorModel.d.ts

@@ -7,6 +7,13 @@ export interface AsyncExpressionValidatorModel extends BaseValidatorModel {
     errorMessage: LocalizedKey;
     expression: DataExpressionType;
     query: OnlineFetchDataQuery;
+    /**
+     * Gates the validator, evaluated before `query` runs, so an unmet condition skips the API call entirely
+     * Omit to always validate.
+     * @label Condition
+     * @version 2.5.x
+     */
+    condition?: DataExpressionType | boolean;
 }
 export interface ExpressionValidatorModel extends BaseValidatorModel {
     type: 'expression';
@@ -17,5 +24,19 @@ export interface CustomFunctionValidatorModel extends BaseValidatorModel {
     functionName: string;
     type: 'customFunction';
 }
-export type ValidatorDefinitionModel = ValidatorModelTypes[] | ValidatorModelTypes;
-export type ValidatorModelTypes = ExpressionValidatorModel | AsyncExpressionValidatorModel | CustomFunctionValidatorModel;
+export type ValidatorDefinitionModel = HardValidationModel[] | HardValidationModel;
+/**
+ * Blocking validation — failing it stops the save until the data is corrected.
+ */
+export type HardValidationModel = ExpressionValidatorModel | AsyncExpressionValidatorModel | CustomFunctionValidatorModel;
+/**
+ * Advisory validation — failing it warns the user on submit, who may then save anyway. Same shapes
+ * as HardValidationModel; what makes it soft is being declared under `upsert.softValidator` rather
+ * than `validator`
+ * @version 2.5.x
+ */
+export type SoftValidationModel = ExpressionValidatorModel | AsyncExpressionValidatorModel | CustomFunctionValidatorModel;
+/**
+ * @version 2.5.x
+ */
+export type SoftValidatorDefinitionModel = SoftValidationModel[] | SoftValidationModel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skedulo/mex-types",
-  "version": "1.60.0",
+  "version": "1.61.0",
   "description": "A central repository store for all the interfaces, type definitions of MEX engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/common/MexDataFlow.d.ts

@@ -1,215 +0,0 @@
-/**
- * V2 MEX data-flow contracts (see Linear MEX-116, MEX-117).
- *
- * These types are the shared contract between mex-engine (RN), the mexwex-bridge
- * SDK (web side), native-form-backend, and mobile-edge-service. They are
- * intentionally framework-agnostic — no React, no MobX, no GraphQL helpers.
- *
- * V2 Data Structure is opt-in per form via `metadata.useDataFlowVersion === '2'`.
- * Forms on V1 Data Structure continue to use the legacy `MexInstanceData` /
- * `MexStaticData` blobs and the `instanceFetch.json` / `staticFetch.json`
- * definitions; none of this file applies to them.
- */
-export type MexDataFlowVersion = '1' | '2';
-export type MexResourceScope = 'Instance' | 'Static';
-/**
- * Shape returned by `defineResource(...)` in the `params.ts` of a form using V2 Data Structure.
- *
- * Two flavours, distinguished by which of `fetch` vs entity-sugar fields is
- * present:
- *   - Entity sugar: { entity, select, filter? }
- *   - Full custom: { fetch }
- *
- * Both flavours share the common header (`name`, `scope`, `invalidateOn?`).
- * Build-time validation (mex-service-libs) enforces that exactly one flavour
- * is populated.
- */
-export type MexResourceDefinition = MexResourceDefinitionEntitySugar | MexResourceDefinitionCustom;
-export interface MexResourceDefinitionBase {
-    /** Stable, unique name within a form bundle. Form devs reference this from `mexBridge.resource.observe({ resource })`. */
-    name: string;
-    /**
-     * Per-form-context (instance) or per-package (static). Defaults to 'Instance'.
-     * Static resources must not reference `ctx.contextObjectId` in their fetch.
-     */
-    scope?: MexResourceScope;
-    /**
-     * Entity types that, when written to, invalidate this resource and force
-     * re-materialization. Used by NFB to wire up CB live-query dependencies.
-     */
-    invalidateOn?: string[];
-}
-export interface MexResourceDefinitionEntitySugar extends MexResourceDefinitionBase {
-    /** GraphQL entity name (e.g. `'Jobs'`, `'JobProducts'`). */
-    entity: string;
-    /** Fields to select. Same shape as GraphQL `select`. */
-    select: Record<string, unknown>;
-    /** Optional EQL filter string. */
-    filter?: string;
-    fetch?: undefined;
-}
-export interface MexResourceDefinitionCustom extends MexResourceDefinitionBase {
-    /**
-     * Async fetcher invoked by the backend on materialization. Receives a
-     * runtime context (graphql client, auth, logger, and `contextObjectId` for
-     * instance-scoped resources only).
-     */
-    fetch: (ctx: MexResourceFetchContext) => Promise<unknown>;
-    entity?: undefined;
-    select?: undefined;
-    filter?: undefined;
-}
-export interface MexResourceFetchContext {
-    /** The form package id. Always present. */
-    packageId: string;
-    /**
-     * The context object id (e.g. a Job UID). Only provided for instance-scoped
-     * resources. Undefined for `scope: 'Static'` resources.
-     */
-    contextObjectId?: string;
-    /** Opaque GraphQL client handle — typed by mex-service-libs at the call site. */
-    graphql: unknown;
-    /** Opaque auth handle — typed by mex-service-libs at the call site. */
-    auth: unknown;
-    /** Opaque logger handle. */
-    logger: unknown;
-}
-export interface MexChangeSetHandlerDefinition {
-    /** Match a ChangeSet by its `name` field. Build-time validation enforces uniqueness within a form. */
-    match: {
-        name: string;
-    };
-    /**
-     * Primary handler. Returns `{ handled: true, uid? }` to suppress the default
-     * mutation, or `{ handled: false }` (or omits the return) to fall through.
-     */
-    handle: (input: MexChangeSetHandlerInput, ctx: MexChangeSetHandlerContext) => Promise<MexChangeSetHandlerResult>;
-    /**
-     * Optional post-mutation hook — fires after `handle` (and after the default
-     * mutation, if it ran). Useful for side effects (telemetry, downstream calls).
-     */
-    handleAfter?: (input: MexChangeSetHandlerInput, ctx: MexChangeSetHandlerContext) => Promise<void>;
-}
-export interface MexChangeSetHandlerInput {
-    /** Operation kind — `'insert' | 'update' | 'delete'` as set by the form. */
-    op: MexChangeSetOp;
-    /** GraphQL entity type the changeset targets (e.g. `'JobProducts'`). */
-    type: string;
-    /** Entity UID. May be a `local:...` temp UID for inserts; resolves via IdMapping. */
-    uid: string;
-    /** Field deltas — only writable fields per the form's contract. */
-    fields: Record<string, unknown>;
-}
-export type MexChangeSetOp = 'insert' | 'update' | 'delete';
-export interface MexChangeSetHandlerContext {
-    packageId: string;
-    contextObjectId?: string;
-    graphql: unknown;
-    auth: unknown;
-    logger: unknown;
-    /** Map from temp `local:...` UIDs to real UIDs after server processing. */
-    resolveUid: (tempUid: string) => string | undefined;
-}
-export type MexChangeSetHandlerResult = {
-    handled: true;
-    uid?: string;
-} | {
-    handled: false;
-} | void;
-/**
- * V2 fields layered onto the existing `MexDefinition` CB Lite document
- * (one per form package). The doc itself already exists for forms on V1 Data Structure;
- * V2 only adds `v2ResourceDataKeys` at the top level and
- * `useDataFlowVersion` inside the existing `metadata` field. Auto-derived
- * by NFB / mobile-edge-service from the form bundle's `params.resources[]`.
- *
- * This interface is the **slim view** the engine returns to the web via
- * `mexBridge.getMexDefinition()` — not the full MexDefinition shape (which
- * also carries `ui`, `customFunction`, etc. that the form doesn't need).
- *
- * ChangeSet handler names are deliberately NOT mirrored to the engine: the
- * form fires `insertChangeSet({ name })` and the backend resolves the
- * handler. There is no client-side name validation.
- */
-export interface MexDefinitionDocument {
-    /** Form package id — derived from `MexDefinition.uid`. */
-    packageId: string;
-    /** Mirrors `metadata.useDataFlowVersion`. `'2'` for forms using V2 Data Structure. */
-    useDataFlowVersion: MexDataFlowVersion;
-    /**
-     * Map from resource name to its scope. Engine validates
-     * `observe({ resource })` against this map; unknown names are rejected
-     * with `INVALID_RESOURCE_NAME`.
-     */
-    v2ResourceDataKeys: Record<string, MexResourceScope>;
-}
-/**
- * Document body shape. `data` is set on successful materialization;
- * `hasError`/`error` is set on failure. The two are mutually exclusive at
- * write time — a successful re-materialization overwrites the error body
- * with a fresh `data` payload.
- */
-export interface MexDataV2Document {
-    /** The materialized resource payload — JSON-serializable. */
-    data?: unknown;
-    /** ISO-8601 timestamp of last successful materialization. */
-    materializedAt?: string;
-    /** Set when materialization failed; mutually exclusive with `data`. */
-    hasError?: boolean;
-    /** Populated when `hasError === true`. */
-    error?: MexDataV2Error;
-}
-export interface MexDataV2Error {
-    code: string;
-    message: string;
-    details?: unknown;
-}
-/**
- * Payload accepted by `mexBridge.insertChangeSet(...)`. The native side wraps
- * this in a ClientEvent and persists it to the local outbox; the form does not
- * wait for server processing.
- */
-export interface MexChangeSetPayload {
-    /**
-     * Handler name resolved server-side. Omit for anonymous changesets that
-     * fall through to the default GraphQL mutation. The engine does **not**
-     * validate this name locally — typos surface as the backend's "no handler
-     * matched" warning, which the form discovers via the resource observe
-     * flow (the pending changeset clears when the default mutation completes).
-     */
-    name?: string;
-    op: MexChangeSetOp;
-    type: string;
-    /** Entity UID — use a `local:...` temp UID for inserts. */
-    uid: string;
-    fields: Record<string, unknown>;
-}
-/**
- * Shape of a pending changeset as observed via `resource.observe({ pendingChangeSets })`.
- * Extends the original payload with bookkeeping the engine layers on.
- */
-export interface MexPendingChangeSet extends MexChangeSetPayload {
-    /** Stable id for the queued CE — used by tests to assert ordering. */
-    changeSetId: string;
-    /** ISO-8601 timestamp the CE was enqueued locally. */
-    enqueuedAt: string;
-}
-/**
- * Error code discriminator for all V2 bridge error paths. Used by the
- * mexwex-bridge SDK's `onError` callbacks and `insertChangeSet` rejections.
- */
-export type MexBridgeErrorCode = 'INVALID_RESOURCE_NAME' | 'FIRST_RECORD_TIMEOUT' | 'SERVER_ERROR' | 'NATIVE_UNAVAILABLE' | 'SCHEMA_ERROR' | 'BRIDGE_DISCONNECTED';
-export interface MexBridgeError {
-    code: MexBridgeErrorCode;
-    message: string;
-    details?: unknown;
-}
-export type MexResourceObserveStatus = 'loading' | 'ready';
-export interface MexResourceObserveSnapshot<TData = unknown> {
-    resourceData?: TData;
-    pendingChangeSets: MexPendingChangeSet[];
-    status: MexResourceObserveStatus;
-    meta?: {
-        materializedAt?: string;
-    };
-}

package/dist/common/MexDataFlow.js

@@ -1,15 +0,0 @@
-"use strict";
-/**
- * V2 MEX data-flow contracts (see Linear MEX-116, MEX-117).
- *
- * These types are the shared contract between mex-engine (RN), the mexwex-bridge
- * SDK (web side), native-form-backend, and mobile-edge-service. They are
- * intentionally framework-agnostic — no React, no MobX, no GraphQL helpers.
- *
- * V2 Data Structure is opt-in per form via `metadata.useDataFlowVersion === '2'`.
- * Forms on V1 Data Structure continue to use the legacy `MexInstanceData` /
- * `MexStaticData` blobs and the `instanceFetch.json` / `staticFetch.json`
- * definitions; none of this file applies to them.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=MexDataFlow.js.map

package/dist/common/MexDataFlow.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"MexDataFlow.js","sourceRoot":"","sources":["../../src/common/MexDataFlow.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}