@reflex-stack/tsp 0.1.2 → 0.1.4

package/README.md

@@ -1,17 +1,32 @@
-# TypeScript Package (TSP)
+# TypeScript Package (tsp)
 
 **TypeScript Package** (tsp), scaffolds and build **Typescript** sources to **EcmaScript modules** and publish them as modular packages to **NPM** or **JSR**.
 
-## Init a new library
+**Features :**
+- It uses `tsc` to compile from ts to js and check errors
+- Generates `.d.ts` to keep types when used
+- Scaffold new packages in 1 minute
+- Testing lib pre-installed, can also use your own or skip tests
+- Generating size report as SVG for **README.md** inclusion ( ex : <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./tests/example-package/reports/main-dark.svg"><img src="./tests/example-package/reports/main-light.svg"></picture> ) 
+- Compatible with latest **Node** / **Bun** / **Deno** and all bundlers with ecma specification
+- Publishing under `.js` and `.d.ts` helps having better performances in your projects ( typescript is faster ), event if **Bun** or **Deno** support Typescript by default.
 
-First, create the associated **git repository** and clone it.
+Check example on [NPM](https://www.npmjs.com/package/@reflex-stack/tsp-example) and [GitHub](https://github.com/reflex-stack/tsp/tree/main/tests/example-package)
 
-Run this command in git trunk :
+## Init a new TypeScript Package
+
+First, create the associated **git repository** for your package and clone it ( optional ).
+
+Then, run this command in the cloned directory. :
 ```bash
 npx @reflex-stack/tsp init
 ```
 
-## Created files
+> If you create this package in a mono-repo, `cd` in the correct repository before running this command. The subdirectory is important for package.json and size report generation. 
+
+#### Created files
+
+This will ask some questions and create those files. It contains 1 **submodule** example and a simple test implementation.
 
 ```
 ├─ dist/
@@ -21,6 +36,7 @@ npx @reflex-stack/tsp init
 │  └─ index.ts
 ├─ tests/
 │  └─ test.js
+│  └─ tsconfig.json ( to have correct typings in test.js )
 ├─ .gitignore
 ├─ .npmignore
 ├─ LICENCE ( if MIT )
@@ -39,27 +55,67 @@ npm run build
 - Will clear `./dist`, build sources from `.ts` files to `.js` and `.d.ts` files.
 - Will generate size report and generate `./reports` directory with JSON and SVG files.
 
-> Run `npm run build --noSizeReport`
+> Run `npm run build --noSizeReport` to skip size report entirely.
 
 #### Test
-- `npm run test`
+```bash
+npm run test
+```
 > Will clear `./dist`, build sources and run tests. No size report.
 
 #### Publish
-- `npm run publish`
-> Will clear `./dist`, build sources and run tests, and start publish process.
+```bash
+npm run publish
+```
+> Will clear `./dist`, build sources, run tests, and start publish process.
 > This will ask you how to upgrade package.json version, push to git and npm.
 
 
 ## Size report
-- TODO SVG doc
-- TODO JSON doc
 
-## tsconfig
-- TODO doc, explain forbidden properties
+**TSP** can generate size reports with brotli compression. It generate :
+- 2 svgs for root module
+- 2 svgs by submodule
+- 2 svgs for total if you have submodules
+
+There are 2 svgs generated, for dark and light mode, to be included in the README.md, on **GitHub** and **NPM**.
+
+> When scaffolded, an example of SVG inclusion is generated in README.md
+
+How to include the size report in `README.md` ?
+
+```html
+Main bundle is <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./reports/main-dark.svg"><img src="./reports/main-light.svg"></picture>
+Submodule is <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./reports/submodule-dark.svg"><img src="./reports/submodule-light.svg"></picture>
+Total is <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./reports/total-dark.svg"><img src="./reports/total-light.svg"></picture>
+```
+
+> Those works in GitHub and NPM
+
+**TSP** can also generate a json size report if needed ( default is set to false )
 
 ## TSP config
-- TODO tsp config
+TSP config is in the generated `package.json` under the `"tsp"` node
+
+```json5
+{
+  "tsp": {
+	// Can set to "bun" or "deno" 
+	"runtime": "node",
+	// If you change them, you should update tsconfig.json file
+	"src": './src',
+	"dist": './dist',
+	"tests": './tests',
+	"tmp": './tmp',
+	// Add your test files here
+	"test-files": ['test.js'],
+	// Where size reports are generated
+	"reports": './reports',
+	"generate-json-report": false,
+	"generate-svg-report": true
+  },
+}
+```
 
-## Next
-- TODO config override from package
+## Next features
+- [ ] docisfy integration

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@reflex-stack/tsp",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"type": "module",
 	"bin": {
 		"tsp": "./src/cli.js"

package/src/commands/init.js

@@ -1,6 +1,6 @@
 import { nicePrint, askInput, askList, newLine, oraTask, execAsync } from "@zouloux/cli"
 import { getConfig } from "../config.js";
-import { getGitRemoteUrl, getTSPPackageJson } from "../utils.js";
+import { getGitRemoteUrl, getGitSubdirectory, getTSPPackageJson } from "../utils.js";
 import { existsSync, writeFileSync } from "node:fs";
 import { Stach } from "stach";
 import { mkdirSync } from "fs";
@@ -29,16 +29,8 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.`
 
 const readmeTemplate = `# {{ packageTextName }}
-Main bundle is
-<picture style="display: inline-block">
-  <source media="(prefers-color-scheme: dark)" srcset="./reports/main-dark.svg">
-  <img src="./reports/main-light.svg">
-</picture>
-Optional submodule is only
-<picture style="display: inline-block">
-  <source media="(prefers-color-scheme: dark)" srcset="./reports/submodule-dark.svg">
-  <img src="./reports/submodule-light.svg">
-</picture>
+Main bundle is <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./reports/main-dark.svg"><img src="./reports/main-light.svg"></picture>
+and optional submodule is only <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./reports/submodule-dark.svg"><img src="./reports/submodule-light.svg"></picture>
 
 ## Install
 
@@ -52,7 +44,7 @@ Optional submodule is only
 ##### Sub module
 - \`import { ... } from "{{ packageNPMName }}/submodule"\`
 
-## tsp commands
+## Build commands
 
 ##### Build
 - \`npm run build\`
@@ -60,6 +52,10 @@ Optional submodule is only
 - \`npm run test\`
 ##### Publish
 - \`npm run publish\`
+
+---
+## TSP
+This package has been created with [tsp](https://github.com/reflex-stack/tsp)
 `
 
 const tsconfigTemplate = `{
@@ -159,8 +155,8 @@ describe("Main module", () => {
 
 describe("Sub module", () => {
 	it("Should call sub random", () => {
-		const rootResult = subRandomFunction()
-		expect(rootResult).toBe(60)
+		const subResult = subRandomFunction()
+		expect(subResult).toBe(60)
 	})
 	// Test error example
 	// it("Should fail", () => {
@@ -181,13 +177,19 @@ export async function init () {
 	}
 	// Get git remote
 	const config = getConfig()
-	let remoteURL = getGitRemoteUrl( config.cwd )
-	if ( !remoteURL )
-		nicePrint(`{o}Before scaffolding your TypeScript package, you should create the associated git repository.`)
-	else
+	const remoteURL = getGitRemoteUrl( config.cwd )
+	const relativeGitSubDirectory = getGitSubdirectory()
+	if ( !remoteURL ) {
+		nicePrint(`{o}Before scaffolding your TypeScript package, you should create the associated git repository, and cd in the correct sub-directory.`)
+	}
+	else {
 		nicePrint(`{d}Git origin is {/}${remoteURL}`)
+		if ( relativeGitSubDirectory ) {
+			nicePrint(`{d}Git sub directory is {/}${relativeGitSubDirectory}. This will be saved to package.json.`)
+		}
+	}
 	newLine()
-	const options = { remoteURL }
+	const options = { remoteURL, relativeGitSubDirectory }
 	options.packageTextName = await askInput(`Package name, in plain text {d}ex : My Package`, { notEmpty: true })
 	options.packageNPMName = await askInput(`Package name, for NPM, with namespace {d}ex : @mynamespace/mypackage`, { notEmpty: true })
 	options.authorName = await askInput(`Author name`, { notEmpty: true })
@@ -250,6 +252,10 @@ export async function init () {
 			type: "git",
 			url: options.remoteURL
 		}
+		// Add subdirectory for package.json and SVG targeting in README.md on NPMJs
+		if ( options.relativeGitSubDirectory ) {
+			packageJson.repository.directory = options.relativeGitSubDirectory
+		}
 	}
 	// Create directories
 	mkdirSync(config.tests, { recursive: true })

package/src/commands/size-report.js

@@ -112,21 +112,37 @@ export function generateJSON ( sizeReport, config ) {
 	)
 }
 
+async function generateTextSVG ( filePath, scheme, text ) {
+	const svgBitFile = new File( filePath );
+	const fontSize = 14
+	const height = fontSize + 1
+	const width = text.length * fontSize * 0.6 + 1
+	svgBitFile.content( () => [
+		`<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">`,
+		`<style> text { fill: ${scheme === "dark" ? "white" : "black" }; font-family: Consolas, Monaco, "Lucida Console", monospace; font-size: ${fontSize}px; }</style>`,
+		`<text y="${height - 1}">${text}</text>`,
+		`</svg>`,
+	].join(""))
+	await svgBitFile.ensureParents()
+	await svgBitFile.save();
+}
+
 export async function generateSVGs ( sizeReport, config ) {
+	let total = 0
 	for ( const bundle of sizeReport ) {
 		const size = bundle.sizes[2]
+		total += size
 		const sizeContent = naiveHumanFileSize( size )
 		for ( const scheme of ["light", "dark"] ) {
-			const bitPath = join( config.cwd, config.reports, `${bundle.name}-${scheme}.svg` )
-			const svgBitFile = new File( bitPath );
-			svgBitFile.content( () => [
-				`<svg width="${sizeContent.length * 10}" height="22" xmlns="http://www.w3.org/2000/svg">`,
-				`<style> text { fill: ${scheme === "dark" ? "white" : "black" }; font-family: 'Segoe UI', 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 14px; }</style>`,
-				`<text y="21">${sizeContent}</text>`,
-				`</svg>`,
-			].join(""))
-			await svgBitFile.ensureParents()
-			await svgBitFile.save();
+			const filePath = join( config.cwd, config.reports, `${bundle.name}-${scheme}.svg` )
+			await generateTextSVG( filePath, scheme, sizeContent )
+		}
+	}
+	if ( sizeReport.length > 1 ) {
+		const sizeContent = naiveHumanFileSize( total )
+		for ( const scheme of ["light", "dark"] ) {
+			const filePath = join( config.cwd, config.reports, `total-${scheme}.svg` )
+			await generateTextSVG( filePath, scheme, sizeContent )
 		}
 	}
 }

