@simplysm/core-common

A common utility package for the Simplysm framework. As a neutral base module usable in both Node.js and browser environments, it provides date/time types, error classes, object/array/string utilities, JSON serialization, ZIP processing, prototype extensions, and more.

Installation

npm install @simplysm/core-common
# or
pnpm add @simplysm/core-common

Initialization

Import the package at your application entry point (e.g., index.ts, main.ts):

import "@simplysm/core-common";

This import globally activates Array, Map, and Set prototype extensions. To use extension methods (getOrCreate(), toggle(), etc.), you must import this at app startup.

Main Modules

Errors

• SdError - Base error class with cause chain tracking
• ArgumentError - Argument validation error with YAML formatting
• NotImplementedError - Indicates unimplemented functionality
• TimeoutError - Timeout error

Custom Types

• DateTime - Date + time (millisecond precision, local timezone)
• DateOnly - Date only (no time)
• Time - Time only (no date, 24-hour cycle)
• Uuid - UUID v4 (cryptographically secure)
• LazyGcMap - Map with auto-expiration (LRU style)

Features

• DebounceQueue - Async debounce queue (executes only last request)
• SerialQueue - Async serial queue (sequential execution)
• EventEmitter - EventTarget wrapper with type-safe events

ZIP

• ZipArchive - ZIP file compression/decompression utility

Object Utilities

• objClone - Deep clone (supports circular references, custom types)
• objEqual - Deep comparison with options
• objMerge - Deep merge (source + target)
• objMerge3 - 3-way merge with conflict detection
• objOmit - Exclude specific keys
• objOmitByFilter - Exclude keys matching a predicate
• objPick - Select specific keys
• objGetChainValue - Query value by chain path
• objGetChainValueByDepth - Query value by descending the same key repeatedly
• objSetChainValue - Set value by chain path
• objDeleteChainValue - Delete value by chain path
• objClearUndefined - Delete keys with undefined values (mutates original)
• objClear - Delete all keys from an object (mutates original)
• objNullToUndefined - Recursively convert null to undefined (mutates original)
• objUnflatten - Convert dot-notation flat object to nested object
• objKeys - Type-safe Object.keys
• objEntries - Type-safe Object.entries
• objFromEntries - Type-safe Object.fromEntries
• objMap - Transform each entry of object

JSON Utilities

• jsonStringify - JSON serialization with custom type support
• jsonParse - JSON deserialization with custom type restoration

XML Utilities

• xmlParse - Parse XML string to object
• xmlStringify - Serialize object to XML string

String Utilities

• strGetSuffix - Korean postposition handling
• strReplaceFullWidth - Convert full-width to half-width
• strToPascalCase - PascalCase conversion
• strToCamelCase - camelCase conversion
• strToKebabCase - kebab-case conversion
• strToSnakeCase - snake_case conversion
• strIsNullOrEmpty - Check for undefined/null/empty (type guard)
• strInsert - Insert at position in string

Number Utilities

• numParseInt - Parse string to integer
• numParseFloat - Parse string to float
• numParseRoundedInt - Round float and return integer
• numFormat - Thousands separator formatting
• numIsNullOrEmpty - Check for undefined/null/0 (type guard)

Date/Time Formatting

• formatDate - Convert date/time to formatted string
• normalizeMonth - Normalize year/month/day when setting month
• convert12To24 - Convert 12-hour to 24-hour format

Byte Utilities

• bytesConcat - Concatenate multiple Uint8Arrays
• bytesToHex - Convert Uint8Array to hex string
• bytesFromHex - Convert hex string to Uint8Array
• bytesToBase64 - Convert Uint8Array to base64 string
• bytesFromBase64 - Convert base64 string to Uint8Array

Async Wait

• waitTime - Wait for specified time
• waitUntil - Wait until condition is true

Worker Data Conversion

• transferableEncode - Serialize custom types for Worker transfer
• transferableDecode - Deserialize Worker data to custom types

Path Utilities

• pathJoin - Combine paths (POSIX-style only)
• pathBasename - Extract filename
• pathExtname - Extract extension

Template Literal Tags

• js - JavaScript code highlighting
• ts - TypeScript code highlighting
• html - HTML markup highlighting
• tsql - MSSQL T-SQL highlighting
• mysql - MySQL SQL highlighting
• pgsql - PostgreSQL SQL highlighting

