@api-client/core 0.20.7 → 0.20.9

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.7",
+  "version": "0.20.9",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/src/modeling/ApiModel.ts

@@ -16,6 +16,7 @@ import { DependentModel, type DependentModelSchema, type DomainDependency } from
 import { observed, toRaw } from '../decorators/observed.js'
 import pluralize from '@jarrodek/pluralize'
 import { createDomainKey } from './helpers/keying.js'
+import { paramNameFor } from './helpers/endpointHelpers.js'
 import { ExposedEntity } from './ExposedEntity.js'
 import { AccessRule, AccessRuleSchema } from './rules/AccessRule.js'
 import { RateLimitingConfiguration, RateLimitingConfigurationSchema } from './rules/RateLimitingConfiguration.js'
@@ -462,15 +463,16 @@ export class ApiModel extends DependentModel {
     }
     const name = domainEntity.info.name || ''
     const segment = pluralize(name.toLocaleLowerCase())
+    const paramName = paramNameFor(name)
     let relativeCollectionPath = `/${segment}`
-    let relativeResourcePath = `/${segment}/{id}`
+    let relativeResourcePath = `/${segment}/{${paramName}}`
 
     // Check for root path collision and resolve by appending a number
     let counter = 1
     const originalCollectionPath = relativeCollectionPath
     while (this.findCollectionPathCollision(relativeCollectionPath)) {
       relativeCollectionPath = `${originalCollectionPath}-${counter}`
-      relativeResourcePath = `${relativeCollectionPath}/{id}`
+      relativeResourcePath = `${relativeCollectionPath}/{${paramName}}`
       counter++
     }
 
