@xpell/core 2.0.0-alpha.10

package/dist/XObject.d.ts

@@ -0,0 +1,287 @@
+/**
+ * XObject — Core Runtime Object Model
+ *
+ * The foundational primitive of the Xpell runtime.
+ *
+ * `XObject` is the base class for objects managed by Xpell modules and provides:
+ * - Identity (`_id`) and typing (`_type`)
+ * - Tree composition (`_children` / `_parent`)
+ * - Lifecycle hooks (`onCreate`, `onMount`, `onFrame`, `onData`)
+ * - Event binding via `XEventManager` (`_on` / `_once`)
+ * - Nano-command execution (`run` / `execute`) powered by `XParser` + `XCommand`
+ * - Data-source integration (`_data_source`) and XData export (`toXData`)
+ *
+ * XObject is module-agnostic: UI (XUI), navigation (XVM), data (XDB), and transport
+ * layers build on top of it without changing its core contract.
+ *
+ * One-liner: XObject is the universal runtime node for Xpell.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @license MIT
+ * @copyright
+ * © 2022–present Aime Technologies. All rights reserved.
+ */
+import XCommand, { XCommandData } from "./XCommand";
+import { XEventListenerOptions } from "./XEventManager";
+import { XNanoCommandPack, XNanoCommand } from "./XNanoCommands";
+export type wordsList = {
+    [k: string]: string;
+};
+export type XValue = string | number | boolean | null | undefined | Function | XValue[] | {
+    [k: string]: XValue;
+};
+export interface IXData {
+    [k: string]: XValue;
+}
+export interface XDataXporterHandler {
+    (inst: any): any;
+}
+export type XDataInstanceXporter = {
+    cls: any;
+    handler: XDataXporterHandler;
+};
+export type XDataXporter = {
+    _ignore_fields: string[];
+    _instance_xporters: {
+        [id: string]: XDataInstanceXporter;
+    };
+};
+export type XObjectOnEventHandler = (xObject: XObject, data?: any) => void;
+export interface XObjectOnEventIndex {
+    [eventName: string]: XObjectOnEventHandler;
+}
+export type XObjectData = {
+    [k: string]: XValue;
+    _id?: string;
+    _type?: string;
+    _children?: Array<XObject | XObjectData>;
+    _name?: string;
+    _data_source?: string;
+    _on?: XObjectOnEventIndex;
+    _once?: XObjectOnEventIndex;
+    _on_create?: string | Function;
+    _on_mount?: string | Function;
+    _on_frame?: string | Function;
+    _on_data?: string | Function;
+    _process_frame?: boolean;
+    _process_data?: boolean;
+    _nano_commands?: XNanoCommandPack;
+    _debug?: boolean;
+};
+/**
+ * XObject class
+ * @class XObject
+ */
+export declare class XObject {
+    [k: string]: string | null | [] | undefined | Function | boolean | number | {} | null;
+    _id: string;
+    _type: string;
+    _children: Array<XObject | XObjectData>;
+    _parent: XObject | null;
+    _name?: string;
+    _data_source?: string;
+    _debug?: boolean;
+    _on: XObjectOnEventIndex;
+    _once: XObjectOnEventIndex;
+    _on_create?: string | Function | undefined;
+    _on_mount?: string | Function | undefined;
+    _on_frame?: string | Function | undefined;
+    _on_data?: string | Function | undefined;
+    _on_event?: string | Function | undefined;
+    _process_frame: boolean;
+    _process_data: boolean;
+    protected _xem_options: XEventListenerOptions;
+    protected _nano_commands: {
+        [k: string]: XNanoCommand;
+    };
+    protected _cache_cmd_txt?: string;
+    protected _cache_jcmd?: any;
+    protected _event_listeners_ids: {
+        [eventName: string]: string[];
+    };
+    protected _event_parsed: boolean;
+    protected _mounted: boolean;
+    protected _xporter: XDataXporter;
+    private _xd_unsub?;
+    private _xd_bound_key?;
+    /**
+     * XObject constructor is creating the object and adding all the data keys to the XObject instance
+     * @param data constructor input data (object)
+     * @param defaults - defaults to merge with data
+     * @param skipParse - skip data parsing
+     * if override this method make sure to call super.init(data,skipParse) and to set skipParse to true
+     */
+    constructor(data: XObjectData, defaults?: any, skipParse?: boolean);
+    log(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Initialize the XObject
+     * @param data - data to parse (XObjectData)
+     * @param skipParse - skip data parsing
+     * @deprecated - use parse method instead
+     */
+    init(data?: any, skipParse?: boolean): void;
+    parseEvents(options?: XEventListenerOptions): void;
+    addEventListener(eventName: string, handler: XObjectOnEventHandler | string, options?: XEventListenerOptions): void;
+    removeEventListener(eventName: string): void;
+    removeAllEventListeners(): void;
+    /**
+     * Append a child XObject to this XObject
+     * @param xobject
+     */
+    append(xobject: XObject): void;
+    /**
+     * Add single nano command to the object
+     * @param commandName - the nano command name
+     * @param nanoCommandFunction
+     */
+    addNanoCommand(commandName: string, nanoCommandFunction: XNanoCommand): void;
+    addNanoCommandPack(ncPack: XNanoCommandPack): void;
+    /**
+     * List of fields to ignore when exporting the xobject to XData or string format
+     * @param <string[]> ignoreFields - an array with all the fields to ignore
+     */
+    addXporterDataIgnoreFields(ignoreFields: string[]): void;
+    /**
+     * Add XData Xporter instance handler
+     * @param <XDataInstanceXporter> ie - the instance exporter object
+     */
+    addXporterInstanceXporter(classOfInstance: any, handler: XDataXporterHandler): void;
+    /**
+     * Parse data to the XObject
+     * @param data data to parse
+     * @param ignore - lis of words to ignore in the parse process
+     */
+    parse(data: XObjectData, ignore?: any): void;
+    /**
+     * Parse data to the XObject
+     * @param data data to parse
+     * @param {object} fields- object with fields and default values (IXData format)
+     *
+     * fields example = {
+     *  _name : "default-name",
+     * ...
+     * }
+     */
+    parseFieldsFromXDataObject(data: XObjectData, fields: {
+        [name: string]: any;
+    }): void;
+    /**
+     * Parse list of fields from IXObjectData to the class
+     * @param {IXObjectData} data -  the data
+     * @param {Array<string>} fields - array of field names (string)
+     * @param checkNonXParams - also check non Xpell fields (fields that not starting with "_" sign)
+     */
+    parseFields(data: XObjectData, fields: Array<string>, checkNonXParams?: boolean): void;
+    /**
+     * this method triggered after the HTML DOM object has been created and added to the parent element
+     * support external _on_create anonymous function in the , example:
+     * _on_create: async (xObject) => {
+     *      // xObject -> The XObject parent of the _on_create function, use instead of this keyword
+     *      // write code that will be executed each frame.
+     *      // make sure to write async anonymous function.
+     * }
+     *
+    */
+    onCreate(): Promise<void>;
+    protected checkAndRunInternalFunction(func: any, ...params: any): Promise<void>;
+    /**
+     * Triggers when the object is being mounted to other element
+     * support external _on_create anonymous function in the , example:
+     * _on_mount: async (xObject) => {
+     *      // xObject -> The XObject parent of the _on_mount function, use instead of this keyword
+     *      // write code that will be executed each frame.
+     *      // make sure to write async anonymous function.
+     * }
+     */
+    onMount(): Promise<void>;
+    emptyDataSource(): void;
+    /**
+     * Triggers when new data is being received from the data source
+     * @param data - the data
+     * if override this method make sure to call super.onData(data) to run the _on_data attribute
+     */
+    onData(data: any): Promise<void>;
+    /**
+     * Triggers from Xpell frame every frame
+     * Support _on_frame atrribute that can be XCommand string or function
+     * @param {number} frameNumber
+     *
+     * XObject supports
+     * 1. External _on_frame anonymous function in the , example:
+     * _on_frame: async (xObject,frameNumber) => {
+     *      // xObject -> The XObject parent of the _on_frame function, use instead of this keyword
+     *      // frameNumber = Xpell current frame number
+     *      // write code that will be executed each frame.
+     *      // make sure to write async anonymous function.
+     *      // be wise with the function execution and try to keep it in the 15ms running time to support 60 FPS
+     * }
+     *
+     * 2. String execution of nano commands
+     *
+     * _on_frame: "nano command text"
+     *
+     */
+    onFrame(frameNumber: number): Promise<void>;
+    /**
+     * Runs object nano commands
+     * @param nanoCommand - object nano command (string)
+     * @param cache - cache last command to prevent multiple parsing on the same command
+     */
+    run(nanoCommand: string, cache?: boolean): Promise<void>;
+    /**
+     * Execute XCommand within the XObject Nano Commands
+     * @param xCommand XCommand to execute
+     *
+     * Nano command example:
+     *
+     * "set-text" : (xCommand,xObject) => {
+     *      xObject.setText(xCommands.params.text)
+     * }
+     *
+     */
+    execute(xCommand: XCommand | XCommandData): Promise<void>;
+    /**
+     * Return an IXObjectData JSON representation of the XObject
+     * @returns IXObjectData
+     */
+    toXData(): IXData;
+    /**
+     * Return a string representation of the XObject
+     * @returns string
+     */
+    toString(): string;
+    clearAttributes(attributes: Array<string>): void;
+    bindDataSource(key?: string, opts?: {
+        initial?: boolean;
+    }): void;
+    unbindDataSource(): void;
+    /**
+     * Dispose the XObject and all its children
+     */
+    dispose(): Promise<void>;
+    /**
+     * Remove a child from the XObject )
+     * @param child - the child to
+     * @returns void
+        */
+    removeChild(child: XObject, dispose?: boolean): void;
+    /**
+     * @param child - the child to add
+     * @deprecated use append method instead
+     */
+    addChild(child: XObject): void;
+}
+/**
+ * ObjectPack class for multi object registration
+ */
+export declare class XObjectPack {
+    [k: string]: any;
+    /**
+     * Get all registered object in this ObjectPack
+     * @returns XObject dictionary
+     */
+    static getObjects(): object;
+}
+export default XObject;

package/dist/XObjectManager.d.ts

@@ -0,0 +1,96 @@
+/**
+ * XObjectManager — Module Object Registry
+ *
+ * Central manager for module-owned XObject instances.
+ *
+ * XObjectManager tracks and manages root XObjects created by Xpell modules.
+ * Child XObjects are considered part of their parent hierarchy and are
+ * not managed independently by the manager.
+ *
+ * XModules use XObjectManager to:
+ * - Register and resolve XObject classes by `_type`
+ * - Create new XObject instances from schemas or commands
+ * - Maintain deterministic ownership of module-level objects
+ *
+ * One-liner: XObjectManager governs the lifetime of module root objects.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @license MIT
+ * @copyright
+ * © 2022–present Aime Technologies. All rights reserved.
+ */
+import XObject, { XObjectPack } from "./XObject";
+export type XObjectManagerIndex = {
+    [name: string]: any;
+};
+export declare class XObjectManager {
+    #private;
+    constructor();
+    get _objects(): XObjectManagerIndex;
+    /**
+     * Checks if an object is found in the object manager
+     * @param xObjectId
+     * @returns
+     */
+    hasObject(xObjectId: string): boolean;
+    /**
+     * Register multiple classes dictionary into the object manager
+     * @param xObjects - key value list -> \{"view":XView,...\}
+     */
+    registerObjects(xObjects: XObjectPack): void;
+    /**
+     * Registers single XObject
+     * @param name - name of the object
+     * @param xObjects The object class
+     */
+    registerObject(name: string, xObjects: XObject): void;
+    /**
+     * Checks if a class (name) is found in the object manager classes dictionary
+     * @param name - class name
+     * @returns {boolean}
+     */
+    hasObjectClass(name: string): boolean;
+    /**
+     * Retrieves XObject class instance
+     * @param name class name
+     * @returns {XObject}
+     */
+    getObjectClass(name: string): any;
+    /**
+     * Retrieves all the classes dictionary
+     * @returns XObjectManagerIndex
+     */
+    getAllClasses(): XObjectManagerIndex;
+    get _classes(): XObjectManagerIndex;
+    /**
+     * Add XObject instance to the manager
+     * @param xObject XObject to maintain
+     */
+    addObject(xObject: XObject): void;
+    /**
+     * Remove XObject from the manager
+     * @param xObjectId object id to remove
+     */
+    removeObject(xObjectId: string): void;
+    /**
+     * Retrieves XObject instance
+     * @param xObjectId XObject id
+     * @returns {XObject}
+     */
+    getObject(xObjectId: string): XObject;
+    /**
+     * alias to getObject
+     * @param id
+     * @returns
+     */
+    go(id: string): XObject;
+    /**
+     * Retrieves XObject instance
+     * @param objectName XObject name
+     * @returns {XObject}
+     */
+    getObjectByName(objectName: string): XObject | null;
+}
+export default XObjectManager;

package/dist/XParams.d.ts

@@ -0,0 +1,60 @@
+/**
+ * XParams — Command Parameter Accessors
+ *
+ * Typed parameter helper for Xpell commands.
+ *
+ * XParams provides a safe, normalized way to read parameters
+ * from Xpell command-like objects (`XCmdLike`) using positional
+ * or named keys, with optional type coercion and defaults.
+ *
+ * It is designed to be used by:
+ * - Nano commands
+ * - XVM internal commands
+ * - Runtime command dispatchers
+ * - AI- or text-generated command inputs
+ *
+ * ---
+ *
+ * ## Responsibilities
+ *
+ * - Read parameters from `_params` safely
+ * - Provide typed accessors (`bool`, `int`, `json`, `str`)
+ * - Apply sane defaults and coercion rules
+ * - Support both positional and named parameters
+ *
+ * ---
+ *
+ * ## Design Notes
+ *
+ * - Parameter access is defensive and non-throwing
+ * - String inputs are normalized when possible
+ * - JSON parsing is best-effort and fail-safe
+ * - XParams does not mutate command objects
+ *
+ * ---
+ *
+ * XParams is a low-level utility and contains no
+ * domain-specific logic or side effects.
+ * XParams turns loose input into safe intent.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @license MIT
+ * @copyright
+ * © 2022–present Aime Technologies. All rights reserved.
+ */
+export type XCmdLike = {
+    _params?: Record<string, any>;
+} | {
+    getParam?: (pos: number, name: string, def: any) => any;
+    _params?: Record<string, any>;
+};
+export declare class XParams {
+    static get(cmd: any, key: string | number, def?: any): any;
+    static has(cmd: any, key: string | number): any;
+    static str(cmd: any, ...keys: (string | number)[]): string | undefined;
+    static bool(cmd: any, key: string | number, def?: boolean): boolean;
+    static int(cmd: any, key: string | number, def?: number): number;
+    static json<T = any>(cmd: any, key: string | number, def?: T): T | undefined;
+}

package/dist/XParser.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Xpell Parser
+ *
+ * Input parsing layer for the Xpell runtime.
+ *
+ * Responsible for converting external representations
+ * (XML, HTML, raw text, and JSON) into normalized
+ * Xpell commands and runtime instructions.
+ *
+ * ---
+ *
+ * ## Responsibilities
+ *
+ * - Parse XML, HTML, raw text, and JSON inputs
+ * - Normalize input into Xpell command structures
+ * - Validate and sanitize external input formats
+ * - Provide a unified entry point for declarative and textual inputs
+ *
+ * ---
+ *
+ * ## Architectural Role
+ *
+ * The parser is format-aware but runtime-agnostic.
+ * It does not execute commands or mutate state directly.
+ *
+ * Parsed output is consumed by:
+ * - XUI (UI creation)
+ * - XVM (navigation and flow)
+ * - XDB (data and entities)
+ *
+ * ---
+ *
+ * The parser defines the boundary between
+ * untrusted input and the Xpell runtime.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @license MIT
+ * @copyright © 2022–present Aime Technologies. All rights reserved.
+ */
+import XCommand from "./XCommand";
+export declare class XParser {
+    private static html2XMap;
+    /**
+     * Adds HTML-Xpell Mapping item
+     * @param htmlElement HTML element to change from
+     * @param xpellElement Xpell element to change to
+     */
+    static addHtml2XpellMapItem(htmlElement: string, xpellElement: string): void;
+    /**
+     * convert text command to Xpell json command
+     * @param {string} txt
+     */
+    static parse(txt: string, module?: string): XCommand;
+    static replaceSpacesInQuotes(inputString: string, replaceWith?: string): string;
+    static parseObjectCommand(command: string, module?: string): {
+        _module: string;
+        _object: string | undefined;
+        _op: string;
+        _params: any;
+    };
+    /**
+     * Converts XML/HTML string to XCommand
+     * @param xmlString XML string
+     * @returns
+     */
+    static xmlString2Xpell(xmlString: string): {};
+    /**
+     * Converts XML/HTML Document to Xpell JSON
+     * @param xmlNode XML Document Node
+     * @param forceXhtml force Xpell XHTML for every unknown object
+     * @returns {} Xpell JSON
+     */
+    static xml2Xpell(xmlNode: any, forceXhtml?: boolean): {};
+}
+export default XParser;

package/dist/XProtocol.d.ts

@@ -0,0 +1,56 @@
+/**
+ * XProtocol — Core Response Envelope (Pre-Wormholes v1)
+ *
+ * Defines the canonical, transport-agnostic response format used by Xpell
+ * runtimes and clients **before** Wormholes / streaming / routing layers.
+ *
+ * This protocol is:
+ * - Platform-neutral (no Node, DOM, or transport dependencies)
+ * - JSON-safe and serializable across process, thread, and network boundaries
+ * - Shared between server and client as a strict wire contract
+ *
+ * Design rules:
+ * - XResponseData is the FINAL response shape for v1
+ * - Errors are represented via XError.toXData() inside `_result`
+ * - Timing fields (`_ts`, `_pt`) are measured on the responder side
+ * - Clients must treat this object as immutable protocol data
+ *
+ * IMPORTANT:
+ * - Do NOT add transport concerns here (request IDs, peers, streams, auth)
+ * - Do NOT mutate XResponseData once sent
+ * - Wormholes and future protocols MUST wrap this envelope, not modify it
+ *
+ * @package xpell-core
+ * @version 2.0.0-alpha
+ * @author Tamir Fridman <DrXoom>
+ */
+export type XResponseData = {
+    _ok: boolean;
+    _ts: number;
+    _pt: number;
+    _result: any;
+};
+export declare class XResponse {
+    _ok: boolean;
+    _ts: number;
+    _pt: number;
+    _result: any;
+    constructor(data?: Partial<XResponseData>);
+    static create(data?: Partial<XResponseData>): XResponse;
+    static ok(result: any): XResponse;
+    static error(error: any): XResponse;
+    stopProcessTimeCounter(): void;
+    /**
+     * Convert to wire-safe object.
+     * NOTE: serialize == finalize timing
+     */
+    toXData(): XResponseData;
+    toString(): string;
+    setXData(data: Partial<XResponseData>): void;
+}
+export declare class XResponseError extends XResponse {
+    constructor(error: any);
+}
+export declare class XResponseOK extends XResponse {
+    constructor(result: any);
+}

package/dist/XUtils.d.ts

@@ -0,0 +1,100 @@
+/**
+ * XUtils — Xpell Utility Package
+ *
+ * Shared utility functions used across the Xpell runtime.
+ *
+ * Provides small, focused helpers that support core modules
+ * (XUI, XVM, XDB, Wormholes) without introducing cross-module
+ * dependencies or architectural coupling.
+ *
+ * ---
+ *
+ * ## Design Principles
+ *
+ * - Stateless and side-effect minimal
+ * - No runtime ownership or lifecycle management
+ * - Safe to use across client, server, and tooling
+ * - Free of UI, navigation, and data-layer assumptions
+ *
+ * ---
+ *
+ * XUtils exists to reduce duplication while keeping the core
+ * architecture clean and modular.
+ *
+ * @packageDocumentation
+ * @since 2022-07-22
+ * @author Tamir Fridman
+ * @copyright © 2022–present Aime Technologies. All rights reserved.
+ * @license MIT
+ */
+export type XFrameScheduler = (cb: () => void) => void;
+export declare const TWO_PI: number;
+export declare class _XUtils {
+    /**
+     * Create ignore list for parser to ignore spell words
+     * @param list - comma-separated list of words
+     * @param reservedWords - base reserved words map (mutated)
+     */
+    createIgnoreList(list: string, reservedWords: Record<string, any>): Record<string, any>;
+    /**
+     * GUID / UUID v4 (cross-platform)
+     *
+     * Preference order:
+     * 1) globalThis.crypto.randomUUID()
+     * 2) globalThis.crypto.getRandomValues() (RFC4122 v4)
+     * 3) Math.random() fallback (NOT crypto-secure, legacy fallback only)
+     */
+    guid(): string;
+    /**
+     * Merge defaults into data object (mutates data)
+     * @param data - target data
+     * @param defaults - defaults object
+     * @param force - overwrite existing values
+     */
+    mergeDefaultsWithData(data: any, defaults: any, force?: boolean): any;
+    /**
+     * Encode string to Base64 (UTF-8 safe, cross-platform)
+     */
+    encode(str: string): string;
+    /**
+     * Decode Base64 string to UTF-8 (cross-platform)
+     */
+    decode(str: string): string;
+    /**
+     * Returns a random integer between min and max (inclusive)
+     * NOTE: Not cryptographically secure (OK for UI, NOT for IDs)
+     */
+    getRandomInt(min: number, max: number): number;
+    /**
+     * Extract parameter from XCommand
+     */
+    getParam(xcmd: any, paramName: string, defaultValue?: any): any;
+    /**
+     * Default frame scheduler (cross-platform)
+     * - Browser: requestAnimationFrame
+     * - Node / non-DOM: setImmediate (fast) or setTimeout (paced by target fps)
+     */
+    createDefaultScheduler(_target_fps?: number): XFrameScheduler;
+}
+declare const XUtils: _XUtils;
+declare const _xu: _XUtils;
+export { XUtils, _xu };
+export default XUtils;
+/**
+ * FPS Calculator (cross-platform + stable)
+ *
+ * - Works in browser + node (performance.now() else Date.now()).
+ * - Smooths frame time via EMA (ms/frame).
+ * - Deadband prevents 119↔120 flicker.
+ *
+ * Notes:
+ * - If your engine runs at 1 FPS on node, this will naturally converge to ~1.
+ * - This is O(1) work per frame (a few ops) and will not affect frame rate.
+ */
+export declare class FPSCalc {
+    #private;
+    constructor(alpha?: number, deadband?: number);
+    private now;
+    calc(): number;
+    reset(): void;
+}