@classytic/primitives 0.4.0 → 0.6.0

package/dist/status-history.d.mts

@@ -0,0 +1,86 @@
+//#region src/workflow/status-history.d.ts
+/**
+ * Generic, immutable status-change log.
+ *
+ * Every domain aggregate that has a state machine (Order, Lead, Opportunity,
+ * Campaign, Subscription, Approval, Shipment, …) ends up reinventing the same
+ * triple: `{ status, occurredAt, by? }` + an append-only array on the entity.
+ * This module gives that pattern one canonical type and one zero-allocation
+ * helper, so domains stay focused on their *transitions* not the bookkeeping.
+ *
+ * Pairs naturally with `state-machine`: the machine decides if a transition
+ * is legal; this helper records the move that happened.
+ *
+ * Frappe's "status change log" with `duration_in_prior_status` was the
+ * inspiration — funnel velocity reports (avg time spent in "Qualification")
+ * are free when you store the duration at write time instead of recomputing
+ * from raw timestamps later.
+ *
+ * @example
+ *   import { appendStatus, type StatusHistory } from '@classytic/primitives/status-history';
+ *   import { defineStateMachine } from '@classytic/primitives/state-machine';
+ *
+ *   type LeadStatus = 'new' | 'qualified' | 'converted' | 'disqualified';
+ *   const MACHINE = defineStateMachine<LeadStatus>({ ... });
+ *
+ *   function qualify(lead: Lead, by: string): Lead {
+ *     MACHINE.assertTransition(lead.id, lead.status, 'qualified');
+ *     return {
+ *       ...lead,
+ *       status: 'qualified',
+ *       statusHistory: appendStatus(lead.statusHistory, 'qualified', { by }),
+ *     };
+ *   }
+ */
+/**
+ * One row of the immutable history. Generic over the status enum so each
+ * domain stays type-safe (`StatusChangeEntry<LeadStatus>` rejects
+ * `'shipped'` at compile time).
+ */
+interface StatusChangeEntry<TStatus extends string> {
+  readonly status: TStatus;
+  readonly occurredAt: Date;
+  /** Who triggered the transition (user id, system actor name, etc.). */
+  readonly by?: string;
+  /** Free-form note — disqualify reason, comments, etc. */
+  readonly note?: string;
+  /**
+   * Milliseconds spent in the previous status. `0` for the first entry.
+   * Computed at write time so downstream funnel-velocity / SLA aggregates
+   * never need to walk timestamps.
+   */
+  readonly durationInPriorMs: number;
+}
+/**
+ * Convenience alias for entity fields: `statusHistory: StatusHistory<LeadStatus>`.
+ */
+type StatusHistory<TStatus extends string> = readonly StatusChangeEntry<TStatus>[];
+interface AppendOptions {
+  by?: string;
+  note?: string;
+  /** Override the timestamp — useful for replay / migration. Defaults to `new Date()`. */
+  at?: Date;
+}
+/**
+ * Append a new status entry, computing `durationInPriorMs` from the last
+ * entry (or `0` for the first row). Returns a fresh array — never mutates.
+ *
+ * The previous-entry lookup is `O(1)` (last element), so this is safe to
+ * call from hot paths.
+ */
+declare function appendStatus<TStatus extends string>(history: StatusHistory<TStatus>, status: TStatus, options?: AppendOptions): StatusHistory<TStatus>;
+/**
+ * Time spent in a status across the entire history. Used for funnel-velocity
+ * dashboards: "how long did this lead sit in `qualified` before it converted?".
+ *
+ * Counts duration on the entries that EXITED `status`. If the entity is
+ * currently in `status` and hasn't transitioned out, the still-elapsing time
+ * is added from `now`.
+ */
+declare function timeInStatus<TStatus extends string>(history: StatusHistory<TStatus>, status: TStatus, now?: Date): number;
+/** Most recent entry, or `null` for an empty history. */
+declare function latestEntry<TStatus extends string>(history: StatusHistory<TStatus>): StatusChangeEntry<TStatus> | null;
+/** Most recent occurrence of `status`, or `null` if it never appeared. */
+declare function lastTransitionTo<TStatus extends string>(history: StatusHistory<TStatus>, status: TStatus): StatusChangeEntry<TStatus> | null;
+//#endregion
+export { AppendOptions, StatusChangeEntry, StatusHistory, appendStatus, lastTransitionTo, latestEntry, timeInStatus };

package/dist/status-history.mjs

@@ -0,0 +1,48 @@
+//#region src/workflow/status-history.ts
+/**
+* Append a new status entry, computing `durationInPriorMs` from the last
+* entry (or `0` for the first row). Returns a fresh array — never mutates.
+*
+* The previous-entry lookup is `O(1)` (last element), so this is safe to
+* call from hot paths.
+*/
+function appendStatus(history, status, options = {}) {
+	const now = options.at ?? /* @__PURE__ */ new Date();
+	const prior = history.length === 0 ? void 0 : history[history.length - 1];
+	const entry = {
+		status,
+		occurredAt: now,
+		durationInPriorMs: prior === void 0 ? 0 : Math.max(0, now.getTime() - prior.occurredAt.getTime()),
+		...options.by !== void 0 ? { by: options.by } : {},
+		...options.note !== void 0 ? { note: options.note } : {}
+	};
+	return [...history, entry];
+}
+/**
+* Time spent in a status across the entire history. Used for funnel-velocity
+* dashboards: "how long did this lead sit in `qualified` before it converted?".
+*
+* Counts duration on the entries that EXITED `status`. If the entity is
+* currently in `status` and hasn't transitioned out, the still-elapsing time
+* is added from `now`.
+*/
+function timeInStatus(history, status, now = /* @__PURE__ */ new Date()) {
+	let total = 0;
+	for (let i = 0; i < history.length; i++) {
+		const entry = history[i];
+		if (i > 0 && history[i - 1].status === status) total += entry.durationInPriorMs;
+	}
+	if (history.length > 0 && history[history.length - 1].status === status) total += Math.max(0, now.getTime() - history[history.length - 1].occurredAt.getTime());
+	return total;
+}
+/** Most recent entry, or `null` for an empty history. */
+function latestEntry(history) {
+	return history.length === 0 ? null : history[history.length - 1];
+}
+/** Most recent occurrence of `status`, or `null` if it never appeared. */
+function lastTransitionTo(history, status) {
+	for (let i = history.length - 1; i >= 0; i--) if (history[i].status === status) return history[i];
+	return null;
+}
+//#endregion
+export { appendStatus, lastTransitionTo, latestEntry, timeInStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -89,6 +89,34 @@
       "types": "./dist/state-machine.d.mts",
       "default": "./dist/state-machine.mjs"
     },
+    "./bank-transaction": {
+      "types": "./dist/bank-transaction.d.mts",
+      "default": "./dist/bank-transaction.mjs"
+    },
+    "./payment-gateway": {
+      "types": "./dist/payment-gateway.d.mts",
+      "default": "./dist/payment-gateway.mjs"
+    },
+    "./phone": {
+      "types": "./dist/phone.d.mts",
+      "default": "./dist/phone.mjs"
+    },
+    "./status-history": {
+      "types": "./dist/status-history.d.mts",
+      "default": "./dist/status-history.mjs"
+    },
+    "./condition": {
+      "types": "./dist/condition.d.mts",
+      "default": "./dist/condition.mjs"
+    },
+    "./mixin": {
+      "types": "./dist/mixin.d.mts",
+      "default": "./dist/mixin.mjs"
+    },
+    "./sla-policy": {
+      "types": "./dist/sla-policy.d.mts",
+      "default": "./dist/sla-policy.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [