TypeScript DataUtils Development Assistant
An expert assistant for working with the Typescript-DataUtils monorepo, which provides TypeScript utility classes for Azure services, caching, and pub/sub messaging operations.
Project Overview
This is a TypeScript monorepo containing data utility packages with the following structure:
**core** - Foundation package with shared models, interfaces, and utilities**azure-table-storage** - Azure Table Storage and Blob Storage helpers**azure-storage-queue** - Azure Storage Queue management**azure-service-bus-pubsub** - Azure Service Bus pub/sub messaging**memory-cache** - In-memory caching implementations**redis-cache** - Redis caching utilitiesInstructions
When working with this codebase, follow these guidelines:
1. Understanding the Architecture
Before making changes:
Recognize this is an interface-driven design where all major components implement interfaces (IDocumentStorageManager, IBasicCache, IPubSubManager)Understand that packages depend on `tsdatautils-core` as the foundationNote the event-driven processing pattern used by QueuedCommandRunner with EventEmitterBe aware of built-in retry mechanisms via ClassFunctionRetrierConsider the function distribution capabilities through ClassFunctionDistributorUnderstand throttling is provided by ClassFunctionThrottler2. Package Structure
Each package follows this structure:
`src/main.ts` - Main export file`src/models/` - TypeScript interfaces and type definitions`src/logic/` - Core business logic and utility classes`src/data/` - Data access and storage implementations`src/converters/` - Data transformation utilities`__tests__/` - Test files organized by functionality3. Development Workflow
When building or testing:
**Building:**
```bash
npm run clean # Clean build artifacts first
npm run build # Development build
npm run build-prod # Production build
```
**Linting:**
```bash
npm run lint # Check for issues
npm run lint-autofix # Auto-fix linting issues
```
**Testing:**
```bash
npm test # Full test suite with coverage
npm run test-only # Tests without linting
npm run test:watch # Watch mode
npm run test-azure # Azure-specific tests (if available)
npm run test-basic # Basic functionality tests (if available)
```
4. Code Conventions
When writing code:
Use TypeScript 4.2+ featuresTarget ES6 with CommonJS modulesImplement interfaces for all major componentsUse Winston for logging with custom transports and modifiersImplement throttling with `p-throttle` and `concurrent-queue` where neededFollow the existing patterns for retry mechanisms and function distributionInclude comprehensive test coverage using Jest with `ts-jest`5. Testing Guidelines
When writing tests:
Place test files in `__tests__/` directoryName files with `.spec.ts` or `.test.ts` suffixAvoid naming files `main.spec.ts` (excluded from test discovery)Use Jest testing framework with ts-jest transformerOrganize tests by functionalityGenerate coverage reports to ensure adequate testing6. Key Classes and Utilities
Be familiar with these core components:
**QueuedCommandRunner** - Manages concurrent job processing with event emissions**ClassFunctionRetrier** - Wraps objects with automatic retry logic**WinstonLogger** - Configurable logging with date stamp and interpolation modifiers**JsonSerializer** - JSON serialization with custom property handlersStorage managers with consistent interfaces for Azure services7. Publishing Changes
When ready to publish:
```bash
npm run publish-npm # Clean, build, and publish to npm
```
Usage Examples
Creating a New Utility Class
When adding a new utility class:
1. Define the interface in `src/models/`
2. Implement the class in `src/logic/` or appropriate directory
3. Export from `src/main.ts`
4. Create comprehensive tests in `__tests__/`
5. Update package dependencies if needed
6. Run full test suite before committing
Adding Azure Service Integration
When integrating a new Azure service:
1. Consider if it belongs in existing packages or needs a new package
2. Implement consistent interfaces following existing storage manager patterns
3. Use Winston logging for operations
4. Implement retry logic using ClassFunctionRetrier where appropriate
5. Add both basic and Azure-specific test suites
6. Document any required Azure configuration
Modifying Core Utilities
When modifying core utilities:
1. Remember that core is the foundation for all other packages
2. Test changes across all dependent packages
3. Maintain backward compatibility where possible
4. Update interface definitions if method signatures change
5. Run full test suite across the monorepo
Important Notes
Each package can be developed and published independentlyAll packages share TypeScript configuration targeting ES6/CommonJSStrict mode is enabled but with relaxed null checks and implicit anySource maps are enabled for debuggingTest files in both `src/` and `__tests__/` are included in compilationCoverage reports are generated in `/coverage` directory per package