@tiangong-lca/tidas-sdk 0.1.20 → 0.1.22

package/README.md

@@ -1,530 +1,253 @@
 # TIDAS TypeScript SDK
 
-[English](README.md) | [中文](README-zh.md)
+TypeScript SDK for TIDAS (TianGong Life Cycle Assessment data format) providing type-safe data manipulation, validation, and comprehensive schema support.
 
-A TypeScript SDK for ILCD/TIDAS data management that provides type-safe data operations for Life Cycle Assessment (LCA) data structures.
+## 🚀 Status
 
-## 🚀 Quick Start
+**Version**: 0.1.20 (Production Ready)
+**Published**: [@tiangong-lca/tidas-sdk](https://www.npmjs.com/package/@tiangong-lca/tidas-sdk)
 
-### Installation
+## ✨ Features
+
+- ✅ **Type-Safe Operations**: Full TypeScript support with generated types
+- ✅ **Runtime Validation**: Zod schema validation for all TIDAS data types
+- ✅ **Complete Schema Coverage**: Support for all 18 TIDAS data types
+- ✅ **Property Access**: Convenient API for accessing nested properties
+- ✅ **Object Utilities**: Factory functions and manipulation utilities
+- ✅ **JSON Conversion**: Seamless serialization/deserialization
+
+## 📦 Installation
 
 ```bash
 npm install @tiangong-lca/tidas-sdk
 ```
 
+## 🔧 Quick Start
+
 ### Basic Usage
 
 ```typescript
-import { createContact } from '@tiangong-lca/tidas-sdk/core';
-
-// Create a new Contact entity
-const contact = createContact();
-
-// Set multilingual name (recommended: use setText method)
-contact.contactDataSet.contactInformation.dataSetInformation['common:name'].setText?.('Dr. Jane Smith', 'en');
-contact.contactDataSet.contactInformation.dataSetInformation['common:name'].setText?.('Dr. Jane Smith', 'fr');
-
-// You can also set the multilingual array directly
-contact.contactDataSet.contactInformation.dataSetInformation['common:shortName'] = [
-  { '@xml:lang': 'en', '#text': 'J. Smith' },
-  { '@xml:lang': 'fr', '#text': 'J. Smith' },
-];
+import { createTidasContact, TidasContact } from '@tiangong-lca/tidas-sdk';
 
-// Get the name in a specific language
-const enName = contact.contactDataSet.contactInformation.dataSetInformation['common:name'].getText?.('en');
+// Create a contact using factory function
+const contact = createTidasContact({
+  name: "Example Organization",
+  email: "contact@example.com"
+});
 
-// Validate the entity
-const validation = contact.validate();
-console.log('Valid:', validation.success);
+// Access properties with type safety
+console.log(contact.name); // "Example Organization"
 
-// Convert to JSON string
-const json = contact.toJSONString(2);
-console.log(json);
+// Convert to JSON
+const json = contact.toJSON();
 ```
 
-## 📦 Package Structure
-
-The SDK provides multiple entry points for different use cases:
+### Advanced Usage
 
 ```typescript
-// Core functionality (recommended)
-import { createContact, createFlow } from '@tiangong-lca/tidas-sdk/core';
-
-// Type definitions
-import { Contact, Flow } from '@tiangong-lca/tidas-sdk/types';
-
-// Zod schemas for validation
-import { ContactSchema } from '@tiangong-lca/tidas-sdk/schemas';
-
-// Utility functions
-import { objectUtils } from '@tiangong-lca/tidas-sdk/utils';
+import { 
+  TidasProcess,
+  createTidasProcess,
+  validateTidasData
+} from '@tiangong-lca/tidas-sdk';
+
+// Create and validate complex objects
+const process = createTidasProcess({
+  name: "Manufacturing Process",
+  description: "Production of electronic components"
+});
 
-// Everything (for convenience, but larger bundle)
-import * from '@tiangong-lca/tidas-sdk';
+// Validate data
+const validation = validateTidasData(process, 'Process');
+if (!validation.success) {
+  console.error('Validation errors:', validation.errors);
+}
 ```
 
-## 🏗️ Features
-
-- **Type Safety**: Full TypeScript support with generated types from ILCD schemas
-- **Runtime Validation**: Zod-based validation with configurable modes (strict/weak/ignore)
-- **8 Entity Types**: Support for all core TIDAS entities
-- **JSON Interoperability**: Seamless conversion between objects and JSON
-- **Batch Operations**: Efficient processing of multiple entities
-- **Multi-language Support**: Built-in support for multi-language text fields
-- **Performance Optimized**: Configurable validation for performance-critical scenarios
-- **AI-Powered Suggestions**: Improve data quality using TIDAS methodology rules
+## 🏗️ Architecture
 
-## 📚 Usage Guide
-
-### 1. Creating Entities
-
-The SDK supports all 8 TIDAS entity types:
+### Module Structure
 
 ```typescript
-import {
-  createContact,
-  createFlow,
-  createProcess,
-  createSource,
-  createFlowProperty,
-  createUnitGroup,
-  createLCIAMethod,
-  createLifeCycleModel,
-} from '@tiangong-lca/tidas-sdk/core';
-
-// Create individual entities
-const contact = createContact();
-const flow = createFlow();
-const process = createProcess();
-
-// Create entities from existing data
-const existingData = { /* TIDAS data structure */ };
-const processWithData = createProcess(existingData);
-```
+// Core imports
+import { 
+  // Types
+  TidasContact,
+  TidasProcess,
+  TidasFlow,
+  // ... all 18 TIDAS types
+
+  // Factory functions
+  createTidasContact,
+  createTidasProcess,
+  createTidasFlow,
+  // ... all factory functions
+
+  // Utilities
+  validateTidasData,
+  convertToJSON,
+  convertFromJSON
+} from '@tiangong-lca/tidas-sdk';
+
+// Individual modules
+import { TidasContact } from '@tiangong-lca/tidas-sdk/core';
+import { TidasTypes } from '@tiangong-lca/tidas-sdk/types';
+import { TidasSchemas } from '@tiangong-lca/tidas-sdk/schemas';
+import { TidasUtils } from '@tiangong-lca/tidas-sdk/utils';
+```
+
+### Supported TIDAS Data Types
+
+- TidasContact
+- TidasFlow
+- TidasProcess
+- TidasSource
+- TidasFlowProperty
+- TidasUnitGroup
+- TidasLCIAMethod
+- TidasLifeCycleModel
+- And 10 additional specialized types
+
+## 🧪 Development
+
+### Setup
 
-### 2. Working with Multi-language Fields
-
-TIDAS entities support multi-language text fields:
-
-```typescript
-// Using setText/getText methods (recommended)
-flow.flowDataSet.flowInformation.dataSetInformation.name.baseName.setText?.('Water', 'en');
-flow.flowDataSet.flowInformation.dataSetInformation.name.baseName.setText?.('Wasser', 'de');
-flow.flowDataSet.flowInformation.dataSetInformation.name.baseName.setText?.('Eau', 'fr');
-
-// Get text in a specific language
-const englishName = flow.flowDataSet.flowInformation.dataSetInformation.name.baseName.getText?.('en');
-
-// Direct array assignment
-flow.flowDataSet.flowInformation.dataSetInformation['common:generalComment'] = [
-  { '@xml:lang': 'en', '#text': 'Pure water for industrial processes' },
-  { '@xml:lang': 'de', '#text': 'Reines Wasser für industrielle Prozesse' },
-  { '@xml:lang': 'fr', '#text': 'Eau pure pour les processus industriels' },
-];
-```
+```bash
+# Clone repository
+git clone https://github.com/tiangong-lca/tidas-sdk.git
+cd tidas-sdk/sdks/typescript
 
-### 3. Validation Modes
+# Install dependencies
+npm install
 
-The SDK provides three validation modes to balance data quality and performance:
+# Build the SDK
+npm run build
 
-```typescript
-import {
-  createProcess,
-  setGlobalValidationMode,
-  getGlobalValidationMode
-} from '@tiangong-lca/tidas-sdk/core';
-
-// Strict validation (default) - Full schema validation, rejects on any error
-const strictProcess = createProcess({}, { mode: 'strict' });
-const result = strictProcess.validate();
-
-// Weak validation - Non-critical issues become warnings
-const weakProcess = createProcess({}, { mode: 'weak', includeWarnings: true });
-const enhanced = weakProcess.validateEnhanced();
-console.log('Warnings:', enhanced.warnings);
-
-// Ignore validation - Skip validation for maximum performance
-const fastProcess = createProcess({}, { mode: 'ignore' });
-// Always passes validation - ideal for bulk operations
-
-// Global validation configuration
-setGlobalValidationMode('weak'); // Applies to all new entities
-const process = createProcess(); // Uses weak validation
-
-// Runtime configuration changes
-process.setValidationMode('strict');
-console.log('Current mode:', process.getValidationConfig().mode);
+# Run tests
+npm test
 ```
 
-### 4. Batch Operations
-
-Create and process multiple entities efficiently:
-
-```typescript
-import { createFlowsBatch, createContactsBatch } from '@tiangong-lca/tidas-sdk/core';
-
-// Create multiple entities at once
-const flowsData = [
-  { flowDataSet: { /* data 1 */ } },
-  { flowDataSet: { /* data 2 */ } },
-  { flowDataSet: { /* data 3 */ } },
-];
-
-const flows = createFlowsBatch(flowsData, { mode: 'weak' });
-
-// Process in batch
-flows.forEach((flow, index) => {
-  flow.flowDataSet.flowInformation.dataSetInformation.name.baseName.setText?.(
-    `Flow ${index + 1}`,
-    'en'
-  );
-});
+### Development Commands
 
-// Validate all
-const validationResults = flows.map(flow => flow.validate());
-const successCount = validationResults.filter(r => r.success).length;
-console.log(`${successCount}/${flows.length} flows are valid`);
-```
+```bash
+# Development mode (watch)
+npm run dev
 
-### 5. JSON Operations
+# Type checking
+npm run typecheck
 
-Convert between entities and JSON:
+# Linting
+npm run lint
+npm run lint:fix
 
-```typescript
-// Export to JSON
-const jsonString = process.toJSONString(2); // Pretty-printed with 2-space indent
-const jsonObject = process.toJSON();
+# Formatting
+npm run format
+npm run format:check
 
-// Import from JSON string
-import { createProcess } from '@tiangong-lca/tidas-sdk/core';
+# Testing
+npm test
+npm run test:watch
+npm run test:coverage
 
-const jsonData = '{ "processDataSet": { ... } }';
-const parsedData = JSON.parse(jsonData);
-const importedProcess = createProcess(parsedData);
-
-// Verify imported data
-const validation = importedProcess.validate();
-if (validation.success) {
-  console.log('Successfully imported and validated');
-}
+# Build
+npm run clean
+npm run build
 ```
 
-### 6. Entity Cloning
+### Testing
 
-Create copies of entities:
-
-```typescript
-// Clone an existing entity
-const originalContact = createContact();
-originalContact.contactDataSet.contactInformation.dataSetInformation['common:name'].setText?.('Dr. Alice Johnson', 'en');
-
-const clonedContact = originalContact.clone();
+```bash
+# Run all tests
+npm test
 
-// Modify the clone independently
-clonedContact.contactDataSet.contactInformation.dataSetInformation['common:name'] = [
-  { '@xml:lang': 'en', '#text': 'Dr. Alice Johnson (Copy)' }
-];
+# Watch mode
+npm run test:watch
 
-// Generate new UUID for the clone
-clonedContact.contactDataSet.contactInformation.dataSetInformation['common:UUID'] = crypto.randomUUID();
+# Coverage report
+npm run test:coverage
 ```
 
-### 7. Entity Relationships
+## 📚 Examples
 
-Build relationships between different entity types:
+See the [examples](./examples/) directory for comprehensive usage examples:
 
-```typescript
-// Create related entities
-const massUnitGroup = createUnitGroup();
-massUnitGroup.unitGroupDataSet.unitGroupInformation.dataSetInformation['common:name'] = [
-  { '@xml:lang': 'en', '#text': 'Mass units' }
-];
-
-const massFlowProperty = createFlowProperty();
-massFlowProperty.flowPropertyDataSet.flowPropertiesInformation.dataSetInformation['common:name'] = [
-  { '@xml:lang': 'en', '#text': 'Mass' }
-];
-
-// Reference unit group in flow property
-const unitGroupUUID = massUnitGroup.unitGroupDataSet.unitGroupInformation.dataSetInformation['common:UUID'];
-massFlowProperty.flowPropertyDataSet.flowPropertiesInformation.quantitativeReference.referenceToReferenceUnitGroup = {
-  '@type': 'unit group data set',
-  '@refObjectId': unitGroupUUID,
-  '@version': '1.0.0',
-  '@uri': '',
-  'common:shortDescription': [{ '@xml:lang': 'en', '#text': 'Mass units' }],
-};
-
-// Create a flow using this flow property
-const co2Flow = createFlow();
-const flowPropertyUUID = massFlowProperty.flowPropertyDataSet.flowPropertiesInformation.dataSetInformation['common:UUID'];
-co2Flow.flowDataSet.flowProperties.flowProperty = {
-  '@dataSetInternalID': '0',
-  referenceToFlowPropertyDataSet: {
-    '@type': 'flow property data set',
-    '@refObjectId': flowPropertyUUID,
-    '@version': '1.0.0',
-    '@uri': '',
-    'common:shortDescription': [{ '@xml:lang': 'en', '#text': 'Mass' }],
-  },
-  meanValue: '1.0',
-};
-```
-
-### 8. AI-Powered Data Improvement
+- [01-basic-usage](./examples/01-basic-usage/) - Basic object creation and manipulation
+- [02-object-oriented-usage](./examples/02-object-oriented-usage/) - Advanced patterns
+- [03-complete-tidas-entities](./examples/03-complete-tidas-entities/) - All data types
 
-Use AI to improve data quality and compliance with TIDAS methodology rules:
+## 🔗 API Reference
 
-```typescript
-import { createProcess, suggestData } from '@tiangong-lca/tidas-sdk';
+### Factory Functions
 
-// Set your OpenAI API key (required)
-process.env.OPENAI_API_KEY = 'your-api-key';
+All TIDAS types have corresponding factory functions:
 
-// Method 1: Using entity's suggest method
-const process = createProcess({ processDataSet: { /* incomplete data */ } });
-const result = await process.suggest({
-  outputDiffSummary: true,  // Get text diff summary
-  outputDiffHTML: true,      // Get HTML diff viewer
-});
+```typescript
+// General pattern
+createTidas{Type}(data: Partial<Tidas{Type}>): Tidas{Type}
 
-console.log(result.data);        // The improved entity
-console.log(result.diffSummary); // Text diff summary
-console.log(result.diffHTML);    // HTML diff visualization
-
-// Method 2: Using the suggestData service function
-const improvedResult = await suggestData(
-  { processDataSet: { /* data */ } },
-  'process',
-  {
-    skipPaths: ['administrativeInformation'],  // Skip certain paths
-    maxRetries: 2,                              // Retry on validation failures
-    outputDiffSummary: true
-  }
-);
-
-// Method 3: Batch suggestions
-import { batchSuggest } from '@tiangong-lca/tidas-sdk';
-
-const results = await batchSuggest([
-  { data: processData1, type: 'process' },
-  { data: flowData, type: 'flow' },
-  { data: contactData, type: 'contact' }
-]);
+// Examples
+createTidasContact(data)
+createTidasProcess(data)
+createTidasFlow(data)
 ```
 
-### 9. Validation Error Handling
-
-Handle validation errors gracefully:
+### Validation
 
 ```typescript
-// Basic validation
-const process = createProcess();
-const validation = process.validate();
-
-if (!validation.success) {
-  console.log('Validation errors:', validation.error.issues);
-  validation.error.issues.forEach(issue => {
-    console.log(`- ${issue.path.join('.')}: ${issue.message}`);
-  });
-}
-
-// Enhanced validation with warnings
-const weakProcess = createProcess({}, { mode: 'weak', includeWarnings: true });
-const enhanced = weakProcess.validateEnhanced();
-
-if (enhanced.warnings) {
-  console.log('Validation warnings:');
-  enhanced.warnings.forEach(warning => {
-    console.log(`[${warning.severity}] ${warning.path.join('.')}: ${warning.message}`);
-  });
+// Validate any TIDAS data
+const result = validateTidasData(data, 'Contact');
+if (result.success) {
+  // Data is valid
+} else {
+  // Handle validation errors
+  console.error(result.errors);
 }
 ```
 
-### 10. Performance Optimization
-
-For performance-critical scenarios:
+### Property Access
 
 ```typescript
-// Use ignore mode for bulk operations
-const startTime = performance.now();
-const manyFlows = createFlowsBatch(
-  Array(1000).fill({}),
-  { mode: 'ignore' }  // Skip validation for maximum speed
-);
-const endTime = performance.now();
-console.log(`Created 1000 flows in ${endTime - startTime}ms`);
-
-// Configure properties without validation overhead
-manyFlows.forEach((flow, index) => {
-  flow.flowDataSet.flowInformation.dataSetInformation.name.baseName.setText?.(
-    `Flow ${index}`,
-    'en'
-  );
-});
-
-// Validate only when needed
-const validationResults = manyFlows.map(f => f.validate());
+// Access nested properties with type safety
+const contact = createTidasContact(data);
+const email = contact.email; // Type: string | undefined
+const address = contact.address?.street; // Type: string | undefined
 ```
 
-## 📚 Examples
+## 📖 Documentation
 
-The `examples/` directory contains comprehensive usage examples:
+- **Development Guidelines**: [../../CLAUDE.md](../../CLAUDE.md)
+- **Project Progress**: [../../docs/development-progress.md](../../docs/development-progress.md)
+- **Requirements**: [../../docs/requirement-design.md](../../docs/requirement-design.md)
+- **Release Notes**: [RELEASE.md](./RELEASE.md)
 
-- `01-basic-usage/` - Simple entity creation and basic operations
-- `02-advanced-features/` - Advanced patterns including batch operations and relationships
-- `03-validation-modes/` - Comprehensive validation configuration examples
+## 🚀 Release
 
-To run the examples:
+Automated release process:
 
 ```bash
-cd examples
-npm install
-npm run run-basic      # Basic entity usage
-npm run run-advanced   # Advanced usage patterns
-npm run run-validation # Validation configuration demo
-```
-
-See [examples/README.md](examples/README.md) for detailed information.
-
-## 🔧 Development
+# Patch release (x.y.Z)
+npm run release:patch
 
-This repository contains the source code for the SDK. The examples use the published npm package.
+# Minor release (x.Y.z)
+npm run release:minor
 
-### Build Commands
-
-```bash
-npm run build               # Compile TypeScript
-npm run dev                 # Watch mode
-npm run generate-types      # Generate types from schemas
-npm run generate-schemas    # Generate Zod schemas
-npm run test                # Run tests
-npm run lint                # Lint code
-npm run format              # Format code
-```
-
-### Project Structure
-
-```
-tidas-typescript/
-├── src/
-│   ├── types/           # Generated TypeScript types (18 files)
-│   ├── schemas/         # Generated Zod schemas (18 files)
-│   ├── core/            # Core functionality
-│   │   ├── base/        # TidasEntity base class
-│   │   ├── entities/    # 8 entity classes
-│   │   ├── factories/   # Factory functions
-│   │   └── config/      # Validation configuration
-│   ├── utils/           # Utility functions
-│   └── services/        # AI suggestion service
-├── examples/            # Usage examples
-├── scripts/             # Code generation scripts
-└── dist/               # Compiled output
+# Major release (X.y.z)
+npm run release:major
 ```
 
 ## 🤝 Contributing
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests and examples
-5. Submit a pull request
+We welcome contributions! Please:
+1. Follow the development guidelines
+2. Add tests for new functionality
+3. Ensure all tests pass and code is properly formatted
+4. Update documentation as needed
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## 🏷️ Version
-
-Current version: 0.1.16
+MIT License - see [LICENSE](../LICENSE) file for details.
 
-## 🔗 Links
+## 🔗 Related Packages
 
-- [npm package](https://www.npmjs.com/package/@tiangong-lca/tidas-sdk)
-- [GitHub repository](https://github.com/tiangong-lca/tidas-sdk)
-
-## 📖 API Reference
-
-### Core Entities
-
-All entity types follow the same pattern:
-
-- `TidasContact` - Contact/organization information
-- `TidasFlow` - Material or energy flows
-- `TidasProcess` - Process datasets
-- `TidasSource` - Literature sources
-- `TidasFlowProperty` - Flow properties (e.g., mass, energy)
-- `TidasUnitGroup` - Unit groups for measurements
-- `TidasLCIAMethod` - LCIA methodology data
-- `TidasLifeCycleModel` - Life cycle models
-
-### Factory Functions
-
-- `createContact(data?, config?)` - Create Contact entity
-- `createFlow(data?, config?)` - Create Flow entity
-- `createProcess(data?, config?)` - Create Process entity
-- `createSource(data?, config?)` - Create Source entity
-- `createFlowProperty(data?, config?)` - Create FlowProperty entity
-- `createUnitGroup(data?, config?)` - Create UnitGroup entity
-- `createLCIAMethod(data?, config?)` - Create LCIAMethod entity
-- `createLifeCycleModel(data?, config?)` - Create LifeCycleModel entity
-
-Batch factory functions:
-
-- `createContactsBatch(dataArray, config?)` - Create multiple Contacts
-- `createFlowsBatch(dataArray, config?)` - Create multiple Flows
-- `createProcessesBatch(dataArray, config?)` - Create multiple Processes
-- (Similar batch functions for all entity types)
-
-### Entity Methods
-
-All entities inherit these methods from `TidasEntity`:
-
-- `validate()` - Validate entity data (legacy format)
-- `validateEnhanced()` - Enhanced validation with warnings
-- `toJSON()` - Convert to plain JavaScript object
-- `toJSONString(indent?)` - Convert to JSON string
-- `clone()` - Create a deep copy of the entity
-- `getValue(path)` - Get nested value using dot notation
-- `getValidationConfig()` - Get current validation configuration
-- `setValidationMode(mode)` - Set validation mode
-- `setValidationConfig(config)` - Set validation configuration
-- `suggest(options?)` - AI-powered data improvement
-
-### Validation Configuration
-
-```typescript
-interface ValidationConfig {
-  mode: 'strict' | 'weak' | 'ignore';
-  includeWarnings?: boolean;
-}
-
-// Global configuration functions
-setGlobalValidationMode(mode: 'strict' | 'weak' | 'ignore'): void
-getGlobalValidationMode(): 'strict' | 'weak' | 'ignore'
-setGlobalValidationConfig(config: Partial<ValidationConfig>): void
-resetGlobalConfig(): void
-```
-
-### AI Suggestion Service
-
-```typescript
-// Suggest improvements for data
-suggestData(
-  data: any,
-  dataType: DataType,
-  options?: SuggestOptions
-): Promise<SuggestResult>
-
-// Batch suggestions
-batchSuggest(
-  items: Array<{ data: any; type: DataType }>,
-  options?: SuggestOptions
-): Promise<SuggestResult[]>
-
-// Validate API key
-validateApiKey(): boolean
-
-// Get available data types
-getAvailableDataTypes(): string[]
-```
+- [tidas-tools](https://pypi.org/project/tidas-tools/): Python utilities for TIDAS data
+- [tidas-python-sdk](../python/): Python SDK (in development)