@vandenberghinc/volt 1.1.26 → 1.1.28

package/frontend/tools/convert_to_jsdoc_tmp.js

@@ -0,0 +1,345 @@
+function convertToJSDoc(code) {
+    // Helper function to clean and format multi-line text
+    const formatMultilineText = (text, indent) => {
+        return text
+            .split('\n')
+            .map(l => l.replace(/^\s*\*\s?/, '').trim())
+            .filter(Boolean)
+            .join("\n" + indent + ' * ');
+    };
+
+    // Helper: convert old docstring to JSDoc format
+    const convertDocstring = (docstring, indent = '    ') => {
+        // Support @desc: or @description:
+        const titleMatch = docstring.match(/@title:\s*([^\n]*)/i);
+        const descMatch = docstring.match(/@(desc|descr|description):\s*([\s\S]+?)(?=@param:|@return:|@funcs:|\*\/)/i);
+
+
+        // Support @descr: or @description: inside @param:
+        const paramNameMatch = docstring.match(/@param:[\s\S]*?@name:\s*([^\n]*)/i);
+        const paramDescrMatch = docstring.match(/@param:[\s\S]*?@(desc|descr|description):\s*:?\s*([\s\S]+?)(?=@return:|@funcs:|\*\/)/i);
+
+        // Allow optional colon after @description and trim before @funcs or */ 
+        const returnDescMatch = docstring.match(/@return:[\s\S]*?@(desc|descr|description)\s*:?\s*([\s\S]+?)(?=@funcs:|\*\/)/i);
+
+        const lines = [];
+        lines.push(indent + '/**');
+
+        // Build summary from title + description if present
+        const title = titleMatch ? titleMatch[1].trim() : '';
+        const desc = descMatch ? formatMultilineText(descMatch[2].trim(), indent) : '';
+        if (!desc) {
+            throw new Error("No description found for docstring:\n" + fullDocstring);
+        }
+        lines.push(indent + ' * {' + title + "}");
+        lines.push(indent + ' * ' + desc);
+        // if (title || desc) {
+        //     const summary = [title, desc].filter(Boolean).join(' — ');
+        //     lines.push(indent + ' * ' + summary);
+        // }
+
+        if (paramNameMatch && paramDescrMatch) {
+            const cleanParamDescr = formatMultilineText(paramDescrMatch[2].trim(), indent);
+            lines.push(indent + ` * @param ${paramNameMatch[1].trim()} ${cleanParamDescr}`);
+        }
+
+        if (returnDescMatch) {
+            const cleanReturnDesc = formatMultilineText(returnDescMatch[2].trim(), indent);
+            lines.push(indent + ` * @returns ${cleanReturnDesc}`);
+        }
+
+        lines.push(indent + ' * @docs');
+        lines.push(indent + ' */');
+
+        return lines.join('\n');
+    };
+
+    // Split code into lines for easier processing
+    const lines = code.split('\n');
+    const result = [];
+    let i = 0;
+
+    while (i < lines.length) {
+        const line = lines[i];
+
+        // Check if this line starts a docstring
+        if (line.trim().startsWith('/**') && i + 1 < lines.length) {
+            // Find the end of the docstring
+            let docEnd = i;
+            let docContent = [line];
+
+            for (let j = i + 1; j < lines.length; j++) {
+                docContent.push(lines[j]);
+                if (lines[j].trim().endsWith('*/')) {
+                    docEnd = j;
+                    break;
+                }
+            }
+
+            const fullDocstring = docContent.join('\n');
+
+            // Check if it's an old-format docstring
+            if (fullDocstring.includes('@docs:')) {
+                // This is an old-format docstring that needs conversion
+
+                // Look ahead to find function signatures
+                let searchIdx = docEnd + 1;
+                let functionName = null;
+                let overloads = [];
+                let implementation = null;
+                let implLineIdx = -1;
+
+                while (searchIdx < lines.length) {
+                    const searchLine = lines[searchIdx].trim();
+
+                    if (searchLine === '') {
+                        searchIdx++;
+                        continue;
+                    }
+
+                    // Check if this looks like a function signature
+                    const funcMatch = searchLine.match(/^(\w+)\s*\([^)]*\)[^;{]*([;{])/);
+
+                    if (funcMatch) {
+                        const funcName = funcMatch[1];
+                        const isImpl = funcMatch[2] === '{' ||
+                            (searchIdx + 1 < lines.length && lines[searchIdx + 1].trim().startsWith('{'));
+
+                        if (!functionName) {
+                            functionName = funcName;
+                        }
+
+                        if (funcName === functionName) {
+                            if (!isImpl) {
+                                overloads.push({
+                                    line: searchLine,
+                                    lineIdx: searchIdx
+                                });
+                            } else {
+                                implementation = searchLine;
+                                implLineIdx = searchIdx;
+                                break;
+                            }
+                        } else {
+                            // Different function, stop
+                            break;
+                        }
+                    } else {
+                        // Not a function signature, stop
+                        break;
+                    }
+
+                    searchIdx++;
+                }
+
+                // Get the indent from the implementation line or first overload
+                let indent = '    ';
+                if (implLineIdx > -1) {
+                    const leadingSpace = lines[implLineIdx].match(/^(\s*)/);
+                    if (leadingSpace) {
+                        indent = leadingSpace[1];
+                    }
+                } else if (overloads.length > 0) {
+                    const leadingSpace = lines[overloads[0].lineIdx].match(/^(\s*)/);
+                    if (leadingSpace) {
+                        indent = leadingSpace[1];
+                    }
+                }
+
+                // Convert the docstring
+                const jsdoc = convertDocstring(fullDocstring, indent);
+
+                if (implLineIdx > -1 && overloads.length > 0) {
+                    // We have overloads and implementation - don't add docstring yet
+                    // Add the overloads without docstring
+                    for (const overload of overloads) {
+                        result.push(lines[overload.lineIdx]);
+                    }
+
+                    // Add the JSDoc before implementation
+                    result.push(jsdoc);
+                    result.push(lines[implLineIdx]);
+
+                    // Skip past all the lines we've processed
+                    i = implLineIdx + 1;
+                } else {
+                    // No overloads or no implementation - put JSDoc in place
+                    result.push(jsdoc);
+
+                    // Add any functions we found
+                    if (overloads.length > 0) {
+                        for (const overload of overloads) {
+                            result.push(lines[overload.lineIdx]);
+                        }
+                        i = overloads[overloads.length - 1].lineIdx + 1;
+                    } else if (implLineIdx > -1) {
+                        result.push(lines[implLineIdx]);
+                        i = implLineIdx + 1;
+                    } else {
+                        i = docEnd + 1;
+                    }
+                }
+            } else {
+                // Not an old-format docstring, keep as-is
+                for (const docLine of docContent) {
+                    result.push(docLine);
+                }
+                i = docEnd + 1;
+            }
+        } else {
+            // Not a docstring line, keep as-is
+            result.push(line);
+            i++;
+        }
+    }
+
+    const convertedCode = result.join('\n');
+
+    // Check for any remaining old-format patterns
+    const checkPatterns = [
+        /@docs:/g,
+        /@title:/g,
+        /@param:\s*\n\s*@name:/g,
+        /@return:\s*\n\s*@description/g,
+        /@funcs:/g
+    ];
+
+    let hasRemaining = false;
+    checkPatterns.forEach(pattern => {
+        if (pattern.test(convertedCode)) {
+            hasRemaining = true;
+        }
+    });
+
+    if (hasRemaining) {
+        console.log('⚠️ Some old-format patterns may remain in the converted code');
+    } else {
+        console.log('✅ All docstrings successfully converted!');
+    }
+
+    return convertedCode;
+}
+
+
+// Example usage
+const test_code = `
+    /**
+     * @docs:
+     * @title: On Suspend
+     * @desc: Script to be run when fetching the media data is stopped before it is completely loaded for whatever reason. The equivalent of HTML attribute \`onsuspend\`.
+     * @param:
+     *     @name: callback
+     *     @descr: The function to be executed when the suspend event occurs. The first parameter of the callback is the \`VElement\` object.
+     * @return:
+     *     @description Returns the \`VElement\` object. Unless parameter \`value\` is \`null\`, then the attribute's value is returned.
+     * @funcs: 2
+     */
+    on_suspend(): Function | undefined;
+    on_suspend(callback: Function): this;
+    on_suspend(callback?: Function): this | Function | undefined {
+        if (callback == null) { return this.onsuspend ?? undefined; }
+        const e = this;
+        this.onsuspend = (t) => callback(e, t);
+        return this;
+    }
+
+    /**
+     * @docs:
+     * @title: On Time Update
+     * @desc: Script to be run when the playing position has changed (like when the user fast forwards to a different point in the media). The equivalent of HTML attribute \`ontimeupdate\`.
+     * @param:
+     *     @name: callback
+     *     @descr: The callback function to execute when the time updates. The first parameter of the callback is the \`VElement\` object.
+     * @return:
+     *     @description Returns the \`VElement\` object. Unless parameter \`callback\` is \`null\`, then the attribute's value is returned.
+     * @funcs: 2
+     */
+    on_time_update(): Function | undefined;
+    on_time_update(callback: ElementEvent<this>): this;
+    on_time_update(callback?: ElementEvent<this>): this | Function | undefined {
+        if (callback == null) { return this.ontimeupdate ?? undefined; }
+        const e = this;
+        this.ontimeupdate = (t) => callback(e, t);
+        return this;
+    }
+
+    /**
+     * @docs:
+     * @title: On Volume Change
+     * @desc: Script to be run each time the volume is changed which includes setting the volume to "mute". 
+     *        The equivalent of HTML attribute \`onvolumechange\`. The first parameter of the callback is the \`VElement\` object.
+     * @param:
+     *     @name: callback
+     *     @descr: The callback function to execute on volume change.
+     * @return:
+     *     @description Returns the \`VElement\` object for chaining unless parameter \`value\` is \`null\`, then the attribute's value is returned.
+     * @funcs: 2
+     */
+    on_volume_change(): Function | undefined;
+    on_volume_change(callback: ElementEvent<this>): this;
+    on_volume_change(callback?: ElementEvent<this>): this | Function | undefined {
+        if (callback == null) { return this.onvolumechange ?? undefined; }
+        const e = this;
+        this.onvolumechange = (t) => callback(e, t);
+        return this;
+    }
+
+    /**
+     * @docs:
+     * @title: On Waiting
+     * @desc: Script to be run when the media has paused but is expected to resume (like when the media pauses to buffer more data). The equivalent of HTML attribute \`onwaiting\`.
+     * @param:
+     *     @name: callback
+     *     @descr: The callback function to execute when the media is waiting.
+     * @return:
+     *     @description Returns the \`VElement\` object unless parameter \`callback\` is \`null\`, then the attribute's value is returned.
+     * @funcs: 2
+     */
+    on_waiting(): Function | undefined;
+    on_waiting(callback: (element: this, time: any) => any): this;
+    on_waiting(callback?: (element: this, time: any) => any): this | Function | undefined {
+        if (callback == null) { return this.onwaiting ?? undefined; }
+        const e = this;
+        this.onwaiting = (t) => callback(e, t);
+        return this;
+    }
+
+    /**
+     * @docs:
+     * @title: On toggle
+     * @desc: Fires when the user opens or closes the \<details> element. 
+     *        The equivalent of HTML attribute \`ontoggle\`. 
+     *        The first parameter of the callback is the \`VElement\` object.
+     * @param:
+     *     @name: value
+     *     @descr: The value to assign. Leave \`null\` to retrieve the attribute's value.
+     * @return:
+     *     @description Returns the \`VElement\` object. Unless parameter \`value\` is \`null\`, then the attribute's value is returned.
+     * @funcs: 2
+     */
+    on_toggle() : Function | undefined;
+    on_toggle(callback: ElementEvent<this>): this;
+    on_toggle(callback?: ElementEvent<this>): this | Function | undefined {
+        if (callback == null) { return this.ontoggle ?? undefined; }
+        const e = this;
+        this.ontoggle = (t) => callback(e, t);
+        return this;
+    }
+
+
+`;
+
+// Convert the code
+// const convertedCode = convertToJSDoc(test_code);
+// console.log('\n📄 Converted Code:=======================\n'+convertedCode + "\n=====================");
+
+// From file.
+import { fileURLToPath } from 'url';
+import * as path from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+import * as vlib from "@vandenberghinc/vlib"
+
+const data = new vlib.Path(__dirname + "/convert_to_jsdoc_input.txt").load_sync();
+const converted = convertToJSDoc(data);
+new vlib.Path(__dirname + "/convert_to_jsdoc_output.txt").save_sync(converted);

package/package.json

@@ -1,7 +1,7 @@
 {
     "author": "Daan van den Bergh",
     "name": "@vandenberghinc/volt",
-    "version": "1.1.26",
+    "version": "1.1.28",
     "description": "",
     "type": "module",
     "types": "./backend/dist/esm/volt.d.ts",
@@ -9,24 +9,22 @@
     "module": "./backend/dist/esm/volt.js",
     "exports": {
         ".": {
-            "require": "./backend/dist/cjs/volt.js",
-            "import": "./backend/dist/esm/volt.js"
+            "require": "./backend/dist/cjs/backend/src/volt.js",
+            "import": "./backend/dist/esm/backend/src/volt.js"
         },
         "./frontend": {
-            "import": "./frontend/dist/volt.js"
+            "import": "./frontend/dist/frontend/src/volt.js"
         }
     },
     "scripts": {
         "link": "vrepo --npm --link --dependencies ../vlib/ts/,../vhighlight/",
         "unlink": "vrepo --npm --unlink",
-        "build": "npm run build:backend --silent && npm run add-backend-dist-files  && npm run build:backend:cjs --silent && npm run build:frontend --silent",
-        "build:backend": "tsc -p backend/tsconfig.json && npm run add-backend-dist-files",
+        "build": "npm run build:backend --silent && npm run build:backend:cjs --silent && npm run build:frontend --silent",
+        "build:backend": "tsc -p backend/tsconfig.json",
         "build:backend:cjs": "vts --transform-esm --debug 1 --src backend/dist/esm/ --dest backend/dist/cjs/ --override --platform node --target es2023",
         "build:frontend": "tsc -p frontend/tsconfig.json",
         "start": "node start.js",
-        "check-circular-dependencies": "npx madge --circular frontend/src/",
-        "add-backend-dist-files": "rsync -az --delete ./frontend/src/css/ ./backend/dist/css/",
-        "generate-docs": "libris --generate-docs"
+        "check-circular-dependencies": "npx madge --circular frontend/src/"
     },
     "publishConfig": {
         "access": "public"
@@ -36,12 +34,12 @@
         "volt-dev": "./backend/dist/esm-dev/cli.js"
     },
     "dependencies": {
-        "@vandenberghinc/vhighlight": "^1.3.14",
-        "@vandenberghinc/vlib": "^1.5.38",
+        "@vandenberghinc/vhighlight": "^1.3.15",
+        "@vandenberghinc/vlib": "^1.6.29",
         "@vandenberghinc/volt": "1.1.21",
         "blob-stream": "^0.1.3",
         "esbuild": "^0.25.4",
-        "mongodb": "^6.16.0",
+        "mongodb": "^6.19.0",
         "nodemailer": "^6.10.1",
         "pdfkit": "^0.14.0",
         "playwright": "^1.52.0",
@@ -49,6 +47,7 @@
     },
     "devDependencies": {
         "@types/node": "^22.15.21",
+        "@types/nodemailer": "^7.0.1",
         "typescript": "^5.8.3"
     },
     "vrepo_links": {

package/backend/dist/cjs/database/collection.d.ts

@@ -1,160 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2022 - 2025 Daan van den Bergh.
- */
-import { AggregationCursor, Collection as MongoCollection, Document as MongoDoc } from 'mongodb';
-import { Document } from "./document.js";
-import type { Database } from "./database.js";
-/** Index options. */
-interface BaseOptions {
-    options?: Record<string, any>;
-    forced?: boolean;
-}
-export type IndexOptions = (BaseOptions & {
-    key: string;
-    keys?: never;
-}) | (BaseOptions & {
-    key?: never;
-    keys: string[];
-});
-export type Query = string | Record<string, any>;
-/**
- * A wrapper class for the MongoDB collection.
- *
- * @note Any document type is suported, including primitives, arrays and objects.
- *
- * @example
- * const col1 = server.db.collection("col1");
- * const col2 = server.db.collection({
- *    name: "col2",
- *    indexes: ["uid", "name"],
- *    ttl: 1000 * 60 * 60 * 24, // 1 day
- * });
- */
-export declare class Collection<Data extends Document.Data = any> {
-    static chunk_size: number;
-    static constructor_scheme: {
-        name: string;
-        ttl: {
-            type: string;
-            default: null;
-        };
-        indexes: {
-            type: string;
-            default: never[];
-            value_scheme: {
-                type: string[];
-                scheme: {
-                    key: {
-                        type: string;
-                        required: (data: any) => boolean;
-                    };
-                    keys: {
-                        type: string[];
-                        required: (data: any) => boolean;
-                        value_scheme: string;
-                        postprocess: (keys: any) => any;
-                    };
-                    options: {
-                        type: string;
-                        required: boolean;
-                    };
-                    forced: {
-                        type: string;
-                        default: boolean;
-                    };
-                };
-                postprocess: (info: any) => any;
-            };
-        };
-    };
-    /** Collection name */
-    name: string;
-    /** Time to live in msec for all documents. */
-    ttl?: number;
-    ttl_enabled: boolean;
-    /** The column. */
-    _col?: MongoCollection;
-    /**
-     * The Database parent class, used to initialize the column on demand.
-     * So the user can define collections at root level before the database is initialized. */
-    db: Database;
-    /** Is initialized. */
-    initialized: boolean;
-    /** The temporary indexes passed to the constructor for the init method. */
-    private _init_indexes?;
-    /** Constructor. */
-    constructor(opts: {
-        name: string;
-        col?: MongoCollection;
-        ttl?: number;
-        indexes?: (string | IndexOptions)[];
-        db: Database;
-    });
-    /** Initialize. */
-    init(): Promise<this>;
-    assert_init(): asserts this is {
-        _col: MongoCollection;
-    };
-    /** Setup the ttl configuration. */
-    _setup_ttl(): Promise<void>;
-    private _process_doc;
-    private _load_chunked;
-    private _save_chunked;
-    col(): Promise<NonNullable<MongoCollection>>;
-    /** Create a reference. */
-    ref<Data extends Document.Data = any>(query: Query, opts?: Omit<ConstructorParameters<typeof Document.Ref<Data>>[1], "col">): Document.Ref<Data>;
-    reference<Data extends Document.Data = any>(query: Query, opts?: Omit<ConstructorParameters<typeof Document.Ref<Data>>[1], "col">): Document.Ref<Data>;
-    /** Has index. */
-    has_index(index: string): Promise<boolean>;
-    create_index(opts: string | IndexOptions): Promise<string>;
-    find(query: Record<string, any>): Promise<Data | undefined>;
-    find_many(query: Record<string, any>): Promise<Data[] | undefined>;
-    exists(path: Query): Promise<boolean>;
-    load(path: Query, opts?: {
-        default?: any;
-        chunked?: boolean;
-        attributes?: string[];
-        projection?: Record<string, any>;
-    } | null): Promise<Data | undefined>;
-    save(path: Query, content: any, opts?: {
-        chunked?: boolean;
-        bulk?: boolean;
-        set?: boolean;
-    } | null): Promise<any>;
-    /** Update many. */
-    update_many(...args: Parameters<typeof MongoCollection.prototype.updateMany>): Promise<any>;
-    list(path: Query, options?: {
-        process?: boolean;
-        projection?: Record<string, any>;
-    }): Promise<Data[]>;
-    list_query(query?: Record<string, any>, options?: {
-        process?: boolean;
-        projection?: Record<string, any>;
-    }): Promise<Data[]>;
-    list_all(query?: Record<string, any>, options?: {
-        process?: boolean;
-        projection?: Record<string, any>;
-    }): Promise<Data[]>;
-    delete(path: Query, opts?: {
-        chunked?: boolean;
-        bulk?: boolean;
-    }): Promise<any>;
-    delete_query(query?: Record<string, any>): Promise<void>;
-    delete_all(path: Query): Promise<void>;
-    delete_many(query: Record<string, any>): Promise<void>;
-    delete_collection(): Promise<void>;
-    clean<T extends Partial<Data> = Data>(doc: T): T | undefined;
-    /** Write bulk operations. */
-    bulk_operations(operations?: any[]): Promise<any>;
-    /** Aggregate */
-    aggregate<T extends Partial<Data> = Data>(pipeline: MongoDoc[], opts: {
-        cursor?: false;
-        clean?: boolean;
-    }): Promise<T[]>;
-    aggregate<T extends Partial<Data> = Data>(pipeline: MongoDoc[], opts?: {
-        cursor: true;
-        clean?: boolean;
-    }): Promise<AggregationCursor<T>>;
-}
-export {};