config2ts 2.5.8 → 2.6.0

package/README.md

@@ -25,7 +25,9 @@ config2ts -d config -o dist -n csv.ts -a public
 |  Enum[]    |      type[]       |
 |    Ref     | namespace.Record  |
 | RefEnum    | namespace.type    |
-|  RefEnum[] |  namespace.type[] |
+| RefEnum[]  | namespace.type[]  |
+|  Template  | namespace.Record  |
+| Template[] | namespace.Record[] |
 |   Object   |   type (Record)   |
 |  Object[]  | type[] (Record[]) |
 
@@ -33,7 +35,8 @@ config2ts -d config -o dist -n csv.ts -a public
 * `Enum` support empty string type
 * `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/type by id
+* `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 Object-style 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`. `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 only, and the target table must have an Index/Map (same file-ordering rule as `Ref`)
 * `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

package/lib/config2ts.js

@@ -55,6 +55,12 @@ const RefPrefix = "Ref[";
 const RefSuffix = "]";
 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[]).
+const TemplateOverrideSeparator = "|";
+const TemplateEntrySeparator = ";";
 const AutoGenHeader = "// Auto Generated by config2ts, DO NOT EDIT\n\n";
 exports.Convert = {
     ini: function (str, moduleName) {
@@ -77,7 +83,7 @@ function csv2ts(csvString, moduleName) {
         if (i === 0) {
             convert = d;
             for (const k in convert) {
-                if (convert[k].startsWith(RefPrefix) && convert[k].endsWith(RefSuffix)) {
+                if (parseRef(convert[k])) {
                     refFields.push(k);
                 }
                 if (parseRefEnum(convert[k])) {
@@ -107,8 +113,16 @@ function csv2ts(csvString, moduleName) {
                 else if (convert[k] === "Number[]") {
                     d[k] = splitStringArray(d[k]).map((val) => Number(val));
                 }
-                else if (convert[k].startsWith(RefPrefix) && convert[k].endsWith(RefSuffix)) {
-                    if (d[k] === "") {
+                else if (parseRef(convert[k])) {
+                    const ref = parseRef(convert[k]);
+                    if (ref.isArray) {
+                        const ids = splitStringArray(d[k]);
+                        d[k] = ids;
+                        if (ids.includes("")) {
+                            console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" ref array contains an empty id`);
+                        }
+                    }
+                    else if (d[k] === "") {
                         console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" ref value is empty`);
                     }
                 }
@@ -123,6 +137,28 @@ function csv2ts(csvString, moduleName) {
                         }
                     }
                 }
+                else if (parseTemplate(convert[k])) {
+                    const template = parseTemplate(convert[k]);
+                    if (template.isArray) {
+                        const entries = d[k] === "" ? [] : d[k].split(TemplateEntrySeparator).map((part) => parseTemplateEntry(part));
+                        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`);
+                            }
+                        }
+                        d[k] = entries;
+                    }
+                    else {
+                        if (d[k] === "") {
+                            console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" template value is empty`);
+                        }
+                        const entry = parseTemplateEntry(d[k]);
+                        if (d[k] !== "" && entry.baseId === "") {
+                            console.warn(`[config2ts] warning: ${moduleName} row ${i} field "${k}" template base id is empty`);
+                        }
+                        d[k] = entry;
+                    }
+                }
                 else {
                     d[k] = String(d[k]);
                 }
