@stacksjs/bun-router 0.0.13 → 0.0.14

package/src/url.ts

@@ -1,126 +0,0 @@
-/**
- * Named-route URL generation
- *
- * A module-level registry of `name → path` populated by both `Router` and
- * `FluentRouter` whenever a route is given a name. `url(name, params)`
- * resolves a registered name into a URL with path parameters substituted
- * and unmatched params appended as a query string.
- */
-
-import process from 'node:process'
-
-const namedRouteRegistry: Map<string, string> = new Map()
-
-/**
- * Register a named-route path. Called by Router/FluentRouter when a route
- * gets a `.name()`.
- */
-export function registerNamedRoute(name: string, path: string): void {
-  namedRouteRegistry.set(name, path)
-}
-
-/**
- * Look up a registered named-route path without parameter substitution.
- * Mostly useful for tests and tooling.
- */
-export function getNamedRoutePath(name: string): string | undefined {
-  return namedRouteRegistry.get(name)
-}
-
-/**
- * Returns a snapshot of every registered named-route. The map itself is not
- * exposed so callers can't mutate the registry.
- */
-export function getNamedRoutes(): ReadonlyMap<string, string> {
-  return new Map(namedRouteRegistry)
-}
-
-/**
- * Clear the registry. Provided for tests; production code should not need it.
- */
-export function clearNamedRoutes(): void {
-  namedRouteRegistry.clear()
-}
-
-export interface UrlOptions {
-  /**
-   * Return a fully-qualified URL using `process.env.APP_URL` (falling back to
-   * `http://localhost`) instead of a path. Defaults to `false`.
-   */
-  absolute?: boolean
-  /**
-   * Override the base used for `absolute: true`. Wins over `APP_URL`.
-   */
-  base?: string
-}
-
-/**
- * Generate a URL for a named route.
- *
- * @example
- * ```ts
- * router.get('/users/{id}', handler).name('users.show')
- *
- * url('users.show', { id: 42 })
- * // → '/users/42'
- *
- * url('users.show', { id: 42, tab: 'profile' })
- * // → '/users/42?tab=profile'
- *
- * url('users.show', { id: 42 }, { absolute: true })
- * // → 'https://app.example/users/42'  (when APP_URL=https://app.example)
- * ```
- */
-export function url(
-  name: string,
-  params: Record<string, string | number | boolean> = {},
-  options: UrlOptions = {},
-): string {
-  const path = namedRouteRegistry.get(name)
-  if (!path) {
-    const known = [...namedRouteRegistry.keys()].sort().join(', ') || '(none registered)'
-    throw new Error(`Named route '${name}' is not defined. Known routes: ${known}`)
-  }
-
-  const consumed = new Set<string>()
-  let resolved = path
-
-  for (const [key, value] of Object.entries(params)) {
-    const required = `{${key}}`
-    const optional = `{${key}?}`
-    const encoded = encodeURIComponent(String(value))
-
-    if (resolved.includes(required)) {
-      resolved = resolved.replaceAll(required, encoded)
-      consumed.add(key)
-    }
-    else if (resolved.includes(optional)) {
-      resolved = resolved.replaceAll(optional, encoded)
-      consumed.add(key)
-    }
-  }
-
-  // Strip any unfilled optional placeholders (e.g. `/posts/{slug?}` → `/posts/`)
-  resolved = resolved.replace(/\/\{[^}]+\?\}/g, '')
-
-  // Throw on unfilled required placeholders so the caller sees the bug.
-  const missing = resolved.match(/\{([^}?]+)\}/g)
-  if (missing && missing.length > 0)
-    throw new Error(`Missing required params for route '${name}': ${missing.join(', ')}`)
-
-  // Append leftover params as query string.
-  const leftover = Object.entries(params).filter(([k]) => !consumed.has(k))
-  if (leftover.length > 0) {
-    const qs = new URLSearchParams()
-    for (const [k, v] of leftover) qs.set(k, String(v))
-    resolved += `?${qs.toString()}`
-  }
-
-  if (options.absolute) {
-    const base = (options.base ?? process.env.APP_URL ?? 'http://localhost').replace(/\/$/, '')
-    const prefixed = base.startsWith('http') ? base : `https://${base}`
-    return `${prefixed}${resolved.startsWith('/') ? resolved : `/${resolved}`}`
-  }
-
-  return resolved
-}

package/src/utils/index.ts

@@ -1 +0,0 @@
-export * from './query-preservation'

package/src/utils/query-preservation.ts

@@ -1,201 +0,0 @@
-/**
- * Query Parameter Preservation
- *
- * Automatically preserves specified query parameters across navigation.
- * This is useful for maintaining state like siteId, theme, locale, etc.
- */
-
-export interface QueryPreservationConfig {
-  /**
-   * Whether query preservation is enabled
-   * Default: true when preserve array is non-empty
-   */
-  enabled?: boolean
-
-  /**
-   * Query parameters to preserve across navigation
-   * Example: ['siteId', 'theme', 'locale']
-   */
-  preserve?: string[]
-
-  /**
-   * Query parameters to never preserve (takes precedence over preserve)
-   * Example: ['_t', 'utm_source']
-   */
-  exclude?: string[]
-
-  /**
-   * URL patterns where preservation should apply
-   * Default: all internal links (same origin)
-   * Example: ['/dashboard/*', '/admin/*']
-   */
-  routes?: string[]
-}
-
-/**
- * Default configuration
- */
-export const defaultQueryPreservationConfig: QueryPreservationConfig = {
-  enabled: true,
-  preserve: [],
-  exclude: ['_t', '_cache', 'callback'],
-  routes: [],
-}
-
-/* eslint-disable prefer-const */
-/**
- * Generate the client-side script for query preservation
- * This script intercepts link clicks and preserves specified query params
- */
-export function generateQueryPreservationScript(config: QueryPreservationConfig): string {
-  const { preserve = [], exclude = [], routes = [] } = config
-
-  if (!preserve.length) {
-    return ''
-  }
-
-  // Minified but readable client-side script
-  return `<script data-query-preservation>
-(function(){
-  var preserve = ${JSON.stringify(preserve)};
-  var exclude = ${JSON.stringify(exclude)};
-  var routes = ${JSON.stringify(routes)};
-
-  function shouldPreserve(href) {
-    // Only preserve for same-origin links
-    try {
-      var url = new URL(href, window.location.origin);
-      if (url.origin !== window.location.origin) return false;
-      // Check route patterns if specified
-      if (routes.length) {
-        var path = url.pathname;
-        return routes.some(function(pattern) {
-          if (pattern.endsWith('*')) {
-            return path.startsWith(pattern.slice(0, -1));
-          }
-          // eslint-disable-next-line prefer-template
-          return path === pattern || path.startsWith(pattern + '/');
-        });
-      }
-      return true;
-    }
-catch (e) { return false; }
-  }
-
-  function getPreservedParams() {
-    var current = new URLSearchParams(window.location.search);
-    var preserved = {};
-    preserve.forEach(function(key) {
-      if (current.has(key) && exclude.indexOf(key) === -1) {
-        preserved[key] = current.get(key);
-      }
-    });
-    return preserved;
-  }
-
-  function enhanceUrl(href) {
-    var url = new URL(href, window.location.origin);
-    var preserved = getPreservedParams();
-    Object.keys(preserved).forEach(function(key) {
-      if (!url.searchParams.has(key)) {
-        url.searchParams.set(key, preserved[key]);
-      }
-    });
-    return url.toString();
-  }
-
-  // Intercept all link clicks
-  document.addEventListener('click', function(e) {
-    var link = e.target.closest('a[href]');
-    if (!link) return;
-
-    var href = link.getAttribute('href');
-    if (!href || href.startsWith('#') || href.startsWith('javascript:') ||
-        href.startsWith('mailto:') || href.startsWith('tel:')) return;
-
-    if (!shouldPreserve(href)) return;
-
-    // Check if link already has all preserved params
-    var enhanced = enhanceUrl(href);
-    if (enhanced !== new URL(href, window.location.origin).toString()) {
-      e.preventDefault();
-      window.location.href = enhanced;
-    }
-  });
-
-  // Expose API for programmatic navigation
-  window.__preserveQuery = {
-    enhance: enhanceUrl,
-    getPreserved: getPreservedParams,
-    navigate: function(href) {
-      window.location.href = enhanceUrl(href);
-    }
-  };
-})();
-</script>`
-}
-
-/**
- * Inject the query preservation script into HTML content
- * Inserts before </head> or </body> if </head> not found
- */
-export function injectQueryPreservationScript(
-  html: string,
-  config: QueryPreservationConfig
-): string {
-  if (!config.enabled || !config.preserve?.length) {
-    return html
-  }
-
-  const script = generateQueryPreservationScript(config)
-  if (!script) {
-    return html
-  }
-
-  // Try to inject before </head> for early execution
-  if (html.includes('</head>')) {
-    return html.replace('</head>', `${script}\n</head>`)
-  }
-
-  // Fallback: inject before </body>
-  if (html.includes('</body>')) {
-    return html.replace('</body>', `${script}\n</body>`)
-  }
-
-  // Last resort: append to end
-  return html + script
-}
-
-/**
- * Build a URL with preserved query parameters
- * Server-side utility for generating links
- */
-export function buildUrlWithPreservedParams(
-  path: string,
-  currentUrl: string | URL,
-  config: QueryPreservationConfig,
-  additionalParams?: Record<string, string>
-): string {
-  const current = typeof currentUrl === 'string' ? new URL(currentUrl) : currentUrl
-  const target = new URL(path, current.origin)
-
-  // Preserve specified params from current URL
-  if (config.preserve) {
-    for (const key of config.preserve) {
-      if (current.searchParams.has(key) && !config.exclude?.includes(key)) {
-        if (!target.searchParams.has(key)) {
-          target.searchParams.set(key, current.searchParams.get(key)!)
-        }
-      }
-    }
-  }
-
-  // Add any additional params
-  if (additionalParams) {
-    for (const [key, value] of Object.entries(additionalParams)) {
-      target.searchParams.set(key, value)
-    }
-  }
-
-  return target.pathname + target.search
-}

