@api-client/core 0.15.1 → 0.16.1

package/src/modeling/definitions/SKU.examples.md

@@ -0,0 +1,230 @@
+# SKU Semantic Examples
+
+This document provides examples of how to use the SKU semantic with different configurations.
+
+## Basic Usage
+
+```typescript
+import { createSKUSemantic, SKU_PRESETS } from './SKU.js'
+
+// Simple SKU with default settings
+const basicSKU = createSKUSemantic()
+
+// Using a preset for product catalogs
+const productSKU = SKU_PRESETS.PRODUCT_STANDARD
+```
+
+## Configuration Examples
+
+### 1. Standard Product Catalog
+
+```typescript
+const productCatalogSKU = createSKUSemantic({
+  validationMode: 'strict',
+  caseMode: 'uppercase',
+  prefix: 'PROD-',
+  enforceUniqueness: true,
+  validateReservedWords: true,
+})
+```
+
+### 2. Simple Inventory System
+
+```typescript
+const simpleSKU = createSKUSemantic({
+  validationMode: 'lenient',
+  caseMode: 'preserve',
+  enforceUniqueness: true,
+})
+```
+
+### 3. Auto-generating SKUs
+
+```typescript
+const autoGeneratedSKU = createSKUSemantic({
+  validationMode: 'strict',
+  caseMode: 'uppercase',
+  autoGenerate: true,
+  autoGenerateSource: 'name', // Generate from product name
+  enforceUniqueness: true,
+})
+```
+
+### 4. Custom Pattern Validation
+
+```typescript
+const customPatternSKU = createSKUSemantic({
+  validationMode: 'custom',
+  customPattern: '^[A-Z]{3}-\\d{4}-[A-Z]{2}$', // Format: ABC-1234-XY
+  caseMode: 'uppercase',
+  enforceUniqueness: true,
+})
+```
+
+### 5. Flexible Multi-category System
+
+```typescript
+const flexibleSKU = createSKUSemantic({
+  validationMode: 'lenient',
+  caseMode: 'preserve',
+  enforceUniqueness: true,
+  validateReservedWords: false, // Allow more flexibility
+})
+```
+
+## Storage Format Details
+
+### Database Schema Generation
+
+The runtime will generate appropriate database schemas with unique constraints:
+
+```sql
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255),
+  sku VARCHAR(50) UNIQUE NOT NULL,
+  description TEXT
+);
+
+-- Automatically creates unique index
+CREATE UNIQUE INDEX idx_products_sku ON products(sku);
+
+-- For case-insensitive uniqueness (depending on configuration)
+CREATE UNIQUE INDEX idx_products_sku_lower ON products(LOWER(sku));
+```
+
+### Case Transformation Examples
+
+```typescript
+// Uppercase transformation
+const uppercaseSKU = createSKUSemantic({ caseMode: 'uppercase' })
+// Input: "prod-123" → Stored: "PROD-123"
+
+// Lowercase transformation  
+const lowercaseSKU = createSKUSemantic({ caseMode: 'lowercase' })
+// Input: "PROD-123" → Stored: "prod-123"
+
+// Preserve original case
+const preserveCaseSKU = createSKUSemantic({ caseMode: 'preserve' })
+// Input: "Prod-123" → Stored: "Prod-123"
+```
+
+## Validation Examples
+
+### Strict Validation
+
+```typescript
+const strictSKU = createSKUSemantic({ validationMode: 'strict' })
+
+// Valid SKUs
+strictSKU.validate('PRODUCT123')  // ✓ Valid
+strictSKU.validate('PROD-123')    // ✓ Valid
+strictSKU.validate('PROD_123')    // ✓ Valid
+
+// Invalid SKUs
+strictSKU.validate('PROD.123')    // ✗ Contains dot
+strictSKU.validate('PROD@123')    // ✗ Contains special character
+strictSKU.validate('PROD 123')    // ✗ Contains space
+```
+
+### Lenient Validation
+
+```typescript
+const lenientSKU = createSKUSemantic({ validationMode: 'lenient' })
+
+// Valid SKUs
+lenientSKU.validate('PRODUCT123')  // ✓ Valid
+lenientSKU.validate('PROD-123')    // ✓ Valid
+lenientSKU.validate('PROD.123')    // ✓ Valid (dots allowed)
+
+// Invalid SKUs
+lenientSKU.validate('PROD@123')    // ✗ Special characters not allowed
+lenientSKU.validate('PROD#123')    // ✗ Hash not allowed
+```
+
+### Custom Pattern Validation
+
+```typescript
+const customSKU = createSKUSemantic({
+  validationMode: 'custom',
+  customPattern: '^[A-Z]{2}\\d{4}$' // Two letters followed by four digits
+})
+
+// Valid SKUs
+customSKU.validate('AB1234')  // ✓ Valid
+customSKU.validate('XY9999')  // ✓ Valid
+
+// Invalid SKUs
+customSKU.validate('ABC123')   // ✗ Wrong format
+customSKU.validate('ab1234')   // ✗ Lowercase letters
+customSKU.validate('A1234')    // ✗ Only one letter
+```
+
+## Reserved Words
+
+The SKU semantic includes protection against common reserved values:
+
+```typescript
+const skuConfig = createSKUSemantic({
+  validateReservedWords: true,
+  reservedValues: ['ADMIN', 'TEST', 'NULL', 'DEFAULT', 'SAMPLE']
+})
+
+// These will be rejected
+skuConfig.validate('ADMIN')   // ✗ Reserved word
+skuConfig.validate('test')    // ✗ Reserved word (case-insensitive)
+skuConfig.validate('NULL')    // ✗ Reserved word
+```
+
+## Auto-generation Behavior
+
+When `autoGenerate` is enabled, the runtime automatically creates SKUs:
+
+```typescript
+const autoSKU = createSKUSemantic({
+  autoGenerate: true,
+  autoGenerateSource: 'name',
+  prefix: 'PROD-',
+  caseMode: 'uppercase'
+})
+
+// For a product named "Blue Widget"
+// Generated SKU might be: "PROD-BLUE-WIDGET" or "PROD-BLUE-WIDGET-001"
+```
+
+## Error Handling
+
+```typescript
+import { validateSKUConfig, validateSKUValue } from './SKU.js'
+
+// Validate configuration
+const configErrors = validateSKUConfig({
+  validationMode: 'custom'  // Invalid: missing customPattern
+})
+console.log(configErrors) // ['customPattern is required when validationMode is custom']
+
+// Validate SKU values
+const valueErrors = validateSKUValue('TEST')
+console.log(valueErrors) // ['SKU cannot use reserved value: TEST']
+```
+
+## Integration with Domain Entities
+
+```typescript
+// In your domain model
+const productEntity = domain.addEntity({
+  name: 'Product',
+  properties: [
+    {
+      name: 'sku',
+      type: 'string',
+      semantics: [createSKUSemantic({
+        validationMode: 'strict',
+        caseMode: 'uppercase',
+        prefix: 'PROD-',
+        enforceUniqueness: true
+      })]
+    }
+  ]
+})
+```

