config2ts 2.6.2 → 2.8.0

package/README.md

@@ -36,7 +36,8 @@ config2ts -d config -o dist -n csv.ts -a public
 * `Enum[]` union contains every value actually present in the data (including `""` for empty slots)
 * `EnumIndex` will generate index type, and will use `Enum` type to generate interface
 * `Ref` / `RefEnum` reference another csv's Record/enum by id: `Ref[file]` is one row (`file.Map["id"]`), `Ref[file][]` is an array of rows with comma-separated ids (`[file.Map["1"],file.Map["2"]]`, typed `File.Record[]`); use `Object[]` for inline private structures and `Ref[]` for shared, identity-bearing rows
-* `Template[file]` inherits a whole row from another table and overrides selected fields: a cell is `<baseId>|<key>:<value>,<key>:<value>` — a pipe separates the base row id from override pairs (e.g. `101|damage:150,range:8`), emitting `{ ...file.Map["101"], damage: 150, range: 8 }` typed `File.Record`; with no overrides the cell is just the id and emits a plain `file.Map["id"]` like `Ref`. Override values may be bare scalars or bracket-wrapped composites mirroring the generated TS syntax — arrays as `[v1,v2]` (e.g. `Params:[6,2.07]`, required for array-typed fields; a bare `Params:6,2.07` gets chopped by the pair comma and prints a warning) and flat objects as `{k:v,k:v}`. `Template[file][]` separates entries with `;` (the same element separator as `Object[]`), e.g. `101|damage:150;102|heal:500` emits `[{ ...file.Map["101"], damage: 150 },{ ...file.Map["102"], heal: 500 }]`. Override key typos and value-type mismatches fail at tsc compile time; overrides are flat top-level fields (no dot-path deep merge), and the target table must have an Index/EnumIndex Map (same file-ordering rule as `Ref`)
+* `Template[file]` inherits a whole row from another table and overrides selected fields: a cell is `<baseId>|<key>:<value>,<key>:<value>` — a pipe separates the base row id from override pairs (e.g. `101|damage:150,range:8`), emitting `{ ...file.Map["101"], damage: 150, range: 8 }` typed `File.Record`; with no overrides the cell is just the id and emits a plain `file.Map["id"]` like `Ref`. Override values may be bare scalars or bracket-wrapped composites mirroring the generated TS syntax — arrays as `[v1,v2]` (e.g. `Params:[6,2.07]`, required for array-typed fields; a bare `Params:6,2.07` gets chopped by the pair comma and prints a warning) and flat objects as `{k:v,k:v}`. `Template[file][]` separates entries with `;` (the same element separator as `Object[]`), e.g. `101|damage:150;102|heal:500` emits `[{ ...file.Map["101"], damage: 150 },{ ...file.Map["102"], heal: 500 }]`. Override key typos and value-type mismatches fail at tsc compile time; overrides are flat top-level fields (no dot-path deep merge), and the target table must have an Index/EnumIndex Map
+* Merge order is resolved automatically: tables are topologically sorted so every referenced table (`Ref`/`RefEnum`/`Template`) is emitted before the tables referencing it — no filename tricks needed; tables without a dependency relation keep alphabetical order. Circular references (`a.csv -> b.csv -> a.csv`) and references to missing files print a warning
 * `Object` parse `key:value,key:value` format, auto-infer value types (number/boolean/string), generates a dedicated `type` that merges all keys
 * `Object[]` separates objects with `;` while commas still separate `key:value` pairs inside each object (same syntax as the `Object` type), e.g. `num:1,,str:a;num:2` makes `[{num:1,str:'a'},{num:2}]`, a bare `;` makes `[{},{}]`; generates a dedicated element `type` merging all keys with the field typed as `type[]`
 * Array convention: primitive arrays (`String[]`/`Number[]`/`Enum[]`/`RefEnum[...] []`) separate elements with `,` and `Object[]` separates objects with `;`; raw cell values are normalized (CRLF/CR unified to LF, whitespace trimmed); an empty cell generates `[]`; otherwise n separators make n+1 slots and every slot is kept (including interior or trailing ones) so parallel arrays stay index-aligned. Empty slots use the type's own zero value — `''` for string/enum/ref-enum, `0` for number, `{}` for empty object slots; `null` is never generated

package/lib/config2ts.js

@@ -756,8 +756,100 @@ function GetTsString(filePath) {
         return "";
     }
 }
