config2ts 2.8.1 → 2.9.0

package/README.md

@@ -6,9 +6,72 @@ convert config to ts file.
 
 run command: `npm install -g config2ts`
 
-# how to use
+# documentation
 
-config2ts -d config -o dist -n csv.ts -a public
+Full documentation is published via GitHub Pages (this repo has Pages enabled):
+
+- English: https://livingyang.github.io/config2ts/
+- 中文: https://livingyang.github.io/config2ts/index-zh.html
+
+# usage
+
+`config2ts` supports two output modes selected by `-m, --mode`:
+
+- `single` (default): merge every table into one file (`-n`, default `csv.ts`).
+- `split`: write one `.ts` file per table plus an auto-generated `index.ts`.
+
+This repo's `config/` folder ships example outputs generated from the same source
+tables, so you can compare both layouts directly:
+
+- single mode example: [`config/total.ts`](config/total.ts)
+- split mode example: [`config/split/`](config/split/) (one file per table + `index.ts`)
+
+## single mode
+
+Merge all config tables into a single TypeScript file.
+
+```bash
+config2ts -d config -o dist -m single -n csv.ts -a public
+```
+
+- `-n` is the merged output file name (default `csv.ts`).
+- `-a` is optional; omit it to skip `assets.ts`.
+- Example output: [`config/total.ts`](config/total.ts) — all tables as `export namespace XxxCsv { ... }` in one file.
+
+## split mode
+
+Write one `.ts` file per config table (named after the source file, e.g.
+`skill.csv` → `skill.ts`) plus an auto-generated `index.ts` that re-exports every
+table and `assets.ts`. Cross-table `Ref`/`RefEnum`/`Template` references are
+resolved with `import` statements injected at the top of the referencing file, so
+every table is independently usable and tree-shakable.
+
+```bash
+config2ts -d config -o dist -m split -a public
+```
+
+- `-n` is reused as the index file name; the single-mode default `csv.ts` is
+  replaced by `index.ts` unless you pass `-n` explicitly.
+- `-a` is optional; omit it to skip `assets.ts`.
+- Example output: [`config/split/`](config/split/) — `z-base.ts`, `a-user.ts`,
+  `skill.ts`, … , `assets.ts`, and `index.ts`.
+
+Output layout under `dist`:
+
+```
+dist/
+  z-base.ts        # export namespace ZBaseCsv { ... }
+  a-user.ts        # import { ZBaseCsv } from "./z-base"; export namespace AUserCsv { ... }
+  skill.ts
+  ...
+  assets.ts        # generated only when -a is given
+  index.ts         # export * from "./z-base"; export * from "./a-user"; ...; export * from "./assets";
+```
+
+Notes:
+- Tables are emitted in topological order; a table only `import`s tables it
+  actually references, and missing/circular references print the same warnings as
+  single mode.
 
 # support type
 
@@ -36,7 +99,7 @@ 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
+* `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[]`
@@ -48,7 +111,7 @@ config2ts -d config -o dist -n csv.ts -a public
 
 Scan assets directory and generate an `assets.ts` index file with nested resource tree.
 
-- `-a, --assets <path>` set assets resource directory. default: `public`
+- `-a, --assets <path>` set assets resource directory (optional, skip asset index if omitted)
 - Output file: `assets.ts` (alongside the merged config file)
 - File and directory names are used exactly as-is (e.g., `Direction.png` → `Direction`, `adjust-horizontal.png` → `'adjust-horizontal'`); keys with special characters are automatically quoted
 - `type` field uses file extension (lowercase), e.g. `'png'`, `'mp3'`, `'svg'`
@@ -103,9 +166,10 @@ const adjustMeta = ASSETS.public.image['adjust-horizontal'];
     -h, --help             output usage information
     -V, --version          output the version number
     -d, --dir <path>       set convert path. default: ./
