jopijs 0.0.1

package/src/@loader-tools/sourceChangesWatcher.ts

@@ -0,0 +1,225 @@
+import path from "node:path";
+import {spawn, ChildProcess} from "node:child_process";
+import chokidar from "chokidar";
+import * as jk_timer from "jopi-toolkit/jk_timer";
+
+export interface SourceChangesWatcherParams {
+    watchDirs: string[];
+    excludeDir: string[];
+    env?: Record<string, string>;
+    cmd?: string;
+    args?: string[];
+    isDev: boolean;
+    mustLog: boolean;
+    jsEngine: string;
+}
+
+/**
+ * Watches source directories for changes and restarts a server process automatically.
+ * - Add directories to watch (recursively).
+ * - Configurable delay (debounce) before restarting.
+ * - Includes a helper to auto-detect the source directory when using TypeScript.
+ */
+export class SourceChangesWatcher {
+    private readonly _fileWatchingDelay: number;
+    private readonly _restartDelay: number;
+
+    private _areSignalCatch = false;
+
+    private restarting = false;
+    private _isStarted = false;
+
+    private _enableLogs: boolean = false;
+
+    private readonly watchDirs: string[];
+    private readonly excludeDir: string[];
+    private readonly env: Record<string, string>;
+
+    private readonly _cmd: string;
+    private readonly _args: string[];
+
+    private _timerId: number = 0;
+    private readonly _isDev: boolean;
+    private readonly _mustLog: boolean;
+
+    constructor(params: SourceChangesWatcherParams) {
+        const isNodeJS = params.jsEngine === "node";
+
+        this._fileWatchingDelay = isNodeJS ? 1000 : 500;
+        this._restartDelay = isNodeJS ? 500 : 10;
+
+        this.watchDirs = params.watchDirs;
+        this.excludeDir = params.excludeDir;
+
+        if (params.env) this.env = params.env;
+        else this.env = process.env as Record<string, string>;
+
+        this._cmd = params.cmd || process.argv0;
+        this._args = params.args || [];
+
+        this._isDev = params.isDev;
+        this._mustLog = params.mustLog;
+    }
+
+    async start() {
+        if (this._isStarted) return;
+        this._isStarted = true;
+
+        for (const dir of this.watchDirs) {
+            await this.watchDirectoryRecursive(dir);
+        }
+
+        // Create the first child.
+        await this.spawnChild(true);
+    }
+
+    private async askToRestart(filePath: string) {
+        if (this.excludeDir) {
+            let isExcluded = this.excludeDir.find(p => filePath.startsWith(p))
+            if (isExcluded) return;
+        }
+
+        // Avoid it if inside a hidden directory (start by .).
+        let pathParts = filePath.split(path.sep);
+        let hiddenPart = pathParts.find(e => e[0] === '.')
+        if (hiddenPart) return;
+
+        // Avoid it if inside a node module. Reason: some tools used it as a temp.
+        let nodeModule = pathParts.find(e => e === 'node_modules');
+        if (nodeModule) return;
+
+        // Allow avoiding restart until stability is found.
+        if (this._timerId) {
+            return;
+        }
+
+        // @ts-ignore
+        this._timerId = setTimeout(async () => {
+            this._timerId = 0;
+
+            if (this.restarting) return;
+            this.restarting = true;
+
+            //console.clear();
+
+            if (this._enableLogs) {
+                console.log("File change watcher - RESTART for:", filePath);
+            }
+
+            try {
+                await this.spawnChild();
+            } finally {
+                this.restarting = false;
+            }
+        }, this._restartDelay);
+    }
+
+    private async watchDirectoryRecursive(dir: string) {
+        const watcher = chokidar.watch(dir, {
+            persistent: true,
+            ignoreInitial: true,
+
+            // Ignore common heavy/irrelevant directories
+            ignored: (watchedPath: string) => {
+                const b = path.basename(watchedPath);
+                return b === 'node_modules' || b === '.git' || b === '.idea' || b === '.vscode';
+            },
+
+            awaitWriteFinish: {
+                stabilityThreshold: this._fileWatchingDelay,
+                pollInterval: Math.min(100, this._fileWatchingDelay)
+            }
+        });
+
+        watcher.on('all', async (_event, paths) => {
+            await this.askToRestart(paths)
+        });
+
+        watcher.on('error', () => { /* swallow watcher errors to keep running */
+        });
+    }
+
+    private killAll() {
+        if (this._isDev) {
+            // > Do a fast hard kill.
+            if (gChild && !gChild.killed) gChild.kill('SIGKILL');
+            process.exit(0);
+        } else {
+            // > Do a soft kill.
+            if (gChild) {
+                const child = gChild;
+                child.kill('SIGTERM');
+
+                setTimeout(() => {
+                    if (!child.killed) {
+                        child.kill('SIGKILL');
+                    }
+                }, 3000);
+            }
+        }
+    }
+
+    public async spawnChild(ignoreSpawnEvent = false) {
+        if (gChild) {
+            if (!gChild.killed) {
+                // Do a hard kill.
+                // Not a problem since we are in dev mode.
+                gChild.kill("SIGKILL");
+            }
+
+            gChild = undefined;
+            await jk_timer.tick(100);
+        }
+
+        let useShell = this._cmd.endsWith('.cmd') || this._cmd.endsWith('.bat') || this._cmd.endsWith('.sh');
+
+        if (!this._areSignalCatch) {
+            this._areSignalCatch = true;
+
+            process.on('SIGTERM', () => this.killAll());
+            process.on('SIGINT', () => this.killAll());
+            process.on('SIGHUP', () => this.killAll());
+            process.on('exit', () => this.killAll());
+        }
+
+        if (this._mustLog) {
+            console.log("spawning", {cmd: this._cmd, args: this._args, cwd: process.cwd(), useShell})
+        }
+
+        const child = spawn(this._cmd, this._args, {
+            stdio: "inherit", shell: useShell,
+            cwd: process.cwd(),
+            env: this.env
+        });
+
+        gChild = child;
+
+        child.on('exit', (code, signal) => {
+            // The current instance has stopped?
+            if (gChild===child) {
+                if (signal) process.kill(process.pid, signal);
+                else process.exit(code ?? 0);
+            }
+        });
+
+        child.on('error', (err) => {
+            // The current instance is in error?
+            if (gChild===child) {
+                console.error(err.message || String(err));
+                process.exit(1);
+            }
+        });
+
+        if (!ignoreSpawnEvent) {
+            child.on("spawn", () => {
+                this.onSpawned();
+            });
+        }
+    }
+
+    onSpawned() {
+        // To override.
+    }
+}
+
+let gChild: ChildProcess|undefined;