package/src/utils.js

@@ -1,4 +1,4 @@
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
 import { newLine, nicePrint } from "@zouloux/cli";
@@ -59,3 +59,19 @@ export function getGitRemoteUrl ( cwd ) {
     return '';
   }
 }
+
+
+export function getGitSubdirectory () {
+    let currentDir = process.cwd()
+    let rootDir = null
+    while ( currentDir !== '/' ) {
+        if ( existsSync(join(currentDir, '.git')) ) {
+            rootDir = currentDir
+            break
+        }
+        currentDir = dirname(currentDir)
+    }
+    if ( !rootDir )
+			return null
+    return relative(rootDir, process.cwd())
+}

package/tests/example-package/README.md

@@ -1,13 +1,31 @@
-# ecma-build test package
-
-Main bundle is only
-<picture style="display: inline-block">
-  <source media="(prefers-color-scheme: dark)" srcset="./reports/main-dark.svg">
-  <img src="./reports/main-light.svg">
-</picture>
-
-Optional sub-module is only 
-<picture style="display: inline-block">
-  <source media="(prefers-color-scheme: dark)" srcset="./reports/submodule-dark.svg">
-  <img src="./reports/submodule-light.svg">
-</picture>
+# TSP Example
+
+## This is a test package for @reflex-stack/tsp, do not use it
+
+Main bundle is <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./reports/main-dark.svg"><img src="./reports/main-light.svg"></picture>
+and optional submodule is only <picture style="display: inline-block"><source media="(prefers-color-scheme: dark)" srcset="./reports/submodule-dark.svg"><img src="./reports/submodule-light.svg"></picture>
+
+## Install
+
+`npm i @reflex-stack/tsp-example`
+
+## Usage
+
+##### Main module
+- `import { ... } from "{{ packageNPMName }}"`
+
+##### Sub module
+- `import { ... } from "{{ packageNPMName }}/submodule"`
+
+## Build commands
+
+##### Build
+- `npm run build`
+##### Test
+- `npm run test`
+##### Publish
+- `npm run publish`
+
+---
+## TSP
+This package has been created with [tsp](https://github.com/reflex-stack/tsp)

package/tests/example-package/dist/stuff.d.ts

@@ -1 +1 @@
-export declare function doStuff(): void;
+export declare function doStuff(): string;

package/tests/example-package/dist/stuff.js

@@ -1,4 +1,5 @@
 import { commonDep } from "./common-dep.js";
 export function doStuff() {
-    console.log("Do stuff", commonDep);
+    console.log("DO STUFFF");
+    return `Do stuff ${commonDep}`;
 }

package/tests/example-package/dist/submodule/index.d.ts

@@ -1 +1 @@
-export declare function doSubmoduleStuff(): void;
+export declare function doSubmoduleStuff(): string;

package/tests/example-package/dist/submodule/index.js

@@ -1,5 +1,5 @@
 import { submoduleDep } from "./submodule-dep.js";
 import { commonDep } from "../common-dep.js";
 export function doSubmoduleStuff() {
-    console.log("Do submodule stuff", submoduleDep, commonDep);
+    return `Do submodule stuff ${submoduleDep} ${commonDep}`;
 }