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

package/dist/entity/http-connector.js

@@ -0,0 +1,295 @@
+/**
+ * HTTP Entity Connector
+ *
+ * REST API connector for entity data persistence and retrieval.
+ * Implements the EntityConnector interface using fetch for HTTP communication.
+ *
+ * @module @pwfabric/runtime/entity/http-connector
+ */
+import { z } from 'zod';
+// ============================================================
+// DEFAULTS
+// ============================================================
+const queryResponseSchema = z
+    .object({
+    items: z.array(z.unknown()).optional(),
+    total: z.number().optional(),
+    offset: z.number().optional(),
+    limit: z.number().optional(),
+})
+    .passthrough();
+/**
+ * `{ data: { fn, field?, value, count, numericCount? }, meta }` is how the
+ * platform answers (`routes/app-records.ts`); a bare `{ value, count }` body
+ * is accepted too. `value` is null when a numeric fn had nothing to reduce.
+ */
+const aggregateBodySchema = z
+    .object({
+    fn: z.enum(['count', 'sum', 'avg']).optional(),
+    field: z.string().optional(),
+    value: z.number().nullable().optional(),
+    count: z.number().optional(),
+})
+    .passthrough();
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_RETRY = {
+    maxRetries: 3,
+    baseDelay: 1000,
+    maxDelay: 10_000,
+    retryableStatuses: [408, 429, 500, 502, 503, 504],
+};
+// ============================================================
+// HTTP ENTITY CONNECTOR
+// ============================================================
+/**
+ * HTTP/REST connector for entity data operations.
+ * Maps entity CRUD operations to standard REST API endpoints.
+ */
+export class HttpEntityConnector {
+    name;
+    type = 'http';
+    config;
+    constructor(name, config) {
+        this.name = name;
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? DEFAULT_TIMEOUT,
+        };
+    }
+    async create(entityType, data) {
+        const url = this.buildUrl(entityType);
+        return this.request('POST', url, data);
+    }
+    async read(entityType, instanceId) {
+        const url = `${this.buildUrl(entityType)}/${instanceId}`;
+        return this.request('GET', url);
+    }
+    async update(entityType, instanceId, data) {
+        const url = `${this.buildUrl(entityType)}/${instanceId}`;
+        return this.request('PATCH', url, data);
+    }
+    async delete(entityType, instanceId) {
+        const url = `${this.buildUrl(entityType)}/${instanceId}`;
+        return this.request('DELETE', url);
+    }
+    async query(entityType, query) {
+        const url = this.buildUrl(entityType);
+        const params = this.buildQueryParams(query);
+        const fullUrl = params ? `${url}?${params}` : url;
+        const result = await this.request('GET', fullUrl);
+        if (!result.success) {
+            return { success: false, error: result.error };
+        }
+        // A vendor shape is mapped BEFORE the built-in schema runs — the mapper
+        // exists precisely for bodies this schema would reject, so validating first
+        // would refuse the very responses it was added to accept.
+        if (this.config.responseMapper) {
+            const mapped = this.config.responseMapper(result.data);
+            const items = mapped.items;
+            const total = mapped.total ?? items.length;
+            const offset = query.pagination?.offset ?? 0;
+            return {
+                success: true,
+                result: {
+                    items,
+                    total,
+                    offset,
+                    limit: query.pagination?.limit ?? items.length,
+                    hasMore: total > offset + items.length,
+                },
+            };
+        }
+        const parsed = queryResponseSchema.safeParse(result.data);
+        if (!parsed.success) {
+            return { success: false, error: 'Invalid query response shape' };
+        }
+        const data = parsed.data;
+        // Accept both the connector contract ({items,total}) and the platform
+        // entity-records envelope ({data:[...], meta:{total}}).
+        const rawItems = (data.items ??
+            data.data ??
+            []);
+        // Entity records store user fields under `.data` — flatten them to the top
+        // level so expression/column bindings ({{id}}, column key 'name') resolve
+        // against the fields, while keeping id/metadata available.
+        const items = rawItems.map((r) => r && typeof r === 'object' && r.data && typeof r.data === 'object'
+            ? { ...r, ...r.data }
+            : r);
+        const meta = data.meta;
+        const total = data.total ?? meta?.total ?? items.length;
+        return {
+            success: true,
+            result: {
+                items,
+                total,
+                offset: data.offset ?? query.pagination?.offset ?? 0,
+                limit: data.limit ?? query.pagination?.limit ?? 50,
+                hasMore: total > (data.offset ?? 0) + items.length,
+            },
+        };
+    }
+    /**
+     * One number over the collection, computed by the server.
+     *
+     * `GET <base>/<type>/count[?filter=]` for a plain count and
+     * `GET <base>/<type>/aggregate?fn=&field=&filter=` for the rest — the two
+     * routes a host registers ahead of the read-one route.
+     * Constants (`defaultQueryParams`) and `entityPathMapper` apply as on
+     * every other read.
+     */
+    async aggregate(entityType, aggregate) {
+        const plainCount = aggregate.fn === 'count' && !aggregate.field;
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(this.config.defaultQueryParams ?? {}))
+            params.set(k, v);
+        if (!plainCount) {
+            params.set('fn', aggregate.fn);
+            if (aggregate.field)
+                params.set('field', aggregate.field);
+        }
+        if (aggregate.filter)
+            params.set('filter', JSON.stringify(aggregate.filter));
+        const url = `${this.buildUrl(entityType)}/${plainCount ? 'count' : 'aggregate'}`;
+        const qs = params.toString();
+        const result = await this.request('GET', qs ? `${url}?${qs}` : url);
+        if (!result.success)
+            return { success: false, error: result.error };
+        const envelope = result.data;
+        const body = envelope.data && typeof envelope.data === 'object' ? envelope.data : envelope;
+        const parsed = aggregateBodySchema.safeParse(body);
+        if (!parsed.success)
+            return { success: false, error: 'Invalid aggregate response shape' };
+        const d = parsed.data;
+        const field = d.field ?? aggregate.field;
+        const out = {
+            fn: d.fn ?? aggregate.fn,
+            ...(field ? { field } : {}),
+            value: d.value ?? null,
+            count: d.count ?? 0,
+        };
+        return { success: true, result: out };
+    }
+    // ============================================================
+    // PRIVATE HELPERS
+    // ============================================================
+    buildUrl(entityType) {
+        const path = this.config.entityPathMapper
+            ? this.config.entityPathMapper(entityType)
+            : `/${entityType}`;
+        return `${this.config.baseUrl}${path}`;
+    }
+    buildQueryParams(query) {
+        const params = new URLSearchParams();
+        // Constants first so a caller's own query can still override one.
+        for (const [k, v] of Object.entries(this.config.defaultQueryParams ?? {})) {
+            params.set(k, v);
+        }
+        if (query.pagination) {
+            params.set('offset', String(query.pagination.offset));
+            params.set('limit', String(query.pagination.limit));
+        }
+        if (query.sort && query.sort.length > 0) {
+            params.set('sort', query.sort.map((s) => `${s.field}:${s.direction}`).join(','));
+        }
+        if (query.filter) {
+            params.set('filter', JSON.stringify(query.filter));
+        }
+        if (query.include && query.include.length > 0) {
+            params.set('include', query.include.join(','));
+        }
+        return params.toString();
+    }
+    async buildHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...this.config.headers,
+        };
+        if (this.config.auth) {
+            const authHeader = await this.resolveAuthHeader(this.config.auth);
+            if (authHeader) {
+                Object.assign(headers, authHeader);
+            }
+        }
+        return headers;
+    }
+    async resolveAuthHeader(auth) {
+        switch (auth.type) {
+            case 'bearer': {
+                // Resolved per request, never cached — a session-length token is the
+                // reason this accepts a function at all. A resolver that answers null
+                // yields NO header: the server's own 401 is a truer error than a
+                // client-side guess, and the panel's errorWhen already renders it.
+                const token = typeof auth.token === 'function' ? await auth.token() : auth.token;
+                return token ? { Authorization: `Bearer ${token}` } : null;
+            }
+            case 'api-key':
+                return auth.apiKey ? { [auth.headerName ?? 'X-API-Key']: auth.apiKey } : null;
+            case 'basic':
+                if (auth.username && auth.password) {
+                    const encoded = btoa(`${auth.username}:${auth.password}`);
+                    return { Authorization: `Basic ${encoded}` };
+                }
+                return null;
+            default:
+                return null;
+        }
+    }
+    async request(method, url, body) {
+        const retryConfig = this.config.retry ?? DEFAULT_RETRY;
+        let lastError = '';
+        for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+                const response = await fetch(url, {
+                    method,
+                    headers: await this.buildHeaders(),
+                    body: body ? JSON.stringify(body) : null,
+                    signal: controller.signal,
+                    ...(this.config.credentials ? { credentials: this.config.credentials } : {}),
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    if (attempt < retryConfig.maxRetries &&
+                        retryConfig.retryableStatuses.includes(response.status)) {
+                        const delay = Math.min(retryConfig.baseDelay * Math.pow(2, attempt), retryConfig.maxDelay);
+                        await this.sleep(delay);
+                        continue;
+                    }
+                    const errorBody = await response.text().catch(() => '');
+                    lastError = `HTTP ${response.status}: ${errorBody || response.statusText}`;
+                    return { success: false, error: lastError };
+                }
+                if (method === 'DELETE' && response.status === 204) {
+                    return { success: true, data: {} };
+                }
+                const jsonData = await response.json();
+                const data = z.record(z.unknown()).parse(jsonData);
+                return { success: true, data };
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+                if (attempt < retryConfig.maxRetries) {
+                    const delay = Math.min(retryConfig.baseDelay * Math.pow(2, attempt), retryConfig.maxDelay);
+                    await this.sleep(delay);
+                    continue;
+                }
+            }
+        }
+        return { success: false, error: lastError };
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create an HTTP entity connector
+ */
+export function createHttpConnector(name, config) {
+    return new HttpEntityConnector(name, config);
+}
+//# sourceMappingURL=http-connector.js.map

package/dist/entity/http-connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-connector.js","sourceRoot":"","sources":["../../src/entity/http-connector.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP Entity Connector\n *\n * REST API connector for entity data persistence and retrieval.\n * Implements the EntityConnector interface using fetch for HTTP communication.\n *\n * @module @pwfabric/runtime/entity/http-connector\n */\n\nimport { z } from 'zod'\nimport type {\n  EntityTypeId,\n  EntityInstanceId,\n  EntityQuery,\n  EntityAggregate,\n  EntityAggregateResult,\n} from './types.js'\nimport type {\n  EntityConnector,\n  EntityConnectorType,\n  ConnectorResult,\n  ConnectorQueryResult,\n  ConnectorAggregateResult,\n} from './connector.js'\n\n// ============================================================\n// CONFIGURATION\n// ============================================================\n\n/**\n * HTTP connector authentication configuration\n */\nexport interface HttpAuthConfig {\n  readonly type: 'bearer' | 'api-key' | 'basic'\n  /**\n   * A fixed value, or a RESOLVER re-invoked on every request.\n   *\n   * A string or a resolver. A delegated PKCE token expires within about an\n   * hour, so a fixed string cannot serve a session; an engine that needs a\n   * live token passes a resolver instead of reimplementing the transport\n   * (and losing retry, timeout and the result envelope on the way).\n   *\n   * A string is used as is; a resolver is awaited per request and its answer\n   * is never cached here, which is the whole point.\n   */\n  readonly token?: string | (() => Promise<string | null>)\n  readonly apiKey?: string\n  readonly headerName?: string\n  readonly username?: string\n  readonly password?: string\n}\n\n/**\n * HTTP connector retry configuration\n */\nexport interface HttpRetryConfig {\n  readonly maxRetries: number\n  readonly baseDelay: number\n  readonly maxDelay: number\n  readonly retryableStatuses: readonly number[]\n}\n\n/**\n * HTTP connector configuration\n */\nexport interface HttpConnectorConfig {\n  readonly baseUrl: string\n  readonly headers?: Record<string, string>\n  readonly timeout?: number\n  readonly auth?: HttpAuthConfig\n  /**\n   * Fetch credentials mode. Set 'include' so cookie-authoritative APIs\n   * receive the session cookie on cross-origin entity requests\n   * the visitor facade has no bearer token to send.\n   */\n  readonly credentials?: RequestCredentials\n  readonly retry?: HttpRetryConfig\n  /**\n   * Query parameters this API requires on every read.\n   *\n   * GENERIC, and the distinction matters because three vendor-shaped widenings\n   * were proposed and reverted the same day. Azure wants `api-version`, plenty\n   * of APIs want `format=json`, Graph wants `expand=fields`: \"this endpoint\n   * takes constant parameters\" is a REST fact, not one provider's dance, and no\n   * provider name appears here.\n   *\n   * It exists because the alternative is worse. A caller that put its constants\n   * in `entityPathMapper` would produce `...?expand=fields?limit=50` the moment\n   * a query carried pagination, and `...?expand=fields/1` on a delete — the URL\n   * is assembled as `params ? url + '?' + params : url`.\n   */\n  readonly defaultQueryParams?: Readonly<Record<string, string>>\n  readonly entityPathMapper?: (entityType: EntityTypeId) => string\n  /**\n   * Maps a vendor response body to the connector's query result shape\n   * `entityPathMapper`'s response-side twin.\n   *\n   * `entityPathMapper` has always let a caller say how an entity type becomes a\n   * URL path; nothing let it say how the answer comes back. So a vendor whose\n   * body is its own shape — Graph replies `{ value: [{ id, fields }] }`, not\n   * `{ items }` — could not use this class at all, and that was the other half\n   * of why every Graph engine forked. Absent, the built-in shapes below apply\n   * unchanged.\n   */\n  readonly responseMapper?: (raw: unknown) => { items: unknown[]; total?: number }\n}\n\n// ============================================================\n// DEFAULTS\n// ============================================================\n\nconst queryResponseSchema = z\n  .object({\n    items: z.array(z.unknown()).optional(),\n    total: z.number().optional(),\n    offset: z.number().optional(),\n    limit: z.number().optional(),\n  })\n  .passthrough()\n\n/**\n * `{ data: { fn, field?, value, count, numericCount? }, meta }` is how the\n * platform answers (`routes/app-records.ts`); a bare `{ value, count }` body\n * is accepted too. `value` is null when a numeric fn had nothing to reduce.\n */\nconst aggregateBodySchema = z\n  .object({\n    fn: z.enum(['count', 'sum', 'avg']).optional(),\n    field: z.string().optional(),\n    value: z.number().nullable().optional(),\n    count: z.number().optional(),\n  })\n  .passthrough()\n\nconst DEFAULT_TIMEOUT = 30_000\n\nconst DEFAULT_RETRY: HttpRetryConfig = {\n  maxRetries: 3,\n  baseDelay: 1000,\n  maxDelay: 10_000,\n  retryableStatuses: [408, 429, 500, 502, 503, 504],\n}\n\n// ============================================================\n// HTTP ENTITY CONNECTOR\n// ============================================================\n\n/**\n * HTTP/REST connector for entity data operations.\n * Maps entity CRUD operations to standard REST API endpoints.\n */\nexport class HttpEntityConnector implements EntityConnector {\n  readonly name: string\n  readonly type: EntityConnectorType = 'http'\n\n  private readonly config: Required<Pick<HttpConnectorConfig, 'baseUrl' | 'timeout'>> &\n    HttpConnectorConfig\n\n  constructor(name: string, config: HttpConnectorConfig) {\n    this.name = name\n    this.config = {\n      ...config,\n      timeout: config.timeout ?? DEFAULT_TIMEOUT,\n    }\n  }\n\n  async create(entityType: EntityTypeId, data: Record<string, unknown>): Promise<ConnectorResult> {\n    const url = this.buildUrl(entityType)\n    return this.request('POST', url, data)\n  }\n\n  async read(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult> {\n    const url = `${this.buildUrl(entityType)}/${instanceId}`\n    return this.request('GET', url)\n  }\n\n  async update(\n    entityType: EntityTypeId,\n    instanceId: EntityInstanceId,\n    data: Record<string, unknown>\n  ): Promise<ConnectorResult> {\n    const url = `${this.buildUrl(entityType)}/${instanceId}`\n    return this.request('PATCH', url, data)\n  }\n\n  async delete(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult> {\n    const url = `${this.buildUrl(entityType)}/${instanceId}`\n    return this.request('DELETE', url)\n  }\n\n  async query(entityType: EntityTypeId, query: EntityQuery): Promise<ConnectorQueryResult> {\n    const url = this.buildUrl(entityType)\n    const params = this.buildQueryParams(query)\n    const fullUrl = params ? `${url}?${params}` : url\n\n    const result = await this.request('GET', fullUrl)\n    if (!result.success) {\n      return { success: false, error: result.error }\n    }\n\n    // A vendor shape is mapped BEFORE the built-in schema runs — the mapper\n    // exists precisely for bodies this schema would reject, so validating first\n    // would refuse the very responses it was added to accept.\n    if (this.config.responseMapper) {\n      const mapped = this.config.responseMapper(result.data)\n      const items = mapped.items as Record<string, unknown>[]\n      const total = mapped.total ?? items.length\n      const offset = query.pagination?.offset ?? 0\n      return {\n        success: true,\n        result: {\n          items,\n          total,\n          offset,\n          limit: query.pagination?.limit ?? items.length,\n          hasMore: total > offset + items.length,\n        },\n      }\n    }\n\n    const parsed = queryResponseSchema.safeParse(result.data)\n    if (!parsed.success) {\n      return { success: false, error: 'Invalid query response shape' }\n    }\n    const data = parsed.data as Record<string, unknown>\n\n    // Accept both the connector contract ({items,total}) and the platform\n    // entity-records envelope ({data:[...], meta:{total}}).\n    const rawItems = ((data.items as unknown[]) ??\n      (data.data as unknown[]) ??\n      []) as Record<string, unknown>[]\n    // Entity records store user fields under `.data` — flatten them to the top\n    // level so expression/column bindings ({{id}}, column key 'name') resolve\n    // against the fields, while keeping id/metadata available.\n    const items = rawItems.map((r) =>\n      r && typeof r === 'object' && r.data && typeof r.data === 'object'\n        ? { ...r, ...(r.data as Record<string, unknown>) }\n        : r\n    )\n    const meta = data.meta as Record<string, unknown> | undefined\n    const total = (data.total as number) ?? (meta?.total as number) ?? items.length\n\n    return {\n      success: true,\n      result: {\n        items,\n        total,\n        offset: (data.offset as number) ?? query.pagination?.offset ?? 0,\n        limit: (data.limit as number) ?? query.pagination?.limit ?? 50,\n        hasMore: total > ((data.offset as number) ?? 0) + items.length,\n      },\n    }\n  }\n\n  /**\n   * One number over the collection, computed by the server.\n   *\n   * `GET <base>/<type>/count[?filter=]` for a plain count and\n   * `GET <base>/<type>/aggregate?fn=&field=&filter=` for the rest — the two\n   * routes a host registers ahead of the read-one route.\n   * Constants (`defaultQueryParams`) and `entityPathMapper` apply as on\n   * every other read.\n   */\n  async aggregate(entityType: EntityTypeId, aggregate: EntityAggregate): Promise<ConnectorAggregateResult> {\n    const plainCount = aggregate.fn === 'count' && !aggregate.field\n    const params = new URLSearchParams()\n    for (const [k, v] of Object.entries(this.config.defaultQueryParams ?? {})) params.set(k, v)\n    if (!plainCount) {\n      params.set('fn', aggregate.fn)\n      if (aggregate.field) params.set('field', aggregate.field)\n    }\n    if (aggregate.filter) params.set('filter', JSON.stringify(aggregate.filter))\n    const url = `${this.buildUrl(entityType)}/${plainCount ? 'count' : 'aggregate'}`\n    const qs = params.toString()\n\n    const result = await this.request('GET', qs ? `${url}?${qs}` : url)\n    if (!result.success) return { success: false, error: result.error }\n\n    const envelope = result.data\n    const body = envelope.data && typeof envelope.data === 'object' ? envelope.data : envelope\n    const parsed = aggregateBodySchema.safeParse(body)\n    if (!parsed.success) return { success: false, error: 'Invalid aggregate response shape' }\n    const d = parsed.data\n    const field = d.field ?? aggregate.field\n    const out: EntityAggregateResult = {\n      fn: d.fn ?? aggregate.fn,\n      ...(field ? { field } : {}),\n      value: d.value ?? null,\n      count: d.count ?? 0,\n    }\n    return { success: true, result: out }\n  }\n\n  // ============================================================\n  // PRIVATE HELPERS\n  // ============================================================\n\n  private buildUrl(entityType: EntityTypeId): string {\n    const path = this.config.entityPathMapper\n      ? this.config.entityPathMapper(entityType)\n      : `/${entityType}`\n    return `${this.config.baseUrl}${path}`\n  }\n\n  private buildQueryParams(query: EntityQuery): string {\n    const params = new URLSearchParams()\n\n    // Constants first so a caller's own query can still override one.\n    for (const [k, v] of Object.entries(this.config.defaultQueryParams ?? {})) {\n      params.set(k, v)\n    }\n\n    if (query.pagination) {\n      params.set('offset', String(query.pagination.offset))\n      params.set('limit', String(query.pagination.limit))\n    }\n\n    if (query.sort && query.sort.length > 0) {\n      params.set('sort', query.sort.map((s) => `${s.field}:${s.direction}`).join(','))\n    }\n\n    if (query.filter) {\n      params.set('filter', JSON.stringify(query.filter))\n    }\n\n    if (query.include && query.include.length > 0) {\n      params.set('include', query.include.join(','))\n    }\n\n    return params.toString()\n  }\n\n  private async buildHeaders(): Promise<Record<string, string>> {\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      Accept: 'application/json',\n      ...this.config.headers,\n    }\n\n    if (this.config.auth) {\n      const authHeader = await this.resolveAuthHeader(this.config.auth)\n      if (authHeader) {\n        Object.assign(headers, authHeader)\n      }\n    }\n\n    return headers\n  }\n\n  private async resolveAuthHeader(auth: HttpAuthConfig): Promise<Record<string, string> | null> {\n    switch (auth.type) {\n      case 'bearer': {\n        // Resolved per request, never cached — a session-length token is the\n        // reason this accepts a function at all. A resolver that answers null\n        // yields NO header: the server's own 401 is a truer error than a\n        // client-side guess, and the panel's errorWhen already renders it.\n        const token = typeof auth.token === 'function' ? await auth.token() : auth.token\n        return token ? { Authorization: `Bearer ${token}` } : null\n      }\n      case 'api-key':\n        return auth.apiKey ? { [auth.headerName ?? 'X-API-Key']: auth.apiKey } : null\n      case 'basic':\n        if (auth.username && auth.password) {\n          const encoded = btoa(`${auth.username}:${auth.password}`)\n          return { Authorization: `Basic ${encoded}` }\n        }\n        return null\n      default:\n        return null\n    }\n  }\n\n  private async request(\n    method: string,\n    url: string,\n    body?: Record<string, unknown>\n  ): Promise<ConnectorResult> {\n    const retryConfig = this.config.retry ?? DEFAULT_RETRY\n    let lastError = ''\n\n    for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {\n      try {\n        const controller = new AbortController()\n        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout)\n\n        const response = await fetch(url, {\n          method,\n          headers: await this.buildHeaders(),\n          body: body ? JSON.stringify(body) : null,\n          signal: controller.signal,\n          ...(this.config.credentials ? { credentials: this.config.credentials } : {}),\n        })\n\n        clearTimeout(timeoutId)\n\n        if (!response.ok) {\n          if (\n            attempt < retryConfig.maxRetries &&\n            retryConfig.retryableStatuses.includes(response.status)\n          ) {\n            const delay = Math.min(\n              retryConfig.baseDelay * Math.pow(2, attempt),\n              retryConfig.maxDelay\n            )\n            await this.sleep(delay)\n            continue\n          }\n\n          const errorBody = await response.text().catch(() => '')\n          lastError = `HTTP ${response.status}: ${errorBody || response.statusText}`\n          return { success: false, error: lastError }\n        }\n\n        if (method === 'DELETE' && response.status === 204) {\n          return { success: true, data: {} }\n        }\n\n        const jsonData = await response.json()\n        const data = z.record(z.unknown()).parse(jsonData)\n        return { success: true, data }\n      } catch (err) {\n        lastError = err instanceof Error ? err.message : String(err)\n\n        if (attempt < retryConfig.maxRetries) {\n          const delay = Math.min(retryConfig.baseDelay * Math.pow(2, attempt), retryConfig.maxDelay)\n          await this.sleep(delay)\n          continue\n        }\n      }\n    }\n\n    return { success: false, error: lastError }\n  }\n\n  private sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms))\n  }\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create an HTTP entity connector\n */\nexport function createHttpConnector(\n  name: string,\n  config: HttpConnectorConfig\n): HttpEntityConnector {\n  return new HttpEntityConnector(name, config)\n}\n"]}