package/src/@loader-tools/tools.ts

@@ -0,0 +1,139 @@
+import path from "node:path";
+import * as jk_app from "jopi-toolkit/jk_app";
+import * as jk_fs from "jopi-toolkit/jk_fs";
+
+import fss from "node:fs";
+import stripJsonComments from "strip-json-comments";
+import {resolve as resolvePath} from "path";
+
+/**
+ * Search the entry point of the current package (ex: ./dist/index.json)
+ * @param nodePackageDir - The path of the current module.
+ * @returns Returns the full path of the script.
+ */
+export function findNodePackageEntryPoint(nodePackageDir: string): string {
+    const packageJsonPath = path.join(nodePackageDir, 'package.json');
+
+    // >>> Try to take the "main" information inside the package.json.
+
+    if (fss.existsSync(packageJsonPath)) {
+        try {
+            const packageJson = JSON.parse(fss.readFileSync(packageJsonPath, 'utf8'));
+
+            if (packageJson.main) {
+                const mainPath = path.join(nodePackageDir, packageJson.main);
+                if (fss.existsSync(mainPath)) return mainPath;
+            }
+        } catch {
+            // Ignore JSON parse errors
+        }
+    }
+
+    // >>> "main" not set? Try all common path.
+
+    const commonPaths = [
+        path.join('dist', 'index.js'),
+        path.join('lib', 'index.js'),
+        path.join('src', 'index.js'),
+        'index.js'
+    ];
+
+    for (const commonPath of commonPaths) {
+        const fullPath = path.join(nodePackageDir, commonPath);
+        if (fss.existsSync(fullPath)) return fullPath;
+    }
+
+    // Default to dist/index.js
+    return path.join(nodePackageDir, 'dist', 'index.js');
+}
+
+/**
+ * Searches for the directory of a specified module.
+ *
+ * @param packageName - The name of the module to find.
+ * @return The path to the module directory if found, or null if not found.
+ */
+export function findNodePackageDir(packageName: string): string|null {
+    let currentDir = process.cwd();
+
+    while (true) {
+        const packagePath = path.join(currentDir, 'node_modules', packageName);
+
+        if (fss.existsSync(packagePath)) {
+            return packagePath;
+        }
+
+        const parentDir = path.dirname(currentDir);
+
+        // Reached root directory
+        if (parentDir === currentDir) {
+            break;
+        }
+
+        currentDir = parentDir;
+    }
+
+    return null;
+}
+
+let gCache_getPathAliasInfo: PathAliasInfo|undefined;
+
+export interface PathAliasInfo {
+    rootDir: string;
+    alias: Record<string, string>
+}
+
+/**
+ * Return a dictionary of path alias (ex: import "@/ui/myComponent")
+ */
+export async function getPathAliasInfo(): Promise<PathAliasInfo> {
+    if (gCache_getPathAliasInfo) return gCache_getPathAliasInfo;
+
+    let pkgJsonFile = jk_app.findPackageJson();
+    if (!pkgJsonFile) throw new Error("Package.json not found");
+
+    const rootDir = path.dirname(pkgJsonFile);
+
+    let tsconfigJsonPath = path.join(rootDir, "tsconfig.json");
+
+    if (!await jk_fs.isFile(tsconfigJsonPath)) {
+        throw new Error(`tsconfig.json not found at ${tsconfigJsonPath}`);
+    }
+
+    let asText = await jk_fs.readTextFromFile(tsconfigJsonPath);
+    let asJson = JSON.parse(stripJsonComments(asText));
+
+    let compilerOptions = asJson.compilerOptions;
+    let declaredAliases: Record<string, string> = {};
+
+    if (compilerOptions) {
+        let paths = compilerOptions.paths;
+
+        /** Exemple
+         * "paths": {
+         *       "@/*": ["./src/shadcn/*"],
+         *       "@/lib/*": ["./src/shadcn/lib/*"],
+         *       "@/components/*": ["./src/shadcn/components/*"]
+         *     }
+         */
+
+        for (let alias in paths) {
+            let pathAlias = paths[alias].pop() as string;
+            if (!pathAlias) continue;
+
+            if (alias.endsWith("*")) alias = alias.substring(0, alias.length - 1);
+            if (pathAlias.endsWith("*")) pathAlias = pathAlias.substring(0, pathAlias.length - 1);
+
+            if (!path.isAbsolute(pathAlias)) {
+                pathAlias = resolvePath(rootDir, pathAlias);
+            }
+
+            if (!alias.endsWith("/")) alias += "/";
+            if (!pathAlias.endsWith("/")) pathAlias += "/";
+
+            declaredAliases[alias] = pathAlias;
+        }
+    }
+
+    return gCache_getPathAliasInfo = {rootDir, alias: declaredAliases};
+}

