API reference

export interface ReadonlySignal<T> {
  (): T;
  /** Reads the value without subscribing the running effect. */
  peek(): T;
}

export interface Signal<T> extends ReadonlySignal<T> {
  set(value: T): void;
  update(fn: (current: T) => T): void;
}

export function signal<T>(initial: T): Signal<T>;

export function signal<T = undefined>(): Signal<T | undefined>;

export function computed<T>(fn: () => T): ReadonlySignal<T>;

export function effect(fn: () => void | (() => void), owner?: Array<() => void>): () => void;

export function untracked<T>(fn: () => T): T;

export type Type<T = any> = abstract new (...args: any[]) => T;

export interface ClassProvider { provide: Type; useClass: Type }

export interface ValueProvider { provide: Type; useValue: unknown }

export interface FactoryProvider { provide: Type; useFactory: () => unknown }

export type Provider = Type | ClassProvider | ValueProvider | FactoryProvider;

export type AotTemplate = (components: Record<string, Type>, kit: object) => object;

export interface ComponentMeta {
  /** Tag name, default `app-root`. */
  selector?: string;
  /** Template source (compiled in the browser). Use `aot` for precompiled templates. */
  template?: string;
  aot?: AotTemplate;
  /** Components used in the template. */
  imports?: Type[];
  /** Services scoped to this component and its descendants. */
  providers?: Provider[];
}

export function component<T extends Type>(Class: T, meta: ComponentMeta): T;

export function Component(meta: ComponentMeta): <T extends Type>(Class: T) => T;

export interface MountedApp<T = any> {
  /** The component instance. */
  instance: T;
  destroy(): void;
}

export function mount<T>(Comp: Type<T>, el: Element, up?: object | null): MountedApp<T>;

export function input<T>(initial: T): Signal<T>;

export interface OutputEmitter<T = void> {
  emit(value: T): void;
  subscribe(fn: (value: T) => void): () => void;
}

export function output<T = void>(): OutputEmitter<T>;

export interface OnInit { ngOnInit(): void }

export interface AfterViewInit { ngAfterViewInit(): void }

export interface OnDestroy { ngOnDestroy(): void }

export interface OnError { ngOnError(error: unknown, where: string): void }

export function inject<T>(Token: Type<T>): T;

export function provide<T>(Token: Type<T>, value: T): void;

export interface TrustedValue { readonly kind: 'html' | 'url'; readonly value: string }

export function trustHtml(html: string): TrustedValue;

export function trustUrl(url: string): TrustedValue;

export function sanitizeUrl(value: unknown, attr: string): string;

export function registerPipe(name: string, fn: (value: any, ...args: any[]) => any): void;

export function viewChild<T = Element>(name: string): Signal<T | null>;

export interface RouteContext {
  path: string;
  params: Record<string, string>;
  query: Record<string, string>;
  route: Route;
}

export type RouteGuard = (to: RouteContext) => boolean | string | void | Promise<boolean | string | void>;

export interface Route {
  /** `users/:id`, `''` for an index route, `**` for anything else. */
  path: string;
  component?: Type;
  /** Code splitting: loaded on the first visit. Resolves to the component or to a module with a default export. */
  load?: () => Promise<Type | { default: Type }>;
  children?: Route[];
  canActivate?: RouteGuard[];
  /** Data loaded before the page renders; read it with `router.data()`. */
  resolve?: Record<string, (to: RouteContext) => unknown | Promise<unknown>>;
  redirectTo?: string;
}

export interface Router {
  readonly path: Signal<string>;
  /** `?page=2` as `{ page: '2' }`. */
  readonly query: ReadonlySignal<Record<string, string>>;
  /** What the matched routes' `resolve` functions returned. */
  readonly data: Signal<Record<string, any>>;
  readonly current: ReadonlySignal<{ component: Type | undefined; params: Record<string, string> } | null>;
  params(): Record<string, string>;
  navigate(to: string, options?: { replace?: boolean }): void;
}

export const router: Router;

export interface RouterOptions {
  /** `hash` (default) works on any static host; `history` uses real paths and needs server support. */
  mode?: 'hash' | 'history';
  /** Path prefix in history mode, e.g. `/app`. */
  base?: string;
}

export function provideRouter(routes: Route[], options?: RouterOptions): Router;

export function enableDevWarnings(log?: (message: string) => void): void;

export type ValidationErrors = Record<string, any> | null;

export type Validator<T = any> = (value: T) => ValidationErrors;

