cry-helpers

General-purpose JavaScript/TypeScript helpers library — ~95 exported functions, classes, and utilities across 11 functional areas.

Install

npm install cry-helpers

Usage

import {
  // Arrays
  dedup, distinct, groupByField, sumArrayByField, inBatches,

  // Objects
  expand, flatten, clone, pick, omit, objDiff,

  // Strings
  leftOfFirst, splitAtFirst, normalizeString, hashString, safeRegexp,

  // Joining
  j, js, jc, jn,       // join filtering out falsy values
  j0, js0, jc0, jn0,   // skip first if falsy
  j1, js1, jc1, jn1,   // include first only if truthy

  // Number formatting
  round2, decimalFormat, percentFormat,

  // Dates
  dateOrSelf, restoreDates, parseDateStr,

  // Validation
  isEmail, isVAT, isEmso, isMongoObjectId,

  // Logging
  Log,

  // Serialization
  serialize,

  // Search
  createSearchLine, searchArray, searchInArray,
  makeSearchFunction, makeSearchLine, makeSearchArray,

  // Utilities
  sleep, createCsv, DeferredPromise, getConf,
} from 'cry-helpers'

Functional overview

| # | Area | Count | Key exports | |---|------|-------|-------------| | 1 | Array utilities | 19 | dedup, distinct, groupByField, sumArrayByField, inBatches, toBatches, findConsecutiveRanges, addToArray, arrayToObject | | 2 | Object utilities | 17 | expand, flatten, clone, pick, omit, objDiff, objCntKeys, lowercaseKeys | | 3 | String utilities | 25 | leftOfFirst, splitAtFirst, normalizeString, replaceTemplate, hashString, safeRegexp, makeCode | | 4 | Number / Formatting | 9 | round / round1–round8, decimalFormat, percentFormat | | 5 | Date utilities | 5 | dateOrSelf, restoreDates, parseDateStr, timestampFromObjectId | | 6 | Validation | 12 | isEmail, isVAT, isEmso, bic4trr, isMongoObjectId, containsAny | | 7 | Logging | 1 class | Log — configurable logger (FATAL–TRACE levels, colored output) | | 8 | j-family (joining) | 12 | j, js, jc, jn + j0/j1 conditional variants | | 9 | Search functions | 8 | createSearchLine, searchArray, searchInArray, makeSearchFunction, makeSearchLine, makeSearchArray | | 10 | Serialization / Types | 6 | serialize (pack/unpack/encode/decode), realType, isAsync | | 11 | Utility / Misc | 3 | sleep, createCsv, DeferredPromise, ExpieringCache, getConf, f |

Examples

Array utilities

import { dedup, groupByField, sumArrayByField, inBatches } from 'cry-helpers'

dedup(['a', 'b', 'a', 'c'])              // ['a', 'b', 'c']

groupByField([{ a: 1 }, { a: 1 }, { a: 2 }], 'a')
// { '1': [{ a: 1 }, { a: 1 }], '2': [{ a: 2 }] }

sumArrayByField([{ x: 1 }, { x: 2 }, { x: 3 }], 'x')  // 6

// Generator: process in chunks
for (const batch of inBatches(largeArray, 100)) {
  // batch is at most 100 items
}

Object utilities

import { expand, flatten, pick, omit } from 'cry-helpers'

expand({ 'a.b.c': 1 })      // { a: { b: { c: 1 } } }
flatten({ a: { b: { c: 1 } } })  // { 'a.b.c': 1 }

pick({ a: 1, b: 2, c: 3 }, ['a', 'c'])   // { a: 1, c: 3 }
omit({ a: 1, b: 2, c: 3 }, ['b'])        // { a: 1, c: 3 }

String joining — the j family

Filters out falsy values (null, undefined, false, 0, "") automatically:

import { j, js, jc, jn } from 'cry-helpers'

j(['a', null, 'b', undefined, 'c'])          // 'a, b, c' (default sep: ', ')
js('a', null, 'b')                            // 'a b'
jc('a', null, 'b')                            // 'a, b'
jn('a', null, 'b')                            // 'ab'

Conditional variants j0/j1 control inclusion based on the first element:

j0(['', 'a', 'b'], ', ')  // '' — first is falsy, entire result is ''
js0('ok', 'a', 'b')       // 'a b' — first is truthy, rest joined
j1(['ok', 'a', 'b'])      // 'ok, a, b' — first is truthy, included

Validation

import { isEmail, isVAT, isEmso, bic4trr } from 'cry-helpers'

isEmail('[email protected]')           // true
isVAT('SI12345678')                   // true (Slovenian VAT)
isEmso('0101006500006')               // true (Slovenian EMŠO)
bic4trr('SI56 0510 0801 2345 678')   // 'LJBASI2X' (NLB)

Logging

import { Log } from 'cry-helpers'

const log = new Log('INFO')            // or process.env.DEBUG=3
log.info('Service started')
log.error('Something went wrong', err)

// Reconfigure on process signal
log.bindToProcessReconfig(true)        // listens to 'reconfig' signal

Search

import { searchInArray, makeSearchFunction } from 'cry-helpers'

const items = [
  { name: 'Ana', city: 'Maribor' },
  { name: 'Primož', city: 'Kranj' },
  { name: 'Jure', city: 'Koper' },
]

// Query syntax: +must -must-not, OR via /
searchInArray(items, '+pri -kranj')    // [{ name: 'Primož', city: 'Kranj' }]

const filterFn = makeSearchFunction('ana / primož')
items.filter(filterFn)                 // Ana + Primož

Serialization

import { serialize } from 'cry-helpers'

// Preserve Date, RegExp, undefined through JSON
const packed = serialize.pack({ date: new Date(), re: /foo/i, flag: undefined })
const restored = serialize.unpack(packed)
restored.date instanceof Date          // true
restored.re instanceof RegExp         // true
restored.flag                         // undefined (preserved)

License

ISC