sibujs 1.0.0-beta.1

package/dist/performance.d.cts

@@ -0,0 +1,416 @@
+declare const Priority: {
+    readonly IMMEDIATE: 0;
+    readonly USER_BLOCKING: 1;
+    readonly NORMAL: 2;
+    readonly LOW: 3;
+    readonly IDLE: 4;
+};
+type PriorityLevel = (typeof Priority)[keyof typeof Priority];
+/**
+ * Schedule an update with a given priority level.
+ * Returns a cancel function.
+ */
+declare function scheduleUpdate(priority: PriorityLevel, callback: () => void): () => void;
+/**
+ * Flush all pending tasks synchronously (useful for testing).
+ */
+declare function flushScheduler(): void;
+/**
+ * Get the number of pending tasks.
+ */
+declare function pendingTasks(): number;
+/**
+ * Yield control back to the main thread, allowing the browser to process
+ * user input, rendering, and other high-priority work.
+ *
+ * Uses `scheduler.yield()` when available (Chrome 115+),
+ * falls back to `setTimeout(0)`.
+ *
+ * @example
+ * ```ts
+ * for (let i = 0; i < items.length; i++) {
+ *   renderItem(items[i]);
+ *   if (i % 50 === 0) await yieldToMain();
+ * }
+ * ```
+ */
+declare function yieldToMain(): Promise<void>;
+/**
+ * Process an array in chunks, yielding to the main thread between chunks.
+ * Prevents long-running loops from blocking the UI.
+ *
+ * @param items Array of items to process
+ * @param processor Callback invoked for each item
+ * @param chunkSize Number of items per chunk before yielding (default: 50)
+ */
+declare function processInChunks<T>(items: T[], processor: (item: T, index: number) => void, chunkSize?: number): Promise<void>;
+
+/**
+ * Mark a state update as non-urgent.
+ * The callback is scheduled at NORMAL priority so it won't block
+ * high-priority work like user input handling.
+ */
+declare function startTransition(callback: () => void): void;
+/**
+ * Returns a deferred getter for a reactive value.
+ * The deferred value mirrors the source but updates at LOW priority,
+ * allowing the UI to remain responsive while expensive derived state
+ * catches up.
+ */
+declare function deferredValue<T>(getter: () => T): () => T;
+/**
+ * Provides a `startTransition` wrapper paired with a reactive
+ * `isPending` flag that is `true` while the transition is in flight.
+ *
+ * Usage:
+ *   const [isPending, startTransition] = transitionState();
+ *   startTransition(() => { setSomeState(newValue); });
+ *   if (isPending()) { // show spinner }
+ */
+declare function transitionState(): [isPending: () => boolean, startTransition: (cb: () => void) => void];
+/**
+ * Reset the ID counter. Call at the start of each SSR request
+ * to ensure server and client produce matching IDs.
+ */
+declare function resetIdCounter(): void;
+/**
+ * Set a custom prefix for generated IDs.
+ * Useful when multiple SibuJS apps coexist on the same page.
+ */
+declare function setIdPrefix(prefix: string): void;
+/**
+ * Generate a unique, stable ID for use in accessibility attributes.
+ * SSR-compatible: call resetIdCounter() at the start of each SSR render
+ * to ensure server and client produce matching IDs.
+ *
+ * @param suffix Optional suffix appended to the generated ID
+ * @returns A unique ID string like "sibu-0", "sibu-1-label"
+ *
+ * @example
+ * ```ts
+ * const id = id();
+ * label({ htmlFor: id, nodes: "Name" });
+ * input({ id, type: "text" });
+ * ```
+ */
+declare function uniqueId(suffix?: string): string;
+
+/**
+ * DOMPool manages a pool of reusable DOM elements to reduce GC pressure.
+ */
+declare class DOMPool {
+    private pools;
+    private maxSize;
+    constructor(maxSize?: number);
+    /**
+     * Get a recycled element or create a new one.
+     */
+    acquire(tag: string): HTMLElement;
+    /**
+     * Return an element to the pool for reuse.
+     * Clears attributes, children, and event listeners.
+     */
+    release(element: HTMLElement): void;
+    /**
+     * Clear all pools.
+     */
+    clear(): void;
+    /**
+     * Get pool statistics.
+     */
+    stats(): Record<string, number>;
+}
+/** Default global pool instance */
+declare const domPool: DOMPool;
+/**
+ * Preloads a resource (script, style, or generic fetch).
+ */
+declare function preloadResource(url: string, type?: "script" | "style" | "fetch" | "image"): void;
+/**
+ * Prefetches a URL for future navigation.
+ */
+declare function prefetch(url: string): void;
+/**
+ * Preloads an image and returns a promise that resolves when loaded.
+ */
+declare function preloadImage(src: string): Promise<HTMLImageElement>;
+
+/**
+ * Bundle size optimization utilities for SibuJS.
+ * Provides markers and utilities for tree-shaking and dead code elimination.
+ */
+/**
+ * Mark a function as pure for tree-shaking.
+ * Bundlers (Rollup, esbuild, webpack) use this to eliminate unused code.
+ * Wraps a factory function with the PURE annotation.
+ */
+declare function pure<T>(fn: () => T): T;
+/**
+ * Conditional import helper for tree-shaking.
+ * Only includes the module in the bundle if the condition is true.
+ * In production builds, dead branches are eliminated.
+ */
+declare function conditional<T>(condition: boolean, loader: () => T): T | undefined;
+/**
+ * Feature flag helper for dead code elimination.
+ * Bundlers can statically replace these with true/false to eliminate dead code.
+ */
+declare const Features: {
+    readonly SSR: boolean;
+    readonly DEV: boolean;
+    readonly BROWSER: boolean;
+};
+/**
+ * Development-only code block. Eliminated in production builds
+ * when process.env.NODE_ENV is set to 'production'.
+ */
+declare function devOnly(fn: () => void): void;
+/**
+ * Marks an export as having no side effects.
+ * Used by module-level sideEffects annotation.
+ */
+declare function noSideEffect<T extends (...args: unknown[]) => unknown>(fn: T): T;
+
+/**
+ * Compiled optimizations for SibuJS.
+ * Provides markers and utilities for Svelte-style compile-time optimizations.
+ * These are hints for build tools and static analyzers.
+ */
+/**
+ * Marks a component's template as static (no reactive bindings).
+ * A build tool can pre-render this to a static HTML string and
+ * skip reactive setup entirely.
+ */
+declare function staticTemplate(html: string): HTMLElement;
+/**
+ * Clone a static template for efficient repeated rendering.
+ * Uses template.content.cloneNode(true) which is faster than createElement.
+ */
+declare function cloneTemplate(template: HTMLTemplateElement): DocumentFragment;
+/**
+ * Pre-compile a component factory.
+ * Caches the template and only applies dynamic bindings on each call.
+ */
+declare function precompile<Props>(templateHtml: string, hydrate: (el: HTMLElement, props: Props) => void): (props: Props) => HTMLElement;
+/**
+ * Marker for static expressions that can be hoisted out of reactive scopes.
+ * A compiler pass would extract these to module scope.
+ */
+declare function hoistable<T>(value: T): T;
+/**
+ * Marks a block of DOM creation as having a known, fixed structure.
+ * Enables block-level optimization where the compiler can generate
+ * optimized creation and patching code.
+ */
+declare function block(factory: () => HTMLElement): HTMLElement;
+
+/**
+ * Schema definition for entity normalization.
+ * Describes the shape of an entity type and its relationships.
+ */
+interface NormalizedSchema {
+    /** Name of the entity type (e.g. "user", "post") */
+    name: string;
+    /** Key used as the unique identifier. Defaults to "id" */
+    idKey?: string;
+    /** Map of relation field names to their entity type names */
+    relations?: Record<string, string>;
+}
+/** Internal normalized state shape, following the ids + entities pattern */
+interface NormalizedState<T> {
+    ids: string[];
+    entities: Record<string, T>;
+}
+/** Actions returned by normalizedStore */
+interface NormalizedStoreActions<T> {
+    /** Add a single entity to the store */
+    add(entity: T): void;
+    /** Add multiple entities to the store */
+    addMany(entities: T[]): void;
+    /** Get an entity by its id, or undefined if not found */
+    get(id: string): T | undefined;
+    /** Get all entities as an array */
+    getAll(): T[];
+    /** Update an entity by merging a partial object */
+    update(id: string, partial: Partial<T>): void;
+    /** Remove an entity by id */
+    remove(id: string): void;
+    /** Query entities matching a predicate */
+    select(predicate: (entity: T) => boolean): T[];
+    /** Get the raw normalized state (reactive getter) */
+    getState(): NormalizedState<T>;
+}
+/**
+ * normalizedStore creates a reactive normalized store for a single
+ * entity type. Internal storage uses the `{ ids, entities }` pattern
+ * (like Redux Toolkit's entity adapter) backed by signal for reactivity.
+ *
+ * @param schema Schema describing the entity type
+ * @returns Store actions for CRUD and query operations
+ *
+ * @example
+ * ```ts
+ * const users = normalizedStore<User>({ name: "user" });
+ *
+ * users.add({ id: "1", name: "Alice" });
+ * users.addMany([
+ *   { id: "2", name: "Bob" },
+ *   { id: "3", name: "Charlie" },
+ * ]);
+ *
+ * const alice = users.get("1");       // { id: "1", name: "Alice" }
+ * const all = users.getAll();         // [Alice, Bob, Charlie]
+ * users.update("1", { name: "Alicia" });
+ * users.remove("3");
+ * const bobs = users.select(u => u.name.startsWith("B"));
+ * ```
+ */
+declare function normalizedStore<T extends Record<string, unknown>>(schema: NormalizedSchema): NormalizedStoreActions<T>;
+/** A map of entity type names to their flat entity tables */
+type NormalizedEntities = Record<string, Record<string, unknown>>;
+/** Result of normalizing nested data */
+interface NormalizeResult {
+    /** The top-level id (or array of ids) of the normalized data */
+    result: string | string[];
+    /** All extracted entities keyed by type name, then by id */
+    entities: NormalizedEntities;
+}
+/**
+ * normalize takes a nested data object (or array) and flattens it into
+ * a normalized entities map according to the provided schema.
+ *
+ * Relations defined in the schema are recursively extracted and replaced
+ * with their id references.
+ *
+ * @param data The nested data to normalize (single object or array)
+ * @param schema The schema describing entity shape and relations
+ * @returns A NormalizeResult with the top-level id(s) and all entities
+ *
+ * @example
+ * ```ts
+ * const postSchema: NormalizedSchema = {
+ *   name: "post",
+ *   relations: { author: "user", comments: "comment" },
+ * };
+ *
+ * const data = {
+ *   id: "p1",
+ *   title: "Hello",
+ *   author: { id: "u1", name: "Alice" },
+ *   comments: [
+ *     { id: "c1", text: "Great!" },
+ *     { id: "c2", text: "Thanks" },
+ *   ],
+ * };
+ *
+ * const { result, entities } = normalize(data, postSchema);
+ * // result === "p1"
+ * // entities.post["p1"] === { id: "p1", title: "Hello", author: "u1", comments: ["c1", "c2"] }
+ * // entities.user["u1"] === { id: "u1", name: "Alice" }
+ * // entities.comment["c1"] === { id: "c1", text: "Great!" }
+ * ```
+ */
+declare function normalize<T extends Record<string, unknown>>(data: T | T[], schema: NormalizedSchema): NormalizeResult;
+/**
+ * denormalize reconstructs a nested object from a flat normalized entities
+ * map, resolving relation references back to their full objects.
+ *
+ * @param id The id of the root entity to reconstruct
+ * @param entities The flat entities map (from normalize or manual construction)
+ * @param schema The schema describing entity shape and relations
+ * @returns The fully reconstructed nested object, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const post = denormalize("p1", entities, postSchema);
+ * // post.author is the full user object, not just "u1"
+ * // post.comments is an array of full comment objects
+ * ```
+ */
+declare function denormalize<T extends Record<string, unknown>>(id: string, entities: NormalizedEntities, schema: NormalizedSchema): T | undefined;
+
+/**
+ * Advanced runtime chunk loading with caching strategies for SibuJS.
+ * Provides configurable caching, preloading, retry logic, and loading orchestration.
+ */
+interface ChunkConfig {
+    /** Maximum number of cached chunks */
+    maxCacheSize?: number;
+    /** Cache TTL in milliseconds (0 = no expiry) */
+    cacheTTL?: number;
+    /** Number of retry attempts on failure */
+    retries?: number;
+    /** Delay between retries in ms */
+    retryDelay?: number;
+    /** Timeout for chunk loading in ms */
+    timeout?: number;
+    /** Called when a chunk starts loading */
+    onLoadStart?: (id: string) => void;
+    /** Called when a chunk finishes loading */
+    onLoadEnd?: (id: string) => void;
+    /** Called when a chunk fails to load */
+    onLoadError?: (id: string, error: Error) => void;
+}
+/**
+ * Central registry for managing dynamic chunks with caching and lifecycle callbacks.
+ */
+declare function createChunkRegistry(config?: ChunkConfig): {
+    /**
+     * Load a chunk by ID. Uses cache if available, otherwise loads via the provided loader.
+     */
+    load<T>(id: string, loader: () => Promise<T>): Promise<T>;
+    /**
+     * Preload a chunk without blocking. Silently caches for later use.
+     */
+    preload<T>(id: string, loader: () => Promise<T>): void;
+    /**
+     * Preload multiple chunks in parallel.
+     */
+    preloadAll(entries: Array<{
+        id: string;
+        loader: () => Promise<unknown>;
+    }>): void;
+    /**
+     * Check if a chunk is cached and valid.
+     */
+    has(id: string): boolean;
+    /**
+     * Get a cached chunk synchronously. Returns undefined if not cached.
+     */
+    get<T>(id: string): T | undefined;
+    /**
+     * Invalidate a cached chunk.
+     */
+    invalidate(id: string): void;
+    /**
+     * Clear all cached chunks.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics.
+     */
+    stats(): {
+        size: number;
+        maxSize: number;
+        pending: number;
+        preloaded: number;
+    };
+};
+/**
+ * Create a lazy-loaded component that uses the chunk registry for caching.
+ * Provides automatic retry, timeout, and cache management.
+ */
+declare function lazyChunk(id: string, loader: () => Promise<{
+    default: () => HTMLElement;
+} | (() => HTMLElement)>, registry: ReturnType<typeof createChunkRegistry>, fallback?: () => HTMLElement): () => HTMLElement;
+/**
+ * Preload ES modules using link[rel=modulepreload].
+ * Improves loading performance by informing the browser early.
+ */
+declare function preloadModule(url: string): void;
+/**
+ * Preload multiple modules.
+ */
+declare function preloadModules(urls: string[]): void;
+
+export { type ChunkConfig, DOMPool, Features, type NormalizeResult, type NormalizedEntities, type NormalizedSchema, type NormalizedState, type NormalizedStoreActions, Priority, type PriorityLevel, block, cloneTemplate, conditional, createChunkRegistry, deferredValue, denormalize, devOnly, domPool, flushScheduler, hoistable, lazyChunk, noSideEffect, normalize, normalizedStore, pendingTasks, precompile, prefetch, preloadImage, preloadModule, preloadModules, preloadResource, processInChunks, pure, resetIdCounter, scheduleUpdate, setIdPrefix, startTransition, staticTemplate, transitionState, uniqueId, yieldToMain };