@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/entity/store.js

@@ -0,0 +1,349 @@
+/**
+ * Entity Store
+ *
+ * Uniform CRUD and query interface backed by connectors.
+ * The store handles validation and delegates persistence to connectors.
+ *
+ * @module @pwfabric/runtime/entity/store
+ */
+import { aggregateThrough } from './aggregate.js';
+// ============================================================
+// DEFAULT ENTITY STORE
+// ============================================================
+/**
+ * Default implementation of EntityStore.
+ * Validates through the registry and delegates persistence to connectors.
+ *
+ * Accepts an optional SurfaceEventBus. When provided, successful
+ * CRUD operations emit entity:created / entity:updated / entity:deleted events on
+ * the bus so that the rest of the surface can react declaratively.
+ *
+ * The bus is surface-scoped — the caller injects the bus for a
+ * specific surface, keeping the store surface-aware without making it globally coupled.
+ */
+/**
+ * The id of a record a connector just created. A record service may answer
+ * with the record itself (`{ id, … }`) or wrap it (`{ data: { id, … } }`, the
+ * shape the data protocol specifies); both are read.
+ */
+function createdIdOf(body) {
+    const own = body?.['id'];
+    if (typeof own === 'string' || typeof own === 'number')
+        return String(own);
+    const inner = body?.['data'];
+    if (inner && typeof inner === 'object' && !Array.isArray(inner)) {
+        const id = inner['id'];
+        if (typeof id === 'string' || typeof id === 'number')
+            return String(id);
+    }
+    return '';
+}
+export class DefaultEntityStore {
+    registry;
+    connectors;
+    eventBus;
+    constructor(registry, connectors, eventBus) {
+        this.registry = registry;
+        this.connectors = connectors;
+        this.eventBus = eventBus ?? undefined;
+    }
+    async create(entityType, data) {
+        // Validate entity type exists
+        if (!this.registry.has(entityType)) {
+            return {
+                success: false,
+                error: {
+                    type: 'not_found',
+                    message: `Entity type '${entityType}' is not registered`,
+                },
+            };
+        }
+        // Validate data against schema
+        const validation = this.registry.validate(entityType, data);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: {
+                    type: 'validation',
+                    message: 'Validation failed',
+                    details: validation.errors,
+                },
+            };
+        }
+        // Resolve connector
+        const connector = this.connectors.resolve(entityType);
+        if (!connector) {
+            return {
+                success: false,
+                error: {
+                    type: 'connector',
+                    message: `No connector found for entity type '${entityType}'`,
+                },
+            };
+        }
+        // Delegate to connector
+        const result = await connector.create(entityType, validation.data);
+        if (!result.success) {
+            return {
+                success: false,
+                error: {
+                    type: 'connector',
+                    message: result.error,
+                },
+            };
+        }
+        const mutationResult = {
+            success: true,
+            data: result.data,
+            id: createdIdOf(result.data),
+        };
+        // emit entity:created on the surface-scoped bus
+        if (this.eventBus) {
+            this.eventBus.emit({
+                type: 'entity:created',
+                surfaceId: 'system',
+                payload: {
+                    entityType,
+                    instanceId: mutationResult.id,
+                    data: mutationResult.data,
+                    timestamp: Date.now(),
+                },
+                timestamp: Date.now(),
+            });
+        }
+        return mutationResult;
+    }
+    async read(entityType, instanceId) {
+        // Validate entity type exists
+        if (!this.registry.has(entityType)) {
+            return {
+                success: false,
+                error: {
+                    type: 'not_found',
+                    message: `Entity type '${entityType}' is not registered`,
+                },
+            };
+        }
+        // Resolve connector
+        const connector = this.connectors.resolve(entityType);
+        if (!connector) {
+            return {
+                success: false,
+                error: {
+                    type: 'connector',
+                    message: `No connector found for entity type '${entityType}'`,
+                },
+            };
+        }
+        // Delegate to connector
+        const result = await connector.read(entityType, instanceId);
+        if (!result.success) {
+            return {
+                success: false,
+                error: {
+                    type: 'not_found',
+                    message: result.error,
+                },
+            };
+        }
+        return {
+            success: true,
+            data: result.data,
+        };
+    }
+    async update(entityType, instanceId, data) {
+        // Validate entity type exists
+        if (!this.registry.has(entityType)) {
+            return {
+                success: false,
+                error: {
+                    type: 'not_found',
+                    message: `Entity type '${entityType}' is not registered`,
+                },
+            };
+        }
+        // Read existing record to merge with updates for validation
+        const connector = this.connectors.resolve(entityType);
+        if (!connector) {
+            return {
+                success: false,
+                error: {
+                    type: 'connector',
+                    message: `No connector found for entity type '${entityType}'`,
+                },
+            };
+        }
+        const existing = await connector.read(entityType, instanceId);
+        if (!existing.success) {
+            return {
+                success: false,
+                error: {
+                    type: 'not_found',
+                    message: existing.error,
+                },
+            };
+        }
+        // Merge existing data with updates for full validation
+        const merged = { ...existing.data, ...data };
+        const validation = this.registry.validate(entityType, merged);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: {
+                    type: 'validation',
+                    message: 'Validation failed',
+                    details: validation.errors,
+                },
+            };
+        }
+        // Delegate to connector
+        const result = await connector.update(entityType, instanceId, data);
+        if (!result.success) {
+            return {
+                success: false,
+                error: {
+                    type: 'connector',
+                    message: result.error,
+                },
+            };
+        }
+        const updateResult = {
+            success: true,
+            data: result.data,
+            id: instanceId,
+        };
+        // emit entity:updated on the surface-scoped bus
+        if (this.eventBus) {
+            this.eventBus.emit({
+                type: 'entity:updated',
+                surfaceId: 'system',
+                payload: {
+                    entityType,
+                    instanceId,
+                    data: updateResult.data,
+                    changeset: data,
+                    timestamp: Date.now(),
+                },
+                timestamp: Date.now(),
+            });
+        }
+        return updateResult;
+    }
+    async delete(entityType, instanceId) {
+        // Validate entity type exists
+        if (!this.registry.has(entityType)) {
+            return {
+                success: false,
+                error: {
+                    type: 'not_found',
+                    message: `Entity type '${entityType}' is not registered`,
+                },
+            };
+        }
+        // Resolve connector
+        const connector = this.connectors.resolve(entityType);
+        if (!connector) {
+            return {
+                success: false,
+                error: {
+                    type: 'connector',
+                    message: `No connector found for entity type '${entityType}'`,
+                },
+            };
+        }
+        // Delegate to connector
+        const result = await connector.delete(entityType, instanceId);
+        if (!result.success) {
+            return {
+                success: false,
+                error: {
+                    type: 'not_found',
+                    message: result.error,
+                },
+            };
+        }
+        const deleteResult = {
+            success: true,
+            data: result.data,
+            id: instanceId,
+        };
+        // emit entity:deleted on the surface-scoped bus
+        if (this.eventBus) {
+            this.eventBus.emit({
+                type: 'entity:deleted',
+                surfaceId: 'system',
+                payload: {
+                    entityType,
+                    instanceId,
+                    timestamp: Date.now(),
+                },
+                timestamp: Date.now(),
+            });
+        }
+        return deleteResult;
+    }
+    async query(entityType, query) {
+        // Validate entity type exists
+        if (!this.registry.has(entityType)) {
+            return {
+                items: [],
+                total: 0,
+                offset: 0,
+                limit: query.pagination?.limit ?? 50,
+                hasMore: false,
+            };
+        }
+        // Resolve connector
+        const connector = this.connectors.resolve(entityType);
+        if (!connector) {
+            return {
+                items: [],
+                total: 0,
+                offset: 0,
+                limit: query.pagination?.limit ?? 50,
+                hasMore: false,
+            };
+        }
+        // Delegate to connector
+        const result = await connector.query(entityType, query);
+        if (!result.success) {
+            return {
+                items: [],
+                total: 0,
+                offset: 0,
+                limit: query.pagination?.limit ?? 50,
+                hasMore: false,
+            };
+        }
+        return result.result;
+    }
+    async aggregate(entityType, aggregate) {
+        // NOT the same as query. An empty list is an honest answer to "could not
+        // list"; `{ value: 0 }` is not an honest answer to "could not count" —
+        // a 403 would read as "0 people are coming". Reject, and the renderer
+        // binds `fallback` and `__errors.<id>` like any failed source.
+        if (!this.registry.has(entityType)) {
+            throw new Error(`Entity type '${String(entityType)}' is not registered`);
+        }
+        const connector = this.connectors.resolve(entityType);
+        if (!connector)
+            throw new Error(`No connector for entity type '${String(entityType)}'`);
+        const result = await aggregateThrough(connector, entityType, aggregate);
+        if (!result.success)
+            throw new Error(result.error);
+        return result.result;
+    }
+}
+// ============================================================
+// FACTORY FUNCTION
+// ============================================================
+/**
+ * Create an entity store.
+ *
+ * Pass an optional `eventBus` to enable surface-scoped event
+ * emission on successful CRUD operations (entity:created, entity:updated, entity:deleted).
+ */
+export function createEntityStore(registry, connectors, eventBus) {
+    return new DefaultEntityStore(registry, connectors, eventBus);
+}
+//# sourceMappingURL=store.js.map

