@objectstack/spec 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# ObjectStack Specification
+
+The ObjectStack Protocol & Specification repository defines the core type definitions and interfaces for the ObjectStack ecosystem. This repository serves as the "Constitution" of the system, providing the contract between backend (ObjectQL) parsers and frontend (ObjectUI) renderers.
+
+## Purpose
+
+This repository contains:
+- **TypeScript Interfaces**: Shared types for the entire ObjectStack ecosystem
+- **No Logic**: Only type definitions, no runtime code or business logic
+- **Universal Compatibility**: Works in Node.js, Browser, and Electron environments
+
+## Metamodel Interfaces
+
+The metamodel defines the structure for describing data models in ObjectStack:
+
+### Core Interfaces
+
+#### `FieldType`
+Defines the available field data types:
+- Text types: `text`, `textarea`, `email`, `url`
+- Numeric types: `number`, `currency`, `percentage`
+- Date/Time types: `date`, `datetime`
+- Relation types: `lookup`
+- Selection types: `select`, `multiselect`
+- Special types: `boolean`, `json`, `file`, `image`
+
+#### `ObjectField`
+Represents a field definition within an entity:
+```typescript
+interface ObjectField {
+  name: string;           // Field identifier
+  label: string;          // Display label
+  type: FieldType;        // Data type
+  required?: boolean;     // Validation
+  unique?: boolean;       // Constraint
+  lookupEntity?: string;  // For lookup fields
+  // ... and more options
+}
+```
+
+#### `ObjectEntity`
+Represents a complete entity (data model) definition:
+```typescript
+interface ObjectEntity {
+  name: string;           // Entity identifier
+  label: string;          // Singular display label
+  pluralLabel: string;    // Plural display label
+  fields: ObjectField[];  // Field definitions
+  primaryKey?: string;    // Primary key field
+  displayField?: string;  // Display field for lookups
+  // ... and more options
+}
+```
+
+#### `ObjectView`
+Represents a view configuration for presenting entity data:
+```typescript
+interface ObjectView {
+  name: string;           // View identifier
+  label: string;          // Display label
+  entityName: string;     // Target entity
+  type: ViewType;         // Presentation type (list, form, detail, etc.)
+  fields?: string[];      // Fields to display
+  columns?: ViewColumn[]; // Column configuration
+  filters?: ViewFilter[]; // Default filters
+  sort?: ViewSort[];      // Default sort order
+  // ... and more options
+}
+```
+
+## Usage
+
+### Installation
+
+```bash
+npm install @objectstack/spec
+```
+
+### Importing Types
+
+```typescript
+// Import all metamodel types
+import { ObjectEntity, ObjectField, ObjectView, FieldType } from '@objectstack/spec';
+
+// Or import specific types
+import type { ObjectEntity } from '@objectstack/spec';
+```
+
+### Example: Defining an Entity
+
+```typescript
+import { ObjectEntity, ObjectField } from '@objectstack/spec';
+
+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
+    },
+    {
+      name: 'role',
+      label: 'Role',
+      type: 'select',
+      required: true,
+      options: [
+        { value: 'admin', label: 'Administrator' },
+        { value: 'user', label: 'User' }
+      ]
+    }
+  ],
+  primaryKey: 'id',
+  displayField: 'name'
+};
+```
+
+## Building
+
+```bash
+npm install
+npm run build
+```
+
+This will compile TypeScript files to JavaScript and generate type declarations in the `dist/` directory.
+
+## Philosophy
+
+Following the ObjectStack Protocol:
+- **Strict Types, No Logic**: This repository contains only type definitions
+- **Documentation as Code**: Every interface property has TSDoc comments for IntelliSense
+- **Universal Compatibility**: Pure TypeScript with no platform-specific dependencies
+
+## License
+
+MIT

package/dist/examples.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare const UserEntity: ObjectEntity;
+/**
+ * Example: All Users List View
+ */
+export declare const AllUsersView: ObjectView;
+/**
+ * Example: Active Users View (with filter)
+ */
+export declare const ActiveUsersView: ObjectView;
+/**
+ * Example: User Form View
+ */
+export declare const UserFormView: ObjectView;
+/**
+ * Example: Product Entity with Lookup
+ */
+export declare const ProductEntity: ObjectEntity;
+//# sourceMappingURL=examples.d.ts.map

package/dist/examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../src/examples.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,YAgExB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,UA+C1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,UAiC7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,UAsB1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,YA0D3B,CAAC"}

package/dist/examples.js

@@ -0,0 +1,250 @@
+/**
+ * Example Usage of ObjectStack Metamodel
+ *
+ * This file demonstrates how to use the metamodel interfaces
+ * to define entities and views.
+ */
+/**
+ * Example: User Entity Definition
+ */
+export const UserEntity = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * 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/dist/types/index.d.ts

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

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,QAAQ,CAAC"}

package/dist/types/index.js

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

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

@@ -0,0 +1,54 @@
+/**
+ * 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 declare function isFieldType(value: unknown): value is FieldType;
+//# sourceMappingURL=field-type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"field-type.d.ts","sourceRoot":"","sources":["../../../src/types/meta/field-type.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,UAAU,GACV,QAAQ,GACR,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,KAAK,GACL,QAAQ,GACR,QAAQ,GACR,aAAa,GACb,MAAM,GACN,MAAM,GACN,OAAO,GACP,UAAU,GACV,YAAY,CAAC;AAEjB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAoB9D"}

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

@@ -0,0 +1,42 @@
+/**
+ * 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
+ */
+/**
+ * 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) {
+    const validTypes = [
+        'text',
+        'textarea',
+        'number',
+        'boolean',
+        'date',
+        'datetime',
+        'email',
+        'url',
+        'lookup',
+        'select',
+        'multiselect',
+        'json',
+        'file',
+        'image',
+        'currency',
+        'percentage',
+    ];
+    return typeof value === 'string' && validTypes.includes(value);
+}

package/dist/types/meta/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/meta/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/meta/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}

package/dist/types/meta/index.js

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