@objectstack/spec 0.1.0 → 0.1.2

package/src/examples.ts

@@ -1,257 +0,0 @@
-/**
- * Example Usage of ObjectStack Metamodel
- * 
- * This file demonstrates how to use the metamodel interfaces
- * to define entities and views.
- */
-
-import type { ObjectEntity, ObjectView } from './types/meta';
-
-/**
- * Example: User Entity Definition
- */
-export 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 Address',
-      type: 'email',
-      required: true,
-      unique: true,
-      maxLength: 255,
-    },
-    {
-      name: 'name',
-      label: 'Full Name',
-      type: 'text',
-      required: true,
-      maxLength: 100,
-    },
-    {
-      name: 'role',
-      label: 'Role',
-      type: 'select',
-      required: true,
-      options: [
-        { value: 'admin', label: 'Administrator' },
-        { value: 'editor', label: 'Editor' },
-        { value: 'viewer', label: 'Viewer' },
-      ],
-    },
-    {
-      name: 'status',
-      label: 'Status',
-      type: 'select',
-      required: true,
-      defaultValue: 'active',
-      options: [
-        { value: 'active', label: 'Active' },
-        { value: 'inactive', label: 'Inactive' },
-        { value: 'suspended', label: 'Suspended' },
-      ],
-    },
-    {
-      name: 'createdAt',
-      label: 'Created At',
-      type: 'datetime',
-      readonly: true,
-    },
-  ],
-  primaryKey: 'id',
-  displayField: 'name',
-  icon: 'user',
-  auditable: true,
-  searchable: true,
-  searchableFields: ['name', 'email'],
-};
-
-/**
- * Example: All Users List View
- */
-export const AllUsersView: ObjectView = {
-  name: 'all_users',
-  label: 'All Users',
-  entityName: 'User',
-  type: 'list',
-  description: 'View all users in the system',
-  columns: [
-    {
-      field: 'name',
-      label: 'Name',
-      width: '25%',
-      sortable: true,
-    },
-    {
-      field: 'email',
-      label: 'Email',
-      width: '30%',
-      sortable: true,
-    },
-    {
-      field: 'role',
-      label: 'Role',
-      width: '15%',
-      sortable: true,
-    },
-    {
-      field: 'status',
-      label: 'Status',
-      width: '15%',
-      sortable: true,
-    },
-    {
-      field: 'createdAt',
-      label: 'Created',
-      width: '15%',
-      sortable: true,
-      format: 'date:MM/DD/YYYY',
-    },
-  ],
-  sort: [
-    {
-      field: 'name',
-      direction: 'asc',
-    },
-  ],
-  pageSize: 25,
-  default: true,
-};
-
-/**
- * Example: Active Users View (with filter)
- */
-export const ActiveUsersView: ObjectView = {
-  name: 'active_users',
-  label: 'Active Users',
-  entityName: 'User',
-  type: 'list',
-  description: 'View only active users',
-  columns: [
-    {
-      field: 'name',
-      width: '30%',
-    },
-    {
-      field: 'email',
-      width: '40%',
-    },
-    {
-      field: 'role',
-      width: '30%',
-    },
-  ],
-  filters: [
-    {
-      field: 'status',
-      operator: 'equals',
-      value: 'active',
-    },
-  ],
-  sort: [
-    {
-      field: 'name',
-      direction: 'asc',
-    },
-  ],
-};
-
-/**
- * Example: User Form View
- */
-export const UserFormView: ObjectView = {
-  name: 'user_form',
-  label: 'User Form',
-  entityName: 'User',
-  type: 'form',
-  description: 'Form for creating and editing users',
-  fields: ['name', 'email', 'role', 'status'],
-  layout: {
-    type: 'sections',
-    sections: [
-      {
-        id: 'basic',
-        title: 'Basic Information',
-        fields: ['name', 'email'],
-      },
-      {
-        id: 'settings',
-        title: 'Settings',
-        fields: ['role', 'status'],
-      },
-    ],
-  },
-};
-
-/**
- * Example: Product Entity with Lookup
- */
-export const ProductEntity: ObjectEntity = {
-  name: 'Product',
-  label: 'Product',
-  pluralLabel: 'Products',
-  description: 'Product catalog',
-  fields: [
-    {
-      name: 'id',
-      label: 'ID',
-      type: 'text',
-      required: true,
-      readonly: true,
-    },
-    {
-      name: 'name',
-      label: 'Product Name',
-      type: 'text',
-      required: true,
-      maxLength: 200,
-    },
-    {
-      name: 'description',
-      label: 'Description',
-      type: 'textarea',
-      maxLength: 1000,
-    },
-    {
-      name: 'price',
-      label: 'Price',
-      type: 'currency',
-      required: true,
-      min: 0,
-    },
-    {
-      name: 'category',
-      label: 'Category',
-      type: 'lookup',
-      required: true,
-      lookupEntity: 'Category',
-      lookupDisplayField: 'name',
-    },
-    {
-      name: 'inStock',
-      label: 'In Stock',
-      type: 'boolean',
-      defaultValue: true,
-    },
-    {
-      name: 'image',
-      label: 'Product Image',
-      type: 'image',
-    },
-  ],
-  primaryKey: 'id',
-  displayField: 'name',
-  icon: 'package',
-  searchable: true,
-  searchableFields: ['name', 'description'],
-};

