velocious 1.0.430 → 1.0.431

package/src/frontend-models/resource-config-validation.js

@@ -0,0 +1,56 @@
+// @ts-check
+
+const frontendModelSafeUrlSegmentPattern = /^[A-Za-z0-9_-]+$/u
+
+/**
+ * Runs the validateFrontendModelResourceCommandName helper.
+ * @param {object} args - Args.
+ * @param {string} args.commandName - Command name candidate.
+ * @param {string} args.modelName - Model class name.
+ * @param {string} args.commandType - Command type key.
+ * @returns {string} - Validated command name.
+ */
+export function validateFrontendModelResourceCommandName({commandName, modelName, commandType}) {
+  if (typeof commandName !== "string" || commandName.length < 1) {
+    throw new Error(`Invalid frontend model command for ${modelName}.${commandType}: expected non-empty string`)
+  }
+
+  if (!frontendModelSafeUrlSegmentPattern.test(commandName)) {
+    throw new Error(`Invalid frontend model command for ${modelName}.${commandType}: "${commandName}"`)
+  }
+
+  return commandName
+}
+
+/**
+ * Runs the validateFrontendModelResourcePath helper.
+ * @param {object} args - Args.
+ * @param {string} args.resourcePath - Resource path candidate.
+ * @param {string} args.modelName - Model class name.
+ * @returns {string} - Validated resource path.
+ */
+export function validateFrontendModelResourcePath({resourcePath, modelName}) {
+  if (typeof resourcePath !== "string" || resourcePath.length < 1) {
+    throw new Error(`Invalid frontend model resource path for ${modelName}: expected non-empty string`)
+  }
+
+  if (resourcePath.includes("?") || resourcePath.includes("#")) {
+    throw new Error(`Invalid frontend model resource path for ${modelName}: "${resourcePath}"`)
+  }
+
+  const normalizedPath = resourcePath.replace(/^\/+|\/+$/g, "")
+
+  if (normalizedPath.length < 1) {
+    throw new Error(`Invalid frontend model resource path for ${modelName}: "${resourcePath}"`)
+  }
+
+  const pathSegments = normalizedPath.split("/")
+
+  for (const pathSegment of pathSegments) {
+    if (!frontendModelSafeUrlSegmentPattern.test(pathSegment)) {
+      throw new Error(`Invalid frontend model resource path for ${modelName}: "${resourcePath}"`)
+    }
+  }
+
+  return resourcePath
+}

package/src/frontend-models/resource-definition.js

@@ -0,0 +1,399 @@
+// @ts-check
+
+import * as inflection from "inflection"
+import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
+import restArgsError from "../utils/rest-args-error.js"
+import {validateFrontendModelResourceCommandName} from "./resource-config-validation.js"
+
+/**
+ * Runs the frontendModelResourcesForBackendProject helper.
+ * @param {import("../configuration-types.js").BackendProjectConfiguration} backendProject - Backend project config.
+ * @returns {Record<string, typeof FrontendModelBaseResource>} - Resource definitions keyed by model name.
+ */
+export function frontendModelResourcesForBackendProject(backendProject) {
+  const resources = backendProject.frontendModels
+
+  if (resources !== undefined) {
+    if (!resources || typeof resources !== "object") {
+      throw new Error(`Expected backend project frontendModels object but got: ${resources}`)
+    }
+
+    return resources
+  }
+
+  return {}
+}
+
+/**
+ * Runs the frontendModelResourceDefinitionIsClass helper.
+ * @param {?} value - Candidate resource definition.
+ * @returns {value is typeof FrontendModelBaseResource} - Whether value is a resource class.
+ */
+export function frontendModelResourceDefinitionIsClass(value) {
+  return typeof value === "function" && (value === FrontendModelBaseResource || value.prototype instanceof FrontendModelBaseResource)
+}
+
+/**
+ * Runs the frontendModelResourceClassFromDefinition helper.
+ * @param {?} resourceDefinition - Resource definition.
+ * @returns {typeof FrontendModelBaseResource | null} - Resource class when definition is class-based.
+ */
+export function frontendModelResourceClassFromDefinition(resourceDefinition) {
+  return frontendModelResourceDefinitionIsClass(resourceDefinition) ? resourceDefinition : null
+}
+
+/**
+ * Runs the frontendModelResourceConfigurationFromDefinition helper.
+ * @param {?} resourceDefinition - Resource definition.
+ * @returns {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | null} - Normalized resource configuration.
+ */
+export function frontendModelResourceConfigurationFromDefinition(resourceDefinition) {
+  if (!frontendModelResourceDefinitionIsClass(resourceDefinition)) return null
+
+  return normalizeFrontendModelResourceConfiguration(resourceDefinition.resourceConfig())
+}
+
+/**
+ * Runs normalize frontend model resource configuration.
+ * @param {import("../configuration-types.js").FrontendModelResourceConfiguration} resourceConfiguration - Raw resource configuration.
+ * @returns {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration} - Normalized resource configuration.
+ */
+function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
+  const restArgs = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {Record<string, ?>} */ ({...resourceConfiguration})
+
+  for (const key of [
+    "abilities",
+    "attributes",
+    "attachments",
+    "builtInCollectionCommands",
+    "builtInMemberCommands",
+    "collectionCommands",
+    "commands",
+    "memberCommands",
+    "modelName",
+    "primaryKey",
+    "relationships",
+    "server"
+  ]) {
+    delete restArgs[key]
+  }
+
+  restArgsError(restArgs)
+
+  const normalizedCommands = normalizeFrontendModelResourceCommands(resourceConfiguration)
+
+  return {
+    ...resourceConfiguration,
+    abilities: normalizeFrontendModelResourceAbilities(resourceConfiguration.abilities),
+    builtInCollectionCommands: normalizedCommands.builtInCollectionCommands,
+    builtInMemberCommands: normalizedCommands.builtInMemberCommands,
+    collectionCommands: normalizedCommands.collectionCommands,
+    memberCommands: normalizedCommands.memberCommands
+  }
+}
+
+/**
+ * Runs normalize frontend model resource abilities.
+ * @param {string[] | undefined} abilities - Resource abilities config (camelCase action list).
+ * @returns {Record<string, string>} - Normalized abilities config.
+ */
+function normalizeFrontendModelResourceAbilities(abilities) {
+  if (abilities === undefined) {
+    return defaultCrudAbilities()
+  }
+
+  if (!Array.isArray(abilities)) {
+    throw new Error("Resource abilities must be an array of action names. Object form is no longer supported.")
+  }
+
+  if (abilities.includes("manage")) {
+    return {
+      create: "manage",
+      destroy: "manage",
+      find: "manage",
+      index: "manage",
+      update: "manage"
+    }
+  }
+
+  /**
+   * Normalized.
+    @type {Record<string, string>} */
+  const normalized = {}
+
+  if (abilities.includes("create")) normalized.create = "create"
+  if (abilities.includes("destroy")) normalized.destroy = "destroy"
+  if (abilities.includes("read")) {
+    normalized.find = "read"
+    normalized.index = "read"
+  }
+  if (abilities.includes("update")) normalized.update = "update"
+
+  return normalized
+}
+
+/**
+ * Runs default crud abilities.
+ * @returns {Record<string, string>} - Default CRUD ability map.
+ */
+function defaultCrudAbilities() {
+  return {
+    create: "create",
+    destroy: "destroy",
+    find: "read",
+    index: "read",
+    update: "update"
+  }
+}
+
+/**
+ * Runs normalize frontend model resource commands.
+ * @param {import("../configuration-types.js").FrontendModelResourceConfiguration} resourceConfiguration - Raw resource configuration.
+ * @returns {{builtInCollectionCommands: Record<string, string>, builtInMemberCommands: Record<string, string>, collectionCommands: Record<string, string>, memberCommands: Record<string, string>}} - Normalized command configuration.
+ */
+function normalizeFrontendModelResourceCommands(resourceConfiguration) {
+  const builtInCollectionCommands = resourceConfiguration.builtInCollectionCommands
+  const builtInMemberCommands = resourceConfiguration.builtInMemberCommands
+  const customCollectionCommands = resourceConfiguration.collectionCommands
+  const customMemberCommands = resourceConfiguration.memberCommands
+  const normalizedBuiltInCollectionCommands = normalizeFrontendModelBuiltInCommands({
+    commandDefaults: {
+      create: "create",
+      index: "index"
+    },
+    commandsConfig: builtInCollectionCommands,
+    modelName: "CollectionCommand"
+  })
+  const normalizedBuiltInMemberCommands = normalizeFrontendModelBuiltInCommands({
+    commandDefaults: {
+      attach: "attach",
+      destroy: "destroy",
+      download: "download",
+      find: "find",
+      update: "update",
+      url: "url"
+    },
+    commandsConfig: builtInMemberCommands,
+    modelName: "MemberCommand"
+  })
+
+  return {
+    builtInCollectionCommands: normalizedBuiltInCollectionCommands,
+    builtInMemberCommands: normalizedBuiltInMemberCommands,
+    collectionCommands: normalizeFrontendModelCustomCommands({commandsConfig: customCollectionCommands, modelName: "CollectionCommand"}),
+    memberCommands: normalizeFrontendModelCustomCommands({commandsConfig: customMemberCommands, modelName: "MemberCommand"})
+  }
+}
+
+/**
+ * Runs normalize frontend model built in commands.
+ * @param {object} args - Arguments.
+ * @param {Record<string, string>} args.commandDefaults - Built-in default command names.
+ * @param {string[] | undefined} args.commandsConfig - Built-in commands config (camelCase command type list).
+ * @param {string} args.modelName - Diagnostic model name.
+ * @returns {Record<string, string>} - Normalized built-in command config.
+ */
+function normalizeFrontendModelBuiltInCommands({commandDefaults, commandsConfig, modelName}) {
+  if (!commandsConfig) {
+    return commandDefaults
+  }
+
+  if (!Array.isArray(commandsConfig)) {
+    throw new Error(`${modelName} configuration must use the array form. Object form is no longer supported.`)
+  }
+
+  /**
+   * Normalized commands.
+    @type {Record<string, string>} */
+  const normalizedCommands = {}
+
+  for (const commandType of commandsConfig) {
+    const defaultCommandName = commandDefaults[commandType]
+
+    if (!defaultCommandName) {
+      throw new Error(`Unknown built-in frontend model command '${commandType}' for ${modelName}`)
+    }
+
+    normalizedCommands[commandType] = validateFrontendModelResourceCommandName({
+      commandName: defaultCommandName,
+      commandType: defaultCommandName,
+      modelName
+    })
+  }
+
+  return normalizedCommands
+}
+
+/**
+ * Runs normalize frontend model custom commands.
+ * @param {object} args - Arguments.
+ * @param {string[] | undefined} args.commandsConfig - Custom commands config (camelCase method-name list).
+ * @param {string} args.modelName - Diagnostic model name.
+ * @returns {Record<string, string>} - Normalized custom command config (camelCase method name → kebab-case command slug).
+ */
+function normalizeFrontendModelCustomCommands({commandsConfig, modelName}) {
+  if (!commandsConfig) {
+    return {}
+  }
+
+  if (!Array.isArray(commandsConfig)) {
+    throw new Error(`${modelName} configuration must use the array form. Object form is no longer supported.`)
+  }
+
+  /**
+   * Normalized commands.
+    @type {Record<string, string>} */
+  const normalizedCommands = {}
+
+  for (const methodName of commandsConfig) {
+    const validatedMethodName = validateFrontendModelResourceCommandName({
+      commandName: methodName,
+      commandType: methodName,
+      modelName
+    })
+    const commandSlug = inflection.dasherize(inflection.underscore(validatedMethodName))
+
+    normalizedCommands[validatedMethodName] = commandSlug
+  }
+
+  return normalizedCommands
+}
+
+/**
+ * Runs the frontendModelResourcePath helper.
+ * @param {string} modelName - Model class name.
+ * @param {?} resourceDefinition - Resource definition.
+ * @returns {string} - Normalized resource path.
+ */
+export function frontendModelResourcePath(modelName, resourceDefinition) {
+  const resourceConfiguration = frontendModelResourceConfigurationFromDefinition(resourceDefinition)
+
+  if (!resourceConfiguration) {
+    throw new Error(`Invalid frontend model resource definition for ${modelName}`)
+  }
+
+  return `/${inflection.dasherize(inflection.pluralize(inflection.underscore(modelName)))}`
+}
+
+/**
+ * Runs the frontendModelActionForCommand helper.
+ * @param {object} args - Arguments.
+ * @param {string} args.commandName - Command path segment.
+ * @param {string} args.modelName - Model class name.
+ * @param {?} args.resourceDefinition - Resource definition.
+ * @returns {"destroy" | "find" | "index" | "create" | "update" | "attach" | "download" | "url" | null} - Frontend action.
+ */
+export function frontendModelActionForCommand({commandName, modelName, resourceDefinition}) {
+  const resourceConfiguration = frontendModelResourceConfigurationFromDefinition(resourceDefinition)
+
+  if (!resourceConfiguration) {
+    throw new Error(`Invalid frontend model resource definition for ${modelName}`)
+  }
+
+  for (const [action, configuredCommandName] of Object.entries({
+    ...resourceConfiguration.builtInCollectionCommands,
+    ...resourceConfiguration.builtInMemberCommands
+  })) {
+    if (configuredCommandName === undefined) continue
+
+    const validatedCommandName = validateFrontendModelResourceCommandName({
+      commandName: configuredCommandName,
+      commandType: /**
+                    * Narrows the runtime value to the documented type.
+                     @type {"attach" | "create" | "destroy" | "download" | "find" | "index" | "update" | "url"} */ (action),
+      modelName
+    })
+
+    if (commandName === validatedCommandName) {
+      return /** Narrows the runtime value to the documented type. @type {"attach" | "create" | "destroy" | "download" | "find" | "index" | "update" | "url"} */ (action)
+    }
+  }
+
+  return null
+}
+
+/**
+ * Runs the frontendModelCustomCommandForPath helper.
+ * @param {object} args - Arguments.
+ * @param {import("../configuration-types.js").BackendProjectConfiguration[]} args.backendProjects - Backend projects to scan.
+ * @param {string} args.currentPath - Request path without query.
+ * @returns {{commandName: string, memberId?: string, methodName: string, modelName: string, resourcePath: string, scope: "collection" | "member"} | null} - Matched custom command metadata.
+ */
+export function frontendModelCustomCommandForPath({backendProjects, currentPath}) {
+  const normalizedCurrentPath = normalizeFrontendModelResourcePathForMatch(currentPath)
+
+  for (const backendProject of backendProjects) {
+    const resources = frontendModelResourcesForBackendProject(backendProject)
+
+    for (const modelName in resources) {
+      const resourceDefinition = resources[modelName]
+      const resourceConfiguration = frontendModelResourceConfigurationFromDefinition(resourceDefinition)
+
+      if (!resourceConfiguration) {
+        continue
+      }
+
+      const resourcePath = normalizeFrontendModelResourcePathForMatch(frontendModelResourcePath(modelName, resourceDefinition))
+      const expectedPrefix = `${resourcePath}/`
+
+      if (!normalizedCurrentPath.startsWith(expectedPrefix)) {
+        continue
+      }
+
+      const pathSegments = normalizedCurrentPath
+        .slice(expectedPrefix.length)
+        .split("/")
+        .filter(Boolean)
+
+      if (pathSegments.length === 1) {
+        const matchedCollectionCommand = Object.entries(resourceConfiguration.collectionCommands)
+          .find(([, commandName]) => commandName === pathSegments[0])
+
+        if (matchedCollectionCommand) {
+          return {
+            commandName: matchedCollectionCommand[1],
+            methodName: matchedCollectionCommand[0],
+            modelName,
+            resourcePath,
+            scope: "collection"
+          }
+        }
+      }
+
+      if (pathSegments.length === 2) {
+        const matchedMemberCommand = Object.entries(resourceConfiguration.memberCommands)
+          .find(([, commandName]) => commandName === pathSegments[1])
+
+        if (matchedMemberCommand) {
+          return {
+            commandName: matchedMemberCommand[1],
+            memberId: decodeURIComponent(pathSegments[0]),
+            methodName: matchedMemberCommand[0],
+            modelName,
+            resourcePath,
+            scope: "member"
+          }
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Runs normalize frontend model resource path for match.
+ * @param {string} path - Path value.
+ * @returns {string} - Normalized path with leading slash and no trailing slash.
+ */
+function normalizeFrontendModelResourcePathForMatch(path) {
+  const withLeadingSlash = path.startsWith("/") ? path : `/${path}`
+
+  if (withLeadingSlash.length > 1) {
+    return withLeadingSlash.replace(/\/+$/, "")
+  }
+
+  return withLeadingSlash
+}