velocious 1.0.430 → 1.0.431

package/src/routes/base-route.js

@@ -0,0 +1,133 @@
+// @ts-check
+
+export default class VelociousBaseRoute {
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {typeof import("./get-route.js").default} */
+  static GetRouteType
+
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {typeof import("./namespace-route.js").default} */
+  static NameSpaceRouteType
+
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {typeof import("./post-route.js").default} */
+  static PostRouteType
+
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {typeof import("./resource-route.js").default} */
+  static ResourceRouteType
+
+  /**
+   * Runs register route get type.
+   * @param {typeof import("./get-route.js").default} RouteClass - Route class to register.
+   */
+  static registerRouteGetType(RouteClass) {
+    this.GetRouteType = RouteClass
+  }
+
+  /**
+   * Runs register route namespace type.
+   * @param {typeof import("./namespace-route.js").default} RouteClass - Route class to register.
+   */
+  static registerRouteNamespaceType(RouteClass) {
+    this.NameSpaceRouteType = RouteClass
+  }
+
+  /**
+   * Runs register route post type.
+   * @param {typeof import("./post-route.js").default} RouteClass - Route class to register.
+   */
+  static registerRoutePostType(RouteClass) {
+    this.PostRouteType = RouteClass
+  }
+
+  /**
+   * Runs register route resource type.
+   * @param {typeof import("./resource-route.js").default} RouteClass - Route class to register.
+   */
+  static registerRouteResourceType(RouteClass) {
+    this.ResourceRouteType = RouteClass
+  }
+
+  /**
+   * Routes.
+    @type {Array<VelociousBaseRoute>} */
+  routes = []
+
+  /**
+   * Mounts.
+    @type {Array<{mountable: {mountInto: (args: object) => void}, options: Record<string, ?>}>} */
+  mounts = []
+
+  constructor() {
+    // Nothing
+  }
+
+  /**
+   * Runs get mounts.
+   * @returns {Array<{mountable: {mountInto: (args: object) => void}, options: Record<string, ?>}>} - Mounts declared on this route.
+   */
+  getMounts() { return this.mounts }
+
+  /**
+   * Runs get.
+   * @abstract
+   * @param {string} name - Name.
+   */
+  get(name) { throw new Error("'get' not implemented") } // eslint-disable-line no-unused-vars
+
+  /**
+   * Runs get human paths.
+   * @abstract
+   * @returns {Array<{action: string | null, method: string, path: string}>} - Route definitions for this resource.
+   */
+  getHumanPaths() { throw new Error(`'getHumanPaths' not implemented for ${this.constructor.name}`) }
+
+  /**
+   * Runs get sub routes.
+   * @returns {Array<VelociousBaseRoute>} - The sub routes.
+   */
+  getSubRoutes() { return this.routes }
+
+  /**
+   * Runs match with path.
+   * @param {object} args - Options object.
+   * @param {Record<string, ?>} args.params - Parameters object.
+   * @param {string} args.path - Path.
+   * @param {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default} args.request - Request object.
+   * @returns {{restPath: string} | undefined} - REST path metadata for this route.
+   */
+  matchWithPath({params, path, request}) { // eslint-disable-line no-unused-vars
+    throw new Error(`No 'matchWithPath' implemented on ${this.constructor.name}`)
+  }
+
+  /**
+   * Runs namespace.
+   * @abstract
+   * @param {string} name - Name.
+   * @param {function(import("./namespace-route.js").default) : void} callback - Callback function.
+   * @returns {void} - No return value.
+   */
+  namespace(name, callback) { throw new Error("'namespace' not implemented") } // eslint-disable-line no-unused-vars
+
+  /**
+   * Runs post.
+   * @abstract
+   * @param {string} name - Name.
+   * @returns {void} - No return value.
+   */
+  post(name) { throw new Error("'post' not implemented") } // eslint-disable-line no-unused-vars
+
+  /**
+   * Runs resources.
+   * @abstract
+   * @param {string} name - Name.
+   * @param {function(import("./resource-route.js").default) : void} callback - Callback function.
+   * @returns {void} - No return value.
+   */
+  resources(name, callback) { throw new Error("'resources' not implemented") } // eslint-disable-line no-unused-vars
+}

package/src/routes/basic-route.js

