@avelonjs/next 0.1.0

package/src/routing.ts

@@ -0,0 +1,275 @@
+import {
+  Invalid,
+  NotFound,
+  type ControllerClass,
+  type HttpMethod,
+  type RouteDefinition,
+  type RouteManifest,
+} from '@avelonjs/core'
+
+const RESOURCE_ACTIONS = ['index', 'create', 'store', 'show', 'edit', 'update', 'destroy'] as const
+type ResourceAction = (typeof RESOURCE_ACTIONS)[number]
+
+interface MutableRoute extends RouteDefinition<ControllerClass> {
+  middleware: string[]
+  bindings: Record<string, string>
+}
+
+function singular(name: string): string {
+  return name.endsWith('s') ? name.slice(0, -1) : name
+}
+
+function joinPath(prefix: string, path: string): string {
+  if (prefix.length === 0) return path
+  const base = prefix.startsWith('/') ? prefix : `/${prefix}`
+  return `${base.replace(/\/$/, '')}${path.startsWith('/') ? path : `/${path}`}`
+}
+
+/** Fluent builder for one route entry. */
+export class RouteBuilder {
+  constructor(private readonly definition: MutableRoute) {}
+
+  /** Sets the stable route name used by `route()`. */
+  name(name: string): this {
+    this.definition.name = name
+    return this
+  }
+
+  /** Appends middleware aliases. */
+  middleware(...names: string[]): this {
+    this.definition.middleware.push(...names)
+    return this
+  }
+
+  /** Marks a path parameter for route-model binding. */
+  bind(param: string, model: string | { readonly name: string }): this {
+    this.definition.bindings[param] = typeof model === 'string' ? model : model.name
+    return this
+  }
+
+  /** Additionally generates a JSON route handler for this route. */
+  api(): this {
+    this.definition.api = true
+    return this
+  }
+}
+
+/** Fluent resource expander returned by {@link Registrar.resource}. */
+export class ResourceBuilder {
+  constructor(
+    private readonly registrar: Registrar,
+    private readonly members: MutableRoute[],
+  ) {}
+
+  /** Marks member parameters for route-model binding. */
+  bind(param: string, model: string | { readonly name: string }): this {
+    const modelName = typeof model === 'string' ? model : model.name
+    for (const definition of this.members) {
+      if (definition.path.includes(`{${param}}`)) definition.bindings[param] = modelName
+    }
+    return this
+  }
+
+  /** Keeps only the named resource actions. */
+  only(...actions: ResourceAction[]): this {
+    const keep = new Set(actions)
+    this.#filter((action) => keep.has(action))
+    return this
+  }
+
+  /** Drops the named resource actions. */
+  except(...actions: ResourceAction[]): this {
+    const drop = new Set(actions)
+    this.#filter((action) => !drop.has(action))
+    return this
+  }
+
+  /** Additionally generates JSON handlers for every remaining resource route. */
+  api(): this {
+    for (const definition of this.members) definition.api = true
+    return this
+  }
+
+  #filter(keep: (action: ResourceAction) => boolean): void {
+    const removed = new Set(
+      this.members.filter((definition) => !keep(definition.action as ResourceAction)),
+    )
+    for (const definition of removed) this.registrar.drop(definition)
+    const remaining = this.members.filter((definition) => !removed.has(definition))
+    this.members.length = 0
+    this.members.push(...remaining)
+  }
+}
+
+class Registrar {
+  readonly #definitions: MutableRoute[] = []
+  #middleware: string[] = []
+  #prefix = ''
+
+  #push(
+    method: HttpMethod,
+    path: string,
+    controller: ControllerClass,
+    action: string,
+    name?: string,
+  ): MutableRoute {
+    const definition: MutableRoute = {
+      name: name ?? `${controller.name}.${action}`,
+      method,
+      path: joinPath(this.#prefix, path.startsWith('/') ? path : `/${path}`),
+      controller,
+      action,
+      middleware: [...this.#middleware],
+      bindings: {},
+      api: false,
+    }
+    this.#definitions.push(definition)
+    return definition
+  }
+
+  /** Removes a definition. Used by resource `only` / `except`. */
+  drop(definition: MutableRoute): void {
+    const index = this.#definitions.indexOf(definition)
+    if (index >= 0) this.#definitions.splice(index, 1)
+  }
+
+  /** Registers a GET route. */
+  get(path: string, controller: ControllerClass, action = 'index'): RouteBuilder {
+    return new RouteBuilder(this.#push('GET', path, controller, action))
+  }
+
+  /** Registers a POST route. */
+  post(path: string, controller: ControllerClass, action = 'store'): RouteBuilder {
+    return new RouteBuilder(this.#push('POST', path, controller, action))
+  }
+
+  /** Registers a PUT route. */
+  put(path: string, controller: ControllerClass, action = 'update'): RouteBuilder {
+    return new RouteBuilder(this.#push('PUT', path, controller, action))
+  }
+
+  /** Registers a PATCH route. */
+  patch(path: string, controller: ControllerClass, action = 'update'): RouteBuilder {
+    return new RouteBuilder(this.#push('PATCH', path, controller, action))
+  }
+
+  /** Registers a DELETE route. */
+  delete(path: string, controller: ControllerClass, action = 'destroy'): RouteBuilder {
+    return new RouteBuilder(this.#push('DELETE', path, controller, action))
+  }
+
+  /**
+   * Expands to the seven resource routes: index, create, store, show, edit, update, destroy.
+   */
+  resource(name: string, controller: ControllerClass): ResourceBuilder {
+    const param = singular(name)
+    const base = `/${name}`
+    const member = `${base}/{${param}}`
+    const members = [
+      this.#push('GET', base, controller, 'index', `${name}.index`),
+      this.#push('GET', `${base}/create`, controller, 'create', `${name}.create`),
+      this.#push('POST', base, controller, 'store', `${name}.store`),
+      this.#push('GET', member, controller, 'show', `${name}.show`),
+      this.#push('GET', `${member}/edit`, controller, 'edit', `${name}.edit`),
+      this.#push('PUT', member, controller, 'update', `${name}.update`),
+      this.#push('DELETE', member, controller, 'destroy', `${name}.destroy`),
+    ]
+    return new ResourceBuilder(this, members)
+  }
+
+  /** Applies middleware to every route registered inside `group`. */
+  middleware(...names: string[]): { group: (callback: () => void) => void } {
+    return {
+      group: (callback) => {
+        const previous = this.#middleware
+        this.#middleware = [...previous, ...names]
+        callback()
+        this.#middleware = previous
+      },
+    }
+  }
+
+  /** Prefixes every route registered inside `group`. */
+  prefix(prefix: string): { group: (callback: () => void) => void } {
+    return {
+      group: (callback) => {
+        const previous = this.#prefix
+        this.#prefix = joinPath(previous, prefix.startsWith('/') ? prefix : `/${prefix}`)
+        callback()
+        this.#prefix = previous
+      },
+    }
+  }
+
+  /** Returns registered routes in declaration order. */
+  all(): readonly RouteDefinition<ControllerClass>[] {
+    return this.#definitions
+  }
+
+  /** Builds a mountable manifest from the current registrations. */
+  manifest(version = '1'): RouteManifest<ControllerClass> {
+    return { version, routes: this.all() }
+  }
+
+  /** Finds a named route or throws. */
+  find(name: string): RouteDefinition<ControllerClass> {
+    const match = this.#definitions.find((definition) => definition.name === name)
+    if (match === undefined) {
+      throw new NotFound(`Route ${name} was not found.`, {
+        metadata: { resource: 'route', identifier: name },
+      })
+    }
+    return match
+  }
+
+  /** Clears registrations. Intended for tests. */
+  reset(): void {
+    this.#definitions.length = 0
+    this.#middleware = []
+    this.#prefix = ''
+  }
+}
+
+/** Process-wide route registrar used by `routes/web.ts`. */
+export const Route = new Registrar()
+
+/**
+ * Resolves a named route to a path, filling `{param}` placeholders.
+ *
+ * `route('posts.show', id)` fills the first parameter. Pass an object when a route has several.
+ */
+export function route(
+  name: string,
+  params?: string | number | Readonly<Record<string, string | number>>,
+): string {
+  const definition = Route.find(name)
+  const values =
+    params === undefined ? [] : typeof params === 'object' ? Object.values(params) : [params]
+  let index = 0
+  const path = definition.path.replace(/\{(\w+)\}/g, () => {
+    const value = values[index++]
+    if (value === undefined) {
+      throw new Invalid(`Missing parameter for route ${name}.`, {
+        metadata: { fields: { route: [`${name} is missing a path parameter.`] } },
+      })
+    }
+    return String(value)
+  })
+  return path
+}
+
+/** Stable generated export name for a write route. */
+export function exportName(definition: RouteDefinition): string {
+  return definition.name.replace(/[^A-Za-z0-9]+/g, '_')
+}
+
+/** `/posts/{post}/edit` -> `posts/[post]/edit`. */
+export function uriToSegments(uri: string): string {
+  return uri
+    .split('/')
+    .filter(Boolean)
+    .map((segment) =>
+      segment.startsWith('{') && segment.endsWith('}') ? `[${segment.slice(1, -1)}]` : segment,
+    )
+    .join('/')
+}