@api-client/core 0.15.1 → 0.16.1

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.15.1",
+  "version": "0.16.1",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/Semantics.ts

@@ -6,13 +6,19 @@ import type { DomainPropertyType } from './DataFormat.js'
  * Using a string enum makes it easy to add or remove semantics in a single place.
  */
 export enum SemanticType {
+  //
   // Entity-Level Semantics
+  //
+
   /**
    * Designates a Data Entity that represents users of the system.
    */
   User = 'Semantic#User',
 
+  //
   // Property-Level Semantics
+  //
+
   /**
    * Annotates the field as the user password.
    * The runtime should treat this field with special care,
@@ -43,11 +49,19 @@ export enum SemanticType {
    */
   DeletedFlag = 'Semantic#DeletedFlag',
   /**
-   * Designates a Data Property as a unique public identifier for a resource.
+   * Designates a Data Property as a unique public identifier for a resource (the slug).
    * This is often used in URLs to provide a user-friendly way to access the resource.
    * For example, a blog post might have a public unique name like "my-first-post".
+   * A URL-friendly text field. The runtime automatically generates a unique, URL-safe string from another field (like a title or name). The user needs to specify which field is used to generate
+   * the slug.
    */
   PublicUniqueName = 'Semantic#PublicUniqueName',
+  /**
+   * A semantic that describes a title of an article, blog post, and so on. This semantic is used with
+   * the `PublicUniqueName` to determine which field is responsible for the slug generation. However,
+   * we may add more automation related to the `title` property in the future.
+   */
+  Title = 'Semantic#Title',
   /**
    * Designates a Data Property as the `role` of a user within the system.
    * This is used to define the user's permissions and access levels.
@@ -56,13 +70,140 @@ export enum SemanticType {
    * Roles are defined on the entity as enums, or as a string property with a controlled vocabulary.
    */
   UserRole = 'Semantic#UserRole',
+  /**
+   * A text or enum field to represent the state of a record (e.g., `draft`, `published`, `pending_review`, `archived`).
+   *
+   * Defined behaviors:
+   * - State-Based Filtering: Automatically prevents public users from seeing records in a draft state.
+   * - State Transitions: In principle, the runtime should prevent the user from skipping some states.
+   * For example, when the record is in the `draft` state, it cannot be moved to the `archived` state without publishing it first. However,
+   * we do not have enough customer feedback to design this functionality correctly right now, so
+   * it serves as a placeholder semantic annotation.
+   */
+  Status = 'Semantic#Status',
+
+  /**
+   * Annotates an integer field that automatically increments.
+   * The runtime automatically increments this number on every update, providing a simple way
+   * to track changes and implement optimistic locking to prevent mid-air collisions.
+   */
+  Version = 'Semantic#Version',
+
+  /**
+   * Annotates a field that holds a reference to an image data via an URL.
+   * The application + runtime should validate that the input is a well-formed URL.
+   */
+  ImageURL = 'Semantic#ImageURL',
+
+  /**
+   * Annotates a field that holds a reference to a file object via an URL. Ity is distinct from the
+   * `ImageURL` semantic as it implicitly states that the target is non-image, binary data (an attachment, for example).
+   */
+  FileURL = 'Semantic#FileURL',
+
+  /**
+   * Annotates the field as a markdown-interpreted field.
+   * When an object is created, the runtime performs additional sanitization to prevent XSS attacks.
+   *
+   * The annotation describes whether the data should be translated to the HTML output when
+   * record is read or the original MD content should be returned.
+   */
+  Markdown = 'Semantic#Markdown',
+
+  /**
+   * Annotates the field as containing HTML content.
+   * The runtime performs sanitization to prevent XSS attacks and validates HTML structure.
+   *
+   * The annotation describes whether the data should be rendered as HTML output when
+   * record is read or the original HTML content should be returned.
+   */
+  HTML = 'Semantic#HTML',
+
+  /**
+   * Annotates a field that holds geospatial coordinate data (latitude/longitude).
+   * The runtime automatically generates API capabilities for location-based queries,
+   * such as "find all restaurants within a 5-mile radius."
+   *
+   * The field should contain coordinate data in a standard format:
+   * - "40.7128,-74.0060" (lat,lon)
+   * - "POINT(-74.0060 40.7128)" (PostGIS format)
+   * - "40.7128°N, 74.0060°W" (degree format)
+   *
+   * Defined behaviors:
+   * - Spatial Indexing: The runtime automatically creates spatial indexes for efficient location-based queries
+   * - Distance Queries: Enables API endpoints for finding records within specified distances
+   * - Coordinate Validation: Validates that the input follows proper coordinate format
+   * - PostGIS Integration: When using PostgreSQL, automatically maps to PostGIS geometry types
+   */
+  GeospatialCoordinates = 'Semantic#GeospatialCoordinates',
+
+  /**
+   * Annotates a field as an email address with validation and verification options.
+   */
+  Email = 'Semantic#Email',
+  /**
+   * Annotates a field as a phone number with validation and formatting options.
+   */
+  Phone = 'Semantic#Phone',
+  /**
+   * Annotates a field as a monetary value with currency support and precision control.
+   * Can store simple decimal amounts or complex objects with amount and currency.
+   * Enforces proper decimal handling to avoid floating-point errors.
+   */
+  Price = 'Semantic#Price',
+  /**
+   * Annotates a field as a URL with validation and allowed protocols.
+   */
+  URL = 'Semantic#URL',
+  /**
+   * Annotates a field as a Stock Keeping Unit (SKU).
+   * Enforces uniqueness at the database level, critical for product catalogs.
+   * Provides automatic validation and formatting for product identification codes.
+   */
+  SKU = 'Semantic#SKU',
+  /**
+   * Annotates a field as a long-form description.
+   */
+  Description = 'Semantic#Description',
+  /**
+   * Annotates a field as a short summary.
+   */
+  Summary = 'Semantic#Summary',
+  /**
+   * Annotates a field as a calculated value based on a formula.
+   */
+  Calculated = 'Semantic#Calculated',
+  /**
+   * Annotates a field as derived from other fields.
+   */
+  Derived = 'Semantic#Derived',
+
+  //
   // Association-Level Semantics
+  //
+
   /**
    * Designates an association that links a resource to a "User" entity instance.
    * This is used to indicate ownership of the resource for access control purposes.
    * For example, a blog post might have a resource owner identifier that points to the user who created it.
+   *
+   * Defined behaviors:
+   * - Automatic Ownership: When a new record is created, this field is automatically populated with the ID of the authenticated user. It also creates a foreign relationship to the `User` semantic object.
+   * - Scoped Access: The runtime automatically filters list and read operations to show only records where the Owner matches the current user. update and delete operations are similarly restricted.
    */
   ResourceOwnerIdentifier = 'Semantic#ResourceOwnerIdentifier',
+  /**
+   * Annotates an association as supporting tag functionality.
+   * Applied to associations between entities to enable tagging behavior.
+   * For example, a Product-Category association with Tags semantic enables product tagging.
+   */
+  Tags = 'Semantic#Tags',
+  /**
+   * Annotates an association as supporting category functionality.
+   * Applied to associations between entities to enable categorization behavior.
+   * For example, a Product-Category association with Categories semantic enables product categorization.
+   */
+  Categories = 'Semantic#Categories',
 }
 
 /**
@@ -165,7 +306,10 @@ export type DataSemantic = EntitySemantic | PropertySemantic | AssociationSemant
  * This acts as a central registry for the application.
  */
 export const DataSemantics: Record<SemanticType, DataSemantic> = {
+  //
   // Entity-Level Definitions
+  //
+
   [SemanticType.User]: {
     id: SemanticType.User,
     displayName: 'User Entity',
@@ -173,7 +317,10 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'Designates an entity that represents system users, crucial for authentication and authorization.',
   },
 
+  //
   // Property-Level Definitions
+  //
+
   [SemanticType.Password]: {
     id: SemanticType.Password,
     displayName: 'User Password',
@@ -203,6 +350,55 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: "Marks a field as the field that contains object's deletion timestamp.",
     applicableDataTypes: ['datetime'],
   },
+  [SemanticType.PublicUniqueName]: {
+    id: SemanticType.PublicUniqueName,
+    displayName: 'Public Unique Name (Slug)',
+    scope: SemanticScope.Property,
+    description: 'A user-friendly, unique public identifier for a resource, often used in URLs.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Title]: {
+    id: SemanticType.Title,
+    displayName: 'Record Title',
+    scope: SemanticScope.Property,
+    description: 'A title for the record. Used as a source for the PublicUniqueName semantic.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.UserRole]: {
+    id: SemanticType.UserRole,
+    displayName: 'User Role Field',
+    scope: SemanticScope.Property,
+    description: "A text or enum field that defines the user's role for role-based authorization.",
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Status]: {
+    id: SemanticType.Status,
+    displayName: 'Record Status',
+    scope: SemanticScope.Property,
+    description: 'A text or enum field to represent the state of a record.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Version]: {
+    id: SemanticType.Version,
+    displayName: 'Version Number',
+    scope: SemanticScope.Property,
+    description: 'An integer field that automatically increments on every update.',
+    applicableDataTypes: ['number'],
+  },
+  [SemanticType.ImageURL]: {
+    id: SemanticType.ImageURL,
+    displayName: 'Image URL',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field that holds a reference to an image data via an URL.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.FileURL]: {
+    id: SemanticType.FileURL,
+    displayName: 'File URL',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field that holds a reference to a file object via an URL (non-image binary data).',
+    applicableDataTypes: ['string'],
+  },
   [SemanticType.DeletedFlag]: {
     id: SemanticType.DeletedFlag,
     displayName: 'Soft Delete Flag',
@@ -210,27 +406,114 @@ export const DataSemantics: Record<SemanticType, DataSemantic> = {
     description: 'A boolean property that marks the object as deleted without physically removing it.',
     applicableDataTypes: ['boolean'],
   },
-  [SemanticType.ResourceOwnerIdentifier]: {
-    id: SemanticType.ResourceOwnerIdentifier,
-    displayName: 'Resource Owner Identifier',
-    scope: SemanticScope.Association,
-    description: 'Links a resource to a "User" entity instance, indicating ownership for access control.',
+  [SemanticType.Markdown]: {
+    id: SemanticType.Markdown,
+    displayName: 'Markdown Content',
+    scope: SemanticScope.Property,
+    description: 'A text field that contains markdown content.',
+    applicableDataTypes: ['string'],
   },
-  [SemanticType.PublicUniqueName]: {
-    id: SemanticType.PublicUniqueName,
-    displayName: 'Public Unique Name (Slug)',
+  [SemanticType.HTML]: {
+    id: SemanticType.HTML,
+    displayName: 'HTML Content',
     scope: SemanticScope.Property,
-    description: 'A user-friendly, unique public identifier for a resource, often used in URLs.',
+    description: 'Annotates a field that contains HTML content.',
     applicableDataTypes: ['string'],
   },
-  [SemanticType.UserRole]: {
-    id: SemanticType.UserRole,
-    displayName: 'User Role Field',
+  [SemanticType.GeospatialCoordinates]: {
+    id: SemanticType.GeospatialCoordinates,
+    displayName: 'Geospatial Coordinates',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field that holds geospatial coordinate data (latitude/longitude).',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Email]: {
+    id: SemanticType.Email,
+    displayName: 'Email',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as an email address with validation and verification options.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Phone]: {
+    id: SemanticType.Phone,
+    displayName: 'Phone',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as a phone number with validation and formatting options.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Price]: {
+    id: SemanticType.Price,
+    displayName: 'Price',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as a monetary value with currency support and precision control.',
+    applicableDataTypes: ['number', 'string'],
+  },
+  [SemanticType.URL]: {
+    id: SemanticType.URL,
+    displayName: 'URL',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as a URL with validation and allowed protocols.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.SKU]: {
+    id: SemanticType.SKU,
+    displayName: 'SKU',
     scope: SemanticScope.Property,
     description:
-      'A text field that is recognized by the runtime as a role of a user in the API. Used with the role-based authorization strategy.',
+      'Annotates a field as a Stock Keeping Unit (SKU). Enforces uniqueness at the database level, critical for product catalogs. Provides automatic validation and formatting for product identification codes.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Description]: {
+    id: SemanticType.Description,
+    displayName: 'Description',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as a long-form description.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Summary]: {
+    id: SemanticType.Summary,
+    displayName: 'Summary',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as a short summary.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Calculated]: {
+    id: SemanticType.Calculated,
+    displayName: 'Calculated',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as a calculated value based on a formula.',
+    applicableDataTypes: ['string'],
+  },
+  [SemanticType.Derived]: {
+    id: SemanticType.Derived,
+    displayName: 'Derived',
+    scope: SemanticScope.Property,
+    description: 'Annotates a field as derived from other fields.',
     applicableDataTypes: ['string'],
   },
+
+  //
+  // Association-Level Definitions
+  //
+
+  [SemanticType.ResourceOwnerIdentifier]: {
+    id: SemanticType.ResourceOwnerIdentifier,
+    displayName: 'Resource Owner Identifier',
+    scope: SemanticScope.Association,
+    description: 'Links a resource to a "User" entity instance, indicating ownership for access control.',
+  },
+  [SemanticType.Tags]: {
+    id: SemanticType.Tags,
+    displayName: 'Tags',
+    scope: SemanticScope.Association,
+    description: 'Annotates an association as supporting tag functionality.',
+  },
+  [SemanticType.Categories]: {
+    id: SemanticType.Categories,
+    displayName: 'Categories',
+    scope: SemanticScope.Association,
+    description: 'Annotates an association as supporting category functionality.',
+  },
 }
 
 /**

package/src/modeling/definitions/Calculated.ts

@@ -0,0 +1,76 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Calculated semantic.
+ * Controls formula, dependencies, and recalculation behavior.
+ *
+ * Use Calculated when you need mathematical operations, aggregations, or complex business logic.
+ */
+export interface CalculatedConfig {
+  /**
+   * Formula to calculate the value (e.g., 'price * quantity').
+   */
+  formula: string
+  /**
+   * List of field names this calculation depends on.
+   */
+  dependencies?: string[]
+  /**
+   * Whether to recalculate the value on update (default: true).
+   */
+  recalculateOnUpdate?: boolean
+  /**
+   * Whether to allow manual override of the calculated value.
+   */
+  allowManualOverride?: boolean
+  /**
+   * Custom metadata for the calculated field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Calculated semantic.
+ */
+export interface AppliedCalculatedSemantic extends AppliedDataSemantic {
+  id: SemanticType.Calculated
+  config?: CalculatedConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Calculated semantic.
+ */
+export const isCalculatedSemantic = (semantic: AppliedDataSemantic): semantic is AppliedCalculatedSemantic => {
+  return semantic.id === SemanticType.Calculated
+}
+
+/**
+ * Helper function to create a Calculated semantic with configuration.
+ */
+export const createCalculatedSemantic = (config: CalculatedConfig): AppliedCalculatedSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_CALCULATED_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Calculated,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Calculated semantic.
+ */
+export const DEFAULT_CALCULATED_CONFIG: Partial<CalculatedConfig> = {
+  recalculateOnUpdate: true,
+  allowManualOverride: false,
+}

package/src/modeling/definitions/Categories.ts

@@ -0,0 +1,84 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Categories semantic.
+ * Controls allowed categories, hierarchy, and formatting for associations.
+ */
+export interface CategoriesConfig {
+  /**
+   * List of allowed categories.
+   */
+  allowedCategories?: string[]
+  /**
+   * Whether to allow custom categories not in the allowedCategories list.
+   */
+  allowCustomCategories?: boolean
+  /**
+   * Whether to allow hierarchical categories (tree structure).
+   */
+  allowHierarchy?: boolean
+  /**
+   * Maximum depth of the category hierarchy.
+   */
+  maxDepth?: number
+  /**
+   * Whether categories are case sensitive.
+   */
+  caseSensitive?: boolean
+  /**
+   * Whether to allow Unicode characters in categories.
+   */
+  allowUnicode?: boolean
+  /**
+   * Custom metadata for the categories association.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Categories semantic.
+ */
+export interface AppliedCategoriesSemantic extends AppliedDataSemantic {
+  id: SemanticType.Categories
+  config?: CategoriesConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Categories semantic.
+ */
+export const isCategoriesSemantic = (semantic: AppliedDataSemantic): semantic is AppliedCategoriesSemantic => {
+  return semantic.id === SemanticType.Categories
+}
+
+/**
+ * Helper function to create a Categories semantic with configuration.
+ */
+export const createCategoriesSemantic = (config: CategoriesConfig = {}): AppliedCategoriesSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_CATEGORIES_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Categories,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Categories semantic.
+ */
+export const DEFAULT_CATEGORIES_CONFIG: CategoriesConfig = {
+  allowCustomCategories: true,
+  allowHierarchy: true,
+  caseSensitive: false,
+  allowUnicode: false,
+}

package/src/modeling/definitions/Derived.ts

@@ -0,0 +1,76 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Derived semantic.
+ * Controls source fields, transformation, and recalculation behavior.
+ *
+ * Use Derived when you need to combine, format, or transform existing field values
+ */
+export interface DerivedConfig {
+  /**
+   * List of source field names this value is derived from.
+   */
+  sourceFields: string[]
+  /**
+   * Name of a transformation function to apply to the source fields.
+   */
+  transformation?: string
+  /**
+   * Whether to recalculate the value on update (default: true).
+   */
+  recalculateOnUpdate?: boolean
+  /**
+   * Whether to allow manual override of the derived value.
+   */
+  allowManualOverride?: boolean
+  /**
+   * Custom metadata for the derived field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Derived semantic.
+ */
+export interface AppliedDerivedSemantic extends AppliedDataSemantic {
+  id: SemanticType.Derived
+  config?: DerivedConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Derived semantic.
+ */
+export const isDerivedSemantic = (semantic: AppliedDataSemantic): semantic is AppliedDerivedSemantic => {
+  return semantic.id === SemanticType.Derived
+}
+
+/**
+ * Helper function to create a Derived semantic with configuration.
+ */
+export const createDerivedSemantic = (config: DerivedConfig): AppliedDerivedSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_DERIVED_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Derived,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Derived semantic.
+ */
+export const DEFAULT_DERIVED_CONFIG: Partial<DerivedConfig> = {
+  recalculateOnUpdate: true,
+  allowManualOverride: false,
+}

package/src/modeling/definitions/Description.ts

@@ -0,0 +1,55 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Description semantic.
+ * Controls length, formatting, and markdown support.
+ */
+export interface DescriptionConfig {
+  /**
+   * Custom metadata for the description field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Description semantic.
+ */
+export interface AppliedDescriptionSemantic extends AppliedDataSemantic {
+  id: SemanticType.Description
+  config?: DescriptionConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Description semantic.
+ */
+export const isDescriptionSemantic = (semantic: AppliedDataSemantic): semantic is AppliedDescriptionSemantic => {
+  return semantic.id === SemanticType.Description
+}
+
+/**
+ * Helper function to create a Description semantic with configuration.
+ */
+export const createDescriptionSemantic = (config: DescriptionConfig = {}): AppliedDescriptionSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_DESCRIPTION_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Description,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Description semantic.
+ */
+export const DEFAULT_DESCRIPTION_CONFIG: DescriptionConfig = {}