apprun 3.35.0 → 3.36.1

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "apprun",
-  "version": "3.35.0",
+  "version": "3.36.1",
   "description": "JavaScript library that has Elm inspired architecture, event pub-sub and components",
   "main": "dist/apprun.js",
   "module": "esm/apprun.js",
   "types": "apprun.d.ts",
   "bin": {
-    "apprun": "apprun-cli.js"
+    "apprun": "cli/index.js"
   },
   "scripts": {
     "build": "tsc -p src && rollup -c && webpack --mode production",
-    "test": "jest --watch",
-    "jest": "jest",
+    "test": "jest",
+    "jest": "jest --watch",
     "jest:debug": "node --inspect node_modules/.bin/jest --runInBand",
     "start": "webpack serve --mode development",
     "build:docs": "marked -i README.md -o demo/home.html & marked -i WHATSNEW.md -o demo/new.html",
@@ -53,10 +53,10 @@
     "typescript": "^5.7.2",
     "webpack": "^5.97.1",
     "webpack-cli": "^6.0.1",
-    "webpack-dev-server": "^5.2.0"
+    "webpack-dev-server": "^5.2.0",
+    "property-information": "^7.1.0"
   },
   "dependencies": {
-    "commander": "^14.0.0",
-    "js-yaml": "^4.1.0"
+    "commander": "^14.0.0"
   }
 }

package/src/app.ts

@@ -3,16 +3,30 @@
  *
  * This file provides:
  * 1. App class - The core event system implementation with pub/sub capabilities
- *    - on(): Subscribe to events
- *    - off(): Unsubscribe from events
- *    - run(): Publish events synchronously
- *    - runAsync(): Publish events asynchronously
- *    - query(): Alias for runAsync
+ *    - on(): Subscribe to events with options (once, delay, global)
+ *    - off(): Unsubscribe from events with proper cleanup
+ *    - run(): Publish events synchronously with error handling
+ *    - runAsync(): Publish events asynchronously with Promise support, returns handler values
+ *    - query(): Deprecated alias for runAsync() - use runAsync() instead
  *
  * 2. Default app singleton - Global event bus instance
  *    - Created once and reused across the application
- *    - Stored in global scope (window/global)
- *    - Version tracked to prevent duplicate instances
+ *    - Stored in global scope (window/global) with version tracking
+ *    - Prevents duplicate instances across different versions
+ *
+ * Features:
+ * - Event wildcards support (events ending with '*')
+ * - Delayed event execution with timeout management
+ * - Once-only event subscriptions
+ * - Async event handling with Promise.all
+ * - Global event bus shared across components
+ * - Memory leak prevention with proper cleanup
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Added validation for event handler functions
+ * - Enhanced error handling in event execution
+ * - Improved null checks in delayed event handling
+ * - Better error reporting for invalid handlers
  *
  * Usage:
  * ```ts
@@ -21,12 +35,18 @@
  *   // Handle event
  * });
  *
- * // Publish events
+ * // Publish events (fire-and-forget)
  * app.run('event-name', ...args);
+ * 
+ * // Get return values from event handlers
+ * app.runAsync('event-name', data).then(results => {
+ *   // Handle results array
+ * });
  * ```
  */
 
 import { EventOptions } from './types'
