av6-utils 1.0.0 → 1.0.1

package/README.md

@@ -1,234 +1,163 @@
-# AV6 Core
+# av6-utils
 
-A comprehensive utility library for AV6 Node.js projects, providing common functionality for data operations, caching, and Excel handling.
+Utilities shared across AV6 Node.js services, covering billing calculations, audit diffing, data-shaping helpers, and reusable regex patterns. Distributed as both CommonJS and ES modules with full TypeScript definitions.
 
-## Features
+- **Typed billing engine** for line-level and master-level price breakdowns with rounding, discount, tax, and co-pay rules.
+- **Audit helpers** that flatten nested payloads and report field-level changes.
+- **General-purpose helpers** for safe object access, numeric casting, regex lookups, templating, and more.
+- **Tree-shakable build** powered by `tsup`, shipping `dist/` bundles plus `.d.ts`.
 
-- **Dynamic Data Operations**: Flexible search, fetch, and CRUD operations with support for dynamic models
-- **Caching Support**: Built-in Redis caching for improved performance
-- **Excel Import/Export**: Seamless Excel file handling for data import and export
-- **Pagination**: Built-in pagination for search results
-- **DTO Mapping**: Support for Data Transfer Object mapping
-- **Type Safety**: Written in TypeScript with comprehensive type definitions
-- **UIN Config Management**: Unique Identification Number generation with configurable segments and automatic reset policies
+---
 
 ## Installation
 
 ```bash
-npm install av6-core
+npm install av6-utils
+# or
+pnpm add av6-utils
 ```
 
-## Usage
-
-### Basic Setup
-
-To use the library, you need to provide the necessary dependencies:
-
-```typescript
-import { commonService, Deps } from 'av6-core';
-import { PrismaClient } from '@prisma/client';
-import winston from 'winston';
-import { AsyncLocalStorage } from 'async_hooks';
-
-// Initialize dependencies
-const deps: Deps = {
-  config: {
-    REDIS_PREFIX: 'your-prefix:',
-    CACHE_KEY_NAME: 'your-cache-key'
-  },
-  mapper: {
-    dtoMapping: {}, // Your DTO mapping functions
-    mappingExport: {}, // Your export mapping functions
-    mappingImport: {}, // Your import mapping functions
-  },
-  helpers: {
-    generateErrorMessage: (type, ...variables) => {
-      // Your error message generation logic
-    },
-    ErrorHandler: class ErrorHandler extends Error {
-      // Your error handler implementation
-    }
-  },
-  logger: winston.createLogger({
-    // Your logger configuration
-  }),
-  cacheAdapter: {
-    // Your cache adapter implementation
-  },
-  requestStorage: new AsyncLocalStorage(),
-  db: new PrismaClient()
-};
-
-// Initialize the service
-const service = commonService(deps);
+### Importing
+
+```ts
+import { calculateBillingFromChildren, findDifferences, customOmit, getPattern, RoundFormat } from "av6-utils";
 ```
 
-### Search Operations
-
-```typescript
-// Perform a search operation
-const searchResult = await service.search({
-  pageNo: 1,
-  pageSize: 10,
-  shortCode: 'USER',
-  searchColumns: ['name', 'email'],
-  searchText: 'john',
-  sortBy: 'createdAt',
-  sortDir: 'DESC',
-  shortCodeData: {
-    shortCode: 'USER',
-    tableName: 'user',
-    isDTO: true,
-    isCacheable: true
-  }
-});
+The package exposes named exports only; pick the pieces you need for optimal bundling.
+
+---
+
+## Helper Utilities (`src/utils/helper.utils.ts`)
+
+| Function                               | Purpose                                                                           |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| `customOmit(obj, keys)`                | Returns `{ rest, omitted }`, splitting an object by keys.                         |
+| `getDynamicValue(obj, "path.to.leaf")` | Safely walks dot-notation paths, returning `null` when a segment is missing.      |
+| `objectTo2DArray(obj, maxCols)`        | Converts key/value pairs into rows with a configurable maximum number of columns. |
+| `toNumberOrNull(value)`                | Attempts to coerce to `number`, returning `null` if it fails.                     |
+| `getPattern[name]`                     | Registry of common regex patterns (emails, SKU, UUID, file extensions, etc.).     |
+| `interpolate(template, vars)`          | Basic `{{ placeholder }}` string interpolation.                                   |
+
+Example:
+
+```ts
+const { rest, omitted } = customOmit({ id: 1, secret: "x" }, ["secret"]);
+const licenseValid = getPattern.licenseTitle.test("AV6 License - 23");
+const greeting = interpolate("Hi {{ user }}!", { user: "Ani" });
 ```
 
