@dynamatix/cat-shared

A comprehensive shared library for Catura Services providing data models, middleware, and services for document management, audit logging, and workflow automation.

📦 Installation

npm install @dynamatix/cat-shared

🚀 Quick Start

import { 
  DocumentModel, 
  AuditModel, 
  applyAuditMiddleware,
  getContext 
} from '@dynamatix/cat-shared';

// Use models directly
const document = new DocumentModel({
  filename: 'example.pdf',
  documentTypeId: '...',
  // ... other fields
});

// Apply audit middleware to track changes
applyAuditMiddleware(DocumentModel);

// Set request context
setContext({ userId: 'user123', requestId: 'req456' });

📚 Features

🔍 Data Models

• Document Management: DocumentModel, DocumentTypeModel, DocumentHistoryModel
• Audit & Compliance: AuditModel, AuditConfigModel
• Workflow Management: WorkflowConfigModel, WorkflowAlertModel
• Form Configuration: FormConfigurationModel
• Value Reference Mapping: ValueReferenceMapModel

🛡️ Audit Middleware

• Automatic change tracking for MongoDB documents
• Configurable audit logging with custom resolvers
• Support for complex field descriptions and lookups
• Integration with request context for user attribution

🔧 Services

• Request Context: AsyncLocalStorage-based context management
• Audit Hooks: Mongoose hooks for automatic audit logging

📖 API Reference

Models

DocumentModel

import { DocumentModel } from '@dynamatix/cat-shared';

const document = new DocumentModel({
  contextId: 'application123',
  filename: 'document.pdf',
  documentTypeId: 'type456',
  documentUrl: 'https://storage.example.com/doc.pdf',
  statusLid: 'status789',
  uploadedBy: 'user123'
});

AuditModel

import { AuditModel } from '@dynamatix/cat-shared';

const auditLog = new AuditModel({
  name: 'Document Updated',
  recordId: 'document123',
  contextId: 'application456',
  oldValue: { status: 'pending' },
  newValue: { status: 'approved' },
  createdBy: 'user789'
});

Middleware

applyAuditMiddleware

import { applyAuditMiddleware } from '@dynamatix/cat-shared';

// Apply audit middleware to a model
applyAuditMiddleware(DocumentModel);

// The model will now automatically log all changes

registerAuditHook

import { registerAuditHook } from '@dynamatix/cat-shared';

// Register custom audit hooks
registerAuditHook(DocumentModel, {
  pre: (doc) => console.log('Before save:', doc),
  post: (doc) => console.log('After save:', doc)
});

Services

Request Context

import { getContext, setContext } from '@dynamatix/cat-shared';

// Set context for the current request
setContext({
  userId: 'user123',
  requestId: 'req456',
  timestamp: new Date()
});

// Get context anywhere in the request lifecycle
const context = getContext();
console.log('Current user:', context.userId);

🔧 Configuration

Audit Configuration

The audit system uses AuditConfigModel to configure what fields to track and how to describe changes:

const auditConfig = new AuditConfigModel({
  modelName: 'Document',
  fields: ['status', 'filename'],
  descriptionField: 'filename',
  descriptionResolverType: 'direct'
});

Value Reference Mapping

Use ValueReferenceMapModel to configure how to resolve and display referenced fields:

const valueMap = new ValueReferenceMapModel({
  field: 'createdBy',
  model: 'User',
  displayField: 'fullName',
  descriptionResolverType: 'lookup'
});

🌱 Seeding

The project includes seeders for initial data setup:

# Run the value reference map seeder
node seeders/value-reference-map.seeder.js

📁 Project Structure

cat-shared/
├── models/                 # MongoDB/Mongoose data models
│   ├── document.model.js
│   ├── audit.model.js
│   ├── workflow-*.model.js
│   └── index.js
├── middlewares/           # Express/Node.js middleware
│   ├── audit.middleware.js
│   └── index.js
├── services/              # Business logic services
│   ├── request-context.service.js
│   ├── audit-log.hook.js
│   └── index.js
├── seeders/               # Database seeding scripts
├── utils/                 # Utility functions
└── index.js               # Main export file

🔌 Exports

The library provides the following export paths:

// Main exports
import { DocumentModel, AuditModel } from '@dynamatix/cat-shared';

// Specific module exports
import { DocumentModel } from '@dynamatix/cat-shared/models';
import { applyAuditMiddleware } from '@dynamatix/cat-shared/middlewares';
import { getContext } from '@dynamatix/cat-shared/services';

🧪 Development

Prerequisites

• Node.js 18+
• MongoDB
• Mongoose 8.13.1+

Local Development

# Clone the repository
git clone <repository-url>
cd cat-shared

# Install dependencies
npm install

# Run tests (when implemented)
npm test

📝 License

ISC License

🤝 Contributing

This is a shared library for Catura Services. Please contact the development team for contribution guidelines.

📞 Support

For support and questions, please contact the Catura Services development team.