package/src/modeling/definitions/SKU.ts

@@ -0,0 +1,254 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Supported SKU validation modes.
+ */
+export type SKUValidationMode = 'strict' | 'lenient' | 'custom'
+
+/**
+ * Supported SKU case transformation modes.
+ */
+export type SKUCaseMode = 'uppercase' | 'lowercase' | 'preserve'
+
+/**
+ * Configuration options for the SKU semantic.
+ * Controls SKU validation, formatting, uniqueness enforcement, and pattern matching.
+ */
+export interface SKUConfig {
+  /**
+   * The validation mode for SKU format.
+   *
+   * - 'strict': Enforces alphanumeric characters with optional hyphens/underscores
+   * - 'lenient': Allows more special characters but still validates basic format
+   * - 'custom': Uses custom regex pattern defined in `customPattern`
+   */
+  validationMode?: SKUValidationMode
+
+  /**
+   * Custom regex pattern for SKU validation when using 'custom' validation mode.
+   * Only used when validationMode is 'custom'.
+   */
+  customPattern?: string
+
+  /**
+   * Case transformation to apply to SKUs.
+   * - 'uppercase': Convert to uppercase (recommended for consistency)
+   * - 'lowercase': Convert to lowercase
+   * - 'preserve': Keep original case
+   */
+  caseMode?: SKUCaseMode
+
+  /**
+   * Prefix to automatically add to SKUs if not present.
+   * Useful for organizing SKUs by category (e.g., 'PROD-', 'SKU-').
+   */
+  prefix?: string
+
+  /**
+   * Whether to enforce global uniqueness across all entities.
+   * When true, creates unique database constraints.
+   * Default: true
+   */
+  enforceUniqueness?: boolean
+
+  /**
+   * Whether to auto-generate SKUs when not provided.
+   * When true, generates SKUs based on other fields or random values.
+   * Default: false
+   */
+  autoGenerate?: boolean
+
+  /**
+   * Field name to use as source for auto-generation.
+   * Only used when autoGenerate is true.
+   * If not specified, uses random generation.
+   */
+  autoGenerateSource?: string
+
+  /**
+   * Whether to validate that SKU doesn't conflict with reserved words or patterns.
+   * Default: true
+   */
+  validateReservedWords?: boolean
+
+  /**
+   * List of reserved SKU values that cannot be used.
+   * Common examples: 'ADMIN', 'TEST', 'NULL', 'DEFAULT'
+   */
+  reservedValues?: string[]
+
+  /**
+   * Custom metadata for the SKU field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for SKU semantic.
+ */
+export interface AppliedSKUSemantic extends AppliedDataSemantic {
+  id: SemanticType.SKU
+  config?: SKUConfig
+}
+
+/**
+ * Type guard to check if a semantic is a SKU semantic.
+ */
+export const isSKUSemantic = (semantic: AppliedDataSemantic): semantic is AppliedSKUSemantic => {
+  return semantic.id === SemanticType.SKU
+}
+
+/**
+ * Helper function to create a SKU semantic with configuration.
+ */
+export const createSKUSemantic = (config: SKUConfig = {}): AppliedSKUSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_SKU_CONFIG,
+    ...config,
+  }
+
+  // Merge metadata separately
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.SKU,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for SKU semantic.
+ * Optimized for common product catalog use cases.
+ */
+export const DEFAULT_SKU_CONFIG: SKUConfig = {
+  validationMode: 'strict',
+  caseMode: 'uppercase',
+  enforceUniqueness: true,
+  autoGenerate: false,
+  validateReservedWords: true,
+  reservedValues: ['ADMIN', 'TEST', 'NULL', 'DEFAULT', 'UNDEFINED', 'SAMPLE', 'DEMO'],
+}
+
+/**
+ * Predefined configurations for common use cases.
+ */
+export const SKU_PRESETS = {
+  /**
+   * Standard product SKU with strict validation and uppercase formatting.
+   */
+  PRODUCT_STANDARD: createSKUSemantic({
+    validationMode: 'strict',
+    caseMode: 'uppercase',
+    prefix: 'PROD-',
+    enforceUniqueness: true,
+  }),
+
+  /**
+   * Simple SKU configuration for basic catalogs.
+   */
+  SIMPLE: createSKUSemantic({
+    validationMode: 'lenient',
+    caseMode: 'preserve',
+    enforceUniqueness: true,
+  }),
+
+  /**
+   * Auto-generating SKU from product name.
+   */
+  AUTO_GENERATE: createSKUSemantic({
+    validationMode: 'strict',
+    caseMode: 'uppercase',
+    autoGenerate: true,
+    autoGenerateSource: 'name',
+    enforceUniqueness: true,
+  }),
+
+  /**
+   * Flexible SKU for variable product types.
+   */
+  FLEXIBLE: createSKUSemantic({
+    validationMode: 'lenient',
+    caseMode: 'preserve',
+    enforceUniqueness: true,
+    validateReservedWords: false,
+  }),
+} as const
+
+/**
+ * Helper function to validate a SKU configuration.
+ */
+export const validateSKUConfig = (config: SKUConfig): string[] => {
+  const errors: string[] = []
+
+  if (config.validationMode === 'custom' && !config.customPattern) {
+    errors.push('customPattern is required when validationMode is custom')
+  }
+
+  if (config.customPattern) {
+    try {
+      new RegExp(config.customPattern)
+    } catch {
+      errors.push('customPattern must be a valid regular expression')
+    }
+  }
+
+  if (config.prefix && config.prefix.length === 0) {
+    errors.push('prefix cannot be empty string')
+  }
+
+  if (config.autoGenerateSource && !config.autoGenerate) {
+    errors.push('autoGenerate must be true when autoGenerateSource is specified')
+  }
+
+  return errors
+}
+
+/**
+ * Helper function to validate SKU value against configuration.
+ */
+export const validateSKUValue = (value: string, config: SKUConfig = DEFAULT_SKU_CONFIG): string[] => {
+  const errors: string[] = []
+  const mergedConfig = { ...DEFAULT_SKU_CONFIG, ...config }
+
+  if (!value || typeof value !== 'string') {
+    errors.push('SKU value must be a non-empty string')
+    return errors
+  }
+
+  if (mergedConfig.validateReservedWords && mergedConfig.reservedValues) {
+    const normalizedValue = value.toUpperCase()
+    if (mergedConfig.reservedValues.some((reserved) => reserved.toUpperCase() === normalizedValue)) {
+      errors.push(`SKU cannot use reserved value: ${value}`)
+    }
+  }
+
+  // Validation pattern checks
+  if (mergedConfig.validationMode === 'strict') {
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+      errors.push('SKU can only contain alphanumeric characters, hyphens, and underscores')
+    }
+  } else if (mergedConfig.validationMode === 'lenient') {
+    if (!/^[A-Za-z0-9_.-]+$/.test(value)) {
+      errors.push('SKU contains invalid characters')
+    }
+  } else if (mergedConfig.validationMode === 'custom' && mergedConfig.customPattern) {
+    try {
+      const regex = new RegExp(mergedConfig.customPattern)
+      if (!regex.test(value)) {
+        errors.push('SKU does not match the required pattern')
+      }
+    } catch {
+      errors.push('Invalid custom pattern configuration')
+    }
+  }
+
+  return errors
+}