export const Validators: {
  required: Validator;
  minLength(n: number): Validator;
  maxLength(n: number): Validator;
  min(n: number): Validator;
  max(n: number): Validator;
  pattern(re: RegExp): Validator;
  email: Validator;
  /** The value must equal what `other()` returns. */
  matches(other: () => unknown): Validator;
};

export class FormControl<T = any> implements Control<T> {
  constructor(initial?: T, validators?: Validator<T>[]);
  readonly value: Signal<T>;
  readonly errors: ReadonlySignal<ValidationErrors>;
  readonly valid: ReadonlySignal<boolean>;
  readonly touched: Signal<boolean>;
  readonly dirty: ReadonlySignal<boolean>;
  initial: T;
  touch(): void;
  setValue(value: T): void;
  reset(value?: T): void;
}

export class FormGroup<T extends Record<string, any> = Record<string, any>> implements Control<T> {
  constructor(controls: Record<string, any>, validators?: Validator<T>[]);
  readonly controls: Record<string, any>;
  readonly value: ReadonlySignal<T>;
  readonly errors: ReadonlySignal<ValidationErrors>;
  readonly valid: ReadonlySignal<boolean>;
  readonly touched: ReadonlySignal<boolean>;
  readonly dirty: ReadonlySignal<boolean>;
  /** `get('address.street')` walks nested groups. */
  get(path: string): any;
  touch(): void;
  setValue(value: Partial<T>): void;
  reset(value?: Partial<T>): void;
}

export class FormArray<T = any> implements Control<T[]> {
  constructor(controls?: any[], validators?: Validator<T[]>[]);
  /** Call it to read the current list: `array.controls()`. */
  readonly controls: Signal<any[]>;
  readonly value: ReadonlySignal<T[]>;
  readonly errors: ReadonlySignal<ValidationErrors>;
  readonly valid: ReadonlySignal<boolean>;
  readonly touched: ReadonlySignal<boolean>;
  readonly dirty: ReadonlySignal<boolean>;
  at(index: number): any;
  push(control: any): void;
  removeAt(index: number): void;
  touch(): void;
  setValue(values: T[]): void;
  reset(): void;
}

export interface HttpRequest {
  method: string;
  url: string;
  headers: Record<string, string>;
  body?: BodyInit | null;
  responseType: 'json' | 'text' | 'blob' | 'response';
  signal?: AbortSignal;
  /** Milliseconds before the request is aborted. */
  timeout?: number;
  credentials?: RequestCredentials;
}

export interface HttpResponse<T = any> {
  status: number;
  statusText: string;
  ok: boolean;
  headers: Headers;
  url: string;
  data: T;
  request: HttpRequest;
}

export type Interceptor = (request: HttpRequest, next: (request: HttpRequest) => Promise<HttpResponse>) => Promise<HttpResponse>;

export class HttpError extends Error {
  status: number;
  data: any;
  response: HttpResponse;
}

export interface RequestOptions {
  params?: Record<string, string | number | boolean | null | undefined>;
  headers?: Record<string, string>;
  responseType?: HttpRequest['responseType'];
  signal?: AbortSignal;
  timeout?: number;
  credentials?: RequestCredentials;
}

export interface HttpClient {
  request<T = any>(method: string, url: string, options?: RequestOptions & { body?: unknown }): Promise<T>;
  get<T = any>(url: string, options?: RequestOptions): Promise<T>;
  delete<T = any>(url: string, options?: RequestOptions): Promise<T>;
  post<T = any>(url: string, body?: unknown, options?: RequestOptions): Promise<T>;
  put<T = any>(url: string, body?: unknown, options?: RequestOptions): Promise<T>;
  patch<T = any>(url: string, body?: unknown, options?: RequestOptions): Promise<T>;
}

export function createHttp(options?: { baseUrl?: string; headers?: Record<string, string>; interceptors?: Interceptor[]; fetch?: typeof fetch }): HttpClient;

export function retry(times?: number, delay?: number): Interceptor;

export interface Resource<T> {
  readonly data: Signal<T | undefined>;
  readonly error: Signal<unknown>;
  readonly loading: Signal<boolean>;
  reload(): void;
  destroy(): void;
}

export function resource<T>(loader: () => Promise<T> | T): Resource<T>;

export type Messages = { [key: string]: string | Messages };

