tessl/npm-builder-io--qwik

An Open-Source sub-framework designed with a focus on server-side-rendering, lazy-loading, and resumable architecture for instant-loading web applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

QRL System

Name: tessl/npm-builder-io--qwik
Author: tessl

Qwik Resource Locators (QRLs) enable precise lazy loading by converting functions and expressions into loadable resources. This is the core innovation that allows Qwik to achieve resumable architecture and instant-loading applications.

Capabilities

QRL Creation

Convert expressions and functions into lazy-loadable resources.

/**
 * Convert expression to QRL for lazy loading
 * @param expression - Function or expression to wrap
 * @returns QRL that loads the expression when needed
 */
function $<T>(expression: T): QRL<T>;

/**
 * Create synchronous QRL (loads immediately when called)
 * @param expression - Function or expression to wrap
 * @returns Synchronous QRL
 */
function sync$<T>(expression: T): SyncQRL<T>;

/**
 * Create QRL with manual synchronization control
 * @param expression - Function to wrap
 * @returns QRL with sync control
 */
function _qrlSync<T>(expression: T): QRL<T>;

// Core QRL interface
interface QRL<T> {
  readonly __qrl__: true;
  // Internal properties for lazy loading
}

// Synchronous QRL interface
interface SyncQRL<T> extends QRL<T> {
  readonly __sync__: true;
}

Usage Examples:

import { $, sync$ } from "@builder.io/qwik";

// Basic QRL creation
const handleClick = $(() => {
  console.log("This function loads only when clicked");
});

// Synchronous QRL
const syncFunction = sync$(() => {
  console.log("This loads immediately when called");
});

// QRL with captured variables
const createHandler = (message: string) => {
  return $(() => {
    console.log(message); // message is captured in closure
  });
};

Event QRLs

Specialized QRL creation for event handlers.

/**
 * Create event handler QRL
 * @param handler - Event handler function
 * @returns QRL optimized for event handling
 */
function event$<T>(handler: T): QRL<T>;

/**
 * Create event handler from existing QRL
 * @param handler - Existing QRL
 * @returns Event-optimized QRL
 */
function eventQrl<T>(handler: QRL<T>): QRL<T>;

Usage Examples:

import { event$, component$ } from "@builder.io/qwik";

export const Button = component$(() => {
  // Event handler with automatic lazy loading
  const handleClick = event$((event: MouseEvent) => {
    event.preventDefault();
    console.log("Button clicked");
  });

  return <button onClick$={handleClick}>Click me</button>;
});

Manual QRL Creation

Advanced QRL creation with explicit chunk and symbol references.

/**
 * Create QRL from chunk path and symbol name
 * @param chunkPath - Path to the code chunk
 * @param symbol - Symbol name within the chunk
 * @param lexicalScopeCapture - Captured lexical scope
 * @returns QRL pointing to the specified symbol
 */
function qrl<T>(
  chunkPath: string,
  symbol: string,
  lexicalScopeCapture?: any[]
): QRL<T>;

/**
 * Create inlined QRL (for development)
 * @param symbol - Function symbol
 * @param symbolName - Name of the symbol
 * @param lexicalScopeCapture - Captured scope
 * @returns Inlined QRL
 */
function inlinedQrl<T>(
  symbol: T,
  symbolName: string,
  lexicalScopeCapture?: any[]
): QRL<T>;

/**
 * Development version of inlined QRL
 * @param symbol - Function symbol
 * @param symbolName - Name of the symbol
 * @param lexicalScopeCapture - Captured scope  
 * @param stackOffset - Stack trace offset
 * @returns Development QRL with debugging info
 */
function inlinedQrlDEV<T>(
  symbol: T,
  symbolName: string,
  lexicalScopeCapture?: any[],
  stackOffset?: number
): QRL<T>;

/**
 * Development version of qrl
 * @param chunkPath - Path to the code chunk
 * @param symbol - Symbol name within the chunk
 * @param lexicalScopeCapture - Captured lexical scope
 * @param stackOffset - Stack trace offset
 * @returns Development QRL with debugging info
 */
function qrlDEV<T>(
  chunkPath: string,
  symbol: string,
  lexicalScopeCapture?: any[],
  stackOffset?: number
): QRL<T>;

QRL Utilities

Utility functions for working with QRLs.

/**
 * Transform function to use implicit dollar syntax
 * @param fn - Function to transform
 * @returns Transformed function
 */
function implicit$FirstArg(fn: any): any;

PropFunction Types

Type definitions for QRL-based prop functions.

// QRL-based function prop
interface PropFunction<T extends Function> extends QRL<T> {
  (...args: Parameters<T>): ReturnType<T>;
}

// Function prop interface
interface PropFnInterface<T> {
  __qrl__: QRL<T>;
}

Usage Examples:

import { qrl, inlinedQrl } from "@builder.io/qwik";

// Manual QRL creation (typically generated by compiler)
const manualQrl = qrl<() => void>(
  "./chunk-abc123.js",
  "handleClick",
  [] // no captured variables
);

// Inlined QRL for development
const devQrl = inlinedQrl(
  () => console.log("dev handler"),
  "devHandler"
);

// Component with QRL props
interface ButtonProps {
  onClick$: PropFunction<() => void>;
  label: string;
}

export const CustomButton = component$<ButtonProps>((props) => {
  return (
    <button onClick$={props.onClick$}>
      {props.label}
    </button>
  );
});

// Usage
export const App = component$(() => {
  const handleClick = $(() => console.log("Clicked!"));
  
  return <CustomButton onClick$={handleClick} label="Click me" />;
});

QRL Lifecycle

Understanding how QRLs work in the Qwik architecture.

// No-op QRL for testing/development
function _noopQrl<T>(): QRL<T>;

// Development no-op QRL
function _noopQrlDEV<T>(): QRL<T>;

// Register symbol for QRL resolution
function _regSymbol<T>(symbol: T, hash: string): T;

QRL Loading Process: