typia 13.1.1 → 13.2.0

package/native/adapter/plugin_options.go

@@ -0,0 +1,117 @@
+package adapter
+
+import (
+  "encoding/json"
+  "fmt"
+  "strings"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// PluginName is typia's identity in the ttsc plugin protocol.
+//
+// typia's descriptor declares it (`packages/typia/src/transform.ts` ->
+// `name: "typia"`) and the playground wasm plugin registers the same string
+// with the ttsc wasm host. ttsc echoes it back on every payload entry, so it is
+// how typia recognizes its own entry among the sibling plugins that ride in the
+// same payload: a transform host carries the entries of every transform-stage
+// plugin, not just its own.
+const PluginName = "typia"
+
+// ReadPluginOptions resolves typia's transform options from the ordered plugin
+// payload the host passes on `--plugins-json`.
+//
+// The host owns tsconfig resolution. It parses the file as JSONC, follows the
+// `extends` chain, discards comments, orders the plugin entries, and hands each
+// native plugin back the resolved entry that caused that plugin to load. That
+// entry is the only authority on typia's options, so this reads it and nothing
+// else -- there is deliberately no fallback that re-reads tsconfig.json.
+//
+// Re-reading the file is what made samchon/typia#1887: the previous reader took
+// the leaf file's raw bytes and regex-matched the option names over the whole
+// text. It therefore dropped an option inherited through `extends` (the host
+// resolved it, typia never saw it), and adopted an option the user had commented
+// out or one that belonged to a sibling plugin's entry (the text matched, the
+// entry did not). Reading the file back cannot be made correct without
+// re-implementing the host's JSONC parse and `extends` walk, so a fallback that
+// tried would either duplicate that work or keep the defect on whichever path
+// took it.
+//
+// An absent or empty payload yields the zero options, which are typia's
+// documented defaults. That is not a guess: a host that hands typia no entry
+// has stated that typia was configured with nothing.
+func ReadPluginOptions(pluginsJSON string) (PluginOptions, error) {
+  entries, err := parsePluginEntries(pluginsJSON)
+  if err != nil {
+    return PluginOptions{}, err
+  }
+  entry := findPluginEntry(entries, PluginName)
+  if entry == nil {
+    return PluginOptions{}, nil
+  }
+  return PluginOptions{
+    Functional: pluginOptionEnabled(entry.Config, "functional"),
+    Numeric:    pluginOptionEnabled(entry.Config, "numeric"),
+    Finite:     pluginOptionEnabled(entry.Config, "finite"),
+    Undefined:  pluginOptionBoolean(entry.Config, "undefined"),
+  }, nil
+}
+
+// parsePluginEntries decodes the payload. An empty payload is not an error --
+// a host may legitimately run typia's binary with no plugin manifest -- but a
+// payload that is present and undecodable is: the host meant to state typia's
+// configuration and we cannot read it, so silently substituting defaults would
+// reintroduce exactly the silent wrong-options failure this reader exists to
+// prevent.
+func parsePluginEntries(pluginsJSON string) ([]driver.PluginEntry, error) {
+  text := strings.TrimSpace(pluginsJSON)
+  if text == "" {
+    return nil, nil
+  }
+  var entries []driver.PluginEntry
+  if err := json.Unmarshal([]byte(text), &entries); err != nil {
+    return nil, fmt.Errorf("invalid --plugins-json payload: %w", err)
+  }
+  return entries, nil
+}
+
+// findPluginEntry returns the payload entry the named plugin owns, or nil when
+// the payload carries none. It matches on the host-assigned name rather than on
+// the entry's `transform` specifier: the specifier is a module request the user
+// may legally spell several ways (bare specifier, absolute path), while the
+// name is the identity the host and the plugin already agree on.
+func findPluginEntry(entries []driver.PluginEntry, name string) *driver.PluginEntry {
+  for index := range entries {
+    if entries[index].Name == name {
+      return &entries[index]
+    }
+  }
+  return nil
+}
+
+// pluginOptionEnabled reports whether a tri-state option is explicitly on.
+// Omitted, explicitly false, and non-boolean all mean off, matching how typia
+// has always treated its three on/off options.
+func pluginOptionEnabled(config map[string]any, name string) bool {
+  value := pluginOptionBoolean(config, name)
+  return value != nil && *value
+}
+
+// pluginOptionBoolean reads one boolean option out of a resolved plugin entry's
+// config, distinguishing "omitted" (nil) from "explicitly false".
+//
+// The distinction is load-bearing for `undefined`: `undefined: false` drives the
+// exactOptionalPropertyTypes workflow and must not collapse into the omitted
+// default. A present-but-non-boolean value is treated as omitted rather than
+// coerced, so a typo cannot silently turn an option on.
+func pluginOptionBoolean(config map[string]any, name string) *bool {
+  raw, ok := config[name]
+  if !ok {
+    return nil
+  }
+  value, ok := raw.(bool)
+  if !ok {
+    return nil
+  }
+  return &value
+}

package/native/adapter/plugin_options_payload_matrix_test.go

@@ -0,0 +1,181 @@
+package adapter
+
+import (
+  "testing"
+)
+
+// TestReadPluginOptionsPayloadMatrix verifies typia reads its options from its
+// own entry in the host payload and from nothing else.
+//
+// The host resolves tsconfig -- JSONC parse, `extends` walk, plugin ordering --
+// and hands each plugin back the entry that loaded it. Reading anything else
+// produced samchon/typia#1887 in both directions: an option inherited through
+// `extends` was dropped because only the leaf file was read, and an option that
+// was commented out or that belonged to a sibling plugin was adopted because the
+// match was against raw file text rather than against typia's entry. Every case
+// below is expressed as the payload the host would actually send for that
+// tsconfig, so the oracle is the host contract rather than typia's own output.
+//
+//  1. Feed the reader each payload shape the host can produce.
+//  2. Assert the three on/off options and the tri-state `undefined` option.
+//  3. Cover the sibling-entry, missing-entry, and empty-payload boundaries.
+func TestReadPluginOptionsPayloadMatrix(t *testing.T) {
+  truth := true
+  lie := false
+  cases := []struct {
+    name     string
+    payload  string
+    expected PluginOptions
+  }{
+    {
+      // The documented shape: options inline on typia's own entry. This is the
+      // one case the old regex scrape got right, so it pins behavior that must
+      // not change.
+      name:     "options on typia's own entry",
+      payload:  `[{"config":{"transform":"typia/lib/transform","functional":true,"numeric":true,"finite":true},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{Functional: true, Numeric: true, Finite: true},
+    },
+    {
+      // A base tsconfig declares the option and the leaf `extends` it. The host
+      // resolved the chain and sends the merged entry; there is no leaf file to
+      // miss it in.
+      name:     "option inherited through extends arrives resolved",
+      payload:  `[{"config":{"transform":"typia/lib/transform","functional":true},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{Functional: true},
+    },
+    {
+      // The user commented the option out. The host's JSONC parse dropped it, so
+      // typia's entry simply does not carry it -- there is no comment left for a
+      // text match to find.
+      name:     "option the user commented out never reaches the entry",
+      payload:  `[{"config":{"transform":"typia/lib/transform"},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{},
+    },
+    {
+      // A transform host carries every transform-stage plugin's entry, so a
+      // sibling's identically-named option sits in the same payload. It belongs
+      // to the sibling.
+      name: "sibling plugin's identically-named option does not leak",
+      payload: `[
+        {"config":{"transform":"other/lib/transform","functional":true,"numeric":true,"finite":true,"undefined":true},"name":"other","stage":"transform"},
+        {"config":{"transform":"typia/lib/transform"},"name":"typia","stage":"transform"}
+      ]`,
+      expected: PluginOptions{},
+    },
+    {
+      // Entry order is the host's, not typia's: typia must find itself by name
+      // rather than assume it is first.
+      name: "typia's entry is found when it is not first",
+      payload: `[
+        {"config":{"transform":"other/lib/transform"},"name":"other","stage":"transform"},
+        {"config":{"transform":"typia/lib/transform","finite":true},"name":"typia","stage":"transform"}
+      ]`,
+      expected: PluginOptions{Finite: true},
+    },
+    {
+      // `undefined: false` drives the exactOptionalPropertyTypes workflow and
+      // must stay distinguishable from an omitted option.
+      name:     "explicit undefined=false is preserved",
+      payload:  `[{"config":{"transform":"typia/lib/transform","undefined":false},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{Undefined: &lie},
+    },
+    {
+      name:     "explicit undefined=true is preserved",
+      payload:  `[{"config":{"transform":"typia/lib/transform","undefined":true},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{Undefined: &truth},
+    },
+    {
+      name:     "omitted undefined stays nil rather than collapsing to false",
+      payload:  `[{"config":{"transform":"typia/lib/transform"},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{},
+    },
+    {
+      // Explicit false is off for the three on/off options, matching how typia
+      // has always read them.
+      name:     "explicit false is off",
+      payload:  `[{"config":{"transform":"typia/lib/transform","functional":false,"numeric":false,"finite":false},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{},
+    },
+    {
+      // A typo must not turn an option on by truthiness.
+      name:     "non-boolean values are not coerced",
+      payload:  `[{"config":{"transform":"typia/lib/transform","functional":"true","numeric":1,"finite":null,"undefined":"false"},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{},
+    },
+    {
+      name:     "entry with no options yields the defaults",
+      payload:  `[{"config":{"transform":"typia/lib/transform"},"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{},
+    },
+    {
+      name:     "payload carrying no typia entry yields the defaults",
+      payload:  `[{"config":{"transform":"other/lib/transform","functional":true},"name":"other","stage":"transform"}]`,
+      expected: PluginOptions{},
+    },
+    {
+      name:     "empty payload array yields the defaults",
+      payload:  `[]`,
+      expected: PluginOptions{},
+    },
+    {
+      name:     "absent payload yields the defaults",
+      payload:  ``,
+      expected: PluginOptions{},
+    },
+    {
+      name:     "blank payload yields the defaults",
+      payload:  `   `,
+      expected: PluginOptions{},
+    },
+    {
+      // An entry with a null config must not panic the map reads.
+      name:     "null config yields the defaults",
+      payload:  `[{"config":null,"name":"typia","stage":"transform"}]`,
+      expected: PluginOptions{},
+    },
+  }
+  for _, tc := range cases {
+    t.Run(tc.name, func(t *testing.T) {
+      options, err := ReadPluginOptions(tc.payload)
+      if err != nil {
+        t.Fatalf("payload should be readable: %v", err)
+      }
+      if options.Functional != tc.expected.Functional ||
+        options.Numeric != tc.expected.Numeric ||
+        options.Finite != tc.expected.Finite {
+        t.Fatalf("on/off options mismatch: got %+v want %+v", options, tc.expected)
+      }
+      if !equalBooleanOption(options.Undefined, tc.expected.Undefined) {
+        t.Fatalf("undefined option mismatch: got %s want %s",
+          formatBooleanOption(options.Undefined), formatBooleanOption(tc.expected.Undefined))
+      }
+    })
+  }
+
+  t.Run("undecodable payload is reported rather than defaulted", func(t *testing.T) {
+    // The host meant to state typia's configuration. If that statement cannot be
+    // read, substituting defaults would silently compile the project under the
+    // wrong options -- the very failure this reader exists to prevent -- so the
+    // host must hear about it instead.
+    if _, err := ReadPluginOptions(`{"not":"an array"}`); err == nil {
+      t.Fatal("an undecodable payload must be an error, not silent defaults")
+    }
+  })
+}
+
+func equalBooleanOption(actual, expected *bool) bool {
+  if actual == nil || expected == nil {
+    return actual == nil && expected == nil
+  }
+  return *actual == *expected
+}
+
+func formatBooleanOption(value *bool) string {
+  if value == nil {
+    return "<nil>"
+  }
+  if *value {
+    return "true"
+  }
+  return "false"
+}

package/native/cmd/ttsc-typia/any_array_type_tags_transform_test.go

@@ -141,13 +141,35 @@ export const validateConcrete = typia.createValidate<
   string[] & tags.MinItems<2> & ContainsStatus
 >();
 
-// Union branch: a tagged any-element array beside another array variant.
-// The union explorer discriminates by element checks, which an any element
-// satisfies trivially, so these tags are knowingly NOT enforced yet (the
-// residual gap documented on issue #1933).
+// Union branch: a tagged any-element array beside another array variant. The
+// wrapper predicate participates in complete-branch selection (#2040).
 export const validateUnion = typia.createValidate<
   { list: (unknown[] & tags.MinItems<2>) | string[] }
 >();
+export const validateUnionReversed = typia.createValidate<
+  { list: string[] | (unknown[] & tags.MinItems<2>) }
+>();
+export const isUnion = typia.createIs<
+  { list: (unknown[] & tags.MinItems<2>) | string[] }
+>();
+export const assertUnion = typia.createAssert<
+  { list: (unknown[] & tags.MinItems<2>) | string[] }
+>();
+export const equalsUnion = typia.createEquals<
+  { list: (unknown[] & tags.MinItems<2>) | string[] }
+>();
+export const validateTupleUnion = typia.createValidate<
+  { list: (unknown[] & tags.MinItems<2>) | [number] }
+>();
+export const validateTaggedAlternatives = typia.createValidate<
+  { list: (unknown[] & tags.MinItems<2>) | (string[] & tags.MaxItems<1>) }
+>();
+export const stringifyUnion = typia.json.createValidateStringify<
+  { list: (unknown[] & tags.MinItems<2>) | string[] }
+>();
+export const schemaUnion = typia.json.schemas<[
+  (unknown[] & tags.MinItems<2>) | string[],
+]>();
 `
 
 const anyArrayTypeTagsRuntimeRunner = `const mod = require("./main.cjs");
@@ -194,11 +216,43 @@ expectFailure("concrete too short", mod.validateConcrete(["SUCCESS"]), "MinItems
 expectFailure("concrete no status", mod.validateConcrete(["a", "b"]), "ContainsStatus");
 expectSuccess("concrete valid", mod.validateConcrete(["a", "SUCCESS"]));
 
-// 4. Union with a tagged any-element branch: pins the documented residual
-//    gap — the whole bucket keeps the historical wholesale acceptance, so
-//    even [1] (matching neither branch on paper) passes. When union branch
-//    backtracking lands, flip the last expectation to a failure.
+// 4. Complete branches backtrack across wrapper predicates and element types.
 expectSuccess("union via tagged any", mod.validateUnion({ list: [1, 2] }));
 expectSuccess("union via string branch", mod.validateUnion({ list: ["solo"] }));
-expectSuccess("union residual gap", mod.validateUnion({ list: [1] }));
+expectFailure("union no valid branch", mod.validateUnion({ list: [1] }), "MinItems<2>");
+expectSuccess("reversed union via tagged any", mod.validateUnionReversed({ list: [1, 2] }));
+expectSuccess("reversed union via string branch", mod.validateUnionReversed({ list: ["solo"] }));
+expectFailure("reversed union no valid branch", mod.validateUnionReversed({ list: [1] }), "MinItems<2>");
+if (mod.isUnion({ list: [1] }) !== false || mod.isUnion({ list: [1, 2] }) !== true) {
+  throw new Error("is did not honor the complete tagged union branches");
+}
+if (mod.equalsUnion({ list: [1] }) !== false || mod.equalsUnion({ list: ["solo"] }) !== true) {
+  throw new Error("equals did not honor the complete tagged union branches");
+}
+let asserted = false;
+try {
+  mod.assertUnion({ list: [1] });
+} catch (error) {
+  asserted = String(error && error.message).includes("MinItems<2>");
+}
+if (asserted !== true) {
+  throw new Error("assert did not attribute the failed wrapper tag");
+}
+
+expectSuccess("tuple branch", mod.validateTupleUnion({ list: [1] }));
+expectSuccess("tuple union tagged any", mod.validateTupleUnion({ list: [1, 2] }));
+expectSuccess("tagged alternative string", mod.validateTaggedAlternatives({ list: ["solo"] }));
+expectSuccess("tagged alternative any", mod.validateTaggedAlternatives({ list: [1, 2] }));
+expectSuccess("tagged alternative empty", mod.validateTaggedAlternatives({ list: [] }));
+expectFailure("tagged alternatives reject", mod.validateTaggedAlternatives({ list: [1] }), "MinItems<2>");
+
+const stringified = mod.stringifyUnion({ list: ["solo"] });
+if (stringified.success !== true || JSON.parse(stringified.data).list[0] !== "solo") {
+  throw new Error("validated stringify rejected a later valid branch: " + JSON.stringify(stringified));
+}
+expectFailure("validated stringify no valid branch", mod.stringifyUnion({ list: [1] }), "MinItems<2>");
+const unionSchema = JSON.stringify(mod.schemaUnion);
+if (unionSchema.includes('"minItems":2') === false) {
+  throw new Error("array union schema lost MinItems: " + unionSchema);
+}
 `

package/native/cmd/ttsc-typia/assert_guard_factory_contract_test.go

@@ -0,0 +1,152 @@
+package main
+
+import (
+  "os"
+  "os/exec"
+  "path/filepath"
+  "strings"
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestAssertGuardFactoryContract verifies factory typing and runtime shape.
+//
+// An assertion-guard factory returns the guard itself. Its successful invocation
+// returns void while narrowing the input; it never returns another callable
+// assertion guard.
+//
+//  1. Compile normal and equals factories with explicit and inferred types.
+//  2. Prove successful invocations narrow and have a void return type.
+//  3. Exercise custom errors and the equals-only surplus-property boundary.
+func TestAssertGuardFactoryContract(t *testing.T) {
+  project := compareEqualCoverProject(t, "assert-guard-factory-", assertGuardFactorySource)
+  ttscTypiaTestAssertGuardFactoryType(t, project)
+  ttscTypiaTestTypecheck(t, project)
+  js := compareEqualCoverTransform(t, project)
+  if strings.Contains(js, "createAssertGuard<") {
+    t.Fatalf("assert guard factory call was not transformed:\n%s", js)
+  }
+
+  node, err := exec.LookPath("node")
+  if err != nil {
+    t.Skip("node executable not found")
+  }
+  runtimeDir := filepath.Join(project, "runtime")
+  if err := os.MkdirAll(runtimeDir, 0o755); err != nil {
+    t.Fatalf("mkdir runtime dir: %v", err)
+  }
+  ttscTypiaTestWriteCommonRuntimeStubs(t, runtimeDir)
+  if err := os.WriteFile(filepath.Join(runtimeDir, "main.cjs"), []byte(ttscTypiaTestRewriteCommonJS(t, js)), 0o644); err != nil {
+    t.Fatalf("write runtime module: %v", err)
+  }
+  runner := filepath.Join(runtimeDir, "run.cjs")
+  if err := os.WriteFile(runner, []byte(assertGuardFactoryRuntime), 0o644); err != nil {
+    t.Fatalf("write runtime runner: %v", err)
+  }
+  cmd := exec.Command(node, runner)
+  cmd.Dir = runtimeDir
+  if output, err := cmd.CombinedOutput(); err != nil {
+    t.Fatalf("assert guard factory runtime cases failed: %v\n%s", err, output)
+  }
+}
+
+func ttscTypiaTestAssertGuardFactoryType(t *testing.T, project string) {
+  t.Helper()
+  program, diagnostics, err := driver.LoadProgram(project, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatalf("load assertion guard fixture: %v", err)
+  }
+  if len(diagnostics) != 0 {
+    t.Fatalf("assertion guard fixture diagnostics: %+v", diagnostics)
+  }
+  defer program.Close()
+
+  source := program.SourceFile(filepath.Join(project, "src", "main.ts"))
+  if source == nil {
+    t.Fatal("assertion guard fixture source was not loaded")
+  }
+  found := 0
+  for _, statement := range source.Statements.Nodes {
+    if statement.Kind != shimast.KindVariableStatement {
+      continue
+    }
+    for _, declaration := range statement.AsVariableStatement().DeclarationList.AsVariableDeclarationList().Declarations.Nodes {
+      name := declaration.Name().Text()
+      if name != "inferred" && name != "inferredEquals" {
+        continue
+      }
+      found++
+      typeName := program.Checker.TypeToString(program.Checker.GetTypeAtLocation(declaration))
+      if strings.Contains(typeName, "=> AssertionGuard") {
+        t.Fatalf("%s returns a nested assertion guard: %s", name, typeName)
+      }
+      if typeName != "AssertionGuard<User>" && !strings.Contains(typeName, "asserts input is User") {
+        t.Fatalf("%s is not an assertion guard: %s", name, typeName)
+      }
+    }
+  }
+  if found != 2 {
+    t.Fatalf("expected two inferred assertion guards, found %d", found)
+  }
+}
+
+const assertGuardFactorySource = `import typia, { AssertionGuard, TypeGuardError } from "typia";
+
+interface User {
+  id: number;
+}
+
+const custom = (props: TypeGuardError.IProps): Error =>
+  Object.assign(new Error("custom guard"), props);
+
+export const guard: AssertionGuard<User> = typia.createAssertGuard<User>(custom);
+export const equalsGuard: AssertionGuard<User> = typia.createAssertGuardEquals<User>(custom);
+export const inferred = typia.createAssertGuard<User>();
+export const inferredEquals = typia.createAssertGuardEquals<User>();
+
+let input: unknown = { id: 1 };
+const returned = guard(input);
+input.id satisfies number;
+
+type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2
+    ? true
+    : false;
+type Assert<T extends true> = T;
+export type FactoryCases = [
+  Assert<Equal<typeof inferred, AssertionGuard<User>>>,
+  Assert<Equal<typeof inferredEquals, AssertionGuard<User>>>,
+  Assert<Equal<typeof returned, void>>,
+];
+
+// @ts-expect-error invoking an assertion guard returns void, not another guard.
+const nested: AssertionGuard<User> = guard(input);
+void nested;
+`
+
+const assertGuardFactoryRuntime = `const mod = require("./main.cjs");
+
+const expect = (label, actual, expected) => {
+  if (actual !== expected) throw new Error(label + ": expected " + expected + ", got " + actual);
+};
+
+expect("normal success returns void", mod.guard({ id: 1 }), undefined);
+expect("equals success returns void", mod.equalsGuard({ id: 1 }), undefined);
+expect("normal permits surplus", mod.guard({ id: 1, extra: true }), undefined);
+
+for (const [label, guard, value] of [
+  ["normal invalid", mod.guard, { id: "bad" }],
+  ["equals invalid", mod.equalsGuard, { id: "bad" }],
+  ["equals surplus", mod.equalsGuard, { id: 1, extra: true }],
+]) {
+  let error;
+  try {
+    guard(value);
+  } catch (exp) {
+    error = exp;
+  }
+  expect(label + " uses custom error", error && error.message, "custom guard");
+}
+`