package/dist/entity/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Entity System Module
+ *
+ * Entity system for schema-based entity types, CRUD operations,
+ * connectors, behaviors, and surface integration.
+ *
+ * Exports:
+ * - Types: EntityTypeId, EntityInstanceId, EntityDefinition, EntityQuery, etc.
+ * - Registry: EntityRegistry, InMemoryEntityRegistry, createEntityRegistry
+ * - Store: EntityStore, DefaultEntityStore, createEntityStore
+ * - Connectors: EntityConnector, ConnectorRegistry, StaticConnector
+ * - Lifecycle: EntityLifecycleEngine, EntityLifecycleHook, createEntityLifecycleEngine
+ * - Facade: EntityFacade, createEntityFacade
+ *
+ * @module @pwfabric/runtime/entity
+ */
+export type { EntityTypeId, EntityInstanceId, EntityFieldType, EntityFieldDefinition, EntityRelationType, EntityRelationDefinition, EntityDefinition, EntityQuery, EntityFilter, EntitySortField, EntityPagination, EntityQueryResult, EntityAggregateFn, EntityAggregate, EntityAggregateResult, EntityMutationResult, EntityReadResult, EntityOperationError, EntityValidationResult, EntityValidationError, } from './types.js';
+export type { EntityRegistry } from './registry.js';
+export { InMemoryEntityRegistry, createEntityRegistry } from './registry.js';
+export type { EntityStore } from './store.js';
+export { DefaultEntityStore, createEntityStore } from './store.js';
+export type { EntityConnectorType, ConnectorResult, ConnectorQueryResult, ConnectorAggregateResult, EntityConnector, ConnectorRegistry, } from './connector.js';
+export { InMemoryConnectorRegistry, createConnectorRegistry } from './connector.js';
+export { StaticConnector, createStaticConnector } from './connectors/index.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';
+export type { EntityLifecycleEngine, EntityLifecycleTransition, EntityLifecycleHook, } from './behavior.js';
+export { DefaultEntityLifecycleEngine, createEntityLifecycleEngine } from './behavior.js';
+export type { EntityLifecycleEvent, EntityBehaviorContext, EntityGuard, EntityAction, } from './behavior.js';
+export type { EntityFacade } from './facade.js';
+export { DefaultEntityFacade, createEntityFacade } from './facade.js';
+export type { EntityDataSourceConfig, EntityDataSource } from './entity-datasource.js';
+export { createEntityDataSource } from './entity-datasource.js';
+export { aggregateEntities, applyEntityQuery, matchesEntityFilter, normalizeEntitySort, sortEntities, } from './apply-query.js';
+export type { AggregateSource } from './aggregate.js';
+export { aggregateThrough } from './aggregate.js';