package/src/@loader-tools/transform.ts

@@ -0,0 +1,138 @@
+import cssModuleCompiler from "./cssModuleCompiler.ts";
+import {supportedExtensionToType} from "./rules.ts";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import * as jk_fs from "jopi-toolkit/jk_fs";
+import {getPackageJsonConfig, INLINE_MAX_SIZE_KO} from "./config.ts";
+import {getVirtualUrlForFile} from "./virtualUrl.ts";
+
+export interface TransformResult {
+    text: string;
+    type: "js"|"text"
+}
+
+export async function transformFile(filePath: string, options: string): Promise<TransformResult> {
+    let text: string;
+
+    if (filePath.endsWith(".json")) {
+        // .json must be ignored with bun.js since some libraries use require and not import.
+        // The matter is that the generated code can't be compatible with import and require
+        // at the same time.
+        //
+        // Moreover, bun.js natif implementation seems way faster.
+        //
+        text = await transform_json(filePath);
+    }
+    else if (options=="raw") {
+        text = await transform_raw(filePath);
+    }
+    else if (options==="inline") {
+        text = await transform_inline(filePath);
+    }
+    else if (filePath.endsWith(".module.css") || (filePath.endsWith(".module.scss"))) {
+        text = await transform_cssModule(filePath);
+    }
+    else if (filePath.endsWith(".css") || (filePath.endsWith(".scss"))) {
+        text = await transform_css(filePath);
+    }
+    else {
+        text = await transform_filePath(filePath);
+    }
+
+    return {text, type: "js"};
+}
+
+async function transform_cssModule(sourceFilePath: string) {
+    return await cssModuleCompiler(sourceFilePath);
+}
+
+/**
+ * Allow getting the file path of the CSS.
+ * Here we mimic Bun.js behaviors.
+ *
+ * To know: Bun.js doesn't allow catching .css file anymore.
+ *          It's why here we are node.js only.
+ */
+async function transform_css(sourceFilePath: string) {
+    sourceFilePath = jk_fs.resolve(sourceFilePath);
+    return `export default ${JSON.stringify(sourceFilePath)};`;
+}
+
+async function transform_filePath(sourceFilePath: string) {
+    let virtualUrl = getVirtualUrlForFile(sourceFilePath);
+
+    if (!virtualUrl?.url) {
+        return `const __PATH__ = ${JSON.stringify(virtualUrl?.sourceFile)}; export default __PATH__;`
+    }
+
+    if (process.env.JOPI_BUNLDER_ESBUILD) {
+        return `const __URL__ = ${JSON.stringify(virtualUrl.url)}; export default __URL__;`
+    }
+
+    return `const __URL__ = ${JSON.stringify(virtualUrl.url)};
+if (typeof(global)!=="undefined") {
+    if (global.jopiAddVirtualUrl) global.jopiAddVirtualUrl(${JSON.stringify(virtualUrl)}, false);
+} else {
+    if (window.jopiAddVirtualUrl) window.jopiAddVirtualUrl(${JSON.stringify(virtualUrl)}, false);
+}
+export default __URL__;`
+}
+
+async function transform_json(filePath: string) {
+    const resText = await jk_fs.readTextFromFile(filePath);
+    return `export default ${resText};`;
+}
+
+async function transform_raw(filePath: string) {
+    let ext = path.extname(filePath);
+    let type = supportedExtensionToType[ext];
+    if (!type) type = "text";
+
+    let resText: string;
+
+    if ((type==="text")||(type==="css")) {
+        resText = await jk_fs.readTextFromFile(filePath);
+    } else {
+        const buffer: Buffer = await fs.readFile(filePath);
+
+        // Here there is no the prefix "data:image/jpeg;base64".
+        // It's the difference with the "?inline" option.
+        //
+        resText = buffer.toString('base64');
+    }
+
+    return `export default  ${JSON.stringify(resText)};`
+}
+
+async function transform_inline(filePath: string) {
+    let ext = path.extname(filePath);
+    let type = supportedExtensionToType[ext];
+    if (!type) type = "text";
+
+    let resText: string;
+
+    if ((type==="text")||(type==="css")) {
+        resText = await jk_fs.readTextFromFile(filePath);
+    } else {
+        const config = getPackageJsonConfig();
+        let maxSize = config ? config.inlineMaxSize_ko : INLINE_MAX_SIZE_KO;
+
+        let fileSize = Math.trunc(await jk_fs.getFileSize(filePath) / 1024);
+
+        if (fileSize > maxSize) {
+            return transform_filePath(filePath);
+        }
+
+        const buffer: Buffer = await fs.readFile(filePath);
+        const mimeType = jk_fs.getMimeTypeFromName(filePath);
+
+        // Here there is no the prefix "data:image/jpeg;base64".
+        // It's the difference with the "?inline" option.
+        //
+        resText = buffer.toString('base64');
+        resText = `data:${mimeType};base64,${resText}`;
+    }
+
+    return `export default ${JSON.stringify(resText)};`
+}

