@simplysm/core-common 13.0.98 → 13.0.99

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/core-common
 
-Core module (common) — platform-neutral core utilities for the Simplysm framework.
+Core module (common) -- platform-neutral core utilities for the Simplysm framework.
 
 Provides error classes, immutable date/time types, prototype extensions, event handling, and utility namespaces that work in both browser and Node.js environments.
 
@@ -14,9 +14,9 @@ npm install @simplysm/core-common
 
 Importing the package entry point (`@simplysm/core-common`) automatically patches `Array`, `Map`, and `Set` prototypes with extension methods. These are declared as side effects in `package.json`:
 
-- `extensions/arr-ext` — Array prototype extensions
-- `extensions/map-ext` — Map prototype extensions
-- `extensions/set-ext` — Set prototype extensions
+- `extensions/arr-ext` -- Array prototype extensions
+- `extensions/map-ext` -- Map prototype extensions
+- `extensions/set-ext` -- Set prototype extensions
 
 If you import only specific modules (e.g., `@simplysm/core-common/dist/types/date-time`), the prototype extensions are **not** applied unless you also import the entry point or the extension modules directly.
 
@@ -57,7 +57,7 @@ If you import only specific modules (e.g., `@simplysm/core-common/dist/types/dat
 | API | Type | Description |
 |-----|------|-------------|
 | `EventEmitter` | class | Type-safe event emitter (EventTarget wrapper) |
-| `DebounceQueue` | class | Async debounce — only the last call executes |
+| `DebounceQueue` | class | Async debounce -- only the last call executes |
 | `SerialQueue` | class | Async serial execution queue |
 
 -> See [docs/features.md](./docs/features.md) for details.
@@ -66,7 +66,7 @@ If you import only specific modules (e.g., `@simplysm/core-common/dist/types/dat
 
 | API | Type | Description |
 |-----|------|-------------|
-| `Array` extensions | prototype | 34 methods — query, transform, diff, sort, mutate |
+| `Array` extensions | prototype | 34 methods -- query, transform, diff, sort, mutate |
 | `Map` extensions | prototype | `getOrCreate`, `update` |
 | `Set` extensions | prototype | `adds`, `toggle` |
 

package/docs/features.md

@@ -129,7 +129,7 @@ export class SerialQueue extends EventEmitter<{ error: SdError }> {
 }
 ```
 
-**Error handling:** Same as `DebounceQueue` — emitted as event if listeners exist, otherwise logged.
+**Error handling:** Same as `DebounceQueue` -- emitted as event if listeners exist, otherwise logged.
 
 **Example:**
 

package/docs/types.md

@@ -57,7 +57,7 @@ export class DateTime {
   /**
    * Parse a string to create DateTime instance
    * Supported formats: 'yyyy-MM-dd HH:mm:ss', 'yyyy-MM-dd HH:mm:ss.fff', 'yyyyMMddHHmmss',
-   *   'yyyy-MM-dd AM/PM HH:mm:ss', ISO 8601
+   *   'yyyy-MM-dd AM/PM HH:mm:ss', Korean AM/PM (오전/오후), ISO 8601
    * @throws ArgumentError If unsupported format
    */
   static parse(str: string): DateTime;

package/docs/utils.md

@@ -26,9 +26,13 @@ Deep equality comparison. Supports DateTime, DateOnly, Time, Uuid, Date, RegExp,
 export function equal(source: unknown, target: unknown, options?: EqualOptions): boolean;
 
 export interface EqualOptions {
+  /** List of keys to compare (applies only to top level) */
   topLevelIncludes?: string[];
+  /** List of keys to exclude from comparison (applies only to top level) */
   topLevelExcludes?: string[];
+  /** Whether to ignore array order. O(n^2) complexity when true */
   ignoreArrayIndex?: boolean;
+  /** Whether to do shallow comparison. Only compare 1 level (reference comparison) when true */
   shallow?: boolean;
 }
 ```
@@ -45,7 +49,9 @@ export function merge<TSource, TMergeTarget>(
 ): TSource & TMergeTarget;
 
 export interface MergeOptions {
+  /** Array processing method. "replace": replace with target (default), "concat": merge (deduplicate) */
   arrayProcess?: "replace" | "concat";
+  /** Whether to delete the key when target is null */
   useDelTargetNull?: boolean;
 }
 ```
@@ -67,8 +73,11 @@ export function merge3<
 ): { conflict: boolean; result: O & S & T };
 
 export interface Merge3KeyOptions {
+  /** List of sub-keys to compare (same as equal's topLevelIncludes) */
   keys?: string[];
+  /** List of sub-keys to exclude from comparison */
   excludes?: string[];
+  /** Whether to ignore array order */
   ignoreArrayIndex?: boolean;
 }
 ```
@@ -203,11 +212,32 @@ export function map<TSource extends object, TNewKey extends string, TNewValue>(
 ): Record<TNewKey | Extract<keyof TSource, string>, TNewValue>;
 ```
 
+**Example:**
+
+```typescript
+const colors = { primary: "255, 0, 0", secondary: "0, 255, 0" };
+
+// Transform only values (pass null for key to keep original)
+obj.map(colors, (key, rgb) => [null, `rgb(${rgb})`]);
+// { primary: "rgb(255, 0, 0)", secondary: "rgb(0, 255, 0)" }
+
+// Transform both keys and values
+obj.map(colors, (key, rgb) => [`${key}Light`, `rgb(${rgb})`]);
+// { primaryLight: "rgb(255, 0, 0)", secondaryLight: "rgb(0, 255, 0)" }
+```
+
 ### Type utilities from `obj`
 
 ```typescript
-export type UndefToOptional<TObject> = { /* undefined props become optional */ };
-export type OptionalToUndef<TObject> = { /* optional props become required + undefined */ };
+/** Convert properties with undefined to optional */
+export type UndefToOptional<TObject> = {
+  [K in keyof TObject as undefined extends TObject[K] ? K : never]?: TObject[K];
+} & { [K in keyof TObject as undefined extends TObject[K] ? never : K]: TObject[K] };
+
+/** Convert optional properties to required + undefined union */
+export type OptionalToUndef<TObject> = {
+  [K in keyof TObject]-?: {} extends Pick<TObject, K> ? TObject[K] | undefined : TObject[K];
+};
 ```
 
 ---
@@ -227,6 +257,16 @@ export function getKoreanSuffix(
 ): string;
 ```
 
+| Type | With final consonant | Without final consonant |
+|------|---------------------|------------------------|
+| `"을"` | 을 | 를 |
+| `"은"` | 은 | 는 |
+| `"이"` | 이 | 가 |
+| `"와"` | 과 | 와 |
+| `"랑"` | 이랑 | 랑 |
+| `"로"` | 으로 | 로 |
+| `"라"` | 이라 | 라 |
+
 ### `str.replaceFullWidth`
 
 Convert full-width characters to half-width (A-Z, a-z, 0-9, space, parentheses).
@@ -240,6 +280,8 @@ export function replaceFullWidth(str: string): string;
 ```typescript
 export function toPascalCase(str: string): string;
 // "hello-world" -> "HelloWorld"
+// "hello_world" -> "HelloWorld"
+// "hello.world" -> "HelloWorld"
 ```
 
 ### `str.toCamelCase`
@@ -247,6 +289,8 @@ export function toPascalCase(str: string): string;
 ```typescript
 export function toCamelCase(str: string): string;
 // "hello-world" -> "helloWorld"
+// "hello_world" -> "helloWorld"
+// "HelloWorld"  -> "helloWorld"
 ```
 
 ### `str.toKebabCase`
@@ -254,6 +298,7 @@ export function toCamelCase(str: string): string;
 ```typescript
 export function toKebabCase(str: string): string;
 // "HelloWorld" -> "hello-world"
+// "helloWorld" -> "hello-world"
 ```
 
 ### `str.toSnakeCase`
@@ -261,6 +306,7 @@ export function toKebabCase(str: string): string;
 ```typescript
 export function toSnakeCase(str: string): string;
 // "HelloWorld" -> "hello_world"
+// "helloWorld" -> "hello_world"
 ```
 
 ### `str.isNullOrEmpty`
@@ -277,6 +323,7 @@ Insert a string at a specific position.
 
 ```typescript
 export function insert(str: string, index: number, insertString: string): string;
+// insert("Hello World", 5, ",") => "Hello, World"
 ```
 
 ---
@@ -499,6 +546,8 @@ Transferable conversion utility for Worker data transfer. Handles custom types t
 
 Source: `src/utils/transferable.ts`
 
+Supported types: Date, DateTime, DateOnly, Time, Uuid, RegExp, Error (including cause, code, detail), Uint8Array, Array, Map, Set, plain objects.
+
 ### `transfer.encode`
 
 Convert objects using Simplysm types to plain objects for Worker transfer.
@@ -536,7 +585,7 @@ Error utility. Source: `src/utils/error.ts`
 
 ### `err.message`
 
-Extract message from unknown type error.
+Extract message from unknown type error. Returns `message` property for `Error` instances, otherwise `String(err)`.
 
 ```typescript
 export function message(err: unknown): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-common",
-  "version": "13.0.98",
+  "version": "13.0.99",
   "description": "Simplysm package - Core module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -32,6 +32,6 @@
     "@zip.js/zip.js": "^2.8.23",
     "consola": "^3.4.2",
     "fast-xml-parser": "^5.5.8",
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.3"
   }
 }