package/src/index.ts

@@ -1,10 +0,0 @@
-/**
- * ObjectStack Specification
- * 
- * This module provides the core type definitions and interfaces for the ObjectStack ecosystem.
- * It defines the contract between backend (ObjectQL) parsers and frontend (ObjectUI) renderers.
- * 
- * @packageDocumentation
- */
-
-export * from './types';

package/src/types/index.ts

@@ -1,9 +0,0 @@
-/**
- * Type Definitions
- * 
- * This module exports all type definitions used in the ObjectStack specification.
- * 
- * @module types
- */
-
-export * from './meta';

package/src/types/meta/field-type.ts

@@ -1,91 +0,0 @@
-/**
- * Field Type Definitions
- * 
- * Defines the available field types in the ObjectStack metamodel.
- * These types determine how fields are stored, validated, and rendered.
- * 
- * @module types/meta/field-type
- */
-
-/**
- * Available field types in the ObjectStack metamodel.
- * 
- * @remarks
- * Each field type corresponds to specific storage, validation, and rendering behavior:
- * 
- * - `text`: Short text strings (single line)
- * - `textarea`: Long text content (multi-line)
- * - `number`: Numeric values (integer or decimal)
- * - `boolean`: True/false values (checkbox)
- * - `date`: Date values (without time)
- * - `datetime`: Date and time values
- * - `email`: Email address with validation
- * - `url`: URL with validation
- * - `lookup`: Reference to another entity (foreign key)
- * - `select`: Single selection from predefined options
- * - `multiselect`: Multiple selections from predefined options
- * - `json`: Arbitrary JSON data structure
- * - `file`: File attachment reference
- * - `image`: Image file reference with preview
- * - `currency`: Monetary values with precision
- * - `percentage`: Percentage values (0-100)
- * 
- * @example
- * ```typescript
- * const nameField: FieldType = 'text';
- * const priceField: FieldType = 'currency';
- * const ownerField: FieldType = 'lookup';
- * ```
- */
-export type FieldType =
-  | 'text'
-  | 'textarea'
-  | 'number'
-  | 'boolean'
-  | 'date'
-  | 'datetime'
-  | 'email'
-  | 'url'
-  | 'lookup'
-  | 'select'
-  | 'multiselect'
-  | 'json'
-  | 'file'
-  | 'image'
-  | 'currency'
-  | 'percentage';
-
-/**
- * Type guard to check if a string is a valid FieldType
- * 
- * @param value - The value to check
- * @returns True if the value is a valid FieldType
- * 
- * @example
- * ```typescript
- * if (isFieldType('text')) {
- *   // value is a valid FieldType
- * }
- * ```
- */
-export function isFieldType(value: unknown): value is FieldType {
-  const validTypes: FieldType[] = [
-    'text',
-    'textarea',
-    'number',
-    'boolean',
-    'date',
-    'datetime',
-    'email',
-    'url',
-    'lookup',
-    'select',
-    'multiselect',
-    'json',
-    'file',
-    'image',
-    'currency',
-    'percentage',
-  ];
-  return typeof value === 'string' && validTypes.includes(value as FieldType);
-}

package/src/types/meta/index.ts

@@ -1,13 +0,0 @@
-/**
- * Metamodel Type Definitions
- * 
- * This module defines the core metamodel interfaces that form the contract
- * between the backend (ObjectQL) parser and the frontend (ObjectUI) renderer.
- * 
- * @module types/meta
- */
-
-export * from './field-type';
-export * from './object-field';
-export * from './object-entity';
-export * from './object-view';

package/src/types/meta/object-entity.ts

@@ -1,265 +0,0 @@
-/**
- * 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>;
-}