@api-client/core 0.20.6 → 0.20.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.20.6",
+  "version": "0.20.7",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {
@@ -105,8 +105,8 @@
     "xpath": "^0.0.34"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.1.0",
-    "@commitlint/config-conventional": "^20.0.0",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@eslint/js": "^10.0.1",
     "@japa/assert": "^4.0.1",
     "@japa/runner": "^5.3.0",

package/src/modeling/ExposedEntity.ts

@@ -5,7 +5,7 @@ import { nanoid } from '../nanoid.js'
 import { Action } from './actions/Action.js'
 import { ActionKind, type ApiActionSchema, createActionFromKind, restoreAction } from './actions/index.js'
 import type { ApiModel } from './ApiModel.js'
-import { ensureLeadingSlash, joinPaths } from './helpers/endpointHelpers.js'
+import { ensureLeadingSlash, joinPaths, paramNameFor } from './helpers/endpointHelpers.js'
 import { AccessRule } from './rules/AccessRule.js'
 import { type RateLimitRule, restoreAccessRule } from './rules/index.js'
 import { RateLimitingConfiguration } from './rules/RateLimitingConfiguration.js'
@@ -302,16 +302,33 @@ export class ExposedEntity extends EventTarget {
       }
     }
 
-    // Preserve current parameter name if present, otherwise default to {id}
-    let param = '{id}'
-    if (this.resourcePath) {
+    // Preserve current parameter name if present, otherwise default to semantic param name
+    let param = ''
+    if (this.resourcePath && this.resourcePath !== '/') {
       const curSegments = this.resourcePath.split('/').filter(Boolean)
       const maybeParam = curSegments[1]
       if (maybeParam && /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(maybeParam)) {
         param = maybeParam
       }
     }
+
+    if (!param) {
+      const entityObj = this.api.domain?.findEntity(this.entity.key, this.entity.domain)
+      if (!entityObj || !entityObj.info.name) {
+        // Never fall back to a default like '{id}' here. Silent param generation failures must throw
+        // to prevent runtime/OAS collisions.
+        throw new Exception(
+          'Cannot generate a semantic parameter name because the associated entity or its name is missing.',
+          {
+            code: 'E_ENTITY_NOT_FOUND',
+            help: 'Ensure the exposed entity points to a valid domain entity with a defined name.',
+          }
+        )
+      }
+      param = `{${paramNameFor(entityObj.info.name)}}`
+    }
     const nextResource = `${normalizedCollection}/${param}`
+    this.#validateParameterCollisions(nextResource)
     this.collectionPath = normalizedCollection
     this.resourcePath = nextResource
     // rely on ApiModel.exposes deep observation to notify on property sets
@@ -372,6 +389,7 @@ export class ExposedEntity extends EventTarget {
         })
       }
       if (this.resourcePath !== cleaned) {
+        this.#validateParameterCollisions(`/${s1}/${s2}`)
         this.resourcePath = `/${s1}/${s2}`
       }
       return
@@ -399,10 +417,50 @@ export class ExposedEntity extends EventTarget {
     }
 
     if (this.resourcePath !== cleaned) {
+      this.#validateParameterCollisions(`/${segments[0]}`)
       this.resourcePath = `/${segments[0]}`
     }
   }
 
+  #checkDuplicatesInPaths(paths: string[]) {
+    const absolute = paths.join('/')
+    const params = [...absolute.matchAll(/\{([^}]+)\}/g)].map((m) => m[1])
+    const seen = new Set<string>()
+    for (const p of params) {
+      if (seen.has(p)) {
+        throw new Exception(`Duplicate path parameter "{${p}}" detected in branch hierarchy.`, {
+          code: 'E_PATH_PARAM_COLLISION',
+          help: 'Change the parameter name in either this resource or its ancestor to ensure unique parameter names.',
+        })
+      }
+      seen.add(p)
+    }
+  }
+
+  #validateDescendantCollisions(parentKey: string, ancestorPaths: string[]) {
+    for (const exposure of this.api.exposes.values()) {
+      if (exposure.parent?.key === parentKey) {
+        const currentPaths = [...ancestorPaths, exposure.resourcePath]
+        this.#checkDuplicatesInPaths(currentPaths)
+        this.#validateDescendantCollisions(exposure.key, currentPaths)
+      }
+    }
+  }
+
+  #validateParameterCollisions(tempResourcePath: string) {
+    const paths: string[] = [tempResourcePath]
+    let parentKey = this.parent?.key
+    while (parentKey) {
+      const parent = this.api.exposes.get(parentKey)
+      if (!parent) break
+      paths.unshift(parent.resourcePath)
+      parentKey = parent.parent?.key
+    }
+
+    this.#checkDuplicatesInPaths(paths)
+    this.#validateDescendantCollisions(this.key, paths)
+  }
+
   /**
    * Computes the absolute path for this exposure's resource endpoint by
    * walking up the exposure tree using `parent.key` until reaching a root exposure.

package/src/modeling/RuntimeApiModel.ts

@@ -166,10 +166,15 @@ export class RuntimeApiModel extends ApiModel {
   constructor(schema: RuntimeApiModelSchema, domainSchema: DataDomainSchema) {
     super(schema, domainSchema)
 
-    if (schema.routingMap) {
-      this.#initializeRouter(schema.routingMap)
+    if (!schema.routingMap) {
+      throw new Exception('The runtime API model must have a routing map.', {
+        code: 'E_MISSING_ROUTING_MAP',
+        help: 'Ensure that the routingMap property is defined when creating a RuntimeApiModel.',
+      })
     }
 
+    this.#initializeRouter(schema.routingMap)
+
     this.#cacheEntitiesAndProperties()
     this.#precomputeAccessRules()
     this.#precomputeSessionProperties()

package/src/modeling/generators/RuntimeModelGenerator.ts

@@ -0,0 +1,79 @@
+import { type ActionKind, type UpdateAction } from '../actions/index.js'
+import { ApiModel, type ApiModelSchema } from '../ApiModel.js'
+import { type RouteDefinition, type RuntimeApiModelSchema } from '../RuntimeApiModel.js'
+
+/**
+ * A class that takes the API model and generates a runtime-optimized API model.
+ *
+ * Note, the API model must be already validated before passing it to this generator.
+ * This class doesn't perform any validation, but it will throw an exception if the API model is invalid.
+ */
+export class RuntimeModelGenerator {
+  #apiModel: ApiModel
+  #apiSchema: ApiModelSchema
+  #routingMap: Record<string, RouteDefinition[]> = {}
+
+  constructor(input: ApiModel | ApiModelSchema) {
+    if (input instanceof ApiModel) {
+      this.#apiModel = input
+      this.#apiSchema = input.toJSON()
+    } else {
+      this.#apiModel = new ApiModel(input)
+      this.#apiSchema = input
+    }
+  }
+
+  public async generate(): Promise<RuntimeApiModelSchema> {
+    if (!this.#apiModel) {
+      throw new Error('API model is not defined')
+    }
+
+    for (const expose of this.#apiModel.exposes.values()) {
+      const colPath = expose.getAbsoluteCollectionPath()
+      const resPath = expose.getAbsoluteResourcePath()
+      for (const action of expose.actions) {
+        switch (action.kind) {
+          case 'list':
+            if (colPath) this.addRoute('GET', colPath, expose.key, action.kind)
+            break
+          case 'create':
+            if (colPath) this.addRoute('POST', colPath, expose.key, action.kind)
+            break
+          case 'search':
+            if (colPath) this.addRoute('POST', `${colPath}/search`, expose.key, action.kind)
+            break
+          case 'read':
+            if (resPath) this.addRoute('GET', resPath, expose.key, action.kind)
+            break
+          case 'update':
+            if (resPath) {
+              const updateAction = action as UpdateAction
+              for (const method of updateAction.allowedMethods) {
+                this.addRoute(method, resPath, expose.key, action.kind)
+              }
+            }
+            break
+          case 'delete':
+            if (resPath) this.addRoute('DELETE', resPath, expose.key, action.kind)
+            break
+        }
+      }
+    }
+
+    return {
+      ...this.#apiSchema,
+      routingMap: this.#routingMap,
+    }
+  }
+
+  private addRoute(method: string, path: string, exposedEntityKey: string, actionKind: ActionKind): void {
+    const upperMethod = method.toUpperCase()
+    if (!this.#routingMap[upperMethod]) {
+      this.#routingMap[upperMethod] = []
+    }
+    this.#routingMap[upperMethod].push({
+      path,
+      lookup: { exposedEntityKey, actionKind },
+    })
+  }
+}

package/src/modeling/helpers/endpointHelpers.ts

@@ -1,7 +1,54 @@
-export function paramNameFor(entityKeyLocal: string): string {
-  const parts = entityKeyLocal.split(':')
-  const key = parts[parts.length - 1]
-  return `${key}Id`
+import { Exception } from '../../exceptions/exception.js'
+
+/**
+ * Generates a semantic parameter name for an entity.
+ * It converts snake_case, kebab-case, or PascalCase to camelCase and appends 'Id'.
+ * @param entityName The entity name (e.g. from entity.info.name)
+ */
+export function paramNameFor(entityName: string): string {
+  if (!entityName) {
+    throw new Exception('Cannot generate parameter name from an empty string.', {
+      code: 'E_INVALID_PARAM_NAME',
+      help: 'The entity name used for path parameter generation is empty.',
+    })
+  }
+
+  // Add a space between lowercase and uppercase letters to handle camelCase/PascalCase
+  let withSpaces = entityName.replace(/([a-z])([A-Z])/g, '$1 $2')
+  // Also split consecutive uppercase letters if followed by a lowercase (e.g. XMLHttp -> XML Http)
+  withSpaces = withSpaces.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+
+  // Replace all non-alphanumeric characters with spaces
+  const cleanStr = withSpaces.replace(/[^a-zA-Z0-9]/g, ' ')
+
+  // Split by spaces and filter out empty strings
+  const words = cleanStr.split(/\s+/).filter(Boolean)
+
+  if (words.length === 0) {
+    throw new Exception(`Cannot generate a valid parameter name from "${entityName}".`, {
+      code: 'E_INVALID_PARAM_NAME',
+      help: 'The entity name must contain alphanumeric characters to generate a path parameter.',
+    })
+  }
+
+  // CamelCase: lower first word, Capitalize subsequent words
+  const camelCased = words
+    .map((word, index) => {
+      const lower = word.toLowerCase()
+      if (index === 0) {
+        return lower
+      }
+      return lower.charAt(0).toUpperCase() + lower.slice(1)
+    })
+    .join('')
+
+  // Ensure it starts with a letter or underscore
+  let param = camelCased
+  if (/^[0-9]/.test(param)) {
+    param = '_' + param
+  }
+
+  return `${param}Id`
 }
 
 /**

package/src/modeling/validation/api_model_rules.ts

@@ -581,6 +581,25 @@ export function validateExposedEntity(exposure: ExposedEntity, apiModel: ApiMode
     }
   }
 
+  // Branch Path Parameter Collision
+  const absoluteResourcePath = exposure.getAbsoluteResourcePath()
+  if (absoluteResourcePath) {
+    const params = [...absoluteResourcePath.matchAll(/\{([^}]+)\}/g)].map((m) => m[1])
+    const uniqueParams = new Set(params)
+    if (uniqueParams.size !== params.length) {
+      const duplicates = params.filter((item, index) => params.indexOf(item) !== index)
+      const duplicateParam = duplicates[0]
+      issues.push({
+        code: createCode('EXPOSURE', 'DUPLICATE_PATH_PARAMETER'),
+        message: `[${entityName}]: The path parameter "{${duplicateParam}}" is duplicated in the resource path hierarchy.`,
+        suggestion:
+          'Change the parameter name in either this resource or its ancestor to ensure unique parameter names.',
+        severity: 'error',
+        context: { ...context, property: 'resourcePath' },
+      })
+    }
+  }
+
   // Minimum Actions
   if (!exposure.actions || exposure.actions.length === 0) {
     issues.push({

package/tests/unit/modeling/RuntimeApiModel.spec.ts

@@ -34,6 +34,20 @@ test.group('RuntimeApiModel', () => {
     assert.deepEqual(runtimeModel.toJSON().routingMap, schema.routingMap)
   }).tags(['@modeling', '@runtime'])
 
+  test('throws error if routingMap is missing', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const schema = {
+      key: 'api-1',
+      info: { name: 'Test API' },
+      // routingMap is intentionally missing
+    }
+
+    assert.throws(
+      () => new RuntimeApiModel(schema as any, domain.toJSON()),
+      'The runtime API model must have a routing map.'
+    )
+  }).tags(['@modeling', '@runtime'])
+
   test('resolves path with matchit', ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const model = domain.addModel({ info: { name: 'Test Model' } })
@@ -311,7 +325,7 @@ test.group('RuntimeApiModel', () => {
       { key: 'api-1', accessRule: [{ type: 'allowAuthenticated', mandatory: true }] },
       domain
     )
-    const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
+    const runtimeModel = new RuntimeApiModel({ ...baseModel.toJSON(), routingMap: {} } as any, domain.toJSON())
 
     const mockAction = {
       exposure: { accessRule: [], parent: undefined },
@@ -327,7 +341,7 @@ test.group('RuntimeApiModel', () => {
   test('getEffectiveRules - defaults to preFetch phase if none specified', async ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const baseModel = new ApiModel({ key: 'api-1' }, domain)
-    const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
+    const runtimeModel = new RuntimeApiModel({ ...baseModel.toJSON(), routingMap: {} } as any, domain.toJSON())
 
     const mockAction = {
       exposure: {
@@ -345,7 +359,7 @@ test.group('RuntimeApiModel', () => {
   test('getEffectiveRules - orders from most specific to most general', async ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const baseModel = new ApiModel({ accessRule: [{ type: 'allowAuthenticated' }] }, domain)
-    const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
+    const runtimeModel = new RuntimeApiModel({ ...baseModel.toJSON(), routingMap: {} } as any, domain.toJSON())
 
     const mockAction = {
       exposure: {

package/tests/unit/modeling/exposed_entity.spec.ts

@@ -18,6 +18,41 @@ test.group('ExposedEntity', () => {
     assert.equal(ex.resourcePath, '/products/{customId}')
   }).tags(['@modeling', '@exposed-entity'])
 
+  test('setCollectionPath throws if semantic param cannot be generated', ({ assert }) => {
+    const model = new ApiModel()
+    const ex = new ExposedEntity(model, {
+      entity: { key: 'missing' },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/', // Forces param generation
+    })
+
+    assert.throws(() => ex.setCollectionPath('products'), 'Cannot generate a semantic parameter name')
+  }).tags(['@modeling', '@exposed-entity'])
+
+  test('setCollectionPath generates semantic param from domain entity', ({ assert }) => {
+    const domain = new DataDomain()
+    domain.info.version = '1.0.0'
+    const dm = domain.addModel()
+    const entity = domain.addEntity(dm.key)
+    entity.info.name = 'user_post'
+
+    const model = new ApiModel()
+    model.attachDataDomain(domain)
+
+    const ex = new ExposedEntity(model, {
+      entity: { key: entity.key },
+      hasCollection: true,
+      collectionPath: '/items',
+      resourcePath: '/', // Forces param generation
+    })
+
+    ex.setCollectionPath('user-posts')
+
+    assert.equal(ex.collectionPath, '/user-posts')
+    assert.equal(ex.resourcePath, '/user-posts/{userPostId}')
+  }).tags(['@modeling', '@exposed-entity'])
+
   test('setResourcePath with collection allows only parameter name change', ({ assert }) => {
     const model = new ApiModel()
     const ex = new ExposedEntity(model, {
@@ -104,6 +139,66 @@ test.group('ExposedEntity', () => {
     assert.equal(grandEx.getAbsoluteResourcePath(), '/users/{userId}/posts/{postId}/details')
   }).tags(['@modeling', '@exposed-entity'])
 
+  test('rejects branch collision when modifying collection path', ({ assert }) => {
+    const model = new ApiModel()
+    const rootSchema: Partial<ExposedEntitySchema> = {
+      key: 'root',
+      entity: { key: 'user' },
+      hasCollection: true,
+      collectionPath: '/users',
+      resourcePath: '/users/{userId}',
+      isRoot: true,
+    }
+    const childSchema: Partial<ExposedEntitySchema> = {
+      key: 'child',
+      entity: { key: 'post' },
+      hasCollection: true,
+      collectionPath: '/posts',
+      resourcePath: '/posts/{postId}',
+      parent: { key: 'root', association: { key: 'toPosts' } },
+    }
+
+    const rootEx = new ExposedEntity(model, rootSchema)
+    const childEx = new ExposedEntity(model, childSchema)
+    model.exposes = new Map([
+      [rootEx.key, rootEx],
+      [childEx.key, childEx],
+    ])
+
+    // Modifying child's collection path to reuse 'userId'
+    assert.throws(() => childEx.setResourcePath('/posts/{userId}'), 'Duplicate path parameter "{userId}" detected')
+  }).tags(['@modeling', '@exposed-entity', '@collision'])
+
+  test('rejects branch collision from descendant when modifying ancestor resource path', ({ assert }) => {
+    const model = new ApiModel()
+    const rootSchema: Partial<ExposedEntitySchema> = {
+      key: 'root',
+      entity: { key: 'user' },
+      hasCollection: true,
+      collectionPath: '/users',
+      resourcePath: '/users/{userId}',
+      isRoot: true,
+    }
+    const childSchema: Partial<ExposedEntitySchema> = {
+      key: 'child',
+      entity: { key: 'post' },
+      hasCollection: true,
+      collectionPath: '/posts',
+      resourcePath: '/posts/{postId}',
+      parent: { key: 'root', association: { key: 'toPosts' } },
+    }
+
+    const rootEx = new ExposedEntity(model, rootSchema)
+    const childEx = new ExposedEntity(model, childSchema)
+    model.exposes = new Map([
+      [rootEx.key, rootEx],
+      [childEx.key, childEx],
+    ])
+
+    // Modifying root's resource path to 'postId' which collides with child
+    assert.throws(() => rootEx.setResourcePath('/users/{postId}'), 'Duplicate path parameter "{postId}" detected')
+  }).tags(['@modeling', '@exposed-entity', '@collision'])
+
   test('ApiModel notifies when nested ExposedEntity collection path changes', async ({ assert }) => {
     const model = new ApiModel({
       exposes: [

package/tests/unit/modeling/generators/RuntimeModelGenerator.spec.ts

@@ -0,0 +1,192 @@
+import { test } from '@japa/runner'
+import { ApiModel } from '../../../../src/modeling/ApiModel.js'
+import { ExposedEntityKind } from '../../../../src/models/index.js'
+import { RuntimeModelGenerator } from '../../../../src/modeling/generators/RuntimeModelGenerator.js'
+import { ApiModelKind } from '../../../../src/models/index.js'
+import type { UpdateActionSchema } from '../../../../src/modeling/actions/index.js'
+
+test.group('RuntimeModelGenerator', () => {
+  test('generates routes from an ApiModel instance', async ({ assert }) => {
+    const apiModel = new ApiModel({
+      key: 'test-api',
+      exposes: [
+        {
+          key: 'users',
+          kind: ExposedEntityKind,
+          entity: { key: 'user' },
+          resourcePath: '/users/{id}',
+          collectionPath: '/users',
+          hasCollection: true,
+          isRoot: true,
+          actions: [
+            { kind: 'list' },
+            { kind: 'create' },
+            { kind: 'search' },
+            { kind: 'read' },
+            { kind: 'update', allowedMethods: ['PUT', 'PATCH'] } as UpdateActionSchema,
+            { kind: 'delete' },
+          ],
+        },
+      ],
+    })
+
+    const generator = new RuntimeModelGenerator(apiModel)
+    const result = await generator.generate()
+
+    assert.equal(result.key, 'test-api')
+    assert.deepEqual(result.routingMap['GET']![0], {
+      path: '/users',
+      lookup: { exposedEntityKey: 'users', actionKind: 'list' },
+    })
+
+    assert.deepEqual(result.routingMap['GET']![1], {
+      path: '/users/{id}',
+      lookup: { exposedEntityKey: 'users', actionKind: 'read' },
+    })
+
+    assert.deepEqual(result.routingMap['POST']![0], {
+      path: '/users',
+      lookup: { exposedEntityKey: 'users', actionKind: 'create' },
+    })
+
+    assert.deepEqual(result.routingMap['POST']![1], {
+      path: '/users/search',
+      lookup: { exposedEntityKey: 'users', actionKind: 'search' },
+    })
+
+    assert.deepEqual(result.routingMap['PUT']![0], {
+      path: '/users/{id}',
+      lookup: { exposedEntityKey: 'users', actionKind: 'update' },
+    })
+
+    assert.deepEqual(result.routingMap['PATCH']![0], {
+      path: '/users/{id}',
+      lookup: { exposedEntityKey: 'users', actionKind: 'update' },
+    })
+
+    assert.deepEqual(result.routingMap['DELETE']![0], {
+      path: '/users/{id}',
+      lookup: { exposedEntityKey: 'users', actionKind: 'delete' },
+    })
+  }).tags(['@modeling', '@generator'])
+
+  test('generates routes from an ApiModelSchema object', async ({ assert }) => {
+    const schema = {
+      kind: ApiModelKind,
+      key: 'test-api-schema',
+      exposes: [
+        {
+          key: 'posts',
+          kind: ExposedEntityKind,
+          entity: { key: 'post' },
+          resourcePath: '/posts/{id}',
+          collectionPath: '/posts',
+          hasCollection: true,
+          isRoot: true,
+          actions: [{ kind: 'list' }],
+        },
+      ],
+    }
+
+    const generator = new RuntimeModelGenerator(schema as any)
+    const result = await generator.generate()
+
+    assert.equal(result.key, 'test-api-schema')
+    assert.lengthOf(result.routingMap['GET'] || [], 1)
+    assert.deepEqual(result.routingMap['GET']![0], {
+      path: '/posts',
+      lookup: { exposedEntityKey: 'posts', actionKind: 'list' },
+    })
+  }).tags(['@modeling', '@generator'])
+
+  test('handles entities without collection paths safely', async ({ assert }) => {
+    const apiModel = new ApiModel({
+      key: 'test-api',
+      exposes: [
+        {
+          key: 'singleton',
+          kind: ExposedEntityKind,
+          entity: { key: 'config' },
+          resourcePath: '/singleton',
+          hasCollection: false,
+          isRoot: true,
+          actions: [{ kind: 'list' }, { kind: 'create' }, { kind: 'search' }],
+        },
+      ],
+    })
+
+    const generator = new RuntimeModelGenerator(apiModel)
+    const result = await generator.generate()
+
+    // Without a collection path, list, create, search should be ignored.
+    assert.deepEqual(result.routingMap, {})
+  }).tags(['@modeling', '@generator'])
+
+  test('generates routes for nested entities (sub-endpoints)', async ({ assert }) => {
+    const apiModel = new ApiModel({
+      key: 'test-api',
+      exposes: [
+        {
+          key: 'users',
+          kind: ExposedEntityKind,
+          entity: { key: 'user' },
+          resourcePath: '/users/{userId}',
+          collectionPath: '/users',
+          hasCollection: true,
+          isRoot: true,
+          actions: [{ kind: 'read' }],
+        },
+        {
+          key: 'user-posts',
+          kind: ExposedEntityKind,
+          entity: { key: 'post' },
+          resourcePath: '/posts/{postId}',
+          collectionPath: '/posts',
+          hasCollection: true,
+          isRoot: false,
+          parent: { key: 'users', association: { key: 'user-posts' } },
+          actions: [
+            { kind: 'list' },
+            { kind: 'read' },
+            { kind: 'create' },
+            { kind: 'update', allowedMethods: ['PATCH'] } as UpdateActionSchema,
+            { kind: 'delete' },
+          ],
+        },
+      ],
+    })
+
+    const generator = new RuntimeModelGenerator(apiModel)
+    const result = await generator.generate()
+
+    assert.deepInclude(result.routingMap['GET']!, {
+      path: '/users/{userId}',
+      lookup: { exposedEntityKey: 'users', actionKind: 'read' },
+    })
+
+    assert.deepInclude(result.routingMap['GET']!, {
+      path: '/users/{userId}/posts',
+      lookup: { exposedEntityKey: 'user-posts', actionKind: 'list' },
+    })
+
+    assert.deepInclude(result.routingMap['GET']!, {
+      path: '/users/{userId}/posts/{postId}',
+      lookup: { exposedEntityKey: 'user-posts', actionKind: 'read' },
+    })
+
+    assert.deepInclude(result.routingMap['POST']!, {
+      path: '/users/{userId}/posts',
+      lookup: { exposedEntityKey: 'user-posts', actionKind: 'create' },
+    })
+
+    assert.deepInclude(result.routingMap['PATCH']!, {
+      path: '/users/{userId}/posts/{postId}',
+      lookup: { exposedEntityKey: 'user-posts', actionKind: 'update' },
+    })
+
+    assert.deepInclude(result.routingMap['DELETE']!, {
+      path: '/users/{userId}/posts/{postId}',
+      lookup: { exposedEntityKey: 'user-posts', actionKind: 'delete' },
+    })
+  }).tags(['@modeling', '@generator'])
+})

package/tests/unit/modeling/helpers/endpointHelpers.spec.ts

@@ -2,9 +2,16 @@ import { test } from '@japa/runner'
 import * as helpers from '../../../../src/modeling/helpers/endpointHelpers.js'
 
 test.group('endpointHelpers', () => {
-  test('paramNameFor extracts last key', ({ assert }) => {
+  test('paramNameFor handles various arbitrary strings', ({ assert }) => {
     assert.equal(helpers.paramNameFor('product'), 'productId')
-    assert.equal(helpers.paramNameFor('domain:product'), 'productId')
-    assert.equal(helpers.paramNameFor('a:b:c'), 'cId')
+    assert.equal(helpers.paramNameFor('user_post'), 'userPostId')
+    assert.equal(helpers.paramNameFor('UserPost'), 'userPostId')
+    assert.equal(helpers.paramNameFor('USER_POST'), 'userPostId')
+    assert.equal(helpers.paramNameFor('user-post'), 'userPostId')
+    assert.equal(helpers.paramNameFor('User Post! '), 'userPostId')
+    assert.equal(helpers.paramNameFor('123item'), '_123itemId')
+    assert.equal(helpers.paramNameFor('XMLHttp'), 'xmlHttpId')
+    assert.throws(() => helpers.paramNameFor('!@#$'), 'Cannot generate a valid parameter name from "!@#$".')
+    assert.throws(() => helpers.paramNameFor(''), 'Cannot generate parameter name from an empty string.')
   })
 })