@h3ravel/url/dist/index.d.ts

Request-aware URI builder and URL manipulation utilities for H3ravel.

/// <reference path="./app.globals.d.ts" />
import { ExtractControllerMethods } from "@h3ravel/shared";
import { Application, ServiceProvider } from "@h3ravel/core";

//#region src/RequestAwareHelpers.d.ts

/**
 * Request-aware URL helper class
 */
declare class RequestAwareHelpers {
  private app;
  private readonly baseUrl;
  constructor(app: Application);
  /**
   * Get the current request instance
   */
  private getCurrentRequest;
  /**
   * Get the current request URL (path only, no query string)
   */
  current(): string;
  /**
   * Get the full current URL with query string
   */
  full(): string;
  /**
   * Get the previous request URL from session or referrer
   */
  previous(): string;
  /**
   * Get the previous request path (without query string)
   */
  previousPath(): string;
  /**
   * Get the current query parameters
   */
  query(): RouteParams;
}
/**
 * Global helper function factory
 */
declare function createUrlHelper(app: Application): () => RequestAwareHelpers;
//#endregion
//#region src/Url.d.ts
/**
 * URL builder class with fluent API and request-aware helpers
 */
declare class Url {
  private readonly _scheme?;
  private readonly _host?;
  private readonly _port?;
  private readonly _path;
  private readonly _query;
  private readonly _fragment?;
  private readonly app?;
  private constructor();
  /**
   * Create a URL from a full URL string
   */
  static of(url: string, app?: Application): Url;
  /**
   * Create a URL from a path relative to the app URL
   */
  static to(path: string, app?: Application): Url;
  /**
   * Create a URL from a named route
   */
  static route<TName extends string = string, TParams extends RouteParams = RouteParams>(name: TName, params?: TParams, app?: Application): Url;
  /**
   * Create a signed URL from a named route
   */
  static signedRoute<TName extends string = string, TParams extends RouteParams = RouteParams>(name: TName, params?: TParams, app?: Application): Url;
  /**
   * Create a temporary signed URL from a named route
   */
  static temporarySignedRoute<TName extends string = string, TParams extends RouteParams = RouteParams>(name: TName, params: TParams | undefined, expiration: number, app?: Application): Url;
  /**
   * Create a URL from a controller action
   */
  static action<C extends new (...args: any) => any>(controller: string | [C, methodName: ExtractControllerMethods<InstanceType<C>>], params?: Record<string, any>, app?: Application): Url;
  /**
   * Set the scheme (protocol) of the URL
   */
  withScheme(scheme: string): Url;
  /**
   * Set the host of the URL
   */
  withHost(host: string): Url;
  /**
   * Set the port of the URL
   */
  withPort(port: number): Url;
  /**
   * Set the path of the URL
   */
  withPath(path: string): Url;
  /**
   * Set the query parameters of the URL
   */
  withQuery(query: Record<string, unknown>): Url;
  /**
   * Merge additional query parameters
   */
  withQueryParams(params: Record<string, unknown>): Url;
  /**
   * Set the fragment (hash) of the URL
   */
  withFragment(fragment: string): Url;
  /**
   * Add a signature to the URL for security
   */
  withSignature(app?: Application, expiration?: number): Url;
  /**
   * Verify if a URL signature is valid
   */
  hasValidSignature(app?: Application): boolean;
  /**
   * Convert the URL to its string representation
   */
  toString(): string;
  /**
   * Get the scheme
   */
  getScheme(): string | undefined;
  /**
   * Get the host
   */
  getHost(): string | undefined;
  /**
   * Get the port
   */
  getPort(): number | undefined;
  /**
   * Get the path
   */
  getPath(): string;
  /**
   * Get the query parameters
   */
  getQuery(): Record<string, unknown>;
  /**
   * Get the fragment
   */
  getFragment(): string | undefined;
}
//#endregion
//#region src/Contracts/UrlContract.d.ts
type RouteParams<N = any> = Record<string, N>;
/**
 * Contract for URL manipulation and generation
 */
