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

package/dist/entity/behavior.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Entity Lifecycle Engine
+ *
+ * Event-driven logic on entity lifecycle transitions
+ * using a trigger-guard-action pattern with priority-based execution.
+ *
+ * @module @pwfabric/runtime/entity/behavior
+ */
+import type { EntityTypeId, EntityInstanceId } from './types.js';
+/**
+ * Entity lifecycle events
+ */
+export type EntityLifecycleEvent = 'onCreate' | 'onUpdate' | 'onDelete' | 'onRead';
+/**
+ * Context passed to guards and actions during lifecycle hook execution
+ */
+export interface EntityBehaviorContext {
+    readonly entityType: EntityTypeId;
+    readonly event: EntityLifecycleEvent;
+    readonly data: Record<string, unknown>;
+    readonly previousData?: Record<string, unknown>;
+    readonly instanceId?: EntityInstanceId;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/**
+ * Guard function that determines whether an action should execute
+ */
+export type EntityGuard = (context: EntityBehaviorContext) => boolean;
+/**
+ * Action function executed during a lifecycle event
+ */
+export type EntityAction = (context: EntityBehaviorContext) => void | Promise<void>;
+/**
+ * Entity lifecycle hook definition combining trigger, guard, and action.
+ * Primary name de-behaviorization.
+ */
+export interface EntityLifecycleHook {
+    readonly id: string;
+    readonly entityType: EntityTypeId;
+    readonly trigger: EntityLifecycleEvent;
+    readonly guard?: EntityGuard;
+    readonly action: EntityAction;
+    readonly priority?: number;
+}
+/**
+ * Entity lifecycle hook engine — registers and executes the
+ * onCreate/onUpdate/onDelete/onRead hooks.
+ */
+export interface EntityLifecycleEngine {
+    /**
+     * Register a lifecycle hook
+     * @throws Error if a hook with the same id is already registered
+     */
+    register(hook: EntityLifecycleHook): void;
+    /**
+     * Unregister a hook by id
+     */
+    unregister(hookId: string): boolean;
+    /**
+     * Execute all matching hooks for an entity type and event.
+     * Hooks are executed in priority order (lower priority number = higher precedence).
+     * Guards are checked before each action. Async actions are awaited.
+     */
+    execute(entityType: EntityTypeId, event: EntityLifecycleEvent, context: EntityBehaviorContext): Promise<void>;
+    /**
+     * Get all hooks for an entity type, optionally filtered by event
+     */
+    getBehaviors(entityType: EntityTypeId, event?: EntityLifecycleEvent): readonly EntityLifecycleHook[];
+    /**
+     * Remove all hooks
+     */
+    clear(): void;
+}
+/**
+ * Default EntityLifecycleEngine implementation.
+ * Stores hooks in a Map, executes in priority order.
+ */
+export declare class DefaultEntityLifecycleEngine implements EntityLifecycleEngine {
+    private readonly hooks;
+    register(hook: EntityLifecycleHook): void;
+    unregister(hookId: string): boolean;
+    execute(entityType: EntityTypeId, event: EntityLifecycleEvent, context: EntityBehaviorContext): Promise<void>;
+    getBehaviors(entityType: EntityTypeId, event?: EntityLifecycleEvent): readonly EntityLifecycleHook[];
+    clear(): void;
+}
+/**
+ * Entity lifecycle transition type. Use instead of EntityLifecycleEvent
+ * when referring to transitions (not bus events).
+ */
+export type EntityLifecycleTransition = EntityLifecycleEvent;
+/**
+ * Create an entity lifecycle engine.
+ */
+export declare function createEntityLifecycleEngine(): EntityLifecycleEngine;

package/dist/entity/behavior.js

@@ -0,0 +1,78 @@
+/**
+ * Entity Lifecycle Engine
+ *
+ * Event-driven logic on entity lifecycle transitions
+ * using a trigger-guard-action pattern with priority-based execution.
+ *
+ * @module @pwfabric/runtime/entity/behavior
+ */
+// ============================================================
+// DEFAULT BEHAVIOR ENGINE
+// ============================================================
+/**
+ * Default EntityLifecycleEngine implementation.
+ * Stores hooks in a Map, executes in priority order.
+ */
+export class DefaultEntityLifecycleEngine {
+    hooks = new Map();
+    register(hook) {
+        if (!hook.id) {
+            throw new Error('Lifecycle hook must have an id');
+        }
+        if (!hook.entityType) {
+            throw new Error('Lifecycle hook must have an entityType');
+        }
+        if (!hook.trigger) {
+            throw new Error('Lifecycle hook must have a trigger');
+        }
+        if (!hook.action) {
+            throw new Error('Lifecycle hook must have an action');
+        }
+        if (this.hooks.has(hook.id)) {
+            throw new Error(`Lifecycle hook '${hook.id}' is already registered`);
+        }
+        this.hooks.set(hook.id, hook);
+    }
+    unregister(hookId) {
+        return this.hooks.delete(hookId);
+    }
+    async execute(entityType, event, context) {
+        const matching = this.getBehaviors(entityType, event);
+        // Sort by priority (lower number = higher precedence, default = 100)
+        const sorted = [...matching].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+        for (const hook of sorted) {
+            // Check guard
+            if (hook.guard) {
+                const allowed = hook.guard(context);
+                if (!allowed) {
+                    continue;
+                }
+            }
+            // Execute action (await if async)
+            await hook.action(context);
+        }
+    }
+    getBehaviors(entityType, event) {
+        const result = [];
+        for (const hook of this.hooks.values()) {
+            if (hook.entityType !== entityType) {
+                continue;
+            }
+            if (event && hook.trigger !== event) {
+                continue;
+            }
+            result.push(hook);
+        }
+        return result;
+    }
+    clear() {
+        this.hooks.clear();
+    }
+}
+/**
+ * Create an entity lifecycle engine.
+ */
+export function createEntityLifecycleEngine() {
+    return new DefaultEntityLifecycleEngine();
+}
+//# sourceMappingURL=behavior.js.map

package/dist/entity/behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior.js","sourceRoot":"","sources":["../../src/entity/behavior.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA6FH,+DAA+D;AAC/D,0BAA0B;AAC1B,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,OAAO,4BAA4B;IACtB,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAA;IAE/D,QAAQ,CAAC,IAAyB;QAChC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;QACnD,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;QAC3D,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;QACvD,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;QACvD,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,CAAC,EAAE,yBAAyB,CAAC,CAAA;QACtE,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC/B,CAAC;IAED,UAAU,CAAC,MAAc;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IAED,KAAK,CAAC,OAAO,CACX,UAAwB,EACxB,KAA2B,EAC3B,OAA8B;QAE9B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;QAErD,qEAAqE;QACrE,MAAM,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC,CAAA;QAEtF,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,cAAc;YACd,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;gBACnC,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,SAAQ;gBACV,CAAC;YACH,CAAC;YAED,kCAAkC;YAClC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC;IAED,YAAY,CACV,UAAwB,EACxB,KAA4B;QAE5B,MAAM,MAAM,GAA0B,EAAE,CAAA;QAExC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,IAAI,IAAI,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;gBACnC,SAAQ;YACV,CAAC;YAED,IAAI,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBACpC,SAAQ;YACV,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnB,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;IACpB,CAAC;CACF;AAYD;;GAEG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,IAAI,4BAA4B,EAAE,CAAA;AAC3C,CAAC","sourcesContent":["/**\n * Entity Lifecycle Engine\n *\n * Event-driven logic on entity lifecycle transitions\n * using a trigger-guard-action pattern with priority-based execution.\n *\n * @module @pwfabric/runtime/entity/behavior\n */\n\nimport type { EntityTypeId, EntityInstanceId } from './types.js'\n\n// ============================================================\n// LIFECYCLE TYPES\n// ============================================================\n\n/**\n * Entity lifecycle events\n */\nexport type EntityLifecycleEvent = 'onCreate' | 'onUpdate' | 'onDelete' | 'onRead'\n\n/**\n * Context passed to guards and actions during lifecycle hook execution\n */\nexport interface EntityBehaviorContext {\n  readonly entityType: EntityTypeId\n  readonly event: EntityLifecycleEvent\n  readonly data: Record<string, unknown>\n  readonly previousData?: Record<string, unknown>\n  readonly instanceId?: EntityInstanceId\n  readonly metadata: Readonly<Record<string, unknown>>\n}\n\n/**\n * Guard function that determines whether an action should execute\n */\nexport type EntityGuard = (context: EntityBehaviorContext) => boolean\n\n/**\n * Action function executed during a lifecycle event\n */\nexport type EntityAction = (context: EntityBehaviorContext) => void | Promise<void>\n\n/**\n * Entity lifecycle hook definition combining trigger, guard, and action.\n * Primary name de-behaviorization.\n */\nexport interface EntityLifecycleHook {\n  readonly id: string\n  readonly entityType: EntityTypeId\n  readonly trigger: EntityLifecycleEvent\n  readonly guard?: EntityGuard\n  readonly action: EntityAction\n  readonly priority?: number\n}\n\n// ============================================================\n// LIFECYCLE ENGINE INTERFACE\n// ============================================================\n\n/**\n * Entity lifecycle hook engine — registers and executes the\n * onCreate/onUpdate/onDelete/onRead hooks.\n */\nexport interface EntityLifecycleEngine {\n  /**\n   * Register a lifecycle hook\n   * @throws Error if a hook with the same id is already registered\n   */\n  register(hook: EntityLifecycleHook): void\n\n  /**\n   * Unregister a hook by id\n   */\n  unregister(hookId: string): boolean\n\n  /**\n   * Execute all matching hooks for an entity type and event.\n   * Hooks are executed in priority order (lower priority number = higher precedence).\n   * Guards are checked before each action. Async actions are awaited.\n   */\n  execute(\n    entityType: EntityTypeId,\n    event: EntityLifecycleEvent,\n    context: EntityBehaviorContext\n  ): Promise<void>\n\n  /**\n   * Get all hooks for an entity type, optionally filtered by event\n   */\n  getBehaviors(\n    entityType: EntityTypeId,\n    event?: EntityLifecycleEvent\n  ): readonly EntityLifecycleHook[]\n\n  /**\n   * Remove all hooks\n   */\n  clear(): void\n}\n\n// ============================================================\n// DEFAULT BEHAVIOR ENGINE\n// ============================================================\n\n/**\n * Default EntityLifecycleEngine implementation.\n * Stores hooks in a Map, executes in priority order.\n */\nexport class DefaultEntityLifecycleEngine implements EntityLifecycleEngine {\n  private readonly hooks = new Map<string, EntityLifecycleHook>()\n\n  register(hook: EntityLifecycleHook): void {\n    if (!hook.id) {\n      throw new Error('Lifecycle hook must have an id')\n    }\n\n    if (!hook.entityType) {\n      throw new Error('Lifecycle hook must have an entityType')\n    }\n\n    if (!hook.trigger) {\n      throw new Error('Lifecycle hook must have a trigger')\n    }\n\n    if (!hook.action) {\n      throw new Error('Lifecycle hook must have an action')\n    }\n\n    if (this.hooks.has(hook.id)) {\n      throw new Error(`Lifecycle hook '${hook.id}' is already registered`)\n    }\n\n    this.hooks.set(hook.id, hook)\n  }\n\n  unregister(hookId: string): boolean {\n    return this.hooks.delete(hookId)\n  }\n\n  async execute(\n    entityType: EntityTypeId,\n    event: EntityLifecycleEvent,\n    context: EntityBehaviorContext\n  ): Promise<void> {\n    const matching = this.getBehaviors(entityType, event)\n\n    // Sort by priority (lower number = higher precedence, default = 100)\n    const sorted = [...matching].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))\n\n    for (const hook of sorted) {\n      // Check guard\n      if (hook.guard) {\n        const allowed = hook.guard(context)\n        if (!allowed) {\n          continue\n        }\n      }\n\n      // Execute action (await if async)\n      await hook.action(context)\n    }\n  }\n\n  getBehaviors(\n    entityType: EntityTypeId,\n    event?: EntityLifecycleEvent\n  ): readonly EntityLifecycleHook[] {\n    const result: EntityLifecycleHook[] = []\n\n    for (const hook of this.hooks.values()) {\n      if (hook.entityType !== entityType) {\n        continue\n      }\n\n      if (event && hook.trigger !== event) {\n        continue\n      }\n\n      result.push(hook)\n    }\n\n    return result\n  }\n\n  clear(): void {\n    this.hooks.clear()\n  }\n}\n\n// ============================================================\n// LIFECYCLE TRANSITIONS AND FACTORY\n// ============================================================\n\n/**\n * Entity lifecycle transition type. Use instead of EntityLifecycleEvent\n * when referring to transitions (not bus events).\n */\nexport type EntityLifecycleTransition = EntityLifecycleEvent\n\n/**\n * Create an entity lifecycle engine.\n */\nexport function createEntityLifecycleEngine(): EntityLifecycleEngine {\n  return new DefaultEntityLifecycleEngine()\n}\n"]}

package/dist/entity/connector.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Entity Connector Interface
+ *
+ * Connector abstraction for entity data persistence and retrieval.
+ * Follows the adapter pattern established by existing data source implementations.
+ *
+ * @module @pwfabric/runtime/entity/connector
+ */
+import type { EntityTypeId, EntityInstanceId, EntityQuery, EntityQueryResult, EntityAggregate, EntityAggregateResult } from './types.js';
+/**
+ * Supported connector types
+ */
+export type EntityConnectorType = 'http' | 'database' | 'static' | 'custom';
+/**
+ * Result of a connector CRUD operation
+ */
+export type ConnectorResult = {
+    readonly success: true;
+    readonly data: Record<string, unknown>;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Result of a connector query operation
+ */
+export type ConnectorQueryResult = {
+    readonly success: true;
+    readonly result: EntityQueryResult;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Result of a connector aggregate operation
+ */
+export type ConnectorAggregateResult = {
+    readonly success: true;
+    readonly result: EntityAggregateResult;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Interface for entity data connectors.
+ * Connectors handle actual data persistence and retrieval.
+ */
+export interface EntityConnector {
+    /** Connector name for identification */
+    readonly name: string;
+    /** Connector type */
+    readonly type: EntityConnectorType;
+    /**
+     * Create a new entity instance
+     */
+    create(entityType: EntityTypeId, data: Record<string, unknown>): Promise<ConnectorResult>;
+    /**
+     * Read a single entity instance by id
+     */
+    read(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult>;
+    /**
+     * Update an existing entity instance
+     */
+    update(entityType: EntityTypeId, instanceId: EntityInstanceId, data: Record<string, unknown>): Promise<ConnectorResult>;
+    /**
+     * Delete an entity instance
+     */
+    delete(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult>;
+    /**
+     * Query entity instances with filter, sort, and pagination
+     */
+    query(entityType: EntityTypeId, query: EntityQuery): Promise<ConnectorQueryResult>;
+    /**
+     * One number over the collection, server-side. OPTIONAL: a connector
+     * that only lists is reduced in memory by `aggregateThrough` instead.
+     */
+    aggregate?(entityType: EntityTypeId, aggregate: EntityAggregate): Promise<ConnectorAggregateResult>;
+}
+/**
+ * Registry for entity connectors with per-entity-type binding support
+ */
+export interface ConnectorRegistry {
+    /**
+     * Register a connector by name
+     */
+    register(connector: EntityConnector): void;
+    /**
+     * Get a connector by name
+     */
+    get(name: string): EntityConnector | undefined;
+    /**
+     * Check if a connector is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Bind an entity type to a specific connector
+     */
+    bind(entityType: EntityTypeId, connectorName: string): void;
+    /**
+     * Resolve the connector for an entity type.
+     * Returns the bound connector, or the default connector if set.
+     */
+    resolve(entityType: EntityTypeId): EntityConnector | undefined;
+    /**
+     * Set a default connector for unbound entity types
+     */
+    setDefault(connectorName: string): void;
+    /**
+     * List all registered connector names
+     */
+    list(): readonly string[];
+    /**
+     * Remove a connector by name
+     */
+    unregister(name: string): boolean;
+    /**
+     * Remove all connectors and bindings
+     */
+    clear(): void;
+}
+/**
+ * In-memory implementation of ConnectorRegistry
+ */
+export declare class InMemoryConnectorRegistry implements ConnectorRegistry {
+    private readonly connectors;
+    private readonly bindings;
+    private defaultConnectorName;
+    register(connector: EntityConnector): void;
+    get(name: string): EntityConnector | undefined;
+    has(name: string): boolean;
+    bind(entityType: EntityTypeId, connectorName: string): void;
+    resolve(entityType: EntityTypeId): EntityConnector | undefined;
+    setDefault(connectorName: string): void;
+    list(): readonly string[];
+    unregister(name: string): boolean;
+    clear(): void;
+}
+/**
+ * Create a connector registry
+ */
+export declare function createConnectorRegistry(): ConnectorRegistry;

package/dist/entity/connector.js

@@ -0,0 +1,89 @@
+/**
+ * Entity Connector Interface
+ *
+ * Connector abstraction for entity data persistence and retrieval.
+ * Follows the adapter pattern established by existing data source implementations.
+ *
+ * @module @pwfabric/runtime/entity/connector
+ */
+// ============================================================
+// IN-MEMORY CONNECTOR REGISTRY
+// ============================================================
+/**
+ * In-memory implementation of ConnectorRegistry
+ */
+export class InMemoryConnectorRegistry {
+    connectors = new Map();
+    bindings = new Map();
+    defaultConnectorName;
+    register(connector) {
+        if (!connector.name) {
+            throw new Error('Connector must have a name');
+        }
+        if (this.connectors.has(connector.name)) {
+            throw new Error(`Connector '${connector.name}' is already registered`);
+        }
+        this.connectors.set(connector.name, connector);
+    }
+    get(name) {
+        return this.connectors.get(name);
+    }
+    has(name) {
+        return this.connectors.has(name);
+    }
+    bind(entityType, connectorName) {
+        if (!this.connectors.has(connectorName)) {
+            throw new Error(`Connector '${connectorName}' is not registered`);
+        }
+        this.bindings.set(entityType, connectorName);
+    }
+    resolve(entityType) {
+        // Check entity-specific binding first
+        const boundName = this.bindings.get(entityType);
+        if (boundName) {
+            return this.connectors.get(boundName);
+        }
+        // Fall back to default
+        if (this.defaultConnectorName) {
+            return this.connectors.get(this.defaultConnectorName);
+        }
+        return undefined;
+    }
+    setDefault(connectorName) {
+        if (!this.connectors.has(connectorName)) {
+            throw new Error(`Connector '${connectorName}' is not registered`);
+        }
+        this.defaultConnectorName = connectorName;
+    }
+    list() {
+        return Array.from(this.connectors.keys());
+    }
+    unregister(name) {
+        // Remove any bindings pointing to this connector
+        for (const [entityType, boundName] of this.bindings) {
+            if (boundName === name) {
+                this.bindings.delete(entityType);
+            }
+        }
+        // Clear default if it matches
+        if (this.defaultConnectorName === name) {
+            this.defaultConnectorName = undefined;
+        }
+        return this.connectors.delete(name);
+    }
+    clear() {
+        this.connectors.clear();
+        this.bindings.clear();
+        this.defaultConnectorName = undefined;
+    }
+}
+// ============================================================
+// FACTORY FUNCTION
+// ============================================================
+/**
+ * Create a connector registry
+ */
+export function createConnectorRegistry() {
+    return new InMemoryConnectorRegistry();
+}
+//# sourceMappingURL=connector.js.map

package/dist/entity/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/entity/connector.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Entity Connector Interface\n *\n * Connector abstraction for entity data persistence and retrieval.\n * Follows the adapter pattern established by existing data source implementations.\n *\n * @module @pwfabric/runtime/entity/connector\n */\n\nimport type {\n  EntityTypeId,\n  EntityInstanceId,\n  EntityQuery,\n  EntityQueryResult,\n  EntityAggregate,\n  EntityAggregateResult,\n} from './types.js'\n\n// ============================================================\n// CONNECTOR TYPES\n// ============================================================\n\n/**\n * Supported connector types\n */\nexport type EntityConnectorType = 'http' | 'database' | 'static' | 'custom'\n\n/**\n * Result of a connector CRUD operation\n */\nexport type ConnectorResult =\n  | { readonly success: true; readonly data: Record<string, unknown> }\n  | { readonly success: false; readonly error: string }\n\n/**\n * Result of a connector query operation\n */\nexport type ConnectorQueryResult =\n  | { readonly success: true; readonly result: EntityQueryResult }\n  | { readonly success: false; readonly error: string }\n\n/**\n * Result of a connector aggregate operation\n */\nexport type ConnectorAggregateResult =\n  | { readonly success: true; readonly result: EntityAggregateResult }\n  | { readonly success: false; readonly error: string }\n\n// ============================================================\n// ENTITY CONNECTOR INTERFACE\n// ============================================================\n\n/**\n * Interface for entity data connectors.\n * Connectors handle actual data persistence and retrieval.\n */\nexport interface EntityConnector {\n  /** Connector name for identification */\n  readonly name: string\n\n  /** Connector type */\n  readonly type: EntityConnectorType\n\n  /**\n   * Create a new entity instance\n   */\n  create(entityType: EntityTypeId, data: Record<string, unknown>): Promise<ConnectorResult>\n\n  /**\n   * Read a single entity instance by id\n   */\n  read(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult>\n\n  /**\n   * Update an existing entity instance\n   */\n  update(\n    entityType: EntityTypeId,\n    instanceId: EntityInstanceId,\n    data: Record<string, unknown>\n  ): Promise<ConnectorResult>\n\n  /**\n   * Delete an entity instance\n   */\n  delete(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult>\n\n  /**\n   * Query entity instances with filter, sort, and pagination\n   */\n  query(entityType: EntityTypeId, query: EntityQuery): Promise<ConnectorQueryResult>\n\n  /**\n   * One number over the collection, server-side. OPTIONAL: a connector\n   * that only lists is reduced in memory by `aggregateThrough` instead.\n   */\n  aggregate?(entityType: EntityTypeId, aggregate: EntityAggregate): Promise<ConnectorAggregateResult>\n}\n\n// ============================================================\n// CONNECTOR REGISTRY\n// ============================================================\n\n/**\n * Registry for entity connectors with per-entity-type binding support\n */\nexport interface ConnectorRegistry {\n  /**\n   * Register a connector by name\n   */\n  register(connector: EntityConnector): void\n\n  /**\n   * Get a connector by name\n   */\n  get(name: string): EntityConnector | undefined\n\n  /**\n   * Check if a connector is registered\n   */\n  has(name: string): boolean\n\n  /**\n   * Bind an entity type to a specific connector\n   */\n  bind(entityType: EntityTypeId, connectorName: string): void\n\n  /**\n   * Resolve the connector for an entity type.\n   * Returns the bound connector, or the default connector if set.\n   */\n  resolve(entityType: EntityTypeId): EntityConnector | undefined\n\n  /**\n   * Set a default connector for unbound entity types\n   */\n  setDefault(connectorName: string): void\n\n  /**\n   * List all registered connector names\n   */\n  list(): readonly string[]\n\n  /**\n   * Remove a connector by name\n   */\n  unregister(name: string): boolean\n\n  /**\n   * Remove all connectors and bindings\n   */\n  clear(): void\n}\n\n// ============================================================\n// IN-MEMORY CONNECTOR REGISTRY\n// ============================================================\n\n/**\n * In-memory implementation of ConnectorRegistry\n */\nexport class InMemoryConnectorRegistry implements ConnectorRegistry {\n  private readonly connectors = new Map<string, EntityConnector>()\n  private readonly bindings = new Map<EntityTypeId, string>()\n  private defaultConnectorName: string | undefined\n\n  register(connector: EntityConnector): void {\n    if (!connector.name) {\n      throw new Error('Connector must have a name')\n    }\n\n    if (this.connectors.has(connector.name)) {\n      throw new Error(`Connector '${connector.name}' is already registered`)\n    }\n\n    this.connectors.set(connector.name, connector)\n  }\n\n  get(name: string): EntityConnector | undefined {\n    return this.connectors.get(name)\n  }\n\n  has(name: string): boolean {\n    return this.connectors.has(name)\n  }\n\n  bind(entityType: EntityTypeId, connectorName: string): void {\n    if (!this.connectors.has(connectorName)) {\n      throw new Error(`Connector '${connectorName}' is not registered`)\n    }\n\n    this.bindings.set(entityType, connectorName)\n  }\n\n  resolve(entityType: EntityTypeId): EntityConnector | undefined {\n    // Check entity-specific binding first\n    const boundName = this.bindings.get(entityType)\n    if (boundName) {\n      return this.connectors.get(boundName)\n    }\n\n    // Fall back to default\n    if (this.defaultConnectorName) {\n      return this.connectors.get(this.defaultConnectorName)\n    }\n\n    return undefined\n  }\n\n  setDefault(connectorName: string): void {\n    if (!this.connectors.has(connectorName)) {\n      throw new Error(`Connector '${connectorName}' is not registered`)\n    }\n\n    this.defaultConnectorName = connectorName\n  }\n\n  list(): readonly string[] {\n    return Array.from(this.connectors.keys())\n  }\n\n  unregister(name: string): boolean {\n    // Remove any bindings pointing to this connector\n    for (const [entityType, boundName] of this.bindings) {\n      if (boundName === name) {\n        this.bindings.delete(entityType)\n      }\n    }\n\n    // Clear default if it matches\n    if (this.defaultConnectorName === name) {\n      this.defaultConnectorName = undefined\n    }\n\n    return this.connectors.delete(name)\n  }\n\n  clear(): void {\n    this.connectors.clear()\n    this.bindings.clear()\n    this.defaultConnectorName = undefined\n  }\n}\n\n// ============================================================\n// FACTORY FUNCTION\n// ============================================================\n\n/**\n * Create a connector registry\n */\nexport function createConnectorRegistry(): ConnectorRegistry {\n  return new InMemoryConnectorRegistry()\n}\n"]}

package/dist/entity/connectors/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Entity Connectors Module
+ *
+ * Connector implementations for entity data persistence.
+ *
+ * @module @pwfabric/runtime/entity/connectors
+ */
+export { StaticConnector, createStaticConnector } from './static.js';
+export type { HttpAuthConfig, HttpRetryConfig, HttpConnectorConfig } from '../http-connector.js';
+export { HttpEntityConnector, createHttpConnector } from '../http-connector.js';
+export type { PostgresConnectorConfig, DatabaseAdapter, DatabaseResult, } from '../postgres-connector.js';
+export { PostgresEntityConnector, createPostgresConnector } from '../postgres-connector.js';

package/dist/entity/connectors/index.js

@@ -0,0 +1,11 @@
+/**
+ * Entity Connectors Module
+ *
+ * Connector implementations for entity data persistence.
+ *
+ * @module @pwfabric/runtime/entity/connectors
+ */
+export { StaticConnector, createStaticConnector } from './static.js';
+export { HttpEntityConnector, createHttpConnector } from '../http-connector.js';
+export { PostgresEntityConnector, createPostgresConnector } from '../postgres-connector.js';
+//# sourceMappingURL=index.js.map

package/dist/entity/connectors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/entity/connectors/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAIpE,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAQ/E,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA","sourcesContent":["/**\n * Entity Connectors Module\n *\n * Connector implementations for entity data persistence.\n *\n * @module @pwfabric/runtime/entity/connectors\n */\n\nexport { StaticConnector, createStaticConnector } from './static.js'\n\n// HTTP connector\nexport type { HttpAuthConfig, HttpRetryConfig, HttpConnectorConfig } from '../http-connector.js'\nexport { HttpEntityConnector, createHttpConnector } from '../http-connector.js'\n\n// PostgreSQL connector\nexport type {\n  PostgresConnectorConfig,\n  DatabaseAdapter,\n  DatabaseResult,\n} from '../postgres-connector.js'\nexport { PostgresEntityConnector, createPostgresConnector } from '../postgres-connector.js'\n"]}

package/dist/entity/connectors/static.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Static Entity Connector
+ *
+ * In-memory Map-based connector for prototyping and testing.
+ * Supports filter, sort, and pagination operations.
+ *
+ * @module @pwfabric/runtime/entity/connectors/static
+ */
+import type { EntityTypeId, EntityInstanceId, EntityQuery } from '../types.js';
+import type { EntityConnector, ConnectorResult, ConnectorQueryResult } from '../connector.js';
+/**
+ * In-memory static connector for prototyping and testing.
+ * Stores data in a Map keyed by entity type, then by instance id.
+ */
+export declare class StaticConnector implements EntityConnector {
+    readonly name: string;
+    readonly type: "static";
+    private readonly store;
+    private counter;
+    constructor(name?: string);
+    create(entityType: EntityTypeId, data: Record<string, unknown>): Promise<ConnectorResult>;
+    read(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult>;
+    update(entityType: EntityTypeId, instanceId: EntityInstanceId, data: Record<string, unknown>): Promise<ConnectorResult>;
+    delete(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult>;
+    query(entityType: EntityTypeId, query: EntityQuery): Promise<ConnectorQueryResult>;
+    /**
+     * Seed data into the connector for testing
+     */
+    seed(entityType: EntityTypeId, records: Record<string, unknown>[]): void;
+    /**
+     * Clear all data from the connector
+     */
+    clear(): void;
+    /**
+     * Clear data for a specific entity type
+     */
+    clearType(entityType: EntityTypeId): void;
+    /**
+     * Get the total count of records for an entity type
+     */
+    count(entityType: EntityTypeId): number;
+    private getOrCreateTypeStore;
+    private generateId;
+    private applyFilter;
+    private matchesCondition;
+    private applySort;
+}
+/**
+ * Create a static connector
+ */
+export declare function createStaticConnector(name?: string): StaticConnector;