@@ -0,0 +1,109 @@
+// @ts-check
+
+import BaseRoute from "./base-route.js"
+
+export default class VelociousBasicRoute extends BaseRoute {
+  /**
+   * Runs get.
+   * @param {string} name - Route name.
+   */
+  get(name) {
+    const GetRoute = VelociousBasicRoute.GetRouteType
+    const route = new GetRoute({name})
+
+    this.routes.push(route)
+  }
+
+  /**
+   * Runs match with path.
+   * @param {object} args - Options object.
+   * @param {Record<string, ?>} args.params - Parameters object.
+   * @param {string} args.path - Path.
+   * @param {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default} args.request - Request object.
+   * @returns {{restPath: string} | undefined} - REST path metadata for this route.
+   */
+  matchWithPath({params, path, request}) { // eslint-disable-line no-unused-vars
+    throw new Error(`No 'matchWithPath' implemented on ${this.constructor.name}`)
+  }
+
+  /**
+   * Mounts a sub-application (e.g. the background-jobs dashboard API) at a path
+   * prefix, similar to mounting Sidekiq::Web in a Rails routes file. The
+   * mountable's `mountInto({configuration, ...options})` is invoked when the
+   * configuration receives the routes.
+   * @param {{mountInto: (args: object) => void}} mountable - Mountable with a static `mountInto` method.
+   * @param {object} [options] - Mount options. Must include an `at` path prefix starting with "/".
+   * @returns {void} - No return value.
+   */
+  mount(mountable, options = {}) {
+    if (!mountable || typeof mountable.mountInto !== "function") {
+      throw new Error("mount expects a mountable with a 'mountInto' method")
+    }
+
+    const at = /**
+                * Narrows the runtime value to the documented type.
+                 @type {Record<string, ?>} */ (options).at
+
+    if (typeof at !== "string" || !at.startsWith("/")) {
+      throw new Error(`mount requires an 'at' option starting with '/', got: ${String(at)}`)
+    }
+
+    this.mounts.push({mountable, options})
+  }
+
+  /**
+   * Runs namespace.
+   * @param {string} name - Name.
+   * @param {function(import("./namespace-route.js").default) : void} callback - Callback function.
+   * @returns {void} - No return value.
+   */
+  namespace(name, callback) {
+    const NamespaceRoute = VelociousBasicRoute.NameSpaceRouteType
+
+    if (!NamespaceRoute) throw new Error("No NamespaceRoute registered")
+
+    const route = new NamespaceRoute({name})
+
+    this.routes.push(route)
+
+    if (callback) {
+      callback(route)
+    }
+  }
+
+  /**
+   * Runs post.
+   * @param {string} name - Name.
+   * @returns {void} - No return value.
+   */
+  post(name) {
+    const PostRoute = VelociousBasicRoute.PostRouteType
+
+    if (!PostRoute) throw new Error("No PostRoute registered")
+
+    const route = new PostRoute({name})
+
+    this.routes.push(route)
+  }
+
+  /**
+   * Runs resources.
+   * @param {string} name - Name.
+   * @param {function(import("./resource-route.js").default) : void} [callback] - Callback function.
+   * @returns {void} - No return value.
+   */
+  resources(name, callback) {
+    const ResourceRoute = VelociousBasicRoute.ResourceRouteType
+
+    if (!ResourceRoute) throw new Error("No ResourceRoute registered")
+
+    const route = new ResourceRoute({name})
+
+    this.routes.push(route)
+
+    if (callback) {
+      callback(route)
+    }
+  }
+}
+

package/src/routes/built-in/debug/controller.js

@@ -0,0 +1,12 @@
+import Controller from "../../../controller.js"
+
+export default class BuiltInDebugController extends Controller {
+  /**
+   * Runs show.
+   * @returns {Promise<void>} - Resolves when the debug snapshot has been rendered.
+   */
+  async show() {
+    this._response.setHeader("Content-Type", "application/json; charset=UTF-8")
+    this._response.setBody(`${JSON.stringify(await this.getConfiguration().getDebugSnapshot(), null, 2)}\n`)
+  }
+}

package/src/routes/built-in/errors/controller.js

@@ -0,0 +1,7 @@
+import Controller from "../../../controller.js"
+
+export default class BuiltInErrorsController extends Controller {
+  async notFound() {
+    this.render({status: "not-found"})
+  }
+}

package/src/routes/built-in/errors/not-found.ejs

@@ -0,0 +1 @@
+Path not found: <%= controller.getRequest().path() %>

package/src/routes/get-route.js

