@h3ravel/url 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,298 @@
+/// <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 {
+  /**
+   * 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 };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,298 @@
+/// <reference path="./app.globals.d.ts" />
+import { Application, ServiceProvider } from "@h3ravel/core";
+import { ExtractControllerMethods } from "@h3ravel/shared";
+
+//#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 {
+  /**
+   * 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 };
+//# sourceMappingURL=index.d.ts.map