@stndrds/schema 1.0.0-alpha.95 → 1.0.0-alpha.97

package/dist/attributes-C-bhC0k5.d.ts

@@ -0,0 +1,673 @@
+import { IconName, CountryIso3, CurrencyCode, ColorId, MimeType } from '@stndrds/constants';
+import { Uuid } from './utils.js';
+
+/**
+ * Feature flag levels (resolution priority: user > tenant > global).
+ *
+ * - `global`: Applies to all tenants and users
+ * - `tenant`: Applies to a specific tenant
+ * - `user`: Applies to a specific user within a tenant
+ */
+type FlagLevel = "global" | "tenant" | "user";
+/**
+ * Flag value types supported by the system.
+ */
+type FlagValueType = "boolean" | "string" | "number" | "json";
+/**
+ * Definition of a feature flag.
+ * Created using the flag builders (booleanFlag, stringFlag, etc.)
+ */
+interface FeatureFlagDefinition<T = unknown> {
+    /** Unique identifier for the flag (kebab-case) */
+    name: string;
+    /** Human-readable label */
+    label: string;
+    /** Optional description */
+    description?: string;
+    /** Type of the flag value */
+    valueType: FlagValueType;
+    /** Default value when no override exists */
+    defaultValue: T;
+    /** Levels at which this flag can be overridden */
+    allowedLevels: FlagLevel[];
+    /** Grouping category for UI */
+    category?: string;
+    /** System flag - cannot be modified via API */
+    system?: boolean;
+}
+/**
+ * Stored override for a feature flag.
+ * Represents a row in the feature_flag_overrides table.
+ */
+interface FlagOverride<T = unknown> {
+    /** Name of the flag being overridden */
+    flagName: string;
+    /** Level of the override */
+    level: FlagLevel;
+    /** Target ID (tenantId for tenant-level, userId for user-level) */
+    targetId?: string;
+    /** Override value */
+    value: T;
+    /** Optional expiration date */
+    expiresAt?: Date;
+    /** Who created this override */
+    createdBy?: string;
+    /** When the override was created */
+    createdAt: Date;
+    /** When the override was last updated */
+    updatedAt: Date;
+}
+/**
+ * Resolved flag value with source information.
+ * Result of flag resolution including where the value came from.
+ */
+interface ResolvedFlag<T = unknown> {
+    /** Flag name */
+    name: string;
+    /** Resolved value */
+    value: T;
+    /** Where the value came from */
+    source: FlagLevel | "default";
+    /** ID of the source (tenantId or userId) if not default */
+    sourceId?: string;
+}
+/**
+ * Feature gate configuration for conditional attribute visibility.
+ * Used with the `.featureGate()` builder method.
+ */
+interface FeatureGate {
+    /** Name of the flag to check */
+    flag: string;
+    /**
+     * Expected value for the gate to pass.
+     * For boolean flags, defaults to `true`.
+     * For other types, compares with strict equality.
+     */
+    expectedValue?: unknown;
+    /**
+     * Behavior when the gate fails.
+     * - `hide`: Attribute is completely hidden (default)
+     * - `show`: Attribute is shown regardless (no gating)
+     * - `disable`: Attribute is visible but read-only
+     */
+    fallback?: "hide" | "show" | "disable";
+}
+/**
+ * Repository interface for feature flag overrides storage.
+ * Added to DatabaseAdapter as an optional repository.
+ *
+ * If not provided, only static defaults from module config are used.
+ */
+interface FeatureFlagsRepository {
+    /**
+     * Get all overrides matching the criteria.
+     * Returns overrides from the database (global, tenant, or user level).
+     */
+    getOverrides(options: {
+        /** Filter by level */
+        level?: FlagLevel;
+        /** Filter by target ID (tenantId or userId) */
+        targetId?: string;
+        /** Filter by flag names (for efficient single/batch lookups) */
+        flagNames?: string[];
+    }): Promise<FlagOverride[]>;
+    /**
+     * Create or update an override.
+     * Uses upsert semantics based on (flagName, level, targetId).
+     */
+    setOverride(override: Omit<FlagOverride, "createdAt" | "updatedAt">): Promise<FlagOverride>;
+    /**
+     * Delete an override.
+     */
+    deleteOverride(flagName: string, level: FlagLevel, targetId?: string): Promise<void>;
+}
+/**
+ * Static flag default value for module configuration.
+ */
+interface StaticFlagDefault {
+    /** Flag name */
+    name: string;
+    /** Default value */
+    value: unknown;
+}
+/**
+ * Feature flags configuration for SchemaModule.
+ */
+interface FeatureFlagsConfig {
+    /**
+     * Static default values for flags.
+     * These are always applied and used when no database override exists.
+     *
+     * @example
+     * ```typescript
+     * featureFlags: {
+     *   defaults: [
+     *     { name: "architect-mode", value: false },
+     *     { name: "ai-chat", value: false },
+     *     { name: "tier", value: "free" },
+     *   ],
+     * }
+     * ```
+     */
+    defaults?: StaticFlagDefault[];
+}
+
+/**
+ * Allowed attribute types in .qualifyWith()
+ *
+ * IMPORTANT: Complex types (formula, rollup, relation, file, user, document, richtext)
+ * are NOT supported to avoid duplicating backend behavior.
+ */
+type PropertyType = "text" | "textarea" | "number" | "checkbox" | "date" | "phone" | "currency" | "status" | "select" | "multiselect" | "rating" | "location";
+/**
+ * Forbidden property types that would require complex backend duplication
+ */
+declare const FORBIDDEN_PROPERTY_TYPES: readonly ["formula", "rollup", "relation", "file", "user", "document", "richtext"];
+type ForbiddenPropertyType = (typeof FORBIDDEN_PROPERTY_TYPES)[number];
+/**
+ * Union of attribute types allowed as qualified relation properties.
+ *
+ * These are the same Attribute types used for object attributes,
+ * restricted to simple types that don't require complex backend duplication.
+ */
+type PropertyAttribute = TextAttribute | TextAreaAttribute | NumberAttribute | CheckboxAttribute | DateAttribute | PhoneAttribute | CurrencyAttribute | StatusAttribute | SelectAttribute | MultiselectAttribute | RatingAttribute | LocationAttribute;
+/**
+ * Schema defining properties for a qualified relation.
+ *
+ * Uses the same Attribute types as object attributes, enabling DRY builders:
+ *
+ * @example
+ * ```typescript
+ * relation({ name: "companies", label: "Companies" })
+ *   .to("companies").many()
+ *   .qualifyWith(
+ *     select({ name: "role", label: "Role" }).options([...]).required(),
+ *     number({ name: "shares", label: "Shares" }).min(0),
+ *   )
+ * ```
+ */
+interface PropertySchema {
+    definitions: PropertyAttribute[];
+}
+/**
+ * Property attribute types that have an `options` array.
+ */
+type OptionPropertyAttribute = SelectAttribute | StatusAttribute | MultiselectAttribute;
+/**
+ * Type guard to check if a property attribute has options.
+ *
+ * @param attr - The property attribute to check
+ * @returns true if the attribute is a select, status, or multiselect type with options
+ *
+ * @example
+ * ```typescript
+ * for (const def of definitions) {
+ *   if (hasOptions(def)) {
+ *     // TypeScript knows def.options exists and is Option[]
+ *     for (const option of def.options) {
+ *       console.log(option.value);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function hasOptions(attr: PropertyAttribute): attr is OptionPropertyAttribute;
+
+type AttributeType = "text" | "textarea" | "richtext" | "number" | "checkbox" | "date" | "phone" | "currency" | "status" | "location" | "select" | "multiselect" | "file" | "user" | "relation" | "rating" | "formula" | "rollup" | "document";
+/**
+ * Status group categorization
+ */
+type StatusGroup = "idle" | "in_progress" | "finished";
+/**
+ * Unified option type for select-like fields
+ */
+interface Option {
+    id: string;
+    label: string;
+    value: string;
+    color?: ColorId;
+    icon?: IconName;
+    description?: string;
+    group?: StatusGroup;
+    /** Value of the inverse option for bilateral relations (e.g. "parent" → "child") */
+    inverse?: string;
+}
+/**
+ * Attribute grouping for UI organization
+ */
+interface AttributeGroup {
+    id: string;
+    label: string;
+    description?: string;
+    attributeIds: string[];
+    collapsible?: boolean;
+    collapsed?: boolean;
+    order?: number;
+}
+interface BaseAttribute<DefaultValueType = unknown> {
+    id: Uuid;
+    name: string;
+    label: string;
+    type: AttributeType;
+    required: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    description?: string;
+    defaultValue?: DefaultValueType;
+    icon?: IconName;
+    order?: number;
+    hidden?: boolean;
+    archived?: boolean;
+    deprecated?: boolean;
+    system?: boolean;
+    /**
+     * Feature gate to conditionally show/hide/disable this attribute.
+     * When the flag condition is not met, the attribute behavior depends on `fallback`:
+     * - "hide" (default): Attribute is completely hidden
+     * - "disable": Attribute is visible but read-only
+     * - "show": No gating (useful for overriding parent settings)
+     */
+    featureGate?: FeatureGate;
+    metadata?: Record<string, unknown>;
+}
+interface TextAttribute extends BaseAttribute<string> {
+    type: "text";
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+type NumberUnit = "integer" | "decimal" | "percentage";
+interface NumberAttribute extends BaseAttribute<number> {
+    type: "number";
+    min?: number;
+    max?: number;
+    unit?: NumberUnit;
+    decimals?: number;
+}
+interface CheckboxAttribute extends BaseAttribute<boolean> {
+    type: "checkbox";
+}
+type DateFormat = "short" | "long" | "full" | "relative";
+type DateValue = string | "today";
+interface DateAttribute extends BaseAttribute<string> {
+    type: "date";
+    dateFormat?: DateFormat;
+    minDate?: DateValue;
+    maxDate?: DateValue;
+}
+interface Phone {
+    countryCode: CountryIso3;
+    phoneNumber: string;
+}
+interface PhoneAttribute extends BaseAttribute<Phone> {
+    type: "phone";
+    defaultCountryCode?: CountryIso3;
+}
+interface Currency {
+    code: CurrencyCode;
+    value: number;
+}
+interface CurrencyAttribute extends BaseAttribute<Currency> {
+    type: "currency";
+    defaultCurrency?: CurrencyCode;
+    allowedCurrencies?: CurrencyCode[];
+}
+/**
+ * StatusAttribute - For workflow states with semantic grouping (idle/in_progress/finished)
+ * Use this for: Task status, Order status, Project phases, Process states
+ * Use SelectAttribute for: Categories, Types, simple choices without workflow
+ */
+interface StatusAttribute extends BaseAttribute<string> {
+    type: "status";
+    options: Option[];
+}
+interface Location {
+    address?: string;
+    address2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: CountryIso3;
+    latitude?: number;
+    longitude?: number;
+}
+type LocationGranularity = "full" | "address" | "city" | "state" | "country" | "coordinates";
+interface LocationAttribute extends BaseAttribute<Location> {
+    type: "location";
+    granularity: LocationGranularity;
+    enableAutocomplete?: boolean;
+    enableMap?: boolean;
+    defaultCountry?: CountryIso3;
+    allowedCountries?: CountryIso3[];
+    displayFormat?: "single_line" | "multi_line" | "compact";
+}
+/**
+ * SelectAttribute - For simple single-choice selection
+ * Use this for: Categories, Document types, Departments, Priorities
+ * Options can be grouped (e.g., countries by continent) but no workflow logic
+ */
+interface SelectAttribute extends BaseAttribute<string> {
+    type: "select";
+    options: Option[];
+}
+interface MultiselectAttribute extends BaseAttribute<string[]> {
+    type: "multiselect";
+    options: Option[];
+}
+interface FileAttribute extends BaseAttribute<string> {
+    type: "file";
+    maxFiles?: number;
+    maxSize?: number;
+    allowedTypes?: MimeType[] | readonly MimeType[];
+    multiple?: boolean;
+}
+interface UserAttribute extends BaseAttribute<string> {
+    type: "user";
+    allowedRoles?: string[];
+    multiple?: boolean;
+}
+/**
+ * Wildcard marker for universal relations (can link to any object)
+ * Use with `.toAny()` builder method
+ */
+declare const RELATION_TARGET_ANY: "*";
+/**
+ * Configuration for bilateral synchronization (bidirectional relations)
+ */
+interface BilateralConfig {
+    /** Target object containing the inverse attribute */
+    object: string;
+    /** Name of the inverse attribute */
+    attribute: string;
+    /** Optional cardinality override (inferred by default) */
+    cardinality?: "one" | "many";
+    /** When true, this side owns the storage direction for qualified properties.
+     *  Set to false on the inverse side (enriched at read time). */
+    storageOwner?: boolean;
+}
+/**
+ * Target object for a relation - defines which objects can be linked
+ */
+interface RelationTarget {
+    /** Object name (e.g., "companies", "contacts") or "*" for any object */
+    object: string;
+    /**
+     * Display template for the label using mustache-like syntax
+     * @example "{name}" or "{firstName} {lastName} — {email}"
+     */
+    displayTemplate?: string;
+    /**
+     * Optional filter to restrict available records
+     * @example { status: "active" }
+     */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Base properties shared by both single and multi relation attributes
+ *
+ * Note: Deletion behavior is always "restrict" - if a record is referenced
+ * by other records, it cannot be deleted until those references are removed.
+ * This is enforced by RecordService.deleteRecord() which throws
+ * RecordReferencedError when attempting to delete a referenced record.
+ */
+interface RelationAttributeBase extends Omit<BaseAttribute<unknown>, "defaultValue"> {
+    type: "relation";
+    /** Target objects that can be linked */
+    targets: RelationTarget[];
+    /** Optional properties schema for qualified relations */
+    properties?: PropertySchema;
+    /** Configuration for bilateral synchronization (opt-in) */
+    bilateral?: BilateralConfig;
+}
+/**
+ * Single relation attribute (one-to-one or many-to-one)
+ * Stores a single record ID or null
+ */
+interface SingleRelationAttribute extends RelationAttributeBase {
+    cardinality: "one";
+    defaultValue?: string | null;
+}
+/**
+ * Multi relation attribute (one-to-many or many-to-many)
+ * Stores an array of record IDs
+ */
+interface MultiRelationAttribute extends RelationAttributeBase {
+    cardinality: "many";
+    defaultValue?: string[];
+    /** Minimum number of relations required */
+    minItems?: number;
+    /** Maximum number of relations allowed */
+    maxItems?: number;
+}
+/**
+ * RelationAttribute links to other objects/records
+ * Discriminated union by cardinality for type-safe value handling
+ *
+ * @example Single relation (many-to-one)
+ * ```typescript
+ * relation({ name: "company", label: "Company" })
+ *   .to("companies")
+ *   .required()
+ * // → Value: "rec-uuid-123" | null
+ * ```
+ *
+ * @example Multi relation (many-to-many)
+ * ```typescript
+ * relation({ name: "contacts", label: "Contacts" })
+ *   .to("contacts", { displayTemplate: "{firstName} {lastName}" })
+ *   .many()
+ *   .maxItems(5)
+ * // → Value: ["rec-1", "rec-2", ...]
+ * ```
+ *
+ * @example Polymorphic relation (multiple target objects)
+ * ```typescript
+ * relation({ name: "linked", label: "Linked Items" })
+ *   .to("companies")
+ *   .to("contacts")
+ *   .to("deals")
+ *   .many()
+ * // → Can link to records from any of these objects
+ * ```
+ */
+type RelationAttribute = SingleRelationAttribute | MultiRelationAttribute;
+/**
+ * Check if a relation attribute is universal (can link to any object)
+ * Universal relations have `targets: [{ object: "*" }]`
+ */
+declare function isUniversalRelation(attr: RelationAttribute): boolean;
+/**
+ * Check if a relation attribute has bilateral synchronization enabled
+ */
+declare function isBilateralRelation(attr: RelationAttribute): attr is RelationAttribute & {
+    bilateral: BilateralConfig;
+};
+/**
+ * Infer the cardinality of the inverse relation
+ * - one → many (contact.company ↔ company.contacts)
+ * - many → many (contact.tags ↔ tag.contacts)
+ */
+declare function inferInverseCardinality(cardinality: "one" | "many"): "one" | "many";
+interface TextAreaAttribute extends BaseAttribute<string> {
+    type: "textarea";
+}
+/**
+ * Available features for richtext editor
+ */
+type RichtextFeature = "headings" | "bold" | "italic" | "lists" | "links" | "images" | "codeBlocks" | "tables";
+/**
+ * RichtextAttribute - Rich text content using semantic markdown
+ *
+ * Stores content as semantic markdown string (with directives like :::callout).
+ * Parsed at runtime to Tiptap JSON for editing.
+ * Use this for: Notes, articles, descriptions, long-form content.
+ *
+ * @example
+ * ```typescript
+ * richtext({ name: "content", label: "Content" })
+ *   .features(["headings", "bold", "italic", "lists", "links"])
+ *   .required()
+ * ```
+ */
+interface RichtextAttribute extends BaseAttribute<string> {
+    type: "richtext";
+    /** Enabled features. If undefined, all features are enabled. */
+    features?: RichtextFeature[];
+}
+interface RatingAttribute extends BaseAttribute<number> {
+    type: "rating";
+    max?: number;
+    iconType?: "star" | "heart" | "thumbs" | "number";
+}
+/**
+ * Return type for formula expressions
+ */
+type FormulaReturnType = "text" | "number" | "boolean" | "date";
+/**
+ * FormulaAttribute - Computed value based on other attributes
+ *
+ * Formulas are calculated at read-time and are always read-only.
+ * Users cannot directly edit formula values.
+ *
+ * @example Simple calculation
+ * ```typescript
+ * formula({ name: "total", label: "Total" })
+ *   .expression("price * quantity")
+ *   .returns("number")
+ *   .decimals(2)
+ * ```
+ *
+ * @example With functions
+ * ```typescript
+ * formula({ name: "fullName", label: "Full Name" })
+ *   .expression("CONCAT(firstName, ' ', lastName)")
+ *   .returns("text")
+ * ```
+ */
+interface FormulaAttribute extends Omit<BaseAttribute<never>, "defaultValue" | "required"> {
+    type: "formula";
+    /** Expression to evaluate (e.g., "price * quantity") */
+    expression: string;
+    /** Expected return type for formatting */
+    returnType: FormulaReturnType;
+    /** Decimal places for number results */
+    decimals?: number;
+    /** Whether to allow relation references in the expression (e.g., "company.name") */
+    allowRelations?: boolean;
+    /** Formula is always not required (read-only) */
+    required: false;
+}
+/**
+ * Aggregation functions for rollup attributes
+ *
+ * Categories:
+ * - Numeric (sum, avg): Only for number, currency, rating types
+ * - Date (earliest, latest): Only for date type
+ * - Count (count, countValues, countUniqueValues, countEmpty): Universal
+ * - Percent (percentEmpty, percentNotEmpty): Universal
+ * - Lookup (original): Returns all values as array, rendered as target type
+ */
+type RollupFunction = "sum" | "avg" | "earliest" | "latest" | "count" | "countValues" | "countUniqueValues" | "countEmpty" | "percentEmpty" | "percentNotEmpty" | "original";
+/**
+ * RollupAttribute - Aggregates values from related records
+ *
+ * Rollups are calculated and stored (denormalized) for performance.
+ * They are automatically recalculated when related records change.
+ * Users cannot directly edit rollup values.
+ *
+ * @example Sum of related amounts
+ * ```typescript
+ * rollup({ name: "totalOrders", label: "Total Orders" })
+ *   .from("orders")           // relation attribute name
+ *   .aggregate("amount")      // target attribute to sum
+ *   .using("sum")
+ *   .decimals(2)
+ * ```
+ *
+ * @example Count of related records
+ * ```typescript
+ * rollup({ name: "orderCount", label: "Number of Orders" })
+ *   .from("orders")
+ *   .using("count")
+ * ```
+ */
+interface RollupAttribute extends Omit<BaseAttribute<never>, "defaultValue" | "required"> {
+    type: "rollup";
+    /** Name of the relation attribute on this object */
+    relationAttribute: string;
+    /**
+     * Dot notation path for multi-level traversal (Phase 4+)
+     * @example "orders.items" - traverse through orders to items
+     */
+    relationPath?: string;
+    /** Attribute name on the target object to aggregate */
+    targetAttribute: string;
+    /** Aggregation function to apply */
+    function: RollupFunction;
+    /** Decimal places for numeric results */
+    decimals?: number;
+    /** Rollup is always not required (read-only) */
+    required: false;
+    /**
+     * Cached type of the target attribute for display purposes
+     * Used when function="original" to render values as the target type
+     */
+    targetAttributeType?: AttributeType;
+    /**
+     * Cached options from target attribute (for select/status/multiselect display)
+     * Required when function="original" and target is a select-like type
+     */
+    targetAttributeOptions?: Option[];
+}
+/**
+ * DocumentAttribute - References one or multiple structured documents.
+ *
+ * Unlike FileAttribute which stores raw file references, DocumentAttribute
+ * provides structured document handling with multi-file support and
+ * optional agent-compatible processing (for example OCR).
+ *
+ * @example Single document
+ * ```typescript
+ * document({ name: "identityDocument", label: "Pièce d'identité" })
+ *   .autoProcess()
+ *   .required()
+ * ```
+ *
+ * @example Multiple documents
+ * ```typescript
+ * document({ name: "contracts", label: "Contrats" })
+ *   .multiple()
+ *   .maxDocuments(10)
+ * ```
+ */
+interface DocumentAttribute extends BaseAttribute<string | string[]> {
+    type: "document";
+    /**
+     * Allow multiple documents.
+     * If true, value is string[] (document IDs).
+     * If false/undefined, value is string (single document ID).
+     */
+    multiple?: boolean;
+    /**
+     * Maximum number of documents when multiple: true.
+     */
+    maxDocuments?: number;
+    /**
+     * Automatically trigger agent-compatible processing on upload.
+     */
+    autoProcess?: boolean;
+}
+type Attribute = TextAttribute | TextAreaAttribute | RichtextAttribute | NumberAttribute | CheckboxAttribute | DateAttribute | PhoneAttribute | CurrencyAttribute | StatusAttribute | LocationAttribute | SelectAttribute | MultiselectAttribute | FileAttribute | UserAttribute | RelationAttribute | RatingAttribute | FormulaAttribute | RollupAttribute | DocumentAttribute;
+/**
+ * Attribute types that are not sortable by default.
+ * These types have complex/binary values without a meaningful natural order.
+ */
+declare const NON_SORTABLE_TYPES: ReadonlySet<AttributeType>;
+/**
+ * Check if an attribute supports sorting based on its type.
+ */
+declare function isAttributeSortable(attr: {
+    type: AttributeType;
+}): boolean;
+
+export { type PropertyType as $, type Attribute as A, type BilateralConfig as B, type CurrencyAttribute as C, type DateAttribute as D, type AttributeGroup as E, type FileAttribute as F, type BaseAttribute as G, type DateFormat as H, type DateValue as I, FORBIDDEN_PROPERTY_TYPES as J, type FeatureFlagsConfig as K, type LocationAttribute as L, type MultiRelationAttribute as M, type NumberAttribute as N, type Option as O, type PhoneAttribute as P, type FlagOverride as Q, type RelationAttribute as R, type SingleRelationAttribute as S, type TextAreaAttribute as T, type UserAttribute as U, type ForbiddenPropertyType as V, NON_SORTABLE_TYPES as W, type NumberUnit as X, type OptionPropertyAttribute as Y, type PropertyAttribute as Z, type PropertySchema as _, type RichtextAttribute as a, RELATION_TARGET_ANY as a0, type StatusGroup as a1, hasOptions as a2, inferInverseCardinality as a3, isAttributeSortable as a4, isBilateralRelation as a5, isUniversalRelation as a6, type MultiselectAttribute as b, type SelectAttribute as c, type StatusAttribute as d, type FormulaAttribute as e, type RollupAttribute as f, type CheckboxAttribute as g, type RatingAttribute as h, type TextAttribute as i, type AttributeType as j, type LocationGranularity as k, type Location as l, type Phone as m, type Currency as n, type DocumentAttribute as o, type FeatureGate as p, type RichtextFeature as q, type RelationTarget as r, type FormulaReturnType as s, type RollupFunction as t, type FlagValueType as u, type FeatureFlagDefinition as v, type FlagLevel as w, type FeatureFlagsRepository as x, type StaticFlagDefault as y, type ResolvedFlag as z };