@stacksjs/bun-router 0.0.4 → 0.0.6

package/src/url.ts

@@ -0,0 +1,126 @@
+/**
+ * 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

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

package/src/utils/query-preservation.ts

@@ -0,0 +1,201 @@
+/**
+ * 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

@@ -0,0 +1,327 @@
+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)
+}