+import { APPRUN_VERSION_GLOBAL } from './version'
 
 export class App {
 
@@ -42,6 +62,7 @@ export class App {
   public use_render: any;
   public use_react: any;
   public route: any;
+  public basePath: string; // Base path for sub-directory deployments
 
   public version: string;
 
@@ -69,10 +90,18 @@ export class App {
     console.assert(subscribers && subscribers.length > 0, 'No subscriber for event: ' + name);
     subscribers.forEach((sub) => {
       const { fn, options } = sub;
+      if (!fn || typeof fn !== 'function') {
+        console.error(`AppRun event handler for '${name}' is not a function:`, fn);
+        return false;
+      }
       if (options.delay) {
         this.delay(name, fn, args, options);
       } else {
-        Object.keys(options).length > 0 ? fn.apply(this, [...args, options]) : fn.apply(this, args);
+        try {
+          Object.keys(options).length > 0 ? fn.apply(this, [...args, options]) : fn.apply(this, args);
+        } catch (error) {
+          console.error(`Error in event handler for '${name}':`, error);
+        }
       }
       return !sub.options.once;
     });
@@ -88,7 +117,11 @@ export class App {
     if (options._t) clearTimeout(options._t);
     options._t = setTimeout(() => {
       clearTimeout(options._t);
-      Object.keys(options).length > 0 ? fn.apply(this, [...args, options]) : fn.apply(this, args);
+      try {
+        Object.keys(options).length > 0 ? fn.apply(this, [...args, options]) : fn.apply(this, args);
+      } catch (error) {
+        console.error(`Error in delayed event handler for '${name}':`, error);
+      }
     }, options.delay);
   }
 
@@ -97,12 +130,25 @@ export class App {
     console.assert(subscribers && subscribers.length > 0, 'No subscriber for event: ' + name);
     const promises = subscribers.map(sub => {
       const { fn, options } = sub;
-      return Object.keys(options).length > 0 ? fn.apply(this, [...args, options]) : fn.apply(this, args);
+      if (!fn || typeof fn !== 'function') {
+        console.error(`AppRun async event handler for '${name}' is not a function:`, fn);
+        return Promise.resolve(null);
+      }
+      try {
+        return Object.keys(options).length > 0 ? fn.apply(this, [...args, options]) : fn.apply(this, args);
+      } catch (error) {
+        console.error(`Error in async event handler for '${name}':`, error);
+        return Promise.reject(error);
+      }
     });
     return Promise.all(promises);
   }
 
+  /**
+   * @deprecated Use runAsync() instead. app.query() will be removed in a future version.
+   */
   query(name: string, ...args: any[]): Promise<any[]> {
+    console.warn('app.query() is deprecated. Use app.runAsync() instead.');
     return this.runAsync(name, ...args);
   }
 
@@ -125,7 +171,7 @@ export class App {
   }
 }
 
-const AppRunVersions = 'AppRun-3.3.11';
+const AppRunVersions = APPRUN_VERSION_GLOBAL;
 let _app: App;
 const root = (typeof window !== 'undefined' ? window :
   typeof global !== 'undefined' ? global :

package/src/apprun-dev-tools.tsx

@@ -1,12 +1,6 @@
 import app from './app';
 import toHTML from './vdom-to-html';
 import { _createEventTests, _createStateTests } from './apprun-dev-tools-tests';
-import yaml from 'js-yaml';
-
-function replacer(key, value) {
-  if (typeof value === 'function') return value.toString(); // value.toString();
-  return ['', null].includes(value) || (typeof value === 'object' && (value.length === 0 || Object.keys(value).length === 0)) ? undefined : value;
-}
 
 function createProxy(obj) {
   const handler = {
@@ -109,7 +103,7 @@ const viewComponents = state => {
 
       return <li>
         <div>{component.constructor.name}</div>
-        <div><pre>{htmlEncode(yaml.dump(component_def, { replacer }))}</pre></div>
+        <div><pre>{htmlEncode(JSON.stringify(component_def, null, 2))}</pre></div>
         <br />
       </li>;
 

package/src/apprun-html.ts

@@ -1,4 +1,5 @@
 import app from './apprun'
+import { safeGlobalAssign, SafeGlobalContext } from './type-utils';
 export {
   app, Component, View, Action, Update, on, update, event, EventOptions,
   customElement, CustomElementOptions,
@@ -14,8 +15,11 @@ app.Fragment = Fragment;
 export default app;
 
 if (typeof window === 'object') {
-  window['React'] = window['_React'] || app;
-  window['html'] = html;
-  window['svg'] = svg;
-  window['run'] = run;
+  const globalWindow = window as SafeGlobalContext;
+  safeGlobalAssign(globalWindow, {
+    'React': globalWindow['_React'] || app,
+    'html': html,
+    'svg': svg,
+    'run': run
+  });
 }

package/src/apprun.ts

@@ -7,8 +7,9 @@
  * 3. Initializes global app instance with:
  *    - Virtual DOM rendering
  *    - Component system
- *    - Router
+ *    - Router with improved null safety
  *    - Web component support
+ *    - Type-safe React integration
  *
  * Key exports:
  * - app: Global event system instance
@@ -17,6 +18,22 @@
  * - Router events and configuration
  * - Web component registration
  *
+ * Features:
+ * - Event-driven architecture with pub/sub pattern
+ * - Virtual DOM rendering with multiple renderer support
+ * - Component lifecycle management
+ * - Client-side routing with hash/path support
+ * - Web Components integration
+ * - React compatibility layer
+ * - TypeScript support with strong typing
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Added null checks for DOM event targets
+ * - Improved global window object assignments with proper typing
+ * - Enhanced React integration parameter validation
+ * - Better error handling for invalid event handlers
+ * - Safer element access with proper type assertions
+ *
  * Usage:
  * ```ts
  * import { app, Component } from 'apprun';
@@ -39,6 +56,7 @@ import { VNode, View, Action, Update, EventOptions, ActionOptions, MountOptions,
 import { on, update, customElement } from './decorator';
 import webComponent, { CustomElementOptions } from './web-component';
 import { Route, route, ROUTER_EVENT, ROUTER_404_EVENT } from './router';
+import { APPRUN_VERSION } from './version';
 
 export type StatelessComponent<T = {}> = (args: T) => string | VNode | void;
 type OnDecorator = {
@@ -70,9 +88,13 @@ export interface IApp {
   start<T, E = any>(element?: Element | string, model?: T, view?: View<T>, update?: Update<T, E>,
     options?: AppStartOptions<T>): Component<T, E>;
   on(name: string, fn: (...args: any[]) => void, options?: any): void;
+  once(name: string, fn: (...args: any[]) => void, options?: any): void;
   off(name: string, fn: (...args: any[]) => void): void;
   run(name: string, ...args: any[]): number;
   find(name: string): any | any[];
+  /** @deprecated Use runAsync() instead. query() will be removed in a future version. */
+  query(name: string, ...args: any[]): Promise<any[]>;
+  runAsync(name: string, ...args: any[]): Promise<any[]>;
   h(tag: string | Function, props, ...children): VNode | VNode[];
   createElement(tag: string | Function, props, ...children): VNode | VNode[];
   render(element: Element | string, node: VNode): void;
@@ -81,12 +103,13 @@ export interface IApp {
   webComponent(name: string, componentClass, options?: CustomElementOptions): void;
   safeHTML(html: string): any[];
   use_render(render, mode?: 0 | 1);
-  use_react(createRoot);
+  use_react(React, ReactDOM);
+  version: string;
 }
 
 if (!app.start) {
 
-  app.version = '3.35.0';
+  app.version = APPRUN_VERSION;
 
   app.h = app.createElement = createElement;
   app.render = render;
@@ -104,8 +127,15 @@ if (!app.start) {
     return component;
   };
 
+  app.once = app.once || ((name: string, fn: (...args: any[]) => void, options: any = {}) => {
+    app.on(name, fn, { ...options, once: true });
+  });
+
+  // Deprecated: app.query is deprecated in favor of app.runAsync
+  app.query = app.query || app.runAsync;
+
   const NOOP = _ => {/* Intentionally empty */ }
-  // app.on('$', NOOP);
+  app.on('/', NOOP);
   app.on('debug', _ => NOOP);
   app.on(ROUTER_EVENT, NOOP);
   app.on(ROUTER_404_EVENT, NOOP);
@@ -114,7 +144,7 @@ if (!app.start) {
 
   if (typeof document === 'object') {
     document.addEventListener("DOMContentLoaded", () => {
-      const init_load = document.body.hasAttribute('apprun-no-init') || app['no-init-route'] || false;
+      const no_init_route = document.body.hasAttribute('apprun-no-init') || app['no-init-route'] || false;
       const use_hash = app.find('#') || app.find('#/') || false;
 
       // console.log(`AppRun ${app.version} started with ${use_hash ? 'hash' : 'path'} routing. Initial load: ${init_load ? 'disabled' : 'enabled'}.`);
@@ -122,17 +152,36 @@ if (!app.start) {
       window.addEventListener('popstate', () => route(location.pathname));
 
       if (use_hash) {
-        init_load && route(location.hash);
+        !no_init_route && route(location.hash);
       } else {
-        init_load && route(location.pathname);
+        !no_init_route && (() => {
+          const basePath = app.basePath || '';
+          let initialPath = location.pathname;
+
+          // Strip base path if present
+          if (basePath && initialPath.startsWith(basePath)) {
+            initialPath = initialPath.substring(basePath.length);
+            if (!initialPath.startsWith('/')) initialPath = '/' + initialPath;
+          }
+
+          route(initialPath);
+        })();
         document.body.addEventListener('click', e => {
           const element = e.target as HTMLElement;
+          if (!element) return;
+
           const menu = (element.tagName === 'A' ? element : element.closest('a')) as HTMLAnchorElement;
           if (menu &&
-            menu.origin === location.origin) {
+            menu.origin === location.origin &&
+            menu.pathname) {
             e.preventDefault();
-            history.pushState(null, '', menu.pathname);
-            route(menu.pathname);
+
+            // Handle base path for navigation
+            const basePath = app.basePath || '';
+            const fullPath = basePath + menu.pathname;
+
+            history.pushState(null, '', fullPath);
+            route(menu.pathname); // Route with relative path (without base path)
           }
         });
       }
@@ -144,12 +193,13 @@ if (!app.start) {
   };
 
   if (typeof window === 'object') {
-    window['Component'] = Component as ComponentType;
-    window['_React'] = window['React'];
-    window['React'] = app;
-    window['on'] = on as OnDecorator;
-    window['customElement'] = customElement;
-    window['safeHTML'] = safeHTML;
+    const globalWindow = window as any;
+    globalWindow['Component'] = Component as ComponentType;
+    globalWindow['_React'] = globalWindow['React'];
+    globalWindow['React'] = app;
+    globalWindow['on'] = on as OnDecorator;
+    globalWindow['customElement'] = customElement;
+    globalWindow['safeHTML'] = safeHTML;
   }
 
   app.use_render = (render, mode = 0) => {
@@ -161,15 +211,42 @@ if (!app.start) {
   };
 
   app.use_react = (React, ReactDOM) => {
+    if (!React || !ReactDOM) {
+      console.error('AppRun use_react: React and ReactDOM parameters are required');
+      return;
+    }
+
+    if (typeof React.createElement !== 'function') {
+      console.error('AppRun use_react: Invalid React object - createElement method not found');
+      return;
+    }
+
+    if (!React.Fragment) {
+      console.error('AppRun use_react: Invalid React object - Fragment not found');
+      return;
+    }
+
     app.h = app.createElement = React.createElement;
     app.Fragment = React.Fragment;
-    app.render = (el, vdom) => ReactDOM.render(vdom, el);
+
+    // React 18+ uses createRoot API
     if (React.version && React.version.startsWith('18')) {
+      if (!ReactDOM.createRoot || typeof ReactDOM.createRoot !== 'function') {
+        console.error('AppRun use_react: ReactDOM.createRoot not found in React 18+');
+        return;
+      }
       app.render = (el, vdom) => {
-        if (!el || !vdom) return;
-        if (!el._root) el._root = ReactDOM.createRoot(el);
-        el._root.render(vdom);
+        if (!el || vdom === undefined) return;
+        if (!(el as any)._root) (el as any)._root = ReactDOM.createRoot(el);
+        (el as any)._root.render(vdom);
+      }
+    } else {
+      // Legacy React versions
+      if (!ReactDOM.render || typeof ReactDOM.render !== 'function') {
+        console.error('AppRun use_react: ReactDOM.render not found in legacy React');
+        return;
       }
+      app.render = (el, vdom) => ReactDOM.render(vdom, el);
     }
   }
 }

package/src/component.ts

@@ -3,19 +3,38 @@
  *
  * This file provides the Component class which is the foundation for:
  * 1. State Management
- *    - Maintains component state
- *    - Handles state updates
- *    - Supports state history
+ *    - Maintains component state with history support
+ *    - Handles state updates with async/iterator support
+ *    - Supports state history navigation (prev/next)
+ *    - Promise and async iterator state handling
  *
  * 2. View Rendering
- *    - Renders virtual DOM to real DOM
+ *    - Renders virtual DOM to real DOM with directives
  *    - Handles component lifecycle (mounted, rendered, unload)
  *    - Supports shadow DOM and web components
+ *    - DOM change tracking with MutationObserver
+ *    - View transition API support
  *
  * 3. Event Handling
- *    - Local and global event subscription
+ *    - Local and global event subscription management
  *    - Event handler registration via decorators
- *    - Action to state updates
+ *    - Action to state updates with error handling
+ *    - Support for event options (delay, once, global)
+ *
+ * Features:
+ * - Component caching for debugging
+ * - Element tracking for cleanup
+ * - History navigation support
+ * - Global vs local event routing
+ * - Async state handling
+ * - Memory leak prevention
+ * - Component unmounting with cleanup
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Enhanced element access with null checks and warnings
+ * - Improved action validation and error handling
+ * - Better error reporting in component actions
+ * - Safer DOM element queries with fallback warnings
  *
  * Usage:
  * ```ts
@@ -36,6 +55,7 @@ import app, { App } from './app';
 import { Reflect } from './decorator'
 import { View, Update, ActionDef, ActionOptions, MountOptions, EventOptions } from './types';
 import directive from './directive';
+import { safeQuerySelector, safeGetElementById } from './type-utils';
 
 const componentCache = new Map();
 if (!app.find('get-components')) app.on('get-components', o => o.components = componentCache);
@@ -74,9 +94,12 @@ export class Component<T = any, E = any> {
     if (typeof document !== 'object') return;
 
     const el = (typeof this.element === 'string' && this.element) ?
-      document.getElementById(this.element) || document.querySelector(this.element) : this.element;
+      safeGetElementById(this.element) || safeQuerySelector(this.element) : this.element;
 
-    if (!el) return;
+    if (!el) {
+      console.warn(`Component element not found: ${this.element}`);
+      return;
+    }
     const tracking_attr = '_c';
     if (!this.unload) {
       el.removeAttribute && el.removeAttribute(tracking_attr);
@@ -236,7 +259,10 @@ export class Component<T = any, E = any> {
   }
 
   add_action(name: string, action, options: ActionOptions = {}) {
-    if (!action || typeof action !== 'function') return;
+    if (!action || typeof action !== 'function') {
+      console.warn(`Component action for '${name}' is not a valid function:`, action);
+      return;
+    }
     if (options.global) this._global_events.push(name);
     this.on(name as any, (...p) => {
 
@@ -248,18 +274,30 @@ export class Component<T = any, E = any> {
         options
       });
 
-      const newState = action(this.state, ...p);
-
-      app['debug'] && app.run('debug', {
-        component: this,
-        _: '<',
-        event: name, p,
-        newState,
-        state: this.state,
-        options
-      });
+      try {
+        const newState = action(this.state, ...p);
+
+        app['debug'] && app.run('debug', {
+          component: this,
+          _: '<',
+          event: name, p,
+          newState,
+          state: this.state,
+          options
+        });
 
-      this.setState(newState, options)
+        this.setState(newState, options);
+      } catch (error) {
+        console.error(`Error in component action '${name}':`, error);
+        app['debug'] && app.run('debug', {
+          component: this,
+          _: '!',
+          event: name, p,
+          error,
+          state: this.state,
+          options
+        });
+      }
     }, options);
   }
 
@@ -329,7 +367,11 @@ export class Component<T = any, E = any> {
   }
 
   // obsolete
+  /**
+   * @deprecated Use runAsync() instead. query() will be removed in a future version.
+   */
   public query(event: E, ...args) {
+    console.warn('component.query() is deprecated. Use component.runAsync() instead.');
     return this.runAsync(event, ...args);
   }
 

package/src/decorator.ts

@@ -5,30 +5,47 @@ import webComponent, { CustomElementOptions } from './web-component';
  * 
  * This file provides decorators that enable:
  * 1. Event Handler Registration
- *    - @on(): Subscribe to events with options
- *    - @update(): Define state updates with metadata
+ *    - @on(): Subscribe to events with options (global, once, delay)
+ *    - @update(): Define state updates with metadata and options
+ *    - Supports method and class decoration patterns
  * 
  * 2. Web Component Integration
  *    - @customElement(): Register as custom element with options
  *    - Handles shadow DOM and attribute observation
+ *    - Automatic lifecycle management for web components
  * 
  * 3. Metadata Management
  *    - Custom Reflect implementation for decorator metadata
- *    - Stores event handler and update metadata
+ *    - Stores event handler and update metadata for runtime use
  *    - Supports runtime reflection for dynamic behavior
+ *    - Metadata keys for event bindings and updates
  * 
+ * Features:
+ * - Event handler decoration with options
+ * - State update method decoration
+ * - Web component registration
+ * - Metadata-driven event binding
+ * - Flexible decorator patterns
+ * - Runtime metadata access
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Enhanced decorator typing for better IDE support
+ * - Improved metadata key management
+ * - Better type inference for decorated methods
+ *
  * Usage:
  * ```ts
  * @customElement('my-element')
  * class MyComponent extends Component {
- *   @on('event')  
+ *   @on('event', { global: true })  
  *   handler(state, ...args) {
  *     // Handle event
  *   }
  * 
- *   @update('event') 
+ *   @update('event', { render: true }) 
  *   updater(state, ...args) {
  *     // Update state
+ *     return newState;
  *   }
  * }
  * ```
@@ -55,7 +72,7 @@ export const Reflect = {
   }
 }
 
-export function update<E=string>(events?: E, options: any = {}) {
+export function update<E = string>(events?: E, options: any = {}) {
   return (target: any, key: string, descriptor: any) => {
     const name = events ? events.toString() : key;
     Reflect.defineMetadata(`apprun-update:${name}`,