susee 1.0.4 → 1.5.1

package/README.md

@@ -2,7 +2,7 @@
 <!-- markdownlint-disable MD041 -->
 <div align="center">
 <img src="https://susee.phothin.dev/logo/susee.webp" width="160" height="160" alt="susee" />
-  <h1>susee</h1>
+  <h1>Susee</h1>
 </div>
 <!-- markdownlint-enable MD033 -->
 
@@ -10,74 +10,54 @@
 
 ## Overview
 
-`susee` is a TypeScript bundler that processes a package's local dependency tree and emits compiled artifacts in multiple module formats. Unlike general-purpose bundlers that target browser environments or bundle `node_modules`, `susee` focuses on library authorship: it collates local TypeScript files, merges them into cohesive bundles, compiles them through the TypeScript compiler, and generates properly formatted outputs for consumption as npm packages.
+Susee is a TypeScript-first bundler for library packages.
 
-## Key Features
+It reads `susee.config.{ts,js,mjs}`, resolves the dependency graph for each entry,
+bundles sources into a single unit, then compiles output for ESM and/or CommonJS with types.
 
-1. **Dependency Tree Resolution** : automatically resolves and collects local TypeScript dependencies starting from specified entry points.
+## Features
 
-2. **Dual-Format Module Output** : generates outputs for both ESM and CommonJS module systems from a single TypeScript source.
+- Loads config from one of:
+  - `susee.config.ts`
+  - `susee.config.js`
+  - `susee.config.mjs`
+- Supports multiple entry points with subpath exports (`.` and `./subpath`).
+- Validates and type-checks dependency files before bundling.
+- Runs dependency, pre-process, and post-process plugins (sync or async).
+- Compiles to:
+  - ESM (`.mjs`, `.d.mts`, source maps)
+  - CommonJS (`.cjs`, `.d.cts`, source maps)
+- Can update `package.json` fields (`type`, `main`, `module`, `types`, `exports`) when `allowUpdatePackageJson` is enabled.
 
-3. **File Extension Conventions** : dual-emit conventions for unambiguous module format identification.
+## Current Constraints
 
-   | Module Format | JavaScript Extension | Type Definition Extension |
-   | ------------- | -------------------- | ------------------------- |
-   | ESM           | `.mjs`               | `.d.mts`                  |
-   | CommonJS      | `.cjs`               | `.d.cts`                  |
+- CommonJS dependencies in the source graph are rejected by core (suggested workaround: `@suseejs/plugin-commonjs`).
+- JSX/TSX dependencies are currently rejected.
+- CLI supports only `susee` and `susee init`.
 
-4. **Automatic package.json Management** : conditionally updates package.json fields based on compilation outputs, this feature is controlled by the `allowUpdatePackageJson` boolean in `SuSeeConfig`.
+## Installation and Quick Start
 
-## Installation
+### Install
 
-Install as a development dependency :
-
-```bash
-npm install susee --save-dev
+```sh
+npm i -D susee
 ```
 
-Global install:
+### Create a config file
 
-```bash
-npm install -g susee
+```sh
+npx susee init
 ```
 
-## Quick Start
-
-The `susee` CLI binary is exposed through the `bin` field and becomes available immediately after installation.
+### Build your first project
 
-### Creating a Minimal Configuration
+Use the CLI:
 
-Create a file named `susee.config.ts` in your project root:
-
-```ts
-import type { SuSeeConfig } from "susee";
-
-const config: SuSeeConfig = {
-  entryPoints: [
-    {
-      entry: "src/index.ts",
-      exportPath: ".",
-      format: "both",
-    },
-  ],
-};
-
-export default config;
-```
-
-### Running Your First Build
-
-Execute the bundler using one of these methods:
-
-#### CLI Execution
-
-with `npx` :
-
-```bash
+```sh
 npx susee
 ```
 
-via `package.json` :
+Or in `package.json`:
 
 ```json
 {
@@ -87,131 +67,118 @@ via `package.json` :
 }
 ```
 
-```bash
-npm run build
-```
+## Config Reference
 
-for global :
+`SuSeeConfig`
 
-```bash
-susee
+```ts
+interface SuSeeConfig {
+  entryPoints: EntryPoint[];
+  outDir?: string; // default: "dist"
+  plugins?: (SuseePlugin | SuseePluginFunction)[]; // default: []
+  allowUpdatePackageJson?: boolean; // default: false
+}
 ```
 
