refactor(typia): dismantle the misc namespace into plain / compare / reflect

Relocates clone/prune to plain, equal/cover to compare, literals to reflect; removes the misc namespace. Tests, examples, and the guide migrated. Fixes #1952.

Author: samchon

examples/src/misc/literals.ts

@@ -1,7 +1,7 @@
 import typia from "typia";
 
 const department: IDepartment = typia.random<IDepartment>();
-const cloned: IDepartment = typia.misc.assertClone<IDepartment>(department);
+const cloned: IDepartment = typia.plain.assertClone<IDepartment>(department);
 
 console.log(cloned);
 

examples/src/misc/assertClone.ts examples/src/plain/assertClone.tsexamples/src/misc/assertClone.ts renamed to examples/src/plain/assertClone.ts

@@ -1,7 +1,7 @@
 import typia from "typia";
 
 const department: IDepartment = typia.random<IDepartment>();
-const pruned: IDepartment = typia.misc.assertPrune<IDepartment>(department);
+const pruned: IDepartment = typia.plain.assertPrune<IDepartment>(department);
 
 console.log(pruned);
 

examples/src/misc/assertPrune.ts examples/src/plain/assertPrune.tsexamples/src/misc/assertPrune.ts renamed to examples/src/plain/assertPrune.ts

@@ -0,0 +1,3 @@
+import typia from "typia";
+
+typia.reflect.literals<"A" | "B" | "C" | 1 | 2n>();

examples/src/reflect/literals.ts

@@ -8,28 +8,28 @@ import (
   "testing"
 )
 
-// TestMiscEqualCoverTransform verifies type-directed structural comparison.
+// TestCompareEqualCoverTransform verifies type-directed structural comparison.
 //
-// Issue #1497 adds `typia.misc.equal` and `typia.misc.cover`:
+// Issue #1497 adds `typia.compare.equal` and `typia.compare.cover`:
 //
 //  1. Transform direct and factory calls for equal/cover.
 //  2. Execute object, partial-object, array-length, native, dynamic-key,
 //     union, and recursive pair-tracking cases.
 //  3. Reject unsupported any, function, Set, Map, WeakSet, and WeakMap types
 //     at transform time.