-    -o, --outDir <path>    set outDir path. default: ./
-    -n, --name <name>      output file name. default: csv.ts
-    -a, --assets <path>    set assets resource directory for asset index. default: public
+    -o, --outDir <path>    set outDir path. default: same as -d
+    -n, --name <name>      output file name (single mode) / index file name (split mode). default: csv.ts
+    -a, --assets <path>    set assets resource directory for asset index (optional, skip asset index if omitted)
+    -m, --mode <mode>      output mode: single (merge into one file) or split (one file per table + index.ts). default: single
 ```
 
 ## supported file formats

package/lib/config2ts.d.ts

@@ -4,5 +4,5 @@ export declare function assets2ts(assetsDir: string): string;
 export declare function GetTsString(filePath: string): string;
 export declare function GetTsStringFromFileList(fileList: string[]): string;
 export declare function GetValidFileList(fileList: string[]): string[];
-export declare function startConvert(dir: string, outDir: string, merge: string, assetsDir?: string): void;
+export declare function startConvert(dir: string, outDir: string, merge: string, assetsDir?: string, mode?: "single" | "split"): void;
 export {};

package/lib/config2ts.js

@@ -871,11 +871,75 @@ function GetValidFileList(fileList) {
         return exports.Convert[GetFileExt(filePath)] != null;
     });
 }
-function startConvert(dir, outDir, merge, assetsDir) {
+// Build the `import { XxxCsv } from "./xxx";` lines a split-mode file needs so
+// its cross-table Ref/RefEnum/Template references resolve. `collectCsvReferences`
+// returns the full base filenames (e.g. "z-base.csv") of referenced tables, which
+// map 1:1 to the split output file "./z-base.ts" and to the namespace
+// `pascalCase("z-base.csv")` === "ZBaseCsv".
+function buildImportLines(filePath, validBases) {
+    const base = path.basename(filePath);
+    const refs = collectCsvReferences(filePath).filter((ref) => ref !== base);
+    const imported = new Set();
+    const lines = [];
+    for (const ref of refs) {
+        if (!validBases.has(ref)) {
+            continue; // missing referenced table; already warned by sortFilesByReferences
+        }
+        if (imported.has(ref)) {
+            continue;
+        }
+        imported.add(ref);
+        const ns = changeCase.pascalCase(ref);
+        const importPath = "./" + path.parse(ref).name;
+        lines.push(`import { ${ns} } from "${importPath}";`);
+    }
+    return lines.join("\n");
+}
+function startConvert(dir, outDir, merge, assetsDir, mode = "single") {
     const fileList = fs.readdirSync(dir);
     const fullFileList = GetValidFileList(fileList).map(function (filename) {
         return path.join(dir, filename);
     });
+    if (mode === "split") {
+        const validBases = new Set(fullFileList.map((f) => path.basename(f)));
+        const orderedFiles = sortFilesByReferences(fullFileList);
+        const exportedNames = [];
+        for (const filePath of orderedFiles) {
+            const base = path.basename(filePath);
+            const outName = path.parse(base).name + ".ts";
+            exportedNames.push(path.parse(base).name);
+            const imports = buildImportLines(filePath, validBases);
+            const body = GetTsString(filePath);
+            const content = AutoGenHeader + (imports ? imports + "\n\n" : "") + body + "\n";
+            const outPath = path.join(outDir, outName);
+            fs.writeFileSync(outPath, content, { encoding: "utf-8" });
+            console.log(`config2ts, ${base} -> ${outPath}`);
+        }
+        let assetsExport = null;
+        if (assetsDir) {
+            const assetsOutput = assets2ts(assetsDir);
+            if (assetsOutput) {
+                const assetsFile = path.join(outDir, "assets.ts");
+                fs.writeFileSync(assetsFile, AutoGenHeader + assetsOutput, { encoding: "utf-8" });
+                console.log(`assets2ts, resource dir: ${assetsDir}, output: ${assetsFile}`);
+                assetsExport = "assets";
+            }
+        }
+        // In split mode the `-n` value is reused as the index file name; fall back to
+        // "index.ts" when the caller leaves the single-mode default "csv.ts" intact.
+        const indexName = merge !== "csv.ts" ? merge : "index.ts";
+        let indexContent = AutoGenHeader;
+        for (const name of exportedNames) {
+            indexContent += `export * from "./${name}";\n`;
+        }
+        if (assetsExport) {
+            indexContent += `export * from "./${assetsExport}";\n`;
+        }
+        const indexPath = path.join(outDir, indexName);
+        fs.writeFileSync(indexPath, indexContent, { encoding: "utf-8" });
+        console.log(`config2ts, ${orderedFiles.length} config files, split mode, index: ${indexPath}`);
+        return;
+    }
     const mergeFile = path.join(outDir, merge);
     fs.writeFileSync(mergeFile, AutoGenHeader + GetTsStringFromFileList(fullFileList), { encoding: "utf-8" });
     console.log(`config2ts, ${fullFileList.length} config files, merge into: ${mergeFile}`);

package/lib/main.js

@@ -42,10 +42,11 @@ const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
 const program = new commander_1.Command();
 program
     .version(pkg.version)
-    .option("-n, --name <name>", "output file name", "csv.ts")
+    .option("-n, --name <name>", "output file name (single mode) / index file name (split mode)", "csv.ts")
     .option("-d, --dir <path>", "set convert path", ".")
     .option("-o, --outDir <path>", "set outDir path")
-    .option("-a, --assets <path>", "set assets resource directory for asset index", "public")
+    .option("-a, --assets <path>", "set assets resource directory for asset index (optional, skip asset index if omitted)")
+    .option("-m, --mode <mode>", "output mode: single (merge into one file) or split (one file per table + index.ts)", "single")
     .parse(process.argv);
 const options = program.opts();
 console.log(options);
@@ -60,4 +61,8 @@ const assetsDir = options.assets ? path.resolve(options.assets) : undefined;
 if (assetsDir) {
     console.log("assetsDir:", assetsDir);
 }
-(0, config2ts_1.startConvert)(dir, outDir, options.name, assetsDir);
+const mode = options.mode === "split" ? "split" : "single";
+if (mode === "single" && options.mode !== "single") {
+    console.warn(`[config2ts] warning: unknown mode "${options.mode}", falling back to "single"`);
+}
+(0, config2ts_1.startConvert)(dir, outDir, options.name, assetsDir, mode);

package/package.json

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