config2ts 2.6.1 → 2.7.0

package/README.md

@@ -36,10 +36,12 @@ 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 (line breaks removed, 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
+* 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
+* Line breaks inside a cell (quote-wrapped in CSV) are preserved for `String` fields (emitted as `\n`) and act as the equivalent separator in structural fields — a line feed equals a comma between array elements / Object pairs / Template override pairs, and equals a semicolon between Object[] elements / Template[] entries (one entry per line works; a blank line is an empty slot by the n+1 rule). Scalar fields (Number/Boolean/Enum/single Ref) have no separator semantics, so a line break there prints a warning and must be removed
 * unrecognized field types fall back to `string` and print a warning (check for typos)
 
 ## assets2ts

package/lib/config2ts.js

@@ -57,10 +57,9 @@ const RefEnumPrefix = "RefEnum[";
 const RefEnumArraySuffix = "][]";
 const TemplatePrefix = "Template[";
 // Inside a Template cell, '|' separates the referenced base row id from the
-// Object-style override pairs; ';' separates multiple entries in the array
-// form (same element separator as Object[]).
+// Object-style override pairs. Entries in the array form (and elements of
+// Object[]/primitive arrays) are separated by ';' and line feeds.
 const TemplateOverrideSeparator = "|";
-const TemplateEntrySeparator = ";";
 const AutoGenHeader = "// Auto Generated by config2ts, DO NOT EDIT\n\n";
 exports.Convert = {
     ini: function (str, moduleName) {
@@ -98,6 +97,15 @@ function csv2ts(csvString, moduleName) {
         else {
             for (const k in d) {
                 d[k] = normalizeCell(d[k]);
+                // Line feeds are preserved on purpose for free-form String fields
+                // (multi-line text such as i18n descriptions), and structural types
+                // treat them as entry/pair separators (one element or key:value pair
+                // per line). Scalar types (Number/Boolean/Enum/single Ref) have no
+                // separator semantics, so a line break there is meaningless — warn
+                // and let the author remove it from the cell.
+                if (convert[k] !== "String" && convert[k] !== "" && !isStructuralType(convert[k]) && d[k].includes("\n")) {
+                    console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" of type "${convert[k]}" contains a line break inside the cell; line breaks are only supported in String fields and structural (array/Object/Template) fields, please remove it`);
+                }
                 if (convert[k] === ObjectStr) {
                     d[k] = parseObject(d[k]);
                 }
@@ -141,11 +149,17 @@ function csv2ts(csvString, moduleName) {
                     const template = parseTemplate(convert[k]);
                     const templateContext = { moduleName, field: k, row: i };
                     if (template.isArray) {
-                        const entries = d[k] === "" ? [] : d[k].split(TemplateEntrySeparator).map((part) => parseTemplateEntry(part, templateContext));
+                        // Semicolons and line feeds both separate template entries (one
+                        // entry per line works in multi-line cells); override pairs inside
+                        // an entry stay on the same line.
+                        const entries = d[k] === "" ? [] : d[k].split(/[;\n]/).map((part) => parseTemplateEntry(part, templateContext));
                         for (let entryIndex = 0; entryIndex < entries.length; entryIndex++) {
                             if (entries[entryIndex].baseId === "") {
                                 console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" template array entry ${entryIndex + 1} has an empty base id`);
                             }
+                            else if (entries[entryIndex].baseId.includes(":")) {
+                                console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" template array entry ${entryIndex + 1} "${entries[entryIndex].baseId}" looks like a key:value pair; each line/semicolon slot must be a full "<baseId>|<overrides>" entry, keep override pairs on the same line`);
+                            }
                         }
                         d[k] = entries;
                     }
@@ -335,7 +349,9 @@ function parseObject(str) {
     if (trimmed === "") {
         return result;
     }
-    const pairs = trimmed.split(",");
+    // Commas and line feeds both separate key:value pairs, so one pair per
+    // line works in multi-line cells (e.g. "num:1\nstr:a").
+    const pairs = trimmed.split(/[,\n]/);
     for (const pair of pairs) {
         const colonIndex = pair.indexOf(":");
         if (colonIndex > 0) {
@@ -346,10 +362,13 @@ function parseObject(str) {
     }
     return result;
 }
-// Normalize a raw cell value: drop line-break artifacts (e.g. Excel/CSV \r\n)
-// and surrounding whitespace so all downstream parsing sees clean text.
+// Normalize a raw cell value: convert CRLF/CR line breaks to LF and trim
+// surrounding whitespace. Line feeds inside a quoted cell are intentional
+// (multi-line cells commonly use LF as their entry separator, e.g. one effect
+// per line), so they must be preserved — only the Windows/old-Mac line-break
+// variants are unified to LF.
 function normalizeCell(str) {
-    return String(str).replace(/\r\n?|\n/g, "").trim();
+    return String(str).replace(/\r\n?/g, "\n").trim();
 }
 // Split a comma-separated primitive-array cell: n commas make n+1 slots and every
 // slot is kept (including an interior or trailing empty one), so parallel arrays
@@ -362,18 +381,20 @@ function splitStringArray(str) {
     if (str === "") {
         return [];
     }
-    return str.split(",").map((v) => v.trim());
+    // Commas and line feeds both separate elements, so one value per line
+    // works in multi-line cells (e.g. "a\nb" -> ['a','b']).
+    return str.split(/[,\n]/).map((v) => v.trim());
 }
-// Object[] separates objects with semicolons (commas are reserved for the
-// key:value pairs inside an object, same syntax as the Object type); each
-// semicolon slot is parsed by the same object rule, so stray empty pairs within
-// an object (e.g. "num:1,,str:a") are ignored while an empty object slot between
-// semicolons (e.g. "a:1;;b:2") becomes an empty object placeholder.
+// Object[] separates objects with semicolons or line feeds (commas are reserved
+// for the key:value pairs inside an object, same syntax as the Object type); each
+// slot is parsed by the same object rule, so stray empty pairs within an object
+// (e.g. "num:1,,str:a") are ignored while an empty object slot between separators
+// (e.g. "a:1;;b:2" or a blank line) becomes an empty object placeholder.
 function parseObjectArray(str) {
     if (str === "") {
         return [];
     }
-    return str.split(";").map((part) => parseObject(part));
+    return str.split(/[;\n]/).map((part) => parseObject(part));
 }
 function parseObjectValue(value) {
     if (value === "true")
@@ -417,6 +438,27 @@ function isKnownType(typeStr) {
     }
     return false;
 }
+// Structural types split cell content on separators (commas/semicolons/pipes),
+// so a line feed can act as the equivalent separator and one entry per line is
+// valid in multi-line cells. Scalar types (Number/Boolean/Enum/single Ref) have
+// no separator semantics, so a line feed in those cells is an error.
+function isStructuralType(typeStr) {
+    if (typeStr === ObjectStr || typeStr === ObjectArrayString || typeStr === "String[]" || typeStr === "Number[]" || typeStr === EnumArrayString) {
+        return true;
+    }
+    const ref = parseRef(typeStr);
+    if (ref && ref.isArray) {
+        return true;
+    }
+    const refEnum = parseRefEnum(typeStr);
+    if (refEnum && refEnum.isArray) {
+        return true;
+    }
+    if (parseTemplate(typeStr)) {
+        return true;
+    }
+    return false;
+}
 // Parse Ref[module] (single) and Ref[module][] (array of row references).
 // Note: "RefEnum[...]" starts with "RefE", so it never collides with "Ref[".
 function parseRef(typeStr) {
@@ -494,9 +536,11 @@ function parseTemplateEntry(str, context) {
     const overrides = parseTemplateOverrides(str.slice(separatorIndex + 1), context);
     return { baseId, overrides };
 }
-// Split a string on a separator while ignoring separators inside [] / {}
-// brackets, so commas inside composite values stay intact.
-function splitBracketAware(str, separator) {
+// Split a string on any character in `separators` while ignoring separators
+// inside [] / {} brackets, so commas inside composite values stay intact.
+// Line feeds are accepted as separators too, so one override pair / array
+// element per line works in multi-line cells.
+function splitBracketAware(str, separators) {
     const parts = [];
     let depth = 0;
     let start = 0;
@@ -509,7 +553,7 @@ function splitBracketAware(str, separator) {
             if (depth > 0)
                 depth--;
         }
-        else if (ch === separator && depth === 0) {
+        else if (separators.includes(ch) && depth === 0) {
             parts.push(str.slice(start, i));
             start = i + 1;
         }
@@ -523,7 +567,7 @@ function splitBracketAware(str, separator) {
 // silently dropped.
 function parseTemplateOverrides(str, context) {
     const overrides = {};
-    for (const pair of splitBracketAware(str, ",")) {
+    for (const pair of splitBracketAware(str, ",\n")) {
         const colonIndex = pair.indexOf(":");
         const trimmedPair = pair.trim();
         if (colonIndex <= 0) {
@@ -548,7 +592,7 @@ function parseOverrideValue(value) {
         if (inner === "") {
             return [];
         }
-        return splitBracketAware(inner, ",").map((element) => {
+        return splitBracketAware(inner, ",\n").map((element) => {
             const elementTrimmed = element.trim();
             if (elementTrimmed.startsWith("{") && elementTrimmed.endsWith("}")) {
                 return parseObject(elementTrimmed.slice(1, -1));
@@ -712,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.1",
+  "version": "2.7.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",