@zebec-network/core-utils

Core TypeScript utilities used across the Zebec Network SDK and services. The package collects small, dependency-light helpers for financial-rate conversion, buffer validation, SHA-256 hashing, date comparison, email shape checks, and async timing — the kinds of primitives that get re-implemented (slightly differently) in every package.

It is published as CommonJS with bundled type declarations and targets Node.js.

Table of contents

• Installation
• Usage
• API
  • bpsUtils
  • bufferUtils
  • cryptoUtils
  • dateUtils
  • emailUtils
  • timeUtils
• Testing
• Build
• License

Installation

npm install @zebec-network/core-utils

pnpm add @zebec-network/core-utils

yarn add @zebec-network/core-utils

Requires Node.js (the package uses node:crypto and Buffer).

Usage

All helpers are re-exported from the package root:

import {
  percentToBps,
  bpsToPercent,
  assertBufferSize,
  sha256Hash,
  sha256HashBuffer,
  areDatesOfSameDay,
  isEmailValid,
  sleep,
} from "@zebec-network/core-utils";

const fee = percentToBps("0.25");          // "25"
const digest = sha256Hash("hello");        // "2cf24dba5fb0a30e..."
await sleep(500);                          // pause 500ms

API

bpsUtils

Helpers for converting between percentages and basis points. Both functions are backed by bignumber.js and floor (rather than round) any excess precision.

percentToBps(percent: string | number): string

Converts a percentage to basis points (1% = 100 bps). Returns an integer string.

percentToBps(1.25);    // "125"
percentToBps("0.5");   // "50"
percentToBps("0.999"); // "99"  (floored)

bpsToPercent(bps: string | number | bigint): string

Converts basis points to a percentage. Returns a string with exactly two decimal places. Accepts bigint for values beyond Number.MAX_SAFE_INTEGER.

bpsToPercent(125);    // "1.25"
bpsToPercent("50");   // "0.50"
bpsToPercent(9999n);  // "99.99"

bufferUtils

type BufferLike = Buffer | Uint8Array

assertBufferSize(buffer: BufferLike, expectedSize: number): void

Throws if buffer.length !== expectedSize. Useful as a precondition check before decoding fixed-size byte payloads.

assertBufferSize(sha256HashBuffer("hello"), 32); // ok
assertBufferSize(Buffer.alloc(16), 32);
// throws: "Buffer size mismatch: expected 32, got 16"

cryptoUtils

Synchronous SHA-256 helpers built on node:crypto.

sha256Hash(input: string): string

Returns a 64-character lowercase hex digest.

sha256Hash("hello");
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

sha256HashBuffer(input: string): Buffer

Returns the raw 32-byte digest as a Buffer.

sha256HashBuffer("hello").length; // 32

Deprecated

The async variants below still work but are kept only for backwards compatibility — prefer the synchronous functions above.

• hashSHA256(input: string): Promise<string> — use sha256Hash instead.
• hashSHA256ToBuffer(input: string): Promise<Buffer> — use sha256HashBuffer instead.

dateUtils

areDatesOfSameDay(date1: Date, date2: Date): boolean

Returns true if both dates share the same UTC year, month, and day. Time-of-day and local timezone offsets are ignored.

areDatesOfSameDay(
  new Date("2026-05-11T01:00:00Z"),
  new Date("2026-05-11T23:59:59Z"),
); // true

emailUtils

isEmailValid(value: string): boolean

Best-effort syntactic check aligned with the HTML5 / WHATWG <input type="email"> definition. Enforces RFC 5321 length limits (local part ≤ 64, total ≤ 254) and rejects leading/trailing or consecutive dots in the local part.

It does not implement the full RFC 5322 grammar (no quoted local parts, no IP-literal or IDN/Unicode domains) and does not confirm the mailbox exists. For authoritative validation, send a confirmation email.

isEmailValid("[email protected]");      // true
isEmailValid("[email protected]"); // true
isEmailValid("[email protected]");     // false
isEmailValid("[email protected]");      // false

timeUtils

sleep(ms: number): Promise<unknown>

Resolves after ms milliseconds via setTimeout. Useful for delays, back-off, or pacing polling loops.

console.log("before");
await sleep(1000);
console.log("one second later");

Testing

Tests live in test/ as *.spec.ts files and run with Mocha via ts-mocha.

Run the full suite:

npm test

Run a single spec file:

npm run test:single -- test/bpsUtils.spec.ts

Each module under src/ has a matching spec:

| Module | Spec | | --- | --- | | src/bpsUtils.ts | test/bpsUtils.spec.ts | | src/bufferUtils.ts | test/bufferUtils.spec.ts | | src/cryptoUtils.ts | test/cryptoUtils.spec.ts | | src/dateUtils.ts | test/dateUtils.spec.ts | | src/emailUtils.ts | test/emailUtils.spec.ts | | src/timeUtils.ts | test/timeUtils.spec.ts |

When adding a new helper, drop a sibling *.spec.ts next to the existing ones — the glob in npm test will pick it up automatically.

Build

npm run build

Produces CommonJS output and .d.ts declaration files in dist/ (the only directory shipped to npm). npm run clean removes the dist/ directory.

Formatting is handled by Biome:

npm run format

License

MIT