@objectstack/spec 0.2.0 → 0.3.1

package/dist/data/validation.zod.d.ts

@@ -125,6 +125,65 @@ export declare const FormatValidationSchema: z.ZodObject<{
 /**
  * 5. Cross-Field Validation
  * Validates relationships between multiple fields.
+ *
+ * ## Use Cases
+ * - Date range validations (end_date > start_date)
+ * - Amount comparisons (discount < total)
+ * - Complex business rules involving multiple fields
+ *
+ * ## Salesforce Examples
+ *
+ * ### Example 1: Close Date Must Be In Current or Future Month
+ * **Salesforce Formula:**
+ * ```
+ * MONTH(CloseDate) < MONTH(TODAY()) ||
+ * YEAR(CloseDate) < YEAR(TODAY())
+ * ```
+ *
+ * **ObjectStack Equivalent:**
+ * ```typescript
+ * {
+ *   type: 'cross_field',
+ *   name: 'close_date_future',
+ *   condition: 'MONTH(close_date) >= MONTH(TODAY()) AND YEAR(close_date) >= YEAR(TODAY())',
+ *   fields: ['close_date'],
+ *   message: 'Close Date must be in the current or a future month'
+ * }
+ * ```
+ *
+ * ### Example 2: Discount Validation
+ * **Salesforce Formula:**
+ * ```
+ * Discount__c > (Amount__c * 0.40)
+ * ```
+ *
+ * **ObjectStack Equivalent:**
+ * ```typescript
+ * {
+ *   type: 'cross_field',
+ *   name: 'discount_limit',
+ *   condition: 'discount > (amount * 0.40)',
+ *   fields: ['discount', 'amount'],
+ *   message: 'Discount cannot exceed 40% of the amount'
+ * }
+ * ```
+ *
+ * ### Example 3: Opportunity Must Have Products
+ * **Salesforce Formula:**
+ * ```
+ * ISBLANK(Products__c) && ISPICKVAL(StageName, "Closed Won")
+ * ```
+ *
+ * **ObjectStack Equivalent:**
+ * ```typescript
+ * {
+ *   type: 'cross_field',
+ *   name: 'products_required_for_won',
+ *   condition: 'products = null AND stage = "closed_won"',
+ *   fields: ['products', 'stage'],
+ *   message: 'Opportunity must have products to be marked as Closed Won'
+ * }
+ * ```
  */
 export declare const CrossFieldValidationSchema: z.ZodObject<{
     name: z.ZodString;
@@ -155,6 +214,124 @@ export declare const CrossFieldValidationSchema: z.ZodObject<{
 /**
  * 6. Async Validation
  * Remote validation via API call or database query.
+ *
+ * ## Use Cases
+ *
+ * ### 1. Email Uniqueness Check
+ * Check if an email address is already registered in the system.
+ * ```typescript
+ * {
+ *   type: 'async',
+ *   name: 'unique_email',
+ *   field: 'email',
+ *   validatorUrl: '/api/users/check-email',
+ *   message: 'This email address is already registered',
+ *   debounce: 500,  // Wait 500ms after user stops typing
+ *   timeout: 3000
+ * }
+ * ```
+ *
+ * ### 2. Username Availability
+ * Verify username is available before form submission.
+ * ```typescript
+ * {
+ *   type: 'async',
+ *   name: 'username_available',
+ *   field: 'username',
+ *   validatorUrl: '/api/users/check-username',
+ *   message: 'This username is already taken',
+ *   debounce: 300,
+ *   timeout: 2000
+ * }
+ * ```
+ *
+ * ### 3. Tax ID Validation
+ * Validate tax ID with government API (e.g., IRS, HMRC).
+ * ```typescript
+ * {
+ *   type: 'async',
+ *   name: 'validate_tax_id',
+ *   field: 'tax_id',
+ *   validatorFunction: 'validateTaxIdWithIRS',
+ *   message: 'Invalid Tax ID number',
+ *   timeout: 10000,  // Government APIs may be slow
+ *   params: { country: 'US', format: 'EIN' }
+ * }
+ * ```
+ *
+ * ### 4. Credit Card Validation
+ * Verify credit card with payment gateway without charging.
+ * ```typescript
+ * {
+ *   type: 'async',
+ *   name: 'validate_card',
+ *   field: 'card_number',
+ *   validatorUrl: 'https://api.stripe.com/v1/tokens/validate',
+ *   message: 'Invalid credit card number',
+ *   timeout: 5000,
+ *   params: {
+ *     mode: 'validate_only',
+ *     checkFunds: false
+ *   }
+ * }
+ * ```
+ *
+ * ### 5. Address Validation
+ * Validate and standardize addresses using geocoding services.
+ * ```typescript
+ * {
+ *   type: 'async',
+ *   name: 'validate_address',
+ *   field: 'street_address',
+ *   validatorFunction: 'validateAddressWithGoogleMaps',
+ *   message: 'Unable to verify address',
+ *   timeout: 4000,
+ *   params: {
+ *     includeFields: ['city', 'state', 'zip'],
+ *     strictMode: true,
+ *     country: 'US'
+ *   }
+ * }
+ * ```
+ *
+ * ### 6. Domain Name Availability
+ * Check if domain name is available for registration.
+ * ```typescript
+ * {
+ *   type: 'async',
+ *   name: 'domain_available',
+ *   field: 'domain_name',
+ *   validatorUrl: '/api/domains/check-availability',
+ *   message: 'This domain is already taken or reserved',
+ *   debounce: 500,
+ *   timeout: 2000
+ * }
+ * ```
+ *
+ * ### 7. Coupon Code Validation
+ * Verify coupon code is valid and not expired.
+ * ```typescript
+ * {
+ *   type: 'async',
+ *   name: 'validate_coupon',
+ *   field: 'coupon_code',
+ *   validatorUrl: '/api/coupons/validate',
+ *   message: 'Invalid or expired coupon code',
+ *   timeout: 2000,
+ *   params: {
+ *     checkExpiration: true,
+ *     checkUsageLimit: true,
+ *     userId: '{{current_user_id}}'
+ *   }
+ * }
+ * ```
+ *
+ * ## Best Practices
+ * - Always set a reasonable `timeout` (default is 5000ms)
+ * - Use `debounce` for fields that are typed (300-500ms recommended)
+ * - Implement proper error handling on the server side
+ * - Cache validation results when appropriate
+ * - Consider rate limiting for external API calls
  */
 export declare const AsyncValidationSchema: z.ZodObject<{
     name: z.ZodString;
@@ -234,6 +411,178 @@ export declare const ValidationRuleSchema: z.ZodType<any>;
 /**
  * 8. Conditional Validation
  * Validation that only applies when a condition is met.
+ *
+ * ## Overview
+ * Conditional validations follow the pattern: "Validate X only if Y is true"
+ * This allows for context-aware validation rules that adapt to different scenarios.
+ *
+ * ## Use Cases
+ *
+ * ### 1. Validate Based on Record Type
+ * Apply different validation rules based on the type of record.
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'enterprise_approval_required',
+ *   when: 'account_type = "enterprise"',
+ *   message: 'Enterprise validation',
+ *   then: {
+ *     type: 'script',
+ *     name: 'require_approval',
+ *     message: 'Enterprise accounts require manager approval',
+ *     condition: 'approval_status = null'
+ *   }
+ * }
+ * ```
+ *
+ * ### 2. Conditional Field Requirements
+ * Require certain fields only when specific conditions are met.
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'shipping_address_when_required',
+ *   when: 'requires_shipping = true',
+ *   message: 'Shipping validation',
+ *   then: {
+ *     type: 'script',
+ *     name: 'shipping_address_required',
+ *     message: 'Shipping address is required for physical products',
+ *     condition: 'shipping_address = null OR shipping_address = ""'
+ *   }
+ * }
+ * ```
+ *
+ * ### 3. Amount-Based Validation
+ * Apply different rules based on transaction amount.
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'high_value_approval',
+ *   when: 'order_total > 10000',
+ *   message: 'High value order validation',
+ *   then: {
+ *     type: 'script',
+ *     name: 'manager_approval_required',
+ *     message: 'Orders over $10,000 require manager approval',
+ *     condition: 'manager_approval_id = null'
+ *   },
+ *   otherwise: {
+ *     type: 'script',
+ *     name: 'standard_validation',
+ *     message: 'Payment method is required',
+ *     condition: 'payment_method = null'
+ *   }
+ * }
+ * ```
+ *
+ * ### 4. Regional Compliance
+ * Apply region-specific validation rules.
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'regional_compliance',
+ *   when: 'region = "EU"',
+ *   message: 'EU compliance validation',
+ *   then: {
+ *     type: 'script',
+ *     name: 'gdpr_consent',
+ *     message: 'GDPR consent is required for EU customers',
+ *     condition: 'gdpr_consent_given = false'
+ *   },
+ *   otherwise: {
+ *     type: 'script',
+ *     name: 'tos_acceptance',
+ *     message: 'Terms of Service acceptance required',
+ *     condition: 'tos_accepted = false'
+ *   }
+ * }
+ * ```
+ *
+ * ### 5. Nested Conditional Validation
+ * Create complex validation logic with nested conditions.
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'country_state_validation',
+ *   when: 'country = "US"',
+ *   message: 'US-specific validation',
+ *   then: {
+ *     type: 'conditional',
+ *     name: 'california_validation',
+ *     when: 'state = "CA"',
+ *     message: 'California-specific validation',
+ *     then: {
+ *       type: 'script',
+ *       name: 'ca_tax_id_required',
+ *       message: 'California requires a valid tax ID',
+ *       condition: 'tax_id = null OR NOT(REGEX(tax_id, "^\\d{2}-\\d{7}$"))'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### 6. Tax Validation for Taxable Items
+ * Only validate tax fields when the item is taxable.
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'tax_field_validation',
+ *   when: 'is_taxable = true',
+ *   message: 'Tax validation',
+ *   then: {
+ *     type: 'script',
+ *     name: 'tax_code_required',
+ *     message: 'Tax code is required for taxable items',
+ *     condition: 'tax_code = null OR tax_code = ""'
+ *   }
+ * }
+ * ```
+ *
+ * ### 7. Role-Based Validation
+ * Apply validation based on user role.
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'role_based_approval_limit',
+ *   when: 'user_role = "manager"',
+ *   message: 'Manager approval limits',
+ *   then: {
+ *     type: 'script',
+ *     name: 'manager_limit',
+ *     message: 'Managers can approve up to $50,000',
+ *     condition: 'approval_amount > 50000'
+ *   }
+ * }
+ * ```
+ *
+ * ## Salesforce Pattern Comparison
+ *
+ * Salesforce doesn't have explicit "conditional validation" rules but achieves similar
+ * behavior using formula logic. ObjectStack makes this pattern explicit and composable.
+ *
+ * **Salesforce Approach:**
+ * ```
+ * IF(
+ *   ISPICKVAL(Type, "Enterprise"),
+ *   AND(Amount > 100000, ISBLANK(Approval__c)),
+ *   FALSE
+ * )
+ * ```
+ *
+ * **ObjectStack Approach:**
+ * ```typescript
+ * {
+ *   type: 'conditional',
+ *   name: 'enterprise_high_value',
+ *   when: 'type = "enterprise"',
+ *   then: {
+ *     type: 'cross_field',
+ *     name: 'amount_approval',
+ *     condition: 'amount > 100000 AND approval = null',
+ *     fields: ['amount', 'approval']
+ *   }
+ * }
+ * ```
  */
 export declare const ConditionalValidationSchema: z.ZodObject<{
     name: z.ZodString;

package/dist/data/validation.zod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.zod.d.ts","sourceRoot":"","sources":["../../src/data/validation.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;EAGjC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKrC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;EAIvC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKjC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;EAIrC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQhC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAW/C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKtC,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACrE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}
+{"version":3,"file":"validation.zod.d.ts","sourceRoot":"","sources":["../../src/data/validation.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2DxB;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;EAGjC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKrC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;EAIvC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKjC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;EAIrC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyHG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQhC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAW/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+KG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKtC,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACrE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}