@@ -552,14 +554,15 @@ export class ApiModel extends DependentModel {
               if (targetDomEntity) {
                 const name = targetDomEntity.info.name || ''
                 const segment = pluralize(name.toLocaleLowerCase())
+                const paramName = paramNameFor(name)
                 let relativeCollectionPath = `/${segment}`
-                let relativeResourcePath = `/${segment}/{id}`
+                let relativeResourcePath = `/${segment}/{${paramName}}`
 
                 let counter = 1
                 const originalCollectionPath = relativeCollectionPath
                 while (this.findResourcePathCollision(relativeCollectionPath)) {
                   relativeCollectionPath = `${originalCollectionPath}-${counter}`
-                  relativeResourcePath = `${relativeCollectionPath}/{id}`
+                  relativeResourcePath = `${relativeCollectionPath}/{${paramName}}`
                   counter++
                 }
 
@@ -582,8 +585,9 @@ export class ApiModel extends DependentModel {
           const name = association.info.name || ''
           const segment = pluralize(name.toLocaleLowerCase())
           const isCollection = association.multiple !== false
+          const paramName = paramNameFor(targetDomainEntity.info.name || '')
           const relativeCollectionPath = isCollection ? `/${segment}` : undefined
-          const relativeResourcePath = isCollection ? `/${segment}/{id}` : `/${segment}`
+          const relativeResourcePath = isCollection ? `/${segment}/{${paramName}}` : `/${segment}`
           // Create nested exposure
           const nestedExposure: ExposedEntitySchema = {
             kind: ExposedEntityKind,

package/src/modeling/RuntimeApiModel.ts

@@ -11,12 +11,55 @@ import { SemanticType } from './Semantics.js'
 import { AccessRule, AccessRuleExecutionPhase } from './rules/AccessRule.js'
 import { Exception } from '../exceptions/exception.js'
 
+/**
+ * Describes a mapped parameter for a route.
+ */
+export interface RouteParam {
+  /**
+   * The name of the parameter in the path (e.g. "userId")
+   * This can be anything as the user can freely change the param names.
+   */
+  paramName: string
+  /**
+   * The "key" of the exposed entity this parameter belongs to.
+   */
+  exposedEntityKey: string
+  /**
+   * The "name" of the exposed entity this parameter belongs to.
+   */
+  exposedEntityName: string
+  /**
+   * The primary key's property name of the exposed entity (e.g., "id").
+   */
+  propertyName: string
+  /**
+   * The name of the association that connects the parent entity to its child (e.g., "comments")
+   * If its missing it means that there's no association, so there's no sub-endpoint in the path
+   * (e.g., `/users/123` - It's a single root endpoint - it doesn't have any sub-endpoints.)
+   */
+  associationName?: string
+}
+
 /**
  * Identifies a specific exposed entity and its action kind.
  */
 export interface RouteLookup {
+  /**
+   * The "key" of the exposed entity that is being accessed.
+   */
   exposedEntityKey: string
+  /**
+   * The "name" of the exposed entity that is being accessed.
+   */
+  exposedEntityName: string
+  /**
+   * The "kind" of the action that is being performed.
+   */
   actionKind: ActionKind
+  /**
+   * Information about each path parameter in this route.
+   */
+  params: RouteParam[]
 }
 
 /**
@@ -44,6 +87,7 @@ export interface RuntimeResolvedAction {
   entity: DomainEntity
   action: Action
   params: Record<string, string>
+  lookup: RouteLookup
 }
 
 export type RuleEvaluator = (rule: AccessRule) => Promise<boolean | undefined> | boolean | undefined
@@ -429,6 +473,7 @@ export class RuntimeApiModel extends ApiModel {
       entity,
       action,
       params,
+      lookup: def.lookup,
     }
   }
 

package/src/modeling/generators/RuntimeModelGenerator.ts

@@ -1,6 +1,7 @@
 import { type ActionKind, type UpdateAction } from '../actions/index.js'
 import { ApiModel, type ApiModelSchema } from '../ApiModel.js'
-import { type RouteDefinition, type RuntimeApiModelSchema } from '../RuntimeApiModel.js'
+import { ExposedEntity } from '../ExposedEntity.js'
+import { RouteParam, type RouteDefinition, type RuntimeApiModelSchema } from '../RuntimeApiModel.js'
 
 /**
  * A class that takes the API model and generates a runtime-optimized API model.
@@ -34,27 +35,27 @@ export class RuntimeModelGenerator {
       for (const action of expose.actions) {
         switch (action.kind) {
           case 'list':
-            if (colPath) this.addRoute('GET', colPath, expose.key, action.kind)
+            if (colPath) this.addRoute('GET', colPath, expose, action.kind)
             break
           case 'create':
-            if (colPath) this.addRoute('POST', colPath, expose.key, action.kind)
+            if (colPath) this.addRoute('POST', colPath, expose, action.kind)
             break
           case 'search':
-            if (colPath) this.addRoute('POST', `${colPath}/search`, expose.key, action.kind)
+            if (colPath) this.addRoute('POST', `${colPath}/search`, expose, action.kind)
             break
           case 'read':
-            if (resPath) this.addRoute('GET', resPath, expose.key, action.kind)
+            if (resPath) this.addRoute('GET', resPath, expose, 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)
+                this.addRoute(method, resPath, expose, action.kind)
               }
             }
             break
           case 'delete':
-            if (resPath) this.addRoute('DELETE', resPath, expose.key, action.kind)
+            if (resPath) this.addRoute('DELETE', resPath, expose, action.kind)
             break
         }
       }
@@ -66,14 +67,65 @@ export class RuntimeModelGenerator {
     }
   }
 
-  private addRoute(method: string, path: string, exposedEntityKey: string, actionKind: ActionKind): void {
+  private addRoute(method: string, path: string, expose: ExposedEntity, actionKind: ActionKind): void {
     const upperMethod = method.toUpperCase()
     if (!this.#routingMap[upperMethod]) {
       this.#routingMap[upperMethod] = []
     }
+
+    const domainEntity = this.#apiModel.domain?.findEntity(expose.entity.key, expose.entity.domain)
+    if (!domainEntity) throw new Error(`Entity ${expose.key} not found, this should never happen`)
+
+    const params: RouteParam[] = []
+    let current: ExposedEntity | undefined
+    let previous: ExposedEntity | undefined = undefined
+    if (['list', 'create', 'search'].includes(actionKind)) {
+      // when starting with a collection, ignore self and start with parent (if any).
+      // A collection won't have any path params anyway, so we can skip it.
+      current = expose.parent ? this.#apiModel.exposes.get(expose.parent.key) : undefined
+      // setting the previous to the current so the associations are captured.
+      previous = expose
+    } else {
+      current = expose
+    }
+
+    while (current) {
+      const match = current.resourcePath.match(/\{([^}]+)\}/)
+      if (match) {
+        const entity = this.#apiModel.domain?.findEntity(current.entity.key, current.entity.domain)
+        if (!entity) throw new Error(`Entity ${current.entity.key} not found, this should never happen`)
+        const pkName = entity.primaryKey()?.info.name
+        if (!pkName) throw new Error(`Entity ${current.entity.key} has no primary key, this should never happen`)
+
+        let associationName: string | undefined
+        if (previous && previous.parent && previous.parent.key === current.key) {
+          for (const assoc of entity.withInheritedAssociations()) {
+            if (previous.parent?.association.key === assoc.key) {
+              associationName = assoc.info.name
+              break
+            }
+          }
+        }
+
+        params.push({
+          paramName: match[1],
+          exposedEntityKey: current.key,
+          exposedEntityName: entity.info.name as string,
+          propertyName: pkName,
+          ...(associationName ? { associationName } : {}),
+        })
+      }
+      previous = current
+      current = current.parent ? this.#apiModel.exposes.get(current.parent.key) : undefined
+    }
     this.#routingMap[upperMethod].push({
       path,
-      lookup: { exposedEntityKey, actionKind },
+      lookup: {
+        exposedEntityKey: expose.key,
+        exposedEntityName: domainEntity.info.name as string,
+        actionKind,
+        params,
+      },
     })
   }
 }

package/tests/fixtures/modeling/runtime/domains.ts

@@ -0,0 +1,270 @@
+import { DataDomain } from '../../../../src/modeling/DataDomain.js'
+import type { DomainEntity } from '../../../../src/modeling/DomainEntity.js'
+import type { DomainModel } from '../../../../src/modeling/DomainModel.js'
+import { SemanticType } from '../../../../src/modeling/Semantics.js'
+
+/**
+ * Creates the simplest data domain with a single entity user.
+ */
+export function userOnlyDomain(): { domain: DataDomain; model: DomainModel; user: DomainEntity } {
+  const domain = new DataDomain({ info: { name: 'Testing Domain', version: '1.0.0' } })
+  const model = domain.addModel({ info: { name: 'Container model' } })
+  const user = model.addEntity({ info: { name: 'user' } })
+  user.addProperty({ info: { name: 'id' }, primary: true })
+  user.addProperty({ info: { name: 'username' }, semantics: [{ id: SemanticType.Username }] })
+  user.addProperty({ info: { name: 'password' }, semantics: [{ id: SemanticType.Password }] })
+  user.addProperty({ info: { name: 'email' }, semantics: [{ id: SemanticType.Email }] })
+  user.addProperty({
+    info: { name: 'role' },
+    semantics: [{ id: SemanticType.UserRole }],
+    schema: {
+      enum: ['admin', 'member', 'guest'],
+    },
+  })
+  return { domain, model, user }
+}
+
+/**
+ * Returns a domain that has 1:1 association between user and config.
+ */
+export function singletonDomain(): {
+  domain: DataDomain
+  model: DomainModel
+  user: DomainEntity
+  config: DomainEntity
+} {
+  const { domain, model, user } = userOnlyDomain()
+  const config = model.addEntity({ info: { name: 'config' } })
+  config.addProperty({ info: { name: 'id' }, primary: true })
+  // user has 1 config
+  user.addAssociation({
+    info: { name: 'config' },
+    targets: [{ key: config.key }],
+    multiple: false,
+    required: false,
+  })
+  config.addAssociation({
+    info: { name: 'owner' },
+    targets: [{ key: user.key }],
+    multiple: false,
+    required: true,
+    semantics: [{ id: SemanticType.ResourceOwnerIdentifier }],
+  })
+  return { domain, model, user, config }
+}
+
+/**
+ * Returns a blog domain with four entities: user, blog, post, comment.
+ */
+export function blogDomain(): {
+  domain: DataDomain
+  user: DomainEntity
+  blog: DomainEntity
+  post: DomainEntity
+  comment: DomainEntity
+} {
+  const domain = new DataDomain({ info: { version: '1.0.0' } })
+  const model = domain.addModel({ info: { name: 'Container Model' } })
+
+  const user = model.addEntity({ info: { name: 'user' }, semantics: [{ id: SemanticType.User }] })
+  user.addProperty({
+    info: { name: 'id' },
+    type: 'string',
+    primary: true,
+    required: true,
+    schema: { defaultValue: { type: 'function', value: 'random' } },
+  })
+  user.addProperty({
+    info: { name: 'name' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Username }],
+  })
+  user.addProperty({
+    info: { name: 'password' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Password }],
+  })
+  user.addProperty({
+    info: { name: 'role' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.UserRole }],
+    schema: {
+      defaultValue: { type: 'literal', value: 'user' },
+      enum: ['user', 'admin', 'moderator'],
+    },
+  })
+
+  const blog = model.addEntity({ info: { name: 'blog' } })
+  blog.addProperty({
+    info: { name: 'id' },
+    type: 'string',
+    primary: true,
+    required: true,
+    schema: { defaultValue: { type: 'function', value: 'random' } },
+  })
+  blog.addProperty({
+    info: { name: 'title' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Title }],
+  })
+  blog.addProperty({
+    info: { name: 'content' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Description }, { id: SemanticType.Markdown }],
+  })
+  blog.addProperty({
+    info: { name: 'status' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Status }],
+    schema: {
+      defaultValue: { type: 'literal', value: 'draft' },
+      enum: ['draft', 'published'],
+    },
+  })
+  blog.addProperty({
+    info: { name: 'created_at' },
+    type: 'datetime',
+    readOnly: true,
+    schema: { defaultValue: { type: 'function', value: 'now' } },
+  })
+  blog.addProperty({
+    info: { name: 'updated_at' },
+    type: 'datetime',
+    readOnly: true,
+    schema: { defaultValue: { type: 'function', value: 'now' } },
+  })
+  blog.addAssociation({
+    info: { name: 'author' },
+    targets: [{ key: user.key }],
+    multiple: false,
+    required: true,
+    semantics: [{ id: SemanticType.ResourceOwnerIdentifier }],
+  })
+  user.addAssociation({
+    info: { name: 'blogs' },
+    targets: [{ key: blog.key }],
+    multiple: true,
+    required: false,
+    onDelete: 'cascade',
+  })
+
+  const post = model.addEntity({ info: { name: 'posts' } })
+  post.addProperty({
+    info: { name: 'id' },
+    type: 'string',
+    primary: true,
+    required: true,
+    schema: { defaultValue: { type: 'function', value: 'random' } },
+  })
+  post.addProperty({
+    info: { name: 'title' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Title }],
+  })
+  post.addProperty({
+    info: { name: 'content' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Description }, { id: SemanticType.Markdown }],
+  })
+  post.addProperty({
+    info: { name: 'status' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Status }],
+    schema: {
+      defaultValue: { type: 'literal', value: 'draft' },
+      enum: ['draft', 'published'],
+    },
+  })
+  post.addProperty({
+    info: { name: 'created_at' },
+    type: 'datetime',
+    readOnly: true,
+    schema: { defaultValue: { type: 'function', value: 'now' } },
+  })
+  post.addProperty({
+    info: { name: 'updated_at' },
+    type: 'datetime',
+    readOnly: true,
+    schema: { defaultValue: { type: 'function', value: 'now' } },
+  })
+  post.addAssociation({
+    info: { name: 'author' },
+    targets: [{ key: user.key }],
+    multiple: false,
+    required: true,
+    semantics: [{ id: SemanticType.ResourceOwnerIdentifier }],
+  })
+  post.addAssociation({
+    info: { name: 'blog' },
+    targets: [{ key: blog.key }],
+    multiple: false,
+    required: true,
+  })
+  user.addAssociation({
+    info: { name: 'posts' },
+    targets: [{ key: post.key }],
+    multiple: true,
+    required: false,
+    onDelete: 'cascade',
+  })
+  blog.addAssociation({
+    info: { name: 'posts' },
+    targets: [{ key: post.key }],
+    multiple: true,
+    required: false,
+    onDelete: 'cascade',
+  })
+
+  const comment = model.addEntity({ info: { name: 'comment' } })
+  comment.addProperty({
+    info: { name: 'id' },
+    type: 'string',
+    primary: true,
+    required: true,
+    schema: { defaultValue: { type: 'function', value: 'random' } },
+  })
+  comment.addProperty({
+    info: { name: 'content' },
+    type: 'string',
+    required: true,
+    semantics: [{ id: SemanticType.Markdown }],
+  })
+  comment.addAssociation({
+    info: { name: 'author' },
+    targets: [{ key: user.key }],
+    multiple: false,
+    required: true,
+    semantics: [{ id: SemanticType.ResourceOwnerIdentifier }],
+  })
+  comment.addAssociation({
+    info: { name: 'post' },
+    targets: [{ key: post.key }],
+    multiple: false,
+    required: true,
+  })
+  user.addAssociation({
+    info: { name: 'comments' },
+    targets: [{ key: comment.key }],
+    multiple: true,
+    required: false,
+    onDelete: 'cascade',
+  })
+  post.addAssociation({
+    info: { name: 'comments' },
+    targets: [{ key: comment.key }],
+    multiple: true,
+    required: false,
+    onDelete: 'cascade',
+  })
+
+  return { domain, user, blog, post, comment }
+}

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