-### Fetch Record
-
-```typescript
-// Fetch a specific record
-const record = await service.fetch({
-  shortCode: 'USER',
-  id: 123,
-  shortCodeData: {
-    shortCode: 'USER',
-    tableName: 'user',
-    isDTO: true,
-    isCacheable: true
-  }
-});
+---
+
+## Billing Calculation Utilities (`src/utils/calculation.utils.ts`)
+
+Two main exports power healthcare/commerce billing logic:
+
+- `calculateSingleChild(input, coPayMode, options)` – processes one line item.
+- `calculateBillingFromChildren(inputs, masterExtra, options)` – aggregates children, applies master-level discounts, and rounds headers.
+
+Key capabilities:
+
+- Supports **percentage or absolute discounts**, **inclusive/exclusive/none** tax methods, and **step-wise vs final** rounding.
+- Handles **co-pay** via `PERCENTAGE-AMOUNT` or `EXCLUSIVE-INCLUSIVE` strategies.
+- Provides fine-grained control over rounding via `RoundFormat` and `precision`.
+
+Example:
+
+```ts
+import { calculateBillingFromChildren, RoundFormat } from "av6-utils";
+
+const result = calculateBillingFromChildren(
+  [
+    { qty: 2, rate: 500, discountMode: "PERCENTAGE", discountValue: 10, taxMethod: "EXCLUSIVE", taxValue: 5 },
+    { qty: 1, rate: 1200, coPaymentType: "PERCENTAGE", coPayValue: 50 },
+  ],
+  { mode: "AMOUNT", value: 150, coPayMode: "PERCENTAGE-AMOUNT" },
+  { calculationMethod: "STEP_WISE", lineRound: RoundFormat.TO_FIXED, precision: 2 }
+);
+
+console.log(result.master.netAmount);
 ```
 
-### Excel Operations
-
-```typescript
-// Import data from Excel
-const importResult = await service.commonExcelImport({
-  shortCode: 'USER',
-  file: excelFile, // File object from upload
-  shortCodeData: {
-    shortCode: 'USER',
-    tableName: 'user'
-  }
-});
-
-// Export data to Excel
-const workbook = await service.commonExcelExport({
-  shortCode: 'USER',
-  isSample: false,
-  shortCodeData: {
-    shortCode: 'USER',
-    tableName: 'user'
-  }
-});
+All related TypeScript types (`ChildCalcInput`, `MasterAdditionalDiscount`, `ChildCalculated`, `BillingCalcResult`, etc.) are exported from `src/types/calculation.ts` for end-to-end typing.
+
+---
+
+## Audit Utilities (`src/utils/audit.utils.ts`)
+
+`findDifferences(obj1, obj2)` flattens nested objects, normalizes dates to `YYYY-MM-DD`, and returns an array of `CreateTransaction` entries detailing changes:
+
+```ts
+import { findDifferences } from "av6-utils";
+
+const changes = findDifferences(
+  { patient: { name: "Ava", dob: "1990-01-01" }, active: true },
+  { patient: { name: "Ava Smith", dob: "1990-01-01" }, active: false }
+);
+// [
+//   { field: "patient name", changedFrom: "Ava", changedTo: "Ava Smith" },
+//   { field: "active", changedFrom: "true", changedTo: "false" }
+// ]
 ```
 