-func TestMiscEqualCoverTransform(t *testing.T) {
-  project := miscEqualCoverProject(t, "misc-equal-cover-", miscEqualCoverSource)
-  js := miscEqualCoverTransform(t, project)
+func TestCompareEqualCoverTransform(t *testing.T) {
+  project := compareEqualCoverProject(t, "compare-equal-cover-", compareEqualCoverSource)
+  js := compareEqualCoverTransform(t, project)
   for _, needle := range []string{"getTime", "source", "flags", "Uint8Array", "WeakMap", "_vctx"} {
     if !strings.Contains(js, needle) {
-      t.Fatalf("misc equal/cover output is missing %q:\n%s", needle, js)
+      t.Fatalf("compare equal/cover output is missing %q:\n%s", needle, js)
     }
   }
-  miscEqualCoverRunRuntimeCases(t, project, js)
-  miscEqualCoverRejectsUnsupported(t)
+  compareEqualCoverRunRuntimeCases(t, project, js)
+  compareEqualCoverRejectsUnsupported(t)
 }
 
-func miscEqualCoverProject(t *testing.T, prefix string, source string) string {
+func compareEqualCoverProject(t *testing.T, prefix string, source string) string {
   t.Helper()
   root := ttscTypiaTestRepoRoot(t)
   base := filepath.Join(root, "packages", "typia", "native", ".tmp-ttsc-typia-tests")
@@ -47,7 +47,7 @@ func miscEqualCoverProject(t *testing.T, prefix string, source string) string {
   if err := os.MkdirAll(src, 0o755); err != nil {
     t.Fatalf("mkdir fixture src: %v", err)
   }
-  if err := os.WriteFile(filepath.Join(dir, "tsconfig.json"), []byte(miscEqualCoverTSConfig), 0o644); err != nil {
+  if err := os.WriteFile(filepath.Join(dir, "tsconfig.json"), []byte(compareEqualCoverTSConfig), 0o644); err != nil {
     t.Fatalf("write tsconfig: %v", err)
   }
   if err := os.WriteFile(filepath.Join(src, "main.ts"), []byte(source), 0o644); err != nil {
@@ -56,7 +56,7 @@ func miscEqualCoverProject(t *testing.T, prefix string, source string) string {
   return dir
 }
 
-func miscEqualCoverTransform(t *testing.T, project string) string {
+func compareEqualCoverTransform(t *testing.T, project string) string {
   t.Helper()
   out, errText, code := ttscTypiaTestCapture(func() int {
     return runTransform([]string{
@@ -67,12 +67,12 @@ func miscEqualCoverTransform(t *testing.T, project string) string {
     })
   })
   if code != 0 {
-    t.Fatalf("misc equal/cover transform failed: code=%d stderr=\n%s", code, errText)
+    t.Fatalf("compare equal/cover transform failed: code=%d stderr=\n%s", code, errText)
   }
   return out
 }
 
-func miscEqualCoverRunRuntimeCases(t *testing.T, project string, js string) {
+func compareEqualCoverRunRuntimeCases(t *testing.T, project string, js string) {
   t.Helper()
   node, err := exec.LookPath("node")
   if err != nil {
@@ -88,33 +88,33 @@ func miscEqualCoverRunRuntimeCases(t *testing.T, project string, js string) {
     t.Fatalf("write runtime module: %v", err)
   }
   runner := filepath.Join(runtimeDir, "run.cjs")
-  if err := os.WriteFile(runner, []byte(miscEqualCoverRuntimeRunner), 0o644); err != nil {
+  if err := os.WriteFile(runner, []byte(compareEqualCoverRuntimeRunner), 0o644); err != nil {
     t.Fatalf("write runtime runner: %v", err)
   }
   cmd := exec.Command(node, runner)
   cmd.Dir = runtimeDir
   output, err := cmd.CombinedOutput()
   if err != nil {
-    t.Fatalf("misc equal/cover runtime cases failed: %v\n%s", err, output)
+    t.Fatalf("compare equal/cover runtime cases failed: %v\n%s", err, output)
   }
 }
 
-func miscEqualCoverRejectsUnsupported(t *testing.T) {
+func compareEqualCoverRejectsUnsupported(t *testing.T) {
   t.Helper()
   cases := []struct {
     Name   string
     Source string
   }{
-    {"any", "export const bad = typia.misc.createEqual<any>();"},
-    {"function", "export const bad = typia.misc.createEqual<() => void>();"},
-    {"set", "export const bad = typia.misc.createCover<Set<string>>();"},
-    {"map", "export const bad = typia.misc.createEqual<Map<string, number>>();"},
-    {"weak-set", "export const bad = typia.misc.createCover<WeakSet<object>>();"},
-    {"weak-map", "export const bad = typia.misc.createEqual<WeakMap<object, object>>();"},
+    {"any", "export const bad = typia.compare.createEqual<any>();"},
+    {"function", "export const bad = typia.compare.createEqual<() => void>();"},
+    {"set", "export const bad = typia.compare.createCover<Set<string>>();"},
+    {"map", "export const bad = typia.compare.createEqual<Map<string, number>>();"},
+    {"weak-set", "export const bad = typia.compare.createCover<WeakSet<object>>();"},
+    {"weak-map", "export const bad = typia.compare.createEqual<WeakMap<object, object>>();"},
   }
   for _, tc := range cases {
     t.Run(tc.Name, func(t *testing.T) {
-      project := miscEqualCoverProject(t, "misc-equal-cover-reject-", `import typia from "typia";
+      project := compareEqualCoverProject(t, "compare-equal-cover-reject-", `import typia from "typia";
 `+tc.Source+`
 `)
       out, errText, code := ttscTypiaTestCapture(func() int {
@@ -133,7 +133,7 @@ func miscEqualCoverRejectsUnsupported(t *testing.T) {
   }
 }
 
-const miscEqualCoverTSConfig = `{
+const compareEqualCoverTSConfig = `{
   "compilerOptions": {
     "target": "ES2022",
     "module": "commonjs",
@@ -148,7 +148,7 @@ const miscEqualCoverTSConfig = `{
 }
 `
 
-const miscEqualCoverSource = `import typia, { misc } from "typia";
+const compareEqualCoverSource = `import typia, { compare } from "typia";
 
 interface IUser {
   name: string;
@@ -164,34 +164,34 @@ interface IUser {
   bytes: Uint8Array;
 }
 
-export const equalUser = typia.misc.createEqual<IUser>();
-export const coverUser = typia.misc.createCover<IUser>();
-export const equalUserDirect = (x: IUser, y: IUser) => typia.misc.equal<IUser>(x, y);
-export const coverUserDirect = (x: IUser, y: misc.Cover<IUser>) => typia.misc.cover<IUser>(x, y);
+export const equalUser = typia.compare.createEqual<IUser>();
+export const coverUser = typia.compare.createCover<IUser>();
+export const equalUserDirect = (x: IUser, y: IUser) => typia.compare.equal<IUser>(x, y);
+export const coverUserDirect = (x: IUser, y: compare.Cover<IUser>) => typia.compare.cover<IUser>(x, y);
 
 interface IDictionary {
   fixed: string;
   [key: string]: string;
 }
-export const equalDictionary = typia.misc.createEqual<IDictionary>();
-export const coverDictionary = typia.misc.createCover<IDictionary>();
+export const equalDictionary = typia.compare.createEqual<IDictionary>();
+export const coverDictionary = typia.compare.createCover<IDictionary>();
 
 type Shape =
   | { kind: "circle"; radius: number; nested: { label: string } }
   | { kind: "square"; size: number; nested: { label: string } };
-export const equalShape = typia.misc.createEqual<Shape>();
-export const coverShape = typia.misc.createCover<Shape>();
+export const equalShape = typia.compare.createEqual<Shape>();
+export const coverShape = typia.compare.createCover<Shape>();
 
 interface INode {
   id: number;
   next: INode | null;
   children: INode[];
 }
-export const equalNode = typia.misc.createEqual<INode>();
-export const coverNode = typia.misc.createCover<INode>();
+export const equalNode = typia.compare.createEqual<INode>();
+export const coverNode = typia.compare.createCover<INode>();
 `
 
-const miscEqualCoverRuntimeRunner = `const mod = require("./main.cjs");
+const compareEqualCoverRuntimeRunner = `const mod = require("./main.cjs");
 
 const expect = (label, actual, expected) => {
   if (actual !== expected) {

…typia/misc_equal_cover_transform_test.go …ia/compare_equal_cover_transform_test.gopackages/typia/native/cmd/ttsc-typia/misc_equal_cover_transform_test.go renamed to packages/typia/native/cmd/ttsc-typia/compare_equal_cover_transform_test.go packages/typia/native/cmd/ttsc-typia/misc_equal_cover_transform_test.go renamed to packages/typia/native/cmd/ttsc-typia/compare_equal_cover_transform_test.go

@@ -8,9 +8,9 @@ import (
   "testing"
 )
 
-// TestMiscCloneBigIntWrapperTransform verifies BigInt wrapper unboxing.
+// TestPlainCloneBigIntWrapperTransform verifies BigInt wrapper unboxing.
 //
-// Collecting TypeScript `BigInt` as native metadata routes `misc.clone` and
+// Collecting TypeScript `BigInt` as native metadata routes `plain.clone` and
 // notation programmers into their native arms. Those arms must unbox the four
 // primitive wrappers through `valueOf()`; before the fix the default branch
 // emitted a bare zero-argument `BigInt()`, which throws for every input, so
@@ -21,8 +21,8 @@ import (
 //  2. Require the emitted code to call `valueOf` and never bare `BigInt()`.
 //  3. Execute clone, assertClone, and camel notation over primitive and boxed
 //     inputs and require primitive bigint identities back.
-func TestMiscCloneBigIntWrapperTransform(t *testing.T) {
-  project := miscCloneBigIntWrapperProject(t)
+func TestPlainCloneBigIntWrapperTransform(t *testing.T) {
+  project := plainCloneBigIntWrapperProject(t)
   out, errText, code := ttscTypiaTestCapture(func() int {
     return runTransform([]string{
       "--cwd", project,
@@ -40,17 +40,17 @@ func TestMiscCloneBigIntWrapperTransform(t *testing.T) {
   if strings.Contains(out, "BigInt()") {
     t.Fatalf("bigint wrapper clone must not emit a bare BigInt() call:\n%s", out)
   }
-  miscCloneBigIntWrapperRunRuntimeCases(t, project, out)
+  plainCloneBigIntWrapperRunRuntimeCases(t, project, out)
 }
 
-func miscCloneBigIntWrapperProject(t *testing.T) string {
+func plainCloneBigIntWrapperProject(t *testing.T) string {
   t.Helper()
   root := ttscTypiaTestRepoRoot(t)
   base := filepath.Join(root, "packages", "typia", "native", ".tmp-ttsc-typia-tests")
   if err := os.MkdirAll(base, 0o755); err != nil {
     t.Fatalf("mkdir temp base: %v", err)
   }
-  dir, err := os.MkdirTemp(base, "misc-clone-bigint-")
+  dir, err := os.MkdirTemp(base, "plain-clone-bigint-")
   if err != nil {
     t.Fatalf("create temp fixture: %v", err)
   }
@@ -61,16 +61,16 @@ func miscCloneBigIntWrapperProject(t *testing.T) string {
   if err := os.MkdirAll(src, 0o755); err != nil {
     t.Fatalf("mkdir fixture src: %v", err)
   }
-  if err := os.WriteFile(filepath.Join(dir, "tsconfig.json"), []byte(miscCloneBigIntWrapperTSConfig), 0o644); err != nil {
+  if err := os.WriteFile(filepath.Join(dir, "tsconfig.json"), []byte(plainCloneBigIntWrapperTSConfig), 0o644); err != nil {
     t.Fatalf("write tsconfig: %v", err)
   }
-  if err := os.WriteFile(filepath.Join(src, "main.ts"), []byte(miscCloneBigIntWrapperSource), 0o644); err != nil {
+  if err := os.WriteFile(filepath.Join(src, "main.ts"), []byte(plainCloneBigIntWrapperSource), 0o644); err != nil {
     t.Fatalf("write source: %v", err)
   }
   return dir
 }
 
-func miscCloneBigIntWrapperRunRuntimeCases(t *testing.T, project string, js string) {
+func plainCloneBigIntWrapperRunRuntimeCases(t *testing.T, project string, js string) {
   t.Helper()
   node, err := exec.LookPath("node")
   if err != nil {
@@ -86,7 +86,7 @@ func miscCloneBigIntWrapperRunRuntimeCases(t *testing.T, project string, js stri
     t.Fatalf("write runtime module: %v", err)
   }
   runner := filepath.Join(runtimeDir, "run.cjs")
-  if err := os.WriteFile(runner, []byte(miscCloneBigIntWrapperRuntimeRunner), 0o644); err != nil {
+  if err := os.WriteFile(runner, []byte(plainCloneBigIntWrapperRuntimeRunner), 0o644); err != nil {
     t.Fatalf("write runtime runner: %v", err)
   }
   cmd := exec.Command(node, runner)
@@ -97,7 +97,7 @@ func miscCloneBigIntWrapperRunRuntimeCases(t *testing.T, project string, js stri
   }
 }
 
-const miscCloneBigIntWrapperTSConfig = `{
+const plainCloneBigIntWrapperTSConfig = `{
   "compilerOptions": {
     "target": "ES2022",
     "module": "commonjs",
@@ -112,19 +112,19 @@ const miscCloneBigIntWrapperTSConfig = `{
 }
 `
 
-const miscCloneBigIntWrapperSource = `import typia from "typia";
+const plainCloneBigIntWrapperSource = `import typia from "typia";
 
 interface BoxedRecord {
   big_value: BigInt;
 }
 
-export const cloneInterface = typia.misc.createClone<BigInt>();
-export const cloneUnion = typia.misc.createClone<bigint | BigInt>();
-export const assertCloneInterface = typia.misc.createAssertClone<BigInt>();
+export const cloneInterface = typia.plain.createClone<BigInt>();
+export const cloneUnion = typia.plain.createClone<bigint | BigInt>();
+export const assertCloneInterface = typia.plain.createAssertClone<BigInt>();
 export const camelRecord = typia.notations.createCamel<BoxedRecord>();
 `
 
-const miscCloneBigIntWrapperRuntimeRunner = `const mod = require("./main.cjs");
+const plainCloneBigIntWrapperRuntimeRunner = `const mod = require("./main.cjs");
 
 const boxed = Object(1n);
 const expectPrimitive = (name, value, expected) => {

…c_clone_bigint_wrapper_transform_test.go …n_clone_bigint_wrapper_transform_test.gopackages/typia/native/cmd/ttsc-typia/misc_clone_bigint_wrapper_transform_test.go renamed to packages/typia/native/cmd/ttsc-typia/plain_clone_bigint_wrapper_transform_test.go packages/typia/native/cmd/ttsc-typia/misc_clone_bigint_wrapper_transform_test.go renamed to packages/typia/native/cmd/ttsc-typia/plain_clone_bigint_wrapper_transform_test.go

@@ -108,10 +108,10 @@ func recursiveVisitTrackingRunRuntimeCases(t *testing.T, project string, js stri
   }
   ttscTypiaTestWriteCommonRuntimeStubs(t, runtimeDir)
   extras := map[string]string{
-    "throw-type-guard-error-stub.cjs":   recursiveVisitTrackingThrowStub,
-    "protobuf-sizer-stub.cjs":           recursiveVisitTrackingProtobufSizerStub,
-    "protobuf-writer-stub.cjs":          recursiveVisitTrackingProtobufWriterStub,
-    "json-stringify-number-stub.cjs":    recursiveVisitTrackingNumberStub,
+    "throw-type-guard-error-stub.cjs": recursiveVisitTrackingThrowStub,
+    "protobuf-sizer-stub.cjs":         recursiveVisitTrackingProtobufSizerStub,
+    "protobuf-writer-stub.cjs":        recursiveVisitTrackingProtobufWriterStub,
+    "json-stringify-number-stub.cjs":  recursiveVisitTrackingNumberStub,
   }
   for name, content := range extras {
     if err := os.WriteFile(filepath.Join(runtimeDir, name), []byte(content), 0o644); err != nil {
@@ -216,13 +216,13 @@ export const validateForest = typia.createValidate<ITree[] | number>();
 
 // Rebuilders: clone must reproduce cycles (structured-clone style), and the
 // assert composition shares one functor with the clone emission.
-export const cloneNode = typia.misc.createClone<INode>();
-export const assertCloneNode = typia.misc.createAssertClone<INode>();
-export const cloneTree = typia.misc.createClone<ITree>();
+export const cloneNode = typia.plain.createClone<INode>();
+export const assertCloneNode = typia.plain.createAssertClone<INode>();
+export const cloneTree = typia.plain.createClone<ITree>();
 
 // In-place walker: prune must terminate on cycles while still erasing the
 // superfluous properties it reaches.
-export const pruneNode = typia.misc.createPrune<INode>();
+export const pruneNode = typia.plain.createPrune<INode>();
 
 // Renaming rebuilder: notations must reproduce cycles under the new keys.
 interface IRenamed {