@api-client/core 0.19.24 → 0.19.25

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.19.24",
+  "version": "0.19.25",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {
@@ -92,6 +92,7 @@
     "@pawel-up/csv": "^0.2.0",
     "@pawel-up/data-mock": "^0.4.0",
     "@pawel-up/jexl": "^4.0.1",
+    "@poppinss/matchit": "^3.2.0",
     "@xmldom/xmldom": "^0.9.9",
     "chalk": "^5.4.1",
     "console-table-printer": "^2.11.2",

package/src/matchit.d.ts

@@ -0,0 +1,19 @@
+declare module '@poppinss/matchit' {
+  export interface Matcher {
+    match?: RegExp
+    cast?: (value: string) => unknown
+  }
+
+  export interface RouteToken {
+    old: string
+    type: 0 | 1 | 2 | 3
+    val: string
+    end: string
+    matcher?: RegExp
+    cast?: (value: string) => unknown
+  }
+
+  export function parse(route: string, matchers?: Record<string, Matcher>): RouteToken[]
+  export function match(url: string, routes: RouteToken[][]): RouteToken[]
+  export function exec(url: string, tokens: RouteToken[], shouldDecodeParam?: boolean): Record<string, string>
+}

package/src/mocking/ModelingMock.ts

@@ -9,6 +9,7 @@ import { Patch } from './lib/Patch.js'
 import { DataCatalog } from './lib/DataCatalog.js'
 import { Permission } from './lib/Permission.js'
 import { Ai } from './lib/Ai.js'
+import { Deployment } from './lib/Deployment.js'
 
 export class ModelingMock {
   faker: Faker = faker
@@ -22,4 +23,5 @@ export class ModelingMock {
   dataCatalog = new DataCatalog()
   permission = new Permission()
   ai = new Ai()
+  deployments = new Deployment()
 }

package/src/mocking/lib/Deployment.ts

@@ -0,0 +1,88 @@
+import { faker } from '@faker-js/faker'
+import { nanoid } from '../../nanoid.js'
+import { DeploymentEnvironment, DeploymentKind, DeploymentStatus } from '../../models/store/Deployment.js'
+import type { DeploymentSchema } from '../../models/store/Deployment.js'
+
+const deploymentEnvironments: DeploymentEnvironment[] = [
+  DeploymentEnvironment.PROD,
+  DeploymentEnvironment.STAGING,
+  DeploymentEnvironment.DEV,
+] as const
+
+export class Deployment {
+  /**
+   * Generates a random deployment object.
+   * @param init Optional values to be present in the object.
+   * @returns Random deployment object.
+   */
+  deployment(init: Partial<DeploymentSchema> = {}): DeploymentSchema {
+    const env = init.env ?? faker.helpers.arrayElement(deploymentEnvironments)
+    let version: string | undefined
+    if (init.version !== undefined) {
+      version = init.version
+    } else if (env === DeploymentEnvironment.PROD) {
+      version = `v${faker.number.int({ min: 1, max: 5 })}`
+    } else {
+      version = undefined
+    }
+
+    const {
+      key = nanoid(),
+      orgId = nanoid(),
+      apiId = nanoid(),
+      orgSlug = faker.internet.domainWord(),
+      apiSlug = faker.internet.domainWord(),
+      modelVersion = faker.system.semver(),
+      status = faker.helpers.arrayElement([
+        DeploymentStatus.Pending,
+        DeploymentStatus.Active,
+        DeploymentStatus.Inactive,
+        DeploymentStatus.Failed,
+      ] as const),
+      createdAt = faker.date.past().getTime(),
+      updatedAt = faker.date.recent().getTime(),
+    } = init
+
+    const result: DeploymentSchema = {
+      kind: DeploymentKind,
+      key,
+      orgId,
+      apiId,
+      orgSlug,
+      apiSlug,
+      env,
+      modelVersion,
+      status,
+      createdAt,
+      updatedAt,
+    }
+    if (version !== undefined && version !== '') {
+      result.version = version
+    }
+    if (status === DeploymentStatus.Active) {
+      result.baseUri = init.baseUri ?? faker.internet.url()
+      result.portalUri = init.portalUri ?? faker.internet.url()
+    } else {
+      if (init.baseUri !== undefined) {
+        result.baseUri = init.baseUri
+      }
+      if (init.portalUri !== undefined) {
+        result.portalUri = init.portalUri
+      }
+    }
+    return result
+  }
+
+  /**
+   * Generates a list of random deployment objects.
+   * @param size Number of deployments to generate. Default is 25.
+   * @returns List of random deployments
+   */
+  deployments(size = 25, init?: Partial<DeploymentSchema>): DeploymentSchema[] {
+    const result: DeploymentSchema[] = []
+    for (let i = 0; i < size; i++) {
+      result.push(this.deployment(init))
+    }
+    return result
+  }
+}

package/src/modeling/Bindings.ts

@@ -147,6 +147,10 @@ export interface AssociationWebBindings {
    * Whether the association is hidden in the schema (not a part of it).
    */
   hidden?: boolean
+  /**
+   * When set it overrides the `name` of the property.
+   */
+  name?: string
 }
 
 export type AssociationBindings = AssociationWebBindings

package/src/modeling/DataFormat.ts

@@ -51,6 +51,8 @@ export type DomainPropertyAttribute =
   | 'multiple'
   | 'primary'
   | 'index'
+  | 'unique'
+  | 'search'
   | 'readOnly'
   | 'writeOnly'
   | 'deprecated'
@@ -60,6 +62,8 @@ export const DomainPropertyAttributes: DomainPropertyAttribute[] = [
   'multiple',
   'primary',
   'index',
+  'unique',
+  'search',
   'readOnly',
   'writeOnly',
   'deprecated',

package/src/modeling/DomainAssociation.ts

@@ -394,6 +394,17 @@ export class DomainAssociation extends DomainElement {
     return object.schema as AssociationWebBindings
   }
 
+  /**
+   * Reads the web binding definition, if any.
+   * Useful for reading binding data without mutating the model when the binding
+   * is missing (unlike `getWebBinding()` which creates the binding when missing).
+   * @returns The web binding definition, if any
+   */
+  readWebBinding(): AssociationWebBindings | undefined {
+    const object = this.bindings.find((i) => i.type === 'web') as AssociationBinding | undefined
+    return object?.schema as AssociationWebBindings | undefined
+  }
+
   /**
    * Returns the schema value of the binding, if any was
    * created.

package/src/modeling/DomainEntity.ts

@@ -374,7 +374,7 @@ export class DomainEntity extends DomainElement {
   }
 
   /**
-   * Lists all parent entities of this entity.
+   * Lists all parent entities of this entity (only the first level).
    *
    * @returns A generator that yields each parent `DomainEntity`.
    * @example
@@ -397,6 +397,35 @@ export class DomainEntity extends DomainElement {
     }
   }
 
+  /**
+   * Lists all parent entities recursively.
+   *
+   * @param direction The direction of the traversal. 'up' (default) lists from immediate parents up to the oldest.
+   *                  'down' lists from the oldest parents down to the immediate parents.
+   * @returns An array of parent `DomainEntity` instances, ordered according to the requested traversal direction.
+   */
+  listAllParents(direction: 'up' | 'down' = 'up'): DomainEntity[] {
+    const visited = new Set<string>()
+    const parents: DomainEntity[] = []
+    const queue: DomainEntity[] = [...this.listParents()]
+
+    let index = 0
+    while (index < queue.length) {
+      const parent = queue[index++]
+      if (!visited.has(parent.key)) {
+        visited.add(parent.key)
+        parents.push(parent)
+        queue.push(...parent.listParents())
+      }
+    }
+
+    if (direction === 'down') {
+      parents.reverse()
+    }
+
+    return parents
+  }
+
   /**
    * Adds a parent to this entity.
    *

package/src/modeling/ExposedEntity.ts

@@ -3,7 +3,7 @@ import { Exception } from '../exceptions/exception.js'
 import { ExposedEntityKind } from '../models/kinds.js'
 import { nanoid } from '../nanoid.js'
 import { Action } from './actions/Action.js'
-import { type ApiActionSchema, restoreAction } from './actions/index.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 { AccessRule } from './rules/AccessRule.js'
@@ -518,6 +518,31 @@ export class ExposedEntity extends EventTarget {
     return action
   }
 
+  /**
+   * @deprecated Use {@link addActionFromKind()} instead.
+   */
+  addCrudAction(actionKind: ActionKind): Action {
+    return this.addActionFromKind(actionKind)
+  }
+
+  /**
+   * Adds an action of a given kind to the exposure.
+   *
+   * @param actionKind The kind of the action to add.
+   * @returns The added action.
+   */
+  addActionFromKind(actionKind: ActionKind): Action {
+    if (this.actions.some((action) => action.kind === actionKind)) {
+      throw new Exception(`Action of kind "${actionKind}" already exists for this exposure`, {
+        code: 'E_ACTION_USED',
+        help: "There's no need to add an API action again.",
+      })
+    }
+    const action = createActionFromKind(this, actionKind)
+    this.actions.push(action)
+    return action
+  }
+
   /**
    * Scans for the indexed and search properties in the `DomainEntity`
    * and recreates the `paginationContract` with all indexed/searched fields.

package/src/modeling/RuntimeApiModel.ts

@@ -0,0 +1,137 @@
+import { match, parse, exec, type RouteToken } from '@poppinss/matchit'
+import { ApiModel, type ApiModelSchema } from './ApiModel.js'
+import type { DataDomainSchema } from './DataDomain.js'
+import type { ActionKind } from './actions/index.js'
+import type { ExposedEntity } from './ExposedEntity.js'
+import type { Action } from './actions/Action.js'
+
+/**
+ * Identifies a specific exposed entity and its action kind.
+ */
+export interface RouteLookup {
+  exposedEntityKey: string
+  actionKind: ActionKind
+}
+
+/**
+ * A routing definition mapping a path to an action lookup.
+ */
+export interface RouteDefinition {
+  path: string
+  lookup: RouteLookup
+}
+
+/**
+ * A map of HTTP methods to their route definitions.
+ */
+export type RoutingMap = Record<string, RouteDefinition[]>
+
+/**
+ * Schema for an API Model optimized for runtime routing.
+ */
+export interface RuntimeApiModelSchema extends ApiModelSchema {
+  routingMap: RoutingMap
+}
+
+export interface RuntimeResolvedAction {
+  entity: ExposedEntity
+  action: Action
+  params: Record<string, string>
+}
+
+/**
+ * An optimized API Model subclass designed for fast runtime lookups.
+ * It pre-compiles the RoutingMap into a radix tree for O(log N) or faster endpoint resolution.
+ */
+export class RuntimeApiModel extends ApiModel {
+  /**
+   * The parsed radix tree for fast routing.
+   * Method -> ParsedRoutes
+   */
+  #routes = new Map<string, RouteToken[][]>()
+
+  /**
+   * Quick map from matchit parsed route format to our RouteDefinition for returning results
+   */
+  #definitions = new WeakMap<RouteToken[], RouteDefinition>()
+
+  constructor(schema: RuntimeApiModelSchema, domainSchema: DataDomainSchema) {
+    super(schema, domainSchema)
+
+    if (schema.routingMap) {
+      this.#initializeRouter(schema.routingMap)
+    }
+  }
+
+  #initializeRouter(routingMap: RoutingMap) {
+    for (const [method, definitions] of Object.entries(routingMap)) {
+      const parsedRoutes = []
+      for (const def of definitions) {
+        // matchit's parse() transforms a route string into an object representation.
+        // It expects `:param` syntax, while our API models use OpenAPI `{param}` syntax.
+        const matchitPath = def.path.replace(/\{([^}]+)\}/g, ':$1')
+        const parsed = parse(matchitPath)
+        this.#definitions.set(parsed, def)
+        parsedRoutes.push(parsed)
+      }
+      this.#routes.set(method.toUpperCase(), parsedRoutes)
+    }
+  }
+
+  /**
+   * Looks up the corresponding exposed entity and action for a given request.
+   *
+   * @param method The HTTP method (e.g., 'GET', 'POST').
+   * @param path The request path (e.g., '/users/123').
+   * @returns An object with the entity, action, and extracted path parameters if a match is found.
+   */
+  lookupAction(method: string, path: string): RuntimeResolvedAction | undefined {
+    const parsedRoutes = this.#routes.get(method.toUpperCase())
+    if (!parsedRoutes) {
+      return undefined
+    }
+
+    // `match` returns the matching parsed route (which is an array of segments), or empty array if no match
+    const matchedRoute = match(path, parsedRoutes)
+    if (!matchedRoute || matchedRoute.length === 0) {
+      return undefined
+    }
+
+    const def = this.#definitions.get(matchedRoute)
+    if (!def) {
+      return undefined
+    }
+
+    const params = exec(path, matchedRoute)
+
+    const entity = this.exposes.get(def.lookup.exposedEntityKey)
+    if (!entity) {
+      return undefined
+    }
+
+    const action = entity.actions.find((a) => a.kind === def.lookup.actionKind)
+    if (!action) {
+      return undefined
+    }
+
+    return {
+      entity,
+      action,
+      params,
+    }
+  }
+
+  override toJSON(): RuntimeApiModelSchema {
+    const base = super.toJSON() as RuntimeApiModelSchema
+
+    const routingMap: RoutingMap = {}
+    for (const [method, parsedRoutes] of this.#routes.entries()) {
+      routingMap[method] = parsedRoutes.map((pr) => this.#definitions.get(pr) as RouteDefinition)
+    }
+
+    return {
+      ...base,
+      routingMap,
+    }
+  }
+}

package/src/modeling/types.ts

@@ -86,6 +86,31 @@ export interface AssociationTarget {
   domain?: string
 }
 
+/**
+ * The list of functions supported for string properties.
+ */
+export type StringFunctions = 'random' | 'uuid-v4'
+/**
+ * The list of functions supported for number properties.
+ */
+export type NumberFunctions = 'incremental'
+/**
+ * The list of functions supported for date properties.
+ */
+export type DateFunctions = 'now'
+/**
+ * The list of functions supported for datetime properties.
+ */
+export type DateTimeFunctions = 'now'
+/**
+ * The list of functions supported for time properties.
+ */
+export type TimeFunctions = 'now'
+/**
+ * The list of all functions that can be used as default values for properties.
+ */
+export type FunctionValue = StringFunctions | NumberFunctions | DateFunctions | DateTimeFunctions | TimeFunctions
+
 /**
  * Describes the default value set on a property schema.
  */
@@ -101,7 +126,7 @@ export interface SchemaDefaultValue {
    * The actual value type depends on the `type`.
    * It is always a string and it has to be casted to the property's data type.
    */
-  value: string
+  value: string | FunctionValue
 }
 
 /**

package/src/models/kinds.ts

@@ -20,6 +20,7 @@ export const DataCatalogKind = 'Core#DataCatalog'
 export const DataCatalogVersionKind = 'Core#DataCatalogVersion'
 export const OrganizationKind = 'Core#Organization'
 export const InvitationKind = 'Core#Invitation'
+export const DeploymentKind = 'Core#Deployment'
 export const ApiModelKind = 'Core#ApiModel'
 export const ExposedEntityKind = 'Core#ExposedEntity'
 export const ApiFileKind = 'Core#ApiFile'