package/dist/entity/index.js

@@ -0,0 +1,31 @@
+/**
+ * Entity System Module
+ *
+ * Entity system for schema-based entity types, CRUD operations,
+ * connectors, behaviors, and surface integration.
+ *
+ * Exports:
+ * - Types: EntityTypeId, EntityInstanceId, EntityDefinition, EntityQuery, etc.
+ * - Registry: EntityRegistry, InMemoryEntityRegistry, createEntityRegistry
+ * - Store: EntityStore, DefaultEntityStore, createEntityStore
+ * - Connectors: EntityConnector, ConnectorRegistry, StaticConnector
+ * - Lifecycle: EntityLifecycleEngine, EntityLifecycleHook, createEntityLifecycleEngine
+ * - Facade: EntityFacade, createEntityFacade
+ *
+ * @module @pwfabric/runtime/entity
+ */
+export { InMemoryEntityRegistry, createEntityRegistry } from './registry.js';
+export { DefaultEntityStore, createEntityStore } from './store.js';
+export { InMemoryConnectorRegistry, createConnectorRegistry } from './connector.js';
+// Connector implementations
+export { StaticConnector, createStaticConnector } from './connectors/index.js';
+export { HttpEntityConnector, createHttpConnector } from './http-connector.js';
+export { PostgresEntityConnector, createPostgresConnector } from './postgres-connector.js';
+export { DefaultEntityLifecycleEngine, createEntityLifecycleEngine } from './behavior.js';
+export { DefaultEntityFacade, createEntityFacade } from './facade.js';
+export { createEntityDataSource } from './entity-datasource.js';
+// applyEntityQuery — the single in-memory applier for EntityQuery
+// (filter → sort → pagination). Connectors call it on their result envelope.
+export { aggregateEntities, applyEntityQuery, matchesEntityFilter, normalizeEntitySort, sortEntities, } from './apply-query.js';
+export { aggregateThrough } from './aggregate.js';
+//# sourceMappingURL=index.js.map

