@mantis-core/utils

Scalable utility toolkit for Mantis Core with runtime-specific modules.

See architecture governance in ARCHITECTURE.md.

Scope

• Shared reusable helpers for all Mantis Core apps/packages.
• Strong TypeScript contracts (Result, branded types, generic helpers).
• Runtime-separated APIs for safer imports:
  • isomorphic (@mantis-core/utils)
  • browser-only (@mantis-core/utils/browser)
  • node-only (@mantis-core/utils/node)

Out Of Scope

• Domain/business logic (real estate, leads, blog workflows).
• Supabase repositories/actions.
• Next.js route-specific behavior.

Folder Architecture

src/
  index.ts              # isomorphic public API
  types.ts              # shared advanced types
  isomorphic/
    index.ts
    classnames.ts
    select.ts
    date.ts
    currency.ts
    base64.ts
    sanitize-html.ts
  browser/
    index.ts
    device.ts
    events.ts
  node/
    index.ts
    crypto.ts

Public API

1) Isomorphic (@mantis-core/utils)

• cn(...inputs)
• getFilterValue(...)
• toStartOfDayIso(...)
• toEndOfDayIso(...)
• getPaginationRange(...)
• formatCurrency(...)
• encodeBase64Json(...)
• decodeBase64Json(...)
• decodeBase64JsonOrThrow(...)
• sanitizeHtmlContent(...)
• types: Brand, Result, JsonValue, MaybeArray, ValueOf

2) Browser (@mantis-core/utils/browser)

• isIOSDevice(...)
• isInStandaloneMode(...)
• isPwaInIOS(...)
• createClickIntentHandler(...)
• simulateTouch(...)
• setViewportHeightCssVar(...)

3) Node (@mantis-core/utils/node)

• hashString(...)
• toSha512(...), toSha256(...), toSha1(...), toMd5(...)
• generateRandomString(...)
• isAes256KeyHex(...)
• assertAes256KeyHex(...)
• encryptAes256Cbc(...)
• decryptAes256Cbc(...)
• types: HexDigest, Aes256KeyHex

Import Rules

• Use root import for cross-runtime helpers:
  • import { formatCurrency } from "@mantis-core/utils";
• Use explicit runtime subpaths for platform APIs:
  • import { toSha512 } from "@mantis-core/utils/node";
  • import { isPwaInIOS } from "@mantis-core/utils/browser";

Do not import node helpers in client bundles.

Build

pnpm --filter @mantis-core/utils build
pnpm --filter @mantis-core/utils typecheck

Scalability Rules

1. Place a utility by runtime first:
   • src/isomorphic/*: can execute in browser and Node.
   • src/browser/*: requires window, document, navigator, Touch*.
   • src/node/*: requires Node built-ins (node:*, Buffer, filesystem/crypto APIs).
2. Keep functions single-purpose and side-effect free when possible.
3. Prefer explicit return contracts (Result, branded types, discriminated unions) over thrown errors for recoverable failures.
4. Do not add domain/business vocabulary (houses, leads, blog workflows).
5. Any new utility must include:
   • named export from its runtime index.ts
   • README usage update if it is part of public API
   • package build/typecheck passing