+// Collect the config file names a CSV references from its type row
+// (Ref[file], RefEnum[file.field], Template[file] and their array forms).
+// ini/toml files never reference other config tables.
+function collectCsvReferences(filePath) {
+    if (GetFileExt(filePath) !== "csv") {
+        return [];
+    }
+    let fileString = fs.readFileSync(filePath).toString();
+    if (fileString.charAt(0) === "\uFEFF") {
+        fileString = fileString.substr(1);
+    }
+    const references = [];
+    (0, d3_dsv_1.csvParse)(fileString, function (d, i) {
+        if (i === 0) {
+            for (const k in d) {
+                const typeStr = d[k];
+                const ref = parseRef(typeStr);
+                const refEnum = parseRefEnum(typeStr);
+                const template = parseTemplate(typeStr);
+                const target = ref ? ref.refModule : refEnum ? refEnum.refModule : template ? template.refModule : null;
+                if (target && !references.includes(target)) {
+                    references.push(target);
+                }
+            }
+        }
+        return null;
+    });
+    return references;
+}
+// Order files so every referenced table is emitted before the table that
+// references it (a referenced namespace must exist when the referencing
+// table's data initializes), so authors no longer need filename tricks (e.g.
+// an "!" prefix) to control order. Files without a dependency relation keep
+// their alphabetical order. References to missing files and circular
+// references are reported; a cycle is broken at the back edge so output is
+// still generated (the runtime data still needs the cycle fixed by hand).
+function sortFilesByReferences(fileList) {
+    const ordered = fileList.slice().sort((a, b) => {
+        const baseA = path.basename(a);
+        const baseB = path.basename(b);
+        return baseA < baseB ? -1 : baseA > baseB ? 1 : 0;
+    });
+    const fileByBase = new Map();
+    for (const filePath of ordered) {
+        fileByBase.set(path.basename(filePath), filePath);
+    }
+    const depsByBase = new Map();
+    for (const filePath of ordered) {
+        const base = path.basename(filePath);
+        const deps = collectCsvReferences(filePath);
+        depsByBase.set(base, deps);
+        for (const dep of deps) {
+            if (!fileByBase.has(dep)) {
+                console.warn(`[config2ts] warning: ${base} references "${dep}" but no config file with that name was found in the config directory`);
+            }
+        }
+    }
+    const sorted = [];
+    // 0 = unvisited, 1 = visiting (on the current DFS trail), 2 = done
+    const state = new Map();
+    const reportedCycles = new Set();
+    function visit(base, trail) {
+        var _a, _b;
+        const current = (_a = state.get(base)) !== null && _a !== void 0 ? _a : 0;
+        if (current === 2) {
+            return;
+        }
+        if (current === 1) {
+            const cycleStart = trail.indexOf(base);
+            const cycleKey = trail.slice(cycleStart).concat(base).join(" -> ");
+            if (!reportedCycles.has(cycleKey)) {
+                reportedCycles.add(cycleKey);
+                console.warn(`[config2ts] warning: circular table reference detected: ${cycleKey}; tables in the cycle may reference an undefined namespace at runtime, please break the reference cycle`);
+            }
+            return;
+        }
+        state.set(base, 1);
+        trail.push(base);
+        for (const dep of (_b = depsByBase.get(base)) !== null && _b !== void 0 ? _b : []) {
+            if (fileByBase.has(dep)) {
+                visit(dep, trail);
+            }
+        }
+        trail.pop();
+        state.set(base, 2);
+        sorted.push(fileByBase.get(base));
+    }
+    for (const filePath of ordered) {
+        visit(path.basename(filePath), []);
+    }
+    return sorted;
+}
 function GetTsStringFromFileList(fileList) {
-    return fileList
+    return sortFilesByReferences(fileList)
         .map(function (filePath) {
         return GetTsString(filePath);
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "config2ts",
-  "version": "2.6.2",
+  "version": "2.8.0",
   "description": "Generate type-safe TypeScript from CSV/INI/TOML config tables — inferred types, enums, cross-table references, and a typed asset index, all from one CLI command.",
   "main": "lib/config2ts.js",
   "types": "lib/config2ts.d.ts",
@@ -27,19 +27,31 @@
     "url": "https://github.com/livingyang/config2ts/issues"
   },
   "homepage": "https://github.com/livingyang/config2ts#readme",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "change-case": "^4.1.2",
     "commander": "^9.5.0",
     "d3-dsv": "^3.0.1",
     "ini": "^3.0.1",
     "json5": "^2.2.3",
-    "toml": "^3.0.0"
+    "toml": "^4.1.2"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^24.5.2",
-    "jest": "^29.5.0",
-    "ts-jest": "^29.4.4",
+    "jest": "^30.5.1",
+    "ts-jest": "^29.4.12",
     "typescript": "^5.9.2"
+  },
+  "overrides": {
+    "@babel/core": "^7.29.6",
+    "browserslist": "^4.28.7",
+    "handlebars": "^4.7.9",
+    "js-yaml": "^3.14.2",
+    "minimatch@^3.0.0": "^3.1.3",
+    "picomatch@^2.0.0": "^2.3.2",
+    "brace-expansion@^1.0.0": "^1.1.16"
   }
 }