package/src/modeling/definitions/Status.ts

@@ -0,0 +1,227 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Status semantic.
+ * These options control state management and workflow behavior.
+ */
+export interface StatusConfig {
+  /**
+   * Allowed states for this status field.
+   * Only required when the field doesn't have enum values defined in the schema.
+   * If enum values are defined in DomainProperty > Schema, those values will be used instead.
+   */
+  allowedStates?: string[]
+
+  /**
+   * Default state when creating new records.
+   * Must be one of the allowedStates (if specified) or enum values from the schema.
+   */
+  defaultState: string
+
+  /**
+   * State transitions configuration.
+   * Maps from current state to array of allowed next states.
+   */
+  transitions?: Record<string, string[]>
+
+  /**
+   * State-specific behaviors and permissions.
+   */
+  stateBehaviors?: Record<
+    string,
+    {
+      /**
+       * Whether records in this state are publicly visible.
+       * Defaults to true if not specified.
+       */
+      isPublic?: boolean
+
+      /**
+       * Whether records in this state can be edited.
+       * Defaults to true if not specified.
+       */
+      isEditable?: boolean
+
+      /**
+       * Whether records in this state can be deleted.
+       * Defaults to false if not specified.
+       */
+      isDeletable?: boolean
+
+      /**
+       * Whether this state requires approval before transition.
+       * Defaults to false if not specified.
+       */
+      requiresApproval?: boolean
+
+      /**
+       * Custom display name for this state.
+       */
+      displayName?: string
+
+      /**
+       * Custom description for this state.
+       */
+      description?: string
+
+      /**
+       * Color or visual indicator for this state.
+       */
+      color?: string
+
+      /**
+       * Icon for this state.
+       */
+      icon?: string
+    }
+  >
+
+  /**
+   * Workflow configuration for status management.
+   */
+  workflow?: {
+    /**
+     * Whether status changes require approval.
+     * Defaults to false if not specified.
+     */
+    requiresApproval?: boolean
+
+    /**
+     * Roles that can approve status changes.
+     * Required if requiresApproval is true.
+     */
+    approvalRoles?: string[]
+
+    /**
+     * Whether to send notifications on status changes.
+     * Defaults to false if not specified.
+     */
+    sendNotifications?: boolean
+
+    /**
+     * Notification channels to use.
+     */
+    notificationChannels?: ('email' | 'sms' | 'push' | 'webhook')[]
+
+    /**
+     * Whether to log status change history.
+     * Defaults to true if not specified.
+     */
+    logHistory?: boolean
+
+    /**
+     * Whether to allow bulk status changes.
+     * Defaults to false if not specified.
+     */
+    allowBulkChanges?: boolean
+  }
+
+  /**
+   * Auto-transitions based on conditions.
+   */
+  autoTransitions?: {
+    /**
+     * Current state that triggers the auto-transition.
+     */
+    from: string
+
+    /**
+     * Target state to transition to.
+     */
+    to: string
+
+    /**
+     * Condition that triggers the transition.
+     * Examples: "after 24 hours", "when approved", "when payment received"
+     */
+    condition: string
+
+    /**
+     * Whether this auto-transition requires approval.
+     * Defaults to false if not specified.
+     */
+    requiresApproval?: boolean
+  }[]
+
+  /**
+   * Custom metadata for the status field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Status semantic.
+ */
+export interface AppliedStatusSemantic extends AppliedDataSemantic {
+  id: SemanticType.Status
+  config?: StatusConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Status semantic.
+ */
+export const isStatusSemantic = (semantic: AppliedDataSemantic): semantic is AppliedStatusSemantic => {
+  return semantic.id === SemanticType.Status
+}
+
+/**
+ * Helper function to create a Status semantic with configuration.
+ */
+export const createStatusSemantic = (config: Partial<StatusConfig> = {}): AppliedStatusSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_STATUS_CONFIG,
+    ...config,
+    // Deep merge nested objects
+    stateBehaviors: config.stateBehaviors
+      ? { ...DEFAULT_STATUS_CONFIG.stateBehaviors, ...config.stateBehaviors }
+      : DEFAULT_STATUS_CONFIG.stateBehaviors,
+    workflow: config.workflow
+      ? { ...DEFAULT_STATUS_CONFIG.workflow, ...config.workflow }
+      : DEFAULT_STATUS_CONFIG.workflow,
+  }
+
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Status,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Status semantic.
+ */
+export const DEFAULT_STATUS_CONFIG: StatusConfig = {
+  defaultState: 'draft',
+  stateBehaviors: {
+    draft: {
+      isPublic: false,
+      isEditable: true,
+      isDeletable: true,
+    },
+    published: {
+      isPublic: true,
+      isEditable: true,
+      isDeletable: false,
+    },
+    archived: {
+      isPublic: false,
+      isEditable: false,
+      isDeletable: false,
+    },
+  },
+  workflow: {
+    requiresApproval: false,
+    sendNotifications: false,
+    logHistory: true,
+    allowBulkChanges: false,
+  },
+}