@api-client/core 0.20.8 → 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.8",
+  "version": "0.20.9",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

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 }
+}