@@ -208,16 +244,21 @@ function csv2ts(csvString, moduleName) {
             else if (convert[field] == ObjectArrayString) {
                 fieldType = field + "[]";
             }
-            else if (convert[field].startsWith(RefPrefix) && convert[field].endsWith(RefSuffix)) {
-                const refModule = convert[field].slice(RefPrefix.length, -RefSuffix.length);
-                const refModuleName = changeCase.pascalCase(refModule);
-                fieldType = `${refModuleName}.Record`;
+            else if (parseRef(convert[field])) {
+                const ref = parseRef(convert[field]);
+                const refModuleName = changeCase.pascalCase(ref.refModule);
+                fieldType = ref.isArray ? `${refModuleName}.Record[]` : `${refModuleName}.Record`;
             }
             else if (parseRefEnum(convert[field])) {
                 const refEnum = parseRefEnum(convert[field]);
                 const refModuleName = changeCase.pascalCase(refEnum.refModule);
                 fieldType = refEnum.isArray ? `${refModuleName}.${refEnum.refField}[]` : `${refModuleName}.${refEnum.refField}`;
             }
+            else if (parseTemplate(convert[field])) {
+                const template = parseTemplate(convert[field]);
+                const refModuleName = changeCase.pascalCase(template.refModule);
+                fieldType = template.isArray ? `${refModuleName}.Record[]` : `${refModuleName}.Record`;
+            }
             else {
                 fieldType = convert[field].toLowerCase();
             }
@@ -241,10 +282,27 @@ function csv2ts(csvString, moduleName) {
         template += "        {\n";
         for (const field in convert) {
             let value = row[field];
-            if (convert[field].startsWith(RefPrefix) && convert[field].endsWith(RefSuffix)) {
-                const refModule = convert[field].slice(RefPrefix.length, -RefSuffix.length);
-                const refModuleName = changeCase.pascalCase(refModule);
-                template += `            ${serializeField(field)}: ${refModuleName}.Map[${JSON.stringify(value)}],\n`;
+            if (parseRef(convert[field])) {
+                const ref = parseRef(convert[field]);
+                const refModuleName = changeCase.pascalCase(ref.refModule);
+                if (ref.isArray) {
+                    const refs = value.map((id) => `${refModuleName}.Map[${JSON.stringify(id)}]`).join(",");
+                    template += `            ${serializeField(field)}: [${refs}],\n`;
+                }
+                else {
+                    template += `            ${serializeField(field)}: ${refModuleName}.Map[${JSON.stringify(value)}],\n`;
+                }
+            }
+            else if (parseTemplate(convert[field])) {
+                const templateType = parseTemplate(convert[field]);
+                const refModuleName = changeCase.pascalCase(templateType.refModule);
+                if (templateType.isArray) {
+                    const entries = value.map((entry) => serializeTemplateEntry(entry, refModuleName)).join(",");
+                    template += `            ${serializeField(field)}: [${entries}],\n`;
+                }
+                else {
+                    template += `            ${serializeField(field)}: ${serializeTemplateEntry(value, refModuleName)},\n`;
+                }
             }
             else {
                 template += `            ${serializeField(field)}: ${json5.stringify(value)},\n`;
@@ -344,17 +402,40 @@ function isKnownType(typeStr) {
     if (knownTypes.includes(typeStr)) {
         return true;
     }
-    if (typeStr.startsWith(RefPrefix) && typeStr.endsWith(RefSuffix)) {
+    if (parseRef(typeStr)) {
         return true;
     }
     if (parseRefEnum(typeStr)) {
         return true;
     }
+    if (parseTemplate(typeStr)) {
+        return true;
+    }
     if (typeof global[typeStr] === "function") {
         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) {
+    if (!typeStr.startsWith(RefPrefix)) {
+        return null;
+    }
+    let isArray = false;
+    let inner = typeStr;
+    if (typeStr.endsWith(RefEnumArraySuffix)) {
+        isArray = true;
+        inner = typeStr.slice(0, -RefEnumArraySuffix.length) + RefSuffix;
+    }
+    if (inner.startsWith(RefPrefix) && inner.endsWith(RefSuffix)) {
+        const refModule = inner.slice(RefPrefix.length, -RefSuffix.length);
+        if (refModule !== "") {
+            return { refModule, isArray };
+        }
+    }
+    return null;
+}
 function parseRefEnum(typeStr) {
     if (typeStr.startsWith(RefEnumPrefix)) {
         let isArray = false;
@@ -375,6 +456,56 @@ function parseRefEnum(typeStr) {
     }
     return null;
 }
+// Parse Template[module] (single) and Template[module][] (array of templated
+// row references). "Template[" starts with 'T', so it never collides with the
+// "Ref[" / "RefEnum[" prefixes.
+function parseTemplate(typeStr) {
+    if (!typeStr.startsWith(TemplatePrefix)) {
+        return null;
+    }
+    let isArray = false;
+    let inner = typeStr;
+    if (typeStr.endsWith(RefEnumArraySuffix)) {
+        isArray = true;
+        inner = typeStr.slice(0, -RefEnumArraySuffix.length) + RefSuffix;
+    }
+    if (inner.startsWith(TemplatePrefix) && inner.endsWith(RefSuffix)) {
+        const refModule = inner.slice(TemplatePrefix.length, -RefSuffix.length);
+        if (refModule !== "") {
+            return { refModule, isArray };
+        }
+    }
+    return null;
+}
+// Parse one Template cell entry: "<baseId>|<key>:<value>,<key>:<value>".
+// The part before the first '|' is the base row id; the part after it reuses
+// the Object rule for the override pairs. No '|' means zero overrides, which
+// is equivalent to a plain Ref.
+function parseTemplateEntry(str) {
+    const separatorIndex = str.indexOf(TemplateOverrideSeparator);
+    if (separatorIndex < 0) {
+        return { baseId: str.trim(), overrides: {} };
+    }
+    const baseId = str.slice(0, separatorIndex).trim();
+    const overrides = parseObject(str.slice(separatorIndex + 1));
+    return { baseId, overrides };
+}
+// Serialize one parsed Template entry to runtime code. Entries without
+// overrides emit a plain ref (same as Ref: `Module.Map["id"]`); entries with
+// overrides spread the base record and apply the overrides on top. Because
+// the spread result is contextually typed as the target Record, a typo'd
+// override key or an incompatible value type fails at tsc compile time.
+function serializeTemplateEntry(entry, refModuleName) {
+    const baseRef = `${refModuleName}.Map[${JSON.stringify(entry.baseId)}]`;
+    const overrideKeys = Object.keys(entry.overrides);
+    if (overrideKeys.length === 0) {
+        return baseRef;
+    }
+    const overrideStr = overrideKeys
+        .map((key) => `${serializeField(key)}:${json5.stringify(entry.overrides[key])}`)
+        .join(",");
+    return `{...${baseRef},${overrideStr}}`;
+}
 function GetFileExt(filePath) {
     const pathObject = path.parse(filePath);
     return pathObject.ext.slice(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "config2ts",
-  "version": "2.5.8",
+  "version": "2.6.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",