@@ -0,0 +1,75 @@
+// @ts-check
+
+import escapeStringRegexp from "escape-string-regexp"
+
+import BaseRoute from "./base-route.js"
+import restArgsError from "../utils/rest-args-error.js"
+
+/**
+ * Runs assign action and controller.
+ * @param {Record<string, ?>} params - Route params object.
+ * @param {string} name - Route name.
+ * @returns {void} - No return value.
+ */
+function assignActionAndController(params, name) {
+  const segments = name.split("/").filter((segment) => segment.length > 0)
+
+  if (segments.length <= 1) {
+    params.action = name
+    return
+  }
+
+  const actionSegment = segments[segments.length - 1]
+  const controllerSuffix = segments.slice(0, -1).join("/")
+  const existingController = typeof params.controller === "string" && params.controller.length > 0 ? params.controller : null
+
+  params.action = actionSegment
+  params.controller = existingController ? `${existingController}/${controllerSuffix}` : controllerSuffix
+}
+
+class VelociousRouteGetRoute extends BaseRoute {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} args.name - Name.
+   */
+  constructor({name, ...restArgs}) {
+    super()
+    restArgsError(restArgs)
+    this.name = name
+    this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+  }
+
+  getHumanPaths() {
+    return [
+      {method: "GET", action: this.name, path: this.name}
+    ]
+  }
+
+  /**
+   * Runs match with path.
+   * @param {object} args - Options object.
+   * @param {Record<string, ?>} args.params - Parameters object.
+   * @param {string} args.path - Path.
+   * @param {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default} args.request - Request object.
+   * @returns {{restPath: string} | undefined} - REST path metadata for this route.
+   */
+  matchWithPath({params, path, request}) { // eslint-disable-line no-unused-vars
+    const match = path.match(this.regExp)
+
+    if (match) {
+      const [_beginnigSlash, _matchedName, restPath] = match
+
+      // Prevent partial prefix matches (e.g., "params" matching "params-with-query")
+      if (restPath && !restPath.startsWith("/")) return
+
+      assignActionAndController(params, this.name)
+
+      return {restPath}
+    }
+  }
+}
+
+BaseRoute.registerRouteGetType(VelociousRouteGetRoute)
+
+export default VelociousRouteGetRoute

package/src/routes/hooks/frontend-model-command-route-hook.js

