av6-utils

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.

• 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.

Installation

npm install av6-utils
# or
pnpm add av6-utils

Importing

import { calculateBillingFromChildren, findDifferences, customOmit, getPattern, RoundFormat } from "av6-utils";

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:

const { rest, omitted } = customOmit({ id: 1, secret: "x" }, ["secret"]);
const licenseValid = getPattern.licenseTitle.test("AV6 License - 23");
const greeting = interpolate("Hi {{ user }}!", { user: "Ani" });

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:

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);

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:

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" }
// ]

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:

import { SuccessMessageType } from "av6-utils/dist/enums/message.enums.js";

const message = SuccessMessageType.CREATED.replace("%1", "Patient");

Note: enums are emitted into dist/enums by TypeScript. Adjust your import path or add an explicit re-export if using them frequently.

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

Development

npm install        # install deps
npm run build      # format *.ts files, then bundle via tsup (CJS+ESM+d.ts)

• 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.

Versioning & Publishing Checklist

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).

License

Licensed under the ISC License. © Aniket Sarkar.