mancha 0.24.0 → 0.24.2

package/dist/interfaces-C8heJ6BZ.d.ts

@@ -1,452 +0,0 @@
-//#region src/store.d.ts
-/**
- * Internal store properties that are always present. These are managed by the framework
- * and should not be set directly by users.
- */
-type InternalStoreState = {
-  /** Reference to the parent store in a hierarchy. */
-  $parent?: SignalStore;
-  /** Reference to the root renderer instance. */
-  $rootRenderer?: SignalStore;
-  /** Reference to the root DOM node. */
-  $rootNode?: Node;
-} & {
-  [key: `$$${string}`]: string | null;
-};
-/**
- * Base type for user-defined store state. Uses `any` intentionally to allow flexible
- * user-defined state types without requiring explicit index signatures.
- */
-type StoreState = Record<string, any>;
-/** Type for expression evaluation function. */
-type EvalFunction = (thisArg: SignalStoreProxy, args: Record<string, unknown>) => unknown;
-/** Type for observer entries that include the store context for proper binding. */
-type ObserverEntry = {
-  observer: Observer<unknown>;
-  store: SignalStore;
-  computedKey?: string;
-};
-/**
- * Internal proxy type used within the store implementation. Uses `any` for dynamic property access.
- */
-type SignalStoreProxy = SignalStore & InternalStoreState & {
-  [key: string]: any;
-};
-/**
- * The reactive context type exposed to effects and computed functions.
- * Includes the store's typed state T, internal state, and an index signature for dynamic access.
- */
-type ReactiveContext<T extends StoreState = StoreState> = SignalStore<T> & InternalStoreState & T & Record<string, unknown>;
-type Observer<T> = (this: SignalStoreProxy) => T;
-type KeyValueHandler = (this: SignalStoreProxy, key: string, value: unknown) => void;
-/** Symbol used to identify computed value markers. */
-
-/** Function type for computed value definitions. Receives reactive context as `$` parameter. */
-type ComputedFn<T extends StoreState, R> = (this: ReactiveContext<T>, $: ReactiveContext<T>) => R;
-declare class SignalStore<T extends StoreState = StoreState> {
-  protected readonly evalkeys: string[];
-  protected readonly expressionCache: Map<string, EvalFunction>;
-  protected readonly observers: Map<string, Set<ObserverEntry>>;
-  protected readonly keyHandlers: Map<RegExp, Set<KeyValueHandler>>;
-  readonly _store: Map<string, unknown>;
-  _lock: Promise<void>;
-  /** Keys with a scheduled observer run. */
-  private readonly _pending;
-  /** Keys whose observers are running right now. */
-  private readonly _executing;
-  /** Keys written while their own observers were running, to notify afterwards. */
-  private readonly _dirty;
-  /**
-   * Stores created from this one, disposed along with it. A subrenderer is only reachable
-   * through the store that created it and the node it renders, so without this nothing ever
-   * disposes a nested `:for` row or a `:render` subrenderer.
-   */
-  protected readonly _children: Set<SignalStore<StoreState>>;
-  /** Per-key deep-mutation subscribers, kept stable so they can be unsubscribed later. */
-  private readonly _mutationCallbacks;
-  /** Set by dispose(). Observers registered by a disposed store must no longer run. */
-  protected _disposed: boolean;
-  /**
-   * Tracks nested computed evaluation depth. When > 0, we're inside a computed
-   * function and writes to reactive properties should trigger a warning.
-   */
-  private _computedDepth;
-  constructor(data?: T);
-  private wrapObject;
-  watch<T>(key: string, observer: Observer<T>): void;
-  addKeyHandler(pattern: RegExp, handler: KeyValueHandler): void;
-  /**
-   * Tags all observer entries matching the given observer function with a computed key.
-   * Called after effect runs to mark which observers belong to which computed.
-   */
-  private tagObserversForComputed;
-  /**
-   * Synchronously marks all computeds that depend on this key as dirty.
-   * Uses the computedKey field on observer entries for O(1) key lookup.
-   * Cascades through computed chains (if A depends on B, and B is marked dirty,
-   * then A is also marked dirty).
-   */
-  private markDependentComputedsDirty;
-  /**
-   * Invokes `entries` and returns their pending tails. Stays synchronous from end to end:
-   * the caller relies on nothing being able to interleave until it returns.
-   */
-  private runObservers;
-  notify(key: string, debounceMillis?: number): Promise<void>;
-  get<T>(key: string, observer?: Observer<T>): unknown;
-  private setupComputed;
-  /**
-   * Returns this store's deep-mutation subscriber for `key`. The same key always yields the
-   * same function, so subscriptions can be matched and removed. Created on demand, so a key
-   * that never holds an object never retains a closure.
-   */
-  private mutationCallback;
-  /**
-   * Sets a value in the store.
-   * @param key - The key to set.
-   * @param value - The value to set (can be a computed marker).
-   * @param local - If true, sets directly on this store bypassing ancestor lookup.
-   *                Use for creating local scope variables that shadow ancestors.
-   */
-  set(key: string, value: unknown, local?: boolean): Promise<void>;
-  del(key: string): Promise<void>;
-  /**
-   * Releases this store and every store created from it, recording them in `disposed` for the
-   * single ancestor pass that follows. Observers registered on ancestors are deliberately left
-   * to the caller: every store here shares this store's ancestors, so removing them once for
-   * the whole subtree replaces a scan of every ancestor once per descendant.
-   */
-  private disposeSubtree;
-  /**
-   * Disposes this store by clearing all observers.
-   * Call this when the store is no longer needed to prevent memory leaks.
-   * Also removes any observers this store registered on ancestor stores, disposes the stores
-   * created from this one, and stops listening to deep mutations of the values it holds.
-   */
-  dispose(): void;
-  keys(): string[];
-  /**
-   * Checks if a key exists in THIS store only (not ancestors).
-   * Use `get(key) !== null` to check if a key exists anywhere in the chain.
-   */
-  has(key: string): boolean;
-  /**
-   * Returns observer statistics for performance reporting.
-   */
-  getObserverStats(): {
-    totalKeys: number;
-    totalObservers: number;
-    byKey: Record<string, number>;
-  };
-  effect<R>(observer: (this: ReactiveContext<T>) => R, _meta?: EffectMeta): R;
-  /**
-   * Creates a computed property that automatically updates when its dependencies change.
-   * The function is evaluated in a reactive effect, and the result is stored. When any
-   * reactive property accessed within the function changes, it re-evaluates and updates.
-   *
-   * **Important:** This method returns a marker object at runtime, but is typed as
-   * returning `R` to enable ergonomic property assignment without type casts. The return
-   * value must be assigned to a store property (via `set()` or `$.prop =`) - do not use
-   * it directly as a value.
-   *
-   * @example
-   * // Using function() to access reactive `this`:
-   * store.set('double', store.$computed(function() { return this.count * 2 }));
-   *
-   * // Using arrow function with $ parameter (for templates):
-   * store.set('double', store.$computed(($) => $.count * 2));
-   *
-   * // Direct property assignment (ergonomic typing):
-   * store.$.doubled = store.$computed(($) => $.count * 2);
-   */
-  $computed<R>(fn: ComputedFn<T, R>): R;
-  private proxify;
-  get $(): SignalStore<T> & InternalStoreState & T;
-  /**
-   * Creates an evaluation function for the provided expression.
-   * @param expr The expression to be evaluated.
-   * @returns The evaluation function.
-   */
-  private makeEvalFunction;
-  /**
-   * Retrieves or creates a cached expression function for the provided expression.
-   * @param expr - The expression to retrieve or create a cached function for.
-   * @returns The cached expression function.
-   */
-  private cachedExpressionFunction;
-  eval(expr: string, args?: Record<string, unknown>): unknown;
-  /**
-   * Executes an async function and returns a reactive state object that tracks the result.
-   *
-   * @param fn - The async function to execute.
-   * @param options - Optional arguments to pass to the function.
-   * @returns A reactive state object with $pending, $result, and $error properties.
-   *
-   * @example
-   * // In :data attribute - executes on mount
-   * :data="{ users: $resolve(api.listUsers) }"
-   *
-   * // With options
-   * :data="{ user: $resolve(api.getUser, { path: { id: userId } }) }"
-   *
-   * // In :on:click - executes on click
-   * :on:click="result = $resolve(api.deleteUser, { path: { id } })"
-   */
-  $resolve<T, O = unknown>(fn: (options?: O) => Promise<T>, options?: O): {
-    $pending: boolean;
-    $result: T | null;
-    $error: Error | null;
-  };
-}
-//#endregion
-//#region src/renderer.d.ts
-/**
- * Represents an abstract class for rendering and manipulating HTML content.
- * Extends the `ReactiveProxyStore` class.
- *
- * @template T - The type of the store state. Defaults to `StoreState`.
- */
-declare abstract class IRenderer<T extends StoreState = StoreState> extends SignalStore<T> {
-  abstract readonly impl: string;
-  private _debugLevel;
-  protected readonly dirpath: string;
-  /** Performance data collected during rendering. Reset on each mount(). */
-  private _perfData;
-  /** Debug level ordering for comparison. */
-  private static readonly DEBUG_LEVELS;
-  readonly _skipNodes: Set<Node>;
-  readonly _customElements: Map<string, Node>;
-  /**
-   * Queue for retrying failed element.value assignments.
-   *
-   * Some DOM elements (notably <select>) silently fail when setting .value if
-   * the required child elements don't exist yet. For example, setting
-   * select.value = "banana" does nothing if no <option value="banana"> exists.
-   *
-   * This happens when :bind on a parent element runs before :for on child
-   * elements creates those children (due to BFS traversal order).
-   *
-   * The fix: after setting .value, check if it actually worked. If not, queue
-   * a retry callback. These callbacks are executed at the end of renderNode()
-   * after all child elements have been created.
-   */
-  readonly _pendingValueRetries: Array<() => void>;
-  abstract parseHTML(content: string, params?: ParserParams): Document | DocumentFragment;
-  abstract serializeHTML(root: DocumentFragment | Node): string;
-  abstract createElement(tag: string, owner?: Document | null): Element;
-  abstract createComment(content: string, owner?: Document | null): Node;
-  abstract textContent(node: Node, tag: string): void;
-  /** Hides an element without touching its application-owned styles. */
-  cloakElement(elem: Element): void;
-  /** Reveals a cloaked element by removing only Mancha's private marker. */
-  uncloakElement(elem: Element): void;
-  /**
-   * Sets the debug level for the current instance.
-   *
-   * @param flag - Boolean for backwards compat (true -> 'lifecycle') or a DebugLevel.
-   * @returns The current instance of the class.
-   */
-  debug(flag: boolean | DebugLevel): this;
-  /**
-   * Returns whether debugging is enabled (any level except 'off').
-   */
-  get debugging(): boolean;
-  /**
-   * Checks if the current debug level is at least the specified level.
-   */
-  private shouldLog;
-  /**
-   * Clears accumulated performance data. Called automatically at the start of `mount()`.
-   *
-   * Use this to reset performance tracking before measuring a specific user flow.
-   * After clearing, only effects and lifecycle events from subsequent operations
-   * will be included in the next `getPerformanceReport()` call.
-   *
-   * @example
-   * ```js
-   * // Setup phase
-   * $.debug('lifecycle');
-   * await $.mount(document.body);
-   *
-   * // Clear to start fresh measurement
-   * $.clearPerformanceReport();
-   *
-   * // Perform user flow to measure
-   * $.items = generateLargeList();
-   *
-   * // Get report for just this flow
-   * const report = $.getPerformanceReport();
-   * ```
-   */
-  clearPerformanceReport(): void;
-  /**
-   * Generates a DOM path for an element (e.g., "html>body>div>ul>li:nth-child(2)").
-   */
-  private getNodePath;
-  /**
-   * Builds an effect identifier from metadata.
-   */
-  buildObserverId(meta?: EffectMeta): string;
-  /**
-   * Records an effect execution for performance tracking.
-   */
-  recordObserverExecution(meta: EffectMeta | undefined, duration: number): void;
-  /**
-   * Returns a structured performance report.
-   */
-  getPerformanceReport(): PerformanceReport;
-  /**
-   * Override effect() to add performance tracking.
-   * Wraps the observer so re-executions via notify() are also tracked.
-   */
-  effect<T>(observer: () => T, meta?: EffectMeta): T;
-  /**
-   * Fetches the remote file at the specified path and returns its content as a string.
-   * @param fpath - The path of the remote file to fetch.
-   * @param params - Optional parameters for the fetch operation.
-   * @returns A promise that resolves to the content of the remote file as a string.
-   */
-  fetchRemote(fpath: string, params?: RenderParams): Promise<string>;
-  /**
-   * Fetches a local path and returns its content as a string.
-   *
-   * @param fpath - The file path of the resource.
-   * @param params - Optional render parameters.
-   * @returns A promise that resolves to the fetched resource as a string.
-   */
-  fetchLocal(fpath: string, params?: RenderParams): Promise<string>;
-  /**
-   * Preprocesses a string content with optional rendering and parsing parameters.
-   *
-   * @param content - The string content to preprocess.
-   * @param params - Optional rendering and parsing parameters.
-   * @returns A promise that resolves to a DocumentFragment representing the preprocessed content.
-   */
-  preprocessString(content: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
-  /**
-   * Preprocesses a remote file by fetching its content and applying preprocessing steps.
-   * @param fpath - The path to the remote file.
-   * @param params - Optional parameters for rendering and parsing.
-   * @returns A Promise that resolves to a DocumentFragment representing the preprocessed content.
-   */
-  preprocessRemote(fpath: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
-  /**
-   * Preprocesses a local file by fetching its content and applying preprocessing steps.
-   * @param fpath - The path to the local file.
-   * @param params - Optional parameters for rendering and parsing.
-   * @returns A promise that resolves to the preprocessed document fragment.
-   */
-  preprocessLocal(fpath: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
-  /**
-   * Creates a subrenderer from the current renderer instance.
-   * @returns A new instance of the renderer with the same state as the original.
-   */
-  subrenderer(): IRenderer;
-  /**
-   * Logs the provided arguments if verbose debugging is enabled.
-   * @param args - The arguments to be logged.
-   */
-  log(...args: unknown[]): void;
-  /**
-   * Preprocesses a node by applying all the registered preprocessing plugins.
-   *
-   * @template T - The type of the input node.
-   * @param {T} root - The root node to preprocess.
-   * @param {RenderParams} [params] - Optional parameters for preprocessing.
-   * @returns {Promise<T>} - A promise that resolves to the preprocessed node.
-   */
-  preprocessNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
-  /**
-   * Renders the node and applies all the registered rendering plugins.
-   *
-   * @template T - The type of the root node (Document, DocumentFragment, or Node).
-   * @param {T} root - The root node to render.
-   * @param {RenderParams} [params] - Optional parameters for rendering.
-   * @returns {Promise<T>} - A promise that resolves to the fully rendered root node.
-   */
-  renderNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
-  /**
-   * Mounts the Mancha application to a root element in the DOM.
-   *
-   * @param root - The root element to mount the application to.
-   * @param params - Optional parameters for rendering the application.
-   * @returns A promise that resolves when the mounting process is complete.
-   */
-  mount(root: Document | DocumentFragment | Node, params?: RenderParams): Promise<void>;
-}
-//#endregion
-//#region src/interfaces.d.ts
-interface ParserParams {
-  /** Whether the file parsed is a root document, or a document fragment. */
-  rootDocument?: boolean;
-  /** Encoding to use when processing local files. */
-  encoding?: "ascii" | "utf8";
-}
-/** The RendererParams interface defines the parameters that can be passed to the renderer. */
-interface RenderParams {
-  /** The current directory of the file being rendered. */
-  dirpath?: string;
-  /** Maximum level of recursion allowed when resolving includes. */
-  maxdepth?: number;
-  /** Cache policy used when resolving remote paths. */
-  cache?: RequestCache | null;
-  /** Whether the current node is the root used in Mancha.moun(...). */
-  rootNode?: Node;
-}
-type RendererPlugin = (this: IRenderer, node: ChildNode, params?: RenderParams) => void | Promise<void>;
-/** Debug level for controlling performance tracking and logging verbosity. */
-type DebugLevel = "off" | "lifecycle" | "effects" | "verbose";
-/** Metadata for identifying effects in performance tracking. */
-type EffectMeta = {
-  /** The directive that created this effect (e.g., 'class', 'bind', 'for'). */
-  directive: string;
-  /** The DOM element associated with this effect, if any. */
-  element?: Element;
-  /** The expression being evaluated by this effect. */
-  expression?: string;
-  /** Direct identifier for effects without a DOM element (e.g., computed property key). */
-  id?: string;
-};
-/** Statistics for a tracked effect. */
-type EffectStats = {
-  /** Effect identifier (e.g., "bind:my-input:user.name"). */
-  id: string;
-  /** Number of times this effect has executed. */
-  executionCount: number;
-  /** Total execution time in milliseconds. */
-  totalTime: number;
-  /** Average execution time per invocation in milliseconds. */
-  avgTime: number;
-};
-/** Structured performance report returned by getPerformanceReport(). */
-type PerformanceReport = {
-  /** Timing data for lifecycle methods. */
-  lifecycle: {
-    mountTime?: number;
-    preprocessTime?: number;
-    renderTime?: number;
-  };
-  /** Effect execution statistics. */
-  effects: {
-    /** Total number of unique effects tracked. */
-    total: number;
-    /** Aggregate stats grouped by directive type. */
-    byDirective: Record<string, {
-      count: number;
-      totalTime: number;
-    }>;
-    /** Top 10 slowest effects by total time. */
-    slowest: EffectStats[];
-  };
-  /** Observer registration statistics. */
-  observers: {
-    /** Number of keys with registered observers. */
-    totalKeys: number;
-    /** Total number of observer registrations. */
-    totalObservers: number;
-    /** Observer count per key. */
-    byKey: Record<string, number>;
-  };
-};
-//#endregion
-export { StoreState as a, IRenderer as i, RenderParams as n, RendererPlugin as r, ParserParams as t };

package/dist/mancha.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mancha.js","sourceRoot":"","sources":["../src/mancha.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAElE,gDAAgD;AAChD,MAAM,aAAa,GAAG,UAAU,CAAC,QAAQ,EAAE,aAAa,CAAC;AAEzD,qEAAqE;AACrE,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;AAChC,0EAA0E;AAC1E,QAAQ,CAAC,UAAU,GAAG,UAAU,CAAC;AACjC,UAAU,CAAC,MAAM,GAAG,QAAmE,CAAC;AAExF,6FAA6F;AAC7F,IAAI,aAAa,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;IACzC,sDAAsD;IACtD,MAAM,KAAK,GAAG,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,WAAW,GAAI,aAAa,CAAC,YAAY,CAAC,OAAO,CAAkB,IAAI,SAAS,CAAC;IACvF,MAAM,MAAM,GAAG,aAAa;SAC1B,YAAY,CAAC,QAAQ,CAAC;QACvB,EAAE,KAAK,CAAC,GAAG,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,aAAa;SAC5B,YAAY,CAAC,KAAK,CAAC;QACpB,EAAE,KAAK,CAAC,GAAG,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAa,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAY,KAAK,EAAE,CAAC,CAAC;IAEtC,iDAAiD;IACjD,oCAAoC;IACpC,8DAA8D;IAC9D,gFAAgF;IAChF,IAAI,KAAiD,CAAC;IACtD,MAAM,UAAU,GAAG,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACvD,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC5B,KAAK,GAAG,SAAS,CAAC;IACnB,CAAC;SAAM,IAAI,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,QAAQ,GAAG,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAC1C,KAAK,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;SAAM,CAAC;QACP,+CAA+C;QAC/C,KAAK,GAAG,IAAI,CAAC;IACd,CAAC;IAED,0EAA0E;IAC1E,4DAA4D;IAC5D,UAAU,CAAC;QACV,QAAQ,EAAE,QAAQ;QAClB,GAAG,EAAE,QAAQ;QACb,MAAM;QACN,KAAK;QACL,KAAK,EAAE,WAAW;QAClB,KAAK;KACL,CAAC,CAAC;AACJ,CAAC;KAAM,IAAI,aAAa,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/C,gFAAgF;IAChF,MAAM,UAAU,GAAG,aAAa;SAC9B,YAAY,CAAC,KAAK,CAAC;QACpB,EAAE,KAAK,CAAC,GAAG,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAa,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAY,KAAK,EAAE,CAAc,CAAC;IACnD,UAAU,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,eAAe,QAAQ,CAAC"}