# 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
      })]
    }
  ]
})
```
