apprun 3.35.0 → 3.36.0

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,12 @@ 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[];
+  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 +102,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,6 +126,12 @@ if (!app.start) {
     return component;
   };
 
+  app.once = app.once || ((name: string, fn: (...args: any[]) => void, options: any = {}) => {
+    app.on(name, fn, { ...options, once: true });
+  });
+
+  app.query = app.query || app.runAsync;
+
   const NOOP = _ => {/* Intentionally empty */ }
   // app.on('$', NOOP);
   app.on('debug', _ => NOOP);
@@ -114,7 +142,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,14 +150,17 @@ 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 && route(location.pathname);
         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);
@@ -144,12 +175,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 +193,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);
   }
 

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}`,

package/src/directive.ts

@@ -2,22 +2,38 @@
  * Component Directives Implementation
  * 
  * This file provides built-in directives for components:
- * 1. Event Binding
+ * 1. Event Binding ($on directives)
  *    - $on: Bind DOM events to component events
  *    - Supports event delegation and parameters
  *    - Handles function, string, and array event handlers
+ *    - Type-safe event target handling
  * 
- * 2. Two-way Data Binding
+ * 2. Two-way Data Binding ($bind directive)
  *    - $bind: Sync form elements with component state
- *    - Handles input types: text, checkbox, radio, select
- *    - Automatic value type conversion
+ *    - Handles input types: text, checkbox, radio, number, range
+ *    - Supports select (single/multiple) and textarea elements
+ *    - Automatic value type conversion for numbers
  *    - Support for complex property paths
  * 
  * 3. Custom Directives
- *    - Extensible directive system
+ *    - Extensible directive system via '$' events
  *    - Processes virtual DOM during rendering
  *    - Supports custom attribute directives
  * 
+ * Features:
+ * - Automatic state synchronization
+ * - Type conversion for form inputs
+ * - Event delegation support
+ * - Multiple event handler formats
+ * - Nested property binding
+ * - Custom directive extensibility
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Added null checks for event targets before type assertions
+ * - Proper typing for different HTML element types
+ * - Enhanced error handling for invalid event targets
+ * - Safer DOM element property access
+ *
  * Usage:
  * ```tsx
  * // Event binding
@@ -27,10 +43,14 @@
  * // Two-way binding
  * <input $bind="state.property" />
  * <select $bind="selected">...</select>