package/dist/entity/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/entity/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Entity Store\n *\n * Uniform CRUD and query interface backed by connectors.\n * The store handles validation and delegates persistence to connectors.\n *\n * @module @pwfabric/runtime/entity/store\n */\n\nimport type {\n  EntityTypeId,\n  EntityInstanceId,\n  EntityQuery,\n  EntityQueryResult,\n  EntityMutationResult,\n  EntityReadResult,\n  EntityAggregate,\n  EntityAggregateResult,\n} from './types.js'\nimport { aggregateThrough } from './aggregate.js'\nimport type { EntityRegistry } from './registry.js'\nimport type { ConnectorRegistry } from './connector.js'\nimport type { SurfaceEventBus } from '@pwfabric/contracts'\n\n// ============================================================\n// ENTITY STORE INTERFACE\n// ============================================================\n\n/**\n * Entity store interface for CRUD operations\n */\nexport interface EntityStore {\n  /**\n   * Create a new entity instance\n   */\n  create(entityType: EntityTypeId, data: Record<string, unknown>): Promise<EntityMutationResult>\n\n  /**\n   * Read a single entity instance\n   */\n  read(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<EntityReadResult>\n\n  /**\n   * Update an existing entity instance\n   */\n  update(\n    entityType: EntityTypeId,\n    instanceId: EntityInstanceId,\n    data: Record<string, unknown>\n  ): Promise<EntityMutationResult>\n\n  /**\n   * Delete an entity instance\n   */\n  delete(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<EntityMutationResult>\n\n  /**\n   * Query entity instances\n   */\n  query(entityType: EntityTypeId, query: EntityQuery): Promise<EntityQueryResult>\n\n  /**\n   * One number over the collection. Server-side when the connector\n   * can; otherwise the connector's rows are reduced in memory. REJECTS when\n   * the number cannot be served — unlike `query`, whose honest failure is an\n   * empty list, a counter's `0` would be a lie.\n   *\n   * OPTIONAL so a host-written `EntityStore` keeps compiling; the facade\n   * lists and reduces through `query` when a store has none.\n   */\n  aggregate?(entityType: EntityTypeId, aggregate: EntityAggregate): Promise<EntityAggregateResult>\n}\n\n// ============================================================\n// DEFAULT ENTITY STORE\n// ============================================================\n\n/**\n * Default implementation of EntityStore.\n * Validates through the registry and delegates persistence to connectors.\n *\n * Accepts an optional SurfaceEventBus. When provided, successful\n * CRUD operations emit entity:created / entity:updated / entity:deleted events on\n * the bus so that the rest of the surface can react declaratively.\n *\n * The bus is surface-scoped — the caller injects the bus for a\n * specific surface, keeping the store surface-aware without making it globally coupled.\n */\n/**\n * The id of a record a connector just created. A record service may answer\n * with the record itself (`{ id, … }`) or wrap it (`{ data: { id, … } }`, the\n * shape the data protocol specifies); both are read.\n */\nfunction createdIdOf(body: Record<string, unknown> | undefined): EntityInstanceId {\n  const own = body?.['id']\n  if (typeof own === 'string' || typeof own === 'number') return String(own) as EntityInstanceId\n  const inner = body?.['data']\n  if (inner && typeof inner === 'object' && !Array.isArray(inner)) {\n    const id = (inner as Record<string, unknown>)['id']\n    if (typeof id === 'string' || typeof id === 'number') return String(id) as EntityInstanceId\n  }\n  return '' as EntityInstanceId\n}\n\nexport class DefaultEntityStore implements EntityStore {\n  private readonly registry: EntityRegistry\n  private readonly connectors: ConnectorRegistry\n  private readonly eventBus: SurfaceEventBus | undefined\n\n  constructor(registry: EntityRegistry, connectors: ConnectorRegistry, eventBus?: SurfaceEventBus) {\n    this.registry = registry\n    this.connectors = connectors\n    this.eventBus = eventBus ?? undefined\n  }\n\n  async create(\n    entityType: EntityTypeId,\n    data: Record<string, unknown>\n  ): Promise<EntityMutationResult> {\n    // Validate entity type exists\n    if (!this.registry.has(entityType)) {\n      return {\n        success: false,\n        error: {\n          type: 'not_found',\n          message: `Entity type '${entityType}' is not registered`,\n        },\n      }\n    }\n\n    // Validate data against schema\n    const validation = this.registry.validate(entityType, data)\n    if (!validation.valid) {\n      return {\n        success: false,\n        error: {\n          type: 'validation',\n          message: 'Validation failed',\n          details: validation.errors,\n        },\n      }\n    }\n\n    // Resolve connector\n    const connector = this.connectors.resolve(entityType)\n    if (!connector) {\n      return {\n        success: false,\n        error: {\n          type: 'connector',\n          message: `No connector found for entity type '${entityType}'`,\n        },\n      }\n    }\n\n    // Delegate to connector\n    const result = await connector.create(entityType, validation.data)\n    if (!result.success) {\n      return {\n        success: false,\n        error: {\n          type: 'connector',\n          message: result.error,\n        },\n      }\n    }\n\n    const mutationResult: EntityMutationResult = {\n      success: true,\n      data: result.data,\n      id: createdIdOf(result.data),\n    }\n\n    // emit entity:created on the surface-scoped bus\n    if (this.eventBus) {\n      this.eventBus.emit({\n        type: 'entity:created',\n        surfaceId: 'system',\n        payload: {\n          entityType,\n          instanceId: mutationResult.id,\n          data: mutationResult.data,\n          timestamp: Date.now(),\n        },\n        timestamp: Date.now(),\n      })\n    }\n\n    return mutationResult\n  }\n\n  async read(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<EntityReadResult> {\n    // Validate entity type exists\n    if (!this.registry.has(entityType)) {\n      return {\n        success: false,\n        error: {\n          type: 'not_found',\n          message: `Entity type '${entityType}' is not registered`,\n        },\n      }\n    }\n\n    // Resolve connector\n    const connector = this.connectors.resolve(entityType)\n    if (!connector) {\n      return {\n        success: false,\n        error: {\n          type: 'connector',\n          message: `No connector found for entity type '${entityType}'`,\n        },\n      }\n    }\n\n    // Delegate to connector\n    const result = await connector.read(entityType, instanceId)\n    if (!result.success) {\n      return {\n        success: false,\n        error: {\n          type: 'not_found',\n          message: result.error,\n        },\n      }\n    }\n\n    return {\n      success: true,\n      data: result.data,\n    }\n  }\n\n  async update(\n    entityType: EntityTypeId,\n    instanceId: EntityInstanceId,\n    data: Record<string, unknown>\n  ): Promise<EntityMutationResult> {\n    // Validate entity type exists\n    if (!this.registry.has(entityType)) {\n      return {\n        success: false,\n        error: {\n          type: 'not_found',\n          message: `Entity type '${entityType}' is not registered`,\n        },\n      }\n    }\n\n    // Read existing record to merge with updates for validation\n    const connector = this.connectors.resolve(entityType)\n    if (!connector) {\n      return {\n        success: false,\n        error: {\n          type: 'connector',\n          message: `No connector found for entity type '${entityType}'`,\n        },\n      }\n    }\n\n    const existing = await connector.read(entityType, instanceId)\n    if (!existing.success) {\n      return {\n        success: false,\n        error: {\n          type: 'not_found',\n          message: existing.error,\n        },\n      }\n    }\n\n    // Merge existing data with updates for full validation\n    const merged = { ...existing.data, ...data }\n    const validation = this.registry.validate(entityType, merged)\n    if (!validation.valid) {\n      return {\n        success: false,\n        error: {\n          type: 'validation',\n          message: 'Validation failed',\n          details: validation.errors,\n        },\n      }\n    }\n\n    // Delegate to connector\n    const result = await connector.update(entityType, instanceId, data)\n    if (!result.success) {\n      return {\n        success: false,\n        error: {\n          type: 'connector',\n          message: result.error,\n        },\n      }\n    }\n\n    const updateResult: EntityMutationResult = {\n      success: true,\n      data: result.data,\n      id: instanceId,\n    }\n\n    // emit entity:updated on the surface-scoped bus\n    if (this.eventBus) {\n      this.eventBus.emit({\n        type: 'entity:updated',\n        surfaceId: 'system',\n        payload: {\n          entityType,\n          instanceId,\n          data: updateResult.data,\n          changeset: data,\n          timestamp: Date.now(),\n        },\n        timestamp: Date.now(),\n      })\n    }\n\n    return updateResult\n  }\n\n  async delete(\n    entityType: EntityTypeId,\n    instanceId: EntityInstanceId\n  ): Promise<EntityMutationResult> {\n    // Validate entity type exists\n    if (!this.registry.has(entityType)) {\n      return {\n        success: false,\n        error: {\n          type: 'not_found',\n          message: `Entity type '${entityType}' is not registered`,\n        },\n      }\n    }\n\n    // Resolve connector\n    const connector = this.connectors.resolve(entityType)\n    if (!connector) {\n      return {\n        success: false,\n        error: {\n          type: 'connector',\n          message: `No connector found for entity type '${entityType}'`,\n        },\n      }\n    }\n\n    // Delegate to connector\n    const result = await connector.delete(entityType, instanceId)\n    if (!result.success) {\n      return {\n        success: false,\n        error: {\n          type: 'not_found',\n          message: result.error,\n        },\n      }\n    }\n\n    const deleteResult: EntityMutationResult = {\n      success: true,\n      data: result.data,\n      id: instanceId,\n    }\n\n    // emit entity:deleted on the surface-scoped bus\n    if (this.eventBus) {\n      this.eventBus.emit({\n        type: 'entity:deleted',\n        surfaceId: 'system',\n        payload: {\n          entityType,\n          instanceId,\n          timestamp: Date.now(),\n        },\n        timestamp: Date.now(),\n      })\n    }\n\n    return deleteResult\n  }\n\n  async query(entityType: EntityTypeId, query: EntityQuery): Promise<EntityQueryResult> {\n    // Validate entity type exists\n    if (!this.registry.has(entityType)) {\n      return {\n        items: [],\n        total: 0,\n        offset: 0,\n        limit: query.pagination?.limit ?? 50,\n        hasMore: false,\n      }\n    }\n\n    // Resolve connector\n    const connector = this.connectors.resolve(entityType)\n    if (!connector) {\n      return {\n        items: [],\n        total: 0,\n        offset: 0,\n        limit: query.pagination?.limit ?? 50,\n        hasMore: false,\n      }\n    }\n\n    // Delegate to connector\n    const result = await connector.query(entityType, query)\n    if (!result.success) {\n      return {\n        items: [],\n        total: 0,\n        offset: 0,\n        limit: query.pagination?.limit ?? 50,\n        hasMore: false,\n      }\n    }\n\n    return result.result\n  }\n\n  async aggregate(entityType: EntityTypeId, aggregate: EntityAggregate): Promise<EntityAggregateResult> {\n    // NOT the same as query. An empty list is an honest answer to \"could not\n    // list\"; `{ value: 0 }` is not an honest answer to \"could not count\" —\n    // a 403 would read as \"0 people are coming\". Reject, and the renderer\n    // binds `fallback` and `__errors.<id>` like any failed source.\n    if (!this.registry.has(entityType)) {\n      throw new Error(`Entity type '${String(entityType)}' is not registered`)\n    }\n    const connector = this.connectors.resolve(entityType)\n    if (!connector) throw new Error(`No connector for entity type '${String(entityType)}'`)\n    const result = await aggregateThrough(connector, entityType, aggregate)\n    if (!result.success) throw new Error(result.error)\n    return result.result\n  }\n}\n\n// ============================================================\n// FACTORY FUNCTION\n// ============================================================\n\n/**\n * Create an entity store.\n *\n * Pass an optional `eventBus` to enable surface-scoped event\n * emission on successful CRUD operations (entity:created, entity:updated, entity:deleted).\n */\nexport function createEntityStore(\n  registry: EntityRegistry,\n  connectors: ConnectorRegistry,\n  eventBus?: SurfaceEventBus\n): EntityStore {\n  return new DefaultEntityStore(registry, connectors, eventBus)\n}\n"]}