package/dist/entity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA4BH,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAI5E,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAWlE,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAEnF,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAI9E,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAQ9E,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAQ1F,OAAO,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAA;AAWzF,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAIrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAE/D,kEAAkE;AAClE,6EAA6E;AAC7E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,GACb,MAAM,kBAAkB,CAAA;AAKzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA","sourcesContent":["/**\n * Entity System Module\n *\n * Entity system for schema-based entity types, CRUD operations,\n * connectors, behaviors, and surface integration.\n *\n * Exports:\n * - Types: EntityTypeId, EntityInstanceId, EntityDefinition, EntityQuery, etc.\n * - Registry: EntityRegistry, InMemoryEntityRegistry, createEntityRegistry\n * - Store: EntityStore, DefaultEntityStore, createEntityStore\n * - Connectors: EntityConnector, ConnectorRegistry, StaticConnector\n * - Lifecycle: EntityLifecycleEngine, EntityLifecycleHook, createEntityLifecycleEngine\n * - Facade: EntityFacade, createEntityFacade\n *\n * @module @pwfabric/runtime/entity\n */\n\n// Types\nexport type {\n  EntityTypeId,\n  EntityInstanceId,\n  EntityFieldType,\n  EntityFieldDefinition,\n  EntityRelationType,\n  EntityRelationDefinition,\n  EntityDefinition,\n  EntityQuery,\n  EntityFilter,\n  EntitySortField,\n  EntityPagination,\n  EntityQueryResult,\n  EntityAggregateFn,\n  EntityAggregate,\n  EntityAggregateResult,\n  EntityMutationResult,\n  EntityReadResult,\n  EntityOperationError,\n  EntityValidationResult,\n  EntityValidationError,\n} from './types.js'\n\n// Registry\nexport type { EntityRegistry } from './registry.js'\nexport { InMemoryEntityRegistry, createEntityRegistry } from './registry.js'\n\n// Store\nexport type { EntityStore } from './store.js'\nexport { DefaultEntityStore, createEntityStore } from './store.js'\n\n// Connectors\nexport type {\n  EntityConnectorType,\n  ConnectorResult,\n  ConnectorQueryResult,\n  ConnectorAggregateResult,\n  EntityConnector,\n  ConnectorRegistry,\n} from './connector.js'\nexport { InMemoryConnectorRegistry, createConnectorRegistry } from './connector.js'\n\n// Connector implementations\nexport { StaticConnector, createStaticConnector } from './connectors/index.js'\n\n// HTTP Connector (REST API connector)\nexport type { HttpAuthConfig, HttpRetryConfig, HttpConnectorConfig } from './http-connector.js'\nexport { HttpEntityConnector, createHttpConnector } from './http-connector.js'\n\n// PostgreSQL Connector (Database connector)\nexport type {\n  PostgresConnectorConfig,\n  DatabaseAdapter,\n  DatabaseResult,\n} from './postgres-connector.js'\nexport { PostgresEntityConnector, createPostgresConnector } from './postgres-connector.js'\n\n// Lifecycle\nexport type {\n  EntityLifecycleEngine,\n  EntityLifecycleTransition,\n  EntityLifecycleHook,\n} from './behavior.js'\nexport { DefaultEntityLifecycleEngine, createEntityLifecycleEngine } from './behavior.js'\n\nexport type {\n  EntityLifecycleEvent,\n  EntityBehaviorContext,\n  EntityGuard,\n  EntityAction,\n} from './behavior.js'\n\n// Facade\nexport type { EntityFacade } from './facade.js'\nexport { DefaultEntityFacade, createEntityFacade } from './facade.js'\n\n// EntityDataSource adapter for surface expression binding\nexport type { EntityDataSourceConfig, EntityDataSource } from './entity-datasource.js'\nexport { createEntityDataSource } from './entity-datasource.js'\n\n// applyEntityQuery — the single in-memory applier for EntityQuery\n// (filter → sort → pagination). Connectors call it on their result envelope.\nexport {\n  aggregateEntities,\n  applyEntityQuery,\n  matchesEntityFilter,\n  normalizeEntitySort,\n  sortEntities,\n} from './apply-query.js'\n\n// aggregateThrough — one number from a connector/engine/facade: server-side\n// when it has `aggregate`, its listed rows reduced in memory when it has not.\nexport type { AggregateSource } from './aggregate.js'\nexport { aggregateThrough } from './aggregate.js'\n"]}