package/src/@loader-tools/virtualUrl.ts

@@ -0,0 +1,57 @@
+import {getPackageJsonConfig} from "./config.js";
+import path from "node:path";
+import * as jk_events from "jopi-toolkit/jk_events";
+import * as jk_crypto from "jopi-toolkit/jk_crypto";
+
+export interface VirtualUrlEntry {
+    url: string;
+    route: string;
+    sourceFile: string;
+    bundleFile?: string;
+}
+
+const gVirtualUrlMap: VirtualUrlEntry[] = [];
+
+export function getVirtualUrlMap() {
+    return gVirtualUrlMap;
+}
+
+export function addVirtualUrlEntry(entry: VirtualUrlEntry) {
+    gVirtualUrlMap.push(entry);
+    jk_events.sendEvent("jopi.virtualUrl.added", entry);
+}
+
+export function getVirtualUrlForFile(filePath: string): VirtualUrlEntry|undefined {
+    // Avoid creating a second entry if already exist.
+    const existing = gVirtualUrlMap.find(e => e.sourceFile === filePath);
+    //
+    if (existing) {
+        return existing;
+    }
+
+    const config = getPackageJsonConfig();
+
+    let route = path.relative(process.cwd(), filePath);
+    route = config.webResourcesRoot_SSR + jk_crypto.md5(route) + path.extname(filePath);
+
+    const entry: VirtualUrlEntry = {
+        // Use an url relative to the url base path.
+        url: "/" + route,
+
+        route: "/" + route,
+        sourceFile: filePath
+    };
+
+    addVirtualUrlEntry(entry);
+    return entry;
+}
+
+// @ts-ignore
+global.jopiAddVirtualUrl = (e: VirtualUrlEntry) => {
+    addVirtualUrlEntry(e);
+}
+
+// @ts-ignore
+global.jopiAddVirtualUrlFor = (filePath: string) => {
+    getVirtualUrlForFile(filePath);
+}

