@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/conditions.ts

@@ -1,692 +0,0 @@
-/**
- * @mindmatrix/react/conditions — Typed condition helpers for transition guards.
- *
- * Factory functions that produce `TransitionCondition` objects for use in
- * model transition definitions. Instead of writing raw condition objects:
- *
- * ```typescript
- * conditions: [
- *   { type: 'expression', expression: 'context.actor_id == state_data.senderId' },
- *   { type: 'role', role: 'admin' },
- *   { type: 'field', field: 'status', operator: 'eq', value: 'draft' },
- * ]
- * ```
- *
- * You can use ergonomic helpers:
- *
- * ```typescript
- * import { isSender, hasRole, fieldEquals, or } from '@mindmatrix/react';
- *
- * conditions: [
- *   or(isSender(), hasRole('admin')),
- *   fieldEquals('status', 'draft'),
- * ]
- * ```
- */
-
-import type { TransitionCondition } from './config/defineModel';
-
-// ============================================================================
-// INTERNAL HELPERS
-// ============================================================================
-
-/** Normalize a condition argument — strings become expression conditions. */
-function normalize(c: TransitionCondition | string): TransitionCondition {
-  return typeof c === 'string' ? { type: 'expression', expression: c } : c;
-}
-
-// ============================================================================
-// EXPRESSION CONDITIONS
-// ============================================================================
-
-/**
- * Create an expression-based transition condition.
- *
- * @param expression - The expression string to evaluate. Must be truthy for the transition to fire.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { expr } from '@mindmatrix/react';
- *
- * transitions: {
- *   approve: {
- *     from: 'review', to: 'approved',
- *     conditions: [
- *       expr('state_data.amount <= context.approvalLimit'),
- *     ],
- *   },
- * }
- * ```
- */
-export function expr(expression: string): TransitionCondition {
-  return { type: 'expression', expression };
-}
-
-/**
- * Alias for {@link expr}. Create an expression-based transition condition.
- *
- * @param expression - The expression string to evaluate.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { when } from '@mindmatrix/react';
- *
- * conditions: [when('input.email != null && LEN(input.email) > 0')]
- * ```
- */
-export function when(expression: string): TransitionCondition {
-  return expr(expression);
-}
-
-// ============================================================================
-// ROLE CHECKS
-// ============================================================================
-
-/**
- * Require the actor to have a specific role.
- *
- * @param role - The role name to check (e.g. `'admin'`, `'owner'`).
- * @returns A `TransitionCondition` of type `'role'`.
- *
- * @example
- * ```typescript
- * import { hasRole } from '@mindmatrix/react';
- *
- * transitions: {
- *   delete: {
- *     from: 'active', to: 'deleted',
- *     conditions: [hasRole('admin')],
- *   },
- * }
- * ```
- */
-export function hasRole(role: string): TransitionCondition {
-  return { type: 'role', role };
-}
-
-/**
- * Require the actor to have at least one of the specified roles.
- *
- * Produces an `OR` combinator wrapping individual role conditions.
- *
- * @param roles - One or more role names.
- * @returns A `TransitionCondition` with an `OR` array of role conditions.
- *
- * @example
- * ```typescript
- * import { hasAnyRole } from '@mindmatrix/react';
- *
- * transitions: {
- *   archive: {
- *     from: 'active', to: 'archived',
- *     conditions: [hasAnyRole('admin', 'owner')],
- *   },
- * }
- * ```
- */
-export function hasAnyRole(...roles: string[]): TransitionCondition {
-  if (roles.length === 1) {
-    return hasRole(roles[0]);
-  }
-  return { OR: roles.map((r) => ({ type: 'role' as const, role: r })) };
-}
-
-// ============================================================================
-// ACTOR / OWNERSHIP CHECKS
-// ============================================================================
-
-/**
- * Require the actor to be the owner of the workflow instance.
- *
- * Generates: `context.actor_id == state_data.<ownerField>`
- *
- * @param ownerField - The field name that stores the owner ID. Defaults to `'ownerId'`.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { isOwner } from '@mindmatrix/react';
- *
- * // Default: checks state_data.ownerId
- * conditions: [isOwner()]
- *
- * // Custom field: checks state_data.createdBy
- * conditions: [isOwner('createdBy')]
- * ```
- */
-export function isOwner(ownerField: string = 'ownerId'): TransitionCondition {
-  return { type: 'expression', expression: `context.actor_id == state_data.${ownerField}` };
-}
-
-/**
- * Require the actor's ID to match a specific field on the instance.
- *
- * Generates: `context.actor_id == state_data.<actorField>`
- *
- * @param actorField - The field name to compare against `context.actor_id`.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { isActor } from '@mindmatrix/react';
- *
- * // Only the sender can edit their message
- * conditions: [isActor('senderId')]
- * // Equivalent to: { type: 'expression', expression: 'context.actor_id == state_data.senderId' }
- * ```
- */
-export function isActor(actorField: string): TransitionCondition {
-  return { type: 'expression', expression: `context.actor_id == state_data.${actorField}` };
-}
-
-/**
- * Shorthand for `isActor('senderId')`. Require the actor to be the message sender.
- *
- * Generates: `context.actor_id == state_data.senderId`
- *
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { isSender, hasRole, or } from '@mindmatrix/react';
- *
- * // Only the sender or an admin can delete a message
- * conditions: [or(isSender(), hasRole('admin'))]
- * ```
- */
-export function isSender(): TransitionCondition {
-  return isActor('senderId');
-}
-
-/**
- * Shorthand for `isActor('createdBy')`. Require the actor to be the record creator.
- *
- * Generates: `context.actor_id == state_data.createdBy`
- *
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { isCreator } from '@mindmatrix/react';
- *
- * conditions: [isCreator()]
- * ```
- */
-export function isCreator(): TransitionCondition {
-  return isActor('createdBy');
-}
-
-// ============================================================================
-// FIELD COMPARISONS
-// ============================================================================
-
-/**
- * Require a field to equal a specific value.
- *
- * @param field - The field name on `state_data`.
- * @param value - The value to compare against.
- * @returns A `TransitionCondition` of type `'field'` with operator `'eq'`.
- *
- * @example
- * ```typescript
- * import { fieldEquals } from '@mindmatrix/react';
- *
- * conditions: [fieldEquals('status', 'draft')]
- * // Equivalent to: { type: 'field', field: 'status', operator: 'eq', value: 'draft' }
- * ```
- */
-export function fieldEquals(field: string, value: unknown): TransitionCondition {
-  return { type: 'field', field, operator: 'eq', value };
-}
-
-/**
- * Require a field to NOT equal a specific value.
- *
- * @param field - The field name on `state_data`.
- * @param value - The value to compare against.
- * @returns A `TransitionCondition` of type `'field'` with operator `'ne'`.
- *
- * @example
- * ```typescript
- * import { fieldNotEquals } from '@mindmatrix/react';
- *
- * conditions: [fieldNotEquals('type', 'system')]
- * ```
- */
-export function fieldNotEquals(field: string, value: unknown): TransitionCondition {
-  return { type: 'field', field, operator: 'ne', value };
-}
-
-/**
- * Require a numeric field to be greater than a value.
- *
- * @param field - The field name on `state_data`.
- * @param value - The numeric threshold.
- * @returns A `TransitionCondition` of type `'field'` with operator `'gt'`.
- *
- * @example
- * ```typescript
- * import { fieldGreaterThan } from '@mindmatrix/react';
- *
- * conditions: [fieldGreaterThan('amount', 1000)]
- * ```
- */
-export function fieldGreaterThan(field: string, value: number): TransitionCondition {
-  return { type: 'field', field, operator: 'gt', value };
-}
-
-/**
- * Require a numeric field to be less than a value.
- *
- * @param field - The field name on `state_data`.
- * @param value - The numeric threshold.
- * @returns A `TransitionCondition` of type `'field'` with operator `'lt'`.
- *
- * @example
- * ```typescript
- * import { fieldLessThan } from '@mindmatrix/react';
- *
- * conditions: [fieldLessThan('retryCount', 3)]
- * ```
- */
-export function fieldLessThan(field: string, value: number): TransitionCondition {
-  return { type: 'field', field, operator: 'lt', value };
-}
-
-/**
- * Require a field's value to be one of the specified values.
- *
- * @param field - The field name on `state_data`.
- * @param values - The allowed values.
- * @returns A `TransitionCondition` of type `'field'` with operator `'in'`.
- *
- * @example
- * ```typescript
- * import { fieldIn } from '@mindmatrix/react';
- *
- * conditions: [fieldIn('priority', ['high', 'critical'])]
- * ```
- */
-export function fieldIn(field: string, values: unknown[]): TransitionCondition {
-  return { type: 'field', field, operator: 'in', value: values };
-}
-
-/**
- * Require a field's value to NOT be one of the specified values.
- *
- * @param field - The field name on `state_data`.
- * @param values - The disallowed values.
- * @returns A `TransitionCondition` of type `'field'` with operator `'not_in'`.
- *
- * @example
- * ```typescript
- * import { fieldNotIn } from '@mindmatrix/react';
- *
- * conditions: [fieldNotIn('status', ['deleted', 'archived'])]
- * ```
- */
-export function fieldNotIn(field: string, values: unknown[]): TransitionCondition {
-  return { type: 'field', field, operator: 'not_in', value: values };
-}
-
-/**
- * Require a field (typically an array or string) to contain a value.
- *
- * @param field - The field name on `state_data`.
- * @param value - The value to check for containment.
- * @returns A `TransitionCondition` of type `'field'` with operator `'contains'`.
- *
- * @example
- * ```typescript
- * import { fieldContains } from '@mindmatrix/react';
- *
- * // Check if the members array contains the actor
- * conditions: [fieldContains('members', 'context.actor_id')]
- * ```
- */
-export function fieldContains(field: string, value: unknown): TransitionCondition {
-  return { type: 'field', field, operator: 'contains', value };
-}
-
-/**
- * Require a field to be set (non-null and non-undefined).
- *
- * @param field - The field name on `state_data`.
- * @returns A `TransitionCondition` of type `'field'` with operator `'is_set'`.
- *
- * @example
- * ```typescript
- * import { fieldIsSet } from '@mindmatrix/react';
- *
- * conditions: [fieldIsSet('approvedBy')]
- * ```
- */
-export function fieldIsSet(field: string): TransitionCondition {
-  return { type: 'field', field, operator: 'is_set' };
-}
-
-/**
- * Require a field to be empty (null, undefined, empty string, or empty array).
- *
- * @param field - The field name on `state_data`.
- * @returns A `TransitionCondition` of type `'field'` with operator `'is_empty'`.
- *
- * @example
- * ```typescript
- * import { fieldIsEmpty } from '@mindmatrix/react';
- *
- * conditions: [fieldIsEmpty('errorMessage')]
- * ```
- */
-export function fieldIsEmpty(field: string): TransitionCondition {
-  return { type: 'field', field, operator: 'is_empty' };
-}
-
-/**
- * Require a field to match a regex pattern.
- *
- * @param field - The field name on `state_data`.
- * @param pattern - The regex pattern string.
- * @returns A `TransitionCondition` of type `'field'` with operator `'matches'`.
- *
- * @example
- * ```typescript
- * import { fieldMatches } from '@mindmatrix/react';
- *
- * conditions: [fieldMatches('email', '^[^@]+@[^@]+\\.[^@]+$')]
- * ```
- */
-export function fieldMatches(field: string, pattern: string): TransitionCondition {
-  return { type: 'field', field, operator: 'matches', value: pattern };
-}
-
-// ============================================================================
-// INPUT VALIDATION
-// ============================================================================
-
-/**
- * Require one or more input fields to be non-null and non-empty.
- *
- * Returns an AND combinator when multiple fields are specified, or a single
- * expression condition for a single field. This mirrors the pattern used in
- * real models like the authentication model's login transition.
- *
- * @param fields - One or more input field names that must be provided.
- * @returns A `TransitionCondition` — single expression or AND combinator.
- *
- * @example
- * ```typescript
- * import { inputRequired } from '@mindmatrix/react';
- *
- * transitions: {
- *   login: {
- *     from: 'unauthenticated', to: 'authenticating',
- *     conditions: [inputRequired('email', 'password')],
- *     // Equivalent to:
- *     // conditions: [
- *     //   { type: 'expression', expression: 'input.email != null && LEN(input.email) > 0' },
- *     //   { type: 'expression', expression: 'input.password != null && LEN(input.password) > 0' },
- *     // ]
- *   },
- * }
- * ```
- */
-export function inputRequired(...fields: string[]): TransitionCondition {
-  const conditions = fields.map((f) => ({
-    type: 'expression' as const,
-    expression: `input.${f} != null && LEN(input.${f}) > 0`,
-  }));
-  if (conditions.length === 1) {
-    return conditions[0];
-  }
-  return { AND: conditions };
-}
-
-/**
- * Require an input field to equal a specific value.
- *
- * Generates: `input.<field> == <value>` (with proper quoting for strings).
- *
- * @param field - The input field name.
- * @param value - The expected value.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { inputEquals } from '@mindmatrix/react';
- *
- * conditions: [inputEquals('confirmDelete', true)]
- * // Generates: { type: 'expression', expression: 'input.confirmDelete == true' }
- *
- * conditions: [inputEquals('action', 'approve')]
- * // Generates: { type: 'expression', expression: 'input.action == "approve"' }
- * ```
- */
-export function inputEquals(field: string, value: unknown): TransitionCondition {
-  const formatted = typeof value === 'string' ? `"${value}"` : String(value);
-  return { type: 'expression', expression: `input.${field} == ${formatted}` };
-}
-
-// ============================================================================
-// STATE CHECKS
-// ============================================================================
-
-/**
- * Require the workflow instance to be in a specific state.
- *
- * Generates: `current_state == "<state>"`
- *
- * @param state - The state name.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { inState } from '@mindmatrix/react';
- *
- * conditions: [inState('active')]
- * ```
- */
-export function inState(state: string): TransitionCondition {
-  return { type: 'expression', expression: `current_state == "${state}"` };
-}
-
-/**
- * Require the workflow instance to NOT be in a specific state.
- *
- * Generates: `current_state != "<state>"`
- *
- * @param state - The state name to exclude.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { notInState } from '@mindmatrix/react';
- *
- * conditions: [notInState('deleted')]
- * ```
- */
-export function notInState(state: string): TransitionCondition {
-  return { type: 'expression', expression: `current_state != "${state}"` };
-}
-
-// ============================================================================
-// BOOLEAN COMBINATORS
-// ============================================================================
-
-/**
- * Logical AND — all sub-conditions must pass.
- *
- * Accepts `TransitionCondition` objects or expression strings.
- *
- * @param conditions - Two or more conditions to combine.
- * @returns A `TransitionCondition` with an `AND` array.
- *
- * @example
- * ```typescript
- * import { and, isOwner, fieldEquals } from '@mindmatrix/react';
- *
- * conditions: [and(isOwner(), fieldEquals('status', 'draft'))]
- * ```
- */
-export function and(...conditions: (TransitionCondition | string)[]): TransitionCondition {
-  return { AND: conditions.map(normalize) };
-}
-
-/**
- * Logical OR — at least one sub-condition must pass.
- *
- * Accepts `TransitionCondition` objects or expression strings.
- * This is especially useful for "owner or admin" patterns common in chat models.
- *
- * @param conditions - Two or more conditions to combine.
- * @returns A `TransitionCondition` with an `OR` array.
- *
- * @example
- * ```typescript
- * import { or, isSender, hasRole } from '@mindmatrix/react';
- *
- * // Only the sender or an admin can delete — mirrors the chat-message delete pattern
- * transitions: {
- *   delete: {
- *     from: ['sent', 'delivered', 'read', 'edited'],
- *     to: 'deleted',
- *     conditions: [or(isSender(), hasRole('admin'))],
- *   },
- * }
- * ```
- */
-export function or(...conditions: (TransitionCondition | string)[]): TransitionCondition {
-  return { OR: conditions.map(normalize) };
-}
-
-/**
- * Logical NOT — negate a condition.
- *
- * Wraps the condition in an expression using `NOT(...)` if it is expression-based,
- * or creates a negated expression from the condition's semantic meaning.
- *
- * @param condition - The condition to negate (object or expression string).
- * @returns A `TransitionCondition` of type `'expression'` with the negated expression.
- *
- * @example
- * ```typescript
- * import { not, hasRole, fieldEquals } from '@mindmatrix/react';
- *
- * // Deny admins
- * conditions: [not(hasRole('admin'))]
- *
- * // Negate an expression
- * conditions: [not('state_data.locked == true')]
- * ```
- */
-export function not(condition: TransitionCondition | string): TransitionCondition {
-  const c = normalize(condition);
-  if (c.type === 'expression' && c.expression) {
-    return { type: 'expression', expression: `NOT(${c.expression})` };
-  }
-  if (c.type === 'role' && c.role) {
-    return { type: 'expression', expression: `NOT(context.roles CONTAINS "${c.role}")` };
-  }
-  if (c.type === 'field' && c.field) {
-    // Invert field operators
-    const invertedOps: Record<string, string> = {
-      eq: 'ne',
-      ne: 'eq',
-      gt: 'lte',
-      gte: 'lt',
-      lt: 'gte',
-      lte: 'gt',
-      in: 'not_in',
-      not_in: 'in',
-      is_set: 'is_empty',
-      is_empty: 'is_set',
-    };
-    const op = c.operator ?? 'eq';
-    const inverted = invertedOps[op];
-    if (inverted) {
-      return { type: 'field', field: c.field, operator: inverted, value: c.value };
-    }
-    // Fallback for operators without a clean inverse (contains, matches)
-    return { type: 'expression', expression: `NOT(state_data.${c.field} ${op.toUpperCase()} ${JSON.stringify(c.value)})` };
-  }
-  // Fallback: wrap the whole thing as a negated expression
-  return { type: 'expression', expression: `NOT(true)` };
-}
-
-// ============================================================================
-// CROSS-MODEL REFERENCE CHECKS
-// ============================================================================
-
-/**
- * Check a role on a referenced workflow instance (cross-model lookup).
- *
- * Uses the `$ref()` expression function to look up a related workflow instance
- * and check a role on it. This mirrors patterns from the chat-channel model
- * where membership roles are checked via `$ref("chat-membership", ...)`.
- *
- * Generates: `$ref("<slug>", "<lookupField>", <lookupValue>).role == "<role>"`
- *
- * @param slug - The workflow definition slug to look up.
- * @param lookupField - The field to match on in the referenced model.
- * @param lookupValue - The expression for the lookup value (e.g. `'state_data.id'`).
- * @param role - The role to check for.
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { refHasRole } from '@mindmatrix/react';
- *
- * // Only channel owners can delete — mirrors chat-channel delete pattern
- * transitions: {
- *   delete: {
- *     from: 'archived', to: 'deleted',
- *     conditions: [refHasRole('chat-membership', 'channel', 'state_data.id', 'owner')],
- *     // Generates: $ref("chat-membership", "channel", state_data.id).role == "owner"
- *   },
- * }
- * ```
- */
-export function refHasRole(slug: string, lookupField: string, lookupValue: string, role: string): TransitionCondition {
-  return {
-    type: 'expression',
-    expression: `$ref("${slug}", "${lookupField}", ${lookupValue}).role == "${role}"`,
-  };
-}
-
-/**
- * Check if a referenced workflow instance has any of the specified roles.
- *
- * Uses the `$ref()` expression function with an `IN` operator. This mirrors
- * the chat-channel archive/restore pattern.
- *
- * Generates: `$ref("<slug>", "<lookupField>", <lookupValue>).role IN [<roles>]`
- *
- * @param slug - The workflow definition slug to look up.
- * @param lookupField - The field to match on in the referenced model.
- * @param lookupValue - The expression for the lookup value.
- * @param roles - The roles to check for (at least one must match).
- * @returns A `TransitionCondition` of type `'expression'`.
- *
- * @example
- * ```typescript
- * import { refHasAnyRole } from '@mindmatrix/react';
- *
- * // Admins or owners can archive — mirrors chat-channel archive pattern
- * transitions: {
- *   archive: {
- *     from: ['active', 'muted'], to: 'archived',
- *     conditions: [refHasAnyRole('chat-membership', 'channel', 'state_data.id', ['admin', 'owner'])],
- *     // Generates: $ref("chat-membership", "channel", state_data.id).role IN ["admin", "owner"]
- *   },
- * }
- * ```
- */
-export function refHasAnyRole(slug: string, lookupField: string, lookupValue: string, roles: string[]): TransitionCondition {
-  const roleList = roles.map((r) => `"${r}"`).join(', ');
-  return {
-    type: 'expression',
-    expression: `$ref("${slug}", "${lookupField}", ${lookupValue}).role IN [${roleList}]`,
-  };
-}