Tasks & Resources

/**
 * Execute task that runs on server and/or client
 * @param task - Task function with execution context
 */
function useTask$(task: TaskFn): void;

/**
 * Execute task from QRL
 * @param task - QRL-wrapped task function
 */
function useTaskQrl(task: QRL<TaskFn>): void;

/**
 * Execute task when element becomes visible
 * @param task - Task function for visible execution
 */
function useVisibleTask$(task: TaskFn): void;

/**
 * Execute visible task from QRL
 * @param task - QRL-wrapped visible task function
 */
function useVisibleTaskQrl(task: QRL<TaskFn>): void;

// Task function interface
type TaskFn = (ctx: TaskCtx) => ValueOrPromise<void>;

// Task execution context
interface TaskCtx {
  /** Track reactive dependencies */
  track<T>(fn: () => T): T;
  /** Cleanup function registration */
  cleanup(fn: () => void): void;
}

// Task configuration options
interface UseTaskOptions {
  /** Task eagerness */
  eagerness?: EagernessOptions;
}

// Eagerness configuration
type EagernessOptions = "load" | "visible" | "idle";

// Visible task options
interface OnVisibleTaskOptions {
  /** Visibility strategy */
  strategy?: VisibleTaskStrategy;
}

// Visibility strategy
type VisibleTaskStrategy = "intersection-observer" | "document-ready" | "document-idle";

/**
 * Create async resource for data fetching
 * @param resource - Resource function
 * @param opts - Resource options
 * @returns Resource return object with loading states
 */
function useResource$<T>(resource: ResourceFn<T>, opts?: ResourceOptions): ResourceReturn<T>;

/**
 * Create resource from QRL
 * @param resource - QRL-wrapped resource function
 * @param opts - Resource options
 * @returns Resource return object
 */
function useResourceQrl<T>(resource: QRL<ResourceFn<T>>, opts?: ResourceOptions): ResourceReturn<T>;

// Resource function interface
type ResourceFn<T> = (ctx: ResourceCtx) => ValueOrPromise<T>;

// Resource execution context
interface ResourceCtx {
  /** Track reactive dependencies */
  track<T>(fn: () => T): T;
  /** Cleanup function registration */
  cleanup(fn: () => void): void;
  /** Cache key */
  cacheKey: string;
  /** Previous value */
  previous: T | undefined;
}

// Resource return object
interface ResourceReturn<T> {
  /** Loading state signal */
  readonly loading: Signal<boolean>;
  /** Resource value signal */  
  readonly value: Signal<T | undefined>;
  /** Promise for the resource */
  readonly promise: Promise<T>;
}

// Resource configuration
interface ResourceOptions {
  /** Resource timeout */
  timeout?: number;
}

/**
 * Create computed signal within component
 * @param compute - Computation function
 * @returns Computed signal
 */
function useComputed$<T>(compute: ComputedFn<T>): Signal<T>;

/**
 * Create computed signal from QRL
 * @param compute - QRL-wrapped computation
 * @returns Computed signal
 */
function useComputedQrl<T>(compute: QRL<ComputedFn<T>>): Signal<T>;

/**
 * Create computed signal outside component
 * @param compute - Computation function
 * @returns Computed signal
 */
function createComputed$<T>(compute: ComputedFn<T>): Signal<T>;

/**
 * Create computed from QRL outside component
 * @param compute - QRL-wrapped computation
 * @returns Computed signal
 */
function createComputedQrl<T>(compute: QRL<ComputedFn<T>>): Signal<T>;

// Computation function type
type ComputedFn<T> = () => T;

import { 
  component$, 
  useTask$, 
  useResource$, 
  useComputed$,
  useSignal 
} from "@builder.io/qwik";

export const DataComponent = component$(() => {
  const userId = useSignal(1);

  // Resource for data fetching
  const userResource = useResource$<User>(async ({ track, cleanup }) => {
    const id = track(() => userId.value);
    
    const controller = new AbortController();
    cleanup(() => controller.abort());
    
    const response = await fetch(`/api/users/${id}`, {
      signal: controller.signal,
    });
    return response.json();
  });

  // Computed value based on resource
  const displayName = useComputed$(() => {
    const user = userResource.value;
    return user ? `${user.firstName} ${user.lastName}` : "Unknown";
  });

  // Task for side effects
  useTask$(({ track }) => {
    const name = track(() => displayName.value);
    console.log("Display name changed:", name);
  });

  return (
    <div>
      {userResource.loading.value && <p>Loading...</p>}
      {userResource.value && (
        <div>
          <h1>{displayName.value}</h1>
          <p>Email: {userResource.value.email}</p>
        </div>
      )}
      <button onClick$={() => userId.value++}>
        Next User
      </button>
    </div>
  );
});