-#### Programmatic Execution
+`EntryPoint`
 
 ```ts
-import { susee } from "susee";
-
-await susee();
+type OutputFormat = ("commonjs" | "esm")[];
+
+interface EntryPoint {
+  entry: string;
+  exportPath: "." | `./${string}`;
+  format?: OutputFormat; // default: ["esm"]
+  tsconfigFilePath?: string;
+  renameDuplicates?: boolean; // default: true
+  binary?: { name: string };
+}
 ```
 
-The `susee()` function is an asynchronous operation that:
-
-1. Loads configuration from `susee.config.ts`
-2. Resolves the dependency tree
-3. Bundles local dependencies
-4. Compiles to target formats
-5. Optionally updates `package.json`
-
-## Configuration summary
-
-### Top-Level Configuration Fields
+### Entry Validation Rules
 
-#### entryPoints
+- At least one `entryPoint` is required.
+- Duplicate `exportPath` values are rejected.
+- Each `entry` file must exist.
 
-An array of [EntryPoint](#entrypoint-structure) objects defining the files to bundle. Each entry point represents a separate bundling operation with its own entry file, export path, and output configuration. The array must contain at least one entry point.
+### TypeScript Options Behavior
 
-#### plugins (optional)
+For each entry point, Susee builds compiler options from:
 
-An optional array of plugin instances that provide transformation hooks. Plugins can be objects or factory functions and execute at different stages of the bundling pipeline (dependency, pre-process, post-process). Defaults to `[]` if not specified.
+1. `tsconfigFilePath` (if provided)
+2. project `tsconfig.json`
+3. Susee defaults
 
-#### allowUpdatePackageJson (optional)
+Susee enforces/adjusts key options internally:
 
-Controls whether `susee` automatically updates the `package.json` file with generated `exports`, `main` fields, and `module` fields. When `true`, susee modifies the `package.json` to reflect the bundled outputs. When `false`, `package.json` remains unchanged.
-Defaults to `true` if not specified.
+- `moduleResolution: "NodeNext"`
+- `allowJs: true`
+- `outDir` set per entry output path
+- `types` includes `node`
+- `lib` includes `ESNext`
 
-#### outDir (optional)
+## Plugin Hooks
 
-Specifies the base output directory where compiled files are written. This can be overridden per entry point if needed (though the current implementation uses a global outDir). Defaults to `"dist"` if not specified.
+Susee supports these plugin stages:
 
-### EntryPoint Structure
+- `dependency`
+  - receives resolved dependency files and compiler options
+  - transforms dependency metadata/content before bundling
+- `pre-process`
+  - receives bundled code before compilation
+- `post-process`
+  - receives emitted JS output content per file
 
-Each entry point in the [entryPoints](#entrypoints) array defines a separate bundling target. The EntryPoint interface specifies the following fields:
+Both sync and async plugins are supported.
 
-**entry**: The file path to the TypeScript entry file. This path is validated during configuration loading to ensure the file exists
+## Output Behavior
 
-**exportPath**: The package export path where this bundle will be exposed. Use "." for the main package export, or subpath like "./config" for additional exports. Duplicate export paths across entry points are not allowed and will cause validation failure.
+- `format: ["esm"]`
+  - emits `.mjs` and `.d.mts`
+- `format: ["commonjs"]`
+  - emits `.cjs` and `.d.cts`
+- `format: ["esm", "commonjs"]`
+  - emits both sets
 
-**format (optional)**: Determines which module format(s), `commonjs`,`esm` or both `esm`and `commonjs` to generate.
-Defaults to `esm` if not specified.
+When `allowUpdatePackageJson` is `true`, Susee can update:
 
-**tsconfigFilePath (optional)**: Optional path to a custom TypeScript configuration file for this specific entry point. If not specified, susee will resolve for TypesScript compiler options as follow :
+- `type` (forced to `module`)
+- `main`
+- `module`
+- `types`
+- `exports` (including subpath exports from `exportPath`)
 
-Priority -
+## CLI
 
-1. this custom `tsconfig.json`
-
-2. `tsconfig.json` at root directory
-
-3. default compiler options of `susee`
-
-Notes: You can control TypesScript compiler options from `tsconfig.json` except , `rootDir` , `outDir`,`module`.
-
-**renameDuplicates (optional)**: Controls whether susee automatically renames duplicate identifiers during the bundling process to avoid naming conflicts when merging files.(default to `true`).If you want to rename your self set to `false`, process will exit with code-1 and print where duplicate found.
-
-## Plugins
-
-Plugins in the ecosystem have three common types:
-
-- `dependency` — transform dependency list before bundling
-- `pre-process` — modify the joined bundle text before compilation
-- `post-process` — modify emitted output files
-
-Plugins may be provided as objects or factories (functions returning the plugin). They may be synchronous or async — the bundler handles both.
-
-## package.json updates
-
-When `allowUpdatePackageJson` is enabled, susee will:
-
-- set `type` to `module` (to ensure ESM compatibility)
-- add/update `main`, `module`, `types` and `exports` for the main export when building the package root
-- merge subpath exports for non-root `exportPath`s without overwriting unrelated exports
-
-Output file name hints (produced by the compiler):
-
-- ESM JS -> `.mjs`
-- ESM types -> `.d.mts`
-- CJS JS -> `.cjs`
-- CJS types -> `.d.cts`
-
-## Limitations & notes
-
-- The bundler only processes local TypeScript files and does not bundle `node_modules` packages.
-- The entry file should be an ESM-compatible TypeScript file.
-- Exports from the entry file are not removed — only dependency exports may be stripped during bundling.
+```bash
+susee
+susee init
+```
 
-## Roadmap
+Any other argument combination exits with an error.
 
-Current environment support:
+## Local Development
 
-- Node.js only.
+Common project scripts:
 
-Planned work:
+```bash
+npm run build
+npm run test
+npm run lint
+npm run fmt
+npm run hooks:install
+```
 
-- [ ] Add first-class support for Deno environments.
-- [ ] Add browser-oriented library build support.
-- [ ] Improve workflows for building React-related libraries.
+Notes:
 
-## Contributing and tests
+- `npm run test` opens an interactive selector (`scripts/susee-tests.ts`).
+- Git hooks are tracked in `.githooks` and installed via `npm run hooks:install`.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow, pull request checklist, and development guidelines.
+## Contributing
 
-- Build and run tests with the repo scripts (see `package.json`):
+Contributions are welcome for bug fixes, features, documentation, and code quality improvements.
 
-```bash
-npm run build
-npm test
-```
+See detail in [CONTRIBUTING.md][file-contribute]
 
 ## License
 
@@ -220,4 +187,5 @@ npm test
 <!-- markdownlint-disable MD053 -->
 
 [license]: LICENSE
+[file-contribute]: CONTRIBUTING.md
 [ptm]: https://github.com/phothinmg

package/bin/index.mjs

@@ -1,3 +1,18 @@
 #!/usr/bin/env node
-import  {susee} from "../dist/index.mjs";
-await susee();
+import process from "node:process";
+import init from "../src/binary/init.mjs";
+import { susee } from "../dist/index.mjs";
+
+async function suseeBuild() {
+	const args = process.argv.slice(2);
+	if (args.length === 0) {
+		await susee();
+	} else if (args.length === 1 && args[0] === "init") {
+		await init();
+	} else {
+		console.error("Unknown CLI usage");
+		process.exit(1);
+	}
+}
+
+await suseeBuild();

package/bin/init.mjs

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import readline from "node:readline/promises";
+import tcolor from "@suseejs/tcolor";
+
+const tsFileText = String.raw`
+import type { SuSeeConfig } from "./src/index.js";
+
+const config: SuSeeConfig = {
+  // Array of entry point objects.
+  // ----------------------------
+  entryPoints: [
+    // You can add more entry points for different export paths.
+    // NOTE: duplicate export paths are not allowed.
+    // --------------------------------------------
+    {
+      // (required) Entry file path.
+      entry: "src/index.ts", // replace with your entry file
+      // (required) Export path for this entry.
+      exportPath: ".", // "." stands for the main export path and can be set to "./foo", "./bar", etc.
+      // (optional) Output module formats ["commonjs"] or ["esm", "commonjs"], default: ["esm"].
+      // Uncomment the following line to edit.
+      //format: ["esm"],
+      // (optional) Rename duplicate declarations, default: true.
+      // Uncomment the following line to edit.
+      //renameDuplicates: true,
+      // (optional) Custom tsconfig.json path, default: undefined.
+      // Uncomment the following line to edit.
+      //tsconfigFilePath: undefined,
+    },
+  ],
+  // NOTE: the following options apply to all entry points.
+  // ----------------------------------------------------------
+  // (optional) Output directory, default: dist.
+  // Uncomment the following line to edit.
+  //outDir: "dist",
+  // (optional) Array of susee plugins, default: [].
+  // Uncomment the following line to edit.
+  //plugins: [],
+  // (optional) Allow susee to update your package.json, default: false.
+  // Uncomment the following line to edit.
+  //allowUpdatePackageJson: false,
+};
+
+export default config;
+`.trim();
+
+const jsFileText = String.raw`
+/**
+ * @type {import("susee").SuSeeConfig}
+ */
+const config = {
+  // Array of entry point objects.
+  // ----------------------------
+  entryPoints: [
+    // You can add more entry points for different export paths.
+    // NOTE: duplicate export paths are not allowed.
+    // --------------------------------------------
+    {
+      // (required) Entry file path.
+      entry: "src/index.ts", // replace with your entry file
+      // (required) Export path for this entry.
+      exportPath: ".", // "." stands for the main export path and can be set to "./foo", "./bar", etc.
+      // (optional) Output module formats ["commonjs"] or ["esm", "commonjs"], default: ["esm"].
+      // Uncomment the following line to edit.
+      //format: ["esm"],
+      // (optional) Rename duplicate declarations, default: true.
+      // Uncomment the following line to edit.
+      //renameDuplicates: true,
+      // (optional) Custom tsconfig.json path, default: undefined.
+      // Uncomment the following line to edit.
+      //tsconfigFilePath: undefined,
+    },
+  ],
+  // NOTE: the following options apply to all entry points.
+  // ----------------------------------------------------------
+  // (optional) Output directory, default: dist.
+  // Uncomment the following line to edit.
+  //outDir: "dist",
+  // (optional) Array of susee plugins, default: [].
+  // Uncomment the following line to edit.
+  //plugins: [],
+  // (optional) Allow susee to update your package.json, default: false.
+  // Uncomment the following line to edit.
+  //allowUpdatePackageJson: false,
+};
+
+export default config;
+`.trim();
+/**
+ *
+ * @returns {Promise<"commonjs"|"esm">}
+ */
+async function getPackageType() {
+	const pkgFile = "package.json";
+	const pkgPath = path.resolve(process.cwd(), pkgFile);
+	const _pkg = await fs.promises.readFile(pkgPath, "utf8");
+	const pkg = JSON.parse(_pkg);
+	let type = "commonjs";
+	if (pkg.type && pkg.type === "module") type = "esm";
+	return type;
+}
+
+export default async function init() {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	const is_ts = await rl.question(tcolor.cyan("Is TypeScript project(y/n) : "));
+	const isTs = is_ts === "y" || is_ts === "Y" || is_ts === "" ? true : false;
+	rl.close();
+	let configFile;
+	let str;
+	if (isTs) {
+		configFile = "susee.config.ts";
+		str = tsFileText;
+	} else {
+		str = jsFileText;
+		const pkgType = await getPackageType();
+		switch (pkgType) {
+			case "commonjs":
+				configFile = "susee.config.mjs";
+				break;
+			case "esm":
+				configFile = "susee.config.js";
+				break;
+		}
+	}
+	const configFilePath = path.resolve(process.cwd(), configFile);
+	if (fs.existsSync(configFilePath)) await fs.promises.unlink(configFilePath);
+	await fs.promises.writeFile(configFilePath, str);
+	console.info(
+		tcolor.cyan(`Susee config file ${configFile} is created at project root`),
+	);
+}