@objectstack/spec 0.1.0

package/dist/types/meta/object-entity.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Object Entity Interface
+ *
+ * Defines the structure of an entity in the ObjectStack metamodel.
+ * Entities represent data models/tables with their fields and relationships.
+ *
+ * @module types/meta/object-entity
+ */
+import { ObjectField } from './object-field';
+/**
+ * Represents an entity definition in the ObjectStack metamodel
+ *
+ * @remarks
+ * ObjectEntity is the core data model definition. It describes a logical
+ * entity (like User, Account, Product) with its fields, constraints,
+ * and metadata. This interface is used by:
+ *
+ * - ObjectQL parser: To validate and process schema definitions
+ * - ObjectUI renderer: To generate forms, tables, and views
+ * - Database drivers: To create tables and migrations
+ * - API generators: To expose REST/GraphQL endpoints
+ *
+ * @example
+ * ```typescript
+ * const userEntity: ObjectEntity = {
+ *   name: 'User',
+ *   label: 'User',
+ *   pluralLabel: 'Users',
+ *   description: 'System user account',
+ *   fields: [
+ *     {
+ *       name: 'id',
+ *       label: 'ID',
+ *       type: 'text',
+ *       required: true,
+ *       readonly: true
+ *     },
+ *     {
+ *       name: 'email',
+ *       label: 'Email',
+ *       type: 'email',
+ *       required: true,
+ *       unique: true
+ *     },
+ *     {
+ *       name: 'name',
+ *       label: 'Full Name',
+ *       type: 'text',
+ *       required: true
+ *     }
+ *   ],
+ *   primaryKey: 'id',
+ *   displayField: 'name'
+ * };
+ * ```
+ */
+export interface ObjectEntity {
+    /**
+     * Technical name of the entity
+     *
+     * @remarks
+     * Used in code, APIs, and database table names.
+     * Should be in PascalCase for entities.
+     * Must be unique across the system.
+     *
+     * @example 'User', 'Account', 'SalesOrder'
+     */
+    name: string;
+    /**
+     * Human-readable singular label for the entity
+     *
+     * @remarks
+     * Used in UI headers, forms, and documentation.
+     *
+     * @example 'User', 'Sales Order', 'Product Category'
+     */
+    label: string;
+    /**
+     * Human-readable plural label for the entity
+     *
+     * @remarks
+     * Used in UI when displaying lists or collections.
+     *
+     * @example 'Users', 'Sales Orders', 'Product Categories'
+     */
+    pluralLabel: string;
+    /**
+     * Detailed description of the entity's purpose
+     *
+     * @remarks
+     * Used for documentation and context-sensitive help
+     */
+    description?: string;
+    /**
+     * Array of field definitions that make up this entity
+     *
+     * @remarks
+     * Each field represents a column/attribute in the entity.
+     * Field names must be unique within the entity.
+     *
+     * @see ObjectField
+     */
+    fields: ObjectField[];
+    /**
+     * Name of the field that serves as the primary key
+     *
+     * @remarks
+     * The primary key uniquely identifies each record.
+     * Must be one of the field names in the fields array.
+     *
+     * @defaultValue 'id'
+     *
+     * @example 'id', 'uuid', 'userId'
+     */
+    primaryKey?: string;
+    /**
+     * Name of the field to use as the display/title field
+     *
+     * @remarks
+     * Used when showing a record reference in lookups, breadcrumbs, etc.
+     * Should be a field that uniquely and meaningfully identifies a record.
+     *
+     * @defaultValue 'name'
+     *
+     * @example 'name', 'title', 'email', 'code'
+     */
+    displayField?: string;
+    /**
+     * Icon identifier for the entity
+     *
+     * @remarks
+     * Used in navigation menus, headers, and lists.
+     * Can be an icon library reference (e.g., 'user', 'building', 'package')
+     * or a URL to a custom icon.
+     *
+     * @example 'user', 'briefcase', 'https://example.com/icon.svg'
+     */
+    icon?: string;
+    /**
+     * Color theme for the entity
+     *
+     * @remarks
+     * Used for visual distinction in UI elements.
+     * Can be a CSS color name, hex code, or theme variable.
+     *
+     * @example 'blue', '#3B82F6', 'primary'
+     */
+    color?: string;
+    /**
+     * Whether this entity should be audited
+     *
+     * @remarks
+     * When enabled, tracks create/update/delete operations with user and timestamp.
+     * Typically adds fields like: createdBy, createdAt, updatedBy, updatedAt
+     *
+     * @defaultValue false
+     */
+    auditable?: boolean;
+    /**
+     * Whether this entity supports soft deletion
+     *
+     * @remarks
+     * When enabled, records are marked as deleted rather than physically removed.
+     * Typically adds a 'deletedAt' timestamp field.
+     *
+     * @defaultValue false
+     */
+    softDelete?: boolean;
+    /**
+     * Whether this entity can be searched via full-text search
+     *
+     * @remarks
+     * When enabled, the entity is indexed for full-text search operations
+     *
+     * @defaultValue false
+     */
+    searchable?: boolean;
+    /**
+     * Names of fields to include in full-text search
+     *
+     * @remarks
+     * Only relevant when searchable is true.
+     * If not specified, all text fields are included.
+     *
+     * @example ['name', 'description', 'email']
+     */
+    searchableFields?: string[];
+    /**
+     * Permission scope identifier
+     *
+     * @remarks
+     * Defines the permission namespace for this entity.
+     * Used to generate permission strings like: '{scope}.read', '{scope}.write'
+     *
+     * @example 'user', 'sales.order', 'product.category'
+     */
+    permissionScope?: string;
+    /**
+     * Custom validation rules
+     *
+     * @remarks
+     * Array of validation rule identifiers that apply to the entire entity.
+     * Can reference built-in validators or custom validation functions.
+     *
+     * @example ['uniqueTogether:email,domain', 'requiredIf:field1,field2']
+     */
+    validationRules?: string[];
+    /**
+     * Database table name override
+     *
+     * @remarks
+     * By default, table name is derived from entity name.
+     * Use this to specify a custom table name.
+     *
+     * @example 'tbl_users', 'legacy_accounts'
+     */
+    tableName?: string;
+    /**
+     * Entity version for schema migration tracking
+     *
+     * @remarks
+     * Incremented when breaking changes are made to the entity structure.
+     * Used for migration management and compatibility checking.
+     *
+     * @defaultValue 1
+     */
+    version?: number;
+    /**
+     * Tags for categorization and filtering
+     *
+     * @remarks
+     * Used to organize entities into logical groups.
+     *
+     * @example ['core', 'sales', 'internal']
+     */
+    tags?: string[];
+    /**
+     * Custom metadata for extensions and plugins
+     *
+     * @remarks
+     * Allows third-party code to attach arbitrary metadata to entities
+     * without modifying the core interface
+     */
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=object-entity.d.ts.map

package/dist/types/meta/object-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-entity.d.ts","sourceRoot":"","sources":["../../../src/types/meta/object-entity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;OAQG;IACH,MAAM,EAAE,WAAW,EAAE,CAAC;IAEtB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE5B;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/types/meta/object-entity.js

@@ -0,0 +1,9 @@
+/**
+ * Object Entity Interface
+ *
+ * Defines the structure of an entity in the ObjectStack metamodel.
+ * Entities represent data models/tables with their fields and relationships.
+ *
+ * @module types/meta/object-entity
+ */
+export {};

package/dist/types/meta/object-field.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Object Field Interface
+ *
+ * Defines the structure of a field within an ObjectEntity.
+ * Fields represent individual data attributes and their metadata.
+ *
+ * @module types/meta/object-field
+ */
+import { FieldType } from './field-type';
+/**
+ * Represents a field definition within an ObjectEntity
+ *
+ * @remarks
+ * ObjectField defines the complete metadata for a single field/attribute
+ * in an entity. This includes its type, validation rules, UI hints, and
+ * relationships to other entities (in the case of lookup fields).
+ *
+ * @example
+ * ```typescript
+ * const nameField: ObjectField = {
+ *   name: 'name',
+ *   label: 'Full Name',
+ *   type: 'text',
+ *   required: true,
+ *   maxLength: 100
+ * };
+ *
+ * const ownerField: ObjectField = {
+ *   name: 'owner',
+ *   label: 'Owner',
+ *   type: 'lookup',
+ *   required: true,
+ *   lookupEntity: 'User',
+ *   lookupDisplayField: 'name'
+ * };
+ * ```
+ */
+export interface ObjectField {
+    /**
+     * Technical name of the field (used in code and database)
+     *
+     * @remarks
+     * Should be in camelCase or snake_case format.
+     * Must be unique within the entity.
+     *
+     * @example 'firstName', 'email', 'created_at'
+     */
+    name: string;
+    /**
+     * Human-readable label for the field
+     *
+     * @remarks
+     * Used in UI forms, tables, and documentation.
+     *
+     * @example 'First Name', 'Email Address', 'Created At'
+     */
+    label: string;
+    /**
+     * Data type of the field
+     *
+     * @see FieldType
+     */
+    type: FieldType;
+    /**
+     * Detailed description of the field's purpose and usage
+     *
+     * @remarks
+     * Used for tooltips, help text, and documentation.
+     */
+    description?: string;
+    /**
+     * Whether the field is required (cannot be null/empty)
+     *
+     * @defaultValue false
+     */
+    required?: boolean;
+    /**
+     * Whether the field value must be unique across all records
+     *
+     * @defaultValue false
+     */
+    unique?: boolean;
+    /**
+     * Default value when creating new records
+     *
+     * @remarks
+     * Can be a static value or a function reference (e.g., 'NOW()' for timestamps)
+     */
+    defaultValue?: unknown;
+    /**
+     * Maximum length for text fields
+     *
+     * @remarks
+     * Only applicable to 'text', 'textarea', 'email', 'url' field types
+     */
+    maxLength?: number;
+    /**
+     * Minimum length for text fields
+     *
+     * @remarks
+     * Only applicable to 'text', 'textarea', 'email', 'url' field types
+     */
+    minLength?: number;
+    /**
+     * Minimum value for numeric fields
+     *
+     * @remarks
+     * Only applicable to 'number', 'currency', 'percentage' field types
+     */
+    min?: number;
+    /**
+     * Maximum value for numeric fields
+     *
+     * @remarks
+     * Only applicable to 'number', 'currency', 'percentage' field types
+     */
+    max?: number;
+    /**
+     * Regular expression pattern for validation
+     *
+     * @remarks
+     * Applied to text-based field types for custom validation rules
+     *
+     * @example '^[A-Z]{2}-\\d{4}$' for pattern like 'AB-1234'
+     */
+    pattern?: string;
+    /**
+     * Target entity name for lookup fields
+     *
+     * @remarks
+     * Required when type is 'lookup'. Specifies which entity this field references.
+     *
+     * @example 'User', 'Account', 'Product'
+     */
+    lookupEntity?: string;
+    /**
+     * Field name in the lookup entity to display
+     *
+     * @remarks
+     * Used to show human-readable text instead of IDs.
+     * Common values: 'name', 'title', 'label'
+     *
+     * @defaultValue 'name'
+     */
+    lookupDisplayField?: string;
+    /**
+     * Available options for select/multiselect fields
+     *
+     * @remarks
+     * Only applicable to 'select' and 'multiselect' field types
+     *
+     * @example
+     * ```typescript
+     * options: [
+     *   { value: 'draft', label: 'Draft' },
+     *   { value: 'published', label: 'Published' }
+     * ]
+     * ```
+     */
+    options?: Array<{
+        /** Internal value stored in database */
+        value: string | number;
+        /** Human-readable label shown in UI */
+        label: string;
+    }>;
+    /**
+     * Whether the field is indexed for faster queries
+     *
+     * @defaultValue false
+     */
+    indexed?: boolean;
+    /**
+     * Whether the field is read-only
+     *
+     * @remarks
+     * Read-only fields can only be set by the system, not by users
+     *
+     * @defaultValue false
+     */
+    readonly?: boolean;
+    /**
+     * Whether the field is hidden from UI by default
+     *
+     * @remarks
+     * Hidden fields are still stored and queryable but not shown in standard forms/views
+     *
+     * @defaultValue false
+     */
+    hidden?: boolean;
+    /**
+     * Custom metadata for extensions and plugins
+     *
+     * @remarks
+     * Allows third-party code to attach arbitrary metadata to fields
+     * without modifying the core interface
+     */
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=object-field.d.ts.map

package/dist/types/meta/object-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-field.d.ts","sourceRoot":"","sources":["../../../src/types/meta/object-field.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,IAAI,EAAE,SAAS,CAAC;IAEhB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,wCAAwC;QACxC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,uCAAuC;QACvC,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IAEH;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/types/meta/object-field.js

@@ -0,0 +1,9 @@
+/**
+ * Object Field Interface
+ *
+ * Defines the structure of a field within an ObjectEntity.
+ * Fields represent individual data attributes and their metadata.
+ *
+ * @module types/meta/object-field
+ */
+export {};