package/dist/entity/postgres-connector.d.ts

@@ -0,0 +1,64 @@
+/**
+ * PostgreSQL Entity Connector
+ *
+ * Database connector for entity data persistence using Drizzle ORM.
+ * Implements the EntityConnector interface with PostgreSQL-specific query building.
+ *
+ * @module @pwfabric/runtime/entity/postgres-connector
+ */
+import type { EntityTypeId, EntityInstanceId, EntityQuery } from './types.js';
+import type { EntityConnector, EntityConnectorType, ConnectorResult, ConnectorQueryResult } from './connector.js';
+/**
+ * PostgreSQL connector configuration
+ */
+export interface PostgresConnectorConfig {
+    /**
+     * Database connection — either a connection string or a Drizzle db instance.
+     * When a string, the connector will create its own connection.
+     * When an object, it must implement the DatabaseAdapter interface.
+     */
+    readonly connection: string | DatabaseAdapter;
+    /** Optional table name prefix for multi-tenant isolation */
+    readonly tablePrefix?: string;
+    /** Default page size for queries */
+    readonly defaultPageSize?: number;
+    /** Maximum page size to prevent excessive queries */
+    readonly maxPageSize?: number;
+}
+/**
+ * Minimal database adapter interface.
+ * This abstracts over Drizzle ORM or any SQL-capable client.
+ */
+export interface DatabaseAdapter {
+    execute(sql: string, params?: unknown[]): Promise<DatabaseResult>;
+}
+/**
+ * Result of a database query execution
+ */
+export interface DatabaseResult {
+    readonly rows: Record<string, unknown>[];
+    readonly rowCount: number;
+}
+/**
+ * PostgreSQL connector for entity data operations.
+ * Maps entity CRUD operations to SQL queries via a DatabaseAdapter.
+ */
+export declare class PostgresEntityConnector implements EntityConnector {
+    readonly name: string;
+    readonly type: EntityConnectorType;
+    private readonly db;
+    private readonly tablePrefix;
+    private readonly defaultPageSize;
+    private readonly maxPageSize;
+    constructor(name: string, config: PostgresConnectorConfig);
+    private tableName;
+    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>;
+}
+/**
+ * Create a PostgreSQL entity connector
+ */
+export declare function createPostgresConnector(name: string, config: PostgresConnectorConfig): PostgresEntityConnector;