package/src/utils.ts

@@ -1,327 +0,0 @@
-import type { ActionHandler, ActionHandlerClass, RouteHandler } from './types'
-import { join } from 'node:path'
-
-// Re-export query preservation utilities
-export * from './utils/query-preservation'
-
-/**
- * Normalizes a path by ensuring it starts with a forward slash and has no trailing slash
- * @param path The path to normalize
- */
-export function normalizePath(path: string): string {
-  // First replace double (or more) slashes with a single slash
-  let normalizedPath = path.replace(/\/+/g, '/')
-
-  // Then ensure there's a leading slash and no trailing slash (unless it's just /)
-  if (!normalizedPath.startsWith('/')) {
-    normalizedPath = `/${normalizedPath}`
-  }
-
-  if (normalizedPath.length > 1 && normalizedPath.endsWith('/')) {
-    normalizedPath = normalizedPath.slice(0, -1)
-  }
-
-  return normalizedPath
-}
-
-/**
- * Converts a string path to an action path for dynamic imports
- * @param path The path to convert (e.g., 'Actions/Home/IndexAction')
- */
-export function toActionPath(path: string): string {
-  return path.replace(/\//g, '_').toLowerCase()
-}
-
-/**
- * Checks if a handler is a class constructor implementing ActionHandlerClass
- * @param handler The handler to check
- */
-export function isActionClass(handler: ActionHandler): handler is new () => ActionHandlerClass {
-  if (typeof handler !== 'function' && typeof handler !== 'object') {
-    return false
-  }
-
-  // Check if it's a class constructor
-  if (typeof handler === 'function' && handler.prototype) {
-    const prototype = handler.prototype as unknown as { handle?: unknown }
-    if (typeof prototype.handle === 'function') {
-      return true
-    }
-  }
-
-  // Check if it's an instance with a handle method
-  if (typeof handler === 'object' && handler !== null && 'handle' in handler && typeof (handler as any).handle === 'function') {
-    return true
-  }
-
-  return false
-}
-
-/**
- * Checks if a handler is a route handler function
- * @param handler The handler to check
- */
-export function isRouteHandler(handler: ActionHandler): handler is RouteHandler {
-  return typeof handler === 'function' && !isActionClass(handler)
-}
-
-/**
- * Extracts named parameters from a path pattern
- * @param pattern The path pattern (e.g., '/users/{id}/posts/{postId}')
- */
-export function extractParamNames(pattern: string): string[] {
-  const matches = pattern.match(/\{([^}]+)\}/g)
-  return matches ? matches.map(m => m.slice(1, -1).replace('?', '')) : []
-}
-
-/**
- * Creates a regex pattern from a path pattern
- * @param pattern The path pattern
- */
-export function createPathRegex(pattern: string): RegExp {
-  const regexPattern = pattern.replace(/\{([^}]+)\}/g, '([^/]+)')
-  return new RegExp(`^${regexPattern}$`)
-}
-
-/**
- * Matches a path against a pattern and extracts parameters
- * @param pattern The path pattern (e.g., '/users/{id}')
- * @param path The actual path (e.g., '/users/123')
- * @param params Output parameter object that will contain extracted parameters
- * @param constraints Optional constraints for route parameters
- * @returns Boolean indicating whether the path matches the pattern
- */
-export function matchPath(
-  pattern: string,
-  path: string,
-  params: Record<string, string>,
-  constraints?: Record<string, string>,
-): boolean {
-  // Both paths should be normalized
-  const normalizedPattern = normalizePath(pattern)
-  const normalizedPath = normalizePath(path)
-
-  // Special case for wildcard patterns
-  if (pattern.endsWith('/*')) {
-    const basePattern = pattern.slice(0, -2)
-    if (path.startsWith(basePattern)) {
-      return true
-    }
-  }
-
-  // Handle patterns with parameters
-  const patternSegments = normalizedPattern.split('/').filter(Boolean)
-  const pathSegments = normalizedPath.split('/').filter(Boolean)
-
-  // Quick check - if segments don't match (accounting for optional params) then no match
-  // For mandatory parameters, the pattern and path must have same number of segments
-  const optionalParamCount = (normalizedPattern.match(/\{[^}]+\?\}/g) || []).length
-
-  if (pathSegments.length < patternSegments.length - optionalParamCount
-    || pathSegments.length > patternSegments.length) {
-    return false
-  }
-
-  // Match each segment
-  for (let i = 0; i < patternSegments.length; i++) {
-    const patternSegment = patternSegments[i]
-    const pathSegment = pathSegments[i]
-
-    // If we've run out of path segments and this is not an optional parameter
-    if (pathSegment === undefined) {
-      if (patternSegment.match(/\{[^}]+\?\}/)) {
-        // This is an optional parameter and we have no path segment for it
-        continue
-      }
-      else {
-        // Required parameter or static segment with no matching path segment
-        return false
-      }
-    }
-
-    // Check if this segment is a parameter
-    const paramMatch = patternSegment.match(/\{([^}:]+)(?::[^}]+)?(\?)?\}/)
-    if (paramMatch) {
-      // This is a parameter segment, extract param name
-      const paramName = paramMatch[1].replace('?', '')
-      // Store the parameter value
-      params[paramName] = pathSegment
-
-      // Check constraints if they exist
-      if (constraints && constraints[paramName]) {
-        try {
-          const regex = new RegExp(`^${constraints[paramName]}$`)
-          if (!regex.test(pathSegment)) {
-            return false
-          }
-        }
-        catch {
-          // If regex is invalid, treat as no constraint
-          console.warn(`Invalid constraint regex for parameter ${paramName}: ${constraints[paramName]}`)
-        }
-      }
-    }
-    else if (patternSegment !== pathSegment) {
-      // Static segment doesn't match
-      return false
-    }
-  }
-
-  return true
-}
-
-/**
- * Joins path segments ensuring proper formatting
- * @param segments Path segments to join
- */
-export function joinPaths(...segments: string[]): string {
-  return normalizePath(segments.join('/'))
-}
-
-/**
- * Validates a route path format
- * @param path The path to validate
- */
-export function validatePath(path: string): boolean {
-  // Path must start with a slash
-  if (!path.startsWith('/')) {
-    return false
-  }
-
-  // Check for balanced curly braces
-  const stack: string[] = []
-  for (const char of path) {
-    if (char === '{') {
-      stack.push(char)
-    }
-    else if (char === '}') {
-      if (stack.length === 0 || stack.pop() !== '{') {
-        return false
-      }
-    }
-  }
-
-  return stack.length === 0
-}
-
-/**
- * Check if a file exists at the given path
- * @param path The file path to check
- */
-export async function fileExists(path: string): Promise<boolean> {
-  try {
-    const file = Bun.file(path)
-    return await file.exists()
-  }
-  catch {
-    return false
-  }
-}
-
-/**
- * Resolve a view name to an actual file path
- * @param viewName The view name (without extension)
- * @param viewsPath The base path for views
- * @param extensions File extensions to try
- */
-export async function resolveViewPath(
-  viewName: string,
-  viewsPath: string,
-  extensions: string[],
-): Promise<string | null> {
-  // If viewName already contains an extension, try it directly
-  if (extensions.some(ext => viewName.endsWith(ext))) {
-    const fullPath = normalizePath(join(viewsPath, viewName))
-    if (await fileExists(fullPath)) {
-      return fullPath
-    }
-    return null
-  }
-
-  // Try each extension
-  for (const ext of extensions) {
-    const fullPath = normalizePath(join(viewsPath, `${viewName}${ext}`))
-    if (await fileExists(fullPath)) {
-      return fullPath
-    }
-  }
-
-  return null
-}
-
-/**
- * Basic HTML template processing - replaces {{ varName }} with the corresponding value
- * @param template The HTML template string
- * @param data The data to inject into the template
- */
-export function processHtmlTemplate(template: string, data: Record<string, any>): string {
-  // Process general variables {{ varName }}
-  let result = template.replace(/\{\{([^}]+)\}\}/g, (match, key) => {
-    const trimmedKey = key.trim()
-    const value = getNestedValue(data, trimmedKey)
-    return value !== undefined ? String(value) : match
-  })
-
-  // Process conditionals {{#if condition}} content {{/if}}
-  result = processConditionals(result, data)
-
-  // Process loops {{#each items}} content {{/each}}
-  result = processLoops(result, data)
-
-  return result
-}
-
-/**
- * Process conditional statements in templates
- */
-function processConditionals(template: string, data: Record<string, any>): string {
-  // Match {{#if condition}} content {{/if}} or {{#if condition}} content {{else}} alternative {{/if}}
-  return template.replace(
-    /\{\{#if ([^}]+)\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}/g,
-    (_match, condition, content, alternative = '') => {
-      const conditionTrimmed = condition.trim()
-      const value = getNestedValue(data, conditionTrimmed)
-      // Explicitly check for falsy values (false, undefined, null, 0, "")
-      return value ? content : alternative
-    },
-  )
-}
-
-/**
- * Process loop statements in templates
- */
-function processLoops(template: string, data: Record<string, any>): string {
-  // Match {{#each items}} content {{/each}}
-  return template.replace(
-    /\{\{#each ([^}]+)\}\}([\s\S]*?)\{\{\/each\}\}/g,
-    (_match, arrayKey, content) => {
-      const array = getNestedValue(data, arrayKey.trim())
-      if (!Array.isArray(array))
-        return ''
-
-      return array.map((item) => {
-        // Replace {{@index}} with the current index
-        // Replace {{this}} with the current item
-        // Replace {{this.property}} with the current item's property
-        return content
-          .replace(/\{\{@index\}\}/g, String(array.indexOf(item)))
-          .replace(/\{\{this\}\}/g, String(item))
-          .replace(/\{\{this\.([^}]+)\}\}/g, (_matchStr: string, prop: string) => {
-            const value = item[prop.trim()]
-            return value !== undefined ? String(value) : ''
-          })
-      }).join('')
-    },
-  )
-}
-
-/**
- * Get a nested value from an object using dot notation
- * @param obj The object to extract value from
- * @param path The path to the value (e.g., 'user.profile.name')
- */
-function getNestedValue(obj: Record<string, any>, path: string): any {
-  return path.split('.').reduce((prev, curr) => {
-    return prev && prev[curr] !== undefined ? prev[curr] : undefined
-  }, obj)
-}