interface UrlContract {
  /**
   * Set the scheme (protocol) of the URL
   */
  withScheme(scheme: string): this;
  /**
   * Set the host of the URL
   */
  withHost(host: string): this;
  /**
   * Set the port of the URL
   */
  withPort(port: number): this;
  /**
   * Set the path of the URL
   */
  withPath(path: string): this;
  /**
   * Set the query parameters of the URL
   */
  withQuery(query: Record<string, any>): this;
  /**
   * Set the fragment (hash) of the URL
   */
  withFragment(fragment: string): this;
  /**
   * Convert the URL to its string representation
   */
  toString(): string;
}
/**
 * Contract for request-aware URL helpers
 */
interface RequestAwareUrlContract {
  /**
   * Get the current request URL
   */
  current(): string;
  /**
   * Get the full current URL with query string
   */
  full(): string;
  /**
   * Get the previous request URL
   */
  previous(): string;
  /**
   * Get the previous request path (without query string)
   */
  previousPath(): string;
  /**
   * Get the current query parameters
   */
  query(): Record<string, any>;
}
/**
 * The Url Helper Contract
 */
interface HelpersContract {
  /**
   * Create a URL from a path relative to the app URL
   */
  to: (path: string) => Url;
  /**
   * Create a URL from a named route
   */
  route: (name: string, params?: Record<string, any>) => string;
  /**
   * Create a signed URL from a named route
   *
   * @param name
   * @param params
   * @returns
   */
  signedRoute: (name: string, params?: Record<string, any>) => Url;
  /**
   * Create a temporary signed URL from a named route
   *
   * @param name
   * @param params
   * @param expiration
   * @returns
   */
  temporarySignedRoute: (name: string, params: Record<string, any> | undefined, expiration: number) => Url;
  /**
   * Create a URL from a controller action
   */
  action: <C extends new (...args: any) => any>(controller: string | [C, methodName: ExtractControllerMethods<InstanceType<C>>], params?: Record<string, any>) => string;
  /**
   * Get request-aware URL helpers
   */
  url: {
    (): RequestAwareHelpers;
    (path: string): string;
  };
}
//#endregion
//#region src/Helpers.d.ts
/**
 * Global helper functions for URL manipulation
 */
/**
 * Create a URL from a path relative to the app URL
 */
declare function to(path: string, app?: Application): Url;
/**
 * Create a URL from a named route
 */
declare function route<TName extends string, TParams extends Record<string, string> = Record<string, string>>(name: TName, params?: TParams, app?: Application): Url;
/**
 * Create a signed URL from a named route
 */
declare function signedRoute<TName extends string, TParams extends Record<string, string> = Record<string, string>>(name: TName, params?: TParams, app?: Application): Url;
/**
 * Create a temporary signed URL from a named route
 */
declare function temporarySignedRoute(name: string, params: Record<string, string> | undefined, expiration: number, app?: Application): Url;
/**
 * Create a URL from a controller action
 */
declare function action(controller: string, app?: Application): Url;
/**
 * Get request-aware URL helpers
 */
declare function url(app?: Application): RequestAwareHelpers;
/**
 * Create URL helpers that are bound to an application instance
 */
declare function createUrlHelpers(app: Application): HelpersContract;
//#endregion
//#region src/Providers/UrlServiceProvider.d.ts
/**
 * Service provider for URL utilities
 */
declare class UrlServiceProvider extends ServiceProvider {
  static priority: number;
  /**
   * Register URL services in the container
   */
  register(): void;
  /**
   * Boot URL services
   */
  boot(): void;
}
//#endregion
export { HelpersContract, RequestAwareHelpers, RequestAwareUrlContract, RouteParams, Url, UrlContract, UrlServiceProvider, action, createUrlHelper, createUrlHelpers, route, signedRoute, temporarySignedRoute, to, url };