-### UIN Config Operations
-
-```typescript
-import { uinConfigService, UinDeps, UIN_RESET_POLICY, UinShortCode } from 'av6-core';
-
-// Initialize UIN Config dependencies
-const uinDeps: UinDeps = {
-  config: {
-    REDIS_PREFIX: 'your-prefix:',
-    CACHE_KEY_NAME: 'your-cache-key'
-  },
-  helpers: {
-    generateErrorMessage: (type, ...variables) => {
-      // Your error message generation logic
-    },
-    ErrorHandler: class ErrorHandler extends Error {
-      // Your error handler implementation
-    }
-  },
-  logger: winston.createLogger({
-    // Your logger configuration
-  }),
-  cacheAdapter: {
-    // Your cache adapter implementation
-  },
-  requestStorage: new AsyncLocalStorage(),
-  db: new PrismaClient(),
-  prisma: PrismaNamespace,
-  shortCode: 'UIN_CONFIG',
-  cacheKey: 'uin-config'
-};
-
-// Initialize the UIN Config service
-const uinService = uinConfigService(uinDeps);
-
-// Create a new UIN Config
-const newUinConfig = await uinService.createUINConfig({
-  shortCode: UinShortCode.INVOICE,
-  seqResetPolicy: UIN_RESET_POLICY.monthly,
-  description: 'Invoice number generator',
-  uinSegments: [
-    { order: 1, type: 'text', value: 'INV-' },
-    { order: 2, type: 'dateFormat', value: 'YYYYMM' },
-    { order: 3, type: 'separator', value: '-' },
-    { order: 4, type: 'sequenceNo', minSeqLength: 5 }
-  ]
-});
-
-// Generate a UIN preview
-const uinPreview = await uinService.previewUIN({
-  uinSegments: [
-    { order: 1, type: 'text', value: 'INV-' },
-    { order: 2, type: 'dateFormat', value: 'YYYYMM' },
-    { order: 3, type: 'separator', value: '-' },
-    { order: 4, type: 'sequenceNo', minSeqLength: 5 }
-  ]
-});
-
-// Get a UIN Config by ID
-const uinConfig = await uinService.getUINConfigById(1);
-
-// Generate a new UIN
-const generatedUin = await uinService.generateUIN(UinShortCode.INVOICE);
+Supporting types live in `src/types/helper.ts`.
+
+---
+
+## Messages (`src/enums/message.enums.ts`)
+
+`SuccessMessageType` and `ErrorMessageType` centralize template strings for UI or API responses. Example:
+
+```ts
+import { SuccessMessageType } from "av6-utils/dist/enums/message.enums.js";
+
+const message = SuccessMessageType.CREATED.replace("%1", "Patient");
 ```
 
-## API Reference
+> Note: enums are emitted into `dist/enums` by TypeScript. Adjust your import path or add an explicit re-export if using them frequently.
+
+---
 
-### Common Service
+## Project Structure
+
+```
+src/
+ ├─ utils/
+ │   ├─ helper.utils.ts
+ │   ├─ calculation.utils.ts
+ │   └─ audit.utils.ts
+ ├─ enums/
+ │   └─ message.enums.ts
+ └─ types/
+     ├─ calculation.ts
+     └─ helper.ts
+dist/
+ └─ index.(js|mjs|d.ts|d.mts)   # Generated by tsup
+```
 
-The library provides a comprehensive service for common operations:
+---
 
-- `search`: Search records with pagination and filtering
-- `dropdownSearch`: Search records for dropdown components
-- `fixedSearch`: Search with fixed criteria
-- `fixedSearchWoPaginationService`: Search with fixed criteria without pagination
-- `commonExcelService`: Generate Excel workbooks
-- `fetch`: Fetch a specific record by ID
-- `commonExcelImport`: Import data from Excel files
-- `commonExcelExport`: Export data to Excel files
-- `delete`: Delete a record
-- `updateStatus`: Update the status of a record
-- `fetchImageStream`: Fetch an image as a stream
+## Development
 
-### UIN Config Service
+```bash
+npm install        # install deps
+npm run build      # format *.ts files, then bundle via tsup (CJS+ESM+d.ts)
+```
 
-The library provides a service for managing Unique Identification Numbers:
+- TypeScript config targets ES2022 with path alias `@/* → src/*`.
+- `tsup.config.ts` emits both module formats and cleans `dist/` on each build.
+- Prettier (installed as a dependency) keeps source formatting consistent.
 
-- `createUINConfig`: Create a new UIN configuration
-- `updateUINConfig`: Update an existing UIN configuration
-- `getUINConfigById`: Retrieve a UIN configuration by ID
-- `getAllUINConfig`: Retrieve all UIN configurations
-- `deleteUINConfig`: Delete a UIN configuration
-- `generateUIN`: Generate a new UIN based on a shortcode
-- `previewUIN`: Preview a UIN based on segment configuration
+---
 
-### Utility Functions
+## Versioning & Publishing Checklist
 
-The library also provides utility functions:
+1. Update `package.json` version and changelog notes (if any).
+2. `npm run build` to refresh `dist/`.
+3. Optionally run a smoke test by importing the built `dist/index.js`.
+4. `npm publish` from the package root (`packages/node-utils`).
 
-- `customOmit`: Omit specific keys from an object
-- `objectTo2DArray`: Convert an object to a 2D array
-- `toRelativeImageUrl`: Convert an absolute path to a relative image URL
+---
 
 ## License
 
-ISC
- 
-
+Licensed under the ISC License. © Aniket Sarkar.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "av6-utils",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",