@@ -0,0 +1,100 @@
+// @ts-check
+
+import {frontendModelActionForCommand, frontendModelCustomCommandForPath, frontendModelResourcePath, frontendModelResourcesForBackendProject} from "../../frontend-models/resource-definition.js"
+
+const SHARED_FRONTEND_MODEL_API_PATH = "/frontend-models"
+const FRONTEND_MODEL_CONTROLLER_PATH = new URL("../../frontend-model-controller.js", import.meta.url).href
+
+/**
+ * Runs frontend model command route hook.
+ * @param {object} args - Hook args.
+ * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+ * @param {string} args.currentPath - Request path without query.
+ * @param {boolean} [args.hasMatchingCustomRoute] - Set when the request path matches an explicit custom route.
+ * @returns {Promise<import("../../configuration-types.js").RouteResolverHookResult | null>} - Route override or null.
+ */
+export default async function frontendModelCommandRouteHook({configuration, currentPath, hasMatchingCustomRoute}) {
+  const normalizedCurrentPath = normalizePath(currentPath)
+
+  if (normalizedCurrentPath === SHARED_FRONTEND_MODEL_API_PATH) {
+    return {
+      action: "frontend-api",
+      controller: "velocious/api",
+      controllerPath: FRONTEND_MODEL_CONTROLLER_PATH
+    }
+  }
+
+  // Don't intercept paths that match explicitly defined custom routes
+  if (hasMatchingCustomRoute) return null
+
+  const backendProjects = configuration.getBackendProjects?.() || []
+  const customCommandMatch = frontendModelCustomCommandForPath({
+    backendProjects,
+    currentPath: normalizedCurrentPath
+  })
+
+  if (customCommandMatch) {
+    /**
+     * Params.
+      @type {Record<string, ?>} */
+    const params = {
+      frontendModelCustomCommandMethodName: customCommandMatch.methodName,
+      frontendModelCustomCommandScope: customCommandMatch.scope,
+      model: customCommandMatch.modelName
+    }
+
+    if (customCommandMatch.memberId) {
+      params.id = customCommandMatch.memberId
+    }
+
+    return {
+      action: "frontend-custom-command",
+      controller: customCommandMatch.resourcePath.replace(/^\/+/, ""),
+      controllerPath: FRONTEND_MODEL_CONTROLLER_PATH,
+      params
+    }
+  }
+
+  for (const backendProject of backendProjects) {
+    const resources = frontendModelResourcesForBackendProject(backendProject)
+
+    for (const modelName in resources) {
+      const resourceDefinition = resources[modelName]
+      const resourcePath = frontendModelResourcePath(modelName, resourceDefinition)
+      const normalizedResourcePath = normalizePath(resourcePath)
+      const expectedPrefix = `${normalizedResourcePath}/`
+
+      if (!normalizedCurrentPath.startsWith(expectedPrefix)) continue
+
+      const commandName = normalizedCurrentPath.slice(expectedPrefix.length)
+      if (commandName.includes("/")) continue
+
+      const action = frontendModelActionForCommand({commandName, modelName, resourceDefinition})
+      if (!action) continue
+      const controller = normalizedResourcePath.replace(/^\/+/, "")
+
+      return {
+        action: `frontend-${action}`,
+        controller,
+        controllerPath: FRONTEND_MODEL_CONTROLLER_PATH
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Runs normalize path.
+ * @param {string} path - Path value.
+ * @returns {string} - Normalized path with leading slash and no trailing slash.
+ */
+function normalizePath(path) {
+  const withLeadingSlash = path.startsWith("/") ? path : `/${path}`
+
+  if (withLeadingSlash.length > 1) {
+    return withLeadingSlash.replace(/\/+$/, "")
+  }
+
+  return withLeadingSlash
+}

package/src/routes/index.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+import GetRoute from "./get-route.js" // eslint-disable-line no-unused-vars
+import NameSpaceRoute from "./namespace-route.js" // eslint-disable-line no-unused-vars
+import PostRoute from "./post-route.js" // eslint-disable-line no-unused-vars
+import RootRoute from "./root-route.js"
+import ResourceRoute from "./resource-route.js" // eslint-disable-line no-unused-vars
+
+export default class VelociousRoutes {
+  rootRoute = new RootRoute()
+
+  /**
+   * Runs draw.
+   * @param {function(import("./root-route.js").default) : void} callback - Callback function.
+   * @returns {void} - No return value.
+   */
+  draw(callback) {
+    callback(this.rootRoute)
+  }
+
+  /**
+   * Collects all `route.mount(...)` registrations across the route tree so the
+   * configuration can apply them when the routes are set.
+   * @returns {Array<{mountable: {mountInto: (args: object) => void}, options: Record<string, ?>}>} - Declared mounts.
+   */
+  getMounts() {
+    /**
+     * Collected.
+      @type {Array<{mountable: {mountInto: (args: object) => void}, options: Record<string, ?>}>} */
+    const collected = []
+
+    /**
+     * Visit.
+     * @param {import("./base-route.js").default} route - Route to visit.
+     */
+    const visit = (route) => {
+      if (typeof route.getMounts === "function") {
+        collected.push(...route.getMounts())
+      }
+
+      for (const subRoute of route.getSubRoutes()) {
+        visit(subRoute)
+      }
+    }
+
+    visit(this.rootRoute)
+
+    return collected
+  }
+}

package/src/routes/namespace-route.js

@@ -0,0 +1,51 @@
+// @ts-check
+
+import restArgsError from "../utils/rest-args-error.js"
+import BaseRoute from "./base-route.js"
+import BasicRoute from "./basic-route.js"
+import escapeStringRegexp from "escape-string-regexp"
+
+class VelociousRouteNamespaceRoute extends BasicRoute {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} args.name - Name.
+   */
+  constructor({name, ...restArgs}) {
+    super()
+    restArgsError(restArgs)
+    this.name = name
+    this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+  }
+
+  getHumanPaths() {
+    return [
+      {method: "GET", action: null, path: this.name}
+    ]
+  }
+
+  /**
+   * Runs match with path.
+   * @param {object} args - Options object.
+   * @param {Record<string, ?>} args.params - Parameters object.
+   * @param {string} args.path - Path.
+   * @param {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default} args.request - Request object.
+   * @returns {{restPath: string} | undefined} - REST path metadata for this route.
+   */
+  matchWithPath({params, path, request}) { // eslint-disable-line no-unused-vars
+    const match = path.match(this.regExp)
+
+    if (match) {
+      const [_beginnigSlash, _matchedName, restPath] = match
+
+      params.controller = this.name
+
+      return {restPath}
+    }
+  }
+}
+
+BaseRoute.registerRouteNamespaceType(VelociousRouteNamespaceRoute)
+
+export default VelociousRouteNamespaceRoute
+

package/src/routes/plugin-routes.js

@@ -0,0 +1,141 @@
+/**
+ * AddRouteOptions type.
+ * @typedef {object} AddRouteOptions
+ * @property {Record<string, ?>} [params] - Static params to merge for matched route.
+ * @property {[typeof import("../controller.js").default, string]} to - Controller class and action tuple.
+ * @property {string} [viewPath] - Optional view path for controllers using renderView().
+ */
+
+/** Lightweight plugin route DSL for route-hook backed endpoints. */
+export default class PluginRoutes {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+   */
+  constructor(args) {
+    const {configuration} = args
+
+    if (!configuration) throw new Error("No configuration given")
+
+    this.configuration = configuration
+  }
+
+  /**
+   * Runs get.
+   * @param {string} routePath - Route path.
+   * @param {AddRouteOptions} options - Route options.
+   * @returns {void} - No return value.
+   */
+  get(routePath, options) {
+    this.addRoute("GET", routePath, options)
+  }
+
+  /**
+   * Runs post.
+   * @param {string} routePath - Route path.
+   * @param {AddRouteOptions} options - Route options.
+   * @returns {void} - No return value.
+   */
+  post(routePath, options) {
+    this.addRoute("POST", routePath, options)
+  }
+
+  /**
+   * Runs add route.
+   * @param {"GET" | "POST"} method - HTTP method.
+   * @param {string} routePath - Route path.
+   * @param {AddRouteOptions} options - Route options.
+   * @returns {void} - No return value.
+   */
+  addRoute(method, routePath, options) {
+    if (typeof routePath !== "string" || !routePath.startsWith("/")) {
+      throw new Error(`Expected route path to be a string starting with '/', got: ${String(routePath)}`)
+    }
+
+    const to = options?.to
+    const staticParams = options?.params
+    const viewPath = options?.viewPath
+    const controllerClass = to?.[0]
+    const action = to?.[1]
+
+    if (typeof action !== "string" || action.length < 1) {
+      throw new Error(`Expected route action to be a non-empty string, got: ${String(action)}`)
+    }
+
+    if (typeof controllerClass !== "function") {
+      throw new Error(`Expected route controller class in 'to: [ControllerClass, action]', got: ${String(controllerClass)}`)
+    }
+
+    const controllerName = typeof controllerClass.name === "string" && controllerClass.name.length > 0
+      ? controllerClass.name
+      : "pluginController"
+
+    if (viewPath !== undefined && typeof viewPath !== "string") {
+      throw new Error(`Expected route viewPath to be a string when provided, got: ${String(viewPath)}`)
+    }
+
+    this.configuration.addRouteResolverHook(({currentPath, request}) => {
+      if (request.httpMethod() !== method) return null
+      const matchedParams = this.matchPath(routePath, currentPath)
+
+      if (!matchedParams) return null
+
+      return {
+        action,
+        controller: controllerName,
+        controllerClass,
+        params: {
+          ...(staticParams || {}),
+          ...matchedParams
+        },
+        viewPath: viewPath || `${this.configuration.getDirectory()}/src/routes`
+      }
+    })
+  }
+
+  /**
+   * Runs match path.
+   * @param {string} routePath - Route pattern.
+   * @param {string} currentPath - Current request path.
+   * @returns {Record<string, string> | null} - Matched params or null.
+   */
+  matchPath(routePath, currentPath) {
+    const routeSegments = routePath.replace(/^\/+|\/+$/g, "").split("/")
+    const currentSegments = currentPath.replace(/^\/+|\/+$/g, "").split("/")
+
+    if (routePath === "/") {
+      return currentPath === "/" ? {} : null
+    }
+
+    if (routeSegments.length !== currentSegments.length) return null
+
+    /**
+     * Params.
+      @type {Record<string, string>} */
+    const params = {}
+
+    for (let index = 0; index < routeSegments.length; index += 1) {
+      const routeSegment = routeSegments[index]
+      const currentSegment = currentSegments[index]
+
+      if (routeSegment.startsWith(":")) {
+        const key = routeSegment.slice(1)
+
+        if (!key) return null
+
+        try {
+          params[key] = decodeURIComponent(currentSegment)
+        } catch {
+          return null
+        }
+
+        continue
+      }
+
+      if (routeSegment !== currentSegment) return null
+    }
+
+    return params
+  }
+}