package/dist/entity/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Entity System Types
+ *
+ * Entity system type definitions for schema-based entity types,
+ * CRUD operations, queries, and validation.
+ *
+ * @module @pwfabric/runtime/entity/types
+ */
+import type { z } from 'zod';
+/**
+ * Branded string type for entity type identifiers
+ */
+export type EntityTypeId = string & {
+    readonly __brand: 'EntityTypeId';
+};
+/**
+ * Branded string type for entity instance identifiers
+ */
+export type EntityInstanceId = string & {
+    readonly __brand: 'EntityInstanceId';
+};
+/**
+ * Supported field types for entity definitions
+ */
+export type EntityFieldType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'enum' | 'json' | 'reference';
+/**
+ * Definition of a single field within an entity
+ */
+export interface EntityFieldDefinition {
+    readonly name: string;
+    readonly type: EntityFieldType;
+    readonly required: boolean;
+    readonly unique?: boolean;
+    readonly defaultValue?: unknown;
+    readonly enumValues?: readonly string[];
+    readonly referenceTarget?: EntityTypeId;
+    readonly validation?: z.ZodType;
+    readonly label?: string;
+    readonly description?: string;
+}
+/**
+ * Supported relation types between entities
+ */
+export type EntityRelationType = 'has-one' | 'has-many' | 'belongs-to' | 'many-to-many';
+/**
+ * Definition of a relation between entity types
+ */
+export interface EntityRelationDefinition {
+    readonly name: string;
+    readonly type: EntityRelationType;
+    readonly target: EntityTypeId;
+    readonly foreignKey?: string;
+    readonly through?: EntityTypeId;
+    readonly cascade?: 'none' | 'delete' | 'nullify';
+}
+/**
+ * Complete definition of an entity type including fields, relations, and schema
+ */
+export interface EntityDefinition {
+    readonly id: EntityTypeId;
+    readonly name: string;
+    readonly description?: string;
+    readonly fields: readonly EntityFieldDefinition[];
+    readonly relations: readonly EntityRelationDefinition[];
+    readonly primaryKey: string;
+    readonly timestamps?: boolean;
+    readonly softDelete?: boolean;
+    readonly schema: z.ZodObject<z.ZodRawShape>;
+}
+/**
+ * Entity query specification with optional filter, sort, and pagination
+ */
+export interface EntityQuery {
+    readonly filter?: EntityFilter;
+    readonly sort?: readonly EntitySortField[];
+    readonly pagination?: EntityPagination;
+    readonly include?: readonly string[];
+}
+/**
+ * Filter condition for entity queries
+ */
+export interface EntityFilter {
+    readonly field: string;
+    readonly operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'contains' | 'startsWith';
+    readonly value: unknown;
+    readonly and?: readonly EntityFilter[];
+    readonly or?: readonly EntityFilter[];
+}
+/**
+ * Sort field specification
+ */
+export interface EntitySortField {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+/**
+ * Pagination parameters
+ */
+export interface EntityPagination {
+    readonly offset: number;
+    readonly limit: number;
+}
+/** One number over a collection: `count` needs no field, the rest reduce `field`. */
+export type EntityAggregateFn = 'count' | 'sum' | 'avg';
+/**
+ * An aggregate request — the source-level `aggregate` key. `filter`
+ * narrows the rows first, in the `EntityQuery.filter` shape.
+ */
+export interface EntityAggregate {
+    readonly fn: EntityAggregateFn;
+    readonly field?: string;
+    readonly filter?: EntityFilter;
+}
+/**
+ * What an aggregate answers: `value` is the number (`null` when a numeric
+ * fn found nothing to reduce), `count` the rows the filter kept.
+ */
+export interface EntityAggregateResult {
+    readonly fn: EntityAggregateFn;
+    readonly field?: string;
+    readonly value: number | null;
+    readonly count: number;
+}
+/**
+ * Result of a paginated entity query
+ */
+export interface EntityQueryResult<T = Record<string, unknown>> {
+    readonly items: readonly T[];
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+    readonly hasMore: boolean;
+}
+/**
+ * Result of a create or update mutation
+ */
+export type EntityMutationResult = {
+    readonly success: true;
+    readonly data: Record<string, unknown>;
+    readonly id: EntityInstanceId;
+} | {
+    readonly success: false;
+    readonly error: EntityOperationError;
+};
+/**
+ * Result of a read operation
+ */
+export type EntityReadResult = {
+    readonly success: true;
+    readonly data: Record<string, unknown>;
+} | {
+    readonly success: false;
+    readonly error: EntityOperationError;
+};
+/**
+ * Error descriptor for entity operations
+ */
+export interface EntityOperationError {
+    readonly type: 'not_found' | 'validation' | 'conflict' | 'connector' | 'unauthorized' | 'unknown';
+    readonly message: string;
+    readonly details?: unknown;
+}
+/**
+ * Result of entity validation (discriminated union)
+ */
+export type EntityValidationResult = {
+    readonly valid: true;
+    readonly data: Record<string, unknown>;
+} | {
+    readonly valid: false;
+    readonly errors: readonly EntityValidationError[];
+};
+/**
+ * Single field validation error
+ */
+export interface EntityValidationError {
+    readonly field: string;
+    readonly message: string;
+    readonly code: string;
+}

package/dist/entity/types.js

@@ -0,0 +1,10 @@
+/**
+ * Entity System Types
+ *
+ * Entity system type definitions for schema-based entity types,
+ * CRUD operations, queries, and validation.
+ *
+ * @module @pwfabric/runtime/entity/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/entity/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/entity/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG","sourcesContent":["/**\n * Entity System Types\n *\n * Entity system type definitions for schema-based entity types,\n * CRUD operations, queries, and validation.\n *\n * @module @pwfabric/runtime/entity/types\n */\n\nimport type { z } from 'zod'\n\n// ============================================================\n// BRANDED IDENTIFIERS\n// ============================================================\n\n/**\n * Branded string type for entity type identifiers\n */\nexport type EntityTypeId = string & { readonly __brand: 'EntityTypeId' }\n\n/**\n * Branded string type for entity instance identifiers\n */\nexport type EntityInstanceId = string & { readonly __brand: 'EntityInstanceId' }\n\n// ============================================================\n// ENTITY FIELD DEFINITIONS\n// ============================================================\n\n/**\n * Supported field types for entity definitions\n */\nexport type EntityFieldType =\n  | 'string'\n  | 'number'\n  | 'boolean'\n  | 'date'\n  | 'datetime'\n  | 'enum'\n  | 'json'\n  | 'reference'\n\n/**\n * Definition of a single field within an entity\n */\nexport interface EntityFieldDefinition {\n  readonly name: string\n  readonly type: EntityFieldType\n  readonly required: boolean\n  readonly unique?: boolean\n  readonly defaultValue?: unknown\n  readonly enumValues?: readonly string[]\n  readonly referenceTarget?: EntityTypeId\n  readonly validation?: z.ZodType\n  readonly label?: string\n  readonly description?: string\n}\n\n// ============================================================\n// ENTITY RELATION DEFINITIONS\n// ============================================================\n\n/**\n * Supported relation types between entities\n */\nexport type EntityRelationType = 'has-one' | 'has-many' | 'belongs-to' | 'many-to-many'\n\n/**\n * Definition of a relation between entity types\n */\nexport interface EntityRelationDefinition {\n  readonly name: string\n  readonly type: EntityRelationType\n  readonly target: EntityTypeId\n  readonly foreignKey?: string\n  readonly through?: EntityTypeId\n  readonly cascade?: 'none' | 'delete' | 'nullify'\n}\n\n// ============================================================\n// ENTITY DEFINITION\n// ============================================================\n\n/**\n * Complete definition of an entity type including fields, relations, and schema\n */\nexport interface EntityDefinition {\n  readonly id: EntityTypeId\n  readonly name: string\n  readonly description?: string\n  readonly fields: readonly EntityFieldDefinition[]\n  readonly relations: readonly EntityRelationDefinition[]\n  readonly primaryKey: string\n  readonly timestamps?: boolean\n  readonly softDelete?: boolean\n  readonly schema: z.ZodObject<z.ZodRawShape>\n}\n\n// ============================================================\n// QUERY TYPES\n// ============================================================\n\n/**\n * Entity query specification with optional filter, sort, and pagination\n */\nexport interface EntityQuery {\n  readonly filter?: EntityFilter\n  readonly sort?: readonly EntitySortField[]\n  readonly pagination?: EntityPagination\n  readonly include?: readonly string[]\n}\n\n/**\n * Filter condition for entity queries\n */\nexport interface EntityFilter {\n  readonly field: string\n  readonly operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'contains' | 'startsWith'\n  readonly value: unknown\n  readonly and?: readonly EntityFilter[]\n  readonly or?: readonly EntityFilter[]\n}\n\n/**\n * Sort field specification\n */\nexport interface EntitySortField {\n  readonly field: string\n  readonly direction: 'asc' | 'desc'\n}\n\n/**\n * Pagination parameters\n */\nexport interface EntityPagination {\n  readonly offset: number\n  readonly limit: number\n}\n\n/** One number over a collection: `count` needs no field, the rest reduce `field`. */\nexport type EntityAggregateFn = 'count' | 'sum' | 'avg'\n\n/**\n * An aggregate request — the source-level `aggregate` key. `filter`\n * narrows the rows first, in the `EntityQuery.filter` shape.\n */\nexport interface EntityAggregate {\n  readonly fn: EntityAggregateFn\n  readonly field?: string\n  readonly filter?: EntityFilter\n}\n\n/**\n * What an aggregate answers: `value` is the number (`null` when a numeric\n * fn found nothing to reduce), `count` the rows the filter kept.\n */\nexport interface EntityAggregateResult {\n  readonly fn: EntityAggregateFn\n  readonly field?: string\n  readonly value: number | null\n  readonly count: number\n}\n\n/**\n * Result of a paginated entity query\n */\nexport interface EntityQueryResult<T = Record<string, unknown>> {\n  readonly items: readonly T[]\n  readonly total: number\n  readonly offset: number\n  readonly limit: number\n  readonly hasMore: boolean\n}\n\n// ============================================================\n// OPERATION RESULTS (DISCRIMINATED UNIONS)\n// ============================================================\n\n/**\n * Result of a create or update mutation\n */\nexport type EntityMutationResult =\n  | {\n      readonly success: true\n      readonly data: Record<string, unknown>\n      readonly id: EntityInstanceId\n    }\n  | { readonly success: false; readonly error: EntityOperationError }\n\n/**\n * Result of a read operation\n */\nexport type EntityReadResult =\n  | { readonly success: true; readonly data: Record<string, unknown> }\n  | { readonly success: false; readonly error: EntityOperationError }\n\n/**\n * Error descriptor for entity operations\n */\nexport interface EntityOperationError {\n  readonly type: 'not_found' | 'validation' | 'conflict' | 'connector' | 'unauthorized' | 'unknown'\n  readonly message: string\n  readonly details?: unknown\n}\n\n// ============================================================\n// VALIDATION TYPES\n// ============================================================\n\n/**\n * Result of entity validation (discriminated union)\n */\nexport type EntityValidationResult =\n  | { readonly valid: true; readonly data: Record<string, unknown> }\n  | { readonly valid: false; readonly errors: readonly EntityValidationError[] }\n\n/**\n * Single field validation error\n */\nexport interface EntityValidationError {\n  readonly field: string\n  readonly message: string\n  readonly code: string\n}\n"]}