+ * 
+ * // Array handlers
+ * <button $onclick={['handler', param1, param2]}>Click</button>
  * ```
  */
 
 import app from './app';
+import { safeEventTarget } from './type-utils';
 
 const getStateValue = (component, name) => {
   return (name ? component['state'][name] : component['state']) || '';
@@ -72,34 +92,65 @@ const apply_directive = (key: string, props: {}, tag, component) => {
       switch (type) {
         case 'checkbox':
           props['checked'] = getStateValue(component, name);
-          props['onclick'] = e => setStateValue(component, name || e.target.name, e.target.checked);
+          props['onclick'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, target.checked);
+            }
+          };
           break;
         case 'radio':
           props['checked'] = getStateValue(component, name) === props['value'];
-          props['onclick'] = e => setStateValue(component, name || e.target.name, e.target.value);
+          props['onclick'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, target.value);
+            }
+          };
           break;
         case 'number':
         case 'range':
           props['value'] = getStateValue(component, name);
-          props['oninput'] = e => setStateValue(component, name || e.target.name, Number(e.target.value));
+          props['oninput'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, Number(target.value));
+            }
+          };
           break;
         default:
           props['value'] = getStateValue(component, name);
-          props['oninput'] = e => setStateValue(component, name || e.target.name, e.target.value);
+          props['oninput'] = e => {
+            const target = safeEventTarget<HTMLInputElement>(e);
+            if (target) {
+              setStateValue(component, name || target.name, target.value);
+            }
+          };
       }
     } else if (tag === 'select') {
       props['value'] = getStateValue(component, name);
       props['onchange'] = e => {
-        if (!e.target.multiple) { // multiple selection use $bind on option
-          setStateValue(component, name || e.target.name, e.target.value);
+        const target = safeEventTarget<HTMLSelectElement>(e);
+        if (target && !target.multiple) { // multiple selection use $bind on option
+          setStateValue(component, name || target.name, target.value);
         }
       }
     } else if (tag === 'option') {
       props['selected'] = getStateValue(component, name);
-      props['onclick'] = e => setStateValue(component, name || e.target.name, e.target.selected);
+      props['onclick'] = e => {
+        const target = safeEventTarget<HTMLOptionElement>(e);
+        if (target) {
+          setStateValue(component, name || (target as any).name, target.selected);
+        }
+      };
     } else if (tag === 'textarea') {
       props['innerHTML'] = getStateValue(component, name);
-      props['oninput'] = e => setStateValue(component, name || e.target.name, e.target.value);
+      props['oninput'] = e => {
+        const target = safeEventTarget<HTMLTextAreaElement>(e);
+        if (target) {
+          setStateValue(component, name || target.name, target.value);
+        }
+      };
     }
   } else {
     app.run('$', { key, tag, props, component });

package/src/router.ts

@@ -3,23 +3,41 @@
  * 
  * This file provides URL routing capabilities:
  * 1. Hash-based routing (#/path)
+ *    - Works with SPA mode using hash fragments
+ *    - Handles hashchange events automatically
+ *    - No server configuration required
  * 2. Path-based routing (/path) 
+ *    - Works with browser history API
+ *    - Requires server configuration for SPA routing
+ *    - Handles popstate events automatically
  * 3. Event-based navigation
+ *    - Routes trigger corresponding component events
+ *    - Automatic route parameter extraction
+ *    - Fallback to 404 handling for unknown routes
  * 
  * Features:
- * - Automatic route event firing
- * - 404 handling via ROUTER_404_EVENT
- * - History API integration
- * - Route parameter parsing
+ * - Automatic route event firing with ROUTER_EVENT
+ * - 404 handling via ROUTER_404_EVENT for unmatched routes
+ * - History API integration for seamless navigation
+ * - Route parameter parsing and injection into events
+ * - URL pattern matching with parameter support
+ * - Global and component-level route handling
+ *
+ * Type Safety Improvements (v3.35.1):
+ * - Enhanced route type definitions
+ * - Better parameter type inference
+ * - Improved URL validation and error handling
  * 
  * Usage:
  * ```ts
  * // Handle routes
  * app.on('#/home', () => // Show home page);
  * app.on('#/users/:id', (id) => // Show user profile);
+ * app.on('/api/*', (path) => // Handle API routes);
  * 
- * // Navigate programmatically
+ * // Navigate programmatically  
  * app.run('route', '#/home');
+ * route('/users/123'); // Direct routing
  * ```
  */
 

package/src/type-utils.ts

@@ -0,0 +1,130 @@
+/**
+ * Type Safety Utilities for AppRun
+ * 
+ * This file provides utility functions and types to improve type safety
+ * across the AppRun framework, including:
+ * 1. Safe type assertions with null checks
+ * 2. Global object assignment helpers
+ * 3. Event target type guards
+ * 4. Function validation utilities
+ */
+
+/**
+ * Safely cast event target to specific HTML element type with null check
+ */
+export function safeEventTarget<T extends HTMLElement = HTMLElement>(event: Event): T | null {
+  return event?.target instanceof HTMLElement ? event.target as T : null;
+}
+
+/**
+ * Type guard to check if an object is a valid function
+ */
+export function isFunction(obj: any): obj is Function {
+  return typeof obj === 'function';
+}
+
+/**
+ * Type guard to check if an object is a valid HTML element
+ */
+export function isHTMLElement(obj: any): obj is HTMLElement {
+  return obj instanceof HTMLElement;
+}
+
+/**
+ * Safely assign properties to global object with type checking
+ */
+export function safeGlobalAssign<T extends Record<string, any>>(
+  globalObj: any,
+  assignments: T
+): void {
+  if (typeof globalObj === 'object' && globalObj !== null) {
+    Object.keys(assignments).forEach(key => {
+      globalObj[key] = assignments[key];
+    });
+  }
+}
+
+/**
+ * Safely get property from global object with fallback
+ */
+export function safeGlobalGet<T>(
+  globalObj: any,
+  property: string,
+  fallback?: T
+): T | undefined {
+  if (typeof globalObj === 'object' && globalObj !== null) {
+    return globalObj[property] ?? fallback;
+  }
+  return fallback;
+}
+
+/**
+ * Type-safe wrapper for DOM element queries
+ */
+export function safeQuerySelector<T extends Element = Element>(
+  selector: string,
+  context: Document | Element = document
+): T | null {
+  try {
+    return context.querySelector<T>(selector);
+  } catch (error) {
+    console.warn(`Invalid selector: ${selector}`, error);
+    return null;
+  }
+}
+
+/**
+ * Type-safe wrapper for DOM element by ID
+ */
+export function safeGetElementById<T extends HTMLElement = HTMLElement>(
+  id: string
+): T | null {
+  try {
+    return document.getElementById(id) as T | null;
+  } catch (error) {
+    console.warn(`Error getting element by id: ${id}`, error);
+    return null;
+  }
+}
+
+/**
+ * Validate and safely execute a function with error handling
+ */
+export function safeExecute<T extends any[], R>(
+  fn: ((...args: T) => R) | undefined | null,
+  args: T,
+  context?: any,
+  errorMessage?: string
+): R | undefined {
+  if (!isFunction(fn)) {
+    if (errorMessage) {
+      console.warn(errorMessage, fn);
+    }
+    return undefined;
+  }
+
+  try {
+    return context ? fn.apply(context, args) : fn(...args);
+  } catch (error) {
+    console.error(errorMessage || 'Error executing function:', error);
+    return undefined;
+  }
+}
+
+/**
+ * Type definitions for improved global object safety
+ */
+export interface SafeGlobalWindow {
+  Component?: any;
+  _React?: any;
+  React?: any;
+  on?: any;
+  customElement?: any;
+  safeHTML?: any;
+  html?: any;
+  svg?: any;
+  run?: any;
+  [key: string]: any;
+}
+
+export type SafeGlobalContext = SafeGlobalWindow | typeof globalThis | any;