@arkstack/realtime 0.18.7 → 0.18.8

package/dist/{RealtimeClient-CpYmOGZa.d.ts → RealtimeClient-CzrWnLtj.d.ts}

@@ -12,6 +12,14 @@ interface RealtimeNotification {
   actionText?: string | null;
   actionLink?: string | null;
   meta?: Record<string, unknown> | null;
+  /**
+   * Stable identity for what this notification is about. A later notification
+   * with the same tag supersedes this one rather than stacking beside it — see
+   * {@link supersede}, which the React and Vue bindings apply for you.
+   */
+  tag?: string | null;
+  /** Removes the notification carrying `tag` instead of displaying anything. */
+  retracted?: boolean;
   read_at: string | null;
   created_at: string;
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as PusherClientConfig, c as RealtimeNotification, d as RealtimeTransportName, i as NotificationHandler, l as RealtimeSubscription, n as createRealtime, o as RealtimeConfig, r as FirebaseClientConfig, s as RealtimeEventHandler, t as RealtimeClient, u as RealtimeTransport } from "./RealtimeClient-CpYmOGZa.js";
+import { a as PusherClientConfig, c as RealtimeNotification, d as RealtimeTransportName, i as NotificationHandler, l as RealtimeSubscription, n as createRealtime, o as RealtimeConfig, r as FirebaseClientConfig, s as RealtimeEventHandler, t as RealtimeClient, u as RealtimeTransport } from "./RealtimeClient-CzrWnLtj.js";
 //#region src/transports/pusher.d.ts
 /**
  * Realtime transport backed by [pusher-js](https://github.com/pusher/pusher-js).
@@ -20,4 +20,30 @@ declare const createPusherTransport: (config: PusherClientConfig) => Promise<Rea
  */
 declare const createFirebaseTransport: (config: FirebaseClientConfig) => Promise<RealtimeTransport>;
 //#endregion
-export { type FirebaseClientConfig, type NotificationHandler, type PusherClientConfig, RealtimeClient, type RealtimeConfig, type RealtimeEventHandler, type RealtimeNotification, type RealtimeSubscription, type RealtimeTransport, type RealtimeTransportName, createFirebaseTransport, createPusherTransport, createRealtime };
+//#region src/supersede.d.ts
+/**
+ * Fold an incoming notification into a list, honouring tag supersession.
+ *
+ * A notification carrying a `tag` names the thing it is about rather than the
+ * moment it was sent, so a later notification with the same tag is understood as
+ * a newer account of the same thing:
+ *
+ * - **Tagged, already present** — replaces the existing entry *in place*. The
+ *   entry keeps its position so a list does not reshuffle under someone reading
+ *   it; only its content changes.
+ * - **Tagged, not present** — prepended, like any other notification.
+ * - **Retracted** — removes the entry it names and contributes nothing itself. A
+ *   retraction for something never seen is a no-op, which is the common case when
+ *   a client connects after the fact.
+ * - **Untagged** — prepended. Untagged notifications never supersede anything.
+ *
+ * Pure and list-in/list-out, so it suits any state container; the React and Vue
+ * bindings are thin wrappers over it.
+ *
+ * @param list      The notifications held so far, newest first.
+ * @param incoming  The notification just received.
+ * @param limit     Caps the retained list (newest kept) when growing it.
+ */
+declare const supersede: (list: RealtimeNotification[], incoming: RealtimeNotification, limit?: number) => RealtimeNotification[];
+//#endregion
+export { type FirebaseClientConfig, type NotificationHandler, type PusherClientConfig, RealtimeClient, type RealtimeConfig, type RealtimeEventHandler, type RealtimeNotification, type RealtimeSubscription, type RealtimeTransport, type RealtimeTransportName, createFirebaseTransport, createPusherTransport, createRealtime, supersede };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { t as supersede } from "./supersede-T1ch4wJF.js";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -260,4 +261,4 @@ const createFirebaseTransport = async (config) => {
 	};
 };
 //#endregion