Other Utilities

• getPrimitiveTypeStr - Infer PrimitiveTypeStr from runtime value
• env - Environment variable object

Array Extensions

Query

• single - Return single element (error if 2+)
• first - Return first element
• last - Return last element

Filtering

• filterExists - Remove null/undefined
• ofType - Filter by type
• filterAsync - Async filter

Mapping/Transformation

• mapAsync - Async mapping (sequential)
• mapMany - Flatten nested arrays and remove null/undefined
• mapManyAsync - Async mapMany
• parallelAsync - Parallel async mapping

Grouping

• groupBy - Group by key
• toMap - Convert to Map
• toMapAsync - Async Map conversion
• toArrayMap - Convert to Map<K, V[]>
• toSetMap - Convert to Map<K, Set<V>>
• toMapValues - Aggregate Map by group
• toObject - Convert to Record<string, V>
• toTree - Convert to tree structure

Deduplication

• distinct - Remove duplicates (new array)
• distinctThis - Remove duplicates (modify original)

Sorting

• orderBy - Ascending sort (new array)
• orderByDesc - Descending sort (new array)
• orderByThis - Ascending sort (modify original)
• orderByDescThis - Descending sort (modify original)

Comparison/Merging

• diffs - Compare differences between arrays
• oneWayDiffs - One-way diff comparison
• merge - Merge arrays

Aggregation

• sum - Sum
• min - Minimum
• max - Maximum

Mutation

• insert - Insert at specific position
• remove - Remove item or items matching predicate
• toggle - Toggle item
• clear - Remove all items
• shuffle - Shuffle array

Map Extensions

• getOrCreate - Get or create and return value
• update - Update value using function

Set Extensions

• adds - Add multiple values at once
• toggle - Toggle value (add/remove/force)

Types

• Bytes - Alias for Uint8Array
• PrimitiveTypeStr - Primitive type string keys
• PrimitiveTypeMap - Mapping from type string to type
• PrimitiveType - Union of all primitive types (includes undefined)
• DeepPartial - Recursively convert properties to optional
• Type - Constructor type
• ObjUndefToOptional - Convert undefined properties to optional
• ObjOptionalToUndef - Convert optional properties to required + undefined
• EqualOptions - Options for objEqual
• ObjMergeOptions - Options for objMerge
• ObjMerge3KeyOptions - Per-key options for objMerge3
• DtNormalizedMonth - Return type of normalizeMonth
• ZipArchiveProgress - Progress info for ZipArchive.extractAll
• ArrayDiffsResult - Result type of Array.diffs()
• ArrayDiffs2Result - Result type of Array.oneWayDiffs()
• TreeArray - Result type of Array.toTree()
• ComparableType - Union of types usable for sorting/comparison

Caveats

Prototype Extension Conflicts

This package extends Array, Map, and Set prototypes. Conflicts may occur when used with other libraries that extend the same method names. In case of conflict, the last defined implementation is applied based on load order.

Timezone Handling

When using DateOnly.parse(), DateTime.parse():

• yyyy-MM-dd, yyyyMMdd format: parse directly from string (no timezone influence)
• ISO 8601 format (2024-01-15T00:00:00Z): interpret as UTC then convert to local

When server and client timezones differ, actively use yyyy-MM-dd format.

Memory Management (LazyGcMap)

LazyGcMap has an internal GC timer, so it must be cleaned up.

// using statement (recommended)
// gcInterval: GC execution interval (ms), expireTime: item expiration time (ms)
using map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 }); // GC every 10 seconds, expire after 60 seconds

// Or explicit dispose() call
const map = new LazyGcMap({ gcInterval: 10000, expireTime: 60000 }); // GC every 10 seconds, expire after 60 seconds
try {
  // ... use
} finally {
  map.dispose();
}

jsonStringify's type Reserved Word

jsonStringify/jsonParse uses objects with __type__ and data keys for type restoration. Be careful as user data in the form { __type__: "DateTime", data: "..." } may be unintentionally type-converted.

Circular References

• objClone: supports circular references (tracked with WeakMap)
• jsonStringify: throws TypeError on circular reference
• transferableEncode: throws TypeError on circular reference (includes path information)

License

Apache-2.0