credl-parser-evaluator/docs/USAGE_EXAMPLES.md

TypeScript-based CREDL Parser and Evaluator that processes CREDL files and outputs complete Intermediate Representations

# CREDL Parser and Evaluator - Usage Examples

This document provides comprehensive usage examples for the CREDL Parser and Evaluator library.

## Basic Usage

### Simple Property Analysis

```typescript
import { processFile } from 'credl-parser-evaluator';

const simpleProperty = `
metadata:
  version: 0.1
  name: "Simple Office Building"
  description: "Basic office property analysis"
  created_date: "2025-06-21"

assets:
  - id: "office-building-1"
    name: "Downtown Office Tower"
    property_type: "Office"
    location: "Chicago, IL"
    total_area_sf: 100000
    buildings:
      - id: "main-tower"
        name: "Main Tower"
        floors: 20
        total_area_sf: 100000

spaces:
  - id: "floor-5-suite-a"
    parent_building: "main-tower"
    type: "office"
    area_sf: 5000
    lease:
      status: "leased"
      tenant: "Tech Company Inc"
      rent_psf: 50
      lease_type: "NNN"

assumptions:
  - name: "discount_rate"
    type: "fixed"
    value: 0.08

models:
  - name: "base_dcf_model"
    type: "deterministic"
    duration_years: 10
    steps_per_year: 12
    inputs: ["discount_rate"]
    outputs: ["IRR", "NPV"]

simulation:
  type: "monte_carlo"
  iterations: 1000
  processes: {}
  outputs:
    summary_metrics: ["IRR", "NPV"]

outputs:
  format: "json"
  metrics: ["IRR", "NPV"]
`;

async function analyzeProperty() {
  const ir = await processFile(simpleProperty);
  console.log(`Processed ${ir.spaces.length} spaces`);
  console.log(`Valid: ${ir.validation.isValid}`);
  return ir;
}
```

## File Processing

### Processing Multiple Files

```typescript
import { processMultipleFiles, writeIRToFile } from 'credl-parser-evaluator';

async function processPortfolio() {
  const files = [
    './chicago-office.credl',
    './austin-retail.credl',
    './denver-residential.credl'
  ];

  const results = await processMultipleFiles(files, 
    { failFast: false },
    { includeDebugInfo: true },
    3 // Max concurrency
  );

  const successful = results.filter(r => r.ir);
  console.log(`Processed ${successful.length}/${files.length} files`);
  
  return results;
}
```

## Stream Processing

### Large File Processing

```typescript
import { processStream } from 'credl-parser-evaluator';
import { createReadStream } from 'fs';

async function processLargeFile(filePath: string) {
  const stream = createReadStream(filePath);
  const ir = await processStream(stream);
  
  console.log(`Processed ${ir.spaces.length} spaces via stream`);
  return ir;
}
```

## Advanced Features

### Working with Presets and Templates

```typescript
const credlWithPresets = `
presets:
  lease_profiles:
    office_standard:
      rent_psf: 45
      lease_type: "gross"
      escalation_rate: 0.025

templates:
  office_floor:
    spaces:
      - id_prefix: "Suite"
        type: "office"
        area_sf: 2500
        count: 4

use_templates:
  - template: "office_floor"
    parent_building: "building-1"
    start_index: 100
`;

async function analyzeAdvancedFeatures() {
  const ir = await processFile(credlWithPresets);
  
  if (ir.template_generated_spaces) {
    console.log(`Generated ${ir.template_generated_spaces.length} spaces from templates`);
  }
  
  return ir;
}
```

## Error Handling

### Robust Processing

```typescript
async function robustProcessing(yamlContent: string) {
  try {
    const ir = await processFile(yamlContent);
    
    if (!ir.validation.isValid) {
      console.warn('File has validation issues:');
      ir.validation.errors.forEach(error => {
        console.warn(`  ${error.field}: ${error.message}`);
      });
    }
    
    return ir;
    
  } catch (error) {
    console.error('Processing failed:', error);
    throw error;
  }
}
```

## Performance Optimization

### Batch Processing

```typescript
async function optimizedBatchProcessing(filePaths: string[]) {
  const batchSize = 5;
  const results = [];
  
  for (let i = 0; i < filePaths.length; i += batchSize) {
    const batch = filePaths.slice(i, i + batchSize);
    
    const batchResults = await processMultipleFiles(batch, 
      { failFast: false },
      { includeDebugInfo: false },
      3
    );
    
    results.push(...batchResults);
    
    // Small delay between batches
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return results;
}
```

For more detailed examples, see the `examples/` directory and test files.