-export { RealtimeClient, createFirebaseTransport, createPusherTransport, createRealtime };
+export { RealtimeClient, createFirebaseTransport, createPusherTransport, createRealtime, supersede };

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
-import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CpYmOGZa.js";
+import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CzrWnLtj.js";
 //#region src/react/index.d.ts
 interface UseNotificationsOptions {
   /** Cap the number of retained notifications (newest kept). Default: unbounded. */
@@ -14,6 +14,10 @@ interface UseNotificationsResult {
  * notifications (newest first) into state. Automatically unsubscribes on unmount
  * or when `client`/`channel` change.
  *
+ * Tagged notifications supersede rather than accumulate: one replaces an earlier
+ * notification with the same tag in place, and a retraction removes it. See
+ * {@link supersede}.
+ *
  * @param client   A {@link RealtimeClient} (from `createRealtime`).
  * @param channel  The channel to subscribe to, e.g. `client.channelFor(user.id)`.
  * @param options  `limit` caps how many notifications are retained.

package/dist/react/index.js

@@ -1,3 +1,4 @@
+import { t as supersede } from "../supersede-T1ch4wJF.js";
 import { useCallback, useEffect, useState } from "react";
 //#region src/react/index.ts
 /**
@@ -5,6 +6,10 @@ import { useCallback, useEffect, useState } from "react";
 * notifications (newest first) into state. Automatically unsubscribes on unmount
 * or when `client`/`channel` change.
 *
+* Tagged notifications supersede rather than accumulate: one replaces an earlier
+* notification with the same tag in place, and a retraction removes it. See
+* {@link supersede}.
+*
 * @param client   A {@link RealtimeClient} (from `createRealtime`).
 * @param channel  The channel to subscribe to, e.g. `client.channelFor(user.id)`.
 * @param options  `limit` caps how many notifications are retained.
@@ -15,10 +20,7 @@ function useNotifications(client, channel, options = {}) {
 	useEffect(() => {
 		let unsubscribe;
 		let cancelled = false;
-		const push = (notification) => setNotifications((prev) => {
-			const next = [notification, ...prev];
-			return limit ? next.slice(0, limit) : next;
-		});
+		const push = (notification) => setNotifications((prev) => supersede(prev, notification, limit));
 		client.subscribe(channel, push).then((off) => {
 			if (cancelled) off();
 			else unsubscribe = off;

package/dist/supersede-T1ch4wJF.js

@@ -0,0 +1,40 @@
+//#region src/supersede.ts
+/**
+* Fold an incoming notification into a list, honouring tag supersession.
+*
+* A notification carrying a `tag` names the thing it is about rather than the
+* moment it was sent, so a later notification with the same tag is understood as
+* a newer account of the same thing:
+*
+* - **Tagged, already present** — replaces the existing entry *in place*. The
+*   entry keeps its position so a list does not reshuffle under someone reading
+*   it; only its content changes.
+* - **Tagged, not present** — prepended, like any other notification.
+* - **Retracted** — removes the entry it names and contributes nothing itself. A
+*   retraction for something never seen is a no-op, which is the common case when
+*   a client connects after the fact.
+* - **Untagged** — prepended. Untagged notifications never supersede anything.
+*
+* Pure and list-in/list-out, so it suits any state container; the React and Vue
+* bindings are thin wrappers over it.
+*
+* @param list      The notifications held so far, newest first.
+* @param incoming  The notification just received.
+* @param limit     Caps the retained list (newest kept) when growing it.
+*/
+const supersede = (list, incoming, limit) => {
+	const { tag, retracted } = incoming;
+	if (retracted) return tag ? list.filter((notification) => notification.tag !== tag) : list;
+	if (tag) {
+		const index = list.findIndex((notification) => notification.tag === tag);
+		if (index !== -1) {
+			const next = list.slice();
+			next[index] = incoming;
+			return next;
+		}
+	}
+	const next = [incoming, ...list];
+	return limit ? next.slice(0, limit) : next;
+};
+//#endregion
+export { supersede as t };

package/dist/vue/index.d.ts

@@ -1,4 +1,4 @@
-import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CpYmOGZa.js";
+import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CzrWnLtj.js";
 import { ComputedRef, Ref } from "vue";
 //#region src/vue/index.d.ts
 interface UseNotificationsOptions {
@@ -16,6 +16,10 @@ interface UseNotificationsResult {
  * notifications (newest first) into a ref. Automatically unsubscribes when the
  * scope is disposed (component unmount).
  *
+ * Tagged notifications supersede rather than accumulate: one replaces an earlier
+ * notification with the same tag in place, and a retraction removes it. See
+ * {@link supersede}.
+ *
  * @param client   A {@link RealtimeClient} (from `createRealtime`).
  * @param channel  The channel to subscribe to, e.g. `client.channelFor(user.id)`.
  * @param options  `limit` caps how many notifications are retained.

package/dist/vue/index.js

@@ -1,3 +1,4 @@
+import { t as supersede } from "../supersede-T1ch4wJF.js";
 import { computed, onScopeDispose, ref } from "vue";
 //#region src/vue/index.ts
 /**
@@ -5,6 +6,10 @@ import { computed, onScopeDispose, ref } from "vue";
 * notifications (newest first) into a ref. Automatically unsubscribes when the
 * scope is disposed (component unmount).
 *
+* Tagged notifications supersede rather than accumulate: one replaces an earlier
+* notification with the same tag in place, and a retraction removes it. See
+* {@link supersede}.
+*
 * @param client   A {@link RealtimeClient} (from `createRealtime`).
 * @param channel  The channel to subscribe to, e.g. `client.channelFor(user.id)`.
 * @param options  `limit` caps how many notifications are retained.
@@ -15,8 +20,7 @@ function useNotifications(client, channel, options = {}) {
 	let unsubscribe;
 	let cancelled = false;
 	const push = (notification) => {
-		const next = [notification, ...notifications.value];
-		notifications.value = limit ? next.slice(0, limit) : next;
+		notifications.value = supersede(notifications.value, notification, limit);
 	};
 	client.subscribe(channel, push).then((off) => {
 		if (cancelled) off();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/realtime",
-  "version": "0.18.7",
+  "version": "0.18.8",
   "type": "module",
   "description": "Client for consuming Arkstack realtime notifications (Pusher/Firebase), with framework-agnostic core plus React and Vue bindings.",
   "homepage": "https://arkstack.toneflix.net/guide/notifications",