export interface I18n {
  readonly locale: Signal<string>;
  /** `params.count` selects the plural form when the message is an object (`one`, `other`...). */
  t(key: string, params?: Record<string, string | number>): string;
  setLocale(locale: string): void;
  load(locale: string, source: Messages | (() => Promise<Messages | { default: Messages }>)): Promise<void>;
  number(value: number, options?: Intl.NumberFormatOptions): string;
  date(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
  relative(value: number, unit?: Intl.RelativeTimeFormatUnit): string;
  /** Registers the pipes `t`, `num` and `date` bound to this instance. */
  installPipes(): void;
}

export function createI18n(options?: { locale?: string; fallback?: string; messages?: Record<string, Messages> }): I18n;

export function hydrate<T>(Comp: Type<T>, el: Element): MountedApp<T>;

export interface DevtoolsNode {
  name: string;
  el: Element;
  instance: any;
  state: Record<string, unknown>;
  children: DevtoolsNode[];
}

export interface DevtoolsApi {
  tree(root?: Element): DevtoolsNode[];
  inspect(el: Element): any;
  state(instance: any): Record<string, unknown>;
  /** Sets a signal field; returns false if it is not a signal. */
  set(instance: any, key: string, value: unknown): boolean;
  closePanel?: () => void;
}

export function enableDevtools(options?: { panel?: boolean }): DevtoolsApi;

export interface RenderOptions {
  /** Inputs to set (signals get `.set(value)`; other properties are assigned). */
  props?: Record<string, unknown>;
  /** Services visible to the whole tree: `[[Api, fakeApi]]`. */
  provide?: Array<[Type, unknown]>;
  /** Container element. By default a new <div> in document.body. */
  into?: Element;
}

export interface Rendered<T = any> {
  container: Element;
  host: Element | null;
  instance: T;
  $(selector: string): Element | null;
  $$(selector: string): Element[];
  text(target: string | Element): string;
  click(target: string | Element): void;
  /** Types into an input/textarea/select (fires `input` and `change`), or sets a checkbox. */
  type(target: string | Element, value: string | boolean): void;
  fire(target: string | Element, type: string, init?: EventInit): boolean;
  /** Resolves after pending signal updates have reached the DOM. */
  flush(): Promise<void>;
  unmount(): void;
}

export function render<T>(Comp: Type<T>, options?: RenderOptions): Rendered<T>;

export function fire(el: Element, type: string, init?: EventInit): boolean;

export function flush(): Promise<void>;

export function cleanup(): void;

export interface RenderOptions {
  /** Request URL (path and query) the router should see. */
  url?: string;
  /** `mount` of the AngeLite runtime your app uses; defaults to the bundled full build. */
  mount?: (Comp: Type, el: Element) => { instance: any; destroy(): void };
  /** HTML shell; `<!--app-->` marks where the app goes (or it needs an element matching `selector`). */
  shell?: string;
  /** Runs before the component is mounted, with the DOM globals in place (set up the router here). */
  setup?: () => unknown;
  /** Called with the component instance; await your data here. */
  ready?: (instance: any) => unknown;
  /** Extra macrotask turns to wait after `ready` (default 2). */
  settle?: number;
  selector?: string;
}

export function renderToString(Comp: Type, options?: RenderOptions): Promise<string>;

export function renderPage(Comp: Type, options: RenderOptions & { shell: string; state?: unknown }): Promise<string>;

export function serializeState(state: unknown): string;

export interface TemplateOptions {
  /** Tags (lowercase) that are components, e.g. ['ui-button']. */
  components?: string[];
  /** The component's fields and methods; enables the "is not a member" check. */
  members?: string[];
  /** Custom pipes registered with registerPipe(). */
  pipes?: string[];
  /** Custom elements (web components) that are not AngeLite components. */
  elements?: string[];
}

export interface CompileOptions extends TemplateOptions {
  /** What to do with problems: log them (default), throw, or ignore. */
  check?: 'warn' | 'error' | false;
}

export function compileTemplate(source: string, options?: CompileOptions): string;

export function checkTemplate(source: string, options?: TemplateOptions): string[];

export function discoverMembers(file: string): string[];

export interface PluginOptions extends Omit<CompileOptions, 'members'> {
  /** An explicit list, or 'auto' to read it from the class file next to the template. */
  members?: string[] | 'auto';
}

export function aotPlugin(options?: PluginOptions): { name: string; setup(build: any): void };

export interface Options {
  components?: string[];
  members?: string[] | 'auto';
  pipes?: string[];
  elements?: string[];
  check?: 'warn' | 'error' | false;
}

export function checkFolder(dir: string, options?: { components?: string[]; pipes?: string[]; elements?: string[]; members?: 'auto' }): Array<{ file: string; message: string }>;