package/src/@loader-types/README.md

@@ -0,0 +1,15 @@
+It contains type declaration for TypesScript `tsconfig.json` which allows support for custom imports.
+
+If you do `import imgUrl from "./myImage.png"` then TypeScript send an error (with node.js) because he don't know
+how to transform this import.
+
+To resolve that, add a `types` section into your `tsconfig.json`.
+
+**Sample**
+```json
+{
+  "compilerOptions": {
+    "types": ["jopijs/types"]
+  }
+}
+```

package/src/@loader-types/extensions.d.ts

@@ -0,0 +1,65 @@
+declare module "*.module.scss" {
+    const styles: {  readonly [className: string]: string; };
+    export default styles;
+}
+
+declare module "*.module.css" {
+    const styles: { readonly [className: string]: string; };
+    export default styles;
+}
+
+declare module "*.css" {const asString: string; export default asString;}
+declare module "*.css?inline" {const asString: string; export default asString;}
+declare module "*.css?raw" {const asString: string; export default asString;}
+
+declare module "*.scss" {const asString: string; export default asString;}
+declare module "*.scss?inline" {const asString: string; export default asString;}
+declare module "*.scss?raw" {const asString: string; export default asString;}
+
+declare module "*.png" {const asString: string; export default asString;}
+declare module "*.png?inline" {const asString: string; export default asString;}
+declare module "*.png?raw" {const asString: string; export default asString;}
+
+declare module "*.gif" {const asString: string; export default asString;}
+declare module "*.gif?inline" {const asString: string; export default asString;}
+declare module "*.gif?raw" {const asString: string; export default asString;}
+
+declare module "*.jpg" {const asString: string; export default asString;}
+declare module "*.jpg?inline" {const asString: string; export default asString;}
+declare module "*.jpg?raw" {const asString: string; export default asString;}
+
+declare module "*.jpeg" {const asString: string; export default asString;}
+declare module "*.jpeg?inline" {const asString: string; export default asString;}
+declare module "*.jpeg?raw" {const asString: string; export default asString;}
+
+declare module "*.webp" {const asString: string; export default asString;}
+declare module "*.webp?inline" {const asString: string; export default asString;}
+declare module "*.webp?raw" {const asString: string; export default asString;}
+
+declare module "*.avif" {const asString: string; export default asString;}
+declare module "*.avif?inline" {const asString: string; export default asString;}
+declare module "*.avif?raw" {const asString: string; export default asString;}
+
+declare module "*.ico" {const asString: string; export default asString;}
+declare module "*.ico?inline" {const asString: string; export default asString;}
+declare module "*.ico?raw" {const asString: string; export default asString;}
+
+declare module "*.woff" {const asString: string; export default asString;}
+declare module "*.woff?inline" {const asString: string; export default asString;}
+declare module "*.woff?raw" {const asString: string; export default asString;}
+
+declare module "*.woff2" {const asString: string; export default asString;}
+declare module "*.woff2?inline" {const asString: string; export default asString;}
+declare module "*.woff2?raw" {const asString: string; export default asString;}
+
+declare module "*.ttf" {const asString: string; export default asString;}
+declare module "*.ttf?inline" {const asString: string; export default asString;}
+declare module "*.ttf?raw" {const asString: string; export default asString;}
+
+declare module "*.txt" {const asString: string; export default asString;}
+declare module "*.txt?inline" {const asString: string; export default asString;}
+declare module "*.txt?raw" {const asString: string; export default asString;}
+
+declare module "*.json" {const asObject: any; export default asObject;}
+declare module "*.json?inline" {const asString: any; export default asString;}
+declare module "*.json?raw" {const asString: any; export default asString;}

package/src/@tool-jopinb/README.md

@@ -0,0 +1 @@
+It's the implementation for tools `jopin` and `jopib`.

package/src/@tool-jopinb/index.ts

@@ -0,0 +1,11 @@
+import {jopiLauncherTool} from "jopijs/loader-tools";
+
+const VERSION = "2.0.0";
+
+export function useEngine(engine: string) {
+    if (process.env.JOPI_LOG==="1") {
+        console.log("JopiN - Loader Version" + VERSION + " - engine=" + engine);
+    }
+
+    jopiLauncherTool(engine).then();
+}

package/src/@ui/README.md

@@ -0,0 +1,3 @@
+The core of jopijs. Here it's mainly the ui-side parts.
+
+This library only include minimal things related to core functionnalities.