import type { DomainPropertyType } from './DataFormat.js';
/**
 * Defines the names for all available data semantics.
 * Using a string enum makes it easy to add or remove semantics in a single place.
 */
export declare enum SemanticType {
    /**
     * Designates a Data Entity that represents users of the system.
     */
    User = "Semantic#User",
    /**
     * Annotates the field as the user password.
     * The runtime should treat this field with special care,
     * ensuring it is encrypted and not exposed in API responses.
     */
    Password = "Semantic#Password",
    /**
     * Annotates the field as the username for user authentication.
     * This identifies which field should be used for login purposes.
     * Can be applied to dedicated username fields or email fields that serve as usernames.
     * The runtime uses this for authentication, password reset, and user lookup operations.
     */
    Username = "Semantic#Username",
    /**
     * Designates a Data Property as the `createdAt` timestamp of an entity.
     * This is used to track when the entity was first created.
     */
    CreatedTimestamp = "Semantic#CreatedTimestamp",
    /**
     * Designates a Data Property as the `updatedAt` timestamp of an entity.
     * This is used to track when the entity was last modified.
     */
    UpdatedTimestamp = "Semantic#UpdatedTimestamp",
    /**
     * Designates a Data Property as the `deletedAt` timestamp of an entity.
     * This is used to track when the entity was soft-deleted.
     * Soft-deletion means the entity is not physically removed from the database,
     * but marked as deleted for logical deletion purposes.
     */
    DeletedTimestamp = "Semantic#DeletedTimestamp",
    /**
     * Designates a Data Property as a boolean flag indicating whether the entity is deleted.
     * This is used for soft-deletion, where the entity is not physically removed from the database,
     * but marked as deleted.
     */
    DeletedFlag = "Semantic#DeletedFlag",
    /**
     * Designates a Data Property as a 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".
     * The runtime automatically generates a URL-safe string from another field (like a title).
     * By default, slugs are generated to be unique, but the configuration allows for duplicates
     * in scenarios where uniqueness is handled by a combination of fields (e.g., year and 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.
     * For example, a user with the role of "admin" would have elevated permissions
     * compared to a user with the role of "guest".
     * 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.
     *
     * As a semantic, it provides flexibility by annotating a base `number` or `string` type,
     * allowing for different storage strategies (e.g., decimal, integer cents, or a JSON object)
     * while maintaining a consistent API for currency operations.
     */
    Currency = "Semantic#Currency",
    /**
     * 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",
    /**
     * Annotates a field that should automatically receive the client's IP address.
     * The runtime automatically populates this field with the request's IP address
     * when creating or updating records, providing audit trail and geolocation capabilities.
     */
    ClientIPAddress = "Semantic#ClientIPAddress",
    /**
     * 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"
}
/**
 * Defines the scope at which a semantic can be applied.
 */
export declare enum SemanticScope {
    /**
     * The semantic applies to an entire Data Entity.
     * This is used for semantics that provide context or constraints at the entity level.
     */
    Entity = "Entity",
    /**
     * The semantic applies to a single Data Property.
     * This is used for semantics that provide context or constraints at the property level.
     */
    Property = "Property",
    /**
     * The semantic applies to an Association between Data Entities.
     * This is used for semantics that provide context or constraints at the association level.
     */
    Association = "Association"
}
/**
 * Defines categories for organizing semantics in the UI.
 */
export declare enum SemanticCategory {
    /**
     * User management, authentication, and access control
     */
    Identity = "Identity & Authentication",
    /**
     * Timestamps, versioning, and record lifecycle
     */
    Lifecycle = "Timestamps & Versioning",
    /**
     * Text content, media, and rich content types
     */
    Content = "Content & Media",
    /**
     * Business-specific data like pricing, inventory, status
     */
    Business = "Business Data",
    /**
     * Contact information and communication
     */
    Contact = "Contact Information",
    /**
     * Organization, categorization, and tagging
     */
    Organization = "Classification & Organization",
    /**
     * Location and geographical data
     */
    Location = "Location & Geography",
    /**
     * Calculated and derived values
     */
    Computed = "Computed Values"
}
/**
 * Defines when a semantic should execute in relation to database operations.
 */
export declare enum SemanticTiming {
    /**
     * Execute before the database operation (validation, preprocessing)
     */
    Before = "Before",
    /**
     * Execute after the database operation (cleanup, notifications, derived values)
     */
    After = "After",
    /**
     * Execute both before and after the operation
     */
    Both = "Both",
    /**
     * No automatic execution (manual/on-demand only)
     */
    None = "None"
}
/**
 * Defines which database operations can trigger a semantic.
 */
export declare enum SemanticOperation {
    Create = "Create",
    Read = "Read",
    Update = "Update",
    Delete = "Delete",
    /**
     * Special operation for list/query operations
     */
    List = "List"
}
/**
 * Defines the execution mode for a semantic.
 */
export declare enum SemanticExecutionMode {
    /**
     * Execute synchronously as part of the main operation
     */
    Synchronous = "Synchronous",
    /**
     * Execute asynchronously after the main operation
     */
    Asynchronous = "Asynchronous",
    /**
     * Execute in background/queue (fire and forget)
     */
    Background = "Background"
}
/**
 * Defines validation strategies for semantics.
 */
export declare enum SemanticValidationStrategy {
    /**
     * Fail the operation if semantic validation fails
     */
    Strict = "Strict",
    /**
     * Log warnings but continue operation
     */
    Warning = "Warning",
    /**
     * Skip validation entirely
     */
    Skip = "Skip"
}
/**
 * Defines caching strategies for computed semantics.
 */
export declare enum SemanticCacheStrategy {
    /**
     * No caching - always compute
     */
    None = "None",
    /**
     * Cache until dependent fields change
     */
    Dependency = "Dependency",
    /**
     * Cache with TTL expiration
     */
    TimeToLive = "TimeToLive",
    /**
     * Cache until manually invalidated
     */
    Manual = "Manual"
}
/**
 * Configuration for when and how a semantic should execute at runtime.
 */
export interface SemanticRuntimeConfig {
    /**
     * When the semantic should execute relative to the database operation.
     */
    timing: SemanticTiming;
    /**
     * Which database operations should trigger this semantic.
     */
    operations: SemanticOperation[];
    /**
     * Priority order for execution when multiple semantics apply.
     * Lower numbers execute first. Default is 100.
     */
    priority?: number;
    /**
     * Whether this semantic can be disabled at the entity/property level.
     */
    canDisable?: boolean;
    /**
     * How the semantic should execute (sync/async/background).
     * Default is Synchronous.
     * @default Synchronous
     */
    executionMode?: SemanticExecutionMode;
    /**
     * Validation strategy when semantic processing fails.
     * Default is Strict.
     * @default Strict
     */
    validationStrategy?: SemanticValidationStrategy;
    /**
     * Maximum execution time in milliseconds before timeout.
     * Default is 5000ms for sync, 30000ms for async.
     * @default 5000 for sync, 30000 for async
     */
    timeoutMs?: number;
    /**
     * Number of retry attempts on failure.
     * Default is 0 (no retries).
     * @default 0
     */
    retryAttempts?: number;
    /**
     * Dependencies on other semantics that must execute first.
     * Uses semantic IDs.
     */
    dependencies?: SemanticType[];
    /**
     * Fields that this semantic depends on for computation.
     * Used for cache invalidation and optimization.
     */
    dependentFields?: string[];
    /**
     * Caching strategy for computed/derived values.
     */
    cacheStrategy?: SemanticCacheStrategy;
    /**
     * Cache TTL in seconds (only used with TimeToLive strategy).
     */
    cacheTtlSeconds?: number;
    /**
     * Whether this semantic should run in transactions.
     * Default is true.
     */
    transactional?: boolean;
    /**
     * Rate limiting configuration for expensive operations.
     */
    rateLimit?: SemanticRateLimit;
    /**
     * Conditional execution based on data or context.
     */
    conditions?: SemanticCondition[];
    /**
     * Audit and logging configuration.
     */
    audit?: SemanticAudit;
}
export interface SemanticRateLimit {
    /**
     * Maximum executions per time window.
     */
    maxExecutions: number;
    /**
     * Time window in seconds.
     */
    windowSeconds: number;
    /**
     * Strategy when rate limit is exceeded.
     */
    strategy: 'queue' | 'drop' | 'error';
}
export interface SemanticCondition {
    /**
     * JEXL expression that must evaluate to true for execution.
     * Has access to entity data, user context, and semantic field references.
     *
     * Available context variables:
     * - `entity`: The entity data being processed
     * - `user`: Current user context (if authenticated)
     * - `operation`: The current operation (Create, Update, etc.)
     * - `semantics`: Object with semantic field accessors
     *
     * Semantic field references use dot notation:
     * - `semantics.CreatedTimestamp` - field with CreatedTimestamp semantic
     * - `semantics.Password` - field with Password semantic
     * - `semantics.User` - entity with User semantic (for associations)
     *
     * @example
     * // Only set timestamp if not already provided
     * "semantics.CreatedTimestamp == null"
     *
     * @example
     * // Only apply to authenticated users
     * "user != null && user.authenticated == true"
     *
     * @example
     * // Only hash password if it's a plain text (not already hashed)
     * "entity[semantics.Password] != null && !entity[semantics.Password].startsWith('$')"
     *
     * @example
     * // Only generate slug if title exists
     * "entity[semantics.Title] != null && entity[semantics.Title].length > 0"
     */
    expression: string;
    /**
     * Description of when this semantic should run.
     */
    description: string;
}
export interface SemanticAudit {
    /**
     * Whether to log semantic execution.
     */
    logExecution: boolean;
    /**
     * Whether to log input/output data.
     */
    logData: boolean;
    /**
     * Retention period for audit logs in days.
     */
    retentionDays: number;
}
/**
 * A base interface for all Data Semantics, containing common properties.
 * A semantic is an annotation applied to a Data Entity, Property, or Association
 * to provide additional context or constraints.
 * This interface is extended by more specific semantic types.
 */
interface BaseDataSemantic {
    /**
     * A unique identifier for the semantic definition.
     */
    id: SemanticType;
    /**
     * A human-readable name for the semantic.
     */
    displayName: string;
    /**
     * A description of the semantic's purpose and impact.
     */
    description: string;
    /**
     * Specifies whether the semantic applies to an Entity, Property, or Association.
     */
    scope: SemanticScope;
    /**
     * The category this semantic belongs to for UI organization.
     */
    category: SemanticCategory;
    /**
     * Whether the semantic has a configuration or additional options.
     * This is used to determine if the semantic requires additional setup or configuration.
     */
    hasConfig: boolean;
    /**
     * Runtime execution configuration for this semantic.
     */
    runtime: SemanticRuntimeConfig;
}
/**
 * Represents a semantic that can be applied to an entire Data Entity.
 */
export interface EntitySemantic extends BaseDataSemantic {
    scope: SemanticScope.Entity;
}
/**
 * Represents a semantic that can be applied to a single property.
 */
export interface PropertySemantic extends BaseDataSemantic {
    scope: SemanticScope.Property;
    /**
     * Optional array of data types this semantic can be applied to.
     * Enforces constraints, e.g., DeletedTimestamp on a DateTime property.
     */
    applicableDataTypes?: DomainPropertyType[];
}
/**
 * Represents a semantic that can be applied to an association between entities.
 */
export interface AssociationSemantic extends BaseDataSemantic {
    scope: SemanticScope.Association;
}
/**
 * A type guard to check if a semantic is an EntitySemantic.
 */
export declare const isEntitySemantic: (semantic: DataSemantic) => semantic is EntitySemantic;
/**
 * A type guard to check if a semantic is a PropertySemantic.
 */
export declare const isPropertySemantic: (semantic: DataSemantic) => semantic is PropertySemantic;
/**
 * A type guard to check if a semantic is a AssociationSemantic.
 */
export declare const isAssociationSemantic: (semantic: DataSemantic) => semantic is AssociationSemantic;
/**
 * Union type for any kind of data semantic
 */
export type DataSemantic = EntitySemantic | PropertySemantic | AssociationSemantic;
/**
 * A map to store the definitions of all available data semantics.
 * This acts as a central registry for the application.
 */
export declare const DataSemantics: Record<SemanticType, DataSemantic>;
/**
 * Get all semantics that should run for a specific operation and timing
 */
export declare function getSemanticsForOperation(semantics: AppliedDataSemantic[], operation: SemanticOperation, timing: SemanticTiming): AppliedDataSemantic[];
/**
 * Check if a specific semantic can be disabled at runtime
 */
export declare function canSemanticBeDisabled(semanticType: SemanticType): boolean;
export declare function getSemanticsByCategory(): Record<SemanticCategory, DataSemantic[]>;
export declare function getSemanticsByCategory(scope: SemanticScope.Entity): Record<SemanticCategory, EntitySemantic[]>;
export declare function getSemanticsByCategory(scope: SemanticScope.Property): Record<SemanticCategory, PropertySemantic[]>;
export declare function getSemanticsByCategory(scope: SemanticScope.Association): Record<SemanticCategory, AssociationSemantic[]>;
/**
 * Helper function to get semantics for a specific category.
 * @param category The category to filter by
 * @returns Array of semantics in the specified category
 */
export declare const getSemanticsByCategoryType: (category: SemanticCategory) => DataSemantic[];
/**
 * Represents the application of a data semantic to a specific
 * entity or property within a user's data model.
 */
export interface AppliedDataSemantic {
    /**
     * The unique identifier of the semantic being applied.
     */
    id: SemanticType;
    /**
     * Optional configuration or values specific to this application.
     */
    config?: Record<string, unknown>;
}
export {};
//# sourceMappingURL=Semantics.d.ts.map