@@ -87,6 +87,7 @@ test.group('ApiModel.exposeEntity()', () => {
     assert.isDefined(nestedB)
     assert.deepEqual(nestedB?.parent?.key, exposedA.key)
     assert.strictEqual(nestedB?.collectionPath, '/entitybs')
+    assert.strictEqual(nestedB?.resourcePath, '/entitybs/{bId}')
   })
 
   test('does not infinitely expose circular associations', ({ assert }) => {
@@ -216,7 +217,7 @@ test.group('ApiModel.exposeEntity()', () => {
     // Expose second entity -> should resolve collision to /items-1
     const exp2 = model.exposeEntity({ key: e2.key })
     assert.equal(exp2.collectionPath, '/items-1')
-    assert.equal(exp2.resourcePath, '/items-1/{id}')
+    assert.equal(exp2.resourcePath, '/items-1/{itemId}')
 
     // Expose third entity -> /items-2
     const e3 = dm.addEntity({ info: { name: 'Item' } })

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

@@ -10,7 +10,7 @@ test.group('OasGenerator', (group) => {
   let api: ApiModel
 
   group.each.setup(() => {
-    domain = new DataDomain({ info: { name: 'Test Domain', version: '1.0.0' } })
+    domain = new DataDomain({ info: { name: 'Test Domain', version: '1.0.0' } }, undefined, { readOnly: true })
     const model = domain.addModel({ info: { name: 'model1' } })
     const user = model.addEntity({ info: { name: 'user' } })
     user.addSemantic({ id: SemanticType.User })
@@ -232,17 +232,17 @@ test.group('OasGenerator', (group) => {
     // User endpoints (CRUD)
     assert.isObject(paths['/users'].get, 'User list')
     assert.isObject(paths['/users'].post, 'User create')
-    assert.isObject(paths['/users/{id}'].get, 'User read')
-    assert.isObject(paths['/users/{id}'].put, 'User put')
-    assert.isObject(paths['/users/{id}'].delete, 'User delete')
+    assert.isObject(paths['/users/{userId}'].get, 'User read')
+    assert.isObject(paths['/users/{userId}'].put, 'User put')
+    assert.isObject(paths['/users/{userId}'].delete, 'User delete')
 
     // Post endpoints (list, update, delete)
     assert.isObject(paths['/posts'].get)
     assert.isUndefined(paths['/posts'].post) // no create Action
-    assert.isUndefined(paths['/posts/{id}'].get) // no read action
-    assert.isObject(paths['/posts/{id}'].patch)
-    assert.isObject(paths['/posts/{id}'].put)
-    assert.isObject(paths['/posts/{id}'].delete)
+    assert.isUndefined(paths['/posts/{postId}'].get) // no read action
+    assert.isObject(paths['/posts/{postId}'].patch)
+    assert.isObject(paths['/posts/{postId}'].put)
+    assert.isObject(paths['/posts/{postId}'].delete)
   })
 
   test('generates standard error responses', ({ assert }) => {