Request-aware URI builder for H3ravel framework

[SaikiranSurapalli17]

Summary

Adds a new package @h3ravel/url providing:

• Request-aware helpers: current, full, previous, previousPath, query
• Fluent immutable URL builder: withScheme, withHost, withPort, withPath, withQuery, withFragment
• Static factories: of, to, route, signedRoute, temporarySignedRoute, action
• HMAC signing and verification with optional expiration
• Smooth integration with @h3ravel/router and @h3ravel/http

Motivation

• Standardize URL manipulation across H3ravel
• Familiar Laravel-like API
• Framework-agnostic, DI-friendly utilities

What’s Implemented

• Static factories:
  • Url.of(string)
  • Url.to(path)
  • Url.route(name, params)
  • Url.signedRoute(name, params)
  • Url.temporarySignedRoute(name, params, expiration)
  • Url.action(controller) (resolved via app.routes signatures)
• Fluent immutable API:
  • All mutators return a new Url instance
• Request-aware helpers (via DI):
  • current(), full(), previous(), previousPath(), query()
• Signing:
  • HMAC-based signing (sha256) with expires support
  • hasValidSignature() verification
• Type-safety:
  • Generic route helpers (Url.route<TName, TParams>) to enable declaration merging in apps
• Integration:
  • Uses router.route, http.request, and app.routes for action resolution

Tests

• packages/url/tests/Url.spec.ts: 31 tests passing
• Request-aware helpers validated by unit tests earlier; DI-based helpers compatible with container mocks

Usage

• From string:
  • Url.of('https://example.com/path')
• From request:
  • url(app).full() // https://example.com/posts?page=2
• Builder chain:
  • Url.of('https://example.com').withScheme('http').withHost('test.com').withPort(8000).withPath('/users').withQuery({ page: 2 }).withFragment('section-1')
• Routes:
  • Url.route('users.show', { id: 1 })
  • Url.signedRoute('users.show', { id: 1 })
  • Url.temporarySignedRoute('users.index', {}, Date.now() + 300000)
  • Url.action('UserController@index')

Type-safe Params (declaration merging example)

declare module '@h3ravel/url' {
  interface RouteParams {
    'users.show': { id: number }
    'posts.index': { page?: number }
  }
}

Breaking Changes

• None. Feature is additive and DI-based.

Notes

• Requires APP_URL or config('app.url') for base URL resolution.
• Requires APP_KEY or config('app.key') for signing.

Closes #40 - cc @3m1n3nc3