@hotmeshio/hotmesh 0.22.1 → 0.22.2

package/build/services/store/providers/postgres/postgres.js

@@ -1511,7 +1511,7 @@ class PostgresStoreService extends __1.StoreService {
         return result.rows[0] ?? null;
     }
     async listEscalations(params = {}) {
-        const { namespace, role, type, subtype, entity, status, assignedTo, workflowId, originId, limit = 50, offset = 0 } = params;
+        const { namespace, role, roles, type, subtype, entity, status, assignedTo, workflowId, originId, available, sortBy, sortOrder, limit = 50, offset = 0 } = params;
         const conditions = [];
         const values = [];
         let idx = 1;
@@ -1519,7 +1519,12 @@ class PostgresStoreService extends __1.StoreService {
             conditions.push(`namespace = $${idx++}`);
             values.push(namespace);
         }
-        if (role) {
+        // roles[] takes precedence over role when both provided
+        if (roles?.length) {
+            conditions.push(`role = ANY($${idx++}::text[])`);
+            values.push(roles);
+        }
+        else if (role) {
             conditions.push(`role = $${idx++}`);
             values.push(role);
         }
@@ -1551,17 +1556,86 @@ class PostgresStoreService extends __1.StoreService {
             conditions.push(`origin_id = $${idx++}`);
             values.push(originId);
         }
+        if (available === true) {
+            conditions.push(`(assigned_to IS NULL OR (assigned_until IS NOT NULL AND assigned_until <= NOW()))`);
+        }
+        if (available === false) {
+            conditions.push(`(assigned_to IS NOT NULL AND (assigned_until IS NULL OR assigned_until > NOW()))`);
+        }
         const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+        const col = sortBy === 'updated_at' ? 'updated_at' : sortBy === 'created_at' ? 'created_at' : 'priority';
+        const dir = sortOrder === 'desc' ? 'DESC' : 'ASC';
+        // Secondary sort is always created_at DESC for deterministic page ordering
+        const orderBy = col === 'priority'
+            ? `ORDER BY priority ${dir}, created_at DESC`
+            : `ORDER BY ${col} ${dir}`;
         values.push(limit, offset);
-        const result = await this.pgClient.query(`SELECT * FROM public.hmsh_escalations ${where} ORDER BY priority ASC, created_at ASC LIMIT $${idx++} OFFSET $${idx}`, values);
+        const result = await this.pgClient.query(`SELECT *,
+         (assigned_to IS NULL OR (assigned_until IS NOT NULL AND assigned_until <= NOW())) AS available
+       FROM public.hmsh_escalations ${where} ${orderBy} LIMIT $${idx++} OFFSET $${idx}`, values);
         return result.rows;
     }
+    async countEscalations(params = {}) {
+        const { namespace, role, roles, type, subtype, entity, status, assignedTo, workflowId, originId, available } = params;
+        const conditions = [];
+        const values = [];
+        let idx = 1;
+        if (namespace) {
+            conditions.push(`namespace = $${idx++}`);
+            values.push(namespace);
+        }
+        if (roles?.length) {
+            conditions.push(`role = ANY($${idx++}::text[])`);
+            values.push(roles);
+        }
+        else if (role) {
+            conditions.push(`role = $${idx++}`);
+            values.push(role);
+        }
+        if (type) {
+            conditions.push(`type = $${idx++}`);
+            values.push(type);
+        }
+        if (subtype) {
+            conditions.push(`subtype = $${idx++}`);
+            values.push(subtype);
+        }
+        if (entity) {
+            conditions.push(`entity = $${idx++}`);
+            values.push(entity);
+        }
+        if (status) {
+            conditions.push(`status = $${idx++}`);
+            values.push(status);
+        }
+        if (assignedTo) {
+            conditions.push(`assigned_to = $${idx++}`);
+            values.push(assignedTo);
+        }
+        if (workflowId) {
+            conditions.push(`workflow_id = $${idx++}`);
+            values.push(workflowId);
+        }
+        if (originId) {
+            conditions.push(`origin_id = $${idx++}`);
+            values.push(originId);
+        }
+        if (available === true) {
+            conditions.push(`(assigned_to IS NULL OR (assigned_until IS NOT NULL AND assigned_until <= NOW()))`);
+        }
+        if (available === false) {
+            conditions.push(`(assigned_to IS NOT NULL AND (assigned_until IS NULL OR assigned_until > NOW()))`);
+        }
+        const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+        const result = await this.pgClient.query(`SELECT COUNT(*)::int AS total FROM public.hmsh_escalations ${where}`, values);
+        return result.rows[0]?.total ?? 0;
+    }
     async claimEscalation(params) {
         const { id, namespace, assignee = '', durationMinutes = 1 } = params;
-        // all_rows: reads the row without locking, so we can distinguish 'not-found' vs 'conflict'
-        // target: attempts the lock; SKIP LOCKED means a locked row is skipped without error
-        // claimed: performs the UPDATE only if target succeeded
-        // The final SELECT always returns exactly 1 row via the dummy left-join — no second round-trip.
+        // Claims are implicit: status stays 'pending'; availability = assigned_to IS NULL OR assigned_until <= NOW().
+        // all_rows: unlocked read to distinguish 'not-found' vs 'conflict'.
+        // target: locks the row only when it is available (no active claim or same assignee re-claiming).
+        // claimed: writes both assigned_until and claim_expires_at (same value) for service-layer compat.
         const result = await this.pgClient.query(`
       WITH all_rows AS MATERIALIZED (
         SELECT id FROM public.hmsh_escalations
@@ -1572,16 +1646,16 @@ class PostgresStoreService extends __1.StoreService {
         WHERE id = $1
           ${namespace ? 'AND namespace = $4' : ''}
           AND status = 'pending'
-          AND (assigned_to IS NULL OR claim_expires_at <= NOW() OR assigned_to = $2)
+          AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)
         LIMIT 1
         FOR UPDATE SKIP LOCKED
       ),
       claimed AS (
         UPDATE public.hmsh_escalations
-        SET status           = 'claimed',
-            assigned_to      = $2,
+        SET assigned_to      = $2,
             claimed_at       = NOW(),
             claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),
+            assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),
             updated_at       = NOW()
         FROM target WHERE public.hmsh_escalations.id = target.id
         RETURNING public.hmsh_escalations.*
@@ -1600,10 +1674,8 @@ class PostgresStoreService extends __1.StoreService {
     async claimEscalationByMetadata(params) {
         const { key, value, namespace, assignee = '', durationMinutes = 1, roles } = params;
         const filter = JSON.stringify({ [key]: value });
-        // all_candidates: counts ALL matching rows (any status) to distinguish 'not-found' vs 'conflict'
-        // target: attempts the lock on the highest-priority pending row; SKIP LOCKED skips already-claimed ones
-        // claimed: performs the UPDATE atomically from target
-        // The dummy left-join ensures exactly 1 row is always returned so candidatesExist is always visible.
+        // target captures prior_assigned_to to detect re-claim (isExtension).
+        // Implicit claim model: status stays 'pending'; availability = assigned_until IS NULL OR assigned_until <= NOW().
         const result = await this.pgClient.query(`
       WITH all_candidates AS MATERIALIZED (
         SELECT id FROM public.hmsh_escalations
@@ -1612,25 +1684,25 @@ class PostgresStoreService extends __1.StoreService {
           AND ($4::text[] IS NULL OR role = ANY($4::text[]))
       ),
       target AS MATERIALIZED (
-        SELECT id FROM public.hmsh_escalations
+        SELECT id, assigned_to AS prior_assigned_to FROM public.hmsh_escalations
         WHERE ${namespace ? 'namespace = $5 AND' : ''}
               metadata @> $1::jsonb
           AND ($4::text[] IS NULL OR role = ANY($4::text[]))
           AND status = 'pending'
-          AND (assigned_to IS NULL OR claim_expires_at <= NOW() OR assigned_to = $2)
+          AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $2)
         ORDER BY priority ASC, created_at ASC
         LIMIT 1
         FOR UPDATE SKIP LOCKED
       ),
       claimed AS (
         UPDATE public.hmsh_escalations
-        SET status           = 'claimed',
-            assigned_to      = $2,
+        SET assigned_to      = $2,
             claimed_at       = NOW(),
             claim_expires_at = NOW() + ($3 * INTERVAL '1 minute'),
+            assigned_until   = NOW() + ($3 * INTERVAL '1 minute'),
             updated_at       = NOW()
         FROM target WHERE public.hmsh_escalations.id = target.id
-        RETURNING public.hmsh_escalations.*
+        RETURNING public.hmsh_escalations.*, target.prior_assigned_to
       )
       SELECT c.*, (SELECT COUNT(*)::int FROM all_candidates) AS candidates_exist
       FROM (VALUES(1)) AS dummy(v)
@@ -1640,8 +1712,10 @@ class PostgresStoreService extends __1.StoreService {
             : [filter, assignee, durationMinutes, roles ?? null]);
         const row = result.rows[0];
         const candidatesExist = row?.candidates_exist ?? 0;
-        if (row?.id)
-            return { ok: true, entry: row, candidatesExist };
+        if (row?.id) {
+            const isExtension = row.prior_assigned_to === assignee;
+            return { ok: true, entry: row, candidatesExist, isExtension };
+        }
         return {
             ok: false,
             reason: candidatesExist > 0 ? 'conflict' : 'not-found',
@@ -1657,7 +1731,7 @@ class PostgresStoreService extends __1.StoreService {
       WITH target AS MATERIALIZED (
         SELECT id, assigned_to FROM public.hmsh_escalations
         WHERE id = $1 ${namespace ? 'AND namespace = $3' : ''}
-          AND status = 'claimed'
+          AND status = 'pending' AND assigned_to IS NOT NULL
         FOR UPDATE
       ),
       released AS (
@@ -1682,6 +1756,7 @@ class PostgresStoreService extends __1.StoreService {
     }
     async resolveEscalation(params) {
         const { id, namespace, resolverPayload } = params;
+        const payloadJson = resolverPayload ? JSON.stringify(resolverPayload) : null;
         const result = await this.pgClient.query(`
       WITH target AS MATERIALIZED (
         SELECT id, signal_key, topic, status FROM public.hmsh_escalations
@@ -1696,7 +1771,7 @@ class PostgresStoreService extends __1.StoreService {
             updated_at       = NOW()
         FROM target
         WHERE public.hmsh_escalations.id = target.id
-          AND target.status IN ('pending', 'claimed')
+          AND target.status = 'pending'
         RETURNING public.hmsh_escalations.id
       )
       SELECT t.signal_key, t.topic, t.status AS prior_status,
@@ -1709,8 +1784,8 @@ class PostgresStoreService extends __1.StoreService {
       FROM (SELECT * FROM target) t
       FULL OUTER JOIN (SELECT id FROM resolved) r ON r.id = t.id
     `, namespace
-            ? [id, resolverPayload ? JSON.stringify(resolverPayload) : null, namespace]
-            : [id, resolverPayload ? JSON.stringify(resolverPayload) : null]);
+            ? [id, payloadJson, namespace]
+            : [id, payloadJson]);
         if (!result.rows[0] || result.rows[0].outcome === 'not-found')
             return { ok: false, reason: 'not-found' };
         if (result.rows[0].outcome === 'already-cancelled')
@@ -1722,6 +1797,7 @@ class PostgresStoreService extends __1.StoreService {
     async resolveEscalationByMetadata(params) {
         const { key, value, namespace, resolverPayload, roles } = params;
         const filter = JSON.stringify({ [key]: value });
+        const payloadJson = resolverPayload ? JSON.stringify(resolverPayload) : null;
         const result = await this.pgClient.query(`
       WITH target AS MATERIALIZED (
         SELECT id, signal_key, topic, status FROM public.hmsh_escalations
@@ -1739,7 +1815,7 @@ class PostgresStoreService extends __1.StoreService {
             updated_at       = NOW()
         FROM target
         WHERE public.hmsh_escalations.id = target.id
-          AND target.status IN ('pending', 'claimed')
+          AND target.status = 'pending'
         RETURNING public.hmsh_escalations.id
       )
       SELECT t.signal_key, t.topic, t.status AS prior_status,
@@ -1752,8 +1828,8 @@ class PostgresStoreService extends __1.StoreService {
       FROM (SELECT * FROM target) t
       FULL OUTER JOIN (SELECT id FROM resolved) r ON r.id = t.id
     `, namespace
-            ? [filter, resolverPayload ? JSON.stringify(resolverPayload) : null, roles ?? null, namespace]
-            : [filter, resolverPayload ? JSON.stringify(resolverPayload) : null, roles ?? null]);
+            ? [filter, payloadJson, roles ?? null, namespace]
+            : [filter, payloadJson, roles ?? null]);
         if (!result.rows[0] || result.rows[0].outcome === 'not-found')
             return { ok: false, reason: 'not-found' };
         if (result.rows[0].outcome === 'already-cancelled')
@@ -1809,7 +1885,7 @@ class PostgresStoreService extends __1.StoreService {
         SET status = 'cancelled', updated_at = NOW()
         FROM target
         WHERE public.hmsh_escalations.id = target.id
-          AND target.status IN ('pending', 'claimed')
+          AND target.status = 'pending'
         RETURNING public.hmsh_escalations.id
       )
       SELECT t.id, t.status AS prior_status,
@@ -1839,7 +1915,7 @@ class PostgresStoreService extends __1.StoreService {
           claim_expires_at = NULL,
           updated_at       = NOW()
       WHERE id = $1 ${namespace ? 'AND namespace = $3' : ''}
-        AND status IN ('pending', 'claimed')
+        AND status = 'pending'
       RETURNING *
     `, namespace ? [id, targetRole, namespace] : [id, targetRole]);
         return result.rows[0] ?? null;
@@ -1915,16 +1991,10 @@ class PostgresStoreService extends __1.StoreService {
     `, namespace ? [id, JSON.stringify(stamped), namespace] : [id, JSON.stringify(stamped)]);
         return result.rows[0] ?? null;
     }
-    async releaseExpiredEscalations(namespace) {
-        const result = await this.pgClient.query(`
-      UPDATE public.hmsh_escalations
-      SET status = 'pending', assigned_to = NULL, assigned_until = NULL,
-          claimed_at = NULL, claim_expires_at = NULL, updated_at = NOW()
-      WHERE status = 'claimed'
-        AND claim_expires_at <= NOW()
-        ${namespace ? 'AND namespace = $1' : ''}
-    `, namespace ? [namespace] : []);
-        return result.rowCount ?? 0;
+    async releaseExpiredEscalations(_namespace) {
+        // No-op in the implicit claim model: availability is computed at query time from
+        // assigned_until, so no background sweep is needed to release expired claims.
+        return 0;
     }
 }
 exports.PostgresStoreService = PostgresStoreService;

package/build/types/hmsh_escalations.d.ts

@@ -34,7 +34,8 @@ export interface EscalationEntry {
     entity: string | null;
     description: string | null;
     role: string | null;
-    status: 'pending' | 'claimed' | 'resolved' | 'cancelled' | 'expired';
+    /** Lifecycle status. Claims are implicit: status='pending' + assigned_to IS NOT NULL + assigned_until > NOW(). */
+    status: 'pending' | 'resolved' | 'cancelled' | 'expired';
     priority: number;
     assigned_to: string | null;
     assigned_until: Date | null;
@@ -55,6 +56,8 @@ export interface EscalationEntry {
     expires_at: Date | null;
     created_at: Date;
     updated_at: Date;
+    /** Computed by list(): true when the row is claimable (no active assignee or expired claim). */
+    available?: boolean;
 }
 /**
  * Result of `claim()` — identifies whether failure was due to the row not
@@ -70,15 +73,15 @@ export type ClaimEscalationResult = {
     reason: 'not-found' | 'conflict';
 };
 /**
- * Result of `claimByMetadata()`. Includes `candidatesExist` — the total
- * count of rows matching the metadata filter regardless of claimability — so
- * callers can distinguish "nothing matching at all" from "found candidates but
- * all are locked or in-progress".
+ * Result of `claimByMetadata()`. Includes `candidatesExist` and `isExtension`:
+ * - `candidatesExist` — total count of rows matching the filter regardless of claimability
+ * - `isExtension` — true when the same assignee re-claims a row they already hold (extends the expiry)
  */
 export type ClaimByMetadataResult = {
     ok: true;
     entry: EscalationEntry;
     candidatesExist: number;
+    isExtension: boolean;
 } | {
     ok: false;
     reason: 'not-found' | 'conflict';
@@ -88,7 +91,7 @@ export type ResolveEscalationResult = {
     ok: true;
 } | {
     ok: false;
-    reason: 'not-found' | 'already-resolved' | 'already-cancelled' | 'signal-failed';
+    reason: 'not-found' | 'already-resolved' | 'already-cancelled';
 };
 export type ReleaseEscalationResult = {
     ok: true;
@@ -105,6 +108,8 @@ export type CancelEscalationResult = {
 export interface ListEscalationsParams {
     namespace?: string;
     role?: string;
+    /** Filter by one or more roles (OR semantics; takes precedence over `role` when both set). */
+    roles?: string[];
     type?: string;
     subtype?: string;
     entity?: string;
@@ -112,6 +117,10 @@ export interface ListEscalationsParams {
     assignedTo?: string;
     workflowId?: string;
     originId?: string;
+    /** When true, returns only rows without an active claim. When false, returns only actively claimed rows. */
+    available?: boolean;
+    sortBy?: 'created_at' | 'priority' | 'updated_at';
+    sortOrder?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
 }

package/index.ts

@@ -18,6 +18,7 @@ import * as KeyStore from './modules/key';
 import { ConnectorService as Connector } from './services/connector/factory';
 import { PostgresConnection as ConnectorPostgres } from './services/connector/providers/postgres';
 import { NatsConnection as ConnectorNATS } from './services/connector/providers/nats';
+import { Escalations } from './services/escalations';
 
 export {
   //Provider Connectors
@@ -30,6 +31,7 @@ export {
   HotMeshConfig,
   Virtual,
   Durable,
+  Escalations,
   DBA,
 
   //Durable Submodules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",