@git.zone/tswatch 2.1.1 → 2.1.5

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@git.zone/tswatch',
-    version: '2.1.0',
+    version: '2.1.3',
     description: 'A development tool for automatically watching and re-compiling TypeScript projects upon detecting file changes, enhancing developer workflows.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxtQkFBbUI7SUFDekIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLGdKQUFnSjtDQUM5SixDQUFBIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git.zone/tswatch",
-  "version": "2.1.1",
+  "version": "2.1.5",
   "private": false,
   "description": "A development tool for automatically watching and re-compiling TypeScript projects upon detecting file changes, enhancing developer workflows.",
   "main": "dist_ts/index.js",
@@ -13,8 +13,8 @@
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^2.6.4",
-    "@git.zone/tstest": "^2.3.1",
-    "@types/node": "^24.0.4"
+    "@git.zone/tstest": "^2.3.2",
+    "@types/node": "^22"
   },
   "dependencies": {
     "@api.global/typedserver": "^3.0.74",
@@ -22,7 +22,7 @@
     "@git.zone/tsrun": "^1.3.3",
     "@push.rocks/early": "^4.0.4",
     "@push.rocks/lik": "^6.2.2",
-    "@push.rocks/smartchok": "^1.0.34",
+    "@push.rocks/smartchok": "^1.1.1",
     "@push.rocks/smartcli": "^4.0.11",
     "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartfile": "^11.2.5",

package/readme.hints.md

@@ -0,0 +1,44 @@
+# tswatch Project Hints
+
+## Core Architecture
+- tswatch is a TypeScript file watcher with multiple operation modes
+- Main class `TsWatch` orchestrates different watch modes
+- `Watcher` class handles individual file watching and command execution
+
+## Available Watch Modes
+1. **npm/node** (default): Runs `npm test` on changes
+2. **test**: Runs `npm run test2` on changes
+3. **element**: Web component development with dev server on port 3002
+4. **service**: Runs `npm run startTs` for service projects
+5. **website**: Full website mode with bundling and asset processing
+6. **echo**: Test mode that runs `npm -v` (for testing)
+
+## Key Implementation Details
+- Uses `@push.rocks/smartchok` for file watching
+- Uses `@git.zone/tsbundle` for bundling with esbuild
+- Uses `@api.global/typedserver` for development server in element mode
+- Element/website modes watch multiple `ts*/` directories
+- All modes support both command execution and function callbacks
+
+## CLI Entry Points
+- `cli.js` -> Main CLI entry point
+- `ts/tswatch.cli.ts` -> CLI implementation with smartcli
+- Default command triggers npm mode
+
+## Project Structure Expectations
+- `ts/` - Backend TypeScript files
+- `ts_web/` - Frontend TypeScript files (element/website modes)
+- `html/` - HTML templates (element/website modes)
+- `assets/` - Static assets (website mode only)
+- `dist_watch/` - Output for element mode
+- `dist_serve/` - Output for website mode
+
+## Development Server Details
+- Port: 3002
+- Features: CORS, gzip compression, live reload injection
+- Only available in element mode via `typedserver` property
+
+## Common Issues to Watch For
+- The test mode runs `test2` script, not `test`
+- Website mode restarts the entire server process on backend changes
+- Element mode rebuilds and reloads on any ts* folder change

package/readme.md

@@ -1,183 +1,213 @@
 # @git.zone/tswatch
 
-A development tool for watching and re-compiling TypeScript projects automatically upon detecting changes.
+A TypeScript file watcher that automatically recompiles and executes your project when files change. Designed to streamline development workflows for various TypeScript project types.
 
-## Install
+## Features
 
-To install `@git.zone/tswatch`, ensure that you have a Node.js environment set up with npm. You can install the package globally or locally within a project using npm:
+- 🔄 **Automatic recompilation** on file changes
+- 🚀 **Multiple project modes**: npm packages, web elements, services, and websites
+- 🌐 **Built-in development server** with live reload for web projects
+- ⚡ **Fast bundling** with esbuild integration
+- 🛠️ **Flexible CLI and programmatic API**
+- 📦 **Zero configuration** for standard project structures
 
-```bash
-npm install @git.zone/tswatch
-```
-
-This command will install the package and enable you to use the `tswatch` command in your terminal to watch TypeScript projects.
-
-## Usage
-
-`@git.zone/tswatch` is a powerful tool designed to streamline your development workflow by monitoring your TypeScript files and automatically recompiling them when changes are detected. This utility is particularly helpful during the development phase of a TypeScript project, ensuring your project remains up-to-date, reflecting the latest changes seamlessly.
-
-### Getting Started with tswatch
+## Prerequisites
 
-To get started, we will explore setting up a basic watcher, integrating tswatch into a Node.js environment, utilizing advanced features, and handling multiple watchers.
+- Node.js (v14 or higher)
+- pnpm (recommended) or npm
 
-### Setting Up a Basic Watcher
+## Installation
 
-#### Step 1: Basic Command-Line Interface Usage
+Install `@git.zone/tswatch` globally or as a development dependency:
 
-After installing `@git.zone/tswatch`, you can start a watcher on your TypeScript project using its command-line interface (CLI). Here's how to initiate a watcher for different project types:
-
-```typescript
-import { runCli } from '@git.zone/tswatch';
+```bash
+# Global installation
+pnpm install -g @git.zone/tswatch
 
-(async () => {
-  await runCli();
-})();
+# As a dev dependency
+pnpm install --save-dev @git.zone/tswatch
 ```
 
-The CLI supports several commands to watch different project types such as `element`, `npm`, `service`, and `website`. Here's how to use them:
+## Quick Start
 
-- **NPM Projects**: Watch a Node.js NPM project:
+```bash
+# Watch and run tests on changes (default behavior)
+tswatch
 
-  ```bash
-  tswatch npm
-  ```
+# Watch a web element project with dev server
+tswatch element
 
-  This command will start a watcher for your node module projects. Whenever changes are detected, the specified npm scripts are executed.
+# Watch a service project
+tswatch service
+```
 
-- **Element Projects**: Watch an element-based architecture:
+## CLI Commands
 
-  ```bash
-  tswatch element
-  ```
+### `tswatch` or `tswatch npm`
+Watches TypeScript files and runs `npm test` on changes. This is the default mode.
 
-  This command sets up a development server with live reloading and bundles TypeScript files to a `dist_watch` directory.
+```bash
+tswatch
+# or explicitly
+tswatch npm
+```
 
-- **Service Projects**: Watch a service project:
+### `tswatch element`
+Sets up a development environment for web components/elements:
+- Starts a dev server on port 3002
+- Bundles TypeScript to `dist_watch/`
+- Enables live reload
+- Watches all `ts*/` folders
 
-  ```bash
-  tswatch service
-  ```
+```bash
+tswatch element
+```
 
-  Watches TypeScript files in a service pattern, restarting the service when changes are detected.
+### `tswatch service`
+Watches TypeScript files in `./ts/` and runs `npm run startTs` on changes. Ideal for backend services.
 
-- **Website Projects**: Perfect for full website projects:
+```bash
+tswatch service
+```
 
-  ```bash
-  tswatch website
-  ```
+### `tswatch website`
+Full website development mode:
+- Bundles TypeScript files to `dist_serve/`
+- Processes HTML files
+- Handles assets
+- Runs `npm run startTs` for server-side code
 
-  Similar to element projects but specifically designed for full websites, recompiling TypeScript files for web deployment scenarios.
+```bash
+tswatch website
+```
 
-#### Step 2: Integration into a Node.js Environment
+### `tswatch test`
+Runs `npm run test2` whenever files change. Useful for projects with custom test scripts.
 
-You can integrate `@git.zone/tswatch` directly into a Node.js project for automatic file watching and recompiling:
+```bash
+tswatch test
+```
 
-```typescript
-import { TsWatch } from '@git.zone/tswatch';
+## Project Structure
 
-const startWatch = async () => {
-  // Initialize watch instance for a node project
-  const watchInstance = new TsWatch('node');
-  await watchInstance.start();
-};
+tswatch expects certain project structures depending on the mode:
 
-// Optionally, stop the watcher gracefully
-const stopWatch = async (watchInstance: TsWatch) => {
-  await watchInstance.stop();
-};
+### NPM/Node Projects
+```
+project/
+├── ts/           # TypeScript source files
+├── test/         # Test files
+└── package.json  # With "test" script
 ```
 
-This setup will establish a node environment watch, automatically recompiling files as changes occur.
+### Element Projects
+```
+project/
+├── ts/           # Backend TypeScript
+├── ts_web/       # Frontend TypeScript
+├── html/         # HTML templates
+│   └── index.ts  # Entry point
+└── dist_watch/   # Output directory (auto-created)
+```
 
-### Advanced Usage: Enhancing Workflow with tswatch
+### Website Projects
+```
+project/
+├── ts/           # Backend TypeScript
+├── ts_web/       # Frontend TypeScript
+│   └── index.ts  # Entry point
+├── html/         # HTML files
+│   └── index.html
+├── assets/       # Static assets
+└── dist_serve/   # Output directory
+```
 
-#### Starting a TypedServer with Watch Integration
+## Programmatic API
 
-For projects requiring a development server, integrate `typedserver` for handling HTTP server tasks:
+### Basic Usage
 
 ```typescript
 import { TsWatch } from '@git.zone/tswatch';
 
-const startTypedServer = async () => {
-  const watchInstance = new TsWatch('element');
-  await watchInstance.start();
+// Create and start a watcher
+const watcher = new TsWatch('node');
+await watcher.start();
 
-  // Serve a local directory using a typedserver with CORS and compression
-  const server = watchInstance.typedserver;
-  if (server) {
-    await server.start();
-  }
-};
+// Stop when done
+await watcher.stop();
 ```
 
-This code watches for changes and serves the project locally, providing reload capabilities for smooth development.
-
-#### Step 3: Custom Watchers
-
-Beyond built-in commands, you can create custom watchers for detailed control over file monitoring and execution responses:
+### Custom Watchers
 
 ```typescript
 import { Watcher } from '@git.zone/tswatch';
 
-const customWatcherSetup = async () => {
-  const customWatcher = new Watcher({
-    filePathToWatch: '/path/to/watch',
-    commandToExecute: 'npm run custom-script',
-  });
+const customWatcher = new Watcher({
+  filePathToWatch: './src',
+  commandToExecute: 'npm run build',
+  timeout: 5000 // Optional timeout in ms
+});
 
-  // Start and stop the custom watcher as needed
-  await customWatcher.start();
-  await customWatcher.stop();
-};
+await customWatcher.start();
 ```
 
-Define specific file paths and custom shell commands with the options provided by the `Watcher` class.
-
-#### Step 4: Handling Multiple Watchers
-
-To handle multiple directories or file sets, use the `ObjectMap` utility, efficiently managing multiple `Watcher` instances within the `TsWatch` framework:
+### Using Function Callbacks
 
 ```typescript
-import { TsWatch } from '@git.zone/tswatch';
+const watcher = new Watcher({
+  filePathToWatch: './src',
+  functionToCall: async () => {
+    console.log('Files changed!');
+    // Your custom logic here
+  }
+});
+```
 
-const setupMultipleWatchers = async () => {
-  const tsWatchInstance = new TsWatch('node');
+## Development Server
 
-  // View active watchers through instance mapping
-  tsWatchInstance.watcherMap.forEach((watcher) => {
-    console.log(`Watcher listening on: ${watcher.toString()}`);
-  });
+Element mode includes a built-in development server:
 
-  // Initiate all watchers
-  await tsWatchInstance.start();
-};
-```
+- **Port**: 3002
+- **Features**: CORS enabled, gzip compression, live reload
+- **Serve directory**: `./dist_watch/`
 
-Incorporate this setup for efficiently managing complex projects with varied sources and parallel build tasks.
+Access your project at `http://localhost:3002` when running in element mode.
 
-#### Handling Timeout and Cleanup
+## Configuration Tips
 
-`@git.zone/tswatch` includes functions to manage process exits and timeout scenarios robustly:
+1. **TypeScript Config**: Ensure your `tsconfig.json` is properly configured for your target environment
+2. **Package Scripts**: Define appropriate scripts in `package.json`:
+   - `test`: For npm mode
+   - `startTs`: For service/website modes
+   - `build`: For general compilation
 
-```typescript
-import { Watcher } from '@git.zone/tswatch';
+3. **File Organization**: Keep TypeScript files in `ts/` (backend) and `ts_web/` (frontend) directories
 
-const watcherWithTimeout = () => {
-  new Watcher({
-    filePathToWatch: './src/',
-    timeout: 10000, // 10 seconds timeout
-    commandToExecute: 'echo "Task completed"',
-  }).start();
-};
-```
+## Common Use Cases
 
-The `timeout` option ensures processes don't run indefinitely, aiding development and potential automated testing scenarios.
+### Developing a Node.js Library
+```bash
+tswatch npm
+```
+Automatically runs tests when you modify source files.
 
-### Conclusion
+### Building a Web Component
+```bash
+tswatch element
+```
+Get instant feedback with live reload while developing custom elements.
 
-By providing flexible configurations, a robust CLI, and deep integration capabilities, `@git.zone/tswatch` serves as a comprehensive solution for automating and optimizing your TypeScript development processes. Whether managing server-side environments or advanced web apps, using this tool will ensure your projects are always ready with the latest changes.
+### Creating a Backend Service
+```bash
+tswatch service
+```
+Automatically restart your service on code changes.
 
-Explore the various features and tailor the tool to fit your unique project requirements, leading to faster and more efficient development workflows.
+### Full-Stack Web Application
+```bash
+tswatch website
+```
+Handle both frontend and backend compilation with asset processing.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tswatch',
-  version: '2.1.1',
+  version: '2.1.3',
   description: 'A development tool for automatically watching and re-compiling TypeScript projects upon detecting file changes, enhancing developer workflows.'
 }